55 lines
6.0 KiB
Markdown
55 lines
6.0 KiB
Markdown
# 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/<PHASE>.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.
|