# ZitPlane — contributor and AI-agent instructions ## Project boundaries - Official ZITADEL Go backend is an external, version-pinned image. Do not vendor, fork or modify its core source. - `auth/ui/v2/` owns login frontend presentation; `users/ui/` owns the user portal. - Authentication, OAuth/OIDC callbacks, MFA, passkeys, sessions and token/security behavior are **protected logic**. - App-specific billing, product permissions, usage and license logic belong in the individual apps, not ZitPlane. ## Phase rules 1. Inspect Git status and read `docs/PHASES.md` before editing. 2. Require an explicitly approved scope before each new phase; stay within its exact allowed paths. 3. Do not add fake runnable scaffolds, dependency versions, secret values or speculative upstream imports. 4. On UI-only tasks edit components, styles and approved assets only; preserve auth flows and API contracts. 5. Mock previews and test identities must be confined to development/test; never enable auth bypass in production. 6. Run one focused verification, inspect exact diff, update relevant docs, and make one local Git commit per approved phase. 7. Never push, deploy, create tags, access real user accounts or alter production without explicit approval. ## Security and portability - No credentials, master keys, database data, cert private keys, session tokens or `.env` in Git. - Production configuration must fail closed if required secrets, HTTPS or storage configuration are absent. - Lock external image versions and upstream Login V2 revision; document upgrade procedure. - Prefer readable React/TypeScript components, accessibility, responsive layouts and small reusable tokens. - Never modify upstream authentication machinery to accommodate an AI-generated UI without a separate security-approved scope. ## Developer experience - Keep README files accurate for the current phase. Do not claim an app runs before it is integrated. - Develop on local/test ZITADEL and synthetic users. Verify OIDC, MFA/passkey and redirect flows before release. ## 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 **Before:** audit Git status/current source, create `notes/.md` scope/plan, and confirm approval. **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.