@revfleet/hscli 0.8.12 → 0.9.0

package/docs/COMMAND_TREE.md

@@ -1,6 +1,6 @@
 # COMMAND_TREE
 
-> Updated: 2026-04-17 for 0.3.0
+> Updated: 2026-07-09 for 0.9.0
 > See also: [COMMAND_COMPATIBILITY.md](COMMAND_COMPATIBILITY.md) · [ARCHITECTURE.md](ARCHITECTURE.md) · [MCP.md](MCP.md)
 
 High-level map of every hscli command. For detailed args and examples per command, run `hscli <domain> <cmd> --help`.
@@ -8,7 +8,7 @@ High-level map of every hscli command. For detailed args and examples per comman
 ## Global flags (apply to every command)
 
 - `--profile <name>` — Auth profile (default: `default`)
-- `--json` / `--format <table|csv|yaml|json>` — Output format
+- `--json` / `--format <table|csv|yaml|json|jsonl>` — Output format (`jsonl` streams one compact envelope per result)
 - `--dry-run` — Simulate without mutating
 - `--force` — Required for live writes / deletes
 - `--policy-file <path>` — Load write/delete policy
@@ -25,29 +25,60 @@ High-level map of every hscli command. For detailed args and examples per comman
 - `hscli auth logout [--profile <name>]`
 - `hscli auth profiles` — list profiles
 - `hscli auth profile-show [--profile <name>]`
+- `hscli auth whoami` — show profile, auth mode, portal/user identity, scopes, routing, and expiry without secrets
 - `hscli auth token-info`
 - `hscli auth set-mode <profile> read-only|read-write`
 - `hscli auth set-hublet <profile> <hublet>` — persist hublet-aware API routing
 - `hscli auth oauth-url --client-id <id> --redirect-uri <uri> --scope <scopes>`
-- `hscli auth oauth-exchange --client-id <id> --client-secret <secret> --redirect-uri <uri> --code <code>`
+- `hscli auth oauth-exchange --client-id <id> --client-secret-env <env> --redirect-uri <uri> --code <code>`
+- `hscli auth refresh [--profile <name>]` — refresh an OAuth profile immediately; normal requests refresh automatically before expiry
 - `hscli auth vault-encrypt` | `vault-decrypt` | `vault-rotate` — encrypted token vault
 
 ## Doctor
 
 - `hscli doctor capabilities [--refresh]` — probe portal tier + scopes
+- `hscli doctor parity` — summarize hscli coverage across public API, internal-adapter, hybrid, and UI-only HubSpot surfaces
 - `hscli doctor scopes list|presets|explain|diff` — local HubSpot scope catalog and preset diffing
 
 ## Guide
 
 - `hscli ui` / `hscli home` — terminal home for profile context, safety state, next action, and operator workflows
-- `hscli guide [--goal portal-migration|setup|read|fetch|write|guardrails|property-preflight|audit-trace|explore]` — guided workflows for common operator tasks
+- `hscli guide [--goal portal-migration|portal-backup|setup|read|fetch|write|guardrails|property-preflight|audit-trace|explore]` — guided workflows for common operator tasks
 - `hscli /migration` — portal/schema migration workflow
+- `hscli /backup` — 360-degree portal backup workflow
 - `hscli /setup` — auth, hublet routing, scopes, and capability setup
 - `hscli /read` — safe source-portal read workflow
 - `hscli /fetch` / `hscli /get` — get records or metadata without mutating the portal
 - `hscli /write` — target-portal write workflow with dry-run + trace
 - `hscli /guardrails` — policy, read-only, trace, and scope checks
 
+## Agent
+
+- `hscli agent list` — list deterministic operator recipes (`data-cleanup`, `pipeline-risk`, `automation-risk`)
+- `hscli agent plan <recipe>` — render a public-API-first, audit-friendly runbook without executing HubSpot requests
+- `hscli agent schedule render <recipe> [--target cron|github-actions|launchd] [--cron "0 8 * * 1"]` — render a schedule artifact; does not install it
+
+## Context
+
+- `hscli context build [--sample-limit 1..100]` — read a small public-API portal profile for agent/runbook context: portal metadata, owners, teams, workflows, CRM sample totals, profile classification, recommended runbooks, and operator questions. Read-only.
+
+## Portals
+
+- `hscli portals list` — local inventory of auth profiles/portal metadata without exposing tokens or calling HubSpot
+- `hscli portals plan [--profiles live,sandbox] [--runbook data-cleanup|pipeline-risk|automation-risk] [--include-context] [--sample-limit 1..100]` — render explicit per-profile context/runbook commands. Plan-only: no HubSpot requests.
+
+## Backup
+
+- `hscli backup plan --portal-id <id> [--out-dir <path>] [--include-internal] [--internal-mode claude-extension|browser-session|manual]` — render a HubSpot 360 downgrade/migration backup runbook. Plan-only: no HubSpot requests, no local file writes.
+
+## Internal Capture
+
+- `hscli internal surfaces` — list allowlisted browser-session capture surfaces and guardrails. No HubSpot requests.
+- `hscli internal coverage` — summarize the internal endpoint docs, allowlisted capture surface counts, read-like POST counts, parameterized endpoints, and promotion policy for future guarded write/replay adapters. No HubSpot requests.
+- `hscli internal capture --surface <id> --portal-id <id> --cookie-file <file> --out-dir <dir>` — capture one allowlisted internal surface to JSON plus `capture-manifest.json`.
+- `hscli internal capture --surface <id> --endpoint <endpoint-id> --body-file <endpoint-id=path> --portal-id <id> --cookie-file <file> --out-dir <dir>` — capture one allowlisted read-only POST/search/RPC endpoint with an explicit JSON body and request-body hash proof.
+- `hscli internal capture --all --portal-id <id> --cookie-file <file> --out-dir <dir>` — capture every allowlisted endpoint that has enough inputs; placeholder/body-heavy endpoints are skipped into the manifest.
+
 ## CRM (23 sub-command files)
 
 Objects:
@@ -55,14 +86,14 @@ Objects:
 - `hscli crm quotes|products|line-items|goals list|get|search|create|update|delete [...]`
 - `hscli crm payments|invoices|subscriptions list|get [...]` — commerce
 - `hscli crm custom-objects schemas list|get|create|update|delete`
-- `hscli crm custom-objects records list|get|search|create|update|delete`
+- `hscli crm custom-objects records list|get|search|create|update|delete|batch-read|batch-create|batch-update|batch-archive`
 - `hscli crm engagements (notes|calls|tasks|emails|meetings) list|get|create|update|delete`
 - `hscli crm activities export <objectType> <recordId>` — export recoverable record activities: engagements, memberships, selected property history
 
 Properties + pipelines + associations:
 - `hscli crm properties list|get|create|batch-create|update|delete` + `hscli crm properties groups list|create|update|delete`
 - `hscli crm pipelines list|get|create|update|delete` + `hscli crm pipelines stages create|update|delete`
-- `hscli crm associations list|get|create|delete`
+- `hscli crm associations list|batch-read|batch-create|create|delete`
 - `hscli crm owners list|get`
 
 Imports + sync + introspection:
@@ -76,6 +107,7 @@ Imports + sync + introspection:
 
 - `hscli marketing emails list|get|create|update|delete`
 - `hscli marketing emails stats <emailId>` — **per-email engagement metrics**
+- `hscli marketing emails utm-audit [--active-only] [--max-pages n]` — **scan emails for manual utm_\* tags** (blast radius of switching source tracking to REWRITE_ALL)
 - `hscli marketing campaigns list|get|create|update|delete`
 - `hscli marketing ads accounts|campaigns list|get`
 - `hscli marketing social accounts|posts list|get`
@@ -86,19 +118,35 @@ Imports + sync + introspection:
 - `hscli marketing events list|get|create|update|delete`
 - `hscli marketing behavioral-events list|get|create|update`
 
-## Sales (4 files)
+## Email tracking (browser-session)
+
+Per-email open+click tracking via the internal edit-publish buffer — flips `disableAllTracking` on drafts **and** published/automated emails, bypassing the client-side REWRITE_ALL gate (no portal-wide UTM setting change needed). Needs `--cookie`/`--csrf`/`--portal-id`.
+
+- `hscli email-tracking disable|enable --ids <ids>|--ids-file <path>` — turn open+click tracking off/on (dry-run/force gated; republishes published emails, no re-send)
+- `hscli email-tracking status --ids <ids>` — read current `disableAllTracking` + publish state
+- `hscli email-tracking gate` — explain the 5 site-settings conditions that gate the in-app toggle (read-only)
+- `hscli email-tracking test-send --id <id> --to <addr> [--plain-text]` — send a test copy (no workflow enrollment)
+- `hscli email-tracking resolve-link <url>` — resolve a `hubspotlinks.com/Ctc/…` link to its destination + UTM params
+
+## Sales (3 files)
 
 - `hscli sales sequences list|get|enrollments`
 - `hscli sales meetings list|get|create|update`
-- `hscli sales calling list|get`
-- `hscli sales goals list|get`
+- `hscli sales calling settings|recordings list`
+
+## Sales Content Internal
+
+- `hscli sales-content search` — internal browser-session discovery across sequences, templates, playbooks, documents, and snippets
+- `hscli sequences list|get|create|delete|migrate` — internal full-fidelity sequence read/write/migration surface
+- `hscli sales-templates list|get|usage|create` — internal sales-template read/write surface
+- `hscli playbooks list|get|questions|create|update|delete|migrate` — internal playbook read/write/migration surface via Chirp RPC
 
 ## Service (4 files)
 
 - `hscli service conversations list|get|send-message`
 - `hscli service feedback list|get`
 - `hscli service chatflows list|get|create|update|delete`
-- `hscli service knowledge-base articles list|get|create|update|delete`
+- `hscli service kb status`
 - `hscli service pipelines list|get|create|update`
 
 ## CMS
@@ -119,6 +167,10 @@ Imports + sync + introspection:
 
 - `hscli reporting dashboards list|get`
 - `hscli reporting reports list|get`
+- `hscli reports pull object-fill-rate --object <type> [--properties <csv>]`
+- `hscli reports pull property-distribution --object <type> --property <name>`
+- `hscli reports pull email-recipients --campaign-ids <ids> [--event-types <csv>] [--contact-properties <csv>]` — uses contact `email` as an internal enrichment key, but only emits requested contact properties
+- `hscli reports pull source-target-parity --source-profile <profile> --target-profile <profile> --objects <csv>`
 
 ## Exports
 
@@ -127,10 +179,18 @@ Imports + sync + introspection:
 
 ## Settings
 
-- `hscli settings users list|get|create|update|delete` + `roles list`
+- `hscli settings users list|get|create|update|delete` + `roles list` — `create` suppresses invite emails unless `--allow-invite-email` is passed
 - `hscli settings teams list`
-- `hscli settings permission-sets list|get|create|update|delete` — internal session-auth endpoint
-- `hscli settings business-units list`
+- `hscli settings permission-sets list|get|create|update|delete|clone` — internal session-auth endpoint
+- `hscli settings permission-sets users list|get|batch-read|assign|assign-batch` — internal app-users payloads and permission-set assignments
+- `hscli settings permission-sets assignments list` — portal-wide user-to-permission-set assignment map
+- `hscli settings permission-sets roles list|get` + `role-categories` + `scopes` — atomic role catalog and scope buckets used by permission sets
+- `hscli settings permission-sets audit assignment-history|role-change-history|user-access --data <json>` — allowlisted permission audit Chirp RPCs
+- `hscli settings permission-sets seats` + `seat-assignments list|update` — seat catalog and user seat assignments
+- `hscli settings permission-sets templates list|get|create` — HubSpot/custom permission templates
+- `hscli settings flp list|object|property|access-state|blocklist|bypass-users` — internal field-level permission inventory
+- `hscli settings business-units list|capture|create-internal` — public list plus internal session-auth capture/create for full BU metadata
+- `hscli settings site-settings get [--full]|set --key <k> --value <v>` — portal CMS/email site settings (source-tracking / UTM mode, identity + click tracking) via internal session-auth; `set` is allowlisted to tracking keys + guarded
 - `hscli settings currencies list`
 - `hscli settings gdpr delete-contact <id>`
 - `hscli settings audit-logs list [--filters]`
@@ -142,9 +202,18 @@ Imports + sync + introspection:
 - `hscli account private-apps` — **list private apps installed (integration audit)**
 - `hscli account api-usage` — daily API usage totals
 
+## Internal Adapters
+
+- `hscli doctor internal-adapters` — list allowlisted browser-session setup/migration adapters. hscli intentionally does not expose a generic internal API passthrough.
+- Browser-session adapters only accept HubSpot app hosts for `--ui-domain` and filter cookie-file exports to that host before sending cookies.
+
 ## Communication preferences
 
-- `hscli communication-preferences status|definitions|update`
+- `hscli communication-preferences subscription-types` — legacy alias for definitions list
+- `hscli communication-preferences definitions list|create` — public read + guarded replay helper with `--business-unit-map`; public definition create may return HTTP 405 on real portals
+- `hscli communication-preferences definitions create-internal` — browser-session migration adapter for Email > Subscription Types creation; rejects non-Email channels
+- `hscli communication-preferences status|subscribe|unsubscribe`
+- `hscli communication-preferences v4 status-batch-read|status-update-batch|subscribe-batch|unsubscribe-batch|subscriptions-list|channels-list`; `subscriptions-list` reads `/communication-preferences/v4/definitions`
 
 ## Conversations
 
@@ -160,12 +229,15 @@ Imports + sync + introspection:
 
 ## Workflows
 
-- `hscli workflows flows list|get` + `actions list|get` + `sequences list|get`
+- `hscli workflows preflight --data <payload> [--id-map-dir <dir>] [--strict]` — check replay payloads for unresolved source IDs
+- `hscli workflows flows list|get|create|update|enable|disable`
+- `hscli workflows v3 list|get|create|delete|enroll|unenroll|enrollments`
+- `hscli workflows id-map <id>` — resolve v3 workflowId ↔ v4 flowId
 
 ## Files + Forms + Domains + Site-search + Timeline
 
 - `hscli files list|get|upload|delete`
-- `hscli forms list|get|create|update|translate-v2|submissions list`
+- `hscli forms list|get|create|update|translate-v2|submissions list` — legacy v2 translator supports property preflight, group splitting, and `--subscription-type-map`
 - `hscli domains list|get`
 - `hscli site-search list --type <type>`
 - `hscli timeline events list|create`
@@ -183,10 +255,17 @@ Imports + sync + introspection:
 
 ## MCP server
 
-- `hscli mcp` — start MCP server over stdio. ~125 tools across the full surface. Profile-isolated via `HSCLI_MCP_PROFILE`.
+- `hscli mcp [--surface minimal|crm|migration|full]` — start the profile-isolated stdio MCP server. Defaults to 29 essential tools; `full` exposes all 180 tools, including raw API access. Use `HSCLI_MCP_PROFILE` and `HSCLI_MCP_SURFACE` when the client cannot pass flags.
 
 Full tool catalog and Claude Desktop / Cursor config in [MCP.md](MCP.md).
 
+## Agent runbooks
+
+- `hscli agent run portal-baseline --output <dir> [--continue-on-error]` — first-run evidence bundle covering identity, capabilities, users, teams, deal pipelines, CRM data readiness, workflows, and request telemetry.
+- `hscli agent run data-cleanup|pipeline-risk|automation-risk --output <dir>` — focused recurring evidence runbooks.
+- `hscli agent plan <recipe>` — render exact commands without calling HubSpot.
+- `hscli agent contract create|inspect|verify|apply` — seal and verify approved write argument arrays; execution still requires `--execute` plus global `--force`.
+
 ## Seed (dev + testing)
 
 - `hscli seed --all [--dry-run]` — seed a test portal with the 48-asset baseline

package/docs/COMPARISON.md

@@ -2,11 +2,14 @@
 
 A factual inventory of what `hscli` exposes via its CLI and MCP server surface, and the HubSpot operations it covers. No comparisons, no marketing framing — just what's in the box.
 
-Last updated: 2026-04-22 (v0.8.0)
+Last updated: 2026-07-09 (v0.9.0)
 
 ## MCP tool surface
 
-`hscli mcp` exposes two tool families over stdio:
+`hscli mcp` exposes native, HubSpot-compatible, and hscli extension tool
+families over stdio. Registration is filtered through the `minimal`, `crm`,
+`migration`, or `full` surface; see the generated
+[MCP tool catalog](MCP_TOOL_CATALOG.md) for the authoritative 180-tool matrix.
 
 ### Native tool family (per-object)
 
@@ -118,8 +121,8 @@ Per-endpoint tier mapping: [docs/TIERS.md](TIERS.md).
 | Method | Supported | Notes |
 |---|:---:|---|
 | HubSpot Private App token | ✅ | Primary. Scriptable / machine-to-machine / CI. |
-| OAuth authorization code | Partial | Available for developer apps via `hscli auth login --oauth` |
-| OAuth refresh-token rotation | ✅ | Persisted in `~/.revfleet/auth.json` (or encrypted `auth.enc`) |
+| OAuth authorization code | ✅ | Available for developer apps via `hscli auth oauth-url` + `hscli auth oauth-exchange` |
+| OAuth refresh-token rotation | ✅ | Automatic before expiry; persisted in `~/.revfleet/auth.json` (or encrypted `auth.enc`) |
 | Legacy `hapikey` | ❌ | Retired by HubSpot (June 2023) |
 
 ## Safety model
@@ -128,7 +131,7 @@ Per-endpoint tier mapping: [docs/TIERS.md](TIERS.md).
 - **Policy-as-code.** `--policy-file <path>` (or `HSCLI_POLICY_FILE`) evaluates rules with method + path globs, time windows (tz-aware), change-ticket requirements, approval gates. See [docs/POLICY_EXAMPLE.json](POLICY_EXAMPLE.json).
 - **Change tickets.** `--change-ticket <id>` required by policy for guarded writes; value is written to telemetry.
 - **Path scope allowlisting.** All requests must resolve to an approved HubSpot API path root; traversal is rejected.
-- **Idempotency keys.** Every write includes an `Idempotency-Key` header for replay-safe retries.
+- **Retry correlation.** Writes reuse one correlation key across retries. Native idempotency is relied on only for endpoints that document it; action contracts plus read-only verification protect broader write flows.
 - **Token redaction.** Bearer tokens, `token=`, `api_key=`, and `Authorization:` values are scrubbed from every output and error payload.
 - **Rate-limit awareness.** Reads HubSpot's `X-HubSpot-RateLimit-*` headers; proactive throttling + daily quota reset in the portal's declared timezone.
 - **Capability probing.** Endpoints are fingerprinted by `portalId + scopes`; `--strict-capabilities` fails fast on unsupported endpoints before issuing a network call.

package/docs/COOKBOOK.md

@@ -11,7 +11,7 @@ All write operations are **dry-run by default**. Omit flags to see the safety er
 ### Login with a private app token
 
 ```bash
-hscli auth login --token "pat-eu1-a1b2c3d4-5678-9abc-def0-1234567890ab"
+printf '%s' "$HUBSPOT_PRIVATE_APP_TOKEN" | hscli auth login --token-stdin
 ```
 
 Hublet is auto-detected from the token prefix (e.g. `pat-eu1-...` routes to `api-eu1.hubapi.com`).
@@ -80,14 +80,21 @@ hscli auth oauth-url \
 ### Exchange an OAuth code for a token
 
 ```bash
+: "${HSCLI_OAUTH_CLIENT_SECRET:?set HSCLI_OAUTH_CLIENT_SECRET in your secret manager}"
 hscli auth oauth-exchange \
   --client-id "a1b2c3d4-5678-9abc-def0-1234567890ab" \
-  --client-secret "secret-value" \
   --code "auth-code-from-redirect" \
   --redirect-uri "https://app.example.com/oauth/callback" \
   --profile oauth-prod
+
+hscli --profile oauth-prod auth whoami
 ```
 
+The access token refreshes automatically before expiry. hscli stores the
+refresh token and the client-secret environment variable name, never the
+client secret itself. Use `hscli --profile oauth-prod auth refresh` to force a
+rotation while diagnosing an OAuth installation.
+
 ---
 
 ## 2. CRM Operations (Contacts, Companies, Deals, Tickets)
@@ -230,6 +237,13 @@ hscli crm custom-objects records create vehicles --force \
   --data '{"properties":{"vin":"1HGCM82633A004352","make":"Honda","model":"Accord"}}'
 ```
 
+### Batch-create custom object records
+
+```bash
+hscli crm custom-objects records batch-create vehicles --force \
+  --data '{"inputs":[{"properties":{"vin":"1HGCM82633A004352","make":"Honda","model":"Accord"}}]}'
+```
+
 ### Search custom object records
 
 ```bash
@@ -310,6 +324,22 @@ hscli crm migration export-metadata \
 
 This captures property groups with their real labels/displayOrder, property definitions, deal/ticket pipelines with per-stage detail, custom object schemas, owners, teams, business units, currencies, and standard association labels. Use it before building replay payloads so pipeline IDs/stage IDs and owner/team mappings are explicit.
 
+### Apply migration ID maps to local payloads
+
+```bash
+hscli crm migration id-map apply \
+  --data @contacts-upsert.json \
+  --field hubspot_owner_id=./id-maps/owners.json \
+  --field sales_owner=./id-maps/owners.json \
+  --field hs_owning_teams=./id-maps/teams.json \
+  --field hs_all_assigned_business_unit_ids=./id-maps/business-units.json \
+  --on-unmapped error \
+  --out contacts-upsert.remapped.json \
+  --report-out contacts-upsert.remap-report.json
+```
+
+`id-map apply` rewrites local JSON only; it never calls HubSpot. It supports `{ inputs: [...] }` batch payloads, arrays, and single records. Use `--on-unmapped error` for final migrations. Use `--on-unmapped drop` only after documenting an explicit policy, for example dropping out-of-scope teams while preserving all mapped NA/GLO teams.
+
 ### Export recoverable record activities
 
 ```bash
@@ -363,7 +393,7 @@ hscli --force crm properties batch-create contacts \
   --data @contacts-properties.json
 ```
 
-`batch-create` skips `hs_*` reserved names, HubSpot-defined/read-only properties, and empty enumerations by default. It also removes enum options with blank labels/values before sending. If you prefer to keep a property whose enum options cannot be recovered, demote it to a free-text property:
+`batch-create` skips HubSpot-reserved names (`hs_*`, `recurring_revenue_*`, and known reserved close-reason names), HubSpot-defined/read-only properties, and empty enumerations by default. It also removes enum options with blank labels/values before sending. Owner-reference enum properties keep `referencedObjectType` and automatically get `externalOptions: true`, which HubSpot requires for object-reference options. If you prefer to keep a property whose enum options cannot be recovered, demote it to a free-text property:
 
 ```bash
 hscli --dry-run crm properties batch-create contacts \
@@ -378,6 +408,8 @@ hscli --force crm properties batch-create 2-123456 \
   --data '{"inputs":[{"name":"migration_region","label":"Migration Region","type":"string","fieldType":"text","groupName":"customobjectinformation"}]}'
 ```
 
+Do not use `crm custom-objects schemas update` to add properties to an existing custom object schema. HubSpot accepts that PATCH but silently ignores the `properties` array, so hscli now fails early and points you to `crm properties batch-create <objectType>`.
+
 ### Update a property label
 
 ```bash
@@ -398,6 +430,16 @@ hscli crm associations create deals 18294750312 companies 9182736450 --dry-run
 hscli crm associations create deals 18294750312 companies 9182736450 --force
 ```
 
+### Batch-create typed associations
+
+```bash
+hscli crm associations batch-create contacts companies --dry-run \
+  --data '{"inputs":[{"from":{"id":"101"},"to":{"id":"202"},"types":[{"associationCategory":"HUBSPOT_DEFINED","associationTypeId":279}]}]}'
+
+hscli crm associations batch-create contacts companies --force \
+  --data @contact-company-associations.json
+```
+
 ### Remove an association
 
 ```bash
@@ -505,6 +547,9 @@ hscli forms create --source-format v2 --strict --dry-run \
 
 hscli forms translate-v2 --data '{"name":"Legacy Webinar Signup","submitText":"Register","formFieldGroups":[{"fields":[{"name":"email","label":"Email","fieldType":"email","required":true}]}]}'
 
+hscli forms create --source-format v2 --subscription-type-map ./id-maps/subscription-types.json --dry-run \
+  --data '{"name":"Legacy Webinar Signup","formFieldGroups":[{"fields":[{"name":"email","label":"Email","fieldType":"email"}]}]}'
+
 hscli forms update "f47ac10b-58cc-4372-a567-0e02b2c3d479" --force \
   --data '{"name":"Q2 Webinar Signup (Updated)"}'
 ```
@@ -540,6 +585,9 @@ hscli workflows flows get 39172845
 
 hscli workflows flows create --dry-run \
   --data '{"name":"New Lead Nurture Sequence","type":"PLATFORM_FLOW"}'
+
+hscli workflows preflight --id-map-dir ./id-maps --strict \
+  --data '{"name":"Workflow export","actions":[],"suppressionListIds":[]}'
 ```
 
 ### Service conversations and feedback
@@ -815,6 +863,76 @@ hscli /write
 hscli /guardrails
 ```
 
+### Render an agent-safe runbook
+
+Use `agent plan` when Codex, Claude Code, Cursor, or a scheduled worker needs a
+deterministic HubSpot operator sequence. The command prints a plan; it does not
+call HubSpot.
+
+```bash
+hscli agent list
+hscli --profile sandbox --policy-file ./policy.json --change-ticket CHG-123 \
+  agent plan automation-risk --json
+```
+
+Render a schedule artifact without installing it:
+
+```bash
+hscli --profile live agent schedule render pipeline-risk \
+  --target cron \
+  --cron "0 8 * * 1"
+```
+
+Available recipes:
+
+- `data-cleanup` — fill-rate, lifecycle, ownership, and audit review
+- `pipeline-risk` — pipeline/stage metadata and deal data-quality review
+- `automation-risk` — workflow inventory, workflow errors, email exposure, and audit review
+
+Every follow-up command still goes through the normal hscli model: public APIs
+first, `--force` for writes, optional `--policy-file`, optional
+`--change-ticket`, shared rate-limit handling, redacted trace/audit output.
+
+### Build a portal context pack
+
+Use `context build` before handing a portal to an agent or migration runbook. It
+performs a small read-only public-API probe and returns deterministic signals:
+portal metadata, owner/team counts, workflow count, CRM object totals/samples,
+profile classification, recommended runbooks, and questions to ask the portal
+owner before writing anything.
+
+```bash
+hscli --profile source-read --json context build --sample-limit 25
+```
+
+### Manage several portals safely
+
+Use `portals list` to see the local profile inventory without printing tokens or
+calling HubSpot. Use `portals plan` when a source/sandbox/live workflow needs
+the same read-only context or agent runbook across several portals.
+
+```bash
+hscli --json portals list
+hscli --json portals plan \
+  --profiles source-read,sandbox-read \
+  --runbook automation-risk \
+  --include-context \
+  --sample-limit 25
+```
+
+The output is plan-only: every rendered command includes an explicit
+`--profile`, so source and target portals stay separate.
+
+### Check API coverage parity
+
+Use `doctor parity` to see which HubSpot areas hscli covers through public APIs,
+which require explicit browser-session/internal adapters, which are hybrid, and
+which remain UI-only/manual evidence.
+
+```bash
+hscli --json doctor parity
+```
+
 ### Check hublet configuration consistency
 
 Verifies that hscli's detected hublet, token prefix, and `@hubspot/cli` config all agree:
@@ -850,6 +968,7 @@ All commands support `--format` and `--json` flags.
 
 ```bash
 hscli crm contacts list --format json
+hscli crm contacts list --format jsonl  # one compact envelope per result
 hscli crm contacts list --format csv
 hscli crm contacts list --format yaml
 hscli crm contacts list --format table   # default
@@ -873,8 +992,8 @@ hscli --telemetry-file ./telemetry.jsonl crm deals create --force \
 ### Manage staging and production side by side
 
 ```bash
-hscli auth login --token "pat-na1-staging-token" --profile staging
-hscli auth login --token "pat-eu1-production-token" --profile production
+printf '%s' "$HUBSPOT_STAGING_TOKEN" | hscli auth login --token-stdin --profile staging
+printf '%s' "$HUBSPOT_PRODUCTION_TOKEN" | hscli auth login --token-stdin --profile production
 
 # Read from staging
 hscli --profile staging crm contacts search --query "test"