## Documentation-first rule — mandatory for ALL future changes
Three distinct Git-tracked knowledge areas are required and must stay synchronized:
1.**`notes/` — development-time scope, planning and phase history.** Before ANY code/config/page/feature/fix/add/remove/refactor (including documentation changes), first write or update a scoped Markdown plan there. State baseline, date, goals, exact allowed paths, exclusions, intended changes, prerequisites, risk and acceptance criteria. Keep in-progress decision log, source evidence, blockers and after-action result. Every update/fix/phase needs a dated entry in `notes/CHANGELOG.md`; do not delete historic outcomes.
2.**`project/` — permanent developer/AI reference.** In the same approved phase, update exact developer descriptions of EVERY affected feature/page/module/file/function, logic location and rationale, dependencies and setup, API/data/security flow, tests/evidence and change history. Maintain `project/FILE-MAP.md`, `project/FUNCTIONS.md`, `project/FEATURES-AND-PAGES.md`, `project/SETUP-AND-DEPENDENCIES.md`, `project/CHANGELOG.md`, and `project/SOURCE-INVENTORY.md` where relevant. Describe unchanged source only when actually inspected; never fabricate behavior.
3.**`docs/` — permanent end-user/operator guidance.** In the same approved phase, document every changed accessible page, button/action, route, feature, permission, setup step, failure case, security or usage limitation in plain, beginner-friendly instructions. Update `docs/USER-GUIDE.md`, `docs/SETUP-GUIDE.md`, `docs/FEATURES-STATUS.md`, `docs/TROUBLESHOOTING.md` and existing focused guides as applicable. Never advertise incomplete source as tested or deployed.
### Mandatory Markdown and manifest policy
- Every **new ZitPlane-owned folder**, including each knowledge-area folder and newly created subfolder, must include its own `README.md` describing **why it exists, who uses it, when/how to update it**, and literal **`MINIFEST.md`** listing its actual direct files/subfolders, owners/purposes, phase and status. The exact filename is `MINIFEST.md` (not `MANIFEST.md`).
- When a first-party file/folder is added, moved or removed, update the relevant parent `MINIFEST.md`, root navigation and source inventory in the same phase. Do not include ignored/generated data in Git manifests as if tracked.
- **Do not edit third-party/upstream/vendor-imported source** (such as nested `auth/ui/v2/apps/login/`, `packages/` or `proto/`) just to inject ZitPlane docs. Preserve upstream byte-for-byte identity and document their paths in `project/SOURCE-INVENTORY.md`; only modify upstream content with explicit scope and license review.
- For preexisting first-party directories not changed in the current phase, add missing per-folder guidance when an approved phase next modifies their structure. Knowledge-area folders `notes/`, `project/`, `docs/` are mandatory immediately.
-`README.md` is the human-friendly entrypoint; `MINIFEST.md` is the exact direct-child inventory; avoid duplicating long feature explanations across both.
### Every change must leave a consistent audit trail
**During:** keep a concise change/decision log and identify each touched function/page/file and user-facing consequence.
**After:** update relevant `project/` and `docs/` files plus manifests, record exact implementation/test/CI results, commit SHA and residual risk in `notes/` and `project/CHANGELOG.md`. Perform one focused scope/patch audit and commit as approved. Do **not** say a CI/build/runtime test passed unless it actually ran.
**Safety:** Never write passwords, personal data, .env contents, secrets, PATs, credentials, private keys or unredacted token-bearing logs into any `notes/`, `project/` or `docs/` Markdown file. Do not expand source write scope simply to satisfy documentation; obtain separate approval if necessary. Remote push/deploy still requires explicit approval.