Standardize reusable repository documentation roles

[brainboxemb]

Problem

Maintained reusable repositories currently answer the same engineering questions
with different document layouts. SCAD libraries have progressed furthest, while
tooling and the general meta layer still contain useful but weakly categorized
documentation.

The shared model is driven by reader questions, not by repository type.

A maintained reusable repository should make it easy to answer:

1. why does this repository exist;
2. why would I use it;
3. how is it put together;
4. how is it tested and qualified;
5. how do I develop and maintain it;
6. how do I use it as a consumer;
7. who are the typical users and use cases.

Numbered documentation families

A maintained documentation collection uses a local README.md as its
overview/index and then stable numbered families:

README.md

10-00-plan.md

20-00-manuals.md
20-01-development.md
20-02-user.md
20-xx-...md

30-00-specification.md

40-00-design.md
40-xx-...md

50-00-verification.md
50-xx-...md

Generated documentation may additionally publish:

99-00-book.md

Numbered source files use <family>-<order>-<name>.md: the first number identifies the family, the second number gives stable ordering inside that family, and the remaining name uses normal kebab-case.

Examples:

20-00-manuals.md
20-10-engineering-workflow.md
20-11-git-workflow.md
20-12-versioning-and-releases.md

40-00-design.md
40-01-project-families.md
40-02-repository-tooling.md
40-03-generated-output.md

Primary ownership:

• README / overview — documentation landing page / reading order;
• 10 plan — current work and roadmap;
• 20 manuals — how contributors and consumers actually work;
• 30 specification — purpose, target users/use cases, why to use it,
  non-goals and desired behavior;
• 40 design — architecture and responsibility boundaries;
• 50 verification — how behavior/released interfaces are qualified;
• 99 book — generated combined reading artifact, never a maintained
  authority.

README convention

Every maintained documentation collection/navigation directory uses a local
README.md as its overview/index.

Do not keep a duplicate 00-00_readme.md. Its alphabetical position in
GitHub's file list is accepted because native GitHub README rendering and one
authority are more valuable than forcing the overview to sort first.

This applies to repository doc/ / docs/ sets and domain documentation
collections. It does not force README files into every source-adjacent detail
directory that is not itself a documentation navigation boundary.

Root repository README.md and AGENTS.md remain repository entrypoints.

Repository-type differences

The families are common; content emphasis differs.

Tools normally need more manual material around CLI/configuration, managed
launchers, reusable workflows/actions and release lifecycle.

Libraries normally emphasize public API usage, consumer semantics and code-near
or generated API reference.

SCAD adds visual/component-local documentation where useful.

Initial application

Dogfood the model in this order before Migration 011 publishes its tooling
baseline:

1. brainboxemb.meta itself — reorganize the general documentation into
   numbered manual/design families and keep domain-specific material in
   domains/;
2. tool.git-project;
3. tool.scad-project.

Useful existing documents are classified and retained instead of mechanically
rewritten.

After this is proven, audit other maintained tooling repositories such as
tool.java-project separately rather than silently expanding Migration 011.

Current-generation maintained SCAD libraries then adopt the same numbered
families during their Migration-011 refresh.

Completed experiment/PoP repositories are not maintenance targets for this
documentation rollout.

[brainboxemb]

Progress:

• Meta dogfood step is complete and merged through PR Standardize numbered repository documentation #144.
• The final filename convention is <family>-<order>-<name>.md with normal kebab-case.
• A documentation collection keeps one native README.md as its chapter-00 / GitHub landing page; no parallel numbered README is kept.
• The long handoff was replaced with a short copy/paste repository pointer.
• tool.git-project implementation is now in PR Adopt numbered repository documentation families tool.git-project#37; its exact-head owner suites are running and currently green where completed.

Next after that PR qualifies/merges: apply the same model to tool.scad-project.

[brainboxemb]

Rollout status

The shared numbered documentation model is now being dogfooded in the intended order.

• brainboxemb.meta — complete on main; general documentation is now the numbered README / 10 plan / 20 manuals / 30 specification / 40 design / 50 verification set. The handoff manual is intentionally short and directly copy/pasteable, with the current goal and repository filled at the end.
• tool.git-project — complete on main via PR Make brainboxemb.meta a reader-oriented portfolio landing page #37; existing useful contract/design/verification docs were classified rather than discarded.
• tool.scad-project — implementation is in PR Record Forge and mechint rollout in changelog #111 from docs/issue-110-numbered-documentation; existing subject docs are classified into manuals/specification/design/verification families and owner CI is running.

After tool.scad-project is qualified/merged, the documentation model is proven on meta + generic tooling + SCAD tooling and Migration 011 can continue with the maintained SCAD libraries/projects.