@ekanos/cli 0.1.4 → 0.1.6

package/templates/claude-skill.md.tmpl

@@ -18,8 +18,24 @@ root. Read it before writing integration code. The definition is one
 3. `npx tsc --noEmit` — types clean.
 4. `npx ekanos validate --json` — findings clean.
 5. `npm test` — green.
-6. `npx ekanos publish` — submits to the Fusion host (refuses while any
-   error-severity finding remains).
+6. **Before publishing, know your target.** If you hold more than one
+   developer seat, run `npx ekanos sources --json` and pass the intended
+   `--source <slug>` explicitly to `publish`. Never pass `--yes` to get past
+   an ambiguous-target error you have not actually resolved — `--yes` is
+   consent to a target you already chose, not a way to silence the check.
+7. `npx ekanos publish --source <slug>` — submits to the Fusion host (refuses
+   while any error-severity finding remains, and refuses `forbidden` if you
+   hold no seat on that source).
+
+## Keeping the toolchain current
+
+If a `validate` finding smells like version skew (an unrecognized-key error on
+a field you're confident is correct), run `npx ekanos upgrade --check` —
+read-only, always safe, reports current vs. target versions and changes
+nothing. A bare `npx ekanos upgrade` MUTATES the project (installs the target
+toolchain, verifies with validate + the test script, rolls back automatically
+on any failure). Never run the bare form just to "see what happens" — use
+`--check` for that.
 
 ## Reading CLI output
 
@@ -32,22 +48,38 @@ remediation instructions and follow them verbatim.** `ekanos validate` puts
 findings in `data.findings`; `ekanos publish` refuses with exit 10 and the
 same findings in `data.findings`.
 
-Exit codes to branch on: `0` ok · `2` usage · `3` validation · `4` run
-`ekanos login` · `7` version already submitted (bump `package.json#version`) ·
-`8` network (retry — do NOT re-login) · `9` precondition · `10` fix findings,
-publish again.
+Exit codes to branch on: `0` ok · `2` usage · `3` validation (also: ambiguous
+publish target — pass `--source` or `--yes`, never guess) · `4` run
+`ekanos login` · `5` forbidden (also: no seat on the target source — run
+`ekanos sources`) · `7` version already submitted (bump `package.json#version`) ·
+`8` network (retry — do NOT re-login) · `9` precondition (also: the project's
+`@ekanos/integration-schema` is newer than this CLI bundles — run
+`ekanos upgrade`) · `10` fix findings, publish again.
 
 ## Hosts and sessions
 
 `ekanos login --host <url>` stores a session; after that, `logout`/`whoami`/
-`status`/`publish` resolve the host from `--host` → `EKANOS_HOST` →
-ekanos.json's `host` field → the sole stored login. `login` itself never reads
-ekanos.json for a host — only `--host`, `EKANOS_HOST`, or the sole stored
-login — since it is the verb that creates credentials. `ekanos status` shows
-who you are logged in as and what this project has submitted. The first
-successful publish saves `host` and `source` into ekanos.json.
+`status`/`sources`/`use`/`publish` resolve the host from `--host` →
+`EKANOS_HOST` → ekanos.json's `host` field → the sole stored login. `login`
+itself never reads ekanos.json for a host — only `--host`, `EKANOS_HOST`, or
+the sole stored login — since it is the verb that creates credentials.
+`ekanos status` shows who you are logged in as and what this project has
+submitted. The first successful publish saves `host` and `source` into
+ekanos.json.
+
+## Publish targets, when you hold more than one seat
+
+`ekanos sources` lists every source you hold a seat on; `ekanos use <slug>`
+sets this project's saved target (seat-checked — refuses a slug you don't
+hold). `publish` verifies its resolved target against your seats before
+packing anything, and — running as an agent, which is JSON/non-interactive
+mode — never prompts: an ambiguous implicit target (ekanos.json, more than one
+seat) is refused with the seat list unless you pass `--yes`. **Always resolve
+the ambiguity yourself** (pick the right `--source`) rather than reaching for
+`--yes` on a target you have not verified.
 
 ## Before claiming done
 
 Run steps 3-5 above and confirm all three are clean — a publish is only as
-good as the validate that precedes it.
+good as the validate that precedes it. If publishing, confirm you named the
+right `--source` rather than relying on `--yes`.