diff --git a/.claude/skills/update-docs/SKILL.md b/.claude/skills/update-docs/SKILL.md
new file mode 100644
index 0000000..529efdf
--- /dev/null
+++ b/.claude/skills/update-docs/SKILL.md
@@ -0,0 +1,157 @@
+---
+name: update-docs
+description: "Update mcli's documentation to match the code: the generated skill doc, README, examples, ADRs, and memory-bank plans. Use after any change that adds, renames, or removes a command, flag, error code, or output shape."
+allowed-tools: default
+---
+
+# Skill: UPDATE-DOCS (mcli)
+
+Bring mcli's documentation back in line with the code. Invoke after a change that
+is user-visible, or standalone with `/update-docs`.
+
+mcli is consumed primarily by LLM agents, not humans reading a wiki. A stale doc
+is not cosmetic debt here — it actively makes agents emit wrong commands. Treat
+documentation drift as a bug.
+
+## The doc surfaces (in priority order)
+
+### 1. `internal/cli/skill.md` — the skill doc (highest priority)
+
+Plain markdown, embedded into the binary by `internal/cli/skill.go`. It is what
+`mcli skill` / `mcli describe` prints, and the primary contract for LLM callers.
+It MUST be updated when a change touches:
+
+- a command or subcommand (added, renamed, removed)
+- a flag that appears in the doc's usage lines
+- an error code or its exit code (see `internal/errs/errs.go`)
+- an output shape, output mode, or column-value write shape
+
+Organise it by what an agent does, in frequency order — discover IDs, read, write,
+recover from an error — not by the shape of the command tree. Board setup is rare;
+writing items is not. Document the flags whose *absence* produces a misleading error
+(`board create --workspace`, `board column create --defaults`) even when `--help`
+calls them optional, and keep the "Failures Worth Knowing About In Advance" section
+current: it is the highest-value section in the doc.
+
+Guards that will fail CI if you forget:
+
+- `TestSkillDoc_MatchesCommandTree` — every command path and flag the doc shows is
+  resolved against the real cobra tree. This is the guard that did not exist when
+  the doc drifted; `TestSkillDoc_AuditCatchesDrift` proves it can still fail.
+- `TestSkill_ErrorCodesMatchErrs` — every code in `errs.AllCodes()` must appear in
+  the doc annotated with the exit code `errs.ToExitCode` really returns.
+- `TestSkill_ContainsGoals` / `TestSkill_ContainsSections` — required commands and
+  section headings.
+- `TestSkill_Concise` — a byte budget (`skillDocMaxBytes`), because bytes are what
+  the doc costs an agent's context. If you are near it, cut or tighten an existing
+  section rather than raising the cap.
+
+Run `go test ./internal/cli/ -run TestSkill` after editing.
+
+### 2. `README.md`
+
+Human-facing entry point. Update the command reference and any example output
+when commands change. Keep it consistent with the skill doc — they should never
+disagree about a flag name.
+
+### 3. `examples/`
+
+JSON request/response examples (`item-create.json`, `board-get.json`, …) and the
+end-to-end demos (`ecommerce-demo.md` / `.sh`). If an output shape or column-value
+encoding changed, these become wrong and misleading. Verify affected examples still
+reflect real output.
+
+### 4. `memory-bank/adrs/` — validate, do not rewrite
+
+ADR-001 (stack), ADR-002 (CLI grammar / exit codes), ADR-003 (LLM skill API),
+ADR-004 (secret storage). ADRs record decisions as of a date; they are **not**
+auto-updated. If a change contradicts an ADR, flag it for human review — either the
+change is wrong or the ADR needs a superseding entry. Never silently edit an ADR to
+match new code.
+
+### 5. `memory-bank/` plans and docs
+
+See the hygiene rules below — this repo has a specific convention.
+
+## Plan hygiene rules (mcli-specific)
+
+The committed part of `memory-bank/` describes **shipped reality**. It is not a
+roadmap and not a scratchpad. Concretely:
+
+- **Committed docs must not contain speculative or unstarted plans.** Aspirational
+  plan docs rot into lies: readers cannot tell "not_started" from "done but never
+  re-marked", which is exactly the failure this repo already hit.
+- **Future / in-design work goes in `memory-bank/private/plans/`**, which is
+  gitignored (`memory-bank/private/`). Design docs awaiting approval live there.
+- **When a plan fully ships, delete it** rather than leaving a COMPLETED doc behind.
+  Git history preserves it, and the code plus ADRs are the durable record.
+- **Never trust a `Status:` marker.** Verify against the codebase before acting on
+  or reporting any plan's status.
+
+`memory-bank/axioms.md` and `memory-bank/projectbrief.md` are durable — update them
+only when a project-level invariant or goal genuinely changes.
+
+## Out of scope for this repo
+
+- `schema/monday.graphql` is vendored, not documentation. Refresh it with
+  `make schema` (runs `tools/introspect` against the live API), not by hand.
+- `.claude/` is gitignored except for this skill; do not add docs there expecting
+  them to be committed.
+
+## Core workflow
+
+### Step 1: Establish the diff
+
+```bash
+git diff HEAD --name-only          # default: uncommitted
+git diff HEAD --stat
+```
+
+With `--since-push`:
+
+```bash
+git diff origin/$(git branch --show-current) --name-only
+```
+
+### Step 2: Map code changes to doc surfaces
+
+For each changed file, ask which surfaces above it invalidates. The common cases:
+
+| Changed | Update |
+|---|---|
+| `internal/cli/*.go` (command/flag) | skill doc, README, examples |
+| `internal/errs/errs.go` | skill doc error codes (test enforces) |
+| output/formatting code | skill doc output shapes, examples, README |
+| `internal/api/**` behaviour | examples, possibly ADR-003 validation |
+
+### Step 3: Apply or propose
+
+With edit permission, make the changes and run the guard tests. Without it, present
+a diff and wait for approval.
+
+### Step 4: Report
+
+```markdown
+## Documentation Update Summary
+
+### Applied
+- ✅ `internal/cli/skill.go`: added `mcli item batch`, updated error-code line
+- ✅ `README.md`: command reference row for `item batch`
+- ✅ `examples/item-create.json`: refreshed to current output shape
+
+### Verified clean
+- `memory-bank/axioms.md` — no invariant changed
+
+### Flagged for human review
+- ⚠️ Change alters exit code for API errors — contradicts ADR-002, needs a
+  superseding ADR or a revert
+
+### Tests
+- `go test ./internal/cli/ -run TestSkill` — pass
+```
+
+## Exit conditions
+
+- Every invalidated surface is updated or explicitly reported as needing review
+- Guard tests pass (`go test ./internal/cli/ -run TestSkill`)
+- No committed doc describes unshipped work
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 75ead53..e276c30 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -2,7 +2,7 @@ name: CI
 
 on:
   push:
-    branches: [main]
+    branches: [master]
   pull_request:
 
 jobs:
diff --git a/.gitignore b/.gitignore
index af25bc8..a686333 100644
--- a/.gitignore
+++ b/.gitignore
@@ -23,7 +23,11 @@ vendor/
 # Private memory-bank area (per setup-memory-bank convention)
 memory-bank/private/
 
-# Symlinks to external tooling (not part of this repo)
-.claude/
+# Symlinks to external tooling (not part of this repo).
+# Exception: .claude/skills/update-docs is a real, repo-specific skill we ship.
+.claude/*
+!.claude/skills/
+.claude/skills/*
+!.claude/skills/update-docs/
 CLAUDE.md
 AGENTS.md
diff --git a/README.md b/README.md
index 57d0b2d..9b5524d 100644
--- a/README.md
+++ b/README.md
@@ -35,11 +35,19 @@ mcli item list --board 9832181507 --subitems
 # Get a single item, including its subitems with column values
 mcli item get 1234567890 --subitems
 
-# Create an item with column values
+# Create an item with typed column shorthands
+mcli item create --board 9832181507 --name "Ship feature" \
+  --status "Working on it" --due 2026-06-01
+
+# Or with raw column JSON, for any column type
 mcli item create --board 9832181507 --name "Ship feature" \
   --col 'status={"label":"Working on it"}' \
   --col 'due_date={"date":"2026-06-01"}'
 
+# Create or update many items in one command (rate-limit friendly)
+echo '[{"name":"Ship v1","status":"Done"},{"name":"Write docs","due":"2026-06-10"}]' \
+  | mcli item create --board 9832181507 -
+
 # Run a raw GraphQL query
 mcli query 'query { me { id name } }'
 ```
@@ -88,6 +96,9 @@ mcli board group list/create/rename/archive/delete
 mcli board column list/create/rename/describe/delete
 
 mcli item list/get/create/update/move/archive/delete
+mcli item create/update ... --status/--due/--date/--number/--text/--checkbox
+                                                            Typed column shorthands
+mcli item create/update --board <id> -                      Batch write, rows on stdin
 mcli item find --board <id> --column <col> --value <text>   Find by column value
 mcli item post-update <id> --body <text>                    Post a comment
 mcli item get-updates <id> [--limit N]                      Read comments/updates
@@ -100,6 +111,9 @@ mcli api list [--type query|mutation]        Browse all ~250 API operations from
 mcli api describe <operation|type>          Inspect signature and argument types
 mcli api <operation> [--arg k=v]...         Execute any operation; JSON args auto-coerced
 
+mcli schema status                   Report which schema is in use and how old it is
+mcli schema refresh                  Fetch the live schema with your token and cache it
+
 mcli query '<graphql>'               Raw GraphQL queries (inline, -f file, -f -)
 mcli query save/list/run/delete      Saved query management
 
@@ -178,6 +192,24 @@ mcli config set routing-key <your-key>   # add baggage: routingKey=<your-key> he
 mcli config set routing-key ""           # clear routing key
 ```
 
+### Keeping the schema fresh
+
+The embedded schema is a snapshot taken when the binary was built, so a long-lived
+install gradually falls behind the live API. `mcli schema refresh` introspects the API
+with your own token and caches the result in `~/.config/mcli/schema.graphql`, which takes
+precedence over the embedded copy — no rebuild, no release wait.
+
+```sh
+mcli schema status                        # source, api-version, age, type count
+mcli schema refresh                       # fetch + cache; prints the type delta
+mcli schema refresh --api-version 2026-08 # one-off fetch, not persisted to config
+```
+
+`mcli api` warns on stderr (never stdout) when the schema in use is more than 30 days
+old. Refreshing is always explicit: no mcli command fetches a schema behind your back.
+To drop the cache and go back to the embedded schema, delete the cached file or run
+`mcli config set api-version default`.
+
 ## Output Modes
 
 Control output format with a global flag or persist a default:
@@ -211,7 +243,7 @@ mcli daemon start --url https://your-server.example.com
 ```
 
 The daemon:
-- Listens for webhook payloads on an HTTP port (default 6780)
+- Listens for webhook payloads on an HTTP port (default 8420)
 - Exposes a Unix socket IPC for CLI commands
 - Opens a Cloudflare Quick Tunnel for a public URL (requires `cloudflared` in PATH)
 - Re-registers webhooks automatically when the tunnel URL changes
@@ -266,20 +298,113 @@ This outputs a concise goal-oriented guide that tells the LLM what commands exis
 
 On **read**, column values are decoded to human-readable form (status labels, ISO dates, etc.).
 
-On **write**, pass monday's raw column-value JSON via `--col <id>=<json>`:
+On **write** there are two paths: typed shorthands for the common types, and raw
+`--col <id>=<json>` for everything else.
+
+### Typed shorthands
+
+| Flag | Column type | Accepts |
+|------|-------------|---------|
+| `--status <label>` | `status` | a label configured on the column, matched case-insensitively |
+| `--date` / `--due` | `date` | `2026-05-10`, `2026-05-10T14:30`, or an RFC3339 timestamp (converted to UTC) |
+| `--number <n>` | `numbers` | any number; empty string clears the column |
+| `--text <s>` | `text` | any string; empty string clears the column |
+| `--checkbox <b>` | `checkbox` | `true`/`false`, `yes`/`no`, `1`/`0` |
+
+```sh
+mcli item create --board 123 --name "Task" --status Done --due 2026-05-10 --number 3
+mcli item update 456 --board 123 --status "Working on it"
+```
+
+A shorthand carries no column id: it addresses **the board's single column of that
+type**, looked up live. That is a deliberate trade:
+
+- If the board has no column of the type, or more than one, the shorthand errors and
+  names the candidates. It never picks one for you — writing a correct value to the
+  wrong column is a silent, expensive mistake.
+- Values are validated before anything is sent. This matters most for `--status`: every
+  mcli item mutation sends `create_labels_if_missing`, so an unvalidated typo would
+  quietly add a new label to the board instead of failing. A bad label is rejected with
+  the column's real labels listed.
+- Using a shorthand costs one extra request (the board's column list) per command — or
+  per *batch*, not per row.
+- `--date` and `--due` are the same flag; passing both is an error.
+
+Shorthands are not available with `--parent` (a subitem lives on its own board, which
+would need a second lookup) — use `--col` there.
+
+### Raw column JSON
+
+`--col <id>=<json>` writes any column, including types with no shorthand:
 
 ```sh
 mcli item create --board 123 --name "Task" \
   --col 'status={"label":"Done"}' \
   --col 'date={"date":"2026-05-10"}' \
-  --col 'priority={"label":"High"}'
+  --col 'people={"personsAndTeams":[{"id":123,"kind":"person"}]}'
 ```
 
+Repeated `--col` flags are order-preserving; if the same column id appears twice the
+last value wins. A shorthand and a `--col` that target the same column is an error, not
+a precedence rule.
+
 Use `mcli board column list --board <id>` to discover column IDs, types, and settings.
 
-### Fetching nested data in one call
+## Batch Writes
 
-To save round-trips, several read commands can pull related records with their decoded column values in a single request:
+`mcli item create --board <id> -` and `mcli item update --board <id> -` read rows from
+stdin instead of flags — a JSON array or one JSON object per line (NDJSON), up to 500
+rows. Create rows need `name`; update rows need `id`. Both accept `group`, `cols`, and
+the same typed shorthands as flags.
+
+```sh
+# JSON array
+echo '[{"name":"Ship v1","status":"Done","due":"2026-05-10"},
+       {"name":"Write docs","number":3,"cols":{"text_9":"draft"}}]' \
+  | mcli item create --board 123 -
+
+# NDJSON, e.g. straight out of jq
+mcli item list --board 999 | jq -c '.items[] | {id, status:"Done"}' \
+  | mcli item update --board 123 -
+```
+
+Row fields are JSON scalars, so `"number": 42` and `"number": "42"` both work.
+
+**Validation happens up front.** Every row is parsed, checked, and encoded before the
+first request fires, so a bad status label in row 40 fails the whole batch with `USAGE`
+and nothing is written. Unknown row fields are rejected too — a mistyped `"columns"`
+instead of `"cols"` would otherwise drop the row's values and report success.
+
+**Rows are sent sequentially.** monday's rate limit is a complexity budget per minute,
+so parallelism would not raise throughput, only reach the ceiling sooner.
+
+Output is a single JSON object:
+
+```json
+{
+  "written": 2,
+  "failed": 1,
+  "verb": "created",
+  "items": [ ... ],
+  "errors": [{"index": 1, "code": "API", "message": "column not found"}]
+}
+```
+
+**On partial failure the exit code is 2 and you should retry only the rows named in
+`errors[].index`.** Item creation has no dedupe key, so re-sending the whole payload
+duplicates every row that succeeded.
+
+`--dry-run` prints the exact `column_values` that would be sent for each row without
+writing anything. It works on single-item create/update too, and needs no API access at
+all unless a shorthand has to be resolved:
+
+```sh
+echo '{"name":"Check me","status":"Done"}' | mcli item create --board 123 - --dry-run
+```
+
+## Fetching nested data in one call
+
+Batch writes save round-trips on the write path; on the read path, several commands can pull related records with their decoded column values in a single request:
 
 | Command | Flag | Adds |
 |---------|------|------|
@@ -341,7 +466,18 @@ mcli mutation run update_order_status --var board=456 --var item=789 \
   --var cols='{"status":{"label":"Ordered"}}'
 ```
 
-See [`examples/ecommerce-demo.md`](examples/ecommerce-demo.md) for a full walkthrough and [`examples/ecommerce-demo.sh`](examples/ecommerce-demo.sh) for a runnable script that sets up Products, Inventory, and Orders boards with a complete semantic layer.
+Each domain below has a full walkthrough (`.md`) and a runnable script (`.sh`) that
+creates the boards, defines a semantic layer, and exercises the workflow end to end:
+
+| Domain | Boards | Walkthrough |
+|---|---|---|
+| E-commerce | Products, Inventory, Orders | [`examples/ecommerce-demo.md`](examples/ecommerce-demo.md) · [`.sh`](examples/ecommerce-demo.sh) |
+| CRM | Companies, Contacts, Deals | [`examples/crm-demo.md`](examples/crm-demo.md) · [`.sh`](examples/crm-demo.sh) |
+| Project portfolio | Portfolios, Projects, Milestones | [`examples/portfolio-demo.md`](examples/portfolio-demo.md) · [`.sh`](examples/portfolio-demo.sh) |
+
+They also exercise the write ergonomics against real board shapes: the e-commerce demo
+seeds inventory with one batch write, and the portfolio demo shows the case a shorthand
+*cannot* serve — a board with two `date` columns, where `--col` takes over.
 
 ## Development
 
@@ -354,6 +490,21 @@ make fmt-check     # Check formatting
 make schema        # Refresh monday.com GraphQL schema (requires token)
 ```
 
+`make schema` rewrites `schema/monday.graphql` and stamps `schema/fetched_at.txt` with
+today's date. That stamp is what `mcli schema status` reports as the embedded schema's
+age, so never edit either file by hand.
+
+### Before cutting a release
+
+```sh
+make schema          # refresh the embedded schema + provenance stamp
+go generate ./...    # regenerate genqlient code against the new schema
+make test lint vet   # must be green
+```
+
+Shipping a release without refreshing means every user starts out with a schema as old
+as the last refresh, and sees the staleness warning sooner.
+
 ### Running against staging
 
 ```sh
diff --git a/examples/crm-demo.md b/examples/crm-demo.md
new file mode 100644
index 0000000..c6385d8
--- /dev/null
+++ b/examples/crm-demo.md
@@ -0,0 +1,257 @@
+# CRM Demo: Companies, Contacts & Deals
+
+This demo shows how an LLM agent (or human) can use mcli's generic commands to:
+
+1. **Create boards** with typed columns and pipeline groups
+2. **Define a semantic layer** of saved queries/mutations with business-domain names
+3. **Seed accounts and contacts** using the structured item commands
+4. **Run a deal through the pipeline** using only the semantic layer (no board IDs in the "business logic")
+5. **Query the pipeline** — by account, by stage, with activity subitems
+
+## Prerequisites
+
+- `mcli auth login` (or `MONDAY_API_TOKEN` set)
+- `jq` in PATH
+
+Run the full demo: `./examples/crm-demo.sh`
+
+---
+
+## Phase 1: Create Boards
+
+```sh
+mcli board create --name "Companies" --kind public --empty   # → {"id":"..."}
+mcli board create --name "Contacts"  --kind public --empty
+mcli board create --name "Deals"     --kind public --empty
+```
+
+Each board starts empty (no default columns/items).
+
+The Deals board also gets two groups so the pipeline has a physical shape —
+open deals live in one group, closed deals in another:
+
+```sh
+mcli board group create --board $DEALS_BOARD --name "Open Pipeline"
+mcli board group create --board $DEALS_BOARD --name "Closed"
+```
+
+## Phase 2: Define Columns
+
+**Companies** — item name is the company name:
+
+```sh
+mcli board column create --board $COMPANIES_BOARD --title "Domain"  --type text
+mcli board column create --board $COMPANIES_BOARD --title "Website" --type link
+mcli board column create --board $COMPANIES_BOARD --title "Owner"   --type people
+mcli board column create --board $COMPANIES_BOARD --title "Segment" --type status \
+  --defaults '{"labels":{"0":"SMB","1":"Mid-Market","2":"Enterprise"}}'
+```
+
+**Contacts** — item name is the person's name; `Company` holds the account's
+domain, which is the join key back to the Companies board:
+
+```sh
+mcli board column create --board $CONTACTS_BOARD --title "Company" --type text
+mcli board column create --board $CONTACTS_BOARD --title "Title"   --type text
+mcli board column create --board $CONTACTS_BOARD --title "Email"   --type text
+mcli board column create --board $CONTACTS_BOARD --title "Owner"   --type people
+```
+
+**Deals** — item name is the deal name; subitems are pipeline activities:
+
+```sh
+mcli board column create --board $DEALS_BOARD --title "Company"        --type text
+mcli board column create --board $DEALS_BOARD --title "Value"          --type numbers
+mcli board column create --board $DEALS_BOARD --title "Expected Close" --type date
+mcli board column create --board $DEALS_BOARD --title "Owner"          --type people
+mcli board column create --board $DEALS_BOARD --title "Stage"          --type status \
+  --defaults '{"labels":{"0":"Discovery","1":"Qualified","2":"Proposal","3":"Negotiation","4":"Won","5":"Lost"}}'
+```
+
+Column descriptions make the board self-documenting for the next agent:
+
+```sh
+mcli board column describe --board $DEALS_BOARD --column $DEAL_COMPANY \
+  --text "Account domain — join key to the Companies board (Domain column)"
+```
+
+### A note on linking boards
+
+mcli can create a `board_relation` column (`--type board_relation`), but the
+link configuration (which boards are connected) is not modelled by the CLI, so
+this demo uses an explicit join key instead: every Contact and Deal stores the
+account **domain** in a text column, and `mcli item find` resolves it. Contacts
+and Deals therefore stay independent boards, while the *activity* relationship —
+which monday models natively — uses **subitems** under each deal.
+
+## Phase 3: Semantic Layer
+
+Saved queries and mutations give business-level names to operations. An LLM can
+call `mcli mutation run advance_deal_stage --var ...` without knowing GraphQL:
+
+### Queries
+
+| Name | Purpose |
+|------|---------|
+| `list_companies` | All accounts with column values |
+| `list_contacts` | All contacts with column values |
+| `list_pipeline` | Deals with their activity subitems |
+| `get_deal` | Single deal detail by item ID |
+
+```sh
+mcli query save list_pipeline --query \
+  'query($boardId: ID!) { boards(ids: [$boardId]) { items_page(limit:100) { items { id name column_values { id text value } subitems { id name } } } } }'
+```
+
+### Mutations
+
+| Name | Purpose |
+|------|---------|
+| `create_company` | Add an account |
+| `create_contact` | Add a contact against an account |
+| `create_deal` | Open a new deal (starts in Discovery) |
+| `advance_deal_stage` | Move a deal to the next stage |
+| `log_deal_activity` | Add an activity subitem to a deal |
+
+```sh
+mcli mutation save advance_deal_stage --query \
+  'mutation($board: ID!, $item: ID!, $cols: JSON!) { change_multiple_column_values(board_id: $board, item_id: $item, column_values: $cols) { id } }'
+```
+
+## Phase 4: Seed Accounts & Contacts
+
+Using the structured `item create` command (more ergonomic for setup). Domain is the
+Companies board's only `text` column and Segment its only `status` column, so `--text`
+and `--status` address them by type — no column ID, and `"Enterprise"` is checked
+against the board's own labels before anything is sent. Website (`link`) and Owner
+(`people`) have no shorthand, so they use monday's raw write shapes via `--col`:
+
+```sh
+ME_ID=$(mcli me | jq -r '.id')
+
+mcli item create --board $COMPANIES_BOARD --name "Acme Corp" \
+  --text "acme.com" \
+  --status "Enterprise" \
+  --col "$CO_WEBSITE"='{"url":"https://acme.com","text":"acme.com"}' \
+  --col "$CO_OWNER"="{\"personsAndTeams\":[{\"id\":$ME_ID,\"kind\":\"person\"}]}"
+```
+
+Shorthands and `--col` mix freely on one command. Where a shorthand does not apply,
+the raw shapes are: `status` → `{"label":"..."}`, `people` →
+`{"personsAndTeams":[...]}`, `numeric` → a quoted string.
+
+The Contacts board is the counter-example: it has three `text` columns (Company,
+Title, Email), so `--text` would be ambiguous and mcli refuses it, naming all three
+rather than guessing. Address those by ID — or by domain name through the semantic
+layer, which is what it is for.
+
+Or using the semantic layer:
+
+```sh
+mcli mutation run create_company \
+  --var board=$COMPANIES_BOARD \
+  --var name="Acme Corp" \
+  --var cols='{"domain":"acme.com","segment":{"label":"Enterprise"}}'
+```
+
+## Phase 5: Run a Deal Through the Pipeline
+
+This is where the semantic layer shines — the agent writes natural JSON in `--var`
+and mcli handles the encoding automatically. monday.com's `JSON` scalar expects a
+stringified JSON value on the wire, but mcli detects variables declared as `JSON`
+in the query and re-encodes them transparently. No double-escaping needed.
+
+```sh
+# 1. Open the deal in Discovery, in the "Open Pipeline" group
+mcli mutation run create_deal \
+  --var board=$DEALS_BOARD \
+  --var group=$GROUP_OPEN \
+  --var name="Acme — Platform rollout" \
+  --var cols='{"company":"acme.com","stage":{"label":"Discovery"},"value":"120000","expected_close":{"date":"2026-12-15"}}'
+
+# 2. Log activities as subitems
+mcli mutation run log_deal_activity --var parent=$DEAL_ID --var name="Discovery call with VP Eng" --var cols='{}'
+mcli mutation run log_deal_activity --var parent=$DEAL_ID --var name="Sent proposal v1"          --var cols='{}'
+
+# 3. Advance the stage (repeat per transition)
+mcli mutation run advance_deal_stage \
+  --var board=$DEALS_BOARD --var item=$DEAL_ID \
+  --var cols='{"stage":{"label":"Qualified"}}'
+```
+
+The same transition through the structured command, when you prefer flags over
+GraphQL — and a raised deal value on the way to Proposal. The Deals board has exactly
+one `status` and one `numbers` column, so the whole update reads in business terms
+with no column IDs and no wire JSON:
+
+```sh
+mcli item update $DEAL_ID --board $DEALS_BOARD \
+  --status "Proposal" \
+  --number 145000
+```
+
+Narrative belongs on the item itself, not in a column:
+
+```sh
+mcli item description $DEAL_ID --set "Multi-region rollout. Champion: VP Eng. Blocker: security review."
+mcli item post-update  $DEAL_ID --body "Stage → Negotiation. Legal reviewing MSA redlines."
+```
+
+When the deal closes, mark it Won and move it out of the open pipeline:
+
+```sh
+mcli item update $DEAL_ID --board $DEALS_BOARD --status "Won"
+mcli item move   $DEAL_ID --to-group $GROUP_CLOSED
+```
+
+## Phase 6: Query the Pipeline
+
+```sh
+# Everything on the account, resolved through the domain join key
+mcli item find --board $CONTACTS_BOARD --column $CT_COMPANY --value "acme.com"
+mcli item find --board $DEALS_BOARD    --column $DEAL_COMPANY --value "acme.com"
+
+# Deals in one stage — status columns match on their label text
+mcli item find --board $DEALS_BOARD --column $DEAL_STAGE --value "Won"
+
+# Open pipeline only (group-scoped), with activity subitems (--subitems is JSON-only)
+mcli item list --board $DEALS_BOARD --group $GROUP_OPEN --subitems --limit 100 --json
+
+# Full deal detail, subitem column values included
+mcli item get $DEAL_ID --subitems
+
+# Semantic layer read path
+mcli query run list_pipeline --var boardId=$DEALS_BOARD --pretty
+mcli query run get_deal --var itemId="[$DEAL_ID]" --pretty
+```
+
+`item find` returns the id/name/group triple plus a page cursor:
+
+```json
+{
+  "items": [
+    { "id": "7890123456", "name": "Acme — Platform rollout", "group": { "id": "topics", "title": "Closed" } }
+  ],
+  "cursor": ""
+}
+```
+
+Total open pipeline value, straight out of `item list` (column values arrive
+already decoded, so `jq` can sum them):
+
+```sh
+mcli item list --board $DEALS_BOARD --group $GROUP_OPEN --limit 100 \
+  | jq --arg col "$DEAL_VALUE" '[.items[].columns[] | select(.id == $col) | .value | tonumber] | add'
+```
+
+## Key Takeaways
+
+- **Generic commands** (`board create`, `board group create`, `board column create`, `item create`) handle setup
+- **Typed shorthands** (`--status`, `--text`, `--number`) drop column IDs and wire JSON where the board has one column of that type; validated before send, and they refuse rather than guess when it has several
+- **Saved queries/mutations** create a domain-specific CRM API layer
+- **A text join key** (the account domain) plus `mcli item find` links boards without needing `board_relation` link settings
+- **Subitems** model the natural one-to-many relationship (deal → activities)
+- **Groups** model pipeline state you want to *see*; the status column models the stage you want to *query*
+- **JSON coercion** — variables declared as `JSON` in the query are auto-stringified, so `--var cols='{"key":"val"}'` just works without double-encoding
+- **LLM agents** can operate entirely through `mcli mutation run <name>` / `mcli query run <name>` without understanding monday.com internals or wire-format quirks
+- The semantic layer is project-local (`.mcli/` directory) and version-controllable
diff --git a/examples/crm-demo.sh b/examples/crm-demo.sh
new file mode 100644
index 0000000..86908b0
--- /dev/null
+++ b/examples/crm-demo.sh
@@ -0,0 +1,286 @@
+#!/usr/bin/env bash
+# crm-demo: set up Companies/Contacts/Deals boards, define a semantic layer of
+# saved queries/mutations, seed accounts and contacts, then run a deal through
+# the pipeline and query it.
+set -euo pipefail
+
+MCLI="${MCLI:-mcli}"
+JQ="${JQ:-jq}"
+
+# The authenticated user is used as the owner for every people column.
+ME_ID=$($MCLI me | $JQ -r '.id')
+PERSON=$(printf '{"personsAndTeams":[{"id":%s,"kind":"person"}]}' "$ME_ID")
+
+# ─── Phase 1: Create Boards ─────────────────────────────────────────────────
+
+echo "=== Phase 1: Create boards ==="
+
+COMPANIES_BOARD=$($MCLI board create --name "Companies" --kind public --empty | $JQ -r '.id')
+echo "Companies board: $COMPANIES_BOARD"
+
+CONTACTS_BOARD=$($MCLI board create --name "Contacts" --kind public --empty | $JQ -r '.id')
+echo "Contacts board: $CONTACTS_BOARD"
+
+DEALS_BOARD=$($MCLI board create --name "Deals" --kind public --empty | $JQ -r '.id')
+echo "Deals board: $DEALS_BOARD"
+
+# Pipeline groups: open deals stay in one group, closed deals move to the other.
+GROUP_OPEN=$($MCLI board group create --board "$DEALS_BOARD" --name "Open Pipeline" | $JQ -r '.id')
+GROUP_CLOSED=$($MCLI board group create --board "$DEALS_BOARD" --name "Closed" | $JQ -r '.id')
+echo "Deals groups: open=$GROUP_OPEN, closed=$GROUP_CLOSED"
+
+# ─── Phase 2: Add Columns ───────────────────────────────────────────────────
+
+echo ""
+echo "=== Phase 2: Define columns ==="
+
+# The typed shorthands used below (--text, --status, --number) address the board's
+# single column of that type. A board created through the API starts with only a Name
+# column, so each board's shape is exactly what this script gives it. Note Contacts
+# gets three text columns on purpose — --text is ambiguous there and mcli refuses it,
+# naming the candidates, rather than picking one.
+
+# Companies: name (built-in), domain, website, owner, segment
+CO_DOMAIN=$($MCLI board column create --board "$COMPANIES_BOARD" --title "Domain" --type text | $JQ -r '.id')
+CO_WEBSITE=$($MCLI board column create --board "$COMPANIES_BOARD" --title "Website" --type link | $JQ -r '.id')
+CO_OWNER=$($MCLI board column create --board "$COMPANIES_BOARD" --title "Owner" --type people | $JQ -r '.id')
+CO_SEGMENT=$($MCLI board column create --board "$COMPANIES_BOARD" --title "Segment" --type status \
+  --defaults '{"labels":{"0":"SMB","1":"Mid-Market","2":"Enterprise"}}' | $JQ -r '.id')
+echo "Companies columns: Domain=$CO_DOMAIN, Website=$CO_WEBSITE, Owner=$CO_OWNER, Segment=$CO_SEGMENT"
+
+# Contacts: Company holds the account domain — the join key to Companies.
+CT_COMPANY=$($MCLI board column create --board "$CONTACTS_BOARD" --title "Company" --type text | $JQ -r '.id')
+CT_TITLE=$($MCLI board column create --board "$CONTACTS_BOARD" --title "Title" --type text | $JQ -r '.id')
+CT_EMAIL=$($MCLI board column create --board "$CONTACTS_BOARD" --title "Email" --type text | $JQ -r '.id')
+CT_OWNER=$($MCLI board column create --board "$CONTACTS_BOARD" --title "Owner" --type people | $JQ -r '.id')
+echo "Contacts columns: Company=$CT_COMPANY, Title=$CT_TITLE, Email=$CT_EMAIL, Owner=$CT_OWNER"
+
+# Deals: company (join key), value, expected close, owner, stage
+DEAL_COMPANY=$($MCLI board column create --board "$DEALS_BOARD" --title "Company" --type text | $JQ -r '.id')
+DEAL_VALUE=$($MCLI board column create --board "$DEALS_BOARD" --title "Value" --type numbers | $JQ -r '.id')
+DEAL_CLOSE=$($MCLI board column create --board "$DEALS_BOARD" --title "Expected Close" --type date | $JQ -r '.id')
+DEAL_OWNER=$($MCLI board column create --board "$DEALS_BOARD" --title "Owner" --type people | $JQ -r '.id')
+DEAL_STAGE=$($MCLI board column create --board "$DEALS_BOARD" --title "Stage" --type status \
+  --defaults '{"labels":{"0":"Discovery","1":"Qualified","2":"Proposal","3":"Negotiation","4":"Won","5":"Lost"}}' | $JQ -r '.id')
+echo "Deals columns: Company=$DEAL_COMPANY, Value=$DEAL_VALUE, Close=$DEAL_CLOSE, Owner=$DEAL_OWNER, Stage=$DEAL_STAGE"
+
+# Self-documenting boards: describe the non-obvious column.
+$MCLI board column describe --board "$DEALS_BOARD" --column "$DEAL_COMPANY" \
+  --text "Account domain — join key to the Companies board (Domain column)" > /dev/null
+$MCLI board column describe --board "$CONTACTS_BOARD" --column "$CT_COMPANY" \
+  --text "Account domain — join key to the Companies board (Domain column)" > /dev/null
+echo "Described the join-key columns"
+
+# Note: mcli can create a board_relation column (--type board_relation), but the
+# board-link settings are not modelled by the CLI, so this demo joins boards on
+# the account domain via 'mcli item find'. Deal activities use native subitems.
+
+# ─── Phase 3: Save Semantic Layer (queries & mutations) ──────────────────────
+
+echo ""
+echo "=== Phase 3: Define semantic layer ==="
+
+# --- Queries ---
+
+$MCLI query save list_companies --query \
+  "query(\$boardId: ID!) { boards(ids: [\$boardId]) { items_page(limit: 100) { items { id name column_values { id text value } } } } }"
+echo "Saved query: list_companies"
+
+$MCLI query save list_contacts --query \
+  "query(\$boardId: ID!) { boards(ids: [\$boardId]) { items_page(limit: 200) { items { id name column_values { id text value } } } } }"
+echo "Saved query: list_contacts"
+
+$MCLI query save list_pipeline --query \
+  "query(\$boardId: ID!) { boards(ids: [\$boardId]) { items_page(limit: 100) { items { id name group { id title } column_values { id text value } subitems { id name } } } } }"
+echo "Saved query: list_pipeline"
+
+$MCLI query save get_deal --query \
+  "query(\$itemId: [ID!]!) { items(ids: \$itemId) { id name column_values { id text value } subitems { id name column_values { id text value } } } }"
+echo "Saved query: get_deal"
+
+# --- Mutations ---
+
+$MCLI mutation save create_company --query \
+  "mutation(\$board: ID!, \$name: String!, \$cols: JSON!) { create_item(board_id: \$board, item_name: \$name, column_values: \$cols) { id } }"
+echo "Saved mutation: create_company"
+
+$MCLI mutation save create_contact --query \
+  "mutation(\$board: ID!, \$name: String!, \$cols: JSON!) { create_item(board_id: \$board, item_name: \$name, column_values: \$cols) { id } }"
+echo "Saved mutation: create_contact"
+
+$MCLI mutation save create_deal --query \
+  "mutation(\$board: ID!, \$group: String!, \$name: String!, \$cols: JSON!) { create_item(board_id: \$board, group_id: \$group, item_name: \$name, column_values: \$cols) { id } }"
+echo "Saved mutation: create_deal"
+
+$MCLI mutation save advance_deal_stage --query \
+  "mutation(\$board: ID!, \$item: ID!, \$cols: JSON!) { change_multiple_column_values(board_id: \$board, item_id: \$item, column_values: \$cols) { id } }"
+echo "Saved mutation: advance_deal_stage"
+
+$MCLI mutation save log_deal_activity --query \
+  "mutation(\$parent: ID!, \$name: String!, \$cols: JSON!) { create_subitem(parent_item_id: \$parent, item_name: \$name, column_values: \$cols) { id } }"
+echo "Saved mutation: log_deal_activity"
+
+# ─── Phase 4: Seed Accounts & Contacts ───────────────────────────────────────
+
+echo ""
+echo "=== Phase 4: Seed accounts and contacts ==="
+
+# Companies (structured command — most ergonomic for setup).
+#
+# Domain is the board's only text column and Segment its only status column, so
+# --text and --status address them by type — no column ID, and the label is checked
+# against the board's own labels before anything is sent. Website (link) and Owner
+# (people) have no shorthand, so they stay on raw --col: the two forms mix freely.
+CO_ACME=$($MCLI item create --board "$COMPANIES_BOARD" --name "Acme Corp" \
+  --text "acme.com" \
+  --status "Enterprise" \
+  --col "$CO_WEBSITE"='{"url":"https://acme.com","text":"acme.com"}' \
+  --col "$CO_OWNER"="$PERSON" | $JQ -r '.id')
+echo "Created company: Acme Corp ($CO_ACME)"
+
+CO_GLOBEX=$($MCLI item create --board "$COMPANIES_BOARD" --name "Globex" \
+  --text "globex.io" \
+  --status "Mid-Market" \
+  --col "$CO_WEBSITE"='{"url":"https://globex.io","text":"globex.io"}' \
+  --col "$CO_OWNER"="$PERSON" | $JQ -r '.id')
+echo "Created company: Globex ($CO_GLOBEX)"
+
+# Contacts (semantic layer — same result, business-level call).
+#
+# Note this board has three text columns (Company, Title, Email), so --text would
+# be ambiguous here and mcli would refuse rather than guess. Columns are addressed
+# by ID, which is what the semantic layer is for.
+CONTACT_COLS=$(printf '{ "%s": "%s", "%s": "%s", "%s": "%s", "%s": %s }' \
+  "$CT_COMPANY" "acme.com" "$CT_TITLE" "VP Engineering" "$CT_EMAIL" "dana@acme.com" "$CT_OWNER" "$PERSON")
+CT_DANA=$($MCLI mutation run create_contact \
+  --var board="$CONTACTS_BOARD" \
+  --var name="Dana Reyes" \
+  --var cols="$CONTACT_COLS" | $JQ -r '.data.create_item.id')
+echo "Created contact: Dana Reyes ($CT_DANA) @ acme.com"
+
+CONTACT_COLS=$(printf '{ "%s": "%s", "%s": "%s", "%s": "%s", "%s": %s }' \
+  "$CT_COMPANY" "acme.com" "$CT_TITLE" "Head of Procurement" "$CT_EMAIL" "sam@acme.com" "$CT_OWNER" "$PERSON")
+CT_SAM=$($MCLI mutation run create_contact \
+  --var board="$CONTACTS_BOARD" \
+  --var name="Sam Okafor" \
+  --var cols="$CONTACT_COLS" | $JQ -r '.data.create_item.id')
+echo "Created contact: Sam Okafor ($CT_SAM) @ acme.com"
+
+CONTACT_COLS=$(printf '{ "%s": "%s", "%s": "%s", "%s": "%s", "%s": %s }' \
+  "$CT_COMPANY" "globex.io" "$CT_TITLE" "CTO" "$CT_EMAIL" "lee@globex.io" "$CT_OWNER" "$PERSON")
+CT_LEE=$($MCLI mutation run create_contact \
+  --var board="$CONTACTS_BOARD" \
+  --var name="Lee Tran" \
+  --var cols="$CONTACT_COLS" | $JQ -r '.data.create_item.id')
+echo "Created contact: Lee Tran ($CT_LEE) @ globex.io"
+
+# ─── Phase 5: Run a Deal Through the Pipeline ────────────────────────────────
+
+echo ""
+echo "=== Phase 5: Open a deal and work the pipeline ==="
+
+# Open the deal in Discovery, inside the "Open Pipeline" group.
+DEAL_COLS=$(printf '{ "%s": "%s", "%s": {"label": "Discovery"}, "%s": "%s", "%s": {"date": "%s"}, "%s": %s }' \
+  "$DEAL_COMPANY" "acme.com" "$DEAL_STAGE" "$DEAL_VALUE" "120000" "$DEAL_CLOSE" "2026-12-15" "$DEAL_OWNER" "$PERSON")
+DEAL_ID=$($MCLI mutation run create_deal \
+  --var board="$DEALS_BOARD" \
+  --var group="$GROUP_OPEN" \
+  --var name="Acme — Platform rollout" \
+  --var cols="$DEAL_COLS" | $JQ -r '.data.create_item.id')
+echo "Opened deal: Acme — Platform rollout ($DEAL_ID) — stage: Discovery, \$120,000"
+
+# A second deal, so the pipeline has more than one row to roll up.
+DEAL_COLS=$(printf '{ "%s": "%s", "%s": {"label": "Qualified"}, "%s": "%s", "%s": {"date": "%s"}, "%s": %s }' \
+  "$DEAL_COMPANY" "globex.io" "$DEAL_STAGE" "$DEAL_VALUE" "38000" "$DEAL_CLOSE" "2026-10-01" "$DEAL_OWNER" "$PERSON")
+DEAL_GLOBEX=$($MCLI mutation run create_deal \
+  --var board="$DEALS_BOARD" \
+  --var group="$GROUP_OPEN" \
+  --var name="Globex — Analytics add-on" \
+  --var cols="$DEAL_COLS" | $JQ -r '.data.create_item.id')
+echo "Opened deal: Globex — Analytics add-on ($DEAL_GLOBEX) — stage: Qualified, \$38,000"
+
+# Log pipeline activities as subitems of the deal.
+$MCLI mutation run log_deal_activity \
+  --var parent="$DEAL_ID" \
+  --var name="Discovery call with VP Engineering" \
+  --var cols='{}' | $JQ -r '.data.create_subitem.id' > /dev/null
+echo "  Activity: discovery call logged"
+
+$MCLI mutation run log_deal_activity \
+  --var parent="$DEAL_ID" \
+  --var name="Technical deep-dive with platform team" \
+  --var cols='{}' | $JQ -r '.data.create_subitem.id' > /dev/null
+echo "  Activity: technical deep-dive logged"
+
+# Stage transition through the semantic layer.
+STAGE_COLS=$(printf '{ "%s": {"label": "Qualified"} }' "$DEAL_STAGE")
+$MCLI mutation run advance_deal_stage \
+  --var board="$DEALS_BOARD" \
+  --var item="$DEAL_ID" \
+  --var cols="$STAGE_COLS" | $JQ -r '.data' > /dev/null
+echo "Deal stage → Qualified"
+
+# Stage transition through the structured command, raising the value at the same
+# time. The Deals board has exactly one status and one numbers column, so the whole
+# update reads in business terms with no column IDs and no wire JSON at all.
+$MCLI item update "$DEAL_ID" --board "$DEALS_BOARD" \
+  --status "Proposal" \
+  --number 145000 > /dev/null
+echo "Deal stage → Proposal (value raised to \$145,000)"
+
+# Narrative lives on the item, not in a column.
+$MCLI item description "$DEAL_ID" \
+  --set "Multi-region platform rollout. Champion: VP Engineering. Blocker: security review." > /dev/null
+$MCLI item post-update "$DEAL_ID" \
+  --body "Stage → Negotiation. Legal is reviewing MSA redlines; close date still 2026-12-15." > /dev/null
+echo "Deal brief + update posted"
+
+STAGE_COLS=$(printf '{ "%s": {"label": "Negotiation"} }' "$DEAL_STAGE")
+$MCLI mutation run advance_deal_stage \
+  --var board="$DEALS_BOARD" \
+  --var item="$DEAL_ID" \
+  --var cols="$STAGE_COLS" | $JQ -r '.data' > /dev/null
+echo "Deal stage → Negotiation"
+
+# Close it: mark Won, then move it out of the open pipeline group.
+$MCLI item update "$DEAL_ID" --board "$DEALS_BOARD" --status "Won" > /dev/null
+$MCLI item move "$DEAL_ID" --to-group "$GROUP_CLOSED" > /dev/null
+echo "Deal stage → Won, moved to the Closed group"
+
+# ─── Phase 6: Query the Pipeline ─────────────────────────────────────────────
+
+echo ""
+echo "=== Phase 6: Query the pipeline ==="
+
+echo "--- Contacts at acme.com (join on the domain key) ---"
+$MCLI item find --board "$CONTACTS_BOARD" --column "$CT_COMPANY" --value "acme.com" --pretty
+
+echo ""
+echo "--- Deals at acme.com ---"
+$MCLI item find --board "$DEALS_BOARD" --column "$DEAL_COMPANY" --value "acme.com" --pretty
+
+echo ""
+echo "--- Won deals (status columns match on label text) ---"
+$MCLI item find --board "$DEALS_BOARD" --column "$DEAL_STAGE" --value "Won" --pretty
+
+echo ""
+echo "--- Open pipeline, with activity subitems (--subitems is JSON-only) ---"
+$MCLI item list --board "$DEALS_BOARD" --group "$GROUP_OPEN" --subitems --limit 100 --json | $JQ '.'
+
+echo ""
+echo "--- Open pipeline value ---"
+OPEN_VALUE=$($MCLI item list --board "$DEALS_BOARD" --group "$GROUP_OPEN" --limit 100 \
+  | $JQ --arg col "$DEAL_VALUE" '[.items[].columns[] | select(.id == $col) | .value | tonumber] | add // 0')
+echo "Open pipeline total: \$$OPEN_VALUE"
+
+echo ""
+echo "--- Won deal detail (semantic layer) ---"
+$MCLI query run get_deal --var itemId="[$DEAL_ID]" --pretty
+
+echo ""
+echo "=== Demo complete ==="
+echo ""
+echo "Board IDs for further exploration:"
+echo "  Companies: $COMPANIES_BOARD"
+echo "  Contacts:  $CONTACTS_BOARD"
+echo "  Deals:     $DEALS_BOARD (groups: open=$GROUP_OPEN, closed=$GROUP_CLOSED)"
diff --git a/examples/ecommerce-demo.md b/examples/ecommerce-demo.md
index 8427cb8..cf20ea2 100644
--- a/examples/ecommerce-demo.md
+++ b/examples/ecommerce-demo.md
@@ -87,12 +87,14 @@ mcli mutation save create_order --query \
 
 ## Phase 4: Seed Data
 
-Using the structured `item create` command (more ergonomic for setup):
+Using the structured `item create` command (more ergonomic for setup). SKU is the
+Products board's only `text` column and Price its only `numbers` column, so the typed
+shorthands address them without the caller knowing either column ID:
 
 ```sh
 mcli item create --board $PRODUCTS_BOARD --name "Widget Pro" \
-  --col "$PROD_SKU"='"WGT-001"' \
-  --col "$PROD_PRICE"='"29.99"'
+  --text "WGT-001" \
+  --number 29.99
 ```
 
 Or using the semantic layer:
@@ -104,6 +106,32 @@ mcli mutation run create_product \
   --var cols='{"sku":"WGT-001","price":"29.99"}'
 ```
 
+Seeding many rows one command at a time walks straight into monday's complexity
+budget. Pass `-` instead and `item create` reads rows from stdin, writing them
+sequentially in one invocation:
+
+```sh
+mcli item create --board $INVENTORY_BOARD - <<'ROWS'
+[{"name": "WGT-001", "text": "WGT-001", "number": 100},
+ {"name": "GDG-002", "text": "GDG-002", "number": 50},
+ {"name": "DHK-003", "text": "DHK-003", "number": 200}]
+ROWS
+```
+
+Rows take the same shorthand keys as the flags, plus `cols` for the raw escape hatch.
+Every row is validated before the first request, so a bad status label fails the whole
+batch with nothing written. The result is one JSON object:
+
+```json
+{ "written": 3, "failed": 0, "verb": "created", "items": [ ... ], "errors": [] }
+```
+
+On a partial failure the exit code is 2 — **retry only the rows named in
+`errors[].index`**, because `create_item` has no dedupe key and re-sending the batch
+would duplicate the rows that already succeeded. `--dry-run` prints the exact
+`column_values` per row without writing anything, and needs no API call at all unless
+a shorthand has to be resolved.
+
 ## Phase 5: Place an Order
 
 This is where the semantic layer shines — the agent writes natural JSON in `--var`
@@ -146,6 +174,8 @@ mcli query run get_order --var itemId="[$ORDER_ID]" --pretty
 ## Key Takeaways
 
 - **Generic commands** (`board create`, `item create`) handle setup
+- **Typed shorthands** (`--text`, `--number`, `--status`, …) address a board's single column of that type, so no column IDs or wire JSON for the common cases
+- **Batch writes** (`item create --board <id> -`) seed many rows in one invocation instead of racing the rate limit
 - **Saved queries/mutations** create a domain-specific API layer
 - **JSON coercion** — variables declared as `JSON` in the query are auto-stringified, so `--var cols='{"key":"val"}'` just works without double-encoding
 - **LLM agents** can operate entirely through `mcli mutation run <name>` / `mcli query run <name>` without understanding monday.com internals or wire-format quirks
diff --git a/examples/ecommerce-demo.sh b/examples/ecommerce-demo.sh
index b692987..11473cc 100755
--- a/examples/ecommerce-demo.sh
+++ b/examples/ecommerce-demo.sh
@@ -24,6 +24,11 @@ echo "Orders board: $ORDERS_BOARD"
 echo ""
 echo "=== Phase 2: Define columns ==="
 
+# The typed shorthands used below (--text, --number) address the board's single column
+# of that type. A board created through the API starts with only a Name column, so each
+# board's shape is exactly what this script gives it. If a type is ever duplicated the
+# shorthand refuses, naming the candidates, rather than picking one.
+
 # Products: name (built-in), SKU, description, price
 PROD_SKU=$($MCLI board column create --board "$PRODUCTS_BOARD" --title "SKU" --type text | $JQ -r '.id')
 PROD_DESC=$($MCLI board column create --board "$PRODUCTS_BOARD" --title "Description" --type long_text | $JQ -r '.id')
@@ -95,38 +100,35 @@ echo "Saved mutation: update_order_status"
 echo ""
 echo "=== Phase 4: Seed data ==="
 
-# Products
+# Products. SKU is the board's only text column and Price its only numbers column,
+# so --text and --number address them without the caller knowing either column ID.
+# Description is long_text, which has no shorthand, so it stays on raw --col.
 ITEM_WIDGET=$($MCLI item create --board "$PRODUCTS_BOARD" --name "Widget Pro" \
-  --col "$PROD_SKU"='"WGT-001"' \
-  --col "$PROD_DESC"='{"text":"Premium widget with enhanced features"}' \
-  --col "$PROD_PRICE"='"29.99"' | $JQ -r '.id')
+  --text "WGT-001" \
+  --number 29.99 \
+  --col "$PROD_DESC"='{"text":"Premium widget with enhanced features"}' | $JQ -r '.id')
 echo "Created product: Widget Pro ($ITEM_WIDGET)"
 
 ITEM_GADGET=$($MCLI item create --board "$PRODUCTS_BOARD" --name "Gadget X" \
-  --col "$PROD_SKU"='"GDG-002"' \
-  --col "$PROD_DESC"='{"text":"Compact gadget for everyday use"}' \
-  --col "$PROD_PRICE"='"49.99"' | $JQ -r '.id')
+  --text "GDG-002" \
+  --number 49.99 \
+  --col "$PROD_DESC"='{"text":"Compact gadget for everyday use"}' | $JQ -r '.id')
 echo "Created product: Gadget X ($ITEM_GADGET)"
 
 ITEM_DOOHICK=$($MCLI item create --board "$PRODUCTS_BOARD" --name "Doohickey" \
-  --col "$PROD_SKU"='"DHK-003"' \
-  --col "$PROD_DESC"='{"text":"Multi-purpose doohickey"}' \
-  --col "$PROD_PRICE"='"9.99"' | $JQ -r '.id')
+  --text "DHK-003" \
+  --number 9.99 \
+  --col "$PROD_DESC"='{"text":"Multi-purpose doohickey"}' | $JQ -r '.id')
 echo "Created product: Doohickey ($ITEM_DOOHICK)"
 
-# Inventory
-INV_W=$($MCLI item create --board "$INVENTORY_BOARD" --name "WGT-001" \
-  --col "$INV_SKU"='"WGT-001"' \
-  --col "$INV_QTY"='"100"' | $JQ -r '.id')
-
-INV_G=$($MCLI item create --board "$INVENTORY_BOARD" --name "GDG-002" \
-  --col "$INV_SKU"='"GDG-002"' \
-  --col "$INV_QTY"='"50"' | $JQ -r '.id')
-
-INV_D=$($MCLI item create --board "$INVENTORY_BOARD" --name "DHK-003" \
-  --col "$INV_SKU"='"DHK-003"' \
-  --col "$INV_QTY"='"200"' | $JQ -r '.id')
-echo "Inventory seeded for 3 SKUs"
+# Inventory — one batch instead of three round-trips. Rows are read from stdin and
+# written sequentially, so seeding N SKUs costs one command against monday's
+# complexity budget rather than N invocations racing it.
+$MCLI item create --board "$INVENTORY_BOARD" - --json <<'ROWS' | $JQ -r '"Inventory: written=\(.written) failed=\(.failed)"'
+[{"name": "WGT-001", "text": "WGT-001", "number": 100},
+ {"name": "GDG-002", "text": "GDG-002", "number": 50},
+ {"name": "DHK-003", "text": "DHK-003", "number": 200}]
+ROWS
 
 # ─── Phase 5: Place an Order ─────────────────────────────────────────────────
 
diff --git a/examples/portfolio-demo.md b/examples/portfolio-demo.md
new file mode 100644
index 0000000..21ea0a2
--- /dev/null
+++ b/examples/portfolio-demo.md
@@ -0,0 +1,311 @@
+# Portfolio Demo: Portfolios, Projects & Milestones
+
+This demo shows how an LLM agent (or human) can use mcli's generic commands to:
+
+1. **Create boards** with typed columns, one group per portfolio
+2. **Define a semantic layer** of saved queries/mutations with business-domain names
+3. **Seed portfolios and projects** using the structured item commands
+4. **Track milestones as subitems**, including typing the subitems board mcli hands back
+5. **Roll up** — projects per portfolio, at-risk projects, milestone status
+
+## Prerequisites
+
+- `mcli auth login` (or `MONDAY_API_TOKEN` set)
+- `jq` in PATH
+
+Run the full demo: `./examples/portfolio-demo.sh`
+
+---
+
+## Phase 1: Create Boards
+
+```sh
+mcli board create --name "Portfolios" --kind public --empty   # → {"id":"..."}
+mcli board create --name "Projects"   --kind public --empty
+```
+
+Each board starts empty (no default columns/items).
+
+Projects get one group per portfolio, so "the projects in this portfolio" is a
+native, cheap query (`item list --group`) rather than a client-side filter:
+
+```sh
+mcli board group create --board $PROJECTS_BOARD --name "Platform Modernization"
+mcli board group create --board $PROJECTS_BOARD --name "Customer Experience"
+```
+
+Milestones are **subitems of projects** — monday materialises them on a
+"Subitems of Projects" board that it creates on first use. Phase 5 shows how to
+discover that board's ID and give it real columns.
+
+## Phase 2: Define Columns
+
+**Portfolios** — item name is the portfolio name:
+
+```sh
+mcli board column create --board $PORTFOLIOS_BOARD --title "Owner"  --type people
+mcli board column create --board $PORTFOLIOS_BOARD --title "Budget" --type numbers
+mcli board column create --board $PORTFOLIOS_BOARD --title "Health" --type status \
+  --defaults '{"labels":{"0":"On Track","1":"At Risk","2":"Off Track"}}'
+```
+
+**Projects** — item name is the project name; `Portfolio` holds the parent
+portfolio's name, which is the join key back to the Portfolios board:
+
+```sh
+mcli board column create --board $PROJECTS_BOARD --title "Portfolio" --type text
+mcli board column create --board $PROJECTS_BOARD --title "Owner"     --type people
+mcli board column create --board $PROJECTS_BOARD --title "Start"     --type date
+mcli board column create --board $PROJECTS_BOARD --title "Target"    --type date
+mcli board column create --board $PROJECTS_BOARD --title "Complete"  --type numbers
+mcli board column create --board $PROJECTS_BOARD --title "Steering Approved" --type checkbox
+mcli board column create --board $PROJECTS_BOARD --title "Risk Notes" --type long_text
+mcli board column create --board $PROJECTS_BOARD --title "RAG" --type status \
+  --defaults '{"labels":{"0":"Green","1":"Amber","2":"Red"}}'
+```
+
+Describe the columns whose meaning is not obvious from the title:
+
+```sh
+mcli board column describe --board $PROJECTS_BOARD --column $PROJ_RAG \
+  --text "Delivery health: Green = on plan, Amber = recoverable slip, Red = escalate"
+```
+
+A `timeline` column (`--type timeline`) is also available and mcli decodes it as
+`{"from":"…","to":"…"}`; this demo uses two `date` columns (Start / Target)
+because their write shape — `{"date":"YYYY-MM-DD"}` — is the one documented for
+`--col`.
+
+## Phase 3: Semantic Layer
+
+Saved queries and mutations give business-level names to operations. An LLM can
+call `mcli mutation run set_project_health --var ...` without knowing GraphQL:
+
+### Queries
+
+| Name | Purpose |
+|------|---------|
+| `list_portfolios` | All portfolios with column values |
+| `list_projects` | All projects with column values and milestone subitems |
+| `projects_in_portfolio` | Projects in one portfolio group (the rollup query) |
+| `get_project` | Single project detail with milestone column values |
+
+```sh
+mcli query save projects_in_portfolio --query \
+  'query($boardId: ID!, $groupIds: [String!]) { boards(ids: [$boardId]) { groups(ids: $groupIds) { id title items_page(limit:100) { items { id name column_values { id text value } subitems { id name } } } } } }'
+```
+
+### Mutations
+
+| Name | Purpose |
+|------|---------|
+| `create_portfolio` | Add a portfolio |
+| `create_project` | Add a project into a portfolio group |
+| `set_project_health` | Update RAG / percent complete / notes |
+| `set_portfolio_health` | Roll the portfolio's own health status up |
+| `add_milestone` | Add a milestone subitem to a project |
+
+```sh
+mcli mutation save add_milestone --query \
+  'mutation($parent: ID!, $name: String!, $cols: JSON!) { create_subitem(parent_item_id: $parent, item_name: $name, column_values: $cols) { id } }'
+```
+
+## Phase 4: Seed Portfolios & Projects
+
+Using the structured `item create` command (more ergonomic for setup). A typed
+shorthand addresses the board's *single* column of that type, so Health (`status`)
+and Budget (`numbers`) need no column ID; Owner (`people`) has no shorthand and uses
+monday's raw write shape:
+
+```sh
+ME_ID=$(mcli me | jq -r '.id')
+
+mcli item create --board $PORTFOLIOS_BOARD --name "Platform Modernization" \
+  --status "On Track" \
+  --number 2400000 \
+  --col "$PF_OWNER"="{\"personsAndTeams\":[{\"id\":$ME_ID,\"kind\":\"person\"}]}"
+```
+
+The Projects board is the instructive case. RAG (`status`), Portfolio (`text`),
+Complete (`numbers`) and Steering Approved (`checkbox`) are each the only column of
+their type, so all four have a shorthand. But **Start and Target are both `date`
+columns** — `--date` would be ambiguous there, so mcli refuses it and names both
+candidates rather than picking one. Those two keep raw `--col`, which is what the
+escape hatch exists for:
+
+```sh
+mcli item create --board $PROJECTS_BOARD --group $GROUP_PLATFORM --name "Auth service rewrite" \
+  --text "Platform Modernization" \
+  --status "Green" \
+  --number 35 \
+  --checkbox true \
+  --col "$PROJ_START"='{"date":"2026-01-05"}' \
+  --col "$PROJ_TARGET"='{"date":"2026-06-30"}'
+```
+
+Where a shorthand does not apply, the raw shapes are: `status` → `{"label":"..."}`,
+`date` → `{"date":"YYYY-MM-DD"}`, `people` → `{"personsAndTeams":[...]}`, `checkbox`
+→ `{"checked":"true"}`, `numeric` → a quoted string.
+
+Shorthands resolve against the board's shape, so `mcli board column list --board <id>`
+is the way to check what is addressable. A board created through the API starts with
+only a Name column, so a board you built with `board column create` has exactly the
+shape you gave it.
+
+Or using the semantic layer:
+
+```sh
+mcli mutation run create_project \
+  --var board=$PROJECTS_BOARD \
+  --var group=$GROUP_PLATFORM \
+  --var name="Auth service rewrite" \
+  --var cols='{"portfolio":"Platform Modernization","rag":{"label":"Green"},"complete":"35"}'
+```
+
+## Phase 5: Milestones as Subitems
+
+`item create --parent` returns the subitem *and* the board monday put it on, so
+the subitems board can be typed on the fly — the first milestone tells you where
+the rest of them live:
+
+```sh
+MS=$(mcli item create --parent $PROJECT_ID --name "Design sign-off")
+MILESTONE_ID=$(jq -r '.id'       <<<"$MS")
+SUBITEM_BOARD=$(jq -r '.board.id' <<<"$MS")
+
+mcli board column create --board $SUBITEM_BOARD --title "Due" --type date
+mcli board column create --board $SUBITEM_BOARD --title "State" --type status \
+  --defaults '{"labels":{"0":"Planned","1":"In Progress","2":"Done","3":"Missed"}}'
+```
+
+`item create --parent` returns the created subitem with its board and parent:
+
+```json
+{
+  "id": "7890123456",
+  "name": "Design sign-off",
+  "state": "active",
+  "board": { "id": "9832181509", "name": "Subitems of Projects" },
+  "parent_item": { "id": "7890123400", "name": "Auth service rewrite" }
+}
+```
+
+Once the columns exist, milestones are updated like any other item — note the
+`--board` is the *subitems* board, not the Projects board:
+
+```sh
+mcli item update $MILESTONE_ID --board $SUBITEM_BOARD \
+  --col "$MS_DUE"='{"date":"2026-02-20"}' \
+  --col "$MS_STATE"='{"label":"Done"}'
+```
+
+Raw `--col` on purpose here: monday created this board, so its default columns are
+not yours to assume. Shorthands suit boards whose shape you defined; on a board you
+did not create, address columns by ID (or check with `mcli board column list`).
+
+Later milestones can go through the semantic layer, because the column IDs are
+now known:
+
+```sh
+mcli mutation run add_milestone \
+  --var parent=$PROJECT_ID \
+  --var name="Beta in production" \
+  --var cols='{"due":{"date":"2026-05-15"},"state":{"label":"Planned"}}'
+```
+
+## Phase 6: Rollup Queries
+
+**Projects per portfolio** — group-scoped, so the board does the filtering:
+
+```sh
+mcli item list --board $PROJECTS_BOARD --group $GROUP_PLATFORM --limit 100 --pretty
+mcli query run projects_in_portfolio --var boardId=$PROJECTS_BOARD --var groupIds="[\"$GROUP_PLATFORM\"]" --pretty
+```
+
+The join key works too, when a project may live outside its portfolio's group:
+
+```sh
+mcli item find --board $PROJECTS_BOARD --column $PROJ_PORTFOLIO --value "Platform Modernization"
+```
+
+**At-risk projects** — status columns match on their label text, so one call per
+label answers "what is red?":
+
+```sh
+mcli item find --board $PROJECTS_BOARD --column $PROJ_RAG --value "Red"
+mcli item find --board $PROJECTS_BOARD --column $PROJ_RAG --value "Amber"
+```
+
+Or in a single pass over the board, since `item list` returns decoded column
+values (`columns[].value` is the label string for a status column):
+
+```sh
+mcli item list --board $PROJECTS_BOARD --limit 100 \
+  | jq --arg rag "$PROJ_RAG" '
+      .items[]
+      | select(any(.columns[]; .id == $rag and (.value == "Red" or .value == "Amber")))
+      | {id, name, group: .group.title}'
+```
+
+**Portfolio-level rollup** — worst project RAG and mean completion per group:
+
+```sh
+mcli item list --board $PROJECTS_BOARD --limit 100 \
+  | jq --arg rag "$PROJ_RAG" --arg pct "$PROJ_COMPLETE" '
+      def col($id): [.columns[] | select(.id == $id) | .value] | first;
+      [.items[] | {portfolio: .group.title, rag: col($rag), pct: col($pct)}]
+      | group_by(.portfolio)[]
+      | { portfolio: .[0].portfolio,
+          projects: length,
+          worst_rag: (if any(.[]; .rag == "Red") then "Red"
+                      elif any(.[]; .rag == "Amber") then "Amber"
+                      else "Green" end),
+          avg_complete: (([.[].pct // 0] | add) / length) }'
+```
+
+**Milestone status for one project**:
+
+```sh
+mcli item get $PROJECT_ID --subitems
+mcli item list --board $PROJECTS_BOARD --group $GROUP_PLATFORM --subitems --limit 100 --json
+```
+
+`item list` returns the standard list envelope — items with decoded columns plus
+a page cursor (`""` means last page):
+
+```json
+{
+  "items": [
+    {
+      "id": "7890123400",
+      "name": "Auth service rewrite",
+      "state": "active",
+      "group": { "id": "topics", "title": "Platform Modernization" },
+      "columns": [
+        { "id": "status", "title": "RAG", "type": "status", "value": "Amber" },
+        { "id": "numbers", "title": "Complete", "type": "numbers", "value": 35 }
+      ]
+    }
+  ],
+  "cursor": ""
+}
+```
+
+Escalations belong on the item, where the next reader will find them:
+
+```sh
+mcli item post-update $PROJECT_ID --body "RAG → Amber: vendor SSO delivery slipped two weeks."
+mcli item description $PROJECT_ID --set "Rewrite of the auth service onto the new platform. Steering: monthly."
+```
+
+## Key Takeaways
+
+- **Generic commands** (`board create`, `board group create`, `board column create`, `item create`) handle setup
+- **Typed shorthands** address a board's single column of a type (`--status`, `--text`, `--number`, `--checkbox`); two `date` columns on the Projects board is exactly the case where they refuse and `--col` takes over
+- **Saved queries/mutations** create a domain-specific portfolio API layer
+- **Groups are the rollup axis** — one group per portfolio makes "projects in portfolio" a server-side filter; the `Portfolio` text column plus `item find` covers the cross-group case
+- **Subitem boards are discoverable** — `item create --parent` returns `board.id`, which is what you pass to `board column create` and to `item update --board` for milestones
+- **Decoded reads** — `item list` / `item get` return status labels and numbers already decoded, so `jq` can roll them up without touching raw monday JSON
+- **JSON coercion** — variables declared as `JSON` in the query are auto-stringified, so `--var cols='{"key":"val"}'` just works without double-encoding
+- **LLM agents** can operate entirely through `mcli mutation run <name>` / `mcli query run <name>` without understanding monday.com internals or wire-format quirks
+- The semantic layer is project-local (`.mcli/` directory) and version-controllable
diff --git a/examples/portfolio-demo.sh b/examples/portfolio-demo.sh
new file mode 100644
index 0000000..2f7ff6f
--- /dev/null
+++ b/examples/portfolio-demo.sh
@@ -0,0 +1,306 @@
+#!/usr/bin/env bash
+# portfolio-demo: set up Portfolios/Projects boards, define a semantic layer of
+# saved queries/mutations, seed portfolios and projects, track milestones as
+# subitems, then run portfolio rollup queries.
+set -euo pipefail
+
+MCLI="${MCLI:-mcli}"
+JQ="${JQ:-jq}"
+
+# The authenticated user is used as the owner for every people column.
+ME_ID=$($MCLI me | $JQ -r '.id')
+PERSON=$(printf '{"personsAndTeams":[{"id":%s,"kind":"person"}]}' "$ME_ID")
+
+# ─── Phase 1: Create Boards ─────────────────────────────────────────────────
+
+echo "=== Phase 1: Create boards ==="
+
+PORTFOLIOS_BOARD=$($MCLI board create --name "Portfolios" --kind public --empty | $JQ -r '.id')
+echo "Portfolios board: $PORTFOLIOS_BOARD"
+
+PROJECTS_BOARD=$($MCLI board create --name "Projects" --kind public --empty | $JQ -r '.id')
+echo "Projects board: $PROJECTS_BOARD"
+
+# One group per portfolio: "projects in this portfolio" becomes a server-side
+# filter (item list --group) instead of a client-side one.
+GROUP_PLATFORM=$($MCLI board group create --board "$PROJECTS_BOARD" --name "Platform Modernization" | $JQ -r '.id')
+GROUP_CX=$($MCLI board group create --board "$PROJECTS_BOARD" --name "Customer Experience" | $JQ -r '.id')
+echo "Projects groups: platform=$GROUP_PLATFORM, cx=$GROUP_CX"
+
+# ─── Phase 2: Add Columns ───────────────────────────────────────────────────
+
+echo ""
+echo "=== Phase 2: Define columns ==="
+
+# The typed shorthands used below (--text, --status, --number, --checkbox) address the
+# board's single column of that type. A board created through the API starts with only
+# a Name column, so each board's shape is exactly what this script gives it. Note
+# Projects gets two date columns (Start, Target) on purpose — --date is ambiguous
+# there and mcli refuses it, naming both, rather than picking one.
+
+# Portfolios: name (built-in), owner, budget, health
+PF_OWNER=$($MCLI board column create --board "$PORTFOLIOS_BOARD" --title "Owner" --type people | $JQ -r '.id')
+PF_BUDGET=$($MCLI board column create --board "$PORTFOLIOS_BOARD" --title "Budget" --type numbers | $JQ -r '.id')
+PF_HEALTH=$($MCLI board column create --board "$PORTFOLIOS_BOARD" --title "Health" --type status \
+  --defaults '{"labels":{"0":"On Track","1":"At Risk","2":"Off Track"}}' | $JQ -r '.id')
+echo "Portfolios columns: Owner=$PF_OWNER, Budget=$PF_BUDGET, Health=$PF_HEALTH"
+
+# Projects: Portfolio holds the portfolio name — the join key to Portfolios.
+PROJ_PORTFOLIO=$($MCLI board column create --board "$PROJECTS_BOARD" --title "Portfolio" --type text | $JQ -r '.id')
+PROJ_OWNER=$($MCLI board column create --board "$PROJECTS_BOARD" --title "Owner" --type people | $JQ -r '.id')
+PROJ_START=$($MCLI board column create --board "$PROJECTS_BOARD" --title "Start" --type date | $JQ -r '.id')
+PROJ_TARGET=$($MCLI board column create --board "$PROJECTS_BOARD" --title "Target" --type date | $JQ -r '.id')
+PROJ_COMPLETE=$($MCLI board column create --board "$PROJECTS_BOARD" --title "Complete" --type numbers | $JQ -r '.id')
+PROJ_APPROVED=$($MCLI board column create --board "$PROJECTS_BOARD" --title "Steering Approved" --type checkbox | $JQ -r '.id')
+PROJ_NOTES=$($MCLI board column create --board "$PROJECTS_BOARD" --title "Risk Notes" --type long_text | $JQ -r '.id')
+PROJ_RAG=$($MCLI board column create --board "$PROJECTS_BOARD" --title "RAG" --type status \
+  --defaults '{"labels":{"0":"Green","1":"Amber","2":"Red"}}' | $JQ -r '.id')
+echo "Projects columns: Portfolio=$PROJ_PORTFOLIO, Owner=$PROJ_OWNER, Start=$PROJ_START, Target=$PROJ_TARGET"
+echo "                  Complete=$PROJ_COMPLETE, Approved=$PROJ_APPROVED, Notes=$PROJ_NOTES, RAG=$PROJ_RAG"
+
+$MCLI board column describe --board "$PROJECTS_BOARD" --column "$PROJ_RAG" \
+  --text "Delivery health: Green = on plan, Amber = recoverable slip, Red = escalate" > /dev/null
+$MCLI board column describe --board "$PROJECTS_BOARD" --column "$PROJ_PORTFOLIO" \
+  --text "Portfolio name — join key to the Portfolios board (item name)" > /dev/null
+echo "Described the RAG and join-key columns"
+
+# Note: a timeline column (--type timeline) is also available and mcli decodes it
+# as {"from":...,"to":...}; this demo uses two date columns because {"date":...}
+# is the documented --col write shape.
+
+# ─── Phase 3: Save Semantic Layer (queries & mutations) ──────────────────────
+
+echo ""
+echo "=== Phase 3: Define semantic layer ==="
+
+# --- Queries ---
+
+$MCLI query save list_portfolios --query \
+  "query(\$boardId: ID!) { boards(ids: [\$boardId]) { items_page(limit: 100) { items { id name column_values { id text value } } } } }"
+echo "Saved query: list_portfolios"
+
+$MCLI query save list_projects --query \
+  "query(\$boardId: ID!) { boards(ids: [\$boardId]) { items_page(limit: 100) { items { id name group { id title } column_values { id text value } subitems { id name column_values { id text value } } } } } }"
+echo "Saved query: list_projects"
+
+$MCLI query save projects_in_portfolio --query \
+  "query(\$boardId: ID!, \$groupIds: [String!]) { boards(ids: [\$boardId]) { groups(ids: \$groupIds) { id title items_page(limit: 100) { items { id name column_values { id text value } subitems { id name } } } } } }"
+echo "Saved query: projects_in_portfolio"
+
+$MCLI query save get_project --query \
+  "query(\$itemId: [ID!]!) { items(ids: \$itemId) { id name column_values { id text value } subitems { id name column_values { id text value } } } }"
+echo "Saved query: get_project"
+
+# --- Mutations ---
+
+$MCLI mutation save create_portfolio --query \
+  "mutation(\$board: ID!, \$name: String!, \$cols: JSON!) { create_item(board_id: \$board, item_name: \$name, column_values: \$cols) { id } }"
+echo "Saved mutation: create_portfolio"
+
+$MCLI mutation save create_project --query \
+  "mutation(\$board: ID!, \$group: String!, \$name: String!, \$cols: JSON!) { create_item(board_id: \$board, group_id: \$group, item_name: \$name, column_values: \$cols) { id } }"
+echo "Saved mutation: create_project"
+
+$MCLI mutation save set_project_health --query \
+  "mutation(\$board: ID!, \$item: ID!, \$cols: JSON!) { change_multiple_column_values(board_id: \$board, item_id: \$item, column_values: \$cols) { id } }"
+echo "Saved mutation: set_project_health"
+
+$MCLI mutation save set_portfolio_health --query \
+  "mutation(\$board: ID!, \$item: ID!, \$cols: JSON!) { change_multiple_column_values(board_id: \$board, item_id: \$item, column_values: \$cols) { id } }"
+echo "Saved mutation: set_portfolio_health"
+
+$MCLI mutation save add_milestone --query \
+  "mutation(\$parent: ID!, \$name: String!, \$cols: JSON!) { create_subitem(parent_item_id: \$parent, item_name: \$name, column_values: \$cols) { id } }"
+echo "Saved mutation: add_milestone"
+
+# ─── Phase 4: Seed Portfolios & Projects ─────────────────────────────────────
+
+echo ""
+echo "=== Phase 4: Seed portfolios and projects ==="
+
+# Health is the board's only status column and Budget its only numbers column, so
+# --status and --number address them by type. Owner (people) has no shorthand yet.
+PF_PLATFORM=$($MCLI item create --board "$PORTFOLIOS_BOARD" --name "Platform Modernization" \
+  --status "On Track" \
+  --number 2400000 \
+  --col "$PF_OWNER"="$PERSON" | $JQ -r '.id')
+echo "Created portfolio: Platform Modernization ($PF_PLATFORM)"
+
+PF_CX=$($MCLI item create --board "$PORTFOLIOS_BOARD" --name "Customer Experience" \
+  --status "On Track" \
+  --number 900000 \
+  --col "$PF_OWNER"="$PERSON" | $JQ -r '.id')
+echo "Created portfolio: Customer Experience ($PF_CX)"
+
+# Projects — structured command, one per portfolio group.
+#
+# This board is the interesting case for shorthands. RAG (status), Portfolio (text),
+# Complete (numbers) and Steering Approved (checkbox) are each the board's only
+# column of their type, so --status/--text/--number/--checkbox all work. But Start
+# and Target are *both* date columns: --date would be ambiguous, so mcli refuses it
+# and names both candidates rather than picking one. Those two keep raw --col, which
+# is exactly what the escape hatch is for.
+PROJ_AUTH=$($MCLI item create --board "$PROJECTS_BOARD" --group "$GROUP_PLATFORM" --name "Auth service rewrite" \
+  --text "Platform Modernization" \
+  --status "Green" \
+  --number 35 \
+  --checkbox true \
+  --col "$PROJ_START"='{"date":"2026-01-05"}' \
+  --col "$PROJ_TARGET"='{"date":"2026-06-30"}' \
+  --col "$PROJ_OWNER"="$PERSON" | $JQ -r '.id')
+echo "Created project: Auth service rewrite ($PROJ_AUTH)"
+
+PROJ_DATA=$($MCLI item create --board "$PROJECTS_BOARD" --group "$GROUP_PLATFORM" --name "Data lake migration" \
+  --text "Platform Modernization" \
+  --status "Amber" \
+  --number 20 \
+  --checkbox true \
+  --col "$PROJ_START"='{"date":"2026-02-01"}' \
+  --col "$PROJ_TARGET"='{"date":"2026-09-30"}' \
+  --col "$PROJ_OWNER"="$PERSON" | $JQ -r '.id')
+echo "Created project: Data lake migration ($PROJ_DATA)"
+
+# Third project via the semantic layer — same result, business-level call.
+PROJECT_COLS=$(printf '{ "%s": "%s", "%s": {"label": "Green"}, "%s": {"date": "%s"}, "%s": {"date": "%s"}, "%s": "%s", "%s": %s }' \
+  "$PROJ_PORTFOLIO" "Customer Experience" "$PROJ_RAG" \
+  "$PROJ_START" "2026-03-02" "$PROJ_TARGET" "2026-08-14" \
+  "$PROJ_COMPLETE" "10" "$PROJ_OWNER" "$PERSON")
+PROJ_PORTAL=$($MCLI mutation run create_project \
+  --var board="$PROJECTS_BOARD" \
+  --var group="$GROUP_CX" \
+  --var name="Self-serve portal" \
+  --var cols="$PROJECT_COLS" | $JQ -r '.data.create_item.id')
+echo "Created project: Self-serve portal ($PROJ_PORTAL)"
+
+# ─── Phase 5: Milestones as Subitems ─────────────────────────────────────────
+
+echo ""
+echo "=== Phase 5: Milestones ==="
+
+# The first subitem tells us which board monday put milestones on, so we can
+# give that board real columns.
+MS_FIRST=$($MCLI item create --parent "$PROJ_AUTH" --name "Design sign-off")
+MS_DESIGN=$($JQ -r '.id' <<<"$MS_FIRST")
+SUBITEM_BOARD=$($JQ -r '.board.id' <<<"$MS_FIRST")
+echo "Milestone subitem board: $SUBITEM_BOARD"
+
+MS_DUE=$($MCLI board column create --board "$SUBITEM_BOARD" --title "Due" --type date | $JQ -r '.id')
+MS_STATE=$($MCLI board column create --board "$SUBITEM_BOARD" --title "State" --type status \
+  --defaults '{"labels":{"0":"Planned","1":"In Progress","2":"Done","3":"Missed"}}' | $JQ -r '.id')
+echo "Milestone columns: Due=$MS_DUE, State=$MS_STATE"
+
+# Backfill the first milestone now that the columns exist. Note the --board is
+# the subitems board, not the Projects board.
+#
+# Raw --col here on purpose: monday creates the subitems board itself, so its
+# default columns are not ours to assume. Shorthands are for boards whose shape you
+# defined — on a board you did not create, address columns by ID.
+$MCLI item update "$MS_DESIGN" --board "$SUBITEM_BOARD" \
+  --col "$MS_DUE"='{"date":"2026-02-20"}' \
+  --col "$MS_STATE"='{"label":"Done"}' > /dev/null
+echo "  Design sign-off — due 2026-02-20 — Done"
+
+# Remaining milestones go through the semantic layer.
+MILESTONE_COLS=$(printf '{ "%s": {"date": "%s"}, "%s": {"label": "%s"} }' "$MS_DUE" "2026-05-15" "$MS_STATE" "In Progress")
+$MCLI mutation run add_milestone \
+  --var parent="$PROJ_AUTH" \
+  --var name="Beta in production" \
+  --var cols="$MILESTONE_COLS" | $JQ -r '.data.create_subitem.id' > /dev/null
+echo "  Beta in production — due 2026-05-15 — In Progress"
+
+MILESTONE_COLS=$(printf '{ "%s": {"date": "%s"}, "%s": {"label": "%s"} }' "$MS_DUE" "2026-06-30" "$MS_STATE" "Planned")
+$MCLI mutation run add_milestone \
+  --var parent="$PROJ_AUTH" \
+  --var name="Legacy service decommissioned" \
+  --var cols="$MILESTONE_COLS" | $JQ -r '.data.create_subitem.id' > /dev/null
+echo "  Legacy service decommissioned — due 2026-06-30 — Planned"
+
+MILESTONE_COLS=$(printf '{ "%s": {"date": "%s"}, "%s": {"label": "%s"} }' "$MS_DUE" "2026-04-10" "$MS_STATE" "Missed")
+$MCLI mutation run add_milestone \
+  --var parent="$PROJ_DATA" \
+  --var name="Schema freeze" \
+  --var cols="$MILESTONE_COLS" | $JQ -r '.data.create_subitem.id' > /dev/null
+echo "  Schema freeze (Data lake migration) — due 2026-04-10 — Missed"
+
+# A missed milestone drives the project — and then the portfolio — off Green.
+HEALTH_COLS=$(printf '{ "%s": {"label": "Red"}, "%s": {"text": "%s"} }' \
+  "$PROJ_RAG" "$PROJ_NOTES" "Schema freeze missed; downstream ETL rework needed. Escalated to steering.")
+$MCLI mutation run set_project_health \
+  --var board="$PROJECTS_BOARD" \
+  --var item="$PROJ_DATA" \
+  --var cols="$HEALTH_COLS" | $JQ -r '.data' > /dev/null
+echo "Data lake migration RAG → Red"
+
+$MCLI item post-update "$PROJ_DATA" \
+  --body "RAG → Red: schema freeze slipped, ETL rework in scope. Recovery plan at next steering." > /dev/null
+$MCLI item description "$PROJ_DATA" \
+  --set "Migration of the analytics estate onto the new data lake. Steering: monthly." > /dev/null
+echo "Escalation update + project brief posted"
+
+PF_COLS=$(printf '{ "%s": {"label": "At Risk"} }' "$PF_HEALTH")
+$MCLI mutation run set_portfolio_health \
+  --var board="$PORTFOLIOS_BOARD" \
+  --var item="$PF_PLATFORM" \
+  --var cols="$PF_COLS" | $JQ -r '.data' > /dev/null
+echo "Platform Modernization portfolio health → At Risk"
+
+# ─── Phase 6: Rollup Queries ─────────────────────────────────────────────────
+
+echo ""
+echo "=== Phase 6: Rollups ==="
+
+echo "--- Projects in Platform Modernization (group-scoped) ---"
+$MCLI item list --board "$PROJECTS_BOARD" --group "$GROUP_PLATFORM" --limit 100 --pretty
+
+echo ""
+echo "--- Same, via the semantic layer ---"
+$MCLI query run projects_in_portfolio \
+  --var boardId="$PROJECTS_BOARD" \
+  --var groupIds="$(printf '["%s"]' "$GROUP_PLATFORM")" --pretty
+
+echo ""
+echo "--- Projects joined by portfolio name ---"
+$MCLI item find --board "$PROJECTS_BOARD" --column "$PROJ_PORTFOLIO" --value "Platform Modernization" --pretty
+
+echo ""
+echo "--- At-risk projects (status columns match on label text) ---"
+$MCLI item find --board "$PROJECTS_BOARD" --column "$PROJ_RAG" --value "Red" --pretty
+$MCLI item find --board "$PROJECTS_BOARD" --column "$PROJ_RAG" --value "Amber" --pretty
+
+echo ""
+echo "--- At-risk projects in one pass (decoded column values) ---"
+$MCLI item list --board "$PROJECTS_BOARD" --limit 100 \
+  | $JQ --arg rag "$PROJ_RAG" '
+      .items[]
+      | select(any(.columns[]; .id == $rag and (.value == "Red" or .value == "Amber")))
+      | {id, name, portfolio: .group.title}'
+
+echo ""
+echo "--- Portfolio rollup: worst RAG and mean completion per portfolio group ---"
+$MCLI item list --board "$PROJECTS_BOARD" --limit 100 \
+  | $JQ --arg rag "$PROJ_RAG" --arg pct "$PROJ_COMPLETE" '
+      def col($id): [.columns[] | select(.id == $id) | .value] | first;
+      [.items[] | {portfolio: .group.title, rag: col($rag), pct: col($pct)}]
+      | group_by(.portfolio)[]
+      | { portfolio: .[0].portfolio,
+          projects: length,
+          worst_rag: (if any(.[]; .rag == "Red") then "Red"
+                      elif any(.[]; .rag == "Amber") then "Amber"
+                      else "Green" end),
+          avg_complete: (([.[].pct // 0] | add) / length) }'
+
+echo ""
+echo "--- Milestones for Auth service rewrite ---"
+$MCLI item get "$PROJ_AUTH" --subitems --pretty
+
+echo ""
+echo "--- Every project with its milestones (--subitems is JSON-only) ---"
+$MCLI item list --board "$PROJECTS_BOARD" --subitems --limit 100 --json | $JQ '.'
+
+echo ""
+echo "=== Demo complete ==="
+echo ""
+echo "Board IDs for further exploration:"
+echo "  Portfolios: $PORTFOLIOS_BOARD"
+echo "  Projects:   $PROJECTS_BOARD (groups: platform=$GROUP_PLATFORM, cx=$GROUP_CX)"
+echo "  Milestones: $SUBITEM_BOARD (subitems of Projects)"
diff --git a/go.mod b/go.mod
index 08593d4..02f5cb8 100644
--- a/go.mod
+++ b/go.mod
@@ -7,6 +7,7 @@ require (
 	github.com/JohannesKaufmann/html-to-markdown/v2 v2.5.2
 	github.com/Khan/genqlient v0.8.1
 	github.com/spf13/cobra v1.10.2
+	github.com/spf13/pflag v1.0.9
 	github.com/vektah/gqlparser/v2 v2.5.19
 	github.com/zalando/go-keyring v0.2.8
 	gopkg.in/yaml.v3 v3.0.1
@@ -29,7 +30,6 @@ require (
 	github.com/mattn/go-isatty v0.0.22 // indirect
 	github.com/ncruces/go-strftime v1.0.0 // indirect
 	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
-	github.com/spf13/pflag v1.0.9 // indirect
 	golang.org/x/crypto v0.52.0 // indirect
 	golang.org/x/mod v0.33.0 // indirect
 	golang.org/x/net v0.55.0 // indirect
diff --git a/internal/api/gen/generated.go b/internal/api/gen/generated.go
index 60cf7cc..7c0461b 100644
--- a/internal/api/gen/generated.go
+++ b/internal/api/gen/generated.go
@@ -72,6 +72,8 @@ type BoardColumnCreateCreate_columnColumn struct {
 	Title string `json:"title"`
 	// The column's type.
 	Type ColumnType `json:"type"`
+	// The column's description.
+	Description string `json:"description"`
 	// The column's settings in a string form.
 	Settings_str string `json:"settings_str"`
 	// The column's width.
@@ -89,6 +91,9 @@ func (v *BoardColumnCreateCreate_columnColumn) GetTitle() string { return v.Titl
 // GetType returns BoardColumnCreateCreate_columnColumn.Type, and is useful for accessing the field via an interface.
 func (v *BoardColumnCreateCreate_columnColumn) GetType() ColumnType { return v.Type }
 
+// GetDescription returns BoardColumnCreateCreate_columnColumn.Description, and is useful for accessing the field via an interface.
+func (v *BoardColumnCreateCreate_columnColumn) GetDescription() string { return v.Description }
+
 // GetSettings_str returns BoardColumnCreateCreate_columnColumn.Settings_str, and is useful for accessing the field via an interface.
 func (v *BoardColumnCreateCreate_columnColumn) GetSettings_str() string { return v.Settings_str }
 
@@ -142,6 +147,8 @@ type BoardColumnDescribeChange_column_metadataColumn struct {
 	Title string `json:"title"`
 	// The column's type.
 	Type ColumnType `json:"type"`
+	// The column's description.
+	Description string `json:"description"`
 	// The column's settings in a string form.
 	Settings_str string `json:"settings_str"`
 	// The column's width.
@@ -159,6 +166,11 @@ func (v *BoardColumnDescribeChange_column_metadataColumn) GetTitle() string { re
 // GetType returns BoardColumnDescribeChange_column_metadataColumn.Type, and is useful for accessing the field via an interface.
 func (v *BoardColumnDescribeChange_column_metadataColumn) GetType() ColumnType { return v.Type }
 
+// GetDescription returns BoardColumnDescribeChange_column_metadataColumn.Description, and is useful for accessing the field via an interface.
+func (v *BoardColumnDescribeChange_column_metadataColumn) GetDescription() string {
+	return v.Description
+}
+
 // GetSettings_str returns BoardColumnDescribeChange_column_metadataColumn.Settings_str, and is useful for accessing the field via an interface.
 func (v *BoardColumnDescribeChange_column_metadataColumn) GetSettings_str() string {
 	return v.Settings_str
@@ -208,6 +220,8 @@ type BoardColumnListBoardsBoardColumnsColumn struct {
 	Title string `json:"title"`
 	// The column's type.
 	Type ColumnType `json:"type"`
+	// The column's description.
+	Description string `json:"description"`
 	// The column's settings in a string form.
 	Settings_str string `json:"settings_str"`
 	// The column's width.
@@ -225,6 +239,9 @@ func (v *BoardColumnListBoardsBoardColumnsColumn) GetTitle() string { return v.T
 // GetType returns BoardColumnListBoardsBoardColumnsColumn.Type, and is useful for accessing the field via an interface.
 func (v *BoardColumnListBoardsBoardColumnsColumn) GetType() ColumnType { return v.Type }
 
+// GetDescription returns BoardColumnListBoardsBoardColumnsColumn.Description, and is useful for accessing the field via an interface.
+func (v *BoardColumnListBoardsBoardColumnsColumn) GetDescription() string { return v.Description }
+
 // GetSettings_str returns BoardColumnListBoardsBoardColumnsColumn.Settings_str, and is useful for accessing the field via an interface.
 func (v *BoardColumnListBoardsBoardColumnsColumn) GetSettings_str() string { return v.Settings_str }
 
@@ -251,6 +268,8 @@ type BoardColumnRenameChange_column_titleColumn struct {
 	Title string `json:"title"`
 	// The column's type.
 	Type ColumnType `json:"type"`
+	// The column's description.
+	Description string `json:"description"`
 	// The column's settings in a string form.
 	Settings_str string `json:"settings_str"`
 	// The column's width.
@@ -268,6 +287,9 @@ func (v *BoardColumnRenameChange_column_titleColumn) GetTitle() string { return
 // GetType returns BoardColumnRenameChange_column_titleColumn.Type, and is useful for accessing the field via an interface.
 func (v *BoardColumnRenameChange_column_titleColumn) GetType() ColumnType { return v.Type }
 
+// GetDescription returns BoardColumnRenameChange_column_titleColumn.Description, and is useful for accessing the field via an interface.
+func (v *BoardColumnRenameChange_column_titleColumn) GetDescription() string { return v.Description }
+
 // GetSettings_str returns BoardColumnRenameChange_column_titleColumn.Settings_str, and is useful for accessing the field via an interface.
 func (v *BoardColumnRenameChange_column_titleColumn) GetSettings_str() string { return v.Settings_str }
 
@@ -432,6 +454,8 @@ type BoardGetBoardsBoardColumnsColumn struct {
 	Title string `json:"title"`
 	// The column's type.
 	Type ColumnType `json:"type"`
+	// The column's description.
+	Description string `json:"description"`
 	// The column's settings in a string form.
 	Settings_str string `json:"settings_str"`
 	// The column's width.
@@ -449,6 +473,9 @@ func (v *BoardGetBoardsBoardColumnsColumn) GetTitle() string { return v.Title }
 // GetType returns BoardGetBoardsBoardColumnsColumn.Type, and is useful for accessing the field via an interface.
 func (v *BoardGetBoardsBoardColumnsColumn) GetType() ColumnType { return v.Type }
 
+// GetDescription returns BoardGetBoardsBoardColumnsColumn.Description, and is useful for accessing the field via an interface.
+func (v *BoardGetBoardsBoardColumnsColumn) GetDescription() string { return v.Description }
+
 // GetSettings_str returns BoardGetBoardsBoardColumnsColumn.Settings_str, and is useful for accessing the field via an interface.
 func (v *BoardGetBoardsBoardColumnsColumn) GetSettings_str() string { return v.Settings_str }
 
@@ -21662,6 +21689,7 @@ mutation BoardColumnCreate ($boardId: ID!, $title: String!, $columnType: ColumnT
 		id
 		title
 		type
+		description
 		settings_str
 		width
 		archived
@@ -21748,6 +21776,7 @@ mutation BoardColumnDescribe ($boardId: ID!, $columnId: String!, $description: S
 		id
 		title
 		type
+		description
 		settings_str
 		width
 		archived
@@ -21794,6 +21823,7 @@ query BoardColumnList ($boardId: ID!) {
 			id
 			title
 			type
+			description
 			settings_str
 			width
 			archived
@@ -21835,6 +21865,7 @@ mutation BoardColumnRename ($boardId: ID!, $columnId: String!, $title: String!)
 		id
 		title
 		type
+		description
 		settings_str
 		width
 		archived
@@ -21985,6 +22016,7 @@ query BoardGet ($id: ID!, $withItems: Boolean! = false, $itemsLimit: Int! = 25,
 			id
 			title
 			type
+			description
 			settings_str
 			width
 			archived
diff --git a/internal/api/items/columns/columns.go b/internal/api/items/columns/columns.go
index f39d302..ef2ade8 100644
--- a/internal/api/items/columns/columns.go
+++ b/internal/api/items/columns/columns.go
@@ -1,7 +1,12 @@
-// Package columns decodes monday.com column values from their raw JSON representation
-// into clean, typed Go values suitable for JSON output.
+// Package columns converts monday.com column values between their raw JSON wire
+// representation and clean Go values.
 //
-// The write path is JSON-passthrough (handled elsewhere). This package is read-path only.
+// Decode (this file) is the read path: raw column JSON → typed value for output.
+// Encode (encode.go) is the write path for the CLI's typed shorthands: a scalar like
+// "Done" or "2026-05-10" → the wire JSON monday expects. The two share one set of
+// column types on purpose, so a shape documented on the read side is the shape
+// written on the write side. Column types with no encoder are still written as raw
+// JSON by the caller (mcli's --col escape hatch).
 package columns
 
 import (
diff --git a/internal/api/items/columns/encode.go b/internal/api/items/columns/encode.go
new file mode 100644
index 0000000..b3af9a5
--- /dev/null
+++ b/internal/api/items/columns/encode.go
@@ -0,0 +1,218 @@
+package columns
+
+import (
+	"encoding/json"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/mondaycom/mcli/internal/errs"
+)
+
+// encoderFn builds the monday wire JSON for one column type from a human-friendly
+// input string. settingsStr is the column's settings_str, used for validation.
+type encoderFn func(settingsStr, input string) (json.RawMessage, error)
+
+// encoders maps monday column types to write-side encoders. Every key here must
+// also have a read-side decoder in registry, so the two halves of a column type
+// cannot drift apart (enforced by TestEncoders_HaveDecoders).
+//
+// This set is deliberately small: it covers the types whose wire shape is
+// unambiguous from a single scalar. Everything else is written through the raw
+// escape hatch, where the caller supplies the JSON.
+var encoders = map[string]encoderFn{
+	"text":     encodeText,
+	"status":   encodeStatus,
+	"date":     encodeDate,
+	"numbers":  encodeNumbers,
+	"checkbox": encodeCheckbox,
+}
+
+// EncodableTypes returns the column types Encode supports, sorted.
+func EncodableTypes() []string {
+	out := make([]string, 0, len(encoders))
+	for t := range encoders {
+		out = append(out, t)
+	}
+	sort.Strings(out)
+	return out
+}
+
+// Encode builds the monday wire JSON for a column write from a human-friendly value.
+//
+// columnType is the column's type as monday reports it; settingsStr is the column's
+// settings_str; input is the caller's value (e.g. "Done", "2026-05-10", "true").
+//
+// Validation is the point, not a bonus: every mcli item mutation sends
+// create_labels_if_missing, so an unvalidated status typo silently creates a new
+// label on the board instead of failing. Encode rejects values the column cannot
+// hold, with errs.Usage, before any request is built.
+func Encode(columnType, settingsStr, input string) (json.RawMessage, error) {
+	fn, ok := encoders[columnType]
+	if !ok {
+		return nil, errs.Usage("no shorthand for column type %q: use --col <id>=<json>", columnType)
+	}
+	return fn(settingsStr, input)
+}
+
+// encodeText writes a "text" column. Wire shape: a bare JSON string.
+func encodeText(_ string, input string) (json.RawMessage, error) {
+	b, err := json.Marshal(input)
+	if err != nil {
+		return nil, errs.Usage("text: %v", err)
+	}
+	return b, nil
+}
+
+// encodeStatus writes a "status" column. Wire shape: {"label":"Done"}.
+// The label is matched against the column's configured labels — exactly first, then
+// case-insensitively, adopting the board's own casing on a case-insensitive hit.
+func encodeStatus(settingsStr, input string) (json.RawMessage, error) {
+	label := strings.TrimSpace(input)
+	if label == "" {
+		return nil, errs.Usage("status: label must not be empty")
+	}
+
+	// An unparseable or absent settings_str means we cannot validate. Write anyway
+	// rather than blocking the caller on metadata we failed to read.
+	if labels := statusLabels(settingsStr); len(labels) > 0 {
+		match, ok := matchLabel(labels, label)
+		if !ok {
+			return nil, errs.Usage("status: %q is not a label on this column; available: %s",
+				label, strings.Join(labels, ", "))
+		}
+		label = match
+	}
+
+	return json.Marshal(map[string]string{"label": label})
+}
+
+// statusLabels returns a status column's labels in index order. It handles both
+// shapes monday uses: the index→name object and the dropdown-style array.
+func statusLabels(settingsStr string) []string {
+	if settingsStr == "" {
+		return nil
+	}
+
+	var asObject struct {
+		Labels map[string]string `json:"labels"`
+	}
+	if err := json.Unmarshal([]byte(settingsStr), &asObject); err == nil && len(asObject.Labels) > 0 {
+		keys := make([]string, 0, len(asObject.Labels))
+		for k := range asObject.Labels {
+			keys = append(keys, k)
+		}
+		sort.Slice(keys, func(i, j int) bool {
+			ni, erri := strconv.Atoi(keys[i])
+			nj, errj := strconv.Atoi(keys[j])
+			if erri == nil && errj == nil {
+				return ni < nj
+			}
+			return keys[i] < keys[j]
+		})
+		out := make([]string, 0, len(keys))
+		for _, k := range keys {
+			if name := asObject.Labels[k]; name != "" {
+				out = append(out, name)
+			}
+		}
+		return out
+	}
+
+	var asArray dropdownSettings
+	if err := json.Unmarshal([]byte(settingsStr), &asArray); err == nil {
+		out := make([]string, 0, len(asArray.Labels))
+		for _, l := range asArray.Labels {
+			if l.Name != "" {
+				out = append(out, l.Name)
+			}
+		}
+		return out
+	}
+
+	return nil
+}
+
+// matchLabel finds want among labels, preferring an exact match and falling back to
+// a case-insensitive one. It returns the board's spelling, not the caller's.
+func matchLabel(labels []string, want string) (string, bool) {
+	for _, l := range labels {
+		if l == want {
+			return l, true
+		}
+	}
+	for _, l := range labels {
+		if strings.EqualFold(l, want) {
+			return l, true
+		}
+	}
+	return "", false
+}
+
+// dateLayouts are the input forms encodeDate accepts, most specific first.
+var dateLayouts = []string{
+	time.RFC3339,
+	"2006-01-02T15:04:05",
+	"2006-01-02T15:04",
+	"2006-01-02 15:04:05",
+	"2006-01-02 15:04",
+	"2006-01-02",
+}
+
+// encodeDate writes a "date" column. Wire shape: {"date":"2026-05-10"}, plus
+// {"time":"14:30:00"} when the input carries a time. monday stores date-column
+// times in UTC, so a zoned input is converted.
+func encodeDate(_ string, input string) (json.RawMessage, error) {
+	s := strings.TrimSpace(input)
+	if s == "" {
+		return nil, errs.Usage("date: value must not be empty")
+	}
+
+	for _, layout := range dateLayouts {
+		t, err := time.Parse(layout, s)
+		if err != nil {
+			continue
+		}
+		if layout == "2006-01-02" {
+			return json.Marshal(map[string]string{"date": t.Format("2006-01-02")})
+		}
+		t = t.UTC()
+		return json.Marshal(map[string]string{
+			"date": t.Format("2006-01-02"),
+			"time": t.Format("15:04:05"),
+		})
+	}
+
+	return nil, errs.Usage("date: %q is not a date; use 2026-05-10, 2026-05-10T14:30, or an RFC3339 timestamp", s)
+}
+
+// encodeNumbers writes a "numbers" column. Wire shape: a JSON string holding the
+// number, e.g. "42". The caller's own formatting is preserved once it parses.
+func encodeNumbers(_ string, input string) (json.RawMessage, error) {
+	s := strings.TrimSpace(input)
+	if s == "" {
+		// An empty numbers column is written as an empty string, which clears it.
+		return json.RawMessage(`""`), nil
+	}
+	if _, err := strconv.ParseFloat(s, 64); err != nil {
+		return nil, errs.Usage("number: %q is not numeric", s)
+	}
+	return json.Marshal(s)
+}
+
+// encodeCheckbox writes a "checkbox" column. Wire shape: {"checked":"true"}.
+func encodeCheckbox(_ string, input string) (json.RawMessage, error) {
+	s := strings.ToLower(strings.TrimSpace(input))
+	switch s {
+	case "yes", "y":
+		s = "true"
+	case "no", "n":
+		s = "false"
+	}
+	b, err := strconv.ParseBool(s)
+	if err != nil {
+		return nil, errs.Usage("checkbox: %q is not a boolean; use true or false", input)
+	}
+	return json.Marshal(map[string]string{"checked": strconv.FormatBool(b)})
+}
diff --git a/internal/api/items/columns/encode_test.go b/internal/api/items/columns/encode_test.go
new file mode 100644
index 0000000..f6375cc
--- /dev/null
+++ b/internal/api/items/columns/encode_test.go
@@ -0,0 +1,177 @@
+package columns
+
+import (
+	"encoding/json"
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/mondaycom/mcli/internal/errs"
+)
+
+// codeOf returns an error's errs code, or "" if it is not an *errs.Error.
+func codeOf(err error) errs.Code {
+	if e, ok := errors.AsType[*errs.Error](err); ok {
+		return e.Code
+	}
+	return ""
+}
+
+// statusSettingsObject is the index→name form monday uses for status columns.
+const statusSettingsObject = `{"labels":{"0":"Not Started","1":"Working on it","2":"Done"}}`
+
+// statusSettingsArray is the id/name array form some columns report instead.
+const statusSettingsArray = `{"labels":[{"id":1,"name":"Open"},{"id":2,"name":"Closed"}]}`
+
+func TestEncode_ok(t *testing.T) {
+	tests := []struct {
+		name       string
+		columnType string
+		settings   string
+		input      string
+		want       string
+	}{
+		{name: "text", columnType: "text", input: "Follow up", want: `"Follow up"`},
+		{name: "text empty clears", columnType: "text", input: "", want: `""`},
+		{name: "status exact", columnType: "status", settings: statusSettingsObject, input: "Done", want: `{"label":"Done"}`},
+		{
+			name: "status case-insensitive adopts board casing", columnType: "status",
+			settings: statusSettingsObject, input: "done", want: `{"label":"Done"}`,
+		},
+		{name: "status array settings", columnType: "status", settings: statusSettingsArray, input: "closed", want: `{"label":"Closed"}`},
+		{name: "status unvalidated without settings", columnType: "status", input: "Whatever", want: `{"label":"Whatever"}`},
+		{name: "date only", columnType: "date", input: "2026-05-10", want: `{"date":"2026-05-10"}`},
+		{name: "date and time", columnType: "date", input: "2026-05-10T14:30", want: `{"date":"2026-05-10","time":"14:30:00"}`},
+		{name: "date space separated", columnType: "date", input: "2026-05-10 14:30:05", want: `{"date":"2026-05-10","time":"14:30:05"}`},
+		{
+			name: "rfc3339 converts to utc", columnType: "date",
+			input: "2026-05-10T14:30:00+03:00", want: `{"date":"2026-05-10","time":"11:30:00"}`,
+		},
+		{name: "numbers int", columnType: "numbers", input: "42", want: `"42"`},
+		{name: "numbers float", columnType: "numbers", input: "42.5", want: `"42.5"`},
+		{name: "numbers negative", columnType: "numbers", input: "-7", want: `"-7"`},
+		{name: "numbers empty clears", columnType: "numbers", input: "", want: `""`},
+		{name: "checkbox true", columnType: "checkbox", input: "true", want: `{"checked":"true"}`},
+		{name: "checkbox yes", columnType: "checkbox", input: "yes", want: `{"checked":"true"}`},
+		{name: "checkbox n", columnType: "checkbox", input: "n", want: `{"checked":"false"}`},
+		{name: "checkbox 0", columnType: "checkbox", input: "0", want: `{"checked":"false"}`},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := Encode(tt.columnType, tt.settings, tt.input)
+			if err != nil {
+				t.Fatalf("Encode(%q, %q) error: %v", tt.columnType, tt.input, err)
+			}
+			if string(got) != tt.want {
+				t.Errorf("Encode(%q, %q) = %s, want %s", tt.columnType, tt.input, got, tt.want)
+			}
+			if !json.Valid(got) {
+				t.Errorf("Encode(%q, %q) produced invalid JSON: %s", tt.columnType, tt.input, got)
+			}
+		})
+	}
+}
+
+func TestEncode_usageErrors(t *testing.T) {
+	tests := []struct {
+		name       string
+		columnType string
+		settings   string
+		input      string
+	}{
+		{name: "unknown column type", columnType: "mirror", input: "x"},
+		{name: "status label not on column", columnType: "status", settings: statusSettingsObject, input: "Nearly Done"},
+		{name: "status empty", columnType: "status", settings: statusSettingsObject, input: ""},
+		{name: "date empty", columnType: "date", input: ""},
+		{name: "date malformed", columnType: "date", input: "next tuesday"},
+		{name: "date day-month order", columnType: "date", input: "10/05/2026"},
+		{name: "numbers not numeric", columnType: "numbers", input: "many"},
+		{name: "checkbox not boolean", columnType: "checkbox", input: "maybe"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := Encode(tt.columnType, tt.settings, tt.input)
+			if err == nil {
+				t.Fatalf("Encode(%q, %q) = %s, want an error", tt.columnType, tt.input, got)
+			}
+			// The caller maps these straight to an exit code; a mislabelled encoder
+			// error would exit 5 (internal) on what is a caller mistake.
+			if code := codeOf(err); code != errs.CodeUsage {
+				t.Errorf("Encode(%q, %q) code = %s, want %s", tt.columnType, tt.input, code, errs.CodeUsage)
+			}
+		})
+	}
+}
+
+// TestEncode_statusErrorListsLabels checks the error is actionable: an agent that
+// guessed a label needs to see the real ones, not just "invalid".
+func TestEncode_statusErrorListsLabels(t *testing.T) {
+	_, err := Encode("status", statusSettingsObject, "Nearly Done")
+	if err == nil {
+		t.Fatal("want an error")
+	}
+	for _, label := range []string{"Not Started", "Working on it", "Done"} {
+		if !strings.Contains(err.Error(), label) {
+			t.Errorf("error %q does not name label %q", err.Error(), label)
+		}
+	}
+}
+
+// TestEncoders_HaveDecoders guards the invariant stated in encoders' doc comment: a
+// type mcli can write is a type mcli can read back, so a round-trip cannot lose data.
+func TestEncoders_HaveDecoders(t *testing.T) {
+	for _, ct := range EncodableTypes() {
+		if _, ok := registry[ct]; !ok {
+			t.Errorf("column type %q has an encoder but no decoder", ct)
+		}
+	}
+}
+
+// TestStatusLabels covers settings_str shapes, including the ones we cannot parse —
+// there, no labels means "write it unvalidated" rather than "reject everything".
+func TestStatusLabels(t *testing.T) {
+	tests := []struct {
+		name     string
+		settings string
+		want     []string
+	}{
+		{name: "empty", settings: "", want: nil},
+		{name: "object form in index order", settings: statusSettingsObject, want: []string{"Not Started", "Working on it", "Done"}},
+		{name: "array form", settings: statusSettingsArray, want: []string{"Open", "Closed"}},
+		{name: "unparseable", settings: "not json", want: nil},
+		{name: "no labels key", settings: `{"labels_colors":{}}`, want: nil},
+		{name: "blank labels dropped", settings: `{"labels":{"0":"","1":"Done"}}`, want: []string{"Done"}},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := statusLabels(tt.settings)
+			if len(got) != len(tt.want) {
+				t.Fatalf("statusLabels(%q) = %v, want %v", tt.settings, got, tt.want)
+			}
+			for i := range got {
+				if got[i] != tt.want[i] {
+					t.Fatalf("statusLabels(%q) = %v, want %v", tt.settings, got, tt.want)
+				}
+			}
+		})
+	}
+}
+
+// TestEncode_statusRoundTripsThroughDecode is the practical form of the
+// encoder/decoder pairing: what we write is what a later read reports.
+func TestEncode_statusRoundTripsThroughDecode(t *testing.T) {
+	raw, err := Encode("status", statusSettingsObject, "working on IT")
+	if err != nil {
+		t.Fatalf("Encode: %v", err)
+	}
+	decoded, err := Decode("status", statusSettingsObject, string(raw))
+	if err != nil {
+		t.Fatalf("Decode: %v", err)
+	}
+	if decoded.Value != "Working on it" {
+		t.Errorf("round trip = %v, want %q", decoded.Value, "Working on it")
+	}
+}
diff --git a/internal/api/queries/boards.graphql b/internal/api/queries/boards.graphql
index 31dc2e9..67c9791 100644
--- a/internal/api/queries/boards.graphql
+++ b/internal/api/queries/boards.graphql
@@ -75,6 +75,7 @@ query BoardGet(
       id
       title
       type
+      description
       settings_str
       width
       archived
@@ -181,6 +182,7 @@ query BoardColumnList($boardId: ID!) {
       id
       title
       type
+      description
       settings_str
       width
       archived
@@ -202,6 +204,7 @@ mutation BoardColumnCreate(
     id
     title
     type
+    description
     settings_str
     width
     archived
@@ -222,6 +225,7 @@ mutation BoardColumnRename($boardId: ID!, $columnId: String!, $title: String!) {
     id
     title
     type
+    description
     settings_str
     width
     archived
@@ -234,6 +238,7 @@ mutation BoardColumnDescribe($boardId: ID!, $columnId: String!, $description: St
     id
     title
     type
+    description
     settings_str
     width
     archived
diff --git a/internal/api/schema/schema.go b/internal/api/schema/schema.go
index bf4fd6a..dac30f1 100644
--- a/internal/api/schema/schema.go
+++ b/internal/api/schema/schema.go
@@ -33,12 +33,21 @@ type ArgDef struct {
 	DefaultValue string
 }
 
+// Source values reported by LoadedSource.
+const (
+	// SourceCached means a locally refreshed schema.graphql was parsed and used.
+	SourceCached = "cached"
+	// SourceEmbedded means the SDL compiled into the binary was used.
+	SourceEmbedded = "embedded"
+)
+
 var (
 	mu           sync.Mutex
 	cachedSchema *ast.Schema
 	cacheErr     error
 	cacheDir     string
 	cacheLoaded  bool
+	loadedSource string
 )
 
 // SetConfigDir sets the directory used to locate a cached schema.graphql file.
@@ -79,6 +88,8 @@ func Load() (*ast.Schema, error) {
 			s, err = gqlparser.LoadSchema(src)
 			if err != nil {
 				err = fmt.Errorf("parse local schema: %w", err)
+			} else {
+				loadedSource = SourceCached
 			}
 		}
 	}
@@ -89,6 +100,7 @@ func Load() (*ast.Schema, error) {
 		if err != nil {
 			err = fmt.Errorf("parse schema: %w", err)
 		}
+		loadedSource = SourceEmbedded
 	}
 
 	cachedSchema = s
@@ -98,6 +110,19 @@ func Load() (*ast.Schema, error) {
 	return cachedSchema, cacheErr
 }
 
+// LoadedSource reports which SDL Load actually parsed: SourceCached or
+// SourceEmbedded. It matters because a cached schema.graphql that exists but
+// fails to parse is silently ignored in favour of the embedded copy, so the
+// presence of the file is not proof that it is in use.
+func LoadedSource() (string, error) {
+	if _, err := Load(); err != nil {
+		return "", err
+	}
+	mu.Lock()
+	defer mu.Unlock()
+	return loadedSource, nil
+}
+
 // QueryFields returns FieldDef for each field on the Query type.
 func QueryFields() ([]FieldDef, error) {
 	s, err := Load()
diff --git a/internal/cli/api.go b/internal/cli/api.go
index 2363c63..69c13ca 100644
--- a/internal/cli/api.go
+++ b/internal/cli/api.go
@@ -56,6 +56,11 @@ Example:
     --arg column_id=status --arg value='{"label":"Done"}'`,
 		Args:               cobra.ArbitraryArgs,
 		DisableFlagParsing: false,
+		// Every 'api' operation is generated from the schema, so a stale schema
+		// silently misrepresents the API surface. Warn on stderr, never stdout.
+		PersistentPreRun: func(cmd *cobra.Command, _ []string) {
+			warnIfSchemaStale(cmd)
+		},
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if len(args) == 0 {
 				return errs.Usage("provide an operation name, or use 'mcli api list'")
diff --git a/internal/cli/api_list.go b/internal/cli/api_list.go
index bf5eed4..c766a3f 100644
--- a/internal/cli/api_list.go
+++ b/internal/cli/api_list.go
@@ -6,6 +6,7 @@ import (
 	"sort"
 	"strings"
 	"text/tabwriter"
+	"unicode/utf8"
 
 	"github.com/spf13/cobra"
 
@@ -116,8 +117,10 @@ func runAPIList(cmd *cobra.Command, typeFilter string, noBuiltins bool, jsonOut
 func truncate(s string, max int) string {
 	// Collapse whitespace / newlines in descriptions.
 	s = strings.Join(strings.Fields(s), " ")
-	if len(s) <= max {
+	// Count runes, not bytes: column descriptions are user-authored and may be
+	// non-ASCII, where byte slicing would split a rune and emit a replacement char.
+	if utf8.RuneCountInString(s) <= max {
 		return s
 	}
-	return s[:max-1] + "…"
+	return string([]rune(s)[:max-1]) + "…"
 }
diff --git a/internal/cli/board.go b/internal/cli/board.go
index 3038235..154ce13 100644
--- a/internal/cli/board.go
+++ b/internal/cli/board.go
@@ -190,7 +190,7 @@ type boardGetOutput struct {
 	Workspace   *boardWorkspace `json:"workspace,omitempty"`
 	Owners      []boardOwner    `json:"owners"`
 	Groups      []boardGroup    `json:"groups"`
-	Columns     []boardColumn   `json:"columns"`
+	Columns     []columnOutput  `json:"columns"`
 	// Items and ItemsCursor are populated only with --items; both are omitted
 	// otherwise (additive per axiom A6).
 	Items       []itemListOutputItem `json:"items,omitempty"`
@@ -215,15 +215,6 @@ type boardGroup struct {
 	Position string `json:"position"`
 }
 
-type boardColumn struct {
-	ID          string `json:"id"`
-	Title       string `json:"title"`
-	Type        string `json:"type"`
-	SettingsStr string `json:"settings_str"`
-	Width       int    `json:"width"`
-	Archived    bool   `json:"archived"`
-}
-
 func newBoardGetCmd() *cobra.Command {
 	var (
 		withItems   bool
@@ -391,7 +382,7 @@ func runBoardGet(cmd *cobra.Command, id string, withItems bool, itemsLimit int,
 		WorkspaceID: b.Workspace_id,
 		Owners:      make([]boardOwner, len(b.Owners)),
 		Groups:      make([]boardGroup, len(b.Groups)),
-		Columns:     make([]boardColumn, len(b.Columns)),
+		Columns:     make([]columnOutput, len(b.Columns)),
 	}
 
 	if b.Workspace.Id != "" {
@@ -414,10 +405,11 @@ func runBoardGet(cmd *cobra.Command, id string, withItems bool, itemsLimit int,
 		}
 	}
 	for i, c := range b.Columns {
-		out.Columns[i] = boardColumn{
+		out.Columns[i] = columnOutput{
 			ID:          c.Id,
 			Title:       c.Title,
 			Type:        string(c.Type),
+			Description: c.Description,
 			SettingsStr: c.Settings_str,
 			Width:       c.Width,
 			Archived:    c.Archived,
@@ -478,12 +470,9 @@ func runBoardGet(cmd *cobra.Command, id string, withItems bool, itemsLimit int,
 
 	if len(out.Columns) > 0 {
 		_, _ = fmt.Fprintf(o, "\nColumns (%d):\n", len(out.Columns))
-		tw := tabwriter.NewWriter(o, 0, 0, 2, ' ', 0)
-		_, _ = fmt.Fprintln(tw, "  ID\tTITLE\tTYPE\tARCHIVED")
-		for _, c := range out.Columns {
-			_, _ = fmt.Fprintf(tw, "  %s\t%s\t%s\t%v\n", c.ID, c.Title, c.Type, c.Archived)
+		if err := writeColumnsTable(o, out.Columns, "  "); err != nil {
+			return errs.Internal("flush columns table: %v", err)
 		}
-		_ = tw.Flush()
 	}
 
 	if withItems {
diff --git a/internal/cli/board_column.go b/internal/cli/board_column.go
index 1d04888..d2f5a50 100644
--- a/internal/cli/board_column.go
+++ b/internal/cli/board_column.go
@@ -3,6 +3,7 @@ package cli
 import (
 	"encoding/json"
 	"fmt"
+	"io"
 	"os"
 	"strings"
 	"text/tabwriter"
@@ -91,6 +92,7 @@ type columnOutput struct {
 	ID          string `json:"id"`
 	Title       string `json:"title"`
 	Type        string `json:"type"`
+	Description string `json:"description,omitempty"`
 	SettingsStr string `json:"settings_str"`
 	Width       int    `json:"width"`
 	Archived    bool   `json:"archived"`
@@ -147,6 +149,7 @@ func runBoardColumnList(cmd *cobra.Command, boardID string) error {
 			ID:          c.Id,
 			Title:       c.Title,
 			Type:        string(c.Type),
+			Description: c.Description,
 			SettingsStr: c.Settings_str,
 			Width:       c.Width,
 			Archived:    c.Archived,
@@ -169,10 +172,30 @@ func runBoardColumnList(cmd *cobra.Command, boardID string) error {
 		return err
 	}
 
-	w := tabwriter.NewWriter(cmd.OutOrStdout(), 0, 0, 2, ' ', 0)
-	_, _ = fmt.Fprintln(w, "ID\tTITLE\tTYPE\tARCHIVED")
-	for _, c := range items {
-		_, _ = fmt.Fprintf(w, "%s\t%s\t%s\t%v\n", c.ID, c.Title, c.Type, c.Archived)
+	return writeColumnsTable(cmd.OutOrStdout(), items, "")
+}
+
+// writeColumnDescriptionLine renders a column's description under a single-object
+// summary, matching between 'column create' and 'column describe'. Unlike the table
+// it is not truncated: there is one column in view and room to read it.
+func writeColumnDescriptionLine(o io.Writer, description string) error {
+	if description == "" {
+		return nil
+	}
+	_, err := fmt.Fprintf(o, "  description: %s\n", description)
+	return err
+}
+
+// writeColumnsTable renders the column table shared by 'board column list' and
+// 'board get', so the two views cannot drift apart. DESCRIPTION comes last: it is
+// the only free-text field, and trailing it keeps a long description from widening
+// every column to its left. indent prefixes each row ('board get' nests its tables).
+func writeColumnsTable(o io.Writer, cols []columnOutput, indent string) error {
+	w := tabwriter.NewWriter(o, 0, 0, 2, ' ', 0)
+	_, _ = fmt.Fprintf(w, "%sID\tTITLE\tTYPE\tARCHIVED\tDESCRIPTION\n", indent)
+	for _, c := range cols {
+		_, _ = fmt.Fprintf(w, "%s%s\t%s\t%s\t%v\t%s\n",
+			indent, c.ID, c.Title, c.Type, c.Archived, truncate(c.Description, 55))
 	}
 	return w.Flush()
 }
@@ -249,6 +272,7 @@ func runBoardColumnCreate(cmd *cobra.Command, boardID, title, columnType, descri
 		ID:          c.Id,
 		Title:       c.Title,
 		Type:        string(c.Type),
+		Description: c.Description,
 		SettingsStr: c.Settings_str,
 		Width:       c.Width,
 		Archived:    c.Archived,
@@ -268,8 +292,10 @@ func runBoardColumnCreate(cmd *cobra.Command, boardID, title, columnType, descri
 		return err
 	}
 
-	_, err = fmt.Fprintf(cmd.OutOrStdout(), "Created column %s: %s (%s)\n", out.ID, out.Title, out.Type)
-	return err
+	if _, err = fmt.Fprintf(cmd.OutOrStdout(), "Created column %s: %s (%s)\n", out.ID, out.Title, out.Type); err != nil {
+		return err
+	}
+	return writeColumnDescriptionLine(cmd.OutOrStdout(), out.Description)
 }
 
 // columnDeleteOutput is the JSON shape for column delete.
@@ -394,6 +420,7 @@ func runBoardColumnRename(cmd *cobra.Command, boardID, columnID, title string) e
 		ID:          c.Id,
 		Title:       c.Title,
 		Type:        string(c.Type),
+		Description: c.Description,
 		SettingsStr: c.Settings_str,
 		Width:       c.Width,
 		Archived:    c.Archived,
@@ -470,6 +497,7 @@ func runBoardColumnDescribe(cmd *cobra.Command, boardID, columnID, description s
 		ID:          c.Id,
 		Title:       c.Title,
 		Type:        string(c.Type),
+		Description: c.Description,
 		SettingsStr: c.Settings_str,
 		Width:       c.Width,
 		Archived:    c.Archived,
@@ -489,6 +517,8 @@ func runBoardColumnDescribe(cmd *cobra.Command, boardID, columnID, description s
 		return err
 	}
 
-	_, err = fmt.Fprintf(cmd.OutOrStdout(), "Updated description for column %s: %s\n", out.ID, out.Title)
-	return err
+	if _, err = fmt.Fprintf(cmd.OutOrStdout(), "Updated description for column %s: %s\n", out.ID, out.Title); err != nil {
+		return err
+	}
+	return writeColumnDescriptionLine(cmd.OutOrStdout(), out.Description)
 }
diff --git a/internal/cli/config.go b/internal/cli/config.go
index 978aaaa..5487fa0 100644
--- a/internal/cli/config.go
+++ b/internal/cli/config.go
@@ -10,7 +10,6 @@ import (
 	apischema "github.com/mondaycom/mcli/internal/api/schema"
 	"github.com/mondaycom/mcli/internal/config"
 	"github.com/mondaycom/mcli/internal/errs"
-	"github.com/mondaycom/mcli/internal/secrets"
 )
 
 // apiVersionRE accepts YYYY-MM calendar versions (e.g. 2026-07) or named
@@ -129,14 +128,7 @@ func runConfigSetAPIVersion(cmd *cobra.Command, cfgPath string, cfg config.Confi
 	}
 
 	// Resolve token to fetch the schema. Missing token is non-fatal: warn and return.
-	var store config.Store
-	if cfg.SecretStore != "" {
-		st, openErr := secrets.Open(cfg.SecretStore, resolveConfigDir())
-		if openErr == nil {
-			store = st
-		}
-	}
-	token, tokenErr := config.ResolveToken(cfg, globals.Token, store)
+	token, tokenErr := resolveAPIToken(cfg)
 	if tokenErr != nil {
 		_, _ = fmt.Fprintf(cmd.ErrOrStderr(),
 			"api-version saved; run 'mcli auth login' then 'mcli config set api-version %s' to refresh schema\n",
@@ -144,7 +136,7 @@ func runConfigSetAPIVersion(cmd *cobra.Command, cfgPath string, cfg config.Confi
 		return nil
 	}
 
-	sdl, fetchErr := apischema.FetchSchema(cmd.Context(), token, config.ResolveEndpoint(cfg), value)
+	schemaPath, fetchErr := fetchAndCacheSchema(cmd.Context(), cfg, value, token)
 	if fetchErr != nil {
 		// Revert the saved version.
 		cfg.APIVersion = ""
@@ -155,13 +147,6 @@ func runConfigSetAPIVersion(cmd *cobra.Command, cfgPath string, cfg config.Confi
 			value, fetchErr, config.ResolveAPIVersion(config.Config{}))
 	}
 
-	schemaPath := apischema.CachedSchemaPath(resolveConfigDir())
-	if err := os.WriteFile(schemaPath, []byte(sdl), 0o600); err != nil {
-		return errs.Internal("write schema cache: %v", err)
-	}
-
-	apischema.SetConfigDir(resolveConfigDir())
-
 	_, err := fmt.Fprintf(cmd.OutOrStdout(), "fetched schema for %s → %s\n", value, schemaPath)
 	return err
 }
diff --git a/internal/cli/item.go b/internal/cli/item.go
index 0d43734..0a30b4b 100644
--- a/internal/cli/item.go
+++ b/internal/cli/item.go
@@ -130,110 +130,202 @@ type itemWriteOutput struct {
 	ParentItem *itemWriteParent `json:"parent_item,omitempty"`
 }
 
+// itemCreateToOutput converts a create_item response to the shared output shape.
+func itemCreateToOutput(resp *gen.ItemCreateResponse) itemWriteOutput {
+	it := resp.Create_item
+	out := itemWriteOutput{ID: it.Id, Name: it.Name, State: string(it.State)}
+	if it.Board.Id != "" {
+		out.Board = &itemWriteBoard{ID: it.Board.Id, Name: it.Board.Name}
+	}
+	if it.Group.Id != "" {
+		out.Group = &itemWriteGroup{ID: it.Group.Id, Title: it.Group.Title}
+	}
+	return out
+}
+
+// subitemCreateToOutput converts a create_subitem response to the shared output shape.
+func subitemCreateToOutput(resp *gen.SubitemCreateResponse) itemWriteOutput {
+	it := resp.Create_subitem
+	out := itemWriteOutput{ID: it.Id, Name: it.Name, State: string(it.State)}
+	if it.Board.Id != "" {
+		out.Board = &itemWriteBoard{ID: it.Board.Id, Name: it.Board.Name}
+	}
+	if it.Parent_item.Id != "" {
+		out.ParentItem = &itemWriteParent{ID: it.Parent_item.Id, Name: it.Parent_item.Name}
+	}
+	return out
+}
+
+// itemUpdateToOutput converts a change_multiple_column_values response to the shared
+// output shape.
+func itemUpdateToOutput(resp *gen.ItemUpdateResponse) itemWriteOutput {
+	it := resp.Change_multiple_column_values
+	out := itemWriteOutput{ID: it.Id, Name: it.Name, State: string(it.State)}
+	if it.Board.Id != "" {
+		out.Board = &itemWriteBoard{ID: it.Board.Id, Name: it.Board.Name}
+	}
+	if it.Group.Id != "" {
+		out.Group = &itemWriteGroup{ID: it.Group.Id, Title: it.Group.Title}
+	}
+	return out
+}
+
+// checkBatchArgs validates the positional argument of a write command: either none,
+// or the batch sentinel. Anything else is a caller mistake worth naming, since a bare
+// item name as a positional arg is an easy thing to try.
+func checkBatchArgs(args []string) error {
+	if len(args) == 0 || isBatchArg(args) {
+		return nil
+	}
+	return errs.Usage("unexpected argument %q: pass %q to read rows from stdin", args[0], batchStdinSentinel)
+}
+
 // --- item create ---
 
+// itemCreateOpts holds the flags of 'mcli item create'.
+type itemCreateOpts struct {
+	boardID    string
+	parentID   string
+	name       string
+	groupID    string
+	colFlags   []string
+	dryRun     bool
+	shorthands map[string]*string
+}
+
 func newItemCreateCmd() *cobra.Command {
-	var (
-		boardID  string
-		parentID string
-		name     string
-		groupID  string
-		colFlags []string
-	)
+	opts := &itemCreateOpts{}
 
 	cmd := &cobra.Command{
-		Use:   "create",
+		Use:   "create [-]",
 		Short: "Create an item (or subitem with --parent)",
 		Long: `Create a monday.com item on a board, or a subitem under a parent item.
 
 Exactly one of --board or --parent must be provided.
-Use --col <id>=<json> to set column values; the JSON must match monday's
-column-value wire shape for the column type. Repeated --col flags are
-order-preserving; if the same column id appears twice, the last value wins.`,
-		Args: cobra.NoArgs,
-		RunE: func(cmd *cobra.Command, _ []string) error {
-			return runItemCreate(cmd, boardID, parentID, name, groupID, colFlags)
+
+Typed shorthands (--status, --date/--due, --number, --text, --checkbox) address the
+board's single column of that type, so no column id is needed. They are validated
+before anything is sent: a status label that is not on the column is rejected rather
+than created. If a board has more than one column of the type, the shorthand is
+ambiguous and errors — use --col for that write.
+
+Use --col <id>=<json> to set any column, including types with no shorthand; the JSON
+must match monday's column-value wire shape for the column type. Repeated --col flags
+are order-preserving; if the same column id appears twice, the last value wins.
+
+Pass - as the only argument to create many items from stdin, as a JSON array or one
+JSON object per line. Each row takes "name", optional "group", optional "cols", and
+the same shorthands as flags:
+
+  echo '[{"name":"Ship v1","status":"Working on it","due":"2026-05-10"}]' \
+    | mcli item create --board 123 -
+
+Rows are validated up front and sent sequentially. On partial failure the exit code is
+2 and errors[].index names the rows to retry — do not re-send the whole batch, item
+creation has no dedupe key.`,
+		Args: cobra.MaximumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return runItemCreate(cmd, args, opts)
 		},
 	}
 
-	cmd.Flags().StringVar(&boardID, "board", "", "board ID (required unless --parent is given)")
-	cmd.Flags().StringVar(&parentID, "parent", "", "parent item ID; creates a subitem when set")
-	cmd.Flags().StringVar(&name, "name", "", "item name (required)")
-	cmd.Flags().StringVar(&groupID, "group", "", "group ID (optional; ignored when --parent is given)")
-	cmd.Flags().StringArrayVar(&colFlags, "col", nil, "column value: <id>=<json> (repeatable)")
+	cmd.Flags().StringVar(&opts.boardID, "board", "", "board ID (required unless --parent is given)")
+	cmd.Flags().StringVar(&opts.parentID, "parent", "", "parent item ID; creates a subitem when set")
+	cmd.Flags().StringVar(&opts.name, "name", "", "item name (required unless reading rows from stdin)")
+	cmd.Flags().StringVar(&opts.groupID, "group", "", "group ID (optional; ignored when --parent is given)")
+	cmd.Flags().StringArrayVar(&opts.colFlags, "col", nil, "column value: <id>=<json> (repeatable)")
+	cmd.Flags().BoolVar(&opts.dryRun, "dry-run", false, "print what would be sent without creating anything")
+	opts.shorthands = addShorthandFlags(cmd)
 
 	cmd.MarkFlagsMutuallyExclusive("board", "parent")
-	_ = cmd.MarkFlagRequired("name")
 
 	return cmd
 }
 
-func runItemCreate(cmd *cobra.Command, boardID, parentID, name, groupID string, colFlags []string) error {
-	if boardID == "" && parentID == "" {
-		return errs.Usage("one of --board or --parent is required")
+func runItemCreate(cmd *cobra.Command, args []string, opts *itemCreateOpts) error {
+	if err := checkBatchArgs(args); err != nil {
+		return err
 	}
 
-	if boardID != "" {
-		if _, err := strconv.ParseUint(boardID, 10, 64); err != nil {
-			return errs.Usage("board id must be a numeric string, got %q", boardID)
+	if opts.boardID == "" && opts.parentID == "" {
+		return errs.Usage("one of --board or --parent is required")
+	}
+	if opts.boardID != "" {
+		if _, err := strconv.ParseUint(opts.boardID, 10, 64); err != nil {
+			return errs.Usage("board id must be a numeric string, got %q", opts.boardID)
 		}
 	}
-	if parentID != "" {
-		if _, err := strconv.ParseUint(parentID, 10, 64); err != nil {
-			return errs.Usage("parent id must be a numeric string, got %q", parentID)
+	if opts.parentID != "" {
+		if _, err := strconv.ParseUint(opts.parentID, 10, 64); err != nil {
+			return errs.Usage("parent id must be a numeric string, got %q", opts.parentID)
+		}
+	}
+
+	set := setShorthands(cmd, opts.shorthands)
+
+	// Shorthands resolve against a board's columns. A subitem lives on its own
+	// hidden subitems board, which we would have to look up separately, so --parent
+	// keeps the raw path only.
+	if len(set) > 0 && opts.parentID != "" {
+		return errs.Usage("typed shorthands need --board; for a subitem use --col <id>=<json>")
+	}
+
+	if isBatchArg(args) {
+		if opts.parentID != "" {
+			return errs.Usage("batch mode needs --board; subitems cannot be created from stdin")
+		}
+		if opts.name != "" || len(opts.colFlags) > 0 || len(set) > 0 {
+			return errs.Usage("batch mode takes every field from stdin: drop --name, --col, and the shorthand flags")
 		}
+		return runItemCreateBatch(cmd, opts.boardID, opts.dryRun)
 	}
 
-	cols, err := parseColFlags(colFlags)
+	if strings.TrimSpace(opts.name) == "" {
+		return errs.Usage("--name is required")
+	}
+
+	cols, err := parseColFlags(opts.colFlags)
 	if err != nil {
 		return err
 	}
-	colValuesStr, err := buildColumnValues(cols)
+
+	// A dry run only needs the API to resolve shorthands.
+	var gql gqlclient.Client
+	if !opts.dryRun || len(set) > 0 {
+		gql, err = newItemClient()
+		if err != nil {
+			return err
+		}
+	}
+
+	enc, err := applyShorthands(cmd.Context(), gql, opts.boardID, cols, set)
 	if err != nil {
 		return err
 	}
 
-	gql, err := newItemClient()
+	colValuesStr, err := buildColumnValues(cols)
 	if err != nil {
 		return err
 	}
 
-	var out itemWriteOutput
+	if opts.dryRun {
+		row := batchRow{Name: opts.name, Group: opts.groupID}
+		return writeBatchDryRun(cmd, "created", []batchRow{row}, []string{colValuesStr})
+	}
 
-	if parentID != "" {
-		resp, apiErr := gen.SubitemCreate(cmd.Context(), gql, parentID, name, colValuesStr)
+	var out itemWriteOutput
+	if opts.parentID != "" {
+		resp, apiErr := gen.SubitemCreate(cmd.Context(), gql, opts.parentID, opts.name, colValuesStr)
 		if apiErr != nil {
 			return apiErr
 		}
-		it := resp.Create_subitem
-		out = itemWriteOutput{
-			ID:    it.Id,
-			Name:  it.Name,
-			State: string(it.State),
-		}
-		if it.Board.Id != "" {
-			out.Board = &itemWriteBoard{ID: it.Board.Id, Name: it.Board.Name}
-		}
-		if it.Parent_item.Id != "" {
-			out.ParentItem = &itemWriteParent{ID: it.Parent_item.Id, Name: it.Parent_item.Name}
-		}
+		out = subitemCreateToOutput(resp)
 	} else {
-		resp, apiErr := gen.ItemCreate(cmd.Context(), gql, boardID, name, groupID, colValuesStr)
+		resp, apiErr := gen.ItemCreate(cmd.Context(), gql, opts.boardID, opts.name, opts.groupID, colValuesStr)
 		if apiErr != nil {
 			return apiErr
 		}
-		it := resp.Create_item
-		out = itemWriteOutput{
-			ID:    it.Id,
-			Name:  it.Name,
-			State: string(it.State),
-		}
-		if it.Board.Id != "" {
-			out.Board = &itemWriteBoard{ID: it.Board.Id, Name: it.Board.Name}
-		}
-		if it.Group.Id != "" {
-			out.Group = &itemWriteGroup{ID: it.Group.Id, Title: it.Group.Title}
-		}
+		out = itemCreateToOutput(resp)
 	}
 
 	mode, modeErr := resolveOutputMode(os.Stdout, globals, configOutputMode())
@@ -251,65 +343,119 @@ func runItemCreate(cmd *cobra.Command, boardID, parentID, name, groupID string,
 	}
 
 	kind := "item"
-	if parentID != "" {
+	if opts.parentID != "" {
 		kind = "subitem"
 	}
-	_, err = fmt.Fprintf(cmd.OutOrStdout(), "Created %s %s: %s\n", kind, out.ID, out.Name)
-	return err
+	o := cmd.OutOrStdout()
+	if _, err = fmt.Fprintf(o, "Created %s %s: %s\n", kind, out.ID, out.Name); err != nil {
+		return err
+	}
+	writeShorthandTrace(o, enc)
+	return nil
+}
+
+// writeShorthandTrace reports which column each shorthand landed on. Pretty output is
+// for humans, and "--status went to status_1 (Stage)" is the one thing a human cannot
+// see from the command they typed.
+func writeShorthandTrace(o io.Writer, enc []encodedShorthand) {
+	for _, e := range enc {
+		_, _ = fmt.Fprintf(o, "  --%s → %s (%s) = %s\n", e.flag, e.colID, e.title, string(e.value))
+	}
 }
 
 // --- item update ---
 
+// itemUpdateOpts holds the flags of 'mcli item update'.
+type itemUpdateOpts struct {
+	boardID    string
+	name       string
+	colFlags   []string
+	dryRun     bool
+	shorthands map[string]*string
+}
+
 func newItemUpdateCmd() *cobra.Command {
-	var (
-		boardID  string
-		name     string
-		colFlags []string
-	)
+	opts := &itemUpdateOpts{}
 
 	cmd := &cobra.Command{
-		Use:   "update <id>",
+		Use:   "update <id> | -",
 		Short: "Update column values on an item",
 		Long: `Update one or more column values on a monday.com item.
 
-Provide --name to rename the item. Use --col <id>=<json> to update columns;
-the JSON must match monday's column-value wire shape. At least one of --name
-or --col must be given.`,
+Provide --name to rename the item. Typed shorthands (--status, --date/--due,
+--number, --text, --checkbox) address the board's single column of that type and are
+validated before anything is sent. Use --col <id>=<json> for any other column; the
+JSON must match monday's column-value wire shape. At least one of --name, --col, or a
+shorthand must be given.
+
+Pass - instead of an item id to update many items from stdin, as a JSON array or one
+JSON object per line. Each row needs "id" and takes optional "name", "cols", and the
+same shorthands as flags:
+
+  echo '{"id":"456","status":"Done"}' | mcli item update --board 123 -
+
+Rows are validated up front and sent sequentially. On partial failure the exit code is
+2 and errors[].index names the rows to retry.`,
 		Args: cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return runItemUpdate(cmd, args[0], boardID, name, colFlags)
+			return runItemUpdate(cmd, args[0], opts)
 		},
 	}
 
-	cmd.Flags().StringVar(&boardID, "board", "", "board ID (required)")
-	cmd.Flags().StringVar(&name, "name", "", "new item name (optional)")
-	cmd.Flags().StringArrayVar(&colFlags, "col", nil, "column value: <id>=<json> (repeatable)")
+	cmd.Flags().StringVar(&opts.boardID, "board", "", "board ID (required)")
+	cmd.Flags().StringVar(&opts.name, "name", "", "new item name (optional)")
+	cmd.Flags().StringArrayVar(&opts.colFlags, "col", nil, "column value: <id>=<json> (repeatable)")
+	cmd.Flags().BoolVar(&opts.dryRun, "dry-run", false, "print what would be sent without updating anything")
+	opts.shorthands = addShorthandFlags(cmd)
+
 	_ = cmd.MarkFlagRequired("board")
 
 	return cmd
 }
 
-func runItemUpdate(cmd *cobra.Command, itemID, boardID, name string, colFlags []string) error {
+func runItemUpdate(cmd *cobra.Command, itemID string, opts *itemUpdateOpts) error {
+	if _, err := strconv.ParseUint(opts.boardID, 10, 64); err != nil {
+		return errs.Usage("board id must be a numeric string, got %q", opts.boardID)
+	}
+
+	set := setShorthands(cmd, opts.shorthands)
+
+	if itemID == batchStdinSentinel {
+		if opts.name != "" || len(opts.colFlags) > 0 || len(set) > 0 {
+			return errs.Usage("batch mode takes every field from stdin: drop --name, --col, and the shorthand flags")
+		}
+		return runItemUpdateBatch(cmd, opts.boardID, opts.dryRun)
+	}
+
 	if _, err := strconv.ParseUint(itemID, 10, 64); err != nil {
 		return errs.Usage("item id must be a numeric string, got %q", itemID)
 	}
-	if _, err := strconv.ParseUint(boardID, 10, 64); err != nil {
-		return errs.Usage("board id must be a numeric string, got %q", boardID)
+	if opts.name == "" && len(opts.colFlags) == 0 && len(set) == 0 {
+		return errs.Usage("nothing to update: provide --name, at least one --col, or a shorthand")
+	}
+
+	cols, err := parseColFlags(opts.colFlags)
+	if err != nil {
+		return err
 	}
 
-	if name == "" && len(colFlags) == 0 {
-		return errs.Usage("nothing to update: provide --name and/or at least one --col")
+	var gql gqlclient.Client
+	if !opts.dryRun || len(set) > 0 {
+		gql, err = newItemClient()
+		if err != nil {
+			return err
+		}
 	}
 
-	cols, err := parseColFlags(colFlags)
+	enc, err := applyShorthands(cmd.Context(), gql, opts.boardID, cols, set)
 	if err != nil {
 		return err
 	}
 
 	// If --name is provided, inject the name column. Monday expects a bare
 	// JSON string for the "name" column in change_multiple_column_values.
-	if name != "" {
-		nameVal, _ := json.Marshal(name)
+	if opts.name != "" {
+		nameVal, _ := json.Marshal(opts.name)
 		cols["name"] = json.RawMessage(nameVal)
 	}
 
@@ -318,28 +464,16 @@ func runItemUpdate(cmd *cobra.Command, itemID, boardID, name string, colFlags []
 		return err
 	}
 
-	gql, err := newItemClient()
-	if err != nil {
-		return err
+	if opts.dryRun {
+		row := batchRow{ID: itemID, Name: opts.name}
+		return writeBatchDryRun(cmd, "updated", []batchRow{row}, []string{colValuesStr})
 	}
 
-	resp, apiErr := gen.ItemUpdate(cmd.Context(), gql, boardID, itemID, colValuesStr)
+	resp, apiErr := gen.ItemUpdate(cmd.Context(), gql, opts.boardID, itemID, colValuesStr)
 	if apiErr != nil {
 		return apiErr
 	}
-
-	it := resp.Change_multiple_column_values
-	out := itemWriteOutput{
-		ID:    it.Id,
-		Name:  it.Name,
-		State: string(it.State),
-	}
-	if it.Board.Id != "" {
-		out.Board = &itemWriteBoard{ID: it.Board.Id, Name: it.Board.Name}
-	}
-	if it.Group.Id != "" {
-		out.Group = &itemWriteGroup{ID: it.Group.Id, Title: it.Group.Title}
-	}
+	out := itemUpdateToOutput(resp)
 
 	mode, modeErr := resolveOutputMode(os.Stdout, globals, configOutputMode())
 	if modeErr != nil {
@@ -356,14 +490,17 @@ func runItemUpdate(cmd *cobra.Command, itemID, boardID, name string, colFlags []
 	}
 
 	o := cmd.OutOrStdout()
-	_, err = fmt.Fprintf(o, "Updated item %s\n", out.ID)
-	if name != "" {
-		_, _ = fmt.Fprintf(o, "  name → %s\n", name)
+	if _, err = fmt.Fprintf(o, "Updated item %s\n", out.ID); err != nil {
+		return err
+	}
+	if opts.name != "" {
+		_, _ = fmt.Fprintf(o, "  name → %s\n", opts.name)
 	}
-	for _, f := range colFlags {
+	for _, f := range opts.colFlags {
 		_, _ = fmt.Fprintf(o, "  col  → %s\n", f)
 	}
-	return err
+	writeShorthandTrace(o, enc)
+	return nil
 }
 
 // --- item post-update ---
diff --git a/internal/cli/item_batch.go b/internal/cli/item_batch.go
new file mode 100644
index 0000000..a1c8c6b
--- /dev/null
+++ b/internal/cli/item_batch.go
@@ -0,0 +1,565 @@
+package cli
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"maps"
+	"os"
+	"strconv"
+	"strings"
+
+	gqlclient "github.com/Khan/genqlient/graphql"
+	"github.com/spf13/cobra"
+
+	"github.com/mondaycom/mcli/internal/api/gen"
+	apigraphql "github.com/mondaycom/mcli/internal/api/graphql"
+	"github.com/mondaycom/mcli/internal/errs"
+)
+
+const (
+	// batchStdinSentinel is the positional arg that switches create/update into
+	// batch mode, reading rows from stdin. ADR-002 specifies this contract.
+	batchStdinSentinel = "-"
+	// batchMaxInputBytes bounds stdin so a runaway pipe cannot exhaust memory.
+	batchMaxInputBytes = 8 << 20
+	// batchMaxRows caps one invocation. create_item has no dedupe key, so an
+	// accidental huge batch is expensive to undo; splitting is the caller's call.
+	batchMaxRows = 500
+)
+
+// jsonScalar is a JSON string, number, or boolean captured as its text form, so a
+// batch row may write "number": 42 or "number": "42" and mean the same thing.
+type jsonScalar string
+
+// UnmarshalJSON accepts a string, number, or boolean.
+func (s *jsonScalar) UnmarshalJSON(b []byte) error {
+	// null is rejected rather than read as "clear the column": encoding/json treats
+	// unmarshalling null as a no-op, so it would silently mean "absent" instead. Use
+	// "" to clear a column.
+	if string(bytes.TrimSpace(b)) == "null" {
+		return fmt.Errorf(`null is not a value; use "" to clear a column`)
+	}
+
+	var str string
+	if err := json.Unmarshal(b, &str); err == nil {
+		*s = jsonScalar(str)
+		return nil
+	}
+	var num json.Number
+	if err := json.Unmarshal(b, &num); err == nil {
+		*s = jsonScalar(num.String())
+		return nil
+	}
+	var boolean bool
+	if err := json.Unmarshal(b, &boolean); err == nil {
+		*s = jsonScalar(strconv.FormatBool(boolean))
+		return nil
+	}
+	return fmt.Errorf("expected a string, number, or boolean, got %s", string(b))
+}
+
+// MarshalJSON keeps --dry-run echoes round-trippable.
+func (s jsonScalar) MarshalJSON() ([]byte, error) {
+	return json.Marshal(string(s))
+}
+
+// batchRow is one row of a batch payload. Create rows carry name/group, update rows
+// carry id, and both may carry raw cols plus the same typed shorthands as the flags.
+//
+// A nil shorthand pointer means "absent"; an empty one means "write empty", which is
+// how a column gets cleared.
+type batchRow struct {
+	ID    string                     `json:"id,omitempty"`
+	Name  string                     `json:"name,omitempty"`
+	Group string                     `json:"group,omitempty"`
+	Cols  map[string]json.RawMessage `json:"cols,omitempty"`
+
+	Text     *jsonScalar `json:"text,omitempty"`
+	Status   *jsonScalar `json:"status,omitempty"`
+	Date     *jsonScalar `json:"date,omitempty"`
+	Due      *jsonScalar `json:"due,omitempty"`
+	Number   *jsonScalar `json:"number,omitempty"`
+	Checkbox *jsonScalar `json:"checkbox,omitempty"`
+}
+
+// shorthands returns the shorthands present on the row, in spec order, so the stdin
+// path and the flag path share one encoder and one resolution rule.
+func (r batchRow) shorthands() []shorthandValue {
+	byFlag := map[string]*jsonScalar{
+		"text":     r.Text,
+		"status":   r.Status,
+		"date":     r.Date,
+		"due":      r.Due,
+		"number":   r.Number,
+		"checkbox": r.Checkbox,
+	}
+	var out []shorthandValue
+	for _, sp := range shorthandSpecs {
+		if v := byFlag[sp.flag]; v != nil {
+			out = append(out, shorthandValue{spec: sp, value: string(*v)})
+		}
+	}
+	return out
+}
+
+// isBatchArg reports whether args select batch mode.
+func isBatchArg(args []string) bool {
+	return len(args) == 1 && args[0] == batchStdinSentinel
+}
+
+// parseBatchRows reads a JSON array or an NDJSON stream of rows.
+//
+// Unknown fields are rejected: a mistyped key like "columns" instead of "cols" would
+// otherwise silently drop every column value in the row and report success.
+func parseBatchRows(r io.Reader) ([]batchRow, error) {
+	data, err := io.ReadAll(io.LimitReader(r, batchMaxInputBytes+1))
+	if err != nil {
+		return nil, errs.Usage("read batch rows from stdin: %v", err)
+	}
+	if len(data) > batchMaxInputBytes {
+		return nil, errs.Usage("batch input exceeds %d bytes; split it into smaller batches", batchMaxInputBytes)
+	}
+
+	trimmed := bytes.TrimSpace(data)
+	if len(trimmed) == 0 {
+		return nil, errs.Usage("no batch rows on stdin")
+	}
+
+	dec := json.NewDecoder(bytes.NewReader(trimmed))
+	dec.DisallowUnknownFields()
+
+	var rows []batchRow
+	if trimmed[0] == '[' {
+		if err := dec.Decode(&rows); err != nil {
+			return nil, errs.Usage("parse batch rows: %v", err)
+		}
+		if dec.More() {
+			return nil, errs.Usage("parse batch rows: unexpected content after the JSON array")
+		}
+	} else {
+		for {
+			var row batchRow
+			if err := dec.Decode(&row); err != nil {
+				if errors.Is(err, io.EOF) {
+					break
+				}
+				return nil, errs.Usage("parse batch row %d: %v", len(rows), err)
+			}
+			rows = append(rows, row)
+		}
+	}
+
+	if len(rows) == 0 {
+		return nil, errs.Usage("no batch rows on stdin")
+	}
+	if len(rows) > batchMaxRows {
+		return nil, errs.Usage("batch has %d rows, max is %d; split it into smaller batches", len(rows), batchMaxRows)
+	}
+	return rows, nil
+}
+
+// validateBatchRow checks what is common to create and update rows.
+func validateBatchRow(index int, row batchRow) error {
+	if row.Date != nil && row.Due != nil {
+		return errs.Usage("row %d: set either \"date\" or \"due\", not both", index)
+	}
+	for id, raw := range row.Cols {
+		if id == "" {
+			return errs.Usage("row %d: cols has an empty column id", index)
+		}
+		if !json.Valid(raw) {
+			return errs.Usage("row %d: cols.%s is not valid JSON", index, id)
+		}
+	}
+	return nil
+}
+
+// validateCreateRows rejects the whole payload before any request fires: a batch that
+// dies halfway through leaves items behind that a retry would duplicate.
+func validateCreateRows(rows []batchRow) error {
+	for i, row := range rows {
+		if err := validateBatchRow(i, row); err != nil {
+			return err
+		}
+		if strings.TrimSpace(row.Name) == "" {
+			return errs.Usage("row %d: \"name\" is required to create an item", i)
+		}
+		if row.ID != "" {
+			return errs.Usage("row %d: \"id\" is not valid when creating items", i)
+		}
+	}
+	return nil
+}
+
+// validateUpdateRows rejects the whole payload before any request fires.
+func validateUpdateRows(rows []batchRow) error {
+	for i, row := range rows {
+		if err := validateBatchRow(i, row); err != nil {
+			return err
+		}
+		if row.ID == "" {
+			return errs.Usage("row %d: \"id\" is required to update an item", i)
+		}
+		if _, err := strconv.ParseUint(row.ID, 10, 64); err != nil {
+			return errs.Usage("row %d: id must be a numeric string, got %q", i, row.ID)
+		}
+		if row.Name == "" && len(row.Cols) == 0 && len(row.shorthands()) == 0 {
+			return errs.Usage("row %d: nothing to update: provide \"name\", \"cols\", or a shorthand", i)
+		}
+	}
+	return nil
+}
+
+// batchNeedsColumns reports whether any row uses a shorthand, i.e. whether the
+// board's columns have to be fetched at all.
+func batchNeedsColumns(rows []batchRow) bool {
+	for _, row := range rows {
+		if len(row.shorthands()) > 0 {
+			return true
+		}
+	}
+	return false
+}
+
+// buildBatchPayloads turns every row into the exact column_values string that will be
+// sent for it, resolving the board's columns at most once for the whole batch.
+//
+// All rows are built up front so a bad status label fails the batch as a usage error
+// instead of surfacing after the first N items are already created.
+func buildBatchPayloads(
+	ctx context.Context, gql gqlclient.Client, boardID string, rows []batchRow,
+) ([]string, error) {
+	var idx *boardColumnIndex
+	if batchNeedsColumns(rows) {
+		var err error
+		idx, err = fetchBoardColumnIndex(ctx, gql, boardID)
+		if err != nil {
+			return nil, err
+		}
+	}
+
+	payloads := make([]string, len(rows))
+	for i, row := range rows {
+		// Copied rather than used in place, so encoding a shorthand never mutates the
+		// caller's parsed row (--dry-run echoes it back).
+		cols := make(map[string]json.RawMessage, len(row.Cols))
+		maps.Copy(cols, row.Cols)
+
+		if short := row.shorthands(); len(short) > 0 {
+			enc, err := encodeShorthands(idx, short)
+			if err != nil {
+				return nil, errs.Usage("row %d: %s", i, errMessage(err))
+			}
+			if err := mergeShorthands(cols, enc); err != nil {
+				return nil, errs.Usage("row %d: %s", i, errMessage(err))
+			}
+		}
+
+		// change_multiple_column_values takes the item name as a "name" column.
+		if row.Name != "" && row.ID != "" {
+			nameVal, _ := json.Marshal(row.Name)
+			cols["name"] = json.RawMessage(nameVal)
+		}
+
+		payload, err := buildColumnValues(cols)
+		if err != nil {
+			return nil, errs.Usage("row %d: %v", i, err)
+		}
+		payloads[i] = payload
+	}
+	return payloads, nil
+}
+
+// errMessage returns an *errs.Error's bare message, so nesting a row index in front
+// of it does not produce a doubled "[USAGE] … [USAGE] …" string.
+func errMessage(err error) string {
+	if e, ok := errors.AsType[*errs.Error](err); ok {
+		return e.Message
+	}
+	return err.Error()
+}
+
+// batchError reports one failed row.
+//
+// Index is the row's position in the input, which is what makes a partial failure
+// recoverable: create_item has no dedupe key, so re-running the whole payload
+// duplicates every row that succeeded. Retry the listed indexes, not the batch.
+type batchError struct {
+	Index   int    `json:"index"`
+	ID      string `json:"id,omitempty"`
+	Code    string `json:"code"`
+	Message string `json:"message"`
+}
+
+// batchWriteOutput is the JSON shape for a batch create or update. It is one
+// top-level object, never a stream (ADR-002), and every key is always present so a
+// caller can read counts without checking for absence.
+type batchWriteOutput struct {
+	// Written is the number of rows monday accepted.
+	Written int `json:"written"`
+	Failed  int `json:"failed"`
+	// Verb is "created" or "updated", so a caller need not infer it from the command.
+	Verb   string            `json:"verb"`
+	Items  []itemWriteOutput `json:"items"`
+	Errors []batchError      `json:"errors"`
+}
+
+// batchDryRunRow echoes one row exactly as it would be sent.
+type batchDryRunRow struct {
+	Index        int    `json:"index"`
+	ID           string `json:"id,omitempty"`
+	Name         string `json:"name,omitempty"`
+	Group        string `json:"group,omitempty"`
+	ColumnValues string `json:"column_values,omitempty"`
+}
+
+// batchDryRunOutput is the JSON shape for a batch --dry-run.
+type batchDryRunOutput struct {
+	DryRun bool             `json:"dry_run"`
+	Verb   string           `json:"verb"`
+	Rows   int              `json:"rows"`
+	Items  []batchDryRunRow `json:"items"`
+}
+
+// classifyBatchErr maps a per-row error to a stable code. Errors from the production
+// client are already *errs.Error; anything else is normalised so a raw transport
+// failure still reports a real code rather than a bare INTERNAL.
+func classifyBatchErr(err error) errs.Code {
+	if e, ok := errors.AsType[*errs.Error](err); ok {
+		return e.Code
+	}
+	if e, ok := errors.AsType[*errs.Error](apigraphql.Normalize(err)); ok {
+		return e.Code
+	}
+	return errs.CodeInternal
+}
+
+// batchRowFn performs the write for one row, returning the item monday reported.
+type batchRowFn func(ctx context.Context, index int, row batchRow, columnValues string) (itemWriteOutput, error)
+
+// runBatch executes rows sequentially and collects per-row outcomes.
+//
+// Sequential is deliberate: monday's limit is complexity-per-minute, so parallelism
+// does not raise throughput, it only reaches the ceiling sooner and makes pacing
+// impossible to reason about.
+func runBatch(ctx context.Context, verb string, rows []batchRow, payloads []string, write batchRowFn) batchWriteOutput {
+	out := batchWriteOutput{
+		Verb:   verb,
+		Items:  make([]itemWriteOutput, 0, len(rows)),
+		Errors: []batchError{},
+	}
+
+	for i, row := range rows {
+		if ctxErr := ctx.Err(); ctxErr != nil {
+			out.Errors = append(out.Errors, batchError{
+				Index:   i,
+				ID:      row.ID,
+				Code:    string(errs.CodeInterrupted),
+				Message: fmt.Sprintf("cancelled before row %d of %d", i, len(rows)),
+			})
+			out.Failed++
+			break
+		}
+
+		item, err := write(ctx, i, row, payloads[i])
+		if err != nil {
+			out.Errors = append(out.Errors, batchError{
+				Index:   i,
+				ID:      row.ID,
+				Code:    string(classifyBatchErr(err)),
+				Message: errMessage(err),
+			})
+			out.Failed++
+			continue
+		}
+		out.Items = append(out.Items, item)
+		out.Written++
+	}
+
+	return out
+}
+
+// writeBatchOutput renders the batch result and returns the error that sets the exit
+// code: any failed row is exit 2, so a caller can tell "all fine" from "mostly fine"
+// without diffing counts.
+func writeBatchOutput(cmd *cobra.Command, out batchWriteOutput) error {
+	mode, modeErr := resolveOutputMode(os.Stdout, globals, configOutputMode())
+	if modeErr != nil {
+		return modeErr
+	}
+
+	o := cmd.OutOrStdout()
+	if mode == ModeJSON {
+		data, mErr := json.Marshal(out)
+		if mErr != nil {
+			return errs.Internal("marshal output: %v", mErr)
+		}
+		if _, err := fmt.Fprintln(o, string(data)); err != nil {
+			return err
+		}
+	} else {
+		if _, err := fmt.Fprintf(o, "%s %s, %d failed\n", out.Verb, pluralItems(out.Written), out.Failed); err != nil {
+			return err
+		}
+		for _, e := range out.Errors {
+			_, _ = fmt.Fprintf(o, "  row %d: [%s] %s\n", e.Index, e.Code, e.Message)
+		}
+	}
+
+	if out.Failed > 0 {
+		return errs.API("%d of %d rows failed; see errors[].index to retry only those",
+			out.Failed, out.Written+out.Failed)
+	}
+	return nil
+}
+
+// writeBatchDryRun renders what a batch would send, without sending it.
+func writeBatchDryRun(cmd *cobra.Command, verb string, rows []batchRow, payloads []string) error {
+	out := batchDryRunOutput{DryRun: true, Verb: verb, Rows: len(rows), Items: make([]batchDryRunRow, 0, len(rows))}
+	for i, row := range rows {
+		out.Items = append(out.Items, batchDryRunRow{
+			Index:        i,
+			ID:           row.ID,
+			Name:         row.Name,
+			Group:        row.Group,
+			ColumnValues: payloads[i],
+		})
+	}
+
+	mode, modeErr := resolveOutputMode(os.Stdout, globals, configOutputMode())
+	if modeErr != nil {
+		return modeErr
+	}
+
+	o := cmd.OutOrStdout()
+	if mode == ModeJSON {
+		data, mErr := json.Marshal(out)
+		if mErr != nil {
+			return errs.Internal("marshal output: %v", mErr)
+		}
+		_, err := fmt.Fprintln(o, string(data))
+		return err
+	}
+
+	if _, err := fmt.Fprintf(o, "dry run: would %s %s\n", verbInfinitive(verb), pluralItems(len(rows))); err != nil {
+		return err
+	}
+	for _, it := range out.Items {
+		label := it.Name
+		if it.ID != "" {
+			label = it.ID
+		}
+		line := fmt.Sprintf("  row %d: %s", it.Index, label)
+		if it.ColumnValues != "" {
+			line += " " + it.ColumnValues
+		}
+		_, _ = fmt.Fprintln(o, line)
+	}
+	return nil
+}
+
+// verbInfinitive turns the output verb into the form a sentence needs.
+func verbInfinitive(verb string) string {
+	switch verb {
+	case "created":
+		return "create"
+	case "updated":
+		return "update"
+	default:
+		return verb
+	}
+}
+
+// pluralItems renders an item count without the "1 items" tell.
+func pluralItems(n int) string {
+	if n == 1 {
+		return "1 item"
+	}
+	return fmt.Sprintf("%d items", n)
+}
+
+// --- batch entry points ---
+
+// runItemCreateBatch implements 'mcli item create --board <id> -'.
+func runItemCreateBatch(cmd *cobra.Command, boardID string, dryRun bool) error {
+	rows, err := parseBatchRows(cmd.InOrStdin())
+	if err != nil {
+		return err
+	}
+	if err := validateCreateRows(rows); err != nil {
+		return err
+	}
+
+	// A dry run that uses no shorthand needs no API access at all, so it stays
+	// usable as a pure parse check without a token.
+	var gql gqlclient.Client
+	if !dryRun || batchNeedsColumns(rows) {
+		gql, err = newItemClient()
+		if err != nil {
+			return err
+		}
+	}
+
+	payloads, err := buildBatchPayloads(cmd.Context(), gql, boardID, rows)
+	if err != nil {
+		return err
+	}
+
+	if dryRun {
+		return writeBatchDryRun(cmd, "created", rows, payloads)
+	}
+
+	out := runBatch(cmd.Context(), "created", rows, payloads,
+		func(ctx context.Context, _ int, row batchRow, columnValues string) (itemWriteOutput, error) {
+			resp, apiErr := gen.ItemCreate(ctx, gql, boardID, row.Name, row.Group, columnValues)
+			if apiErr != nil {
+				return itemWriteOutput{}, apiErr
+			}
+			return itemCreateToOutput(resp), nil
+		})
+
+	return writeBatchOutput(cmd, out)
+}
+
+// runItemUpdateBatch implements 'mcli item update --board <id> -'.
+func runItemUpdateBatch(cmd *cobra.Command, boardID string, dryRun bool) error {
+	rows, err := parseBatchRows(cmd.InOrStdin())
+	if err != nil {
+		return err
+	}
+	if err := validateUpdateRows(rows); err != nil {
+		return err
+	}
+
+	var gql gqlclient.Client
+	if !dryRun || batchNeedsColumns(rows) {
+		gql, err = newItemClient()
+		if err != nil {
+			return err
+		}
+	}
+
+	payloads, err := buildBatchPayloads(cmd.Context(), gql, boardID, rows)
+	if err != nil {
+		return err
+	}
+
+	if dryRun {
+		return writeBatchDryRun(cmd, "updated", rows, payloads)
+	}
+
+	out := runBatch(cmd.Context(), "updated", rows, payloads,
+		func(ctx context.Context, _ int, row batchRow, columnValues string) (itemWriteOutput, error) {
+			resp, apiErr := gen.ItemUpdate(ctx, gql, boardID, row.ID, columnValues)
+			if apiErr != nil {
+				return itemWriteOutput{}, apiErr
+			}
+			return itemUpdateToOutput(resp), nil
+		})
+
+	return writeBatchOutput(cmd, out)
+}
diff --git a/internal/cli/item_batch_test.go b/internal/cli/item_batch_test.go
new file mode 100644
index 0000000..fd718cf
--- /dev/null
+++ b/internal/cli/item_batch_test.go
@@ -0,0 +1,914 @@
+package cli
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+
+	"github.com/mondaycom/mcli/internal/errs"
+)
+
+// gqlCall records one request the CLI made.
+type gqlCall struct {
+	op   string
+	vars map[string]any
+}
+
+// gqlRecorder is a fake monday endpoint that records every call and lets a test
+// return a full response body (data or errors) per request.
+type gqlRecorder struct {
+	mu    sync.Mutex
+	calls []gqlCall
+}
+
+// newGQLRecorder starts a server whose handler is fn(op, vars, nthCallOfThatOp) and
+// returns the raw GraphQL response body to send.
+func newGQLRecorder(t *testing.T, fn func(op string, vars map[string]any, n int) string) (*gqlRecorder, *httptest.Server) {
+	t.Helper()
+	rec := &gqlRecorder{}
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		raw, err := io.ReadAll(r.Body)
+		if err != nil {
+			http.Error(w, "read body", http.StatusBadRequest)
+			return
+		}
+		var body map[string]any
+		if err := json.Unmarshal(raw, &body); err != nil {
+			http.Error(w, "parse body", http.StatusBadRequest)
+			return
+		}
+		op, _ := body["operationName"].(string)
+		vars, _ := body["variables"].(map[string]any)
+
+		rec.mu.Lock()
+		n := 0
+		for _, c := range rec.calls {
+			if c.op == op {
+				n++
+			}
+		}
+		rec.calls = append(rec.calls, gqlCall{op: op, vars: vars})
+		rec.mu.Unlock()
+
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = fmt.Fprint(w, fn(op, vars, n))
+	}))
+	t.Cleanup(srv.Close)
+	installItemFactory(t, srv.URL)
+	return rec, srv
+}
+
+// ops returns the recorded operation names in order.
+func (r *gqlRecorder) ops() []string {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	out := make([]string, 0, len(r.calls))
+	for _, c := range r.calls {
+		out = append(out, c.op)
+	}
+	return out
+}
+
+// countOp returns how many times op was called.
+func (r *gqlRecorder) countOp(op string) int {
+	n := 0
+	for _, got := range r.ops() {
+		if got == op {
+			n++
+		}
+	}
+	return n
+}
+
+// varsFor returns the variables of the nth (0-based) call to op.
+func (r *gqlRecorder) varsFor(op string, n int) map[string]any {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	seen := 0
+	for _, c := range r.calls {
+		if c.op != op {
+			continue
+		}
+		if seen == n {
+			return c.vars
+		}
+		seen++
+	}
+	return nil
+}
+
+// boardColumnsBody is a BoardColumnList response for a board with one column of each
+// shorthand-addressable type, plus an archived status column that must be ignored (it
+// would otherwise make --status ambiguous even though it cannot be written).
+func boardColumnsBody() string {
+	cols := []map[string]any{
+		{"id": "name", "title": "Name", "type": "name", "settings_str": "{}", "width": 200, "archived": false},
+		{"id": "status_1", "title": "Stage", "type": "status", "settings_str": testStatusSettings, "width": 150, "archived": false},
+		{"id": "status_old", "title": "Old Stage", "type": "status", "settings_str": testStatusSettings, "width": 150, "archived": true},
+		{"id": "date_4", "title": "Due", "type": "date", "settings_str": "{}", "width": 150, "archived": false},
+		{"id": "numbers_7", "title": "Estimate", "type": "numbers", "settings_str": "{}", "width": 150, "archived": false},
+		{"id": "text_9", "title": "Notes", "type": "text", "settings_str": "{}", "width": 150, "archived": false},
+		{"id": "checkbox_2", "title": "Blocked", "type": "checkbox", "settings_str": "{}", "width": 150, "archived": false},
+	}
+	boards := []map[string]any{{"id": "9832181507", "columns": cols}}
+	return fmt.Sprintf(`{"data":%s}`, mustMarshal(map[string]any{"boards": boards}))
+}
+
+// boardColumnsBodyTextOnly is a board with no column of most shorthand types, for the
+// "this board has none" path.
+func boardColumnsBodyTextOnly() string {
+	cols := []map[string]any{
+		{"id": "name", "title": "Name", "type": "name", "settings_str": "{}", "width": 200, "archived": false},
+		{"id": "text_9", "title": "Notes", "type": "text", "settings_str": "{}", "width": 150, "archived": false},
+	}
+	boards := []map[string]any{{"id": "9832181507", "columns": cols}}
+	return fmt.Sprintf(`{"data":%s}`, mustMarshal(map[string]any{"boards": boards}))
+}
+
+// itemCreateBody is a successful create_item response.
+func itemCreateBody(id, name string) string {
+	return fmt.Sprintf(`{"data":{"create_item":{"id":%q,"name":%q,"state":"active",`+
+		`"board":{"id":"9832181507","name":"Dev Board"},"group":{"id":"topics","title":"Sprint 1"}}}}`, id, name)
+}
+
+// itemUpdateBody is a successful change_multiple_column_values response.
+func itemUpdateBody(id, name string) string {
+	return fmt.Sprintf(`{"data":{"change_multiple_column_values":{"id":%q,"name":%q,"state":"active",`+
+		`"board":{"id":"9832181507","name":"Dev Board"},"group":{"id":"topics","title":"Sprint 1"}}}}`, id, name)
+}
+
+// gqlErrorBody is a GraphQL error response.
+func gqlErrorBody(message, code string) string {
+	return fmt.Sprintf(`{"errors":[{"message":%q,"extensions":{"code":%q}}]}`, message, code)
+}
+
+// execItemCreateStdin runs 'item create' with stdin wired to in.
+func execItemCreateStdin(t *testing.T, in string, args ...string) (string, error) {
+	t.Helper()
+	globals = GlobalFlags{JSON: true}
+	defer func() { globals = GlobalFlags{} }()
+
+	var buf bytes.Buffer
+	cmd := newItemCmd()
+	// Mirror the production root command: usage text must not land on stdout, which
+	// batch mode uses for its JSON result even when it exits non-zero.
+	cmd.SilenceUsage = true
+	cmd.SilenceErrors = true
+	cmd.SetOut(&buf)
+	cmd.SetErr(io.Discard)
+	cmd.SetIn(strings.NewReader(in))
+	cmd.SetArgs(append([]string{"create"}, args...))
+	err := cmd.Execute()
+	return buf.String(), err
+}
+
+// execItemUpdateStdin runs 'item update' with stdin wired to in.
+func execItemUpdateStdin(t *testing.T, in string, args ...string) (string, error) {
+	t.Helper()
+	globals = GlobalFlags{JSON: true}
+	defer func() { globals = GlobalFlags{} }()
+
+	var buf bytes.Buffer
+	cmd := newItemCmd()
+	// Mirror the production root command: usage text must not land on stdout, which
+	// batch mode uses for its JSON result even when it exits non-zero.
+	cmd.SilenceUsage = true
+	cmd.SilenceErrors = true
+	cmd.SetOut(&buf)
+	cmd.SetErr(io.Discard)
+	cmd.SetIn(strings.NewReader(in))
+	cmd.SetArgs(append([]string{"update"}, args...))
+	err := cmd.Execute()
+	return buf.String(), err
+}
+
+// decodeBatch parses batch output.
+func decodeBatch(t *testing.T, out string) batchWriteOutput {
+	t.Helper()
+	var got batchWriteOutput
+	if err := json.Unmarshal([]byte(strings.TrimSpace(out)), &got); err != nil {
+		t.Fatalf("parse output: %v\nraw: %s", err, out)
+	}
+	return got
+}
+
+// ---- jsonScalar ----
+
+// TestJSONScalar accepts the three JSON scalar forms, so a row may write
+// "number": 42 without quoting and "checkbox": true without stringifying.
+func TestJSONScalar(t *testing.T) {
+	tests := []struct {
+		in   string
+		want string
+	}{
+		{in: `"Done"`, want: "Done"},
+		{in: `42`, want: "42"},
+		{in: `42.5`, want: "42.5"},
+		{in: `true`, want: "true"},
+		{in: `false`, want: "false"},
+		{in: `""`, want: ""},
+	}
+	for _, tt := range tests {
+		var got jsonScalar
+		if err := json.Unmarshal([]byte(tt.in), &got); err != nil {
+			t.Errorf("Unmarshal(%s): %v", tt.in, err)
+			continue
+		}
+		if string(got) != tt.want {
+			t.Errorf("Unmarshal(%s) = %q, want %q", tt.in, got, tt.want)
+		}
+	}
+
+	for _, bad := range []string{`null`, `[1]`, `{"a":1}`} {
+		var got jsonScalar
+		if err := json.Unmarshal([]byte(bad), &got); err == nil {
+			t.Errorf("Unmarshal(%s) = %q, want an error", bad, got)
+		}
+	}
+}
+
+// ---- parsing ----
+
+func TestParseBatchRows_arrayAndNDJSON(t *testing.T) {
+	array := `[{"name":"a"},{"name":"b"}]`
+	ndjson := "{\"name\":\"a\"}\n{\"name\":\"b\"}\n"
+
+	for _, in := range []string{array, ndjson} {
+		rows, err := parseBatchRows(strings.NewReader(in))
+		if err != nil {
+			t.Fatalf("parseBatchRows(%q): %v", in, err)
+		}
+		if len(rows) != 2 || rows[0].Name != "a" || rows[1].Name != "b" {
+			t.Errorf("parseBatchRows(%q) = %+v", in, rows)
+		}
+	}
+}
+
+// TestParseBatchRows_rejectsUnknownField is why DisallowUnknownFields is set: a
+// mistyped key would otherwise drop the caller's data and report success.
+func TestParseBatchRows_rejectsUnknownField(t *testing.T) {
+	_, err := parseBatchRows(strings.NewReader(`[{"name":"a","columns":{"x":1}}]`))
+	if err == nil {
+		t.Fatal("want an error for an unknown row field")
+	}
+	if codeOf(err) != errs.CodeUsage {
+		t.Errorf("code = %s, want %s", codeOf(err), errs.CodeUsage)
+	}
+}
+
+func TestParseBatchRows_errors(t *testing.T) {
+	tests := []struct {
+		name string
+		in   string
+	}{
+		{name: "empty", in: ""},
+		{name: "whitespace only", in: "  \n\t\n"},
+		{name: "empty array", in: "[]"},
+		{name: "truncated array", in: `[{"name":"a"}`},
+		{name: "trailing content after array", in: `[{"name":"a"}] {"name":"b"}`},
+		{name: "not an object", in: `"a string"`},
+		{name: "bad ndjson second row", in: "{\"name\":\"a\"}\nnope\n"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			rows, err := parseBatchRows(strings.NewReader(tt.in))
+			if err == nil {
+				t.Fatalf("parseBatchRows(%q) = %+v, want an error", tt.in, rows)
+			}
+			if codeOf(err) != errs.CodeUsage {
+				t.Errorf("code = %s, want %s", codeOf(err), errs.CodeUsage)
+			}
+		})
+	}
+}
+
+func TestParseBatchRows_maxRows(t *testing.T) {
+	rows := make([]string, batchMaxRows)
+	for i := range rows {
+		rows[i] = fmt.Sprintf(`{"name":"item %d"}`, i)
+	}
+	atMax := "[" + strings.Join(rows, ",") + "]"
+
+	got, err := parseBatchRows(strings.NewReader(atMax))
+	if err != nil {
+		t.Fatalf("parseBatchRows at max (%d rows): %v", batchMaxRows, err)
+	}
+	if len(got) != batchMaxRows {
+		t.Errorf("parsed %d rows, want %d", len(got), batchMaxRows)
+	}
+
+	overMax := "[" + strings.Join(append(rows, `{"name":"one too many"}`), ",") + "]"
+	if _, err := parseBatchRows(strings.NewReader(overMax)); err == nil {
+		t.Errorf("parseBatchRows accepted %d rows, want a cap at %d", batchMaxRows+1, batchMaxRows)
+	}
+}
+
+// ---- create batch ----
+
+func TestItemCreateBatch_happyPath(t *testing.T) {
+	rec, _ := newGQLRecorder(t, func(op string, vars map[string]any, n int) string {
+		if op != "ItemCreate" {
+			t.Errorf("unexpected op %q", op)
+		}
+		name, _ := vars["name"].(string)
+		return itemCreateBody(fmt.Sprintf("100%d", n), name)
+	})
+
+	in := `[{"name":"a","group":"topics"},{"name":"b"},{"name":"c","cols":{"text_9":"hi"}}]`
+	out, err := execItemCreateStdin(t, in, "--board", "9832181507", "-")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	got := decodeBatch(t, out)
+	if got.Written != 3 || got.Failed != 0 {
+		t.Errorf("written=%d failed=%d, want 3/0", got.Written, got.Failed)
+	}
+	if got.Verb != "created" {
+		t.Errorf("verb = %q, want created", got.Verb)
+	}
+	if len(got.Items) != 3 {
+		t.Fatalf("items = %d, want 3", len(got.Items))
+	}
+	if got.Errors == nil {
+		t.Error("errors is null; it must always be present as an array")
+	}
+	if rec.countOp("ItemCreate") != 3 {
+		t.Errorf("made %d ItemCreate calls, want 3", rec.countOp("ItemCreate"))
+	}
+	// No shorthand in the payload, so the board's columns must not be fetched.
+	if rec.countOp("BoardColumnList") != 0 {
+		t.Errorf("fetched board columns %d times for a --col-only batch, want 0", rec.countOp("BoardColumnList"))
+	}
+
+	if cv, _ := rec.varsFor("ItemCreate", 2)["columnValues"].(string); cv != `{"text_9":"hi"}` {
+		t.Errorf("row 2 columnValues = %q, want the row's cols", cv)
+	}
+	if gid, _ := rec.varsFor("ItemCreate", 0)["groupId"].(string); gid != "topics" {
+		t.Errorf("row 0 groupId = %q, want topics", gid)
+	}
+}
+
+func TestItemCreateBatch_ndjson(t *testing.T) {
+	rec, _ := newGQLRecorder(t, func(_ string, vars map[string]any, n int) string {
+		name, _ := vars["name"].(string)
+		return itemCreateBody(fmt.Sprintf("200%d", n), name)
+	})
+
+	in := "{\"name\":\"a\"}\n{\"name\":\"b\"}\n"
+	out, err := execItemCreateStdin(t, in, "--board", "9832181507", "-")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got := decodeBatch(t, out); got.Written != 2 {
+		t.Errorf("written = %d, want 2", got.Written)
+	}
+	if rec.countOp("ItemCreate") != 2 {
+		t.Errorf("made %d ItemCreate calls, want 2", rec.countOp("ItemCreate"))
+	}
+}
+
+// TestItemCreateBatch_shorthandsFetchColumnsOnce is the rate-limit point of the
+// design: N rows using shorthands cost one column lookup, not N.
+func TestItemCreateBatch_shorthandsFetchColumnsOnce(t *testing.T) {
+	rec, _ := newGQLRecorder(t, func(op string, vars map[string]any, n int) string {
+		switch op {
+		case "BoardColumnList":
+			return boardColumnsBody()
+		case "ItemCreate":
+			name, _ := vars["name"].(string)
+			return itemCreateBody(fmt.Sprintf("300%d", n), name)
+		default:
+			t.Errorf("unexpected op %q", op)
+			return `{"data":{}}`
+		}
+	})
+
+	in := `[{"name":"a","status":"done","due":"2026-05-10"},{"name":"b","number":42,"checkbox":true},{"name":"c"}]`
+	out, err := execItemCreateStdin(t, in, "--board", "9832181507", "-")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got := decodeBatch(t, out); got.Written != 3 {
+		t.Errorf("written = %d, want 3", got.Written)
+	}
+	if n := rec.countOp("BoardColumnList"); n != 1 {
+		t.Errorf("fetched board columns %d times, want exactly 1 for the whole batch", n)
+	}
+
+	cv0, _ := rec.varsFor("ItemCreate", 0)["columnValues"].(string)
+	var parsed0 map[string]json.RawMessage
+	if err := json.Unmarshal([]byte(cv0), &parsed0); err != nil {
+		t.Fatalf("row 0 columnValues is not JSON: %q", cv0)
+	}
+	if string(parsed0["status_1"]) != `{"label":"Done"}` {
+		t.Errorf("row 0 status_1 = %s, want the board's own casing", parsed0["status_1"])
+	}
+	if string(parsed0["date_4"]) != `{"date":"2026-05-10"}` {
+		t.Errorf("row 0 date_4 = %s", parsed0["date_4"])
+	}
+
+	cv1, _ := rec.varsFor("ItemCreate", 1)["columnValues"].(string)
+	var parsed1 map[string]json.RawMessage
+	if err := json.Unmarshal([]byte(cv1), &parsed1); err != nil {
+		t.Fatalf("row 1 columnValues is not JSON: %q", cv1)
+	}
+	if string(parsed1["numbers_7"]) != `"42"` {
+		t.Errorf("row 1 numbers_7 = %s, want a bare JSON number to be accepted", parsed1["numbers_7"])
+	}
+	if string(parsed1["checkbox_2"]) != `{"checked":"true"}` {
+		t.Errorf("row 1 checkbox_2 = %s, want a bare JSON bool to be accepted", parsed1["checkbox_2"])
+	}
+
+	// Row 2 sets nothing, so it must send an empty column_values rather than "{}".
+	if cv2, _ := rec.varsFor("ItemCreate", 2)["columnValues"].(string); cv2 != "" {
+		t.Errorf("row 2 columnValues = %q, want empty", cv2)
+	}
+}
+
+// TestItemCreateBatch_badLabelFailsBeforeAnyWrite: one bad status label must not
+// leave the first N items created. Validation happens before the first mutation.
+func TestItemCreateBatch_badLabelFailsBeforeAnyWrite(t *testing.T) {
+	rec, _ := newGQLRecorder(t, func(op string, _ map[string]any, _ int) string {
+		if op == "BoardColumnList" {
+			return boardColumnsBody()
+		}
+		t.Errorf("unexpected write %q: the batch should have failed validation first", op)
+		return `{"data":{}}`
+	})
+
+	in := `[{"name":"a","status":"done"},{"name":"b","status":"Dunn"}]`
+	_, err := execItemCreateStdin(t, in, "--board", "9832181507", "-")
+	if err == nil {
+		t.Fatal("want an error for an unknown status label")
+	}
+	if codeOf(err) != errs.CodeUsage {
+		t.Errorf("code = %s, want %s", codeOf(err), errs.CodeUsage)
+	}
+	if !strings.Contains(err.Error(), "row 1") {
+		t.Errorf("error %q does not name the offending row", err.Error())
+	}
+	if rec.countOp("ItemCreate") != 0 {
+		t.Errorf("created %d items before failing, want 0", rec.countOp("ItemCreate"))
+	}
+}
+
+// TestItemCreateBatch_partialFailure is the contract that makes a batch retryable:
+// exit 2, and errors[].index names exactly which rows to re-send.
+func TestItemCreateBatch_partialFailure(t *testing.T) {
+	rec, _ := newGQLRecorder(t, func(_ string, vars map[string]any, n int) string {
+		if n == 1 {
+			return gqlErrorBody("column not found", "InvalidColumnIdException")
+		}
+		name, _ := vars["name"].(string)
+		return itemCreateBody(fmt.Sprintf("400%d", n), name)
+	})
+
+	in := `[{"name":"a"},{"name":"b"},{"name":"c"}]`
+	out, err := execItemCreateStdin(t, in, "--board", "9832181507", "-")
+	if err == nil {
+		t.Fatal("want an error so a partial failure does not exit 0")
+	}
+	if got := errs.ToExitCode(err); got != 2 {
+		t.Errorf("exit code = %d, want 2", got)
+	}
+
+	got := decodeBatch(t, out)
+	if got.Written != 2 || got.Failed != 1 {
+		t.Errorf("written=%d failed=%d, want 2/1", got.Written, got.Failed)
+	}
+	if len(got.Errors) != 1 {
+		t.Fatalf("errors = %d, want 1", len(got.Errors))
+	}
+	if got.Errors[0].Index != 1 {
+		t.Errorf("failed row index = %d, want 1", got.Errors[0].Index)
+	}
+	if got.Errors[0].Code == "" {
+		t.Error("failed row has no code")
+	}
+	if got.Errors[0].Code == string(errs.CodeInternal) {
+		t.Errorf("failed row code = %s; an API rejection should not be reported as internal", got.Errors[0].Code)
+	}
+	if !strings.Contains(got.Errors[0].Message, "column not found") {
+		t.Errorf("failed row message = %q, want the API's message", got.Errors[0].Message)
+	}
+	// All three rows are attempted: one bad row does not abandon the rest.
+	if rec.countOp("ItemCreate") != 3 {
+		t.Errorf("made %d ItemCreate calls, want 3", rec.countOp("ItemCreate"))
+	}
+}
+
+func TestItemCreateBatch_validationErrors(t *testing.T) {
+	tests := []struct {
+		name string
+		in   string
+	}{
+		{name: "missing name", in: `[{"cols":{"text_9":"hi"}}]`},
+		{name: "blank name", in: `[{"name":"   "}]`},
+		{name: "id not allowed on create", in: `[{"name":"a","id":"456"}]`},
+		{name: "date and due together", in: `[{"name":"a","date":"2026-05-10","due":"2026-06-01"}]`},
+		{name: "empty col id", in: `[{"name":"a","cols":{"":"hi"}}]`},
+		{name: "second row invalid", in: `[{"name":"a"},{"name":""}]`},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			rec, _ := newGQLRecorder(t, func(op string, _ map[string]any, _ int) string {
+				t.Errorf("unexpected request %q for invalid input", op)
+				return `{"data":{}}`
+			})
+			_, err := execItemCreateStdin(t, tt.in, "--board", "9832181507", "-")
+			if err == nil {
+				t.Fatalf("want an error for %s", tt.name)
+			}
+			if codeOf(err) != errs.CodeUsage {
+				t.Errorf("code = %s, want %s", codeOf(err), errs.CodeUsage)
+			}
+			if len(rec.ops()) != 0 {
+				t.Errorf("made %d requests for invalid input, want 0", len(rec.ops()))
+			}
+		})
+	}
+}
+
+// TestItemCreateBatch_flagsRejected: silently ignoring --name in batch mode would
+// create N items that all disagree with what the caller typed.
+func TestItemCreateBatch_flagsRejected(t *testing.T) {
+	for _, extra := range [][]string{
+		{"--name", "x"},
+		{"--col", "text_9=\"hi\""},
+		{"--status", "Done"},
+	} {
+		args := append([]string{"--board", "9832181507", "-"}, extra...)
+		_, err := execItemCreateStdin(t, `[{"name":"a"}]`, args...)
+		if err == nil {
+			t.Errorf("want an error for batch mode with %v", extra)
+			continue
+		}
+		if codeOf(err) != errs.CodeUsage {
+			t.Errorf("code for %v = %s, want %s", extra, codeOf(err), errs.CodeUsage)
+		}
+	}
+}
+
+func TestItemCreateBatch_parentRejected(t *testing.T) {
+	_, err := execItemCreateStdin(t, `[{"name":"a"}]`, "--parent", "456", "-")
+	if err == nil {
+		t.Fatal("want an error: subitems cannot be created in batch")
+	}
+	if codeOf(err) != errs.CodeUsage {
+		t.Errorf("code = %s, want %s", codeOf(err), errs.CodeUsage)
+	}
+}
+
+// TestItemCreateBatch_dryRunSendsNothing keeps --dry-run honest: it must not need a
+// token and must not write.
+func TestItemCreateBatch_dryRunSendsNothing(t *testing.T) {
+	rec, _ := newGQLRecorder(t, func(op string, _ map[string]any, _ int) string {
+		t.Errorf("dry run made a request: %q", op)
+		return `{"data":{}}`
+	})
+
+	in := `[{"name":"a","cols":{"text_9":"hi"}},{"name":"b"}]`
+	out, err := execItemCreateStdin(t, in, "--board", "9832181507", "-", "--dry-run")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(rec.ops()) != 0 {
+		t.Errorf("dry run made %d requests, want 0", len(rec.ops()))
+	}
+
+	var got batchDryRunOutput
+	if err := json.Unmarshal([]byte(strings.TrimSpace(out)), &got); err != nil {
+		t.Fatalf("parse output: %v\nraw: %s", err, out)
+	}
+	if !got.DryRun || got.Rows != 2 || len(got.Items) != 2 {
+		t.Fatalf("dry run output = %+v", got)
+	}
+	if got.Items[0].ColumnValues != `{"text_9":"hi"}` {
+		t.Errorf("row 0 column_values = %q", got.Items[0].ColumnValues)
+	}
+	if got.Items[1].Name != "b" {
+		t.Errorf("row 1 name = %q, want b", got.Items[1].Name)
+	}
+}
+
+// TestItemCreateBatch_dryRunWithShorthandsResolvesColumns: a dry run is the way to
+// check a shorthand resolves, so it does fetch columns — but still writes nothing.
+func TestItemCreateBatch_dryRunWithShorthandsResolvesColumns(t *testing.T) {
+	rec, _ := newGQLRecorder(t, func(op string, _ map[string]any, _ int) string {
+		if op == "BoardColumnList" {
+			return boardColumnsBody()
+		}
+		t.Errorf("dry run made a write request: %q", op)
+		return `{"data":{}}`
+	})
+
+	out, err := execItemCreateStdin(t, `[{"name":"a","status":"Done"}]`, "--board", "9832181507", "-", "--dry-run")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if n := rec.countOp("BoardColumnList"); n != 1 {
+		t.Errorf("fetched board columns %d times, want 1", n)
+	}
+	if rec.countOp("ItemCreate") != 0 {
+		t.Error("dry run created an item")
+	}
+	if !strings.Contains(out, `status_1`) {
+		t.Errorf("dry run output does not show the resolved column: %s", out)
+	}
+}
+
+// TestItemCreateBatch_positionalArgRejected: a bare item name as a positional arg is
+// an easy mistake, and silently ignoring it would create nothing useful.
+func TestItemCreateBatch_positionalArgRejected(t *testing.T) {
+	_, err := execItemCreateStdin(t, "", "--board", "9832181507", "My Item")
+	if err == nil {
+		t.Fatal("want an error for an unexpected positional argument")
+	}
+	if codeOf(err) != errs.CodeUsage {
+		t.Errorf("code = %s, want %s", codeOf(err), errs.CodeUsage)
+	}
+}
+
+// ---- update batch ----
+
+func TestItemUpdateBatch_happyPath(t *testing.T) {
+	rec, _ := newGQLRecorder(t, func(op string, vars map[string]any, _ int) string {
+		if op != "ItemUpdate" {
+			t.Errorf("unexpected op %q", op)
+		}
+		id, _ := vars["itemId"].(string)
+		return itemUpdateBody(id, "renamed")
+	})
+
+	in := "{\"id\":\"111\",\"cols\":{\"text_9\":\"hi\"}}\n{\"id\":\"222\",\"name\":\"renamed\"}\n"
+	out, err := execItemUpdateStdin(t, in, "--board", "9832181507", "-")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	got := decodeBatch(t, out)
+	if got.Written != 2 || got.Failed != 0 {
+		t.Errorf("written=%d failed=%d, want 2/0", got.Written, got.Failed)
+	}
+	if got.Verb != "updated" {
+		t.Errorf("verb = %q, want updated", got.Verb)
+	}
+	if id, _ := rec.varsFor("ItemUpdate", 0)["itemId"].(string); id != "111" {
+		t.Errorf("row 0 itemId = %q, want 111", id)
+	}
+	// A row's "name" is written through the name column, as the single path does.
+	if cv, _ := rec.varsFor("ItemUpdate", 1)["columnValues"].(string); cv != `{"name":"renamed"}` {
+		t.Errorf("row 1 columnValues = %q, want the name column", cv)
+	}
+}
+
+func TestItemUpdateBatch_validationErrors(t *testing.T) {
+	tests := []struct {
+		name string
+		in   string
+	}{
+		{name: "missing id", in: `[{"name":"a"}]`},
+		{name: "non-numeric id", in: `[{"id":"abc","name":"a"}]`},
+		{name: "nothing to update", in: `[{"id":"111"}]`},
+		{name: "second row has no id", in: `[{"id":"111","name":"a"},{"name":"b"}]`},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			rec, _ := newGQLRecorder(t, func(op string, _ map[string]any, _ int) string {
+				t.Errorf("unexpected request %q for invalid input", op)
+				return `{"data":{}}`
+			})
+			_, err := execItemUpdateStdin(t, tt.in, "--board", "9832181507", "-")
+			if err == nil {
+				t.Fatalf("want an error for %s", tt.name)
+			}
+			if codeOf(err) != errs.CodeUsage {
+				t.Errorf("code = %s, want %s", codeOf(err), errs.CodeUsage)
+			}
+			if len(rec.ops()) != 0 {
+				t.Errorf("made %d requests for invalid input, want 0", len(rec.ops()))
+			}
+		})
+	}
+}
+
+func TestItemUpdateBatch_partialFailure(t *testing.T) {
+	newGQLRecorder(t, func(_ string, vars map[string]any, n int) string {
+		if n == 0 {
+			return gqlErrorBody("item not found", "ResourceNotFoundException")
+		}
+		id, _ := vars["itemId"].(string)
+		return itemUpdateBody(id, "ok")
+	})
+
+	in := `[{"id":"111","name":"a"},{"id":"222","name":"b"}]`
+	out, err := execItemUpdateStdin(t, in, "--board", "9832181507", "-")
+	if err == nil {
+		t.Fatal("want an error so a partial failure does not exit 0")
+	}
+	if got := errs.ToExitCode(err); got != 2 {
+		t.Errorf("exit code = %d, want 2", got)
+	}
+
+	got := decodeBatch(t, out)
+	if got.Written != 1 || got.Failed != 1 {
+		t.Errorf("written=%d failed=%d, want 1/1", got.Written, got.Failed)
+	}
+	if len(got.Errors) != 1 {
+		t.Fatalf("errors = %d, want 1", len(got.Errors))
+	}
+	// The item id is echoed on the failure so a caller can retry by id, not position.
+	if got.Errors[0].ID != "111" {
+		t.Errorf("failed row id = %q, want 111", got.Errors[0].ID)
+	}
+	if got.Errors[0].Index != 0 {
+		t.Errorf("failed row index = %d, want 0", got.Errors[0].Index)
+	}
+}
+
+func TestItemUpdateBatch_flagsRejected(t *testing.T) {
+	_, err := execItemUpdateStdin(t, `[{"id":"111","name":"a"}]`, "--board", "9832181507", "-", "--name", "x")
+	if err == nil {
+		t.Fatal("want an error for batch mode with --name")
+	}
+	if codeOf(err) != errs.CodeUsage {
+		t.Errorf("code = %s, want %s", codeOf(err), errs.CodeUsage)
+	}
+}
+
+// ---- single-item shorthands ----
+
+func TestItemCreate_shorthandFlags(t *testing.T) {
+	rec, _ := newGQLRecorder(t, func(op string, vars map[string]any, _ int) string {
+		if op == "BoardColumnList" {
+			return boardColumnsBody()
+		}
+		name, _ := vars["name"].(string)
+		return itemCreateBody("5001", name)
+	})
+
+	_, err := execItemCreateStdin(t, "", "--board", "9832181507", "--name", "Ship v1",
+		"--status", "working on it", "--due", "2026-05-10T09:00", "--number", "3", "--checkbox", "yes")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	cv, _ := rec.varsFor("ItemCreate", 0)["columnValues"].(string)
+	var parsed map[string]json.RawMessage
+	if err := json.Unmarshal([]byte(cv), &parsed); err != nil {
+		t.Fatalf("columnValues is not JSON: %q", cv)
+	}
+	want := map[string]string{
+		"status_1":   `{"label":"Working on it"}`,
+		"date_4":     `{"date":"2026-05-10","time":"09:00:00"}`,
+		"numbers_7":  `"3"`,
+		"checkbox_2": `{"checked":"true"}`,
+	}
+	for col, wantVal := range want {
+		if string(parsed[col]) != wantVal {
+			t.Errorf("%s = %s, want %s", col, parsed[col], wantVal)
+		}
+	}
+	// The archived status column must not have been written to.
+	if _, ok := parsed["status_old"]; ok {
+		t.Error("wrote to an archived column")
+	}
+}
+
+// TestItemCreate_shorthandNoColumnOfType: the board fixture has no checkbox column,
+// so --checkbox must fail loudly rather than being dropped.
+func TestItemCreate_shorthandNoColumnOfType(t *testing.T) {
+	rec, _ := newGQLRecorder(t, func(op string, _ map[string]any, _ int) string {
+		if op == "BoardColumnList" {
+			return boardColumnsBodyTextOnly()
+		}
+		t.Errorf("unexpected write %q", op)
+		return `{"data":{}}`
+	})
+
+	_, err := execItemCreateStdin(t, "", "--board", "9832181507", "--name", "x", "--checkbox", "true")
+	if err == nil {
+		t.Fatal("want an error: the board has no checkbox column")
+	}
+	if codeOf(err) != errs.CodeUsage {
+		t.Errorf("code = %s, want %s", codeOf(err), errs.CodeUsage)
+	}
+	if rec.countOp("ItemCreate") != 0 {
+		t.Error("created an item despite an unresolvable shorthand")
+	}
+}
+
+// TestItemCreate_shorthandCollidesWithCol keeps an ambiguous write from happening.
+func TestItemCreate_shorthandCollidesWithCol(t *testing.T) {
+	newGQLRecorder(t, func(op string, _ map[string]any, _ int) string {
+		if op == "BoardColumnList" {
+			return boardColumnsBody()
+		}
+		t.Errorf("unexpected write %q", op)
+		return `{"data":{}}`
+	})
+
+	_, err := execItemCreateStdin(t, "", "--board", "9832181507", "--name", "x",
+		"--status", "Done", "--col", `status_1={"index":2}`)
+	if err == nil {
+		t.Fatal("want an error when --status and --col target one column")
+	}
+	if codeOf(err) != errs.CodeUsage {
+		t.Errorf("code = %s, want %s", codeOf(err), errs.CodeUsage)
+	}
+}
+
+func TestItemCreate_shorthandWithParentRejected(t *testing.T) {
+	_, err := execItemCreateStdin(t, "", "--parent", "456", "--name", "x", "--status", "Done")
+	if err == nil {
+		t.Fatal("want an error: shorthands need --board")
+	}
+	if codeOf(err) != errs.CodeUsage {
+		t.Errorf("code = %s, want %s", codeOf(err), errs.CodeUsage)
+	}
+}
+
+// TestItemCreate_dateAndDueMutuallyExclusive: cobra enforces this, and it must stay
+// enforced — the two flags write the same column.
+func TestItemCreate_dateAndDueMutuallyExclusive(t *testing.T) {
+	_, err := execItemCreateStdin(t, "", "--board", "9832181507", "--name", "x",
+		"--date", "2026-05-10", "--due", "2026-06-01")
+	if err == nil {
+		t.Fatal("want an error when both --date and --due are given")
+	}
+}
+
+// TestItemUpdate_shorthandFlags checks the update path resolves shorthands too, and
+// that --name still travels as the name column alongside them.
+func TestItemUpdate_shorthandFlags(t *testing.T) {
+	rec, _ := newGQLRecorder(t, func(op string, vars map[string]any, _ int) string {
+		if op == "BoardColumnList" {
+			return boardColumnsBody()
+		}
+		id, _ := vars["itemId"].(string)
+		return itemUpdateBody(id, "x")
+	})
+
+	_, err := execItemUpdateStdin(t, "", "111", "--board", "9832181507", "--name", "x", "--status", "Done")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	cv, _ := rec.varsFor("ItemUpdate", 0)["columnValues"].(string)
+	var parsed map[string]json.RawMessage
+	if err := json.Unmarshal([]byte(cv), &parsed); err != nil {
+		t.Fatalf("columnValues is not JSON: %q", cv)
+	}
+	if string(parsed["status_1"]) != `{"label":"Done"}` {
+		t.Errorf("status_1 = %s", parsed["status_1"])
+	}
+	if string(parsed["name"]) != `"x"` {
+		t.Errorf("name = %s, want \"x\"", parsed["name"])
+	}
+}
+
+// TestItemUpdate_shorthandOnlyIsEnough: a shorthand alone must satisfy the
+// "nothing to update" guard, which predates shorthands.
+func TestItemUpdate_shorthandOnlyIsEnough(t *testing.T) {
+	rec, _ := newGQLRecorder(t, func(op string, vars map[string]any, _ int) string {
+		if op == "BoardColumnList" {
+			return boardColumnsBody()
+		}
+		id, _ := vars["itemId"].(string)
+		return itemUpdateBody(id, "x")
+	})
+
+	if _, err := execItemUpdateStdin(t, "", "111", "--board", "9832181507", "--status", "Done"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if rec.countOp("ItemUpdate") != 1 {
+		t.Errorf("made %d ItemUpdate calls, want 1", rec.countOp("ItemUpdate"))
+	}
+}
+
+// TestItemCreate_clearTextWithEmptyShorthand: --text "" must reach the API as an
+// empty value, not be treated as "flag not set".
+func TestItemCreate_clearTextWithEmptyShorthand(t *testing.T) {
+	rec, _ := newGQLRecorder(t, func(op string, vars map[string]any, _ int) string {
+		if op == "BoardColumnList" {
+			return boardColumnsBody()
+		}
+		name, _ := vars["name"].(string)
+		return itemCreateBody("6001", name)
+	})
+
+	if _, err := execItemCreateStdin(t, "", "--board", "9832181507", "--name", "x", "--text", ""); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	cv, _ := rec.varsFor("ItemCreate", 0)["columnValues"].(string)
+	if cv != `{"text_9":""}` {
+		t.Errorf("columnValues = %q, want the text column cleared", cv)
+	}
+}
diff --git a/internal/cli/item_shorthand.go b/internal/cli/item_shorthand.go
new file mode 100644
index 0000000..f3b601d
--- /dev/null
+++ b/internal/cli/item_shorthand.go
@@ -0,0 +1,230 @@
+package cli
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"sort"
+	"strings"
+
+	gqlclient "github.com/Khan/genqlient/graphql"
+	"github.com/spf13/cobra"
+
+	"github.com/mondaycom/mcli/internal/api/gen"
+	"github.com/mondaycom/mcli/internal/api/items/columns"
+	"github.com/mondaycom/mcli/internal/errs"
+)
+
+// shorthandSpec maps one typed shorthand flag to the monday column type it writes.
+// There is no column id in the flag, so the column is resolved by type against the
+// board's live columns; see boardColumnIndex.resolve.
+type shorthandSpec struct {
+	flag       string
+	columnType string
+	usage      string
+}
+
+// shorthandSpecs are the typed column shorthands, in the order they are applied and
+// reported. Every columnType here must be encodable by the columns package
+// (enforced by TestShorthandSpecs_AreEncodable).
+var shorthandSpecs = []shorthandSpec{
+	{flag: "text", columnType: "text", usage: `set the board's text column, e.g. --text "Follow up"`},
+	{flag: "status", columnType: "status", usage: `set the board's status column by label, e.g. --status Done`},
+	{flag: "date", columnType: "date", usage: `set the board's date column, e.g. --date 2026-05-10 or 2026-05-10T14:30`},
+	{flag: "due", columnType: "date", usage: `alias for --date`},
+	{flag: "number", columnType: "numbers", usage: `set the board's numbers column, e.g. --number 42`},
+	{flag: "checkbox", columnType: "checkbox", usage: `set the board's checkbox column, e.g. --checkbox true`},
+}
+
+// shorthandValue is one shorthand the caller actually supplied.
+type shorthandValue struct {
+	spec  shorthandSpec
+	value string
+}
+
+// encodedShorthand is a shorthand after resolution: which column it landed on and
+// the wire JSON written there.
+type encodedShorthand struct {
+	flag  string
+	colID string
+	title string
+	value json.RawMessage
+}
+
+// addShorthandFlags declares the typed column shorthands on cmd and returns the
+// destinations they parse into, keyed by flag name.
+func addShorthandFlags(cmd *cobra.Command) map[string]*string {
+	vals := make(map[string]*string, len(shorthandSpecs))
+	for _, sp := range shorthandSpecs {
+		v := new(string)
+		cmd.Flags().StringVar(v, sp.flag, "", sp.usage)
+		vals[sp.flag] = v
+	}
+	// --due is sugar for --date; accepting both would be ambiguous about precedence.
+	cmd.MarkFlagsMutuallyExclusive("date", "due")
+	return vals
+}
+
+// setShorthands returns the shorthands the caller passed, in spec order. A flag left
+// at its zero value is not "set an empty value" — only Changed counts, so
+// `--text ""` still clears a text column.
+func setShorthands(cmd *cobra.Command, vals map[string]*string) []shorthandValue {
+	var out []shorthandValue
+	for _, sp := range shorthandSpecs {
+		if cmd.Flags().Changed(sp.flag) {
+			out = append(out, shorthandValue{spec: sp, value: *vals[sp.flag]})
+		}
+	}
+	return out
+}
+
+// writableColumn is the subset of a board column needed to write to it.
+type writableColumn struct {
+	id       string
+	title    string
+	colType  string
+	settings string
+}
+
+// boardColumnIndex holds a board's live columns grouped by type.
+//
+// It is fetched at most once per invocation and never cached across invocations: a
+// stale mapping would resolve a shorthand onto a column that has since been deleted
+// or retyped, which writes the right value to the wrong place. One extra request is
+// the cheaper mistake.
+type boardColumnIndex struct {
+	byType map[string][]writableColumn
+	// types is the sorted set of types present, for "the board has none" errors.
+	types []string
+}
+
+// fetchBoardColumnIndex reads the board's columns. Archived columns are skipped:
+// they cannot be written and would only create phantom ambiguity.
+func fetchBoardColumnIndex(ctx context.Context, gql gqlclient.Client, boardID string) (*boardColumnIndex, error) {
+	resp, err := gen.BoardColumnList(ctx, gql, boardID)
+	if err != nil {
+		return nil, err
+	}
+	if len(resp.Boards) == 0 {
+		return nil, errs.NotFound("board %s", boardID)
+	}
+
+	idx := &boardColumnIndex{byType: make(map[string][]writableColumn)}
+	for _, c := range resp.Boards[0].Columns {
+		if c.Archived {
+			continue
+		}
+		t := string(c.Type)
+		idx.byType[t] = append(idx.byType[t], writableColumn{
+			id: c.Id, title: c.Title, colType: t, settings: c.Settings_str,
+		})
+	}
+	for t := range idx.byType {
+		idx.types = append(idx.types, t)
+	}
+	sort.Strings(idx.types)
+	return idx, nil
+}
+
+// resolve returns the board's single column of the spec's type.
+//
+// It never guesses. Silently taking the first of three status columns would move the
+// wrong field on a CRM board, and an LLM caller would have no way to notice.
+func (idx *boardColumnIndex) resolve(sp shorthandSpec) (writableColumn, error) {
+	candidates := idx.byType[sp.columnType]
+	switch len(candidates) {
+	case 1:
+		return candidates[0], nil
+	case 0:
+		types := "none"
+		if len(idx.types) > 0 {
+			types = strings.Join(idx.types, ", ")
+		}
+		return writableColumn{}, errs.Usage("--%s needs a %s column, but this board has none; its column types are: %s",
+			sp.flag, sp.columnType, types)
+	default:
+		parts := make([]string, 0, len(candidates))
+		for _, c := range candidates {
+			parts = append(parts, fmt.Sprintf("%s (%q)", c.id, c.title))
+		}
+		return writableColumn{}, errs.Usage("--%s is ambiguous: this board has %d %s columns: %s — use --col <id>=<json> to pick one",
+			sp.flag, len(candidates), sp.columnType, strings.Join(parts, ", "))
+	}
+}
+
+// encodeShorthands resolves each shorthand against the board's columns and encodes
+// its value into monday's wire shape.
+func encodeShorthands(idx *boardColumnIndex, set []shorthandValue) ([]encodedShorthand, error) {
+	out := make([]encodedShorthand, 0, len(set))
+	seen := make(map[string]string, len(set))
+
+	for _, sv := range set {
+		col, err := idx.resolve(sv.spec)
+		if err != nil {
+			return nil, err
+		}
+		if prev, dup := seen[col.id]; dup {
+			return nil, errs.Usage("--%s and --%s both target column %s; use only one", prev, sv.spec.flag, col.id)
+		}
+		seen[col.id] = sv.spec.flag
+
+		value, err := columns.Encode(sv.spec.columnType, col.settings, sv.value)
+		if err != nil {
+			return nil, annotateShorthandError(sv.spec.flag, col, err)
+		}
+
+		out = append(out, encodedShorthand{flag: sv.spec.flag, colID: col.id, title: col.title, value: value})
+	}
+	return out, nil
+}
+
+// annotateShorthandError re-points an encoder error at the flag and column the caller
+// can actually see. The encoder only knows the column type.
+func annotateShorthandError(flag string, col writableColumn, err error) error {
+	msg := err.Error()
+	if e, ok := errors.AsType[*errs.Error](err); ok {
+		msg = e.Message
+	}
+	return errs.Usage("--%s (column %s %q): %s", flag, col.id, col.title, msg)
+}
+
+// mergeShorthands folds resolved shorthands into a --col map.
+//
+// A collision is an error rather than a precedence rule: if --status and
+// --col status_1=… both target one column, silently letting either win is how you
+// ship a write that does not match what the caller wrote.
+func mergeShorthands(cols map[string]json.RawMessage, enc []encodedShorthand) error {
+	for _, e := range enc {
+		if _, exists := cols[e.colID]; exists {
+			return errs.Usage("--%s and --col %s both target column %s (%q); use only one",
+				e.flag, e.colID, e.colID, e.title)
+		}
+		cols[e.colID] = e.value
+	}
+	return nil
+}
+
+// applyShorthands resolves and merges shorthands into cols, fetching the board's
+// columns only when at least one shorthand is set — a pure --col invocation stays a
+// single request, exactly as before.
+func applyShorthands(
+	ctx context.Context, gql gqlclient.Client, boardID string,
+	cols map[string]json.RawMessage, set []shorthandValue,
+) ([]encodedShorthand, error) {
+	if len(set) == 0 {
+		return nil, nil
+	}
+	idx, err := fetchBoardColumnIndex(ctx, gql, boardID)
+	if err != nil {
+		return nil, err
+	}
+	enc, err := encodeShorthands(idx, set)
+	if err != nil {
+		return nil, err
+	}
+	if err := mergeShorthands(cols, enc); err != nil {
+		return nil, err
+	}
+	return enc, nil
+}
diff --git a/internal/cli/item_shorthand_test.go b/internal/cli/item_shorthand_test.go
new file mode 100644
index 0000000..c7897ba
--- /dev/null
+++ b/internal/cli/item_shorthand_test.go
@@ -0,0 +1,238 @@
+package cli
+
+import (
+	"encoding/json"
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/mondaycom/mcli/internal/api/items/columns"
+	"github.com/mondaycom/mcli/internal/errs"
+)
+
+// statusSettings is a status column's settings_str as monday reports it.
+const testStatusSettings = `{"labels":{"0":"Not Started","1":"Working on it","2":"Done"}}`
+
+// codeOf returns an error's errs code, or "" if it is not an *errs.Error.
+func codeOf(err error) errs.Code {
+	if e, ok := errors.AsType[*errs.Error](err); ok {
+		return e.Code
+	}
+	return ""
+}
+
+// testIndex builds a boardColumnIndex without going through the API.
+func testIndex(cols ...writableColumn) *boardColumnIndex {
+	idx := &boardColumnIndex{byType: map[string][]writableColumn{}}
+	for _, c := range cols {
+		idx.byType[c.colType] = append(idx.byType[c.colType], c)
+	}
+	for t := range idx.byType {
+		idx.types = append(idx.types, t)
+	}
+	return idx
+}
+
+// specFor returns the shorthandSpec for a flag name.
+func specFor(t *testing.T, flag string) shorthandSpec {
+	t.Helper()
+	for _, sp := range shorthandSpecs {
+		if sp.flag == flag {
+			return sp
+		}
+	}
+	t.Fatalf("no shorthand spec for --%s", flag)
+	return shorthandSpec{}
+}
+
+// TestShorthandSpecs_AreEncodable guards the contract in shorthandSpecs' doc comment:
+// a flag whose column type has no encoder would fail at runtime, not at build time.
+func TestShorthandSpecs_AreEncodable(t *testing.T) {
+	encodable := map[string]bool{}
+	for _, ct := range columns.EncodableTypes() {
+		encodable[ct] = true
+	}
+	for _, sp := range shorthandSpecs {
+		if !encodable[sp.columnType] {
+			t.Errorf("--%s writes column type %q, which columns.Encode does not support", sp.flag, sp.columnType)
+		}
+	}
+}
+
+func TestBoardColumnIndex_resolveOne(t *testing.T) {
+	idx := testIndex(
+		writableColumn{id: "status_1", title: "Stage", colType: "status", settings: testStatusSettings},
+		writableColumn{id: "text_9", title: "Notes", colType: "text"},
+	)
+	got, err := idx.resolve(specFor(t, "status"))
+	if err != nil {
+		t.Fatalf("resolve: %v", err)
+	}
+	if got.id != "status_1" {
+		t.Errorf("resolved column = %q, want status_1", got.id)
+	}
+}
+
+// TestBoardColumnIndex_resolveNone checks the error names the types the board does
+// have, so a caller can pick a real column instead of guessing again.
+func TestBoardColumnIndex_resolveNone(t *testing.T) {
+	idx := testIndex(
+		writableColumn{id: "text_9", title: "Notes", colType: "text"},
+		writableColumn{id: "people_2", title: "Owner", colType: "people"},
+	)
+	_, err := idx.resolve(specFor(t, "status"))
+	if err == nil {
+		t.Fatal("want an error when the board has no status column")
+	}
+	if codeOf(err) != errs.CodeUsage {
+		t.Errorf("code = %s, want %s", codeOf(err), errs.CodeUsage)
+	}
+	for _, want := range []string{"text", "people"} {
+		if !strings.Contains(err.Error(), want) {
+			t.Errorf("error %q does not name existing type %q", err.Error(), want)
+		}
+	}
+}
+
+// TestBoardColumnIndex_resolveAmbiguous is the important one: guessing here would
+// write a correct value to the wrong column, silently.
+func TestBoardColumnIndex_resolveAmbiguous(t *testing.T) {
+	idx := testIndex(
+		writableColumn{id: "status_1", title: "Stage", colType: "status", settings: testStatusSettings},
+		writableColumn{id: "status_2", title: "Priority", colType: "status", settings: testStatusSettings},
+	)
+	_, err := idx.resolve(specFor(t, "status"))
+	if err == nil {
+		t.Fatal("want an error when the board has two status columns")
+	}
+	if codeOf(err) != errs.CodeUsage {
+		t.Errorf("code = %s, want %s", codeOf(err), errs.CodeUsage)
+	}
+	for _, want := range []string{"status_1", "Stage", "status_2", "Priority", "--col"} {
+		if !strings.Contains(err.Error(), want) {
+			t.Errorf("error %q does not mention %q", err.Error(), want)
+		}
+	}
+}
+
+func TestEncodeShorthands(t *testing.T) {
+	idx := testIndex(
+		writableColumn{id: "status_1", title: "Stage", colType: "status", settings: testStatusSettings},
+		writableColumn{id: "date_4", title: "Due", colType: "date"},
+		writableColumn{id: "numbers_7", title: "Estimate", colType: "numbers"},
+	)
+
+	set := []shorthandValue{
+		{spec: specFor(t, "status"), value: "done"},
+		{spec: specFor(t, "due"), value: "2026-05-10"},
+		{spec: specFor(t, "number"), value: "3.5"},
+	}
+
+	enc, err := encodeShorthands(idx, set)
+	if err != nil {
+		t.Fatalf("encodeShorthands: %v", err)
+	}
+	if len(enc) != 3 {
+		t.Fatalf("encoded %d shorthands, want 3", len(enc))
+	}
+
+	byCol := map[string]string{}
+	for _, e := range enc {
+		byCol[e.colID] = string(e.value)
+	}
+	want := map[string]string{
+		"status_1":  `{"label":"Done"}`,
+		"date_4":    `{"date":"2026-05-10"}`,
+		"numbers_7": `"3.5"`,
+	}
+	for col, wantVal := range want {
+		if byCol[col] != wantVal {
+			t.Errorf("column %s = %s, want %s", col, byCol[col], wantVal)
+		}
+	}
+}
+
+// TestEncodeShorthands_badLabelNamesFlagAndColumn checks the encoder's error is
+// re-pointed at what the caller typed. "status: 'Dunn' is not a label" is much less
+// useful than naming the flag and the column it resolved to.
+func TestEncodeShorthands_badLabelNamesFlagAndColumn(t *testing.T) {
+	idx := testIndex(writableColumn{id: "status_1", title: "Stage", colType: "status", settings: testStatusSettings})
+	_, err := encodeShorthands(idx, []shorthandValue{{spec: specFor(t, "status"), value: "Dunn"}})
+	if err == nil {
+		t.Fatal("want an error for an unknown status label")
+	}
+	if codeOf(err) != errs.CodeUsage {
+		t.Errorf("code = %s, want %s", codeOf(err), errs.CodeUsage)
+	}
+	for _, want := range []string{"--status", "status_1", "Stage", "Done"} {
+		if !strings.Contains(err.Error(), want) {
+			t.Errorf("error %q does not mention %q", err.Error(), want)
+		}
+	}
+}
+
+// TestEncodeShorthands_twoFlagsOneColumn covers --date and --due both landing on the
+// board's only date column when the mutual-exclusion check is bypassed (batch rows go
+// through their own validation, so this layer must still refuse).
+func TestEncodeShorthands_twoFlagsOneColumn(t *testing.T) {
+	idx := testIndex(writableColumn{id: "date_4", title: "Due", colType: "date"})
+	_, err := encodeShorthands(idx, []shorthandValue{
+		{spec: specFor(t, "date"), value: "2026-05-10"},
+		{spec: specFor(t, "due"), value: "2026-06-01"},
+	})
+	if err == nil {
+		t.Fatal("want an error when two shorthands target one column")
+	}
+	if codeOf(err) != errs.CodeUsage {
+		t.Errorf("code = %s, want %s", codeOf(err), errs.CodeUsage)
+	}
+}
+
+func TestMergeShorthands(t *testing.T) {
+	cols := map[string]json.RawMessage{"text_9": json.RawMessage(`"hi"`)}
+	err := mergeShorthands(cols, []encodedShorthand{
+		{flag: "status", colID: "status_1", title: "Stage", value: json.RawMessage(`{"label":"Done"}`)},
+	})
+	if err != nil {
+		t.Fatalf("mergeShorthands: %v", err)
+	}
+	if string(cols["status_1"]) != `{"label":"Done"}` {
+		t.Errorf("status_1 = %s, want the encoded label", cols["status_1"])
+	}
+	if string(cols["text_9"]) != `"hi"` {
+		t.Errorf("mergeShorthands clobbered an existing --col value")
+	}
+}
+
+// TestMergeShorthands_collision: --status and --col status_1=... in one command is
+// ambiguous. Picking a winner would send a value the caller did not ask for.
+func TestMergeShorthands_collision(t *testing.T) {
+	cols := map[string]json.RawMessage{"status_1": json.RawMessage(`{"index":2}`)}
+	err := mergeShorthands(cols, []encodedShorthand{
+		{flag: "status", colID: "status_1", title: "Stage", value: json.RawMessage(`{"label":"Done"}`)},
+	})
+	if err == nil {
+		t.Fatal("want an error when a shorthand and --col target one column")
+	}
+	if codeOf(err) != errs.CodeUsage {
+		t.Errorf("code = %s, want %s", codeOf(err), errs.CodeUsage)
+	}
+	for _, want := range []string{"--status", "--col", "status_1"} {
+		if !strings.Contains(err.Error(), want) {
+			t.Errorf("error %q does not mention %q", err.Error(), want)
+		}
+	}
+}
+
+// TestApplyShorthands_noneSkipsFetch: a pure --col command must not gain a request.
+// A nil client would panic if applyShorthands tried to use it.
+func TestApplyShorthands_noneSkipsFetch(t *testing.T) {
+	cols := map[string]json.RawMessage{"text_9": json.RawMessage(`"hi"`)}
+	enc, err := applyShorthands(t.Context(), nil, "123", cols, nil)
+	if err != nil {
+		t.Fatalf("applyShorthands: %v", err)
+	}
+	if len(enc) != 0 {
+		t.Errorf("encoded %d shorthands, want 0", len(enc))
+	}
+}
diff --git a/internal/cli/root.go b/internal/cli/root.go
index 75c7656..76bdb81 100644
--- a/internal/cli/root.go
+++ b/internal/cli/root.go
@@ -64,9 +64,13 @@ func init() {
 	rootCmd.AddCommand(newSearchCmd())
 	rootCmd.AddCommand(newDocCmd())
 	rootCmd.AddCommand(newAPICmd())
+	rootCmd.AddCommand(newSchemaCmd())
 
 	requireKnownSubcommands(rootCmd)
 
+	// Subcommands inherit this: cobra's FlagErrorFunc() walks up to the parent.
+	rootCmd.SetFlagErrorFunc(usageFlagError)
+
 	apischema.SetConfigDir(resolveConfigDir())
 }
 
@@ -74,6 +78,13 @@ func init() {
 // the user (or an LLM) at the command index.
 const unknownCommandHint = "Run 'mcli help' to see available commands."
 
+// usageFlagError classifies a flag parse failure (unknown flag, missing value, bad
+// value) as a usage error. Cobra returns these as plain errors, which would otherwise
+// reach the exit-code translator unclassified and report INTERNAL.
+func usageFlagError(cmd *cobra.Command, err error) error {
+	return errs.Usage("%s\nRun '%s --help' for usage.", err.Error(), cmd.CommandPath())
+}
+
 // requireKnownSubcommands makes every namespace command (one with subcommands
 // but no action of its own) reject unknown subcommands. Cobra's default shows
 // the namespace's help and exits 0, so a typo like `mcli item lst` looks like a
@@ -102,18 +113,56 @@ func Execute(ctx context.Context) error {
 	return friendlyUnknownCommand(rootCmd.Execute())
 }
 
-// friendlyUnknownCommand rewrites cobra's bare "unknown command …" error (raised
-// for an unknown top-level command) into a usage error that points at
-// `mcli help`. This gives a typo an actionable message and exit code 1 (usage)
-// instead of a generic exit 5, while preserving any "Did you mean …?" suggestion
-// cobra already put in the message. Unknown subcommands are handled in
-// requireKnownSubcommands and already carry the hint, so they don't match here.
+// cobraArgErrorMarkers identify cobra's argument-count validation failures
+// (cobra.ExactArgs and friends). Cobra builds these with fmt.Errorf and exposes no
+// sentinel, so matching the message is the only hook available. The markers are the
+// invariant middles of those messages rather than their prefixes, which vary
+// ("accepts", "accepts at most", "accepts between … and …").
+var cobraArgErrorMarkers = []string{
+	" arg(s), received ",      // accepts N / at most N / between N and M
+	" arg(s), only received ", // requires at least N
+}
+
+// cobraFlagGroupMarker identifies all three of cobra's flag-group validation
+// failures (MarkFlagsMutuallyExclusive, RequiredTogether, OneRequired).
+const cobraFlagGroupMarker = "flags in the group ["
+
+// cobraRequiredFlagMarker identifies MarkFlagRequired violations, e.g.
+// `required flag(s) "board" not set`. Cobra raises these from ValidateRequiredFlags
+// after parsing succeeds, so they bypass the FlagErrorFunc entirely. This is the
+// most common malformed call mcli sees — nearly every item and column command
+// requires --board — which makes it the worst one to report as INTERNAL.
+const cobraRequiredFlagMarker = "required flag(s) "
+
+// friendlyUnknownCommand reclassifies cobra's own validation failures as usage
+// errors so they exit 1 instead of a generic 5.
+//
+// This matters more than it looks: mcli is driven by LLM agents in steady state, and
+// INTERNAL reads as "mcli broke, try again" while USAGE reads as "your call was
+// wrong, fix it". Leaving a malformed invocation on exit 5 invites an agent to retry
+// a call that can never succeed. Flag *parse* errors are handled by the FlagErrorFunc
+// set in init; this covers the checks cobra runs after parsing, which do not route
+// through it.
+//
+// The "unknown command" branch also keeps cobra's "Did you mean …?" suggestion.
+// Unknown subcommands are handled in requireKnownSubcommands and already carry the
+// hint, so they do not reach here.
 func friendlyUnknownCommand(err error) error {
 	if err == nil {
 		return nil
 	}
-	if strings.HasPrefix(err.Error(), "unknown command ") {
-		return errs.Usage("%s\n%s", err.Error(), unknownCommandHint)
+	msg := err.Error()
+
+	if strings.HasPrefix(msg, "unknown command ") {
+		return errs.Usage("%s\n%s", msg, unknownCommandHint)
+	}
+	if strings.Contains(msg, cobraFlagGroupMarker) || strings.HasPrefix(msg, cobraRequiredFlagMarker) {
+		return errs.Usage("%s", msg)
+	}
+	for _, marker := range cobraArgErrorMarkers {
+		if strings.Contains(msg, marker) {
+			return errs.Usage("%s", msg)
+		}
 	}
 	return err
 }
diff --git a/internal/cli/root_test.go b/internal/cli/root_test.go
index 4ca1e0c..3980ff9 100644
--- a/internal/cli/root_test.go
+++ b/internal/cli/root_test.go
@@ -42,6 +42,83 @@ func TestFriendlyUnknownCommand_PassesThroughUnrelated(t *testing.T) {
 	}
 }
 
+// newCobraValidationTree builds a command whose args and flag groups are validated by
+// cobra itself, wired the way rootCmd is.
+func newCobraValidationTree(args cobra.PositionalArgs, requiredFlags ...string) *cobra.Command {
+	root := &cobra.Command{Use: "mcli", SilenceErrors: true, SilenceUsage: true}
+	root.SetFlagErrorFunc(usageFlagError)
+
+	leaf := &cobra.Command{
+		Use:  "leaf",
+		Args: args,
+		RunE: func(*cobra.Command, []string) error { return nil },
+	}
+	leaf.Flags().String("date", "", "")
+	leaf.Flags().String("due", "", "")
+	leaf.Flags().String("board", "", "")
+	leaf.MarkFlagsMutuallyExclusive("date", "due")
+	for _, name := range requiredFlags {
+		if err := leaf.MarkFlagRequired(name); err != nil {
+			panic(err)
+		}
+	}
+
+	root.AddCommand(leaf)
+	return root
+}
+
+// TestCobraValidationErrorsAreUsage drives real cobra rather than asserting on
+// hand-written strings: the classifier matches cobra's message text, so a cobra
+// upgrade that rewords one must fail here instead of silently regressing these
+// invocations to INTERNAL (exit 5), which tells an agent to retry a call that can
+// never succeed.
+func TestCobraValidationErrorsAreUsage(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		name     string
+		args     cobra.PositionalArgs
+		argv     []string
+		required []string
+	}{
+		{"exact args, too few", cobra.ExactArgs(1), []string{"leaf"}, nil},
+		{"exact args, too many", cobra.ExactArgs(1), []string{"leaf", "a", "b"}, nil},
+		{"at most", cobra.MaximumNArgs(1), []string{"leaf", "a", "b"}, nil},
+		{"at least", cobra.MinimumNArgs(2), []string{"leaf", "a"}, nil},
+		{"between", cobra.RangeArgs(2, 3), []string{"leaf", "a"}, nil},
+		{"mutually exclusive flags", cobra.NoArgs, []string{"leaf", "--date", "x", "--due", "y"}, nil},
+		{"unknown flag", cobra.NoArgs, []string{"leaf", "--bogus"}, nil},
+		{"flag missing its value", cobra.NoArgs, []string{"leaf", "--board"}, nil},
+		// Verified live: `mcli item update <id> --status Done` (no --board) reported
+		// INTERNAL/5 until cobraRequiredFlagMarker was added. Nearly every item and
+		// column command requires --board, so this is the most-hit malformed call.
+		{"required flag not set", cobra.NoArgs, []string{"leaf"}, []string{"board"}},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			root := newCobraValidationTree(tc.args, tc.required...)
+			root.SetOut(&bytes.Buffer{})
+			root.SetErr(&bytes.Buffer{})
+			root.SetArgs(tc.argv)
+
+			err := friendlyUnknownCommand(root.Execute())
+			if err == nil {
+				t.Fatal("expected an error")
+			}
+			e, ok := errors.AsType[*errs.Error](err)
+			if !ok {
+				t.Fatalf("expected *errs.Error, got %T (%v)", err, err)
+			}
+			if e.Code != errs.CodeUsage {
+				t.Errorf("expected USAGE (exit 1), got %s: %v", e.Code, err)
+			}
+		})
+	}
+}
+
 // newNamespaceTree builds a minimal root → namespace → leaf tree mirroring the
 // real command layout (a namespace with no action of its own) and applies
 // requireKnownSubcommands to it.
diff --git a/internal/cli/schema.go b/internal/cli/schema.go
new file mode 100644
index 0000000..096f0ff
--- /dev/null
+++ b/internal/cli/schema.go
@@ -0,0 +1,339 @@
+package cli
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"sort"
+	"time"
+
+	"github.com/spf13/cobra"
+
+	apischema "github.com/mondaycom/mcli/internal/api/schema"
+	"github.com/mondaycom/mcli/internal/config"
+	"github.com/mondaycom/mcli/internal/errs"
+	"github.com/mondaycom/mcli/internal/secrets"
+	rawschema "github.com/mondaycom/mcli/schema"
+)
+
+// staleAfterDays is how old the live schema may get before mcli warns. monday
+// ships API versions quarterly and adds fields within a version continuously, so
+// a month is a reasonable "you are probably missing operations" threshold.
+const staleAfterDays = 30
+
+// maxDeltaNames caps how many added/removed type names a refresh prints before
+// collapsing to a count, so the output stays readable when a version bump lands.
+const maxDeltaNames = 10
+
+func newSchemaCmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "schema",
+		Short: "Inspect and refresh the local monday.com GraphQL schema",
+		Long: `Inspect and refresh the monday.com GraphQL schema that drives 'mcli api'.
+
+mcli ships with an embedded schema. Refreshing fetches the live schema with your
+own API token and caches it locally, so you pick up new monday operations without
+waiting for an mcli release.`,
+	}
+	cmd.AddCommand(newSchemaRefreshCmd())
+	cmd.AddCommand(newSchemaStatusCmd())
+	return cmd
+}
+
+func newSchemaRefreshCmd() *cobra.Command {
+	var apiVersion string
+
+	cmd := &cobra.Command{
+		Use:   "refresh",
+		Short: "Fetch the live schema and cache it locally",
+		Long: `Fetch the monday.com GraphQL schema by introspection and cache it locally.
+
+Uses your configured API token and API version. The cached schema takes precedence
+over the embedded one for all 'mcli api' operations.`,
+		Args: cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return runSchemaRefresh(cmd, apiVersion)
+		},
+	}
+
+	cmd.Flags().StringVar(&apiVersion, "api-version", "",
+		"fetch this API version instead of the configured one (not persisted)")
+
+	return cmd
+}
+
+func newSchemaStatusCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "status",
+		Short: "Report which schema is in use and how old it is",
+		Args:  cobra.NoArgs,
+		RunE:  runSchemaStatus,
+	}
+}
+
+// schemaStatus is the JSON shape for 'mcli schema status'.
+type schemaStatus struct {
+	// Source is "cached" when a locally refreshed schema is in use, "embedded"
+	// when the copy compiled into the binary is.
+	Source     string `json:"source"`
+	Path       string `json:"path,omitempty"`
+	APIVersion string `json:"api_version"`
+	// FetchedAt is YYYY-MM-DD, or empty when the date cannot be determined.
+	FetchedAt string `json:"fetched_at,omitempty"`
+	// AgeDays is -1 when FetchedAt is unknown.
+	AgeDays int  `json:"age_days"`
+	Stale   bool `json:"stale"`
+	Types   int  `json:"types"`
+}
+
+// liveSchemaInfo reports which schema apischema.Load would use and how old it is.
+// A cached schema's age comes from its file mtime; the embedded schema's from the
+// date recorded at `make schema` time.
+func liveSchemaInfo(cfg config.Config) schemaStatus {
+	st := schemaStatus{
+		Source:     apischema.SourceEmbedded,
+		APIVersion: config.ResolveAPIVersion(cfg),
+		AgeDays:    -1,
+	}
+
+	if s, err := apischema.Load(); err == nil && s != nil {
+		st.Types = len(s.Types)
+	}
+	// Ask apischema which SDL it parsed rather than inferring it from the file's
+	// existence: an unparseable cache falls back to the embedded copy.
+	if src, err := apischema.LoadedSource(); err == nil {
+		st.Source = src
+	}
+
+	var fetched time.Time
+	if st.Source == apischema.SourceCached {
+		st.Path = apischema.CachedSchemaPath(resolveConfigDir())
+		if fi, err := os.Stat(st.Path); err == nil {
+			fetched = fi.ModTime()
+		}
+	} else {
+		fetched = rawschema.FetchedAt()
+	}
+
+	if !fetched.IsZero() {
+		st.FetchedAt = fetched.Format("2006-01-02")
+		st.AgeDays = int(time.Since(fetched).Hours() / 24)
+		st.Stale = st.AgeDays > staleAfterDays
+	}
+
+	return st
+}
+
+// warnIfSchemaStale emits a one-line staleness warning to stderr.
+//
+// It deliberately never fetches: mcli is driven by LLM agents in steady state, and
+// an implicit network call on a read path can hang, fail, or need a token that is
+// not there. It also never writes to stdout, which carries the JSON contract.
+func warnIfSchemaStale(cmd *cobra.Command) {
+	cfg, err := config.Load(resolveConfigPath())
+	if err != nil {
+		return
+	}
+	st := liveSchemaInfo(cfg)
+	if !st.Stale {
+		return
+	}
+	// A failed warning is not worth reporting: it must never affect the command's
+	// own exit status.
+	_, _ = fmt.Fprintf(cmd.ErrOrStderr(),
+		"warning: %s monday schema is %d days old; run 'mcli schema refresh' to update\n",
+		st.Source, st.AgeDays)
+}
+
+// resolveAPIToken resolves the API token with the standard precedence:
+// --token flag, then MONDAY_API_TOKEN, then the configured secret store.
+func resolveAPIToken(cfg config.Config) (config.APIToken, error) {
+	var store config.Store
+	if cfg.SecretStore != "" {
+		st, openErr := secrets.Open(cfg.SecretStore, resolveConfigDir())
+		if openErr != nil {
+			return "", openErr
+		}
+		store = st
+	}
+	return config.ResolveToken(cfg, globals.Token, store)
+}
+
+// fetchAndCacheSchema introspects the live schema for apiVersion, writes it to the
+// local cache and busts the in-memory cache so the new SDL takes effect
+// immediately. It is the single implementation shared by 'mcli schema refresh' and
+// 'mcli config set api-version'.
+func fetchAndCacheSchema(ctx context.Context, cfg config.Config, apiVersion string, token config.APIToken) (string, error) {
+	sdl, err := apischema.FetchSchema(ctx, token, config.ResolveEndpoint(cfg), apiVersion)
+	if err != nil {
+		return "", err
+	}
+
+	path := apischema.CachedSchemaPath(resolveConfigDir())
+	if err := os.WriteFile(path, []byte(sdl), 0o600); err != nil {
+		return "", errs.Internal("write schema cache: %v", err)
+	}
+
+	apischema.SetConfigDir(resolveConfigDir())
+	return path, nil
+}
+
+// schemaTypeNames returns the set of type names in the currently loaded schema.
+// It returns nil if the schema cannot be loaded, so a refresh still succeeds when
+// only the delta summary is unavailable.
+func schemaTypeNames() map[string]bool {
+	s, err := apischema.Load()
+	if err != nil || s == nil {
+		return nil
+	}
+	names := make(map[string]bool, len(s.Types))
+	for name := range s.Types {
+		names[name] = true
+	}
+	return names
+}
+
+// diffNames returns names present in b but not a, sorted.
+func diffNames(a, b map[string]bool) []string {
+	var out []string
+	for name := range b {
+		if !a[name] {
+			out = append(out, name)
+		}
+	}
+	sort.Strings(out)
+	return out
+}
+
+// schemaRefreshOutput is the JSON shape for 'mcli schema refresh'.
+type schemaRefreshOutput struct {
+	Path       string   `json:"path"`
+	APIVersion string   `json:"api_version"`
+	Types      int      `json:"types"`
+	Added      []string `json:"added"`
+	Removed    []string `json:"removed"`
+}
+
+func runSchemaRefresh(cmd *cobra.Command, apiVersionOverride string) error {
+	cfg, err := config.Load(resolveConfigPath())
+	if err != nil {
+		return errs.Internal("load config: %v", err)
+	}
+
+	apiVersion := config.ResolveAPIVersion(cfg)
+	if apiVersionOverride != "" {
+		if !apiVersionRE.MatchString(apiVersionOverride) {
+			return errs.Usage("invalid api-version %q: must be YYYY-MM (e.g. 2026-07) or a named version (e.g. dev)", apiVersionOverride)
+		}
+		apiVersion = apiVersionOverride
+	}
+
+	token, err := resolveAPIToken(cfg)
+	if err != nil {
+		return err
+	}
+
+	before := schemaTypeNames()
+
+	path, err := fetchAndCacheSchema(cmd.Context(), cfg, apiVersion, token)
+	if err != nil {
+		return err
+	}
+
+	after := schemaTypeNames()
+
+	out := schemaRefreshOutput{
+		Path:       path,
+		APIVersion: apiVersion,
+		Types:      len(after),
+		Added:      diffNames(before, after),
+		Removed:    diffNames(after, before),
+	}
+
+	mode, modeErr := resolveOutputMode(os.Stdout, globals, configOutputMode())
+	if modeErr != nil {
+		return modeErr
+	}
+
+	if mode == ModeJSON {
+		data, mErr := json.Marshal(out)
+		if mErr != nil {
+			return errs.Internal("marshal output: %v", mErr)
+		}
+		_, err = fmt.Fprintln(cmd.OutOrStdout(), string(data))
+		return err
+	}
+
+	o := cmd.OutOrStdout()
+	_, _ = fmt.Fprintf(o, "fetched schema for %s → %s\n", apiVersion, path)
+	_, _ = fmt.Fprintf(o, "types: %d\n", out.Types)
+	printDelta(o, "added", out.Added)
+	printDelta(o, "removed", out.Removed)
+	if len(out.Added) == 0 && len(out.Removed) == 0 && before != nil {
+		_, _ = fmt.Fprintln(o, "no type changes")
+	}
+	return nil
+}
+
+// printDelta writes a "label: a, b, c" line, collapsing to a count past
+// maxDeltaNames. It prints nothing for an empty delta.
+func printDelta(w interface{ Write([]byte) (int, error) }, label string, names []string) {
+	if len(names) == 0 {
+		return
+	}
+	if len(names) > maxDeltaNames {
+		_, _ = fmt.Fprintf(w, "%s: %d types\n", label, len(names))
+		return
+	}
+	for _, n := range names {
+		_, _ = fmt.Fprintf(w, "%s: %s\n", label, n)
+	}
+}
+
+func runSchemaStatus(cmd *cobra.Command, _ []string) error {
+	cfg, err := config.Load(resolveConfigPath())
+	if err != nil {
+		return errs.Internal("load config: %v", err)
+	}
+
+	st := liveSchemaInfo(cfg)
+
+	mode, modeErr := resolveOutputMode(os.Stdout, globals, configOutputMode())
+	if modeErr != nil {
+		return modeErr
+	}
+
+	switch mode {
+	case ModeJSON:
+		data, mErr := json.Marshal(st)
+		if mErr != nil {
+			return errs.Internal("marshal output: %v", mErr)
+		}
+		_, err = fmt.Fprintln(cmd.OutOrStdout(), string(data))
+		return err
+
+	case ModeTerse:
+		_, err = fmt.Fprintf(cmd.OutOrStdout(), "%s %s age=%dd types=%d stale=%t\n",
+			st.Source, st.APIVersion, st.AgeDays, st.Types, st.Stale)
+		return err
+
+	default:
+		o := cmd.OutOrStdout()
+		_, _ = fmt.Fprintf(o, "source:      %s\n", st.Source)
+		if st.Path != "" {
+			_, _ = fmt.Fprintf(o, "path:        %s\n", st.Path)
+		}
+		_, _ = fmt.Fprintf(o, "api-version: %s\n", st.APIVersion)
+		if st.FetchedAt != "" {
+			_, _ = fmt.Fprintf(o, "fetched:     %s (%d days ago)\n", st.FetchedAt, st.AgeDays)
+		} else {
+			_, _ = fmt.Fprintf(o, "fetched:     unknown\n")
+		}
+		_, _ = fmt.Fprintf(o, "types:       %d\n", st.Types)
+		if st.Stale {
+			_, _ = fmt.Fprintf(o, "\nschema is stale; run 'mcli schema refresh' to update\n")
+		}
+		return nil
+	}
+}
diff --git a/internal/cli/schema_test.go b/internal/cli/schema_test.go
new file mode 100644
index 0000000..4b44e63
--- /dev/null
+++ b/internal/cli/schema_test.go
@@ -0,0 +1,433 @@
+package cli
+
+import (
+	"bytes"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/spf13/cobra"
+
+	apischema "github.com/mondaycom/mcli/internal/api/schema"
+	"github.com/mondaycom/mcli/internal/errs"
+	rawschema "github.com/mondaycom/mcli/schema"
+)
+
+// runSchemaCmd executes a 'schema' subcommand against an isolated config dir.
+// Not safe for parallel tests: it mutates globals and the apischema cache.
+func runSchemaCmd(t *testing.T, dir string, args ...string) (string, string, error) {
+	t.Helper()
+
+	origGlobals := globals
+	t.Cleanup(func() { globals = origGlobals })
+	globals.Config = filepath.Join(dir, "config.yaml")
+	// Default to JSON so assertions don't depend on whether the test binary's
+	// stdout happens to be a TTY. A caller that pre-sets another mode keeps it.
+	if !globals.Pretty && !globals.Terse && !globals.CSV {
+		globals.JSON = true
+	}
+
+	apischema.SetConfigDir(dir)
+	t.Cleanup(func() { apischema.SetConfigDir("") })
+
+	root := &cobra.Command{Use: "mcli", SilenceErrors: true, SilenceUsage: true}
+	root.AddCommand(newSchemaCmd())
+
+	var out, errOut bytes.Buffer
+	root.SetOut(&out)
+	root.SetErr(&errOut)
+	root.SetArgs(args)
+	err := root.Execute()
+	return out.String(), errOut.String(), err
+}
+
+// introspectionServer serves a minimal but valid introspection response.
+func introspectionServer(t *testing.T) *httptest.Server {
+	t.Helper()
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = io.WriteString(w, minimalIntrospectionJSONForCLI())
+	}))
+	t.Cleanup(srv.Close)
+
+	origFetch := apischema.FetchHTTPClient
+	apischema.FetchHTTPClient = srv.Client()
+	t.Cleanup(func() { apischema.FetchHTTPClient = origFetch })
+
+	t.Setenv("MONDAY_API_URL", srv.URL)
+	return srv
+}
+
+func decodeStatus(t *testing.T, out string) schemaStatus {
+	t.Helper()
+	var st schemaStatus
+	if err := json.Unmarshal([]byte(out), &st); err != nil {
+		t.Fatalf("unmarshal status %q: %v", out, err)
+	}
+	return st
+}
+
+// TestSchemaStatus_embedded verifies status reports the embedded SDL when no
+// local cache exists, dated from the provenance file written by 'make schema'.
+func TestSchemaStatus_embedded(t *testing.T) {
+	dir := t.TempDir()
+
+	out, _, err := runSchemaCmd(t, dir, "schema", "status")
+	if err != nil {
+		t.Fatalf("schema status: %v", err)
+	}
+
+	st := decodeStatus(t, out)
+	if st.Source != apischema.SourceEmbedded {
+		t.Errorf("source = %q, want %q", st.Source, apischema.SourceEmbedded)
+	}
+	if st.Path != "" {
+		t.Errorf("path = %q, want empty for the embedded schema", st.Path)
+	}
+	if st.Types < 100 {
+		t.Errorf("types = %d, want the full embedded schema (>100)", st.Types)
+	}
+	if st.APIVersion == "" {
+		t.Error("api_version is empty")
+	}
+	if want := rawschema.FetchedAt().Format("2006-01-02"); st.FetchedAt != want {
+		t.Errorf("fetched_at = %q, want %q from schema/fetched_at.txt", st.FetchedAt, want)
+	}
+	// Don't hardcode staleness: it depends on today's date. Assert the invariant.
+	if st.Stale != (st.AgeDays > staleAfterDays) {
+		t.Errorf("stale = %t but age_days = %d (threshold %d)", st.Stale, st.AgeDays, staleAfterDays)
+	}
+}
+
+// TestSchemaStatus_cached verifies a parseable local cache is reported as the
+// live schema, aged by its file mtime.
+func TestSchemaStatus_cached(t *testing.T) {
+	dir := t.TempDir()
+	writeCachedSchema(t, dir, time.Now())
+
+	out, _, err := runSchemaCmd(t, dir, "schema", "status")
+	if err != nil {
+		t.Fatalf("schema status: %v", err)
+	}
+
+	st := decodeStatus(t, out)
+	if st.Source != apischema.SourceCached {
+		t.Errorf("source = %q, want %q", st.Source, apischema.SourceCached)
+	}
+	if st.Path != apischema.CachedSchemaPath(dir) {
+		t.Errorf("path = %q, want %q", st.Path, apischema.CachedSchemaPath(dir))
+	}
+	if st.AgeDays != 0 {
+		t.Errorf("age_days = %d, want 0 for a just-written cache", st.AgeDays)
+	}
+	if st.Stale {
+		t.Error("stale = true for a just-written cache")
+	}
+}
+
+// TestSchemaStatus_cachedStale verifies the staleness threshold is driven by the
+// cache file's mtime.
+func TestSchemaStatus_cachedStale(t *testing.T) {
+	dir := t.TempDir()
+	writeCachedSchema(t, dir, time.Now().AddDate(0, 0, -(staleAfterDays+5)))
+
+	out, _, err := runSchemaCmd(t, dir, "schema", "status")
+	if err != nil {
+		t.Fatalf("schema status: %v", err)
+	}
+
+	st := decodeStatus(t, out)
+	if !st.Stale {
+		t.Errorf("stale = false for a schema %d days old", st.AgeDays)
+	}
+	if st.AgeDays <= staleAfterDays {
+		t.Errorf("age_days = %d, want > %d", st.AgeDays, staleAfterDays)
+	}
+}
+
+// TestSchemaStatus_unparseableCacheReportsEmbedded guards the one case where the
+// cache file's existence lies: apischema silently falls back to the embedded SDL
+// when the cached file doesn't parse, and status must say so.
+func TestSchemaStatus_unparseableCacheReportsEmbedded(t *testing.T) {
+	dir := t.TempDir()
+	if err := os.WriteFile(apischema.CachedSchemaPath(dir), []byte("this is not graphql {{{"), 0o600); err != nil {
+		t.Fatalf("write cache: %v", err)
+	}
+
+	out, _, err := runSchemaCmd(t, dir, "schema", "status")
+	if err != nil {
+		t.Fatalf("schema status: %v", err)
+	}
+
+	st := decodeStatus(t, out)
+	if st.Source != apischema.SourceEmbedded {
+		t.Errorf("source = %q, want %q when the cache doesn't parse", st.Source, apischema.SourceEmbedded)
+	}
+	if st.Types < 100 {
+		t.Errorf("types = %d, want the embedded schema to be in use", st.Types)
+	}
+}
+
+// TestSchemaStatus_terse verifies the single-line form stays greppable.
+func TestSchemaStatus_terse(t *testing.T) {
+	dir := t.TempDir()
+	writeCachedSchema(t, dir, time.Now())
+
+	origGlobals := globals
+	t.Cleanup(func() { globals = origGlobals })
+	globals.Terse = true
+
+	out, _, err := runSchemaCmd(t, dir, "schema", "status")
+	if err != nil {
+		t.Fatalf("schema status: %v", err)
+	}
+
+	line := strings.TrimSpace(out)
+	if strings.Contains(line, "\n") {
+		t.Errorf("terse output is not a single line: %q", out)
+	}
+	for _, want := range []string{apischema.SourceCached, "age=0d", "stale=false", "types="} {
+		if !strings.Contains(line, want) {
+			t.Errorf("terse output %q is missing %q", line, want)
+		}
+	}
+}
+
+// TestSchemaRefresh_success verifies refresh writes the cache, reports the type
+// delta, and flips status over to the cached schema.
+func TestSchemaRefresh_success(t *testing.T) {
+	dir := t.TempDir()
+	introspectionServer(t)
+
+	origGlobals := globals
+	t.Cleanup(func() { globals = origGlobals })
+	globals.Token = "fake-token"
+
+	out, _, err := runSchemaCmd(t, dir, "schema", "refresh")
+	if err != nil {
+		t.Fatalf("schema refresh: %v", err)
+	}
+
+	var got schemaRefreshOutput
+	if err := json.Unmarshal([]byte(out), &got); err != nil {
+		t.Fatalf("unmarshal refresh output %q: %v", out, err)
+	}
+	if got.Path != apischema.CachedSchemaPath(dir) {
+		t.Errorf("path = %q, want %q", got.Path, apischema.CachedSchemaPath(dir))
+	}
+	if got.APIVersion == "" {
+		t.Error("api_version is empty")
+	}
+	if got.Types == 0 {
+		t.Error("types = 0, want the refreshed schema's type count")
+	}
+	// The fixture schema is far smaller than the embedded one, so the delta must
+	// show the embedded types dropping out.
+	if len(got.Removed) == 0 {
+		t.Error("removed is empty, want the embedded types absent from the fixture")
+	}
+
+	data, readErr := os.ReadFile(apischema.CachedSchemaPath(dir))
+	if readErr != nil {
+		t.Fatalf("cache not written: %v", readErr)
+	}
+	if !strings.Contains(string(data), "type Query") {
+		t.Errorf("cache missing 'type Query': %s", data)
+	}
+
+	statusOut, _, statusErr := runSchemaCmd(t, dir, "schema", "status")
+	if statusErr != nil {
+		t.Fatalf("schema status: %v", statusErr)
+	}
+	if st := decodeStatus(t, statusOut); st.Source != apischema.SourceCached {
+		t.Errorf("after refresh source = %q, want %q", st.Source, apischema.SourceCached)
+	}
+}
+
+// TestSchemaRefresh_apiVersionOverrideNotPersisted verifies --api-version affects
+// the fetch without writing to config.yaml.
+func TestSchemaRefresh_apiVersionOverrideNotPersisted(t *testing.T) {
+	dir := t.TempDir()
+
+	var gotVersion string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotVersion = r.Header.Get("API-Version")
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = io.WriteString(w, minimalIntrospectionJSONForCLI())
+	}))
+	defer srv.Close()
+
+	origFetch := apischema.FetchHTTPClient
+	apischema.FetchHTTPClient = srv.Client()
+	t.Cleanup(func() { apischema.FetchHTTPClient = origFetch })
+	t.Setenv("MONDAY_API_URL", srv.URL)
+
+	origGlobals := globals
+	t.Cleanup(func() { globals = origGlobals })
+	globals.Token = "fake-token"
+
+	out, _, err := runSchemaCmd(t, dir, "schema", "refresh", "--api-version", "2026-08")
+	if err != nil {
+		t.Fatalf("schema refresh: %v", err)
+	}
+
+	if gotVersion != "2026-08" {
+		t.Errorf("API-Version header = %q, want 2026-08", gotVersion)
+	}
+	var got schemaRefreshOutput
+	if err := json.Unmarshal([]byte(out), &got); err != nil {
+		t.Fatalf("unmarshal refresh output: %v", err)
+	}
+	if got.APIVersion != "2026-08" {
+		t.Errorf("api_version = %q, want 2026-08", got.APIVersion)
+	}
+	if _, statErr := os.Stat(filepath.Join(dir, "config.yaml")); statErr == nil {
+		t.Error("refresh wrote config.yaml; --api-version must not be persisted")
+	}
+}
+
+// TestSchemaRefresh_invalidAPIVersion verifies the override is validated before
+// any network call, so a typo is a usage error rather than an API error.
+func TestSchemaRefresh_invalidAPIVersion(t *testing.T) {
+	dir := t.TempDir()
+
+	_, _, err := runSchemaCmd(t, dir, "schema", "refresh", "--api-version", "2026-7")
+	if err == nil {
+		t.Fatal("expected an error for a malformed api-version")
+	}
+	e, ok := err.(*errs.Error)
+	if !ok || e.Code != errs.CodeUsage {
+		t.Errorf("error = %T %v, want errs.CodeUsage", err, err)
+	}
+}
+
+// TestSchemaRefresh_noToken verifies refresh fails with an auth error rather than
+// silently leaving the schema alone.
+func TestSchemaRefresh_noToken(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("MONDAY_API_TOKEN", "")
+
+	origGlobals := globals
+	t.Cleanup(func() { globals = origGlobals })
+	globals.Token = ""
+
+	_, _, err := runSchemaCmd(t, dir, "schema", "refresh")
+	if err == nil {
+		t.Fatal("expected an error when no token is available")
+	}
+	e, ok := err.(*errs.Error)
+	if !ok || e.Code != errs.CodeAuth {
+		t.Errorf("error = %T %v, want errs.CodeAuth", err, err)
+	}
+	if _, statErr := os.Stat(apischema.CachedSchemaPath(dir)); statErr == nil {
+		t.Error("cache was written despite the missing token")
+	}
+}
+
+// TestSchemaRefresh_fetchError verifies an API failure leaves the existing cache
+// untouched.
+func TestSchemaRefresh_fetchError(t *testing.T) {
+	dir := t.TempDir()
+	writeCachedSchema(t, dir, time.Now())
+	before, err := os.ReadFile(apischema.CachedSchemaPath(dir))
+	if err != nil {
+		t.Fatalf("read cache: %v", err)
+	}
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusForbidden)
+	}))
+	defer srv.Close()
+
+	origFetch := apischema.FetchHTTPClient
+	apischema.FetchHTTPClient = srv.Client()
+	t.Cleanup(func() { apischema.FetchHTTPClient = origFetch })
+	t.Setenv("MONDAY_API_URL", srv.URL)
+
+	origGlobals := globals
+	t.Cleanup(func() { globals = origGlobals })
+	globals.Token = "fake-token"
+
+	if _, _, refreshErr := runSchemaCmd(t, dir, "schema", "refresh"); refreshErr == nil {
+		t.Fatal("expected an error when introspection returns 403")
+	}
+
+	after, err := os.ReadFile(apischema.CachedSchemaPath(dir))
+	if err != nil {
+		t.Fatalf("cache disappeared after a failed refresh: %v", err)
+	}
+	if !bytes.Equal(before, after) {
+		t.Error("a failed refresh modified the existing cache")
+	}
+}
+
+// TestWarnIfSchemaStale_stderrOnly verifies the staleness warning never touches
+// stdout, which carries the JSON contract that LLM callers parse.
+func TestWarnIfSchemaStale_stderrOnly(t *testing.T) {
+	dir := t.TempDir()
+	writeCachedSchema(t, dir, time.Now().AddDate(0, 0, -(staleAfterDays+5)))
+
+	origGlobals := globals
+	t.Cleanup(func() { globals = origGlobals })
+	globals.Config = filepath.Join(dir, "config.yaml")
+
+	apischema.SetConfigDir(dir)
+	t.Cleanup(func() { apischema.SetConfigDir("") })
+
+	cmd := &cobra.Command{Use: "api"}
+	var out, errOut bytes.Buffer
+	cmd.SetOut(&out)
+	cmd.SetErr(&errOut)
+
+	warnIfSchemaStale(cmd)
+
+	if out.Len() != 0 {
+		t.Errorf("warning leaked to stdout: %q", out.String())
+	}
+	if !strings.Contains(errOut.String(), "mcli schema refresh") {
+		t.Errorf("stderr = %q, want the refresh hint", errOut.String())
+	}
+}
+
+// TestWarnIfSchemaStale_silentWhenFresh verifies a fresh schema produces no noise.
+func TestWarnIfSchemaStale_silentWhenFresh(t *testing.T) {
+	dir := t.TempDir()
+	writeCachedSchema(t, dir, time.Now())
+
+	origGlobals := globals
+	t.Cleanup(func() { globals = origGlobals })
+	globals.Config = filepath.Join(dir, "config.yaml")
+
+	apischema.SetConfigDir(dir)
+	t.Cleanup(func() { apischema.SetConfigDir("") })
+
+	cmd := &cobra.Command{Use: "api"}
+	var out, errOut bytes.Buffer
+	cmd.SetOut(&out)
+	cmd.SetErr(&errOut)
+
+	warnIfSchemaStale(cmd)
+
+	if out.Len() != 0 || errOut.Len() != 0 {
+		t.Errorf("expected no output for a fresh schema, got stdout=%q stderr=%q", out.String(), errOut.String())
+	}
+}
+
+// writeCachedSchema writes a parseable schema.graphql into dir and backdates its
+// mtime, which is what liveSchemaInfo uses to age a cached schema.
+func writeCachedSchema(t *testing.T, dir string, modTime time.Time) {
+	t.Helper()
+	path := apischema.CachedSchemaPath(dir)
+	if err := os.WriteFile(path, []byte("type Query { hello: String }\n"), 0o600); err != nil {
+		t.Fatalf("write cached schema: %v", err)
+	}
+	if err := os.Chtimes(path, modTime, modTime); err != nil {
+		t.Fatalf("set cache mtime: %v", err)
+	}
+}
diff --git a/internal/cli/skill.go b/internal/cli/skill.go
index 73296fa..77086b9 100644
--- a/internal/cli/skill.go
+++ b/internal/cli/skill.go
@@ -1,11 +1,20 @@
 package cli
 
 import (
+	_ "embed"
 	"fmt"
 
 	"github.com/spf13/cobra"
 )
 
+// skillDoc is the agent-facing description of mcli. It lives in skill.md rather
+// than in a Go string literal: markdown is full of backticks, and a Go raw string
+// cannot contain one, so the previous `+ "`" + ` form made the doc effectively
+// unreviewable and let it drift from the real flag set.
+//
+//go:embed skill.md
+var skillDoc string
+
 func newSkillCmd() *cobra.Command {
 	return &cobra.Command{
 		Use:     "skill",
@@ -22,202 +31,3 @@ func runSkill(cmd *cobra.Command) error {
 	_, err := fmt.Fprint(cmd.OutOrStdout(), skillDoc)
 	return err
 }
-
-const skillDoc = `# mcli — monday.com CLI
-
-CLI for monday.com's GraphQL API. Designed for LLM agents.
-
-- JSON to stdout by default. Errors to stderr as ` + "`" + `{"error":{"code":"...","message":"..."}}` + "`" + `
-- Discover flags for any command: ` + "`mcli <command> --help`" + `
-- Auth: ` + "`--token <t>`" + ` flag > ` + "`MONDAY_API_TOKEN`" + ` env > stored credential (` + "`mcli auth login`" + `)
-
-## Monday Hierarchy
-
-` + "```" + `
-Workspace → Folder → Board → { Group, Column } → Item → Subitem
-` + "```" + `
-
-## Goals & Commands
-
-### Set up a board
-
-1. Create a board: ` + "`mcli board create --name ... --kind public`" + `
-2. Add groups to organize items: ` + "`mcli board group create --board <id> --name ...`" + `
-3. Add columns to define data shape: ` + "`mcli board column create --board <id> --title ... --type status`" + `
-4. Set column description (helps you understand it later): ` + "`mcli board column describe --board <id> --column <id> --text ...`" + `
-
-### Discover board structure
-
-- ` + "`mcli board get <id>`" + ` — full detail (groups + columns + settings); add ` + "`--items`" + ` to also get the first page of items with column values (` + "`--items-limit N`" + `, ` + "`--items-cursor`" + `)
-- ` + "`mcli board group list --board <id>`" + ` — just groups
-- ` + "`mcli board column list --board <id>`" + ` — just columns (includes settings_str with labels/options)
-
-### Search
-
-` + "`mcli search <query> [-t boards|items|docs] [--limit N]`" + `
-
-Search all entity types at once or restrict with ` + "`-t`" + `. Returns a JSON object with
-` + "`boards`" + `, ` + "`items`" + `, and ` + "`docs`" + ` arrays (empty arrays for types not searched).
-
-### CRUD items
-
-- Create: ` + "`mcli item create --board <id> --name ... [--group <id>] [--col <col_id>=<json>]...`" + `
-- Read list: ` + "`mcli item list --board <id> [--group <id>] [--limit N] [--cursor ...] [--subitems]`" + ` — ` + "`--subitems`" + ` adds each item's subitems with column values (JSON output)
-- Read one: ` + "`mcli item get <id> [--subitems]`" + ` — includes decoded column values, subitems, creator; ` + "`--subitems`" + ` adds each subitem's column values (` + "`--subitem-count N`" + ` caps them)
-- Find by column value: ` + "`mcli item find --board <id> --column <col_id> --value <text>`" + `
-- Update: ` + "`mcli item update <id> --board <id> [--name ...] [--col <col_id>=<json>]...`" + `
-- Move: ` + "`mcli item move <id> --to-group <id>`" + ` or ` + "`--to-board <id> --group <id>`" + `
-- Archive: ` + "`mcli item archive <id>`" + ` (recoverable)
-- Delete: ` + "`mcli item delete <id>`" + ` (permanent)
-- Post update/comment: ` + "`mcli item post-update <id> --body <text>`" + `
-- Read updates/comments: ` + "`mcli item get-updates <id> [--limit N]`" + `
-- Read description: ` + "`mcli item description <id>`" + ` — returns markdown
-- Write description: ` + "`mcli item description <id> --set <md>`" + ` or ` + "`--set-file <path>`" + `
-
-### Subitems
-
-` + "`mcli item create --parent <item_id> --name ...`" + ` — creates under a parent item.
-
-### Workspace & folder management
-
-- ` + "`mcli workspace list/get/create/update/delete`" + `
-- ` + "`mcli folder list/create/rename/delete`" + `
-
-### Board lifecycle
-
-- ` + "`mcli board list`" + `, ` + "`mcli board rename <id> <name>`" + `, ` + "`mcli board archive <id>`" + `, ` + "`mcli board delete <id>`" + `
-- Groups: ` + "`mcli board group list/create/rename/archive/delete`" + `
-- Columns: ` + "`mcli board column list/create/rename/describe/delete`" + `
-
-### Semantic Layer (recommended workflow)
-
-Saved queries and mutations let you define a **business-level API** over monday.com
-boards. Once set up, all operations use domain names like ` + "`create_order`" + ` or
-` + "`list_products`" + ` instead of raw board IDs, column IDs, and GraphQL. This keeps
-conversations in business terms: "add 3 widgets to the order" rather than
-"create a subitem on board 1234 with col_xyz set to 3".
-
-**Setup pattern (one-time, per project):**
-
-1. Create boards and columns with ` + "`mcli board create`" + ` / ` + "`mcli board column create`" + `
-2. Save domain-named queries and mutations that encode the GraphQL + board structure
-3. Use only ` + "`mcli query run <name>`" + ` / ` + "`mcli mutation run <name>`" + ` for day-to-day operations
-
-**Check if a semantic layer exists:** ` + "`mcli query list`" + ` and ` + "`mcli mutation list`" + `.
-If saved operations exist, prefer them over raw commands.
-
-**Example — e-commerce semantic layer:**
-
-` + "```sh" + `
-# Define once:
-mcli mutation save create_order --query 'mutation($board: ID!, $name: String!, $cols: JSON!) { create_item(board_id: $board, item_name: $name, column_values: $cols) { id } }'
-mcli mutation save add_order_line --query 'mutation($parent: ID!, $name: String!, $cols: JSON!) { create_subitem(parent_item_id: $parent, item_name: $name, column_values: $cols) { id } }'
-mcli mutation save update_order_status --query 'mutation($board: ID!, $item: ID!, $cols: JSON!) { change_multiple_column_values(board_id: $board, item_id: $item, column_values: $cols) { id } }'
-mcli query save list_products --query 'query($boardId: ID!) { boards(ids: [$boardId]) { items_page(limit:100) { items { id name column_values { id text value } } } } }'
-
-# Use forever after — business language, no GraphQL knowledge needed:
-mcli mutation run create_order --var board=123 --var name="ORD-42" --var cols='{"customer":"Acme","status":{"label":"Draft"}}'
-mcli mutation run add_order_line --var parent=456 --var name="Widget x2" --var cols='{}'
-mcli mutation run update_order_status --var board=123 --var item=456 --var cols='{"status":{"label":"Ordered"}}'
-mcli query run list_products --var boardId=789
-` + "```" + `
-
-**JSON variable coercion:** Variables declared as ` + "`JSON`" + ` in the query are automatically
-stringified on the wire. Write natural JSON in ` + "`--var cols='{...}'`" + ` — no double-encoding.
-
-Saved operations live in ` + "`.mcli/queries/`" + ` and ` + "`.mcli/mutations/`" + ` (local, version-controllable)
-or ` + "`~/.config/mcli/queries/`" + ` / ` + "`~/.config/mcli/mutations/`" + ` (` + "`--global`" + `).
-
-Management: ` + "`mcli query list`" + ` · ` + "`mcli query delete <name>`" + ` · ` + "`mcli mutation list`" + ` · ` + "`mcli mutation delete <name>`" + `
-
-### Generic API (any operation)
-
-For operations not covered by built-in commands:
-` + "`mcli api list`" + ` · ` + "`mcli api describe <op>`" + ` · ` + "`mcli api <op> --arg key=value...`" + `
-
-JSON args are auto-coerced — pass natural JSON (no double-encoding).
-Override selection: ` + "`--select \"id,name,column_values{id,text}\"`" + `. Preview: ` + "`--dry-run`" + `.
-
-### Raw GraphQL (escape hatch)
-
-For anything not covered by structured commands or the semantic layer.
-See https://developer.monday.com/api-reference/reference/about-the-api-reference for the full API.
-
-- Inline: ` + "`mcli query '<graphql>' [--var key=value]...`" + `
-- From file: ` + "`mcli query -f <file> [--var key=value]... [--vars-file vars.json]`" + `
-- From stdin: ` + "`echo '...' | mcli query -f -`" + `
-
-Variables are auto-typed: 42→int, true→bool, ` + "`{...}`" + `→JSON, else string.
-Variables declared as ` + "`JSON`" + ` in the query are auto-stringified (no double-encoding needed).
-
-` + "```sh" + `
-mcli query save my-report --query 'query($boardId: ID!) { boards(ids: [$boardId]) { items_page(limit:100) { items { name column_values { id text } } } } }'
-mcli query run my-report --var boardId=9832181507
-` + "```" + `
-
-Inline mutations: ` + "`mcli mutation '<graphql>' [--var key=value]...`" + `
-
-Output is raw passthrough: ` + "`" + `{"data":...,"errors":...,"extensions":...}` + "`" + `. Exit 0 if no errors, exit 2 if errors present.
-
-### Documents
-
-- Read: ` + "`mcli doc read <doc_id>`" + ` — export full document as markdown
-- Write: ` + "`mcli doc write <doc_id> --content <md>`" + ` or ` + "`--file <path>`" + ` — replace all content
-
-### Current User
-
-` + "`mcli me`" + ` — print id, name, email, account, and team memberships.
-
-### Daemon + Notifications (webhook inbox)
-
-1. Start daemon: ` + "`mcli daemon start`" + ` (requires ` + "`cloudflared`" + ` in PATH, or pass ` + "`--url`" + `)
-2. Register webhook: ` + "`mcli webhook create --board <id> --event create_item`" + `
-3. Poll for events: ` + "`mcli notification count`" + ` (quick) or ` + "`mcli notification list --unread`" + `
-4. Acknowledge: ` + "`mcli notification ack <id>`" + ` or ` + "`mcli notification ack --all`" + `
-
-Available events: ` + "`mcli webhook events`" + `
-
-## Output Modes
-
-Control output format with a global flag or ` + "`mcli config set output-mode <mode>`" + `:
-
-| Flag | Config value | Description |
-|------|-------------|-------------|
-| ` + "`--json`" + ` | ` + "`json`" + ` | Machine-readable JSON (default when stdout is not a TTY) |
-| ` + "`--pretty`" + ` | ` + "`pretty`" + ` | Human-readable table/label output (default when stdout is a TTY) |
-| ` + "`--terse`" + ` | ` + "`terse`" + ` | Compact one-line-per-result output for scripting |
-| ` + "`--csv`" + ` | ` + "`csv`" + ` | Comma-separated values with header row |
-
-Precedence: explicit flag > config file > TTY detection.
-
-## Output Shapes
-
-| Pattern | Shape |
-|---------|-------|
-| List | ` + "`" + `{"items":[...],"cursor":""}` + "`" + ` — empty cursor = last page |
-| Get | Single object |
-| Write | The affected object |
-| Delete/Archive | ` + "`" + `{"id":"...","name":"...","state":"..."}` + "`" + ` |
-
-## Column Values
-
-On read: decoded to human-readable (status→label, date→ISO string, etc.).
-On write: pass monday's raw JSON via ` + "`--col <column_id>=<json>`" + `. Common shapes:
-
-| Type | Write JSON |
-|------|-----------|
-| status | ` + "`" + `{"label":"Done"}` + "`" + ` |
-| date | ` + "`" + `{"date":"2026-05-10"}` + "`" + ` |
-| text | ` + "`" + `"hello"` + "`" + ` |
-| numeric | ` + "`" + `"42"` + "`" + ` |
-| people | ` + "`" + `{"personsAndTeams":[{"id":123,"kind":"person"}]}` + "`" + ` |
-| dropdown | ` + "`" + `{"ids":[1,2]}` + "`" + ` |
-| checkbox | ` + "`" + `{"checked":"true"}` + "`" + ` |
-| link | ` + "`" + `{"url":"https://...","text":"label"}` + "`" + ` |
-
-Use ` + "`mcli board column list --board <id>`" + ` to discover column IDs, types, and settings.
-
-## Error Codes
-
-` + "`USAGE`" + ` (exit 5) · ` + "`AUTH`" + ` (exit 1) · ` + "`API`" + ` (exit 1) · ` + "`RATE_LIMITED`" + ` (auto-retried, exit 1 if exhausted)
-`
diff --git a/internal/cli/skill.md b/internal/cli/skill.md
new file mode 100644
index 0000000..90a0543
--- /dev/null
+++ b/internal/cli/skill.md
@@ -0,0 +1,233 @@
+# mcli — monday.com CLI
+
+CLI for monday.com's GraphQL API, built for LLM agents: non-interactive, one JSON
+object per call, stable error codes.
+
+- **Output:** a single JSON object on stdout (never a stream). Errors go to stderr as `{"error":{"code":"...","message":"..."}}` and the exit code follows the code — see Errors.
+- **It never guesses.** When a command cannot tell what you meant it fails with `USAGE` and names the candidates. Read the message; do not retry the same call.
+- **Discovery:** `mcli <command> --help` for real flags · `mcli api list` for every API operation.
+- **Auth:** `--token <t>` > `MONDAY_API_TOKEN` > stored credential (`mcli auth login --token <t>`). Verify with `mcli auth status`.
+- **Global flags:** `--json` / `--pretty` / `--terse` / `--csv` · `--no-input` (never prompt, fail instead) · `-v` (request metadata to stderr).
+
+## Monday Hierarchy
+
+```
+Workspace → Folder → Board → { Group, Column } → Item → Subitem
+                   → Doc
+```
+
+An item lives in one group on one board. A *column* defines a field; a *column value*
+holds that item's data for it. Subitems live on a separate board that monday creates
+on first use.
+
+## Start Here: Discover IDs
+
+Board, group, and column IDs are opaque and not guessable, and every write needs them.
+
+- Find by name: `mcli search <query> [-t boards|items|docs] [--limit N]` (max 20 per type)
+- `mcli board list [--workspace <id>] [--limit N] [--cursor <c>]`
+- **Board shape — the one to reach for:** `mcli board get <id>` returns groups + columns + settings. Add `--items` for the first page of items with values (`--items-limit N` max 500, `--items-cursor <c>`).
+- Columns only: `mcli board column list --board <id>` → id, title, type, description, and `settings_str` (status labels live here)
+- Groups only: `mcli board group list --board <id>`
+
+## Read Items
+
+- Page a board: `mcli item list --board <id> [--group <id>] [--limit N] [--cursor <c>] [--subitems]`
+- One item: `mcli item get <id> [--subitems] [--subitem-count N]`
+- By column value: `mcli item find --board <id> --column <col_id> --value <text>` — status columns match on **label text**
+- Comments: `mcli item get-updates <id> [--limit N]`
+- Long description: `mcli item description <id>` → markdown
+
+Reads are decoded for you: status → its label, date → an ISO string, numbers → a
+number. You never parse monday's raw column JSON when reading.
+
+## Write Items
+
+```sh
+mcli item create --board <id> [--group <id>] --name "..." [shorthands] [--col <id>=<json>]...
+mcli item update <id> --board <id> [--name "..."]  [shorthands] [--col <id>=<json>]...
+```
+
+**Typed shorthands** spare you a column lookup. Each addresses the board's *single*
+column of that type and is validated before anything is sent:
+
+`--status Done` · `--date 2026-05-10` (or `2026-05-10T14:30`) · `--due` (alias of `--date`) · `--number 42` · `--text "..."` · `--checkbox true`
+
+If the board has **0 or 2+** columns of that type, the command fails with `USAGE` and
+names the candidates rather than choosing one. Use `--col <column_id>=<json>` there,
+and for every type without a shorthand (people, link, dropdown, long_text, timeline…).
+
+`--dry-run` prints the exact `column_values` that would be sent, and writes nothing.
+
+### Many items at once
+
+Pass `-` in place of `--name` / `<id>` to read rows from stdin — a JSON array or one
+object per line, max 500 rows. This is one command against monday's rate limit
+instead of N:
+
+```sh
+echo '[{"name":"Ship v1","status":"Done","due":"2026-05-10"},{"name":"Docs","number":3}]' \
+  | mcli item create --board 123 -
+echo '{"id":"456","status":"Done"}' | mcli item update --board 123 -
+```
+
+Create rows need `name`; update rows need `id`. Both also accept `group`, `cols`
+(raw, as `{"<column_id>": <json>}`), and the shorthand keys `status`, `date`/`due`,
+`number`, `text`, `checkbox`.
+
+- **Every row is validated before the first request.** One bad status label fails the whole batch with `USAGE` and writes nothing.
+- Output: `{"written":N,"failed":N,"verb":"created","items":[...],"errors":[{"index":i,"code":"...","message":"..."}]}`
+- Exit 2 on partial failure. **Retry only the rows named in `errors[].index`** — item creation has no dedupe key, so re-sending the batch duplicates the rows that already succeeded.
+
+### Move, lifecycle, notes
+
+- `mcli item move <id> --to-group <id>` (same board) or `--to-board <id> --group <id>`
+- `mcli item archive <id>` (recoverable) · `mcli item delete <id>` (**permanent**)
+- Comment: `mcli item post-update <id> --body <text|-> [--parent <update_id>]`
+- Description: `mcli item description <id> --set <md>` or `--set-file <path>`
+- Subitem: `mcli item create --parent <item_id> --name "..."` — the response carries `board.id`, the board monday put subitems on. Pass that ID to `board column create` and to later `item update --board`.
+
+## Column Values (write shapes)
+
+Prefer a shorthand. Where none exists, `--col <column_id>=<json>` takes monday's raw
+shape:
+
+| Type | Write JSON |
+|---|---|
+| status | `{"label":"Done"}` |
+| date | `{"date":"2026-05-10"}` |
+| text, long_text | `"hello"` or `{"text":"hello"}` |
+| numbers | `"42"` — quoted |
+| checkbox | `{"checked":"true"}` |
+| people | `{"personsAndTeams":[{"id":123,"kind":"person"}]}` |
+| dropdown | `{"ids":[1,2]}` |
+| link | `{"url":"https://...","text":"label"}` |
+| timeline | `{"from":"2026-01-01","to":"2026-03-01"}` |
+
+`""` clears a column. `null` is rejected — use `""`. Computed types (mirror, formula,
+progress, dependency, auto_number) cannot be written directly.
+
+## Errors: What To Do Next
+
+stderr carries `{"error":{"code":"...","message":"..."}}` and the exit code follows:
+
+| Code / exit | Meaning, and the next move |
+|---|---|
+| `USAGE` 1 | Your call is malformed — bad flag, ambiguous shorthand, invalid label. **Fix the call; never retry it unchanged.** |
+| `API` 2 | monday rejected the request. Read the message: usually a permission problem or an invalid column value. |
+| `NOT_FOUND` 2 | The ID does not exist, or this token cannot see it. Re-discover it; this is not transient. |
+| `AUTH` 3 | Token missing, invalid, or expired. Not retryable — check `mcli auth status`. |
+| `RATE_LIMITED` 4 | mcli already retried with backoff (up to 3×, honouring `Retry-After` / `reset_in`) and still failed. The complexity budget is **per minute**, so parallelism does not help: wait, then batch instead of looping per item. |
+| `INTERNAL` 5 | Unexpected, and the fallback for any unclassified error. Retrying will not help; report it. |
+| `DAEMON_REQUIRED` 6 | Start the daemon first (see Webhook Inbox). |
+| `INTERRUPTED` 130 | Cancelled by SIGINT/SIGTERM. |
+
+## Failures Worth Knowing About In Advance
+
+These fail in ways the error message alone will not explain:
+
+- **`board create` without `--workspace`** goes to the account's default workspace and often returns `API: User unauthorized to perform action`, which says nothing about workspaces. Pass `--workspace <id>` from `mcli workspace list`.
+- **A `status` column created without `--defaults`** gets monday's stock labels, so a later `--status "<your label>"` fails validation. Define labels at creation time.
+- **`item update` needs `--board`** even though the item ID is already unique.
+- **A board created through the API has only a Name column** — no default status, date, or person columns. There is nothing to inherit; create what you need.
+- **Shorthands describe a board's shape, not a convention.** On a board you did not create, a shorthand may be ambiguous (two `date` columns) or missing. Check `board column list` first, or address columns by ID.
+- **A subitem's columns are not the parent board's columns.** Updating a subitem takes the *subitems* board ID.
+- **`--col` takes JSON, not text:** `--col status='{"label":"Done"}'`, not `--col status=Done`.
+
+## Output Modes & Shapes
+
+`--json` (default when stdout is not a TTY) · `--pretty` (default on a TTY) · `--terse`
+· `--csv`. Precedence: explicit flag > `mcli config set output-mode <mode>` > TTY
+detection. **Pass `--json` explicitly** rather than relying on TTY detection.
+
+| Pattern | Shape |
+|---|---|
+| List | `{"items":[...],"cursor":"..."}` — empty cursor means last page |
+| Get | a single object |
+| Write | the affected object |
+| Delete / archive | `{"id":"...","name":"..."}`, plus `"state"` for items |
+| Batch write | `{"written":N,"failed":N,"verb":"...","items":[...],"errors":[...]}` |
+| Raw GraphQL | passthrough `{"data":...,"errors":...,"extensions":...}` |
+
+## Build A Board (one-time setup)
+
+1. `mcli board create --name "..." --kind public|private|share --workspace <id> [--empty] [--description "..."]` — `--empty` omits monday's sample *items*; either way an API-created board starts with just a Name column.
+2. `mcli board group create --board <id> --name "..." [--color <hex>]`
+3. `mcli board column create --board <id> --title "..." --type <type> [--defaults <json>] [--description "..."]`
+
+Set `--description` when creating the column rather than making a second
+`board column describe` call — a described column tells the next reader, human or
+agent, what it means, and `board column list` / `board get` return it. Status
+columns need their labels up front:
+
+```sh
+mcli board column create --board <id> --title "Stage" --type status \
+  --defaults '{"labels":{"0":"Todo","1":"Doing","2":"Done"}}' \
+  --description "Delivery stage; Done means shipped to production"
+```
+
+Common writable `--type` values: `text`, `long_text`, `numbers`, `status`, `dropdown`,
+`date`, `timeline`, `people`, `checkbox`, `link`, `email`, `phone`, `location`,
+`rating`, `hour`, `country`, `file`, `doc`, `board_relation`.
+
+## Boards, Workspaces, Folders, Docs
+
+- Boards: `mcli board list/get/create/rename/archive/delete`
+- Groups: `mcli board group list/create/rename/archive/delete --board <id>`
+- Columns: `mcli board column list/create/rename/describe/delete --board <id>`
+- Workspaces: `mcli workspace list/get/create/update/delete` — `create` needs `--kind open|closed`
+- Folders: `mcli folder list/create/rename/delete` — `--workspace <id>`, `--parent <id>`
+- Docs: `mcli doc create --workspace <id> --name "..."` · `mcli doc read <id>` → markdown · `mcli doc write <id> --content <md>` or `--file <path|->` (replaces all content)
+- `mcli me` — current user id, name, email, account, teams
+- `mcli config get|set <key> [<value>]` · `mcli version`
+
+## Semantic Layer (optional; worth it for repeated work)
+
+Saved queries and mutations attach business names to operations, so later calls carry
+no board or column IDs. **Check whether one already exists before doing anything by
+hand:** `mcli query list` and `mcli mutation list` — if saved operations exist, prefer
+them over raw commands.
+
+```sh
+mcli mutation save create_order --query 'mutation($board: ID!, $name: String!, $cols: JSON!) { create_item(board_id: $board, item_name: $name, column_values: $cols) { id } }'
+mcli mutation run  create_order --var board=123 --var name="ORD-42" --var cols='{"status":{"label":"Draft"}}'
+```
+
+Variables declared `JSON` in the query are stringified on the wire, so write natural
+JSON in `--var` with no double-encoding. Other `--var` values are auto-typed:
+`42`→int, `true`→bool, `{...}`→JSON, otherwise string. `--vars-file <json>` supplies a
+whole variables object.
+
+Definitions live in `.mcli/queries/` and `.mcli/mutations/` (project-local and
+version-controllable) or `~/.config/mcli/` with `--global`. Manage them with
+`mcli query|mutation list` and `... delete <name>`.
+
+## Escape Hatches
+
+**Any API operation, still structured** — prefer this over raw GraphQL:
+
+`mcli api list [--type query|mutation] [--no-builtins]` · `mcli api describe <op>` · `mcli api <op> --arg key=value...`
+
+JSON args are auto-coerced. `--select "id,name,column_values{id,text}"` overrides the
+selection set; `--dry-run` previews the request. The operation list comes from a
+schema embedded at build time — if `mcli api` warns on stderr that it is stale, or an
+operation you expect is missing, run `mcli schema refresh` (`mcli schema status`
+reports which schema is in use and its age).
+
+**Raw GraphQL**, when nothing above fits:
+
+`mcli query '<graphql>' [--var k=v]...` · `-f <file>` · `-f -` for stdin · `mcli mutation '<graphql>' ...`
+
+Output is passthrough `{"data":...,"errors":...}`: exit 0 when `errors` is absent,
+exit 2 when present. Reference:
+https://developer.monday.com/api-reference/reference/about-the-api-reference
+
+## Webhook Inbox (react to changes instead of polling)
+
+1. `mcli daemon start` — needs `cloudflared` in PATH, or pass `--url <public-url>` (`--port N` to move off 8420)
+2. `mcli webhook create --board <id> --event <type>` — `mcli webhook events` lists types; `mcli webhook list [--board <id>]` and `mcli webhook delete <id>` manage them
+3. `mcli notification count` is the cheap poll; then `mcli notification list [--unread] [--board <id>] [--event <t>] [--since <RFC3339>] [--limit N]`
+4. `mcli notification ack <id>` or `mcli notification ack --all`
+
+Commands that need the daemon fail with `DAEMON_REQUIRED` (exit 6) when it is not
+running.
diff --git a/internal/cli/skill_test.go b/internal/cli/skill_test.go
index 054c00c..a2c3747 100644
--- a/internal/cli/skill_test.go
+++ b/internal/cli/skill_test.go
@@ -2,11 +2,17 @@ package cli
 
 import (
 	"bytes"
+	"fmt"
 	"io"
+	"regexp"
+	"slices"
+	"strconv"
 	"strings"
 	"testing"
 
+	"github.com/mondaycom/mcli/internal/errs"
 	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
 )
 
 func execSkill(t *testing.T, args ...string) (string, error) {
@@ -95,10 +101,12 @@ func TestSkill_ContainsSections(t *testing.T) {
 
 	sections := []string{
 		"## Monday Hierarchy",
-		"## Goals & Commands",
-		"## Output Shapes",
+		"## Start Here: Discover IDs",
+		"## Read Items",
+		"## Write Items",
 		"## Column Values",
-		"## Error Codes",
+		"## Errors: What To Do Next",
+		"## Output Modes & Shapes",
 	}
 
 	for _, section := range sections {
@@ -138,13 +146,243 @@ func TestSkill_AliasDescribe(t *testing.T) {
 	}
 }
 
+// skillDocMaxBytes is a budget, not a limit found by measurement: this doc is loaded
+// into an agent's context on every session, so a new section should displace
+// something rather than simply appending. Raise it only with a reason.
+//
+// The budget is in bytes, not lines, because bytes are what the doc actually costs
+// an agent. Line count is a poor proxy: reflowing a paragraph changes it without
+// changing the cost, while one dense table row costs far more than one short line.
+const skillDocMaxBytes = 14000
+
 func TestSkill_Concise(t *testing.T) {
 	out, err := execSkill(t)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
-	lines := strings.Count(out, "\n")
-	if lines > 200 {
-		t.Errorf("skill doc should be concise; got %d lines (max 200)", lines)
+	if len(out) > skillDocMaxBytes {
+		t.Errorf("skill doc should be concise; got %d bytes (max %d)", len(out), skillDocMaxBytes)
+	}
+}
+
+// TestSkill_ErrorCodesMatchErrs guards the skill doc against drifting from the
+// real exit-code mapping. Every code in errs.AllCodes must appear in the doc
+// annotated with the exit code errs.ToExitCode actually returns for it.
+func TestSkill_ErrorCodesMatchErrs(t *testing.T) {
+	out, err := execSkill(t)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	for _, code := range errs.AllCodes() {
+		want := errs.ToExitCode(&errs.Error{Code: code})
+
+		// Matches "`CODE` 4" and grouped forms like "`API`/`NOT_FOUND` 2".
+		re := regexp.MustCompile("`" + string(code) + "`(?:/`[A-Z_]+`)*\\s+(\\d+)")
+		m := re.FindStringSubmatch(out)
+		if m == nil {
+			t.Errorf("code %s is not documented with an exit code in the skill doc", code)
+			continue
+		}
+		if got, _ := strconv.Atoi(m[1]); got != want {
+			t.Errorf("skill doc documents %s as exit %d, but errs.ToExitCode returns %d", code, got, want)
+		}
+	}
+}
+
+// ─── Drift guard ────────────────────────────────────────────────────────────
+//
+// The skill doc is the only description of mcli an agent gets, and a wrong flag in
+// it costs a failed API call and a retry loop. Nothing tied it to the real command
+// tree, so it drifted: `board create` was documented without `--workspace` (whose
+// absence returns an opaque "User unauthorized"), and `board column create` without
+// `--defaults` (whose absence silently gives a status column monday's stock labels).
+// These tests read the doc the way an agent does — every invocation it could copy —
+// and check each one against the real cobra tree.
+
+var (
+	skillCodeSpanRE = regexp.MustCompile("`([^`\n]+)`")
+	// skillCommandWordRE matches a token that could name a subcommand, including the
+	// compressed alternation forms the doc uses ("list/create", "query|mutation").
+	skillCommandWordRE = regexp.MustCompile(`^[a-z][a-z0-9|/-]*$`)
+	skillFlagRE        = regexp.MustCompile(`--[a-z][a-z0-9-]*|(?:^|\s)-([a-z])\b`)
+)
+
+// skillInvocations returns every documented mcli invocation: the text of each inline
+// code span, and each line of each fenced code block, from "mcli " onward. Those are
+// the strings an agent copies, so they are the ones that have to stay true.
+func skillInvocations(doc string) []string {
+	var out []string
+	add := func(s string) {
+		if _, rest, ok := strings.Cut(s, "mcli "); ok {
+			out = append(out, strings.TrimSpace(rest))
+		}
+	}
+	inFence := false
+	for line := range strings.SplitSeq(doc, "\n") {
+		if strings.HasPrefix(strings.TrimSpace(line), "```") {
+			inFence = !inFence
+			continue
+		}
+		if inFence {
+			add(line)
+			continue
+		}
+		for _, m := range skillCodeSpanRE.FindAllStringSubmatch(line, -1) {
+			add(m[1])
+		}
+	}
+	return out
+}
+
+// skillCommandPaths expands an invocation's leading command words into one path per
+// alternative, so "board group list/create" yields both real paths. Expansion stops
+// at the first token that cannot be a command name — a placeholder, flag, or literal
+// — which keeps flag *values* like "public|private|share" from being expanded.
+func skillCommandPaths(tokens []string) [][]string {
+	paths := [][]string{{}}
+	for _, tok := range tokens {
+		if !skillCommandWordRE.MatchString(tok) {
+			break
+		}
+		alts := strings.FieldsFunc(tok, func(r rune) bool { return r == '/' || r == '|' })
+		var next [][]string
+		for _, p := range paths {
+			for _, alt := range alts {
+				next = append(next, append(append([]string{}, p...), alt))
+			}
+		}
+		paths = next
+	}
+	return paths
+}
+
+// skillResolve walks as far down the real command tree as the path goes, returning
+// the deepest command matched and how many tokens it consumed.
+func skillResolve(path []string) (*cobra.Command, int) {
+	cmd := rootCmd
+	depth := 0
+	for _, tok := range path {
+		child := skillChild(cmd, tok)
+		if child == nil {
+			break
+		}
+		cmd, depth = child, depth+1
+	}
+	return cmd, depth
+}
+
+func skillChild(parent *cobra.Command, name string) *cobra.Command {
+	for _, c := range parent.Commands() {
+		if c.Name() == name {
+			return c
+		}
+		if slices.Contains(c.Aliases, name) {
+			return c
+		}
+	}
+	return nil
+}
+
+// skillHasFlag reports whether name is a real flag on cmd, counting flags inherited
+// from a parent or from the root's persistent set.
+func skillHasFlag(cmd *cobra.Command, name string) bool {
+	for _, set := range []*pflag.FlagSet{cmd.Flags(), cmd.PersistentFlags(), cmd.InheritedFlags(), rootCmd.PersistentFlags()} {
+		if set.Lookup(name) != nil {
+			return true
+		}
+	}
+	return false
+}
+
+func skillHasShorthand(cmd *cobra.Command, short string) bool {
+	for _, set := range []*pflag.FlagSet{cmd.Flags(), cmd.PersistentFlags(), cmd.InheritedFlags(), rootCmd.PersistentFlags()} {
+		if set.ShorthandLookup(short) != nil {
+			return true
+		}
+	}
+	return false
+}
+
+// skillAudit is the result of checking a doc against the real command tree.
+type skillAudit struct {
+	problems     []string
+	pathsChecked int
+	flagsChecked int
+}
+
+// auditSkillDoc checks every invocation in doc against the real cobra tree: that the
+// command path exists, and that each flag shown alongside it is a real flag on that
+// command. It returns human-readable problems rather than failing, so a negative test
+// can assert that it actually catches drift.
+func auditSkillDoc(doc string) skillAudit {
+	var a skillAudit
+	for _, inv := range skillInvocations(doc) {
+		tokens := strings.Fields(inv)
+		if len(tokens) == 0 {
+			continue
+		}
+		for _, path := range skillCommandPaths(tokens) {
+			if len(path) == 0 {
+				continue // e.g. `mcli <command> --help`, a deliberate placeholder
+			}
+			cmd, depth := skillResolve(path)
+			if depth == 0 {
+				a.problems = append(a.problems, fmt.Sprintf("unknown command %q (in `mcli %s`)", path[0], inv))
+				continue
+			}
+			// Tokens past the resolved command are positional args, not typos:
+			// `mcli mutation save create_order` resolves to "mutation save".
+			a.pathsChecked++
+			for _, m := range skillFlagRE.FindAllStringSubmatch(inv, -1) {
+				a.flagsChecked++
+				if short := m[1]; short != "" {
+					if !skillHasShorthand(cmd, short) {
+						a.problems = append(a.problems, fmt.Sprintf("-%s is not a shorthand on %q (in `mcli %s`)", short, cmd.CommandPath(), inv))
+					}
+					continue
+				}
+				name := strings.TrimPrefix(m[0], "--")
+				if !skillHasFlag(cmd, name) {
+					a.problems = append(a.problems, fmt.Sprintf("--%s is not a flag on %q (in `mcli %s`)", name, cmd.CommandPath(), inv))
+				}
+			}
+		}
+	}
+	return a
+}
+
+// TestSkillDoc_MatchesCommandTree is the check that was missing when the doc drifted:
+// every command and flag an agent could copy out of the doc has to be real.
+func TestSkillDoc_MatchesCommandTree(t *testing.T) {
+	a := auditSkillDoc(skillDoc)
+	for _, p := range a.problems {
+		t.Errorf("skill doc: %s", p)
+	}
+	// Guard the guard: without these, a broken extractor would pass vacuously.
+	if a.pathsChecked < 40 {
+		t.Errorf("only checked %d command paths; expected 40+ — is skillInvocations still working?", a.pathsChecked)
+	}
+	if a.flagsChecked < 60 {
+		t.Errorf("only checked %d flags; expected 60+ — is skillFlagRE still working?", a.flagsChecked)
+	}
+}
+
+// TestSkillDoc_AuditCatchesDrift proves the audit above can fail. Each case is a form
+// of drift that has actually happened or plausibly could.
+func TestSkillDoc_AuditCatchesDrift(t *testing.T) {
+	cases := map[string]string{
+		"renamed flag":      "`mcli board create --name x --workspac 1`",
+		"flag on wrong cmd": "`mcli item list --defaults x`",
+		"deleted command":   "`mcli board coloumn list --board 1`",
+		"bad shorthand":     "`mcli search foo -z boards`",
+		"drift in a fence":  "```sh\nmcli item create --board 1 --nam x\n```",
+	}
+	for name, doc := range cases {
+		t.Run(name, func(t *testing.T) {
+			if a := auditSkillDoc(strings.ReplaceAll(doc, "\\n", "\n")); len(a.problems) == 0 {
+				t.Errorf("audit found no problem in %q, but it should have", doc)
+			}
+		})
 	}
 }
diff --git a/internal/errs/errs.go b/internal/errs/errs.go
index 597a5d2..e082c58 100644
--- a/internal/errs/errs.go
+++ b/internal/errs/errs.go
@@ -20,8 +20,6 @@ const (
 	CodeRateLimited Code = "RATE_LIMITED"
 	// CodeNotFound indicates a resource was not found.
 	CodeNotFound Code = "NOT_FOUND"
-	// CodeConflict indicates a resource conflict.
-	CodeConflict Code = "CONFLICT"
 	// CodeInternal indicates an unexpected internal error.
 	CodeInternal Code = "INTERNAL"
 	// CodeDaemonRequired indicates the mcli daemon is not running but is needed.
@@ -30,6 +28,22 @@ const (
 	CodeInterrupted Code = "INTERRUPTED"
 )
 
+// AllCodes lists every Code mcli can report. It exists so documentation can be
+// verified against the real set of codes: adding a Code here without also
+// documenting it (see internal/cli skill doc) fails the test suite.
+func AllCodes() []Code {
+	return []Code{
+		CodeUsage,
+		CodeAPI,
+		CodeNotFound,
+		CodeAuth,
+		CodeRateLimited,
+		CodeInternal,
+		CodeDaemonRequired,
+		CodeInterrupted,
+	}
+}
+
 // Error is a structured error value carrying a Code, a human message, and an
 // optional wrapped cause.
 type Error struct {
diff --git a/memory-bank/adrs/ADR-002-cli-grammar.md b/memory-bank/adrs/ADR-002-cli-grammar.md
index 9d172e8..5fca5ed 100644
--- a/memory-bank/adrs/ADR-002-cli-grammar.md
+++ b/memory-bank/adrs/ADR-002-cli-grammar.md
@@ -60,10 +60,12 @@ Decisions in this document cover:
 |-----:|:--------|
 | 0 | Success |
 | 1 | Usage / input error (bad flag, invalid argument) |
-| 2 | API error (Monday returned GraphQL errors or non-2xx) |
+| 2 | API error (Monday returned GraphQL errors or non-2xx), or resource not found |
 | 3 | Auth error (missing or invalid token) |
 | 4 | Rate-limit / complexity-budget exceeded after retries |
-| 5 | Internal / unexpected error |
+| 5 | Internal / unexpected error, and the fallback for any unclassified error |
+| 6 | Daemon required but not running (see the daemon amendment below) |
+| 130 | Interrupted (SIGINT / SIGTERM / context cancellation) |
 
 ### Error format
 When any command fails and `--json` is active (or stdout is non-TTY), the last line of stdout is a single JSON object:
@@ -72,7 +74,22 @@ When any command fails and `--json` is active (or stdout is non-TTY), the last l
 {"error": {"code": "RATE_LIMITED", "message": "Complexity budget exceeded", "retryAfter": 30, "requestId": "..."}}
 ```
 
-`code` is drawn from a stable enumeration (`USAGE`, `AUTH`, `API`, `RATE_LIMITED`, `NOT_FOUND`, `CONFLICT`, `INTERNAL`). The same codes map to exit codes above. Human mode prints a red, structured error to stderr and exits.
+`code` is drawn from a stable enumeration (`USAGE`, `AUTH`, `API`, `RATE_LIMITED`, `NOT_FOUND`, `INTERNAL`, `DAEMON_REQUIRED`, `INTERRUPTED`). The same codes map to exit codes above. Human mode prints a red, structured error to stderr and exits.
+
+`internal/errs` is the single source of truth: `errs.AllCodes()` enumerates the codes and
+`errs.ToExitCode` performs the mapping. A test asserts the generated skill doc agrees with
+both, so this table cannot drift from the implementation unnoticed.
+
+#### Amendment (2026-09-08)
+
+Two codes were added after this ADR was first written, when the daemon landed:
+`DAEMON_REQUIRED` (exit 6) and `INTERRUPTED` (exit 130). They are now included in the
+table and enumeration above.
+
+A `CONFLICT` code was also originally specified here. It was never emitted — no
+constructor was ever written for it — and it has been removed from `internal/errs` rather
+than left as unreachable API surface. Resource conflicts surface as `API` (exit 2), which
+is what monday actually returns them as.
 
 ### Stdin / piping
 - Commands that accept bulk input (e.g. `mcli item create`) accept JSON on stdin when `-` is passed as a positional or when no positional is given and stdin is non-TTY.
diff --git a/memory-bank/adrs/ADR-003-llm-skill-api.md b/memory-bank/adrs/ADR-003-llm-skill-api.md
index eebb1f6..598c001 100644
--- a/memory-bank/adrs/ADR-003-llm-skill-api.md
+++ b/memory-bank/adrs/ADR-003-llm-skill-api.md
@@ -51,9 +51,11 @@ Top-level shape (schema version `1`):
     "2": "api error",
     "3": "auth error",
     "4": "rate limited",
-    "5": "internal error"
+    "5": "internal error",
+    "6": "daemon required",
+    "130": "interrupted"
   },
-  "errorCodes": ["USAGE", "AUTH", "API", "RATE_LIMITED", "NOT_FOUND", "CONFLICT", "INTERNAL"],
+  "errorCodes": ["USAGE", "AUTH", "API", "RATE_LIMITED", "NOT_FOUND", "INTERNAL", "DAEMON_REQUIRED", "INTERRUPTED"],
   "globalFlags": [ { "name": "json", "type": "bool", "description": "..." } ],
   "commands": [
     {
diff --git a/memory-bank/archive/plan-api-version.md b/memory-bank/archive/plan-api-version.md
deleted file mode 100644
index 7f86aaa..0000000
--- a/memory-bank/archive/plan-api-version.md
+++ /dev/null
@@ -1,102 +0,0 @@
-# Plan: Configurable API Version with Schema Auto-Refresh
-
-**Status**: COMPLETED
-**Created**: 2026-06-22
-
-## Overview
-
-`mcli config set api-version <version>` saves the version, fetches the schema for that version from the Monday.com API, and caches it locally. All subsequent `mcli api` commands use the cached schema and send the correct `API-Version` header. Falls back to the embedded schema when no local cache exists.
-
-If the version does not exist or the fetch fails, the version is reverted to the default and an error is reported — the CLI never enters a broken state.
-
----
-
-## Phase 1: Config struct + API-Version header
-**Status**: completed
-
-Wire the version through config into every API request.
-
-### Tasks:
-- [x] **1.1** Add `APIVersion string` (`yaml:"api_version,omitempty"`) to `Config` struct in `internal/config/config.go`
-- [x] **1.2** Add `config.ResolveAPIVersion(cfg Config) string` — precedence: `MONDAY_API_VERSION` env > `cfg.APIVersion` > `"2026-07"`
-- [x] **1.3** Update `httpx.NewClient(token, cliVersion, apiVersion string)` — add `apiVersion` param, store on `RetryTransport`, use instead of const
-- [x] **1.4** Update `internal/cli/query.go:newQueryHTTPClient` — pass `config.ResolveAPIVersion(cfg)` to `httpx.NewClient`
-- [x] **1.5** Update `internal/api/graphql/client.go:New` — add `WithAPIVersion(v string)` option; `newGQLClient()` in `client.go` passes `config.ResolveAPIVersion(cfg)`
-- [x] **1.6** Add `api-version` case to `runConfigSet` (validate `^\d{4}-\d{2}$`, or `"default"` to reset) and `runConfigGet` in `internal/cli/config.go`
-
-**Completion criteria**: `MONDAY_API_VERSION=2025-10 mcli query '{ me { id } }'` sends `API-Version: 2025-10`; `mcli config set api-version 2025-10 && mcli config get api-version` round-trips.
-
----
-
-## Phase 2: Local schema cache
-**Status**: completed
-
-Make `Load()` prefer a locally-cached schema file over the embedded SDL.
-
-### Tasks:
-- [x] **2.1** Add `apischema.SetConfigDir(dir string)` — stores the dir path; called once from `cli.Execute()` via `resolveConfigDir()`. Resets the sync state so the next `Load()` re-resolves.
-- [x] **2.2** Update `Load()` — when `configDir` is set, attempt `os.ReadFile(configDir + "/schema.graphql")` first; fall back to `rawschema.SDL` if the file is absent or unreadable
-- [x] **2.3** Add `apischema.CachedSchemaPath(configDir string) string` — returns `filepath.Join(configDir, "schema.graphql")`
-
-**Completion criteria**: placing a valid SDL at `~/.config/mcli/schema.graphql` causes `mcli api list` to reflect its contents; removing the file reverts to the embedded SDL.
-
----
-
-## Phase 3: Schema fetch on `config set api-version`
-**Status**: completed
-
-Extract the introspection logic from the tool and wire it into `config set`.
-
-### Tasks:
-- [x] **3.1** Create `internal/api/schema/fetch.go` — extract `fetchSchema(ctx, token, endpoint, apiVersion string) (introspSchema, error)` and `renderSDL(schema) string` from `tools/introspect/main.go` (shared, no build tag). The introspect types (`introspType`, etc.) move here too.
-- [x] **3.2** Update `tools/introspect/main.go` — replace inline logic with calls to the shared functions; read `MONDAY_API_VERSION` env (falls back to `"2026-07"`) for the `API-Version` header
-- [x] **3.3** Update `runConfigSet` for `api-version` with tentative save → fetch → revert-on-error or write schema
-- [x] **3.4** Handle the no-token case gracefully: save the config key but skip the fetch and warn
-- [x] **3.5** `mcli config set api-version default` resets to empty and removes cached schema.graphql
-
-**Completion criteria**: `mcli config set api-version 2026-08` (valid token) writes schema + confirms; `mcli config set api-version 9999-99` returns error, reverts to default, leaves no stale schema file.
-
----
-
-## Phase 4: Tests
-**Status**: completed
-
-### Tasks:
-- [x] **4.1** `internal/api/schema/schema_test.go` — `TestLoadResolved_localFile`: write a minimal SDL to a temp dir, call `SetConfigDir` + `Load()`, assert the local schema is used
-- [x] **4.2** `internal/api/schema/fetch_test.go` — mock HTTP server returning a known introspection response; assert `fetchSchema` returns expected types and `renderSDL` produces valid SDL
-- [x] **4.3** `internal/cli/config_test.go` — three cases: success, invalid format, 4xx revert
-
-### Known limitation
-Monday.com does not reject unknown version strings — it silently returns its current schema. The revert-on-error path fires on network/HTTP errors but not on unrecognised version values.
-
----
-
-## Risks & Trade-offs
-
-| Item | Note |
-|------|------|
-| `sync.Once` reset | `SetConfigDir` must reset the once-cell. Use a mutex + flag rather than `sync.Once` directly, or swap to an atomic pointer. |
-| Token required for schema fetch | Handled in 3.4 — degrade gracefully, version still saves. |
-| `tools/introspect` shares types with `internal/api/schema` | Introspect types move to `internal/api/schema/fetch.go`; introspect tool becomes a thin wrapper. |
-| Local schema may drift | A stale `schema.graphql` silently shadows the embedded one. Acceptable — user opted in by running `config set`. |
-| Revert on bad version | Config is written twice (once with new version, once with revert). Small window where config holds a bad version on crash, but schema file was never written so Load() falls back to embedded — safe. |
-
----
-
-## File Inventory
-
-| File | Change |
-|------|--------|
-| `internal/config/config.go` | Add `APIVersion` field, `ResolveAPIVersion()` |
-| `internal/httpx/client.go` | Add `apiVersion` param to `NewClient`, remove const |
-| `internal/api/graphql/client.go` | Add `WithAPIVersion` option |
-| `internal/cli/client.go` | Pass `ResolveAPIVersion` to graphql client |
-| `internal/cli/query.go` | Pass `ResolveAPIVersion` to `httpx.NewClient` |
-| `internal/cli/config.go` | Add `api-version` to set/get, schema fetch + revert logic |
-| `internal/cli/root.go` | Call `apischema.SetConfigDir(resolveConfigDir())` in init |
-| `internal/api/schema/schema.go` | Add `SetConfigDir`, update `Load()` |
-| `internal/api/schema/fetch.go` | New — shared introspect types + `fetchSchema` + `renderSDL` |
-| `tools/introspect/main.go` | Thin wrapper using shared functions |
-| `internal/api/schema/schema_test.go` | Add local file override test |
-| `internal/api/schema/fetch_test.go` | New — mocked HTTP fetch test |
-| `internal/cli/config_test.go` | New — end-to-end config set tests |
diff --git a/memory-bank/archive/plan-v0.md b/memory-bank/archive/plan-v0.md
deleted file mode 100644
index 416d4b1..0000000
--- a/memory-bank/archive/plan-v0.md
+++ /dev/null
@@ -1,202 +0,0 @@
-# Plan: mcli v0
-
-*Created: 2026-05-08*
-*Status: Phase 0 complete*
-
-## Goal
-Ship a Go-based CLI for monday.com's GraphQL API covering auth, boards (list/get/create), items (list/get/create/update/move + subitems), a raw GraphQL escape hatch, and an LLM skill API.
-
-See `memory-bank/projectbrief.md` for scope and `memory-bank/axioms.md` for ground truths.
-
-## Phase 0 — Foundations ✅
-
-**Deliverables:**
-- `memory-bank/projectbrief.md`
-- `memory-bank/axioms.md`
-- `memory-bank/adrs/ADR-001-stack.md`
-- `memory-bank/adrs/ADR-002-cli-grammar.md`
-- `memory-bank/adrs/ADR-003-llm-skill-api.md`
-- `memory-bank/docs/plan-v0.md` (this file)
-
-**Acceptance:**
-- AC-0.1: All ADRs committed with status `Active`.
-- AC-0.2: `axioms.md` covers coherence, LLM-native output, single binary, dependency policy.
-- AC-0.3: Git repo initialized with a checkpoint commit.
-
-## Phase 1 — Scaffold + auth + config ✅
-
-**Deliverables:**
-- `go.mod`, `cmd/mcli/main.go`, `internal/cli/root.go` with cobra skeleton.
-- `mcli version` wired to a `-ldflags`-injected version string.
-- `mcli auth login --token <t>` persists token at `~/.config/mcli/config.yaml` (mode 0600).
-- Token resolution precedence: `--token` flag > `MONDAY_API_TOKEN` env > config file.
-- `internal/config` package with typed config + load/save helpers.
-- `internal/httpx` package: authenticated HTTP client with `User-Agent: mcli/<version>`, 429/5xx backoff, request ID logging.
-- `Makefile` targets: `build`, `test`, `lint`, `vet`.
-- `.golangci.yml` with a conservative rule set.
-- GitHub Actions CI: build + test + lint on push/PR.
-
-**Acceptance:**
-- AC-1.1: `mcli version` prints the injected version.
-- AC-1.2: `mcli auth login --token TEST` writes the expected file with mode 0600.
-- AC-1.3: Config round-trip test: save → load returns structurally identical config.
-- AC-1.4: `golangci-lint run` exits 0.
-
-## Phase 1.5 — Secret-storage retrofit ✅
-
-Driven by ADR-004 and axioms A11 (no plaintext secrets) and A12 (LLM-primary). Phase 1 stored the token in plaintext; this phase replaces that with keychain-default + age-encrypted-file fallback.
-
-**Deliverables:**
-- `internal/secrets/secrets.go` — `Store` interface (`Put`/`Get`/`Delete`/`Available`), `BackendName` enum (`keychain`, `file`), `Open(name) (Store, error)` factory.
-- `internal/secrets/keychain.go` — `zalando/go-keyring` backend; `Available()` probes by attempting a sentinel read.
-- `internal/secrets/file.go` — age passphrase backend; reads `MCLI_PASSPHRASE` env; file at `<config-dir>/credentials.age` mode 0600; refuses to operate when env unset.
-- `internal/secrets/file_test.go` — round-trip encrypt/decrypt; missing-passphrase error.
-- `internal/secrets/keychain_test.go` — table-driven tests against an in-memory fake; one real-keychain test gated by build tag `keychain_real`.
-- `internal/config/config.go` — drop `Token` field; add `SecretStore` (BackendName); `Load` migrates legacy configs by stripping `token:` and emitting a stderr warning.
-- `internal/config/config_test.go` — migration test, `SecretStore` round-trip, `ResolveToken` rewritten to consult a `secrets.Store`.
-- `internal/cli/auth.go` — `auth login --token <t> [--store keychain|file]`; new `auth logout`; new `auth status` (never prints token).
-
-**Acceptance:**
-- AC-1.5.1: `mcli auth login --token T` → `mcli auth status` reports `keychain`; `grep -r T ~/.config/mcli` finds nothing.
-- AC-1.5.2: `MCLI_PASSPHRASE=p mcli auth login --token T --store file` → `credentials.age` exists 0600, contains no occurrence of `T` in raw bytes.
-- AC-1.5.3: `mcli auth logout` clears the secret; subsequent token-needing op returns `AUTH`.
-- AC-1.5.4: `--token` > `MONDAY_API_TOKEN` > backend precedence verified by table-driven test.
-- AC-1.5.5: A pre-existing `config.yaml` with `token:` is rewritten without that field on first read; warning emitted to stderr.
-- AC-1.5.6: All Phase 1 acceptance checks (AC-1.1 .. AC-1.4) still pass.
-- AC-1.5.7: `gofmt -l .`, `go vet ./...`, `golangci-lint run`, `go test -race ./...` all clean.
-
-**Deps added (both permissive):**
-- `github.com/zalando/go-keyring` — MIT.
-- `filippo.io/age` — BSD-3-Clause.
-
-## Phase 2 — GraphQL client + schema ✅
-
-**Deliverables:**
-- `schema/monday.graphql` — Monday GraphQL schema committed.
-- `Makefile` target `make schema` that refreshes the schema from a live endpoint (requires token).
-- `tools/gqlgen.go` wiring `Khan/genqlient` with generation config.
-- `internal/api/graphql` package:
-  - typed client wrapping the authenticated HTTP client,
-  - error normalization (GraphQL errors in a 200 → structured `APIError`),
-  - complexity-budget awareness (parse `X-Complexity-*` headers if present; extract from error payloads otherwise),
-  - retry on `COMPLEXITY_BUDGET_EXHAUSTED` with exponential backoff.
-- `go generate ./...` produces typed query bindings.
-- CI check: `go generate` produces no diff.
-
-**Acceptance:**
-- AC-2.1: A trivial `me { id name }` query returns a typed struct.
-- AC-2.2: A forced GraphQL error maps to a structured `APIError` with a stable `Code`.
-- AC-2.3: `go generate` produces no diff in CI.
-
-## Phase 3 — Boards ✅
-
-**Deliverables:**
-- `mcli board list [--workspace <id>] [--limit <n>] [--cursor <c>]`
-- `mcli board get <id>`
-- `mcli board create --name <name> [--workspace <id>] [--kind public|private|share]`
-- `internal/api/boards` package with typed request/response Go structs.
-- `examples/` JSON per command (per ADR-003).
-- Unit tests against recorded fixtures for each command.
-
-**Acceptance:**
-- AC-3.1: All three commands round-trip against recorded fixtures.
-- AC-3.2: Each command has at least one validated example JSON.
-- AC-3.3: `mcli describe board list` returns a manifest entry with a non-empty output schema.
-
-## Phase 4 — Items + column value normalization ✅
-
-Monday's `column_values` are JSON-string blobs whose shape varies per column type. Coherence direction (revised 2026-05-11): **write path is JSON-passthrough** — users supply the raw monday column-value JSON via `--col <id>=<json>`, which mcli wraps into the `column_values` map. **Read path normalizes** — we decode known types into clean human/LLM-readable values, falling through to raw JSON for unsupported types. Rationale: monday's column types are too customizable (esp. status/dropdown via settings_str) to expose a stable per-type write syntax in v0; LLMs are well-suited to construct the JSON blobs when handed the type. We can layer a hybrid syntax in a later phase if usage shows common types dominate.
-
-**Deliverables:**
-- `internal/api/items/columns` package:
-  - a registry of supported column types for the read path (text, long-text, status, date, datetime, people, dropdown, numeric, link, email, phone, timeline, tags, checkbox),
-  - `Decode(columnType, settingsStr, valueJSON) (any, error)` per type; passthrough (raw JSON string) for unknown types,
-  - no Encode registry in v0 — write path validates each `--col` value as JSON and aggregates into the wire-shape `column_values` string.
-- `mcli item list --board <id> [--group <id>] [--limit <n>] [--cursor <c>]`
-- `mcli item get <id>`
-- `mcli item create --board <id> [--group <id>] --name <name> [--col <col>=<value>]...` with repeated `--col` flags.
-- `mcli item update <id> [--name <name>] [--col <col>=<value>]...`
-- `mcli item move <id> --to-group <id> | --to-board <id>` (one of).
-- `--parent <id>` flag on `item create` to create a subitem.
-- Tests for every column type's Encode/Decode, including round-trip against the real API under a build tag.
-
-**Acceptance:**
-- AC-4.1: All item commands work against recorded fixtures.
-- AC-4.2: Every supported column type has a Decode test against a representative real-shape JSON sample.
-- AC-4.3: Unsupported column types Decode to their raw JSON string (passthrough, no error). Encode side is JSON-passthrough end-to-end so unsupported types are not a special case there.
-- AC-4.4: Subitems created via `--parent` appear under the parent on a subsequent `mcli item get`.
-
-## Phase 5 — Raw query escape hatch ✅
-
-**Deliverables:**
-- `mcli query '<graphql>'` inline, `-f <file>`, `-f -` from stdin.
-- `--var key=value` with auto-typing (int/float/bool/null/JSON obj/string).
-- `--vars-file <json>` for complex variables; combinable with `--var` (flag wins).
-- Saved queries: `mcli query save/list/run/delete` with local + global storage.
-- Output: raw passthrough `{"data":...,"errors":...,"extensions":...}`.
-- Exit code 2 if `errors` is non-empty, 0 otherwise.
-
-**Acceptance:**
-- AC-5.1: `echo 'query { me { id } }' | mcli query -f -` works. ✅
-- AC-5.2: Variables from flags and from file produce identical requests. ✅
-- AC-5.3: A query with GraphQL errors exits 2. ✅
-
-## Phase 6 — LLM skill API (partially complete)
-
-**Status:** `mcli skill` (alias `mcli describe`) ships a static goal-oriented Markdown skill doc. The original plan called for structured JSON manifest per ADR-003 + CI drift checks; those are deferred — the static skill doc is sufficient for LLM consumption in v0.
-
-**Shipped:**
-- `mcli skill` / `mcli describe` — prints concise goal-oriented skill doc (~120 lines)
-- Covers: hierarchy, CRUD goals, raw GraphQL, saved queries/mutations, column values, output shapes, error codes.
-
-**Deferred to post-v0:**
-- `mcli describe --json` structured manifest (ADR-003 shape)
-- CI drift check: regenerating SKILL.md produces no diff
-- CI schema check: every example JSON validates against its command's output schema
-
-## Phase 7 — Release (partially complete)
-
-**Shipped:**
-- `README.md` with quickstart, install, design principles, commands, LLM integration, column values, saved queries, development section.
-
-**Remaining:**
-- GitHub Actions release workflow: on tag push, build darwin/linux × amd64/arm64, attach to GitHub Release.
-- Install instructions: direct binary download + checksums. Homebrew tap deferred to post-v0.
-- Versioning: start at `v0.1.0`. Semver applies once v1.0.0 ships.
-
-**Acceptance:**
-- AC-7.1: A tag push produces a GitHub Release with all four platform binaries.
-- AC-7.2: The README quickstart works end-to-end against a real token. ✅
-
-## Out of scope (v0)
-Explicitly deferred, each a candidate for its own later plan:
-- Updates / comments.
-- Files upload.
-- Webhooks CRUD.
-- Teams, users CRUD, notifications.
-- Docs (Monday's "Docs" product).
-- ~~Workspace, group CRUD.~~ (done in Phase 4.5)
-- Mirror / formula column *writes* (read-through is fine).
-- OAuth.
-- Homebrew tap.
-- MCP server wrapper.
-
-## Open questions
-- ~~Binary name `mcli`~~ — resolved 2026-05-09 (chosen, in production).
-- ~~Config path `~/.config/mcli/`~~ — resolved 2026-05-09 (XDG-aware).
-- JSON-schema generation library for manifest: decide in Phase 2 (candidates: `invopop/jsonschema`).
-
-## Phase 2 prerequisites (carry-overs from Phase 1)
-- **httpx body preservation across retries**: `RetryTransport.RoundTrip` does not preserve the request body across retries. POST requests (all of GraphQL) will silently send an empty body on retry attempts. Must be fixed before Phase 2 wires real GraphQL calls. Fix: snapshot `req.GetBody` (or buffer the body) before the first attempt and replay on each retry. Add a test that posts a non-empty body and verifies the retry receives the same body.
-
-## Progress log
-- 2026-05-08: Phase 0 complete — axioms + ADR-001/002/003 + this plan.
-- 2026-05-09: Phase 1 complete — scaffold + auth + config. Deps: cobra, yaml.v3. All AC met; go test -race green, golangci-lint clean.
-- 2026-05-09: Phase 1 review fixes — error output path now honors ADR-002 (JSON to stdout in non-TTY/--json, human to stderr in --pretty/TTY); cobra error/usage rendering silenced; new internal/cli/output.go with TTY detection. R3 (httpx body preservation) carried as Phase 2 prerequisite.
-- 2026-05-09: Phase 1.5 complete — secret storage retrofit. internal/secrets (keychain + age file). config no longer holds token; legacy plaintext migration in place. Deps: zalando/go-keyring (MIT), filippo.io/age (BSD-3). All AC met; tests + lint clean.
-- 2026-05-10: Phase 2 complete — schema introspection (4890 lines, 272 types), genqlient wired (Me + BoardByID bindings), typed graphql client wrapper with error normalisation (COMPLEXITY_BUDGET_EXHAUSTED → RateLimited; auth → Auth) and complexity-budget retry above httpx. Hidden→visible `mcli me` smoke command verified live against real API (AC-2.1). CI no-diff check on internal/api/gen/ (AC-2.3). R3 (httpx body preservation) fixed as prerequisite. Deps: Khan/genqlient (MIT). All AC met.
-- 2026-05-10: Phase 3 complete — mcli board {list,get,create}. Notable: monday's `boards` query without workspace_ids returns empty when the var is sent as null; required `# @genqlient(omitempty: true)` to drop it. Page+limit pagination encoded as decimal-string cursor for surface uniformity. Live smoke: 25-board listing, get of board 9832181507, create of board 18412490770. Examples committed under examples/.
-- 2026-05-11: Phase 4 complete — items CRUD + column-value normalization. 4a: Decode registry (14 types + passthrough). 4b: item list (cursor-based items_page) + item get (full detail w/ subitems, creator, columns). 4c: item create (--board/--parent mutually exclusive, --col passthrough), item update (--name as bare JSON string, --col). 4d: item move (--to-group XOR --to-board+--group). Name column fix: monday expects bare string, not {"name":...}. Live verified all commands against board 9832181507.
-- 2026-05-12: Phase 4.5 complete — board structure + workspace + skill. 4.5a: workspace list/get/create/update/delete + folder list/create/rename/delete. 4.5b: board rename/delete/archive, group CRUD (list/create/delete/archive/rename), column CRUD (list/create/delete/rename/describe). 4.5c: item delete/archive + `mcli skill`/`mcli describe` (1028-line LLM skill doc generated from command tree). All live-verified. 50 command sections in skill doc.
-- 2026-05-12: Phase 5 complete — `mcli query` raw GraphQL escape hatch. Inline query as first arg, -f file/stdin, --var with auto-typing, --vars-file. Saved queries (save/list/run/delete) with local (.mcli/queries/) + global (~/.config/mcli/queries/) storage. Skill doc rewritten to 107-line goal-oriented format with raw query section.
-- 2026-05-12: `mcli mutation` — mirrors query with separate namespace (.mcli/mutations/ local, ~/.config/mcli/mutations/ global). Save/list/run/delete subcommands. Live verified full lifecycle. README added with quickstart + commands reference.
diff --git a/memory-bank/docs/plan-daemon-webhooks.md b/memory-bank/docs/plan-daemon-webhooks.md
deleted file mode 100644
index f3c7ddb..0000000
--- a/memory-bank/docs/plan-daemon-webhooks.md
+++ /dev/null
@@ -1,165 +0,0 @@
-# Plan: mcli Daemon + Webhooks + Notifications
-
-*Created: 2026-05-12*
-*Status: not_started*
-
-## Overview
-
-Add a persistent daemon to mcli that receives monday.com webhook events via Cloudflare Quick Tunnels, stores them in a local SQLite inbox, and exposes them to LLM agents through `mcli notification list`. The daemon also manages webhook lifecycle — registering/unregistering hooks with monday.com and re-registering them when the tunnel URL changes.
-
-**Architecture:**
-
-```
-monday.com → POST → Cloudflare Quick Tunnel → mcli daemon (localhost)
-                                                    ↓
-                                              SQLite event store
-                                                    ↑
-                                     mcli notification list (agent polls)
-```
-
-**IPC:** The daemon exposes a Unix socket (`~/.config/mcli/daemon.sock`) for CLI-to-daemon communication. CLI commands (`notification list`, `webhook create`, etc.) talk to the daemon over this socket.
-
-**Key decisions:**
-- Storage: SQLite via `modernc.org/sqlite` (pure Go, BSD, no CGO — preserves static binary)
-- Tunnel: Cloudflare Quick Tunnels (`cloudflared` external binary, not bundled)
-- Daemon gate: All daemon-dependent commands require explicit `mcli daemon start` — no auto-start. Agent must understand a persistent process is involved.
-- Webhook registration: One webhook per `create` call (board + event pair). Matches monday's API 1:1.
-
-## Phase 1: Daemon Core + Local IPC
-**Status**: not_started
-
-The daemon process that listens on localhost, serves a health/control API over a Unix socket, and manages its own lifecycle (PID file, signal handling).
-
-### Tasks:
-- [ ] **`internal/daemon/daemon.go`**: Core daemon struct — HTTP server on configurable port, Unix socket for IPC at `~/.config/mcli/daemon.sock`
-- [ ] **`internal/daemon/ipc.go`**: IPC protocol over Unix socket — simple REST-style JSON (status, list-events, ack-event, register-webhook, etc.)
-- [ ] **`internal/daemon/pidfile.go`**: PID file at `~/.config/mcli/daemon.pid` — create on start, remove on stop, detect stale PIDs
-- [ ] **`mcli daemon start [--port N] [--detach] [--url <external-url>]`**: Start the daemon. If no `--url`, requires cloudflared (Phase 2). `--detach` forks to background.
-- [ ] **`mcli daemon stop`**: Sends shutdown signal via IPC socket
-- [ ] **`mcli daemon status`**: Reports running/stopped, PID, port, tunnel URL
-- [ ] **`internal/cli/daemon_gate.go`**: Helper that checks daemon is running (socket exists + responds to ping); used by notification/webhook commands to gate with "daemon not running, run `mcli daemon start`"
-- [ ] Unit tests: start/stop lifecycle, PID file handling, IPC round-trip
-
-### Acceptance Criteria:
-- [ ] `AC-P1-1`: `mcli daemon start` starts an HTTP server and creates PID file + socket
-- [ ] `AC-P1-2`: `mcli daemon status` reports running state
-- [ ] `AC-P1-3`: `mcli daemon stop` cleanly shuts down and removes PID/socket
-- [ ] `AC-P1-4`: `mcli notification list` with daemon stopped prints "daemon not running" error with hint
-
----
-
-## Phase 2: Cloudflare Quick Tunnel Integration
-**Status**: not_started
-
-Auto-expose the daemon's local port via Cloudflare Quick Tunnels. Persist the active tunnel URL. Detect URL changes and trigger webhook re-registration (Phase 4).
-
-### Tasks:
-- [ ] **`internal/daemon/tunnel.go`**: Launch `cloudflared tunnel --url http://localhost:<port>` as a subprocess, parse the assigned URL from its stderr output
-- [ ] **Tunnel lifecycle**: Start with daemon, restart on crash, kill on daemon stop
-- [ ] **URL persistence**: Write current tunnel URL to SQLite (or `~/.config/mcli/tunnel_url`) — consumed by webhook registration
-- [ ] **URL change detection**: When tunnel restarts and URL changes, emit an internal event that Phase 4 hooks into for re-registration
-- [ ] **Fallback `--url`**: If user passes `--url https://my.server/hooks`, skip cloudflared entirely (for production deploys)
-- [ ] **Prerequisite check**: On `daemon start` without `--url`, verify `cloudflared` is in PATH; if missing, error with install instructions
-- [ ] Unit tests: URL parsing from cloudflared output, fallback mode
-
-### Acceptance Criteria:
-- [ ] `AC-P2-1`: `mcli daemon start` launches cloudflared and reports the public URL
-- [ ] `AC-P2-2`: `mcli daemon status` shows the active tunnel URL
-- [ ] `AC-P2-3`: `mcli daemon start --url https://x` skips cloudflared
-- [ ] `AC-P2-4`: If cloudflared is missing, daemon start fails with clear error message
-
----
-
-## Phase 3: Webhook HTTP Handler + Event Store
-**Status**: not_started
-
-The HTTP handler that receives monday.com webhook POSTs, handles the challenge handshake, and stores events in SQLite.
-
-### Tasks:
-- [ ] **`internal/daemon/handler.go`**: HTTP handler at `/webhook` — handles monday's challenge verification (echo `{"challenge": token}`) and normal event POSTs
-- [ ] **`internal/daemon/store.go`**: SQLite-based event store. DB at `~/.config/mcli/events.db`. Schema: `events(id TEXT PK, received_at TEXT, board_id TEXT, event_type TEXT, webhook_id TEXT, payload JSON, read INTEGER DEFAULT 0)`
-- [ ] **Event schema**: Canonical event struct — `{id, received_at, board_id, event_type, webhook_id, payload, read}`
-- [ ] **Retention/compaction**: Max events configurable (default 1000), oldest auto-pruned on write. Or TTL-based (7 days default).
-- [ ] **Monday webhook auth**: Verify request structure. Research if monday signs payloads (HMAC) and implement if so.
-- [ ] Unit tests: challenge handling, event storage CRUD, retention pruning
-
-### Acceptance Criteria:
-- [ ] `AC-P3-1`: POST to `/webhook` with challenge payload returns `{"challenge": ...}` (200 OK)
-- [ ] `AC-P3-2`: POST to `/webhook` with event payload stores it in SQLite
-- [ ] `AC-P3-3`: Events exceeding retention limit are pruned
-- [ ] `AC-P3-4`: Stored events are queryable via store interface (list, filter by board/type/read-status)
-
----
-
-## Phase 4: Webhook Registration + Persistence
-**Status**: not_started
-
-CRUD commands for monday.com webhooks. Persist registrations locally so they survive daemon restarts and tunnel URL changes.
-
-### Tasks:
-- [ ] **Webhook registry table**: SQLite table `webhooks(id TEXT PK, board_id TEXT, event TEXT, url TEXT, created_at TEXT)` — `id` is monday's webhook ID
-- [ ] **`mcli webhook create --board <id> --event <type>`**: Registers with monday via GraphQL `create_webhook` using current tunnel URL. Persists to local registry. Requires daemon running.
-- [ ] **`mcli webhook list [--board <id>]`**: Lists locally registered webhooks
-- [ ] **`mcli webhook delete <id>`**: Calls monday's `delete_webhook` + removes from local registry
-- [ ] **Re-registration on URL change**: When tunnel URL changes (detected in Phase 2), iterate all persisted webhooks, delete old + create new with new URL. Update local registry IDs.
-- [ ] **`mcli webhook events`**: List the 21 available WebhookEventType values for discoverability
-- [ ] Unit tests: CRUD operations, re-registration flow with mocked GraphQL
-
-### Acceptance Criteria:
-- [ ] `AC-P4-1`: `mcli webhook create --board 123 --event create_item` registers with monday and persists locally
-- [ ] `AC-P4-2`: `mcli webhook list` shows registered webhooks with board/event/URL
-- [ ] `AC-P4-3`: `mcli webhook delete <id>` removes from monday and local store
-- [ ] `AC-P4-4`: On tunnel URL change, all webhooks are re-registered with new URL
-- [ ] `AC-P4-5`: `mcli webhook events` prints available event types
-
----
-
-## Phase 5: Notification Commands (Agent Interface)
-**Status**: not_started
-
-The commands the LLM agent actually uses to poll the inbox.
-
-### Tasks:
-- [ ] **`mcli notification list [--unread] [--board <id>] [--event <type>] [--since <time>] [--limit N]`**: Fetches events from daemon via IPC. JSON output: `{"items": [...], "unread_count": N}`
-- [ ] **`mcli notification ack <id>` / `mcli notification ack --all`**: Mark events as read
-- [ ] **`mcli notification count`**: Quick unread count (for heartbeat efficiency — cheaper than full list)
-- [ ] **Daemon gate**: All notification commands check daemon is running first; if not, return `{"error":{"code":"DAEMON_REQUIRED","message":"...run mcli daemon start..."}}`
-- [ ] **Skill doc update**: Add notifications section — "poll `mcli notification count` on heartbeat, fetch details with `mcli notification list --unread`"
-- [ ] Unit tests: list/ack/count via mocked IPC
-
-### Acceptance Criteria:
-- [ ] `AC-P5-1`: `mcli notification list --unread --json` returns unread events
-- [ ] `AC-P5-2`: `mcli notification ack <id>` marks event as read; subsequent `--unread` excludes it
-- [ ] `AC-P5-3`: `mcli notification count` returns `{"unread": N}` with daemon running
-- [ ] `AC-P5-4`: All notification commands return DAEMON_REQUIRED error when daemon is stopped
-- [ ] `AC-P5-5`: Skill doc updated with notification workflow
-
----
-
-## Phase 6: Integration Testing + Docs
-**Status**: not_started
-
-### Tasks:
-- [ ] **End-to-end test**: daemon start → webhook create → simulate POST → notification list → ack → notification count = 0
-- [ ] **README update**: Add daemon/webhook/notification section
-- [ ] **plan-v0.md update**: Add phase entry
-- [ ] **ADR**: ADR for daemon architecture decisions (IPC choice, storage format, tunnel strategy)
-
-### Acceptance Criteria:
-- [ ] `AC-P6-1`: Full lifecycle e2e test passes
-- [ ] `AC-P6-2`: README documents the setup and agent polling workflow
-
----
-
-## Dependencies
-
-| Package | Purpose | License |
-|---------|---------|---------|
-| `modernc.org/sqlite` | Pure-Go SQLite (no CGO, preserves static binary) | BSD-3-Clause |
-| (external) `cloudflared` | Cloudflare Quick Tunnels binary — user-installed prerequisite | Apache-2.0 |
-
-## Open Questions
-
-1. **Monday webhook signing** — does monday sign webhook payloads (HMAC)? If so we should verify. Need to check their docs.
-2. **Daemon logging** — where do daemon logs go? stderr when foreground, file when detached?
-3. **Event payload shape** — monday's webhook POST body varies by event type. Do we normalize or store raw?
diff --git a/memory-bank/docs/plan-dynamic-api.md b/memory-bank/docs/plan-dynamic-api.md
deleted file mode 100644
index d24bc4d..0000000
--- a/memory-bank/docs/plan-dynamic-api.md
+++ /dev/null
@@ -1,347 +0,0 @@
-# Plan: Dynamic GraphQL API Commands + LLM Skill Exposure
-
-**Status**: COMPLETED (Phase 5 deferred — selection set intelligence)
-**Created**: 2026-06-21  
-**Updated**: 2026-06-22  
-**Branch**: `worktree-feat+dynamic-api`  
-**Depends on**: Phase 5 complete (search, docs, output modes)
-
-## Motivation
-
-mcli covers ~50 typed operations via hand-coded commands. Monday.com's API exposes ~90 query fields and ~160 mutation fields. Users (and LLM agents) needing uncovered operations must compose raw GraphQL manually via `mcli query`/`mcli mutation`. This plan adds a dynamic `mcli api` namespace that makes **every** API operation discoverable and executable without writing GraphQL.
-
-Reference: [kevinhury/monday-cli](https://github.com/kevinhury/monday-cli) — generates CLI commands from schema. We go further: embedded schema, auto-selection sets, JSON coercion, and LLM skill integration.
-
-## Design Principles
-
-1. **Zero GraphQL knowledge required** — users pass args by name, get JSON back
-2. **Friendly JSON handling** — Monday's `JSON` scalar requires stringified JSON on the wire (e.g. `column_values` must be `"{\"status\":{\"label\":\"Done\"}}"` not `{"status":{"label":"Done"}}`). The dynamic commands MUST auto-stringify any argument declared as `JSON` type in the schema, exactly like `coerceJSONVars` does today for `mcli query`. Users/LLMs pass natural JSON; the CLI handles the double-encoding internally.
-3. **Built-ins remain canonical** — `mcli api` is additive; existing commands keep their ergonomic flags and formatted output
-4. **LLM-first discovery** — agents can enumerate operations, read signatures, and invoke without human assistance
-5. **Single binary, no network** — schema is `//go:embed`'d from the committed SDL
-
-## Architecture
-
-```
-schema/monday.graphql (committed, refreshable via `make schema`)
-       │
-       ▼  go:embed + gqlparser v2
-internal/api/schema/             ← NEW package
-  schema.go                      load/cache parsed AST
-  selection.go                   auto-generate selection sets
-       │
-       ▼
-internal/cli/api.go              ← NEW: dynamic cobra command tree
-       │
-       ├─ mcli api <field_name> [--arg k=v]... [--select ...]
-       ├─ mcli api list [--type query|mutation]
-       └─ mcli api describe <field_or_type_name>
-```
-
-## JSON Coercion Detail
-
-The existing `coerceJSONVars` regex-parses variable declarations to find `$var: JSON` and stringifies map/slice values. For the dynamic commands, we have **schema-level type info** — much better:
-
-```
-For each argument of the target field:
-  1. Resolve its type from the parsed AST
-  2. If the leaf type is the `JSON` scalar:
-     - Accept the user's value as natural JSON (object, array, or string)
-     - If it's already a string (user passed a raw string), use as-is
-     - If it's a map/slice (parsed from --arg val='{...}'), json.Marshal → string
-  3. All other scalars: use existing parseVarValue auto-typing (int, bool, etc.)
-```
-
-This means: `--arg column_values='{"status":{"label":"Done"}}'` just works. No double-quoting, no escape gymnastics. The CLI knows from the schema that `column_values` is `JSON` and handles stringification.
-
-## Phases
-
-### Phase 1: Schema Package (foundation)
-**Status**: completed  
-**Effort**: ~1 day  
-**Delivers**: Reusable parsed schema access for the whole codebase
-
-New `internal/api/schema/` package:
-
-| Function | Purpose |
-|----------|---------|
-| `Load() *ast.Schema` | Parse embedded SDL via gqlparser, cache result |
-| `QueryFields() []FieldDef` | Root Query fields (name, description, args, return type) |
-| `MutationFields() []FieldDef` | Root Mutation fields |
-| `TypeDef(name string) *TypeInfo` | Lookup any type's fields/args/enums/description |
-| `IsJSONScalar(argType *ast.Type) bool` | Resolve whether an arg needs JSON coercion |
-| `DefaultSelection(typeName string, depth int) string` | Generate `{ id name ... }` for a return type |
-
-```go
-// FieldDef is the information needed to register a dynamic command.
-type FieldDef struct {
-    Name        string
-    Description string
-    Args        []ArgDef
-    ReturnType  string    // e.g. "Board", "[Item]!", "JSON"
-    IsQuery     bool      // false = mutation
-}
-
-type ArgDef struct {
-    Name         string
-    Description  string
-    TypeString   string   // e.g. "ID!", "[String]", "JSON"
-    IsRequired   bool
-    IsJSON       bool     // true if leaf scalar is JSON
-    DefaultValue string   // "" if none
-}
-```
-
-**Embed strategy**:
-```go
-//go:embed schema/monday.graphql
-var schemaSDL string
-```
-
-The embed directive lives in `internal/api/schema/embed.go` (or similar) and references the repo-root schema via a relative path from the module root.
-
----
-
-### Phase 2: Dynamic Command Registration (`mcli api`)
-**Status**: completed  
-**Effort**: ~2-3 days  
-**Delivers**: Every API operation executable via CLI
-
-> **Implementation note**: Used `cobra.ArbitraryArgs` + `RunE` on the `api` parent (not 250 dynamic subcommands) to avoid startup cost and cobra routing complexity. `list` and `describe` are static subcommands.
-
-New `internal/cli/api.go`:
-
-**Registration strategy** — lazy to avoid startup cost:
-```go
-func newAPICmd() *cobra.Command {
-    cmd := &cobra.Command{
-        Use:   "api",
-        Short: "Execute any monday.com API operation by name",
-    }
-    // Subcommands registered only when 'api' is actually invoked
-    cmd.PersistentPreRunE = func(cmd *cobra.Command, args []string) error {
-        registerDynamicCommands(cmd)
-        return nil
-    }
-    // Static subcommands always present
-    cmd.AddCommand(newAPIListCmd())
-    cmd.AddCommand(newAPIDescribeCmd())
-    return cmd
-}
-```
-
-**Each dynamic command**:
-
-```
-mcli api create_notification --arg user_id=12345 --arg text="Hello" --arg target_id=67890 --arg target_type=Project
-```
-
-Execution flow:
-1. Look up field definition from parsed schema
-2. Parse `--arg` flags → map[string]any via `parseVarValue`
-3. For each arg where `IsJSON == true`: if value is map/slice, `json.Marshal` it to string
-4. Validate required args are present (report missing with helpful message)
-5. Generate GraphQL operation string:
-   ```graphql
-   mutation($user_id: ID!, $text: String!, $target_id: ID!, $target_type: NotificationTargetType!) {
-     create_notification(user_id: $user_id, text: $text, target_id: $target_id, target_type: $target_type) {
-       id
-     }
-   }
-   ```
-6. Selection set: auto-generated from return type (depth 2) unless `--select` overrides
-7. Delegate to `executeRawQuery` (reuses auth, retry, error normalization)
-
-**Flags per dynamic command**:
-- `--arg key=value` (repeatable) — auto-typed, JSON-coerced
-- `--arg-file path.json` — bulk args from JSON file
-- `--select fields` — override auto-selection (e.g. `"id,name,column_values{id,text,value}"`)
-- `--depth N` — control auto-selection depth (default 2)
-- `--dry-run` — print generated GraphQL without executing
-
-**Help text generation**:
-```
-$ mcli api create_notification --help
-Execute: mutation create_notification
-
-Create a new notification.
-
-Arguments:
-  user_id         ID!                        (required) The user to notify
-  text            String!                    (required) Notification text
-  target_id       ID!                        (required) Target entity ID  
-  target_type     NotificationTargetType!    (required) Target type (Project/Post)
-
-Returns: Notification { id }
-
-See also: No built-in equivalent.
-Use --dry-run to preview the generated GraphQL.
-```
-
-**Built-in cross-reference**: For fields that have a built-in equivalent (e.g. `boards` → `mcli board list`), help text includes:
-```
-See also: mcli board list (structured output, pagination flags)
-```
-
----
-
-### Phase 3: Discovery & Browsing
-**Status**: completed  
-**Effort**: ~1 day  
-**Delivers**: Schema exploration without leaving the terminal
-
-#### `mcli api list`
-
-```
-$ mcli api list --type mutation | head
-create_board          Create a new board                              [see: mcli board create]
-create_column         Create a new column in a board                  [see: mcli board column create]
-create_doc            Create a new doc                                
-create_folder         Create a new folder                             [see: mcli folder create]
-create_group          Create a new group in a board                   [see: mcli board group create]
-create_item           Create a new item                               [see: mcli item create]
-create_notification   Create a new notification                       
-create_subitem        Create a new subitem                            [see: mcli item create --parent]
-create_webhook        Create a new webhook                            [see: mcli webhook create]
-...
-```
-
-- `--type query|mutation` — filter
-- `--json` — machine-readable array
-- `--no-builtins` — hide operations that have built-in equivalents
-- Supports grep-friendly output (one line per operation)
-
-#### `mcli api describe <name>`
-
-Works for both operations and types:
-
-```
-$ mcli api describe Board
-type Board {
-  id: ID!                      The board's unique identifier
-  name: String!                The board's name
-  state: State!                The board's state (active/archived/deleted)
-  board_kind: BoardKind!       The board's kind (public/private/share)
-  columns: [Column!]!          The board's columns
-  groups: [Group!]!            The board's groups
-  items_page(...): ItemsResponse!  Items with cursor pagination
-  ...
-}
-```
-
----
-
-### Phase 4: LLM Skill & Subskill Update
-**Status**: completed  
-**Effort**: ~1 day  
-**Delivers**: LLM agents can self-serve any API operation
-
-Update `skillDoc` in `internal/cli/skill.go` to add:
-
-```markdown
-### Generic API (any operation)
-
-For operations not covered by built-in commands, use `mcli api`:
-
-1. Discover: `mcli api list` — see all ~250 available operations
-2. Inspect: `mcli api describe <operation>` — see args, types, description  
-3. Execute: `mcli api <operation> --arg key=value...`
-
-JSON arguments (like column_values) are auto-handled — pass natural JSON,
-no double-encoding needed:
-  mcli api change_column_value --arg board_id=123 --arg item_id=456 \
-    --arg column_id=status --arg value='{"label":"Done"}'
-
-Override returned fields: `--select "id,name,column_values{id,text}"`
-Preview query without executing: `--dry-run`
-
-### Capability Categories
-
-| Category | Example operations |
-|----------|-------------------|
-| Notifications | create_notification |
-| Teams | add_teams_to_board, create_team, add_users_to_team |
-| Apps | create_app, install_app, app_subscriptions |
-| Forms | create_form, update_form_question |
-| Automations | trigger_events, block_events |
-| Dashboards | create_dashboard, create_widget |
-| Portfolios | create_portfolio, connect_project_to_portfolio |
-```
-
-**Subskill concept**: The skill doc categorizes operations so LLMs can narrow their search. `mcli api list` output is grep-able, so an LLM can: `mcli api list | grep team` to find team-related operations.
-
----
-
-### Phase 5: Selection Set Intelligence (stretch)
-**Status**: not_started (deferred)  
-**Effort**: ~1-2 days  
-**Delivers**: Better defaults, less --select overriding needed
-
-- **Smart scalar preference**: auto-select `id`, `name`, `state`, `kind` and other common scalars at depth 1
-- **Pagination awareness**: if return type has `cursor`/`items_page` pattern, include cursor fields
-- **Depth control**: `--depth 1` for IDs only, `--depth 3` for nested structures
-- **Presets**: `--select @id` (just id), `--select @full` (depth 4, all scalars)
-- **Connection pattern**: detect `[Type!]!` vs `TypeResponse { items, cursor }` and handle both
-
----
-
-## Key Decisions
-
-| # | Decision | Rationale |
-|---|----------|-----------|
-| 1 | `mcli api` namespace (not top-level) | Avoids collision with built-ins; clear "generic" boundary |
-| 2 | JSON coercion from schema types (not regex) | More reliable than regex; we HAVE the parsed schema |
-| 3 | `//go:embed` the SDL | Single binary; no runtime file or network dependency |
-| 4 | Lazy command registration | ~250 commands would slow startup if always registered |
-| 5 | Reuse `executeRawQuery` | Gets auth, retry, complexity handling, error codes for free |
-| 6 | Auto-selection with override | LLMs rarely know field names upfront; smart defaults reduce roundtrips |
-| 7 | `--dry-run` flag | Debugging and learning; LLM agents can verify before executing |
-
-## Risks & Mitigations
-
-| Risk | Mitigation |
-|------|-----------|
-| ~250 subcommands pollute help/completion | Lazy registration; `mcli api list` for discovery; top-level `mcli --help` just shows `api` as one entry |
-| Schema embedded at build time may drift | CI refresh (`make schema`); `mcli api --schema-version` shows generation date; warn if >30 days |
-| Deep return types → oversized queries | Cap at depth 2; document `--depth` and `--select` |
-| Some mutations need complex nested JSON args | JSON coercion handles this transparently; `--arg-file` for very complex cases |
-| Field name collisions between Query and Mutation | Monday's schema has none today; if one appears, prefix with `query/` or `mutation/` and add `--mutation` flag |
-
-## Effort Summary
-
-| Phase | Days | Ships independently? | Prerequisite |
-|-------|------|---------------------|--------------|
-| 1: Schema package | 1 | No (foundation) | — |
-| 2: Dynamic commands | 2-3 | Yes (core MVP) | Phase 1 |
-| 3: Discovery/browsing | 1 | Yes | Phase 1 |
-| 4: LLM skill update | 1 | Yes | Phase 2 |
-| 5: Selection intelligence | 1-2 | Yes (stretch) | Phase 1 |
-| **Total** | **6-8 days** | | |
-
-**MVP = Phases 1-3** (~4-5 days): parse schema, register dynamic commands with JSON coercion, add list/describe.  
-**Full = Phases 1-4** (~5-6 days): add LLM skill documentation.  
-**Polish = Phase 5** (~1-2 more days): smarter selection sets.
-
-## File Inventory (new files)
-
-```
-internal/api/schema/
-  embed.go              //go:embed directive + raw SDL string
-  schema.go             Load(), QueryFields(), MutationFields(), TypeDef()
-  selection.go          DefaultSelection(), depth-limited field picker
-  coerce.go             IsJSONScalar(), CoerceArgs() — schema-aware JSON stringification
-  schema_test.go        Unit tests against embedded schema
-
-internal/cli/
-  api.go                newAPICmd(), dynamic command registration, execution
-  api_list.go           mcli api list
-  api_describe.go       mcli api describe
-  api_test.go           Integration tests (mocked HTTP)
-```
-
-## Non-Goals (explicitly out of scope)
-
-- Replacing built-in commands — they stay for ergonomics and formatted output
-- Subscriptions — monday.com doesn't expose GraphQL subscriptions publicly
-- Schema hot-reload from live API — use `make schema` + rebuild
-- Tab completion for dynamic arg values (enum completion could be Phase 6)
diff --git a/memory-bank/docs/plan-phase4.5.md b/memory-bank/docs/plan-phase4.5.md
deleted file mode 100644
index 6eb1884..0000000
--- a/memory-bank/docs/plan-phase4.5.md
+++ /dev/null
@@ -1,86 +0,0 @@
-# Phase 4.5: Board Structure, Workspace, Delete + Skill Command
-
-## Overview
-
-Add the fundamental structural commands an LLM agent needs to fully manage a monday.com workspace hierarchy: workspaces, folders, board structure (groups/columns), delete/archive for boards+items, and the `mcli skill` command that outputs the LLM skill document.
-
-Monday's hierarchy: Account → Workspace → Folder → Board → Group/Column → Item → Subitem.
-
-## Phase 4.5a: Workspace + Folder commands
-**Status**: completed
-
-### Tasks:
-- [x] **GraphQL queries/mutations**: `workspaces` (list), `create_workspace`, `update_workspace`, `delete_workspace`, `folders` (list), `create_folder`, `update_folder`, `delete_folder`
-- [x] **`mcli workspace list`** `[--kind open|closed|template]`
-- [x] **`mcli workspace get <id>`**
-- [x] **`mcli workspace create`** `--name <name> --kind open|closed [--description <text>]`
-- [x] **`mcli workspace update <id>`** `[--name] [--description] [--kind]`
-- [x] **`mcli workspace delete <id>`**
-- [x] **`mcli folder list`** `[--workspace <id>]`
-- [x] **`mcli folder create`** `--name <name> [--workspace <id>] [--parent <folder-id>]`
-- [x] **`mcli folder rename <id> <name>`**
-- [x] **`mcli folder delete <id>`**
-- [x] Unit tests per command (httptest fixtures)
-- [x] Live smoke test at least workspace list + folder list
-
-### Acceptance Criteria:
-- [x] `AC-4.5a-1`: `mcli workspace list --json` returns workspaces with id/name/kind
-- [x] `AC-4.5a-2`: `mcli workspace create + get + update + delete` round-trip works
-- [x] `AC-4.5a-3`: `mcli folder list --workspace <id> --json` returns folders
-- [x] `AC-4.5a-4`: All commands have unit tests; `go test -race` green
-
-## Phase 4.5b: Board delete/rename/archive + group CRUD + column CRUD
-**Status**: completed
-
-### Tasks:
-- [x] **GraphQL mutations**: `delete_board`, `archive_board`, `update_board(name)`, `create_group`, `delete_group`, `archive_group`, `update_group(title)`, `create_column`, `delete_column`, `change_column_title`, `change_column_metadata(description)`
-- [x] **`mcli board rename <id> <name>`**
-- [x] **`mcli board delete <id>`**
-- [x] **`mcli board archive <id>`**
-- [x] **`mcli board group list --board <id>`**
-- [x] **`mcli board group create --board <id> --name <name> [--color <hex>]`**
-- [x] **`mcli board group delete --board <id> --group <id>`**
-- [x] **`mcli board group archive --board <id> --group <id>`**
-- [x] **`mcli board group rename --board <id> --group <id> --name <name>`**
-- [x] **`mcli board column list --board <id>`**
-- [x] **`mcli board column create --board <id> --title <title> --type <type> [--defaults <json>]`**
-- [x] **`mcli board column delete --board <id> --column <id>`**
-- [x] **`mcli board column rename --board <id> --column <id> --title <title>`**
-- [x] **`mcli board column describe --board <id> --column <id> --text <description>`**
-- [x] Unit tests per command
-- [x] Live smoke: create group, rename, archive; create column, rename, set description, delete
-
-### Acceptance Criteria:
-- [x] `AC-4.5b-1`: `mcli board delete` returns deleted board id+name; board no longer appears in list
-- [x] `AC-4.5b-2`: Group CRUD round-trip: create → list → rename → archive
-- [x] `AC-4.5b-3`: Column CRUD round-trip: create → list → rename → describe → delete
-- [x] `AC-4.5b-4`: `board group list` and `board column list` return targeted subsets (not full board-get payload)
-- [x] `AC-4.5b-5`: All commands unit-tested; `go test -race` green
-
-## Phase 4.5c: Item delete/archive + `mcli skill`
-**Status**: completed
-
-### Tasks:
-- [x] **GraphQL mutations**: `delete_item`, `archive_item`
-- [x] **`mcli item delete <id>`**
-- [x] **`mcli item archive <id>`**
-- [x] **`mcli skill`** (alias: `mcli describe`) — generates and outputs the full LLM skill Markdown document describing all commands, their flags, output shapes, error codes, and primary-use-case workflows
-- [x] Skill doc content: command reference table, JSON output schemas, workflow examples (create board → add columns → add items → update status), error handling patterns
-- [x] CI check: `mcli skill` output is deterministic (regenerate + diff = no change)
-- [x] Unit tests for delete/archive commands
-
-### Acceptance Criteria:
-- [x] `AC-4.5c-1`: `mcli item delete <id> --json` returns `{"id":"...", "name":"..."}` of deleted item
-- [x] `AC-4.5c-2`: `mcli item archive <id> --json` returns archived item; item state becomes archived
-- [x] `AC-4.5c-3`: `mcli skill` outputs valid Markdown with all registered commands
-- [x] `AC-4.5c-4`: `mcli describe` is an alias that produces identical output to `mcli skill`
-- [x] `AC-4.5c-5`: CI drift check passes (skill doc regeneration produces no diff)
-
-## Design Notes
-
-- **Destructive ops (delete)**: Per axiom A12, no interactive confirmation. Return deleted resource's id+name in response so LLM can verify.
-- **Archive vs Delete**: Both exposed. Archive = soft-delete (recoverable). Help text should guide LLMs to prefer archive.
-- **Column types**: `create_column --type` validates against the ColumnType enum. Help text lists valid types.
-- **Column defaults**: JSON-passthrough pattern (same as `--col` on item write). The `defaults` field is type-specific config.
-- **`mcli skill`**: Self-describing output per axiom A2. This is the single artifact an LLM loads to learn the full CLI. Must stay in sync with actual commands — generated, not hand-written.
-- **Workspace update**: Single command with optional flags rather than separate rename/describe commands — fewer commands for the LLM to learn, one API call covers multiple changes.
diff --git a/memory-bank/docs/plan-phase5.md b/memory-bank/docs/plan-phase5.md
deleted file mode 100644
index 862dd67..0000000
--- a/memory-bank/docs/plan-phase5.md
+++ /dev/null
@@ -1,179 +0,0 @@
-# Phase 5: Search, Docs, Output Modes & Wrapper Promotion
-
-## Overview
-
-Promote high-value features from the Deno wrapper into the Go core binary, and add a token-efficient output mode for LLM consumers. After implementation, update the README and `skill` doc to reflect new commands.
-
-## Context
-
-The Deno wrapper (`mcli` shim) adds search, doc read/write, item description, item updates read, and item find on top of the Go binary (`_mcli`). These are the primary discovery and read-path commands for LLM-driven workflows. Promoting them eliminates the Deno runtime dependency and reduces latency.
-
-The output system today has two modes: `ModeJSON` (non-TTY default) and `ModePretty` (TTY). LLM consumers pay per-token, so a `terse` mode (minimal formatting, no padding) and `csv` mode are needed.
-
-## Phase 5a: Output Mode Infrastructure
-**Status**: completed
-
-**Goal**: Add `terse` and `csv` output modes with persistent config default.
-
-### Tasks:
-- [x] Add `output_mode` field to `Config` struct
-- [x] Add `mcli config` command: `mcli config set output-mode <mode>` / `mcli config get output-mode`
-- [x] Extend `OutputMode` enum: `ModeJSON`, `ModePretty`, `ModeTerse`, `ModeCSV`
-- [x] Add `--terse` and `--csv` global flags to `rootCmd`
-- [x] Update `resolveOutputMode` precedence: `--json` > `--csv` > `--terse` > `--pretty` > config default > TTY-detect
-- [x] Add terse formatters to existing commands: `board list`, `board get`, `item list`, `item get`, `me`
-- [x] Terse format spec: one line per entity, pipe or tab-separated key fields, no alignment padding
-- [x] CSV format: standard RFC 4180, headers on first line
-- [x] Unit tests for resolveOutputMode with all flag/config combinations
-
-### Acceptance Criteria:
-- [x] `AC-5a-1`: `mcli config set output-mode terse` persists; subsequent commands default to terse
-- [x] `AC-5a-2`: `--json`, `--csv`, `--terse`, `--pretty` flags override config
-- [x] `AC-5a-3`: Existing JSON/pretty behavior unchanged when no config set
-- [x] `AC-5a-4`: Terse output for `item list` is ≤50% the token count of pretty output
-
-## Phase 5b: Search Command
-**Status**: pending
-
-**Goal**: `mcli search <query> [-t boards|items|docs] [--limit N]`
-
-### Tasks:
-- [ ] Add `search.graphql` using monday's `search { boards(query:...) { results { ... } } items(...) docs(...) }` API
-- [ ] Run genqlient codegen
-- [ ] Implement `internal/cli/search.go` with all four output modes
-- [ ] JSON: `{"boards":[...],"items":[...],"docs":[...]}`
-- [ ] Pretty: grouped sections with aligned columns
-- [ ] Terse: `board:12345:Board Name` / `item:67890:Item Name:board=12345` / `doc:111:Doc Name`
-- [ ] CSV: type,id,name,context columns
-- [ ] Register `newSearchCmd()` under `rootCmd` in `root.go`
-- [ ] Unit tests with httptest fixtures
-
-### Acceptance Criteria:
-- [ ] `AC-5b-1`: `mcli search "foo" --json` returns boards/items/docs matching query
-- [ ] `AC-5b-2`: `mcli search "foo" -t items` restricts to items only
-- [ ] `AC-5b-3`: `mcli search "foo" --terse` produces one-line-per-result format
-
-## Phase 5c: Item Find (server-side column filter)
-**Status**: pending
-
-**Goal**: `mcli item find --board <id> --column <col_id> --value <text>`
-
-### Tasks:
-- [ ] Add `ItemFind` GraphQL query: `boards(ids:[$boardId]) { items_page(query_params: {rules: [{column_id:$colId, compare_value:[$value], operator:contains_text}]}) { items { id name group { id title } } } }`
-- [ ] Implement `internal/cli/item_find.go`
-- [ ] People-column resolution: when column type is `people`, resolve name/email to compare_value via user lookup (depends on 5f)
-- [ ] All four output modes
-- [ ] Unit tests
-
-### Acceptance Criteria:
-- [ ] `AC-5c-1`: `mcli item find --board 123 --column status --value Done` returns matching items
-- [ ] `AC-5c-2`: People-column lookup by email resolves correctly
-- [ ] `AC-5c-3`: JSON output includes item id, name, group
-
-## Phase 5d: Item Updates (read)
-**Status**: pending
-
-**Goal**: `mcli item updates <id> [--limit N]`
-
-### Tasks:
-- [ ] Add `ItemUpdates` GraphQL query: `items(ids:[$id]) { updates(limit:$limit) { id text_body created_at creator { id name } replies { id text_body created_at creator { id name } } } }`
-- [ ] Implement as `newItemUpdatesCmd()` subcommand under `mcli item`
-- [ ] Pretty: threaded display with creator + timestamp
-- [ ] Terse: `update_id|creator_name|timestamp|first_line_of_body` per update
-- [ ] JSON: full update objects
-- [ ] CSV: id,creator,created_at,text_body
-- [ ] Unit tests
-
-### Acceptance Criteria:
-- [ ] `AC-5d-1`: `mcli item updates 12345 --json` returns updates with replies
-- [ ] `AC-5d-2`: `--limit 5` restricts result count
-- [ ] `AC-5d-3`: Terse output is one line per update (replies indented or appended)
-
-## Phase 5e: Item Description + Doc Read/Write
-**Status**: pending
-
-**Goal**: `mcli item description <id> [--set <md> | --set-file <path>]` and `mcli doc <id> [--set <md> | --set-file <path>]`
-
-### Tasks:
-- [ ] Add GraphQL operations:
-  - `export_markdown_from_doc(docId: $id)` for reading
-  - `set_item_description_content(item_id: $id, markdown: $md)` for writing item descriptions
-  - `add_content_to_doc_from_markdown(docId: $id, markdown: $md)` for writing docs
-  - `delete_doc_blocks(block_ids: $ids)` for clearing doc before rewrite
-  - `docs(ids: [$id]) { id blocks { id type content } }` for resolving doc structure
-- [ ] Implement `internal/cli/item_description.go`:
-  - Read: fetch column_values → find DirectDocValue → extract objectId → export_markdown_from_doc
-  - Write: call set_item_description_content with markdown
-- [ ] Implement `internal/cli/doc.go`:
-  - Read: resolve doc (by id or object_id) → export_markdown_from_doc
-  - Write: resolve doc → delete existing blocks → add_content_to_doc_from_markdown
-  - Flags: `--set <markdown_string>` or `--set-file <path>` (read file contents)
-- [ ] Output: read returns raw markdown (all modes); write returns confirmation
-- [ ] Unit tests
-
-### Acceptance Criteria:
-- [ ] `AC-5e-1`: `mcli item description 12345` outputs markdown content
-- [ ] `AC-5e-2`: `mcli item description 12345 --set "# Hello"` updates the description
-- [ ] `AC-5e-3`: `mcli doc 999` outputs markdown; `mcli doc 999 --set-file ./content.md` updates it
-- [ ] `AC-5e-4`: Doc pagination works (>200 blocks fetched correctly)
-
-## Phase 5f: Enhance `me` + User Resolution
-**Status**: pending
-
-**Goal**: Richer `me` output; reusable user lookup for `item find`.
-
-### Tasks:
-- [ ] Expand `Me` GraphQL query: add `email`, `account { id name }`, `teams { id name }`
-- [ ] Add `MeExtended` query (or expand existing) to fetch `favorites { object { id type } }` and `boards(limit:10, order_by:used_at) { id name workspace { id name } }`
-- [ ] Add `internal/api/users/resolve.go`: `ResolveByEmail(email) → id` and `ResolveByName(name) → id` using `users(emails:...)` / `users(name:...)` API
-- [ ] Update `me` formatters:
-  - Pretty: teams, favorites, recent boards (tabular)
-  - Terse: `@id name <email> | teams: t1,t2 | recent: ^bid1,^bid2`
-  - JSON: full object
-- [ ] Unit tests for user resolution + me output
-
-### Acceptance Criteria:
-- [ ] `AC-5f-1`: `mcli me --json` includes email, account, teams
-- [ ] `AC-5f-2`: `mcli me` (pretty) shows recent boards and favorites
-- [ ] `AC-5f-3`: User resolution by email works for item find people columns
-
-## Phase 5g: README + Skill Doc Update
-**Status**: pending
-
-**Goal**: Update README.md and `skill` command output to document all new commands and output modes.
-
-### Tasks:
-- [ ] Update README.md:
-  - Add search command to feature list
-  - Add doc read/write commands
-  - Add item description, item updates, item find
-  - Document output modes (--json, --terse, --csv, --pretty) and config
-  - Update installation/usage sections if needed
-- [ ] Update `skillDoc` constant in `internal/cli/skill.go`:
-  - Add search section
-  - Add doc management section
-  - Add item description and item updates sections
-  - Add item find section
-  - Document output mode config
-- [ ] Verify `mcli skill` output renders correctly
-
-### Acceptance Criteria:
-- [ ] `AC-5g-1`: README documents all new commands with usage examples
-- [ ] `AC-5g-2`: `mcli skill` output includes search, doc, description, updates, find
-- [ ] `AC-5g-3`: Output modes section explains terse format for LLM consumers
-
-## Dependencies
-
-```
-5a (output infra) ──→ 5b, 5c, 5d, 5e, 5f (all consume output modes)
-5f (user resolve) ──→ 5c (item find needs people-column resolution)
-5b, 5d, 5e can proceed in parallel once 5a lands
-5g (docs) ──→ all other phases complete
-```
-
-## Out of Scope (remain in Deno wrapper)
-
-- DuckDB caching layer (consider SQLite in a future phase)
-- Rich board grid formatter (complex layout logic, still iterating)
-- `setup-token` interactive wizard (already covered by `mcli auth login`)
-- `ensure-label` (niche, rarely called)
diff --git a/schema/embed.go b/schema/embed.go
index 7870b05..9f99fac 100644
--- a/schema/embed.go
+++ b/schema/embed.go
@@ -1,7 +1,31 @@
 // Package schema exposes the monday.com GraphQL SDL as an embedded string.
 package schema
 
-import _ "embed"
+import (
+	_ "embed"
+	"strings"
+	"time"
+)
 
 //go:embed monday.graphql
 var SDL string
+
+// fetchedAtRaw is the date the embedded SDL was introspected, in YYYY-MM-DD form.
+// It is rewritten by `make schema` (see tools/introspect).
+//
+//go:embed fetched_at.txt
+var fetchedAtRaw string
+
+// fetchedAtLayout is the date format stored in fetched_at.txt.
+const fetchedAtLayout = "2006-01-02"
+
+// FetchedAt reports the date the embedded SDL was introspected from the monday
+// API. It returns the zero Time if the recorded date is missing or unparseable,
+// so callers must check IsZero before treating the value as an age.
+func FetchedAt() time.Time {
+	t, err := time.Parse(fetchedAtLayout, strings.TrimSpace(fetchedAtRaw))
+	if err != nil {
+		return time.Time{}
+	}
+	return t
+}
diff --git a/schema/fetched_at.txt b/schema/fetched_at.txt
new file mode 100644
index 0000000..14cb8d4
--- /dev/null
+++ b/schema/fetched_at.txt
@@ -0,0 +1 @@
+2026-06-17
diff --git a/tools/introspect/main.go b/tools/introspect/main.go
index e8e776d..978a553 100644
--- a/tools/introspect/main.go
+++ b/tools/introspect/main.go
@@ -24,9 +24,10 @@ import (
 )
 
 const (
-	endpoint    = "https://api.monday.com/v2"
-	outFile     = "schema/monday.graphql"
-	httpTimeout = 60 * time.Second
+	endpoint      = "https://api.monday.com/v2"
+	outFile       = "schema/monday.graphql"
+	fetchedAtFile = "schema/fetched_at.txt"
+	httpTimeout   = 60 * time.Second
 )
 
 func main() {
@@ -62,7 +63,14 @@ func run(ctx context.Context) error {
 		return fmt.Errorf("write %s: %w", outPath, err)
 	}
 
+	// Record when this SDL was fetched so the CLI can warn when the embedded
+	// schema has gone stale (see schema.FetchedAt).
+	fetchedAt := time.Now().UTC().Format("2006-01-02") + "\n"
+	if err := os.WriteFile(fetchedAtFile, []byte(fetchedAt), 0o644); err != nil {
+		return fmt.Errorf("write %s: %w", fetchedAtFile, err)
+	}
+
 	lines := strings.Count(sdl, "\n")
-	fmt.Fprintf(os.Stderr, "introspect: wrote %s (%d lines)\n", outPath, lines)
+	fmt.Fprintf(os.Stderr, "introspect: wrote %s (%d lines), %s\n", outPath, lines, fetchedAtFile)
 	return nil
 }