# Plans

Engineering plans for the **knoe.dev** platform. Each document scopes one initiative — its strategic context, design, schema, and the components it adds — and is intended to outlive the implementation work itself: when the work ships, the plan stays as the architectural reference.

## Who this is for

You are a junior or mid-level engineer who has been invited to contribute to knoe.dev. These documents are written for you. They assume:

- You are comfortable reading code and skimming a Maven `pom.xml`.
- You have used Kubernetes at least casually (`kubectl get pods`, helm charts).
- You may **not** have prior Kerberos, OIDC, or CNPG experience — relevant terms are defined inline or in the glossary section of each plan.
- You have not seen this repo before. Each plan starts with the strategic context and links to existing code before it asks you to write any.

If a sentence in a plan assumes knowledge you don't have, that's a bug in the plan — open an issue.

## What lives here

| File | Initiative | When you should read it |
| --- | --- | --- |
| [`knoe-auth-round-1.md`](knoe-auth-round-1.md) | Identity backbone for the platform: MIT Kerberos KDC + invite-anchored web enrollment + TOTP 2FA. Round 1 of N. **Shipped.** | Before touching `authority/`, `etc/init_kdc.sh`, `etc/init_knoe_users.sh`, anything in `deploy/gcp/gke/knoe-auth-*` or `knoe-kdc-*`, or the `knoe.*` database schema. |
| [`deployment-modes.md`](deployment-modes.md) | Four-mode installer (`min` / `k3d` / `k3s` / `gke`) with a welcome-screen mode selector and a `min`-mode fast-path through the wizard. **Shipped in Phase 0.** | Before touching `knoe/ui/screens/welcome.py`, `knoe/ui/screens/navigation.py`, or adding any new wizard screen. |

Each plan follows the same shape: **Context → How it's wired (file references) → Architecture → Schema / API → Step-by-step → Verification → Glossary.**

## Status conventions

A plan in this directory has one of three statuses, declared at the top:

- **Active plan. Not yet implemented.** — the design is agreed, the code isn't there yet. Read deliverables top-to-bottom.
- **Implemented and operational. Architectural reference.** — the work shipped. The doc explains how it works and *why*; cross-references point at real files. Read the context and the rationale; jump to specific sections when you have a question.
- **Archived.** — superseded by a later round or a different approach. Lives in `archive/` with a one-line "see X instead" pointer.

## Customer deploys

The knoe.dev platform supports per-customer deployments — currently the most active is `prole.org`. The convention is **branches in this repo**, not separate forks. Customer-specific divergence (config, branding, on-prem manifests, kubeconfig handling) lives on a branch named after the customer; platform changes always land on `main` and customer branches rebase or merge from main on a regular cadence. See the customer's own `docs/plans/` for resync notes — for example, `~/dev/prole/docs/plans/customer-deploy-resync.md` if you have that working tree checked out.

## How to propose a new plan

1. Copy `knoe-auth-round-1.md` as a template — the section structure is the convention.
2. Lead with **why** (one or two paragraphs). Half the value of a plan is forcing the author to articulate the motivation.
3. Cite real files with paths relative to the repo root. If you reference something that doesn't exist yet, label it **(net-new)** so a reader doesn't go hunting.
4. End with a **Verification** section — a short checklist a reviewer can run to decide whether the plan is done, or — once shipped — that the implementation still matches the spec.
5. Open an MR. Plans are reviewed like code.