diff --git a/docs/spec/07-implementation-phases-todo.md b/docs/spec/07-implementation-phases-todo.md index 3d81439..014e7eb 100644 --- a/docs/spec/07-implementation-phases-todo.md +++ b/docs/spec/07-implementation-phases-todo.md @@ -369,3 +369,62 @@ Acceptance criteria: - exported data can be assigned back to the correct Revit objects PostgreSQL should be introduced when shared multi-user operation, background jobs or operational scale justify it. External-object count alone does not require an immediate migration. + +## Phase 14: Documentation and Collaboration Handoff + +Goal: + +After the legacy consumer path has been removed, provide one accurate entry point for developers, contributors and LLM-assisted work. + +Timing: + +- perform the final rewrite after legacy cutover so the documentation describes only the supported architecture +- update documentation incrementally during earlier phases, but do not present transitional paths as the long-term design + +README target structure: + +- short project purpose and current maturity/status +- supported domain workflow at a high level +- technology stack +- prerequisites +- recommended Docker development quick start +- direct local development start +- test, type-check and build commands +- database persistence, migration, backup and restore basics +- production deployment/install instructions once a production setup exists +- concise documentation map +- contribution entry point + +README content to remove or relocate: + +- historical requirement checklists +- file-by-file implementation status from early prototypes +- obsolete legacy consumer architecture +- long domain specifications already maintained in `docs/` +- broken links and claims that are not verified by the current code + +Documentation tasks: + +- add a `docs/README.md` index with current, future and archived documents clearly separated +- keep current architecture, domain invariants, API behavior and interaction behavior synchronized with code +- archive superseded initial requirements under `docs/archive/` when they are still useful for traceability +- remove obsolete documentation that has no remaining historical or operational value +- update `AGENTS.md` with current entry points, supported/deprecated paths and forward architecture constraints +- add a concise contributor workflow for branches, migrations, tests and commits +- document how a colleague creates an empty local database and optionally loads safe sample data +- avoid duplicating the same architecture facts across README, `AGENTS.md` and detailed docs; link to one source of truth + +Deployment documentation requirements: + +- distinguish development Compose from production deployment +- do not label the hot-reload development stack as a production setup +- document required environment variables, ports, health checks, persistent storage and migration behavior +- verify backup and restore procedures + +Acceptance criteria: + +- a colleague can clone the repository and start a clean development environment using only the README +- a contributor can identify the supported architecture and relevant code entry points without reading historical specs +- an LLM receives domain invariants, current module boundaries and deferred architecture direction without relying on stale legacy files +- every README command and internal documentation link is verified +- production instructions describe a real tested deployment path or clearly state that none is supported yet