meguro-mcp 0.2.7 → 0.2.9

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to `meguro-mcp` are recorded here. Versions follow Semantic Versioning.
 
+## 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
+  without guessing a store or run identifier.
+- Exposes `admin_schema` through the hosted-safe registry, corrects hosted OAuth connection
+  guidance, and adds immutable documentation currency/index metadata.
+- Changes no earlier immutable documentation byte stream and carries no unrelated tool or protocol
+  behavior beyond the landed MEG-768 cold-walk corrections.
+
 ## 0.2.7 — 2026-08-08
 
 - Adds the optional `storeId` selector to `gate_evaluate` and `gate_verdict`, preserving every

package/README.md

@@ -43,7 +43,7 @@ Console provides fast trusted proof and evidence inspection; the agency agent no
 
 <!-- BEGIN GENERATED MCP TOOL TABLE -->
 <!-- Run `npm run docs:tools --workspace meguro-mcp` to refresh this section from `tools/list`. -->
-This table is generated from the server's live `tools/list` response (46 tools).
+This table is generated from the server's live `tools/list` response (47 tools).
 
 | Tool | Title | Behavior annotations |
 |---|---|---|
@@ -84,6 +84,7 @@ This table is generated from the server's live `tools/list` response (46 tools).
 | `exam_status` | Read Shopify Exam status | read-only · non-destructive · idempotent · closed-world |
 | `exam_report` | Read a Shopify Exam receipt | read-only · non-destructive · idempotent · closed-world |
 | `practice_run_start` | Start a practice run | read-write · non-destructive · non-idempotent · closed-world |
+| `practice_runs_list` | List practice runs | read-only · non-destructive · idempotent · closed-world |
 | `practice_run_status` | Read practice-run status | read-only · non-destructive · idempotent · closed-world |
 | `practice_run_checkpoint` | Capture a practice-run checkpoint | read-write · non-destructive · non-idempotent · closed-world |
 | `practice_run_advance` | Advance store time | read-write · non-destructive · non-idempotent · closed-world |
@@ -181,11 +182,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.7
+npx -y meguro-mcp@0.2.9
 ```
 
 ### Environment
@@ -203,7 +204,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.7
+  -- npx -y meguro-mcp@0.2.9
 ```
 
 ### Register — Cursor (`.cursor/mcp.json`)
@@ -213,7 +214,7 @@ claude mcp add meguro \
   "mcpServers": {
     "meguro": {
       "command": "npx",
-      "args": ["-y", "meguro-mcp@0.2.7"],
+      "args": ["-y", "meguro-mcp@0.2.9"],
       "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.7",
+  "version": "0.2.9",
   "private": false,
   "type": "module",
   "description": "Meguro control-plane MCP server: drive worlds, runs, and verdicts from your own AI tools.",

package/src/docs.mjs

@@ -20,9 +20,11 @@ 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 PRODUCT_GUIDE_VERSION = 1;
 const PRODUCT_GUIDE_V2_VERSION = 2;
 const PRODUCT_GUIDE_V3_VERSION = 3;
+const PRODUCT_GUIDE_V4_VERSION = 4;
 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}`;
@@ -38,11 +40,61 @@ const GETTING_STARTED_LATEST_URI = `meguro://docs/getting-started/v${GETTING_STA
 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 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}`;
+export const DOCUMENTATION_INDEX_URI = 'meguro://docs/index/v1';
+export const DOCUMENTATION_INDEX_V2_URI = 'meguro://docs/index/v2';
+
+const DOCUMENTATION_CURRENCY_V1 = deepFreeze({
+  indexVersion: 1,
+  currentUriByTopic: {
+    'gate-policy': GATE_POLICY_V2_URI,
+    'getting-started': GETTING_STARTED_V6_URI,
+    index: DOCUMENTATION_INDEX_URI,
+    'product-guide': PRODUCT_GUIDE_V3_URI,
+    'receipt-guide': RECEIPT_GUIDE_V7_URI,
+  },
+});
+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 CURRENT_DOCUMENTATION_CURRENCY = DOCUMENTATION_CURRENCY_V2;
+
+function documentationVersionFromUri(uri) {
+  const match = /\/v([1-9][0-9]*)$/u.exec(uri);
+  if (!match) throw new Error(`Documentation URI has no immutable version: ${uri}`);
+  return Number(match[1]);
+}
+
+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: \`${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.',
+    '',
+    '| Family | Current version | Current resource |',
+    '| --- | ---: | --- |',
+    ...rows.map(([topic, uri]) => `| ${topic} | v${documentationVersionFromUri(uri)} | ${uri} |`),
+  ].join('\n');
+}
 
-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 })\`.`;
+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)} })\`.`;
 export const PRODUCT_GUIDE_SHA256 = 'e5450c1b4181cec4d6ed0a498dbff1cb25d2e223ff2228928aecbbce9674f074';
 
 function deepFreeze(value) {
@@ -1211,6 +1263,38 @@ 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 RECEIPT_GUIDE_V6_TEXT = simulationVocabularyText(
   RECEIPT_GUIDE_V5_TEXT
     .replace('# Meguro receipt guide v5', '# Meguro receipt guide v6')
@@ -1262,13 +1346,13 @@ function entry(input) {
     name: input.name,
     title: input.title,
     description: input.description,
-    mimeType: 'text/markdown',
+    mimeType: input.mimeType ?? 'text/markdown',
     text,
     sha256: digest,
   });
 }
 
-export function buildDocumentationCatalog(inputs) {
+export function buildDocumentationCatalog(inputs, currency) {
   const rows = inputs.map(entry).sort((left, right) => codepointCompare(left.uri, right.uri));
   const byUri = new Map();
   const byTopicVersion = new Map();
@@ -1279,6 +1363,19 @@ export function buildDocumentationCatalog(inputs) {
     byUri.set(row.uri, row);
     byTopicVersion.set(key, row);
   }
+  const currentUriByTopic = currency?.currentUriByTopic ?? Object.fromEntries(
+    [...new Set(rows.map((row) => row.topic))].map((topic) => {
+      const current = rows.filter((row) => row.topic === topic).sort((left, right) => left.version - right.version).at(-1);
+      return [topic, current.uri];
+    }),
+  );
+  for (const topic of new Set(rows.map((row) => row.topic))) {
+    const currentUri = currentUriByTopic[topic];
+    const current = byUri.get(currentUri);
+    if (!current || current.topic !== topic) {
+      throw new Error(`Documentation currency has no valid current resource for ${topic}`);
+    }
+  }
   return deepFreeze({
     list() {
       return rows.map((row) => deepFreeze({
@@ -1292,6 +1389,8 @@ export function buildDocumentationCatalog(inputs) {
           'meguro/topic': row.topic,
           'meguro/version': row.version,
           'meguro/sha256': row.sha256,
+          'meguro/status': row.uri === currentUriByTopic[row.topic] ? 'current' : 'superseded',
+          'meguro/current-uri': currentUriByTopic[row.topic],
         },
       }));
     },
@@ -1363,6 +1462,15 @@ 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: 'product-guide',
     version: PRODUCT_GUIDE_VERSION,
@@ -1391,6 +1499,33 @@ 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: 'index',
+    version: DOCUMENTATION_CURRENCY_V1.indexVersion,
+    uri: DOCUMENTATION_INDEX_URI,
+    name: 'Meguro documentation index v1',
+    title: 'Meguro documentation index v1',
+    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: 'receipt-guide',
     version: RECEIPT_GUIDE_VERSION,
@@ -1472,7 +1607,7 @@ const CATALOG = buildDocumentationCatalog([
     description: 'Immutable named checks and flip conditions republished with the simulation-run vocabulary.',
     text: GATE_POLICY_V2_TEXT,
   },
-]);
+], CURRENT_DOCUMENTATION_CURRENCY);
 
 export function documentationResources() {
   return CATALOG.list();

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.7' };
+const SERVER_INFO = { name: 'meguro', version: '0.2.9' };
 const PROTOCOL_VERSION = '2025-03-26';
 
 const tools = createTools({

package/src/tools.mjs

@@ -26,6 +26,7 @@ const DOCUMENTATION_TOOL_CONTRACT = documentationToolContract();
 const DOCUMENTATION_TOPICS = new Set(DOCUMENTATION_TOOL_CONTRACT.topics);
 const FLEET_TOOL_NAMES = new Set([
   'templates_list', 'stores_list', 'store_create', 'store_delete', 'store_passport',
+  'practice_runs_list',
   'workspaces_list', 'workspace_create', 'workspace_archive', 'workspace_unarchive',
   'share_create', 'shares_list', 'share_status', 'share_publish', 'share_revoke',
   'catalog_slice_read', 'catalog_slice_snapshot', 'catalog_slices_saved',
@@ -69,6 +70,7 @@ const TOOL_PRESENTATION = Object.freeze({
   exam_status: { title: 'Read Shopify Exam status', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
   exam_report: { title: 'Read a Shopify Exam receipt', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
   practice_run_start: { title: 'Start a practice run', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+  practice_runs_list: { title: 'List practice runs', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
   practice_run_status: { title: 'Read practice-run status', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
   practice_run_checkpoint: { title: 'Capture a practice-run checkpoint', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
   practice_run_advance: { title: 'Advance store time', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
@@ -832,13 +834,94 @@ function runsListProjection(value, lifecycle) {
     ...(visible.length === 0 ? {
       emptyState: {
         message: `No ${lifecycle ?? 'matching'} Shopify dev-store history runs were found. This says nothing about practice simulation attempts.`,
-        practiceAttemptRecovery: 'For a known practice simulation attemptId, call practice_run_report and practice_run_impact. To discover an attemptId, open the Console Runs/Receipts view; MCP has no practice-attempt list tool today.',
+        practiceAttemptRecovery: 'Call practice_runs_list to discover practice simulation attempts, then pass one exact attemptId to practice_run_report or practice_run_impact.',
       },
     } : {}),
     clockDiscipline: 'runClock names lifecycle timestamps; worldClock names scenario coordinates and does not invent an unreported Store-time.',
   });
 }
 
+function practiceRunsSelectionError(storeIds) {
+  const multiple = storeIds.length > 1;
+  const meaning = multiple
+    ? `This workspace has more than one practice store (${storeIds.length}), so Meguro cannot infer which store's practice runs to list`
+    : 'This workspace has no practice store, so there are no store-owned practice runs to list';
+  const nextStep = multiple
+    ? 'Call stores_list({}), choose one exact storeId, then call practice_runs_list({ storeId: "<exact storeId>" }). You may instead provide a known receiptId so Meguro can derive its owning store.'
+    : 'Create a practice store first, then call practice_runs_list with its storeId or with a receiptId from one of its runs.';
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify({
+        code: 'store-selection-required',
+        storeIds,
+        errors: [{ code: 'store-selection-required', message: `Store selection required. ${meaning}. ${nextStep}`, meaning, nextStep }],
+      }, null, 2),
+    }],
+    isError: true,
+  };
+}
+
+function practiceRunReceiptSelectionError(receiptId) {
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify({
+        code: 'receipt-unavailable',
+        errors: [{
+          code: 'receipt-unavailable',
+          message: `Practice receipt ${receiptId} is not available in this workspace.`,
+          meaning: 'The receipt does not identify a retained practice run owned by this workspace.',
+          nextStep: 'Call practice_runs_list with an exact current storeId, or use a receiptId returned by a prior practice_runs_list or practice_run_report response.',
+        }],
+      }, null, 2),
+    }],
+    isError: true,
+  };
+}
+
+function practiceRunReceiptStoreMismatch(receiptId, receiptStoreId, requestedStoreId) {
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify({
+        code: 'receipt-store-mismatch',
+        errors: [{
+          code: 'receipt-store-mismatch',
+          message: `Receipt and storeId identify different practice stores. Receipt ${receiptId} belongs to ${receiptStoreId}, not ${requestedStoreId}.`,
+          meaning: `Receipt ${receiptId} belongs to store ${receiptStoreId}, not ${requestedStoreId}.`,
+          nextStep: `Retry with storeId ${receiptStoreId}, or omit storeId and let Meguro derive it from receiptId ${receiptId}.`,
+        }],
+      }, null, 2),
+    }],
+    isError: true,
+  };
+}
+
+function practiceRunsProjection(value, storeId, storeSelection) {
+  const attempts = Array.isArray(value?.playbacks) ? value.playbacks : [];
+  return secretSafe({
+    schemaVersion: 'meguro.practice-run-list.v1',
+    storeId,
+    storeSelection,
+    attempts: attempts
+      .filter((attempt) => attempt?.storeId === storeId || attempt?.worldId === storeId)
+      .map((attempt) => ({
+        attemptId: attempt.attemptId,
+        state: attempt.status,
+        clock: {
+          mode: attempt.clock?.mode ?? null,
+          baselineDay: attempt.baselineDay ?? null,
+          watermarkDay: attempt.watermarkDay ?? null,
+          simulationDays: attempt.simulationDays ?? attempt.clock?.simulationDays ?? null,
+          elapsedSimulationDays: attempt.elapsedSimulationDays ?? null,
+          remainingSimulationDays: attempt.remainingSimulationDays ?? null,
+        },
+        receiptRef: { attemptId: attempt.attemptId },
+      })),
+  });
+}
+
 function practiceAttemptComparisonGuidanceFor(toolName, a, b) {
   const attemptIds = [a, b].filter((id) => PRACTICE_ATTEMPT_ID.test(id));
   const calls = attemptIds.flatMap((attemptId) => [
@@ -900,6 +983,21 @@ function practiceStoreConnectionNotFoundGuidance(storeId) {
   };
 }
 
+function practiceRunsStoreNotFoundGuidance(storeId) {
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify({
+        code: 'practice-store-not-found',
+        message: `practice_runs_list could not find practice store ${storeId} in this account or the store is no longer active.`,
+        nextAction: 'Call stores_list({}) and use an exact current storeId from the returned stores array.',
+        stopCondition: `If stores_list({}) returns no current stores, stop: there is no practice store whose attempts can be listed. Do not retry ${JSON.stringify(storeId)}.`,
+      }, null, 2),
+    }],
+    isError: true,
+  };
+}
+
 function legacyGateArtifactNotFoundGuidance(runId) {
   return {
     content: [{
@@ -957,6 +1055,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,
@@ -1881,7 +1984,7 @@ export function createTools(config) {
     },
     {
       name: 'runs_list',
-      description: 'List Shopify dev-store history runs created by run_start so an agent can re-find that family of prior work. It does not list practice simulation attempts returned by practice_run_start; those use pa-* ids, practice_run_report, and practice_run_impact, while attempt discovery lives in the Console Runs/Receipts view today. Optional history-run lifecycle filtering supports running, paused, completed, failed, or cleaning. An empty result explicitly says it is only about history runs. The payload names run-clock lifecycle timestamps separately from world-clock scenario coordinates and returns no filter counts.',
+      description: 'List Shopify dev-store history runs created by run_start so an agent can re-find that family of prior work. It does not list practice simulation attempts returned by practice_run_start; call practice_runs_list for those pa-* ids, then use practice_run_report or practice_run_impact. Optional history-run lifecycle filtering supports running, paused, completed, failed, or cleaning. An empty result explicitly says it is only about history runs. The payload names run-clock lifecycle timestamps separately from world-clock scenario coordinates and returns no filter counts.',
       inputSchema: {
         type: 'object',
         additionalProperties: false,
@@ -1992,6 +2095,20 @@ export function createTools(config) {
         anyOf: [{ required: ['storeId'] }, { required: ['worldId'] }],
       },
     },
+    {
+      name: 'practice_runs_list',
+      description: 'List bounded practice simulation attempt facts for one exact practice store: attemptId, lifecycle state, Store-clock summary, and a receiptRef that can be passed unchanged to practice_run_report. Store selection follows one fail-closed ladder: receiptId derives its owning store; otherwise an explicit storeId wins; omission is allowed only when the workspace has exactly one current store; zero or multiple stores return a structured store-selection-required error and never choose silently. An OAuth grant may select an owned workspace; an account API key remains bound to its own workspace.',
+      inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          workspaceId: { type: 'string', minLength: 1, description: 'Optional OAuth selector for an account-owned non-default workspace. An account API key can name only its bound workspace.' },
+          storeId: { ...PRACTICE_STORE_ID_INPUT_SCHEMA, description: 'Optional exact practice-store id from stores_list. Omit only with receiptId or when the workspace has exactly one current store.' },
+          receiptId: { type: 'string', minLength: 4, maxLength: 128, pattern: '^pa-[a-z0-9][a-z0-9-]{0,124}$', description: 'Optional known pa-* practice receipt identity. Meguro derives its owning store and refuses a conflicting storeId.' },
+        },
+        required: [],
+      },
+    },
     {
       name: 'practice_run_status',
       description: 'Read the server-authoritative state of an external-agent practice simulation run, including its announced simulation-run deadlines and immutable simulation run receipt after any exit. Use Console for quick proof; the tested agent remains in the caller\'s environment.',
@@ -2059,7 +2176,7 @@ export function createTools(config) {
     },
     {
       name: 'get_connection_details',
-      description: `Fetch connection material for supported Shopify Admin GraphQL versions ${ADMIN_API_SUPPORTED_VERSION_LABEL}; the default is ${ADMIN_API_DEFAULT_VERSION}. Returns adminApiVersion (default), adminApiVersions (supported set), adminVersions (exact versioned URLs), the default URL, access token, and shop domain for an existing Meguro practice store so an assistant can configure a user agent without opening the dashboard. Inspect the selected version with admin_schema before the first Admin call; an agent targeting a newer Shopify release outside the supported set must treat that behavior as not established. Takes the canonical practice-store id (storeId) and returns it back, so the result passes directly into practice_run_start({ storeId }) — no identifier translation. The practice-store id is not an attemptId (run identity). Requires an account API key because it reveals the per-store token.`,
+      description: `Fetch connection material for supported Shopify Admin GraphQL versions ${ADMIN_API_SUPPORTED_VERSION_LABEL}; the default is ${ADMIN_API_DEFAULT_VERSION}. Returns adminApiVersion (default), adminApiVersions (supported set), adminVersions (exact versioned URLs), the default URL, access token, and shop domain for an existing Meguro practice store so an assistant can configure a user agent without opening the dashboard. Inspect the selected version with admin_schema before the first Admin call; an agent targeting a newer Shopify release outside the supported set must treat that behavior as not established. Takes the canonical practice-store id (storeId) and returns it back, so the result passes directly into practice_run_start({ storeId }) — no identifier translation. The practice-store id is not an attemptId (run identity). The hosted MCP path uses the caller's OAuth grant; the public STDIO path uses its workspace-bound account API key.`,
       inputSchema: {
         type: 'object',
         additionalProperties: false,
@@ -2630,6 +2747,50 @@ export function createTools(config) {
             ...consoleUrlFields(started.consoleRef, started.consoleRefExpiresAt),
           }));
         }
+        case 'practice_runs_list': {
+          const workspaceId = optionalWorkspaceId(args);
+          const requestedStoreId = args.storeId === undefined
+            ? undefined
+            : validatedStoreId(requiredString(args, 'storeId'), 'storeId');
+          const receiptId = args.receiptId === undefined
+            ? undefined
+            : requiredPracticeAttemptId(args, 'receiptId');
+          if (receiptId) {
+            const listed = await fleetRequest(name, 'GET', '/practice/playbacks', undefined, { workspaceId });
+            if ('error' in listed) return listed.error;
+            const playbacks = Array.isArray(listed.value?.playbacks) ? listed.value.playbacks : [];
+            const referenced = playbacks.find((attempt) => attempt?.attemptId === receiptId);
+            if (!referenced) return practiceRunReceiptSelectionError(receiptId);
+            const receiptStoreId = String(referenced.storeId ?? referenced.worldId ?? '');
+            if (requestedStoreId && requestedStoreId !== receiptStoreId) {
+              return practiceRunReceiptStoreMismatch(receiptId, receiptStoreId, requestedStoreId);
+            }
+            return textResult(practiceRunsProjection(listed.value, receiptStoreId, 'receipt-derived'));
+          }
+
+          const fleet = await fleetRequest(name, 'GET', '/practice/stores', undefined, { workspaceId });
+          if ('error' in fleet) return fleet.error;
+          const storeIds = [...new Set((Array.isArray(fleet.value?.stores) ? fleet.value.stores : [])
+            .map((store) => String(store?.storeId ?? store?.worldId ?? '').trim())
+            .filter((storeId) => /^[a-z0-9-]+$/u.test(storeId)))].sort();
+
+          if (requestedStoreId && !storeIds.includes(requestedStoreId)) {
+            return practiceRunsStoreNotFoundGuidance(requestedStoreId);
+          }
+          if (!requestedStoreId && storeIds.length !== 1) {
+            return practiceRunsSelectionError(storeIds);
+          }
+
+          const listPath = queryPath('/practice/playbacks', { worldId: requestedStoreId ?? storeIds[0] });
+          const listed = await fleetRequest(name, 'GET', listPath, undefined, { workspaceId });
+          if ('error' in listed) return listed.error;
+          const selectedStoreId = requestedStoreId ?? storeIds[0];
+          return textResult(practiceRunsProjection(
+            listed.value,
+            selectedStoreId,
+            requestedStoreId ? 'explicit-store-id' : 'single-store',
+          ));
+        }
         case 'practice_run_status': {
           const attemptId = requiredPracticeAttemptId(args);
           const response = await practiceApi('GET', `/practice/playbacks/${encodeURIComponent(attemptId)}/state`);