pandora-cli-skills 1.1.68 → 1.1.70

package/README.md

@@ -22,14 +22,36 @@ Node.js `>=18` required.
   - root overview and routing index
 - [`docs/skills/capabilities.md`](./docs/skills/capabilities.md)
   - capability map, canonical paths, and PollCategory mapping
+- [`docs/skills/agent-quickstart.md`](./docs/skills/agent-quickstart.md)
+  - fastest safe bootstrap path for agents using local CLI, stdio MCP, remote MCP HTTP, and SDKs
 - [`docs/skills/command-reference.md`](./docs/skills/command-reference.md)
   - human-oriented command and flag reference; use capabilities/schema for machine authority
+- [`docs/skills/trading-workflows.md`](./docs/skills/trading-workflows.md)
+  - discover -> quote -> trade/sell -> claim workflows
+- [`docs/skills/portfolio-closeout.md`](./docs/skills/portfolio-closeout.md)
+  - portfolio inspection, history/export, LP exits, claim-all, and mirror closeout
 - [`docs/skills/mirror-operations.md`](./docs/skills/mirror-operations.md)
   - mirror deploy/go safety, timing, validation, sync, and closeout guidance
 - [`docs/skills/agent-interfaces.md`](./docs/skills/agent-interfaces.md)
   - schema, MCP, JSON envelopes, recovery hints, fork runtime, and error codes
+- [`docs/skills/policy-profiles.md`](./docs/skills/policy-profiles.md)
+  - policy packs, signer profiles, gateway scopes, and preferred secret handling
+- [`docs/skills/recipes.md`](./docs/skills/recipes.md)
+  - reusable safe workflows that compile to ordinary Pandora commands
+- [`docs/benchmarks/README.md`](./docs/benchmarks/README.md)
+  - public benchmark harness, release-gate role, and agent-readiness interpretation
+- [`docs/benchmarks/scenario-catalog.md`](./docs/benchmarks/scenario-catalog.md)
+  - scenario-by-scenario benchmark coverage and parity groups
+- [`docs/benchmarks/scorecard.md`](./docs/benchmarks/scorecard.md)
+  - weighted scoring, parity failures, and benchmark output interpretation
 - [`docs/skills/legacy-launchers.md`](./docs/skills/legacy-launchers.md)
   - `launch` / `clone-bet` legacy script wrappers
+- [`docs/trust/release-verification.md`](./docs/trust/release-verification.md)
+  - verify tarballs, checksums, attestations, SBOM, and cosign signatures before install
+- [`docs/trust/security-model.md`](./docs/trust/security-model.md)
+  - trust boundaries, mutation controls, and secret-handling posture across CLI, MCP, gateway, and SDKs
+- [`docs/trust/support-matrix.md`](./docs/trust/support-matrix.md)
+  - support status and guarantees for local CLI, MCP transports, SDKs, benchmarks, and packaged docs
 
 ## Quickstart
 
@@ -40,6 +62,11 @@ pandora --output json capabilities
 # schema for typed consumers
 pandora --output json schema
 
+# inspect shipped policy packs and named profiles
+pandora --output json policy list
+pandora --output json profile list
+pandora --output json recipe list
+
 # MCP server mode
 pandora mcp
 
@@ -58,6 +85,98 @@ pandora --output json sell --dry-run \
 pandora --output json operations list --status planned,queued,running --limit 20
 ```
 
+## 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 capabilities
+pandora --output json schema
+pandora --output json policy list
+pandora --output json profile list
+
+# 2) start local stdio MCP, or intentionally host remote MCP
+pandora mcp
+# or
+pandora mcp http [--auth-scopes <csv>]
+```
+
+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
+
+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
+- the preferred agent pattern is a scoped MCP gateway plus signer material only on the runtime that actually executes live tools
+
+## Live execution setup
+
+Only do this when the runtime will execute signing commands:
+
+```bash
+npm run init-env
+npm run doctor
+```
+
+Populate `.env` or process env with only the fields your live workflow actually needs:
+- `CHAIN_ID`
+- `RPC_URL`
+- `PRIVATE_KEY`
+- `ORACLE`
+- `FACTORY`
+- `USDC`
+
+## SDK And Contract Export
+
+```bash
+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`
+  - 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`
+- 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 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.
+- 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.
+
 ## Mirror safety summary
 - `mirror plan|deploy|go` use a sports-aware suggested `targetTimestamp`; they do not assume a generic `+1h` buffer.
 - Use `--target-timestamp <unix|iso>` only when you intentionally need to override the suggested close time.

package/README_FOR_SHARING.md

@@ -1,18 +1,25 @@
 # Pandora CLI & Skills — Shareable Package
 
-Sanitized, shareable copy of the Pandora CLI docs and package metadata.
+Sanitized, shareable copy of the Pandora CLI docs, SDK surfaces, and package metadata.
 
 ## Included
 - `SKILL.md`
 - `README.md`
 - `README_FOR_SHARING.md`
 - `docs/skills/*.md`
+- `docs/trust/*.md`
+- `docs/benchmarks/**`
+- `benchmarks/latest/core-report.json`
+- `sdk/generated/*`
+- `sdk/typescript/**`
+- `sdk/python/**`
 - `package.json`
 - `package-lock.json`
 - `.gitignore`
 - `scripts/.env.example`
 - `scripts/create_market_launcher.ts`
 - `scripts/create_polymarket_clone_and_bet.ts`
+- `scripts/release/install_release.sh`
 - `references/creation-script.md`
 - `references/contracts.md`
 - `references/checklist.md`
@@ -23,27 +30,49 @@ Sanitized, shareable copy of the Pandora CLI docs and package metadata.
 - local runtime secrets
 - `node_modules`
 
+Packaging note:
+- The published npm package ships the latest benchmark report and trust/reference docs.
+- The full benchmark harness, CI workflows, and release-maintainer scripts remain repository surfaces rather than installed runtime baggage.
+
 ## Setup
 Prerequisite: Node.js `>=18`.
 
 ```bash
 npm install
-npm run init-env
-npm run doctor
-npm run build
+node cli/pandora.cjs --output json capabilities
+node cli/pandora.cjs --output json schema
+node cli/pandora.cjs --output json policy list
+node cli/pandora.cjs --output json profile list
+node cli/pandora.cjs --output json recipe list
 node cli/pandora.cjs help
 ```
 
 Operation tracking:
 - use `pandora --output json operations list --status planned,queued,running --limit 20` to inspect persisted mutable-operation records
 
-Fill `scripts/.env` with:
-- `CHAIN_ID`
-- `PRIVATE_KEY`
-- `RPC_URL`
-- `ORACLE`
-- `FACTORY`
-- `USDC`
+Preferred agent path:
+- start with `capabilities`, `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`
+- 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
+
+Live execution setup:
+- run `npm run init-env`
+- run `npm run doctor`
+- then, only if this local process will sign live transactions, populate `.env` or process env with only the fields your live workflow needs:
+  - `CHAIN_ID`
+  - `PRIVATE_KEY`
+  - `RPC_URL`
+  - `ORACLE`
+  - `FACTORY`
+  - `USDC`
 
 Optional live Polymarket hedge env:
 - `POLYMARKET_PRIVATE_KEY`
@@ -53,19 +82,84 @@ Optional live Polymarket hedge env:
 - `POLYMARKET_API_PASSPHRASE`
 - `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 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`
+- 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.
+
 ## Documentation map
 - [`SKILL.md`](./SKILL.md)
   - root overview and doc router
 - [`docs/skills/capabilities.md`](./docs/skills/capabilities.md)
   - capability map and PollCategory guidance
+- [`docs/skills/agent-quickstart.md`](./docs/skills/agent-quickstart.md)
+  - fastest safe bootstrap path for external agents
 - [`docs/skills/command-reference.md`](./docs/skills/command-reference.md)
   - human-oriented command and flag reference; use capabilities/schema for machine authority
+- [`docs/skills/trading-workflows.md`](./docs/skills/trading-workflows.md)
+  - discover -> quote -> trade/sell -> claim workflows
+- [`docs/skills/portfolio-closeout.md`](./docs/skills/portfolio-closeout.md)
+  - portfolio inspection, LP exits, claim-all, mirror closeout, and operation tracking
 - [`docs/skills/mirror-operations.md`](./docs/skills/mirror-operations.md)
   - mirror safety, validation, sync, and closeout workflow
 - [`docs/skills/agent-interfaces.md`](./docs/skills/agent-interfaces.md)
   - schema, MCP, JSON envelopes, recovery hints, and runtime contracts
+- [`docs/skills/policy-profiles.md`](./docs/skills/policy-profiles.md)
+  - policy packs, signer profiles, gateway scopes, and secret-handling guidance
+- [`docs/skills/recipes.md`](./docs/skills/recipes.md)
+  - reusable safe workflows that compile to ordinary Pandora commands
 - [`docs/skills/legacy-launchers.md`](./docs/skills/legacy-launchers.md)
   - legacy `launch` / `clone-bet` notes
+- [`docs/trust/release-verification.md`](./docs/trust/release-verification.md)
+  - verify tarballs, checksums, attestations, SBOM, and cosign signatures before install
+- [`docs/trust/security-model.md`](./docs/trust/security-model.md)
+  - trust boundaries, mutation controls, and secret-handling posture across CLI, MCP, gateway, and SDKs
+- [`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
+
+```bash
+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`
+  - 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`
+- 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.
+
+## Policy And Profile Status
+
+- `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`.
+- 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.
+- For current live automation, prefer scoped gateway tokens plus env-based signer injection over raw command-line private keys.
 
 ## Mirror operator guidance
 - `mirror plan|deploy|go` use a sports-aware suggested `targetTimestamp`; they do not rely on a generic `+1h` rule.

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.68
+version: 1.1.70
 ---
 
 # Pandora CLI & Skills
@@ -13,14 +13,36 @@ Start here, then open the smallest scoped doc that matches the task:
 
 - [`docs/skills/capabilities.md`](./docs/skills/capabilities.md)
   - command families, canonical paths, use-case routing, and PollCategory mapping
+- [`docs/skills/agent-quickstart.md`](./docs/skills/agent-quickstart.md)
+  - smallest safe bootstrap for agents using local CLI, stdio MCP, remote MCP HTTP, or SDK consumers
 - [`docs/skills/command-reference.md`](./docs/skills/command-reference.md)
   - human-oriented command and flag reference, sports matrix, mirror subcommands, and quant/model detail; use capabilities/schema for machine authority
+- [`docs/skills/trading-workflows.md`](./docs/skills/trading-workflows.md)
+  - canonical discover -> quote -> buy/sell -> claim flows, plus arbitrage routing
+- [`docs/skills/portfolio-closeout.md`](./docs/skills/portfolio-closeout.md)
+  - portfolio inspection, history/export, LP exits, claim-all, operations, and mirror closeout
 - [`docs/skills/mirror-operations.md`](./docs/skills/mirror-operations.md)
   - mirror timing, validation, independent-source rules, deploy/go workflow, sync, and closeout guidance
 - [`docs/skills/agent-interfaces.md`](./docs/skills/agent-interfaces.md)
   - schema, MCP, JSON envelopes, recovery hints, fork runtime, streams, and error codes
+- [`docs/skills/policy-profiles.md`](./docs/skills/policy-profiles.md)
+  - policy packs, signer profiles, gateway scopes, and preferred secret-handling guidance
+- [`docs/skills/recipes.md`](./docs/skills/recipes.md)
+  - reusable safe workflows that compile to ordinary Pandora commands with policy/profile validation
+- [`docs/benchmarks/README.md`](./docs/benchmarks/README.md)
+  - benchmark harness overview, release-gate role, and agent-readiness framing
+- [`docs/benchmarks/scenario-catalog.md`](./docs/benchmarks/scenario-catalog.md)
+  - scenario-by-scenario benchmark coverage and parity groups
+- [`docs/benchmarks/scorecard.md`](./docs/benchmarks/scorecard.md)
+  - weighted scoring, parity failures, and interpretation of benchmark output
 - [`docs/skills/legacy-launchers.md`](./docs/skills/legacy-launchers.md)
   - `launch` / `clone-bet` legacy script wrappers and how they differ from mirror flows
+- [`docs/trust/release-verification.md`](./docs/trust/release-verification.md)
+  - release verification flow for checksums, provenance attestations, SBOM, and cosign signatures
+- [`docs/trust/security-model.md`](./docs/trust/security-model.md)
+  - trust boundaries, mutation controls, secret handling, and release posture
+- [`docs/trust/support-matrix.md`](./docs/trust/support-matrix.md)
+  - support guarantees and limits for local CLI, MCP transports, SDKs, benchmarks, and packaged docs
 
 ## Critical safety rules
 - `mirror plan|deploy|go` do **not** assume a generic `+1h` close buffer. They use a sports-aware suggested `targetTimestamp`; use `--target-timestamp <unix|iso>` only when intentionally overriding that suggestion.
@@ -30,20 +52,45 @@ 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`.
 
 ## Capability routing
 - Machine-first discovery:
   - 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
+- 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
   - run `pandora mcp http ...` only when intentionally hosting the remote HTTP MCP gateway for external agents
 - Discovery, scanning, and market lookup:
   - open [`docs/skills/capabilities.md`](./docs/skills/capabilities.md)
+- First-time agent bootstrap:
+  - open [`docs/skills/agent-quickstart.md`](./docs/skills/agent-quickstart.md)
 - Exact flags for a command family:
   - open [`docs/skills/command-reference.md`](./docs/skills/command-reference.md)
+- Buy/sell/claim/arbitrage workflows:
+  - open [`docs/skills/trading-workflows.md`](./docs/skills/trading-workflows.md)
+- Portfolio inspection, LP exits, and closeout:
+  - open [`docs/skills/portfolio-closeout.md`](./docs/skills/portfolio-closeout.md)
 - Mirror deployment, verification, sync, or closeout:
   - open [`docs/skills/mirror-operations.md`](./docs/skills/mirror-operations.md)
 - Agent, MCP, schema, JSON output, or recovery contracts:
   - open [`docs/skills/agent-interfaces.md`](./docs/skills/agent-interfaces.md)
+  - use it for policy scope behavior, gateway auth guidance, and signer-profile status
+- Policy packs, signer profiles, or gateway scope design:
+  - open [`docs/skills/policy-profiles.md`](./docs/skills/policy-profiles.md)
+- Reusable workflows and safe recipe execution:
+  - open [`docs/skills/recipes.md`](./docs/skills/recipes.md)
+- Benchmark methodology, scenarios, or scorecards:
+  - open [`docs/benchmarks/README.md`](./docs/benchmarks/README.md)
+  - then [`docs/benchmarks/scenario-catalog.md`](./docs/benchmarks/scenario-catalog.md) or [`docs/benchmarks/scorecard.md`](./docs/benchmarks/scorecard.md) as needed
+- Release verification, support matrix, or security posture:
+  - open [`docs/trust/release-verification.md`](./docs/trust/release-verification.md)
+  - then [`docs/trust/support-matrix.md`](./docs/trust/support-matrix.md) or [`docs/trust/security-model.md`](./docs/trust/security-model.md) as needed
 - Manual market launcher scripts:
   - open [`docs/skills/legacy-launchers.md`](./docs/skills/legacy-launchers.md)
 
@@ -65,6 +112,11 @@ Start here, then open the smallest scoped doc that matches the task:
 - 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`
+    - 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`