@signal4/s4 2.6.1 → 2.8.0

package/README.md

@@ -26,6 +26,65 @@ This package contains three surfaces backed by one HTTP client:
 | CLI | `npx @signal4/s4 search ...` | `client.ts` | `handlers/` → text |
 | MCP server | `s4 --mcp` | `client.ts` | `handlers/` → text |
 
+## CLI quick start
+
+```bash
+s4 collections                              # what you can scope to (omit --collection = whole corpus)
+s4 search immigration policy -n 10          # unquoted multi-word topic; -n / -k / --limit = number of results
+s4 search --keyword "border wall" -s "Tucker Carlson" --since 2024-06
+s4 search tariffs --collection anglosphere --days 800 -o tariffs.md
+s4 timeline tariffs --since 2023 -g quarter  # day | week | month | quarter | year (calendar buckets)
+s4 count tariffs --since 2025 --by month     # segments · episodes · channels per month, no cap
+s4 count "carbon tax" -m keyword --collection Canadian --by channel   # exact; rank shows by what they said
+s4 count "carbon tax" --vs "carbon pricing" --since 2024 --by quarter # several topics side by side
+s4 count "Strong Borders Act" -m keyword --by episode --order date -n 100  # every matching episode, newest first
+s4 count "carbon tax" -m keyword --since 2025 --by speaker   # who speaks in the matching segments, names corroborated per episode
+s4 top-speakers --topic tariffs -d 90       # same ranking, from the transcripts (not episode titles)
+s4 entity-claims "Donald Trump"             # every entity row of that name + merges; says what it matched
+s4 search tariffs --keyword --since 2025 --page 3   # pages of -n; --all follows every page
+s4 top-channels --topic Medicaid --country us -d 365 # channels ranked by what they said
+s4 segment 42314442                         # full text of a quote (seg:ID from search)
+s4 --version
+```
+
+Flags: `-n/-k/--limit` results · `--offset` skip · `-s` speaker · `-c` channel · `-d/--days` · `-m` mode ·
+`-o/--out` file · `--since/--until` (or `--start/--end`; `2023`, `2023-06`, `2023-06-15`; on search, claims, timeline, trend, the claims-analysis commands, top-claims, top-channels, top-speakers) · `--collection` (every corpus command) · `--json`.
+`--days` has no ceiling on search, claims, timeline and count; report commands cap at 365.
+`count` groups with `--by` (day · week · month · quarter · year · channel · episode · speaker · language · country · platform · collection · lean);
+keyword counts are exact, semantic counts are estimates at similarity ≥0.35, and every language is counted unless `--language` names some. Errors go to stderr with exit 1.
+
+## Paging
+
+Every list command and tool pages the same way: `limit` + `offset` (CLI `-n` and `--offset`,
+or `--page N`), and every answer ends with the next call (`next: offset:40`, CLI `--offset 40`).
+`s4 <command> --all` follows the pages for you (up to 50). How deep each list goes:
+
+| List | Depth |
+|---|---|
+| keyword search, `count` breakdowns, entity claims, claim observations | every match |
+| semantic / hybrid quote search | rank 2,000 (`depth_reached` says when you hit it) |
+| semantic / hybrid claims search | rank 1,000 |
+| top speakers / channels / talk time | 200 (topic rankings: every match) |
+| top claims | 100 |
+
+Past a semantic depth, `--keyword` search or `count ... --by episode` list every match.
+From TypeScript, `paginate()` walks the pages of any list call:
+
+```typescript
+import { paginate, searchQuotes } from '@signal4/s4/client';
+for await (const quote of paginate(searchQuotes, { topic: 'tariffs', mode: 'keyword', days: 365 })) { /* ... */ }
+```
+
+## Speed
+
+Every MCP tool description and every `s4 <command> --help` starts with how long the call takes at
+default settings: **instant** (<0.5s), **fast** (0.5–2.5s) or **slow** (>2.5s). Search, counts,
+timelines and trends also say how that grows with the window, e.g.
+`[fast ~1.5–2.5s; 12 months ~3–6.5s, all time ~5–11s]`. When a call is expected to take a while,
+the MCP server sends a progress notice with the estimate as it starts (to clients that pass a
+`progressToken`), and the CLI prints it to stderr. Answers that took longer than 2.5s end with
+`Took Ns`. The numbers live in `src/speed.ts`, measured against the live API (signal4#292, #296).
+
 ## TypeScript Client
 
 For applications that need typed access to the Signal4 API (frontends, agents, pipelines, scripts):
@@ -80,6 +139,7 @@ The client reads from environment variables:
 - `searchClaims(params)` — Search extracted claims with stance and observation counts
 - `detectTrend(params)` — Compare recent vs baseline mention volume
 - `getTimeline(params)` — Topic mention volume over time
+- `getCollections()` — Collections a key can scope to
 
 **Entities**
 - `searchSpeakers(query, limit?)` — Autocomplete speaker search

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAsgD7E,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CA6E1C"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,6EAA6E;AA0qD7E,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CA+G1C"}