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.
k3d-gke-mirror.md	Laptop-resident model of the GKE platform — minimum-viable k3d stack (CNPG + KDC) that lets host-side knoe-auth iterate against real Postgres + Kerberos. Active. Phase 1 in flight (Junie).	Before touching k8s/knoe/knoe-kdc-*, the make k3d-knoe-* targets, or docs/local-dev-knoe-auth.md. Phase 1 brief at junie/k3d-knoe-auth-dev-loop.md.
customer-deploy-resync.md	Original plan to converge ~/dev/prole onto knoe-db/main as a customer-deploy branch. Dormant — prole rebrand merged into main; no separate prole working tree currently under development.	Only if you're considering activating a per-customer branching workflow.
junie/ (subdirectory)	Self-contained, single-task work briefs for Junie to consume from inside the IDE. Tactical, single-MR scope, paired against numbered items in ../TODO.md.	When you want to hand a discrete task to Junie or audit what's been queued.
../TODO.md (sibling)	Master TODO index — single source of truth for unfinished work, including reality-vs-intent gaps flagged in CLAUDE.md/AGENTS.md.	Before picking up any task, to see what's already on the queue.

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 is designed to support per-customer deployments via branches in this repo, not separate forks. Customer-specific divergence (config, branding, on-prem manifests, kubeconfig handling) would live 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.

Currently no customer branch is active. The original plan to converge ~/dev/prole into a customer/prole.org branch is captured in customer-deploy-resync.md and is dormant — the prole→knoe rebrand has merged into main itself, and there is no separate ~/dev/prole working tree under development. origin and knoe remotes both point at upstream git@git-ssh.knoe.dev:knoe.dev/knoe-db.git.

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.