This directory has two audiences:
- Current pre-GA users start in the repository README and the collapsed CLI spec.
- Contributors and maintainers use the contract, architecture, operations, release, and design indexes below.
docs/user/ is historical legacy save/restore guidance until it is rewritten
for the collapsed direct model. Do not use it for new release notes, support
answers, or active product guidance.
The release-facing user path is:
| Document | Purpose |
|---|---|
| README | Current pre-GA public entry point |
| Overview | Collapsed active surface and direct-model boundaries |
| CLI Spec | Current release-facing public command surface |
| AFSCP Direct Contract | Internal trusted platform contract |
The top-level Quickstart, FAQ,
Examples, Troubleshooting, and
docs/user/ pages are legacy references until rewritten. Keep new active
guidance in the collapsed docs listed above.
Use these entry points when changing JVS, validating release behavior, or maintaining a published version:
These are the source of truth for support answers, QA release gates, user-visible behavior, public JSON fields, and help text:
| Area | Start here | Use it for |
|---|---|---|
| Specification map | Overview | Current release-facing and supporting document map |
| Product contract | Product Plan | Current product promises and release scope |
| CLI contract | CLI Spec | Public command behavior and JSON fields |
| AFSCP direct contract | AFSCP Direct Contract | Trusted platform save/list/restore/status/doctor JSON surface |
| Restore contract | Restore Spec | Historical preview/run behavior, safety choices, and recovery |
| Cleanup contract | Cleanup Spec | Preview/run cleanup behavior and protection reasons |
| Go facade | API Documentation | Stable library entry points |
| Architecture | Architecture | Implementation boundaries and component responsibilities |
| Security | Security Model and Threat Model | Trust boundaries and risk labels |
| Conformance | Conformance Test Plan and Traceability Matrix | Required evidence and test coverage |
| Operations | Operations Index | Maintainer runbooks, migration, and repair flow |
| Release | Release Index | Release policy, evidence, changelog, and signing |
These records explain why current release-facing behavior looks the way it does.
They are useful for engineering, product, and QA, but they are not the public
contract. If a design record conflicts with user docs or 02_CLI_SPEC.md, the
release-facing contract wins and the design record needs cleanup.
| Area | Start here | Use it for |
|---|---|---|
| Save point/workspace model | Save Point And Workspace Semantics | Supporting mental model for save points, workspace pointers, and history |
| Explicit workspace folders | Workspace Path And History Pointer Semantics | Implemented explicit-folder and history from design record |
| Smart copy reporting | Smart Copy Boundaries | Implemented transfer-reporting model and remaining copy-planning refinements |
| Repo clone | Repo Clone Product Plan | Implemented repo clone behavior and release evidence checklist |
| Repo/workspace lifecycle | Repo/Workspace Lifecycle Product Plan | Implemented move, rename, delete, and detach design record |
| External control root | External Control Root Product Handoff | Implemented operator/platform profile and later lifecycle parity notes |
These documents are not current commitments unless promoted into the release-facing contracts above:
| Area | Start here | Use it for |
|---|---|---|
| Design index | Design Index | Non-release-facing design notes and active design references |
| Product research | Product Gaps For Next Plan | Non-committal product gaps to consider later |
| Later copy planning | Smart Copy Boundaries | Remaining filesystem gates and optimization refinements not required for GA |
| External lifecycle parity | External Control Root Product Handoff | Later move/rename/delete/detach parity for external control roots |
- User docs use product vocabulary: folder, workspace, save point, history, view, restore, cleanup, recovery, and doctor.
- Developer docs may discuss implementation and release mechanics, but should not become the first stop for ordinary users.
- Product gaps are research notes, not current commitments.
- Implemented design records are explanatory. They do not override the release-facing user docs, CLI spec, or conformance contract.