docs: design proposals for issues #2, #3, #4, #5 #9

Design proposals for the four larger / greenfield issues — #2 (Vault secrets), #3 (custom domains), #4 (BYO IdP), #5 (repo-migration auto-port) — to review and approve before implementation. (The two tractable enhancements, #6 observability and #7 platform agent-work, shipped as implementation PRs.)

Each proposal under docs/proposals/ is:

• Anchored in real code — concrete file:line for every seam (verified, not guessed: e.g. domains.ts:parseDomainRegistry, server.ts:resolveAppHost:1767, dispatcher.ts:WEBHOOK_EVENTS, the app-auth extraEnvFrom mount).
• Concrete — actual manifests, tool signatures, and code shapes you could build from.
• Validated where possible — the Vault proposal helm templates its chart (hashicorp/vault 0.33.0, vault-secrets-operator 1.4.0 confirmed to exist).
• Honest — explicit hard parts, tradeoffs/alternatives, and Open questions per doc.

The four

• #2 self-serve secrets (Vault) — per-app env vars via Vault alongside sops (replacing sops would rewrite the whole fork-sealing sovereignty invariant). The crux is single-node unseal without cloud KMS: a concrete strategy (Shamir keys sealed into the existing sops trust root, replayed by an unseal Job) with dev-mode/transit/cloud-KMS all rejected and why. VSO syncs Vault KV → a k8s Secret onto the existing extraEnvFrom seam, so _app-template needs no change.
• #3 self-serve domains — most plumbing exists (registry, resolver, per-host cert, create_app(domain:)); the gap is self-serve granting + DNS ownership verification (the Vercel-style crux) + public ACME TLS (the internal CA can't sign public domains).
• #4 bring your IdP — mitosis up IdP env → Forgejo as OAuth2 relying party → IdP groups mapped to Forgejo orgs/teams; mcp authz already keys off Forgejo membership, so synced identities flow through unchanged. Notes the agents QA-login coupling.
• #5 repo migration — a new agent "port" role conforms a migrated repo onto the template via create_app; trigger via webhook (HMAC vs PAT discussed — none exists today), bulk via the sweep with a concurrency guard + ported idempotency state. Flags the non-Node-source limitation.

How to use

Comment on the Open questions in each, then approve (or steer) the approach. Each proposal lays its build out as phased, per-repo PRs — approval turns it into the plan.