@getmarrow/mcp 3.9.42 → 3.9.44

package/README.md

@@ -1,768 +1,181 @@
 # @getmarrow/mcp
 
-> **Governance, proof, and decision intelligence for MCP-compatible agent fleets.**
+> MCP-native runtime control, proof, and fleet intelligence for AI agents.
 
-![npm](https://img.shields.io/npm/v/@getmarrow/mcp)
-![npm](https://img.shields.io/npm/dw/@getmarrow/mcp)
-![npm bundle size](https://img.shields.io/bundlephobia/minzip/@getmarrow/mcp)
-![GitHub](https://img.shields.io/github/license/getmarrow/marrow-mcp)
-![TypeScript](https://img.shields.io/badge/TypeScript-5.3%2B-blue)
-![Node.js](https://img.shields.io/badge/Node.js-18%2B-green)
+Marrow is the runtime control and proof layer for teams running AI agents. It applies policy and prior lessons before consequential actions, then records the evidence and outcome afterward.
 
-Marrow gives your agent a governance loop that compounds.
+Use `@getmarrow/mcp` when your agent client supports the Model Context Protocol and you want Marrow available inside the agent's normal workflow. It works with Claude Code, Claude Desktop, Cursor and other MCP-compatible clients without replacing the model or harness.
 
-With `@getmarrow/mcp`, any MCP-compatible client can ask Marrow before risky work, inspect live loop state during work, collect required proof, and commit outcomes when the work is done. That means your agent stops operating without accountability and starts carrying forward real decision history.
-
-**Your agent stops repeating the same mistakes. It learns from prior sessions, authorized fleet history, and sanitized shared signals while staying inside proof, policy, and tenant boundaries.**
-
-## Trust and Data Boundaries
-
-Marrow is tenant-aware by design. Private account, fleet, workflow, proof-pack, and agent data stays scoped to the authenticated account and authorized agent-bound keys.
-
-Enterprise tenants receive a strong private governance baseline from day one: risk gates, proof requirements, workflow templates, private/account learning, and exact next actions. Teams that enable sanitized aggregate contribution unlock richer k-anonymous collective workflow guidance. Contribution never means raw prompts, decisions, proof packs, code, secrets, account identifiers, agent identifiers, or customer identities.
-
-For business pilots, review the live trust notes before production rollout: https://getmarrow.ai/docs#trust-boundaries
-
-## What's New in v3.9.40
-
-v3.9.40 adds MCP tools for Marrow's governance-control layer.
-
-- `marrow_governance_control_plane` returns Marrow's cross-harness control-plane contract.
-- `marrow_hermes_integration` maps Hermes `/goal`, verification evidence, `/learn`, `/journey`, and background subagents into Marrow proof/outcome workflows.
-- `marrow_completion_contracts` lists built-in proof contracts for deploy, merge, publish, migration, security, support, and Hermes goal workflows.
-- `marrow_evaluate_completion_contract` checks whether an agent has enough proof to mark work complete.
-- `marrow_governance_timeline` returns a fleet journey timeline across decisions, gates, and proof packs.
-- `marrow_buyer_proof` returns owner/procurement-ready value proof: failures avoided, risky actions reviewed, proofs completed, token/time saved, failure classes, and reliability score.
-
----
-
-## Current Backend Surfaces
-
-The Marrow API also exposes two agent-facing surfaces that help MCP clients and operators verify whether passive capture is producing useful fleet data:
-
-- `GET /v1/agent/data-quality` returns an authenticated attribution scorecard for the current account or bound agent, including `agent_id`, `source_meta`, harness/client, workflow type, outcome closure, and non-trivial data coverage.
-- `GET /v1/agent/integrations/{client}` returns a per-harness setup guide for supported clients such as Codex, Claude Code, Cursor, Composer, Windsurf, Cline, OpenCode, Hermes, OpenClaw, Gemini, Grok, DeepSeek, Qwen, Kimi, MiniMax, GLM, MCP clients, CI runners, and custom harnesses.
-
-These endpoints are protected by Marrow API-key or agent-bound-key auth and are documented in the source-of-truth docs at [getmarrow.ai/docs](https://getmarrow.ai/docs/).
-
----
-
-## Start Here
-
-For most agents and new users, start with the universal installer:
+## Install
 
 ```bash
-npx @getmarrow/install --yes
-```
-
-The installer detects your MCP client, agent instructions, Node project, and runtime surfaces, then wires the safest passive setup automatically.
-It now also includes a governed runner: `npx @getmarrow/install run --agent <agent-id> -- <command>`, which gives MCP and non-MCP agents the same pre-action Marrow risk gate and automatic outcome closure for existing shell, deploy, publish, merge, and migration commands.
-MCP clients can also call `marrow_first_value` to show the first five-minute proof payload directly inside the agent.
-
-Use this MCP package directly when you want manual MCP server/hook setup for Claude Code, Claude Desktop, Cursor, or another MCP-compatible client. Use `@getmarrow/sdk` when you are building a custom Node/TypeScript integration in code.
-
-## Auto-Logging
-
-Marrow auto-logs at three layers — transparent to your agent, invisible to you:
-
-| Layer | How | Agent effort |
-|-------|-----|-------------|
-| Server-side | Every authenticated API call auto-logged as a decision | Zero |
-| Governed runner | `npx @getmarrow/install run --agent <id> -- <command>` — pre-action gate + outcome proof around existing commands | Minimal |
-| SDK | `marrow.think()` / `marrow.commit()` — explicit control | Minimal |
-| MCP hooks | `npx @getmarrow/mcp setup` — PostToolUse + UserPromptSubmit hooks | Zero |
-
-**Passive mode in action:** Run `npx @getmarrow/mcp setup` once. Every tool call your agent makes (Bash, file edits, MCP calls) is auto-logged in the background. Marrow intelligence is auto-injected into your agent's context. Fail-silent, 2-second timeout, never blocks your prompt.
-
-Disable: `MARROW_AUTO_HOOK=false`. Debug: `MARROW_HOOK_DEBUG=true`.
-
----
-
-## Improvement Since Onboarding
-
-`marrow_dashboard` and `marrow_digest` now return an `improvement` block comparing your agents' current performance against their day-1 baseline — a frozen snapshot of the first week of activity. Baseline captures automatically once an account reaches 7 days OR 20 decisions (whichever first).
-
-Four measured deltas, all from real decision data:
-
-- `attempts_per_success` — baseline week vs current week
-- `time_to_success_seconds` — median think → successful commit
-- `drift_rate` — % of decisions without a matching prior pattern
-- `success_rate` — baseline vs current outcome fraction
-
-Sample response:
-
-```json
-{
-  "improvement": {
-    "status": "active",
-    "days_since_baseline": 20,
-    "decisions_since_baseline": 2124,
-    "baseline_captured_at": "2026-04-23T15:07:41.919Z",
-    "trigger_reason": "time_7d",
-    "time_to_success_seconds": { "baseline": 244, "current": 24, "delta_pct": -90.16 }
-  }
-}
-```
-
-Accounts with <7 days of activity AND <20 decisions get an onboarding payload showing days/decisions until baseline fires. Token-value proof is also available now: MCP agents can call `marrow_model_usage` or attach `model_usage` to `marrow_commit` so Marrow reports observed model calls, tokens, estimated savings, trend direction, and top models without storing raw prompts or completions.
-
----
-
-## What's New in v3.9.37
-
-v3.9.37 adds MCP token-value proof status parity.
-
-- `marrow_model_usage` records compact provider/model token counts through `/v1/agent/model-usage`.
-- `marrow_commit` accepts optional `model_usage` and returns `token_value_signal` from the backend.
-- `marrow_runtime_status` calls `/v1/agent/status?fast=1` for live passive hook, token-capture, outcome-closure, and exact repair-command diagnostics.
-- Token usage data is counts and labels only: provider, model, input/output/cached/total tokens, cost, latency, outcome linkage, and optional saved-token estimates.
-- Do not send raw prompts, completions, tool logs, secrets, or customer content.
-
-## What's New in v3.9.33
-
-v3.9.33 adds MCP tools for adaptive governance recommendations and explicit policy profiles, while keeping the enterprise readiness contract documented for business pilots.
-
-- `marrow_mode_recommend` returns an explainable `passive`, `pilot`, or `enforce` recommendation for the current project/workflow.
-- `marrow_policy_profiles` lists saved account policy profiles, including the default business starter profile.
-- `marrow_create_policy_profile` creates or updates explicit rules such as local=passive, staging=pilot, production deploys=enforce.
-- `marrow_assign_project_policy_profile` binds an active profile to a project key so future resolves use it automatically.
-- `marrow_policy_resolve` resolves the current workflow mode from saved policy profiles, falling back to recommendation.
-- Marrow does not silently auto-switch modes. The agent/user must accept or override the recommendation.
-- MCP agents can call `GET /v1/agent/enterprise-readiness?agents=20` when an owner asks whether Marrow is ready for a fleet rollout.
-- The response is owner-safe and covers tenant isolation, data boundaries, fail behavior, policy controls, scale proof, and a 30-day pilot package.
-- The source-of-truth docs include the enterprise trust and scale readiness page at [getmarrow.ai/docs](https://getmarrow.ai/docs/).
-
-```json
-{
-  "project": {
-    "name": "agent-api",
-    "type": "node",
-    "frameworks": ["edge-service"],
-    "signals": ["package_json", "platform_config", "github_actions"]
-  },
-  "workflow": {
-    "action": "deploy production service",
-    "type": "deploy",
-    "environment": "production"
-  }
-}
-```
-
-## What's New in v3.9.42
-
-v3.9.42 adds typed adaptive capacity instructions to the MCP runtime contract.
-
-- `marrow_agent_runtime` now types `capacity_guidance` with capacity state, cache duration, recommended batch size, retry delay, safe parallelism, and polling guidance.
-- Passive hooks can keep low-risk work moving with bounded cached guidance while requiring a fresh gate and proof for high-risk actions.
-- The field is additive and remains compatible with existing MCP setup and outcome-closure hooks.
-
-Business value: MCP-compatible fleets get explicit backpressure behavior from Marrow instead of hard-coded retry guesses in every agent.
-
-## Previous Release Notes
-
-### v3.9.31
-
-v3.9.31 is a docs-sync release. It keeps npm and GitHub README copy aligned with Marrow's current backend-first runtime contract and proof/gate enforcement loop. Runtime behavior is unchanged from v3.9.30.
-
-v3.9.30 brings MCP tools and passive prompt hooks up to Marrow's current backend-first runtime contract and proof/gate enforcement loop:
-
-- UserPromptSubmit context now prefers `intervention.agent_copy`, so agents see the strongest `before you act` instruction before legacy runtime text.
-- `marrow_agent_runtime` types now expose `intervention`, `runtime_contract`, `risk_gate_event`, and `behavior_governance` for `/v1/agent/runtime`.
-- MCP now supports the backend-first contracts `marrow.before-action-intervention.v1` and `agent-runtime-contract.v3`.
-- `marrow_commit` exposes `proof`, `gate_receipt_id`, `action`, `surfaces`, and `auto_gate` fields for gated work.
-- MCP commit paths preserve the same fleet agent identity used by `marrow_think`, preventing agent-bound key commit mismatches.
-- `marrow_run` and `marrow_auto` attach standard proof packs when they close outcomes automatically.
-
-First-run value proof remains current:
-
-- `marrow_first_value` returns the five-minute proof payload: capture status, runtime gate, first useful lesson, value proof, and the exact try-this-now prompt.
-- UserPromptSubmit hook context still shows runtime interruption state, why Marrow is interrupting, required proof, and the quiet/noise policy.
-- Legacy `before_you_act_injection` types still expose `state`, `why_now`, `noise_policy`, `required_proof`, `missing_proof`, and `owner_approval_required`.
-
-Previous agent-native runtime behavior remains current:
-
-- UserPromptSubmit hooks call the one-call runtime by default, so agents receive status, risk gate, lessons, proof requirements, and exact next action before acting.
-- When Marrow marks `before_you_act_injection.must_use_before_action=true`, the prompt injection labels the Marrow action gate as required and tells the agent to stop if the lesson/proof cannot be applied.
-- `marrow_agent_runtime` now includes structured `before_you_act_injection` data for fleet lessons and deployment playbooks.
-- PostToolUse continues to close outcomes automatically for successful and failed tool calls.
-- Degraded passive capture points agents to exact installer/MCP/SDK repair commands.
-
-```json
-{
-  "action": "deploy edge service to production",
-  "type": "deploy",
-  "surfaces": ["github", "deployment-platform", "production"]
-}
-```
-
-Full feature history, examples, and API reference live at [getmarrow.ai/docs](https://getmarrow.ai/docs/).
-
----
-
-### Gated Commit Proof
-
-For risky actions, call `marrow_agent_runtime` before acting and pass the receipt plus proof into `marrow_commit`:
-
-```json
-{
-  "decision_id": "...",
-  "success": true,
-  "outcome": "Deploy succeeded and production smoke passed",
-  "gate_receipt_id": "runtime.gate_receipt.id",
-  "proof": {
-    "summary": "Production deploy completed",
-    "checks": ["tests passed", "smoke passed"],
-    "outcome": "success",
-    "blockers": "none",
-    "commits_prs_shas": "abc123",
-    "rollback_target": "previous release version",
-    "handoff_result_file": "/tmp/marrow-handoffs/release/result.md",
-    "deployment_and_smoke": "production smoke passed"
-  }
-}
-```
-
-If you provide `action` and omit `gate_receipt_id`, `marrow_commit` can fetch a matching runtime gate receipt automatically.
-
-## Human-Directed Attribution Status
-
-The Marrow API supports privacy-preserving provenance fields on direct `POST /v1/decisions` calls: `source_kind`, `human_directed`, `source_confidence`, `instruction_ref`, `instruction_hash`, and `source_meta`. These fields classify instruction source class without identifying the human or storing raw prompts/PII.
-
-MCP tools and passive hooks now attach structured attribution by default. Marrow sends `X-Marrow-Agent-Id` when `MARROW_FLEET_AGENT_ID` or `MARROW_AGENT_ID` is configured, and it fills `source_meta.channel`, `source_meta.client`, `source_meta.agent_id`, and `source_meta.user_intent` where safe. Set `MARROW_CLIENT`, `MARROW_HARNESS`, or `MARROW_AGENT_CLIENT` to one of the supported client labels (`codex`, `claude-code`, `cursor`, `gemini`, `grok`, `deepseek`, `qwen`, `kimi`, `minimax`, `cline`, `opencode`, `hermes`, `glm`, `openclaw`, `windsurf`, or `custom`) for cleaner per-harness reporting.
-
----
-
-## Agent Value Report
-
-`marrow_value_report` lets MCP agents pull owner-ready proof of Marrow value without a dashboard. The existing passive hooks remain the default install path: `PostToolUse` logs meaningful tool outcomes and `UserPromptSubmit` injects relevant context plus decision briefs for risky prompts.
-
-### Value Report Tool
-
-MCP tool: `marrow_value_report`.
-
-Use it when an agent needs to explain whether Marrow is active, useful, and improving the fleet.
-
-```json
-{
-  "period": "7d",
-  "agentId": "jarvis-agent"
-}
-```
-
-The response includes summary, decisions, success rate, saves, active agents, top risks, recommendations, and improvement data. It does not expose raw action, context, or outcome text.
-
-### Passive Decision Briefs
-
-Agents no longer need to remember to call `marrow_decision_brief` for common deploy, publish, merge, audit, patch, secret, or production prompts. They still can call it explicitly when they need stronger control.
-
-### Decision Brief Tool
-
-MCP tool: `marrow_decision_brief`.
-
-Use it before deploys, publishes, merges, audits, patches, secret changes, or production work. One call returns the agent's operating brief: risk, workflow/playbook steps, handoff requirements, freshness/source-of-truth checks, minimum verification checks, proof-pack fields, and next actions.
-
-```json
-{
-  "action": "publish SDK and MCP packages to npm and update docs",
-  "type": "deploy",
-  "role": "deploy",
-  "surfaces": ["github", "npm", "docs", "production"]
-}
+npx @getmarrow/mcp setup
 ```
 
-Marrow returns aggregated prior failure categories only. It does not expose raw action, context, or outcome text from past decisions.
-
-`marrow_decision_brief` is additive. It gives the pre-action operating brief, then the agent still logs intent with `marrow_think`/passive auto-logging and commits the verified outcome with `marrow_commit`.
-
-Passive decision briefs are enabled by default. Set `MARROW_PASSIVE_BRIEF=false` to disable them, or `MARROW_PASSIVE_BRIEF=always` to brief every prompt.
-
-### Workflow Gate Tool
+Set the key through trusted secret storage:
 
-MCP tool: `marrow_workflow_gate`.
-
-Use it before deploys, publishes, merges, DB migrations, key rotation, destructive commands, or production work.
-
-```json
-{
-  "action": "rotate deployment token and verify production",
-  "riskTolerance": "medium",
-  "requiresApproval": true
-}
+```bash
+export MARROW_API_KEY=mrw_live_...
 ```
 
-The response returns `allow`, `warn`, `review_required`, or `block`, plus prior lessons and deployment playbooks when available.
-
-Passive value summaries are enabled by default in auto mode. Set `MARROW_PASSIVE_VALUE_SUMMARY=false` to disable them, or `MARROW_PASSIVE_VALUE_SUMMARY=always` to include them on every prompt hook.
-
-Full feature history, examples, and API reference live at [getmarrow.ai/docs](https://getmarrow.ai/docs/).
-
----
-
-## Agent-Narrated Marrow Contribution
-
-Marrow now tells the agent exactly what it contributed to each decision, so the agent can surface that contribution to the user in plain English — no dashboard required.
-
-Three new fields:
-
-- `marrow_think` returns `marrow_contributed` describing what intelligence Marrow surfaced for this decision (warnings consulted, shared patterns, similar decisions, workflow templates, loop detection, collective insight).
-- `marrow_commit` returns `marrow_contributed` describing concrete signals on the commit itself (pattern reused, warning avoided, workflow step).
-- `marrow_session_end` returns `session_summary` aggregating Marrow's contribution across the session, plus a one-line `narrative` for the agent to surface as it wraps up.
-
-Each object includes `has_signal: boolean` — when true, the agent narrates Marrow's role in 1 sentence; when false, it stays quiet. The built-in `marrow-always-on` system prompt now instructs agents on tone and timing for these narrations.
-
-Sample think response:
+Then configure the MCP server:
 
 ```json
 {
-  "decision_id": "...",
-  "intelligence": { "...": "..." },
-  "marrow_contributed": {
-    "warnings_consulted": 2,
-    "hive_patterns_surfaced": 12,
-    "similar_decisions_found": 8,
-    "workflow_templates_available": 1,
-    "loop_detected": false,
-    "collective_intelligence": true,
-    "team_context_present": false,
-    "has_signal": true
+  "mcpServers": {
+    "marrow": {
+      "command": "npx",
+      "args": ["-y", "@getmarrow/mcp"]
+    }
   }
 }
 ```
 
-The user installed Marrow to make their agent better. They should hear, in plain English, what Marrow actually did. Their agent's reply IS the dashboard.
-
----
-
-## Agent-Narrated Milestones
-
-`marrow_commit` returns a `narrative` field. When a milestone fires (first commit, baseline capture, decision 100/500/1000/5000, weekly recap), the backend returns a human-readable string the agent relays to the user. Otherwise it returns `null`.
-
-```json
-{
-  "committed": true,
-  "narrative": "Baseline captured. Your first-week averages: 42s per task, 1.3 attempts per success."
-}
-```
-
-Narratives are aggregated metrics only — no user data, no decision content, no heuristics.
-
----
-
-## Velocity Metrics
-
-`marrow_dashboard` and `marrow_digest` include three measured velocity metrics:
-
-- `attempts_per_success` — avg decisions before an agent lands a success
-- `time_to_success_seconds` — median seconds from `marrow_think` to successful `marrow_commit`
-- `drift_rate` — % of decisions that didn't link to a known pattern
-
-Each reports `{current, previous, delta_pct, direction}` so operators see whether agents are trending toward or away from improvement.
-
-All metrics are computed from real decision data — no estimates, no heuristics.
-
----
-
-## Passive Mode
-
-Running `npx @getmarrow/mcp setup` installs a PostToolUse hook into `.claude/settings.json`. After setup, every tool call your agent makes (Bash, file edits, MCP calls) is auto-logged to Marrow in the background — no agent discipline required.
-
-Disable via: `MARROW_AUTO_HOOK=false`
-
-For troubleshooting hook behavior, set `MARROW_HOOK_DEBUG=true` to re-enable one-line stderr diagnostics.
-
-PostToolUse now marks automatic outcome closure explicitly. Successful tool calls commit success, tool errors commit failure, and `/v1/agent/status` can tell the agent whether the outcome hook is missing. If status is degraded, run `npx @getmarrow/install --yes` or `npx @getmarrow/mcp setup` to repair passive capture.
-
-MCP write paths now keep a bounded in-process retry queue for temporary network/server failures on `think` and `commit`. Auth failures, policy blocks, proof-pack failures, and validation errors are not retried blindly; status returns exact failure reasons and fix commands instead.
-
-**Operator visibility + auto-intelligence tools.**
-
-## Operator Tools
-
-### marrow_dashboard
-
-Operator dashboard in one call. Account health, top failures, workflow status, recent activity, Marrow's saves metric. Now includes velocity metrics (see v3.3.0 section above).
-
-### marrow_digest
-
-Periodic summary with success rate trend vs previous period. Optional `period` parameter (default `7d`). Now includes velocity summary (see v3.3.0 section above).
-
-### marrow_agent_status
-
-Agent-native proof that Marrow is connected and collecting useful signal. Optional `period` and `agentId` parameters; when omitted, the tool filters by `MARROW_AGENT_ID`. Returns `active`, `state`, `signals`, `quality`, `proof`, `failure_reasons`, `agent_warnings`, `diagnostics`, and `next_actions` without exposing raw decision text. Common failure reasons include `missing_key`, `invalid_key`, `wrong_agent_id`, `network_blocked`, and `proof_required`.
-
-### marrow_decision_brief
-
-One pre-action call before meaningful work. Returns `risk`, `workflow`, `handoff`, `freshness`, `quality`, `role_playbook`, `failure_alerts`, `proof_pack`, `source_of_truth`, `fleet_reliability`, and `next_actions`.
-
-Use this before risky work so the agent does not need to stitch together multiple backend calls. It does not replace outcome logging.
-
-### marrow_session_end
-
-Explicitly end a session and optionally auto-commit any open decision. Prevents orphaned decisions.
-
-### marrow_accept_detected
-
-Convert a detected recurring pattern into an enforced workflow. Pattern ID comes from `orient()` response's `suggested_workflows`.
-
-## Intelligence Fields in marrow_think Response
-
-`marrow_think` surfaces three additional fields when the backend provides them:
-- `onboarding_hint` — contextual tip for new accounts
-- `intelligence.collective` — entitlement-gated, k-anonymous aggregate patterns when the tenant contributes sanitized aggregate signals and the minimum-account threshold is met
-- `curated_baseline_guidance` — strong private baseline guidance for private or non-contributing tenants
-- `intelligence.team_context` — recent decisions from other sessions in the same account, so multi-agent teams stay aware of each other's work
-
----
+For most new installations, start with the universal installer instead:
 
-## Available Templates
-
-24 pre-built workflow templates across 8 industries. Browse via `marrow_list_templates` and install with `marrow_install_template`.
-
-- **Insurance (4):** `claims-triage`, `fraud-review`, `underwriting-decision`, `complaint-escalation`
-- **Healthcare (4):** `patient-triage`, `clinical-documentation`, `prior-authorization`, `coding-audit`
-- **E-commerce (3):** `order-fulfillment`, `refund-approval`, `return-processing`
-- **Legal (3):** `contract-review`, `case-triage`, `document-discovery`
-- **SaaS (6):** `code-review-deploy`, `incident-response`, `feature-rollout`, `ticket-triage`, `escalation-flow`, `lead-qualify`
-- **Fintech (2):** `etl-pipeline`, `approval-flow`
-- **Media (1):** `content-publish`
-- **Enterprise (1):** `change-management`
-
-Full catalog with descriptions: [https://getmarrow.ai/docs/#template-marketplace](https://getmarrow.ai/docs/#template-marketplace)
-
-```
-marrow_list_templates({ industry: 'insurance' })
-marrow_install_template({ slug: 'claims-triage' })
+```bash
+npx @getmarrow/install --yes
 ```
 
-## Claude Code Compatibility
+## What's New in v3.9.44
 
-Marrow MCP works natively with Claude Code. The server runs as a long-running process and handles the full MCP protocol correctly.
+v3.9.44 makes the MCP integration an always-on governance lifecycle rather than a prompt reminder:
 
-## One-Command Agent Setup
+- `UserPromptSubmit` obtains relevant before-action guidance without storing raw prompt text;
+- `PostToolUse` records compact success/failure lifecycle receipts;
+- `Stop` keeps unfinished outcomes visible instead of silently treating a session exit as success;
+- transient lifecycle delivery failures use an owner-only, bounded local spool with stable event IDs;
+- `marrow_decision_trace` explains the tenant-scoped path from prior failure and lesson through gate, proof, workflow, and outcome.
 
-Inject Marrow instructions directly into your project's `CLAUDE.md`:
+Existing MCP tools and stable context API names remain compatible. Authentication, policy, proof, and validation failures are surfaced rather than retried as network failures.
 
-```bash
-npx @getmarrow/mcp setup
-```
-
-After setup, your agent uses Marrow automatically every session, and Claude Code PostToolUse hooks auto-log tool calls in the background — no human prompting required.
+## Governed Action Flow
 
-## Auto-Enroll by Default
-The `marrow-always-on` prompt is served to all MCP clients automatically. Set `MARROW_AUTO_ENROLL=false` to opt out.
+Before deploys, merges, publishes, migrations, credential changes, financial operations, or customer-impacting work:
 
-## Security Hardening
-- **Input validation** — all URL path parameters are sanitized to prevent path traversal
-- **SSRF protection** — `MARROW_BASE_URL` must use HTTPS
-- **Crash protection** — malformed JSON on stdin no longer kills the server
-- **Error handling** — proper error logging throughout
-- **HTTP status checking** — API errors return clear messages
+1. Call `marrow_agent_runtime` or `marrow_decision_brief`.
+2. Stop when the returned decision is `block` or `review_required`; otherwise follow its prior lesson and proof contract.
+3. Call `marrow_think` to record intent and obtain the `decision_id` that will be closed.
+4. Perform the action only when its gate allows it.
+5. Call `marrow_commit` with that `decision_id`, the outcome, gate receipt, and required proof.
 
-### Auto-Warn on Orient
-The `marrow_orient` tool now accepts `autoWarn: true` and warns you BEFORE you start a task that recently failed:
+Example pre-action request:
 
 ```json
 {
-  "name": "marrow_orient",
+  "tool": "marrow_agent_runtime",
   "arguments": {
-    "autoWarn": true,
-    "task": "Fix authentication error"
+    "action": "deploy the production worker",
+    "type": "deploy",
+    "role": "deploy",
+    "surfaces": ["repository", "deployment", "production"]
   }
 }
 ```
 
-**Response includes warnings:**
-```
-⚠️ HIGH: This task type failed 4x with approach='retry-without-fix'.
-         Try approach='apply-patch-first' (89% success rate)
-```
-
-### Loop Detection on Think
-The `marrow_think` tool now accepts `checkLoop: true` and detects if you're about to retry a failed approach:
+Example closeout:
 
 ```json
 {
-  "name": "marrow_think",
+  "tool": "marrow_think",
   "arguments": {
-    "action": "Retry auth with method='internal'",
+    "action": "deploy the production worker",
+    "type": "process",
     "checkLoop": true
   }
 }
 ```
 
-**Response includes loop warnings:**
-```
-🚨 LOOP DETECTED: You're retrying a failed approach.
-   Previous failure: 'retry-without-fix' approach not supported.
-   Suggested: Use 'apply-patch-first' approach instead.
-```
-
-### Rate Limiting
-- `marrow_orient`: 30 requests/minute per account
-- `marrow_think`: 60 requests/minute per account
-- Automatic 429 responses when limit exceeded
-
-### Enhanced PII Protection
-- Automatic stripping of emails, phone numbers, API keys from all responses
-- Applied to `recentLessons`, `warnings`, and `outcome` fields
-- Deep object stripping for complex data structures
-
----
-
-## The Problem
-
-Most agents still operate with shallow governance.
-
-They might keep a short context window, maybe write a note or two, then lose the important part:
-- what they were trying to do
-- what they actually did
-- whether it worked
-- what pattern that should teach the next run
-
-That creates a familiar failure loop:
-- the same mistakes repeat
-- work gets marked done without structured outcome proof
-- agents drift between sessions
-- hosts have no clean way to inspect whether the work loop is actually closed
-
-**Marrow fixes this.**
-
-Through MCP, your agent can:
-- orient at session start
-- log intent before meaningful action
-- inspect loop state before handoff or completion
-- commit outcomes back to Marrow with proof cleanly
-
----
-
-## How It Works
-
-Marrow exposes a simple operating loop through MCP:
-
-```text
-orient -> think -> act -> check -> commit
-```
-
-That gives agents an actual governance discipline:
-- **orient** → pick up recent lessons and current loop state
-- **think** → log intent and receive decision intelligence
-- **act** → perform the meaningful work
-- **check** → inspect whether the loop is still open or missing something
-- **commit** → log the outcome and close the loop
-
-The value compounds with use. Each decision your agent logs makes the fleet safer — failure rates drop, patterns emerge, proof requirements get clearer, and the next session starts with real intelligence instead of a blank slate. Teams running multiple agents see this compound fastest, but even a single agent builds meaningful history within a few sessions.
-
----
-
-## Install
-
-Default path for new users:
-
-```bash
-npx @getmarrow/install --yes
-```
-
-Manual MCP path for MCP-native clients:
-
-### Quick Start (Claude Code)
-
-```bash
-# 1. Add the MCP server
-claude mcp add marrow -e MARROW_API_KEY="$MARROW_API_KEY" -- npx @getmarrow/mcp
-
-# 2. Set up auto-enrollment (agent uses Marrow automatically)
-npx @getmarrow/mcp setup
-```
-
-That's it. Your agent will use Marrow automatically in every session.
-
-### Manual Setup
-
-Run it directly with `npx`:
-
-```bash
-MARROW_API_KEY="$MARROW_API_KEY" npx @getmarrow/mcp
-```
-
-Or register it in your MCP client config using environment variables or your client's secret storage. Avoid putting API keys in command arguments or static config files.
-
----
-
-## MCP Tools
-
-### Core Loop Tools
-
-#### `marrow_orient`
-**Call this first** at session start. Returns failure warnings from your history so you avoid known mistakes immediately.
-
-#### `marrow_think`
-Log intent before meaningful action. Returns pattern insights, similar past decisions, and a recommended next step.
-
-#### `marrow_commit`
-Log the outcome after acting. Closes the decision loop. Can include `model_usage` so Marrow returns token-value proof after work completes.
-
-#### `marrow_model_usage`
-Record compact model token/cost/latency counts when your harness exposes them. This powers token savings proof in `/v1/agent/value/proof` and owner reports.
-
-#### `marrow_run`
-Zero-ceremony wrapper. Handles orient → think → commit in a single call.
-
-#### `marrow_auto`
-Fire-and-forget logging. Pass what you're about to do (and optionally the outcome). Marrow handles everything in the background.
-
-### Memory Management Tools
-
-#### `marrow_list_memories`
-List memories with optional filters:
-- `status` — Filter by status (active, outdated, deleted)
-- `query` — Search query
-- `limit` — Max results
-- `agentId` — Include memories shared with this agent
-
-#### `marrow_get_memory`
-Get a single memory by ID.
-
-#### `marrow_update_memory`
-Update memory text, tags, or metadata.
-
-#### `marrow_delete_memory`
-Soft delete a memory.
-
-#### `marrow_mark_outdated`
-Mark a memory as outdated.
-
-#### `marrow_supersede_memory`
-Atomically replace a memory with a new version.
-
-#### `marrow_share_memory`
-Share a memory with specific agents.
-
-#### `marrow_export_memories`
-Export memories to JSON or CSV format.
-
-#### `marrow_import_memories`
-Import memories with merge (dedup) or replace mode.
-
-#### `marrow_retrieve_memories`
-Full-text search with filters:
-- `query` — Search query (required)
-- `limit` — Max results
-- `from` / `to` — Date range (ISO-8601)
-- `tags` — Comma-separated tags
-- `source` — Source filter
-- `status` — Status filter
-- `shared` — Include shared memories
-
-### Query Tools
-
-#### `marrow_ask`
-Query the collective hive in plain English. Ask about failure patterns, what worked, what broke, or get a recommendation.
-
-#### `marrow_status`
-Check Marrow platform health and status.
-
----
-
-## Claude Code Config
-
-```bash
-claude mcp add marrow -e MARROW_API_KEY="$MARROW_API_KEY" -- npx @getmarrow/mcp
-```
-
-## Claude Desktop Config
-
 ```json
 {
-  "mcpServers": {
-    "marrow": {
-      "command": "npx",
-      "args": ["@getmarrow/mcp"],
-      "env": {
-        "MARROW_API_KEY": "${MARROW_API_KEY}"
-      }
+  "tool": "marrow_commit",
+  "arguments": {
+    "decision_id": "decision_id returned by marrow_think",
+    "gate_receipt_id": "receipt id returned by marrow_agent_runtime",
+    "success": true,
+    "outcome": "Production deploy succeeded and smoke checks passed.",
+    "proof": {
+      "checks": ["tests passed", "secret scan passed", "production smoke passed"],
+      "rollback_target": "previous release"
     }
   }
 }
 ```
 
----
+High-risk work can be allowed, warned, held for review, or blocked according to account policy. Low-risk work can use passive guidance and bounded cached state where the runtime contract permits it.
 
-## Environment Variables
+## Passive Use
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `MARROW_API_KEY` | Yes | Your API key from getmarrow.ai. Prefer environment variables or client secret storage. MCP also auto-loads `.marrow/env`, `.marrow/env.local`, `.env`, `.env.local`, `~/.marrow/env`, and `~/.marrow/env.local`. |
-| `MARROW_KEY` | No | Alias accepted by MCP for fleet runners and secret managers. |
-| `MARROW_BASE_URL` | No | Custom API URL (default: `https://api.getmarrow.ai`). Must use HTTPS. |
-| `MARROW_SESSION_ID` | No | Session identifier for multi-agent setups |
-| `MARROW_FLEET_AGENT_ID` | No | Agent identifier sent as `X-Marrow-Agent-Id` for fleet attribution |
-| `MARROW_CLIENT` / `MARROW_HARNESS` / `MARROW_AGENT_CLIENT` | No | Harness/client label used for per-client reporting, such as `codex`, `claude-code`, `cursor`, `gemini`, `qwen`, `opencode`, or `custom` |
-| `MARROW_AUTO_ENROLL` | No | Auto-enrollment prompt (default: `true`). Set to `false` to disable. |
-| `MARROW_AUTO_HOOK` | No | PostToolUse auto-logging kill switch. Set to `false` to disable the hook without editing settings. |
-| `MARROW_PASSIVE_BRIEF` | No | Passive decision-brief mode for the prompt hook. Defaults to `auto`; set `false` to disable or `always` to brief every prompt. |
-| `MARROW_HOOK_DEBUG` | No | When set to `true`, write-side and prompt-context hooks emit one-line stderr diagnostics. |
-| `MARROW_CONTEXT_HOOK_DEBUG` | No | When set to `true`, only the UserPromptSubmit context hook emits one-line stderr diagnostics. |
+`npx @getmarrow/mcp setup` installs supported prompt, tool-result, and session-stop hooks so the agent can receive before-action context, record meaningful tool outcomes, and keep unfinished closure visible without the owner repeatedly prompting it to use Marrow.
 
-If hooks are installed but no decisions are being logged, run:
+The hooks send compact classifications and lifecycle receipts. They do not need raw prompts, completions, command output, tool output, or credentials. A completed tool or session does not automatically become a successful business outcome; explicit success/failure closure is required.
 
-```bash
-npx @getmarrow/install doctor
-```
+Check the installed runtime:
 
-Deep doctor with harmless write/outcome verification:
-
-```bash
-MARROW_API_KEY=<your_marrow_key> npx @getmarrow/install doctor --self-test
+```text
+marrow_agent_status
 ```
 
-Healthy output should confirm `key valid: yes`, `account active: yes`, `agent identity accepted: yes`, `write test event: passed`, and `outcome closed: passed`. If it fails, Marrow returns the exact reason and fix command.
+Status diagnostics distinguish missing keys, invalid keys, wrong bound-agent identity, network limits, missing hooks, and incomplete proof. They include an exact repair action without exposing secrets.
 
-Stable project-local key file:
+## Primary MCP Tools
 
-```bash
-mkdir -p .marrow
-printf "MARROW_API_KEY=<your_marrow_key>\\n" > .marrow/env
-chmod 600 .marrow/env
-npx @getmarrow/mcp setup
-```
+| Tool | Purpose |
+| --- | --- |
+| `marrow_agent_runtime` | One-call pre-action status, policy gate, relevant lessons, proof requirements, and exact next action |
+| `marrow_decision_brief` | Compact operating brief for meaningful work |
+| `marrow_think` | Record intent and retrieve relevant governance intelligence |
+| `marrow_commit` | Close an action with outcome, receipt, and proof |
+| `marrow_workflow_gate` | Evaluate a workflow action against policy |
+| `marrow_completion_contracts` | List proof contracts for consequential action types |
+| `marrow_evaluate_completion_contract` | Check whether evidence is sufficient to call work complete |
+| `marrow_agent_status` | Verify capture, identity, outcome coverage, and hook health |
+| `marrow_value_report` | Return account/agent value evidence without requiring a dashboard |
+| `marrow_buyer_proof` | Return owner-ready governance and reliability evidence |
+| `marrow_governance_timeline` | Inspect decisions, gates, proof packs, and outcomes over time |
+| `marrow_decision_trace` | Explain the tenant-scoped causal path behind one governed decision |
+| `marrow_fleet_lessons` | Retrieve proven lessons authorized for the current account or agent |
+| `marrow_model_usage` | Record compact token, cost, and latency counts when the harness exposes them |
 
----
+The package also exposes key management, fleet handoff, deployment history, adaptive policy, context/lesson, query, and workflow-example tools. See the [complete source-of-truth documentation](https://getmarrow.ai/docs/) for every tool and field.
 
-## The Always-On Prompt
+## Context and Workflow Examples
 
-Marrow includes a built-in prompt called `marrow-always-on` that instructs agents to use Marrow automatically. It's served by default — no configuration needed.
+The stable `marrow_*memory*` tools manage authorized context and prior lessons used by governance decisions. They are advanced supporting APIs, not a separate product category.
 
-**To use:** In your MCP client, request the `marrow-always-on` prompt and include it in your system instructions. For Claude Code, run `npx @getmarrow/mcp setup` instead — it handles this automatically.
+The template tools expose 24 configurable workflow examples. They are starting points for policy design, not customer case studies, regulatory validation, legal advice, or proof of production use in each listed industry.
 
----
+## Trust and Data Boundaries
+
+- Private account, fleet, workflow, proof, and agent data remains tenant-scoped by default.
+- Agent-bound keys can be restricted to an allowed identity and permission set.
+- Sanitized aggregate contribution is optional and never means sharing raw prompts, code, secrets, proof packs, account identifiers, agent identifiers, or customer identities.
+- Existing API keys are never returned after creation; key material should be supplied through the client's secret store.
+- Marrow returns guidance and policy data. Agents must not execute returned text as shell input.
 
-## Why This Matters
+See the [Trust Center](https://getmarrow.ai/trust/) for implemented controls, current limits, and roadmap status.
 
-Without Marrow:
-- Agents repeat the same failures session after session
-- Successful patterns get lost when the context window clears
-- There's no structured trail of what was tried and what worked
-- Every new session starts from zero
+## Environment
 
-With Marrow:
-- Failure patterns surface before you repeat them
-- Successful outcomes compound across sessions
-- Every decision has a trail: intent → action → outcome
-- The hive gets smarter with every logged decision
+| Variable | Required | Purpose |
+| --- | --- | --- |
+| `MARROW_API_KEY` | Yes | Account or agent-bound API key |
+| `MARROW_BASE_URL` | No | API base override |
+| `MARROW_AGENT_ID` | No | Bound agent identity for MCP tools |
+| `MARROW_FLEET_AGENT_ID` | No | Fleet agent identity used by passive setup |
 
-**Marrow tells you what went wrong last time before you do it again.**
+## Documentation
 
----
+- [Source-of-truth docs](https://getmarrow.ai/docs/)
+- [Trust Center](https://getmarrow.ai/trust/)
+- [Status](https://getmarrow.ai/status/)
+- [GitHub](https://github.com/getmarrow/marrow-mcp)
 
 ## License
 
 MIT
 
----
-
 ## Related Packages
 
-- **[@getmarrow/install](https://www.npmjs.com/package/@getmarrow/install)** — Default front door for new users. Detects local agent/runtime surfaces, writes safe config, runs self-tests, and reports first-value proof.
-- **[@getmarrow/sdk](https://www.npmjs.com/package/@getmarrow/sdk)** — TypeScript/Node.js SDK for programmatic access to Marrow. Use this for custom agent integrations outside of MCP.
-
-**📖 Full API reference with all endpoints:** [https://getmarrow.ai/docs/#api-reference](https://getmarrow.ai/docs/#api-reference)
+- [@getmarrow/install](https://www.npmjs.com/package/@getmarrow/install) - default installer, self-test, governed runner, and operator TUI
+- [@getmarrow/sdk](https://www.npmjs.com/package/@getmarrow/sdk) - Node.js and TypeScript integration for owned agent runtimes