meguro-mcp 0.2.4 → 0.2.6

package/src/docs.mjs

@@ -1,15 +1,49 @@
 import { createHash } from 'node:crypto';
+import {
+  ADMIN_API_DEFAULT_VERSION,
+  ADMIN_API_SUPPORTED_VERSIONS,
+  ADMIN_API_VERSION_REGISTRY,
+} from './admin-versions.generated.mjs';
 
 const RECEIPT_GUIDE_VERSION = 1;
-const RECEIPT_GUIDE_LATEST_VERSION = 2;
+const RECEIPT_GUIDE_V2_VERSION = 2;
+const RECEIPT_GUIDE_V3_VERSION = 3;
+const RECEIPT_GUIDE_V4_VERSION = 4;
+const RECEIPT_GUIDE_LATEST_VERSION = 5;
+const RECEIPT_GUIDE_V6_VERSION = 6;
+const RECEIPT_GUIDE_V7_VERSION = 7;
 const GATE_POLICY_VERSION = 1;
+const GATE_POLICY_V2_VERSION = 2;
 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 PRODUCT_GUIDE_VERSION = 1;
+const PRODUCT_GUIDE_V2_VERSION = 2;
+const PRODUCT_GUIDE_V3_VERSION = 3;
 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}`;
+const RECEIPT_GUIDE_V4_URI = `meguro://docs/receipt-guide/v${RECEIPT_GUIDE_V4_VERSION}`;
 const RECEIPT_GUIDE_LATEST_URI = `meguro://docs/receipt-guide/v${RECEIPT_GUIDE_LATEST_VERSION}`;
+const RECEIPT_GUIDE_V6_URI = `meguro://docs/receipt-guide/v${RECEIPT_GUIDE_V6_VERSION}`;
+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 GETTING_STARTED_URI = `meguro://docs/getting-started/v${GETTING_STARTED_VERSION}`;
-
-export const GETTING_STARTED_INSTRUCTIONS = 'New to Meguro? Read `meguro://docs/getting-started/v1` with `resources/read`, or call `docs_read({ topic: "getting-started", version: 1 })`, before starting for the exact tool sequence from template discovery to receipt.';
+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 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}`;
+
+export const MCP_INITIALIZE_INSTRUCTIONS = `Start with \`${GETTING_STARTED_V6_URI}\` or call \`docs_read({ topic: "getting-started", version: 6 })\`; for general Meguro questions, read \`${PRODUCT_GUIDE_V3_URI}\` or call \`docs_read({ topic: "product-guide", version: 3 })\`.`;
+export const PRODUCT_GUIDE_SHA256 = 'e5450c1b4181cec4d6ed0a498dbff1cb25d2e223ff2228928aecbbce9674f074';
 
 function deepFreeze(value) {
   if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
@@ -535,6 +569,79 @@ const RECEIPT_FIELDS = deepFreeze({
   ]),
 });
 
+const RECEIPT_FIELDS_V3 = deepFreeze({
+  ...RECEIPT_FIELDS,
+  'meguro.shared-receipt.v2': stableFields([
+    ...RECEIPT_FIELDS['meguro.shared-receipt.v2'],
+    'rejectionAttribution.acceptedCalls',
+    'rejectionAttribution.allCallsRejected',
+    'rejectionAttribution.classification',
+    'rejectionAttribution.evidenceSource',
+    'rejectionAttribution.explanation',
+    'rejectionAttribution.field',
+    'rejectionAttribution.gateStatus',
+    'rejectionAttribution.headline',
+    'rejectionAttribution.operation',
+    'rejectionAttribution.reasonCode',
+    'rejectionAttribution.rejectedCalls',
+    'rejectionAttribution.requiresReview',
+    'rejectionAttribution.responsibleLayer',
+    'rejectionAttribution.schemaVersion',
+    'rejectionAttribution.targetValidity',
+  ]),
+});
+
+const FINANCIAL_SOURCE_FIELDS = [
+  'revenueCents',
+  'refundedCents',
+  'netRevenueCents',
+  'cogsCents',
+  'costLedgerCents',
+  'wrongfulDeclinePenaltyCents',
+  'storeCreditNetCostCents',
+  'freeShippingSubsidyCents',
+  'orderRiskCostCents',
+  'inventoryTransferCostCents',
+  'catalogQualityImprovementCostCents',
+  'loyaltyExpectedRedemptionCostCents',
+  'winbackOfferCostCents',
+  'cartRecoveryCostCents',
+  'fulfillmentCostCents',
+  'netContributionCents',
+];
+
+const RECEIPT_FIELDS_V5 = deepFreeze({
+  ...RECEIPT_FIELDS_V3,
+  'meguro.hosted-impact-report.v1': stableFields([
+    ...RECEIPT_FIELDS_V3['meguro.hosted-impact-report.v1'],
+    'effectLines[].sourceField',
+    ...FINANCIAL_SOURCE_FIELDS.flatMap((field) => [
+      `financialSourceTotals.baseline.${field}`,
+      `financialSourceTotals.treated.${field}`,
+    ]),
+  ]),
+});
+
+const RECEIPT_FIELDS_LATEST = deepFreeze({
+  ...RECEIPT_FIELDS_V5,
+  'meguro.tiktok-practice-receipt.v1': stableFields([
+    ...RECEIPT_FIELDS_V5['meguro.tiktok-practice-receipt.v1']
+      .filter((field) => field !== 'rehearsalDigest' && field !== 'software.rehearsalProjectionVersion'),
+    'simulationDigest',
+    'software.simulationProjectionVersion',
+  ]),
+});
+
+const RECEIPT_FIELDS_V7 = deepFreeze({
+  ...RECEIPT_FIELDS_LATEST,
+  'meguro.hosted-impact-report.v1': stableFields([
+    ...RECEIPT_FIELDS_LATEST['meguro.hosted-impact-report.v1'],
+    'dailyMetricBasis.units',
+    'dailyMetricBasis.orders.customer_depth_model',
+    'dailyMetricBasis.orders.sold_units_proxy',
+  ]),
+});
+
 const FIELD_MEANINGS = Object.freeze({
   schemaVersion: 'Selects the immutable wire contract used to interpret the remaining fields.',
   evidenceContext: 'Carries the declared subject, attempt history, and world provenance without verifying a customer-declared build identity.',
@@ -581,8 +688,8 @@ function fieldMeaning(schema, path) {
   return `Recorded ${words(leaf)} in ${schema}; interpret it with that schema's basis and adjacent evidence fields.`;
 }
 
-function renderFieldInventory() {
-  return Object.entries(RECEIPT_FIELDS).map(([schema, paths]) => [
+function renderFieldInventory(fields = RECEIPT_FIELDS) {
+  return Object.entries(fields).map(([schema, paths]) => [
     `### \`${schema}\``,
     '',
     ...paths.map((path) => `- \`${path}\` — ${fieldMeaning(schema, path)}`),
@@ -673,9 +780,75 @@ retention policy.`;
 // the MEG-622 account-deletion interpretation without mutating any previously citable resource.
 const RECEIPT_GUIDE_V2_TEXT = RECEIPT_GUIDE_TEXT
   .replace('# Meguro receipt guide v1', '# Meguro receipt guide v2')
-  .replace(`Published URI: \`${RECEIPT_GUIDE_URI}\``, `Published URI: \`${RECEIPT_GUIDE_LATEST_URI}\``)
+  .replace(`Published URI: \`${RECEIPT_GUIDE_URI}\``, `Published URI: \`${RECEIPT_GUIDE_V2_URI}\``)
   .replace('## Field inventory', `${ACCOUNT_DELETION_GUIDE_TEXT}\n\n## Field inventory`);
 
+const RECEIPT_GUIDE_V3_TEXT = RECEIPT_GUIDE_V2_TEXT
+  .replace('# Meguro receipt guide v2', '# Meguro receipt guide v3')
+  .replace(`Published URI: \`${RECEIPT_GUIDE_V2_URI}\``, `Published URI: \`${RECEIPT_GUIDE_V3_URI}\``)
+  .replace(renderFieldInventory(RECEIPT_FIELDS), renderFieldInventory(RECEIPT_FIELDS_V3));
+
+const IMPACT_RECOMPUTATION_GUIDE_TEXT = `## Recomputing impact money figures
+
+Every comparable \`meguro.hosted-impact-report.v1\` money effect line carries \`sourceField\`.
+Recompute its \`amountCents\` as
+\`financialSourceTotals.treated[sourceField] - financialSourceTotals.baseline[sourceField]\`.
+The refund effect links to \`refundedCents\`; net revenue links to \`netRevenueCents\`; net
+contribution links to \`netContributionCents\`.
+
+For either arm, \`netRevenueCents = revenueCents - refundedCents\`. Net contribution is that net
+revenue minus the same arm's COGS and every listed operating-cost component: \`costLedgerCents\`,
+\`wrongfulDeclinePenaltyCents\`, \`storeCreditNetCostCents\`, \`freeShippingSubsidyCents\`,
+\`orderRiskCostCents\`, \`inventoryTransferCostCents\`, \`catalogQualityImprovementCostCents\`,
+\`loyaltyExpectedRedemptionCostCents\`, \`winbackOfferCostCents\`, \`cartRecoveryCostCents\`, and
+\`fulfillmentCostCents\`. These are the source totals used by the verdict, not a second calculation.
+
+When \`metricSource\` is \`sold_units_proxy\`, the count line is labeled as a net-units effect used
+as a one-order-per-unit proxy. It is not an observed order count.`;
+
+const RECEIPT_GUIDE_V4_TEXT = RECEIPT_GUIDE_V3_TEXT
+  .replace('# Meguro receipt guide v3', '# Meguro receipt guide v4')
+  .replace(`Published URI: \`${RECEIPT_GUIDE_V3_URI}\``, `Published URI: \`${RECEIPT_GUIDE_V4_URI}\``)
+  .replace('## Field inventory', `${IMPACT_RECOMPUTATION_GUIDE_TEXT}\n\n## Field inventory`)
+  .replace(renderFieldInventory(RECEIPT_FIELDS_V3), renderFieldInventory(RECEIPT_FIELDS_V5));
+
+const PUBLIC_RECEIPT_DELIVERY_GUIDE_TEXT = `## Public receipt delivery
+
+For every newly returned \`meguro.public-receipt-reference.v1\`, \`canonicalPath\` is the complete
+environment-qualified HTTPS URL of the immutable artifact. Fetch that URL as-is without credentials;
+do not join it to the MCP origin, Console origin, or another guessed host. The same rule applies to
+the run reference in \`publicReceipt\` and the impact reference in \`impactPublicReceipt\`.
+
+\`\`\`sh
+curl --fail --silent --show-error "$CANONICAL_URL" --output receipt.json
+printf '%s  %s\\n' "$EXPECTED_SHA256" receipt.json | shasum -a 256 --check
+\`\`\`
+
+Unknown, malformed, foreign, expired, purged, and never-issued public ids return the same
+\`receipt-unavailable\` response. Fetchability ends at the receipt-availability window stated by the
+live product response; retain the exact bytes in your own evidence store when longer custody is
+required.`;
+
+// Published documentation is append-only. V1-V4 retain their original bytes and digests; V5 binds
+// the canonical receipt reference to the selected environment's public API without an undefined
+// out-of-band MEGURO_ORIGIN variable.
+const RECEIPT_GUIDE_V5_TEXT = RECEIPT_GUIDE_V4_TEXT
+  .replace('# Meguro receipt guide v4', '# Meguro receipt guide v5')
+  .replace(`Published URI: \`${RECEIPT_GUIDE_V4_URI}\``, `Published URI: \`${RECEIPT_GUIDE_LATEST_URI}\``)
+  .replace('## Independent exact-byte verification', `${PUBLIC_RECEIPT_DELIVERY_GUIDE_TEXT}\n\n## Independent exact-byte verification`)
+  .replace(
+    '`publicReceipt.canonicalPath` without credentials, preserve the exact response bytes, compute',
+    '`publicReceipt.canonicalPath` as a complete URL without credentials, preserve the exact response bytes, compute',
+  )
+  .replace(
+    'curl --fail --silent --show-error "$MEGURO_ORIGIN$CANONICAL_PATH" --output receipt.json',
+    'curl --fail --silent --show-error "$CANONICAL_URL" --output receipt.json',
+  )
+  .replace(
+    'The unauthenticated path from which an independent reader fetches the exact issued bytes.',
+    'The complete environment-qualified HTTPS URL from which an independent reader fetches the exact issued bytes without credentials.',
+  );
+
 export const GATE_POLICY_V1_CHECKS = deepFreeze([
   {
     name: 'blocked-write and error evidence',
@@ -810,8 +983,278 @@ All published documentation resources are immutable. Cite the exact URI, version
 digest returned by Meguro.
 `;
 
+const GETTING_STARTED_V2_TEXT = GETTING_STARTED_TEXT
+  .replace('# Getting started with Meguro v1', '# Getting started with Meguro v2')
+  .replace(`Published URI: \`${GETTING_STARTED_URI}\``, `Published URI: \`${GETTING_STARTED_V2_URI}\``)
+  .replace(
+    '   account-scoped `MEGURO_API_TOKEN` and cannot control other stores or account resources.',
+    `   account-scoped \`MEGURO_API_TOKEN\` and cannot control other stores or account resources.
+
+   This practice store emulates Shopify Admin GraphQL \`2026-04\`. If your agent targets a newer
+   Shopify release, call \`admin_schema\` to inspect the modeled contract before issuing the first
+   Admin call; newer-release behavior is not established by a \`2026-04\` practice result.
+`,
+  );
+
+const GETTING_STARTED_V3_TEXT = GETTING_STARTED_V2_TEXT
+  .replace('# Getting started with Meguro v2', '# Getting started with Meguro v3')
+  .replace(`Published URI: \`${GETTING_STARTED_V2_URI}\``, `Published URI: \`${GETTING_STARTED_LATEST_URI}\``)
+  .replace(
+    `   This practice store emulates Shopify Admin GraphQL \`2026-04\`. If your agent targets a newer
+   Shopify release, call \`admin_schema\` to inspect the modeled contract before issuing the first
+   Admin call; newer-release behavior is not established by a \`2026-04\` practice result.
+`,
+    `   The supported Shopify Admin GraphQL versions are ${ADMIN_API_SUPPORTED_VERSIONS.map((version) => `\`${version}\``).join(' and ')}; the
+   default is \`${ADMIN_API_DEFAULT_VERSION}\`. Read \`adminApiVersion\` for the default,
+   \`adminApiVersions\` for the supported set, and \`adminVersions\` for the exact versioned Admin URLs.
+   Use the URL whose version segment matches your agent. Call \`admin_schema\` with that version before
+   issuing the first Admin call; valid Shopify additions outside Meguro's modeled subset return an
+   explicit teaching refusal rather than approximate behavior.
+`,
+  );
+
+const PRODUCT_GUIDE_TEXT = `# Meguro product guide v1
+
+Published URI: \`${PRODUCT_GUIDE_URI}\`
+
+## What Meguro is—and is not
+
+Meguro is a technical evaluation environment for commerce agents. Its core product primitives are
+practice stores, deterministic Store time, recorded API behavior, immutable receipts, and Gate
+evidence.
+
+Practice results do not prove live-market demand, future revenue, production performance, or live
+Shopify acceptance. Live-platform claims are established only by the relevant real-platform or
+Shopify Exam evidence; never infer them from practice compatibility or modeled outcomes.
+
+## Core nouns
+
+- **Template:** a supported, versioned starting scenario used to create a practice store.
+- **Practice store / \`storeId\`:** an owned synthetic commerce environment and its canonical public
+  identifier. It is not a merchant's production store.
+- **Store time:** the deterministic scenario clock advanced through the run lifecycle. It is distinct
+  from wall-clock request time.
+- **Run / \`attemptId\`:** one bounded evaluation window and the identifier used by its lifecycle,
+  status, and evidence tools.
+- **Receipt:** the immutable record of what the agent called, what was accepted or rejected, and what
+  the declared evidence establishes. For field-level interpretation, read
+  \`meguro://docs/receipt-guide/v1\` or \`meguro://docs/receipt-guide/v2\`.
+- **Modeled outcome / Impact context:** scenario-derived context that compares recorded behavior with
+  a declared model. It is not a merchant forecast, causal claim, or production result.
+- **Gate:** a release signal computed from named receipt facts, thresholds, and precedence. For the
+  exact policy, read \`meguro://docs/gate-policy/v1\`.
+- **Shopify Exam:** a captured API-shape fidelity exam against an eligible Shopify development store.
+  Its evidence establishes only the bounded live-platform facts recorded by that exam, not blanket
+  Shopify acceptance or merchant outcomes.
+
+## Product surfaces and boundaries
+
+- **Console** provides visual setup, receipt inspection, account administration, client revocation,
+  plans, billing, and payment actions.
+- **Hosted OAuth MCP** is the recommended control plane for interactive agents.
+- **Public STDIO MCP** is the local and CI fallback.
+- **Practice-store Admin endpoint** is the Shopify-shaped data plane used by the commerce agent under
+  evaluation; it is separate from the MCP control plane.
+- **MCP does not perform money actions:** it does not check out, buy or change a subscription, manage
+  payment methods, or make another payment.
+
+## Question-to-source routing
+
+| User asks | Agent must do |
+|---|---|
+| What is Meguro or what does it prove? | Answer from this product guide and preserve its evidence boundary. |
+| How do I start an evaluation? | Read \`meguro://docs/getting-started/v1\`. |
+| What does this receipt or verdict mean? | Read the appropriate receipt guide and \`meguro://docs/gate-policy/v1\`. |
+| What stores exist? | Call \`stores_list\`. |
+| What runs exist or what happened? | Call \`runs_list\` and the relevant status, report, or impact tool. |
+| What workspaces exist? | Call \`workspaces_list\`. |
+| What is my current usage or cap? | Call \`usage_read\`; do not answer from static values. |
+| Which templates are available? | Call \`templates_list\`. |
+| How much does a plan cost, or how do I subscribe or change plans? | Direct the user to Console → Plans & Billing. Do not quote immutable pricing or attempt payment through MCP. |
+| How do I manage or revoke an MCP connection? | Direct the user to Console → Connection → MCP authorizations. |
+| How do I delete my account? | Direct the user to the Console-only account-deletion flow and [Meguro Help](https://meguro.io/help.html). |
+| Where can I learn more or get support? | Use [Meguro Help](https://meguro.io/help.html) or [hello@meguro.io](mailto:hello@meguro.io); do not invent another location. |
+
+## Answering discipline
+
+- Use live MCP tools for user-, workspace-, store-, run-, usage-, and template-specific facts.
+- Use immutable guides for stable concepts and evidence interpretation.
+- Use Console for money actions and explicitly Console-only account actions.
+- Never infer an undocumented capability, price, limit, legal conclusion, Shopify acceptance, or
+  merchant outcome.
+- If neither an in-band document nor a tool result establishes the answer, say that it is not
+  established and direct the user to Meguro Help or support.
+
+## Stable concepts versus changing facts
+
+Do not hardcode plan prices, current tier allowances, trial length, supported-country lists, current
+account state, or current fleet state. Read changing values from the appropriate live tool or the
+canonical Console surface.
+
+Do not reproduce or interpret legal terms. Link to the canonical [Terms](https://meguro.io/terms) and
+[Privacy Notice](https://meguro.io/privacy).
+`;
+
+function simulationVocabularyText(source) {
+  const replacements = [
+    ['returns-rehearsal', 'returns-simulation'],
+    ['runConclusionReceipt', 'simulationRunReceipt'],
+    ['runConclusionClock', 'simulationRunClock'],
+    ['meguro.run-conclusion-receipt.v1', 'meguro.simulation-run-receipt.v1'],
+    ['meguro.run-conclusion-clock.v1', 'meguro.simulation-run-clock.v1'],
+    ['consumedCredits', 'consumedSimulationRuns'],
+    ['billableRuns', 'billableSimulationRuns'],
+    ['remainingCredits', 'remainingSimulationRuns'],
+    ['monthlyRunCredits', 'monthlySimulationRuns'],
+    ['run credits', 'simulation runs'],
+    ['run credit', 'simulation run'],
+    ['Run credits', 'Simulation runs'],
+    ['Run credit', 'Simulation run'],
+    ['Conclusions', 'Simulation runs'],
+    ['conclusions', 'simulation runs'],
+    ['Conclusion', 'Result'],
+    ['conclusion', 'result'],
+    ['Rehearsals', 'Simulations'],
+    ['rehearsals', 'simulations'],
+    ['Rehearsal', 'Simulation'],
+    ['rehearsal', 'simulation'],
+  ];
+  let text = String(source);
+  for (const [before, after] of replacements) text = text.split(before).join(after);
+  return text;
+}
+
+const GETTING_STARTED_V4_TEXT = simulationVocabularyText(
+  GETTING_STARTED_V3_TEXT
+    .replace('# Getting started with Meguro v3', '# Getting started with Meguro v4')
+    .replace(`Published URI: \`${GETTING_STARTED_LATEST_URI}\``, `Published URI: \`${GETTING_STARTED_V4_URI}\``),
+);
+const ADMIN_VERSION_POLICY_GUIDE_TEXT = [
+  '## Shopify Admin version policy',
+  '',
+  "Meguro checks Shopify's official version schedule weekly and opens a migration ticket when a new",
+  "stable Admin release appears. Meguro mirrors Shopify's published accessible-until window; it does",
+  'not make an independent support-window promise.',
+  '',
+  ...ADMIN_API_VERSION_REGISTRY.map((entry) => {
+    const released = `${entry.releaseDate.slice(0, 10)} ${entry.releaseDate.slice(11, 16)} UTC`;
+    const supportedUntil = `${entry.supportedUntil.slice(0, 10)} ${entry.supportedUntil.slice(11, 16)} UTC`;
+    return `- \`${entry.apiVersion}\`: released ${released}; accessible until ${supportedUntil}.`;
+  }),
+  '',
+  `Source: [Shopify API versioning](${ADMIN_API_VERSION_REGISTRY[0]?.supportSourceUrl}).`,
+].join('\n');
+const GETTING_STARTED_V5_TEXT = GETTING_STARTED_V4_TEXT
+  .replace('# Getting started with Meguro v4', '# Getting started with Meguro v5')
+  .replace(`Published URI: \`${GETTING_STARTED_V4_URI}\``, `Published URI: \`${GETTING_STARTED_V5_URI}\``)
+  .replace('## Control and data planes', `${ADMIN_VERSION_POLICY_GUIDE_TEXT}\n\n## Control and data planes`);
+const PRODUCT_GUIDE_V2_TEXT = simulationVocabularyText(
+  PRODUCT_GUIDE_TEXT
+    .replace('# Meguro product guide v1', '# Meguro product guide v2')
+    .replace(`Published URI: \`${PRODUCT_GUIDE_URI}\``, `Published URI: \`${PRODUCT_GUIDE_V2_URI}\``),
+);
+const GETTING_STARTED_V6_TEXT = GETTING_STARTED_V5_TEXT
+  .replace('# Getting started with Meguro v5', '# Getting started with Meguro v6')
+  .replace(`Published URI: \`${GETTING_STARTED_V5_URI}\``, `Published URI: \`${GETTING_STARTED_V6_URI}\``)
+  .replace(
+    /## What Meguro is\n\n[\s\S]*?\n\n## Identities/u,
+    `## Begin with the world
+
+Meguro gives your agent a practice store with a year of modeled commerce history already behind it.
+When a run drives or schedules Store time, the store moves through Store days; between runs, its
+Store time stays frozen. The receipt is the store's memory of that run: the calls it heard, the
+changes it accepted or rejected, and the bounded evidence those events established.
+
+This is a deterministic practice world, not a merchant forecast or blanket certification of live
+platform behavior. Preserve every stated evidence boundary when you carry a receipt into a release
+decision.
+
+## Identities`,
+  )
+  .replace(
+    '## Canonical discovery-first sequence',
+    `## What requires your human
+
+Your human owns the Meguro account, chooses or changes the plan, and grants the agent access by
+completing hosted OAuth or by creating and supplying a workspace API key. The agent must never buy
+or change a plan, consent on the human's behalf, or invent or recover a credential. After that grant,
+the agent can discover templates and stores, run the world, and retrieve its receipt through MCP.
+
+## Canonical discovery-first sequence`,
+  );
+const PRODUCT_GUIDE_V3_TEXT = PRODUCT_GUIDE_V2_TEXT
+  .replace('# Meguro product guide v2', '# Meguro product guide v3')
+  .replace(`Published URI: \`${PRODUCT_GUIDE_V2_URI}\``, `Published URI: \`${PRODUCT_GUIDE_V3_URI}\``)
+  .replace(
+    /## What Meguro is—and is not\n\n[\s\S]*?\n\n## Core nouns/u,
+    `## Begin with the world
+
+Meguro gives a commerce agent a practice store with a year of modeled commerce history already
+behind it. The store moves through Store days only while a run drives or schedules its clock, and it
+stays frozen between runs. The receipt is the store's memory of that run: recorded API behavior,
+accepted and rejected changes, and the bounded evidence earned inside the declared world.
+
+Practice results do not prove live-market demand, future revenue, production performance, or live
+Shopify acceptance. Live-platform claims require the relevant real-platform or Shopify Exam evidence;
+never infer them from practice compatibility or modeled outcomes.
+
+## Core nouns`,
+  )
+  .replace(
+    '## Question-to-source routing',
+    `## What requires your human
+
+Your human creates and owns the account, chooses or changes its plan, and grants agent access by
+completing hosted OAuth or by creating and supplying a workspace API key. MCP does not buy or change
+a plan, consent for the human, or reveal a credential that the human has not granted.
+
+## Question-to-source routing`,
+  )
+  .replace('Read \`meguro://docs/getting-started/v1\`.', `Read \`${GETTING_STARTED_V6_URI}\`.`);
+const RECEIPT_GUIDE_V6_TEXT = simulationVocabularyText(
+  RECEIPT_GUIDE_V5_TEXT
+    .replace('# Meguro receipt guide v5', '# Meguro receipt guide v6')
+    .replace(`Published URI: \`${RECEIPT_GUIDE_LATEST_URI}\``, `Published URI: \`${RECEIPT_GUIDE_V6_URI}\``),
+);
+const DAILY_METRIC_BASIS_GUIDE_TEXT = [
+  '## Daily signed net-unit basis',
+  '',
+  'Every `meguro.hosted-impact-report.v1` carries `dailyMetricBasis` beside `days`. Render or',
+  'retain those exact strings when interpreting the daily columns.',
+  '',
+  '`days[].units` is signed net units in the simulation: sold units minus returned units. It may be',
+  'negative when returns exceed sales. When `days[].orderMetricSource` is',
+  '`sold_units_proxy`, `days[].orders` is that same signed net-unit value used as a',
+  'one-order-per-net-unit proxy; it is not an observed order count and may also be negative. When the',
+  'source is `customer_depth_model`, `days[].orders` is the separate modeled order count and is not',
+  'netted against returns.',
+].join('\n');
+function replaceDerivedFieldInventory(source, fields) {
+  const headingIndex = source.indexOf('## Field inventory');
+  const firstSchemaIndex = source.indexOf('\n### `', headingIndex);
+  if (headingIndex < 0 || firstSchemaIndex < 0) {
+    throw new Error('Receipt guide field inventory is missing');
+  }
+  return `${source.slice(0, firstSchemaIndex + 1)}${simulationVocabularyText(renderFieldInventory(fields))}`;
+}
+
+const RECEIPT_GUIDE_V7_WITH_BASIS = RECEIPT_GUIDE_V6_TEXT
+  .replace('# Meguro receipt guide v6', '# Meguro receipt guide v7')
+  .replace('Published URI: `' + RECEIPT_GUIDE_V6_URI + '`', 'Published URI: `' + RECEIPT_GUIDE_V7_URI + '`')
+  .replace('## Field inventory', `${DAILY_METRIC_BASIS_GUIDE_TEXT}\n\n## Field inventory`);
+const RECEIPT_GUIDE_V7_TEXT = replaceDerivedFieldInventory(RECEIPT_GUIDE_V7_WITH_BASIS, RECEIPT_FIELDS_V7);
+const GATE_POLICY_V2_TEXT = simulationVocabularyText(
+  GATE_POLICY_TEXT
+    .replace('# Meguro Gate policy v1', '# Meguro Gate policy v2')
+    .replace(`Published URI: \`${GATE_POLICY_URI}\``, `Published URI: \`${GATE_POLICY_V2_URI}\``),
+);
+
 function entry(input) {
   const text = String(input.text);
+  const digest = sha256(text);
+  if (input.expectedSha256 && input.expectedSha256 !== digest) {
+    throw new Error(`Documentation digest drift for ${input.uri}: expected ${input.expectedSha256}, received ${digest}`);
+  }
   return deepFreeze({
     topic: input.topic,
     version: input.version,
@@ -821,7 +1264,7 @@ function entry(input) {
     description: input.description,
     mimeType: 'text/markdown',
     text,
-    sha256: sha256(text),
+    sha256: digest,
   });
 }
 
@@ -875,6 +1318,79 @@ const CATALOG = buildDocumentationCatalog([
     description: 'Discovery-first technical-evaluator sequence from template selection through an immutable practice receipt.',
     text: GETTING_STARTED_TEXT,
   },
+  {
+    topic: 'getting-started',
+    version: GETTING_STARTED_V2_VERSION,
+    uri: GETTING_STARTED_V2_URI,
+    name: 'Getting started with Meguro v2',
+    title: 'Getting started with Meguro v2',
+    description: 'Discovery-first evaluator sequence with the explicit Shopify Admin GraphQL 2026-04 boundary.',
+    text: GETTING_STARTED_V2_TEXT,
+  },
+  {
+    topic: 'getting-started',
+    version: GETTING_STARTED_LATEST_VERSION,
+    uri: GETTING_STARTED_LATEST_URI,
+    name: 'Getting started with Meguro v3',
+    title: 'Getting started with Meguro v3',
+    description: `Discovery-first evaluator sequence for Shopify Admin GraphQL ${ADMIN_API_SUPPORTED_VERSIONS.join(' and ')} with default ${ADMIN_API_DEFAULT_VERSION}.`,
+    text: GETTING_STARTED_V3_TEXT,
+  },
+  {
+    topic: 'getting-started',
+    version: GETTING_STARTED_V4_VERSION,
+    uri: GETTING_STARTED_V4_URI,
+    name: 'Getting started with Meguro v4',
+    title: 'Getting started with Meguro v4',
+    description: `Simulation-vocabulary evaluator sequence for Shopify Admin GraphQL ${ADMIN_API_SUPPORTED_VERSIONS.join(' and ')} with default ${ADMIN_API_DEFAULT_VERSION}.`,
+    text: GETTING_STARTED_V4_TEXT,
+  },
+  {
+    topic: 'getting-started',
+    version: GETTING_STARTED_V5_VERSION,
+    uri: GETTING_STARTED_V5_URI,
+    name: 'Getting started with Meguro v5',
+    title: 'Getting started with Meguro v5',
+    description: `Version-policy evaluator sequence for Shopify Admin GraphQL ${ADMIN_API_SUPPORTED_VERSIONS.join(' and ')} with default ${ADMIN_API_DEFAULT_VERSION}.`,
+    text: GETTING_STARTED_V5_TEXT,
+  },
+  {
+    topic: 'getting-started',
+    version: GETTING_STARTED_V6_VERSION,
+    uri: GETTING_STARTED_V6_URI,
+    name: 'Getting started with Meguro v6',
+    title: 'Getting started with Meguro v6',
+    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: 'product-guide',
+    version: PRODUCT_GUIDE_VERSION,
+    uri: PRODUCT_GUIDE_URI,
+    name: 'Meguro product guide v1',
+    title: 'Meguro product guide v1',
+    description: 'Stable product concepts, evidence boundaries, surface responsibilities, and question-to-source routing.',
+    text: PRODUCT_GUIDE_TEXT,
+    expectedSha256: PRODUCT_GUIDE_SHA256,
+  },
+  {
+    topic: 'product-guide',
+    version: PRODUCT_GUIDE_V2_VERSION,
+    uri: PRODUCT_GUIDE_V2_URI,
+    name: 'Meguro product guide v2',
+    title: 'Meguro product guide v2',
+    description: 'Stable product concepts, simulation vocabulary, evidence boundaries, surface responsibilities, and question-to-source routing.',
+    text: PRODUCT_GUIDE_V2_TEXT,
+  },
+  {
+    topic: 'product-guide',
+    version: PRODUCT_GUIDE_V3_VERSION,
+    uri: PRODUCT_GUIDE_V3_URI,
+    name: 'Meguro product guide v3',
+    title: 'Meguro product guide v3',
+    description: 'World-first product concepts, evidence boundaries, surface responsibilities, and question-to-source routing.',
+    text: PRODUCT_GUIDE_V3_TEXT,
+  },
   {
     topic: 'receipt-guide',
     version: RECEIPT_GUIDE_VERSION,
@@ -886,13 +1402,58 @@ const CATALOG = buildDocumentationCatalog([
   },
   {
     topic: 'receipt-guide',
-    version: RECEIPT_GUIDE_LATEST_VERSION,
-    uri: RECEIPT_GUIDE_LATEST_URI,
+    version: RECEIPT_GUIDE_V2_VERSION,
+    uri: RECEIPT_GUIDE_V2_URI,
     name: 'Meguro receipt guide v2',
     title: 'Meguro receipt guide v2',
     description: 'V1 receipt interpretation plus the Console-only account-deletion and public-id invalidation contract.',
     text: RECEIPT_GUIDE_V2_TEXT,
   },
+  {
+    topic: 'receipt-guide',
+    version: RECEIPT_GUIDE_V3_VERSION,
+    uri: RECEIPT_GUIDE_V3_URI,
+    name: 'Meguro receipt guide v3',
+    title: 'Meguro receipt guide v3',
+    description: 'V2 receipt interpretation plus the complete shared-receipt rejection-attribution field inventory.',
+    text: RECEIPT_GUIDE_V3_TEXT,
+  },
+  {
+    topic: 'receipt-guide',
+    version: RECEIPT_GUIDE_V4_VERSION,
+    uri: RECEIPT_GUIDE_V4_URI,
+    name: 'Meguro receipt guide v4',
+    title: 'Meguro receipt guide v4',
+    description: 'V3 receipt interpretation plus receipt-contained source totals for recomputing every impact money figure.',
+    text: RECEIPT_GUIDE_V4_TEXT,
+  },
+  {
+    topic: 'receipt-guide',
+    version: RECEIPT_GUIDE_LATEST_VERSION,
+    uri: RECEIPT_GUIDE_LATEST_URI,
+    name: 'Meguro receipt guide v5',
+    title: 'Meguro receipt guide v5',
+    description: 'V4 receipt interpretation plus environment-qualified public receipt delivery and exact-byte verification.',
+    text: RECEIPT_GUIDE_V5_TEXT,
+  },
+  {
+    topic: 'receipt-guide',
+    version: RECEIPT_GUIDE_V6_VERSION,
+    uri: RECEIPT_GUIDE_V6_URI,
+    name: 'Meguro receipt guide v6',
+    title: 'Meguro receipt guide v6',
+    description: 'V5 receipt interpretation republished with the simulation-run vocabulary and renamed lifecycle fields.',
+    text: RECEIPT_GUIDE_V6_TEXT,
+  },
+  {
+    topic: 'receipt-guide',
+    version: RECEIPT_GUIDE_V7_VERSION,
+    uri: RECEIPT_GUIDE_V7_URI,
+    name: 'Meguro receipt guide v7',
+    title: 'Meguro receipt guide v7',
+    description: 'V6 receipt interpretation plus explicit signed net-unit semantics for daily impact rows.',
+    text: RECEIPT_GUIDE_V7_TEXT,
+  },
   {
     topic: 'gate-policy',
     version: GATE_POLICY_VERSION,
@@ -902,6 +1463,15 @@ const CATALOG = buildDocumentationCatalog([
     description: 'Immutable named checks, receipt facts, thresholds, precedence, flip conditions, and self-gating guidance.',
     text: GATE_POLICY_TEXT,
   },
+  {
+    topic: 'gate-policy',
+    version: GATE_POLICY_V2_VERSION,
+    uri: GATE_POLICY_V2_URI,
+    name: 'Meguro Gate policy v2',
+    title: 'Meguro Gate policy v2',
+    description: 'Immutable named checks and flip conditions republished with the simulation-run vocabulary.',
+    text: GATE_POLICY_V2_TEXT,
+  },
 ]);
 
 export function documentationResources() {
@@ -916,13 +1486,73 @@ export function documentationByTopic(topic, version) {
   return CATALOG.readTopic(topic, version);
 }
 
+function documentationList(values, conjunction = 'and') {
+  if (values.length === 1) return String(values[0]);
+  if (values.length === 2) return `${values[0]} ${conjunction} ${values[1]}`;
+  return `${values.slice(0, -1).join(', ')}, ${conjunction} ${values.at(-1)}`;
+}
+
+export function deriveDocumentationToolContract(resources) {
+  if (!Array.isArray(resources) || resources.length === 0) {
+    throw new Error('Documentation tool contract requires at least one published resource');
+  }
+  const byTopic = new Map();
+  const seen = new Set();
+  for (const resource of resources) {
+    const topic = String(resource?._meta?.['meguro/topic'] ?? '').trim();
+    const version = Number(resource?._meta?.['meguro/version']);
+    const description = String(resource?.description ?? '').trim();
+    if (!/^[a-z][a-z0-9-]{0,63}$/u.test(topic)) {
+      throw new Error(`Documentation resource has an invalid topic: ${topic || '(missing)'}`);
+    }
+    if (!Number.isSafeInteger(version) || version < 1) {
+      throw new Error(`Documentation resource ${resource?.uri ?? '(unknown)'} has an invalid version`);
+    }
+    if (!description) {
+      throw new Error(`Documentation resource ${resource?.uri ?? '(unknown)'} has no description`);
+    }
+    const key = `${topic}:v${version}`;
+    if (seen.has(key)) throw new Error(`Duplicate documentation tool contract entry: ${key}`);
+    seen.add(key);
+    const rows = byTopic.get(topic) ?? [];
+    rows.push({ version, description });
+    byTopic.set(topic, rows);
+  }
+
+  const topics = [...byTopic.keys()].sort(codepointCompare);
+  const versions = [...new Set([...byTopic.values()].flatMap((rows) => rows.map((row) => row.version)))]
+    .sort((left, right) => left - right);
+  const announcements = topics.map((topic) => {
+    const rows = byTopic.get(topic).sort((left, right) => left.version - right.version);
+    const latest = rows.at(-1);
+    return `${topic} versions [${rows.map((row) => row.version).join(', ')}] `
+      + `(latest v${latest.version}: ${latest.description.replace(/[.]+$/u, '')})`;
+  });
+  const topicList = documentationList(topics);
+  const versionList = documentationList(versions);
+  return deepFreeze({
+    topics,
+    versions,
+    description: `Read immutable Meguro product and simulation evidence documentation in-band. `
+      + `Published registry: ${announcements.join('; ')}. Account deletion is deliberately not an MCP tool. `
+      + 'Pass the exact published topic and version so cited documentation never resolves to mutable latest content.',
+    topicDescription: `Published Meguro simulation-documentation topic. Registry topics: ${topicList}.`,
+    versionDescription: `Published immutable simulation-documentation version. Registry versions: ${versionList}.`,
+    topicError: `topic must be ${documentationList(topics, 'or')}`,
+  });
+}
+
+export function documentationToolContract() {
+  return deriveDocumentationToolContract(documentationResources());
+}
+
 export function receiptGuideFieldManifest() {
   return deepFreeze({
     schemas() {
-      return Object.keys(RECEIPT_FIELDS).sort();
+      return Object.keys(RECEIPT_FIELDS_V7).sort();
     },
     schemaFields(schema) {
-      const fields = RECEIPT_FIELDS[schema];
+      const fields = RECEIPT_FIELDS_V7[schema];
       if (!fields) throw new Error(`Receipt schema not documented: ${schema}`);
       return [...fields];
     },