diff --git a/docs/README.md b/docs/README.md index f551520..05fd0c9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -13,14 +13,11 @@ structure the public docs site exposes. metadata. - `docs/project/`: maintainer-facing planning notes that should not be treated as public package documentation. Start with - `docs/project/socket-store-contract-map.md` for cross-package contract work. - Use `docs/project/store-creation-path.md` for the official store creation - decision. Use `docs/project/release-order.md` for cross-repository release - order and migration-note gates. Use - `docs/project/documentation-examples-closeout.md` for the #10 umbrella - documentation and runnable examples reconciliation. Use - `docs/project/agent-docs-mcp-closeout.md` for the #13 umbrella - agent-readable docs and MCP evaluation reconciliation. + [`docs/project/README.md`](./project/README.md) for the internal-docs index, + then use `docs/project/socket-store-contract-map.md` for cross-package + contract work, `docs/project/store-creation-path.md` for the official store + creation decision, and `docs/project/release-order.md` for cross-repository + release order. Root files keep their existing roles: `README.md` is the concise package overview, `example/` contains runnable app code, and `src/` is the source of @@ -59,6 +56,11 @@ VitePress source tree and are not deployed. If Pages is not enabled for the repository yet, an owner must configure Pages to use GitHub Actions as the source before the workflow can publish. +Use [`docs/project/README.md`](./project/README.md) as the entry point for +internal repository notes. If an accepted process or architecture rule needs a +single long-lived source of truth, record that need there and promote the rule +into a dedicated SPEC instead of repeating it across closeout notes. + To roll back a bad docs deployment, revert the commit that changed the public docs or workflow and let the `Pages` workflow deploy the reverted artifact. If the workflow itself is failing, disable Pages publication in repository settings diff --git a/docs/project/README.md b/docs/project/README.md new file mode 100644 index 0000000..fa79ea4 --- /dev/null +++ b/docs/project/README.md @@ -0,0 +1,44 @@ +# Project Docs + +`docs/project/` is for maintainer-facing notes that explain repository +decisions, verification workflow, and historical closeout context. These files +are not part of the public package contract. + +## File Guide + +- `socket-store-contract-map.md`: cross-package contract inventory for adapter + work that depends on `socket-store`. +- `store-creation-path.md`: the accepted store creation path for public docs + and examples. +- `release-order.md`: cross-repository release-order guidance for maintainers. +- `check-failure-playbook.md`: how to triage local or CI failures without + weakening checks. +- `documentation-examples-closeout.md`: historical closeout note for the #10 + documentation and runnable examples umbrella. +- `agent-docs-mcp-closeout.md`: historical closeout note for the #13 agent + docs and MCP evaluation umbrella. + +## Keep, Update, Or Retire + +- Keep durable maintainer references such as contract maps, store creation + decisions, release order, and failure playbooks. +- Keep closeout notes only as historical reconciliation records. They should + say which umbrella issue they close and should not be treated as ongoing + policy documents. +- Move user-facing guidance back to `docs/public/`. +- Move agent-oriented package context back to `docs/agents/`. + +## When A SPEC Would Be The Right SSOT + +This folder intentionally avoids introducing a full SPEC or ADR system. If the +repository later accepts long-lived process or architecture rules that multiple +project notes must follow, those accepted rules should move into a dedicated +SPEC and these notes should link to it instead of restating them. + +The clearest current SPEC candidates are: + +- cross-repository release-order policy +- accepted package-boundary rules between `react-socket-store` and + `socket-store` +- accepted store-creation and adapter-integration conventions once they stop + evolving as issue-by-issue docs work diff --git a/docs/project/agent-docs-mcp-closeout.md b/docs/project/agent-docs-mcp-closeout.md index d9fd98f..6dde4bf 100644 --- a/docs/project/agent-docs-mcp-closeout.md +++ b/docs/project/agent-docs-mcp-closeout.md @@ -43,3 +43,10 @@ closeout branch. Issue #59 remains blocked on an owner-confirmed public docs URL/path. Treat that as separate public docs hosting work, not as a blocker for the #13 umbrella reconciliation. + +## Future SSOT Need + +If the repository later accepts a durable policy for agent-facing docs, +cross-package agent boundaries, or MCP-as-docs-query evaluation, that accepted +policy should move into a dedicated SPEC instead of remaining only in this +closeout record. diff --git a/docs/project/documentation-examples-closeout.md b/docs/project/documentation-examples-closeout.md index 5f73691..a2bc024 100644 --- a/docs/project/documentation-examples-closeout.md +++ b/docs/project/documentation-examples-closeout.md @@ -40,3 +40,9 @@ No additional runtime behavior is required in this closeout branch. Issue #58 tracks public docs snippet verification. Treat that as the remaining hardening work for executable README and `docs/public` examples, not as a blocker for the #10 umbrella reconciliation. + +## Future SSOT Need + +If documentation conventions, example-shape requirements, or release-order +dependencies become durable cross-cutting rules, move those accepted rules into +a dedicated SPEC instead of continuing to spread them across closeout notes.