@series-a/cli 0.23.1 → 1.0.0

package/CHANGELOG.md

@@ -1,149 +1,33 @@
-# @series-a/cli
+# Changelog
 
-All notable changes to this package are documented here. This project follows
-[Semantic Versioning](https://semver.org/) and uses
-[Changesets](https://github.com/changesets/changesets) to manage releases.
+All notable changes to `@series-a/cli` (and the paired `@series-a/mcp` server).
 
-## 0.23.0 — Bulk lead upserts, named profiles, atomic mutations
+## 1.0.0 — first stable release
 
-- `leads bulk_upsert` works at scale again. The database now enforces one lead per LinkedIn URL per workspace, so bulk imports update existing leads in place instead of failing with a Postgres conflict error. Repeated URLs inside a single request are collapsed, and leads without a LinkedIn URL stay separate records.
-- Named workspace profiles: `login -p <name>` stores a profile per workspace, and logging into a new workspace no longer silently re-points your `default` profile — you are warned and can opt in with `--set-default` (or skip the prompt with `--force`).
-- Workspace isolation on agent reads and mutations: `agents show <name>` and every agent mutation now resolve strictly inside the authenticated workspace, so same-named agents in other workspaces can never be returned or changed.
-- Every mutation returns JSON. `voice card --rebuild`, `intel-prompts resync` and watchlist toggles now return the changed record, the workspace id and an explicit success/error status instead of exiting silently.
-- Watchlist operations are atomic and de-duplicated by workspace + normalised name + type; removed items stay removed (suppressions) and are no longer reintroduced by automatic prompt sync, which now only reads active, approved, human-authored knowledge records.
-- `agents pipeline [name]` (alias `inspect`) exposes an agent's configuration, pipeline stages, blocking gates and advisory gates for inspection — defaults to the Content Creator Agent.
-- Content pipeline quality: signals are retrieved workspace-wide (drafts no longer report "0 signals" when teammates persisted them), signal sources are integrity-checked and quarantined when URL, title, publisher, text and summary disagree, publication dates and source authority are required before evidence is accepted, and alignment + evidence + citation checks must all complete before an article is eligible.
-- P0 watchlist topics are treated as highest research priority, not mandatory inclusion — all P0s are searched, only relevant ones are used, and searched/selected/excluded topics are recorded with scores and reasons.
-- Voice benchmarks are built from cleaned document structure (PDF page furniture, headers/footers and hard line wraps removed), so paragraph and heading metrics are realistic, and generation and scoring share the same benchmark and reference set.
-- Image generation failures now surface the real reason (model, input or storage error) in the app instead of a generic non-2xx message.
+First release marked stable for internal team use.
 
+### Commands
+- `login` / `logout` — API key stored with owner-only permissions in `~/.config/setu/config.json`
+- `practice create` — from a website URL, or from `--name` + `--town` with AI enrichment
+- `practice import <file.csv>` — bulk create with validation, `--dry-run`, `--limit`, bounded concurrency, `--out` results file and `--resume`
+- `practice review <draft-id>` / `practice publish <draft-id>`
+- `practice claim-link <practice-id>` — generate or rotate a claim link
+- `practice delete <id>` / `practice unpublish <id>` — refused for claimed or user-owned profiles
+- `dentist create --practice <id> --name "..."`
+- `status [<practice-id>]`
 
-## 0.22.3 — Sales Navigator imports from the CLI
+### Reliability
+- Request timeouts, retries with exponential backoff on network errors and 408/425/429/5xx, `Retry-After` support
+- Request IDs and `--verbose` diagnostics
+- Non-zero exit codes on failure; unknown commands fail loudly
+- `--version` and `--help` on every command; `--json` for machine-readable output
 
-- Import Sales Navigator lead lists straight from the CLI: `leads import-from sales_nav_url --url "<search-url>"` or `sales_nav_keywords --query "..."`. These queue as cap-aware background imports that drip-feed inside your LinkedIn read limits instead of blocking live campaigns.
-- Track and control them: `leads import-schedules` (progress, ETA, waiting reason) and `leads import-schedule pause|resume|cancel <id>`. Resuming resets retries and nudges the scheduler immediately.
-- Idempotent: re-running an identical import reuses the active schedule instead of duplicating it; match is per-source (URL for url imports, keywords for keyword imports).
-- Options: `--limit` (1–1000, default 100), `--audience` (segment id or name; created if missing), `--priority normal|high|rush`.
-- Docs updated in README and SKILLS.md; MCP gains `lead_import_schedules` and extended `import_leads`.
+### MCP
+- `@series-a/mcp` stdio server exposing practice create/review/publish, dentist create, claim-link, profile status and profile delete
+- Server version now reported from the package version
 
-## 0.22.0 — Admin keys, analytics parity, safety hardening, Obsidian sync
+## 0.2.0 — internal preview
+- Retries, logout, CSV validation, delete/unpublish, MCP delete tool
 
-- Admin keys work end-to-end. `login --admin` persists admin scope and reports reachable workspace count, `whoami` shows `scope: admin (cross-workspace)` plus reachable workspaces, and the caller identity is no longer hardcoded — override with `--as-agent <name>` or `ADVISOROS_AGENT_NAME`, persisted per profile.
-- Full analytics, safety and resource parity: `campaigns stats|events|health|leads`, new `analytics`, `safety`, `ctas`, `audiences`, `notifications`, `newsletter`, `video`, `watchlist`, `meetings`, `activity`, `workspaces` groups, and a generic `export` command that writes any list action to CSV.
-- Safety and coverage hardening:
-  - `campaigns preflight`, and `campaigns launch|resume` now dry-run by default and require `--confirm`; the API refuses to launch a campaign with no leads, no sequence, no steps or no sender.
-  - New `campaigns archive|clone|delete|remove-leads` and `sequences delete|update-step|delete-step`.
-  - Every destructive command prompts, and requires `--yes` when scripted; `--dry-run` previews.
-  - List actions now return honest `pagination` metadata (total, limit, offset, next_cursor) and allow up to 1000 rows.
-  - Not-found reads return 404 and a non-zero exit; unknown resources/actions return 400 with the supported list instead of a 500.
-- Add `advisoros kb link|sync|status|unlink` — two-way sync between a workspace Knowledge Base and a local offline Obsidian vault (Markdown + frontmatter + wikilinks, hash-based conflict detection).
-
-
-## 0.21.0 — Automatic voice checks, real citations, grounded drafts
-
-- Voice results are always up to date: every draft now runs a voice check automatically the moment it is created or its text is edited, and the fresh score and report are stamped onto the draft. `content show` and release decisions always see the latest voice result — no manual scoring step. Drafts whose voice check cannot finish are held back (`needs_revision`) instead of being left in a hanging "pending" state.
-- `content citations` now writes a real citation record per source used: inline citation markers are inserted into the draft body where each source's findings appear, then persisted and returned with counts. Calling it on a draft with no citations syncs them automatically instead of returning empty.
-- Draft generation is evidence-locked: required source signals must be quoted and attributed with a distinctive finding (topic-only mentions fail), copied source wording is rejected, rhythm is compared against the author's own benchmark, and the pre-release gate now blocks drafts on grounding, citations, framework fidelity, and pending/timed-out voice checks. Publication stays blocked until all checks pass.
-- Restored Agent API actions: `graphics` accepts `refine` again, plus the platform/account listing operations; legacy sequence and campaign action names are accepted as aliases.
-- Fixed `meetings` / `integrations` reads in the Agent API returning 500s (wrong sync-timestamp column).
-
-## 0.20.0 — Sequence migration fixes and hour-level waits
-
-- Hour- and minute-level waits from the terminal: `sequences add-step --delay-hours 3` and `--delay-minutes 45` (also on `update-step`), and in `replace-steps` JSON via `delay_hours` / `delay_minutes`. The step table now prints `3h` / `45m` instead of forcing days.
-- `replace-steps` now accepts a flat ordered list (no `parent` links) and treats it as a chain — HeyReach-style exports import directly.
-- Condition children without a `branch_label` default to the `yes` branch instead of failing validation.
-- Short ID prefixes (first characters of an ID) resolve for sequences and campaigns; invalid IDs return a structured 404 "not found" instead of a malformed-UUID 500.
-- `sequences show` works with both short and full IDs; alias actions (`show`, `get`) accepted.
-- `content generate` without `--wait` now returns a queued job id immediately instead of risking a gateway timeout; poll with `agents job-status <id>`. With `--wait` it blocks until the draft is ready. Finished drafts now reliably carry their final voice result and citation metadata.
-- Invite-withdraw and warm-up steps remain API-side only (not yet exposed); auto-withdraw stays off by default.
-
-## 0.15.1 — Engine fixes and reliability patch
-
-- `voice set` / `voice pin-benchmark` no longer fail with a `user_id` null violation — the Agent API now resolves the actor from the API key, workspace member, or owner context automatically.
-- AI-generated invitations are truncated at sentence/word boundaries with `{{token}}` protection — no more messages cut off mid-placeholder or mid-URL.
-- 1st-degree leads no longer stall sequences: the DM step is skipped with a clear `dm_skipped_not_first_degree` audit reason and the lead continues to the next step.
-- Fixed misleading "completed" stats: leads that only had zero-read cached identity lookups are now finalized as `skipped` with an explicit finish reason instead of `completed`.
-- `agent-run` 403s resolved: workspace guard now matches both agent name and type, so scheduled agents fire reliably from CLI-triggered workspaces.
-- Newsletter metrics now fall back to send-time provider handoff for delivered counts when Resend webhooks are absent.
-
-## 0.15.0 — Newsletter audiences and sending
-
-- `advisoros audiences create|edit|delete|add-leads|remove-leads` — full CRUD for smart audiences (lead segments), not just read + enrol.
-- `advisoros newsletter audience-create|audience-show|audience-edit|audience-delete` — manage mailing audiences; mirrored to Resend automatically when the workspace has it connected, local-only when it does not.
-- `advisoros newsletter contact-add|contacts-import|contact-remove|contact-unsubscribe` — contact management including CSV bulk import.
-- `advisoros newsletter sync-segment <segmentId> <audienceId>` — push a smart audience's leads into a mailing audience.
-- `advisoros newsletter send|test|render|metrics` — send now, schedule, test-send, render HTML, and read delivery totals, open/click/bounce rates and sending health.
-- New Agent API actions on `audiences` and `newsletter`; MCP gains `manage_audience` and `send_newsletter` (44 tools, manifest 0.12.0).
-
-## 0.14.0 — Daily reports
-
-- `advisoros reports list` — browse persisted daily reports (past and present) per workspace, with status, activity totals and recipient/sent counts.
-- `advisoros reports show <id|YYYY-MM-DD>` — full report detail including stats and the shareable dashboard URL.
-- `advisoros reports generate` — run the daily-report engine on demand; dry-run by default, `--send` emails all workspace members, `--to <email>` sends a single test copy.
-- Backed by the new Agent API `daily_reports` resource (`list` / `get` / `generate`).
-
-## 0.13.0 — Full lifecycle + scheduling engine
-
-- Campaign lifecycle is complete from the terminal: `campaigns update` (name, goal, sequence, sender accounts, daily send limit — no longer create-time-only), `launch`, `pause`, `resume`, `archive`, `clone`, and `delete` (dry-run preview by default, `--force` to execute, blocked when the campaign has dispatched activity unless forced).
-- Sequence editing: `sequences update-step`, `delete-step`, and `replace-steps` — steps are no longer append-only. Graph validation flags disconnected nodes and cycles before launch.
-- Scheduling engine awareness: calendar/schedule commands report whether a workspace will publish via Taplio (when connected) or the built-in cron scheduler, so automation targets the right engine.
-- Live counts after writes: campaign and sequence mutations re-read the record and return live stats, clearly separated from the stored snapshot which may lag.
-- Clearer errors under load: the API now returns a typed 429 with retry-after guidance instead of empty lists during heavy automation; the CLI surfaces this plainly.
-
-## 0.12.0 — Agent audit trail
-
-- `advisoros audit list/show/stats` — query the durable per-workspace audit log of every CLI/MCP/Agent API action (actor, surface, action, outcome, duration, correlation ID).
-- CLI requests now send actor/client/version headers so audit records attribute actions to the right user and CLI version.
-- `login` persists the profile email for audit attribution.
-
-## 0.11.0 — Video management
-
-- `videos` resource group: `list`, `show`, `create`, `generate`, `update`, `publish`, `unpublish`, `refresh`, `delete` against video projects, with workspace scoping and destructive-action confirmation.
-
-## 0.10.0 — Calendar & Command Centre write access
-
-- Full content calendar read/write/delete/schedule via CLI, with bulk operations and engine-aware scheduling (Taplio when connected, built-in cron otherwise).
-- Command Centre content management: update, approve, schedule, unschedule, and publish-now actions.
-
-## 0.9.0 — Tone of Voice
-
-- Full Tone of Voice support: workspace configuration, writing-sample references, benchmark pinning, voice cards, scoring/redrafting, and report CRUD.
-
-## 0.8.0 — Content Strategy
-
-- Full content strategy read/write: create, list, show, update, delete strategies; manage strategy posts; retry/resume generation.
-
-## 0.7.0 — Hardening & admin keys
-
-- Shared typed errors with machine-readable codes across all commands.
-- Cursor pagination up to 1,000 items per page.
-- Destructive actions require explicit confirmation (`--confirm` / `--force`).
-- `login --admin` for admin API keys, `--as-agent` impersonation flag, and `whoami` scope reporting.
-- Admin keys (`advos_admin_…`) authorize from key scope alone and work across all workspaces.
-
-## 0.6.1 — Campaign editing
-
-- `campaigns` — added `update`/`edit` (name, description, goal, sequence, sender accounts, daily send limit, launch stage, status). Mirrors the new `update_campaign` MCP tool.
-
-## 0.2.0 — Write coverage expansion
-
-- `inbox` — added `send`, `reply` (dry-run by default, `--confirm` to dispatch, 7,900 char guard), `mark-read` (bulk), `snooze` (`--for`, `--until`, `--clear`).
-- `sequences` — added `create`, `update`, `add-step` (per-action char limits: invite 200 / DM 8000 / comment 1250), `clone` (with branch remap), `validate`.
-- `content` — full CRUD: `create`, `update`, `delete` alongside existing `list`/`show`/`publish`.
-- `calendar` — new resource group: `list`, `create`, `update`, `delete` against `calendar_posts`.
-- `signals` — new resource group backed by `intelligence_signals`: `list`, `create`, `update`, `delete`.
-- `pipelines` — alias of `opportunities` with `list`, `create`, `update`, `delete`.
-- `agents` — added `create`, `update`, `set-status`, `delete`, `recent-runs`.
-
-## 0.1.0 — Initial release
-
-
-- `advisoros login` / `logout` / `whoami` / `profiles` with multi-workspace profile support.
-- `leads` — `list`, `get`, `set-status`, `import` (CSV/JSON/JSONL, auto-chunked), `verify`.
-- `campaigns` — `list`, `show`, `create`, `add-leads`, `launch`, `pause`, `resume`.
-- `sequences` — `list`, `show` (ordered step table).
-- `inbox` — `threads` (read-only).
-- `content` — `list`, `show`, `publish`.
-- `agents` — `list`, `run`, `job`.
-- Global flags: `--json`, `--workspace`, `--profile`, `--api-key`.
-- Programmatic SDK via `@series-a/cli/src/api.mjs`.
+## 0.1.0 — internal alpha
+- Initial CLI and MCP server

package/README.md

@@ -1,316 +1,98 @@
-# @series-a/cli
+# Setu CLI (internal)
 
-A command-line interface to the AdvisorPro platform — drive leads, campaigns, sequences and agents from your terminal. Built on top of the [`/agent-api`](https://github.com/series-a/advisoros/blob/main/docs/agent-api.md) M2M router, so anything the CLI does is auditable and workspace-scoped.
-
----
+Build claimable practice and dentist profiles from the command line.
 
 ## Install
 
 ```bash
-# Run without installing — always fetches latest
-npx @series-a/cli@latest --help
-
-# Pin a version (recommended for CI)
-npx @series-a/cli@0.1.0 --help
-
-# Or install globally
-npm i -g @series-a/cli
-advisoros --help
-```
-
-Requires **Node.js ≥ 20**.
-
-> Releases are tagged `cli-vX.Y.Z` in the repo and published to npm with [provenance](https://docs.npmjs.com/generating-provenance-statements). See [`CHANGELOG.md`](./CHANGELOG.md).
-
-## 1. Get an API key
-
-1. Sign in to AdvisorPro.
-2. Open **Settings → API Keys**.
-3. Click **New key** → choose **Workspace** scope (recommended).
-4. Copy the key — you won't see it again.
-
-The **CLI quickstart** card on that page shows a copy-paste `npx` command pre-filled with your workspace ID.
-
-> Admin keys (cross-workspace) also work but are intentionally restricted. Default to workspace keys.
-
-## 2. Log in
-
-```bash
-npx @series-a/cli@latest login
-# Prompts for API key + workspace ID (the 6-char slug, e.g. dmw9wj)
-```
-
-### Admin login
-
-Admin keys (`advos_admin_…`) are detected automatically — no workspace prompt:
-
-```bash
-advisoros login --admin
-# ✓ Logged in as admin profile "default" — N workspaces reachable
-
-advisoros workspaces list                       # admin-only, no workspace needed
-advisoros campaigns list --workspace dmw9wj     # pass workspace per command
-advisoros whoami                                # shows scope: admin (cross-workspace)
-```
-
-Multiple workspaces?
-
-```bash
-advisoros login --profile acme        # save as "acme"
-advisoros leads list --profile acme   # use the named profile
-```
-
-Config is stored at `~/.advisoros/config.json` with mode `0600`. You can also use env vars: `ADVISOROS_API_KEY`, `ADVISOROS_WORKSPACE_ID`, `ADVISOROS_PROFILE`, `ADVISOROS_BASE_URL`.
-
-```bash
-advisoros whoami
-advisoros profiles
-advisoros logout --profile acme
-```
-
-## 3. Command reference
-
-Global flags (work on every subcommand):
-
-| Flag | Description |
-|---|---|
-| `--json` | Emit raw JSON instead of formatted tables. |
-| `-w, --workspace <id>` | Override the workspace from your profile. |
-| `-p, --profile <name>` | Pick a saved profile. |
-| `--api-key <key>` | Override the saved API key. |
-
-### Leads
-
-```bash
-advisoros leads list [--status new] [--persona founder] [--search acme] [--limit 50]
-advisoros leads get <id>
-advisoros leads set-status <id> <new|engaged|won|lost>
-advisoros leads import --file leads.csv [--persona founder]
-advisoros leads import-from <source> [--query ...] [--post <url>] [--file <path>] [--audience <name>] [--campaign <id>] [--limit 50] [--no-enrich]
-advisoros leads import-status <jobId>
-advisoros leads update <id> [--name ...] [--title ...] [--company ...] [--email ...] [--linkedin ...] [--persona ...] [--score ...] [--status ...] [--notes ...]
-advisoros leads delete <id>
-advisoros leads verify <id>
-```
-
-`leads import` accepts CSV (header row), JSON array, or JSONL. Upserts on `(workspace_id, linkedin_url)`. Bulk requests are auto-chunked at 200/call (server cap: 500/call).
-
-`leads import-from` runs any of the import sources in **Get Leads → Import Leads**:
-
-| source | required params | what it does |
-|---|---|---|
-| `linkedin_search` | `--query` | keyword / title / company people search via Unipile |
-| `company_search` | `--query` | LinkedIn company search |
-| `post_reactors` | `--post <url>` | everyone who reacted to a LinkedIn post |
-| `paste_profiles` | `--file <path>` | name + LinkedIn URL lines; rest is enriched |
-| `csv` | `--file <path>` | same CSV parser the UI uses |
-| `heyreach` | `--file <path>` `--campaign <id>` | HeyReach campaign CSV, statuses preserved |
-| `sales_nav_url` | `--url <sales-nav-search-url>` | queues a background Sales Navigator import, drip-fed inside the LinkedIn read limits |
-| `sales_nav_keywords` | `--query` | same background queue, from Sales Navigator keywords |
-
-All sources accept `--audience` to attach leads to a segment (created if missing). LinkedIn-backed sources run at bulk read priority so live campaigns are not starved. Long-running imports return a `job_id`; poll with `advisoros leads import-status <jobId>`.
-
-Sales Navigator sources do not run inline — they create a **scheduled import** that the
-cap-aware scheduler drip-feeds over hours or days:
-
-```bash
-advisoros leads import-from sales_nav_url --url "https://www.linkedin.com/sales/search/people?..." \
-  --limit 500 --audience "Q3 ICP" --priority high
-advisoros leads import-schedules
-advisoros leads import-schedule pause|resume|cancel <id>
-```
-
-Cancelling keeps the leads already imported.
-
-### Campaigns
-
-```bash
-advisoros campaigns list [--status active]
-advisoros campaigns show <id>
-advisoros campaigns create --name "Founder Pitch Club" \
-                           --sequence <sequenceId> \
-                           --senders acc_a,acc_b \
-                           --daily-limit 25
-advisoros campaigns add-leads <campaignId> --lead-ids id1,id2,id3
-advisoros campaigns add-leads <campaignId> --file lead-ids.txt
-advisoros campaigns launch <id>
-advisoros campaigns pause  <id>
-advisoros campaigns resume <id>
+cd packages/cli && npm link      # gives you the `setu` command
+setu login                       # paste the internal CLI key
 ```
 
-`launch` flips status to `active` — the `enforce_campaign_char_limits` trigger validates every step's copy against LinkedIn limits before allowing the transition.
+The key is the `SETU_CLI_API_KEY` secret from the Setu backend. It is stored at
+`~/.config/setu/config.json` (chmod 600). You can also set `SETU_CLI_API_KEY`
+and `SETU_API_URL` as environment variables in CI.
 
-### Sequences / Inbox / Content / Agents / Meetings / Newsletter / Integrations
+## Build one profile
 
 ```bash
-advisoros sequences list
-advisoros sequences show <id>
-
-advisoros inbox threads [--campaign <id>] [--lead <id>] [--needs-attention] [--limit 50]
-
-advisoros content list [--status published] [--type post] [--search ...]
-advisoros content show <id>
-advisoros content publish <id>
-
-advisoros agents list
-advisoros agents run <name> --input '{"foo":"bar"}'
-advisoros agents trigger <name> --input '{"foo":"bar"}'
-advisoros agents history [--agent <name>] [--days 30] [--limit 50]
-advisoros agents job <jobId>
-
-advisoros meetings list [--limit 50]
-advisoros meetings transcripts [--provider fireflies|roam] [--since 2026-01-01] [--limit 50]
-advisoros meetings transcript <transcriptId>
-
-advisoros newsletter list
-advisoros newsletter create --subject "Weekly roundup" --body "<html>..." [--preview-text "..."]
-advisoros newsletter edit <id> [--subject ...] [--body ...] [--preview-text ...] [--status draft|scheduled]
-advisoros newsletter delete <id>
-
-advisoros integrations status
-advisoros integrations check <platform>
+setu practice create --url https://smiledental.co.uk
+setu practice create --name "Smile Dental" --town Portsmouth
+setu practice review <draft-id>
+setu practice publish <draft-id>
 ```
 
-> **Heads-up:** `inbox send`/`reply` are intentionally **not** in v1. Outbound goes through `campaigns launch` (sender resolution + char limits + per-sender daily budget). For one-off DMs, use the web inbox.
+`create` scrapes the practice website (services, pricing, hours, team, images),
+pulls their Google listing (address, phone, rating, reviews, opening hours) and
+returns a readiness score. Nothing is public until `publish`.
 
-`meetings transcript` only returns full text once the transcript has been anonymised; otherwise metadata is returned with the body redacted.
+`publish` creates an **unclaimed** listing: it appears in patient search with an
+"Unclaimed" badge, ranked below live subscribed practices, with enquiry capture
+instead of booking. It also seeds any clinicians the AI detected (skip with
+`--no-dentists`).
 
-`integrations status` is read-only and never returns credentials. `integrations check <platform>` runs a live health probe for the requested platform (e.g. `linkedin_tool`).
+## Bulk import
 
-### Obsidian vault mirror (`kb`) — one-way
+CSV with any of these columns: `name, website, town, postcode, email, phone`.
 
 ```bash
-advisoros kb link ./client-vault --workspace dmw9wj
-advisoros kb status ./client-vault           # dry-run preview
-advisoros kb pull ./client-vault             # mirror notes + graph entities
-advisoros kb pull ./client-vault --preserve-local
+setu practice import practices.csv --publish
 ```
 
-One-way push, AdvisorPro → Obsidian. Markdown notes with frontmatter, `[[wikilinks]]` and an
-`## Entities` block, plus `Entities/<Type>/*.md` for graph nodes. Local edits are overwritten unless
-`--preserve-local` is used (remote copy lands as `<slug>.remote.md`). Nothing is pushed back.
-
+Rows are processed one at a time (Firecrawl / Google rate limits) and failures
+are listed at the end so you can retry them.
 
-## Examples
-
-**Spin up a campaign from a fresh CSV:**
+## Claim links
 
 ```bash
-advisoros leads import --file ./prospects.csv --persona founder
-advisoros leads list --persona founder --limit 200 --json \
-  | jq -r '.leads[].id' > lead-ids.txt
-
-advisoros campaigns create --name "Q3 Founder Outreach" \
-  --sequence 1a2b3c4d-... --senders acc_milan --daily-limit 25
-# → ✓ Created campaign 8297f04d-...
-
-advisoros campaigns add-leads 8297f04d-... --file lead-ids.txt
-advisoros campaigns launch    8297f04d-...
+setu practice claim-link <practice-id>
+setu status                       # every seeded profile and its claim state
+setu status <practice-id>         # one profile plus its claim attempts
 ```
 
-**Tail a long-running agent job:**
+Send the claim link in outreach. The practice signs in, and is verified either
+by their email domain matching their website, or by a code sent to the public
+contact address on their Google listing. On success the profile transfers to
+them, pre-filled, and they continue through the normal onboarding and
+subscription flow.
 
-```bash
-JOB=$(advisoros agents run lead-intelligence --input '{}' --json | jq -r '.run.job_id')
-watch -n 5 "advisoros agents job $JOB --json | jq '{status,progress}'"
-```
-
-## Safety rails
-
-Anything that stops sending, un-enrols leads or deletes data now asks first.
+## Clinicians
 
 ```bash
-# Launch is a dry run until you confirm — preflight runs server-side.
-advisoros campaigns preflight 9884b9ec
-advisoros campaigns launch 9884b9ec            # shows blockers, changes nothing
-advisoros campaigns launch 9884b9ec --confirm  # actually launches
-
-# Destructive commands prompt; scripts must pass --yes.
-advisoros campaigns delete 9884b9ec --dry-run
-advisoros campaigns delete 9884b9ec --yes
-advisoros sequences delete-step 6b60d6ad --yes
+setu dentist create --name "Dr Jane Roe" --practice <id> --profile-url https://…/team/jane
 ```
 
-A campaign with no leads, no sequence, no steps or no sender account is
-**refused**, not silently activated. `--force` overrides once you know why.
-
-New commands: `campaigns preflight|archive|clone|delete|remove-leads`,
-`sequences delete|update-step|delete-step`.
-
-## Reading more than 200 rows
+## Flags
 
-List commands accept `--limit` up to 1000 and every list response carries
-`pagination` (`total`, `limit`, `offset`, `next_cursor`, `has_more`). If you ask
-for more than the maximum, the response says it was clamped instead of quietly
-truncating.
+`--json` for machine-readable output, `--operator "Your Name"` to attribute
+seeded profiles to you.
 
-## Exit codes
-
-| Code | Meaning |
-|---|---|
-| 0 | Success |
-| 1 | Generic failure (`error` in JSON response or thrown). Stderr contains the message. |
-
-## Programmatic use
-
-```js
-import { call } from "@series-a/cli/src/api.mjs";
-
-const { campaigns } = await call("campaigns", "list", { status: "active" }, {
-  apiKey: process.env.ADVISOROS_API_KEY,
-  workspaceId: "dmw9wj",
-});
-```
+## Reliability
 
-## Troubleshooting
+- Every request has a timeout (`SETU_TIMEOUT_MS`, default 240s) and retries
+  transient failures (network drops, 429, 5xx) with exponential backoff
+  (`SETU_RETRIES`, default 3). `Retry-After` is honoured.
+- `--verbose` prints retry attempts and stack traces.
+- `setu logout` removes the stored key from this machine.
+- Unknown commands and failed bulk imports exit non-zero (safe for scripts/CI).
 
-- **401 Unauthorized** — key wrong / revoked / wrong base URL. Re-run `advisoros login`.
-- **403 not authorized for the requested workspace_id** — workspace-scoped key + `--workspace` to a different workspace. Use the matching key.
-- **CHAR_LIMIT_EXCEEDED on launch** — a sequence step exceeds LinkedIn limits (200 invitations / 8000 DMs / 1250 comments). Fix in web app.
-- **Network error** — check `ADVISOROS_BASE_URL` if you're pointing at a non-default deployment.
-
-## Releasing (maintainers)
+## Bulk import
 
 ```bash
-cd tools/cli
-npx changeset                                            # describe the change
-npm run version-packages                                 # bump package.json + CHANGELOG.md
-git commit -am "chore(cli): release v$(node -p "require('./package.json').version")"
-git tag "cli-v$(node -p "require('./package.json').version")"
-git push --follow-tags
-# → .github/workflows/cli-release.yml publishes to npm with provenance
+setu practice import practices.csv --dry-run            # validate only
+setu practice import practices.csv --publish \
+  --concurrency 3 --out results.json                    # run
+setu practice import practices.csv --resume results.json # retry failures only
 ```
 
-`NPM_TOKEN` must be set in the repo's GitHub Actions secrets (automation token with publish access to the `@series-a` org).
-
-## Roadmap (v1.1)
-
-- `inbox send` / `inbox reply` with explicit `--confirm` + per-sender budget enforcement.
-- `agents tail <jobId>` (SSE).
-- `admin workspaces …` (admin keys only).
-- Single-binary builds via `pkg`.
-
-## Full API reference
-
-See [`docs/agent-api.md`](../../docs/agent-api.md) for the underlying `/agent-api` envelope.
+Rows need either a `website`/`url`, or a `name` plus `town`/`city`; anything
+else is reported and skipped before any API call is made.
 
-
-
-## Admin keys
-
-Admin keys (`advos_admin_…`) are authorised by the key itself — they do **not** need an
-`agent_workspace_bindings` row. `agent_name` is an audit label only.
+## Removing seeded profiles
 
 ```bash
-advisoros login --admin --profile ops     # no workspace prompt; prints reachable workspace count
-advisoros whoami --profile ops            # scope: admin (cross-workspace) + reachable count
-advisoros workspaces list --profile ops   # every reachable workspace (paginated, up to 1000)
-advisoros analytics overview --workspace dmw9wj --profile ops
+setu practice delete <practice-id> --unpublish   # hide from patients
+setu practice delete <practice-id>               # delete (unclaimed only)
 ```
 
-Caller identity is overridable: `--as-agent <name>` on any command, `ADVISOROS_AGENT_NAME`
-in the environment, or the `agentName` stored on the profile at login (default `advisoros-cli`).
-
-Workspace-scoped keys are unchanged: they can only reach their own workspace (403 otherwise)
-and cannot use the `workspaces` resource. An agent without bindings now gets a typed 403
-explaining to use an admin key, instead of a 500.
+Claimed or user-owned profiles are always refused.