636a2795cb
Adds docs/plans/ as the canonical engineering reference for completed and
in-flight initiatives. Written for jr/mid engineers who have not seen the
repo before — each plan starts with strategic context and links to existing
code before asking for changes.
README.md index, audience, and status conventions
deployment-modes.md four-mode installer (min/k3d/k3s/gke), welcome-screen
mode selector, min-mode fast-path. Status: shipped.
knoe-auth-round-1.md Kerberos KNOE.DEV realm, invite-OTP enrollment,
Google corroboration, TOTP 2FA. Status: operational.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
||
|---|---|---|
| .. | ||
| customer-deploy-resync.md | ||
| deployment-modes.md | ||
| knoe-auth-round-1.md | ||
| README.md | ||
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
- Copy
knoe-auth-round-1.mdas a template — the section structure is the convention. - Lead with why (one or two paragraphs). Half the value of a plan is forcing the author to articulate the motivation.
- 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.
- 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.
- Open an MR. Plans are reviewed like code.