docs(skills): correct databases-run token claims (E2E-verified)

[eddietejeda]

Summary

Corrects the databases run token description in hotdata/SKILL.md. A follow-up to #186, prompted by end-to-end testing against the live API.

In #186 I changed this line to claim the minted credential is a database_api_token restricted to "create databases, run queries, and upload data," with workspace-level operations returning 403. E2E testing proved that wrong.

What the E2E test found

Decoding the JWT actually minted by databases run:

{
  "permissions": ["read", "write"],
  "source": "database_token",
  "workspaces": ["work…"],
  "database": "dbid…",
  "scope": "permission:read_write workspace:… database:…"
}

Running a full permission matrix with this token in isolation (empty config dir, token only) produced zero 403s — it can list databases/workspaces/connections/usage/queries/indexes/tables, create databases, create indexes, delete databases, and upload data.

The database_api_token + create/query/upload allow-list in sdk.rs/databases.rs refers to a different credential (a database-scoped API key), which I incorrectly conflated into this section. The original wording (source:"database_token", permissions:["read","write"]) was accurate.

Fix

Restore the accurate JWT-claims description (verified against the decoded live token) and add a note that the child picks up the token from HOTDATA_DATABASE_TOKEN.

Broader E2E validation (no other doc changes needed)

Ran the real CLI against api.hotdata.dev across every documented command and the full managed-database lifecycle — all behave as the skills document:

• Reads: auth status, workspaces/connections/databases/tables/indexes/embedding-providers/results/queries/jobs list, usage, context list, queries <id>, results <id>
• query execute (table/json/csv), query status exit codes 0/1/2 (3 on truncation is code/unit-test-backed; the live dataset didn't truncate)
• search bm25 (auto-infers --type/--column from a single index; returns score; scoped via catalog-qualified --table, no -d — matches docs)
• Lifecycle: databases create --table … --expires-at → databases load --file → query → databases tables list → indexes create (sorted + bm25) → search → databases run → cleanup

🤖 Generated with Claude Code

[claude]

Documentation correction verified against the code: database_session.rs:6 documents the minted JWT as carrying "workspace + database read/write scope," matching the corrected permissions:["read","write"] wording, and the codebase treats database_api_token as a distinct credential (databases.rs:1006-1011, auth.rs) — confirming the prior wording conflated two different tokens. The fix makes the docs accurate.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!