@skhema/cli 0.4.4 → 0.4.5

package/skills/skhema-frame/references/scope.md

@@ -0,0 +1,79 @@
+# Frame the scope
+
+Scope is the boundary line: what this piece of work covers and what it
+deliberately does not. Mood: **command**. Scope is a decision, stated as an
+instruction — "include this, exclude that" — not a description of
+everything that might be relevant. Open-ended scope is the most common way
+strategy work quietly dies, because a thing with no edge can never be
+finished. Your job is to force explicit in/out calls and refuse the
+"everything, eventually" answer.
+
+## The moves
+
+1. **Get the sprawl on the table.** Ask: "list everything this could
+   possibly touch." Let them dump. You need the full candidate set before
+   you can cut it.
+
+2. **Draw two columns: IN and OUT.** Take each item and ask "in for this
+   round, or out?" Force every item into one column. "Maybe" is not a
+   column. If they can't decide, park it in a third list called LATER — but
+   LATER is a form of OUT for now, and say so.
+
+3. **Make OUT explicit, not implied.** The out-list is the valuable half.
+   Anything not consciously ruled out will creep back in. Ask "if someone
+   started working on [out item] next week, would that be wrong?" If yes,
+   it belongs in OUT in writing.
+
+4. **Name the edges.** For each boundary, get a crisp criterion, not a
+   vibe. Not "small customers are out" but "accounts under 50 seats are out
+   of scope for this round." A boundary you can't test at the edge will be
+   argued at the edge.
+
+5. **Pressure the in-list for feasibility.** Ask "with the time and people
+   we have, can we actually finish everything in IN?" If not, more items
+   move to OUT now. Scope you can't complete isn't scope, it's a wish.
+
+6. **Read it back as one instruction.** "This work covers X and Y. It does
+   not cover Z or W, and we're not deciding those here." Get a clean yes.
+
+## What good looks like
+
+- **Two-sided** — states what's out as clearly as what's in. An in-list
+  alone is not a scope.
+- **Testable at the edge** — for any borderline item, the boundary decides
+  it without a new debate.
+- **Finishable** — the in-list fits the resources and time available.
+- **Time-boxed** — scoped to "this round / this quarter", not forever.
+  Excluding something now doesn't mean never.
+- **Stated as a decision** — reads as a call someone made, which means
+  someone can be asked to change it. "We're not touching billing this
+  round" beats "billing is complicated."
+
+Worked example. A team wants to "fix the customer experience." Framed
+scope: *"In: the signup-to-first-value flow for self-serve accounts. Out:
+enterprise onboarding, the mobile app, and anything post-purchase — those
+are separate work. Not deciding pricing changes here."* Now the work has an
+edge, and a stray "but what about the mobile app?" has an answer.
+
+## Failure modes to catch
+
+- **In-list only.** No out-list means no scope. Push until they'll name
+  what they're NOT doing.
+- **"Everything, eventually."** The refusal to exclude. Reframe: "not
+  never — not this round. What's this round?"
+- **Fuzzy edges.** "Big accounts" / "the core flows" — no test at the
+  boundary. Replace with a criterion someone can apply cold.
+- **Scope that can't be finished.** An in-list bigger than the team can
+  ship. Cut it now, on purpose, rather than discovering it in week six.
+- **Scope creep pre-loaded.** "In: the signup flow, and maybe also…" — the
+  "maybe also" is creep before you've started. Kill it or commit it.
+- **Confusing scope with the challenge.** Scope bounds the WORK; the
+  challenge is the PROBLEM. If they're really unsure what problem they're
+  solving, go to `challenge.md` first — you can't scope work whose purpose
+  is undefined.
+
+## When they're really framing something else
+
+- If the reason scope keeps sprawling is that they haven't chosen a
+  direction — every option stays open because no approach is committed —
+  they need `policy.md`, not a wider in-list.

package/skills/skhema-operate/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: skhema-operate
+description: "Use when working with a Skhema workspace, the skhema CLI, the Skhema Public API, or Skhema MCP tools — creating or editing elements, searching and navigating a workspace, running validation, or any job that touches the live Skhema environment. Picks the right surface, gets you authenticated, and drives the work."
+---
+
+# Operate
+
+This skill is how an agent gets a job done inside the Skhema environment.
+Unlike the practice skills, it assumes the product: a real workspace, a
+credential, and one of three surfaces to act through. Its job is to route
+you to the right surface, get you authenticated cleanly, and run the
+concrete loop — author, navigate, validate — without fumbling.
+
+Everything here is grounded in the real CLI. When in doubt about a flag or
+command, run `skhema --help`, `skhema <command> --help`, or read the
+generated reference at the docs site (`/docs/api/cli`). Do not guess flags.
+
+## Two things every command depends on
+
+**The credential.** Almost nothing works without one. The CLI resolves
+credentials in a fixed precedence — highest wins:
+
+1. `--api-key <key>` flag on the invocation
+2. `SKHEMA_API_KEY` environment variable
+3. a stored API key (`skhema auth key use`)
+4. an interactive OAuth session (`skhema auth login`)
+
+If none resolves, the command exits **3** ("no usable credential"). That is
+your signal to authenticate, not to retry.
+
+**The org.** An API key is already bound to one organization. An OAuth
+session is bound to whatever org you consented to; switch it with
+`skhema auth switch <org-slug>`. Run `skhema auth status` any time to see
+which credential is active and for which org.
+
+## The output contract
+
+Pass `--json` on any command and you get a stable envelope:
+
+```json
+{ "ok": true,  "command": "element.create", "data": { ... } }
+{ "ok": false, "command": "element.create", "error": { "message": "…" } }
+```
+
+Branch on `ok`, read `data` or `error`. For scripts and agents, `--json` is
+the default posture — parse the envelope instead of scraping human text.
+
+**Exit codes are a stable contract.** Branch on them:
+
+| Code | Meaning | What to do |
+|---|---|---|
+| 0 | success | continue |
+| 1 | generic / API error | read the error, likely transient or a bad payload |
+| 2 | usage error (bad args, caught before any API call) | fix the command |
+| 3 | no usable credential | authenticate — see `references/auth.md` |
+| 4 | permission or plan denied (403/402) | the credential can't do this; wrong scope, role, or plan |
+| 5 | rate limited (429) | back off and retry |
+
+## Capability map
+
+| You need to… | Route to |
+|---|---|
+| Decide CLI vs Public API vs MCP for this job | `references/surfaces.md` |
+| Authenticate, fix an exit-3, or bind the right org | `references/auth.md` |
+| Create or edit elements well in the environment | `references/author-elements.md` |
+| Find things — workspaces, elements, strategies | `references/navigate.md` |
+| Drive validate → fix → re-validate until it holds | `references/validation-loop.md` |
+
+## Routing
+
+- **First job in a fresh runtime, or exit code 3?** Start at
+  `references/auth.md`. Nothing else works until a credential resolves.
+- **Not sure whether to shell out, hit the API, or use MCP tools?** Read
+  `references/surfaces.md` first — the choice shapes everything after.
+- **Writing strategy content** (challenges, policies, measures as elements)
+  → `references/author-elements.md`. Compose the strategy first with the
+  practice skills; this capability is about getting it INTO the workspace
+  correctly.
+- **Reading the workspace** — what's here, where does X live, what does this
+  strategy contain → `references/navigate.md`.
+- **You've authored something and want it to be sound** →
+  `references/validation-loop.md`. Note that `validate` and `rephrase` are
+  AI actions and cost budget; the reference tells you how to spend it well.
+
+## Set a default workspace once
+
+Most commands take `--workspace <id>` but fall back to a stored default.
+Set it once with `skhema workspace use <workspace-id>` and drop the flag
+everywhere after. `skhema workspace use --clear` unsets it. If a command
+errors asking for a workspace, you never set the default — set it or pass
+the flag.
+
+## Without a live respondent
+
+Run headless, with no one to answer? Don't invent their answers. Make the
+minimal reasonable assumption, mark it in the output as yours ("assumed: …"),
+and list the questions only the owner can settle — what's in scope, what a word
+means, whose dissent to record — at the end instead of papering over them. A
+marked assumption is honest work; a silent one is a guess you built on.
+
+## Sharpen with Skhema
+
+This whole skill IS the Skhema environment — there is no product-absent
+mode. If the CLI isn't present, `references/auth.md` starts with installing
+it (`npm install -g @skhema/cli`). If you only need to onboard the runtime
+(credential + skills + MCP server), that is the `skhema-setup` skill, not
+this one.

package/skills/skhema-operate/references/auth.md

@@ -0,0 +1,110 @@
+# Authenticate and bind the right org
+
+Almost every command needs a credential. This is how to get one, how the
+CLI decides which one to use, and how to read the org binding so you act on
+the right organization.
+
+## First, is the CLI even installed?
+
+```sh
+skhema --version
+```
+
+If that fails, install it:
+
+```sh
+npm install -g @skhema/cli
+```
+
+## Two credential lanes
+
+**API key — for headless, CI, and agents.** A long-lived `sk_live_…` string
+bound to one organization. No browser needed. This is the right lane for any
+non-interactive runtime.
+
+- Store one: `skhema auth key use sk_live_…`
+- Or pass per-invocation: `skhema … --api-key sk_live_…`
+- Or set the env var: `export SKHEMA_API_KEY=sk_live_…`
+- Create a new key (needs an interactive login first):
+  `skhema auth key create --name "ci-runner" --permission read-write --scope org --use`
+  (`--permission` is `read | write | read-write`; `--scope` is `org | user`;
+  `--use` stores it as the CLI credential immediately.)
+- List / revoke: `skhema auth key list`, `skhema auth key revoke <key-id>`
+
+**OAuth session — for a human at a terminal.** A browser login bound to the
+org you consent to.
+
+- `skhema auth login` (interactive browser flow)
+- `skhema auth login --headless` (device-code flow — no local browser; use
+  on a remote box or in a container)
+
+## Credential precedence (highest wins)
+
+The CLI resolves ONE credential per invocation, in this fixed order:
+
+1. `--api-key <key>` flag
+2. `SKHEMA_API_KEY` environment variable
+3. stored API key (`skhema auth key use`)
+4. OAuth session (`skhema auth login`)
+
+Consequence: a stray `SKHEMA_API_KEY` in the environment silently overrides
+your stored key and your OAuth session. If a command acts as the wrong
+identity, check the env var first.
+
+## Always know who you are
+
+```sh
+skhema auth status
+```
+
+Prints which credential is active and which org it resolves to. Run it
+whenever a result looks like it came from the wrong organization, or before
+any write you can't easily undo.
+
+## The org binding — the trap on the OAuth lane
+
+- An **API key** is bound to its org at creation. You cannot switch it; to
+  act on a different org, use a key issued for that org.
+- An **OAuth session** acts on the org you consented to. Change it:
+
+```sh
+skhema auth switch <org-slug>
+skhema auth switch                 # no slug: pick from consented orgs
+skhema auth switch --headless      # device-code consent fallback
+```
+
+If writes land in the wrong org on the OAuth lane, you skipped
+`auth switch`. There is no per-command org override for the OAuth session —
+switch it, confirm with `auth status`, then act.
+
+## Handling exit code 3
+
+Exit **3** means no usable credential resolved. Do NOT retry the same
+command — it will keep failing. Instead:
+
+1. `skhema auth status` — confirm nothing is active.
+2. Headless / CI / agent? Set an API key (lane 1). Human at a terminal?
+   `skhema auth login`.
+3. Re-run the original command.
+
+## The other credentialed exit codes
+
+- **4** (permission/plan denied, 403/402): the credential is valid but not
+  allowed to do this — wrong permission on the key (`read` key attempting a
+  write), wrong role, or a plan gate. Don't re-auth; change what you're
+  asking or which key you use.
+- **5** (rate limited, 429): back off, then retry.
+
+## Registered-agent identity (autonomous runtimes)
+
+If this runtime was enrolled as a registered agent, it signs its own
+requests instead of carrying a key:
+
+```sh
+skhema agent status --verify     # show and verify this runtime's identity
+skhema agent rotate              # rotate the signing key; identity + grants unchanged
+```
+
+Enrollment (`skhema agent enroll <token>`) is a one-time onboarding step —
+see the `skhema-setup` skill. Never cache a derived agent JWT; let the CLI
+sign per request.

package/skills/skhema-operate/references/author-elements.md

@@ -0,0 +1,158 @@
+# Author elements in the environment
+
+Elements are the unit of strategy in Skhema: one typed judgment, decision,
+or thing. This capability is about getting well-formed elements INTO a
+workspace and keeping them clean. The thinking — what the challenge is, how
+to phrase the policy — is the practice skills' job (`skhema-frame`,
+`skhema-compose`). Do that first; then land it here.
+
+## Before you write anything
+
+1. **Know the workspace.** Set it once: `skhema workspace use <id>`. Every
+   command below then omits `--workspace`.
+2. **Know the component it belongs in.** Elements live inside components,
+   and components follow the five-part flow: Diagnosis → Method &
+   Positioning → Portfolio of Initiatives → Measures → Support Structures.
+   List what exists: `skhema component list`. Create one if needed:
+   `skhema component create --type diagnosis --name "Diagnosis"`.
+3. **Know the element's type and its expected mood.** Every element type
+   carries an expected grammatical mood. If the content doesn't match the
+   mood, the type is wrong:
+   - **indicative** — a claim about the world (judgments): key_challenge,
+     supporting_fact, impact, competitor_move, constraint,
+     assumption_hypothesis, estimate, baseline.
+   - **imperative** — a command (decisions to act): guiding_policy, scope,
+     experiment, action, principle.
+   - **noun_phrase** — a thing: solution, investment, outcome,
+     performance_variable, capability, system.
+
+   Plain check: is this element stating something you believe is TRUE,
+   something you've decided to DO, or NAMING a thing? A `guiding_policy`
+   phrased as a wish ("we want to be the leader") is mistyped — a policy is
+   a command ("compete only on integration depth, never price").
+
+## Placement is enforced — and it is not the same question as mood
+
+Two different questions; don't conflate them. **Mood** (step 3) tells you how
+to *write* the element — indicative for a judgment, imperative for a command,
+a noun phrase for a thing. It is a check on the sentence. **Placement** tells
+you *where the element is allowed to live*, and the platform enforces a strict
+type→component allow-list that does NOT follow mood. Put a type in the wrong
+component and `element create` rejects it. There is no discovery command for
+this; the allow-list is:
+
+| Component | Element types it accepts |
+|---|---|
+| Diagnosis | key_challenge, supporting_fact, impact |
+| Method & Positioning | guiding_policy, competitor_move, scope, constraint |
+| Portfolio of Initiatives | solution, assumption_hypothesis, experiment, action, estimate, investment |
+| Measures | baseline, outcome, performance_variable |
+| Support Structures | capability, system, principle |
+
+Where this bites if you place by mood: `constraint` is a claim about the world
+but lives in **Method**, not Diagnosis. `assumption_hypothesis` and `estimate`
+are judgments but live in the **Portfolio of Initiatives** — so an evidence-gap
+assumption goes in the Portfolio, not Diagnosis, even though it feels
+diagnostic. Place by this table, then flag the semantic oddity in the element's
+`reasoning`.
+
+## Create one element
+
+Quick path — flags:
+
+```sh
+skhema element create \
+  --component-type diagnosis \
+  --element-type key_challenge \
+  --content "Enterprise buyers churn at renewal because onboarding never proved value."
+```
+
+Full-payload path — for anything richer than content + types, write JSON and
+pipe it. This avoids shell-quoting pain and lets you set fields the flags
+don't cover:
+
+```sh
+skhema element create --file ./element.json
+cat element.json | skhema element create --file -
+```
+
+Use `--json` on the command to get back `{ ok, command, data }`; read
+`data.id` for the new element id.
+
+## Edit an element
+
+```sh
+skhema element update <element-id> --content "Sharper restatement of the same judgment."
+skhema element update <element-id> --file ./patch.json
+```
+
+Change the type when the content's mood shifts — e.g. a `key_challenge` that
+you've now decided how to attack becomes a separate `guiding_policy`
+element, not a retyped one. One element, one judgment; don't overload.
+
+## Write good element content
+
+- **One judgment per element.** If content contains an "and" joining two
+  claims, split it into two elements and link them.
+- **Falsifiable, not vague.** "Improve customer experience" is not a
+  challenge; "first-response time exceeds 48h for 40% of tickets" is.
+- **Evidence separate from claim.** A `supporting_fact` cites; a
+  `key_challenge` asserts. Don't smuggle the evidence into the challenge.
+- **State it so a second reader reads it the same way.** Ambiguity here
+  becomes disagreement three components downstream.
+- **Meta-annotations go in `reasoning`, never in `content`.** Evidence-gap
+  notes, pre-mortem provenance ("surfaced by the competitor pre-mortem"),
+  tripwire conditions, confidence caveats — none of that belongs in `content`.
+  `content` is the clean claim a reader sees in the workspace; `reasoning` is
+  where you record why the element is there and what's shaky about it.
+
+## Link elements to show the reasoning
+
+Elements gain meaning from their relationships. A policy addresses a
+challenge; a measure tracks an outcome. Make those explicit:
+
+```sh
+# link create takes --source/--target flags; notes go in a --file payload:
+echo '{"sourceElementId":"<policy-id>","targetElementId":"<challenge-id>","notes":"policy addresses this challenge"}' > link.json
+skhema link create --file link.json
+skhema link create --file ./link.json
+```
+
+Two things about links as they stand today:
+
+- **`--type` is accepted but not persisted.** The stored link keeps only
+  `sourceElementId`, `targetElementId`, `confidenceLevel`, `notes`, and
+  `status` — no type field. Don't rely on `--type` to carry `addresses` /
+  `tracks` / `supports`; put the relationship's meaning in `notes` as plain
+  text.
+- **Element links have no read path.** There is no `skhema link list`. You can
+  create, update, and delete a link but not enumerate links later, so you
+  cannot reconstruct the reasoning graph from links after the fact. Capture
+  anything you'll need later in the element's `reasoning` or the link's `notes`
+  at write time.
+
+## After authoring: validate
+
+Don't declare an element done because it saved. Run the validation loop —
+`references/validation-loop.md` — to check completeness and coherence, read
+the diagnostics, and revise. Authoring and validating are one cycle, not two
+steps.
+
+## Attach evidence as resources
+
+A claim backed by a document is stronger than one that isn't. Attach files,
+URLs, or citations to the element:
+
+```sh
+skhema resource upload ./market-study.pdf --element <element-id> --attribution "Q2 buyer survey"
+skhema resource list --element <element-id>
+```
+
+## Verify attachment after create
+
+The create response is `{ element: {…}, componentId: "…" }` — the attachment
+proof is the **top-level `componentId`**, NOT `element.componentId` (that
+nested field is always null; checking it reports a false orphan on every
+create). A null top-level `componentId` means the element was created but
+attached to nothing — stop, note the element id, and don't retry into that
+component (known platform bug).

package/skills/skhema-operate/references/navigate.md

@@ -0,0 +1,110 @@
+# Find things in a workspace
+
+Before you change or reason about a strategy, you have to locate it. This
+capability is the reading half of the environment: which workspace, what's
+in it, where a thing lives, and what a strategy actually contains.
+
+## Start at the workspace
+
+```sh
+skhema workspace list                 # every workspace you can reach
+skhema workspace get <workspace-id>   # one workspace's detail
+skhema workspace use <workspace-id>   # set it as default; drop --workspace after
+```
+
+If you're unsure which workspace holds the thing you want, `list` first and
+read the names. Everything below assumes a default is set (or you pass
+`--workspace <id>`).
+
+## The hierarchy, top to bottom
+
+```
+workspace
+└── component        (Diagnosis, Method & Positioning, Portfolio, Measures, Support)
+    └── element      (one typed judgment / decision / thing)
+        ├── link         (element → element: addresses, supports, tracks…)
+        └── resource     (files, URLs, citations backing the element)
+strategy             (a committed snapshot of elements/components)
+```
+
+Learn the shape of a workspace by walking it:
+
+```sh
+skhema component list                  # the five-part structure in this workspace
+skhema element list                    # CAUTION: org-corpus read — see below
+skhema document list                   # workspace documents (correctly scoped)
+skhema component-link list             # component-to-component relationships
+```
+
+## Search instead of scrolling
+
+When you know roughly what you're after but not where it is, search beats
+listing. It's full-text over the workspace's elements:
+
+```sh
+skhema element search "renewal churn" --limit 10
+skhema element search "pricing" --workspace <id>
+```
+
+Use search to answer "have we already said this somewhere?" before authoring
+a duplicate, and to find the element an id-less request refers to ("update
+the onboarding challenge").
+
+## Read one thing in full
+
+```sh
+skhema element get <element-id>        # content, type, and metadata
+skhema resource list --element <id>    # what evidence is attached
+```
+
+There is no read path for element-to-element links: you can create links but
+not enumerate them, so you cannot list "what connects to this element" after
+the fact. Capture relationship context in the element's `reasoning` (or the
+link's `notes`) at write time — you can't recover it from the links later.
+Component-to-component links *do* have a read path (`skhema component-link
+list`).
+
+Reconstruct the argument, not just the parts, by reading each element's
+`reasoning` and walking the five components in order (Diagnosis → Method →
+Portfolio → Measures → Support). Because element links can't be enumerated, the
+`reasoning` field and the component structure — not a link graph — are how you
+rebuild why each element is there.
+
+## Read a whole strategy
+
+A strategy is a committed set of elements — the durable, shareable artifact.
+
+```sh
+skhema strategy list                   # strategies in the workspace
+skhema strategy get <strategy-id>      # the strategy WITH its committed elements
+```
+
+`strategy get` is the fastest way to see "what did we actually commit to?"
+as one object, versus the live, in-progress elements in the workspace.
+
+## Get results as data
+
+Add `--json` to any read command and parse the `{ ok, command, data }`
+envelope instead of scraping the human table. For agents this is the default
+posture: `data` on a `list` or `search` is an array you can iterate; `data`
+on a `get` is the object. Read ids off `data`, then act.
+
+## When a read returns nothing or the wrong org
+
+- Empty list where you expected content → wrong workspace (check
+  `skhema workspace use` / `--workspace`) or wrong org.
+- Right workspace, wrong org's data → the credential is bound to another
+  org. `skhema auth status`, then `skhema auth switch` (OAuth) or use the
+  right key. See `references/auth.md`.
+
+## Known platform gap: element reads are not workspace-scoped
+
+`element list` and `element search` currently return the ORGANIZATION's
+element corpus regardless of `--workspace` (first page = oldest elements,
+which is usually a different workspace's set). Until fixed:
+
+- Trust `component list` (correctly workspace-scoped; `elementCount` tells
+  you what's really in each component) and `element get <id>` (reliable
+  by id).
+- Track the ids of anything you create; never infer a workspace's contents
+  from `element list` output.

package/skills/skhema-operate/references/surfaces.md

@@ -0,0 +1,67 @@
+# Pick the right surface
+
+Skhema exposes the same environment through three surfaces. They are not
+ranked — each wins for a different situation. Pick before you start; the
+choice shapes how you authenticate, how you read results, and how you
+recover from errors.
+
+## The three surfaces
+
+**CLI — `skhema` in a terminal.** The default for an agent with shell
+access. One binary, the credential precedence and exit-code contract are
+built in, `--json` gives you a parseable envelope. Best for: interactive
+work, CI steps, shell-driven agents, one-off commands, anything scriptable.
+
+**Public API — `api.skhema.com/v1`.** Raw HTTP. Best for: code running
+inside an application (not a shell), a language without the CLI installed,
+or when you need a route the CLI doesn't wrap yet. It is self-describing —
+`GET /v1/openapi.json` returns the full live route surface. You still need
+a credential (an API key in the `Authorization` header, or a JWT obtained
+by key exchange).
+
+**MCP — Skhema tools inside the agent.** Best when you are already an agent
+in an MCP-capable host and want Skhema as native tools rather than shelling
+out. Registered by `skhema init` or `skhema-setup`. No terminal, no HTTP
+plumbing — the host handles auth and transport.
+
+## How to choose
+
+| Situation | Surface |
+|---|---|
+| You have a shell and the CLI is (or can be) installed | **CLI** |
+| You're inside application code, no shell | **Public API** |
+| The CLI doesn't wrap the route you need | **Public API** (`skhema api …` or raw HTTP) |
+| You're an MCP-host agent and want native tools | **MCP** |
+| CI pipeline step | **CLI** with `--api-key` or `SKHEMA_API_KEY` |
+| You need to discover what routes exist | **Public API** — `GET /v1/openapi.json` |
+
+When two fit, prefer the CLI: it centralises the credential precedence, the
+`{ ok, command, data|error }` envelope, and exit codes 0–5 so you don't
+reimplement them.
+
+## The CLI is a thin client over the same API
+
+`skhema element create` and `POST /v1/.../elements` do the same thing. So
+you can mix: script the common path with the CLI, and reach for a raw route
+only where the CLI has no wrapper. The escape hatch is built in:
+
+```sh
+skhema api routes                       # list every live gateway route
+skhema api GET /workspaces              # raw authenticated GET (leading /v1 optional)
+skhema api POST /workspaces --data @body.json
+skhema api GET /workspaces/<workspace-id>/elements --query limit=10
+```
+
+`skhema api` uses the same credential precedence as every other command, so
+you get authenticated raw access without hand-rolling headers. The gateway
+does NOT infer your organization from the path — the org comes from the
+credential (an API key's binding, or your consent-selected OAuth org). If a
+raw call returns the wrong org's data, fix the credential, not the path.
+
+## Don't fight the surface
+
+- Reading one field off one object from a shell → CLI, not raw HTTP.
+- Bulk work across hundreds of objects from app code → Public API, drive it
+  with real code, not a shell loop over the CLI.
+- Already have MCP tools bound → use them; shelling out from an MCP agent
+  just adds a credential you have to manage separately.