@signal4/s4 2.6.1 → 2.7.0

package/README.md

@@ -26,6 +26,38 @@ 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 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 · 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.
+
+## 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 +112,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;AAgnD7E,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAmG1C"}