Files
ZitPlane/notes/DOCS-01.md
T

45 lines
4.3 KiB
Markdown

# 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.