litentry · hanwencheng · Jun 2, 2026 · Jun 2, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -3,8 +3,8 @@
 ## Architecture
 Rust monorepo with Cargo workspace. See `docs/arch.md` for component inventory.
 See `docs/spec/credential-backend-interface.md` for the CredentialBackend trait contract (15 methods).
-See `docs/spec/plans/milestones-roadmap.md` for the M1–M7 milestone roadmap (replaces the archived v1/v2 staged plan).
-See `docs/spec/plans/execution-plan.md` for the orchestration runbook (ralph, team, ultraqa).
+See `docs/plan/milestones-roadmap.md` for the M1–M7 milestone roadmap (replaces the archived v1/v2 staged plan).
+See `docs/plan/execution-plan.md` for the orchestration runbook (ralph, team, ultraqa).
 Do not read folder `docs/archived`
 
 ## Docs layout (lean)
@@ -18,7 +18,7 @@ Do not read folder `docs/archived`
 **User-facing instructions** — every behavior/caveat a user would notice (e.g. `agentkeys wire` taking over the runtime's `hooks:` block) goes in [`docs/user-manual.md`](docs/user-manual.md), the single home for user-aware instructions.
 
 ## Architecture-as-source-of-truth policy
-[`docs/arch.md`](docs/arch.md) is the **single source of truth** for component inventory, key inventory (K1–K11), trust boundaries, identity model (HDKD actor tree), and per-actor binding ceremonies. **After editing any architectural doc** (broker plans, signer-protocol, demo doc, runbooks, plan files in `docs/spec/plans/`, heima-gaps), re-open `arch.md` and verify it still matches; if it diverges, update arch.md in the same change. If the per-doc detail outgrows arch.md, link from arch.md outward — never duplicate. The wiki page at [`docs/wiki/agent-role-and-usage-hdkd-per-agent-omni.md`](docs/wiki/agent-role-and-usage-hdkd-per-agent-omni.md) is a focused operator reference for the agent role; it defers to arch.md.
+[`docs/arch.md`](docs/arch.md) is the **single source of truth** for component inventory, key inventory (K1–K11), trust boundaries, identity model (HDKD actor tree), and per-actor binding ceremonies. **After editing any architectural doc** (broker plans, signer-protocol, demo doc, runbooks, plan files in `docs/plan/`, heima-gaps), re-open `arch.md` and verify it still matches; if it diverges, update arch.md in the same change. If the per-doc detail outgrows arch.md, link from arch.md outward — never duplicate. The wiki page at [`docs/wiki/agent-role-and-usage-hdkd-per-agent-omni.md`](docs/wiki/agent-role-and-usage-hdkd-per-agent-omni.md) is a focused operator reference for the agent role; it defers to arch.md.
 
 ## `/create-pr` policy
 When the `/create-pr` skill is invoked from a Claude Code worktree at `.claude/worktrees/<name>`, the worktree is a *git worktree* under the main repo — `jj` cannot colocate there (`jj git init --colocate` fails with "Cannot create a colocated jj repo inside a Git worktree"). Use this hybrid workflow so the jj-only rule is preserved everywhere it can be:
@@ -76,7 +76,7 @@ If a hardcoded value is genuinely temporary — e.g. you're sketching a fix and
 Hardcoded values that go unrecorded compound: each new operator adds defaults baked into a different layer, the runbook drifts from reality, and the project becomes un-deployable to anyone but the original author. The audit log is the cure — it forces an explicit decision instead of an accumulating series of "I'll fix it later"s.
 
 ## Plan-completion policy
-When the user references a plan (e.g. `docs/spec/plans/issue-XX-*.md`), **complete every numbered step in the plan's implementation-order table — not a self-selected subset**. If you cannot complete a step (interactive flow needs human, scope explosion, prerequisites missing), say so up front before starting work and get explicit approval to defer. Never silently drop steps and ship a partial plan as "done."
+When the user references a plan (e.g. `docs/plan/issue-XX-*.md`), **complete every numbered step in the plan's implementation-order table — not a self-selected subset**. If you cannot complete a step (interactive flow needs human, scope explosion, prerequisites missing), say so up front before starting work and get explicit approval to defer. Never silently drop steps and ship a partial plan as "done."
 
 The end-of-PR summary is mandatory and has two sections in this exact order:
 
@@ -211,7 +211,7 @@ The agent-side wire demo (`agentkeys wire hermes` inside the aiosandbox) MUST ex
 
 On every session start:
 1. `jj log --limit 10 && cat harness/progress.json && bash harness/init.sh $(jq -r .current_stage harness/progress.json)`
-2. Read the milestone scope for the current milestone in `docs/spec/plans/milestones-roadmap.md` (the v1/v2 stage framing is archived at `docs/archived/development-stages-v2-2026-04.md`)
+2. Read the milestone scope for the current milestone in `docs/plan/milestones-roadmap.md` (the v1/v2 stage framing is archived at `docs/archived/development-stages-v2-2026-04.md`)
 3. Pick the HIGHEST-PRIORITY incomplete deliverable from `harness/features.json`
 4. Implement ONE deliverable
 5. Run tests: `cargo test -p <crate>` for the affected crate
@@ -257,7 +257,7 @@ Determine the real opcode level any time by *executing* a probe on a dev chain (
 
 ## Deployed contract registry
 
-Live contract addresses on each chain (Heima mainnet v2 set, the ERC-4337 master infra #164, historical v1) are kept in [`docs/contracts.md`](docs/contracts.md) — the single canonical registry, indexed from `arch.md` §5. (The old `docs/spec/deployed-contracts.md` is now a redirect to it.) The same addresses are also written to `scripts/operator-workstation.env` (via `env_set` in `scripts/heima-bring-up.sh` step 6) for shell-script consumption — those env-file entries are the operational source of truth and `docs/contracts.md` is the human-readable canonical record (deployer, deploy date, block, explorer links, ABI summary).
+Live contract addresses on each chain (Heima mainnet v2 set, the ERC-4337 master infra #164, historical v1) plus the prod/test EVM deployer wallets are kept in [`docs/spec/deployed-contracts.md`](docs/spec/deployed-contracts.md) — the single canonical registry, indexed from `arch.md` §5. (`docs/contracts.md` is now a redirect to it.) The same addresses are also written to `scripts/operator-workstation.env` (via `env_set` in `scripts/heima-bring-up.sh` step 6) for shell-script consumption — those env-file entries are the operational source of truth and `docs/spec/deployed-contracts.md` is the human-readable canonical record (deployer, deploy date, block, explorer links, ABI summary).
 
 Verify all contracts are live + functional any time:
 

diff --git a/README.md b/README.md
@@ -77,7 +77,7 @@ Dual-licensed under **MIT OR Apache-2.0**, at your choice.
 | [`CLAUDE.md`](CLAUDE.md) | Project-specific rules: docs layout, /create-pr workflow in worktrees, terminology-source-of-truth, branch push policy, idempotent-remote-setup invariants, runbook-fix-fold-back policy. **Read first, every session.** |
 | [`docs/arch.md`](docs/arch.md) | Single source of truth for component inventory (K1–K11), trust boundaries, HDKD actor tree, per-actor binding ceremonies. When the per-doc detail outgrows arch.md, link outward — never duplicate. |
 | [`docs/spec/plans/development-stages.md`](docs/spec/plans/development-stages.md) | The 8-stage build plan. Each stage has a `harness/stage-N-done.sh` gate; never self-grade — run the gate. |
-| [`docs/spec/plans/execution-plan.md`](docs/spec/plans/execution-plan.md) | Orchestration runbook (ralph, team, ultraqa workflows). |
+| [`docs/plan/execution-plan.md`](docs/plan/execution-plan.md) | Orchestration runbook (ralph, team, ultraqa workflows). |
 | [`docs/spec/broker-and-operator-dev-guide.md`](docs/spec/broker-and-operator-dev-guide.md) | Inner edit-build-test loop for broker + operator-side code. Use this before suggesting changes to the broker's run-time behavior. |
 
 ### Hard rules (from CLAUDE.md)

diff --git a/TODOS.md b/TODOS.md
@@ -54,13 +54,13 @@ production-aligned path.
 
 ### Deprecate `agentkeys-mock-server` `/credential/*` — replace with S3 + OIDC + client-side AES-GCM
 
-Draft issue body lives at [`docs/spec/plans/issue-credential-storage-s3-oidc.md`](docs/spec/plans/issue-credential-storage-s3-oidc.md). File on the GitHub repo with:
+Draft issue body lives at [`docs/plan/issue-credential-storage-s3-oidc.md`](docs/plan/issue-credential-storage-s3-oidc.md). File on the GitHub repo with:
 
 ```bash
 gh issue create --repo litentry/agentKeys \
   --title "Replace mock-server /credential/* with S3-backed encrypted storage (OIDC-scoped, PrincipalTag-isolated)" \
   --label "stage-7+,architecture,credential-storage" \
-  --body-file docs/spec/plans/issue-credential-storage-s3-oidc.md
+  --body-file docs/plan/issue-credential-storage-s3-oidc.md
 ```
 
 Architecture rationale, wire contract sketch, IAM-delta scope, and 6-step migration plan all in the draft. Reuses the SES Lambda's PrincipalTag-isolated bucket + the §5.1 OIDC workflow — zero new deployable artifacts. Forced by the post-issue-#83 storage failure: provision now succeeds through key mint but the legacy backend at `:8090` (loopback-only per [arch.md §11](docs/arch.md#L670)) is unreachable from the operator workstation.

diff --git a/crates/agentkeys-broker-server/Cargo.toml b/crates/agentkeys-broker-server/Cargo.toml
@@ -37,7 +37,7 @@ aws-sdk-sts = "1"
 # Real SES sender for email-link auth. Optional, gated behind
 # auth-email-link — without the feature the broker has no SES sender at
 # all (StubEmailSender remains for tests). Pulled in by Pass 1 of
-# Option B per docs/spec/plans/issue-74 (see commit log).
+# Option B per docs/archived/issue-74-dev-key-service-plan.md (see commit log).
 aws-sdk-sesv2 = { version = "1", optional = true }
 jsonwebtoken = "9"
 p256 = { version = "0.13", features = ["pkcs8", "pem", "ecdsa"] }

diff --git a/crates/agentkeys-broker-server/src/handlers/agent/mod.rs b/crates/agentkeys-broker-server/src/handlers/agent/mod.rs
@@ -1,6 +1,6 @@
 //! §10.2 agent-bootstrap endpoints — **method A, agent-initiated** (issue #144,
 //! flipped from master-initiated; design doc
-//! `docs/spec/plans/agent-initiated-pairing-method-a.md`).
+//! `docs/archived/agent-initiated-pairing-method-a.md`).
 //!
 //! The agent shows a code, the master claims it (the Matter/HomeKit IoT model),
 //! and the master still submits the on-chain binding (decision 1 — no contract

diff --git a/crates/agentkeys-cli/src/hook.rs b/crates/agentkeys-cli/src/hook.rs
@@ -10,7 +10,7 @@
 //!
 //! Wire protocol (Hermes / Claude-Code compatible — see
 //! `docs/wiki/agent-iam-guarantee-glossary.md` §3 + the plan
-//! `docs/spec/plans/phase-1-fresh-user-wire-onboarding.md` §5.2):
+//! `docs/plan/phase-1-fresh-user-wire-onboarding.md` §5.2):
 //!
 //! ```text
 //! stdin:  {hook_event_name, tool_name, tool_input, session_id, cwd, extra}

diff --git a/crates/agentkeys-cli/src/lib.rs b/crates/agentkeys-cli/src/lib.rs
@@ -118,7 +118,7 @@ impl CredentialBackendKind {
 /// Which envelope format the S3 backend writes. Defaults to `V1` to keep
 /// existing #87 deployments working unchanged; operators opt in to `V2`
 /// once they've finished the dual-tag + bucket-policy migration steps in
-/// `docs/spec/plans/v2-issues/issue-v2-stage-1-foundation.md`.
+/// `docs/plan/v2-issues/issue-v2-stage-1-foundation.md`.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum EnvelopeVersionFlag {
     V1,

diff --git a/crates/agentkeys-cli/src/wire.rs b/crates/agentkeys-cli/src/wire.rs
@@ -8,7 +8,7 @@
 //!
 //! Phase 1.a ships the Hermes adapter. The `RuntimeAdapter` trait is the
 //! seam additional runtimes (Claude Code, Codex, OpenClaw) slot into in
-//! Phase 1.b — see docs/spec/plans/phase-1-fresh-user-wire-onboarding.md §4.
+//! Phase 1.b — see docs/plan/phase-1-fresh-user-wire-onboarding.md §4.
 
 use std::path::PathBuf;
 use std::process::Command;

diff --git a/crates/agentkeys-core/src/s3_backend.rs b/crates/agentkeys-core/src/s3_backend.rs
@@ -180,7 +180,7 @@ impl S3CredentialBackend {
     /// `actor_omni_hex`. Stage 1 ships v1 as default so existing #87
     /// deployments keep working unchanged; per-operator opt-in flips this
     /// to v2 once the bucket policy + OIDC dual-tag rollout completes
-    /// (see `docs/spec/plans/v2-issues/issue-v2-stage-1-foundation.md`
+    /// (see `docs/plan/v2-issues/issue-v2-stage-1-foundation.md`
     /// migration step 9).
     pub fn with_write_envelope(mut self, envelope: WriteEnvelope) -> Self {
         self.write_envelope = envelope;

diff --git a/crates/agentkeys-mcp-server/README.md b/crates/agentkeys-mcp-server/README.md
@@ -35,7 +35,7 @@ Auto-seeds vendor `magiclick:demo-tok` + three memory namespaces (`travel`,
 `family`, `profile`) on actor `O_kevin_001`. Walk the three-act
 storyboard with `bash scripts/mcp-demo-mode-a.sh` (asserts each act's
 exact wire shape). Full step-by-step walkthrough:
-[`docs/spec/plans/issue-107-mcp-demo-runbook.md`](../../docs/spec/plans/issue-107-mcp-demo-runbook.md).
+[`docs/plan/issue-107-mcp-demo-runbook.md`](../../docs/plan/issue-107-mcp-demo-runbook.md).
 
 ### Local (HTTP, against a real broker / workers)
 
@@ -72,7 +72,7 @@ cargo run -p agentkeys-mcp-server -- \
 Test it locally without a real cloud account: `bash scripts/mcp-demo-mode-d-xiaozhi-endpoint.sh`
 spins up a mock relay that mirrors `xinnan-tech/mcp-endpoint-server`'s
 routing exactly, then drives every act through it. Full runbook in
-[`docs/spec/plans/issue-107-mcp-demo-runbook.md`](../../docs/spec/plans/issue-107-mcp-demo-runbook.md) §B.
+[`docs/plan/issue-107-mcp-demo-runbook.md`](../../docs/plan/issue-107-mcp-demo-runbook.md) §B.
 
 ### Docker
 
@@ -198,5 +198,5 @@ Coverage:
 - Vendor onboarding portal — M2 (#114)
 - Volcano Ark marketplace registration — M2
 
-See [`docs/spec/plans/issue-107-mcp-server-phase1.md`](../../docs/spec/plans/issue-107-mcp-server-phase1.md)
+See [`docs/archived/issue-107-mcp-server-phase1.md`](../../docs/archived/issue-107-mcp-server-phase1.md)
 for the full plan + follow-ups.
diff --git a/crates/agentkeys-mcp-server/src/tools/stubs.rs b/crates/agentkeys-mcp-server/src/tools/stubs.rs
@@ -10,7 +10,7 @@
 use crate::errors::McpError;
 
 pub const SPEC_URL: &str =
-    "https://github.com/litentry/agentKeys/blob/main/docs/spec/plans/milestones-roadmap.md#m4";
+    "https://github.com/litentry/agentKeys/blob/main/docs/plan/milestones-roadmap.md#m4";
 
 pub fn not_implemented_v1() -> McpError {
     McpError::NotImplementedV1 {

diff --git a/docs/agent-iam-strategy.md b/docs/agent-iam-strategy.md
@@ -7,7 +7,7 @@
 **Companion docs**:
 - [`ai-hardware-companion-office-hours.md`](./research/ai-hardware-companion-office-hours.md) — original wedge brainstorm (positioning is updated by this doc)
 - [`xiaozhi-hermes-architecture.md`](./research/xiaozhi-hermes-architecture.md), [`volcano-ark-mcp-integration.md`](./research/volcano-ark-mcp-integration.md), [`tuya-vs-xiaozhi.md`](./research/tuya-vs-xiaozhi.md) — tactical adapter architectures (unchanged by this doc)
-- [issue #103 plan](./spec/plans/issue-103-aiosandbox-hermes-esp32-demo.md) — Phase 1 execution (scope is updated by this doc)
+- [issue #103 plan](./plan/issue-103-aiosandbox-hermes-esp32-demo.md) — Phase 1 execution (scope is updated by this doc)
 
 ---
 
@@ -240,7 +240,7 @@ A corollary of §3.6: if hooks are the IAM-guarantee delivery mechanism, *who wr
 - **Manual** — user runs both `agentkeys …` and the runtime's own setup wizard, then hand-edits `~/.<runtime>/config.<ext>` to register AgentKeys hooks. Two-wizard friction. Demo "surprise" effect diluted because the user already configured the runtime.
 - **Automatic** — AgentKeys CLI writes the hook scripts + the `hooks:` block + the runtime's LLM-provider config in one idempotent command. One wizard. Strong demo surprise. Higher maintenance burden (track each runtime's config schema; nightly drift check needed).
 
-**Decision (2026-05-28): hybrid.** Detailed in [`docs/spec/plans/phase-1-fresh-user-wire-onboarding.md`](./spec/plans/phase-1-fresh-user-wire-onboarding.md):
+**Decision (2026-05-28): hybrid.** Detailed in [`docs/plan/phase-1-fresh-user-wire-onboarding.md`](./plan/phase-1-fresh-user-wire-onboarding.md):
 
 | AgentKeys owns | Runtime owns |
 |---|---|
@@ -330,7 +330,7 @@ The demo runs on MagicLick 2.5 (xiaozhi-esp32 v1.9.4, unchanged) + stock xinnan-
 | Deliverable | What it is | Why it matters |
 |---|---|---|
 | AgentKeys MCP server | 7 active tools wrapping existing backend RPCs | The integration surface vendors plug into |
-| **`agentkeys wire <runtime>` CLI** (per §3.7) | Hybrid auto-provisioning — writes IAM-gate config + LLM-provider config into a Task Host's config files; idempotent; tracked in [`docs/spec/plans/phase-1-fresh-user-wire-onboarding.md`](./spec/plans/phase-1-fresh-user-wire-onboarding.md) | The user-facing entry point that turns "AgentKeys is wired into the runtime" into one command. The fresh-user "surprise" moment depends on this. |
+| **`agentkeys wire <runtime>` CLI** (per §3.7) | Hybrid auto-provisioning — writes IAM-gate config + LLM-provider config into a Task Host's config files; idempotent; tracked in [`docs/plan/phase-1-fresh-user-wire-onboarding.md`](./plan/phase-1-fresh-user-wire-onboarding.md) | The user-facing entry point that turns "AgentKeys is wired into the runtime" into one command. The fresh-user "surprise" moment depends on this. |
 | Hermes adapter (Phase 1.a) | First runtime adapter for `wire`; lives in `crates/agentkeys-cli/src/wire/adapters/hermes.rs` | Validates the hybrid auto-provisioning shape against a real Task Host inside aiosandbox |
 | `agentkeys hook check / audit / memory-inject` CLI helpers | The thin wrappers the dropped hook scripts call — translate host stdin/stdout JSON to AgentKeys MCP tool calls | Makes the hook scripts trivial (single `exec` line); bug fixes ship in the AgentKeys binary, not in the user's filesystem |
 | Parent-control web UI (mobile-responsive) | One page: actor list, scope toggles, revoke buttons, audit feed | The face of "Agent IAM" — without this, Act 3 isn't a demo |
@@ -495,7 +495,7 @@ Privacy is a benefit, not a category. "Privacy product" is crowded (Brave, DuckD
 |---|---|
 | [`ai-hardware-companion-office-hours.md`](./research/ai-hardware-companion-office-hours.md) | Update positioning note at top to point at this strategy doc + add Agent IAM framing + three-narrative reality. Substance below the banner stays. |
 | [`ai-hardware-companion-wedge.md`](./research/ai-hardware-companion-wedge.md) | Update positioning sections — sharper "Agent IAM" framing; keep market sizing + competitive analysis as-is. |
-| [issue #103 plan](./spec/plans/issue-103-aiosandbox-hermes-esp32-demo.md) | Pivot demo storyboard to the three-act IAM demo per §4.3. Add parent-control web UI deliverable. Note the four corrections (bounded revocation, two-tier audit, delegation-as-preview, zero orchestration). Implementation detail unchanged (cap-token machinery already exists). |
+| [issue #103 plan](./plan/issue-103-aiosandbox-hermes-esp32-demo.md) | Pivot demo storyboard to the three-act IAM demo per §4.3. Add parent-control web UI deliverable. Note the four corrections (bounded revocation, two-tier audit, delegation-as-preview, zero orchestration). Implementation detail unchanged (cap-token machinery already exists). |
 | [`xiaozhi-hermes-architecture.md`](./research/xiaozhi-hermes-architecture.md) | No change — MCP-direct pivot still correct. |
 | [`volcano-ark-mcp-integration.md`](./research/volcano-ark-mcp-integration.md) | Minor: clarify Phase 2 timing per §5 above; tool inventory unchanged. |
 | [`tuya-vs-xiaozhi.md`](./research/tuya-vs-xiaozhi.md) | No change — complement-not-compete framing still correct. |