@senso-ai/cli 0.11.0 → 0.12.0

package/README.md

@@ -124,9 +124,11 @@ Options: `--max-results <n>`
 ```
 senso content list                   List all knowledge base items
 senso content get <id>               Get full content detail by ID
+senso content versions <id>          List version history for a content item
 senso content delete <id>            Delete content (knowledge base + external)
 senso content unpublish <id>         Unpublish and revert to draft
 senso content verification           List items in verification workflow
+senso content verification-counts    Counts by status + published-domain summaries
 senso content reject <versionId>     Reject a content version
 senso content restore <versionId>    Restore rejected version to draft
 senso content owners <id>            List owners of a content item
@@ -134,7 +136,16 @@ senso content set-owners <id>        Replace owners (--user-ids)
 senso content remove-owner <id> <userId>  Remove a single owner
 ```
 
-Options: `content list` supports `--limit`, `--offset`, `--search`, `--sort`. `content verification` supports `--limit`, `--offset`, `--search`, `--status`. `content reject` supports `--reason`.
+Options: `content list` supports `--limit`, `--offset`, `--search`, `--sort`. `content verification` supports `--limit`, `--offset`, `--search`, `--status`, `--substatus`. `content reject` supports `--reason`.
+
+### Generated Content (GEO)
+
+```
+senso generated-content list         List published or draft generated content (--status published|drafts)
+senso generated-content get <id>     Get a generated content item with its rendered body
+```
+
+Options: `generated-content list` supports `--status`, `--limit`, `--offset`, `--search`.
 
 ### Content Generation
 
@@ -152,6 +163,24 @@ senso engine publish                 Publish content to external destinations (-
 senso engine draft                   Save content as draft for review (--data)
 ```
 
+### Tracked Competitors & Sources
+
+```
+senso competitors list               List tracked competitors
+senso competitors add                Add a competitor (--name, --url)
+senso competitors suggest            Get AI-generated competitor suggestions
+senso competitors batch-add          Add up to 50 competitors (--data)
+senso competitors update <id>        Update a competitor (--name, --url)
+senso competitors delete <id>        Remove a competitor
+
+senso tracked-sources list           List citation-classification rules
+senso tracked-sources add            Add a rule (--pattern, --match-type, --tier)
+senso tracked-sources update <id>    Replace a rule (--pattern, --match-type, --tier)
+senso tracked-sources delete <id>    Remove a rule
+```
+
+Options: `tracked-sources add`/`update` support `--category`, `--label`, `--priority`; `update` also supports `--active`/`--no-active`. `--match-type` is one of `domain | host | path_prefix | exact_url`; `--tier` is one of `primary | tracked | secondary`.
+
 ### Ingestion
 
 ```
@@ -185,6 +214,63 @@ senso prompts delete <promptId>      Delete a prompt
 
 Options: `prompts list` supports `--limit`, `--offset`, `--search`, `--sort`.
 
+### Analytics (GEO)
+
+Read-only metrics for your own organization: how often the AI models name your brand, your share of every brand mention the models made, and which domains and pages get cited. Works with the organization API key from `senso login`.
+
+```
+senso analytics summary              Headline metrics + previous window + deltas
+senso analytics mentions             Visibility time series (day or week buckets)
+senso analytics citations            Citation rates and shares, with the series
+senso analytics domains              Cited domains, ranked (coverage + share)
+senso analytics pages                Cited pages, with the prompts driving them
+senso analytics prompts              Per-prompt performance table
+senso analytics prompt <promptId>    One prompt: history + latest full answers
+senso analytics answers              Latest answer per prompt × model × location
+senso analytics glossary             Canonical definition of every metric
+senso analytics filters              Filter values that have data for this org
+```
+
+Options:
+
+| Command | Options |
+|---------|---------|
+| all except `prompt <promptId>`, `glossary`, `filters` | `--from`, `--to`, `--models`, `--location`, `--prompt-type`, `--tag` |
+| `mentions`, `citations` | `--group-by <day\|week>` |
+| `domains` | `--tier`, `--domain-contains`, `--sort <citations\|coverage>`, `--limit`, `--offset` |
+| `pages` | `--tier`, `--domain`, `--domain-contains`, `--url-contains`, `--sort <citations\|coverage>`, `--limit`, `--offset` |
+| `prompts` | `--search`, `--sort <mention_rate\|share_of_voice\|citations\|answered\|text>`, `--order <asc\|desc>`, `--limit`, `--offset` |
+| `prompt <promptId>` | `--from`, `--to`, `--models`, `--location`, `--no-include-answers` |
+| `answers` | `--from`, `--to`, `--models`, `--location`, `--prompt-type`, `--tag`, `--mentioned <bool>`, `--cited <bool>`, `--citation-tier <primary\|tracked\|secondary>`, `--limit`, `--offset` |
+
+`--from`/`--to` are `YYYY-MM-DD` and default to the 30 days ending at the most recent day that has data for your model/location filter (max window: 365 days). `--models` and `--location` are comma-separated; locations are case-sensitive exact codes (`US`, `US/California`) — the API also accepts `locations` as an alias for the `location` query param. Run `senso analytics filters` to see the values that actually have data.
+
+`analytics answers` is a snapshot, not a window. It always returns the newest stored answer per prompt × model × location, and `--from`/`--to` filter on `run_at` — when that answer was collected. Narrowing the window therefore **hides** prompt × model × location combinations whose latest answer falls outside it; it does not return older answers in their place. Use `analytics mentions` or `analytics citations` for history.
+
+Reading the numbers:
+
+- **Share of Voice** is your mention instances ÷ `brand_mention_total` — mentions of *every* brand the models named, not just your tracked competitors. It matches the Share of Voice in the Senso app. `tracked_mention_total` is still returned as a raw count in `totals`, but it is not the denominator.
+- **Citation Rate** and **Citation Coverage** divide by `D` — answers with at least one citation. **Citation Share** divides by `S` — total citation instances. They are different metrics on different denominators; every table shows the numerator and denominator next to the percentage so you can check.
+- The three tier **rates** are independent and can sum past 100% (one answer can cite an owned page and an external page). The three tier **shares** partition and sum to exactly 100%.
+- A metric renders as `—` when its denominator was zero. That is "not measured", not 0%.
+- Every response carries `notes[]` — caveats about window truncation, null denominators and tracking-set dependence. They are printed under a **Notes** heading in `plain` and `table` output, and are part of the payload in `--output json`.
+- `senso analytics glossary` is the canonical definition, denominator and gotcha for every metric.
+
+### Industry Intelligence (partner key required)
+
+```
+senso industries list                List industries visible to the partner
+senso industries summary <industry>  Industry overview over a time window
+senso industries brand <industry> <brandName>    One brand within an industry
+senso industries domain <industry> <domainOrUrl> Domain/URL citation lookup
+senso industries prompt-metrics <industry>       Per-prompt industry metrics
+senso industries glossary            Competitive-intelligence metric glossary
+```
+
+These commands read partner-scoped endpoints and **require a partner API key**. The organization key stored by `senso login` is rejected with a 401/403 — pass a partner key with `--api-key <key>` or `SENSO_API_KEY`. For metrics about your own organization, use `senso analytics` instead.
+
+Options: all except `list` and `glossary` support `--from`, `--to`, `--location`, `--models`; `prompt-metrics` also supports `--limit`, `--offset`; `list` supports `--search`. The `<industry>` argument accepts a UUID or a name (e.g. `"Automotive"`).
+
 ### Organization
 
 ```
@@ -219,15 +305,6 @@ senso run-config schedule            Get run schedule (days of week)
 senso run-config set-schedule        Set run schedule (--data)
 ```
 
-### Notifications
-
-```
-senso notifications list             List notifications
-senso notifications read <id>        Mark notification as read
-```
-
-Options: `notifications list` supports `--limit`, `--offset`, `--unread-only`.
-
 ### CLI Management
 
 ```
@@ -298,7 +375,7 @@ cnt_def456   Variable Rate Products   draft
 
 ## Auto-Update
 
-The CLI checks for new versions once every 24 hours (via GitHub releases) and shows a notice on stderr if an update is available:
+The CLI checks for new versions once every 24 hours (via the npm registry) and shows a notice on stderr if an update is available:
 
 ```
 ╭──────────────────────────────────────────────╮
@@ -344,22 +421,26 @@ npm test
 ```
 src/
 ├── cli.ts                 # Entry point — arg parsing, command dispatch
-├── commands/              # One file per command group (16 files)
+├── commands/              # One file per command group
 │   ├── auth.ts            # login, logout, whoami
 │   ├── search.ts          # search, search context, search content
-│   ├── content.ts         # CRUD + verification + owners
+│   ├── content.ts         # CRUD + versions + verification + owners
+│   ├── generated-content.ts  # GEO generated content (list, get)
 │   ├── generate.ts        # content generation settings + triggers
 │   ├── engine.ts          # publish, draft
+│   ├── competitors.ts     # tracked competitors CRUD + suggest
+│   ├── tracked-sources.ts # citation-classification rules CRUD
 │   ├── ingest.ts          # upload, reprocess (with S3 upload)
 │   ├── brand-kit.ts       # get, set
 │   ├── content-types.ts   # CRUD
 │   ├── prompts.ts         # CRUD
+│   ├── analytics.ts       # org GEO analytics (summary, citations, prompts, …)
+│   ├── industries.ts      # partner-scoped competitive intelligence
 │   ├── org.ts             # get, update
 │   ├── users.ts           # CRUD + set-current
 │   ├── api-keys.ts        # CRUD + revoke
 │   ├── members.ts         # list
 │   ├── run-config.ts      # models, schedule
-│   ├── notifications.ts   # list, read
 │   └── update.ts          # self-update
 ├── lib/
 │   ├── api-client.ts      # HTTP wrapper (native fetch, X-API-Key auth)
@@ -369,7 +450,7 @@ src/
 └── utils/
     ├── logger.ts          # Colored log helpers (picocolors)
     ├── branding.ts        # ASCII logo, gradient banner, boxed panels
-    └── updater.ts         # GitHub releases version check
+    └── updater.ts         # npm registry version check
 ```
 
 ### Tech Stack
@@ -388,7 +469,7 @@ src/
 
 ### Releasing a New Version
 
-This project uses [semantic versioning](https://semver.org/). The CLI's auto-update checker compares the installed version against the latest GitHub release using semver, so pre-release tags and version ordering are handled correctly.
+This project uses [semantic versioning](https://semver.org/). Publishing to npm is automated: pushing a `v*` tag runs `.github/workflows/publish.yml`, which builds the CLI and publishes it via [npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers) (GitHub Actions OIDC, no token secrets). Every pull request and push to `main` runs `.github/workflows/ci.yml` (typecheck, build, tests, smoke test).
 
 ```bash
 # 1. Bump the version in package.json, commit, and create a git tag
@@ -396,14 +477,11 @@ npm version patch   # 0.1.0 → 0.1.1 (bug fixes)
 npm version minor   # 0.1.0 → 0.2.0 (new features, backwards-compatible)
 npm version major   # 0.1.0 → 1.0.0 (breaking changes)
 
-# 2. Push the commit and tag
-git push origin main --tags
-
-# 3. Create a GitHub release (this is what the auto-updater checks)
-gh release create v0.2.0 --title "v0.2.0" --notes "Release notes here"
+# 2. Push the commit and tag — the tag triggers the publish workflow
+git push --follow-tags
 ```
 
-After step 3, users running the CLI will see the update notice within 24 hours (or immediately via `senso update`).
+The publish workflow refuses to run if the tag does not match the version in `package.json`. Once it finishes, users running the CLI will see the update notice within 24 hours (or immediately via `senso update`).
 
 ---