Files

4.3 KiB

DOCS-01 — Repository knowledge-base and developer rules

Date: 2026-11-22 State: COMPLETED — exact manifest/link/scope audit PASS; documentation committed locally, not pushed to Gitea. Baseline: 40af5007503501643d1e9ad2ab3939ba57dab5f9 (main) User approval: Create Git-tracked notes/, project/ and docs/ knowledge areas, add mandatory docs-first and documentation-sync rules to AGENTS.md, give each new knowledge-area directory a README and a MINIFEST.md.

Scope lock — documentation only

Allowed: notes/**, project/**, docs/**, root AGENTS.md, README.md and MINIFEST.md for navigation and root-folder inventory. Source inventory can be read in core/**, auth/**, users/**, deployment/**, tests/**, scripts/**, packages/**.

Out of scope: All app/backend/auth logic, upstream ZITADEL snapshot, Compose, UI, package versions, secrets, .env, tests, CI, releases, deployment, remotes/production changes. Existing unrelated untracked AI_INSTRUCTIONS.md must not be modified/staged.

Required deliverables

  1. notes/: how-to, manifest, this pre-change plan and append-only change timeline.
  2. project/: developer-oriented map: real architecture, features/pages, function/logic ownership, module/technology rationale, setup references, phase change history, source file inventory.
  3. docs/: user-facing how-to for current features/pages/buttons, setup prerequisites, error/limitations; preserve earlier architecture/phase/evidence files.
  4. AGENTS.md: enforce pre-change notes, implementation logs, concurrent developer and end-user documentation updates, status/provenance rules, README/MINIFEST maintenance on new first-party folders.
  5. Explicitly distinguish existing implementation, not-yet-run tests, planned capabilities and unverified runtime behavior.

Pre-change evidence

  • main baseline matches Gitea 40af500....
  • notes/, project/ previously absent; docs/ already contains ARCHITECTURE, DEVELOPMENT, PHASES and P02/P03/P04 evidence.
  • P02 backend configuration, P03 imported upstream Login V2 v4.20.4, P04 custom Account Portal source exist; runtime/CI/deployment remain unverified.
  • AI_INSTRUCTIONS.md already exists as unrelated untracked file; preserve.
  • No change to other project sources approved.

Final result / verification

  • Added Git-tracked notes/ (README, MINIFEST, DOCS-01 plan/results, chronological log) before creating other documentation content.
  • Added project/: README, MINIFEST, architecture, file map, function map, feature/page register, setup/dependency rationale, changelog, and exact 701-path Git tracked-source inventory.
  • Expanded existing docs/: README, MINIFEST, first-party page-by-page/visible button guide, operator/setup guide, feature status and troubleshooting. Preserved P02/P03/P04 existing evidence.
  • Root AGENTS.md now requires notes before every change, synchronized developer/user docs, historical logs, README and literal MINIFEST for each new first-party directory, accurate verification status, secret-safe Markdown and upstream-vendor exception.
  • Root README.md now navigates all three knowledge areas; root MINIFEST.md lists top-level tracked files/folders and phases.
  • Source-file changes outside documentation paths: none. ZITADEL, Login V2, Account Portal, Docker Compose and dependency manifests unchanged.
  • Focused documentation-only audit (2026-11-22): notes 4/4 manifest entries, project 9/9, docs 12/12; 28 Markdown files checked, 0 broken relative links, Git tracked file inventory 701/701, out-of-scope staged files 0, staged application code files 0, unrelated AI_INSTRUCTIONS.md untouched.
  • One generated source-inventory trailing blank line corrected; final git diff --cached --check PASS.
  • Local build, test, dev server, Docker, CI and deployment: NOT RUN (documentation-only phase).
  • Git checkpoint: record is in this phase's local Git commit; inspect git log -1 for exact SHA. No remote push was requested in DOCS-01.
  • Preexisting limitations unchanged: P02 Docker acceptance, P03 Login build, P04 Account Portal OIDC/build and production deployment remain unverified.

Maintenance rule: Future approved changes must first update their own dated notes/ phase record and then keep project/, docs/ and MINIFEST.md synchronized with actual source and evidence.