luxin-cli 0.2.7 → 0.2.8

package/CHANGELOG.md

@@ -6,6 +6,22 @@ provenance; this file is the human- and agent-readable release map.
 
 ## Unreleased
 
+## 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)

package/bin/luxin.mjs

@@ -15,7 +15,20 @@ import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import os from "node:os";
 
-const VERSION = "0.2.7";
+const VERSION = "0.2.8";
+// Content-derived identity of the guidance this package ships (#2302). Kept in
+// sync with docs/public-contract/skill.md by `pnpm skill-revision:write` and
+// gated by `pnpm skill-revision:check`; the mirror cannot import from src/.
+const SKILL_REVISION = "b1dc1284d18d";
+// `luxin skill` prints these bundled bytes rather than fetching them, so the
+// guidance can never describe a CLI other than the one printing it. Packed by
+// public-cli/package.json `files`.
+const SKILL_GUIDANCE_FILE = "skill-core.md";
+const SKILL_GUIDANCE_SCHEMA = "image-skill.skill-guidance.v1";
+const SKILL_CORE_URL = "https://luxin.sh/skill-core.md";
+const SKILL_REFRESH_COMMAND = "npx skills update luxin";
+const INSTALLED_SKILL_REVISION_ENV = "LUXIN_SKILL_REVISION";
+const INSTALLED_SKILL_REVISION_HEADER = "x-luxin-skill-revision";
 const PACKAGE_NAME = "luxin";
 const DEFAULT_API_BASE_URL = "https://api.luxin.sh";
 const DEFAULT_DOCS_BASE_URL = "https://luxin.sh";
@@ -334,7 +347,8 @@ function agentSkillHint(commandPrefix = "luxin") {
     url: AGENT_SKILL_URL,
     llms_url: AGENT_LLMS_URL,
     cli_docs_url: AGENT_CLI_DOCS_URL,
-    read_command: "curl -fsSL https://luxin.sh/skill.md",
+    // #2302: point at the CLI-carried guidance, not the discovery stub.
+    read_command: "luxin skill --json",
     recommended_start_command: renderGuidePrefixedCommand(
       commandPrefix,
       "create --guide --prompt PROMPT --json",
@@ -387,6 +401,8 @@ async function main(rawArgv) {
         return await doctor(rest);
       case "trust":
         return await trust(rest);
+      case "skill":
+        return await skill(rest);
       case "signup":
         return await signup(rest);
       case "claim":
@@ -503,12 +519,13 @@ function commandHelpByKey(key) {
     "": {
       command: "help",
       usage:
-        "luxin <doctor|trust|signup|claim|whoami|usage|quota|credits|capabilities|models|create|upload|edit|assets|jobs|activity|feedback> --json",
+        "luxin <doctor|trust|skill|signup|claim|whoami|usage|quota|credits|capabilities|models|create|upload|edit|assets|jobs|activity|feedback> --json",
       docs_url: "https://luxin.sh/cli.md",
       agent_skill: agentSkillHint(),
       commands: [
         "doctor",
         "trust",
+        "skill",
         "signup --agent --agent-name NAME --runtime RUNTIME",
         "claim request --contact INBOX",
         "claim code",
@@ -560,6 +577,13 @@ function commandHelpByKey(key) {
       description:
         "Return npm provenance, hosted contract hashes, API health, and model availability evidence.",
     },
+    skill: {
+      command: "luxin skill help",
+      usage: "luxin skill --json",
+      docs_url: "https://luxin.sh/cli.md#luxin-skill",
+      description:
+        "Print the full agent guidance bundled with this CLI version, so instructions always match the installed code. No network call, no auth, no spend.",
+    },
     signup: {
       command: "luxin signup help",
       usage: "luxin signup --agent --agent-name NAME --runtime RUNTIME --json",
@@ -880,6 +904,104 @@ function unsupportedFlagsMessage(command, flags) {
     .join(", ")}`;
 }
 
+// #2302: the installed SKILL.md is a ~4KB discovery stub. Everything volatile
+// -- flags, workflows, recovery, funding -- lives in the guidance body this
+// command prints, so an agent working from a months-old install still reads
+// instructions that match the code it is about to run.
+//
+// Bundled, not fetched. A network fetch could serve prose this build does not
+// implement, which is the drift the split exists to remove.
+async function skill(argv) {
+  const args = parseArgs(argv);
+  const unsupportedFlags = [...args.flags.keys()].filter(
+    (flag) => !["json"].includes(flag),
+  );
+  if (args.positionals.length > 0 || unsupportedFlags.length > 0) {
+    return invalid(
+      "luxin skill",
+      unsupportedFlags.length > 0
+        ? unsupportedFlagsMessage("skill", unsupportedFlags)
+        : "skill does not accept positional arguments",
+    );
+  }
+
+  let content;
+  try {
+    content = await readFile(
+      new URL(`../${SKILL_GUIDANCE_FILE}`, import.meta.url),
+      "utf8",
+    );
+  } catch (error) {
+    return failure(
+      "luxin skill",
+      7,
+      "SKILL_GUIDANCE_UNAVAILABLE",
+      `bundled skill guidance could not be read: ${
+        error instanceof Error ? error.message : "unknown error"
+      }. Reinstall the CLI, or read ${SKILL_CORE_URL}`,
+      false,
+    );
+  }
+
+  const refresh = skillRefresh();
+  return success(
+    "luxin skill",
+    {
+      schema: SKILL_GUIDANCE_SCHEMA,
+      revision: SKILL_REVISION,
+      source: "bundled_cli_package",
+      format: "markdown",
+      bytes: Buffer.byteLength(content, "utf8"),
+      canonical_url: SKILL_CORE_URL,
+      refresh_command: SKILL_REFRESH_COMMAND,
+      mutation: {
+        provider_call: false,
+        credit_debit: false,
+        media_write: false,
+        local_file_write: false,
+      },
+      ...(refresh === null ? {} : { skill_refresh: refresh }),
+      content,
+    },
+    refresh === null ? [] : [skillRefreshWarning(refresh)],
+  );
+}
+
+/**
+ * Self-reported identity of the caller's installed skill copy. 12 lowercase hex
+ * or nothing: the value is echoed into a response field and forwarded as a
+ * header, so it must not become a channel for arbitrary text.
+ */
+function installedSkillRevision() {
+  const raw = process.env[INSTALLED_SKILL_REVISION_ENV];
+  if (typeof raw !== "string") {
+    return null;
+  }
+  const trimmed = raw.trim().toLowerCase();
+  return /^[0-9a-f]{12}$/.test(trimmed) ? trimmed : null;
+}
+
+/**
+ * The compact nudge, or nothing at all. Omitted when the caller reports nothing
+ * or reports the revision this CLI ships. Content hashes are unordered, so this
+ * says "differs", never "older".
+ */
+function skillRefresh() {
+  const installed = installedSkillRevision();
+  if (installed === null || installed === SKILL_REVISION) {
+    return null;
+  }
+  return {
+    installed_revision: installed,
+    current_revision: SKILL_REVISION,
+    refresh_command: SKILL_REFRESH_COMMAND,
+  };
+}
+
+function skillRefreshWarning(refresh) {
+  return `installed skill revision ${refresh.installed_revision} does not match the current revision ${refresh.current_revision} this CLI ships; refresh with: ${refresh.refresh_command}`;
+}
+
 async function trust(argv) {
   const args = parseArgs(argv);
   const unsupportedFlags = [...args.flags.keys()].filter(
@@ -2342,6 +2464,7 @@ async function createGuide(args, options = {}) {
       },
     ),
   };
+  const guideSkillRefresh = skillRefresh();
   const guideData = {
     schema:
       guideOperation === "edit"
@@ -2468,20 +2591,25 @@ async function createGuide(args, options = {}) {
       credit_debit: false,
       media_write: false,
     },
+    // #2302: present only when the caller self-reported a revision that is not
+    // the one this CLI ships. Survives ready_compact deliberately -- a nudge
+    // that only appears in the blocked stages would never reach the agents who
+    // are working fine on stale instructions, which is the whole failure mode.
+    ...(guideSkillRefresh === null ? {} : { skill_refresh: guideSkillRefresh }),
   };
   for (const field of compactOmittedFields) {
     delete guideData[field];
   }
-  return createGuideSuccess(
-    command,
-    quota?.envelope.actor ?? null,
-    guideData,
-    plannedDebitUnavailable
+  return createGuideSuccess(command, quota?.envelope.actor ?? null, guideData, [
+    ...(plannedDebitUnavailable
       ? [
           "create_credit_debit_unavailable: this hosted API does not publish per-aspect-ratio create debits, so the credits above are the model's default-shape quote and may not be what create debits. Run the dry_run command in escape_hatches for the exact figure before budgeting.",
         ]
-      : [],
-  );
+      : []),
+    ...(guideSkillRefresh === null
+      ? []
+      : [skillRefreshWarning(guideSkillRefresh)]),
+  ]);
 }
 
 function createGuideSuccess(command, actor, data, warnings = []) {
@@ -6869,6 +6997,12 @@ async function apiRequest(input) {
         ...(input.token === undefined
           ? {}
           : { authorization: `Bearer ${input.token}` }),
+        // #2302: self-reported identity of the installed skill copy, so the
+        // hosted side can measure how stale the installed base is. Non-secret,
+        // omitted entirely when unset, never guessed.
+        ...(installedSkillRevision() === null
+          ? {}
+          : { [INSTALLED_SKILL_REVISION_HEADER]: installedSkillRevision() }),
       },
       body: input.body === undefined ? undefined : JSON.stringify(input.body),
     });

package/cli.md

@@ -93,6 +93,63 @@ verified, the command still returns a packet with explicit `unreachable`,
 `not_available_yet`, `inspect_only`, or `stale_or_mismatched` states rather
 than omitting the field.
 
+### `luxin skill`
+
+Prints the full agent guidance that shipped with this CLI version.
+
+```bash
+luxin skill --json
+```
+
+The published `SKILL.md` at `https://luxin.sh/skill.md` is a ~4KB discovery
+stub: it carries identity, the first command, the safety invariants, and a
+revision, and nothing else. Flags, workflows, model parameters, recovery, and
+funding details live here, because an installed skill file is a snapshot that
+never updates while `npx luxin-cli@latest` updates on every call.
+
+The body is read from the package this command is running from, not fetched, so
+the guidance always matches the installed code by construction. No network call,
+no auth, no spend. The same bytes are served at
+`https://luxin.sh/skill-core.md`.
+
+`data` uses `schema: "image-skill.skill-guidance.v1"` and carries `revision`
+(the 12-hex content-derived identity of the published skill), `source`,
+`format`, `bytes`, `canonical_url`, `refresh_command`, `mutation`, and
+`content`.
+
+#### Skill revision and staleness
+
+An installed skill file records its revision as `metadata.skill_revision` in its
+frontmatter. Export it so the CLI can tell you when your copy has fallen behind
+the guidance the CLI ships:
+
+```bash
+export LUXIN_SKILL_REVISION=<metadata.skill_revision from your installed SKILL.md>
+```
+
+When the value differs from what the running CLI ships, `luxin skill` and
+`create --guide` / `edit --guide` add `data.skill_refresh`:
+
+```json
+{
+  "skill_refresh": {
+    "installed_revision": "0123456789ab",
+    "current_revision": "b1dc1284d18d",
+    "refresh_command": "npx skills update luxin"
+  }
+}
+```
+
+They also emit one warning line naming the same command. When the revisions
+match, or when `LUXIN_SKILL_REVISION` is unset, the field is omitted entirely.
+
+Refreshing is always a command you choose to run. Luxin never rewrites your
+skill files, agent config, or hooks, and never fetches instructions to follow
+them. The revision is also forwarded to the hosted API as a non-secret
+`x-luxin-skill-revision` header and published unauthenticated on
+`GET /healthz` as `skill_revision`, so a client can compare without downloading
+any contract file.
+
 ### `luxin signup --agent`
 
 Bootstraps restricted agent access. Signup is anonymous by default: no contact
@@ -280,6 +337,13 @@ recommended (`data.self_fund_preparation.recommended` is `true`), the
 `data.self_fund_*` fields stay in the compact response and are not listed in
 `data.output_mode.omitted_fields`.
 
+`data.skill_refresh` is the other field that survives the compact response, for
+the same reason: an agent whose installed skill file has gone stale is usually
+an agent whose calls are otherwise succeeding. It appears only when
+`LUXIN_SKILL_REVISION` is exported and differs from the revision the running CLI
+ships, and carries `installed_revision`, `current_revision`, and
+`refresh_command`. See [`luxin skill`](#luxin-skill) for the full handshake.
+
 ```bash
 IMAGE_SKILL_DISCOVERY_SOURCE=cli-md luxin create --guide --prompt "a compact field camera on a stainless workbench"
 ```

package/commands.json

@@ -20,6 +20,13 @@
       "mutation": false,
       "spend": false
     },
+    {
+      "id": "skill",
+      "docs_anchor": "luxin-skill",
+      "surface": "client",
+      "mutation": false,
+      "spend": false
+    },
     {
       "id": "signup",
       "docs_anchor": "luxin-signup-agent",
@@ -148,13 +155,13 @@
       "key": "",
       "help": {
         "command": "help",
-        "usage": "luxin <doctor|trust|signup|claim|whoami|usage|quota|credits|capabilities|models|create|upload|edit|assets|jobs|activity|feedback> --json",
+        "usage": "luxin <doctor|trust|skill|signup|claim|whoami|usage|quota|credits|capabilities|models|create|upload|edit|assets|jobs|activity|feedback> --json",
         "docs_url": "https://luxin.sh/cli.md",
         "agent_skill": {
           "url": "https://luxin.sh/skill.md",
           "llms_url": "https://luxin.sh/llms.txt",
           "cli_docs_url": "https://luxin.sh/cli.md",
-          "read_command": "curl -fsSL https://luxin.sh/skill.md",
+          "read_command": "luxin skill --json",
           "recommended_start_command": "luxin create --guide --prompt PROMPT --json",
           "model_discovery_command": "luxin models list --available --operation image.generate --json",
           "model_inspection_command": "luxin models show MODEL_ID --json",
@@ -164,6 +171,7 @@
         "commands": [
           "doctor",
           "trust",
+          "skill",
           "signup --agent --agent-name NAME --runtime RUNTIME",
           "claim request --contact INBOX",
           "claim code",
@@ -220,6 +228,15 @@
         "description": "Return npm provenance, hosted contract hashes, API health, and model availability evidence."
       }
     },
+    {
+      "key": "skill",
+      "help": {
+        "command": "luxin skill help",
+        "usage": "luxin skill --json",
+        "docs_url": "https://luxin.sh/cli.md#luxin-skill",
+        "description": "Print the full agent guidance bundled with this CLI version, so instructions always match the installed code. No network call, no auth, no spend."
+      }
+    },
     {
       "key": "signup",
       "help": {

package/llms.txt

@@ -3,10 +3,14 @@
 Status: live preview hosted-product contract
 Canonical homepage: https://luxin.sh
 Canonical skill URL: https://luxin.sh/skill.md
+Canonical skill guidance URL: https://luxin.sh/skill-core.md
 Canonical LLM URL: https://luxin.sh/llms.txt
 Canonical CLI URL: https://luxin.sh/cli.md
 Canonical hosted API URL: https://api.luxin.sh
 
+Skill freshness:
+https://luxin.sh/skill.md is a ~4KB discovery stub carrying identity, the first command, the safety invariants, and metadata.skill_revision. The full guidance is https://luxin.sh/skill-core.md, and `luxin skill --json` prints those same bytes from the installed package, so guidance always matches the running CLI. Export LUXIN_SKILL_REVISION=<metadata.skill_revision of your installed copy>: when it differs from what the CLI ships, `luxin skill` and `create --guide` return data.skill_refresh with installed_revision, current_revision, and refresh_command `npx skills update luxin`, plus one warning line. When it matches or is unset the field is omitted. Refreshing is a command you run; Luxin never rewrites skill files, agent config, or hooks. GET https://api.luxin.sh/healthz publishes the current skill_revision unauthenticated.
+
 Purpose:
 Luxin is zero-setup creative media for agents: no provider API key, no OAuth, no install to manage, and no per-provider billing account. Agents start with the hosted guide, follow one next command, and use one thin CLI/client and API to generate and edit images, generate video and audio (music, sound), and create 3D assets (image-to-3D mesh, glb), get durable owned media URLs, recover jobs, inspect models, cap spend, pay through credits (browserless agent x402 when returned available; Stripe Checkout human handoff as fallback), and leave feedback. If the guide needs restricted agent signup before first media, it returns that command explicitly.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "luxin-cli",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "Image generation, image editing, video, audio, and image-to-3D for agents, with no API key to obtain first. The agent signs itself up, starts on free preview credits, and gets hosted media URLs, recoverable jobs, and cost receipts.",
   "type": "module",
   "private": false,
@@ -21,6 +21,7 @@
     "CONTRIBUTING.md",
     "CODE_OF_CONDUCT.md",
     "skill.md",
+    "skill-core.md",
     "llms.txt",
     "cli.md",
     "commands.json",