docs(skills): adopt composite query audit contract + ban bash heredocs

skills/claude-code/SKILL.md

@@ -1,41 +1,62 @@
 # Topline OS CLI Skill
 
-Use the `topline` CLI for Topline OS CRM workflows. For broad CRM analytics, **prefer the hosted warehouse SQL path** (`topline --agent query ...`) when `TOPLINE_QUERY_TOKEN` is configured. Use REST-backed CLI commands for live operational reads, exact object drilldowns, and approved writes.
+Use the `topline` CLI for Topline OS CRM workflows. For broad CRM analytics, **prefer the composite warehouse commands** (`topline --agent query audit|snapshot|freshness`) when `TOPLINE_QUERY_TOKEN` is configured. They wrap the standard pipeline audit shape into one CLI call. Use REST-backed CLI commands for live operational reads, exact object drilldowns, and approved writes.
 
-## Standard pipeline audit contract (hard limit — 4 calls)
+## Standard pipeline audit contract (hard limit — 3 calls)
 
 For any "what happened in pipeline X over window W" question, run **exactly** this sequence and stop:
 
-1. Readiness probe. Prefer `topline --agent query doctor` when the installed CLI supports it; JSON: `queryTokenPresent`, `schemaReachable`, `tableCount`, `missingTables`, `recommendation`. If the command returns `unknown query command "doctor"`, the binary is stale — rebuild via `scripts/install-local.sh`, or use `topline --agent query help` + `topline --agent query explain --tables opportunities,pipeline_stages,messages,contacts,call_events,appointments` as the fallback probe and proceed with SQL. If `queryTokenPresent` is false, `schemaReachable` is false, or `explain` fails for an expected table, stop and report the readiness gap. If `missingTables` is non-empty, treat each as an `os-mcp` coverage bug and surface it in the final answer.
-2. `topline --agent query sql --sql '<composite audit>'` — ONE call returning open count/value, stage rollup, activity by channel/direction, moved/created/closed deals in window, top active deals. If the window is custom/relative and not already known, prepend a single `date` call before this step.
+1. `topline --agent query doctor` — readiness probe. JSON: `queryTokenPresent`, `schemaReachable`, `tableCount`, `missingTables`, `recommendation`. If `queryTokenPresent` is false, `schemaReachable` is false, or any expected table is missing, stop and report the readiness gap. Missing tables/views are `os-mcp` coverage bugs; surface them in the final answer.
+2. `topline --agent query audit --pipeline PIPELINE_ID --since WINDOW --status open` — one composite call returning `freshness`, `snapshot`, `activity` (with `unique_touches`), `deals`, and `movement`. Default `--since this-week-et` for "this week"; the CLI resolves the window.
 3. Answer.
 
-**Hard ceiling: 4 tool calls after skills load** (date if needed + readiness probe + composite SQL + answer). Banned in the default flow:
+**Hard ceiling: 3 tool calls after skills load** (doctor + audit + answer). Banned in the default flow:
 
+- Raw `topline --agent query sql --sql ...` for standard pipeline audits — `query audit` already covers the shape.
+- `query schema`, `query explain`, or per-table freshness SQL before `query audit`. The audit payload's `freshness` field is enough.
 - `pipeline audit`, `opportunities search`, `conversations search`, per-conversation message fetches.
-- `python3` / `execute_code` / any subprocess wrapper around `topline`. The CLI returns JSON; parse it directly. Reshape data in SQL with a final `SELECT`, not in Python.
+- `python3` / `execute_code` / any subprocess wrapper around `topline`. The CLI returns JSON; parse it directly.
+- **Bash heredocs around `query sql`**: `SQL=$(cat <<'SQL' ... SQL)` or `topline --agent query sql --sql "$(cat <<SQL ... SQL)"`. Same shape as the Python wrapper anti-pattern, different shell. If you find yourself authoring multi-line SQL for a standard pipeline question, switch to `query audit`.
 - Editing this skill (or the audits skill) via `skill_manage` mid-run. The contract is read-only during execution; propose edits in a separate turn.
 
-`query doctor` replaces the prior ad-hoc freshness/token probe. Only run a separate freshness SQL (`MAX(_synced_at)` per table) if the user explicitly asks about sync lag.
-
 Exceptions — each requires the user explicitly asking:
 
 - "Drill into deal X" → `opportunities` / `conversations` / `messages` calls OK.
 - "Why does SQL disagree with the audit?" → run `pipeline audit` and reconcile.
-- "Is the warehouse stale?" → freshness deep-dive (`MAX(_synced_at)` per table).
+- "Is the warehouse stale?" → `topline --agent query freshness` or a targeted `MAX(_synced_at)` SQL.
+- Non-standard analytics that `query audit` / `snapshot` / `freshness` cannot express → raw `query sql` is fine, but keep it inline (`--sql '...'`), not in a heredoc.
 
-If `query doctor`'s `recommendation` flags stale data or coverage gaps, disclose it in the answer but do **not** auto-fallback to REST. Coverage gaps are bugs to fix in `os-mcp`, not workarounds for the agent.
+If `query doctor` or the audit payload's `freshness` rows flag stale data or coverage gaps, disclose it in the answer but do **not** auto-fallback to REST. Coverage gaps are bugs to fix in `os-mcp`, not workarounds for the agent.
 
-## Hosted warehouse SQL (preferred for analytics)
+## Composite warehouse commands (preferred for analytics)
 
 ```bash
 topline --agent query doctor
-topline --agent query schema     # only when doctor flags schema not cached or stale
+topline --agent query audit --pipeline PIPELINE_ID --since this-week-et --status open
+topline --agent query snapshot --pipeline PIPELINE_ID --status open
+topline --agent query freshness
+```
+
+Answer from `query audit` JSON directly:
+
+- `snapshot.rows` → open count/value and stage distribution.
+- `activity.rows` → `unique_touches` by channel/direction.
+- `deals.rows` → per-deal touch breakdowns.
+- `movement.rows` → stage/status/record movement.
+- `freshness.rows` → data freshness caveats.
+
+Keep activity and movement separate.
+
+`TOPLINE_QUERY_TOKEN` must be a connection-bound token from `https://os-mcp.topline.com/connect`; raw PITs are intentionally rejected for SQL. Never print query tokens.
+
+## Raw SQL (non-standard analytics only)
+
+```bash
 topline --agent query explain --tables opportunities,pipeline_stages,messages,contacts,call_events,appointments
 topline --agent query sql --sql 'SELECT status, COUNT(*) AS n FROM opportunities GROUP BY status ORDER BY n DESC'
 ```
 
-`TOPLINE_QUERY_TOKEN` must be a connection-bound token from `https://os-mcp.topline.com/connect`; raw PITs are intentionally rejected for SQL. Never print query tokens.
+Use raw SQL only for analytics the composite commands cannot express. Keep it inline; do not assemble multi-line SQL in a bash heredoc.
 
 ## Pipeline audit (diagnostic / one-off only — NOT the analytics default)
 
@@ -56,7 +77,7 @@ Useful switches:
 - `--conversation-limit 10` and `--message-limit 30` to tune lookup volume.
 - `--include-tasks false` to skip overdue task hygiene.
 
-Do **not** run this after a successful SQL audit "to verify" — cross-verification is a drilldown subroutine, not the default.
+Do **not** run this after a successful `query audit` "to verify" — cross-verification is a drilldown subroutine, not the default.
 
 ## Setup and supporting commands