ADR-0010 — Projects document themselves here through a git submodule, one folder each

• Status: Approved
• Date: 2026-10-31
• Deciders: P@puncoz
• Approved by: P@puncoz
• Approved on: 2026-11-01
• Supersedes: —
• Superseded by: ADR-0024 (in part: decision 2 for a project with several repositories: each edits its own folders, the primary the shared files)
• Design documents: PROJECT_AGENTS.md, ../app-flow/package-navigation.mdx, ../app-flow/site-pages.mdx, AGENTS.md §1, §8

ContextCopy Anchor Link

The owner's project and package repositories will include this repository as a git submodule and maintain their own documentation in it. Their agents then work inside this repository without having read its working agreement, from a repository whose rules differ.

Three things are undecided without this ADR: where a project's pages go (the per-project content layout is open, AGENTS.md §1), how changes made in a submodule come back, and what a private project may put here. Every file under content/ is published (ADR-0002, §6.1), and a consuming repository may be private.

DecisionCopy Anchor Link

1. One folder per project or package: content/<project-slug>/, published at /<project-slug>, in the shape of ADR-0013 and ADR-0015. Readers reach it from the home page, search and the header. The slug is agreed with the owner when the folder is first created.
2. Consuming repositories edit only their own folder. Any other change, such as another project's pages, src/, configuration, dependencies or this site's documents, is a change to the site and goes through ADR-0001.
3. Edit only; a human commits. An agent in a consuming repository never commits, pushes, rebases or switches branches inside the submodule, and never moves the submodule pointer. It lists its changes and hands the human the commands.
4. Public only until private documentation is decided. A private project keeps its documentation in its own repository and adds nothing here, until an ADR decides how private documentation is stored, served and searched.
5. PROJECT_AGENTS.md at the repository root is the guide for consuming repositories, with a block each one pastes into its own AGENTS.md / CLAUDE.md. It changes in the same change as anything that alters how they work here, and so does AGENTS.md.
6. Writing pages inside a project's folder needs no ADR, within this guide and the content invariants.

Options consideredCopy Anchor Link

ConsequencesCopy Anchor Link

Positive

• Each project's documentation lives next to its code and is published in one place.
• A person reviews every change before it reaches a public surface.

Negative / accepted trade-offs

• Every update needs a manual commit in the submodule and a pointer bump in the project.
• Private projects have no documentation here until a later ADR.
• Projects are found from the home page and search, not a sidebar switcher; a large number may need grouping later (a new ADR).

Content invariantsCopy Anchor Link

All five apply to every consuming repository's pages; PROJECT_AGENTS.md §4 restates them. Invariant 1 is the reason for decision 4.

Security considerationsCopy Anchor Link

• Trust boundary. Content moves from consuming repositories, some of them private, into this public site. The controls are: private repositories add nothing (decision 4); public pages carry no secrets, internal hostnames, client names, personal data or copied private code (PROJECT_AGENTS.md §2); and a human reviews and commits every change (decision 3).
• Scope. Consuming agents may only edit their own folder (decision 2), so a consuming repository cannot change routes, the search sync or another project's pages.
• Publishing. Consumers verify with bunx next build and never run bun run build, which writes to the live search index.

Implementation notesCopy Anchor Link

• PROJECT_AGENTS.md written with the paste-in block.
• App flow: ../app-flow/package-navigation.mdx and ../app-flow/site-pages.mdx.
• On approval: the first consuming project's folder, with the slug agreed with the owner.
• On approval: ../dfd/system.mdx gains consuming repositories as a source, across the trust boundary.
• Tests: the catalogue build checks (ADR-0015 decision 5) fail on a folder without a catalog; automated tests belong with the test runner chosen under ADR-0007.

Docs to update on implementationCopy Anchor Link

• AGENTS.md §1, §8, §10
• README.md — project structure, decisions table
• ./index.mdx — index row, next free number
• ./index.mdx — status on approval