@revfleet/hscli 0.8.7 → 0.8.10

package/docs/PUBLISHING.md

@@ -0,0 +1,154 @@
+# Publishing runbook
+
+How to cut a new release of `@revfleet/hscli` on npm. Written for the maintainer (currently Luigi / `lvermeulen94@gmail.com`) and for any assistant helping the release.
+
+## Prerequisites
+
+- Write access to `npmjs.com/package/@revfleet/hscli` (check `npm owner ls @revfleet/hscli`).
+- Write access to `github.com/revfleet/hscli` (push to `main`, create tags).
+- Working `gh` CLI, logged in (`gh auth status` shows the `revfleet` org).
+- A terminal session where you can respond to a **passkey prompt** from your password manager. The npm account is protected by a passkey (WebAuthn / platform authenticator), not a TOTP code. `npm publish` will fail interactively with `EOTP` if the passkey prompt can't reach you.
+
+## Release flow
+
+### 1. Land all changes on a feature branch
+
+```bash
+cd /Users/louisv/Pro-Desktop/Projets/hscli-main
+git checkout -b <branch-name>
+# ... commits ...
+git push -u origin <branch-name>
+```
+
+### 2. Verify CI locally before opening a PR
+
+```bash
+npm run typecheck
+npm run lint
+npm test
+```
+
+All three should be clean. CI runs the same checks across Node 20 and 22.
+
+### 3. Bump the version
+
+Edit `package.json`:
+
+```json
+{
+  "version": "X.Y.Z"
+}
+```
+
+Patch-bump for docs-only / internal fixes, minor for new surface (tools, commands), major for breaking changes.
+
+### 4. Update `CHANGELOG.md`
+
+Add a new section at the top:
+
+```markdown
+## X.Y.Z - YYYY-MM-DD
+
+<one-paragraph summary>
+
+### New
+
+- ...
+
+### Fixes
+
+- ...
+
+### Tests / Docs
+
+- ...
+```
+
+Follow the shape of recent entries — tie every change to a file path when useful.
+
+### 5. Commit, push, open PR
+
+```bash
+git add package.json CHANGELOG.md src/ tests/ docs/ README.md
+git commit -m "<conventional commit message>"
+git push
+gh pr create --title "..." --body "..."
+```
+
+### 6. Wait for CI green
+
+```bash
+gh pr checks <pr-number>
+```
+
+Both `lint-test-build (20)` and `lint-test-build (22)` must pass.
+
+### 7. Merge + tag
+
+```bash
+gh pr merge <pr-number> --squash --delete-branch
+git checkout main
+git fetch origin
+git reset --hard origin/main
+git tag -a vX.Y.Z -m "vX.Y.Z — <short description>"
+git push origin vX.Y.Z
+```
+
+### 8. `npm publish` — the passkey gotcha
+
+**Only the maintainer running an interactive terminal on their own machine can do this step.** Automated agents can't, because npm's 2FA is a passkey.
+
+```bash
+npm publish
+```
+
+Expected flow:
+
+1. `npm publish` prints the tarball contents + metadata.
+2. It hangs briefly, waiting for 2FA. On a passkey-only account it will print:
+   ```
+   npm error code EOTP
+   npm error This operation requires a one-time password...
+   ```
+3. Your password manager / browser should have surfaced a passkey prompt at the same time. Approve it.
+4. If the prompt didn't surface, re-run with `--otp=<code>` — but your npm account doesn't issue codes, so this path isn't available. You have to fix the passkey prompt instead (Chrome/Safari browser extension, OS-native passkey UI, or `1Password` / `Bitwarden` browser extension depending on your setup).
+
+If the passkey prompt is dismissed or times out, re-run `npm publish`.
+
+**Alternative: one-time npm token.** If you need to publish from a non-interactive environment (CI, remote agent), you can generate a temporary automation token at npmjs.com → Access Tokens → "Automation" (bypasses 2FA by design). Scope it to `@revfleet/hscli` only, set a short expiry, and delete it after use. Store it in the environment where the publish runs (`npm config set //registry.npmjs.org/:_authToken=<token>` or `NODE_AUTH_TOKEN`). Do NOT commit this token.
+
+### 9. Verify the release
+
+```bash
+npm view @revfleet/hscli version   # should print X.Y.Z
+npm view @revfleet/hscli dist-tags # 'latest' should point at X.Y.Z
+```
+
+Also confirm the GitHub Release exists at `https://github.com/revfleet/hscli/releases/tag/vX.Y.Z`. If the `release.yml` GitHub Action is set up, pushing the tag should have triggered it automatically.
+
+## Common failure modes
+
+| Error | Cause | Fix |
+|---|---|---|
+| `EOTP` at publish | Passkey prompt didn't reach you | Re-run `npm publish` from a terminal where the browser / OS can surface the passkey UI |
+| `E403 Forbidden` on the first publish of a new version | Name conflict / too-similar-to-existing-package | Rename under a scope (`@revfleet/<name>`) |
+| `E404` during `npm publish` | Scope doesn't exist on npm | Create it at npmjs.com/~yourname → "Create org" |
+| `EUSAGE` in CI | `package-lock.json` out of sync with `package.json` | Regenerate lock with `rm -rf node_modules package-lock.json && npm install` |
+| `release:verify` fails checksums step | `dist/` doesn't match `release/checksums.sha256` | Run `npm run build` then `npm run release:checksums` and commit |
+| GitHub tag-push triggers release workflow but attestation step fails | Attestations require a public repo | The workflow has `continue-on-error: true` on that step; the tarball still publishes |
+
+## Deprecating a bad release
+
+If a published version is broken:
+
+```bash
+npm deprecate @revfleet/hscli@X.Y.Z "Broken release — use X.Y.(Z+1). See CHANGELOG."
+```
+
+Do NOT `npm unpublish` past 72 hours — npm blocks it, and even within 72 hours unpublishing disrupts anyone who cached the tarball. Deprecation + a patch release is the right move.
+
+## Keeping the passkey flow manageable
+
+- Keep the password manager extension installed in your default browser. If Chrome/Safari doesn't see the passkey, publish fails.
+- Every now and then (once a quarter), generate a short-lived automation token specifically for planned maintenance. Revoke immediately after.
+- Don't switch the npm account away from passkey 2FA. Passkeys are more secure than TOTP and the "automation token" escape hatch is sufficient for the 1 hour/quarter you need CI publish.

package/docs/RELEASE_GOVERNANCE.md

@@ -0,0 +1,34 @@
+# Release governance
+
+> See also: [TESTING_PLAN.md](TESTING_PLAN.md) · [COMMAND_COMPATIBILITY.md](COMMAND_COMPATIBILITY.md) · [SECURITY.md](../SECURITY.md) · [PUBLISHING.md](PUBLISHING.md)
+
+## Versioning & Compatibility
+- Use semantic versioning.
+- Do not remove or rename commands without a major version bump.
+- Keep JSON response envelopes stable (`ok/data` and `ok/error`).
+
+## Required Release Gates
+1. `npm run typecheck`
+2. `npm test`
+3. `npm run build`
+4. `npm run release:checksums`
+5. `shasum -a 256 -c release/checksums.sha256`
+6. `npm audit --audit-level=low`
+
+Use one command for local release validation:
+
+```bash
+npm run release:verify
+```
+
+## Security Gates
+- No plaintext secrets in logs/tests/docs.
+- Policy-controlled destructive commands in production profiles.
+- `--force` required for writes and `--dry-run` available for preview.
+
+## Publishing Checklist
+1. Update `CHANGELOG.md`
+2. Confirm command compatibility notes
+3. Tag release in git
+4. Publish release artifacts with checksums
+5. Announce breaking changes (if any) with migration guidance

package/docs/REPORTING_SETUP.md

@@ -0,0 +1,310 @@
+# Reporting & Analytics Setup Guide
+
+> See also: [PORTAL_SETUP.md](PORTAL_SETUP.md) · [MARKETING_SETUP.md](MARKETING_SETUP.md) · [SALES_SETUP.md](SALES_SETUP.md) · [OPERATIONS_SETUP.md](OPERATIONS_SETUP.md)
+
+Complete configuration guide for HubSpot reporting and analytics. Covers dashboards, custom reports, attribution, analytics tools, and report sharing.
+
+**Prerequisites:**
+- Portal authenticated (`hscli auth whoami`)
+- Users & Teams configured (see [PORTAL_SETUP.md](./PORTAL_SETUP.md))
+- CRM data populated (contacts, deals, tickets, etc.)
+
+---
+
+## 1. Dashboards
+
+**Where:** Reports > Dashboards
+
+### 1.1 Dashboard Configuration
+
+| Setting | What to configure | Why it matters |
+|---------|-------------------|----------------|
+| Dashboard name | Descriptive name per audience (e.g., "Sales Leadership", "Marketing Overview") | Quick identification |
+| Visibility | Private, team, or everyone | Access control |
+| Default dashboard | Which dashboard loads first per user | Immediate visibility of key metrics |
+| Layout | 1, 2, or 3 column grid | Information density |
+| Date range | Default date filter (this month, this quarter, custom) | Consistent time window |
+| Filters | Dashboard-level filters (owner, team, pipeline) | Interactive exploration |
+
+### 1.2 Recommended Dashboards
+
+| Dashboard | Audience | Key reports |
+|-----------|----------|-------------|
+| Executive Summary | C-suite | Revenue, pipeline, conversion rates, NPS |
+| Marketing Performance | Marketing team | Traffic, leads, email metrics, campaign ROI |
+| Sales Pipeline | Sales leadership | Pipeline value, stage conversion, forecast |
+| Sales Rep Activity | Sales managers | Calls, emails, meetings, deals per rep |
+| Service Overview | Service leadership | Tickets, resolution time, CSAT, SLA compliance |
+| Revenue Operations | RevOps | Funnel, lifecycle stage conversion, data quality |
+| Website Analytics | Marketing/Content | Traffic, top pages, conversion rates, SEO |
+| ABM Dashboard | ABM team | Target account engagement, pipeline by tier |
+
+### 1.3 Dashboard Best Practices
+
+| Practice | Why |
+|----------|-----|
+| One dashboard per audience | Different teams need different views |
+| 8–12 reports per dashboard | Focused, not overwhelming |
+| Lead with KPIs at top | Most important metrics first |
+| Include trend charts | Context over point-in-time numbers |
+| Add comparison periods | Month-over-month, year-over-year |
+| Set recurring email delivery | Automated reporting cadence |
+
+---
+
+## 2. Custom Reports
+
+**Where:** Reports > Reports > Create Report
+
+### 2.1 Report Types
+
+| Type | Description | Best for |
+|------|-------------|----------|
+| Single object | One CRM object (contacts, deals, etc.) | Simple counts, lists, breakdowns |
+| Cross-object | Multiple related objects | Contacts with deals, deals with tickets |
+| Funnel | Stage-to-stage conversion | Sales funnel, lifecycle progression |
+| Attribution | Multi-touch revenue attribution | Marketing ROI |
+| Custom report builder | Drag-and-drop visual builder | Complex multi-dimensional reports |
+| Dataset-based | Built on Operations Hub datasets | Advanced calculated metrics |
+
+### 2.2 Visualization Types
+
+| Chart type | Best for | Example |
+|------------|----------|---------|
+| Bar chart | Comparisons | Deals by stage, leads by source |
+| Line chart | Trends over time | Monthly revenue, traffic growth |
+| Area chart | Volume trends | Cumulative deals over time |
+| Pie/donut | Proportions | Lead source distribution |
+| KPI/number | Single metric | Total revenue, open tickets |
+| Table | Detailed data | Contact list with properties |
+| Pivot table | Multi-dimensional | Revenue by rep by quarter |
+| Funnel | Stage progression | Lead → MQL → SQL → Customer |
+| Combo chart | Dual axis | Revenue (bars) + deal count (line) |
+
+### 2.3 Common Custom Reports
+
+| Report | Objects | Metrics | Dimensions |
+|--------|---------|---------|------------|
+| Pipeline velocity | Deals | Average days in stage | Pipeline stage |
+| Lead source ROI | Contacts + Deals | Revenue, conversion rate | Original source |
+| Rep performance | Deals | Total revenue, win rate, avg deal size | Owner |
+| Ticket resolution | Tickets | Avg time to close, volume | Priority, category |
+| Email engagement | Marketing emails | Open rate, click rate, unsubscribes | Campaign, date |
+| Landing page conversion | Landing pages | Views, submissions, conversion rate | Page, source |
+| MQL → SQL conversion | Contacts | Conversion rate, time to convert | Source, date |
+| Customer lifecycle | Contacts | Count per lifecycle stage | Stage, date |
+
+---
+
+## 3. Attribution Reporting
+
+**Where:** Reports > Attribution (Marketing Hub Enterprise / CMS Hub Enterprise)
+
+### 3.1 Attribution Models
+
+| Model | Description | Best for |
+|-------|-------------|----------|
+| First touch | 100% credit to first interaction | Understanding acquisition channels |
+| Last touch | 100% credit to last interaction before conversion | Understanding closing channels |
+| Linear | Equal credit to all touchpoints | Balanced view of all interactions |
+| U-shaped | 40% first, 40% last, 20% middle | Valuing both discovery and conversion |
+| W-shaped | 30% first, 30% lead create, 30% deal create, 10% middle | Full funnel visibility |
+| Time decay | More credit to recent interactions | Recency-weighted analysis |
+| Full path | 22.5% each for 4 key stages, 10% remaining | Most comprehensive model |
+| Custom | Define your own weights | Tailored to your business |
+
+### 3.2 Attribution Configuration
+
+| Setting | What to configure | Why it matters |
+|---------|-------------------|----------------|
+| Content types | Which interactions to track (pages, emails, ads, etc.) | Attribution scope |
+| Conversion events | What counts as a conversion (form submit, deal create) | Define success metrics |
+| Lookback window | How far back to attribute (30, 60, 90 days) | Attribution time frame |
+| Revenue attribution | Connect deal revenue to marketing touchpoints | Marketing ROI |
+
+### 3.3 Contact vs. Revenue Attribution
+
+| Type | Question it answers | Data needed |
+|------|-------------------|-------------|
+| Contact attribution | "Which channels create the most leads?" | Contacts + interactions |
+| Revenue attribution | "Which channels drive the most revenue?" | Contacts + deals + interactions |
+
+---
+
+## 4. Analytics Tools
+
+**Where:** Reports > Analytics Tools
+
+### 4.1 Traffic Analytics
+
+| Report | What it shows | Where |
+|--------|--------------|-------|
+| Sources | Traffic by channel (organic, paid, social, email, direct) | Analytics > Traffic |
+| Topic clusters | SEO performance by topic | Analytics > Traffic > Topics |
+| Pages | Performance per page (views, bounce rate, time on page) | Analytics > Traffic > Pages |
+| UTM parameters | Campaign tracking performance | Analytics > Traffic > UTM |
+
+### 4.2 Contact Analytics
+
+| Report | What it shows | Where |
+|--------|--------------|-------|
+| Contact create attribution | How contacts were created | Analytics > Contacts |
+| Lifecycle stage funnel | Conversion through stages | Analytics > Contacts > Lifecycle |
+| List performance | Growth and engagement per list | Analytics > Contacts > Lists |
+
+### 4.3 Sales Analytics
+
+| Report | What it shows | Where |
+|--------|--------------|-------|
+| Deal forecast | Weighted pipeline by category | Reports > Sales Analytics |
+| Sales activities | Calls, emails, meetings per rep | Reports > Sales Analytics |
+| Deal velocity | Time in each pipeline stage | Reports > Sales Analytics |
+| Win/loss analysis | Win rate by source, rep, product | Reports > Sales Analytics |
+| Quota attainment | Actual vs. target per rep | Reports > Sales Analytics |
+
+### 4.4 Service Analytics
+
+| Report | What it shows | Where |
+|--------|--------------|-------|
+| Ticket volume | Tickets created over time | Reports > Service Analytics |
+| Resolution time | Average time to close by priority | Reports > Service Analytics |
+| SLA performance | % tickets meeting SLA targets | Reports > Service Analytics |
+| Agent performance | Tickets handled, resolution time per agent | Reports > Service Analytics |
+| CSAT/NPS trends | Customer satisfaction over time | Reports > Service Analytics |
+
+---
+
+## 5. Report Sharing & Scheduling
+
+**Where:** Reports > Dashboards > Share/Email
+
+### 5.1 Sharing Options
+
+| Method | Configuration | Use case |
+|--------|--------------|----------|
+| Dashboard sharing | Share with specific users, teams, or everyone | Ongoing access |
+| Scheduled email | Recurring dashboard email (daily, weekly, monthly) | Automated reporting |
+| Slack integration | Send reports to Slack channels | Real-time team visibility |
+| Export | PDF, CSV, XLSX export | Offline analysis, presentations |
+| Embed | Embed dashboard in external page | Portal or intranet |
+
+### 5.2 Scheduled Report Configuration
+
+| Setting | What to configure | Why it matters |
+|---------|-------------------|----------------|
+| Recipients | Email addresses (internal + external) | Who receives the report |
+| Frequency | Daily, weekly, monthly | Reporting cadence |
+| Day/time | When the email is sent | Convenient delivery |
+| Subject line | Custom email subject | Clear identification |
+| Message | Optional note with context | Explain what to look for |
+| Dashboard filters | Pre-set filters for the emailed version | Relevant data per audience |
+
+---
+
+## 6. Goals & Tracking
+
+**Where:** Reports > Goals
+
+### 6.1 Goal Types
+
+| Goal type | Metric | Example |
+|-----------|--------|---------|
+| Revenue | Deal revenue closed | $500K/quarter |
+| Deals | Number of deals closed | 20 deals/month |
+| Contacts | New contacts created | 500 leads/month |
+| Calls | Calls logged | 50 calls/week per rep |
+| Meetings | Meetings booked | 15 meetings/week per rep |
+| Custom | Any numeric property | Custom KPIs |
+
+### 6.2 Goal Configuration
+
+| Setting | What to configure | Why it matters |
+|---------|-------------------|----------------|
+| Goal name | Descriptive name | Identification |
+| Contributors | Users, teams, or pipelines | Who is responsible |
+| Target value | Numeric target per period | Clear objective |
+| Duration | Monthly, quarterly, annual | Time-bounded targets |
+| Tracking property | Which CRM property to measure | Accurate measurement |
+| Pipeline filter | Which pipeline(s) count | Relevant scope |
+
+---
+
+## 7. Custom Behavioral Events
+
+**Where:** Reports > Analytics > Custom Behavioral Events (Marketing Hub Enterprise)
+
+### 7.1 Event Configuration
+
+| Setting | What to configure | Why it matters |
+|---------|-------------------|----------------|
+| Event name | Descriptive name (e.g., "Pricing Page Viewed") | Clear identification |
+| Event properties | Custom data with the event (plan type, feature viewed) | Granular analysis |
+| Tracking method | JavaScript API, HTTP API, or integration | Implementation approach |
+| Completion trigger | API call when event occurs | Real-time tracking |
+
+### 7.2 Event Use Cases
+
+| Event | Tracking method | Purpose |
+|-------|----------------|---------|
+| Product feature usage | JavaScript API in app | Product-led metrics |
+| Pricing page interaction | JavaScript tracking | Purchase intent signals |
+| API usage | HTTP API from backend | Developer engagement |
+| In-app NPS response | HTTP API from app | Product satisfaction |
+| Onboarding step completion | HTTP API from app | Activation tracking |
+
+---
+
+## Setup Checklist
+
+### Dashboards
+```
+[ ] Executive summary dashboard created
+[ ] Marketing performance dashboard created
+[ ] Sales pipeline dashboard created
+[ ] Service overview dashboard created
+[ ] Dashboard permissions set per team
+[ ] Default dashboard assigned per role
+```
+
+### Custom Reports
+```
+[ ] Key reports built for each department
+[ ] Pipeline velocity report created
+[ ] Lead source ROI report created
+[ ] Rep performance report created
+[ ] Ticket resolution report created
+[ ] Reports added to appropriate dashboards
+```
+
+### Attribution
+```
+[ ] Attribution model selected (start with linear or U-shaped)
+[ ] Content types configured
+[ ] Conversion events defined
+[ ] Lookback window set
+[ ] Revenue attribution enabled (if deals exist)
+```
+
+### Analytics Tools
+```
+[ ] Traffic analytics reviewed and bookmarked
+[ ] UTM parameter convention established
+[ ] Contact analytics baseline recorded
+[ ] Sales analytics reports reviewed
+```
+
+### Sharing & Scheduling
+```
+[ ] Weekly dashboard email scheduled for leadership
+[ ] Monthly dashboard email scheduled for stakeholders
+[ ] Slack integration configured for key metrics
+[ ] Export templates created for board reporting
+```
+
+### Goals
+```
+[ ] Revenue goals set per rep and team
+[ ] Activity goals set (calls, meetings) per rep
+[ ] Goals visible on dashboards
+[ ] Monthly goal review process established
+```

package/docs/ROADMAP-DATE-BASED-API.md

@@ -0,0 +1,103 @@
+# Roadmap: Date-based API versioning migration
+
+Status: **planning** (targeted for v0.9.x series, 2026-H2)
+Owner: hscli maintainer
+Last updated: 2026-04-22
+
+## Context
+
+HubSpot announced ([Spring 2026 Spotlight](https://developers.hubspot.com/changelog), 2026-04-14) that date-based API versioning is now GA. Going forward, public API endpoints will use `/YYYY-MM/` segments instead of `/v1/`, `/v2/`, `/v3/`, `/v4/`. Example:
+
+```
+Today:    /crm/v3/objects/contacts
+Future:   /crm/2026-03/objects/contacts
+```
+
+HubSpot has not (as of 2026-04-22) published a deprecation timeline for the numeric `vN` routes, and existing `/crm/v3/...` calls continue to work. This is forward-looking planning, not a response to a live incident.
+
+## Why `hscli` can't just swap paths wholesale
+
+Three reasons:
+
+1. **Coverage completeness.** `hscli` claims 1,180 endpoints. Every one of them has a hand-rolled path in the codebase. Migrating them all in a single PR is a multi-thousand-line diff; reviewability is near zero.
+2. **Per-endpoint cutover cadence.** HubSpot is unlikely to flip every endpoint to date-based versioning on the same day. Each endpoint will have its own migration window, and during that window both `/v3/` and `/2026-03/` will be valid — possibly with *different response shapes*.
+3. **Backward compatibility for users.** A scripted user who pins `@revfleet/hscli@0.7.x` must keep working as long as HubSpot keeps the `/vN/` routes live. We don't want to force callers onto a new hscli major just because we migrated internally.
+
+## Proposed approach: `apiVersion` client option + version table
+
+### 1. Path builder layer
+
+Introduce a helper `resolveVersionedPath({ area, date? })` that takes a logical endpoint and returns a concrete path. Example:
+
+```ts
+// Old — hand-rolled, hardcoded
+await client.request(`/crm/v3/objects/${objectType}/batch/read`);
+
+// New — explicit
+await client.request(
+  resolveVersionedPath("crm", "2026-03", `objects/${objectType}/batch/read`),
+);
+// → "/crm/2026-03/objects/contacts/batch/read" (if 2026-03 is selected)
+// → "/crm/v3/objects/contacts/batch/read"      (if v3 is selected)
+```
+
+The signature we want is small enough to retrofit incrementally.
+
+### 2. Version preference table
+
+Store a per-area version preference in `src/core/api-versions.ts`:
+
+```ts
+export const API_VERSIONS: Record<string, { current: string; fallback: string }> = {
+  crm:        { current: "v3",      fallback: "v3" },
+  marketing:  { current: "v3",      fallback: "v3" },
+  automation: { current: "v4",      fallback: "v4" },
+  // When HubSpot flips CRM to date-based:
+  // crm:     { current: "2026-03", fallback: "v3" },
+};
+```
+
+`fallback` is what we'd retry with on `404`/`ENDPOINT_NOT_AVAILABLE`, so we can roll forward aggressively without breaking on portals where HubSpot hasn't cut over yet.
+
+### 3. Response-shape adapter
+
+HubSpot may reshape response envelopes in the date-based endpoints. We'll add a small adapter layer in `src/core/api-shapes.ts` that normalizes responses back to the v3 shape our commands expect, gated per `(area, version)` tuple. Start with an identity adapter and add transformations only when actual drift surfaces.
+
+### 4. Capability probe extension
+
+The existing `hscli doctor capabilities` + cache file at `~/.revfleet/capabilities.json` already fingerprints endpoints by `portalId + scopes`. Add an additional dimension: `preferredVersion`. When a probe notices a newer `/YYYY-MM/` variant returning 200, cache that preference and future calls opt in automatically.
+
+### 5. Opt-in flag before default
+
+Ship the migration in three phases:
+
+- **Phase A (v0.8.x):** Version table exists. Defaults still resolve to `vN`. `--api-version 2026-03` flag + `HSCLI_API_VERSION` env var accepted for callers that want to exercise date-based paths manually.
+- **Phase B (v0.9.x):** For each area HubSpot has promoted, flip `current` to the date-based version. Keep `fallback` pointing at `vN` so the capability probe can retry. Log both paths in trace telemetry when a fallback happens.
+- **Phase C (v1.0):** Drop the `fallback` and delete any v3 path helpers HubSpot has formally deprecated. Breaking change justified by HubSpot's own deprecation.
+
+## Effort estimate
+
+- Phase A scaffolding (version table, `resolveVersionedPath`, flag wiring): **1–2 days**
+- Retrofitting 1,180 callsites to use `resolveVersionedPath` (mechanical refactor): **2–3 days** (spread across v0.8.x patches)
+- Adapter layer + capability probe extension: **1 day each**
+- Per-area cutover (Phase B): **hours per area, weeks of calendar time** — driven by HubSpot's own schedule
+
+## Non-goals
+
+- **Not rebuilding the client.** The request/retry/rate-limit layer doesn't need to change.
+- **Not anticipating HubSpot's every reshaping.** We add adapters when drift is observed, not pre-emptively.
+- **Not breaking v0.x callers.** Anyone on v0.7.x today should still work against their portal in 2027 unless HubSpot removes the v3 endpoint entirely.
+
+## Open questions
+
+- **What's HubSpot's removal timeline for `/v3/`?** Unknown as of 2026-04-22. The changelog says "GA" but not "deprecated". We'll revisit when that announcement lands.
+- **Will date-based versioning apply to the Search API?** The HubSpot Remote MCP server is built on CRM Search; any date-based cutover there affects us through the `search_crm_objects` compat tool too.
+- **Legacy `/contacts/v1/`, `/deals/v1/` etc.** — these predate the v1/v2/v3/v4 system. Likely to be removed before the numeric-to-date migration completes. Track separately.
+
+## Action items (not yet started)
+
+- [ ] Add `src/core/api-versions.ts` with the version table.
+- [ ] Add `resolveVersionedPath()` helper + unit tests.
+- [ ] Add `--api-version <YYYY-MM>` global CLI flag + `HSCLI_API_VERSION` env.
+- [ ] Retrofit the top-20-most-called endpoints first (`contacts`, `companies`, `deals`, `tickets`, `owners`, `properties`, associations, pipelines) as proof of concept in a dedicated PR.
+- [ ] Watch the HubSpot changelog for the first per-area "GA on date-based versioning" notice and flip that area's `current` in a follow-up.