meguro-mcp 0.2.8 → 0.2.10

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to `meguro-mcp` are recorded here. Versions follow Semantic Versioning.
 
+## 0.2.10 — 2026-08-10
+
+- Adds immutable getting-started v8, product-guide v5, and documentation-index v4 resources that
+  cross-link current guidance from one registry-derived currency authority; receipt-guide v7 remains
+  the current receipt guide.
+- Removes the remaining fixed Admin API version from current observation-plan metadata and derives
+  the declared target from the supported-version registry without changing historical resources.
+- Adds current troubleshooting for incompatible model data, assertion-family exercise guidance, and
+  the channel-abstraction explanation while preserving existing tool identities and input schemas.
+
+## 0.2.9 — 2026-08-10
+
+- Keeps the full real-store history-run family in the public STDIO registry while the hosted OAuth
+  surface now teaches and exposes only the practice-world run lane.
+- Adds immutable getting-started v7, product-guide v4, and documentation-index v2 resources with
+  hosted-first control-plane guidance, Gate-policy v2 citations, and one honest STDIO history-lane
+  bridge.
+- Reconciles `usage_read` with the exempt auto-provisioned sample store shown by `stores_list`, while
+  preserving every existing tool name, input schema, and prior documentation byte stream.
+
 ## 0.2.8 — 2026-08-09
 
 - Adds `practice_runs_list` so a cold MCP-only evaluator can discover existing practice attempts

package/README.md

@@ -105,15 +105,21 @@ local stdio server and the hosted OAuth resource server:
 |---|---|
 | `meguro://docs/gate-policy/v1` | `6d647b3c78fd4e2d93f59a85b90a853096cc73e9cdfd6ba5e3ea505dc07b4aaf` |
 | `meguro://docs/gate-policy/v2` | `e49378fd745f71aab893db34864aefeb7345c9a25000ad328dfba4e44d007469` |
+| `meguro://docs/gate-policy/v3` | `bcd1434cddf99f42261081d9d217285ebf4a93d9e42d23a47bf577c8ee91fbe9` |
 | `meguro://docs/getting-started/v1` | `afd19ca6576ae2a8fb03c2e143d25d47fb739682f44180541dd13f779a5f29df` |
 | `meguro://docs/getting-started/v2` | `70fdbf36d68a6dd7abb93fe9b403f85c9c0323b3dc3472ab638c6cbe5982ec61` |
 | `meguro://docs/getting-started/v3` | `765cba2b68806f0b1d83255a1742d83ce71ebf7f65f8095e7076cd36e4a1ba6c` |
 | `meguro://docs/getting-started/v4` | `db534eb544e414be353d6cd4db8dfb9e8dba772dcb10d8287a1a27f8736e5307` |
 | `meguro://docs/getting-started/v5` | `156dcf81266f2bd4e4203dbd09661e49a481395ba4a63528f0540d8ea89bc285` |
 | `meguro://docs/getting-started/v6` | `34cf3ab48a32714b0c3edb24a7920843954172c0d5501e60574adc5a1058071f` |
+| `meguro://docs/getting-started/v7` | `650201c983138cb2c34cfef3e93611d510faf42d974f32762207216c3189ece1` |
+| `meguro://docs/index/v1` | `1d52205148a3438339238c9e65271b2c377cd0a96c7088d75de7f2dce9552843` |
+| `meguro://docs/index/v2` | `df861c87fa17db23d3173c1d900a884d39b228d493d7e35fcab9b2a531ae9aad` |
+| `meguro://docs/index/v3` | `422e91488281867aa2454223a8042248a667c57ea2ae56878bdb136693fe4894` |
 | `meguro://docs/product-guide/v1` | `e5450c1b4181cec4d6ed0a498dbff1cb25d2e223ff2228928aecbbce9674f074` |
 | `meguro://docs/product-guide/v2` | `b15590df7699f7ad685a30b0698e2c25b5b7b1531afa4e43e9f04a4b38ab9db2` |
 | `meguro://docs/product-guide/v3` | `8dc9e0fae91a2433ea7ca02b9278484250be0d336e2daac96f949da577487dc9` |
+| `meguro://docs/product-guide/v4` | `a874a1af1bcf18e7abe6b32b8d226a648b1292458010992528a551c270e9816e` |
 | `meguro://docs/receipt-guide/v1` | `9d8150258765d252cb7cc3bad307acdc429b0435ca22f0362b69cf7471e3a333` |
 | `meguro://docs/receipt-guide/v2` | `7df261021b48ce732e6043a8917f8a2673b1f83ff1d8790927abc18f34fb3f6f` |
 | `meguro://docs/receipt-guide/v3` | `c76b823aed8187834c8ae79a751b53d2720fe7245a31b0b195f440deac9b75cb` |
@@ -182,11 +188,11 @@ See [the agency quickstart](../../docs/agency-practice-run-quickstart.md) and [H
 ## Advanced: CI or local STDIO
 
 Use the public STDIO package for CI, local automation, or clients without hosted Streamable HTTP and
-OAuth support. It requires a workspace-bound `meg_sk_…` API key and exposes the full 46-tool local
+OAuth support. It requires a workspace-bound `meg_sk_…` API key and exposes the full 47-tool local
 surface. Pin the exact public version in client configuration so a quickstart stays reproducible:
 
 ```bash
-npx -y meguro-mcp@0.2.8
+npx -y meguro-mcp@0.2.10
 ```
 
 ### Environment
@@ -204,7 +210,7 @@ claude mcp add meguro \
   -e MEGURO_API_BASE_URL=https://api-dev.meguro.io \
   -e MEGURO_API_TOKEN=meg_sk_... \
   -e MEGURO_DASHBOARD_URL=https://... \
-  -- npx -y meguro-mcp@0.2.8
+  -- npx -y meguro-mcp@0.2.10
 ```
 
 ### Register — Cursor (`.cursor/mcp.json`)
@@ -214,7 +220,7 @@ claude mcp add meguro \
   "mcpServers": {
     "meguro": {
       "command": "npx",
-      "args": ["-y", "meguro-mcp@0.2.8"],
+      "args": ["-y", "meguro-mcp@0.2.10"],
       "env": {
         "MEGURO_API_BASE_URL": "https://api-dev.meguro.io",
         "MEGURO_API_TOKEN": "meg_sk_...",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "meguro-mcp",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "private": false,
   "type": "module",
   "description": "Meguro control-plane MCP server: drive worlds, runs, and verdicts from your own AI tools.",

package/src/docs.mjs

@@ -14,15 +14,20 @@ const RECEIPT_GUIDE_V6_VERSION = 6;
 const RECEIPT_GUIDE_V7_VERSION = 7;
 const GATE_POLICY_VERSION = 1;
 const GATE_POLICY_V2_VERSION = 2;
+const GATE_POLICY_V3_VERSION = 3;
 const GETTING_STARTED_VERSION = 1;
 const GETTING_STARTED_V2_VERSION = 2;
 const GETTING_STARTED_LATEST_VERSION = 3;
 const GETTING_STARTED_V4_VERSION = 4;
 const GETTING_STARTED_V5_VERSION = 5;
 const GETTING_STARTED_V6_VERSION = 6;
+const GETTING_STARTED_V7_VERSION = 7;
+const GETTING_STARTED_V8_VERSION = 8;
 const PRODUCT_GUIDE_VERSION = 1;
 const PRODUCT_GUIDE_V2_VERSION = 2;
 const PRODUCT_GUIDE_V3_VERSION = 3;
+const PRODUCT_GUIDE_V4_VERSION = 4;
+const PRODUCT_GUIDE_V5_VERSION = 5;
 const RECEIPT_GUIDE_URI = `meguro://docs/receipt-guide/v${RECEIPT_GUIDE_VERSION}`;
 const RECEIPT_GUIDE_V2_URI = `meguro://docs/receipt-guide/v${RECEIPT_GUIDE_V2_VERSION}`;
 const RECEIPT_GUIDE_V3_URI = `meguro://docs/receipt-guide/v${RECEIPT_GUIDE_V3_VERSION}`;
@@ -32,16 +37,24 @@ const RECEIPT_GUIDE_V6_URI = `meguro://docs/receipt-guide/v${RECEIPT_GUIDE_V6_VE
 const RECEIPT_GUIDE_V7_URI = `meguro://docs/receipt-guide/v${RECEIPT_GUIDE_V7_VERSION}`;
 const GATE_POLICY_URI = `meguro://docs/gate-policy/v${GATE_POLICY_VERSION}`;
 const GATE_POLICY_V2_URI = `meguro://docs/gate-policy/v${GATE_POLICY_V2_VERSION}`;
+const GATE_POLICY_V3_URI = `meguro://docs/gate-policy/v${GATE_POLICY_V3_VERSION}`;
 const GETTING_STARTED_URI = `meguro://docs/getting-started/v${GETTING_STARTED_VERSION}`;
 const GETTING_STARTED_V2_URI = `meguro://docs/getting-started/v${GETTING_STARTED_V2_VERSION}`;
 const GETTING_STARTED_LATEST_URI = `meguro://docs/getting-started/v${GETTING_STARTED_LATEST_VERSION}`;
 const GETTING_STARTED_V4_URI = `meguro://docs/getting-started/v${GETTING_STARTED_V4_VERSION}`;
 const GETTING_STARTED_V5_URI = `meguro://docs/getting-started/v${GETTING_STARTED_V5_VERSION}`;
 const GETTING_STARTED_V6_URI = `meguro://docs/getting-started/v${GETTING_STARTED_V6_VERSION}`;
+const GETTING_STARTED_V7_URI = `meguro://docs/getting-started/v${GETTING_STARTED_V7_VERSION}`;
+const GETTING_STARTED_V8_URI = `meguro://docs/getting-started/v${GETTING_STARTED_V8_VERSION}`;
 const PRODUCT_GUIDE_URI = `meguro://docs/product-guide/v${PRODUCT_GUIDE_VERSION}`;
 const PRODUCT_GUIDE_V2_URI = `meguro://docs/product-guide/v${PRODUCT_GUIDE_V2_VERSION}`;
 const PRODUCT_GUIDE_V3_URI = `meguro://docs/product-guide/v${PRODUCT_GUIDE_V3_VERSION}`;
+const PRODUCT_GUIDE_V4_URI = `meguro://docs/product-guide/v${PRODUCT_GUIDE_V4_VERSION}`;
+const PRODUCT_GUIDE_V5_URI = `meguro://docs/product-guide/v${PRODUCT_GUIDE_V5_VERSION}`;
 export const DOCUMENTATION_INDEX_URI = 'meguro://docs/index/v1';
+export const DOCUMENTATION_INDEX_V2_URI = 'meguro://docs/index/v2';
+export const DOCUMENTATION_INDEX_V3_URI = 'meguro://docs/index/v3';
+export const DOCUMENTATION_INDEX_V4_URI = 'meguro://docs/index/v4';
 
 const DOCUMENTATION_CURRENCY_V1 = deepFreeze({
   indexVersion: 1,
@@ -53,7 +66,37 @@ const DOCUMENTATION_CURRENCY_V1 = deepFreeze({
     'receipt-guide': RECEIPT_GUIDE_V7_URI,
   },
 });
-const CURRENT_DOCUMENTATION_CURRENCY = DOCUMENTATION_CURRENCY_V1;
+const DOCUMENTATION_CURRENCY_V2 = deepFreeze({
+  indexVersion: 2,
+  currentUriByTopic: {
+    'gate-policy': GATE_POLICY_V2_URI,
+    'getting-started': GETTING_STARTED_V7_URI,
+    index: DOCUMENTATION_INDEX_V2_URI,
+    'product-guide': PRODUCT_GUIDE_V4_URI,
+    'receipt-guide': RECEIPT_GUIDE_V7_URI,
+  },
+});
+const DOCUMENTATION_CURRENCY_V3 = deepFreeze({
+  indexVersion: 3,
+  currentUriByTopic: {
+    'gate-policy': GATE_POLICY_V3_URI,
+    'getting-started': GETTING_STARTED_V7_URI,
+    index: DOCUMENTATION_INDEX_V3_URI,
+    'product-guide': PRODUCT_GUIDE_V4_URI,
+    'receipt-guide': RECEIPT_GUIDE_V7_URI,
+  },
+});
+const DOCUMENTATION_CURRENCY_V4 = deepFreeze({
+  indexVersion: 4,
+  currentUriByTopic: {
+    'gate-policy': GATE_POLICY_V3_URI,
+    'getting-started': GETTING_STARTED_V8_URI,
+    index: DOCUMENTATION_INDEX_V4_URI,
+    'product-guide': PRODUCT_GUIDE_V5_URI,
+    'receipt-guide': RECEIPT_GUIDE_V7_URI,
+  },
+});
+const CURRENT_DOCUMENTATION_CURRENCY = DOCUMENTATION_CURRENCY_V4;
 
 function documentationVersionFromUri(uri) {
   const match = /\/v([1-9][0-9]*)$/u.exec(uri);
@@ -61,12 +104,12 @@ function documentationVersionFromUri(uri) {
   return Number(match[1]);
 }
 
-function documentationIndexText(currency) {
+function documentationIndexText(currency, publishedUri = DOCUMENTATION_INDEX_URI) {
   const rows = Object.entries(currency.currentUriByTopic).sort(([left], [right]) => codepointCompare(left, right));
   return [
     `# Meguro documentation index v${currency.indexVersion}`,
     '',
-    `Published URI: \`${DOCUMENTATION_INDEX_URI}\``,
+    `Published URI: \`${publishedUri}\``,
     '',
     'This immutable index records the current published version of every documentation family at issuance.',
     'Use the `meguro/status` annotations from `resources/list` for live currency; cited versioned resources never change.',
@@ -79,7 +122,10 @@ function documentationIndexText(currency) {
 
 const CURRENT_GETTING_STARTED_URI = CURRENT_DOCUMENTATION_CURRENCY.currentUriByTopic['getting-started'];
 const CURRENT_PRODUCT_GUIDE_URI = CURRENT_DOCUMENTATION_CURRENCY.currentUriByTopic['product-guide'];
-export const MCP_INITIALIZE_INSTRUCTIONS = `Start with \`${CURRENT_GETTING_STARTED_URI}\` or call \`docs_read({ topic: "getting-started", version: ${documentationVersionFromUri(CURRENT_GETTING_STARTED_URI)} })\`; for general Meguro questions, read \`${CURRENT_PRODUCT_GUIDE_URI}\` or call \`docs_read({ topic: "product-guide", version: ${documentationVersionFromUri(CURRENT_PRODUCT_GUIDE_URI)} })\`.`;
+const CURRENT_RECEIPT_GUIDE_URI = CURRENT_DOCUMENTATION_CURRENCY.currentUriByTopic['receipt-guide'];
+const CURRENT_GATE_POLICY_URI = CURRENT_DOCUMENTATION_CURRENCY.currentUriByTopic['gate-policy'];
+const CURRENT_INDEX_URI = CURRENT_DOCUMENTATION_CURRENCY.currentUriByTopic.index;
+export const MCP_INITIALIZE_INSTRUCTIONS = `Start with \`${CURRENT_GETTING_STARTED_URI}\` or call \`docs_read({ topic: "getting-started", version: ${documentationVersionFromUri(CURRENT_GETTING_STARTED_URI)} })\`; for general Meguro questions, read \`${CURRENT_PRODUCT_GUIDE_URI}\` or call \`docs_read({ topic: "product-guide", version: ${documentationVersionFromUri(CURRENT_PRODUCT_GUIDE_URI)} })\`; distinguish the documentation resource version in each \`meguro://docs/.../vN\` URI, the runtime Gate policy contract \`meguro.release-gate-policy.v1\` version 1, and the requested Shopify Admin API version from ${ADMIN_API_SUPPORTED_VERSIONS.map((version) => `\`${version}\``).join(' or ')} with default \`${ADMIN_API_DEFAULT_VERSION}\`.`;
 export const PRODUCT_GUIDE_SHA256 = 'e5450c1b4181cec4d6ed0a498dbff1cb25d2e223ff2228928aecbbce9674f074';
 
 function deepFreeze(value) {
@@ -913,6 +959,23 @@ export const GATE_POLICY_V1_CHECKS = deepFreeze([
   },
 ]);
 
+function absoluteGateVerdictFactPath(path) {
+  return `facts.${path}`;
+}
+
+function absoluteGateVerdictFactText(text) {
+  return String(text)
+    .replaceAll('catalogSourceSummary.', 'facts.catalogSourceSummary.')
+    .replaceAll('summary.', 'facts.summary.');
+}
+
+export const GATE_POLICY_V3_CHECKS = deepFreeze(GATE_POLICY_V1_CHECKS.map((check) => ({
+  ...check,
+  facts: check.facts.map(absoluteGateVerdictFactPath),
+  threshold: absoluteGateVerdictFactText(check.threshold),
+  flip: absoluteGateVerdictFactText(check.flip),
+})));
+
 const GATE_POLICY_TEXT = `# Meguro Gate policy v1
 
 Published URI: \`${GATE_POLICY_URI}\`
@@ -1248,6 +1311,118 @@ a plan, consent for the human, or reveal a credential that the human has not gra
 ## Question-to-source routing`,
   )
   .replace('Read \`meguro://docs/getting-started/v1\`.', `Read \`${GETTING_STARTED_V6_URI}\`.`);
+const REAL_STORE_HISTORY_LANE_BRIDGE = 'Meguro\'s separate real-store history lane still exists in the public STDIO distribution for internal and CI use; hosted OAuth MCP does not expose or teach that lane.';
+const GETTING_STARTED_V7_TEXT = GETTING_STARTED_V6_TEXT
+  .replace('# Getting started with Meguro v6', '# Getting started with Meguro v7')
+  .replace(`Published URI: \`${GETTING_STARTED_V6_URI}\``, `Published URI: \`${GETTING_STARTED_V7_URI}\``)
+  .replaceAll('meguro://docs/gate-policy/v1', 'meguro://docs/gate-policy/v2')
+  .replace(
+    `The local \`meguro-mcp\` server is the Meguro control plane: it discovers stores and drives run
+lifecycle. The practice store's returned Shopify-shaped Admin endpoint is the data plane used by the
+commerce agent under evaluation. A practice store's storefront MCP endpoint is neither of those and
+cannot replace the local control plane or the Shopify-shaped Admin endpoint.`,
+    `Hosted OAuth MCP is the recommended control plane for interactive agents. The public STDIO
+distribution is the CI and internal fallback. The practice store's returned Shopify-shaped Admin
+endpoint is the data plane used by the commerce agent under evaluation; its storefront MCP endpoint
+is neither control plane nor a substitute for the Shopify-shaped Admin endpoint.
+
+${REAL_STORE_HISTORY_LANE_BRIDGE}`,
+  );
+const PRODUCT_GUIDE_V4_TEXT = PRODUCT_GUIDE_V3_TEXT
+  .replace('# Meguro product guide v3', '# Meguro product guide v4')
+  .replace(`Published URI: \`${PRODUCT_GUIDE_V3_URI}\``, `Published URI: \`${PRODUCT_GUIDE_V4_URI}\``)
+  .replaceAll('meguro://docs/gate-policy/v1', 'meguro://docs/gate-policy/v2')
+  .replace(`Read \`${GETTING_STARTED_V6_URI}\`.`, `Read \`${GETTING_STARTED_V7_URI}\`.`)
+  .replace(
+    '- **Public STDIO MCP** is the local and CI fallback.',
+    `- **Public STDIO MCP** is the CI and internal fallback.
+
+${REAL_STORE_HISTORY_LANE_BRIDGE}`,
+  )
+  .replace(
+    '| What runs exist or what happened? | Call \`runs_list\` and the relevant status, report, or impact tool. |',
+    '| What practice runs exist or what happened? | Call \`practice_runs_list\` and the relevant \`practice_run_status\`, \`practice_run_report\`, or \`practice_run_impact\` tool. |',
+  );
+const CURRENT_VERSION_LABELS_TEXT = `## Three different version labels
+
+- **Documentation resource version:** the trailing \`vN\` in an immutable \`meguro://docs/.../vN\`
+  URI identifies that document's bytes. Read \`${CURRENT_INDEX_URI}\` for the current resource URI in
+  every documentation family.
+- **Runtime Gate policy contract version:** \`meguro.release-gate-policy.v1\`, version \`1\`, identifies
+  the policy evaluated against receipt facts. The current explanatory documentation for that contract
+  is \`${CURRENT_GATE_POLICY_URI}\`; its documentation resource version is a separate number.
+- **Requested Shopify Admin API version:** the version segment in an Admin request selects one of
+  ${ADMIN_API_SUPPORTED_VERSIONS.map((version) => `\`${version}\``).join(' or ')}. The current default is
+  \`${ADMIN_API_DEFAULT_VERSION}\`; a caller may still request a supported non-default version, and the
+  resulting plan and evidence retain that requested value.`;
+const CURRENT_DEEPER_DOCUMENTATION_TEXT = `## Deeper in-band documentation
+
+- Receipt interpretation: read \`${CURRENT_RECEIPT_GUIDE_URI}\` or call
+  \`docs_read({ topic: "receipt-guide", version: ${documentationVersionFromUri(CURRENT_RECEIPT_GUIDE_URI)} })\`.
+- Gate policy: read \`${CURRENT_GATE_POLICY_URI}\` or call
+  \`docs_read({ topic: "gate-policy", version: ${documentationVersionFromUri(CURRENT_GATE_POLICY_URI)} })\`.
+- Current-document pointers: read \`${CURRENT_INDEX_URI}\` or call
+  \`docs_read({ topic: "index", version: ${documentationVersionFromUri(CURRENT_INDEX_URI)} })\`.
+
+All published documentation resources are immutable. Cite the exact URI, version, and SHA-256
+digest returned by Meguro.`;
+const GETTING_STARTED_V7_DEEPER_DOCUMENTATION_TEXT = `## Deeper in-band documentation
+
+- Receipt interpretation: read \`${RECEIPT_GUIDE_URI}\` or
+  \`${RECEIPT_GUIDE_V2_URI}\`, or call
+  \`docs_read({ topic: "receipt-guide", version: 1 })\` or
+  \`docs_read({ topic: "receipt-guide", version: 2 })\`.
+- Gate policy: read \`${GATE_POLICY_V2_URI}\`, or call
+  \`docs_read({ topic: "gate-policy", version: 1 })\`.
+
+All published documentation resources are immutable. Cite the exact URI, version, and SHA-256
+digest returned by Meguro.`;
+const CIMD_TROUBLESHOOTING_TEXT = `## Claude Code authentication troubleshooting
+
+If Claude Code reports Authenticated but calls return \`401 invalid_token\`, remove the stored Meguro
+server entry and re-add it; the CLI can retain an expired token across logout/login.`;
+const ASSERTION_FAMILY_EXERCISE_TEXT = `## How to exercise each assertion family
+
+- **Receipt:** complete a run after the agent sends at least one Admin call, then read the immutable
+  receipt. This exercises receipt construction and attribution; an empty or incomplete run does not.
+- **State safety:** during an open run, issue the representative supported state-changing action and
+  any intended refusal case, then inspect the recorded accepted/rejected action and resulting store
+  state. A read-only run cannot establish this family.
+- **Backoff:** use genuinely provoked throttling, for example with cost-heavy queries that drain the
+  configured GraphQL bucket, observe the throttled response, wait as directed, and send the matching
+  retry. Ordinary successful traffic does not exercise retry recovery or throttle discipline.
+- **Webhook:** this family is not available in this run mode on the current hosted practice lane:
+  the lane has no supported webhook-subscription registration or delivery endpoint. That is a lane limitation,
+  never an agent omission. This documentation adds no webhook capability.`;
+const CHANNEL_ABSTRACTION_TEXT = `## Effect-level channel abstraction
+
+Messaging and fulfillment channels are represented as effect-level practice actions. For example,
+cart-recovery's supported write is **Recover abandoned checkout**, while generic email/SMS sending is
+\`knownUnsupported\`. The practice world grades the decision's effect, not the delivery channel; a
+generic channel appearing in \`knownUnsupported\` does not mean the corresponding commerce decision
+is absent when an effect-level action is declared.`;
+const GETTING_STARTED_V8_TEXT = GETTING_STARTED_V7_TEXT
+  .replace('# Getting started with Meguro v7', '# Getting started with Meguro v8')
+  .replace(`Published URI: \`${GETTING_STARTED_V7_URI}\``, `Published URI: \`${GETTING_STARTED_V8_URI}\``)
+  .replace(GETTING_STARTED_V7_DEEPER_DOCUMENTATION_TEXT, CURRENT_DEEPER_DOCUMENTATION_TEXT)
+  .replace('## Control and data planes', `${CURRENT_VERSION_LABELS_TEXT}\n\n## Control and data planes`)
+  .replace('## Deeper in-band documentation', `${CIMD_TROUBLESHOOTING_TEXT}\n\n## Deeper in-band documentation`);
+const PRODUCT_GUIDE_V5_TEXT = PRODUCT_GUIDE_V4_TEXT
+  .replace('# Meguro product guide v4', '# Meguro product guide v5')
+  .replace(`Published URI: \`${PRODUCT_GUIDE_V4_URI}\``, `Published URI: \`${PRODUCT_GUIDE_V5_URI}\``)
+  .replace(
+    `read
+  \`${RECEIPT_GUIDE_URI}\` or \`${RECEIPT_GUIDE_V2_URI}\`.`,
+    `read \`${CURRENT_RECEIPT_GUIDE_URI}\`.`,
+  )
+  .replaceAll(RECEIPT_GUIDE_URI, CURRENT_RECEIPT_GUIDE_URI)
+  .replaceAll(RECEIPT_GUIDE_V2_URI, CURRENT_RECEIPT_GUIDE_URI)
+  .replaceAll(GATE_POLICY_V2_URI, CURRENT_GATE_POLICY_URI)
+  .replaceAll(GETTING_STARTED_V7_URI, CURRENT_GETTING_STARTED_URI)
+  .replace(
+    '## Stable concepts versus changing facts',
+    `${CURRENT_VERSION_LABELS_TEXT}\n\n${ASSERTION_FAMILY_EXERCISE_TEXT}\n\n${CHANNEL_ABSTRACTION_TEXT}\n\n## Stable concepts versus changing facts`,
+  );
 const RECEIPT_GUIDE_V6_TEXT = simulationVocabularyText(
   RECEIPT_GUIDE_V5_TEXT
     .replace('# Meguro receipt guide v5', '# Meguro receipt guide v6')
@@ -1285,6 +1460,71 @@ const GATE_POLICY_V2_TEXT = simulationVocabularyText(
     .replace('# Meguro Gate policy v1', '# Meguro Gate policy v2')
     .replace(`Published URI: \`${GATE_POLICY_URI}\``, `Published URI: \`${GATE_POLICY_V2_URI}\``),
 );
+const GATE_POLICY_V1_CHECK_TEXT = GATE_POLICY_V1_CHECKS.map((check) => `### ${check.name}
+
+- Receipt facts: ${check.facts.map((fact) => `\`${fact}\``).join(', ')}
+- Threshold: ${check.threshold}.
+- Flip condition: ${check.flip}.`).join('\n\n');
+const GATE_POLICY_V3_CHECK_TEXT = GATE_POLICY_V3_CHECKS.map((check) => `### ${check.name}
+
+- Receipt facts: ${check.facts.map((fact) => `\`${fact}\``).join(', ')}
+- Threshold: ${check.threshold}.
+- Flip condition: ${check.flip}.`).join('\n\n');
+const GATE_POLICY_V3_FACT_ROOT_TEXT = `## Canonical fact root
+
+Every receipt-fact path in this policy is absolute against the complete
+\`meguro.gate-verdict.v1\` payload returned by \`gate_verdict\`. The authoritative facts live
+under \`facts\`; do not strip that prefix, resolve a citation against another receipt projection,
+or copy a citation's value as a substitute for resolving its path.
+
+Resolve every required path before applying a threshold. If any path is absent, fail closed with:
+
+\`\`\`json
+{"schemaVersion":"meguro.gate-policy-fact-resolution.v1","status":"refused","code":"required-receipt-fact-missing","policyUri":"${GATE_POLICY_V3_URI}","missingFactPaths":["facts.example"],"meaning":"The canonical Gate verdict does not contain every fact required by this policy.","nextStep":"Call gate_evaluate for the receipt, then call gate_verdict again. Do not infer, fabricate, or default a missing fact."}
+\`\`\``;
+const GATE_POLICY_V3_TEXT = GATE_POLICY_V2_TEXT
+  .replace('# Meguro Gate policy v2', '# Meguro Gate policy v3')
+  .replace(`Published URI: \`${GATE_POLICY_V2_URI}\``, `Published URI: \`${GATE_POLICY_V3_URI}\``)
+  .replace('## Checks', `${GATE_POLICY_V3_FACT_ROOT_TEXT}\n\n## Checks`)
+  .replace(GATE_POLICY_V1_CHECK_TEXT, GATE_POLICY_V3_CHECK_TEXT)
+  .replace(
+    `A verdict citing policy version 1 always resolves to \`${GATE_POLICY_URI}\`. This content and digest
+do not change. A future policy receives a new id, version, URI, and digest; it is appended beside v1
+instead of replacing it.`,
+    `The runtime policy remains \`meguro.release-gate-policy.v1\`, version \`1\`. Documentation version 3
+corrects its fact-path addressing against the complete canonical verdict payload; it does not rewrite
+the runtime thresholds or either historical documentation resource. Versions 1 and 2 retain their
+original bytes and digests, while this corrected resource remains immutable at \`${GATE_POLICY_V3_URI}\`.`,
+  );
+
+function gatePolicyValueAt(value, path) {
+  return path.replace(/\[(\d+)\]/gu, '.$1').split('.').reduce((current, key) => {
+    if (!current || typeof current !== 'object' || !Object.hasOwn(current, key)) return undefined;
+    return current[key];
+  }, value);
+}
+
+export function gatePolicyFactResolution(verdict) {
+  const required = [...new Set(GATE_POLICY_V3_CHECKS.flatMap((check) => check.facts))];
+  const missingFactPaths = required.filter((path) => gatePolicyValueAt(verdict, path) === undefined);
+  if (missingFactPaths.length) {
+    return deepFreeze({
+      schemaVersion: 'meguro.gate-policy-fact-resolution.v1',
+      status: 'refused',
+      code: 'required-receipt-fact-missing',
+      policyUri: GATE_POLICY_V3_URI,
+      missingFactPaths,
+      meaning: 'The canonical Gate verdict does not contain every fact required by this policy.',
+      nextStep: 'Call gate_evaluate for the receipt, then call gate_verdict again. Do not infer, fabricate, or default a missing fact.',
+    });
+  }
+  return deepFreeze({
+    schemaVersion: 'meguro.gate-policy-fact-resolution.v1',
+    status: 'resolved',
+    policyUri: GATE_POLICY_V3_URI,
+    resolvedFactPaths: required,
+  });
+}
 
 function entry(input) {
   const text = String(input.text);
@@ -1415,6 +1655,24 @@ const CATALOG = buildDocumentationCatalog([
     description: `World-first discovery sequence for Shopify Admin GraphQL ${ADMIN_API_SUPPORTED_VERSIONS.join(' and ')} with default ${ADMIN_API_DEFAULT_VERSION}.`,
     text: GETTING_STARTED_V6_TEXT,
   },
+  {
+    topic: 'getting-started',
+    version: GETTING_STARTED_V7_VERSION,
+    uri: GETTING_STARTED_V7_URI,
+    name: 'Getting started with Meguro v7',
+    title: 'Getting started with Meguro v7',
+    description: `Hosted-first practice-store sequence for Shopify Admin GraphQL ${ADMIN_API_SUPPORTED_VERSIONS.join(' and ')} with default ${ADMIN_API_DEFAULT_VERSION}.`,
+    text: GETTING_STARTED_V7_TEXT,
+  },
+  {
+    topic: 'getting-started',
+    version: GETTING_STARTED_V8_VERSION,
+    uri: GETTING_STARTED_V8_URI,
+    name: 'Getting started with Meguro v8',
+    title: 'Getting started with Meguro v8',
+    description: `Current-link-derived hosted sequence with explicit document, Gate-contract, and Shopify Admin version labels; supported Admin versions ${ADMIN_API_SUPPORTED_VERSIONS.join(' and ')}, default ${ADMIN_API_DEFAULT_VERSION}.`,
+    text: GETTING_STARTED_V8_TEXT,
+  },
   {
     topic: 'product-guide',
     version: PRODUCT_GUIDE_VERSION,
@@ -1443,6 +1701,24 @@ const CATALOG = buildDocumentationCatalog([
     description: 'World-first product concepts, evidence boundaries, surface responsibilities, and question-to-source routing.',
     text: PRODUCT_GUIDE_V3_TEXT,
   },
+  {
+    topic: 'product-guide',
+    version: PRODUCT_GUIDE_V4_VERSION,
+    uri: PRODUCT_GUIDE_V4_URI,
+    name: 'Meguro product guide v4',
+    title: 'Meguro product guide v4',
+    description: 'Hosted-first product concepts, practice-run vocabulary, evidence boundaries, and question-to-source routing.',
+    text: PRODUCT_GUIDE_V4_TEXT,
+  },
+  {
+    topic: 'product-guide',
+    version: PRODUCT_GUIDE_V5_VERSION,
+    uri: PRODUCT_GUIDE_V5_URI,
+    name: 'Meguro product guide v5',
+    title: 'Meguro product guide v5',
+    description: 'Current-link-derived product concepts with version-label, assertion-family, and effect-level channel guidance.',
+    text: PRODUCT_GUIDE_V5_TEXT,
+  },
   {
     topic: 'index',
     version: DOCUMENTATION_CURRENCY_V1.indexVersion,
@@ -1452,6 +1728,33 @@ const CATALOG = buildDocumentationCatalog([
     description: 'Immutable current-version pointers for every published Meguro documentation family.',
     text: documentationIndexText(DOCUMENTATION_CURRENCY_V1),
   },
+  {
+    topic: 'index',
+    version: DOCUMENTATION_CURRENCY_V2.indexVersion,
+    uri: DOCUMENTATION_INDEX_V2_URI,
+    name: 'Meguro documentation index v2',
+    title: 'Meguro documentation index v2',
+    description: 'Immutable current-version pointers for every published Meguro documentation family after the hosted run-lane separation.',
+    text: documentationIndexText(DOCUMENTATION_CURRENCY_V2, DOCUMENTATION_INDEX_V2_URI),
+  },
+  {
+    topic: 'index',
+    version: DOCUMENTATION_CURRENCY_V3.indexVersion,
+    uri: DOCUMENTATION_INDEX_V3_URI,
+    name: 'Meguro documentation index v3',
+    title: 'Meguro documentation index v3',
+    description: 'Immutable current-version pointers after correcting Gate-policy fact paths against the canonical verdict payload.',
+    text: documentationIndexText(DOCUMENTATION_CURRENCY_V3, DOCUMENTATION_INDEX_V3_URI),
+  },
+  {
+    topic: 'index',
+    version: DOCUMENTATION_CURRENCY_V4.indexVersion,
+    uri: DOCUMENTATION_INDEX_V4_URI,
+    name: 'Meguro documentation index v4',
+    title: 'Meguro documentation index v4',
+    description: 'Immutable current-version pointers after the current-link, version-label, and explanatory-rider documentation mint.',
+    text: documentationIndexText(DOCUMENTATION_CURRENCY_V4, DOCUMENTATION_INDEX_V4_URI),
+  },
   {
     topic: 'receipt-guide',
     version: RECEIPT_GUIDE_VERSION,
@@ -1533,6 +1836,15 @@ const CATALOG = buildDocumentationCatalog([
     description: 'Immutable named checks and flip conditions republished with the simulation-run vocabulary.',
     text: GATE_POLICY_V2_TEXT,
   },
+  {
+    topic: 'gate-policy',
+    version: GATE_POLICY_V3_VERSION,
+    uri: GATE_POLICY_V3_URI,
+    name: 'Meguro Gate policy v3',
+    title: 'Meguro Gate policy v3',
+    description: 'Immutable named checks with absolute fact paths against the complete canonical Gate verdict payload.',
+    text: GATE_POLICY_V3_TEXT,
+  },
 ], CURRENT_DOCUMENTATION_CURRENCY);
 
 export function documentationResources() {

package/src/server.mjs

@@ -14,7 +14,7 @@ import {
 } from './protocol.mjs';
 import { createTools, redactSecrets } from './tools.mjs';
 
-const SERVER_INFO = { name: 'meguro', version: '0.2.8' };
+const SERVER_INFO = { name: 'meguro', version: '0.2.10' };
 const PROTOCOL_VERSION = '2025-03-26';
 
 const tools = createTools({

package/src/tools.mjs

@@ -397,7 +397,12 @@ const PRACTICE_RUN_OBSERVATION_REQUEST_INPUT_SCHEMA = Object.freeze({
   type: 'object',
   additionalProperties: false,
   properties: {
-    apiVersion: { type: 'string', const: '2026-04', description: 'The Admin API version supported by planned checkpoint observations.' },
+    apiVersion: {
+      type: 'string',
+      enum: [...ADMIN_API_SUPPORTED_VERSIONS],
+      default: ADMIN_API_DEFAULT_VERSION,
+      description: `Requested Shopify Admin API version for this checkpoint observation. Supported: ${ADMIN_API_SUPPORTED_VERSION_LABEL}; default: ${ADMIN_API_DEFAULT_VERSION}. The retained non-default version remains explicit in the stored plan and evidence.`,
+    },
     query: { type: 'string', minLength: 1, maxLength: 30000, description: 'One read-only Shopify Admin GraphQL document.' },
     operationName: { type: 'string', minLength: 1, description: 'Required when query contains more than one operation.' },
     // GraphQL variables are deliberately arbitrary JSON keys. The registry sweep pins this one
@@ -725,12 +730,49 @@ function receiptProjection(value) {
   const practiceRun = attempt.practiceRun ?? value?.practiceRun ?? null;
   const calls = Array.isArray(value?.events?.calls) ? value.events.calls : [];
   const actions = Array.isArray(value?.events?.actions) ? value.events.actions : [];
+  const capabilityMatrix = value?.receiptEvidence?.assertionCapabilities;
+  const webhookCapability = capabilityMatrix?.schemaVersion === 'meguro.receipt-assertion-capabilities.v1'
+    && capabilityMatrix?.families?.webhook
+    && typeof capabilityMatrix.families.webhook === 'object'
+    ? capabilityMatrix.families.webhook
+    : null;
   const assertions = Array.isArray(value?.receiptEvidence?.assertions)
-    ? value.receiptEvidence.assertions.slice(0, 50).map((assertion) => ({
-      id: assertion.id,
-      status: assertion.status,
-      label: assertion.label,
-    }))
+    ? value.receiptEvidence.assertions.slice(0, 50).map((assertion) => {
+      if (assertion?.category !== 'webhook') {
+        return { id: assertion.id, status: assertion.status, label: assertion.label };
+      }
+      if (webhookCapability?.availability === 'available') {
+        return { id: assertion.id, status: assertion.status, label: assertion.label, detail: assertion.detail };
+      }
+      if (webhookCapability?.availability === 'unavailable'
+        && webhookCapability.statusLabel === 'not available in this run mode'
+        && typeof webhookCapability.detail === 'string'
+        && webhookCapability.detail.trim()) {
+        return {
+          id: assertion.id,
+          status: webhookCapability.statusLabel,
+          label: assertion.label,
+          detail: webhookCapability.detail,
+        };
+      }
+      if (webhookCapability?.availability === 'unknown'
+        && webhookCapability.statusLabel === 'availability unknown'
+        && typeof webhookCapability.detail === 'string'
+        && webhookCapability.detail.trim()) {
+        return {
+          id: assertion.id,
+          status: webhookCapability.statusLabel,
+          label: assertion.label,
+          detail: webhookCapability.detail,
+        };
+      }
+      return {
+        id: assertion.id,
+        status: 'availability unknown',
+        label: assertion.label,
+        detail: 'Webhook assertion availability is unknown because this receipt has no capability metadata.',
+      };
+    })
     : [];
   const verdict = value?.report?.verdict && typeof value.report.verdict === 'object'
     ? Object.fromEntries(['status', 'outcome', 'grade', 'score', 'headline', 'horizonDays']
@@ -1048,6 +1090,7 @@ function usageProjection(value) {
           ? 'Retained activity does not agree with the tier meter; the competing activity-derived total is withheld.'
           : 'Retained activity is incomplete; no activity-derived consumption total is projected.',
     },
+    simulationRunAccounting: value?.simulationRunAccounting ?? null,
     headroom: {
       remainingSimulationRuns,
       remainingStoreSlots: Math.max(0, activeStoreLimit - activeStores),
@@ -1055,6 +1098,11 @@ function usageProjection(value) {
     },
     limits: {
       activeStores,
+      activeStoreAccounting: {
+        basis: 'metered-active-stores',
+        exemptionMarker: 'auto-provisioned-sample-store',
+        note: 'activeStores counts metered stores. A stores_list row marked auto-provisioned-sample-store is an exempt sample store and is not counted here.',
+      },
       activeStoreLimit,
       activeWorkspaces,
       activeWorkspaceLimit,
@@ -1991,7 +2039,7 @@ export function createTools(config) {
     },
     {
       name: 'usage_read',
-      description: 'Read authoritative tier-meter simulation runs, practice-store, and workspace headroom before starting work. A billable simulation-run total is shown only when complete retained activity reconciles to that meter; incomplete coverage or a source mismatch is disclosed without projecting a competing consumption number.',
+      description: 'Read authoritative tier-meter simulation runs, practice-store, and workspace headroom before starting work. When retained activity reconciles, simulationRunAccounting gives the exact counted + excluded non-billable sample = visible completed equation and the stable exclusion-policy identity. Incomplete coverage or a source mismatch is disclosed without projecting a competing consumption number.',
       inputSchema: { type: 'object', additionalProperties: false, properties: {}, required: [] },
     },
     {