Prepare for tinycloud 0.3.17: structured queries — the query verb (skill floor → 0.3.17)

[kdr]

What

Teaches the agent skills the new query verb shipping in tinycloud 0.3.17 (built from the private source repo; SDK 0.7.23): analytical read-only SQL — or a natural-language question compiled to SQL server-side — over a collection's structured data. Where probe/ask FIND content semantically, query MEASURES it: counts, group-bys, joins, and aggregates over file attributes, user metadata, connector source_metadata, and extracted entities, via three per-request virtual tables (files / entities / segment_entities).

Surfaces updated

• skills/tinycloud/SKILL.md — cheat-sheet block ("MEASURE things": schema-first flow, NL vs --sql, exports), cloud-verb billing line, collections section (query reads any type), and a gotcha: when to reach for query over probe/ask, the latest-extraction-only caveat, metadata collections having no extraction (query files.metadata/files.source_metadata), --max-rows/data.truncated → --export, and what bills vs what's free.
• reference/verbs.md — verb-table row + a full ### query section: virtual-table schema, join rule (USING (file_id, collection_id), LEFT JOIN), schema-first guidance, exactly-one-of question/--sql, dry-run, export lifecycle (--background → query show → -o download, 24h link), run store (list/show/cancel), billing + server limits; shared cache-flags note now includes query.
• reference/glossary.md — "Structured query" and "Virtual tables" entries.
• reference/pipelines.md — entities-collection analytics example; cache-flags note.
• README.md — commands-table row, example invocation, collections paragraph.
• CLAUDE.md — 0.3.17 entry in the version history (verbs 16→17, features 40→42).
• tinycloud-skill.json + preflight.sh — floor → 0.3.17, query.v1 + query.export.v1 added to required features (CI-diffed pair kept in sync; skill_version bumped).

Verification

• npm test — full offline unit + e2e suite passes.
• shellcheck clean on install.sh, smoke-test.sh, preflight.sh.
• Metadata-sync check (preflight REQUIRED_FEATURES / MIN_VERSION / MAX_VERSION_EXCLUSIVE vs tinycloud-skill.json) passes.
• claude plugin validate . passes.
• Skill claims grounded against a 0.3.17 dev build run live against the deployed query API (schema introspection, sync SQL with real rows, NL dry-run returning compiled SQL, run store list/show).

⚠️ Merge gate (same as the 0.3.12–0.3.16 floor raises)

This PR raises the skill floor to 0.3.17, so it must merge only after the live CDN serves channels.stable = 0.3.17 (otherwise every preflight fails with exit 11). Hold until the 0.3.17 release lands on the CDN.

---

Note

Low Risk
Documentation and version-metadata only; no runtime code changes. Main operational risk is merging before the 0.3.17 CDN release, which would break skill preflight for users still on 0.3.16.

Overview
Prepares the 0.3.17 public dist and agent skills for the new query verb: read-only SQL or NL-compiled analytics over collections (files / entities / segment_entities), with schema / list / show / cancel and CSV/JSONL export flows documented across SKILL.md, verbs.md, glossary, pipelines, and README.

Compatibility gate:tinycloud-skill.json and preflight.sh raise min_version to 0.3.17 and require query.v1 + query.export.v1; plugin/marketplace and package.json versions match. Agents are steered to use query for count/group/join tasks vs probe/ask, with schema-first guidance and billing/export gotchas called out in the skill.

Merge only after CDN channels.stable = 0.3.17, or preflight will fail on older binaries.

^{Reviewed by Cursor Bugbot for commit 6e61442. Bugbot is set up for automated code reviews on this repo. Configure here.}