Task-oriented technical guidance for practice, evidence, automation, and verification.
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.
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
Have an agent or Shopify Admin client that can send one authenticated GraphQL read.
Steps
Create a practice store. Choose a scenario for the commerce behavior you want to simulate.
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. Let it read and, when appropriate, make one bounded state-changing call.
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.
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 the compatibility table lists it — Meguro cannot exercise them, and won't pretend to.
You're testing storefront, themes, or checkout UX. A practice store is commerce state behind an Admin-shaped API, not a rendered storefront.
You're load-testing. The throttle model exists to exercise your agent's backoff discipline, not to benchmark a platform.
Your agent never touches commerce state. If it reads a static catalog once, a fixture file is cheaper.
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
Name one representative agent decision and the meaningful state change that should follow.
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 product-owned metafields
Success looks like
The chosen scenario contains the entities and modeled pressure needed to make the representative action interpretable.
If it fails
If the required mutation is outside the declared surface, choose a supported representative action or record the gap; do not treat an unsupported call as success.
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.
Pick the simplest clock that matches who should control modeled time.
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
Decide whether an operator, Meguro, or your code owns each time advance. This beginner choice is separate from runner grants, temporal requirement JSON, immutable revisions, and Exam eligibility.
Steps
Mode
Control
Use it when
Manual
An operator advances Store time
You want to inspect each boundary before moving on
Automatic
Meguro advances after the first agent call
The agent should run through a bounded scenario without operator steps
Code controlled
Your runner copies the server-owned practiceRun.advanceCursor unchanged
Automation must choose exact checkpoints deterministically
Success looks like
The active run displays its chosen clock, current modeled day, and next allowed action.
If it fails
If an advance is rejected, refresh the run state and copy its fresh practiceRun.advanceCursor object unchanged. For code-controlled runs, create a fresh one-time runner authorization after time advances; it is shown once, hashed at rest, expiring, revocable, and command-bound.
Inspect whether the call was accepted, rejected, or unsupported and whether tracked state changed.
Advance Store time only when the scenario needs a later modeled consequence.
Finish when the intended evidence is present, or cancel safely when the run should stop.
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; infrastructure start failures or runs with no agent execution do not consume a simulation run.
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 a Configured Receipt Gate.
Before you start
Treat the receipt as a technical evaluation. Recorded API behavior is automatic whether or not a Configured Receipt Gate exists, and its customer wording comes from the Default run policy. 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
Read Goal outcome for whether the intended technical task happened.
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.
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.
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, immutable revision, issuance time, and receipt-availability window.
Steps
Download or copy the bounded artifact from the product.
Retain it within your plan’s availability window or in your own controlled evidence store.
Recompute the documented artifact digest to verify bytes and detect alteration.
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.
Run the same bounded lifecycle from CI, hosted MCP, or a local stdio client 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 or local tooling, or authorize the hosted remote 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 remote MCP: connect with OAuth 2.1 to stateless Streamable HTTP /mcp.
Local alternative: run the Meguro MCP client over stdio and provide its workspace API token in the local environment.
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.
Use Configured Receipt Gate as a receipt-evidence signal
Configured Receipt Gate makes a selected evidence rule repeatable; it does not own the release decision.
Use this when
Use this when an optional configured policy should compute a repeatable signal over selected immutable receipt evidence. No configured Receipt Gate exists. The receipt's recorded API behavior remains available.
Before you start
Choose the receipts, facts, thresholds, policy version, and artifact visibility. Configured Receipt Gate does not decide whether you should ship.
Steps
Select the receipt rows and the evidence facts your policy cites.
Run the named Configured Receipt Gate policy or your own policy over those facts.
Inspect blocked, waiting, and clear rows with their cited evidence.
Copy or download the bounded result artifact. A local compatibility file alone does not create saved Configured Receipt Gate history.
Success looks like
Every signal resolves to its policy version and cited receipt facts; you own the release decision.
If it fails
If a fact is absent, keep the signal waiting or failing according to the named policy. Do not expose internal “Do not ship” wording as Meguro authority or infer an unrecorded cause.
Replay an eligible captured practice tape against an actual Shopify development store under the Exam contract.
Use this when
Use Shopify Exam only when actual Shopify development-store replay is the next technical proof.
Before you start
Start from an eligible captured run. Eligibility is explicit and can be blocked by missing or unsupported replay input, incomplete or ungraded runs, temporal requirements, or unsupported operations.
Steps
Review the captured replay preview and exact target boundary.
Confirm the actual Shopify development store and Admin API version 2026-04.
Run the eligible replay, comparison, cleanup, and receipt generation flow.
Read the meguro.shopify-exam-receipt.v2 private receipt or meguro.shopify-exam-public-receipt.v2 public receipt and criteria version 5 result.
Success looks like
On success, use the V2 public receipt as live-verified input limited to the exercised operations and declared development-store target. Exact and normalized passing classifications remain distinct.
If it fails
On block, stop and follow the named blocker code: resolve the specified eligibility, setup, replay, comparison, historical materialization, or cleanup problem before creating a new Exam run. An Exam does not establish production simulation, deployment safety, future demand, or complete Shopify compatibility.
Next action
Carry only the Exam’s exercised-operation evidence into your next review. Ordinary practice runs never inherit live-Shopify proof.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.
30-day runs can continue one aging store to 365 world-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.
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.
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.
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.
Without signing in, hosted MCP supports initialization, lists the complete tool catalog, and serves docs_read; only docs_read is callable without authorization, and all other tools require OAuth.
Local alternative: Meguro MCP over stdio with a workspace API token.
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 Connection settings. Rotate credentials after possible exposure and update every intended client; never paste Cognito tokens, browser cookies, or browser storage into a terminal.
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: Free and Solo allow 1 including Default; Builder allows 10.
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.
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
Representative evidence
Pricing
Products with margin and demand sensitivity
Price or discount change plus modeled demand and contribution
Inventory
Low stock or incoming supply
Single-location adjustment plus modeled stock position
Order cash refund
Canonical committed order and priced committed lines
Line-item cash refund plus separately labelled return/restocking evidence
Fulfillment
Open fulfillment work or shipping thresholds
Fulfillment progress or delivery-profile consequence
Retention
Abandoned checkout or discount pressure
Bounded offer plus separately labelled modeled cohort or loyalty evidence
Catalog
Modeled launch pressure, quality gaps, bundles, or plans
Product-owned 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, automatic, or code controlled.
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 modeled world-time 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 Receipt Gate
An optional configured policy over selected receipt facts; the user owns the release decision.
Shopify Exam
An eligible captured replay against an actual Shopify development store that tests the recorded API shapes under the declared Exam contract.
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
Catalog, variants, pricing, inventory, cost, status, tags, SEO, and product-owned metafields
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
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
productUpdate, metafieldsSet
Catalog
A preauthored DRAFT product activates through productUpdate(status: ACTIVE); product-owned metadata remains supported
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. The former fake bundle/subscription roots are absent. Remaining 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, non-product metafields, carrier APIs, webhook-subscription mutations, and native checkout completion are outside the current declared practice contract.Reference and troubleshooting
API and runner reference
Public control, runner, receipt, and schema contracts.
Scope and proof boundaries
These identifiers and routes are legitimate public integration material. A runner 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; worldId remains an accepted compatibility alias.
attemptId identifies the run returned by start and is used by later lifecycle calls.
Control calls use the workspace API key; the agent receives only the separate Admin URL and per-store token.
Runner lifecycle
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
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; legacy flat expectedDay and expectedCallSeq request fields remain compatible.
Schemas and artifacts
Read Receipt schema v1 for the rendered receipt schema. Public temporal exports are allowlisted summaries; private exports contain bounded internal-forensics material and belong in restricted artifacts. Same scenario, seed, clock, and agent calls produce the same modeled result; changed inputs create new evidence rather than rewriting an old receipt.
Advanced Store-time contracts
Code-controlled runners use short-lived one-time grants bound to one workspace, store, run, current Store-time coordinate, immutable revision, and command digest. Temporal requirements are versioned JSON arrays evaluated against recorded calls and scenario time. Changing a requirement produces a new immutable revision; eligibility for Shopify Exam remains an explicit later decision rather than an effect of choosing a clock.Reference and troubleshooting
Troubleshooting and recovery
Concrete recovery steps for authentication, runs, Store time, receipts, limits, networking, service failures, deletion, and billing.
Scope and proof boundaries
Start with the exact visible state, take the bounded next action, and stop before an ambiguous retry. Every entry below keeps support details customer-safe. Never send access tokens, API keys, credentials, authorization headers, private request payloads, secrets, or customer PII/data.
401 or 403 authentication failure
What you see
A request returns 401, 403, unauthorized, forbidden, or “sign in or present an API key.”
What it usually means
The credential is missing, invalid, revoked, expired, or not allowed to reach that workspace or store. A workspace API key and a per-store Admin token are not interchangeable.
What to do next
Sign in again for dashboard requests. For an external control client, create or select a valid workspace API key in Connection settings; for an agent’s Admin request, recopy that store’s Admin URL and token. Retry one read before starting or changing a run.
What to include for support
Include the route, whether the request came from the dashboard, a control client, or an Admin client, the timestamp and timezone, and the exact visible error text. Never include the credential or authorization header.
Wrong credential type: workspace key versus per-store Admin token
What you see
A credential works in one Meguro surface but is rejected by another, or an Admin client never records its first read.
What it usually means
Workspace control keys beginning meg_sk_… authenticate external control clients to one workspace. Per-store Admin tokens beginning meg_pw_… authenticate an agent only to one practice store.
What to do next
Use the workspace key only with the public control API or local control tooling. Use the per-store token with that store’s Admin GraphQL URL and X-Shopify-Access-Token, then confirm one read.
What to include for support
Include the route, client type, store ID when visible, timestamp and timezone, and exact visible error. State only which credential type you used; never send its value.
Unsupported GraphQL field or mutation
What you see
The response contains GraphQL errors or userErrors naming an unsupported field, mutation, argument, or shape.
What it usually means
The request is outside the declared Shopify-shaped practice surface. Unsupported calls fail loudly instead of returning fake success.
What to do next
Open Supported Admin GraphQL surface, compare the exact operation family, and use a supported representative action when one preserves the job. Otherwise record the gap and do not count the call as compatible.
What to include for support
Include the operation name, requested API version when visible, route, store/run ID, timestamp and timezone, and exact public error text. Do not send variables, private payloads, or customer data.
Agent makes reads but no writes
What you see
Calls are recorded, but the receipt shows no accepted representative write, “no writes,” or report-only evidence.
What it usually means
The client connected, but it did not issue or complete the write that represents the agent job. Reads may occur before a run; writes require an active run.
What to do next
Start a run, name one supported bounded write, run the agent again, and inspect whether the call was accepted, rejected, or unsupported. A zero-write or report-only run does not establish impact.
What to include for support
Include the visible store and run IDs, route, timestamp and timezone, intended operation name, exact visible status, and whether it persists after reload. Do not send the request payload.
Run waiting for the agent’s first call
What you see
The run says “Waiting for your agent’s first call” and no call appears.
What it usually means
The observation window is armed, but the agent has not reached this store’s Admin URL with its per-store token. Automatic Store time begins only after the first agent call.
What to do next
Verify the agent process is running, recopy the current store Admin URL and per-store token, and send one authenticated read. Do not start another run until this run records or rejects that call.
What to include for support
Include the route, store/run ID, timestamp and timezone, agent client name, exact visible waiting text, and whether reload changes it. Never send the Admin token.
Automatic or code-controlled Store time appears stopped
What you see
The modeled day does not move while an automatic or code-controlled run is active.
What it usually means
Automatic time may still be waiting for the first agent call. Code-controlled time moves only when the runner sends an allowed advance with the server-owned practiceRun.advanceCursor.
What to do next
Check the run status and current clock mode. For automatic time, confirm the first authenticated call. For code-controlled time, fetch fresh status and copy its practiceRun.advanceCursor object unchanged into advance.
What to include for support
Include the run ID, clock mode, displayed Store day, route, timestamp and timezone, exact visible status, and whether it persists after reload. Do not send runner authorization.
Concurrent Store-clock change
What you see
An advance is rejected with “scenario clock changed concurrently” or another message that the Store clock changed concurrently.
What it usually means
Another accepted call or advance changed the run coordinate after the client last read it. The stale expected day or call sequence cannot be applied.
What to do next
Fetch the current run status, replace the stale expected day and expected call sequence with the returned values, create a fresh one-time authorization when required, and retry the one intended advance once.
What to include for support
Include the run ID, displayed clock mode and current coordinate, route, timestamp and timezone, exact visible error, and whether a fresh status read changed the coordinate. Never send the authorization value.
Run or receipt unavailable after completion or reload
What you see
A completed run or receipt is missing, unavailable, or reported as expired after reload.
What it usually means
The simulation run may not have ended durably, the selected workspace may differ, or the receipt may be outside the active plan’s availability window. An ID or hash alone cannot recreate a result.
What to do next
Reload once, confirm the selected workspace and store, reopen the simulation run from its history, and use a previously retained artifact if the receipt availability window has ended. Do not manufacture a replacement result.
What to include for support
Include the visible run or receipt ID, workspace name without customer data, route, completion time and timezone, exact visible status, and whether it persists after reload.
Missing agent identity or requested API version
What you see
The receipt says agent identity is missing or “Requested API version was not captured for these calls.”
What it usually means
The run recorded behavior, but it lacks a declared identity or version coordinate needed for the claim you want to make. The missing field cannot be inferred later.
What to do next
Configure the client to declare its agent/build identity and intended Shopify Admin API version, then create a new run and confirm both fields appear before relying on the new receipt for version coverage.
What to include for support
Include the receipt/run ID, route, timestamp and timezone, exact visible missing-field text, client name, and whether a fresh run reproduces it. Do not send source, payloads, or credentials.
Shopify Exam eligibility or blocker
What you see
Shopify Exam is unavailable or names an eligibility, setup, replay, comparison, historical materialization, or cleanup blocker.
What it usually means
The captured run does not currently satisfy the explicit Exam contract for the selected development-store target and exercised operations.
What to do next
Open the run, follow its named blocker, and correct only that eligibility or setup condition before creating a new Exam run. Ordinary practice evidence does not become live-Shopify proof while the blocker remains.
What to include for support
Include the practice-run and Exam-run IDs, blocker code and visible message, requested API version, timestamp and timezone, and whether reload changes the blocker. Never send Shopify credentials or private receipt bytes.
Expired one-time or runner authorization
What you see
The product says “Authorization expired,” “Local runner authorization has expired,” or reports an unavailable one-time authorization.
What it usually means
The short-lived, command-bound authorization expired, was revoked, was already used, or no longer matches the run’s current Store-time coordinate.
What to do next
Fetch the current run state, create a new authorization for the exact current command and coordinate, replace the expired value in the runner, and retry. Never reuse an expired one-time authorization.
What to include for support
Include the run ID, command name, current displayed coordinate, route, timestamp and timezone, exact visible error, and whether a newly created authorization succeeds. Never send either authorization value.
Simulation canvas, simulation-run, receipt-retention, active-store, or workspace limit
What you see
Meguro stops an action and names a simulation-canvas, simulation-run, receipt availability, active-store, or active-workspace limit.
What it usually means
The current enforced plan contract does not allow that action or capacity. Existing readable stores and evidence are not upgraded or invalidated by the limit message.
What to do next
Open Usage and Plans and billing to identify the exact limit. Finish or cancel work before deleting an active store, archive an unused workspace to release its slot, retain receipts within their availability window, or choose a plan whose enforced capacity fits the work.
What to include for support
Include the account email, exact limit name and visible counts, route, timestamp and timezone, exact visible message, and whether reload changes it. Do not include billing credentials or customer data.
Public receipt or hash integrity versus result verification
What you see
A public receipt hash matches, or a reviewer asks whether a matching digest proves the result.
What it usually means
The digest verifies the artifact bytes and detects alteration. It does not verify that the evidence supports the result, expand the exercised scope, or turn modeled evidence into live proof.
What to do next
Verify the digest, then separately review the receipt’s goal outcome, recorded calls, evidence classification, proof boundaries, target, and exercised operation scope.
What to include for support
Include only the public receipt ID or URL, digest, issuance time and timezone, route, and the exact visible integrity result. Do not send private receipt content or customer data.
HTTP 429 or throttling when applicable
What you see
A request returns 429 or a visible throttling message.
What it usually means
The applicable surface declined the request at that moment. Practice rate-limit evidence is bounded to the exercised mode and is not a claim of exact Shopify rate-limit parity.
What to do next
Stop parallel retries. If the response provides Retry-After, wait for that visible duration before one retry; otherwise reduce request concurrency, fetch fresh state, and retry later without assuming a guaranteed window.
What to include for support
Include the route, operation name, status code, visible Retry-After value when provided, timestamp and timezone, run ID, exact visible error, and whether one later retry changed it.
CORS or client networking failure
What you see
A browser or client reports CORS, a blocked preflight, failed fetch, DNS/TLS failure, or no HTTP response.
What it usually means
The client may be using the wrong public origin or route, a browser-only request may not be allowed there, or the network failed before Meguro returned a product response.
What to do next
Confirm the current public URL and route, reload once, retry from the intended client, and use the documented server-side or MCP path when a browser origin is not supported. Do not disable browser security.
What to include for support
Include the route and public origin, client/browser name and version, timestamp and timezone, exact visible network text, whether any status code appeared, and whether reload reproduces it. Do not send headers or payloads.
HTTP 500 or service failure
What you see
A request returns 500, “internal server error,” or a visible service-failure message.
What it usually means
Meguro could not complete that request. The error does not establish whether a write occurred, so repeating a mutation immediately could create ambiguous evidence.
What to do next
Stop the workflow, reload once, inspect the visible run or store state, and retry a read-only status request. Do not repeat a write unless the current state shows it is safe; contact support if the failure persists.
What to include for support
Include the account email, route, visible store/run/receipt ID, timestamp and timezone, exact visible error text, and whether it persists after reload. Never send request payloads, authorization headers, credentials, secrets, or customer data.
Account and practice-store deletion
What you see
Delete account or Delete practice store is unavailable, blocked, expired, or does not complete after confirmation.
What it usually means
An active run can protect a store from deletion; a store deletion preview can become stale or single-use; permanent account deletion is owner-only, requires recent sign-in, and may resume in bounded steps.
What to do next
For a practice store, finish or cancel its active run, request a fresh deletion preview, and confirm again. For an account, sign in again, open Account settings as the owner, type the required confirmation, and resume only from the displayed deletion state.
What to include for support
Include the account email, route, visible store ID or deletion phase, timestamp and timezone, exact visible error, and whether it persists after reload. Never send confirmation tokens, credentials, private payloads, or customer data.
Billing, checkout, or subscription support
What you see
Checkout is canceled or delayed, a plan change is not reflected, payment is past due, or Manage billing is unavailable.
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.