luxin-cli 0.2.7 → 0.2.9

package/CHANGELOG.md

@@ -6,6 +6,62 @@ provenance; this file is the human- and agent-readable release map.
 
 ## Unreleased
 
+## 0.2.9 - 2026-08-17
+
+Discovery, batch work, and recovery — the release for agents doing real
+multi-image jobs.
+
+- New command: `luxin models overview` — a ~2KB orientation payload with
+  category groups and counts, the cheapest executable model per category,
+  alias hints, and runnable next commands. Read this instead of the full list.
+- New command: `luxin models find` — terse, cost-sorted decision rows with
+  `--max-credits`, `--limit` (default 10), `--sort credits|usd`, a free-text
+  query, and the existing filters. Rows carry aspect-ratio support and honest
+  availability, include cataloged-but-not-yet-wired models (clearly marked,
+  ranked last), and report `total_matched` with a narrowing hint. The query
+  that used to return 4,000+ lines now answers in ~130. (#2114)
+- `models list` gains the same `--limit` / `--sort` / `--max-credits` flags
+  and is byte-identical when you don't use them. Against an older hosted API,
+  find/overview/narrowing degrade honestly client-side and say so in
+  `warnings`.
+- New: `luxin create --batch items.json` (or `--batch -`) — sequential
+  multi-image work as one command: shared defaults plus per-item prompts,
+  whole-document validation before any spend. `--dry-run` prices the whole
+  job with the same debit math the live run charges, checks your credits AND
+  the daily job cap, and answers "your credits cover K of N; the batch stops
+  at item K+1" with the top-up sized to the actual need. At any wall the
+  completed items are delivered and the batch stops cleanly with one digest
+  and one recovery block; re-running with the same `--batch-id` skips
+  completed, unchanged items. `seed_policy: fixed | increment | random` where
+  the model supports a seed. (#2304)
+- Recovery handle in the envelope: live create/edit responses now carry
+  `data.idempotency_key` on success and `error.recovery.idempotency_key` plus
+  a re-runnable `error.recovery.recover_command` on failure, so an
+  interrupted spend is recoverable from the envelope alone. stdout is exactly
+  one JSON document per invocation — now stated plainly in the contract; the
+  in-flight recovery line stays on stderr. (#2240)
+- Hosted-side, already live and noted for completeness: create/edit responses
+  echo `effective_parameters` (each knob tagged explicit / default_policy /
+  provider_default) so you can see the configuration that actually ran, and
+  `resolution` without `quality` on xai.grok-imagine-image-2.0 now sends the
+  medium tier you were already being quoted. (#2310)
+
+## 0.2.8 - 2026-08-12
+
+- New command: `luxin skill` prints the full usage guidance from bundled
+  package bytes, so instructions always match the CLI you are running. The
+  installed SKILL.md is now a ~4KB discovery stub that points here; the full
+  body is also served at https://luxin.sh/skill-core.md.
+- Skill freshness handshake: export `LUXIN_SKILL_REVISION=<the revision in
+your stub's frontmatter>` and `create --guide`, `edit --guide`, and
+  `luxin skill` will return `data.skill_refresh` with the current revision and
+  the exact refresh command (`npx skills update luxin`) whenever your installed
+  copy no longer matches. The field is omitted entirely when you are current.
+  Nothing ever rewrites your files, config, or hooks — refresh is always an
+  explicit command you run.
+- `agent_skill.read_command` now points at `luxin skill --json` instead of
+  curling the stub.
+
 ## 0.2.7 - 2026-08-12
 
 - Release (pricing): the guide's local credit quoting for xAI models moved from

package/README.md

@@ -85,9 +85,67 @@ Naming note: Luxin is a creative-media runtime for agents. It is unrelated to
 `luxon`, the datetime library; the npm package here is `luxin-cli` and the
 installed binary is `luxin`.
 
+## Keeping The Skill Current
+
+The installed `SKILL.md` is a ~4KB discovery stub. Everything volatile — flags,
+workflows, recovery, funding — lives in the guidance the CLI itself carries, so
+it always matches the code you are running:
+
+```bash
+npm_config_update_notifier=false npx -y luxin-cli@latest skill
+```
+
+Refresh the installed stub with the standard verb:
+
+```bash
+npx skills update luxin
+```
+
+The stub records its own identity as `metadata.skill_revision`. Export it and
+the CLI will say when your copy no longer matches the guidance it ships,
+returning `data.skill_refresh` plus one warning line on `luxin skill` and
+`create --guide`:
+
+```bash
+export LUXIN_SKILL_REVISION=<metadata.skill_revision from your installed SKILL.md>
+```
+
+Detection is remote; mutation stays local and explicit. Luxin prints the refresh
+command and never rewrites your skill files, agent config, or hook files.
+
+### Optional: refresh at session start (copy-paste, opt-in)
+
+Some runtimes can run a command when a session starts. If you want an automatic
+refresh, add it yourself — Luxin will not install it for you, and nothing below
+runs unless you put it there. For Claude Code, in `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx skills update luxin",
+            "timeout": 60
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Two things worth knowing before you adopt it: it adds a network call to every
+session start, and it applies updates without showing you a diff first. Running
+`npx skills update luxin` by hand when a nudge appears keeps the change
+reviewable.
+
 Agent-facing contracts:
 
 - [Hosted skill contract](https://luxin.sh/skill.md)
+- [Hosted skill guidance](https://luxin.sh/skill-core.md)
 - [Hosted LLM contract](https://luxin.sh/llms.txt)
 - [Hosted CLI contract](https://luxin.sh/cli.md)
 - [Public repo skill source](https://github.com/danielgwilson/luxin/tree/main/skills/luxin)