docs: repository - Document structure and naming conventions #266

Current delivery and branch audit — 24 October 2026

This current snapshot supersedes conflicting earlier branch instructions and implementation-status claims below. Earlier dated notes remain historical evidence, not current acceptance. No status, hierarchy, native PR association or repository change is proposed by this description patch.

• Outcome: Publish an evidence-backed structure/naming guide with directly relevant documentation links.
• Recorded status: Backlog. Accepted whole-child completion is not established.
• Verified implementation position: Native parent is this coordination epic, contrary to old “no additional parent” wording. docs/GITHUB_DIRECTORY.md and docs/BRANCH_NAMING_LOCAL.md exist; no canonical whole-repository structure guide named docs/repository-structure.md exists.
• Outstanding acceptance: Verify current entry/alias/content/test examples; distinguish observed names from requirements; document Figma logical paths and unresolved runtime discrepancies without fixing application code.

Branch instructions

• Repository: lightspeedwp/ThisOneTimeOnAcidCom
• Implementing issue(s): this existing child; GitHub sync counterpart docs: repository - Document structure and naming conventions #266 in the same repository. Linear GitHub-sync mapping retrieved; GitHub issue body/parent not independently re-read in this audit. Do not use a closing/development association until independently verified.
• Parent epic context: native parent verified; coordination only. No implementation branch/file plan belongs to the epic itself.
• Allowed closing target(s): none now. Whole-child acceptance and independent GitHub/Linear mapping/association review are required before proposing a closing target; never the parent.
• Branch state: proposed new branch
• Branch: docs/repository-structure-guide
• Base: develop, verified at 3f583002482d80ffd1910676bcf7c63e13989b20; refresh before separately authorised implementation
• Naming policy: target instructions, contributor guide, validator, local branch guide, organisation strategy. Classification rationale: docs is the candidate code/documentation class; authorised prefix is checked independently of the Linear title. Exact proposed name passed node scripts/validate-branch-name.js --branch docs/repository-structure-guide in this read-only audit. It is not created or approved for creation.
• Pull request template: shared pr_docs.md — explicitly read/use its sections; do not add a repository-local copy
• PR association safeguard: No parent identifier/link in a future branch name, PR title/body, coding prompt, development link or closing directive. Association/status automation settings remain unverified; do not assume “Related to” text or a hyperlink is harmless. Child references in this description are not proposed PR text.
• Constraints: preserve unrelated work; do not create/switch/rename/delete branches, force-push, merge, deploy, change settings or close records under this draft. Shared locked configuration/templates require human review. Residual protected-file declarations remain relevant despite absent guard workflow; do not equate absent automated enforcement with permission. Workflow ownership conflicts require controller/owner resolution, not local edits to managed dependency workflows.
• Conflicts or missing evidence: Complete current application entry/alias and naming-example sampling before writing; no broad root/index rewrite. Existing parent correction is a record-only proposal.

Expected file changes

Plan status: provisional bounded proposal, not an approved or exhaustive implementation manifest; conditional rows are not permission to act.

• Out of scope: Application/runtime fixes, bulk moves/renames, foreign WordPress rules/frontmatter, protected-file edits.
• Remaining discovery: Complete current application entry/alias and naming-example sampling before writing; no broad root/index rewrite. Existing parent correction is a record-only proposal.
• Scope-change gate: stop for revised exact scope and approval before adding materially different paths or operations. No unbounded “other files as needed”. Protected-file approval never overrides a prohibition on routine agent edits.

Evidence and handoff packet

• Recipient and request: originating issue-management audit; read-only exact existing-record preview for approval, not a new intake or implicit specialist invocation.
• Selected record: this existing child description, separate from the coordination parent; no writes performed.
• Implementing targets and criteria: this child’s existing outcome and acceptance criteria remain in force. Publish an evidence-backed structure/naming guide with directly relevant documentation links. Outstanding gates: Verify current entry/alias/content/test examples; distinguish observed names from requirements; document Figma logical paths and unresolved runtime discrepancies without fixing application code.
• Sources checked: current Linear description/status/native parent/relations/explicit pullRequests and GitHub sync metadata; target instructions, contributor guide, validator, local branch guide, organisation strategy; the exact source paths/revisions above and current repository inventory. Shared template config checked at 47aee0722033f65d4d9d57429b410b518646b817. Some path evidence is inventory-only and is labelled as such; it is not full content/behaviour validation.
• Branch/PR evidence: Current remote inventory includes historical epic/repo-governance-lightspeedwp/ThisOneTimeOnAcidCom#237 and broad governance/testing branches; scope/base/diff fit was not verified, so none is recommended for reuse. An open application-instrumentation pull request overlaps shared configuration; refresh its head, changed paths and scope before choosing a branch or editing shared files. No reuse is approved. No native linked PR was returned for this child; descriptive/historical references are not native associations.
• Association and closing rationale: Linear GitHub-sync mapping retrieved; GitHub issue body/parent not independently re-read in this audit. Do not use a closing/development association until independently verified. No complete-child acceptance or closing target established. Linear GitHub documentation lookup identified the integration article but did not expose its detailed association content; current workspace linking/status rules remain unverified. No parent identifier/link in a future branch name, PR title/body, coding prompt, development link or closing directive. Association/status automation settings remain unverified; do not assume “Related to” text or a hyperlink is harmless. Child references in this description are not proposed PR text.
• Unresolved points and exclusions: Complete current application entry/alias and naming-example sampling before writing; no broad root/index rewrite. Existing parent correction is a record-only proposal. Application/runtime fixes, bulk moves/renames, foreign WordPress rules/frontmatter, protected-file edits.
• Approval state: draft only. Exact description-preview approval is still required; repository edits/branch actions/PRs/settings/native associations retain separate boundaries. Existing GitHub issue sync is active, so approved description changes may propagate externally; no duplicate GitHub body write is proposed.

Documentation Update Summary

Document the actual folder structure, key files and naming conventions throughout lightspeedwp/ThisOneTimeOnAcidCom. Contributors should be able to locate existing functionality and place new files without relying on outdated Figma Make paths.

This is a React/TypeScript/Vite repository, not a WordPress plugin.

Linked Stories/Tasks/PRs/Epic

Existing synced record: GitHub #266. The native parent is the coordination epic; no additional dependency or PR association is proposed.

Milestones & Timeline

No new deadline or milestone proposed.

What documentation is needed?

Create a canonical repository structure and naming guide under docs/, with links from relevant contributor documentation and indexes.

Cover:

• Application: index.html → src/main.tsx → src/app/App.tsx; src/app/routes.ts; the @ alias resolving to src/app.
• Components and supporting code: src/app/components/{common,figma,layout,pages,sections,template-parts,ui}/, plus hooks, libraries, utilities and data.
• Styles: src/styles/index.css and the blocks, components, effects, patterns, themes and tokens directories.
• Content: distinguish src/app/data/{mock,types}/ from editorial Markdown under root content/, including book ordering and journal metadata.
• Tooling and assets: public assets, scripts/, tests/, e2e/, package/configuration files, ignored build output and deployment configuration.
• Documentation and agent artefacts: guidelines/, docs/, prompts/, reports/, tasks/, .claude/, .gemini/, .specify/ and .github/specs/.

Provide naming rules with real examples:

• PascalCase custom React components; preserve lowercase UI-library exceptions.
• useCamelCase.ts hooks and observed camelCase utility filenames.
• Kebab-case CSS filenames and BEM selectors.
• Content filenames, ordered book directories, documentation, prompts, reports, agent artefacts and test suffixes.
• Reserved filenames and existing legacy exceptions.

Distinguish documented requirements from observed practice. Correct directly relevant path/naming guidance; record unresolved runtime or configuration discrepancies separately rather than fixing them here.

Why is this documentation important?

Existing documentation conflicts with the repository tree, including logical Figma paths, layout/ naming, alias resolution and content locations. Accurate guidance will reduce misplaced files and contradictory contributor instructions.

Acceptance Criteria

• Directory coverage and key-file explanations match the current repository tree.
• Logical Figma paths are clearly mapped to actual repository paths.
• Naming guidance includes verified examples and explicit exceptions.
• Source, editorial content, generated output and governance artefacts are distinguished.
• Entry points, aliases and test commands match executable configuration.
• Relevant documentation links resolve and the guide is discoverable.
• Supplied shared instructions are adapted selectively; no WordPress layout, unsupported validation tools or foreign frontmatter requirements are imported.
• No application changes, bulk moves/renames or protected-file edits are included.
• Remaining contradictions are recorded for separate review.

Additional Context

Use repository-local AGENTS.md, CONTRIBUTING.md, configuration and guideline documents as primary evidence.

All supplied reference paths exist, but archived instructions are historical—not authoritative target-repository policy. In particular, the archived file-management reference forbids new use; consult the current file organisation guidance selectively instead. Plugin-structure guidance is not applicable.

Definition of Ready

• Documentation scope and reference sources confirmed.
• Proposed title, label and description approved.
• Ownership and any delivery dependencies confirmed before implementation.

Definition of Done

• Guide and directly related documentation corrections reviewed for accuracy and accessibility.
• Paths, examples and links verified against the implementation branch.
• Unresolved discrepancies recorded without unrelated fixes.
• Any documentation PR follows verified repository branch and review requirements.

Supplementary references and research findings

Shared instruction references

Reference repository: lightspeedwp/.github on develop.

Use these as selective references, not target-repository requirements:

• Archived references under .github/instructions/.archive/: naming-conventions.instructions.md, file-management.instructions.md, jsdoc.instructions.md, jest.instructions.md, frontmatter.instructions.md, tests.instructions.md, testing.instructions.md, javascript.instructions.md, json.instructions.md, agents.instructions.md.
• Other supplied references under .github/instructions/: hooks.instructions.md, plugin-structure.instructions.md, readme.instructions.md, tools.instructions.md, workflows.instructions.md, prompt.instructions.md, instructions.instructions.md, docs.instructions.md, agent-spec.instructions.md, mermaid.instructions.md, markdown.instructions.md, meta.instructions.md, reporting.instructions.md.

All 23 unique supplied paths were found during research. Archived file-management guidance forbids new use; consult the current file organisation reference instead. Control-plane-local guidance must not override this repository’s own instructions.

Verified repository findings

Research snapshot: develop at 4ecdb26d9655a48bf000a7c89da2f70383edce87. Re-check before implementation.

• React/TypeScript/Vite with npm, ESM and Node 24 configuration. Do not import WordPress plugin structure or assume Tailwind is installed.
• Active entry is src/main.tsx; a separate src/app/main.tsx also exists. The @ alias maps to src/app.
• Actual component directory is layout/, not layouts/. Preserve lowercase UI-library filenames and reserved-name exceptions rather than imposing blanket PascalCase.
• React hooks, Git hooks and agent hooks are distinct. Relevant tooling includes lefthook.yml, .claude/hooks/ and scripts/claude/.
• Tests use different runners and locations: Jest configuration, Playwright under e2e/, Bats and a separate Node test suite. Do not claim every existing test is covered by one command.
• Root reports/{topic}/ is the target convention; do not import .github/reports/.
• Editorial metadata must follow the target’s actual schemas, including scripts/journal-schema.ts, not governance frontmatter from another repository.

Contradictions requiring explicit treatment

• Existing README/guidelines contain logical Figma paths, incorrect alias guidance and outdated claims about content locations, dependencies and scripts.
• Book and journal loader globs differ from actual root content locations. Record this as a potential separate implementation follow-up; documentation work does not authorise runtime fixes.
• Journal guidance contains older pnpm and journal-content/ references.
• Netlify configuration exists, but its activation depends on external deployment settings that were not verified.
• Preserve protected files and centrally managed workflows. Do not perform unrelated moves, renames, configuration changes or cleanup.

Close-out boundary

This issue captures documentation work only. No implementation PR was created, and potential runtime discrepancies have not been fixed or filed separately.