@skhema/cli 0.4.3 → 0.4.5

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

@@ -0,0 +1,92 @@
+# Frame a single decision
+
+Sometimes the whole strategy is stuck behind one fork. Build or buy. This
+segment or that one. Hire now or wait. The person circles it and can't
+move. A decision isn't a mood-typed element the way a challenge or policy
+is — it's the choice you resolve BEFORE you can state the command. Your job
+is to frame the choice cleanly: the real question, the genuine options,
+what evidence would actually settle it, and whether it can be undone. A
+well-framed decision often answers itself.
+
+## The moves
+
+1. **Extract the real question.** People state decisions as a preferred
+   answer ("we should just build it"). Ask "what's the actual question
+   here?" and phrase it as a fork: "Do we build the integration ourselves
+   or buy an off-the-shelf one?" One question, not a bundle. If there are
+   three tangled questions, separate them and frame the one that blocks the
+   others.
+
+2. **Lay out the genuine options.** Ask "what are the real choices — two,
+   maybe three?" Kill fake options (the strawman nobody would pick) and
+   surface hidden ones (the "do nothing / not yet" option is almost always
+   real and almost always omitted). Each option should be one someone could
+   honestly argue for.
+
+3. **Name what would settle it.** For each option, ask "what would have to
+   be true for this to be the right call?" Then: "what evidence would tell
+   us whether it's true — and do we have it, or can we get it cheaply?"
+   This turns a values argument into a question of fact wherever possible.
+   If the deciding evidence is gettable in a day, get it before deciding.
+
+4. **Test reversibility.** Ask "if we pick this and we're wrong, how hard
+   is it to undo?" Sort the decision:
+   - **Reversible (a two-way door):** cheap to unwind. Don't agonise —
+     pick the most likely-right option fast, and treat it as a test. The
+     cost of deliberating exceeds the cost of being wrong.
+   - **Irreversible (a one-way door):** expensive or impossible to unwind.
+     Slow down, gather the settling evidence, widen the options. This is
+     where care pays.
+   Say which kind it is out loud — people routinely agonise over reversible
+   calls and rush irreversible ones.
+
+5. **State the frame back.** "The question is [fork]. The real options are
+   [A, B, do-nothing]. It turns on whether [X] is true, which we could
+   learn by [evidence]. It's [reversible / irreversible], so we should
+   [move fast and test / slow down and verify]." Often, at this point, the
+   answer is obvious and they decide on the spot.
+
+## What good looks like
+
+- **One question, as a fork** — not a bundle, not a pre-loaded answer.
+- **Genuine options** — each defensible; the do-nothing option included;
+  no strawmen.
+- **Evidence-anchored** — names what fact would settle it and whether
+  that fact is obtainable, separating "we disagree on facts" from "we
+  disagree on values."
+- **Reversibility called** — explicitly tagged one-way or two-way, with the
+  matching tempo (fast-and-testable vs slow-and-verified).
+- **Decidable** — after the frame, a reasonable person could make the call,
+  or knows exactly what to go learn first.
+
+Worked example. Stuck on: "we should build our own billing." Framed: *"The
+question is whether we build billing in-house or adopt a provider. Options:
+build, adopt a provider, or stay on the manual process one more quarter. It
+turns on whether our pricing is stable enough that off-the-shelf tiers
+fit — which we'll know from the pricing review already underway. Adopting a
+provider is largely reversible; building is not. So: don't build yet;
+adopt a provider now as the reversible move, and revisit only if the
+pricing review shows we're genuinely non-standard."*
+
+## Failure modes to catch
+
+- **Pre-loaded answer.** "Should we build it (yes)?" Not a decision, a
+  request for agreement. Force the honest fork.
+- **Missing the do-nothing option.** "Wait" / "not yet" is almost always
+  available and often best. Always surface it.
+- **Strawman options.** Two choices where one is obviously absurd. That's a
+  decision already made, dressed as deliberation.
+- **Values fight that's really a facts fight.** They're arguing preferences
+  when a cheap piece of evidence would settle it. Find the fact, get it.
+- **Agonising over a two-way door.** Slow, careful process on a decision
+  that's trivial to reverse. Name it reversible and move.
+- **Rushing a one-way door.** Fast call on something they can't undo. Name
+  it irreversible and slow down.
+
+## When they're really framing something else
+
+- If resolving this one fork wouldn't actually unblock them — there are
+  really many entangled choices — they may need `challenge.md` to reframe
+  the problem, or `scope.md` to bound what's even being decided this round.
+- Once decided, an irreversible directional choice usually becomes a
+  `policy.md`; capture it there so it guides what follows.

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

@@ -0,0 +1,82 @@
+# Frame the outcome
+
+An outcome is the state they want to reach — success, named as a thing.
+Mood: **noun phrase**. It's not a verb ("increase retention"), not an
+instruction, not a list of activities. It's the world as it will be when
+they've succeeded, stated so plainly that anyone could later look and say
+"yes, that happened" or "no, it didn't." Your job is to turn a fuzzy
+aspiration into something observable, attributable, and time-bound — and to
+keep it distinct from the measures that will track it.
+
+## The moves
+
+1. **Ask for the finished world, not the effort.** "When this has worked,
+   what's true that isn't true today?" If they answer with activities ("we'll
+   have shipped the new onboarding, run the campaign…"), stop them: those
+   are the work, not the outcome. Ask again for the resulting state.
+
+2. **Make it observable.** Ask "how would an outsider know this happened,
+   without you telling them?" Push until the outcome names something you
+   could point at — a behaviour, a rate, a position — not a feeling.
+
+3. **Make it attributable.** Ask "if this happens, will it be because of
+   what we did, or could it happen anyway?" An outcome you can't plausibly
+   claim credit for is a wish about the weather. Tie it to their own action.
+
+4. **Time-box it.** "By when is this true?" No date means no outcome —
+   "eventually" can never succeed or fail. Get a horizon they'll stand
+   behind.
+
+5. **Separate the outcome from its measures.** The outcome is the state
+   ("non-technical teams reach paid on their own"); the measure is the
+   dial you read to check ("self-serve paid-conversion rate"). Name the
+   outcome first, as a noun phrase. If they lead with a metric, ask "and
+   the metric moving would mean WHAT is now true?" — that answer is the
+   outcome. One outcome can have several measures; don't collapse them.
+
+6. **Read it back as a noun phrase.** "A world where [state], by [date],
+   as a result of our work." Confirm they'd recognise it as success and
+   could tell, later, whether it happened.
+
+## What good looks like
+
+- **A state, not an action** — reads as a noun phrase describing how things
+  are, not a verb telling someone what to do.
+- **Observable** — someone outside the room could confirm it happened.
+- **Attributable** — plausibly the result of their strategy, not ambient
+  luck or the market.
+- **Time-bound** — has a horizon by which it's true or it isn't.
+- **Distinct from its measures** — the outcome is the reality; measures are
+  the instruments. Keep them separate so you don't mistake a moving dial
+  for a changed world.
+
+Worked example. Aspiration: "we want better activation." Framed outcome:
+*"Self-serve teams reaching their first paid tier without human help,
+within their first week — the norm rather than the exception, by end of
+Q3."* It's a state (teams reaching paid on their own), observable,
+attributable (it's their onboarding), time-bound (end of Q3). Its measures
+— week-one self-serve conversion rate, support tickets per signup — are
+separate instruments, framed later.
+
+## Failure modes to catch
+
+- **Activity list masquerading as outcome.** "Ship X, launch Y, hire Z."
+  That's the plan. Ask what's TRUE once it's all done.
+- **Verb where a noun belongs.** "Improve retention." An instruction, not a
+  described state. Reframe to the state improved retention produces.
+- **Unobservable.** "Customers love us", "the team is aligned." No outside
+  test. Push to something pointable-at.
+- **Unattributable.** "Revenue grows 20%" — might happen from a market
+  tailwind regardless. Tie it to their move, or narrow it to the part they
+  drive.
+- **No horizon.** "Eventually we're the leader." Can't succeed or fail.
+  Demand a date.
+- **Measure-in-place-of-outcome.** They name a metric and stop. A metric is
+  a proxy; ask what reality it stands for, and frame that.
+
+## When they're really framing something else
+
+- If they can't say what success looks like because they haven't chosen a
+  direction, the missing piece is a `policy.md`, not an outcome.
+- If the "outcome" is really one all-or-nothing choice they're stuck on,
+  it's a `decision.md`.

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

@@ -0,0 +1,82 @@
+# Frame the guiding policy
+
+A guiding policy is the direction they're committing to — the approach that
+will shape every later choice. Mood: **command**. It's an instruction to
+the organisation: "we will go THIS way." The trap is that people restate
+the goal and call it a policy. "Become the market leader" is a goal. "Win
+by being the only option that works out of the box for non-technical teams"
+is a policy — it commits to a road and rules out others. Your job is to
+force a real commitment, not another statement of the destination.
+
+## The moves
+
+1. **Check they have the challenge.** A policy answers a challenge. If they
+   can't state the problem in one sentence, stop and run `challenge.md`
+   first. A direction with no problem is a slogan.
+
+2. **Ask for the approach, not the aim.** "Given that problem, what's your
+   approach to overcoming it?" If the answer names a destination ("get to
+   $10M", "be number one"), push: "that's where you want to end up — how
+   are you going to get there in a way your competitors aren't?"
+
+3. **Force the trade-off.** A real policy rules something out. Ask: "what
+   does this approach mean we WON'T do?" If choosing it costs nothing —
+   rules out nothing, upsets no one — it isn't a policy, it's a platitude.
+   A direction everyone can agree to is a direction that doesn't direct.
+
+4. **Find the leverage.** Ask "why will this work when other approaches
+   wouldn't?" A guiding policy usually names a source of advantage — a
+   strength they have, a weakness in rivals, a change in the market they're
+   riding. Make the "why this beats the alternatives" explicit.
+
+5. **Test it against a real choice.** Take a live decision they face and
+   ask "does this policy tell you which way to go on that?" If the policy
+   doesn't change any actual decision, it isn't guiding anything. Sharpen
+   until it does.
+
+6. **State it as one committed instruction.** "We will [approach], by
+   [source of leverage], which means we won't [ruled-out path]." Get a yes
+   they'd defend to someone who preferred the ruled-out path.
+
+## What good looks like
+
+- **A direction, not a destination** — says how they'll travel, not just
+  where they'll arrive.
+- **Costs something** — rules out a plausible alternative. If nothing was
+  given up, nothing was chosen.
+- **Leverage-bearing** — names why this route wins, not just that it's
+  nice.
+- **Decision-changing** — a person holding this policy makes different calls
+  than a person without it.
+- **Committed** — stated as "we will", owned, defensible against the people
+  who wanted the other road.
+
+Worked example. Challenge: non-technical teams abandon the product at
+setup. Restated-goal trap: "become the easiest tool in the category."
+Framed policy: *"We win by being the only tool a non-technical team can get
+to first value with zero setup and no admin — which means we won't chase
+the power-user features our competitors compete on."* It commits, it rules
+out the power-user road, it names the leverage (their setup experience),
+and it decides real roadmap fights.
+
+## Failure modes to catch
+
+- **Goal restated as policy.** "Grow 3x", "be the leader." A destination,
+  not a route. Ask how, and how differently from rivals.
+- **The costless platitude.** "Delight customers", "focus on quality." Rules
+  nothing out; everyone nods. Force the trade-off.
+- **The wish-list.** Three approaches joined by "and" — because they
+  wouldn't choose. A policy that keeps every option isn't guiding. Make
+  them pick the primary one.
+- **Leverage-free direction.** A route with no reason it beats the
+  alternatives. Ask "why will this work when the obvious approach wouldn't?"
+- **Policy that changes no decision.** If every real choice comes out the
+  same with or without it, it's decoration. Test against a live call.
+
+## When they're really framing something else
+
+- If they can't commit to any direction because one specific fork is
+  blocking everything — build vs buy, this segment vs that — frame that
+  fork first with `decision.md`, then return to the overall policy.
+- If "success" itself is still fuzzy, they may need `outcome.md` before a
+  policy makes sense.

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.