@mriekki/project-forge 4.26.1 → 4.27.1

package/assets/generated/ASSEMBLY.json

@@ -1,10 +1,10 @@
 {
   "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.26.1",
+  "version": "4.27.1",
   "components": {
     "core": {
-      "revision": "670b84af788323ce361a49677aff772c0d1541c4",
+      "revision": "eac51d50a9e3c8931159ee8dedba79e63ba7867b",
       "version": "4.3.1",
       "distribution": "greenfield-workspace",
       "files": [
@@ -368,6 +368,21 @@
           "destination": ".github/skills/ux-review/SKILL.md",
           "sha256": "2d0031a7041b8174ef056cf35015d5a9faadbc960313b3d1117bf55b8cb44486"
         },
+        {
+          "source": "core/skills/review-user-feedback/SKILL.md",
+          "destination": ".github/skills/review-user-feedback/SKILL.md",
+          "sha256": "80f6087b222b76d93b92e5cbacf33ac1af1a6e797bf27b796b7d70b34280d5e0"
+        },
+        {
+          "source": "core/process/ENGINEERING_BACKLOG.md",
+          "destination": "docs/process/ENGINEERING_BACKLOG.md",
+          "sha256": "49f3f6d4f48ffed74c8a22e075a8efe1c04c6f40d1c3b978184e4c29a6e00bfa"
+        },
+        {
+          "source": "core/skills/manage-backlog/SKILL.md",
+          "destination": ".github/skills/manage-backlog/SKILL.md",
+          "sha256": "23561dfe3d5010ea9bfbb41ae7657734c40477d43303b56f4a05ac8fd8ad6ef8"
+        },
         {
           "source": "core/instructions/project-forge-web-guidance.instructions.md",
           "destination": ".github/instructions/project-forge-web-guidance.instructions.md",
@@ -386,7 +401,7 @@
       ]
     },
     "deployment": {
-      "revision": "e9ca6e12e5b19f691b25ce0aba758a43c3df2913",
+      "revision": "0f80ad06eedeeeb84fcf70cd367873b23d70af25",
       "distribution": "greenfield-project",
       "files": [
         {
@@ -599,6 +614,31 @@
           "destination": "tools/project-forge-deployment/project_forge_deployment/proxy_peer.py",
           "sha256": "ae6c8cb26b83ed07765fa4740ce5c68f52cafd2209b4f055887a4457cfb41c03"
         },
+        {
+          "source": "src/project_forge_deployment/auth_recovery_guard.py",
+          "destination": "tools/project-forge-deployment/project_forge_deployment/auth_recovery_guard.py",
+          "sha256": "8ca97923b994f07655b04062556e2dd755c2127ff134ecbfe64c64f20f0e5ac8"
+        },
+        {
+          "source": "src/project_forge_deployment/auth_recovery_capture.py",
+          "destination": "tools/project-forge-deployment/project_forge_deployment/auth_recovery_capture.py",
+          "sha256": "de8e2db1d66b07d69afe11aa331264cc180cd9b3ecf734c175cd1fdff5764d4c"
+        },
+        {
+          "source": "src/project_forge_deployment/auth_recovery_lifecycle.py",
+          "destination": "tools/project-forge-deployment/project_forge_deployment/auth_recovery_lifecycle.py",
+          "sha256": "ade089a5b1e9ee98ca06e81f6629b07f3786e65a106f3bdd0c3639cfccd038a8"
+        },
+        {
+          "source": "src/project_forge_deployment/auth_recovery_schedule.py",
+          "destination": "tools/project-forge-deployment/project_forge_deployment/auth_recovery_schedule.py",
+          "sha256": "10e7e9b8d2f1b24c9abb1f10aebbd9a89677896ee4d51d33d12f8a0f174bed23"
+        },
+        {
+          "source": "src/project_forge_deployment/auth_recovery_retention.py",
+          "destination": "tools/project-forge-deployment/project_forge_deployment/auth_recovery_retention.py",
+          "sha256": "953a5e4ef790a61b6ba8742352a89b97ace346b116033e03831c9a19dd7e6288"
+        },
         {
           "source": "src/project_forge_deployment/recovery_scope.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/recovery_scope.py",
@@ -712,7 +752,7 @@
         {
           "source": "docs/RECOVERY_READINESS.md",
           "destination": "docs/project-forge/RECOVERY_READINESS.md",
-          "sha256": "ae94a858c9431ad1f432cb75e76b532d83f69c8ca163707ac12d9ea11c60edc1"
+          "sha256": "61d4b26d5f126acbc544925489acb3adc8d6c7ea5d2d02b4b71bf6ccb3d3171b"
         },
         {
           "source": "docs/images/developer-environment-journey.svg",
@@ -730,6 +770,112 @@
           "sha256": "357896c40ff2c7a93bf77811af61d2559103d2e386a5fd887c7041d016114b10"
         }
       ]
+    },
+    "authentication": {
+      "revision": "6db1c1e8a0d3cb0a20aa3415ca0e228f8849df46",
+      "distribution": "greenfield-project",
+      "files": [
+        {
+          "source": "src/ProjectForge.Auth/AdmissionPolicy.cs",
+          "destination": "tools/project-forge-auth-kit/src/ProjectForge.Auth/AdmissionPolicy.cs",
+          "sha256": "74b76dd227ff3dd5545e14ff69283ef02dd06017165bf35189bf99e041103f22"
+        },
+        {
+          "source": "src/ProjectForge.Auth/AuthenticationDiagnostics.cs",
+          "destination": "tools/project-forge-auth-kit/src/ProjectForge.Auth/AuthenticationDiagnostics.cs",
+          "sha256": "b1c0d112e963bc3122b56c1a5459c2d3e6575d391433b85f6e02d0bc4fbb58a2"
+        },
+        {
+          "source": "src/ProjectForge.Auth/ProjectForge.Auth.csproj",
+          "destination": "tools/project-forge-auth-kit/src/ProjectForge.Auth/ProjectForge.Auth.csproj",
+          "sha256": "25d111608dc0c1dd47702cd0501f7de2e20d67552ff7e1c3779722985c27641e"
+        },
+        {
+          "source": "src/ProjectForge.Auth/PwaExistingProjectCompatibility.cs",
+          "destination": "tools/project-forge-auth-kit/src/ProjectForge.Auth/PwaExistingProjectCompatibility.cs",
+          "sha256": "5ab5b6b4f017b8eed3d1d412966420eba07ed102b4fb41ecffd012ed77812d2c"
+        },
+        {
+          "source": "src/ProjectForge.Auth.Runtime/ProjectAuthStore.cs",
+          "destination": "tools/project-forge-auth-kit/src/ProjectForge.Auth.Runtime/ProjectAuthStore.cs",
+          "sha256": "e8255f660c6834803effc5659ca8c7d8517f34c195d371c811b77dee3ecd9c23"
+        },
+        {
+          "source": "src/ProjectForge.Auth.Runtime/ProjectForge.Auth.Runtime.csproj",
+          "destination": "tools/project-forge-auth-kit/src/ProjectForge.Auth.Runtime/ProjectForge.Auth.Runtime.csproj",
+          "sha256": "ae704a37487250b5198cc5c61bfcb600fe03b877d6b818c9700b8768d14365bc"
+        },
+        {
+          "source": "src/ProjectForge.Auth.Runtime/ProjectForgeAuthRuntimeExtensions.cs",
+          "destination": "tools/project-forge-auth-kit/src/ProjectForge.Auth.Runtime/ProjectForgeAuthRuntimeExtensions.cs",
+          "sha256": "73a73a3aca995030c3e2db90b8670e2998df348266bff196b3686751ce0325f9"
+        },
+        {
+          "source": "tools/household_connect.py",
+          "destination": "tools/project-forge-auth-kit/household_connect.py",
+          "sha256": "f3517f483fc027f9db3cfb3256000bf9738509cbeb17711fa3fbf93dd91df7be"
+        },
+        {
+          "source": "docs/HOUSEHOLD_REGISTRY.md",
+          "destination": "tools/project-forge-auth-kit/docs/HOUSEHOLD_REGISTRY.md",
+          "sha256": "17a466927402398f5b69a958325aaaaf5ea953193b8d3c60d5d5bf201dca8009"
+        },
+        {
+          "source": "docs/HOUSEHOLD_INFRASTRUCTURE_ADOPTION.md",
+          "destination": "tools/project-forge-auth-kit/docs/HOUSEHOLD_INFRASTRUCTURE_ADOPTION.md",
+          "sha256": "5cbbc6843d4a02b8f50153b6cc9cbaad9df6629748d8a541524af31bc9b07bdf"
+        },
+        {
+          "source": "src/ProjectForge.Transport/ProjectForge.Transport.csproj",
+          "destination": "tools/project-forge-auth-kit/src/ProjectForge.Transport/ProjectForge.Transport.csproj",
+          "sha256": "213e625c19e95b2a5ef315f01e2ca63fa56d3f5d1634dce920d493aeec1a4240"
+        },
+        {
+          "source": "src/ProjectForge.Transport/StrictPublicOriginTransport.cs",
+          "destination": "tools/project-forge-auth-kit/src/ProjectForge.Transport/StrictPublicOriginTransport.cs",
+          "sha256": "3c91970ad8f7f4feb0db8eda2289109a7748d439d71752a13a1c8e394b8070fd"
+        },
+        {
+          "source": "samples/ProjectForgeAuth.Api/Program.cs",
+          "destination": "tools/project-forge-auth-kit/samples/ProjectForgeAuth.Api/Program.cs",
+          "sha256": "baf0471b649864aeb7bdad76a74fe91279cc0a6b708b4487f62b2b940f6334cf"
+        },
+        {
+          "source": "samples/ProjectForgeAuth.Api/ProjectForgeAuth.Api.csproj",
+          "destination": "tools/project-forge-auth-kit/samples/ProjectForgeAuth.Api/ProjectForgeAuth.Api.csproj",
+          "sha256": "5f77a342dbfd3f062705f77f42285d41ee7ded2122533045d54de8d66cacb93b"
+        },
+        {
+          "source": "samples/ProjectForgeAuth.Api/wwwroot/index.html",
+          "destination": "tools/project-forge-auth-kit/samples/ProjectForgeAuth.Api/wwwroot/index.html",
+          "sha256": "97f28fd0a4269ecbff7cc2ac94d12fdcad236b0f5bd07c538e7d241f4796dfb0"
+        },
+        {
+          "source": "samples/ProjectForgeAuth.Api/wwwroot/auth.js",
+          "destination": "tools/project-forge-auth-kit/samples/ProjectForgeAuth.Api/wwwroot/auth.js",
+          "sha256": "cfb0d94c2c4b9bb2093dc9e322c226a8e4eead0a8cef31f194ddbac5d3420823"
+        },
+        {
+          "source": "src/ProjectForge.Auth.Runtime/ResendProjectInvitationDelivery.cs",
+          "destination": "tools/project-forge-auth-kit/src/ProjectForge.Auth.Runtime/ResendProjectInvitationDelivery.cs",
+          "sha256": "ff6a62f99eb984388c265aa72f47f3b223a3594371f8f041208f5f4e4887f017"
+        },
+        {
+          "source": "docs/PROJECT_AUTH_REFERENCE.md",
+          "destination": "tools/project-forge-auth-kit/docs/PROJECT_AUTH_REFERENCE.md",
+          "sha256": "1bbca014b897f3748e8af9039ba39cf14e8c445cf4748b2596b5ee733876a90b"
+        },
+        {
+          "source": "tools/project_auth_recovery.py",
+          "destination": "tools/project-forge-auth-kit/project_auth_recovery.py",
+          "sha256": "4f7864e33a1bc8bbb577a3459e06ed2fcf7e65a8349513c17510917680e68c9e"
+        },
+        {
+          "source": "docs/AUTH_RECOVERY_RETENTION.md",
+          "destination": "tools/project-forge-auth-kit/docs/AUTH_RECOVERY_RETENTION.md",
+          "sha256": "bc75171c05fdc3f454c67dcc3e2b7e226946ac32b5d02de62c9fc3b0b3bef0cf"
+        }
+      ]
     }
   }
 }

package/assets/generated/authentication/docs/AUTH_RECOVERY_RETENTION.md

@@ -0,0 +1,101 @@
+# Auth Kit recovery-set inventory and retention contract
+
+This is an internal low-level Project recovery building block, not an
+operator-ready Production backup command and **not** application recovery
+qualification. The canonical generated Auth Kit helper is
+`tools/project-forge-auth-kit/project_auth_recovery.py`.
+
+## Inert backup set
+
+The owner must first independently quiesce its *exact* application instance,
+prove a stable stopped Docker container/image and stable private storage, and
+checkpoint any SQLite WAL. The `capture_quiesced_set(source, destination,
+declaration, runtime_guard)` helper cannot stop the app or prove that the
+provided runtime guard is trustworthy.
+
+Use a new private backup-set parent (0700 on POSIX), outside the live data
+tree. Each set name must have form `YYYYMMDDTHHMMSSZ-<8..32 lowercase hex>`
+with a valid UTC calendar timestamp and collision-resistant suffix. The set
+contains exactly `auth.sqlite`, `keys/key-*.xml`, and `receipt.json`.
+Capture publishes exclusively; an existing destination, even an empty one
+created after the initial check, is never replaced. A failed capture cleans
+only its newly created private staging directory.
+
+The receipt contains only Project identifier, recovery policy, protector
+generation and file digests. It is **not signed** and cannot establish
+provenance against a privileged attacker capable of rewriting both data
+and receipt. Provider credentials and application secrets are not stored
+in it.
+
+## Read-only inventory and retention
+
+`plan_verified_retention(sets_root, declaration, keep_last=7)` inspects
+every set before recommending **candidate names only**. It requires owner
+private inventory storage, exact canonical names, valid receipts, complete
+SQLite/key material, SHA-256 integrity, compatible Auth Kit schema and the
+same declared Project, generation and authentication policy. Any
+interrupted staging directory, symlink, missing/corrupt member, unknown
+directory, or unexpected Project identity blocks the entire plan.
+
+The function preserves at least two newest verified sets and at most
+1,000 tracked sets; the **plan never deletes anything**. No background job,
+notification, or email receipt is installed by this function.
+
+## Explicit disposable-only deletion primitive (not a scheduled operation)
+
+`apply_reviewed_disposable_retention(sets_root, lock_directory, declaration,
+reviewed_plan, keep_last=7, environment="disposable",
+authorize_disposable_delete=True)` is a Linux-only, low-level primitive.
+It rejects every non-disposable environment, implicit authorization, unsafe
+private directories, symlinks, corrupt sets, and inventory changes since the
+complete **read-only plan** was reviewed. It preserves at least the latest two
+verified recovery sets, bounds deletions to 32 per invocation, uses a private
+nonblocking retention lock, and anchors unlink/rmdir operations to no-follow
+directory descriptors instead of invoking recursive path deletion. After
+each batch the operator must obtain and review a new read-only plan.
+
+**This is not automatically called by capture or setup**, and is not a
+Production retention CLI. The caller is responsible for proving the exact
+generated Project's ownership, separation from live data, completed backup,
+and the intended disposable environment. A directory deletion spanning
+multiple files is **not atomic**; on a filesystem failure, a partially
+pruned old candidate may need manual inspection/reconciliation before
+any further retention or backup inventory planning. Do not treat a
+partial failure as retention success.
+
+Deployment Kit must still add and qualify a separately reviewed operator
+driver coordinating the backup/recovery lifecycle lock, durable status and
+receipts, persistent scheduling, recovery-point verification, escalation and
+notification before automatic retention is permissible.
+
+## Restore is isolated and not readiness
+
+`materialize_disposable_restore` creates only a new separate directory
+outside backup and live paths and rechecks the hashes. No live data
+overwrite or application restart occurs. A separate disposable application
+must demonstrate actual key-ring protector viability, session-preservation
+or invalidation policy, provider configuration recovery and health before
+`applicationRecoveryReady` can ever be true. Artifact inspection always
+reports it as **false**.
+
+## Running application health is not recovery readiness
+
+The managed .NET Auth Kit maps `GET /health` **behind the exact trusted
+Caddy peer/public-origin middleware**, not on an unprotected direct socket.
+It performs a read-only check that the current per-Project Auth SQLite file
+already exists with supported schema and expected account/session tables.
+Missing, uninitialized or corrupt SQLite returns HTTP 503 without creating
+a replacement identity database. An ordinary running instance with a
+readable store returns 200. The endpoint exposes no account details,
+filesystem paths, providers or session tokens.
+
+This is an **application liveness signal only**, not a recovery completion
+gate: even 200 does not prove that the restored DataProtection keyring
+can decrypt historical state, that a prior session still authorizes,
+that real Google/Resend work, that the backup set was preserved, that a
+scheduled job/alert reached its target, or that normal routed traffic
+is safe. All those remain independently proven acceptance requirements.
+
+This material is not permission to change any PWA Production service, use
+a household Provider credential, release the Authentication component to
+npm, or label a generated Project ready for Production.

package/assets/generated/authentication/docs/HOUSEHOLD_INFRASTRUCTURE_ADOPTION.md

@@ -0,0 +1,55 @@
+# One-time Household Infrastructure Adoption — PWA Pilot
+
+**Status (2026-11-14):** Household Registry and Project Auth runtime source PRs are merged. The PWA-specific Auth Kit cutover was independently accepted in [PWA issue #43](https://github.com/mriekki/family-meal-planner-mark-pwa/issues/43), using a *fresh app-owned Auth Kit account/session database and persistent keyring* because the PWA was an unused shell; its prior records and credentials were preserved separately for rollback. **This does not qualify shared household provider resources, general generated-Project recovery or a published Authentication-enabled Project Forge package.** Auth Kit [release issue #5](https://github.com/mriekki/project-forge-auth-kit/issues/5) is the current release gate, and [recovery issue #9](https://github.com/mriekki/project-forge-auth-kit/issues/9) tracks generated-Project readiness. No provider/Production changes are authorized by this document.
+
+This is the agreed one-time path for reusing relevant Family Meal Planner PWA infrastructure to bootstrap shared Project Forge household defaults. Do not repeat Google, Cloudflare, and Resend setup from scratch merely because a reusable household profile is introduced.
+
+The Authentication Kit owns this provider-resource assessment proposal. Existing-repository adoption, New Project discovery, deployment mechanics, and the PWA's own work-item approvals remain owned by their established Project Forge components.
+
+## Separate infrastructure and application responsibilities
+
+**A — Existing household infrastructure (first):** Inventory the existing PWA Google Cloud configuration, Cloudflare account/domain/Tunnel/Caddy network, Resend sending domain, and Ubuntu/Docker environment. Determine shared administrator-owned assets versus application-specific resources. Use independent **read-only provider verification** to establish current resource existence and ownership. Reuse appropriate shared assets, but allocate separate OAuth clients/redirects, narrowly scoped Resend keys, and exact app-owned ingress/routes for future Projects. PWA's credentials, hostnames, database, production route and runtime stay as-is.
+
+**B — PWA-specific application adoption (accepted):** This migration has already occurred under PWA's separate review and Production approval. The accepted exception uses a newly seeded, isolated Auth Kit account/session database and persistent DataProtection keyring; historical PWA identities/passwords/sessions were *not* automatically translated because no active Product users or substantive Production user data needed migration. Historical PWA data and implementation were preserved for an explicit rollback. A future consumer with established users **must not inherit** this fresh-account exception: preserve or explicitly reconcile identities, sessions, passwords and app-owned authorization through that Project's own reviewed migration. Never auto-link by email or treat Household Registry membership as Project login.
+
+## How to run the implemented assessment
+
+From the private Authentication Kit checkout, run:
+
+    python3 tools/household_adoption.py assess \
+      --checkout /path/to/fmp \
+      --expected-commit <exact-40-hex-pwa-head> \
+      --output /private/existing/directory/pwa-household-assessment.json
+
+The parent output directory must already exist outside the PWA checkout. On Windows, use paths and continuation syntax appropriate for PowerShell. The output is a new JSON report: an existing report is NEVER overwritten. POSIX writes use owner-only mode; Windows permissions depend on the destination directory.
+
+The report is bound to the exact local Git HEAD commit, with hashes for a **fixed allowlist of committed source files**: Project Forge baseline, deployment topology, OIDC implementation, account schema/service/endpoints, Resend adapter, production provider boundaries, and exact origin transport. It never reads uncommitted files, database content, .env, provider credential material, private SSH data, local settings or live provider accounts. No provider API calls or Production actions occur.
+
+The report includes **source-evidence-found** versus **needs-source-review** markers, and all provider candidates remain **provider-inventory-unverified**. Source evidence cannot establish whether live Google, Cloudflare or Resend resources are currently provisioned, reusable or owned by the household. It contains a deterministic assessment SHA-256 for future reviewed plans and no secrets or personal account records.
+
+The source assessor implements **assess** only and never applies changes. Separate
+draft Registry tools now implement the GET-only provider ID verifier and
+name-based discovery, the digest-locked adoption-plan generator, and an
+explicitly reviewed host-local Registry resource import/rollback.
+See `HOUSEHOLD_REGISTRY.md` for the exact operator procedure.
+These are not a live provider migration or automatic PWA identity cutover.
+
+## Required review stages before any migration writes
+
+1. Assess the **delivered** PWA commit using the read-only tool, not an older chat summary or uncommitted worktree.
+2. Independently inventory non-secret Google Cloud, Cloudflare, and Resend resources using
+   the trusted local read-only verification **commands**. Cloudflare allows read-scoped
+   API tokens, whereas Resend may require a Full access key to perform its GET
+   domain metadata reads; this verifier issues GET requests only. Never load or
+   transmit such keys from ChatGPT or hosted CI. Confirm ownership, existing
+   sharing, restrictions and per-Project scope.
+3. Produce a reviewed household profile plan that classifies each asset as preserve, reuse existing shared resource, create separately scoped Project resource, or defer.
+4. Separately approve any actual provider or host write with an idempotent, least-privileged executor, durable receipt and rollback/stop controls. No automatic PWA route or credential replacement.
+5. Treat the accepted PWA Auth Kit cutover as a Project-specific completed event documented in PWA issue #43. For a different established Project, separately approve identity/session migration, disposable-data rehearsal, rollback, authorization and app-specific feature equivalence; do not assume the PWA fresh-account exception applies.
+6. Only enable an opt-in household capability in Bootstrap's existing New Project lifecycle after full generated-Project integration proof.
+
+## Current limitations and safety
+
+Merged Auth Kit runtime includes .NET 10 Google OIDC code flow, per-Project SQLite account/invitation/session persistence, reference browser, exact proxy ingress checks, and a Bootstrap-managed optional generated API. Reusable, disposable Auth Kit recovery tests now cover real SQLite/DataProtection artifacts and isolated application HTTP startup; Deployment Kit includes exact Docker stopped-container capture, disposable stop/capture/resume and a durable interrupted-run journal. These are **not** real provider inventory, per-Project provider setup, durable Production scheduling/alert delivery, real full-application recovery readiness or npm release acceptance. The PWA-specific Production cutover is accepted separately; nothing here authorizes changing it.
+
+Do not commit resulting reports to public repositories. They exclude credentials but still contain useful operational metadata. Secrets stay in protected local/provider input mechanisms, not Git, log output, shell argv, Chat, or plain JSON. PWA Production, FB-001/FB-002 requirements, provider resources and live data are all explicitly outside this change.

package/assets/generated/authentication/docs/HOUSEHOLD_REGISTRY.md

@@ -0,0 +1,246 @@
+# Project Forge Household Registry
+
+Status: **tested Registry and adoption engine under review, not deployed or published as a supported capability**.
+
+This is a .NET 10 / SQLite service that persists shared household membership,
+registered Projects and non-secret infrastructure references. It can be
+accessed from a browser on Windows, WSL/Linux or macOS by a family Developer
+such as Kyle using his own Google identity.
+
+## Ownership and authority
+
+The Registry stores household identity, approved Google issuer+subject
+membership, admin/developer/member roles, one-time invitations, registered
+Projects, shared resource references, explicit Project-resource bindings
+and audit entries. It does **not** store provider tokens, Project passwords,
+application user accounts, PWA sessions, Google OAuth client secrets,
+Resend keys, SSH credentials or application data.
+
+A household Developer is not automatically an administrator or user of PWA
+or any other Project. Independent applications continue to operate if the
+Registry is temporarily offline.
+
+## First-time setup (trusted host; not a public endpoint)
+
+Provision a private SQLite data directory owned by the non-root service UID.
+For deployment, provide these settings from protected local configuration:
+
+    PF_HOUSEHOLD_DB=/data/household.sqlite
+    PF_HOUSEHOLD_ID=my-household
+    PF_HOUSEHOLD_NAME=My Household
+    PF_INITIAL_GOOGLE_SUBJECT=<exact-preverified-google-subject>
+
+In a trusted host administration session execute exactly once:
+
+    dotnet ProjectForge.HouseholdRegistry.dll admin-init
+
+The exact initial subject must be independently verified; email matches or
+first-visitor behavior never grant administration. The operation refuses an
+already-initialized registry.
+
+The runtime requires:
+
+    PF_HOUSEHOLD_DB=/data/household.sqlite
+    PF_GOOGLE_CLIENT_ID=<per-registry-oauth-client-id>
+    PF_GOOGLE_CLIENT_SECRET_FILE=/run/secrets/google_oidc_client_secret
+    PF_REGISTRY_KEY_DIR=/data/keys
+    PF_REGISTRY_PUBLIC_ORIGIN=https://registry.example.com
+    PF_TRUSTED_CADDY_IP=<exact-reviewed-managed-caddy-ip>
+
+Google callback: https://registry.example.com/signin-google
+
+Do not put credentials in a tracked compose file, Git, Chat, CLI arguments,
+shell history, or a public household profile. The service Dockerfile runs
+as non-root on internal port 8080. The Deployment Kit must own Caddy/Tunnel
+routing, exact public origin, allowed header forwarding and peer convergence;
+do not publish the container directly to LAN/public TCP or trust Docker
+network subnets. Use the Kit's read-only platform peer inspection before
+reviewing the exact Caddy transport setting. The application rejects a
+non-HTTPS or unexpected public host.
+
+The `deploy/household-registry.compose.yml` reference is an isolated
+no-host-port, non-root service with a separately mounted Google OAuth secret
+file, durable SQLite volume and persistent private DataProtection key ring.
+Set `PF_CADDY_NETWORK`, `PF_REVIEWED_CADDY_IP`,
+`PF_HOUSEHOLD_DATA_DIR`, `PF_REGISTRY_GOOGLE_CLIENT_ID`,
+`PF_GOOGLE_CLIENT_SECRET_FILE`, and `PF_REGISTRY_PUBLIC_ORIGIN`
+through trusted host setup. The exact Caddy network/IP values must come
+from the existing Deployment Kit 4.26.1 read-only proxy-peer observation.
+Do not enable or rewrite the shared Caddy route from this Compose template,
+and do not put OAuth secrets into provider inventory JSON.
+
+On POSIX the key ring directory is restricted to owner access. Protect the
+mounted persistent volume, backups and host secret file. A Production
+deployment must validate process UID/GID and backup/restore before cutover.
+
+The .NET runtime uses a Google OIDC code flow with PKCE and server cookie;
+the browser sends an antiforgery header on all mutations. Every Registry API
+call rereads member status so disabling a Developer immediately blocks future
+Registry API access. Provider references always start unverified unless
+installed through a separately approved adoption plan.
+
+## One-time existing household adoption from PWA
+
+First create the exact-commit read-only PWA source assessment, as documented
+in HOUSEHOLD_INFRASTRUCTURE_ADOPTION.md:
+
+    python3 tools/household_adoption.py assess --checkout /path/to/fmp \
+      --expected-commit <exact-40-hex-pwa-commit> \
+      --output /private/evidence/pwa.json
+
+Verify existing shared provider resources with read-only scoped credentials,
+in a trusted local terminal. The Cloudflare and Resend credentials are read
+from PF_CF_READ_TOKEN and PF_RESEND_READ_TOKEN environment variables; Google
+Cloud access uses the current trusted gcloud auth identity.
+
+    python3 tools/household_provider_verify.py verify \
+      --google-project <google-project-id> \
+      --cf-account <account-id> --cf-zone <zone-id> \
+      --cf-tunnel <tunnel-id> --resend-domain <domain-id> \
+      --output /private/evidence/providers.json
+
+**Preferred when existing provider names are known but IDs are not:** locate
+the exact existing Cloudflare zone/tunnel and Resend sender domain automatically
+through their read-only listing endpoints, then independently verify all
+discovered IDs using the original detailed provider API checks:
+
+    python3 tools/household_provider_discover.py discover \
+      --google-project <existing-google-cloud-project-id> \
+      --cf-zone-name <exact-cloudflare-zone-domain> \
+      --cf-tunnel-name <exact-production-tunnel-name> \
+      --resend-domain-name <exact-verified-sender-domain> \
+      --pwa-hostname <exact-existing-pwa-public-hostname> \
+      --pwa-origin-service <exact-existing-pwa-unix-origin-service> \
+      --output /private/evidence/providers.json
+
+The name-discovery command uses the same protected environment variables and
+`gcloud auth` context as the ID-based `verify` command. It fails closed if a
+list is incomplete or paginated, resource names are ambiguous or missing, or
+any detail response disagrees with the expected resource. Its only persistent
+output is the same private, exclusive-created, non-secret provider observation
+JSON. When both optional `--pwa-hostname` and `--pwa-origin-service`
+are provided, it also performs a **GET** for the remotely managed tunnel's
+ingress configuration, requires exactly one matching existing PWA hostname
+without a path restriction, checks the exact reviewed Unix socket service and
+the owning Cloudflare account, and records only that matched route. A
+missing/changed/ambiguous route fails closed. A locally managed tunnel or a
+Cloudflare account without read permission for the configuration endpoint
+cannot satisfy this optional proof and requires a separately reviewed
+on-host ingress check; do not silently treat a tunnel record as routing
+evidence. The verifier never rewrites the existing PWA route.
+
+The route proof does not check the Caddy virtual-host table, Google OAuth
+client redirects, or live application availability; those still have
+independent acceptance requirements. It does not change tunnel routing or
+attest Google OAuth client callbacks.
+
+**Optional no-API-key-in-the-shell Resend path:** the official Resend CLI
+supports an interactive, locally approved browser OAuth login. After separately
+installing the official `resend` CLI, the operator may authorize an isolated
+local profile (do **not** run this in CI):
+
+    resend --profile household-review login --web
+
+Then append `--resend-cli --resend-profile household-review` to the
+`household_provider_discover.py discover` command above. In that mode, the
+script runs only `resend domains list` and `resend domains get <id>` with
+JSON output, captures/sanitizes CLI output, and does not require
+`PF_RESEND_READ_TOKEN`, pass a token argument or read the CLI credential file.
+The CLI's locally stored OAuth permission may still be broad; only the
+invoked commands are read-only. Resend's browser authorization callback must
+reach the same local machine as the CLI (check WSL/Windows localhost routing
+if needed). No OAuth login is launched or granted by the verification script.
+Cloudflare still needs its separately scoped Zone/Tunnel Read token. For Cloudflare, use a token scoped to **Zone Read** and
+**Cloudflare Tunnel/Connectors Read** on the intended account. **Resend
+currently offers Full access or Sending access keys, not a read-only API-key
+permission**; `GET /domains` requires an authorized key that can retrieve
+domain metadata. The variable name `PF_RESEND_READ_TOKEN` describes the
+**read-only behavior of this verifier**, not the Resend key's privileges.
+If the operator chooses to provide a Full access key, use it **only in the
+trusted local terminal**, never in hosted CI or a tracked file, and remove
+its environment variable after the read. An existing send-only key cannot
+be used for this domain inventory. No new key should be created without
+explicit operator review. **Never paste tokens, key files or Google
+authorization codes into a chat or commit them into Git.**
+
+These commands make only HTTPS GET requests; no provider resource or
+credential is modified. The output contains independently confirmed non-secret
+references, status and observation time. Evidence must be less than 24 hours
+old to create a new plan. Dashboard screenshots are useful inventory clues
+but are **not** equivalent to this API-backed evidence.
+
+Create the exact reviewed import plan:
+
+    python3 tools/household_adoption_plan.py plan \
+      --assessment /private/evidence/pwa.json \
+      --provider-evidence /private/evidence/providers.json \
+      --household-id my-household \
+      --registry-origin https://registry.example.com \
+      --pwa-hostname <exact-existing-pwa-public-hostname> \
+      --pwa-origin-service <exact-existing-pwa-unix-origin-service> \
+      --output /private/evidence/adoption-plan.json
+
+Supplying the exact PWA hostname and Unix origin to the plan command
+requires the upstream provider evidence to contain a matching, independently
+read Cloudflare tunnel route. A missing or changed route cannot be used to
+approve the household resource-reference import. This binds the preexisting
+PWA ingress preservation review into the exact provider-evidence digest;
+it does not test the downstream Caddy virtual-host mapping. The two route
+parameters must be supplied together. If the tunnel is locally managed and
+the configuration-read API is unavailable, stop and obtain a separately
+reviewed local ingress proof rather than claiming the remote tunnel
+configuration was verified.
+
+Review the full plan and its printed file SHA-256. After administrator
+approval, copy the reviewed plan securely to the Registry host, ensure
+PF_INITIAL_GOOGLE_SUBJECT identifies the approved household admin, and
+set PF_APPROVED_ADOPTION_SHA to that exact reviewed file checksum and
+PF_HOUSEHOLD_ADOPTION_PLAN to the local private file. Then run, from the
+trusted host context only:
+
+    dotnet ProjectForge.HouseholdRegistry.dll admin-import
+
+This is the **actual one-time household resource reference migration**.
+It creates five reviewed Google/Cloudflare/Resend reference records in one
+SQLite transaction with an audit receipt, preserves existing matching
+resources, and treats an identical exact plan replay as no-op. It does not
+create new OAuth clients, Resend keys or DNS routes and does not modify PWA
+or its Production data. A different plan must receive a fresh reviewed
+checksum. An operator-reviewed resource reference is not a cryptographic
+attestation of continuing provider availability.
+
+## Invite another Developer
+
+The initial administrator signs in to the Registry browser with Google,
+creates a one-time 48-hour invitation for the Developer's verified Google
+email and shares the resulting token privately (not in a URL, Git issue or
+terminal logs). Kyle signs into the same Registry origin using his Google
+account and redeems that token. He can then register Projects and view
+approved household references. He still needs separately approved provider
+credentials and Project-specific application authorization.
+
+The Registry address itself is a non-secret **explicit locator** shared with
+the Developer. New Project Forge setup must verify that exact HTTPS origin
+and perform authorized discovery; it must never scan household networks or
+copy the Registry database.
+
+## Backups and safe recovery
+
+Use a trusted SQLite consistent backup or stop the Registry before copying
+its protected volume. Protect the directory and backups with owner-only
+permissions; perform an integrity check and disposable restore rehearsal
+before Production adoption. A schema version newer than the service
+understands fails closed. Backup and restoration must not overwrite PWA's
+independent SQLite database or application-managed migration journals.
+
+## What is still required for production and next kit
+
+Registry deployment into the actual household, real provider credentials and
+resource verification, controlled PWA authentication adapter/migration,
+existing-account and password compatibility proof, full Google callback and
+hostile Caddy/Tunnel tests, cross-platform New Project setup integration and
+package distribution/installed consumer qualification.
+
+These are real release blockers, not solved by the Registry's passing domain
+tests. A successful Registry deployment is also not permission to rewrite
+PWA Production, reset user sessions or install a new provider adapter.