docs(skill): context API only for data model and workspace docs

Remove legacy local-path guidance. SKILL, WORKFLOWS, MODEL_BUILD, and
DATA_MODEL.template now treat DATAMODEL workspace context as authoritative;
./DATAMODEL.md is only a CLI push/pull surface.

Author: eddietejeda

skills/hotdata/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hotdata
-description: Use this skill when the user wants to run hotdata CLI commands, query the Hotdata API, list workspaces, list connections, create connections, list tables, manage datasets, execute SQL queries, inspect query run history, search tables, manage indexes, manage sandboxes, manage workspace context (data model, glossary, and other named Markdown in the context API), sync context with local files via pull/push, or interact with the hotdata service. Activate when the user says "run hotdata", "query hotdata", "list workspaces", "list connections", "create a connection", "list tables", "list datasets", "create a dataset", "upload a dataset", "execute a query", "search a table", "list indexes", "create an index", "list query runs", "list past queries", "query history", "list sandboxes", "create a sandbox", "run a sandbox", "workspace context", "pull context", "push context", "data model", or asks you to use the hotdata CLI.
+description: Use this skill when the user wants to run hotdata CLI commands, query the Hotdata API, list workspaces, list connections, create connections, list tables, manage datasets, execute SQL queries, inspect query run history, search tables, manage indexes, manage sandboxes, manage workspace context and the data model via the context API (`hotdata context`), or interact with the hotdata service. Activate when the user says "run hotdata", "query hotdata", "list workspaces", "list connections", "create a connection", "list tables", "list datasets", "create a dataset", "upload a dataset", "execute a query", "search a table", "list indexes", "create an index", "list query runs", "list past queries", "query history", "list sandboxes", "create a sandbox", "run a sandbox", "workspace context", "pull context", "push context", "data model", or asks you to use the hotdata CLI.
 version: 0.1.11
 ---
 
@@ -31,17 +31,19 @@ All commands that accept `--workspace-id` are optional. If omitted, the active w
 
 ## Workspace context (API)
 
-The workspace stores **named Markdown documents** through the Hotdata **context API** (`/v1/context`). The CLI maps each name to a file **`./<NAME>.md`** in the **current working directory** (only for `pull` / `push`; names follow SQL table–identifier rules: ASCII letters, digits, underscore; no dot in the API name; max 128 characters; SQL reserved words are not allowed as names).
+The workspace stores **named Markdown documents** only through the Hotdata **context API** (`/v1/context`). The **authoritative** copy always lives on the server under a **name** (stem) such as `DATAMODEL` or `GLOSSARY`.
 
-**Agents (Claude and similar): use the context API as the canonical store.** Do not assume a data model exists only on disk in the repo.
+The CLI command **`hotdata context push`** reads **`./<NAME>.md`** and **`pull`** writes that file in the **current working directory**—those files exist only as a **transport surface** for the API, not as a second source of truth. **`hotdata context show <name>`** prints Markdown to stdout so agents can read the model **without** any local file. Context names follow SQL table–identifier rules (ASCII letters, digits, underscore; no dot in the API name; max 128 characters; SQL reserved words are not allowed).
 
-1. **Before** planning queries, explaining schema, or making modeling decisions, load what the workspace already has: `hotdata context show DATAMODEL` (and `hotdata context list` to discover other stems such as `GLOSSARY`).
-2. **After** you materially change the data model (or glossary), persist it for the workspace: write or edit `./DATAMODEL.md` in the project directory where CLI commands run, then `hotdata context push DATAMODEL`. If there is no local file yet, create `./DATAMODEL.md` from the template or from `context show` output, then edit and push.
-3. **Optional:** `hotdata context pull DATAMODEL` refreshes `./DATAMODEL.md` from the server; use `--force` if the file already exists.
+**Agents (Claude and similar): treat workspace context as the only store for the data model and shared narrative docs.**
 
-The standard stem for the workspace semantic model is **`DATAMODEL`** (local sync file **`DATAMODEL.md`**). Use additional stems the same way (for example **`GLOSSARY`** ↔ **`GLOSSARY.md`**) for other long-lived narrative context.
+1. **Before** planning queries, explaining schema, or modeling, load the workspace: `hotdata context show DATAMODEL` (and `hotdata context list` for other stems such as `GLOSSARY`). Handle a missing context by starting from [references/DATA_MODEL.template.md](references/DATA_MODEL.template.md) and pushing when ready.
+2. **After** you change the model, persist it with **`hotdata context push DATAMODEL`**. The CLI requires a local `./DATAMODEL.md` for that step: write the body there (from `context show`, the template, or your edits), then run `push` from the project directory.
+3. Use **`hotdata context pull DATAMODEL`** when you intentionally want a local `./DATAMODEL.md` copy (for example a human editor); it still reflects API state, not a parallel document.
 
-Template and deep modeling procedure still apply to the **content** you store: [references/DATA_MODEL.template.md](references/DATA_MODEL.template.md), [references/MODEL_BUILD.md](references/MODEL_BUILD.md). Keep those documents **out of agent skill install paths**; the authoritative copy for the team should live in **workspace context** (and optionally a synced local file in the repo).
+The standard stem for the workspace semantic model is **`DATAMODEL`**. Add other stems the same way (e.g. **`GLOSSARY`**) for glossary or runbooks.
+
+Use [references/DATA_MODEL.template.md](references/DATA_MODEL.template.md) and [references/MODEL_BUILD.md](references/MODEL_BUILD.md) for **what to write inside** the Markdown you store in context. Never put workspace-specific model text inside agent skill install paths—only in **workspace context** (and transient `./<NAME>.md` for push/pull when needed).
 
 ## Multi-step workflows (Model, History, Chain, Indexes)
 
@@ -54,8 +56,6 @@ These are **patterns** built from the commands below—not separate CLI subcomma
 
 Full step-by-step procedures: [references/WORKFLOWS.md](references/WORKFLOWS.md).
 
-**Legacy / optional local paths:** Older docs may refer to `DATA_MODEL.md` under `docs/` or the project root. **Going forward, prefer workspace context** (`DATAMODEL` + `context show` / `push` / `pull`). If the user keeps a git-tracked file, treat it as a **synced copy**: `context pull` when starting, `context push` after edits.
-
 ## Available Commands
 
 ### List Workspaces
@@ -199,7 +199,7 @@ Use `hotdata datasets <dataset_id>` to look up the `table_name` before writing q
 
 ### Workspace context (named Markdown)
 
-Syncs workspace **context API** documents with **`./<NAME>.md`** in the current directory. See [Workspace context (API)](#workspace-context-api) for agent rules.
+Reads and writes workspace **context API** documents. **`show`** needs no local file; **`push`** / **`pull`** use **`./<NAME>.md`** in the current directory only as the CLI transport format. See [Workspace context (API)](#workspace-context-api).
 
 ```
 hotdata context list [-w <workspace_id>] [--prefix <stem>] [-o table|json|yaml]

skills/hotdata/references/DATA_MODEL.template.md

@@ -1,6 +1,6 @@
 # Data model — `<project name>`
 
-> Copy this file to your **project** directory (e.g. `./DATA_MODEL.md`, `./data_model.md`, or `./docs/DATA_MODEL.md`).  
+> **Storage:** This Markdown structure is kept in **workspace context** under the name **`DATAMODEL`**. Use `hotdata context show DATAMODEL` to read it; maintain `./DATAMODEL.md` in your **project directory** (where you run `hotdata`) only when editing, then `hotdata context push DATAMODEL`. Do not use `docs/DATA_MODEL.md` or other repo paths as the source of truth.  
 > Do not commit workspace-specific content into agent skill folders.  
 > For a **full** build (per-table detail, connector enrichment, index summary), follow [MODEL_BUILD.md](MODEL_BUILD.md) from the installed skill’s `references/` (or this repo’s `skills/hotdata/references/`). Relative links to `MODEL_BUILD.md` below work only while this file lives next to those references; in your project, open that path separately if the link 404s.
 

skills/hotdata/references/MODEL_BUILD.md

@@ -1,8 +1,8 @@
 # Building a workspace data model (advanced)
 
-Optional **deep pass** for a single authoritative markdown model. For a short checklist only, use the **Model** section in [WORKFLOWS.md](WORKFLOWS.md) and [DATA_MODEL.template.md](DATA_MODEL.template.md).
+Optional **deep pass** for a single authoritative markdown model stored in **workspace context**. For a short checklist only, use the **Model** section in [WORKFLOWS.md](WORKFLOWS.md) and [DATA_MODEL.template.md](DATA_MODEL.template.md).
 
-**Output:** Save as `DATA_MODEL.md`, `data_model.md`, or `docs/DATA_MODEL.md` in the **project directory** where you run `hotdata` (not inside agent skill folders).
+**Output:** The live document is **`DATAMODEL`** in the context API. Maintain it with `hotdata context show DATAMODEL`, edit `./DATAMODEL.md` in the **project directory** where you run `hotdata`, then **`hotdata context push DATAMODEL`**. Do not use `docs/`, `DATA_MODEL.md`, or other repo-only paths as the system of record. Never store workspace-specific model text inside agent skill folders.
 
 ---
 
@@ -95,7 +95,7 @@ When suggesting a new index, use the same connection/schema/table/column names a
 
 ## 6. Document structure
 
-Start from [DATA_MODEL.template.md](DATA_MODEL.template.md) and extend as needed:
+This Markdown body is what you store under **`DATAMODEL`** (`hotdata context push DATAMODEL`). Start from [DATA_MODEL.template.md](DATA_MODEL.template.md) and extend as needed:
 
 - **Overview** — Domains and what the workspace is for.
 - **Per connection** — Optional subsection per source; for **deep** models, **repeat** one block per `connection.schema.table` (grain, column table with name/type/nullable/PK-FK/notes, relationships, queryability, caveats)—the template’s single `####` heading is a pattern to copy for each table.

skills/hotdata/references/WORKFLOWS.md

@@ -2,14 +2,14 @@
 
 Procedures for **Model**, **History**, **Chain**, and **Indexes**. These compose existing `hotdata` commands; they are not separate subcommands.
 
-## Where files live
+## Where things live
 
 | Concept | Location |
 |--------|----------|
-| **Model** | Your **project** root or `docs/` (e.g. `DATA_MODEL.md` / `data_model.md`). Never store workspace-specific model text inside agent skill directories. |
+| **Model** | **Workspace context API** — stem **`DATAMODEL`** (`hotdata context show DATAMODEL`, `context push` / `pull` with `./DATAMODEL.md` in the project cwd only as the CLI file surface). Never store workspace-specific model text inside agent skill directories. |
 | **History** | `hotdata queries list` / `queries <query_run_id>` for query runs (execution history); `hotdata results list` / `results <id>` for row data. |
-| **Chain** | Intermediate tables in **`datasets.main.*`**; document stable ones in the Model file under **Derived tables (Chain)**. |
-| **Indexes** | Recommendations and decisions live in Hotdata (`indexes list` / `indexes create`). Optional project log (e.g. `INDEXES.md`) if you track rationale outside the catalog. |
+| **Chain** | Intermediate tables in **`datasets.main.*`**; document stable chains in **workspace context `DATAMODEL`** under **Derived tables (Chain)**. |
+| **Indexes** | Recommendations and live objects in Hotdata (`indexes list` / `indexes create`). Record rationale in **`DATAMODEL`** (e.g. Search & index summary) or a dedicated context stem if you split concerns. |
 
 ---
 
@@ -19,8 +19,9 @@ Procedures for **Model**, **History**, **Chain**, and **Indexes**. These compose
 
 ### Initialize
 
-1. Copy `references/DATA_MODEL.template.md` from this skill bundle to your project as `DATA_MODEL.md` or `docs/DATA_MODEL.md`.
-2. Fill workspace-specific sections as you discover schema.
+1. Use [DATA_MODEL.template.md](DATA_MODEL.template.md) in this skill bundle as the **structure** for what you store in workspace context.
+2. In the **project directory** where you run `hotdata`, create or refresh `./DATAMODEL.md` (from the template, from `hotdata context show DATAMODEL`, or from `hotdata context pull DATAMODEL`), fill workspace-specific sections as you discover schema, then **`hotdata context push DATAMODEL`** so the workspace owns the document.
+3. Agents that skip local files: `hotdata context show DATAMODEL` to read; when updating, write `./DATAMODEL.md` then `hotdata context push DATAMODEL`.
 
 ### Deep model pass (optional)
 
@@ -41,7 +42,7 @@ hotdata datasets list
 hotdata datasets <dataset_id>                # schema detail per dataset
 ```
 
-Use output to update **Connections**, **Tables**, **Columns**, and **Datasets** in the model. Optional: small exploratory queries once names are known:
+Use output to update **Connections**, **Tables**, **Columns**, and **Datasets** in **workspace context `DATAMODEL`** (edit via `./DATAMODEL.md` + `hotdata context push DATAMODEL`, or your editor workflow). Optional: small exploratory queries once names are known:
 
 ```bash
 hotdata query "SELECT * FROM <connection>.<schema>.<table> LIMIT 5"
@@ -107,7 +108,7 @@ Query footers include a `result-id` when applicable—record it for later, or pi
    hotdata query "SELECT * FROM datasets.main.<table_name> WHERE ..."
    ```
 
-**Naming:** Prefer predictable `--table-name` values, e.g. `chain_<topic>_<YYYYMMDD>`, and list long-lived chains in **Model → Derived tables (Chain)**.
+**Naming:** Prefer predictable `--table-name` values, e.g. `chain_<topic>_<YYYYMMDD>`, and list long-lived chains in **DATAMODEL → Derived tables (Chain)** in workspace context.
 
 ---
 
@@ -164,7 +165,7 @@ Large builds: add `--async` and track with **`hotdata jobs list`** / **`hotdata
 
 ### 4. Verify
 
-Re-run representative **`hotdata query`** or **`hotdata search`** workloads. Update **Model → Search & index summary** (if you maintain a data model doc) so future agents know what exists.
+Re-run representative **`hotdata query`** or **`hotdata search`** workloads. Update **DATAMODEL → Search & index summary** in workspace context (`hotdata context push DATAMODEL` after editing `./DATAMODEL.md`) so future agents see what exists.
 
 ### Guardrails