@series-a/cli 0.22.2 → 0.22.3

package/CHANGELOG.md

@@ -4,6 +4,14 @@ 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.
 
+## 0.22.3 — Sales Navigator imports from the CLI
+
+- 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`.
+
 ## 0.22.0 — Admin keys, analytics parity, safety hardening, Obsidian sync
 
 - 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.

package/README.md

@@ -95,7 +95,7 @@ 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 six import sources in **Get Leads → Import Leads**:
+`leads import-from` runs any of the import sources in **Get Leads → Import Leads**:
 
 | source | required params | what it does |
 |---|---|---|
@@ -105,9 +105,23 @@ advisoros leads verify <id>
 | `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

package/SKILLS.md

@@ -0,0 +1,319 @@
+# AdvisorPro Skills Guide for AI Agents
+
+This file teaches any AI agent — CLI user or MCP client — how to operate
+AdvisorPro safely and effectively. It covers the mental model, the core
+workflows (campaigns, content, brand), the safety rails you must respect,
+and the tricks that separate a smooth run from a failed one.
+
+Two surfaces, one backend:
+
+- **CLI** — `advisoros` binary (`npm i -g @series-a/cli`), authenticates with
+  an API key saved per profile in `~/.advisoros/config.json`.
+- **MCP server** — `advisoros-mcp`, 44 tools, OAuth for the signed-in user.
+
+Both talk to the same `/agent-api` gateway. Everything is **scoped to one
+workspace**. Every mutation is **audited** (who, when, what, outcome).
+
+---
+
+## 1. The non-negotiable first steps
+
+### MCP
+1. **Always call `list_workspaces` first.** Every other tool requires a
+   `workspace_id`. You can only see workspaces you belong to — never guess an
+   ID from another session.
+2. Read the tool description before calling: destructive tools document their
+   own confirmation protocol.
+
+### CLI
+```bash
+advisoros login --profile main          # saves API key + workspace
+advisoros whoami                        # confirm the active profile/workspace
+```
+Global flags on every command: `--json` (machine output — **always use this
+when an AI is parsing the result**), `-w/--workspace`, `-p/--profile`,
+`--api-key`, `--as-agent <name>` (labels your audit rows — set it to your
+agent's name).
+
+---
+
+## 2. Mental model
+
+- **Leads** are people. They enter via import and are enriched from LinkedIn
+  afterwards. Dedupe key is `(workspace_id, linkedin_url)` — re-importing the
+  same URL upserts, never duplicates.
+- **Sequences** are message trees (steps with actions, delays, branches).
+  They are **not append-only** — steps can be edited, deleted, re-parented,
+  or wholesale replaced.
+- **Campaigns** bind leads + a sequence + sender LinkedIn accounts + a daily
+  limit. Lifecycle: draft → launch → pause/resume → archive/delete.
+- **Content** items are drafts until scheduled/published. Nothing is ever
+  auto-published from a draft.
+- **Knowledge base** grounds all AI generation. Only **confirmed
+  human-authored** items train the voice and count as citable evidence.
+- **Agents** run asynchronously: you get a `job_id` back, then poll.
+
+---
+
+## 3. LinkedIn safety — read this before any outreach
+
+LinkedIn account safety overrides everything else. The server (not the CLI or
+MCP) is the enforcing authority; you are expected to check before acting.
+
+Hard limits (server-enforced):
+- Invite note: **200 characters**
+- Direct message: **8,000 characters** (CLI caps client-side at 7,900)
+- Comment: **1,250 characters**
+- Per sender: **~25 invites/day, ~80 messages/day**
+
+Rules for agents:
+- **Before planning outreach or a bulk import, check capacity.**
+  CLI: `advisoros safety check` / `safety limits` / `safety reads`.
+  MCP: `linkedin_safety` (returns remaining capacity, cooldowns, and
+  `safe_bulk_import_size`).
+- **A cooldown or a 429 is not a failure.** Back off using `Retry-After` /
+  `retry_after_seconds` and retry. Never hammer.
+- `campaigns launch` and `sequences validate` run the same char-limit checks
+  the server enforces — **validate before launch**, not after.
+
+---
+
+## 4. How to create a campaign (end to end)
+
+### The fast path: `campaign-flow`
+One command does import → sequence → launch → status:
+
+```bash
+advisoros campaign-flow \
+  --name "Q3 CFO outreach" \
+  --file leads.csv \
+  --goal "Book discovery calls with CFOs" \
+  --senders <senderId1>,<senderId2> \
+  --daily-limit 25 \
+  --launch
+```
+Add `--dry-run` first to print the plan without touching the API.
+
+### The step-by-step path
+```bash
+# 1. Check capacity
+advisoros safety check
+
+# 2. Import leads (auto-chunks at 200/call, upserts on linkedin_url)
+advisoros leads import --file leads.csv
+# or from a source:
+advisoros leads import-from linkedin_search --query "CFO fintech London"
+# Sales Navigator (queued in the background, cap-aware):
+advisoros leads import-from sales_nav_url --url "<sales-nav-search-url>" --limit 500
+advisoros leads import-schedules            # progress, ETA, why it is waiting
+advisoros leads import-schedule pause|resume|cancel <scheduleId>
+
+# 3. Build or pick a sequence
+advisoros sequences create --name "CFO 3-touch"
+advisoros sequences add-step <seqId> --action sendInvitation --message "..."
+advisoros sequences add-step <seqId> --action wait --days 3
+advisoros sequences add-step <seqId> --action sendMessage --message "..."
+advisoros sequences validate <seqId>      # same checks as launch — do this
+
+# 4. Create the campaign and attach everything
+advisoros campaigns create --name "Q3 CFO outreach" \
+  --sequence <seqId> --senders <id1,id2> --daily-limit 25
+advisoros campaigns add-leads <campaignId> --file leads.csv
+
+# 5. Preflight, then launch (launch runs preflight itself and asks --confirm)
+advisoros campaigns preflight <campaignId>
+advisoros campaigns launch <campaignId> --confirm
+```
+
+MCP equivalent: `import_leads` → `manage_sequence` → `update_campaign` →
+`manage_campaign` (`preflight`, then `launch`).
+
+### After launch
+```bash
+advisoros campaigns stats <id>     # funnel: invites → accepts → replies → meetings
+advisoros campaigns health <id>    # run state, stalls, retries, watchdog
+advisoros campaigns events <id>    # full event log
+```
+
+---
+
+## 5. Sequences: the tricks
+
+- Allowed step actions: `viewProfile`, `addReaction`, `sendInvitation`,
+  `sendMessage`, `wait`. Nothing else — the server rejects unknown actions.
+- `sequences show <id>` accepts a **unique ID prefix**, not just full UUIDs.
+- `replace-steps` is **atomic**: it swaps the whole tree from a JSON file,
+  validated server-side. Prefer it over many `add-step` calls when an AI is
+  generating a full sequence.
+- `update-step` patches one step in place; `delete-step` re-parents its
+  children automatically.
+- Message templates support `{first_name}`-style tokens; the server guards
+  against unfilled tokens (~20-char guard). Keep variables real.
+- Waits can be expressed in days/hours/minutes. A lead who **replies is
+  removed from all further automation automatically** — never re-add them.
+
+---
+
+## 6. Keeping a consistent brand
+
+Brand consistency lives in three places; keep all three in sync.
+
+### a) The brand record (visual identity)
+```bash
+advisoros brand show                 # colours, fonts, logos, tagline, imagery
+advisoros brand set --primary-color "#1B4B8F" --font-heading "Inter"
+advisoros brand fields               # every editable field
+advisoros brand imagery set --style "minimal editorial" --mood "calm, expert"
+advisoros brand logos set --variant primary --url https://...
+advisoros brand social set --linkedin https://linkedin.com/company/...
+```
+MCP: `manage_brand` (same fields; supports partial updates, add/remove of
+motifs and reference URLs, logo upload, and the imagery direction that steers
+**every generated image**).
+
+### b) Tone of voice (written identity)
+```bash
+advisoros voice show                 # directive + apply-by-default flag
+advisoros voice set --directive "..." --apply-default
+advisoros voice sync                 # re-pull from Business Build
+advisoros voice references           # KB items used as writing samples
+advisoros voice add-reference <knowledgeItemId>
+advisoros voice set-primary <knowledgeItemId>   # pin the benchmark sample
+advisoros voice card                 # measured voice card (stylometric targets)
+advisoros voice score --file draft.md    # score text against the voice
+advisoros voice redraft --file draft.md  # rewrite in the author's voice
+```
+MCP: `tone_of_voice`.
+
+**The rule that matters:** only knowledge items confirmed as human-authored
+count as voice-training material. Confirm them first (`voice add-reference`,
+or MCP `curate_knowledge` with `approve`). AI-authored items are down-weighted
+and labelled in every retrieval — don't try to train the voice on them.
+
+### c) Knowledge base (factual identity)
+```bash
+advisoros knowledge add --url https://...     # auto-scraped + AI-classified
+advisoros knowledge add --title "..." --text "..." --category positioning
+advisoros knowledge list
+advisoros knowledge reclassify <id>
+```
+Categories: positioning, proof-points, frameworks, personas, case-studies,
+transcripts, market-intel, general. Generation is grounded in the KB — a thin
+KB means generic output. Feed it real positioning and real proof points.
+
+### Generating on-brand output
+```bash
+advisoros content generate --topic "..." --type linkedin_post   # KB + reference
+                                                                # grounded, URL-sanitised
+advisoros content citations <id>    # every source recorded for a draft
+```
+MCP: `generate_graphic` / `refine_graphic` for images (returns public URLs,
+uses the brand imagery direction automatically), `create_content_draft` for
+text (drafts only — nothing auto-publishes).
+
+---
+
+## 7. Content strategy & calendar
+
+```bash
+advisoros strategies ideate --weeks 4          # multi-week arc from KB + signals
+advisoros strategies create ...
+advisoros strategies resume <id>               # continue an interrupted build
+advisoros content list / show / approve / schedule / publish
+advisoros content bulk-approve                 # approve everything pending
+advisoros calendar list / create
+```
+Scheduling routes through Taplio when connected, otherwise the built-in cron
+scheduler. MCP: `content_strategy`, `content_strategy_posts`,
+`schedule_content`, `manage_content`.
+
+---
+
+## 8. Running agents (async jobs)
+
+```bash
+advisoros agents list
+advisoros agents run <name>              # returns a job_id immediately
+advisoros agents job <jobId>             # poll until terminal
+```
+MCP: `trigger_agent` (or `history: true` for recent runs).
+
+Watch recipe:
+```bash
+JOB=$(advisoros agents run news-monitor --json | jq -r .job_id)
+until advisoros agents job "$JOB" --json | jq -e '.status=="completed"'; do
+  sleep 15
+done
+```
+A job ends in a **terminal state** (`completed` or `failed`). Content jobs
+also carry `content_ids` and trace steps — if a job stays `running`, poll
+longer (large articles take minutes); don't resubmit, dispatch is
+exactly-once.
+
+---
+
+## 9. Destructive actions — the confirm protocol
+
+Deletion is allowed but always two-step:
+
+- CLI: `campaigns delete <id>` is dry-run by default; re-run with `--force`.
+- MCP: `manage_campaign` / `manage_sequence` with `operation: "delete"`:
+  first `dry_run: true` to see the impact, then `confirm: true` to execute.
+  Campaigns that already dispatched activity also require `force: true`.
+
+`archive` is the reversible alternative — prefer it when unsure.
+
+---
+
+## 10. Tricks & gotchas
+
+1. **`--json` everywhere.** Human tables are for humans; parse JSON.
+2. **`--as-agent <name>` on every call.** Your actions appear in
+   `advisoros audit list` — make them attributable.
+3. **Mutation responses are live.** Every campaign/sequence mutation returns
+   the freshly re-read record with live counts. List `stats` snapshots can
+   lag — trust the `live` block after a mutation.
+4. **Imports are idempotent.** Re-importing the same leads upserts on
+   `(workspace_id, linkedin_url)`. Safe to retry after a crash.
+5. **Inbox sends are dry-run by default.** `inbox send`/`reply` exit code `2`
+   without `--confirm` — nothing hits LinkedIn until you confirm.
+6. **Intelligence before content.** `signals list` and the watchlist (P0–P3
+   priorities) drive what the content agents write about. A tuned watchlist +
+   rich KB + confirmed voice references = on-topic, on-voice output.
+7. **`export <resource> <action>`** turns any list into CSV for offline work.
+8. **`kb sync`** mirrors the knowledge base into an Obsidian vault — one-way
+   push only, never a source of truth in the other direction.
+9. **`integrations status`** is read-only health. It will never return
+   credentials — don't ask it to.
+10. **Transcripts are anonymised** before storage. You will never see raw PII
+    from `meetings`/`list_transcripts`; that's by design.
+11. **Rate limits:** per-key sliding window. On HTTP 429, respect
+    `Retry-After`. Empty results are never used as a throttle signal — if you
+    get an empty list, the data is genuinely empty.
+12. **MCP writes are limited** to leads, knowledge items, drafts, and the
+    management tools above. Nothing auto-publishes; publishing is a deliberate
+    `manage_content publish_now` / `content publish` call.
+
+---
+
+## 11. Cheatsheet
+
+| Task | CLI | MCP tool |
+|---|---|---|
+| Discover workspaces | `workspaces list` (admin) | `list_workspaces` (first!) |
+| Check LinkedIn capacity | `safety check` | `linkedin_safety` |
+| Import leads | `leads import` / `import-from` | `import_leads` |
+| Track Sales Nav imports | `leads import-schedules` / `import-schedule` | `lead_import_schedules` |
+| Build a sequence | `sequences create/add-step/replace-steps/validate` | `manage_sequence` |
+| Launch a campaign | `campaign-flow` or `campaigns create/add-leads/launch` | `manage_campaign` |
+| Campaign funnel | `campaigns stats` | `campaign_analytics` |
+| Brand identity | `brand show/set/imagery/logos/social` | `manage_brand` |
+| Voice | `voice show/set/references/score` | `tone_of_voice` |
+| Knowledge | `knowledge add/list/reclassify` | `add_knowledge_item`, `curate_knowledge` |
+| Generate content | `content generate` | `create_content_draft`, `generate_graphic` |
+| Schedule | `content schedule` / `calendar create` | `schedule_content` |
+| Run an agent | `agents run` + `agents job` | `trigger_agent` |
+| Who did what | `audit list` | `list_audit` |
+
+When in doubt: `advisoros <command> --help`, `docs/cli.md`, and
+`docs/agent-api.md` are the canonical references.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@series-a/cli",
-  "version": "0.22.2",
+  "version": "0.22.3",
   "description": "AdvisorPro command-line interface — drive leads, campaigns, sequences and agents from your terminal.",
   "type": "module",
   "bin": {
@@ -10,6 +10,7 @@
     "bin/",
     "src/",
     "README.md",
+    "SKILLS.md",
     "CHANGELOG.md",
     "LICENSE"
   ],

package/src/commands/resources.mjs

@@ -111,12 +111,14 @@ export function registerLeads(program) {
     });
 
   withCommonOpts(leads.command("import-from <source>"))
-    .description("Import leads from any source: linkedin_search | company_search | post_reactors | paste_profiles | csv | heyreach")
-    .option("--query <q>", "search keywords (linkedin_search / company_search)")
+    .description("Import leads from any source: linkedin_search | company_search | post_reactors | paste_profiles | csv | heyreach | sales_nav_url | sales_nav_keywords")
+    .option("--query <q>", "search keywords (linkedin_search / company_search / sales_nav_keywords)")
+    .option("--url <url>", "full Sales Navigator search URL (sales_nav_url)")
     .option("--post <url>", "LinkedIn post URL (post_reactors)")
     .option("--file <path>", "CSV or pasted-profile text file (csv / paste_profiles / heyreach)")
     .option("--audience <name>", "audience (segment) name or id to attach to")
     .option("--campaign <id>", "campaign id (required for heyreach)")
+    .option("--priority <p>", "queue priority for Sales Navigator imports: normal | high | rush")
     .option("--limit <n>", "max prospects for LinkedIn sources", "50")
     .option("--no-enrich", "skip the LinkedIn verify + enrich chain")
     .action(async function (source) {
@@ -125,9 +127,11 @@ export function registerLeads(program) {
         const params = {
           source,
           query: o.query,
+          search_url: o.url,
           post_url: o.post,
           audience: o.audience,
           campaign_id: o.campaign,
+          priority: o.priority,
           limit: Number(o.limit),
           enrich: o.enrich !== false,
         };
@@ -137,12 +141,58 @@ export function registerLeads(program) {
           else params.csv = text;
         }
         const r = await call("leads", "import", params, ctxFrom(this));
-        emit(this, r, (d) => process.stdout.write(
-          `✓ Imported ${d.imported ?? 0} leads (${d.duplicates ?? 0} duplicates, ${d.skipped ?? 0} skipped, ${d.failed ?? 0} failed)\n` +
-          (d.job_id ? `  job: ${d.job_id}\n` : "")));
+        emit(this, r, (d) => {
+          if (d.schedule) {
+            process.stdout.write(
+              `${d.reused ? "↻ Reusing existing" : "✓ Queued"} background import — ${d.schedule.target_count} leads\n` +
+              `  schedule: ${d.schedule.id} (${d.schedule.status})\n` +
+              `  It drip-feeds inside your LinkedIn read limits. Track with \`advisoros leads import-schedules\`.\n`,
+            );
+            return;
+          }
+          process.stdout.write(
+            `✓ Imported ${d.imported ?? 0} leads (${d.duplicates ?? 0} duplicates, ${d.skipped ?? 0} skipped, ${d.failed ?? 0} failed)\n` +
+            (d.job_id ? `  job: ${d.job_id}\n` : ""));
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(leads.command("import-schedules"))
+    .description("List queued/running Sales Navigator background imports")
+    .option("--status <s>", "filter by status (queued|running|awaiting_capacity|paused|completed|failed|cancelled)")
+    .option("--all", "include finished imports")
+    .option("--limit <n>", "max rows", "25")
+    .action(async function () {
+      try {
+        const o = this.optsWithGlobals();
+        const r = await call("leads", "import_schedules", {
+          status: o.status,
+          active: o.all ? false : true,
+          limit: Number(o.limit),
+        }, ctxFrom(this));
+        emit(this, r, (d) => table(d.schedules ?? [], [
+          ["id", (s) => s.id.slice(0, 8)],
+          ["status", (s) => s.status],
+          ["progress", (s) => `${s.imported_count}/${s.target_count}`],
+          ["priority", (s) => s.priority],
+          ["source", (s) => s.source],
+          ["target", (s) => truncate(s.search_url || s.search_query || "", 48)],
+          ["reason", (s) => truncate(s.last_reason || "", 40)],
+        ]));
       } catch (e) { fail(e); }
     });
 
+  withCommonOpts(leads.command("import-schedule <action> <id>"))
+    .description("Pause, resume or cancel a scheduled import (action: pause|resume|cancel)")
+    .action(async function (action, id) {
+      try {
+        const r = await call("leads", "import_schedule_update", { id, action }, ctxFrom(this));
+        emit(this, r, (d) =>
+          process.stdout.write(`✓ Import ${d.schedule.id} is now ${d.schedule.status}\n`));
+      } catch (e) { fail(e); }
+    });
+
+
   withCommonOpts(leads.command("import-status <jobId>"))
     .description("Poll a running lead import")
     .action(async function (jobId) {