prole/docs/plans

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