@revfleet/hscli 0.8.7 → 0.8.10

package/docs/TIERS.md

@@ -0,0 +1,320 @@
+# HubSpot Plan Tier Requirements
+
+Every HubSpot public API endpoint is gated by a specific HubSpot plan tier. hscli
+exposes **100% of the 1180 public endpoints** as CLI commands, but whether a
+given command actually returns data depends on whether the portal has the
+required tier activated.
+
+This document maps hscli modules to the HubSpot product hubs and tiers that
+unlock them, based on [HubSpot's official pricing page](https://www.hubspot.com/pricing)
+and the [developer documentation](https://developers.hubspot.com/docs/api/overview)
+as of April 2026. Tiers are cumulative — e.g. "Marketing Hub Professional+" means
+Professional and Enterprise both unlock the endpoint.
+
+If an endpoint returns **403 Forbidden** with a message like *"This endpoint is
+not available on your account"* or *"This feature is part of HubSpot's [X] Hub"*,
+it's tier-locked. Upgrade the portal to the required tier or test on a portal
+that has it.
+
+## Quick tier map
+
+| Tier | Reachable endpoints (approx) |
+|---|---:|
+| **Free** (any account) | ~550 |
+| **Starter** (any hub, $20-50/mo) | +~80 |
+| **Professional** (any hub, $800-900/mo) | +~250 |
+| **Enterprise** (any hub, $3200+/mo) | +~100 |
+| **Commerce Hub** add-on | +~60 |
+| **Operations Hub Pro+** | +~40 |
+| **Developer Test Account** (free) | +~30 |
+| **Developer App + legacy hapikey** | +~40 (zombie — see below) |
+
+Cumulative ceiling with Marketing+Sales+Service+CMS+Ops+Commerce **all at
+Enterprise plus a dev app**: ~1140 / 1180 reachable (96.6%). Of the remaining
+~40, most are [zombie endpoints](#zombie-endpoints) HubSpot never migrated off
+legacy auth.
+
+---
+
+## Free (no paid plan required)
+
+These endpoints work on any HubSpot portal, including free personal accounts
+and Developer Test Accounts.
+
+### CRM objects (standard)
+- `hscli crm contacts ...` — `/crm/v3/objects/contacts` (all CRUD + search + batch)
+- `hscli crm companies ...` — `/crm/v3/objects/companies`
+- `hscli crm deals ...` — `/crm/v3/objects/deals`
+- `hscli crm tickets ...` — `/crm/v3/objects/tickets`
+- `hscli crm engagements` — notes, tasks, calls, meetings, emails
+- `hscli crm feedback-submissions`
+- `hscli crm communications` — SMS / WhatsApp logs
+
+### CRM infrastructure
+- `hscli crm properties ...` — `/crm/v3/properties/{objectType}` + groups
+- `hscli crm pipelines ...` — `/crm/v3/pipelines/{deals|tickets}`
+- `hscli crm owners ...` — `/crm/v3/owners`
+- `hscli crm associations ...` — `/crm/v3/associations` + `/crm/v4/associations`
+- `hscli crm schemas ...` (custom objects) — `/crm/v3/schemas`
+- `hscli crm imports ...` — `/crm/v3/imports`
+- `hscli crm exports ...` — `/crm/v3/exports`
+- `hscli lists ...` + `lists folders` — `/crm/v3/lists`
+
+### Settings (admin)
+- `hscli settings users,teams,currencies` — `/settings/v3/users`, `/settings/v3/users/teams`, `/settings/v3/currencies`
+- `hscli settings audit-logs` — `/settings/v3/audit-logs` (read-only)
+- `hscli account info,api-usage,private-apps,audit-logs` — `/account-info/v3`
+
+### Files + Forms
+- `hscli files ...` + `files folders` — `/files/v3/files`, `/files/v3/folders`
+- `hscli forms ...` — `/marketing/v3/forms` (basic CRUD)
+- `hscli submissions ...` — `/form-integrations/v1`, `/submissions/v3`
+
+### Webhooks
+- `hscli webhooks ...` — `/webhooks/v3/subscriptions` (portal-side)
+
+### OAuth + Auth
+- `hscli auth ...` — `/oauth/v1`, `/oauth/v3`
+
+### Communication Preferences
+- `hscli communication-preferences ...` — `/communication-preferences/v3` + v4 batch
+
+### Events
+- `hscli events ...` — `/events/v3` (behavioral events + event definitions)
+- `hscli timeline ...` — `/crm/v3/timeline/events` (emit events, not templates)
+
+### Conversations (read)
+- `hscli conversations threads,messages,actors` — `/conversations/v3/conversations`
+
+### Legacy CRM v1/v2
+All work on Free portals (backward-compatibility preserved by HubSpot):
+- `hscli contacts-v1` — `/contacts/v1`
+- `hscli companies-v2` — `/companies/v2`
+- `hscli deals-v1` — `/deals/v1`
+- `hscli owners-v2` — `/owners/v2`
+- `hscli engagements-v1` — `/engagements/v1`
+- `hscli properties-legacy` — `/properties/v1`, `/properties/v2`
+
+### Analytics (basic)
+- `hscli reporting` — `/analytics/v2/reports` (read, limited by tier)
+
+---
+
+## Marketing Hub (Starter+)
+
+Upgrade: $20/mo and up. Unlocks email marketing + form follow-ups.
+
+### Starter
+- `hscli marketing emails list,get` — read `/marketing/v3/emails` (limited send volume)
+- `hscli marketing subscriptions` — subscription types
+- `hscli marketing-emails-v1 list,get` — read legacy emails
+- `hscli ctas read` — CTA reporting (legacy)
+
+### Professional+ (adds)
+- `hscli marketing emails create,update,stats` — full editorial CRUD + analytics
+- `hscli marketing campaigns` — `/marketing/v3/campaigns`
+- `hscli marketing ads` — `/marketing/v3/ads/{accounts,campaigns}`
+- `hscli marketing social` — `/marketing/v3/social/{accounts,posts}`
+- `hscli marketing seo` — `/marketing/v3/seo` + `/cms/v3/seo/audit`
+- `hscli marketing events` + `attendance` + `participations` — `/marketing/v3/marketing-events`
+- `hscli marketing behavioral-events` — custom behavioral event definitions
+- `hscli marketing transactional single-email-send,smtp-tokens` — `/marketing/v3/transactional`
+- `hscli broadcast ...`, `broadcasts-root` — legacy social broadcast
+- `hscli email-events list,get,campaigns` — `/email/public/v1/events` (legacy per-recipient stream)
+- `hscli marketing-extras ads-events,legacy-email-ab-test`
+- `hscli marketing-emails-v1 create,update,clone,publish,statistics` — full legacy CRUD
+
+### Enterprise (adds)
+- `hscli settings business-units ...`, `hscli business-units` — `/settings/v3/business-units`, `/business-units/v3`
+- `marketing.campaigns.revenue.read` scope — revenue attribution endpoints
+
+---
+
+## Sales Hub (Starter+)
+
+Upgrade: $20/mo and up. Unlocks meeting scheduler + basic deal tools.
+
+### Starter
+- `hscli scheduler links-list,link-get` — `/scheduler/v3/meetings/meeting-links` (basic)
+- `hscli sales meetings ...` — `/crm/v3/objects/meetings` (create/link)
+
+### Professional+ (adds)
+- `hscli sales sequences list,get,enrollments,enroll,unenroll` — `/automation/v4/sequences`
+- `hscli scheduler book,reschedule,cancel` — advanced scheduler ops
+- `hscli sales calling` — `/crm/v3/extensions/calling/*` (calling SDK, partly zombie — see below)
+- `hscli crm goals` — `/crm/v3/objects/goal_targets` (basic custom goals in Starter, full forecasting Pro)
+- `hscli crm dated associations-2025-09 usage-report` — high-usage associations report
+
+### Enterprise (adds)
+- `crm.schemas.forecasts.read`, `crm.objects.forecasts.read` — forecast data
+- `crm.extensions_calling_transcripts.read,write` — call transcripts
+- `crm.dealsplits.read_write` — deal splits
+- `sales-email-read` — email templates API
+
+---
+
+## Service Hub (Starter+)
+
+Upgrade: $20/mo and up. Unlocks ticket automation + chatflows.
+
+### Starter
+- `hscli service chatflows ...` — `/conversations/v3/chatflows`
+- `hscli service feedback` — `/crm/v3/objects/feedback_submissions`
+- `hscli conversations inboxes,channels,channel-accounts` — `/conversations/v3/conversations/*`
+- `hscli conversations custom-channels` — app-dev custom channels
+
+### Professional+ (adds)
+- `hscli service knowledge-base ...` — `/cms/v3/knowledge_base` (articles, settings)
+- `hscli service pipelines` — `/crm/v3/pipelines/tickets` with > 1 pipeline
+- `hscli conversations messages send` — send messages into threads
+
+### Enterprise (adds)
+- Custom survey types + advanced routing (endpoints read-only on Pro)
+
+---
+
+## CMS Hub (Starter+)
+
+Upgrade: $23/mo (CMS Hub Starter). Unlocks HubSpot-hosted website.
+
+### Starter
+- `hscli cms site-pages,pages,landing-pages` — basic CRUD
+- `hscli cms url-redirects` — URL redirects
+- `hscli cms topics` — blog topics
+- `hscli cms audit-logs` — content audit log
+- `hscli cms blog-posts,blogs,blog-authors,blog-tags,blog-settings` — full blog CRUD (Starter onwards)
+- `hscli cms landing-page-folders` — landing page organization
+
+### Professional+ (adds)
+- `hscli cms hubdb ...` — `/cms/v3/hubdb/tables` (HubDB)
+- `hscli cms seo-audit` — SEO audit API
+- `hscli cms domains` — multi-domain listing
+- `hscli cms source-code ...` — theme/module source code API
+- `hscli cms content-v2 ...` — legacy Content API v2 (Pages, Layouts, Templates, Modules)
+- `hscli cms pages ab-test,revisions,multi-language` — A/B testing + multi-language
+- `hscli comments` — `/comments/v3/comments`
+
+### Enterprise (adds)
+- `cms.membership.access_groups.read,write` — CMS membership access groups
+- Multi-brand (via Business Units)
+
+---
+
+## Operations Hub (Starter+)
+
+Upgrade: $20/mo and up. Unlocks data sync + custom code.
+
+### Starter
+- `hscli crm imports,exports` — enhanced batch import/export
+- `hscli integration-sync` (integrations) — basic 2-way sync
+
+### Professional+ (adds)
+- `hscli automation workflows` — `/automation/v4/flows` (Workflows)
+- `hscli automation actions ...` — `/automation/v4/actions/{appId}` (custom code actions, requires OAuth dev app)
+- `hscli crm dated *` — dated 2025-09 API with batch
+- `hscli marketing behavioral-events` — custom event definitions (send on Ops Pro+)
+
+### Enterprise (adds)
+- Advanced data quality automation + team-based custom-code permissions
+
+---
+
+## Commerce Hub (Commerce add-on)
+
+Commerce Hub is a separate add-on (not a tier). Free Commerce gives limited
+Stripe checkout + quotes; paid unlocks the full suite.
+
+### Commerce Hub (Free with Commerce account)
+- `hscli crm quotes ...` — `/crm/v3/objects/quotes` (basic, requires `hs_language`)
+- `hscli crm products ...` — `/crm/v3/objects/products`
+- `hscli crm line-items ...` — `/crm/v3/objects/line_items`
+
+### Commerce Hub Professional+
+- `hscli crm invoices ...` — `/crm/v3/objects/invoices`
+- `hscli crm subscriptions ...` — `/crm/v3/objects/subscriptions`
+- `hscli crm payments ...` — `/crm/v3/objects/payments`
+- `hscli crm orders,carts,discounts,fees,taxes` — commerce objects
+- `hscli payments-subscriptions get,cancel,pause` — `/payments/subscriptions/v1`
+- `hscli tax list,get,create,update,delete` — `/tax/v3/taxes` (tax rates)
+
+---
+
+## Developer Platform (HubSpot Developer Account, free)
+
+These endpoints require a [HubSpot Developer Account](https://developers.hubspot.com/)
+(free, separate from a customer portal). You build an "App" in the developer
+account, install it via OAuth onto a test portal, and use the OAuth
+access_token. hscli supports this via `hscli auth oauth-url` +
+`hscli auth oauth-exchange --profile <devapp>`.
+
+### Accessible via OAuth Developer App
+- `hscli webhooks` — `/webhooks/v3/{appId}/subscriptions` (app developer's webhook subscriptions)
+- `hscli automation actions` — `/automation/v4/actions/{appId}` (custom workflow actions)
+- `hscli integrators timeline-event-templates` — `/integrators/timeline/v3/{appId}/event/templates`
+- `hscli integrations timeline create,batch-create,update,delete` — `/integrations/v1/application/{appId}/timeline`
+- `hscli crm cards ...` — `/crm/v3/extensions/cards/{appId}` (UI Extension cards)
+- `hscli feature-flags ...` — `/feature/flags/v3/{appId}/flags` (app feature flags)
+- `hscli appinstalls uninstall` — `/appinstalls/v3/external/install`
+
+### Developer Test Account
+- `hscli integrations me` — `/integrations/v1/me` (introspect installed app on test portal)
+
+---
+
+## Zombie endpoints
+
+HubSpot retired the legacy **Developer API Key (`hapikey=...` query param)** for
+new accounts in June 2023, but never migrated these endpoints to modern auth.
+They require a legacy hapikey that only old accounts still have:
+
+- `/crm/v3/extensions/calling/{appId}/settings/*` — Calling Extensions SDK (3 endpoints)
+- `/crm/v3/extensions/cards/dev/{appId}` — UI Extensions dev preview (2 endpoints)
+- `/crm/v3/extensions/videoconferencing/settings/{appId}` — Video Conf SDK (2 endpoints)
+- `/media-bridge/v1/{appId}/properties/*` — Media Bridge (24 endpoints)
+- `/media-bridge/v1/{appId}/schemas,settings` — Media Bridge infra (6 endpoints)
+- `/crm/v3/timeline/event-templates` (write) — app-level templates
+- A few others in `/integrators/timeline/v3/{appId}` write path
+
+**Total: ~40 zombie endpoints** (3.4% of the 1180 API surface).
+
+hscli exposes CLI commands for all of them — they're documented, typed, and
+available — but they'll return 401/403 with
+*"This API can't be called using an OAuth access token. A valid developer API
+key must be provided in the `hapikey=` query param"* on any portal that no
+longer has a legacy hapikey.
+
+If HubSpot eventually migrates these (GitHub tracker: [HubSpot dev community](https://community.hubspot.com/)),
+hscli will immediately work on them — the commands already exist.
+
+---
+
+## Reporting an endpoint not working
+
+If you hit an endpoint that should work on your tier but returns an unexpected
+error, open an issue at [Luigi08001/hscli/issues](https://github.com/revfleet/hscli/issues/new)
+with:
+
+1. Your portal's HubSpot plan (Starter / Pro / Enterprise, which Hubs)
+2. The exact `hscli ...` command you ran
+3. The error output (redact tokens)
+4. The HubSpot correlation ID from the response (helps HubSpot debug faster)
+
+For zombie endpoints, issues will be tagged `hubspot-platform` and tracked
+separately — they aren't fixable in hscli.
+
+---
+
+## Tier reference: HubSpot official pricing
+
+Accurate as of 2026-04-21. Prices in USD, monthly, billed annually:
+
+| Hub | Free | Starter | Professional | Enterprise |
+|---|---:|---:|---:|---:|
+| Marketing Hub | ✓ | $20 | $890 | $3,600 |
+| Sales Hub | ✓ | $20 | $90 (seat) | $150 (seat) |
+| Service Hub | ✓ | $20 | $90 (seat) | $150 (seat) |
+| CMS Hub | — | $23 | $400 | $1,500 |
+| Operations Hub | ✓ | $20 | $800 | $2,000 |
+| Commerce Hub | ✓ (limited) | — | $90 (seat) | — |
+
+Check [hubspot.com/pricing](https://www.hubspot.com/pricing) for the latest.

package/docs/TUTORIALS/audit-portal-writes.md

@@ -0,0 +1,150 @@
+# Tutorial: Audit every write to your HubSpot portal
+
+**Time:** ~10 min
+**Prerequisites:** `hscli` installed, at least one trace file recorded (see the [trace tutorial](trace-replay-repro.md)).
+
+You need to answer: "Which agent deleted 40 contacts on Friday?" or "Did any automation write to pipelines outside business hours last quarter?" `hscli audit` rolls up JSONL traces to give you operational auditability without a backend.
+
+## Step 0 — ensure traces exist
+
+If you haven't recorded yet, start one session:
+
+```bash
+hscli trace start
+# ... run some commands, let MCP tools run, etc ...
+hscli trace stop
+```
+
+Traces are saved as `~/.revfleet/trace-*.jsonl`. `hscli audit` auto-scans that directory by default — no configuration needed.
+
+## Step 1 — timeline
+
+```bash
+hscli audit timeline --since 24h
+```
+
+Chronological event list across every trace file. Useful for "what happened in the last hour / day / week".
+
+Flags:
+- `--since 15m | 24h | 7d` — time window (default: all time)
+- `--limit N` — max events to show (default: 100, shown most-recent-first)
+- `--writes-only` — filter to `POST/PUT/PATCH/DELETE`
+- `[file-or-dir]` — positional arg overrides the default `~/.revfleet/` scan
+
+## Step 2 — who did what
+
+For each profile, get a breakdown by method, status, and path root:
+
+```bash
+hscli audit who alice --since 7d
+```
+
+Output shape:
+```json
+{
+  "profile": "alice",
+  "totalEvents": 412,
+  "reads": 380,
+  "writes": 32,
+  "byMethod":    { "GET": 380, "POST": 20, "PATCH": 8, "DELETE": 4 },
+  "byStatus":    { "200": 390, "201": 18, "400": 2, "500": 2 },
+  "byPathRoot":  { "crm": 300, "marketing": 80, "cms": 32 },
+  "lastTen":     [ ... ]
+}
+```
+
+Great for answering "is profile X chatty or abusive?" or "did their error rate spike?".
+
+## Step 3 — who touched this path
+
+Inverse lookup: a given path pattern, who's been hitting it?
+
+```bash
+hscli audit what /crm/v3/objects/deals --since 7d
+```
+
+Substring match — `/deals` catches `/crm/v3/objects/deals`, `/crm/v3/objects/deals/123`, `/crm/v3/objects/deals/batch/read`, etc.
+
+Output buckets by profile, MCP tool (if the request came from `hscli mcp`), and method. Also lists `recentWrites` — the last 10 write operations against that path.
+
+This is the go-to command for incident response: **"An unexpected delete happened on contacts. Who?"**
+
+```bash
+hscli audit what /crm/v3/objects/contacts --since 24h
+# → byProfile: { "alice": 12, "claude-agent": 3 }
+# → byTool: { "crm-batch-delete": 2 }
+# → recentWrites: [ ... with profile, toolName, timestamp ... ]
+```
+
+## Step 4 — every write, ever
+
+The most security-relevant audit view:
+
+```bash
+hscli audit writes --since 24h
+```
+
+Returns *every* `POST/PUT/PATCH/DELETE` event in the window, counts failed vs successful, and includes a `limit`-capped list. Ideal for daily operator review.
+
+## Step 5 — MCP tool breakdown
+
+If you're running `hscli mcp` (exposing tools to Claude, Cursor, etc.), every request is tagged with `toolName`. Roll up per tool:
+
+```bash
+hscli audit by-tool --since 7d
+```
+
+Output:
+```json
+{
+  "totalMcpCalls": 1200,
+  "uniqueTools": 28,
+  "breakdown": [
+    { "tool": "crm-contacts-list", "calls": 450, "writes": 0,  "errors": 2, "errorRate": "0.4%", "avgMs": 180, "maxMs": 520 },
+    { "tool": "crm-contacts-create", "calls": 120, "writes": 120, "errors": 15, "errorRate": "12.5%", "avgMs": 320, "maxMs": 1800 },
+    ...
+  ]
+}
+```
+
+Sorted by call count descending. Quick pattern-matching:
+
+- Highest-call-count tool → "which tool is the chatty one"
+- Highest error rate → "which tool is the buggy one" or "which tool is hitting a capability boundary"
+- Highest maxMs → "which tool has tail-latency issues"
+
+## Step 6 — combine with `jq` for custom views
+
+Every audit command outputs JSON when you pass `--json` (or use `--format json` globally). Pipe into `jq` for ad-hoc queries:
+
+```bash
+# All 5xx writes in the last day, path + profile + ts
+hscli --json audit writes --since 24h \
+  | jq '.data.writes[] | select(.status >= 500) | { ts, profile, method, path, status }'
+
+# Top 5 profiles by write count
+hscli --json audit timeline --since 7d --writes-only --limit 10000 \
+  | jq '.data.events | group_by(.profile) | map({ profile: .[0].profile, count: length }) | sort_by(-.count) | .[:5]'
+```
+
+## Step 7 — feed into CI / Slack / PagerDuty
+
+Because everything is JSON-in / JSON-out, you can:
+
+- Run `hscli audit writes --since 1h` as a cron job; if any `failedWrites > 0`, POST to Slack.
+- Gate your deploy pipeline on `hscli audit by-tool --since 1h | jq '.data.breakdown[] | select(.errorRate | rtrimstr("%") | tonumber > 5)'` — fail if any tool's error rate spiked.
+- Archive traces to S3 daily for long-term compliance — the format is append-only JSONL, gzip-friendly.
+
+## What you get
+
+- Every trace file in `~/.revfleet/` becomes a queryable, structured audit log — no DB, no service to run.
+- Five pre-built aggregations (timeline, who, what, writes, by-tool) cover 90% of operator questions.
+- Works whether the traffic came from a human at a terminal, a cron job, or an MCP-connected agent.
+- Combined with [policy-as-code](secure-agent-writes.md), you get "what rule fired, against which request, from which tool, at what time" — in aggregate.
+
+## Tips
+
+- Trace files retain the HTTP request metadata but not the auth token — safe to share between operators.
+- If you store multiple portals in separate profiles (`hscli --profile prod ...`, `--profile staging ...`), `audit who` naturally segments by portal.
+- For a persistent audit trail, write traces to a shared path (`--out /mnt/shared-audit/trace-$(date +%F-%H%M).jsonl`) and scan with `hscli audit --file /mnt/shared-audit/`.
+- `audit who` and `audit what` return `0` for `totalEvents` when nothing matches — no error, just silence — so they're safe to run in pipelines.

package/docs/TUTORIALS/secure-agent-writes.md

@@ -0,0 +1,177 @@
+# Tutorial: Secure agent writes with policy-as-code
+
+**Time:** ~15 min
+**Prerequisites:** `hscli` installed, a HubSpot Private App token authenticated (`hscli auth login --token-stdin`).
+
+Agents that write to a production HubSpot portal need guardrails beyond `--force`. This tutorial walks through setting up a policy file so that an MCP-backed agent can read freely, write only to safe paths, require change tickets for risky writes, and be prevented from destructive deletes altogether.
+
+## The problem
+
+You've connected Claude (or any MCP client) to `hscli mcp` and want it to operate on your live HubSpot portal. Without policy:
+
+- The agent could `POST /crm/v3/objects/contacts/gdpr-delete` with a user-provided ID and permanently delete records.
+- Writes are authorised by *whether `--force` was passed*, not *what the write is*.
+- There's no auditable record of *why* a particular write was allowed.
+
+`hscli policy` fixes all three.
+
+## Step 1 — start from a template
+
+```bash
+hscli policy templates list
+```
+
+You should see five built-in templates. For an agent that needs to create and update records but must never delete, start with `no-deletes`:
+
+```bash
+hscli policy templates extract no-deletes --to ./policy.json
+```
+
+Open `policy.json` — you'll see a `version: 2` schema with `profiles.default.rules` that allow `GET/POST/PATCH/PUT` and deny all `DELETE`.
+
+## Step 2 — tighten for your environment
+
+Say you want:
+- Writes on CRM objects only — no CMS, no workflows.
+- `gdpr-delete` and batch archive operations always blocked.
+- Any write during business hours only, US/Eastern.
+- Any PATCH or PUT requires a change ticket ID.
+
+Edit `policy.json`:
+
+```json
+{
+  "version": 2,
+  "profiles": {
+    "default": {
+      "defaultAction": "deny",
+      "rules": [
+        {
+          "name": "allow-reads",
+          "match": { "method": "GET", "path": "**" },
+          "action": "allow"
+        },
+        {
+          "name": "block-gdpr-delete",
+          "match": { "method": "*", "path": "**/gdpr-delete**" },
+          "action": "deny"
+        },
+        {
+          "name": "block-batch-archive",
+          "match": { "method": "POST", "path": "**/batch/archive" },
+          "action": "deny"
+        },
+        {
+          "name": "allow-crm-writes-with-ticket",
+          "match": { "method": "POST", "path": "/crm/v3/objects/**" },
+          "action": "allow",
+          "requireChangeTicket": true,
+          "window": { "tz": "US/Eastern", "hours": "09-17", "days": "mon-fri" }
+        },
+        {
+          "name": "allow-crm-updates-with-ticket",
+          "match": { "method": "PATCH", "path": "/crm/v3/objects/**" },
+          "action": "allow",
+          "requireChangeTicket": true,
+          "window": { "tz": "US/Eastern", "hours": "09-17", "days": "mon-fri" }
+        }
+      ]
+    }
+  }
+}
+```
+
+Rules are evaluated **first-match-wins**, so order matters. `defaultAction: "deny"` means any method/path not explicitly matched is blocked — safe by default.
+
+## Step 3 — validate before shipping
+
+```bash
+hscli policy validate ./policy.json
+```
+
+This parses the file and flags structural issues (invalid actions, malformed `window.hours`, rules with no `match` block that would match everything). If `valid: true`, you're good.
+
+## Step 4 — dry-run rule matching
+
+Before enforcing, confirm the right rule fires for the requests you expect:
+
+```bash
+hscli --policy-file ./policy.json \
+  policy show-matching POST /crm/v3/objects/contacts
+# → matched: allow-crm-writes-with-ticket, effectiveAction: allow
+
+hscli --policy-file ./policy.json \
+  policy show-matching DELETE /crm/v3/objects/contacts/123
+# → matched: (none), effectiveAction: deny (from defaultAction)
+
+hscli --policy-file ./policy.json \
+  policy show-matching POST /crm/v3/objects/contacts/gdpr-delete
+# → matched: block-gdpr-delete, effectiveAction: deny
+```
+
+## Step 5 — enforce
+
+Either pass `--policy-file` on every invocation, or set it globally:
+
+```bash
+export HSCLI_POLICY_FILE=$PWD/policy.json
+```
+
+From now on, every `hscli` command (and every MCP tool call) runs through the policy. A denied write fails *before* the HTTP request is issued.
+
+Try a denied operation:
+
+```bash
+hscli --force crm contacts delete 123
+# → POLICY_DEFAULT_DENY: No policy rule matched DELETE /crm/v3/objects/contacts/123
+#   and profile default action is 'deny'.
+```
+
+Try an allowed write without a ticket:
+
+```bash
+hscli --force crm contacts create --data '{"properties":{"email":"jane@example.com"}}'
+# → POLICY_CHANGE_TICKET_REQUIRED: Policy rule 'allow-crm-writes-with-ticket'
+#   requires --change-ticket for POST /crm/v3/objects/contacts.
+```
+
+With a ticket:
+
+```bash
+hscli --force --change-ticket CHG-12345 \
+  crm contacts create --data '{"properties":{"email":"jane@example.com"}}'
+```
+
+## Step 6 — hook into MCP
+
+For Claude Desktop / Cursor / any MCP client, set the env var in the server config so the policy binds to the agent's stdio server:
+
+```json
+{
+  "mcpServers": {
+    "hscli": {
+      "command": "hscli",
+      "args": ["mcp"],
+      "env": {
+        "HSCLI_MCP_PROFILE": "default",
+        "HSCLI_POLICY_FILE": "/absolute/path/to/policy.json"
+      }
+    }
+  }
+}
+```
+
+Now every tool call the agent makes is filtered through the same rules.
+
+## What you get
+
+- Every write the agent attempts is auditable against a versioned policy file.
+- Destructive operations (`gdpr-delete`, batch archive) are *structurally* impossible.
+- Change tickets travel with the request and are written to telemetry.
+- Off-hours writes are rejected — no more 2am surprises.
+
+## Going further
+
+- Pair this with `hscli trace start` (see the [trace tutorial](trace-replay-repro.md)) to record every request + matched rule to a JSONL file.
+- Then use [`hscli audit`](audit-portal-writes.md) to answer questions like "all deletes blocked by policy last 7 days" or "which agent tried the most denied writes".
+- Policy error codes (`POLICY_RULE_DENY`, `POLICY_DEFAULT_DENY`, `POLICY_CHANGE_TICKET_REQUIRED`, `POLICY_APPROVAL_REQUIRED`, `POLICY_OUT_OF_WINDOW`) are machine-readable — parse them in CI to fail builds on denied operations.