Explain
The topics behind metro docs explain.
Topics for metro docs explain <topic> --markdown: decision trees for agents, plus lookups for commands, shapes, rules, gotchas and scopes.
Source
Generated from metro docs explain --list --markdown in metrocli/metro @146bf3e. Source schemaVersion: metro.docs.explain.index.v1.
- schemaVersion:
metro.docs.explain.index.v1 - apiAccess:
none - nextSafeStep: Run metro docs explain <topic> --json for a single topic, or use explicit prefixes such as command:, shape:, gotcha:, rule:, scope:, policy:, and example: to avoid ambiguous IDs. This index does not authorize live reads or writes.
Summary
{
"operatingTopicCount": 14,
"lookupKindCount": 8,
"genericExplainableCount": 425,
"liveApiAccess": "none"
}Operating topics (agent decision trees)
| id | status | apiAccess | summary | explain |
|---|---|---|---|---|
| first-safe-preview | local-install-backed | none | Give a new authorized teammate or internal agent one terminal-native path to prove installability, command discovery, profile shape, local validation, and sandbox-labeled preview without live API access. | metro docs explain first-safe-preview --json |
| install.troubleshooting | local-install-backed | none | Use this topic when npm packaging, global installation, or the installed metro binary fails: prove the package manifest, runtime file allowlist, executable bin, temporary-prefix install, and local-only smoke command before moving to setup profiles or safe preview work. | metro docs explain install.troubleshooting --json |
| package.publish-readiness | blocked-open-questions | none | Use this topic before treating the local tarball install path as an internal npm release: current proof covers npm pack contents and a temporary-prefix metro install, while registry publishing, release provenance, approval ownership, and signing or equivalent integrity evidence remain explicit blockers. | metro docs explain package.publish-readiness --json |
| ci.local-checks | local-proof-backed | none | Use this topic when wiring metro into CI or agent automation: run package, install, unit, golden, site, syntax, and secret-scan checks that need no API keys, then parse metro JSON contracts instead of scraping prose. | metro docs explain ci.local-checks --json |
| setup.troubleshooting | local-proof-backed | none | Use this topic when the first safe preview path, local profile doctor, or profile resolution fails: keep setup local-only, inspect schemaVersion and findings, fix the profile file or non-secret fingerprint, then rerun setup doctor and setup resolve before using profile evidence in read-gate or preflight manifests. | metro docs explain setup.troubleshooting --json |
| input.normalize | local-proof-backed | none | Use metro input normalize to turn local JSON/YAML workflow shape inputs and reviewed expert API request envelopes into stable canonical JSON, validation findings, and deterministic hashes before preview, proof, or future apply work. | metro docs explain input.normalize --json |
| output.anatomy | local-proof-backed | none | Use this topic to read metro JSON output consistently: identify the schema version first, check live-execution flags and API access, inspect status/refusal fields, then follow generatedFrom, sourceIds, sources, payload hashes, and nextSafeStep before using the output as local evidence. | metro docs explain output.anatomy --json |
| refusal.troubleshooting | local-proof-backed | none | Use this topic when metro refuses a live read, live apply, unsupported workflow apply, or unsafe input: keep the refusal as a safety signal, identify the schema and blocked command, then gather the local preview, preflight, gate, audit, read-back, and approval evidence named by nextSafeStep before retrying any narrower local command. | metro docs explain refusal.troubleshooting --json |
| billing-provider.attachment | local-preview-backed | none | Use the local Stripe billing-provider attachment shape to validate delivery method scope, existing configuration policy, Stripe draft behavior, and read-back evidence before any future customer billing-provider write is considered. | metro docs explain billing-provider.attachment --json |
| customer.setup | local-preview-backed | none | Use the local customer-setup shape to validate customer identity, ingest alias collision review, optional Stripe billing-provider configuration, customer configuration, read-back checks, and rollback planning before any customer create workflow is considered. | metro docs explain customer.setup --json |
| credits.product.decision | local-preview-backed | none | When someone says "add a credits product", stop and classify before creating Metronome objects. Most asks are (A) a new pricing dimension on an existing USAGE product, (B) a credit grant on an existing contract, (C) credits inside a package commit schedule, or rarely (D) a greenfield USAGE product + billable metric. Do not create products or billable metrics for new action codes. | metro docs explain credits.product.decision --json |
| workspace.routing | local-preview-backed | none | Use metro workspace explain, metro plan <intent>, and metro route --goal to pick optimal shapes, refuse suboptimal API paths (e.g. products.create for a new action code), and bind sandbox/production via tenant profiles. For ambiguous "credits product" asks start with metro docs explain credits.product.decision --markdown. | metro docs explain workspace.routing --json |
| contract-overrides.inspection | local-proof-backed | none | Use contracts.getRateSchedule for customer-specific contract prices that must include contract-level overrides; use rateCards.getRates for rate-card source prices before customer contract overrides. | metro docs explain contract-overrides.inspection --json |
| product-rate-retirement.readback | local-proof-backed | none | Use rateCards.addRates only as a reviewed future write for closing rates; verify product retirement with rateCards.getRates, rateCards.getRateSchedule, products.get, and invoice-impact evidence before any product archive is considered. | metro docs explain product-rate-retirement.readback --json |
Lookup kinds
| kind | count | description | examples |
|---|---|---|---|
| api-endpoint | 69 | Reviewed Metronome endpoint IDs from the local expert API catalog. | usage.ingest, usage.groups, usage.batch, events.search |
| api-family | 14 | Endpoint-family summaries derived from the reviewed API catalog. | billable-metrics, billing-provider, contracts, credits |
| command | 166 | Supported local command metadata from the command catalog. | command:input.normalize, command:docs.explain, command:api.read-plan |
| shape | 16 | Workflow shape summaries and validator links from the shape catalog. | shape:customer-setup, shape:pro-annual, shape:pro-annual-self-serve-v2, shape:free-credit-trial |
| validator-rule | 68 | Validator rules, severities, and remediation guidance. | MTR-TENANT-001, MTR-TENANT-002, MTR-TENANT-003, MTR-TENANT-004 |
| gotcha | 59 | Known failure modes from the gotcha register. | gotcha:tenant-selected-by-key, gotcha:env-file-not-authorization, gotcha:never-infer-production-from-key-presence, gotcha:fingerprints-not-key-values |
| permission-scope | 25 | Permission scopes and owner/approval policy requirements. | metronome:billable-metrics:read, metronome:billable-metrics:write, metronome:billing-provider:read, metronome:billing-provider:write |
| example-fixture | 8 | Checked command/output fixtures used as local proof examples. | example:api.catalog.contracts, example:api.explain.contracts-create, example:api.search.contract-create, example:api.diff.contracts-create-vs-update-end-date |
sourceIds
credits-product-decisiondanger-zoneendpoint-matrixexample:api.catalog.contractsexample:api.explain.contracts-createexample:api.preflight.contracts-createexample:api.preview.contracts-createexample:api.readinesslocal-probe-prod-all-ratesmetro-api-preview-goldenmetro-api-read-audit-products-get-fixturemetro-api-read-audit-products-get-goldenmetro-api-read-audit-rate-cards-get-rates-fixturemetro-api-read-audit-rate-cards-get-rates-goldenmetro-api-read-mock-contracts-rate-schedule-goldenmetro-api-read-mock-rate-cards-get-rates-goldenmetro-api-read-pipeline-contracts-rate-schedule-goldenmetro-api-read-pipeline-goldenmetro-api-read-pipeline-products-get-goldenmetro-api-read-pipeline-rate-card-schedule-goldenmetro-api-read-pipeline-rate-cards-get-rates-goldenmetro-api-read-plan-golden-contracts-rate-schedulemetro-api-read-plan-golden-products-getmetro-api-read-plan-golden-rate-card-schedulemetro-api-read-plan-golden-rate-cards-get-ratesmetro-api-read-refusal-goldenmetro-api-readiness-goldenmetro-api-readiness-summary-goldenmetro-billing-provider-attach-fixturemetro-billing-provider-inspect-plan-goldenmetro-billing-provider-preview-goldenmetro-command-catalogmetro-command-reference-goldenmetro-customer-setup-fixturesmetro-customer-setup-preview-goldenmetro-docs-explain-billing-provider-attachment-goldenmetro-docs-explain-ci-local-checks-goldenmetro-docs-explain-customer-setup-goldenmetro-docs-explain-first-safe-preview-goldenmetro-docs-explain-input-normalize-goldenmetro-docs-explain-install-troubleshooting-goldenmetro-docs-explain-output-anatomy-goldenmetro-docs-explain-package-publish-readiness-goldenmetro-docs-explain-product-rate-retirement-readback-goldenmetro-docs-explain-refusal-troubleshooting-goldenmetro-docs-explain-setup-troubleshooting-goldenmetro-docs-explain-topic-index-goldenmetro-input-filesmetro-input-normalizemetro-input-normalize-api-goldenmetro-input-normalize-shape-goldenmetro-input-referencemetro-input-reference-goldenmetro-install-testmetro-package-testmetro-product-retirement-preview-goldenmetro-release-artifact-manifest-goldenmetro-release-evidence-check-goldenmetro-release-evidence-plan-goldenmetro-release-readiness-goldenmetro-release-retention-policy-goldenmetro-safe-preview-quickstartmetro-setup-fixturesmetro-setup-profilesmetro-setup-quickstartmetro-setup-resolve-goldenmetro-workspace-routingmetronome-customers-hierarchiesmetronome-stripe-deliverypackages-contractsrate-cards-dimensionalshape-complimentary-credit-grantshape-dimensional-rate-card
sources
docs/SAFETY.mddocs/metronome-cli/CLI_ARCHITECTURE.mddocs/metronome-cli/COOKBOOK.mddocs/metronome-cli/GOTCHAS.mddocs/metronome-cli/QUICKSTART.mddocs/metronome-cli/README.mddocs/metronome-cli/SHAPE_CATALOG.mddocs/metronome-cli/SHAPE_CATALOG.md#product-or-rate-retirementdocs/metronome-cli/VALIDATION_AND_GUARDRAILS.mddocs/metronome-cli/VALIDATION_AND_GUARDRAILS.md#rate-card-rulesdocs/metronome-cli/one-goal.mddocs/metronome-cli/site/agents.mddocs/metronome-cli/site/install.htmldocs/metronome-cli/site/install.html#first-safe-previewdocs/metronome-cli/site/integration.htmldocs/metronome-cli/site/verify-site.jshttps://docs.metronome.com/api-reference/billable-metrics/create-a-billable-metric.mdhttps://docs.metronome.com/api-reference/contracts/get-the-rate-schedule-for-a-contract.mdhttps://docs.metronome.com/api-reference/customers/create-a-customer.mdhttps://docs.metronome.com/api-reference/customers/fetch-billing-provider-configurations-for-a-customer.mdhttps://docs.metronome.com/api-reference/customers/get-a-customer.mdhttps://docs.metronome.com/api-reference/customers/list-customers.mdhttps://docs.metronome.com/api-reference/customers/set-billing-provider-configurations-for-a-customer.mdhttps://docs.metronome.com/api-reference/customers/update-a-customer-configuration.mdhttps://docs.metronome.com/api-reference/invoices/list-invoices.mdhttps://docs.metronome.com/api-reference/products/archive-a-product.mdhttps://docs.metronome.com/api-reference/products/create-a-product.mdhttps://docs.metronome.com/api-reference/products/get-a-product.mdhttps://docs.metronome.com/api-reference/rate-cards/add-rates.mdhttps://docs.metronome.com/api-reference/rate-cards/get-a-rate-schedule.mdhttps://docs.metronome.com/api-reference/rate-cards/get-rates.mdhttps://docs.metronome.com/api-reference/settings/list-account-level-billing-providers.mdpackage.jsonpackages/metro-core/src/api-catalog/preview.jspackages/metro-core/src/api-catalog/read-pipeline.jspackages/metro-core/src/api-catalog/read-refusal.jspackages/metro-core/src/api-catalog/readiness.jspackages/metro-core/src/api-catalog/validation.jspackages/metro-core/src/apply-gate/index.jspackages/metro-core/src/audit/index.jspackages/metro-core/src/commands/catalog.jspackages/metro-core/src/docs/explain.jspackages/metro-core/src/docs/input-reference.jspackages/metro-core/src/input/files.jspackages/metro-core/src/input/normalize.jspackages/metro-core/src/inspect/index.jspackages/metro-core/src/preflight/index.jspackages/metro-core/src/preview/index.jspackages/metro-core/src/proof/sandbox-manifest.jspackages/metro-core/src/release/readiness.jspackages/metro-core/src/setup/profiles.jspackages/metro-core/src/shapes/index.jspackages/metro-core/src/validators/index.jsskills/metronome-customers-hierarchies/SKILL.mdskills/metronome-danger-zone/SKILL.mdskills/metronome-danger-zone/references/endpoint-matrix.mdskills/metronome-danger-zone/references/endpoint-matrix.md#11-invoicesskills/metronome-danger-zone/references/endpoint-matrix.md#15-settings--securityskills/metronome-danger-zone/references/endpoint-matrix.md#3-productsskills/metronome-danger-zone/references/endpoint-matrix.md#4-rate-cardsskills/metronome-danger-zone/references/endpoint-matrix.md#6-customersskills/metronome-danger-zone/references/endpoint-matrix.md#7-billing-provider-configs-stripeskills/metronome-danger-zone/references/endpoint-matrix.md#9-contractsskills/metronome-packages-contracts/SKILL.mdskills/metronome-stripe-delivery/SKILL.md
Agent notes
- Prefer
--jsonwhen scripting parsers; use--markdownwhen loading context into an agent. - Never treat HTML as the source of truth, regenerate from
metro docs <ref> --markdown. - Live reads/writes still require tenant flags + confirmation tokens.
Plus 14 source-document topics, one per Metronome docs page metro cites. List them with
metro docs explain --list.