Contents

Start here

Meet Meguro's practice store

Meguro gives your agent a Shopify-shaped practice store with modeled history and a Store clock that moves only inside a run.

Use this when

Use this orientation before your first run or when reviewing a Meguro claim.

Before you start

Choose the agent behavior you want to inspect. Meguro is a simulation environment, not a forecast or certification service.

Steps

Evaluate whether the client can connect to the declared Admin GraphQL surface and make the intended reads or writes.
Inspect observed calls separately from modeled commerce consequences.
Read every not established statement before carrying evidence into a release conversation.

Success looks like

You can state exactly what the agent attempted, what the practice surface accepted or rejected, and what modeled store state changed.

If it fails

Unsupported calls fail loudly. A zero-write run does not establish impact, and a practice receipt does not prove future demand, production performance, certification, or full Shopify parity.

Next action

Continue to Drive your first practice store.

Start here

Drive your first practice store

Create a store with modeled history, connect your agent, and drive it through one bounded simulation. The store hands you a receipt at the end.

Use this when

Use this when you want the shortest path from a new practice store to inspectable evidence.

Before you start

For an MCP agent, open Connection settings and copy the agent instruction. Approve access when it asks. For an existing Shopify Admin client, use the steps below.

Steps

Create a practice store. Choose a scenario for the job you want your agent to handle and read its brief.
Confirm connection with one authenticated read. Point the client at the store Admin URL and token.
Start a run. Choose who controls Store time and open the observation window.
Run the agent. Have it carry out the scenario's brief through the planned Store days, using the clock you chose.
Open the receipt. Review recorded behavior, modeled change, and proof boundaries.

Success looks like

The receipt opens with the expected store, agent/run identity, recorded calls, and an explicit evidence boundary.

If it fails

If the first read is not recorded, stop: recheck the Admin URL, send the whole per-store token as X-Shopify-Access-Token, and retry the read before starting another run.

Next action

Open Meguro and create a practice store.

Start here

When not to use Meguro

Meguro is deliberately narrow. It is the wrong tool when:

Scope and proof boundaries

You need proof of live performance. Receipts are rehearsal evidence from a simulated store — not forecasts, certifications, or evidence of market demand. Meguro says this in-band because it's true.

Your critical path lives outside the modeled subset. Meguro models a subset of the Shopify Admin API and refuses the rest with a teaching error rather than faking behavior. If the calls your app depends on aren't in the modeled subset — the refusal enumerates it, and Supported Admin GraphQL surface lists it — Meguro cannot exercise them, and won't pretend to.

You're testing storefront pages, themes, or checkout UI. A practice store renders no pages. It serves two agent surfaces: the Admin-shaped API, and a shopper endpoint that models Storefront reads, cart, and a checkout that ends at the buyer handoff. Payment placement is out.

You're load-testing. Meguro models Shopify's request cost bucket, so throttling and backoff show up on the receipt. It measures no latency or capacity and benchmarks nothing.

Your agent only reads. If it reads a catalog once and writes nothing, a fixture file is cheaper. An agent that writes gets a full receipt without moving Store time. Time matters only for modeled consequences.

You want someone to run your agent for you. Meguro never executes your agent; it provides the store and the record. Bring your own agent — that's the design, not a gap.

Connect and run

Choose a practice store

Match the store and scenario to the agent job before you start collecting evidence.

Use this when

Use this when selecting a practice store for pricing, inventory, fulfillment, retention, or catalog work. Return/restocking, loyalty-credit, cohort, and cross-location transfer economics are internal modeled evidence, not provider operations to send.

Before you start

Read the scenario's brief and check that it matches the job you want your agent to handle.

Steps

Pricing or promotion: choose demand and margin pressure with supported Product or variant price actions.
Inventory: choose low-stock or replenishment pressure.
Order cash refund: choose a canonical committed order with priced committed lines. Return and restocking economics stay internal modeled evidence.
Fulfillment: choose backlog, SLA, or shipping-threshold pressure.
Retention: choose modeled winback or abandoned-checkout pressure. Cohort, loyalty-credit, and response economics stay internal modeled evidence; no Shopify transaction-discount action is served.
Catalog: choose launch, metadata, bundle, or subscription-plan work.

Agent job	Modeled pressure	Meaningful actions to exercise
Pricing	Demand and margin response	Product and variant price changes
Inventory	Stockouts and incoming supply	Adjust available inventory at one location
Order cash refund	Canonical committed order with priced committed lines	Issue a line-item cash refund; inspect separately labelled return/restocking evidence
Fulfillment	Backlog and delivery thresholds	Fulfill an order or adjust a delivery profile
Retention	Modeled winback or abandoned-checkout pressure	Analyze modeled response evidence; no Shopify transaction-discount action is served
Catalog	Launch and content quality	Update product data, variants, or metafields

Success looks like

The scenario's brief matches your agent's job, and the required calls are supported.

If it fails

If a required call is unsupported, record the gap. Choose another scenario only if its brief still matches the job you need to rehearse.

Next action

Continue to Connect your agent over MCP, or Connect an existing Shopify Admin client.

Connect and run

Connect your agent over MCP

Connect your own agent to Meguro’s hosted MCP server, approve access, and choose a practice scenario.

Use this when

Use this when your agent speaks MCP. Meguro runs one hosted server; there is no Meguro package to install or local Meguro STDIO server to start.

Before you start

Use this hosted endpoint, including /mcp: https://mcp-dev.meguro.io/mcp.

Have a Meguro account, or create one during browser sign-in. An accepted ordinary start reserves one monthly simulation run, counted as used while open; it is charged only when the run completes or is stopped after agent execution, even if agent checks fail. Refused starts reserve none; cancellation, expiration, failure before agent execution, and completion or stopping without agent execution release the reservation. Your included first evaluation and its authorized continuations, the automatic sample, and practice-world upkeep use no monthly run. Each ordinary Builder continuation is a separate start under the same rule; a plain start after the included evaluation ends is ordinary. A problem after execution has no separate exemption; settlement follows how the run ends.

Browser consent and permissions

Sign in and approve only the requested access. Every browser approval creates a fresh grant; reconnecting does not replace or revoke older grants. The consent screen names the permissions it requests:

View your practice stores
Create and delete practice stores
Read practice runs and receipts
Start, advance, finish, and clean up practice runs
Read store connection tokens

Workspace API key alternative

Clients that support authorization headers can use a workspace API key instead of OAuth. Create it in Console → Settings → API keys and configure Authorization: Bearer <workspace API key> in the client’s protected credential or header settings. The key remains bound to its workspace. Do not use a per-store Admin token, paste browser tokens or cookies, or put a key in a launch command, receipt or support message.

usage_read needs the owner OAuth grant and refuses a workspace API key; a key-authenticated client reads usage and caps in Console → Usage instead.

Steps

Claude.ai connectors

In Claude.ai, open Customize → Connectors, select + → Add custom connector, enter https://mcp-dev.meguro.io/mcp, and select Add. On Team or Enterprise, an owner first adds the Web custom connector in Organization settings → Connectors; members then select Connect.
Connect and complete Meguro’s browser sign-in and consent. In a conversation, open + → Connectors and enable Meguro.

Official Claude connector instructions.

Claude Code

Run claude mcp add --transport http meguro https://mcp-dev.meguro.io/mcp.
Open Claude Code, run /mcp, select Meguro and complete browser authentication. Confirm it is connected before asking it to act.

Official Claude Code instructions.

Cursor

Select Add Meguro to Cursor, then review and accept Cursor’s server-install prompt. The link configures the same hosted endpoint shown above.
Complete browser authentication when prompted and enable the server for your agent.

Official Cursor install-link instructions.

ChatGPT web

Open Settings → Security and login and enable Developer mode. Availability depends on your account and workspace policy.
Open Plugins, select +, enter the name Meguro and a description, and enter https://mcp-dev.meguro.io/mcp under Connection as a public MCP server URL. Create the connection and complete browser consent.
Start a new conversation and add the MCP connection from the tools menu.

Official ChatGPT connection instructions.

Codex and the ChatGPT desktop app

For the CLI, run codex mcp add meguro --url https://mcp-dev.meguro.io/mcp, then codex mcp login meguro and complete browser consent.
Alternatively, in the desktop app open Settings → MCP servers → Add server, name it Meguro, select Streamable HTTP and enter https://mcp-dev.meguro.io/mcp. Save, select Restart, then Authenticate. The desktop app, CLI and IDE extension share the host’s MCP configuration.

Official Codex and desktop instructions.

Compatibility bridge

If your client accepts only a command, configure npx -y mcp-remote https://mcp-dev.meguro.io/mcp as its MCP launch command and complete browser consent. This is a third-party bridge to the hosted server, not a local Meguro server. Prefer the direct URL when your client supports it. Bridge instructions.

Success looks like

The client lists Meguro’s tools. Ask it: “Choose a practice scenario, read its brief, and do what the brief asks. Bring me back the receipt link.” It should read the server-owned scenario and run plan before starting.

If it fails

If authentication fails, confirm the endpoint includes /mcp and reconnect through your client’s authentication control. Reauthorization creates a fresh grant; revoke any older grants you no longer want. A client that lacks remote HTTP support needs the compatibility bridge above.

Next action

Review and revoke access at Console account menu → Authorized clients. Revocation stops refresh immediately; an issued access token can remain valid for up to 15 minutes. Remove the connection in your client separately to clear its local configuration.

Connect and run

Connect an existing Shopify Admin client

Keep the client you already use; change only its Admin URL and per-store token.

Use this when

Use this when connecting a Shopify Admin GraphQL client to one practice store.

Before you start

Create the store first. Keep the workspace API key separate from the per-store Admin token.

Steps

Open the store’s Connect view and copy its Admin GraphQL URL and per-store Admin token.
Set the client’s Admin endpoint to that URL and send the token as X-Shopify-Access-Token.
Send one authenticated read such as a shop identity query. Reads work before a run.
Wait for Meguro to record the first call, then start the run before sending writes.

Success looks like

The connection listener records the read against the intended store without exposing either credential in a receipt.

If it fails

What happened: no read appeared. What it means: the process may be using a different URL or clipped token. What to do next: copy both fields again, confirm the header, and retry one read. Writes outside an active run are rejected.

Next action

Continue to Choose Store time, or open Stores and re-enter this store’s Overview.

Connect and run

Choose Store time

Pick Manual or Scheduled Store time for your run.

Use this when

Use this when starting a run that needs modeled events over time and you must choose its store clock.

Before you start

Time moves as your run drives it. Choose Manual when you need an explicit advance, or Scheduled when the next qualifying run request should materialize elapsed Store time.

Steps

Mode	Control	Use it when
Manual	You explicitly advance Store time	You want to inspect each boundary before moving on
Scheduled	The next qualifying run request materializes elapsed Store time	You want elapsed time to catch up as your run continues

Success looks like

The active run displays its chosen clock, current modeled day, and next allowed action.

If it fails

If a Manual advance is rejected, refresh the run state and copy its fresh practiceRun.advanceCursor object unchanged. Scheduled time does not advance an idle run in the background.

Next action

Continue to Exercise and finish a run. In Meguro, select the store and continue from its Overview or Runs tab.

Connect and run

Exercise and finish a run

Have your agent carry out the scenario's brief through the planned Store days, then inspect the receipt.

Use this when

Use this after a read has confirmed connection and the run is active.

Before you start

Read the scenario's brief and run plan. Check that the required calls are on the supported Admin GraphQL surface.

Steps

Have your agent carry out the scenario's brief.
Inspect which calls were accepted, rejected, or unsupported, and what state changed.
Time moves as your run drives it. In Manual mode, explicitly advance time; in Scheduled mode, elapsed time is materialized on the next qualifying run request.
At the planned end, follow the run's completion instructions and open the receipt. If the run needs to stop early, cancel it and review the partial evidence.

Success looks like

The concluded receipt distinguishes accepted calls, blocked calls, state deltas, and empty or partial evidence.

If it fails

A zero-write simulation run does not establish impact. Cancellation preserves evidence already recorded. An accepted ordinary start reserves one monthly simulation run, counted as used while open; it is charged only when the run completes or is stopped after agent execution, even if agent checks fail. Refused starts reserve none; cancellation, expiration, failure before agent execution, and completion or stopping without agent execution release the reservation. Your included first evaluation and its authorized continuations, the automatic sample, and practice-world upkeep use no monthly run. Each ordinary Builder continuation is a separate start under the same rule; a plain start after the included evaluation ends is ordinary. A problem after execution has no separate exemption; settlement follows how the run ends.

Next action

Open Read the current receipt.

Understand the result

Read the current receipt

Interpret the customer hierarchy first, then move into evidence and developer details.

Use this when

Use this for any concluded receipt before sharing it or evaluating it with the Configured Gate.

Before you start

Read the Gate’s decision sealed in the receipt first. A receipt's sealed gate is go only when the run completed with recorded agent execution and at least one recorded Admin call, no rejected call remains unresolved, every exercised declared expected rejection held, every exercised declared time requirement was met, and every exercised named check whose subject is the agent held. Otherwise it is no-go. A check that was not exercised never decides the Gate, and neither does a check whose subject is Meguro or is not established. A canceled run and a run that stopped before completion are no-go; waiting exists only before the receipt seals. Console, MCP, the public and private receipt, the card, Markdown and CI all show this one sealed decision; do not derive another from calls, summaries or modeled outcome. Modeled outcome and money are separate facts. Confirm the store, scenario, seed, declared agent subject, client API target, execution environment, live verification state, and exercised operation scope. Customer-declared build identity is not independently verified by Meguro.

Steps

In the signed-in Console receipt view:

Read the Gate sentence for the Gate’s sealed decision, then Goal outcome for the separate modeled result.
Read Lane integrity for whether the run stayed inside the declared execution lane.
Read Footprint for calls, accepted and rejected writes, and modeled changes.
Inspect the Decisive moment and Next technical proof.
Use Evidence for reviewable facts and Developer details for protocols and debugging.
Classify claims as Observed, Modeled, or Not established.

These are Console section labels, not JSON fields. The public receipt document, Markdown at canonicalPath + .md or JSON with ?format=json, has no such sections. The Markdown opens with the lead sentence, then:

Mechanics: calls recorded, accepted and rejected, idempotent replays, committed store-state changes, run lifecycle, reversion evidence, and the recorded Admin API version.
Conduct: the Gate sentence, rejected-call counts and corrections, recorded API behavior, and each named check.
Scenario outcome: the modeled scenario outcome, comparison, horizon and basis, modeled money, and the scenario evidence boundary.
Recorded detail: Shared receipt facts, Result semantics, Counts, Rejected call forensics, What changed, and Timeline when present.

In the JSON, under the wrapper’s receipt member, the Gate decision is gate, named checks are assertionOutcomes, rejection counts and corrections are conductAuthority, changes are changes, counts are counts, the call timeline is timeline, Store time and recording times are time, and the lead sentence, the three plane blocks, the Recorded detail blocks and the Markdown text with its digest are under presentation. Read Receipt schema for every field path.

Success looks like

You can trace the result to recorded calls and explicitly bounded modeled consequences without upgrading simulation evidence into production proof.

If it fails

If the evidence is partial, identify the missing proof layer: agent contact, representative write, state delta, scenario source, or completion. Do not replace missing evidence with inference.

Next action

Continue to Share, retain, and verify receipt integrity, or select the store and reopen its Runs tab.

Understand the result

Share, retain, and verify receipt integrity

Verify artifact integrity without implying that a digest verifies the receipt’s result.

Use this when

Use this before sharing or retaining receipt evidence.

Before you start

Choose the customer-safe artifact and check its visibility, issuance time, and how many days your plan keeps receipts.

Steps

Copy the receipt’s public URL: the canonicalPath of its receipt reference, of the form https://<API host>/public/receipts/<receipt id>. The same reference’s sha256 is the published digest.
Fetch it with an unauthenticated GET, no credentials or headers, and save the response body exactly as received: curl -fsS -o receipt.json '<canonicalPath>?format=json'.
Compute SHA-256 over those saved bytes without reformatting or re-serializing them: shasum -a 256 receipt.json.
Compare the lowercase hex result with the reference’s sha256. The same value is served as source.digest at <canonicalPath>?view=report-back and in the response’s X-Meguro-SHA256 header. A match proves these bytes are unaltered; it does not validate the run’s result.
Retain the saved bytes in your own controlled evidence store if you need them after your plan stops keeping the receipt.
Review the evidence and proof-boundary text separately; digest validity does not validate the result.

Success looks like

The artifact bytes match their digest and the reviewer can identify what was observed, modeled, and not established.

If it fails

If the receipt is no longer fetchable, use a previously retained artifact. Never infer a result from an id or digest alone. Practice receipts do not prove future demand or full Shopify parity.

Next action

Read Use the Configured Gate to project the same sealed decision in CI.

Automate

Automate a practice run

Run the same bounded lifecycle from CI or hosted MCP without repository-only steps.

Use this when

Use this when the five-step practice loop must run repeatably outside the dashboard.

Before you start

Create a workspace API key for direct API calls, or authorize hosted MCP with OAuth. Keep control credentials out of the agent process; the agent receives only the store Admin URL and token.

Steps

Package-free CI: call the documented practice HTTP endpoints with your existing HTTP client; preserve failed artifacts and return a CI exit code owned by your policy.
Hosted MCP: connect with OAuth 2.1 to stateless Streamable HTTP /mcp. Clients without remote transport support can bridge to the hosted URL with npx -y mcp-remote <hosted MCP URL>; configure OAuth or a workspace key as standard Bearer authorization, never as a process argument.
Start, inspect status, capture checkpoints when needed, copy practiceRun.advanceCursor unchanged into advance, finish or cancel, and fetch the receipt.

Success looks like

Automation emits only copyable or downloadable artifacts, preserves the full receipt boundary, and never passes the workspace key to the agent under test.

If it fails

If a control call fails, record its status and bounded response, refresh status for the server-owned practiceRun.advanceCursor, and stop rather than manufacturing a successful artifact. The shopper-facing practice-store /api/mcp is a separate Storefront data plane, not the hosted control plane.

Next action

Add a Configured Gate check for the concluded receipt with Use the Configured Gate; keep any money threshold in your own CI step.

Automate

Use the Configured Gate

The Configured Gate projects the Gate’s decision sealed in the selected receipt; it does not decide whether you should ship.

Use this when

Use this when CI or Console should read the same Gate decision already sealed with a concluded run receipt.

Before you start

Choose the Store and receipt. Configured Gate needs no caller-defined criteria or policy version. Keep a modeled-money threshold separate and customer-owned.

Before a secret-bearing CI job, download Meguro CI kit v2 from the public marketing site, verify its pinned SHA-256, unpack it as byo-ci-test/, review it, and commit that directory. CI runs the vendored files; it never downloads executable code after secrets are supplied.

curl -fsS -o meguro-ci-kit-v2.tar.gz https://site-dev.meguro.io/downloads/meguro-ci-kit-v2.tar.gz
curl -fsS -o meguro-ci-kit-v2.tar.gz.sha256 https://site-dev.meguro.io/downloads/meguro-ci-kit-v2.tar.gz.sha256
printf '%s  %s\n' '37ca683e4373b8f25ac04723e1f67853f7a6e123ac46a233634cb277921f5de4' 'meguro-ci-kit-v2.tar.gz' | cmp - meguro-ci-kit-v2.tar.gz.sha256
shasum -a 256 -c meguro-ci-kit-v2.tar.gz.sha256
tar -xzf meguro-ci-kit-v2.tar.gz
git add byo-ci-test/

Steps

Select one Store and its concluded receipt.
Read or evaluate the Configured Gate; the response carries policy meguro.release-gate-policy.v2 and the receipt’s own go/no-go sentence.
Fail CI when the Gate is no-go. If your business rule also requires nonnegative net contribution, add a separate command that checks the receipt’s modeled value.
Retain the receipt and Gate evaluation together so the decision remains traceable.

Success looks like

The Configured Gate response and the receipt display one Gate decision. Modeled outcome, catalog source, and money remain separate facts; you own the release decision.

If it fails

If the run has not concluded, the Gate is transiently waiting. A sealed receipt is go or no-go, never waiting.

Next action

The Exam answer transcript in Verify with Shopify Exam is separate and is not a Configured Gate evidence source. To continue in Meguro, select the store and open its Gate controls.

Verify on Shopify

Verify with Shopify Exam

The Exam replays the recorded requests on your Shopify development store and records Shopify's answers.

Use this when

Use Shopify Exam when you need Shopify’s recorded answers for requests from one Practice run.

Before you start

The Exam proves only what Shopify returned for those recorded requests on that development store. It does not decide whether the agent was right. Target-store state can differ from the Practice world, especially for calls recorded after the Practice clock first advanced.

Steps

Confirm the Shopify development store and the recorded requests to replay.
Use the shared call index to line up the Practice record with Shopify’s answer transcript.
Preflight reads the run’s eligibility record and names each code with its meaning. Blocking codes make the tape unreplayable: no capture, missing tape rows, an unsupported plane, or mixed API versions. Mutations and calls across Store days are recorded facts, not blockers.
accepted means Shopify answered without GraphQL or user errors; rejected means Shopify answered with errors; no-answer means Meguro cannot determine Shopify’s answer after a send; not-replayed means the call was recorded without being sent.
A call is not replayed when its request needs an id Shopify never returned, and its record names that id’s earlier cause, or when Practice refused it for Meguro’s own infrastructure reasons (the rate-limit throttle, storage unavailability, or a Store-time advance in progress). Where the two stores answer an id or cursor differently, the transcript records the difference and replay continues.
When the source ledger contains webhook creation, read this disclosure before replay: “A webhook subscription in this transcript points at the agent's callback URL from the run. Shopify sends development-store events there until the Exam removes the subscription after the last replayed call.”
Preparation restores Meguro’s canonical baseline and preserves customer-owned and earlier Exam-tagged objects. After the last replayed call, the Exam removes the metafield definitions (with their values), pins, and webhook subscriptions that replay created, found only in Shopify’s answers to replayed calls; each removal is recorded in the transcript and nothing else on the store is touched.

Success looks like

Exact Shopify and Practice request/response material stays private. The public transcript is redacted and capability-addressed.

If it fails

The completed private and public Exam transcript share one lifetime fixed when sealing completes: 7 days on Free, 90 days on Solo, or 365 days on Builder. Later plan changes do not extend or shorten that deadline. The sealed Shopify body and header evidence follows that lifetime. Practice-response references are attemptId/tapeSequence citations plus a digest, not downloadable copies; the source Store and run keep their own lifetime.

Next action

A no-answer does not establish a Shopify result. An Exam does not establish whether the agent was right, production safety, future demand, or complete Shopify compatibility.

Account and billing

Plans, simulation runs, and limits

Pricing and capacity follow the enforced Free, Solo, and Builder contracts.

Use this when

Use this when choosing a plan or interpreting Usage.

Before you start

A no-card 14-day Solo trial lands on permanent Free. Read simulation run and simulation canvas before comparing limits.

Steps

Plan	Price	Simulation runs / month	Canvas	Receipts kept	Active stores	Active workspaces
Free	$0	10	14 Store days	7 days	1	1
Solo	$60/month or $600/year	30	30 Store days	90 days	1	1
Builder	$199/month or $1,990/year	100 included	30-day runs can continue one aging store to 365 Store days	365 days	3	10

Success looks like

Usage shows reserved, charged, released, remaining, and overage simulation runs under the current plan. Every tier receives the same receipt truth; plans change capacity, not evidence quality.

An accepted ordinary start reserves one monthly simulation run, counted as used while open; it is charged only when the run completes or is stopped after agent execution, even if agent checks fail. Refused starts reserve none; cancellation, expiration, failure before agent execution, and completion or stopping without agent execution release the reservation. Your included first evaluation and its authorized continuations, the automatic sample, and practice-world upkeep use no monthly run. Each ordinary Builder continuation is a separate start under the same rule; a plain start after the included evaluation ends is ordinary. A problem after execution has no separate exemption; settlement follows how the run ends.

An accepted ordinary start reserves one monthly simulation run, and Usage counts that reservation as used while the run is open.
A refused start reserves no monthly simulation run.
A run that completes or is stopped after your agent began executing is charged one monthly simulation run, even if your agent's checks fail.
Canceling a run releases its reservation, whether you cancel before or after your agent began executing.
A run that expires because your agent never began, it went idle, or it reached its maximum age releases its reservation, even after your agent began executing.
If Meguro cannot prepare a run before your agent begins executing, its reservation is released. A problem after your agent began executing has no separate exemption: the run is settled by how it ends.
A run that completes or is stopped without any agent execution releases its reservation.
The automatic sample run on the practice store Meguro sets up for you uses no monthly simulation run.
Each ordinary Builder continuation is its own run: it reserves one monthly simulation run and is charged or released by the same rule.
After your included root run ends, a plain start on that Store is an ordinary run and follows the same rule.
Practice-world upkeep, the simulation work that keeps your practice world's Store time and events moving, uses no monthly simulation run.

Every run carries one durable classification:

customer-started-tier-credit: An ordinary run you or your agent started. It reserves one monthly simulation run when accepted and is charged or released by how it ends.
onboarding-evaluation-grant: The automatic sample does not bind your included evaluation; the first accepted run on a customer-chosen template store binds it to that Store and its planned Store-day horizon; explicit continuations through its remaining included days consume no monthly run; after the root ends, a plain start replays the same Store days as a new run and spends one monthly run.
provisioned-sample-exemption: The automatic sample run on the practice store Meguro set up for you. It uses no monthly simulation run.
system-world-upkeep: Practice-world upkeep that keeps your practice world's Store time and events moving. It uses no monthly simulation run.

If it fails

Free and Solo stop the exact over-limit action before work begins and name the limit; existing stores and evidence remain readable. Builder records usage beyond 100 included simulation runs, but automated overage invoicing is not enabled at launch. Archiving a store or workspace can release its active slot.

Next action

Open Usage or public pricing.

Account and billing

Credentials and connections

Use each credential only for its declared target and rotate it when exposure is possible.

Use this when

Use this when connecting an external tool, CI job, MCP client, or Shopify Admin client.

Before you start

Distinguish the workspace API key from the per-store Admin token. Real credential values must never enter Documentation, receipts, support messages, or logs.

Steps

Workspace API key: begins meg_sk_…, is shown once, and scopes an external control client to one workspace. Put it in MEGURO_API_TOKEN.
Safe key retries: Console keeps one request identity for a pending create or rotation, including across navigation, and resends that same operation after an interrupted response. A completed retry returns the recorded key metadata without the secret; choose Rotate explicitly to obtain another one. Meguro never creates or rotates another key merely to recover plaintext that was already delivered once.
Per-store Admin token: begins meg_pw_…, targets one practice store, and is sent by the agent as X-Shopify-Access-Token.
Hosted control plane: OAuth 2.1 remote MCP over stateless Streamable HTTP /mcp, with workspace API keys accepted as Bearer authorization.
Before authorization, only docs_read, templates_list, template_get, and plan_validate are callable. Other tools require an authorized principal through OAuth or a workspace API key.
Compatibility bridge: clients without remote transport support can use mcp-remote to reach the hosted MCP URL.
Separate shopper plane: a practice store’s /api/mcp endpoint models Storefront shopper interactions and does not replace the control plane.

Success looks like

The external control client is limited to its workspace, while the agent under test can reach only the intended practice store.

If it fails

An invalid or revoked workspace key must be replaced in Settings → API keys. Rotate credentials after possible exposure and update every intended client; never paste Console sign-in tokens, browser cookies, or browser storage into a terminal.

Next action

Open Settings → API keys to manage workspace keys, or Console account menu → Authorized clients to review and revoke hosted MCP clients.

Account and billing

Workspaces, deletion, and support

Separate customer evidence by workspace and use owner-only deletion when an account must be removed.

Use this when

Use workspaces to isolate stores, runs, keys, members, and evidence for different customers or operating contexts.

Before you start

Check your active-workspace limit, including Default: 1 on Free, 1 on Solo, or 10 on Builder.

Steps

Create or select the intended workspace before creating stores and keys.
Archive an inactive workspace to release its slot; restoring it rechecks the current limit.
For account deletion, use the owner-only account settings flow. Deletion revokes workspace keys first and cancels an active subscription without issuing an automatic refund.

Success looks like

The selected workspace owns its stores, runs, receipts, members, and keys without cross-workspace credential reach.

If it fails

If a workspace or deletion action is unavailable, confirm owner/member role and the active limit. For unresolved account or billing issues, contact hello@meguro.io without sending credentials.

Next action

Open Workspaces or Account settings.

Reference and troubleshooting

Store and scenario catalog

Choose by agent job first, then use the store detail to inspect the exact entities and modeled pressure.

Scope and proof boundaries

Catalog entries declare modeled commerce conditions; they are not forecasts or claims about future customer demand. A template does not redefine the globally supported Admin GraphQL surface. Scenario-only launch-candidate state, carrier-expedite consequences, and variant discontinuation are modeled or reference-only; do not treat them as Shopify read or write capabilities. productUpdate(status: ARCHIVED) affects a whole product, not a variant.

Choose by agent job

Agent job	Look for	Served Admin operation	Representative evidence
Pricing	Products with margin and demand sensitivity	`productVariantsBulkUpdate`	Product or variant price change plus modeled demand and contribution
Inventory	Low stock or incoming supply	`inventoryAdjustQuantities`	Single-location adjustment plus modeled stock position
Order cash refund	Canonical committed order and priced committed lines	`refundCreate`	Line-item cash refund plus separately labelled return/restocking evidence
Fulfillment	Open fulfillment work or shipping thresholds	`fulfillmentCreateV2`, `deliveryProfileUpdate`	Fulfillment progress or delivery-profile consequence
Retention	Modeled winback or abandoned-checkout pressure	Unsupported: no discount or offer mutation is served	Separately labelled modeled cohort or loyalty evidence only
Catalog	Modeled launch pressure, quality gaps, bundles, or plans	`productUpdate`, `metafieldsSet`, `metafieldDefinitionCreate`, `productBundleCreate`, `sellingPlanGroupCreate`	Product or variant catalog change and accepted call record

Inspect the selected store

The store detail is authoritative for its scenario label, seed, starting modeled day, entities, pressure, and suggested meaningful actions. Use Supported Admin GraphQL surface to verify the call shape separately.

Reference and troubleshooting

Canonical definitions

Each product term is defined once here; task articles link to these anchors.

Scope and proof boundaries

These definitions describe Meguro’s current public product contract. They do not expand a practice receipt into production, forecasting, certification, or full-platform proof.

Definitions

Term	Authoritative definition
Practice store	A deterministic Shopify-shaped environment with a declared Admin GraphQL surface, modeled commerce behavior, and an explicit scenario and seed.
Store clock	The declared control of modeled store time for a run: Manual or Scheduled. Time moves as your run drives it.
Run	One bounded observation window in which an agent acts against one practice store and Meguro records calls and state changes.
Receipt	The immutable review artifact for a concluded run: recorded calls, accepted or blocked actions, modeled state changes, proof boundaries, and integrity metadata.
Simulation run	One execution for one agent version, one store, one scenario, and one seed; a failure can be the honest result when agent execution occurred.
Simulation canvas	The maximum number of Store days available to one simulation run or continuation chain under the active plan.
Observed	Directly recorded from the agent interaction or target system during this run.
Modeled	Computed by Meguro’s declared practice-store model from recorded inputs and actions.
Not established	A claim the available evidence does not prove and must not imply.
Configured Gate	Displays the Gate’s go or no-go decision sealed in a receipt for a selected Store and receipt. The user owns any release decision.
Shopify Exam	A replay of recorded requests that records Shopify’s answers on one development store. It does not decide whether the agent was right.
Workspace API key	A one-time-shown credential beginning meg_sk_ that authenticates an external tool to one workspace.
Per-store Admin token	A credential beginning meg_pw_ that targets one practice store through its Shopify-shaped Admin endpoint.

Reference and troubleshooting

Supported Admin GraphQL surface

The declared Shopify-shaped Admin surface and its loud boundaries.

Scope and proof boundaries

This is a practice surface, not a claim of full Shopify parity. Help names three states: served v1 provider operations, internal modeled evidence, and deferred v2. Supported fields and shapes are bounded; unsupported calls return GraphQL errors or userErrors rather than fake success.

Supported query roots

Roots	Use
`shop`, `node`, `nodes`	Shop identity, global-id readback, and object hydration
`products`, `product`, `productByHandle`, `productVariants`, `inventoryItems`	Catalog, variants, pricing, inventory, cost, status, tags, SEO, and metafields
`collections`, `collection`, `collectionByIdentifier`, `collectionByHandle`, `collectionsCount`	The custom collections a template seeds from its own catalog, their products in manual order, and `Product.collections`; `collectionByIdentifier` also finds a collection by a custom ID, a metafield value its definition requires to be unique; no collection write is served
`orders`, `order`, `draftOrders`, `draftOrder`	Canonical committed orders, priced line items, financial and fulfillment state, risk, refunds, and bounded drafts
`customers`, `customer`, `segments`	Read-only lifecycle, repeat-buyer, and winback context; no persistent customer membership operation
`locations`, `fulfillmentOrders`, `deliveryProfiles`	Inventory location, fulfillment, and delivery evidence
`webhookSubscriptions`, `webhookSubscription`, `webhookSubscriptionsCount`	The webhook subscriptions recorded on the store's active run, also readable through `node`; send each webhook root as the only root field of its document

Supported mutation families

Family	Use	Modeled consequence
`productVariantsBulkUpdate`	Pricing	Price and compare-at values can affect modeled demand and margin
`inventoryAdjustQuantities`	Inventory	Truthful available-inventory adjustment at a single location; no cross-location transfer operation
`refundCreate`	Order refunds	Line-item cash refund only against a canonical committed `Order` and its priced committed lines. `NO_RESTOCK` and `RETURN` are the restock choices. `RefundInput.transactions`, `RefundInput.refundMethods`, and `Customer.storeCreditAccounts` are absent.
`fulfillmentCreateV2`, `deliveryProfileUpdate`	Fulfillment	Fulfillment progress and shipping-threshold effects
`productBundleCreate`, `sellingPlanGroupCreate`	Bundles and plans	Native creation and official readback; attach, churn, and money remain modeled scenario effects
`draftOrderCreate`, `draftOrderComplete`	Order staging	Only `draftOrderComplete` establishes a canonical committed order. The shopper surface serves UCP general access and places none: a checkout there ends at a buyer handoff
`webhookSubscriptionCreate`, `webhookSubscriptionUpdate`, `webhookSubscriptionDelete`	Webhooks	Run-scoped HTTPS subscriptions to `PRODUCTS_UPDATE`, `ORDERS_CREATE`, `ORDERS_CANCELLED`, `REFUNDS_CREATE` and `INVENTORY_LEVELS_UPDATE`, with filters, include fields, a name, and Product metafields selected by namespace or identifier; XML, Google Pub/Sub and Amazon EventBridge are not modeled
`productUpdate`, `metafieldsSet`, `metafieldDefinitionCreate`, `metafieldDefinitionUpdate`, `metafieldDefinitionDelete`, `metafieldDefinitionPin`, `metafieldDefinitionUnpin`	Catalog	A preauthored DRAFT product activates through `productUpdate(status: ACTIVE)`. Metafields and merchant-owned metafield definitions are supported for every Shopify metafield type except references to articles, companies, metaobjects, pages and taxonomy values, on products, variants, collections, customers, draft orders, locations, media images, orders, selling plans and the shop. Every documented validation is enforced, including RE2 `regex` and JSON `schema`, and the `adminFilterable`, `smartCollectionCondition` and `uniqueValues` capabilities can be enabled. Reference values must name an entity the store holds. `products(query:)` filters by an admin-filterable metafield

Meguro-native debugging extensions

productBundleCreate returns an asynchronous product operation; read it through productOperation(id). sellingPlanGroupCreate returns a selling-plan group; read it through sellingPlanGroup, sellingPlanGroups, and nested SellingPlanGroup.sellingPlans. Other Meguro-native lifecycle extensions are not ordinary Shopify Admin roots or proof of Shopify support. Attach, churn, and money are modeled scenario outcomes, not Shopify response fields.

Internal modeled evidence

Return/restocking, loyalty-credit, cohort, and cross-location transfer economics are internal modeled evidence. They are not a request shape, provider mutation, provider readback, or provider identity.

Deferred v2

The provider Return lifecycle, collection curation, gift cards, product creation, persistent customer membership, aggregate-order economics, and store-credit refunds are deferred v2. Current v1 has no provider operation or substitute for them.

Known boundary

Absolute inventory-set writes, broad order edits, pending-payment draft completion, generic payment lifecycle, bulk operations, broad productSet, metafields in app-reserved namespaces or on owners the store does not hold, carrier APIs, and native checkout completion are outside the current declared practice contract.

Reference and troubleshooting

API reference

Public control, receipt, and schema contracts.

Scope and proof boundaries

These identifiers and routes are legitimate public integration material. A customer run controls one bounded practice lifecycle; it does not grant Shopify production access or verify a receipt result.

Identity and credentials

storeId identifies the practice store.
attemptId identifies the run returned by start and is used by later lifecycle calls.
Direct external HTTP control calls use a workspace API key. Hosted MCP control tools accept an authorized principal through OAuth or a workspace API key. The agent receives only the separate Admin URL and per-store token.

Run lifecycle

Every HTTP route below is served at the API host https://api-dev.meguro.io; for example, Start is POST https://api-dev.meguro.io/practice/stores/{storeId}/playbacks.

Action	HTTP route	MCP tool
Start	`POST /practice/stores/{storeId}/playbacks`	`practice_run_start`
Status	`GET /practice/playbacks/{attemptId}/state`	`practice_run_status`
Checkpoint	`POST /practice/playbacks/{attemptId}/checkpoint`	`practice_run_checkpoint`
Advance	`POST /practice/playbacks/{attemptId}/advance`	`practice_run_advance`
Finish	`POST /practice/playbacks/{attemptId}/finish`	`practice_run_finish`
Cancel	`POST /practice/playbacks/{attemptId}/cancel`	`practice_run_cancel`
Receipt	`GET /practice/playbacks/{attemptId}/report`	`practice_run_report`

Advance accepts exactly one of days or until. Copy the current server-owned practiceRun.advanceCursor object unchanged. For example: { "days": 1, "advanceCursor": { "expectedDay": 12, "expectedCallSeq": 4 } }.

Cancel requires a reason, for example { "reason": "operator-request" }.

Schemas and artifacts

What it usually means

The account may still be waiting for a signed payment update, the action may require the account owner, or the current subscription state may keep Free limits in effect.

What to do next

Open Plans and billing as the account owner. After a delayed return, use Check again once and do not submit Checkout again while confirmation is pending. Use Manage billing for the current subscription or contact support if the signed update remains missing.

What to include for support

Include the account email, route, selected plan and interval, timestamp and timezone, exact visible billing text, and whether it persists after reload. Never send card details, checkout URLs, credentials, or payment secrets.

Reference and troubleshooting

Contact support

Escalate an unresolved Documentation problem with enough customer-safe context to investigate it.

Scope and proof boundaries

Support context should identify the visible customer-facing failure without exposing secrets, private payloads, customer data, or internal implementation details.

Contact support

Email hello@meguro.io after completing the relevant troubleshooting step. There is no need to send a private diagnostic bundle.

What to include

Your account email.
The route where the problem appears.
The visible store, run, or receipt ID when available.
The timestamp and timezone.
The exact visible error text.
Whether the issue persists after reload.

What never to send

Never send access tokens, API keys, credentials, authorization headers, private request payloads, secrets, or customer PII/data. Remove those values before sending any screenshot or copied text.