pandora-cli-skills 1.1.69 → 1.1.71

package/README.md

@@ -57,6 +57,7 @@ Node.js `>=18` required.
 
 ```bash
 # compact capability digest for agents
+pandora --output json bootstrap
 pandora --output json capabilities
 
 # schema for typed consumers
@@ -85,12 +86,17 @@ pandora --output json sell --dry-run \
 pandora --output json operations list --status planned,queued,running --limit 20
 ```
 
+Notes:
+- `bootstrap` is the preferred first call for cold agents and returns canonical tools by default.
+- Use `pandora --output json bootstrap --include-compatibility` only when you are debugging or migrating a legacy caller that still speaks in alias commands.
+
 ## Agent-first onboarding
 
 Use this path when the consumer is an agent, not a human operator:
 
 ```bash
 # 1) discover the live contract
+pandora --output json bootstrap
 pandora --output json capabilities
 pandora --output json schema
 pandora --output json policy list
@@ -102,23 +108,55 @@ pandora mcp
 pandora mcp http [--auth-scopes <csv>]
 ```
 
+Canonical-routing note:
+- start from `bootstrap`, then resolve any follow-up decisions against canonical tool names from `bootstrap`, `capabilities`, or `schema`
+- only opt into compatibility aliases with `--include-compatibility` when you are inspecting legacy/debug workflows; do not use alias names as the default planning surface for new agents
+
 If you are embedding the shipped SDKs instead of only consuming raw JSON:
-- local SDK execution maps to `pandora mcp` over stdio
-- remote SDK execution maps to intentionally hosted `pandora mcp http ...` plus a bearer token
-- the shared JS contract export remains under `sdk/generated`
-- the embedded TypeScript SDK keeps a local loader and manifest under `sdk/typescript/generated`, but the heavy generated JSON artifacts are shared from `sdk/generated` in the published root package
-- the embedded Python SDK keeps a local manifest under `sdk/python/pandora_agent/generated` and falls back to `sdk/generated` for heavy generated JSON artifacts in the published root package
+- standalone SDK package identities:
+  - TypeScript/Node: `@pandora/agent-sdk`
+  - Python: `pandora-agent`
+- current release flow builds and verifies standalone SDK artifacts for those package identities; this document does not yet claim public registry publication
+- this repository and the root Pandora package also vendor matching SDK copies under `sdk/typescript` and `sdk/python` for parity, local audit, and in-tree consumption
+- local SDK execution maps to `pandora mcp` over stdio on the same machine
+- remote SDK execution maps to intentionally hosted `pandora mcp http ...`; remote clients connect to the `/mcp` endpoint with a bearer token
+- standalone SDK packages ship package-local generated artifacts
+- the repository root also keeps a shared contract bundle under `sdk/generated` for parity checks, custom generators, and vendored consumers
+- the vendored TypeScript copy keeps a local loader and manifest under `sdk/typescript/generated`
+- the vendored Python copy keeps a local manifest under `sdk/python/pandora_agent/generated/manifest.json`; in the published root package its loader falls back to the shared `sdk/generated` bundle for the heavy generated JSON artifacts
 
 For live signing:
 - current builds ship policy packs and named profiles in alpha
 - current builds also ship first-party recipes in alpha via `recipe list|get|validate|run`
-- inspect them with `policy list|get|lint` and `profile list|get|validate` before exposing tools to an agent
-- do not assume every built-in signer profile is runtime-ready:
-  - implemented backends today: `read-only`, `local-env`
-  - planning/placeholder sample backends: `external-signer`, `local-keystore`
-  - current built-in ready profile: `market_observer_ro`
-  - current built-in pending profiles: `prod_trader_a`, `dev_keystore_operator`, `desk_signer_service`
-- there is not yet a universal `--profile` selector across mutating commands, so live execution still commonly resolves signing material from env / `.env` / explicit flags
+- inspect them with `policy list|get|lint` and `profile list|get|explain|validate` before exposing tools to an agent
+- treat `bootstrap` as the machine-usable recommendation surface:
+  - `defaults.policyId` / `defaults.profileId`
+  - `policyProfiles.policyPacks.recommendedReadOnlyPolicyId` / `recommendedMutablePolicyId`
+  - `policyProfiles.signerProfiles.recommendedReadOnlyProfileId` / `recommendedMutableProfileId`
+  - `nextSteps[]`
+- use `bootstrap` for safe defaults, then use `policy explain`, `policy recommend`, and `profile recommend` for exact context-aware remediation or ranking
+  - use `policy get` for pack inspection
+  - use `profile get` for raw profile state
+  - use `profile explain` for exact usability decisions
+- do not collapse signer readiness into one “pending” bucket:
+  - implementation-status fields: `implementedBackends`, `placeholderBackends`
+  - runtime-readiness fields: `readyBuiltinIds`, `degradedBuiltinIds`, `placeholderBuiltinIds`
+  - backend-level rollup: `policyProfiles.signerProfiles.backendStatuses`
+  - vocabulary: `policyProfiles.signerProfiles.statusAxes`
+  - today, all shipped signer backends are implemented: `read-only`, `local-env`, `local-keystore`, `external-signer`
+  - in the default runtime view, `market_observer_ro` is the only built-in profile reporting `ready`, and it is read-only
+  - `--runtime-local-readiness` actively probes local signer/network prerequisites and can promote built-in mutable profiles such as `prod_trader_a`, `dev_keystore_operator`, and `desk_signer_service` to `ready` when their runtime requirements are satisfied
+  - in the current runtime, no built-in mutable profile is ready
+  - current built-in mutable profile states are:
+    - `prod_trader_a`: backend rollup `degraded`, per-profile `resolutionStatus` `missing-secrets`
+    - `dev_keystore_operator`: backend rollup `degraded`, per-profile `resolutionStatus` `missing-keystore`
+    - `desk_signer_service`: backend rollup `degraded`, per-profile `resolutionStatus` `missing-context`
+  - `degraded` means the backend is implemented, but this process is still missing signer material, keystore access, external-signer context, network context, or other compatibility prerequisites
+  - use `profile list` for the compact `runtimeReady` / `resolutionStatus` view
+  - use `profile explain --id <profile-id> [--command <tool>] [--mode <mode>] [--policy-id <id>] [--chain-id <id>] [--category <id|name>]` before mutable execution to inspect `explanation.requestedContext`, `explanation.usable`, `explanation.readiness`, `explanation.compatibility`, `explanation.remediation`, and `explanation.blockers`
+- there is not yet a universal `--profile` selector across mutating commands
+- direct Pandora signer-bearing commands now accept `--profile-id` / `--profile-file` for `trade`, `sell`, `lp add`, `lp remove`, `resolve`, `claim`, `mirror deploy`, `mirror go`, `mirror sync once|run|start`, and `sports create run`
+- other live families still commonly resolve signing material from env / `.env` / explicit flags
 - the preferred agent pattern is a scoped MCP gateway plus signer material only on the runtime that actually executes live tools
 
 ## Live execution setup
@@ -138,7 +176,23 @@ Populate `.env` or process env with only the fields your live workflow actually
 - `FACTORY`
 - `USDC`
 
-## SDK And Contract Export
+## Standalone SDKs And Contract Export
+
+Current shipped consumer paths:
+- TypeScript/Node:
+  - standalone package identity: `@pandora/agent-sdk`
+  - current external install path: signed GitHub release tarball attached to the tagged Pandora release
+  - repository checkout path: `sdk/typescript` for maintainers and in-tree consumers
+  - vendored root-package copy: `pandora-cli-skills/sdk/typescript`
+- Python:
+  - standalone package identity: `pandora-agent`
+  - current external install path: signed GitHub release wheel or sdist attached to the tagged Pandora release
+  - repository checkout path: `sdk/python` for maintainers and in-tree consumers
+  - module/import name: `pandora_agent`
+- Shared static contract bundle:
+  - standalone TypeScript package: `@pandora/agent-sdk/generated`
+  - repository/root shared bundle: `sdk/generated`
+  - vendored root-package subpath: `pandora-cli-skills/sdk/generated`
 
 ```bash
 npm run generate:sdk-contracts
@@ -146,33 +200,72 @@ npm run generate:sdk-contracts
 
 Run that only from a repository checkout. The published npm package ships the generated SDK artifacts already and does not include the repo-only generator script.
 
-- This package ships SDK alpha source/artifact surfaces:
-  - JavaScript/TypeScript SDK entrypoints under `sdk/typescript`
-  - TypeScript embedded loader/manifest under `sdk/typescript/generated`
-  - Python SDK source/package under `sdk/python`
-  - Python embedded manifest under `sdk/python/pandora_agent/generated`
+- This repository ships standalone SDK alpha packages plus vendored copies and the shared contract bundle:
+  - JavaScript/TypeScript SDK package sources under `sdk/typescript`
+  - Python SDK package sources under `sdk/python`
+  - vendored TypeScript loader/manifest under `sdk/typescript/generated`
+  - vendored Python manifest under `sdk/python/pandora_agent/generated`
   - shared JS contract export under `sdk/generated`
 - `capabilities.data.transports.sdk` reports `supported=true` and `status="alpha"` in current builds.
 - Use `capabilities` for compact discovery, canonical tool routing, transport status, and registry digests.
 - Use `schema` for the authoritative contract export: JSON envelope definitions, per-command input schemas, and `commandDescriptors`.
-- In a repository checkout, `npm run generate:sdk-contracts` regenerates the shared export in `sdk/generated` and the standalone SDK-local generated copies in `sdk/typescript/generated` and `sdk/python/pandora_agent/generated`.
-- In the published root package, the shared JSON contract bundle is stored once under `sdk/generated`; embedded SDK loaders/manifests route to that shared bundle instead of duplicating it.
-- For embedded SDK consumers, prefer each SDK's own generated manifest/artifact entrypoints instead of hard-coding `sdk/generated`:
-  - TypeScript: `sdk/typescript/generated/manifest.json`
-  - Python: `sdk/python/pandora_agent/generated/manifest.json`
+- In a repository checkout, `npm run generate:sdk-contracts` regenerates the shared export in `sdk/generated` plus the standalone SDK package-local copies in `sdk/typescript/generated` and `sdk/python/pandora_agent/generated`.
+- Standalone SDK consumers should prefer the standalone package entrypoints and package-local generated artifacts:
+  - TypeScript SDK package identity: `@pandora/agent-sdk`
+  - TypeScript generated bundle subpath: `@pandora/agent-sdk/generated`
+  - Python SDK package identity: `pandora-agent`
+- Current release/distribution status:
+  - standalone SDK artifacts are built and verified in release flow
+  - use signed GitHub release assets as the external installation path unless a release explicitly announces public npm/PyPI publication
+- The root Pandora package continues to vendor matching copies:
+  - TypeScript client: `pandora-cli-skills/sdk/typescript`
+  - shared contract bundle: `pandora-cli-skills/sdk/generated`
+  - vendored manifests: `sdk/typescript/generated/manifest.json` and `sdk/python/pandora_agent/generated/manifest.json`
 - Custom generators can still export raw `capabilities` / `schema` snapshots if they need bespoke codegen.
 - Regenerate cached clients or derived types when `commandDescriptorVersion` or `registryDigest.descriptorHash` changes.
-- For most agent bootstrap flows, start with `capabilities`, `schema`, `policy`, `profile`, or MCP before embedding the alpha SDK sources into your own code.
+- For most agent bootstrap flows, start with `bootstrap`, then `schema`, `policy`, `profile`, or MCP before embedding the alpha SDK sources into your own code.
 - For direct execution instead of local codegen, connect an SDK or MCP client to `pandora mcp` for local stdio, or intentionally host `pandora mcp http ...` for remote streamable HTTP execution.
 
 ## Policy And Signer Guidance
 
 - Prefer scoped MCP access over broad live credentials when an agent can work through `pandora mcp http`. The gateway enforces bearer-token scopes from `--auth-scopes` against each tool's declared `policyScopes`.
 - Current builds ship policy packs in alpha. `capabilities.data.policyProfiles.policyPacks` reports `supported=true` and `status="alpha"`, and `pandora --output json policy list|get|lint` exposes the available built-in/user-defined packs.
-- Current builds also ship named signer profiles in alpha. `capabilities.data.policyProfiles.signerProfiles` reports `supported=true` and `status="alpha"`, and `pandora --output json profile list|get|validate` exposes sample/user profiles plus readiness metadata.
-- `capabilities.data.policyProfiles.signerProfiles` also exposes `implementedBackends`, `placeholderBackends`, `readyBuiltinIds`, and `pendingBuiltinIds`.
-- In current builds, treat only `market_observer_ro` as built-in runtime-ready by default unless `profile get` reports otherwise in your runtime.
-- There is not yet a universal `--profile` selector across mutating commands. Live execution still commonly resolves secrets from process env, `.env`, or explicit flags while profile-directed execution rolls out.
+- Current builds also ship named signer profiles in alpha. `capabilities.data.policyProfiles.signerProfiles` reports `supported=true` and `status="alpha"`, and `pandora --output json profile list|get|explain|validate` exposes sample/user profiles plus readiness metadata.
+- `bootstrap` is the canonical recommendation surface today:
+  - `defaults.policyId` and `defaults.profileId` are the cold-start defaults
+  - `policyProfiles.policyPacks.recommendedReadOnlyPolicyId` / `recommendedMutablePolicyId` are the machine-usable policy recommendations
+  - `policyProfiles.signerProfiles.recommendedReadOnlyProfileId` / `recommendedMutableProfileId` are the machine-usable profile recommendations
+  - `nextSteps[]` gives the canonical follow-up commands in order
+- `bootstrap` remains the preferred cold-start surface, but exact-context commands are also available:
+  - `policy explain`
+  - `policy recommend`
+  - `profile recommend`
+- treat those exact-context commands as follow-ups after you already know the canonical target tool and execution context; they are not a substitute for `bootstrap`
+- `capabilities.data.policyProfiles.signerProfiles` now separates implementation status from runtime readiness:
+  - implementation fields: `implementedBackends`, `placeholderBackends`
+  - runtime fields: `readyBuiltinIds`, `degradedBuiltinIds`, `placeholderBuiltinIds`, `pendingBuiltinIds`
+  - backend rollup: `backendStatuses`
+  - vocabulary: `statusAxes`
+- In the default runtime view, `market_observer_ro` is the only built-in profile reporting `ready`, and it is read-only.
+- Use `pandora --output json capabilities --runtime-local-readiness` when you want the CLI to actively probe local signer/network prerequisites; under valid runtime conditions, built-in mutable profiles such as `prod_trader_a`, `dev_keystore_operator`, and `desk_signer_service` can move from `degraded` to `ready`.
+- In the current runtime, no built-in mutable profile is ready:
+  - `prod_trader_a` resolves as `missing-secrets`
+  - `dev_keystore_operator` resolves as `missing-keystore`
+  - `desk_signer_service` resolves as `missing-context`
+- Treat `degraded` as the backend-level summary only. The exact cause lives in the per-profile payload:
+  - `profile list` for `runtimeReady` and `resolutionStatus`
+  - `profile get --id <profile-id>` for raw `resolution` and constraint details
+  - `profile explain --id <profile-id> [--command <tool>] [--mode <mode>] [--policy-id <id>] [--chain-id <id>] [--category <id|name>]` for the exact decision surface:
+    - prefer canonical command names from `bootstrap`, `capabilities`, or `schema` when filling `--command`
+    - `explanation.requestedContext.exact` tells you whether the evaluation is complete or still missing flags
+    - `explanation.requestedContext.missingFlags` tells the agent what to add before trusting the answer
+    - `explanation.remediation[]` is the machine-usable action list; treat `blockers` as the human-readable summary
+- There is not yet a universal `--profile` selector across mutating commands.
+- Direct signer-bearing execution now supports `--profile-id` / `--profile-file` on:
+  - `trade`, `sell`, `lp add`, `lp remove`, `resolve`, `claim`
+  - `mirror deploy`, `mirror go`, `mirror sync once|run|start`
+  - sports live execution paths that route through the shared sports parsers/services
+- Some families still commonly bootstrap secrets from process env, `.env`, or explicit flags, but profile-directed execution is no longer limited to the core trading/admin commands.
 - The built-in read-only pair is `research-only` plus `market_observer_ro`. Use that pattern for discovery, schema inspection, validation, and other non-signing agent workflows before granting write access.
 - If you host `pandora mcp http` without `--auth-token` or `--auth-token-file`, Pandora generates a bearer token at `~/.pandora/mcp-http/auth-token`. If the runtime cannot resolve a home directory, pass one of those flags explicitly.
 - `--private-key <hex>` remains supported because the live parser surface still accepts it, but use it as a manual fallback rather than the default operator pattern.

package/README_FOR_SHARING.md

@@ -39,6 +39,7 @@ Prerequisite: Node.js `>=18`.
 
 ```bash
 npm install
+node cli/pandora.cjs --output json bootstrap
 node cli/pandora.cjs --output json capabilities
 node cli/pandora.cjs --output json schema
 node cli/pandora.cjs --output json policy list
@@ -51,17 +52,23 @@ Operation tracking:
 - use `pandora --output json operations list --status planned,queued,running --limit 20` to inspect persisted mutable-operation records
 
 Preferred agent path:
-- start with `capabilities`, `schema`, `policy list`, `profile list`, and `recipe list`; none of those require signer material
+- start with `bootstrap`, then `schema`, `policy list`, `profile list`, and `recipe list`; none of those require signer material
 - use `pandora mcp` for local stdio tool execution
 - use `pandora mcp http --auth-scopes ...` when you intentionally want a remote MCP gateway
-- for a remote read-only planning token that covers `scan`, `quote`, `portfolio`, `mirror plan`, `sports create plan`, and `operations list|get`, use `capabilities:read,contracts:read,documentation:read,policy:read,profile:read,operations:read,scan:read,quote:read,portfolio:read,mirror:read,sports:read,network:indexer,network:rpc,network:polymarket,network:sports`
+- for a remote read-only planning token that covers `scan`, `quote`, `portfolio`, `mirror plan`, `sports create plan`, and `operations list|get`, use `capabilities:read,contracts:read,help:read,schema:read,operations:read,scan:read,quote:read,portfolio:read,mirror:read,sports:read,network:indexer,network:rpc,network:polymarket,network:sports`
 - add `operations:write` only when the remote runtime needs `operations cancel|close`; over MCP those mutating calls also require `intent.execute=true`
 - give the agent the minimum bearer-token scopes it needs
 - only provision signing secrets on the runtime that will actually execute live mutating tools
 - if you are embedding the shipped SDKs, use each package's own generated artifacts:
-  - `sdk/typescript/generated` for the embedded TypeScript loader/manifest
-  - `sdk/python/pandora_agent/generated` for the embedded Python manifest
-  - `sdk/generated` for the shared JS contract export
+  - standalone SDK package identities are `@pandora/agent-sdk` and `pandora-agent`
+  - current release flow builds and verifies standalone SDK artifacts for those package identities; this guide does not yet claim public registry publication
+  - this shareable package also includes vendored SDK copies under `sdk/typescript` and `sdk/python`
+  - local SDK execution uses `pandora mcp`; remote SDK execution uses intentionally hosted `pandora mcp http ...` plus a bearer token to `/mcp`
+  - `sdk/typescript/generated/manifest.json` is the TypeScript manifest entrypoint
+  - `sdk/python/pandora_agent/generated/manifest.json` is the Python manifest entrypoint
+  - `sdk/generated` is the shared contract bundle
+- `bootstrap` and `GET /bootstrap` return canonical tools by default
+- only use `--include-compatibility` or `?include_aliases=1` when you are debugging or migrating a legacy caller that still depends on alias names
 
 Live execution setup:
 - run `npm run init-env`
@@ -83,17 +90,38 @@ Optional live Polymarket hedge env:
 - `POLYMARKET_HOST`
 
 Credential handling note:
-- Current builds ship policy packs and named profiles in alpha via `policy list|get|lint` and `profile list|get|validate`.
+- Current builds ship policy packs and named profiles in alpha via `policy list|get|lint` and `profile list|get|explain|validate`.
 - Current builds also ship first-party recipes in alpha via `recipe list|get|validate|run`.
 - Current live command execution still commonly resolves signer secrets from flags/env during rollout.
-- Do not assume every built-in signer profile is runtime-ready:
-  - implemented backends today: `read-only`, `local-env`
-  - planning/placeholder sample backends: `external-signer`, `local-keystore`
-  - current built-in ready profile: `market_observer_ro`
-  - current built-in pending profiles: `prod_trader_a`, `dev_keystore_operator`, `desk_signer_service`
+- Treat `bootstrap` as the recommendation surface for both policies and profiles:
+  - `defaults.policyId` / `defaults.profileId`
+  - `policyProfiles.policyPacks.recommendedReadOnlyPolicyId` / `recommendedMutablePolicyId`
+  - `policyProfiles.signerProfiles.recommendedReadOnlyProfileId` / `recommendedMutableProfileId`
+  - `nextSteps[]`
+- `bootstrap` is still the preferred cold-start surface, but standalone `policy explain`, `policy recommend`, and `profile recommend` are available for exact context-aware reasoning.
+- treat those exact-context commands as follow-ups after you already know the canonical target tool and execution context from `bootstrap`, `capabilities`, or `schema`
+- Use `policy get` for pack inspection, `profile get` for raw profile state, and `profile explain` for exact execution-context decisions.
+- Do not collapse signer readiness into one “pending” bucket:
+  - implementation-status fields: `implementedBackends`, `placeholderBackends`
+  - runtime-readiness fields: `readyBuiltinIds`, `degradedBuiltinIds`, `placeholderBuiltinIds`
+  - backend rollup: `policyProfiles.signerProfiles.backendStatuses`
+  - vocabulary: `policyProfiles.signerProfiles.statusAxes`
+  - today, all shipped signer backends are implemented: `read-only`, `local-env`, `local-keystore`, `external-signer`
+  - in the default runtime view, `market_observer_ro` is the only built-in profile reporting `ready`, and it is read-only
+  - `--runtime-local-readiness` actively probes local signer/network prerequisites and can promote built-in mutable profiles such as `prod_trader_a`, `dev_keystore_operator`, and `desk_signer_service` to `ready` when their runtime requirements are satisfied
+  - in the current runtime, no built-in mutable profile is ready
+  - current built-in mutable profile states are:
+    - `prod_trader_a`: backend rollup `degraded`, per-profile `resolutionStatus` `missing-secrets`
+    - `dev_keystore_operator`: backend rollup `degraded`, per-profile `resolutionStatus` `missing-keystore`
+    - `desk_signer_service`: backend rollup `degraded`, per-profile `resolutionStatus` `missing-context`
+  - `degraded` means the backend exists, but this runtime is still missing signer material, keystore access, external-signer context, network context, or compatibility prerequisites
+  - use `profile list` for the compact `runtimeReady` / `resolutionStatus` view
+  - use `profile explain --id <profile-id> [--command <tool>] [--mode <mode>] [--policy-id <id>] [--chain-id <id>] [--category <id|name>]` before mutable execution to inspect `explanation.requestedContext`, `explanation.usable`, `explanation.readiness`, `explanation.compatibility`, `explanation.remediation`, and `explanation.blockers`
 - Prefer process env, `.env`, or your own secret-manager wrapper that materializes those env vars before launching Pandora.
 - Avoid putting raw `--private-key` values on the command line unless you explicitly need a one-off manual override.
-- There is not yet a universal `--profile` selector across mutating commands.
+- There is not yet a universal `--profile` selector across every mutating command family.
+- Direct Pandora signer-bearing commands now accept `--profile-id` / `--profile-file` for `trade`, `sell`, `lp add`, `lp remove`, `resolve`, `claim`, `mirror deploy`, `mirror go`, `mirror sync once|run|start`, and `sports create run`.
+- Mirror deploy/go/sync flows and sports live execution paths now also accept profile selectors in current builds; use `pandora --output json capabilities` or `schema` to confirm support on the exact command family you plan to call.
 
 ## Documentation map
 - [`SKILL.md`](./SKILL.md)
@@ -125,7 +153,23 @@ Credential handling note:
 - [`docs/trust/support-matrix.md`](./docs/trust/support-matrix.md)
   - support status and guarantees for local CLI, MCP transports, SDKs, benchmarks, and packaged docs
 
-## SDK And Contract Export
+## Standalone SDKs And Contract Export
+
+Current shipped consumer paths:
+- TypeScript/Node:
+  - standalone package identity: `@pandora/agent-sdk`
+  - current external install path: signed GitHub release tarball attached to the tagged Pandora release
+  - unpacked tree path: `sdk/typescript` for maintainers and in-tree consumers
+  - vendored root-package copy: `pandora-cli-skills/sdk/typescript`
+- Python:
+  - standalone package identity: `pandora-agent`
+  - current external install path: signed GitHub release wheel or sdist attached to the tagged Pandora release
+  - embedded package source: `sdk/python` for maintainers and in-tree consumers
+  - module/import name: `pandora_agent`
+- Shared contract bundle:
+  - standalone TypeScript package: `@pandora/agent-sdk/generated`
+  - installed root-package subpath: `pandora-cli-skills/sdk/generated`
+  - unpacked tree path: `sdk/generated`
 
 ```bash
 npm run generate:sdk-contracts
@@ -133,20 +177,28 @@ npm run generate:sdk-contracts
 
 Run that only from a repository checkout. The published npm package already includes the generated SDK artifacts and does not ship the repo-only generator script.
 
-- This package ships SDK alpha source/artifact surfaces:
-  - JavaScript/TypeScript SDK entrypoints under `sdk/typescript`
-  - TypeScript embedded loader/manifest under `sdk/typescript/generated`
-  - Python SDK source/package under `sdk/python`
-  - Python embedded manifest under `sdk/python/pandora_agent/generated`
+- This repository ships standalone SDK alpha packages plus vendored copies and the shared contract bundle:
+  - JavaScript/TypeScript SDK package sources under `sdk/typescript`
+  - Python SDK package sources under `sdk/python`
+  - vendored TypeScript loader/manifest under `sdk/typescript/generated`
+  - vendored Python manifest under `sdk/python/pandora_agent/generated`
   - shared JS contract export under `sdk/generated`
 - `capabilities.data.transports.sdk` reports `supported=true` and `status="alpha"` in current builds.
 - Export `capabilities` for compact routing, transport, and digest metadata.
 - Export `schema` for authoritative JSON Schema definitions and per-command descriptors.
-- In a repository checkout, `npm run generate:sdk-contracts` regenerates the shared export in `sdk/generated` plus the standalone SDK-local generated copies in `sdk/typescript/generated` and `sdk/python/pandora_agent/generated`.
-- In the published root package, the shared JSON contract bundle is stored once under `sdk/generated`; embedded SDK loaders/manifests route to that shared bundle instead of duplicating it.
-- SDK consumers should prefer the package-local manifests/artifacts they ship with:
-  - TypeScript: `sdk/typescript/generated/manifest.json`
-  - Python: `sdk/python/pandora_agent/generated/manifest.json`
+- In a repository checkout, `npm run generate:sdk-contracts` regenerates the shared export in `sdk/generated` plus the standalone SDK package-local copies in `sdk/typescript/generated` and `sdk/python/pandora_agent/generated`.
+- Standalone SDK consumers should prefer the standalone package entrypoints and package-local generated artifacts:
+  - TypeScript SDK package identity: `@pandora/agent-sdk`
+  - TypeScript generated bundle subpath: `@pandora/agent-sdk/generated`
+  - Python SDK package identity: `pandora-agent`
+  - use signed GitHub release assets as the external installation path unless a release explicitly announces public npm/PyPI publication
+- Current release/distribution status:
+  - standalone SDK artifacts are built and verified in release flow
+  - public npm/PyPI publication is not claimed by this guide yet
+- This shareable root package also vendors matching copies:
+  - TypeScript client: `pandora-cli-skills/sdk/typescript`
+  - shared contract bundle: `pandora-cli-skills/sdk/generated`
+  - vendored manifests: `sdk/typescript/generated/manifest.json` and `sdk/python/pandora_agent/generated/manifest.json`
 - Raw `capabilities` / `schema` exports remain available for custom generators.
 - Rebuild any generated client layer when `commandDescriptorVersion` or `registryDigest.descriptorHash` changes.
 - Use `pandora mcp` for local stdio SDK/MCP execution, or intentionally hosted `pandora mcp http ...` for remote streamable HTTP execution instead of local code generation.
@@ -155,10 +207,35 @@ Run that only from a repository checkout. The published npm package already incl
 
 - `pandora mcp http` enforces bearer-token scopes from `--auth-scopes` against each tool's declared `policyScopes`.
 - `capabilities.data.policyProfiles.policyPacks` reports `supported=true` and `status="alpha"` in current builds. Use `policy list|get|lint` to inspect the shipped packs.
-- `capabilities.data.policyProfiles.signerProfiles` reports `supported=true` and `status="alpha"` in current builds. Use `profile list|get|validate` to inspect the shipped/sample profiles and readiness metadata.
-- The signer-profile payload also exposes `implementedBackends`, `placeholderBackends`, `readyBuiltinIds`, and `pendingBuiltinIds`.
+- `capabilities.data.policyProfiles.signerProfiles` reports `supported=true` and `status="alpha"` in current builds. Use `profile list|get|explain|validate` to inspect the shipped/sample profiles and readiness metadata.
+- `bootstrap` is the canonical recommendation surface for cold agents:
+  - `defaults.policyId` / `defaults.profileId`
+  - `policyProfiles.policyPacks.recommendedReadOnlyPolicyId` / `recommendedMutablePolicyId`
+  - `policyProfiles.signerProfiles.recommendedReadOnlyProfileId` / `recommendedMutableProfileId`
+  - `nextSteps[]`
+- Keep using `bootstrap` first for defaults, and use `policy explain`, `policy recommend`, or `profile recommend` when the agent already knows the exact workflow context it wants to evaluate.
+- Compatibility aliases stay hidden by default; opt in only for legacy/debug inspection, not routine planning.
+- The signer-profile payload now separates implementation status from runtime readiness:
+  - implementation fields: `implementedBackends`, `placeholderBackends`
+  - runtime fields: `readyBuiltinIds`, `degradedBuiltinIds`, `placeholderBuiltinIds`, `pendingBuiltinIds`
+  - backend rollup: `backendStatuses`
+  - vocabulary: `statusAxes`
 - The built-in read-only bootstrap pair is `research-only` plus `market_observer_ro`.
-- Do not assume a global `--policy` or `--profile` selector exists across mutating commands yet.
+- In the default runtime view, `market_observer_ro` is the only built-in profile reporting `ready`, and it is read-only.
+- Use `pandora --output json capabilities --runtime-local-readiness` when you want the CLI to actively probe local signer/network prerequisites; under valid runtime conditions, built-in mutable profiles such as `prod_trader_a`, `dev_keystore_operator`, and `desk_signer_service` can move from `degraded` to `ready`.
+- In the current runtime, no built-in mutable profile is ready:
+  - `prod_trader_a` resolves as `missing-secrets`
+  - `dev_keystore_operator` resolves as `missing-keystore`
+  - `desk_signer_service` resolves as `missing-context`
+- Treat `degraded` as the backend-level summary only. The exact reason lives in the profile payload:
+  - `profile list` for `runtimeReady` and `resolutionStatus`
+  - `profile get --id <profile-id>` for raw `resolution`
+  - `profile explain --id <profile-id> [--command <tool>] [--mode <mode>] [--policy-id <id>] [--chain-id <id>] [--category <id|name>]` for the exact decision surface:
+    - prefer canonical command names from `bootstrap`, `capabilities`, or `schema` when filling `--command`
+    - `explanation.requestedContext.exact` tells you whether the evaluation is complete
+    - `explanation.requestedContext.missingFlags` tells you what to add before trusting the result
+    - `explanation.remediation[]` is the machine-usable action list; `blockers` is the human-readable summary
+- Do not assume a global `--policy` or `--profile` selector exists across every mutating family yet.
 - For current live automation, prefer scoped gateway tokens plus env-based signer injection over raw command-line private keys.
 
 ## Mirror operator guidance

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: pandora-cli-skills
 summary: Index and operator guide for Pandora CLI capabilities, mirror operations, and agent-native interfaces.
-version: 1.1.69
+version: 1.1.70
 ---
 
 # Pandora CLI & Skills
@@ -52,16 +52,52 @@ Start here, then open the smallest scoped doc that matches the task:
 - CLI mirror execute reruns use `--validation-ticket <ticket>`. MCP execute/live reruns use `agentPreflight = { validationTicket, validationDecision: "PASS", validationSummary }`.
 - `sports create run` does not expose a CLI `--validation-ticket`; agent-controlled execute uses `agentPreflight` / `PANDORA_AGENT_PREFLIGHT`.
 - `launch` / `clone-bet` still expose `--target-timestamp-offset-hours`; that legacy script flag is **not** the mirror timing model.
-- Prefer policy-scoped MCP access and the shipped read-only policy/profile artifacts over raw `--private-key` when operating live flows. Policy packs and named profiles are now shipped in alpha via `policy` / `profile`, but current CLI execution still commonly resolves secrets from flags/env and does not yet expose a universal `--profile` selector across mutating commands.
-- Do not assume every built-in signer profile is execution-ready. Current built-in runtime-ready profile: `market_observer_ro`. Built-in pending profiles: `prod_trader_a`, `dev_keystore_operator`, `desk_signer_service`. Implemented backends today: `read-only`, `local-env`. Placeholder planning backends: `external-signer`, `local-keystore`.
+- Prefer policy-scoped MCP access and the shipped read-only policy/profile artifacts over raw `--private-key` when operating live flows. Policy packs and named profiles are now shipped in alpha via `policy` / `profile`. Profile-directed execution already covers the highest-value signer-bearing paths:
+  - `trade`, `sell`, `lp add`, `lp remove`, `resolve`, `claim`
+  - `mirror deploy`, `mirror go`, `mirror sync once|run|start`
+  - `sports create run`
+  - `mirror deploy`, `mirror go`, `mirror sync once|run|start`
+  - sports live execution paths routed through the shared sports command/parser stack
+- Profile support is still not universal across every mutating family, so use `capabilities` / `schema` as the authority for the current command-level surface.
+- Do not collapse signer readiness into one “pending” bucket. Use `capabilities.data.policyProfiles.signerProfiles.statusAxes` plus:
+  - implementation fields: `implementedBackends`, `placeholderBackends`
+  - runtime fields: `readyBuiltinIds`, `degradedBuiltinIds`, `placeholderBuiltinIds`, `pendingBuiltinIds`
+  - backend rollup: `backendStatuses`
+  - today, all shipped signer backends are implemented: `read-only`, `local-env`, `local-keystore`, `external-signer`
+  - in the default runtime view, `market_observer_ro` is the only built-in profile reporting `ready`, and it is read-only
+  - `--runtime-local-readiness` actively probes local signer/network prerequisites and can promote built-in mutable profiles such as `prod_trader_a`, `dev_keystore_operator`, and `desk_signer_service` to `ready` when their runtime requirements are satisfied
+  - in the current runtime, no built-in mutable profile is ready
+  - current built-in mutable profile states are:
+    - `prod_trader_a`: backend rollup `degraded`, per-profile `resolutionStatus` `missing-secrets`
+    - `dev_keystore_operator`: backend rollup `degraded`, per-profile `resolutionStatus` `missing-keystore`
+    - `desk_signer_service`: backend rollup `degraded`, per-profile `resolutionStatus` `missing-context`
+  - `degraded` means the backend is implemented, but the current process is still missing signer material, keystore access, external-signer context, network context, or other compatibility prerequisites
+  - use `bootstrap` for machine-usable policy/profile recommendations:
+    - `defaults.policyId` / `defaults.profileId`
+    - `policyProfiles.policyPacks.recommendedReadOnlyPolicyId` / `recommendedMutablePolicyId`
+    - `policyProfiles.signerProfiles.recommendedReadOnlyProfileId` / `recommendedMutableProfileId`
+    - `nextSteps[]`
+  - `bootstrap` returns canonical tools by default
+  - use `--include-compatibility` or remote `include_aliases=1` only for legacy/debug workflows or migration diffing
+  - use standalone exact-context commands when needed:
+    - `policy explain --id <policy-id> --command <tool> --mode <mode> --chain-id <id> --category <id|name> [--profile-id <id>]`
+    - `policy recommend --command <tool> --mode <mode> --chain-id <id> --category <id|name> [--profile-id <id>]`
+    - `profile recommend --command <tool> --mode <mode> --chain-id <id> --category <id|name> [--policy-id <id>]`
+  - use `profile list` for the compact readiness view and `profile explain --id <profile-id> [--command <tool>] [--mode <mode>] [--policy-id <id>] [--chain-id <id>] [--category <id|name>]` when you need the exact go/no-go answer via `requestedContext`, `usable`, `readiness`, `compatibility`, `remediation`, and `blockers`
 
 ## Capability routing
 - Machine-first discovery:
+  - run `pandora --output json bootstrap` for the canonical first-call summary
   - run `pandora --output json capabilities` for the compact runtime digest
   - run `pandora --output json schema` for the full contract surface
   - run `pandora --output json policy list` to inspect shipped policy packs
   - run `pandora --output json profile list` to inspect shipped profiles, `runtimeReady`, `resolutionStatus`, and backend readiness metadata
-  - when exposing Pandora to external agents, start with `capabilities/schema`, then intentionally host `pandora mcp http --auth-scopes ...`, then provision signing secrets only on that runtime if a selected tool actually requires them
+  - keep bootstrap/capabilities/schema planning on canonical tool names by default
+  - opt into compatibility aliases only for legacy/debug workflows; do not promote alias names back into normal agent routing
+  - use `bootstrap` first for defaults; use `policy explain`, `policy recommend`, and `profile recommend` only when you already know the exact command/mode/chain/category path you want evaluated
+  - run `pandora --output json profile explain --id <profile-id> [--command <tool>] [--mode <mode>] [--policy-id <id>] [--chain-id <id>] [--category <id|name>]` before mutable execution to inspect `explanation.requestedContext`, `explanation.usable`, `explanation.readiness`, `explanation.compatibility`, `explanation.remediation`, and `explanation.blockers`
+  - use `capabilities.data.policyProfiles.signerProfiles.backendStatuses` when you need the compact backend-level split between `implemented` / `placeholder` and `ready` / `degraded`
+  - when exposing Pandora to external agents, start with `bootstrap`, then `schema`, then intentionally host `pandora mcp http --auth-scopes ...`, then provision signing secrets only on that runtime if a selected tool actually requires them
 - in a repository checkout, use `npm run generate:sdk-contracts` when regenerating the shared JS export in `sdk/generated` plus the standalone SDK-local generated copies in `sdk/typescript/generated` and `sdk/python/pandora_agent/generated`
 - SDK alpha source/artifact surfaces are already shipped in this build under `sdk/typescript`, `sdk/python`, and `sdk/generated`
 - in the published root package, the shared JSON contract bundle lives once under `sdk/generated`; the embedded TypeScript/Python SDK loaders keep their own manifests and route heavy generated artifacts to the shared bundle
@@ -97,7 +133,7 @@ Start here, then open the smallest scoped doc that matches the task:
 ## Canonical command paths
 - Discovery:
   - `pandora scan` is the canonical enriched discovery path.
-  - `pandora markets scan` remains a backward-compatible alias.
+  - `pandora markets scan` remains a backward-compatible alias for legacy/debug workflows.
   - `pandora markets list|get` are the raw indexer browse surfaces.
 - Trading:
   - `pandora quote` is the canonical read-only pricing path.
@@ -106,20 +142,22 @@ Start here, then open the smallest scoped doc that matches the task:
   - `pandora claim` is the canonical redeem path.
 - Arbitrage:
   - `pandora arb scan` is the canonical arbitrage scan path.
-  - `pandora arbitrage` remains the bounded one-shot wrapper.
+  - `pandora arbitrage` remains the bounded one-shot wrapper for legacy/debug workflows.
 - Mirror:
   - `pandora mirror browse|plan|deploy|verify|lp-explain|hedge-calc|simulate|go|sync|status|close`
 - Agent-native:
-    - `pandora --output json capabilities`
-    - `pandora --output json schema`
-    - `pandora --output json policy list|get|lint`
-    - `pandora --output json profile list|get|validate`
-    - `pandora --output json recipe list|get|validate|run`
+  - `pandora --output json bootstrap`
+  - preferred first call for cold agents; canonical tools only by default
+  - `pandora --output json capabilities`
+  - `pandora --output json schema`
+  - `pandora --output json policy list|get|lint`
+  - `pandora --output json profile list|get|explain|validate`
+  - `pandora --output json recipe list|get|validate|run`
     - use `capabilities` for compact discovery/routing and `schema` for authoritative contract export when generating client types
     - for embedded SDK consumers, load the SDK-local manifest entrypoints first rather than assuming every language reads directly from `sdk/generated`
     - `pandora mcp`
     - `pandora mcp http ...` only for remote gateway hosting, not routine discovery
-    - `pandora operations get|list|cancel|close`
+    - `pandora operations get|list|receipt|verify-receipt|cancel|close`
 
 ## PollCategory enum
 Use this mapping anywhere a deploy-style flow explicitly exposes `--category`: