@agentskit/doc-bridge 1.4.1 → 1.5.0

package/ecosystem.json

@@ -1,13 +1,22 @@
 {
   "schemaVersion": 2,
-  "$comment": "Canonical registry of AgentsKit ecosystem products. Stable identity lives in products[] (seven). Numeric values live in the generated ecosystem-claims ledger. The properties array is the full seven-product v1 projection of products[] (same order) for sibling consumers.",
+  "$comment": "Canonical registry of AgentsKit ecosystem products. Stable identity lives in products[] (seven). Numeric values live in the generated ecosystem-claims ledger. The deprecated properties array remains a v1 four-product shim for Doc Bridge / sibling consumers until those schemas accept the full seven-product set \u2014 do not treat properties as the product catalog.",
   "parentBrand": {
     "id": "agentskit",
     "name": "AgentsKit"
   },
+  "positioning": {
+    "canonicalDescription": "AgentsKit is the open-source TypeScript ecosystem for building production AI agents without locking application architecture to a model provider, framework, database, or hosted platform.",
+    "metaDescription": "Open-source TypeScript ecosystem for production AI agents. Swap models, providers, tools, memory, RAG, and interfaces without architectural lock-in.",
+    "commercialBoundary": "AgentsKit, Chat, Registry, Playbook, Doc Bridge, and Code Review are free and open source. AKOS is the optional paid managed control plane for teams that need enterprise operations, governance, and infrastructure.",
+    "openSourceProductIds": ["agentskit", "registry", "agentskit-chat", "playbook", "doc-bridge", "code-review"],
+    "managedProductIds": ["akos"]
+  },
   "products": [
     {
       "id": "agentskit",
+      "public": true,
+      "distributionClass": "open-source",
       "name": "AgentsKit",
       "shortName": "AgentsKit",
       "kind": "library",
@@ -16,6 +25,34 @@
       "maturity": "beta",
       "repo": "AgentsKit-io/agentskit",
       "accent": "#2EA043",
+      "metadata": {
+        "alternateName": "AgentsKit.js",
+        "description": "A free, MIT-licensed TypeScript ecosystem for production AI agents with replaceable contracts for models, runtimes, tools, memory, RAG, observability, sandboxing, evaluation, and interfaces.",
+        "dateCreated": "2026-04-02",
+        "applicationCategory": "DeveloperApplication",
+        "runtimePlatform": "JavaScript runtimes supporting ES2022",
+        "license": "MIT",
+        "author": {
+          "givenName": "Emerson",
+          "familyName": "Braun",
+          "url": "https://github.com/EmersonBraun"
+        },
+        "keywords": [
+          "AI agents",
+          "agent framework",
+          "TypeScript",
+          "JavaScript",
+          "LLM",
+          "multi-agent",
+          "tools",
+          "memory",
+          "RAG",
+          "observability",
+          "sandboxing",
+          "evaluation",
+          "MCP"
+        ]
+      },
       "showcase": {
         "claimSource": {
           "url": "https://www.agentskit.io/api/stats.json",
@@ -30,20 +67,19 @@
         "stage": "Build",
         "headline": "One foundation. Every layer stays yours.",
         "detail": "Compose runtime, adapters, tools, memory, RAG, and UI without glue code or lock-in.",
-        "proof": "{{packages}} packages · <{{core-size-kb-gzip}} KB core",
+        "proof": "22 packages · 10 KB core budget",
         "sales": {
           "kind": "integration-stack",
           "headline": "Swap the stack. Keep the agent.",
           "metrics": [
-            { "value": "{{catalog-providers}}", "label": "providers" },
-            { "value": "{{native-adapters}}", "label": "adapters" },
-            { "value": "{{integrations}}", "label": "integrations" }
+            { "value": "140+", "label": "providers" },
+            { "value": "25", "label": "adapters" },
+            { "value": "50", "label": "integrations" }
           ],
           "capabilities": ["Tools", "RAG", "Memory", "MCP"],
           "steps": ["Choose any adapter", "Add tools and memory", "Ship without rewrites"]
         },
-        "cta": "Build with AgentsKit",
-        "ctaSurface": "docs"
+        "cta": "Build with AgentsKit"
       },
       "surfaces": {
         "home": "https://www.agentskit.io",
@@ -68,6 +104,8 @@
     },
     {
       "id": "registry",
+      "public": true,
+      "distributionClass": "open-source",
       "name": "AgentsKit Registry",
       "shortName": "Registry",
       "kind": "registry",
@@ -90,15 +128,14 @@
         "proof": "Ready-made · source-owned",
         "sales": {
           "kind": "registry-install",
-          "headline": "Ready-to-use agents from the live Registry.",
-          "metric": "{{agents}}",
-          "metricLabel": "shadcn-like agents",
-          "capabilities": ["Research", "Support", "Coding", "Data", "Marketing", "{{remaining-categories}} additional categories"],
+          "headline": "Source-owned agents for your project.",
+          "metric": "Source-owned",
+          "metricLabel": "agent code",
+          "capabilities": ["Ready-made agents", "Source ownership", "CLI installation"],
           "steps": ["Find the right agent", "Run npx agentskit add", "Own every line"],
           "command": "npx agentskit add research"
         },
-        "cta": "Explore the Registry",
-        "ctaSurface": "home"
+        "cta": "Explore the Registry"
       },
       "surfaces": {
         "home": "https://registry.agentskit.io",
@@ -123,6 +160,8 @@
     },
     {
       "id": "agentskit-chat",
+      "public": true,
+      "distributionClass": "open-source",
       "name": "AgentsKit Chat",
       "shortName": "Chat",
       "kind": "framework",
@@ -134,24 +173,22 @@
       "showcase": {
         "stage": "Deliver",
         "headline": "One agent. Every conversation surface.",
-        "detail": "Define the experience once and deliver it across web, desktop, CLI, and mobile.",
-        "proof": "Web · Desktop · CLI · Mobile",
+        "detail": "Define the experience once and connect the conversation surface that fits the product.",
+        "proof": "Human ↔ agent · shared experience",
         "sales": {
           "kind": "human-agent",
           "headline": "Human ↔ agent. Without losing control.",
-          "metric": "4",
-          "metricLabel": "surfaces · one conversation",
+          "metric": "One",
+          "metricLabel": "agent experience",
           "logos": [
-            { "id": "web", "label": "Web" },
-            { "id": "desktop", "label": "Desktop" },
-            { "id": "cli", "label": "CLI" },
-            { "id": "mobile", "label": "Mobile" }
+            { "id": "human", "label": "Human" },
+            { "id": "agent", "label": "Agent" },
+            { "id": "tools", "label": "Tools" }
           ],
-          "capabilities": ["Streaming", "Approvals", "Tool results", "Shared state"],
-          "steps": ["Agent requests a protected action", "Human approves", "The conversation continues everywhere"]
+          "capabilities": ["Conversation", "Human control", "Tool results"],
+          "steps": ["Define the agent experience", "Connect the conversation surface", "Keep the human in control"]
         },
-        "cta": "Explore AgentsKit Chat",
-        "ctaSurface": "home"
+        "cta": "Explore AgentsKit Chat"
       },
       "surfaces": {
         "home": "https://chat.agentskit.io",
@@ -175,19 +212,21 @@
     },
     {
       "id": "playbook",
+      "public": true,
+      "distributionClass": "open-source",
       "name": "Agents Playbook",
       "shortName": "Playbook",
       "kind": "methodology",
       "role": "discipline",
-      "promise": "Train coding agents to ship code your team would merge.",
+      "promise": "Make agents ship code a human would actually merge.",
       "maturity": "stable",
       "repo": "AgentsKit-io/agents-playbook",
       "accent": "#8B5CF6",
       "showcase": {
         "stage": "Standardize",
-        "headline": "The open engineering harness for coding agents.",
-        "detail": "Open rules, prompts, memory, evals, and executable gates turn every correction into behavior coding agents can repeat.",
-        "proof": "Train the behavior · not the model",
+        "headline": "Engineering standards agents can execute.",
+        "detail": "Turn repeatable practices into guidance that coding agents can follow in every repository.",
+        "proof": "Convention → executable guidance",
         "sales": {
           "kind": "standards-flow",
           "headline": "Your standards. Every agent. Every repository.",
@@ -202,8 +241,7 @@
           "capabilities": ["Repository rules", "Review criteria", "Agent guidance", "Team conventions"],
           "steps": ["Define the standard once", "Agents receive executable guidance", "Review consistent output"]
         },
-        "cta": "Explore the harness",
-        "ctaSurface": "home"
+        "cta": "Explore the Playbook"
       },
       "surfaces": {
         "home": "https://playbook.agentskit.io",
@@ -228,6 +266,8 @@
     },
     {
       "id": "doc-bridge",
+      "public": true,
+      "distributionClass": "open-source",
       "name": "Doc Bridge",
       "shortName": "Doc Bridge",
       "kind": "developer-tool",
@@ -255,8 +295,7 @@
           "capabilities": ["ADRs", "Handoffs", "Agent findings", "Human-readable docs"],
           "steps": ["Humans document decisions", "Agents receive precise context", "Agent findings return to humans"]
         },
-        "cta": "Generate your first handoff",
-        "ctaSurface": "home"
+        "cta": "Explore Doc Bridge"
       },
       "surfaces": {
         "home": "https://doc-bridge.agentskit.io/",
@@ -280,6 +319,8 @@
     },
     {
       "id": "code-review",
+      "public": true,
+      "distributionClass": "open-source",
       "name": "AgentsKit Code Review",
       "shortName": "Code Review",
       "kind": "developer-tool",
@@ -310,35 +351,38 @@
     },
     {
       "id": "akos",
-      "name": "AgentsKit OS",
+      "public": false,
+      "distributionClass": "managed-service",
+      "accessModel": "paid-managed-service",
+      "aliases": ["AgentsKit OS"],
+      "name": "AKOS",
       "shortName": "AKOS",
-      "kind": "product",
+      "kind": "managed-service",
       "role": "operation",
-      "promise": "Run and govern agents in production.",
+      "promise": "Add optional managed operations when production governance calls for it.",
       "maturity": "stable",
-      "repo": "AgentsKit-io/agentskit-os",
+      "repo": null,
+      "distributionPolicy": "Public commercial references only; never use private implementation as contribution evidence.",
       "accent": "#34D399",
       "showcase": {
         "stage": "Operate",
-        "headline": "Run and govern agents in production.",
-        "detail": "Add orchestration, governance, and operational control when your system needs it.",
-        "proof": "Orchestration · governance · control",
+        "headline": "Optional managed operations for agents.",
+        "detail": "A managed layer for teams that need additional operational controls. AgentsKit can be used without it.",
+        "proof": "Optional · managed operations",
         "sales": {
           "kind": "enterprise-control",
-          "headline": "The enterprise control plane for agents.",
-          "metric": "Enterprise",
-          "metricLabel": "operations and governance",
+          "headline": "Managed operations for production agents.",
+          "metric": "Optional",
+          "metricLabel": "managed layer",
           "logos": [
-            { "id": "logs", "label": "Logs" },
-            { "id": "approvals", "label": "Approvals" },
-            { "id": "rbac", "label": "RBAC" },
-            { "id": "policies", "label": "Policies" }
+            { "id": "managed", "label": "Managed" },
+            { "id": "optional", "label": "Optional" },
+            { "id": "operations", "label": "Operations" }
           ],
-          "capabilities": ["Logs", "Approvals", "RBAC", "Policies", "Tracing", "Costs"],
-          "steps": ["Agent requests a protected action", "RBAC and policy gates evaluate", "Human approves; logs and trace persist"]
+          "capabilities": ["Managed operations", "Production support", "Optional adoption"],
+          "steps": ["Assess the operational need", "Evaluate the managed layer", "Adopt it only when it fits"]
         },
-        "cta": "Explore AgentsKit OS",
-        "ctaSurface": "home"
+        "cta": "Evaluate managed operations"
       },
       "surfaces": {
         "home": "https://akos.agentskit.io",
@@ -369,29 +413,16 @@
       "stats": "https://www.agentskit.io/api/stats.json"
     },
     {
-      "id": "registry",
-      "name": "AgentsKit Registry",
-      "barLabel": "Registry",
-      "domain": "registry.agentskit.io",
-      "url": "https://registry.agentskit.io",
-      "repo": "AgentsKit-io/agentskit-registry",
-      "tagline": "Copy ready-made agents and own the source.",
-      "kind": "registry",
-      "accent": "#58A6FF",
-      "llms": "https://registry.agentskit.io/llms.txt",
-      "stats": "https://registry.agentskit.io/r/index.json"
-    },
-    {
-      "id": "agentskit-chat",
-      "name": "AgentsKit Chat",
-      "barLabel": "Chat",
-      "domain": "chat.agentskit.io",
-      "url": "https://chat.agentskit.io",
-      "repo": "AgentsKit-io/agentskit-chat",
-      "tagline": "Define one agent experience and deliver it across interfaces.",
-      "kind": "framework",
-      "accent": "#F59E0B",
-      "llms": "https://chat.agentskit.io/llms.txt"
+      "id": "akos",
+      "name": "AKOS",
+      "barLabel": "AKOS",
+      "domain": "akos.agentskit.io",
+      "url": "https://akos.agentskit.io",
+      "repo": null,
+      "tagline": "Add optional managed operations when production governance calls for it.",
+      "kind": "managed-service",
+      "accent": "#34D399",
+      "llms": "https://akos.agentskit.io/llms.txt"
     },
     {
       "id": "playbook",
@@ -400,47 +431,24 @@
       "domain": "playbook.agentskit.io",
       "url": "https://playbook.agentskit.io",
       "repo": "AgentsKit-io/agents-playbook",
-      "tagline": "Train coding agents to ship code your team would merge.",
+      "tagline": "Make agents ship code a human would actually merge.",
       "kind": "methodology",
       "accent": "#8B5CF6",
       "llms": "https://playbook.agentskit.io/llms.txt",
       "stats": "https://playbook.agentskit.io/api/stats.json"
     },
     {
-      "id": "doc-bridge",
-      "name": "Doc Bridge",
-      "barLabel": "Doc Bridge",
-      "domain": "doc-bridge.agentskit.io",
-      "url": "https://doc-bridge.agentskit.io/",
-      "repo": "AgentsKit-io/doc-bridge",
-      "tagline": "Turn repository documentation into executable agent handoffs.",
-      "kind": "developer-tool",
-      "accent": "#06B6D4",
-      "llms": "https://doc-bridge.agentskit.io/llms.txt"
-    },
-    {
-      "id": "code-review",
-      "name": "AgentsKit Code Review",
-      "barLabel": "Code Review",
-      "domain": "github.com",
-      "url": "https://github.com/AgentsKit-io/code-review-cli",
-      "repo": "AgentsKit-io/code-review-cli",
-      "tagline": "Run deep, low-noise review with the model already in use.",
-      "kind": "developer-tool",
-      "accent": "#F97316",
-      "llms": "https://raw.githubusercontent.com/AgentsKit-io/code-review-cli/main/llms.txt"
-    },
-    {
-      "id": "akos",
-      "name": "AgentsKit OS",
-      "barLabel": "AKOS",
-      "domain": "akos.agentskit.io",
-      "url": "https://akos.agentskit.io",
-      "repo": "AgentsKit-io/agentskit-os",
-      "tagline": "Run and govern agents in production.",
-      "kind": "product",
-      "accent": "#34D399",
-      "llms": "https://akos.agentskit.io/llms.txt"
+      "id": "registry",
+      "name": "AgentsKit Registry",
+      "barLabel": "Registry",
+      "domain": "registry.agentskit.io",
+      "url": "https://registry.agentskit.io",
+      "repo": "AgentsKit-io/agentskit-registry",
+      "tagline": "Copy ready-made agents and own the source.",
+      "kind": "registry",
+      "accent": "#58A6FF",
+      "llms": "https://registry.agentskit.io/llms.txt",
+      "stats": "https://registry.agentskit.io/r/index.json"
     }
   ],
   "builder": {

package/mcpb/manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": "0.3",
   "name": "doc-bridge",
   "display_name": "Doc Bridge",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "Deterministic repository handoffs for coding agents, running locally without an LLM or API key.",
   "long_description": "Doc Bridge turns a repository's own documentation and ownership metadata into deterministic handoffs: where an agent should start, which paths it may edit, which checks it must run, and when a human must take over. The local connector exposes the same read-only contract available through Doc Bridge CLI and CI.",
   "author": {
@@ -63,6 +63,30 @@
     {
       "name": "registry.topology",
       "description": "Return the static Doc Bridge curator and delegate topology."
+    },
+    {
+      "name": "docbridge.snapshot",
+      "description": "Read the latest discovery snapshot from the resumable workflow."
+    },
+    {
+      "name": "docbridge.report",
+      "description": "Read the latest reconciliation report from the resumable workflow."
+    },
+    {
+      "name": "docbridge.diagnostics",
+      "description": "Read reconciliation diagnostics from the latest workflow report."
+    },
+    {
+      "name": "docbridge.relations",
+      "description": "Read bounded architecture relations from the latest workflow snapshot."
+    },
+    {
+      "name": "docbridge.run",
+      "description": "Read the latest resumable Doc Bridge workflow state."
+    },
+    {
+      "name": "docbridge.proposals",
+      "description": "Create, inspect, approve, and apply human-gated Doc Bridge proposals."
     }
   ],
   "tools_generated": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentskit/doc-bridge",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "mcpName": "io.github.AgentsKit-io/doc-bridge",
   "description": "Human↔agent documentation bridge — deterministic handoffs, doc-site links, memory→docs, optional AgentsKit RAG/chat.",
   "type": "module",
@@ -117,6 +117,7 @@
     "github-slugger": "^2.0.0",
     "mermaid": "^11.16.1",
     "minimatch": "^10.2.6",
+    "typescript": "^6.0.3",
     "zod": "^3.24.2"
   },
   "peerDependencies": {
@@ -171,7 +172,6 @@
     "react-dom": "19.2.0",
     "tailwindcss": "4.3.2",
     "tsup": "^8.5.0",
-    "typescript": "^6.0.3",
     "vitest": "^4.1.9"
   },
   "directories": {

package/skills/doc-bridge-handoff/scripts/resolve-handoff.mjs

@@ -3,7 +3,7 @@
 import { spawnSync } from 'node:child_process'
 import { isAbsolute } from 'node:path'
 
-const VERSION = '1.4.1'
+const VERSION = '1.5.0'
 const kinds = new Set(['package', 'ownership'])
 const args = process.argv.slice(2)
 const id = args[0]

package/src/agents/registry-adapter.ts

@@ -0,0 +1,97 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { z } from 'zod'
+
+import type { DocBridgeConfigV1 } from '../config/schema.js'
+import { AgentProposalV1Schema, type AgentProposalV1, type DiscoverySnapshotV1, type ReconciliationReportV1 } from '../schemas/knowledge.js'
+import { contentHashForArtifactV1 } from '../index-builder/content-hash.js'
+import { containedPath, redactValue } from '../safety/repository.js'
+
+export const DEFAULT_REGISTRY_AGENT_ID = 'ecosystem-doc-bridge-corpus-scanner'
+
+const RegistryAgentMetadataSchema = z.object({
+  id: z.string().min(1).max(256),
+  version: z.string().min(1).max(64),
+  provider: z.string().min(1).max(128).optional(),
+  model: z.string().min(1).max(256).optional(),
+  capabilities: z.array(z.string().min(1).max(128)).max(32).default([]),
+}).strict()
+
+export type RegistryAgentMetadata = z.infer<typeof RegistryAgentMetadataSchema> & { readonly root: string }
+
+export type RegistryAgentContext = {
+  readonly snapshot: DiscoverySnapshotV1
+  readonly report: ReconciliationReportV1
+  readonly evidence: readonly ReconciliationReportV1['diagnostics'][number]['evidence'][number][]
+  readonly capabilities: readonly ['snapshot.read', 'evidence.read', 'proposal.write']
+  readonly network: false
+  readonly shell: false
+}
+
+export type RegistryAgentRunner = (context: RegistryAgentContext) => Promise<unknown> | unknown
+
+export type RegistryAgentAdapter = {
+  readonly metadata: RegistryAgentMetadata
+  readonly run: (snapshot: DiscoverySnapshotV1, report: ReconciliationReportV1, evidence?: readonly RegistryAgentContext['evidence'][number][]) => Promise<AgentProposalV1>
+}
+
+const deepFreeze = <T>(value: T): T => {
+  if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+    Object.freeze(value)
+    for (const child of Object.values(value as Record<string, unknown>)) deepFreeze(child)
+  }
+  return value
+}
+
+const registryConfig = (config: DocBridgeConfigV1) => config.intelligence?.registry
+
+export const loadRegistryAgentRunner = async (root: string, config: DocBridgeConfigV1): Promise<RegistryAgentRunner> => {
+  const metadata = loadRegistryAgentMetadata(root, config)
+  const configured = registryConfig(config)?.runnerModule
+  const modulePath = configured ? containedPath(root, configured) : containedPath(root, join(metadata.root, 'doc-bridge-adapter.js'))
+  if (!modulePath || !existsSync(modulePath)) throw new Error(`Registry agent "${metadata.id}" has no local runner module. Configure intelligence.registry.runnerModule or add doc-bridge-adapter.js to the installed agent.`)
+  const loaded = await import(pathToFileURL(modulePath).href) as { default?: unknown; run?: unknown }
+  const runner = typeof loaded.run === 'function' ? loaded.run : typeof loaded.default === 'function' ? loaded.default : loaded.default && typeof loaded.default === 'object' && 'run' in loaded.default && typeof loaded.default.run === 'function' ? loaded.default.run : undefined
+  if (!runner) throw new Error(`Registry agent runner at ${modulePath} must export a function or { run }. `)
+  return runner as RegistryAgentRunner
+}
+
+export const loadRegistryAgentMetadata = (root: string, config: DocBridgeConfigV1): RegistryAgentMetadata => {
+  const settings = registryConfig(config)
+  const id = settings?.agentId ?? DEFAULT_REGISTRY_AGENT_ID
+  const agentRoot = settings?.agentRoot ?? 'agents'
+  const agentPath = containedPath(root, join(agentRoot, id))
+  if (!agentPath || !existsSync(agentPath)) throw new Error(`AgentsKit Registry agent "${id}" is not installed at ${join(agentRoot, id)}. Install it with: npx agentskit add ${id}`)
+  const metadataPath = [join(agentPath, 'agent.json'), join(agentPath, 'manifest.json')].find(existsSync)
+  if (!metadataPath) throw new Error(`Registry agent "${id}" is installed but has no agent.json or manifest.json metadata.`)
+  const metadata = RegistryAgentMetadataSchema.parse(JSON.parse(readFileSync(metadataPath, 'utf8')) as unknown)
+  if (metadata.id !== id) throw new Error(`Installed Registry agent metadata id "${metadata.id}" does not match configured id "${id}".`)
+  return { ...metadata, root: agentPath }
+}
+
+export const createRegistryAgentAdapter = (root: string, config: DocBridgeConfigV1, runner: RegistryAgentRunner): RegistryAgentAdapter => {
+  if (!registryConfig(config)?.enabled) throw new Error('Registry agents are disabled. Set intelligence.registry.enabled: true to run an assisted workflow.')
+  const metadata = loadRegistryAgentMetadata(resolve(root), config)
+  return {
+    metadata,
+    run: async (snapshot, report, evidence = report.diagnostics.flatMap((diagnostic) => diagnostic.evidence).slice(0, 64)) => {
+      const context = deepFreeze({ snapshot: redactValue(snapshot), report: redactValue(report), evidence: redactValue(evidence), capabilities: ['snapshot.read', 'evidence.read', 'proposal.write'] as const, network: false as const, shell: false as const }) as RegistryAgentContext
+      const proposal = AgentProposalV1Schema.parse(await runner(context))
+      if (proposal.contentHash !== contentHashForArtifactV1(proposal)) throw new Error('Registry agent proposal contentHash does not match its canonical contents.')
+      if (proposal.baseSnapshotHash !== snapshot.contentHash || proposal.baseReportHash !== report.contentHash) throw new Error('Registry agent proposal is not based on the supplied snapshot/report hashes.')
+      if (proposal.origin.kind !== 'registry-agent' || proposal.origin.id !== metadata.id) throw new Error(`Registry agent proposal origin must be ${metadata.id}.`)
+      return proposal
+    },
+  }
+}
+
+export const persistRegistryAgentProposal = (stateDir: string, proposal: AgentProposalV1): string => {
+  AgentProposalV1Schema.parse(proposal)
+  if (proposal.contentHash !== contentHashForArtifactV1(proposal)) throw new Error('Cannot persist a Registry agent proposal with an invalid contentHash.')
+  const safeHash = contentHashForArtifactV1(proposal)
+  mkdirSync(join(resolve(stateDir), 'agents'), { recursive: true })
+  const path = join(resolve(stateDir), 'agents', `${proposal.origin.id}-${safeHash}.json`)
+  writeFileSync(path, `${JSON.stringify(proposal, null, 2)}\n`, 'utf8')
+  return path
+}