@moda-ai/cli 1.44.1 → 1.45.0

package/README.md

@@ -274,24 +274,36 @@ rendered = moda.prompt("support.triage").render({
 })
 ```
 
-## Push prompts, skills, and tools without a repo scan
+## Register your harness for replays
 
 When the GitHub App or `moda harness analyze` isn't an option, have your coding
 agent write `.moda/registry.json` from the codebase and push it. Only what the
 manifest lists is uploaded. It needs just an API key.
 
 ```bash
-moda registry template --out=.moda/registry.json   # starter manifest (moda_registry.v1)
+moda registry prompt                                # brief to hand your coding agent
+moda registry template --out=.moda/registry.json   # starter manifest (moda_registry.v2)
 moda registry validate                              # local validation, no network
 moda registry push --dry-run                        # server-side preview
-moda registry push                                  # prompts, skills, and tools
+moda registry push                                  # prompts, skills, tools, then agent wiring
+moda registry status                                # registered harness and version
+moda registry coverage --days=7                     # recent traces vs the registry
 ```
 
 Prompts go to the prompt registry, skills to the skill library (pass `--live`
 or set `"live": true` to serve them), and tools to the tool registry as OpenAI
-function schemas. The format is in the bundled `moda-cli` skill. This fills
-the registries only: the harness graph (agents and how they connect) still
-comes from `moda harness analyze`, the GitHub App, or an approved report.
+function schemas. The v2 sections describe how the harness runs:
+
+- `agents`: each agent's prompt, model and params, tools, skills, handoffs,
+  and trace names.
+- `routing`: how the harness switches prompts.
+- `context`: what the runtime injects into prompts.
+- `runtime` and `mcpServers`.
+
+Replay rebuilds the agent that answered each replayed turn from these, and
+switches agents when the model hands off. The format is in the bundled
+`moda-cli` skill. The analyzer's citation graph (the dashboard Harness map)
+still comes from `moda harness analyze`, the GitHub App, or an approved report.
 
 ## Anchors and message windows
 

package/dist/cli.js

@@ -2062,9 +2062,539 @@ async function runSyncCommand(context) {
 }
 
 // src/registry.ts
+import { execFileSync } from "node:child_process";
 import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, realpathSync as realpathSync2, statSync, writeFileSync as writeFileSync2 } from "node:fs";
 import { dirname as dirname2, isAbsolute as isAbsolute2, relative, resolve as resolve2 } from "node:path";
-var REGISTRY_SCHEMA = "moda_registry.v1";
+
+// src/registry-harness.ts
+var HARNESS_SECTIONS = ["runtime", "agents", "routing", "context", "mcpServers"];
+var ROUTING_STRATEGIES = ["single", "trace_attribute", "handoff", "router", "rules"];
+var HISTORY_STRATEGIES = ["full", "window", "summary", "truncate_tokens"];
+var SKILL_LOADING_MODES = ["tool", "system_prompt", "none"];
+var CONTEXT_SOURCES = ["static", "clock", "trace", "tool", "memory", "retrieval", "unknown"];
+var CONTEXT_TARGETS = ["prompt_variable", "system_append"];
+var CLOCK_FORMATS = ["date", "datetime", "iso"];
+var MCP_TRANSPORTS = ["stdio", "http", "sse", "streamable_http"];
+var AGENT_KEY_PATTERN = /^[A-Za-z0-9_.-]{1,128}$/;
+var TOOL_NAME_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+var VARIABLE_PATTERN = /^[A-Za-z_][A-Za-z0-9_.]{0,127}$/;
+var MAX_AGENTS = 100;
+var MAX_CONTEXT = 200;
+var MAX_MCP_SERVERS = 50;
+var MAX_HARNESS_DOCUMENT_BYTES = 1e6;
+var AGENT_FIELDS = {
+  key: "string",
+  name: "string",
+  description: "string",
+  entry: "boolean",
+  prompt: "string",
+  model: "object",
+  tools: "string[]",
+  skills: "string[]",
+  handoffs: "object[]",
+  subagents: "object[]",
+  context: "string[]",
+  maxToolRoundsPerTurn: "number",
+  responseSchema: "object",
+  match: "object"
+};
+var MODEL_FIELDS = {
+  id: "string",
+  provider: "string",
+  temperature: "number",
+  maxTokens: "number",
+  topP: "number",
+  reasoningEffort: "string"
+};
+var HANDOFF_FIELDS = { to: "string", tool: "string", description: "string" };
+var SUBAGENT_FIELDS = { agent: "string", tool: "string", description: "string" };
+var MATCH_FIELDS = { agentNames: "string[]", promptKeys: "string[]" };
+var ROUTING_FIELDS = { strategy: "string", default: "string", notes: "string" };
+var RUNTIME_FIELDS = {
+  framework: "string",
+  language: "string",
+  maxToolRoundsPerTurn: "number",
+  parallelToolCalls: "boolean",
+  history: "object",
+  skillLoading: "string",
+  notes: "string"
+};
+var HISTORY_FIELDS = { strategy: "string", maxMessages: "number", maxTokens: "number" };
+var CONTEXT_FIELDS = {
+  key: "string",
+  variable: "string",
+  source: "string",
+  value: "string",
+  format: "string",
+  target: "string",
+  description: "string"
+};
+var MCP_FIELDS = {
+  name: "string",
+  transport: "string",
+  url: "string",
+  command: "string",
+  tools: "string[]",
+  description: "string"
+};
+function handoffToolName(handoff) {
+  return handoff.tool?.trim() || `transfer_to_${handoff.to.replace(/[^A-Za-z0-9_-]/g, "_")}`.slice(0, 64);
+}
+function hasHarnessSections(input) {
+  return HARNESS_SECTIONS.some((section) => input[section] !== undefined);
+}
+function validateHarnessSections(input, known, errors, warnings) {
+  if (!hasHarnessSections(input))
+    return;
+  const document = {};
+  if (input.runtime !== undefined) {
+    if (checkObject("runtime", input.runtime, RUNTIME_FIELDS, errors)) {
+      const runtime = input.runtime;
+      checkPositiveInt("runtime.maxToolRoundsPerTurn", runtime.maxToolRoundsPerTurn, errors);
+      checkEnum("runtime.skillLoading", runtime.skillLoading, SKILL_LOADING_MODES, errors);
+      if (runtime.history !== undefined && checkObject("runtime.history", runtime.history, HISTORY_FIELDS, errors)) {
+        checkEnum("runtime.history.strategy", runtime.history.strategy, HISTORY_STRATEGIES, errors);
+        checkPositiveInt("runtime.history.maxMessages", runtime.history.maxMessages, errors);
+        checkPositiveInt("runtime.history.maxTokens", runtime.history.maxTokens, errors);
+      }
+      document.runtime = runtime;
+    }
+  }
+  const contextKeys = new Set;
+  if (input.context !== undefined) {
+    const entries = listOf("context", input.context, MAX_CONTEXT, errors);
+    document.context = [];
+    entries.forEach((raw, index) => {
+      const label = `context[${index}]`;
+      if (!checkObject(label, raw, CONTEXT_FIELDS, errors))
+        return;
+      const entry = raw;
+      if (!nonEmpty(entry.key))
+        errors.push(`${label}.key is required`);
+      else if (contextKeys.has(entry.key))
+        errors.push(`${label}: duplicate context key "${entry.key}"`);
+      else
+        contextKeys.add(entry.key);
+      if (!nonEmpty(entry.source))
+        errors.push(`${label}.source is required (one of ${CONTEXT_SOURCES.join(", ")})`);
+      else
+        checkEnum(`${label}.source`, entry.source, CONTEXT_SOURCES, errors);
+      checkEnum(`${label}.target`, entry.target, CONTEXT_TARGETS, errors);
+      checkEnum(`${label}.format`, entry.format, CLOCK_FORMATS, errors);
+      const target = entry.target ?? "prompt_variable";
+      if (target === "prompt_variable") {
+        if (!nonEmpty(entry.variable))
+          errors.push(`${label}.variable is required for target "prompt_variable"`);
+        else if (!VARIABLE_PATTERN.test(entry.variable))
+          errors.push(`${label}.variable "${entry.variable}" is not a valid template variable name`);
+      }
+      if (entry.source === "static" && typeof entry.value !== "string")
+        errors.push(`${label}.value is required for source "static"`);
+      if (entry.source !== "static" && entry.value !== undefined) {
+        errors.push(`${label}.value is only allowed for source "static" (record runtime values in traces instead)`);
+      }
+      document.context.push(entry);
+    });
+  }
+  const agentKeys = new Set;
+  const agents = input.agents === undefined ? [] : listOf("agents", input.agents, MAX_AGENTS, errors);
+  for (const raw of agents) {
+    if (isRecord(raw) && nonEmpty(raw.key) && AGENT_KEY_PATTERN.test(raw.key))
+      agentKeys.add(raw.key);
+  }
+  if (input.agents !== undefined) {
+    document.agents = [];
+    const seen = new Set;
+    let entries = 0;
+    agents.forEach((raw, index) => {
+      const label = `agents[${index}]`;
+      if (!checkObject(label, raw, AGENT_FIELDS, errors))
+        return;
+      const agent = raw;
+      if (!nonEmpty(agent.key))
+        errors.push(`${label}.key is required`);
+      else if (!AGENT_KEY_PATTERN.test(agent.key))
+        errors.push(`${label}.key "${agent.key}" may only contain letters, digits, ".", "_" and "-" (max 128)`);
+      else if (seen.has(agent.key))
+        errors.push(`${label}: duplicate agent key "${agent.key}"`);
+      else
+        seen.add(agent.key);
+      if (agent.entry === true)
+        entries += 1;
+      if (agent.model !== undefined && checkObject(`${label}.model`, agent.model, MODEL_FIELDS, errors)) {
+        const model = agent.model;
+        if (typeof model.temperature === "number" && (model.temperature < 0 || model.temperature > 2)) {
+          errors.push(`${label}.model.temperature must be between 0 and 2`);
+        }
+        if (typeof model.topP === "number" && (model.topP <= 0 || model.topP > 1))
+          errors.push(`${label}.model.topP must be in (0, 1]`);
+        checkPositiveInt(`${label}.model.maxTokens`, model.maxTokens, errors);
+      }
+      checkPositiveInt(`${label}.maxToolRoundsPerTurn`, agent.maxToolRoundsPerTurn, errors);
+      if (agent.match !== undefined)
+        checkObject(`${label}.match`, agent.match, MATCH_FIELDS, errors);
+      const handoffTools = new Set;
+      (Array.isArray(agent.handoffs) ? agent.handoffs : []).forEach((handoff, hIndex) => {
+        const hLabel = `${label}.handoffs[${hIndex}]`;
+        if (!checkObject(hLabel, handoff, HANDOFF_FIELDS, errors))
+          return;
+        if (!nonEmpty(handoff.to)) {
+          errors.push(`${hLabel}.to is required`);
+          return;
+        }
+        if (!agentKeys.has(handoff.to))
+          errors.push(`${hLabel}.to "${handoff.to}" is not an agent key in this manifest`);
+        if (handoff.to === agent.key)
+          errors.push(`${hLabel}: an agent cannot hand off to itself`);
+        const tool = handoffToolName(handoff);
+        if (!TOOL_NAME_PATTERN.test(tool))
+          errors.push(`${hLabel}.tool "${tool}" must match ${TOOL_NAME_PATTERN.source}`);
+        else if (handoffTools.has(tool))
+          errors.push(`${hLabel}: duplicate handoff tool "${tool}"`);
+        else if ((agent.tools ?? []).includes(tool))
+          errors.push(`${hLabel}: handoff tool "${tool}" collides with a tool in ${label}.tools`);
+        handoffTools.add(tool);
+      });
+      (Array.isArray(agent.subagents) ? agent.subagents : []).forEach((subagent, sIndex) => {
+        const sLabel = `${label}.subagents[${sIndex}]`;
+        if (!checkObject(sLabel, subagent, SUBAGENT_FIELDS, errors))
+          return;
+        if (!nonEmpty(subagent.agent))
+          errors.push(`${sLabel}.agent is required`);
+        else if (!agentKeys.has(subagent.agent))
+          errors.push(`${sLabel}.agent "${subagent.agent}" is not an agent key in this manifest`);
+        if (!nonEmpty(subagent.tool))
+          errors.push(`${sLabel}.tool is required (the tool name the parent calls)`);
+        else if (!(agent.tools ?? []).includes(subagent.tool)) {
+          errors.push(`${sLabel}.tool "${subagent.tool}" must also be listed in ${label}.tools (with its schema in tools[])`);
+        }
+      });
+      for (const key of agent.context ?? []) {
+        if (!contextKeys.has(key))
+          errors.push(`${label}.context "${key}" is not a key in context[]`);
+      }
+      if (nonEmpty(agent.prompt) && !known.prompts.has(agent.prompt)) {
+        warnings.push(`${label}.prompt "${agent.prompt}" is not in prompts[]; it must already exist in Moda`);
+      }
+      for (const tool of agent.tools ?? []) {
+        if (!known.tools.has(tool))
+          warnings.push(`${label}.tools "${tool}" is not in tools[]; it must already exist in Moda`);
+      }
+      for (const skill of agent.skills ?? []) {
+        if (!known.skills.has(skill))
+          warnings.push(`${label}.skills "${skill}" is not in skills[]; it must already exist in Moda`);
+      }
+      document.agents.push(agent);
+    });
+    if (entries > 1)
+      errors.push('agents: at most one agent may set "entry": true');
+  }
+  if (input.routing !== undefined) {
+    if (checkObject("routing", input.routing, ROUTING_FIELDS, errors)) {
+      const routing = input.routing;
+      checkEnum("routing.strategy", routing.strategy, ROUTING_STRATEGIES, errors);
+      if (routing.default !== undefined && !agentKeys.has(routing.default)) {
+        errors.push(`routing.default "${routing.default}" is not an agent key in agents[]`);
+      }
+      document.routing = routing;
+    }
+  }
+  if (input.mcpServers !== undefined) {
+    document.mcpServers = [];
+    const names = new Set;
+    listOf("mcpServers", input.mcpServers, MAX_MCP_SERVERS, errors).forEach((raw, index) => {
+      const label = `mcpServers[${index}]`;
+      if (!checkObject(label, raw, MCP_FIELDS, errors))
+        return;
+      const server = raw;
+      if (!nonEmpty(server.name))
+        errors.push(`${label}.name is required`);
+      else if (names.has(server.name))
+        errors.push(`${label}: duplicate MCP server name "${server.name}"`);
+      else
+        names.add(server.name);
+      checkEnum(`${label}.transport`, server.transport, MCP_TRANSPORTS, errors);
+      if (server.url !== undefined && hasUrlCredentials(server.url)) {
+        errors.push(`${label}.url must not contain credentials (user info or token query parameters)`);
+      }
+      document.mcpServers.push(server);
+    });
+  }
+  if (Buffer.byteLength(JSON.stringify(document), "utf8") > MAX_HARNESS_DOCUMENT_BYTES) {
+    errors.push(`harness sections exceed ${MAX_HARNESS_DOCUMENT_BYTES} bytes`);
+  }
+  return document;
+}
+function hasUrlCredentials(raw) {
+  try {
+    const url = new URL(raw);
+    if (url.username || url.password)
+      return true;
+    return [...url.searchParams.keys()].some((key) => /token|key|secret|password|auth/i.test(key));
+  } catch {
+    return false;
+  }
+}
+function listOf(label, value, max, errors) {
+  if (!Array.isArray(value)) {
+    errors.push(`${label} must be an array`);
+    return [];
+  }
+  if (value.length > max)
+    errors.push(`${label} has ${value.length} entries; the limit is ${max}`);
+  return value;
+}
+function checkObject(label, value, spec, errors) {
+  if (!isRecord(value)) {
+    errors.push(`${label} must be an object`);
+    return false;
+  }
+  let typed = true;
+  for (const [key, item] of Object.entries(value)) {
+    const expected = spec[key];
+    if (!expected) {
+      errors.push(`${label}: unknown field "${key}" (allowed: ${Object.keys(spec).join(", ")})`);
+      continue;
+    }
+    const ok = expected === "string[]" ? Array.isArray(item) && item.every((entry) => typeof entry === "string") : expected === "object[]" ? Array.isArray(item) && item.every(isRecord) : expected === "object" ? isRecord(item) : expected === "number" ? typeof item === "number" && Number.isFinite(item) : typeof item === expected;
+    if (!ok) {
+      errors.push(`${label}.${key} must be ${describe(expected)}`);
+      typed = false;
+    }
+  }
+  return typed;
+}
+function describe(type) {
+  if (type === "string[]")
+    return "an array of strings";
+  if (type === "object[]")
+    return "an array of objects";
+  return type === "object" ? "an object" : `a ${type}`;
+}
+function checkEnum(label, value, allowed, errors) {
+  if (value === undefined || typeof value !== "string")
+    return;
+  if (!allowed.includes(value))
+    errors.push(`${label} must be one of ${allowed.join(", ")} (got "${value}")`);
+}
+function checkPositiveInt(label, value, errors) {
+  if (value === undefined || typeof value !== "number")
+    return;
+  if (!Number.isInteger(value) || value <= 0)
+    errors.push(`${label} must be a positive integer`);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function nonEmpty(value) {
+  return typeof value === "string" && value.trim() !== "";
+}
+
+// src/registry-prompt.ts
+var REGISTRY_AGENT_BRIEF = `# Register this repo's AI harness with Moda for faithful replays
+
+You are working in the repository that runs our production AI agent. Moda
+replays recorded production conversations against our agent to test prompt,
+tool, and skill changes. A replay is only as faithful as what Moda knows about
+how our agent actually runs. Your job: describe our harness to Moda exactly,
+push it with the \`moda\` CLI, and make sure our production traces say which
+agent and prompt handled each LLM call.
+
+## Ground rules
+
+- Read the code; do not guess. Every value you register must come from the
+  repo (cite the file in \`sourcePath\` or in a note). If something is decided
+  at runtime and you can't find it, say so in your final report.
+- Copy prompt text, tool names, tool descriptions, and parameter schemas
+  verbatim. For templated prompts, keep the template with its placeholders
+  (\`{{name}}\`, \`{name}\`, \`\${name}\`). Never register a rendered example.
+- Never put secrets in the manifest: no API keys, tokens, auth headers, env var
+  values, or customer data.
+- Do not change runtime behaviour. Part 5 adds trace metadata only. Show the
+  diff and get my OK before committing it.
+- Only \`.moda/registry.json\` (plus the files it references) is uploaded.
+  Nothing else in the repo leaves this machine.
+
+## Part 0: setup
+
+1. Run \`moda --version\`. You need 1.44.0 or newer. If it's older, run
+   \`npm install -g @moda-ai/cli@latest\`.
+2. Auth: \`MODA_API_KEY\` must be set, or run \`moda auth login --api-key=<key>\`.
+   Ask me for the key if neither is available. Check with \`moda doctor\`.
+3. Run \`moda registry template\` to see a complete example manifest, and
+   \`moda registry status\` to see what is already registered.
+
+## Part 1: inventory the harness
+
+Find every place the code calls an LLM: direct SDK calls (OpenAI, Anthropic,
+Gemini, Bedrock, OpenRouter), framework agents, and anything else. For each
+call site, write down:
+
+- **Agent**: the logical agent it belongs to, with a stable key such as
+  \`triage\` or \`billing\`. Different system prompts, tool sets, or models mean
+  different agents. A one-off call (summariser, classifier, title generator)
+  is its own agent if it runs during a conversation.
+- **Prompt**: the system prompt or messages it sends, how they're built
+  (static text, template plus variables, or code that assembles them), and
+  the file.
+- **Model and settings**: model id, provider, temperature, max tokens, top_p,
+  and reasoning effort, wherever they're set (code, config, env defaults).
+- **Tools**: every tool the model can call at that site, with the exact JSON
+  schema the model sees. Include MCP tools and agents exposed as tools.
+- **Skills**: SKILL.md files or instruction docs the agent loads, and HOW it
+  loads them (a tool such as skill_read or read_file, inlined into the system
+  prompt, or not at all).
+- **Loop limits**: max tool rounds or steps per turn, parallel tool calls, and
+  how history is truncated or summarised.
+
+Framework hints:
+
+- **OpenAI Agents SDK**: \`Agent(name, instructions, model, model_settings,
+  tools, handoffs)\`. \`name\` is the trace agent name. Handoffs become
+  \`transfer_to_<agent>\` tools.
+- **Claude Agent SDK / Claude Code SDK**: \`ClaudeAgentOptions(system_prompt,
+  model, allowed_tools, mcp_servers, agents=...)\`. Subagents are \`agents\`,
+  and skills live in \`.claude/skills/*/SKILL.md\`.
+- **LangGraph / LangChain**: each node that binds an LLM (\`bind_tools\`,
+  \`create_react_agent\`) is an agent. Conditional edges are the routing.
+- **Vercel AI SDK**: \`generateText\` / \`streamText({ system, tools, model,
+  maxSteps | stopWhen })\`.
+- **Raw SDK calls**: the system message, \`tools=\`, and \`model=\` arguments.
+
+## Part 2: work out prompt switching
+
+Work out how the harness decides which agent and prompt answers a given turn.
+That becomes \`routing\` and the agents' \`handoffs\`:
+
+- **single**: one agent always answers. Prompt versions still change over
+  time; Part 5 handles that.
+- **handoff**: the model transfers control by calling a tool (OpenAI Agents
+  handoffs, a "transfer_to_*" function, or a supervisor delegating). Add
+  \`handoffs: [{ "to": "<agent key>", "tool": "<exact tool name>",
+  "description": "<when>" }]\` to the source agent.
+- **router / rules**: code picks the agent (by channel, intent classifier,
+  conversation stage, user plan, or feature flag). Describe the rule in
+  \`routing.notes\` and make sure Part 5's attribution names the chosen agent
+  on every call.
+- **trace_attribute**: the agent is already identified on every trace.
+- **subagents** (agents as tools): the parent calls a tool that runs another
+  agent and returns its result. Register that tool's schema in \`tools[]\`,
+  list it in the parent's \`tools\`, and add \`subagents: [{ "agent": "<child
+  key>", "tool": "<tool name>" }]\`.
+
+Set \`routing.default\` to the agent that answers when nothing else decides,
+and mark the first agent a conversation reaches with \`"entry": true\`.
+
+## Part 3: list the injected context
+
+For every placeholder in every prompt, and anything appended to the prompt at
+runtime, add a \`context[]\` entry:
+
+- \`source: "static"\`: the same value every time (put it in \`value\`).
+- \`source: "clock"\`: the current date or time (\`format\`: date, datetime, or
+  iso). Replay uses the original conversation's time.
+- \`source: "trace"\`: a per-user or per-conversation value, such as the
+  profile, account, plan, or locale.
+- \`source: "memory" | "retrieval" | "tool"\`: memory recall, RAG results, or a
+  tool fetched before the call.
+- \`target: "prompt_variable"\` (with \`variable\` set to the placeholder name,
+  without braces) for template variables, or \`target: "system_append"\` for
+  blocks the code appends.
+
+List context keys on an agent with \`context: [...]\` when only some agents get
+them.
+
+## Part 4: write, validate, and push the manifest
+
+Write \`.moda/registry.json\` with \`"schema": "moda_registry.v2"\`:
+
+- \`prompts[]\`: \`{ key, file | content | systemPrompt | messages, name,
+  description, variables, modelConfig, responseSchema, sourcePath }\`. If the
+  repo already uses \`moda prompts\` (it has a \`.moda/prompts.lock.json\`),
+  reuse those keys.
+- \`tools[]\`: \`{ schema: { name, description, parameters } }\`, exactly as
+  sent to the model.
+- \`skills[]\`: \`{ key, file: "path/to/SKILL.md" }\`. Set \`"live": true\` only
+  if I ask.
+- \`agents[]\`: \`{ key, name, entry, prompt, model: { id, provider,
+  temperature, maxTokens, topP, reasoningEffort }, tools, skills, handoffs,
+  subagents, context, maxToolRoundsPerTurn, responseSchema, match: {
+  agentNames, promptKeys } }\`. \`match.agentNames\` are the names this agent
+  carries in traces; \`match.promptKeys\` are prompt keys that identify it.
+- \`routing\`: \`{ strategy, default, notes }\`.
+- \`runtime\`: \`{ framework, language, maxToolRoundsPerTurn,
+  parallelToolCalls, history: { strategy, maxMessages, maxTokens },
+  skillLoading: "tool" | "system_prompt" | "none" }\`.
+- \`context[]\`: from Part 3.
+- \`mcpServers[]\`: \`{ name, transport, url | command, tools, description }\`,
+  with no credentials. Their tools still go in \`tools[]\`.
+
+Then run:
+
+    moda registry validate          # local; fix every error and read every warning
+    moda registry push --dry-run    # server-side preview, writes nothing
+    moda registry push --message="<what you registered or changed>"
+
+Re-pushing an unchanged manifest is a no-op. A changed prompt adds a new
+version, and a changed harness adds a new harness version.
+
+## Part 5: make traces name the agent and prompt version
+
+Replay picks the agent and prompt version that handled the replayed turn from
+attributes on each LLM call. Auto-instrumented calls don't carry them, so add
+them at each call site from Part 1:
+
+| What | OTel span attribute | Vercel AI SDK \`experimental_telemetry.metadata\` | \`/v1/ingest\` event field |
+|---|---|---|---|
+| Agent | \`gen_ai.agent.name\` (or \`moda.agent_name\`) | \`moda.agent_name\` | \`agent_name\` |
+| Prompt key | \`moda.prompt_key\` | \`moda.prompt_key\` | \`prompt_name\` |
+| Prompt version | \`moda.prompt_version_id\` | \`moda.prompt_version_id\` | \`prompt_version_id\` |
+
+- The agent value must be the agent's \`key\` or one of its
+  \`match.agentNames\`. Frameworks that already set \`gen_ai.agent.name\`
+  (OpenAI Agents SDK, many OpenInference/OpenLLMetry instrumentations) only
+  need \`match.agentNames\` to list those names.
+- Get the prompt version id from \`.moda/prompts.lock.json\` (written by
+  \`moda prompts sync\`), or leave it out. Replay then uses the prompt's prod
+  version.
+- Node with the Moda SDK: \`Moda.withLLMCall(..., ({ span }) =>
+  span.rawSpan.setAttribute(...))\`, or pass Vercel metadata through
+  \`Moda.getVercelAITelemetry({ metadata })\`.
+- Python: set the attributes in your OpenTelemetry instrumentation on the LLM
+  span, or send \`agent_name\` / \`prompt_*\` on \`/v1/ingest\` events.
+- Show me the diff before committing it.
+
+## Part 6: verify
+
+    moda registry status
+    moda registry coverage --days=7
+    moda registry log                # each push is a commit; review what changed
+
+Coverage compares the last N days of production traces with what you
+registered: the share of LLM calls naming an agent or prompt, agent names and
+prompt keys that match no registered agent, tools used in production but not
+registered, and registered agents never seen. Fix the manifest (or the
+attribution) and push again until there is nothing unexplained left. Attribution
+added in Part 5 only shows up on traces created after it ships.
+
+## Final report
+
+Reply with:
+
+1. The agents you registered: key, prompt, model, tool count, skill count, and
+   handoffs.
+2. The routing strategy, and how you verified it.
+3. Context entries whose values replay can't reproduce (\`trace\`, \`memory\`,
+   \`retrieval\`, \`tool\`).
+4. The attribution diff (or that it's pending my OK).
+5. The \`moda registry coverage\` result, plus anything unexplained you
+   couldn't resolve.
+6. Anything you found but couldn't express in the manifest.
+`;
+
+// src/registry.ts
+var REGISTRY_SCHEMA = "moda_registry.v2";
+var REGISTRY_SCHEMA_V1 = "moda_registry.v1";
 var DEFAULT_REGISTRY_PATH = ".moda/registry.json";
 var SKILL_KEY_PATTERN = /^[A-Za-z0-9_-]+$/;
 var MAX_ITEMS_PER_SECTION = 500;
@@ -2075,7 +2605,7 @@ var REGISTRY_TEMPLATE = {
       key: "support.triage",
       name: "Support triage system prompt",
       description: "Routes inbound support messages",
-      content: "You are a support triage agent. Classify the request and ...",
+      content: "You are a support triage agent for {{company_name}}. Today is {{current_date}}. Classify the request and ...",
       sourcePath: "src/agents/triage/prompt.ts"
     },
     {
@@ -2108,12 +2638,49 @@ description: How to process refund requests
         }
       }
     }
+  ],
+  runtime: {
+    framework: "openai-agents",
+    language: "python",
+    maxToolRoundsPerTurn: 6,
+    history: { strategy: "window", maxMessages: 40 },
+    skillLoading: "tool"
+  },
+  agents: [
+    {
+      key: "triage",
+      name: "Triage",
+      entry: true,
+      prompt: "support.triage",
+      model: { id: "openai/gpt-5.1", temperature: 0.2, maxTokens: 1024 },
+      tools: ["lookup_customer"],
+      handoffs: [{ to: "reply", description: "Hand off once the request is classified" }],
+      match: { agentNames: ["TriageAgent"] }
+    },
+    {
+      key: "reply",
+      name: "Reply writer",
+      prompt: "support.reply",
+      model: { id: "anthropic/claude-sonnet-5-5", temperature: 0.4, maxTokens: 2048 },
+      skills: ["refund-policy"],
+      match: { agentNames: ["ReplyAgent"] }
+    }
+  ],
+  routing: { strategy: "handoff", default: "triage" },
+  context: [
+    { key: "today", variable: "current_date", source: "clock", format: "date" },
+    { key: "company", variable: "company_name", source: "static", value: "Acme" }
   ]
 };
 var REGISTRY_SUBCOMMAND_FLAGS = {
   template: ["out", "dry-run"],
   validate: ["file", "manifest"],
-  push: ["file", "manifest", "live", "dry-run"]
+  push: ["file", "manifest", "live", "dry-run", "message"],
+  log: ["limit"],
+  show: [],
+  status: [],
+  coverage: ["days"],
+  prompt: []
 };
 async function runRegistryCommand(context) {
   const subcommand = context.positionals[0] ?? "push";
@@ -2123,18 +2690,50 @@ async function runRegistryCommand(context) {
       return writeTemplate(context);
     case "validate": {
       const registry = loadRegistry(context);
+      printWarnings(context, registry.warnings);
       context.output.writeData({
-        schema: REGISTRY_SCHEMA,
+        schema: registry.schema,
         manifest: displayPath(context, registry.manifestPath),
         valid: true,
-        counts: countsOf(registry)
+        counts: countsOf(registry),
+        warnings: registry.warnings
       });
       return { exitCode: 0 };
     }
     case "push":
       return pushRegistry(context);
+    case "status":
+      return readRegistry(context, "/harness-registry");
+    case "log": {
+      const limit = context.flags.limit;
+      if (limit !== undefined && !/^\d+$/.test(limit)) {
+        throw new CliInputError("--limit must be a whole number.", "Usage: moda registry log [--limit=20]");
+      }
+      return readRegistry(context, `/registry/commits${limit ? `?limit=${limit}` : ""}`);
+    }
+    case "show": {
+      const ref = context.positionals[1];
+      if (!ref) {
+        throw new CliInputError("Missing commit.", 'Usage: moda registry show <commit> (a hash from `moda registry log`, or "working")');
+      }
+      return readRegistry(context, ref === "working" ? "/registry/compare?to=working" : `/registry/commits/${encodeURIComponent(ref)}`);
+    }
+    case "coverage": {
+      const days = context.flags.days;
+      if (days !== undefined && !/^\d+$/.test(days)) {
+        throw new CliInputError("--days must be a whole number of days.", "Usage: moda registry coverage [--days=7]");
+      }
+      return readRegistry(context, `/harness-registry/coverage${days ? `?days=${days}` : ""}`);
+    }
+    case "prompt":
+      if (context.outputMode === "human")
+        process.stdout.write(`${REGISTRY_AGENT_BRIEF}
+`);
+      else
+        context.output.writeData({ prompt: REGISTRY_AGENT_BRIEF });
+      return { exitCode: 0 };
     default:
-      throw new CliInputError(`Unknown registry command '${subcommand}'.`, "Usage: moda registry template|validate|push [--file=.moda/registry.json] [--dry-run] [--live]");
+      throw new CliInputError(`Unknown registry command '${subcommand}'.`, "Usage: moda registry template|validate|push|status|coverage|log|show|prompt [--file=.moda/registry.json] [--dry-run] [--live]");
   }
 }
 function writeTemplate(context) {
@@ -2159,6 +2758,9 @@ function writeTemplate(context) {
   return { exitCode: 0 };
 }
 async function pushRegistry(context) {
+  const message = context.flags.message;
+  if (message === "true")
+    throw new CliInputError("Missing text for --message.", 'Usage: moda registry push --message="Add billing agent"');
   const registry = loadRegistry(context);
   const profileOptions = { profile: context.profile, env: context.env };
   const hasKey = Boolean(resolveApiKey(profileOptions));
@@ -2191,7 +2793,20 @@ async function pushRegistry(context) {
   await push("prompts", "/prompts/sync", registry.prompts.length, { prompts: registry.prompts });
   await push("skills", "/skills/sync", registry.skills.length, { skills: registry.skills });
   await push("tools", "/tool-definitions/sync", registry.tools.length, { tools: registry.tools });
+  if (registry.harness) {
+    await push("harness", "/harness-registry/sync", 1, { schema: registry.schema, document: registry.harness });
+  }
+  let commit;
+  let commitError;
+  if (!context.dryRun && sections.some((section) => section.status === "synced")) {
+    try {
+      commit = await callControlAPI("/registry/commits", { method: "POST", body: JSON.stringify({ ...message ? { message } : {}, ...gitInfo(context.cwd) }) }, profileOptions);
+    } catch (error) {
+      commitError = error instanceof Error ? error.message : String(error);
+    }
+  }
   const failed = sections.filter((section) => section.status === "error");
+  printWarnings(context, registry.warnings);
   if (context.outputMode === "human" && !context.quiet) {
     for (const section of sections) {
       const detail = section.status === "error" ? ` — ${section.error}` : describeActions(section.response);
@@ -2200,13 +2815,26 @@ async function pushRegistry(context) {
     if (sections.some((section) => section.section === "tools" && section.status === "synced")) {
       console.error("  Replays now give your agent these tools with their real schemas and descriptions.");
     }
+    if (sections.some((section) => section.section === "harness" && section.status === "synced")) {
+      console.error("  Replays now rebuild the agent live at each replayed turn. Check `moda registry coverage`.");
+    }
+    const recorded = isRecord2(commit) && isRecord2(commit.commit) ? commit.commit : undefined;
+    if (recorded) {
+      const label = commit && isRecord2(commit) && commit.action === "unchanged" ? "no registry changes since" : "commit";
+      console.error(`  ${label} ${String(recorded.id).slice(0, 7)} (#${String(recorded.seq)}) ${String(recorded.summary ?? "")}`);
+    } else if (commitError) {
+      console.error(`  commit: not recorded — ${commitError}`);
+    }
   }
   context.output.writeData({
-    schema: REGISTRY_SCHEMA,
+    schema: registry.schema,
     manifest: displayPath(context, registry.manifestPath),
     dryRun: context.dryRun,
     counts: countsOf(registry),
-    sections
+    sections,
+    warnings: registry.warnings,
+    ...commit !== undefined ? { commit } : {},
+    ...commitError ? { commitError } : {}
   }, {
     status: failed.length > 0 ? "error" : "success",
     ...failed.length > 0 ? {
@@ -2219,11 +2847,39 @@ async function pushRegistry(context) {
   });
   return { exitCode: failed.length > 0 ? 1 : 0 };
 }
+function gitInfo(cwd) {
+  const git = (...args) => execFileSync("git", args, { cwd, stdio: ["ignore", "pipe", "ignore"], timeout: 5000 }).toString().trim();
+  try {
+    const gitCommit = git("rev-parse", "HEAD");
+    const branch = git("rev-parse", "--abbrev-ref", "HEAD");
+    return {
+      gitCommit,
+      ...branch && branch !== "HEAD" ? { gitBranch: branch } : {},
+      gitDirty: git("status", "--porcelain").length > 0
+    };
+  } catch {
+    return {};
+  }
+}
+async function readRegistry(context, endpoint) {
+  const profileOptions = { profile: context.profile, env: context.env };
+  if (!resolveApiKey(profileOptions)) {
+    throw new CliInputError("No Moda API key found.", "Set MODA_API_KEY, run `moda auth login --api-key=<key>`, or select a profile with an API key.");
+  }
+  context.output.writeData(await callControlAPI(endpoint, { method: "GET" }, profileOptions));
+  return { exitCode: 0 };
+}
+function printWarnings(context, warnings) {
+  if (context.outputMode !== "human" || context.quiet)
+    return;
+  for (const warning of warnings)
+    console.error(`  warning: ${warning}`);
+}
 function describeActions(response) {
-  const synced = isRecord(response) && Array.isArray(response.synced) ? response.synced : [];
+  const synced = isRecord2(response) && Array.isArray(response.synced) ? response.synced : [];
   const counts = new Map;
   for (const item of synced) {
-    if (!isRecord(item))
+    if (!isRecord2(item))
       continue;
     const action = typeof item.action === "string" ? `${item.action}${typeof item.reason === "string" ? ` (${item.reason})` : ""}` : item.changed === false ? "unchanged" : item.policyChanged === true && item.changed === true ? "changed (live setting)" : item.changed === true ? "changed" : "synced";
     counts.set(action, (counts.get(action) ?? 0) + 1);
@@ -2298,13 +2954,17 @@ function checkFields(label, item, spec, errors) {
 }
 function resolveRegistry(input, options) {
   const errors = [];
-  if (!isRecord(input)) {
+  const warnings = [];
+  if (!isRecord2(input)) {
     throw new CliInputError("Registry manifest must be a JSON object with prompts, skills, and/or tools arrays.");
   }
-  if (input.schema !== undefined && input.schema !== REGISTRY_SCHEMA) {
-    errors.push(`schema must be "${REGISTRY_SCHEMA}" (got ${JSON.stringify(input.schema)})`);
+  if (input.schema !== undefined && input.schema !== REGISTRY_SCHEMA && input.schema !== REGISTRY_SCHEMA_V1) {
+    errors.push(`schema must be "${REGISTRY_SCHEMA}" or "${REGISTRY_SCHEMA_V1}" (got ${JSON.stringify(input.schema)})`);
+  }
+  if (input.schema === REGISTRY_SCHEMA_V1 && hasHarnessSections(input)) {
+    errors.push(`${HARNESS_SECTIONS.join(", ")} need schema "${REGISTRY_SCHEMA}"`);
   }
-  const known = new Set(["schema", "prompts", "skills", "tools"]);
+  const known = new Set(["schema", "prompts", "skills", "tools", ...HARNESS_SECTIONS]);
   for (const key of Object.keys(input)) {
     if (!known.has(key))
       errors.push(`unknown top-level field "${key}"`);
@@ -2336,7 +2996,7 @@ function resolveRegistry(input, options) {
   const sourcePathFor = (file) => relative(options.cwd, resolve2(options.cwd, file)).split("\\").join("/");
   const prompts = arrayOf(input.prompts, "prompts", errors).map((raw, index) => {
     const label = `prompts[${index}]`;
-    if (!isRecord(raw)) {
+    if (!isRecord2(raw)) {
       errors.push(`${label} must be an object`);
       return;
     }
@@ -2361,7 +3021,7 @@ function resolveRegistry(input, options) {
   });
   const skills = arrayOf(input.skills, "skills", errors).map((raw, index) => {
     const label = `skills[${index}]`;
-    if (!isRecord(raw)) {
+    if (!isRecord2(raw)) {
       errors.push(`${label} must be an object`);
       return;
     }
@@ -2403,13 +3063,13 @@ function resolveRegistry(input, options) {
   const toolNames = new Set;
   const tools = arrayOf(input.tools, "tools", errors).map((raw, index) => {
     const label = `tools[${index}]`;
-    if (!isRecord(raw) || !isRecord(raw.schema)) {
+    if (!isRecord2(raw) || !isRecord2(raw.schema)) {
       errors.push(`${label}.schema must be an object (OpenAI function schema)`);
       return;
     }
     checkFields(label, raw, TOOL_FIELDS, errors);
     const tool = raw;
-    const inner = tool.schema.type === "function" && isRecord(tool.schema.function) ? tool.schema.function : tool.schema;
+    const inner = tool.schema.type === "function" && isRecord2(tool.schema.function) ? tool.schema.function : tool.schema;
     const schemaName = typeof inner.name === "string" ? inner.name.trim() : undefined;
     const name = (typeof tool.name === "string" ? tool.name.trim() : "") || schemaName;
     if (typeof tool.name === "string" && tool.name.trim() && schemaName && tool.name.trim() !== schemaName) {
@@ -2428,9 +3088,9 @@ function resolveRegistry(input, options) {
       errors.push(`${label}: schema.description must be a string`);
     }
     if (inner.parameters !== undefined) {
-      if (!isRecord(inner.parameters) || inner.parameters.type !== "object") {
+      if (!isRecord2(inner.parameters) || inner.parameters.type !== "object") {
         errors.push(`${label}: schema.parameters.type must be "object"`);
-      } else if (inner.parameters.properties !== undefined && !isRecord(inner.parameters.properties)) {
+      } else if (inner.parameters.properties !== undefined && !isRecord2(inner.parameters.properties)) {
         errors.push(`${label}: schema.parameters.properties must be an object`);
       }
     }
@@ -2452,6 +3112,7 @@ function resolveRegistry(input, options) {
       skillKeys.add(skill.key);
     }
   }
+  const harness = validateHarnessSections(input, { prompts: promptKeys, tools: toolNames, skills: skillKeys }, errors, warnings);
   if (errors.length > 0) {
     throw new CliInputError(`Registry manifest is invalid:
   - ${errors.join(`
@@ -2459,12 +3120,15 @@ function resolveRegistry(input, options) {
   }
   const resolved = {
     manifestPath: options.manifestPath,
+    schema: typeof input.schema === "string" ? input.schema : harness ? REGISTRY_SCHEMA : REGISTRY_SCHEMA_V1,
     prompts: prompts.filter(isDefined),
     skills: skills.filter(isDefined),
-    tools: tools.filter(isDefined)
+    tools: tools.filter(isDefined),
+    ...harness ? { harness } : {},
+    warnings
   };
-  if (resolved.prompts.length + resolved.skills.length + resolved.tools.length === 0) {
-    throw new CliInputError("Registry manifest has no prompts, skills, or tools to push.");
+  if (resolved.prompts.length + resolved.skills.length + resolved.tools.length === 0 && !harness) {
+    throw new CliInputError("Registry manifest has no prompts, skills, tools, or agents to push.");
   }
   return resolved;
 }
@@ -2481,7 +3145,16 @@ function arrayOf(value, label, errors) {
   return value;
 }
 function countsOf(registry) {
-  return { prompts: registry.prompts.length, skills: registry.skills.length, tools: registry.tools.length };
+  return {
+    prompts: registry.prompts.length,
+    skills: registry.skills.length,
+    tools: registry.tools.length,
+    ...registry.harness ? {
+      agents: registry.harness.agents?.length ?? 0,
+      context: registry.harness.context?.length ?? 0,
+      mcpServers: registry.harness.mcpServers?.length ?? 0
+    } : {}
+  };
 }
 function displayPath(context, path) {
   const rel = relative(context.cwd, path);
@@ -2491,7 +3164,7 @@ function isInside(root, target) {
   const rel = relative(resolve2(root), target);
   return rel === "" || !rel.startsWith("..") && !isAbsolute2(rel);
 }
-function isRecord(value) {
+function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function nonEmptyString(value) {
@@ -7198,7 +7871,7 @@ Commands:
   skills sync                      Push local .claude/skills/**/SKILL.md up to Moda
   skills sync --dry-run            Show what would be pushed without writing
   skills list|show|policy          List pushed skills, show one, or set --live/--local
-  registry push                    Push prompts, skills, and tools from one JSON manifest
+  registry push                    Push prompts, skills, tools, and agent wiring from one JSON manifest
 
 Options:
   --help                           Show this help message
@@ -7993,7 +8666,7 @@ async function searchFallbackToTraces(params) {
     last_timestamp: row.last_timestamp ?? null
   }));
   const first = asString(rows[0].conversation_id);
-  const describe = literal ? "trace-level keyword matches (each trace contains the words)" : `trace-level ${traceMode}-ranked related traces (they may not contain the exact words; fallback.total is the candidate pool, not a match count)`;
+  const describe2 = literal ? "trace-level keyword matches (each trace contains the words)" : `trace-level ${traceMode}-ranked related traces (they may not contain the exact words; fallback.total is the candidate pool, not a match count)`;
   const nextCommands = [];
   if (first) {
     nextCommands.push({ command: `moda audit ${first}`, purpose: "Open the top trace to locate the relevant message.", mutability: "read", requires_approval: false });
@@ -8018,7 +8691,7 @@ async function searchFallbackToTraces(params) {
         ...hasMore ? { next_offset: nextOffset } : {}
       }
     },
-    warning: `Message-level search returned 0 results, so these are ${describe}, from \`moda traces --search\`. ` + `Each result is a whole trace, not a message, with no score or message index. ` + `Open one with \`moda audit <conversation_id>\` or \`moda context <conversation_id>\` to find the matching turn.` + (hasMore ? " More exist: page with the suggested `moda traces --search ... --offset` command." : ""),
+    warning: `Message-level search returned 0 results, so these are ${describe2}, from \`moda traces --search\`. ` + `Each result is a whole trace, not a message, with no score or message index. ` + `Open one with \`moda audit <conversation_id>\` or \`moda context <conversation_id>\` to find the matching turn.` + (hasMore ? " More exist: page with the suggested `moda traces --search ... --offset` command." : ""),
     nextCommands
   };
 }
@@ -9681,17 +10354,19 @@ var commandRegistry = createCommandRegistry([
   },
   {
     name: "registry",
-    description: "Push prompts, skills, and tools to Moda from one agent-written JSON manifest (no repo scan)",
+    description: "Push prompts, skills, tools, and agent wiring (agents, routing, context) to Moda from one agent-written JSON manifest, so replays rebuild your harness (no repo scan)",
     examples: [
+      "moda registry prompt",
       "moda registry template --out=.moda/registry.json",
       "moda registry validate",
       "moda registry push --dry-run",
-      "moda registry push --file=.moda/registry.json"
+      "moda registry push --file=.moda/registry.json",
+      "moda registry coverage --days=7"
     ],
     subcommands: [
       {
         name: "template",
-        description: "Print (or write with --out) an example moda_registry.v1 manifest",
+        description: "Print (or write with --out) an example moda_registry.v2 manifest",
         usage: "moda registry template [--out=<path>] [--yes]",
         flags: [
           { name: "--out=<path>", description: "Write the template to a file instead of stdout (refuses to overwrite without --yes)." }
@@ -9707,18 +10382,51 @@ var commandRegistry = createCommandRegistry([
       },
       {
         name: "push",
-        description: "Upload the manifest's prompts, skills, and tools to the API key's tenant",
-        usage: "moda registry push [--file=<path>] [--dry-run] [--live]",
+        description: "Upload the manifest's prompts, skills, tools, and harness sections to the API key's tenant",
+        usage: "moda registry push [--file=<path>] [--dry-run] [--live] [--message=<text>]",
         flags: [
           { name: "--file=<path>", description: "Manifest path (default .moda/registry.json)." },
+          { name: "--message=<text>", description: "Message for the registry commit this push records (shown in the dashboard Registry history)." },
           { name: "--dry-run", description: "Server-side preview; nothing is written. Without an API key, validates locally only." },
           { name: "--live", description: "Mark every pushed skill live (included in the served skill surface)." }
         ],
         examples: ["moda registry push --dry-run", "moda registry push --live"]
+      },
+      {
+        name: "status",
+        description: "Show the registered harness (agents, routing, context) and its version",
+        usage: "moda registry status",
+        examples: ["moda registry status"]
+      },
+      {
+        name: "log",
+        description: "Registry history: one commit per push, with what changed",
+        usage: "moda registry log [--limit=20]",
+        flags: [{ name: "--limit=<n>", description: "Commits to list (default 50)." }],
+        examples: ["moda registry log --limit=10"]
+      },
+      {
+        name: "show",
+        description: `A registry commit's file diffs, or "working" for changes since the last push`,
+        usage: "moda registry show <commit|working>",
+        examples: ["moda registry show 3f9a2c1", "moda registry show working"]
+      },
+      {
+        name: "coverage",
+        description: "Compare recent production traces with the registry: attribution rate, unmatched agents and prompts, unregistered tools",
+        usage: "moda registry coverage [--days=7]",
+        flags: [{ name: "--days=<n>", description: "Look-back window in days (default 7, max 30)." }],
+        examples: ["moda registry coverage --days=7"]
+      },
+      {
+        name: "prompt",
+        description: "Print the brief to hand your coding agent so it inventories and registers your harness",
+        usage: "moda registry prompt",
+        examples: ["moda registry prompt | pbcopy", 'claude "$(moda registry prompt)"']
       }
     ],
     auth: "api-key",
-    authNote: "template and validate are local; push needs the API key (push --dry-run without a key validates locally only).",
+    authNote: "template, validate, and prompt are local; push, status, log, show, and coverage need the API key (push --dry-run without a key validates locally only).",
     outputModes: ["human", "json", "agent"],
     mutability: "write",
     validateConfigBeforeRun: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moda-ai/cli",
-  "version": "1.44.1",
+  "version": "1.45.0",
   "description": "CLI for Moda - AI agent analytics and observability",
   "type": "module",
   "bin": {

package/skills/integration/index.json

@@ -1,7 +1,7 @@
 {
   "schema_version": "moda.skill_index.v1",
-  "bundled_at": "2026-10-09T09:20:18.058Z",
-  "cli_version": "1.44.1",
+  "bundled_at": "2026-10-09T19:33:51.744Z",
+  "cli_version": "1.45.0",
   "skills": [
     {
       "id": "integration-cloudflare-think",

package/skills/moda-cli/SKILL.md

@@ -39,8 +39,9 @@ Activate this skill when the user wants to:
 - List/filter traces by user, environment, cluster, outcome, or time
 - Manage code-first prompt versions when the user explicitly asks for prompt
   sync, prompt status, or prompt promotion
-- Push their prompts, skills, and tool definitions to Moda without a repo
-  scan — `moda registry push` (section 7b)
+- Push their prompts, skills, tool definitions, and agent wiring (agents,
+  routing, injected context) to Moda without a repo scan, so replays rebuild
+  their harness — `moda registry push` (section 7b)
 
 **Do not** activate for: writing code that calls the Moda Data API directly
 (use the API docs instead), changing application instrumentation unless the
@@ -832,41 +833,66 @@ Page with `--cursor=<nextCursor>`. Playouts exist only for runs whose
 playouts were captured; `playoutCount: 0` on `run` means there is no
 transcript to read.
 
-### 7b. Push prompts, skills, and tools without a repo scan (`moda registry`)
+### 7b. Register the harness for replays (`moda registry`)
 
-Use when the user wants their prompts, skills, and tools visible in Moda but
-cannot (or does not want to) connect the GitHub App or run `moda harness
-analyze`. This fills the prompt, skill, and tool registries only. It does not
-create the harness graph (agents and how they connect), which still comes from
-`moda harness analyze`, the GitHub App, or an approved report via
-`moda harness sync --from-report`. **You** are the analyst: read the codebase you already have access
-to, write one manifest, and push exactly what it lists. Nothing else in the
-repo is uploaded.
+Use when the user wants their prompts, skills, tools, or agent wiring in Moda
+so replays rebuild their harness faithfully, without the GitHub App or `moda
+harness analyze`. **You** are the analyst: read the codebase you already have,
+write one manifest, and push exactly what it lists. Nothing else in the repo is
+uploaded. For a full guided pass (inventory, prompt switching, context,
+attribution, and verification), run `moda registry prompt` and follow the
+brief it prints.
 
 ```bash
-moda registry template --out=.moda/registry.json   # starter manifest
+moda registry prompt                                # the step-by-step brief for this job
+moda registry template --out=.moda/registry.json   # starter manifest (moda_registry.v2)
 # ...fill in .moda/registry.json from the codebase...
 moda registry validate                              # local only, no network
 moda registry push --dry-run                        # server-side preview, writes nothing
 moda registry push                                  # upload
+moda registry status                                # what is registered (harness version)
+moda registry coverage --days=7                     # production traces vs the registry
+moda registry log                                   # history: one commit per push
+moda registry show <commit|working>                 # a commit's file diffs / changes since the last push
 ```
 
-Manifest (`moda_registry.v1`; every section optional, ≤500 entries each):
+Every successful `push` records a registry **commit**: the whole registry
+(prompts, tools, skills, agents, harness settings) snapshotted as files, with
+your repo's git SHA, branch, and dirty flag. Pass `--message="..."` to label
+it. The dashboard **Registry** page shows these commits git-style: a log,
+per-file diffs, a file browser, and uncommitted changes made outside a push
+(dashboard edits, MCP discovery, `moda prompts sync`).
+
+Manifest (`moda_registry.v2`; `moda_registry.v1` with only prompts, skills, and
+tools still works; every section optional, ≤500 entries in prompts, skills, and tools):
 
 ```json
 {
-  "schema": "moda_registry.v1",
+  "schema": "moda_registry.v2",
   "prompts": [
-    { "key": "support.triage", "name": "Triage", "description": "...",
-      "content": "You are ...", "sourcePath": "src/agents/triage.ts" },
-    { "key": "support.reply", "file": "prompts/reply.md" }
+    { "key": "support.triage", "file": "prompts/triage.md" },
+    { "key": "support.billing", "content": "You handle billing for {{company_name}}..." }
   ],
   "skills": [
-    { "key": "refund-policy", "description": "...", "file": ".claude/skills/refund-policy/SKILL.md" }
+    { "key": "refund-policy", "file": ".claude/skills/refund-policy/SKILL.md" }
   ],
   "tools": [
     { "schema": { "name": "lookup_customer", "description": "...",
       "parameters": { "type": "object", "properties": { "email": { "type": "string" } } } } }
+  ],
+  "runtime": { "framework": "openai-agents", "maxToolRoundsPerTurn": 6, "skillLoading": "tool" },
+  "agents": [
+    { "key": "triage", "entry": true, "prompt": "support.triage",
+      "model": { "id": "openai/gpt-5.1", "temperature": 0.2, "maxTokens": 1024 },
+      "tools": ["lookup_customer"],
+      "handoffs": [{ "to": "billing", "tool": "transfer_to_billing" }],
+      "match": { "agentNames": ["TriageAgent"] } },
+    { "key": "billing", "prompt": "support.billing", "skills": ["refund-policy"] }
+  ],
+  "routing": { "strategy": "handoff", "default": "triage" },
+  "context": [
+    { "key": "company", "variable": "company_name", "source": "static", "value": "Acme" },
+    { "key": "today", "variable": "current_date", "source": "clock", "format": "date" }
   ]
 }
 ```
@@ -881,24 +907,64 @@ Manifest (`moda_registry.v1`; every section optional, ≤500 entries each):
 - **Skills:** `key` (letters, digits, `_`, `-`) plus `skillMd` or `file` (full
   SKILL.md). Pushed skills are *local* by default. Set `"live": true`, or pass
   `--live`, to include them in the served skill surface. Leaving `live` out
-  never demotes a skill that is already live.
+  never demotes a skill that is already live. Replays load the skills an agent
+  lists in `agents[].skills`, whether or not they are live.
 - **Tools:** an OpenAI function `schema` (a wrapped
   `{"type":"function","function":{...}}` is accepted), plus optional
   `isActive`. Copy names and parameter schemas exactly as the agent registers
   them with the model. Tools are upserted by name and never overwrite
   MCP-server-managed tools (those report `skipped`).
+- **Agents:** one per distinct prompt, tool set, or model. Fields: `key`,
+  `name`, `description`, `entry`, `prompt` (prompt key), `model` (`id`,
+  `provider`, `temperature`, `maxTokens`, `topP`, `reasoningEffort`), `tools`
+  (tool names), `skills` (skill keys), `handoffs` (`to`, `tool`,
+  `description`), `subagents` (`agent`, `tool`; the tool must also be in
+  `tools`), `context` (context keys), `maxToolRoundsPerTurn`,
+  `responseSchema`, `match` (`agentNames` as they appear in traces,
+  `promptKeys`).
+- **Routing (prompt switching):** `strategy` is `single`, `handoff`, `router`,
+  `rules`, or `trace_attribute`; `default` is an agent key; put code-level
+  rules in `notes`. Replay runs the agent named on the replayed turn's trace
+  (agent name, then prompt key), else `default`, else the `entry` agent. When
+  the replayed model calls a handoff tool, replay switches to the target
+  agent's prompt, tools, model, and params.
+- **Context:** what the runtime injects. `source` is `static` (with `value`),
+  `clock` (`format`: date, datetime, or iso; replay uses the source
+  conversation's time), or `trace`, `memory`, `retrieval`, `tool`, or
+  `unknown`. Those last ones are reported as unresolved in replay fidelity,
+  never invented. `target` is `prompt_variable` (needs `variable`) or
+  `system_append`.
+- **Runtime:** `framework`, `language`, `maxToolRoundsPerTurn`,
+  `parallelToolCalls`, `history` (`strategy`, `maxMessages`, `maxTokens`),
+  and `skillLoading` (`tool`, `system_prompt`, or `none`).
+- **MCP servers:** `name`, `transport`, `url` or `command`, `tools`, and
+  `description`, with no credentials. List their tools in `tools[]` too.
 - `file` paths are relative to the directory you run the command from and must
   stay inside it (symlinks included).
 
+**Traces must name the agent.** For per-turn prompt switching, each LLM call
+should carry `gen_ai.agent.name` (or `moda.agent_name`; with the Vercel AI SDK
+use `experimental_telemetry.metadata["moda.agent_name"]`; `agent_name` on
+`/v1/ingest`), set to an agent `key` or one of its `match.agentNames`. It
+should also carry `moda.prompt_key` / `moda.prompt_version_id`. Only add these
+to application code when the user asks for it or approves the diff.
+`moda registry coverage` shows how many recent calls resolve to a registered
+agent, which agent names, prompt keys, and tools are unregistered, and which
+agents were never seen.
+
 `push` needs an API key. `push --dry-run` without one only validates locally
 (status `validated`). Each section goes to its own endpoint and reports
 `sections[].status` (`synced`, `dry_run`, `validated`, `skipped`, or `error`).
-If any section fails, `push` exits `1`, lists the failures in `errors[]`, and
-still pushes the other sections. The whole manifest is validated before any
-request, with every error listed at once. Unknown fields and wrong types are
-rejected, matching what the server accepts. Skill keys are stricter than the
-server (letters, digits, `_`, `-`) because they double as `.claude/skills/<key>/`
-directory names.
+The harness sections (`runtime`, `agents`, `routing`, `context`, and
+`mcpServers`) are pushed last, as one versioned document. Re-pushing an
+unchanged one reports `unchanged`. If any section fails, `push` exits `1`,
+lists the failures in `errors[]`, and still pushes the other sections. The
+whole manifest is validated before any request, with every error listed at
+once. `warnings[]` names agent references to prompts, tools, or skills that
+the manifest doesn't define; they must already exist in Moda. Unknown fields
+and wrong types are rejected, matching what the server accepts. Skill keys are
+stricter than the server (letters, digits, `_`, `-`) because they double as
+`.claude/skills/<key>/` directory names.
 
 ### 8. Fixing detected Problems
 
@@ -1226,7 +1292,7 @@ npx: `npx -p @moda-ai/cli moda <command>`.
 | `moda prompts diff` | Read-only: only prompts changed/new/deleted since last sync (hash-level, not a text diff) |
 | `moda prompts sync` | Upload changed prompt versions and update lockfile |
 | `moda prompts promote <key>` | Move a remote prompt label |
-| `moda registry template\|validate\|push` | Push prompts, skills, and tools from one agent-written manifest (`--file`, `--dry-run`, `--live`); no repo scan |
+| `moda registry template\|validate\|push\|status\|coverage\|log\|show\|prompt` | Register prompts, skills, tools, and agent wiring from one agent-written manifest (`--file`, `--dry-run`, `--live`, `--message`, `--days`); every push is a commit in the Registry history; no repo scan |
 | `moda users` / `moda user <id>` | End users with health/activity; one user's profile |
 | `moda problem-reopen <pid>` | Reopen a Problem marked fixed |
 | `moda signals <create\|update\|activate\|pause\|delete\|examples\|refine\|revise\|proposals\|accept\|reject\|search\|preview>` | Manage custom signals (writes take `--dry-run`; LLM-backed ones are rate-limited per key) |