M1: MCP server Phase 1 (#107, #108, #109, #111)

.github/REVIEW_GUIDELINES.md

@@ -1,8 +1,11 @@
 # Review Guidelines — agentkeys
 
 This is the single source of truth for code review patterns in this repo. The
-`claude-code-review.yml` workflow points Claude at this file; human reviewers
-should also use it as a checklist.
+[`claude-code-review.yml`](workflows/claude-code-review.yml) workflow points
+Claude at this file on PR *submission* events (`opened`, `ready_for_review`,
+`reopened`) — NOT on every push, to cap token cost. Human reviewers should
+use it as a checklist, and `@claude`-invoked reviews
+(see [`claude.yml`](workflows/claude.yml)) pick it up when relevant.
 
 Background: these patterns were distilled from 15+ PR review cycles in
 March-April 2026 where codex repeatedly surfaced the same classes of bug. Each
@@ -144,7 +147,7 @@ Reference: PR #18 P2, PR #22 v2 P2.
 
 ### 6. Session TTL is 30 days uniformly
 
-Master, agent, sandbox — all sessions are 30 days per `wiki/session-token.md`.
+Master, agent, sandbox — all sessions are 30 days per `docs/wiki/session-token.md`.
 Don't introduce per-type TTL splits; they were tried and reverted.
 
 Reference: PR #23.

.github/workflows/claude-code-review.yml

@@ -2,9 +2,16 @@ name: Claude Code Review
 
 on:
   pull_request:
-    types: [opened, synchronize, ready_for_review, reopened]
+    # Run only on PR submission events — NOT on every push (`synchronize`).
+    # `opened`        — first PR submission
+    # `ready_for_review` — draft promoted to ready (effectively a submission)
+    # `reopened`      — closed PR reopened
+    # Subsequent pushes to the PR branch are intentionally NOT reviewed, to
+    # cap Claude usage cost. Re-trigger manually by closing + reopening the
+    # PR, or by `@claude review` mention (handled in claude.yml).
+    types: [opened, ready_for_review, reopened]
     # Run only on paths that contain real code or CI config.
-    # Pure docs pushes (`docs/**`, `wiki/**`) don't need a full code review
+    # Pure docs pushes (`docs/**`, including `docs/wiki/**`) don't need a full code review
     # — they go through normal PR approval. This also skips Cargo.lock-only
     # churn and README-only edits.
     paths:
@@ -68,9 +75,9 @@ jobs:
             - READ `.github/REVIEW_GUIDELINES.md` for agentkeys-specific review
               patterns (audit-log contract, session-token redaction, URL encoding
               via reqwest `.query()`, `--test-threads=1` requirement, etc).
-            - Related specs: `docs/spec/architecture.md`,
+            - Related specs: `docs/arch.md`,
               `docs/spec/credential-backend-interface.md`,
-              `wiki/session-token.md` (30-day TTL policy).
+              `docs/wiki/session-token.md` (30-day TTL policy).
 
             TEST CONSTRAINTS:
             - Tests mutate shared process state (HOME, keyring accounts) so
@@ -85,7 +92,7 @@ jobs:
                interpolation into query strings.
             4. Token / session-token redaction in prompts and log lines.
             5. Case-insensitive wallet comparison (EIP-55 vs backend lowercase).
-            6. Session TTL uniformly 30 days per `wiki/session-token.md`.
+            6. Session TTL uniformly 30 days per `docs/wiki/session-token.md`.
             7. Synchronous keychain ops — no fire-and-forget delete.
             8. Path traversal guards on any user-supplied session_id / filename.
 

.github/workflows/pm-auto-archive-closed-pr.yml

@@ -0,0 +1,84 @@
+name: pm — auto-archive closed PRs in project
+
+# When a PR closes (merged or not), archive its project board item immediately.
+# Built-in "Auto-archive items" workflow only archives by age (30+ days closed),
+# which leaves the active views cluttered with freshly-closed PRs. This Action
+# archives on close so the board stays focused on in-flight + open work.
+#
+# Required repo secret: PM_PROJECT_TOKEN (same as the other pm-* workflows)
+
+on:
+  pull_request:
+    types: [closed]
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: 'PR number to archive (for manual re-runs)'
+        required: false
+
+permissions:
+  contents: read
+
+jobs:
+  archive:
+    runs-on: ubuntu-latest
+    env:
+      GH_TOKEN: ${{ secrets.PM_PROJECT_TOKEN }}
+      PROJECT_OWNER: litentry
+      PROJECT_NUMBER: '19'
+    steps:
+      - name: Install jq
+        run: sudo apt-get update && sudo apt-get install -y jq
+
+      - name: Determine PR number
+        id: pr
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            echo "number=${{ github.event.pull_request.number }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "number=${{ github.event.inputs.pr_number }}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Resolve project ID + PR item ID
+        id: resolve
+        run: |
+          project_id=$(gh project view "$PROJECT_NUMBER" --owner "$PROJECT_OWNER" --format json | jq -r '.id')
+          echo "project_id=$project_id" >> "$GITHUB_OUTPUT"
+
+          pr_num="${{ steps.pr.outputs.number }}"
+          item_id=$(gh api graphql -f query='
+            query($owner: String!, $number: Int!) {
+              organization(login: $owner) {
+                projectV2(number: $number) {
+                  items(first: 100, orderBy: {field: POSITION, direction: ASC}) {
+                    nodes {
+                      id
+                      content { ... on PullRequest { number } }
+                    }
+                  }
+                }
+              }
+            }
+          ' -F "owner=$PROJECT_OWNER" -F "number=$PROJECT_NUMBER" \
+            | jq -r --arg n "$pr_num" '.data.organization.projectV2.items.nodes[] | select(.content.number == ($n|tonumber)) | .id' \
+            | head -n1)
+
+          if [ -z "$item_id" ] || [ "$item_id" = "null" ]; then
+            echo "info PR #$pr_num is not on the project board — nothing to archive"
+            echo "found=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "item_id=$item_id" >> "$GITHUB_OUTPUT"
+            echo "found=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Archive the PR's project item
+        if: steps.resolve.outputs.found == 'true'
+        run: |
+          gh api graphql -f query='
+            mutation($project: ID!, $item: ID!) {
+              archiveProjectV2Item(input: { projectId: $project, itemId: $item }) {
+                item { id }
+              }
+            }
+          ' -F "project=${{ steps.resolve.outputs.project_id }}" -F "item=${{ steps.resolve.outputs.item_id }}" \
+            >/dev/null && echo "ok archived PR #${{ steps.pr.outputs.number }} from project board"

.github/workflows/publish-wiki.yml

@@ -1,17 +1,17 @@
 name: Publish wiki
 
-# One-way mirror: wiki/ in this repo is the canonical source for the GitHub Wiki.
-# Every push to main that touches wiki/ copies the folder over to
+# One-way mirror: docs/wiki/ in this repo is the canonical source for the GitHub Wiki.
+# Every push to main that touches docs/wiki/ copies the folder over to
 # litentry/agentKeys.wiki.git.
 #
 # Edits made directly through the GitHub Wiki web UI will be overwritten on the
-# next push to main that touches wiki/. See wiki/Home.md for the developer note.
+# next push to main that touches docs/wiki/. See docs/wiki/Home.md for the developer note.
 
 on:
   push:
     branches: [main]
     paths:
-      - 'wiki/**'
+      - 'docs/wiki/**'
   workflow_dispatch:
 
 jobs:
@@ -29,4 +29,4 @@ jobs:
       - name: Publish to wiki
         uses: Andrew-Chen-Wang/github-wiki-action@v4
         with:
-          path: wiki/
+          path: docs/wiki/

.gitignore

@@ -15,6 +15,20 @@ AWSCLIV2.pkg
 # Local developer secrets — template is checked in as .env.example.
 agentkeys-secrets.env
 
+# Operator-supplied mnemonic file(s) for the chain deployer (referenced
+# by HEIMA_DEPLOYER_MNEMONIC_FILE in scripts/heima-bring-up.sh).
+# Never committed — the mnemonic IS the key.
+/test-hei
+/test-hei.*
+/.heima-mnemonic
+/*-mnemonic
+
+# Node deps for scripts/heima-paseo-sudo.mjs (installed via
+# `npm install --prefix scripts` by scripts/heima-paseo-bring-up.sh on
+# first run). scripts/package.json + scripts/package-lock.json are
+# checked in; scripts/node_modules/ is not.
+scripts/node_modules/
+
 # Stage 6 runbook one-shot JSON artifacts. CLAUDE.md mandates the
 # `jq -n --arg` → `$(...)` pattern piped directly into the AWS CLI call
 # (no file on disk). If any of these reappear, someone reverted to the

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "crates/agentkeys-chain/lib/forge-std"]
+	path = crates/agentkeys-chain/lib/forge-std
+	url = https://github.com/foundry-rs/forge-std