@revfleet/hscli 0.9.8 → 0.11.0

package/docs/COMMAND_TREE.md

@@ -21,7 +21,7 @@ High-level map of every hscli command. For detailed args and examples per comman
 
 ## Auth
 
-- `hscli auth login [--token-stdin|--token <token>]` `[--hublet eu1|na1|na2|ap1]` — with no token flag in an interactive terminal, hscli prompts without echoing the token; use `--token-stdin` for CI
+- `hscli auth login [--auth-type private-app|service-key|personal-access-key] [--token-stdin|--token <token>] [--portal-id <id>] [--hublet eu1|na1|na2|ap1]` — credential type is explicit and never inferred from a `pat-*` prefix; with no token flag, hscli uses a hidden prompt; use `--token-stdin` for CI
 - `hscli auth logout [--profile <name>]`
 - `hscli auth profiles` — list profiles
 - `hscli auth profile-show [--profile <name>]`
@@ -31,8 +31,8 @@ High-level map of every hscli command. For detailed args and examples per comman
 - `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-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
+- `hscli auth refresh [--profile <name>]` — refresh an OAuth or Personal Access Key profile when it is expired or near expiry; normal requests perform the same check automatically
+- `hscli auth encrypt` | `hscli auth decrypt` — encrypt or decrypt the local token vault with `HSCLI_VAULT_PASSPHRASE`
 
 ## Doctor
 
@@ -59,9 +59,15 @@ High-level map of every hscli command. For detailed args and examples per comman
 ## Agent
 
 - `hscli baseline [--output <dir>] [--resume] [--fail-fast] [--submit] [--backend-url <origin>] [--api-key-env <name>]` — run the 12-signal read-only Portal Baseline and write `portal-baseline.md`, SHA-256 integrity-checked aggregate `revfleet-evidence.json`, and the local audit ledger; `--submit` explicitly sends only that aggregate contract to a configured HTTPS RevFleet origin after local artifacts are written
-- `hscli agent list` — list deterministic operator recipes (`portal-baseline`, `data-cleanup`, `pipeline-risk`, `automation-risk`)
+- `hscli agent list` — list deterministic operator recipes (`portal-baseline`, `access-baseline`, `reporting-joinability`, `data-cleanup`, `pipeline-risk`, `automation-risk`)
 - `hscli agent plan <recipe>` — render a public-API-first, audit-friendly runbook without executing HubSpot requests
-- `hscli agent run <recipe> [--output <dir>] [--resume] [--continue-on-error]` — execute a read-only runbook into a resumable local evidence directory
+- `hscli agent run <recipe> [--output <dir>] [--resume] [--continue-on-error]` — execute a read-only runbook into a resumable local evidence directory; resume requires existing run-ID-bound manifest/checkpoint and completed-step files plus ledger events, preserves the original run ID/start time, and records `run-resumed`; use a new directory without `--resume` for a fresh run (except one-shot `reporting-joinability`, which rejects resume/continue)
+- `hscli agent plan access-baseline` — render the no-network Integration and Access Readiness plan for the existing public capability probes.
+- `hscli agent run access-baseline --confirm-read-only [--output <dir>]` — after explicit human acknowledgement, run only `doctor capabilities --refresh` and write local aggregate-status `access-baseline.json` and `access-baseline.md`; unschedulable and not submit-capable.
+- `hscli agent access-baseline report <run-directory> [--output <file>]` — regenerate the local report with no HubSpot or RevFleet request.
+- `hscli agent plan reporting-joinability` — render the no-network, aggregate-only `sequence → meeting → deal` public-read plan; it does not inspect HubSpot native report/dashboard UI.
+- `hscli agent run reporting-joinability --confirm-read-only [--output <dir>]` — after explicit human acknowledgement, write only `reporting-joinability.json` and `reporting-joinability.md` from three public-read status probes; the sequence surface remains explicitly not probed because the documented list request requires an identity that this contract never derives, stores, or sends. No CRM rows, IDs, response bodies, scheduling, MCP, submission, or remediation.
+- `hscli agent reporting-joinability report <run-directory> [--output <file>]` — regenerate the local reporting joinability report without calling HubSpot; native report inventory and attribution correctness remain unavailable.
 - `hscli agent evidence export <run-directory> [--output <file>]` — create SHA-256 integrity-checked aggregate-only `revfleet.hscli-evidence/v1` JSON; raw steps and identities remain local
 - `hscli agent evidence report <run-directory> [--output <file>]` — render the deterministic Markdown report from aggregate evidence only
 - `hscli agent evidence submit <run-directory> [--backend-url <origin>] [--api-key-env <name>]` — submit integrity-checked aggregate evidence to an explicit RevFleet origin (`REVFLEET_BACKEND_URL` is the fallback); does not create a full scan score
@@ -264,7 +270,11 @@ Per-email open+click tracking via the internal edit-publish buffer — flips `di
 
 ## MCP server
 
-- `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.
+- `hscli --profile <name> mcp [serve] [--surface minimal|crm|migration|full] [--allow-writes] [--allow-cross-profile]` — start the stdio MCP server, locked to the startup profile and unable to execute live writes by default. The default exposes 31 read/diagnostic tools; `full` exposes 182 tools and includes raw API access.
+- `hscli --json mcp manifest [--surface ...]` — print the packaged MCP version, protocol/transport support, and tool safety coverage without accessing HubSpot.
+- `hscli --profile <name> --json mcp doctor [--surface ...] [--all]` — inspect local read/dry-run/write readiness; `--all` adds explicit client-managed checks for both official HubSpot MCP products.
+- `hscli --profile <name> --json mcp setup --client <client> [--surface ...]` — print a secret-free, plan-only side-by-side setup for HubSpot Remote MCP, Developer MCP, and hscli.
+- `hscli --json mcp matrix` — compare transport, authentication boundary, intended use, and compatibility status.
 
 Full tool catalog and Claude Desktop / Cursor config in [MCP.md](MCP.md).
 
@@ -272,6 +282,10 @@ Full tool catalog and Claude Desktop / Cursor config in [MCP.md](MCP.md).
 
 - `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 run access-baseline --confirm-read-only [--output <dir>]` — one explicit, local-only availability matrix from the existing public capability probes; it cannot be scheduled or submitted.
+- `hscli agent access-baseline report <run-directory> [--output <file>]` — regenerate the local access matrix without calling HubSpot or RevFleet.
+- `hscli agent run reporting-joinability --confirm-read-only [--output <dir>]` — one explicit, local-only aggregate evidence contract for the operational `sequence → meeting → deal` chain; it cannot be scheduled, submitted, or exposed through MCP.
+- `hscli agent reporting-joinability report <run-directory> [--output <file>]` — regenerate the local joinability report without calling HubSpot; it never audits native report/dashboard UI.
 - `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`.
 

package/docs/COMPARISON.md

@@ -2,14 +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-07-09 (v0.9.0)
+Last updated: 2026-07-31 (unreleased)
 
 ## MCP tool surface
 
 `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.
+[MCP tool catalog](MCP_TOOL_CATALOG.md) for the authoritative 182-tool matrix.
 
 ### Native tool family (per-object)
 
@@ -28,9 +28,13 @@ families over stdio. Registration is filtered through the `minimal`, `crm`,
 | reporting | `reporting_dashboards_{list,get}` |
 | raw | `hub_api_request` |
 
-### HubSpot Remote MCP compatibility family
+### HubSpot Remote MCP name-compatible subset
 
-`hscli mcp` also registers the 11 tool names used by HubSpot's hosted Remote MCP server at `mcp.hubspot.com`. An agent built against the HubSpot Remote MCP can point at `hscli mcp` without modification:
+`hscli mcp` registers an 11-tool snapshot of familiar names from HubSpot's
+hosted Remote MCP. This is a name-compatible subset, not endpoint-level
+interchangeability: hscli uses local stdio + local profiles, while Remote MCP
+uses Streamable HTTP + client-managed OAuth and the authenticated HubSpot
+user's permissions. Compare the current products with `hscli --json mcp matrix`.
 
 | Tool | Scope | Notes |
 |---|---|---|
@@ -46,9 +50,11 @@ families over stdio. Registration is filtered through the `minimal`, `crm`,
 | `get_campaign_asset_types` | Read | Supported asset types |
 | `get_campaign_asset_metrics` | Read | Per-asset metrics |
 
-### Extension tool family (hscli-only)
+### Supplemental operator tool family
 
-Tools for surfaces not exposed by HubSpot's hosted Remote MCP:
+Additional hscli operator tools. Some product areas can overlap with the
+evolving official service, but hscli keeps deterministic bulk, migration,
+backup, policy, and audit semantics:
 
 | Area | Tools |
 |---|---|
@@ -121,6 +127,8 @@ Per-endpoint tier mapping: [docs/TIERS.md](TIERS.md).
 | Method | Supported | Notes |
 |---|:---:|---|
 | HubSpot Private App token | ✅ | Primary. Scriptable / machine-to-machine / CI. |
+| HubSpot Service Key | ✅ | Account-level REST credential for system-to-system automation and MCP; availability follows HubSpot's current Service Key rollout. |
+| HubSpot Personal Access Key | ✅ | Local user-bound CLI credential; exchanged and refreshed five minutes before expiry. |
 | 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) |

package/docs/COOKBOOK.md

@@ -17,6 +17,43 @@ hscli auth login
 `auth login` uses a hidden terminal prompt, so the token never enters shell
 history. Use stdin only for CI or non-interactive shells.
 
+The default auth type is `private-app`. Keep it explicit in runbooks:
+
+```bash
+hscli auth login --auth-type private-app --profile production
+```
+
+### Login with an account Service Key
+
+Service Keys are stable, scoped account credentials for REST API operations.
+They are not Personal Access Keys and hscli does not infer the type from their
+prefix.
+
+```bash
+hscli auth login --auth-type service-key --profile automation
+hscli --profile automation auth whoami
+```
+
+`whoami` reports `restOnly: true` for Service Key profiles. Webhooks, UI
+extensions, and other app-platform features need their own supported auth path.
+
+### Login with a Personal Access Key
+
+Personal Access Keys are tied to one HubSpot user and account. hscli exchanges
+the key for a short-lived access token and refreshes it automatically five
+minutes before expiry.
+
+```bash
+hscli auth login \
+  --auth-type personal-access-key \
+  --portal-id 123456 \
+  --profile local-dev
+```
+
+The expected portal ID is checked before the profile is saved and again during
+refresh. Use `hscli auth encrypt` because the PAK must remain available locally
+to mint replacement access tokens.
+
 Hublet is auto-detected from the token prefix (e.g. `pat-eu1-...` routes to `api-eu1.hubapi.com`).
 If the token does not expose enough metadata, force routing explicitly:
 
@@ -30,6 +67,13 @@ hscli --hublet eu1 --profile live account info
 
 ```bash
 echo "$HUBSPOT_TOKEN" | hscli auth login --token-stdin --profile production
+
+printf '%s' "$HUBSPOT_SERVICE_KEY" | hscli auth login \
+  --auth-type service-key --token-stdin --profile automation
+
+printf '%s' "$HUBSPOT_PERSONAL_ACCESS_KEY" | hscli auth login \
+  --auth-type personal-access-key --portal-id 123456 \
+  --token-stdin --profile local-dev
 ```
 
 ### Switch between profiles
@@ -95,8 +139,8 @@ 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.
+client secret itself. Use `hscli --profile oauth-prod auth refresh` to run the
+same expiry check explicitly while diagnosing an OAuth installation.
 
 ---
 

package/docs/INTERNAL-ENDPOINTS-DISCOVERY.md

@@ -811,3 +811,62 @@ Asset	Body export	Notes
 Sequence	✅ Full	GET /api/sequences/v3/sequences/{id} — includes steps, settings, email templates by ID, send window, unenrollment rules, dependencies
 Playbook	✅ Full	listPlaybooks RPC returns body + htmlBody inline. Plus questions via separate RPC.
 Caveat: Sequence steps reference templates by ID; full fidelity requires also fetching template bodies. Same for playbook questions.
+
+## Iteration 16 — promoted operator commands and guarded workflow replacement
+
+The following contracts were promoted from discovery notes into explicit hscli
+commands. They are intentionally not exposed as arbitrary internal HTTP calls:
+
+| Command | Endpoint | Evidence semantics |
+|---|---|---|
+| `workflows inspect <flowId>` | `GET /api/automationplatform/v1/flows/{flowId}?portalId={portalId}` | Current full editor definition; internal browser-session source. |
+| `workflows revisions <flowId>` | `GET /api/automationplatform/v1/hybrid/revisions/{flowId}?portalId={portalId}&limit=100&after=...` | Revision definitions and authors; paginated completeness is reported. |
+| `workflows errors <flowId>` | `GET /api/automationapps/v1/insights/canvas/errors/{flowId}` | Rolling seven-day canvas evidence; explicitly marked incomplete outside that window. |
+| `lists inspect-filters <listId>` | `GET /api/inbounddb-lists/v1/lists/{listId}` | Internal filter tree. |
+| `crm record-layouts ...` | `/api/crm-record-cards/v4/...` | Record-page layouts and card property configuration. |
+
+`POST /api/automationplatform/v1/hybrid/batch` is a full workflow replacement,
+not a normal CRUD update. It is available only through the CLI command
+`workflows update-internal` and is forbidden in generic `internal capture` and
+MCP. The command is plan-only by default and execution requires a disabled
+single flow, exact ID match, fresh live version, HubSpot validation, same-session
+portal proof, a private pre-write snapshot, `version = live + 1`, a sealed
+action contract, change ticket, global `--force`, experimental opt-in, and the
+exact acknowledgement `REPLACE WORKFLOW <flowId>`. The non-idempotent save is
+sent once with retries disabled, then reconciled against both current state and
+revision history. Any ambiguous result fails closed and instructs the operator
+not to retry automatically.
+
+`PUT /api/crm-record-cards/v4/crm-cards/{cardId}` is also a full replacement,
+even when the intended edit is only one property list. The promoted command
+`crm record-layouts update-card` therefore accepts only an ordered CSV of
+`propertyNames`, merges it into the freshly-read full card, and uses the same
+plan-first, portal-proof, private snapshot, sealed contract, ticket, explicit
+acknowledgement, no-retry, and post-write verification model. It is CLI-only
+and absent from the generic internal capture catalogue and MCP.
+
+The public seat-history companion is:
+
+```text
+GET /crm/v3/objects/0-115/{userId}
+  ?properties=hs_assigned_seats
+  &propertiesWithHistory=hs_assigned_seats
+  &archived=false
+```
+
+It is exposed as `settings users seat-history <userId>` and does not use
+browser credentials.
+
+Two discoveries remain documentation-only because the supplied evidence does
+not include a complete executable RPC contract:
+
+- `CrmUsagesUiService/getPageOfFilteredUsagesForDependencyNodeAndAssetDisplayType`
+  needs the exact fully-qualified Chirp service name and a redacted request
+  fixture before it can be allowlisted.
+- `UserPermissionAuditLogsRpc/getPagedLogs` needs the exact fully-qualified
+  Chirp service name. Its known body uses `{ userId, offset: {}, limit }`, and
+  the pagination cursor is an object rather than an integer.
+
+No live write was used to validate this iteration. The workflow replacement is
+covered by mocked contract and safety tests; its internal HubSpot contract must
+still be treated as unstable.

package/docs/INTERNAL-ENDPOINTS.md

@@ -69,6 +69,19 @@ Workflows
 Method	Path	Status	Notes
 GET	/api/automation/v4/flows	✅	List flows. Hard cap limit=100; paginate via after.
 GET	/api/automation/v4/flows/{id}	❌	401 from in-tab JS.
+GET	/api/automationplatform/v1/flows/{id}?portalId={portalId}	✅	Current editor definition in hybrid format; `hscli workflows inspect`.
+GET	/api/automationplatform/v1/hybrid/{id}	✅	Full hybrid action graph.
+GET	/api/automationplatform/v1/hybrid/revisions/{id}?portalId={portalId}&limit=100&after={cursor}	✅	Full revision history with definitions and authors; `after` is optional.
+POST	/api/automationplatform/v1/validation?portalId={portalId}	✅	Read-like validation preview before save.
+GET	/api/automationapps/v1/insights/canvas/errors/{id}	✅	Rolling canvas execution/enrollment errors.
+POST	/api/automationplatform/v1/hybrid/batch	⚠️	Undocumented full-flow replacement. CLI-only via `workflows update-internal`; disabled flows only, plan-first, snapshot, no retry, post-save verification, and high-risk acknowledgement. Forbidden in generic internal capture and MCP.
+PUT	/api/crm-record-cards/v4/crm-cards/{cardId}	⚠️	Undocumented full-card replacement. CLI-only via `crm record-layouts update-card`; propertyNames-only delta, plan-first, snapshot, no retry, exact post-save order verification. Forbidden in generic internal capture and MCP.
+
+Public seat-history companion: `GET /crm/v3/objects/0-115/{userId}` with
+`properties=hs_assigned_seats` and
+`propertiesWithHistory=hs_assigned_seats`, exposed as
+`hscli settings users seat-history <userId>`. This does not require a browser
+session.
 POST	/api/automation/v4/flows	✅	Create flow.
 PUT/PATCH	/api/automation/v4/flows/{id}	✅	Update.
 DELETE	/api/automation/v4/flows/{id}	✅	Soft delete; recoverable from Deleted view.

package/docs/INTERNAL_ENDPOINTS.md

@@ -58,7 +58,7 @@ read-like surfaces into JSON backup assets:
 | `permission-access` | App users, teams, permission sets, assignment maps, roles, seats, templates, FLP, and access-audit RPCs |
 | `datasets-reporting` | Data Studio datasets, reportable sources, joins, formulas, previews, async resolve calls, and async result polling |
 | `reports-dashboards` | Report definitions, favorites, report audit/history, record-view metadata, report permissions, report template discovery, dashboard layouts, widgets, dashboard grants, and report-list views |
-| `workflows-hybrid` | Workflow inventories, hybrid action graphs, validation, output fields, action catalog, CRM object context, canvas errors, access checks, filter-description previews, and card-position RPCs |
+| `workflows-hybrid` | Workflow inventories, current hybrid action graphs, full revision history, validation previews, output fields, action catalog, CRM object context, canvas errors, access checks, filter-description previews, and card-position RPCs |
 | `properties-metadata` | Internal property metadata, legacy v1/v2 fallbacks, property groups, grouped-property listings, named property reads, recycled properties, quotas, fill rates, validation, dynamic options, and conditional options |
 | `crm-search` | Read-only CRM search, CRM GraphQL, object preview, and single-object UI payload helpers used by report builders, help desk, quotes, and object indexes |
 | `object-metadata` | Schema metadata, framework-builder metadata, portal-scoped object types, event object types, and object-type batch reads |
@@ -107,6 +107,24 @@ for research and migration design, but they are not included in
 be implemented as explicit product commands with policy checks, dry-run,
 `--force`, and audit trails.
 
+The sole promoted workflow write adapter is
+`hscli workflows update-internal <flowId>`. It targets the undocumented
+`POST /api/automationplatform/v1/hybrid/batch` editor endpoint and is never
+part of `internal capture` or MCP. It is plan-only by default and adds stronger
+gates than normal writes: one disabled flow, matching requested/input/live ID,
+same-session portal proof, live-version optimistic locking, validation,
+owner-only snapshot, one request with retries disabled, and post-save proof
+from both current state and revision history. Operators must also provide a
+change ticket, sealed action contract, explicit experimental opt-in, `--force`,
+and an ID-bound acknowledgement.
+
+Record-card writes are similarly promoted only through
+`crm record-layouts update-card`. The command reads the live card, replaces
+only `configuration.propertyNames`, snapshots the full before/after payload,
+uses one non-retried `PUT /api/crm-record-cards/v4/crm-cards/{cardId}`, and
+verifies the exact ordered property list. It is not available to generic
+capture or MCP.
+
 ## Browser Session Auth Pattern
 
 Most internal endpoints require the HubSpot browser cookies plus the modern
@@ -189,15 +207,15 @@ commands. hscli exposes only the allowlisted reads below through
 | Reports | `/api/dashboard/v2/reports/*`, `/reporting-migration/v2/reports/migrate` |
 | Reporting data | `/api/reporting/v3/dataset/resolve/async` |
 | Datasets | `/sql-reporting/v1/datasets/*`, `/sql-reporting/v1/extended-reportable-options/*` |
-| Workflows | `/api/automationplatform/v1/hybrid/{flowId}`, validation, output fields, action catalog |
+| Workflows | `/api/automationplatform/v1/flows/{flowId}`, `/api/automationplatform/v1/hybrid/{flowId}`, `/api/automationplatform/v1/hybrid/revisions/{flowId}`, validation, canvas errors, output fields, action catalog; guarded CLI-only full replacement via `/api/automationplatform/v1/hybrid/batch` |
 | Properties | `/api/properties/v4/{typeId}`, `/api/properties/v4/groups/{typeId}`, v2 fallbacks |
-| Lists / segments | Legacy contacts lists, ILS segments, list search, and UI list views |
+| Lists / segments | Legacy contacts lists, ILS segments, list search, UI list views, and `/api/inbounddb-lists/v1/lists/{listId}` complete filter trees |
 | Sales content | `/api/templates/v1`, `/api/sales-content/v1`, `/api/sales-content-libraries/v2` |
 | Sequences | `/api/salescontentsearch/v2/search`, `/api/sequences/v3/sequences/{id}` |
 | Playbooks | Chirp RPC `com.hubspot.playbooks.rpc.PlaybooksRpc` |
 | Audit logs | `/api/audit-log/v1`, `/api/audit-log/v3`, `/api/security-audit-logs/v1` |
 | Object metadata | `/api/data-model/v3`, `/api/framework-builder/v1`, `/api/schemas-metadata/v1` |
-| CRM views | `/api/sales/v4/views/{typeId}`, legacy v2/v3 views, visualization settings |
+| Saved contacts views | Captured contacts surface: `POST /api/sales/v4/views/by-category/search/0-1`, `POST /api/sales/v4/views/with-visualization-settings`, and `DELETE /api/sales/v4/views/{viewId}`. Exposed as `hscli sales views list|create|delete`; create/delete require browser-session portal proof, explicit acknowledgement, `--execute`, global `--force`, and a change ticket. `PUT /api/sales/v4/views/{viewId}` is unverified and deliberately not exposed. |
 | Owners | `/api/owners/v2/owners`, `/owners-aether-search/v1/owners-search` |
 | Branding | `/api/branding/v1/*`, `/api/business-units/v1/*`, `/api/multi-brand/v1/*` |
 | Forms and marketing | `/forms/v2/forms`, `/marketing/v3/forms`, `/api/cosemail/v1/*` |
@@ -206,7 +224,7 @@ commands. hscli exposes only the allowlisted reads below through
 | Social and ads | `/api/broadcast/v2/*` plus read-only `com.hubspot.ads.rpc.*` Chirp RPCs |
 | CRM search and previews | `/api/crm-search/*`, `/api/graphql/crm`, and `/inbounddb-objects/v1/*` |
 | Conditional properties | `/api/conditional-properties/v2/rules/*` plus unified RPC reads |
-| Record cards | `/api/crm-record-cards/v4/container-views/*` |
+| Record cards | `/api/crm-record-cards/v4/container-views/search`, `/get-view/CRM_RECORD_PAGE/{layoutId}`, `/api/crm-record-cards/v4/crm-cards/all`, and `/crm-cards/{cardId}` |
 | Conversations / help desk | Custom views and Chirp RPC help desk services |
 | Chatflows | Chirp RPC `com.hubspot.chatflows.rpc.*` |
 | Payments / quotes / forecast | Feature-gated internal setup and eligibility endpoints |

package/docs/MCP.md

@@ -18,6 +18,11 @@ hscli mcp                                      # minimal: essential CRM reads
 hscli mcp --surface crm                        # curated CRM reads + writes
 hscli mcp --surface migration                  # cross-product migration tools
 hscli mcp --surface full                       # all tools, including raw API
+hscli --json mcp manifest --surface minimal    # protocol + transport + tool metadata
+hscli --profile prod --json mcp doctor         # local profile and safety diagnostics
+hscli --profile prod --json mcp doctor --all   # external checks, clearly marked not live-run
+hscli --profile prod --json mcp setup --client codex  # plan only; no credential/config write
+hscli --json mcp matrix                        # intended use + trust boundaries
 ```
 
 The default `minimal` surface keeps agent context and write exposure small.
@@ -26,10 +31,12 @@ pass command arguments.
 
 ## Profile isolation and safety defaults
 
-- **Profile isolation**: set `HSCLI_MCP_PROFILE=<profile>` to hard-lock the MCP server to one auth profile.
+- **Profile isolation**: `hscli --profile <profile> mcp serve` hard-locks the server to that startup profile by default.
   - If a tool call requests a different profile, the server rejects it.
+  - Cross-profile selection is available only with the operator-controlled `--allow-cross-profile` startup flag.
 - **Write tools are dry-run by default**:
-  - `force: true` is required to execute actual writes.
+  - `force: true` on the tool call is necessary but not sufficient.
+  - The operator must also start the server with `--allow-writes` (or explicitly set `HSCLI_MCP_ALLOW_WRITES=1`).
   - Without `force`, write tools return a dry-run payload (`{ dryRun: true, method, path, body }`).
 - **Lifecycle coverage for CRM objects**:
   - standard object tools now include delete, merge, batch read/upsert/archive.
@@ -39,6 +46,20 @@ pass command arguments.
   - Pipeline object types: `deals`, `tickets`
 - **Secrets redaction**:
   - Token-like fields and bearer strings are redacted in MCP tool outputs and errors.
+- **Conservative tool annotations**:
+  - Every registered tool publishes `readOnlyHint`, `destructiveHint`,
+    `idempotentHint`, and `openWorldHint`.
+  - Unknown or mixed-operation tools default to write/destructive metadata.
+  - `manage_crm_objects` and raw `hub_api_request` are destructive because
+    their runtime arguments can select delete operations.
+- **Stable diagnostic schemas**:
+  - `hscli_mcp_manifest` and `hscli_mcp_doctor` publish MCP `outputSchema`
+    declarations and return validated structured content.
+  - The 11-tool HubSpot name-compatible subset also publishes object-level
+    output schemas so clients can rely on structured content without assuming
+    HubSpot Remote MCP authorization or transport equivalence.
+  - Raw HubSpot tools deliberately do not claim stable output schemas because
+    their response shapes vary by endpoint, product tier, and portal state.
 
 ## Claude Desktop setup
 
@@ -84,14 +105,29 @@ If your client accepts env vars, set:
 - `HSCLI_HOME` to the auth profile directory containing `auth.json`
 - `HSCLI_MCP_PROFILE` to force strict profile isolation
 
+## Three-server setup
+
+The products are complementary and should be configured side by side:
+
+| Server | Transport / auth | Best use |
+|---|---|---|
+| HubSpot Remote MCP | Streamable HTTP, OAuth 2.1 + PKCE, HubSpot user permissions | User-authorized CRM, activities, content, and marketing operations |
+| HubSpot Developer MCP | stdio via HubSpot CLI 8.2+ | HubSpot app and CMS development (`hs mcp setup`) |
+| hscli MCP | local stdio, hscli profile | Bulk operations, migrations, backups, internal adapters, policy, tickets, audit evidence |
+
+Run `hscli --profile <name> --json mcp setup --client <client>` for a
+secret-free plan. The command does not perform OAuth, write client config, or
+store credentials. Run `mcp doctor --all` afterward; external checks remain
+`external-check-required` until the owning client completes them.
+
 ## Tool surfaces
 
 | Surface | Tools | Intended use | Raw API |
 |---|---:|---|---|
-| `minimal` | 29 | Agent discovery and essential CRM reads | No |
-| `crm` | 136 | CRM objects, schemas, properties, associations, imports | No |
-| `migration` | 179 | Curated cross-product backup and migration work | No |
-| `full` | 180 | Explicit operator access to every registered tool | Yes |
+| `minimal` | 31 | Agent diagnostics, discovery, and essential CRM reads | No |
+| `crm` | 138 | CRM objects, schemas, properties, associations, imports | No |
+| `migration` | 181 | Curated cross-product backup and migration work | No |
+| `full` | 182 | Explicit operator access to every registered tool | Yes |
 
 The exact catalog is generated from runtime registration metadata, including
 domain, inferred risk, surfaces, and description:
@@ -107,5 +143,11 @@ npm run docs:mcp:check
 ## Notes
 
 - MCP transport is stdio only in this implementation.
+- The packaged SDK currently negotiates MCP `2025-11-25`. Streamable HTTP,
+  MCP Tasks, MCP Apps, and explicit `2026-07-28` opt-in are not enabled.
+  They require a separate SDK-v2 migration and transport compatibility gate.
 - Existing auth + HTTP core logic is reused (`getToken`, `HubSpotClient`, `maybeWrite`, redaction).
 - `hub_api_request` is exposed only by `--surface full`.
+- MCP writes use the startup write gate, dry-run, force, policy, portal-pin, and change-ticket gates,
+  but are not yet bound to sealed `hscli agent contract` prepare/apply/verify
+  workflows. `mcp doctor` reports this limitation explicitly.