altalandi 0.1.0 → 0.2.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Altalandi
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Altalandi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,53 +1,142 @@
-# altalandi
-
-Turn English or stiff/AI-translated Icelandic into Icelandic that reads as if a
-native wrote it — from your terminal. Thin client over the
-[Altalandi API](https://altalandi.is). Zero dependencies (Node ≥ 18).
-
-```bash
-export ALTALANDI_API_KEY="rtv_..."     # mint one at https://altalandi.is/portal
-npx altalandi "Make sure to reach out to us today."
-#  → Hafðu samband við okkur í dag.
-```
-
-`stdout` is the refined text (pipe it anywhere); `stderr` carries the 0–100
-nativeness score, the meaning verdict, and the diff.
-
-## Install
-
-```bash
-npm i -g altalandi      # then use `altalandi ...`
-# or run without installing:  npx altalandi "..."
-```
-
-## Usage
-
-```bash
-altalandi "Some English or Icelandic text."
-echo "some text" | altalandi --domain marketing
-altalandi --json "..."                 # full JSON response
-altalandi --fast "..."                 # skip the meaning + nativeness gates
-```
-
-| flag | default | meaning |
-|------|---------|---------|
-| `--domain` | `general` | `general` \| `marketing` \| `data-analysis` \| `childrens-fiction` |
-| `--register` | `neutral` | `formal` \| `neutral` \| `warm` |
-| `--json` | off | print the full API response |
-| `--fast` | off | `preserveMeaning:false`, `scoreNativeness:false` (one model call) |
-
-## The meaning guarantee
-
-Altalandi never silently changes meaning. For Icelandic input where the rewrite
-can't be verified to preserve meaning, it returns the **original unchanged** and
-says so on `stderr` (or `meaningPreserved:false` with `--json`). Check it before
-trusting the output in an automated pipeline.
-
-## Config
-
-| env | default | purpose |
-|-----|---------|---------|
-| `ALTALANDI_API_KEY` | — | your key (Bearer). Mint at https://altalandi.is/portal |
-| `ALTALANDI_BASE_URL` | `https://altalandi.is/api` | API base (override for self-hosting) |
-
-MIT licensed. The hosted API is metered per key (calls + words/day).
+# altalandi
+
+Turn English or stiff/AI-translated Icelandic into Icelandic that reads as if a
+native wrote it—from your terminal or application. This package provides the
+`altalandi` CLI and a typed, zero-dependency JavaScript client for the hosted
+[Altalandi API](https://altalandi.is) (Node ≥ 18).
+
+```bash
+# Mint once at https://altalandi.is/portal, then enter it without shell history:
+read -rsp "Altalandi API key: " ALTALANDI_API_KEY; echo
+export ALTALANDI_API_KEY
+npx altalandi "Make sure to reach out to us today."
+#  → Hafðu samband við okkur í dag.
+```
+
+PowerShell 7: `$env:ALTALANDI_API_KEY = Read-Host "Altalandi API key" -MaskInput`.
+
+`stdout` is the refined text (pipe it anywhere); `stderr` carries the 0–100
+nativeness score, the meaning verdict, every API warning, and the diff.
+
+## Install
+
+```bash
+npm i -g altalandi      # then use `altalandi ...`
+# or run without installing:  npx altalandi "..."
+```
+
+For an application dependency, install locally and import the package root:
+
+```bash
+npm i altalandi
+```
+
+## Updating
+
+```bash
+altalandi update          # check, then ask before updating
+altalandi update --check  # only report; change nothing
+altalandi --version
+```
+
+`altalandi update` checks npm for a newer version and asks before installing
+it. It works out how you installed the CLI (global, project dependency or `npx`)
+and runs the matching command. If you use Claude Code, it then offers to install
+or refresh the `/altalandi` skill that ships with each version. A skill you have
+edited is backed up before it is replaced.
+
+Nothing changes without your answer. Without a terminal to ask in (agents, CI,
+pipes) it only reports what is available; pass `--yes` when a script already has
+your consent.
+
+Exit codes: `0` up to date or updated · `10` an update is available but was not
+applied · `1` the check or the update failed.
+
+## JavaScript / TypeScript client
+
+`refineVerified` requests the meaning gate and throws unless the API returns
+strict `meaningPreserved: true`. It reads `ALTALANDI_API_KEY` automatically:
+
+```js
+import { refineVerified } from "altalandi";
+
+const result = await refineVerified("Make sure to reach out to us today.", {
+  domain: "marketing",
+});
+console.log(result.output);
+```
+
+Use `refine` when you need to inspect an unverified result yourself, then apply
+the same strict assertion before shipping it:
+
+```js
+import { assertMeaningVerified, refine } from "altalandi";
+
+const result = await refine("Some text", { register: "warm" });
+assertMeaningVerified(result); // throws on both false and null
+console.log(result.output);
+```
+
+Both functions accept `apiKey` (for a secret-manager value), `baseUrl`, and
+`timeoutMs` alongside the request options. The defaults are
+`ALTALANDI_API_KEY`, `https://altalandi.is/api`, and 300,000 ms. API, network,
+timeout, and verification failures throw `AltalandiError` subclasses with a
+stable `code`; errors never include the request text or API key. TypeScript
+declarations ship with the package. The CLI uses the same 300-second request
+deadline, including response-body download.
+
+## Usage
+
+```bash
+altalandi "Some English or Icelandic text."
+echo "some text" | altalandi --domain marketing
+altalandi --json "..."                 # full JSON response
+altalandi --fast "..."                 # skip the meaning + nativeness gates
+```
+
+| flag | default | meaning |
+|------|---------|---------|
+| `--domain` | `general` | `general` \| `marketing` \| `data-analysis` \| `childrens-fiction` |
+| `--register` | `neutral` | `formal` \| `neutral` \| `warm` |
+| `--json` | off | print the full API response |
+| `--fast` | off | `preserveMeaning:false`, `scoreNativeness:false`, `onlyImprove:false`, `polishPass:false`, `scoring:"none"` — normally one model call (structured input can still add a structure-preserving retry) |
+
+## The meaning guarantee
+
+Altalandi never silently changes meaning. For Icelandic input where the rewrite
+can't be verified to preserve meaning, it returns the **original unchanged** and
+says so on `stderr` (or `meaningPreserved:false` with `--json`). Check it before
+trusting the output in an automated pipeline. Only `meaningPreserved:true` is a
+verified pass; `null` means the gate was skipped or did not complete. `--fast`
+deliberately skips the gate, so its result is unverified by design.
+
+Without `--fast`, a `null` meaning verdict is printed as **MEANING UNVERIFIED**:
+the check did not run or could not complete, so review the output before use.
+With `--fast`, `null` is expected and is printed as **meaning check skipped**.
+API warnings are always printed on `stderr`; under `--json` they remain in the
+unchanged `warnings` array.
+
+For automation, a successful HTTP response is not enough: without `--fast`, the
+CLI prints the text or JSON response and then exits with status **3** when
+`meaningPreserved` is `false` or `null`. Only strict `true` exits 0. `--fast` is
+the explicit verification opt-out and exits 0 after a successful API response.
+
+| exit | meaning |
+|------|---------|
+| `0` | verified success, or successful `--fast` request |
+| `1` | API or network failure |
+| `2` | missing input/key or invalid CLI usage |
+| `3` | response printed, but meaning was false or unverified |
+
+## Config
+
+| env | default | purpose |
+|-----|---------|---------|
+| `ALTALANDI_API_KEY` | — | your key (Bearer). Mint at https://altalandi.is/portal |
+| `ALTALANDI_BASE_URL` | `https://altalandi.is/api` | API base (override for self-hosting) |
+
+MIT licensed. Portal keys share a daily account-level billable-word budget;
+operator-issued keys remain per-key, and key rotation does not reset account
+usage. The request's text and glossary fields are charged at the effective billing-tier
+weight. Each whitespace-delimited token is at least one unit; an unbroken token
+uses one unit per 20 characters, rounded up.

package/altalandi.mjs

@@ -1,87 +1,169 @@
-#!/usr/bin/env node
-// altalandi — turn English or stiff/AI Icelandic into native Icelandic from
-// your terminal. Zero dependencies (Node >= 18 has global fetch).
-//
-//   export ALTALANDI_API_KEY=...        # get one at https://altalandi.is
-//   altalandi "Make sure to reach out to us today."
-//   echo "some text" | altalandi --domain marketing
-//
-// stdout = the refined text (so you can pipe it); stderr = nativeness score,
-// meaning verdict, and the diff.
-
-const args = process.argv.slice(2);
-const opts = { domain: "general", register: "neutral", json: false, fast: false };
-const positional = [];
-for (let i = 0; i < args.length; i++) {
-  const a = args[i];
-  if (a === "-h" || a === "--help") { help(); process.exit(0); }
-  else if (a === "--json") opts.json = true;
-  else if (a === "--fast") opts.fast = true;
-  else if (a === "--domain") opts.domain = args[++i];
-  else if (a === "--register") opts.register = args[++i];
-  else if (a === "--base-url") opts.baseUrl = args[++i];
-  else if (a === "--key") opts.key = args[++i];
-  else positional.push(a);
-}
-
-function help() {
-  console.log(`altalandi — native Icelandic from your terminal
-
-Usage:
-  altalandi "text to refine"
-  echo "text" | altalandi
-  altalandi --domain marketing --register warm "text"
-
-Options:
-  --domain     general | marketing | data-analysis | childrens-fiction  (default general)
-  --register   formal | neutral | warm  (default neutral)
-  --fast       skip the meaning gate + nativeness score (faster, cheaper)
-  --json       print the full JSON response
-  --base-url   API base  (default $ALTALANDI_BASE_URL or https://altalandi.is/api)
-  --key        API key   (default $ALTALANDI_API_KEY)
-
-stdout = refined text; stderr = nativeness / meaning / diff.`);
-}
-
-function readStdin() {
-  return new Promise((resolve) => {
-    if (process.stdin.isTTY) return resolve("");
-    let d = "";
-    process.stdin.setEncoding("utf8");
-    process.stdin.on("data", (c) => (d += c));
-    process.stdin.on("end", () => resolve(d));
-  });
-}
-
-const baseUrl = (opts.baseUrl || process.env.ALTALANDI_BASE_URL || "https://altalandi.is/api").replace(/\/$/, "");
-const key = opts.key || process.env.ALTALANDI_API_KEY || process.env.ALTALANDI_KEY;
-
-const text = (positional.join(" ").trim()) || (await readStdin()).trim();
-if (!text) { console.error("No input. Pass text as an argument or pipe via stdin.  (altalandi --help)"); process.exit(2); }
-if (!key) { console.error("No API key. Set ALTALANDI_API_KEY or pass --key.  Get one at https://altalandi.is"); process.exit(2); }
-
-const body = { text, domain: opts.domain, register: opts.register };
-if (opts.fast) { body.preserveMeaning = false; body.scoreNativeness = false; }
-
-try {
-  const res = await fetch(`${baseUrl}/v1/refine`, {
-    method: "POST",
-    headers: { "content-type": "application/json", authorization: `Bearer ${key}` },
-    body: JSON.stringify(body),
-  });
-  const data = await res.json().catch(() => ({}));
-  if (!res.ok) { console.error(`Error ${res.status}: ${data.detail || res.statusText}`); process.exit(1); }
-  if (opts.json) { process.stdout.write(JSON.stringify(data, null, 2) + "\n"); process.exit(0); }
-
-  process.stdout.write(data.output + "\n");
-  const q = data.quality || {};
-  const meta = [];
-  if (q.nativenessScore != null) meta.push(`nativeness ${q.nativenessScore}/100`);
-  if (data.meaningPreserved === false) meta.push("⚠ MEANING DRIFT — returned the original");
-  else if (data.meaningPreserved === true) meta.push("meaning preserved");
-  if (meta.length) console.error("· " + meta.join(" · "));
-  for (const d of data.diffs || []) console.error(`  − ${d.before}\n  + ${d.after}  (${d.reason})`);
-} catch (e) {
-  console.error("Request failed:", e.message);
-  process.exit(1);
-}
+#!/usr/bin/env node
+// altalandi — turn English or stiff/AI Icelandic into native Icelandic from
+// your terminal. Zero dependencies (Node >= 18 has global fetch).
+//
+//   export ALTALANDI_API_KEY=...        # get one at https://altalandi.is
+//   altalandi "Make sure to reach out to us today."
+//   echo "some text" | altalandi --domain marketing
+//
+// stdout = the refined text (so you can pipe it); stderr = nativeness score,
+// meaning verdict, API warnings, and the diff.
+
+import { refine } from "./client.mjs";
+
+const args = process.argv.slice(2);
+
+// Subcommands and meta flags are handled before anything that needs an API key
+// or input text. `altalandi update` checks for a newer CLI and skill and asks
+// before changing anything.
+let handled = false;
+if (args[0] === "update") {
+  handled = true;
+  const { runUpdate } = await import("./update.mjs");
+  const rest = args.slice(1);
+  if (rest.includes("-h") || rest.includes("--help")) { updateHelp(); process.exit(0); }
+  // exitCode, never process.exit(): the registry request can leave a socket
+  // mid-close, and exiting then aborts Node on Windows with a libuv assertion
+  // (UV_HANDLE_CLOSING). The refine path below exits the same way for the
+  // same reason.
+  process.exitCode = await runUpdate({
+    check: rest.includes("--check"),
+    yes: rest.includes("--yes") || rest.includes("-y"),
+    skillOnly: rest.includes("--skill-only"),
+  });
+}
+if (!handled && (args.includes("-v") || args.includes("--version"))) {
+  const { currentVersion } = await import("./update.mjs");
+  console.log(await currentVersion());
+  process.exit(0);
+}
+
+function updateHelp() {
+  console.log(`altalandi update — check for a newer version and update if you agree
+
+Usage:
+  altalandi update            check, then ask before updating the CLI and the /altalandi skill
+  altalandi update --check    only report; never change anything
+  altalandi update --yes      update without asking (for scripts that already have consent)
+
+Nothing changes without consent. Without a terminal to ask in (agents, CI,
+pipes) and without --yes, it only reports what is available.
+
+Exit codes: 0 up to date or updated · 10 an update is available but was not
+applied · 1 the check or the update failed.`);
+}
+
+if (!handled) {
+const opts = { domain: "general", register: "neutral", json: false, fast: false };
+const positional = [];
+for (let i = 0; i < args.length; i++) {
+  const a = args[i];
+  if (a === "-h" || a === "--help") { help(); process.exit(0); }
+  else if (a === "--json") opts.json = true;
+  else if (a === "--fast") opts.fast = true;
+  else if (a === "--domain") opts.domain = args[++i];
+  else if (a === "--register") opts.register = args[++i];
+  else if (a === "--base-url") opts.baseUrl = args[++i];
+  else if (a === "--key") opts.key = args[++i];
+  else positional.push(a);
+}
+
+function help() {
+  console.log(`altalandi — native Icelandic from your terminal
+
+Usage:
+  altalandi "text to refine"
+  echo "text" | altalandi
+  altalandi --domain marketing --register warm "text"
+
+Commands:
+  altalandi update     check for a newer version and update if you agree
+  altalandi --version  print the installed version
+
+Options:
+  --domain     general | marketing | data-analysis | childrens-fiction  (default general)
+  --register   formal | neutral | warm  (default neutral)
+  --fast       no polish, no nativeness score, no meaning gate — normally one writer call
+               (structured input can still add a structure-preserving retry)
+  --json       print the full JSON response
+  --base-url   API base  (default $ALTALANDI_BASE_URL or https://altalandi.is/api)
+
+stdout = refined text; stderr = nativeness / meaning / warnings / diff.
+Without --fast, false/null meaning verification exits 3 after printing the response.`);
+}
+
+function readStdin() {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) return resolve("");
+    let d = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (c) => (d += c));
+    process.stdin.on("end", () => resolve(d));
+  });
+}
+
+const baseUrl = (opts.baseUrl || process.env.ALTALANDI_BASE_URL || "https://altalandi.is/api").replace(/\/$/, "");
+const key = opts.key || process.env.ALTALANDI_API_KEY || process.env.ALTALANDI_KEY;
+
+if (opts.key) {
+  console.error("⚠ --key is deprecated because command arguments can leak through shell history/process listings; load ALTALANDI_API_KEY instead.");
+}
+
+const text = (positional.join(" ").trim()) || (await readStdin()).trim();
+if (!text) { console.error("No input. Pass text as an argument or pipe via stdin.  (altalandi --help)"); process.exit(2); }
+if (!key) { console.error("No API key. Load ALTALANDI_API_KEY securely (masked setup: https://altalandi.is/portal)."); process.exit(2); }
+
+const requestOptions = {
+  apiKey: key,
+  baseUrl,
+  domain: opts.domain,
+  register: opts.register,
+};
+// --fast disables every optional quality/verification pass. The writer can
+// still retry once when it drops document structure, as documented in --help.
+// Name every switch explicitly so a future server-default change cannot make
+// this client silently slower.
+if (opts.fast) {
+  requestOptions.preserveMeaning = false;
+  requestOptions.scoreNativeness = false;
+  requestOptions.onlyImprove = false;
+  requestOptions.polishPass = false;
+  requestOptions.scoring = "none";
+}
+
+try {
+  // refine() owns a single 300-second AbortController deadline across fetch
+  // and response-body parsing, matching the hosted package API.
+  const data = await refine(text, requestOptions);
+  const verificationFailed = !opts.fast && data.meaningPreserved !== true;
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+    if (verificationFailed) {
+      console.error("Meaning verification did not pass; JSON was printed, exiting with status 3.");
+    }
+  } else {
+    process.stdout.write(data.output + "\n");
+    const q = data.quality || {};
+    const meta = [];
+    if (q.nativenessScore != null) meta.push(`nativeness ${q.nativenessScore}/100`);
+    if (data.meaningPreserved === false) meta.push("⚠ MEANING DRIFT — returned the original");
+    else if (data.meaningPreserved === true) meta.push("meaning preserved");
+    else if (opts.fast) meta.push("meaning check skipped (--fast)");
+    else meta.push("⚠ MEANING UNVERIFIED — review before use");
+    if (meta.length) console.error("· " + meta.join(" · "));
+    for (const warning of Array.isArray(data.warnings) ? data.warnings : []) {
+      console.error(`⚠ ${warning}`);
+    }
+    for (const d of data.diffs || []) console.error(`  − ${d.before}\n  + ${d.after}  (${d.reason})`);
+  }
+
+  // stdout/JSON is intentionally written first so callers can inspect the
+  // server response, but guarded automation must not accept null/false as a
+  // verified success. --fast is the explicit opt-out from this contract.
+  if (verificationFailed) process.exitCode = 3;
+} catch (e) {
+  console.error("Request failed:", e.message);
+  process.exit(1);
+}
+}

package/client.d.ts

@@ -0,0 +1,113 @@
+export type SourceLang = "auto" | "en" | "is";
+export type Domain = "general" | "marketing" | "data-analysis" | "childrens-fiction";
+export type Register = "formal" | "neutral" | "warm";
+export type WriterTier = "standard" | "max";
+export type ScoringTier = "none" | "fast" | "rigorous";
+
+export interface GlossaryTerm {
+  en: string;
+  is: string;
+  note?: string;
+}
+
+export interface FetchResponseLike {
+  ok: boolean;
+  status: number;
+  statusText?: string;
+  text(): Promise<string>;
+}
+
+export type FetchLike = (
+  url: string,
+  init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    signal: any;
+  },
+) => Promise<FetchResponseLike>;
+
+export interface RefineOptions {
+  sourceLang?: SourceLang;
+  domain?: Domain;
+  register?: Register;
+  preserveMeaning?: boolean;
+  scoreNativeness?: boolean;
+  /** IS-refine: keep the original unless improvement is verified. */
+  onlyImprove?: boolean;
+  /** Optional EN→IS monolingual polish pass; false by default. */
+  polishPass?: boolean;
+  writer?: WriterTier;
+  scoring?: ScoringTier;
+  glossary?: GlossaryTerm[];
+  returnDiffs?: boolean;
+  /** Defaults to ALTALANDI_API_KEY. Never put a key in source control. */
+  apiKey?: string;
+  /** Defaults to https://altalandi.is/api. */
+  baseUrl?: string;
+  /** Per-request timeout in milliseconds; defaults to 300000. */
+  timeoutMs?: number;
+  /** Optional fetch-compatible implementation, useful for controlled runtimes and tests. */
+  fetch?: FetchLike;
+}
+
+export interface RefineDiff {
+  before: string;
+  after: string;
+  layer: "L1" | "L2" | "L3";
+  reason: string;
+}
+
+export interface RefineQuality {
+  nativenessScore: number | null;
+  translationeseTells: string[];
+  iceBertScore: number | null;
+  morphologyOk: boolean | null;
+  calqueFlags: string[];
+  englishRemnants: string[];
+  encodingArtifacts: string[];
+}
+
+export interface RefineResult {
+  id: string;
+  output: string;
+  sourceLang: "en" | "is";
+  diffs: RefineDiff[];
+  quality: RefineQuality;
+  /** Only strict true is a completed verification; null means skipped/unavailable. */
+  meaningPreserved: boolean | null;
+  meaningNotes: string;
+  modelUsed: string;
+  tier?: { writer: WriterTier; scoring: ScoringTier };
+  billedTier?: { writer: WriterTier; scoring: ScoringTier };
+  warnings: string[];
+}
+
+export type VerifiedRefineResult = RefineResult & { meaningPreserved: true };
+
+export interface AltalandiErrorOptions {
+  code?: string;
+  status?: number;
+}
+
+export class AltalandiError extends Error {
+  readonly code: string;
+  readonly status?: number;
+  constructor(message: string, options?: AltalandiErrorOptions);
+}
+
+export class MeaningVerificationError extends AltalandiError {
+  readonly verdict: false | null;
+  constructor(verdict: boolean | null | undefined);
+}
+
+/** Refine text and return the full hosted API response. */
+export function refine(text: string, options?: RefineOptions): Promise<RefineResult>;
+
+/** Refine text and throw unless meaningPreserved is strict true. */
+export function refineVerified(text: string, options?: RefineOptions): Promise<VerifiedRefineResult>;
+
+/** Narrow an existing result to one with a verified meaning verdict. */
+export function assertMeaningVerified(
+  result: RefineResult,
+): asserts result is VerifiedRefineResult;

package/client.mjs

@@ -0,0 +1,208 @@
+const DEFAULT_BASE_URL = "https://altalandi.is/api";
+const DEFAULT_TIMEOUT_MS = 300_000;
+const REQUEST_FIELDS = [
+  "sourceLang",
+  "domain",
+  "register",
+  "preserveMeaning",
+  "scoreNativeness",
+  "onlyImprove",
+  "polishPass",
+  "writer",
+  "scoring",
+  "glossary",
+  "returnDiffs",
+];
+
+export class AltalandiError extends Error {
+  constructor(message, { code = "ALTALANDI_ERROR", status } = {}) {
+    super(message);
+    this.name = "AltalandiError";
+    this.code = code;
+    if (Number.isInteger(status)) this.status = status;
+  }
+}
+
+export class MeaningVerificationError extends AltalandiError {
+  constructor(verdict) {
+    const changed = verdict === false;
+    super(
+      changed
+        ? "Altalandi could not preserve the input meaning."
+        : "Altalandi did not return a verified meaning verdict.",
+      { code: changed ? "MEANING_NOT_PRESERVED" : "MEANING_UNVERIFIED" },
+    );
+    this.name = "MeaningVerificationError";
+    this.verdict = verdict === false ? false : null;
+  }
+}
+
+function env(name) {
+  if (typeof process === "undefined" || !process.env) return undefined;
+  return process.env[name];
+}
+
+function cleanText(value, secret = "") {
+  if (typeof value !== "string") return "";
+  let cleaned = value.replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/\s+/g, " ").trim();
+  if (secret) cleaned = cleaned.split(secret).join("[redacted]");
+  return cleaned.slice(0, 300);
+}
+
+function errorDetail(payload) {
+  const detail = payload?.detail;
+  if (typeof detail === "string") return detail;
+  if (Array.isArray(detail)) {
+    return detail
+      .map((entry) => (typeof entry?.msg === "string" ? entry.msg : ""))
+      .filter(Boolean)
+      .join("; ");
+  }
+  return "";
+}
+
+function requestBody(text, options) {
+  const body = { text };
+  for (const field of REQUEST_FIELDS) {
+    if (options[field] !== undefined) body[field] = options[field];
+  }
+  return body;
+}
+
+/**
+ * Refine English or Icelandic text through the hosted Altalandi API.
+ * Client settings (`apiKey`, `baseUrl`, `timeoutMs`, `fetch`) are never sent in
+ * the JSON body. The full API result is returned without weakening its verdict.
+ */
+export async function refine(text, options = {}) {
+  if (typeof text !== "string" || !text.trim()) {
+    throw new AltalandiError("Altalandi requires non-empty text.", { code: "INVALID_INPUT" });
+  }
+
+  const explicitKey = options.apiKey;
+  const selectedKey = explicitKey === undefined ? env("ALTALANDI_API_KEY") : explicitKey;
+  if (selectedKey !== undefined && typeof selectedKey !== "string") {
+    throw new AltalandiError("Altalandi apiKey must be a string.", { code: "INVALID_CONFIG" });
+  }
+  const apiKey = selectedKey?.trim();
+  if (!apiKey) {
+    throw new AltalandiError(
+      "No Altalandi API key. Set ALTALANDI_API_KEY or pass apiKey explicitly.",
+      { code: "MISSING_API_KEY" },
+    );
+  }
+
+  const selectedBaseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+  if (typeof selectedBaseUrl !== "string") {
+    throw new AltalandiError("Altalandi baseUrl must be a string.", { code: "INVALID_CONFIG" });
+  }
+  const baseUrl = selectedBaseUrl.trim().replace(/\/+$/, "");
+  if (!baseUrl) {
+    throw new AltalandiError("Altalandi baseUrl must not be empty.", { code: "INVALID_CONFIG" });
+  }
+
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new AltalandiError("Altalandi timeoutMs must be a positive number.", {
+      code: "INVALID_CONFIG",
+    });
+  }
+
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function") {
+    throw new AltalandiError("This runtime does not provide fetch.", { code: "INVALID_CONFIG" });
+  }
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    let response;
+    try {
+      response = await fetchImpl(`${baseUrl}/v1/refine`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify(requestBody(text, options)),
+        signal: controller.signal,
+      });
+    } catch {
+      if (controller.signal.aborted) {
+        throw new AltalandiError(`Altalandi timed out after ${timeoutMs} ms.`, {
+          code: "TIMEOUT",
+        });
+      }
+      throw new AltalandiError("Altalandi could not reach the API.", { code: "NETWORK_ERROR" });
+    }
+
+    let raw = "";
+    try {
+      raw = await response.text();
+    } catch {
+      if (controller.signal.aborted) {
+        throw new AltalandiError(`Altalandi timed out after ${timeoutMs} ms.`, {
+          code: "TIMEOUT",
+        });
+      }
+      if (response.ok) {
+        throw new AltalandiError("Altalandi could not read the API response.", {
+          code: "INVALID_RESPONSE",
+          status: response.status,
+        });
+      }
+      // The HTTP status remains useful when an error response has no readable body.
+    }
+
+    let payload;
+    if (raw) {
+      try {
+        payload = JSON.parse(raw);
+      } catch {
+        if (response.ok) {
+          throw new AltalandiError("Altalandi returned an invalid JSON response.", {
+            code: "INVALID_RESPONSE",
+            status: response.status,
+          });
+        }
+      }
+    }
+
+    if (!response.ok) {
+      const status = Number.isInteger(response.status) ? response.status : 0;
+      const statusText = cleanText(response.statusText);
+      const detail = cleanText(errorDetail(payload), apiKey);
+      const suffix = detail || statusText;
+      throw new AltalandiError(
+        `Altalandi API request failed (${status || "unknown status"})${suffix ? `: ${suffix}` : "."}`,
+        { code: "API_ERROR", status },
+      );
+    }
+
+    if (!payload || typeof payload !== "object" || Array.isArray(payload) || typeof payload.output !== "string") {
+      throw new AltalandiError("Altalandi returned an invalid response shape.", {
+        code: "INVALID_RESPONSE",
+        status: response.status,
+      });
+    }
+
+    return payload;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+/** Assert that an existing result carries a completed, positive meaning check. */
+export function assertMeaningVerified(result) {
+  if (result?.meaningPreserved !== true) {
+    throw new MeaningVerificationError(result?.meaningPreserved);
+  }
+  return result;
+}
+
+/** Request meaning verification and reject unless the API returns strict true. */
+export async function refineVerified(text, options = {}) {
+  const result = await refine(text, { ...options, preserveMeaning: true });
+  assertMeaningVerified(result);
+  return result;
+}

package/package.json

@@ -1,17 +1,55 @@
-{
-  "name": "altalandi",
-  "version": "0.1.0",
-  "description": "Turn English or stiff/AI-translated Icelandic into native-sounding Icelandic from your terminal — via the Altalandi API, with a meaning-preservation check.",
-  "type": "module",
-  "bin": { "altalandi": "./altalandi.mjs" },
-  "files": ["altalandi.mjs", "README.md", "LICENSE"],
-  "keywords": [
-    "icelandic", "íslenska", "translation", "translationese", "nlp",
-    "altalandi", "cli", "i18n", "localization", "language"
-  ],
-  "homepage": "https://altalandi.is",
-  "repository": { "type": "git", "url": "git+https://github.com/pbidhjorvar/ritvit.git", "directory": "tools/cli" },
-  "bugs": { "url": "https://github.com/pbidhjorvar/ritvit/issues" },
-  "engines": { "node": ">=18" },
-  "license": "MIT"
-}
+{
+  "name": "altalandi",
+  "version": "0.2.0",
+  "description": "Hosted Altalandi API client and CLI for native-sounding Icelandic with meaning verification.",
+  "type": "module",
+  "main": "./client.mjs",
+  "types": "./client.d.ts",
+  "exports": {
+    ".": {
+      "types": "./client.d.ts",
+      "import": "./client.mjs",
+      "default": "./client.mjs"
+    }
+  },
+  "bin": {
+    "altalandi": "altalandi.mjs"
+  },
+  "files": [
+    "altalandi.mjs",
+    "update.mjs",
+    "skill/SKILL.md",
+    "client.mjs",
+    "client.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/cli.test.mjs test/client.test.mjs test/update.test.mjs"
+  },
+  "keywords": [
+    "icelandic",
+    "íslenska",
+    "translation",
+    "translationese",
+    "nlp",
+    "altalandi",
+    "cli",
+    "i18n",
+    "localization",
+    "language"
+  ],
+  "homepage": "https://altalandi.is",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pbidhjorvar/ritvit.git",
+    "directory": "tools/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/pbidhjorvar/ritvit/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}

package/skill/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: altalandi
+description: >-
+  MANUAL COMMAND — only run when the user explicitly invokes /altalandi. Do NOT
+  trigger automatically, and do not use it proactively on Icelandic writing tasks.
+  When invoked: refine English or stiff/AI-translated Icelandic into native
+  Icelandic via the Altalandi API, with a meaning-preservation check.
+---
+
+# Altalandi — native Icelandic, with a meaning guarantee
+
+Altalandi is a guarded pipeline, not a single model call: a frontier LLM rewrites
+to native register, a rule proofreader cleans up, then a validation gate checks
+meaning (back-translation **plus** deterministic invariants — numbers, dates,
+negation, legal force, names) and a **candidate veto** refuses any rewrite the
+pipeline itself has flagged as broken (invented words, a quoted defect, mojibake).
+Every change comes back as a diff with the reason.
+
+## How to call it
+
+When the user runs `/altalandi`, refine the target text via the API.
+
+1. **CLI, always with `--json`** — `npx altalandi --json "<text>"`. Flags:
+   `--domain`, `--register`. Needs `ALTALANDI_API_KEY` in the env.
+   **Use `--json` from an agent.** When a rewrite is refused, the plain-text mode
+   prints the reason as a `⚠` warning on stderr, but it also prints "meaning
+   preserved" and exits 0 — easy for an agent to misread as success. The JSON
+   carries `rewriteAttempted` and `rejectionReason`, which are unambiguous.
+   Run `npx altalandi update` now and then to get the latest CLI and this skill.
+2. **HTTP** — `POST https://altalandi.is/api/v1/refine` with
+   `Authorization: Bearer $ALTALANDI_API_KEY` and body `{ "text": "...", ... }`.
+
+(Do NOT rely on an MCP tool here — an MCP `refine_icelandic` tool is always available
+to the model, which defeats manual-only invocation. This command calls the CLI/HTTP
+directly so it only runs when you ask.)
+
+Auth: set **`ALTALANDI_API_KEY`** once in the shell env (or your project's `.env`).
+Existing `rtv_…` keys keep working — there is no rotation. Mint or view keys at
+https://altalandi.is/portal. Machine-readable docs: https://altalandi.is/llms-full.txt
+and https://altalandi.is/api/openapi.json.
+
+## Parameters
+
+- `text` (required) — the text to refine (English or Icelandic; auto-detected).
+- `domain` — `general` | `marketing` | `data-analysis` | `childrens-fiction`.
+- `register` — `formal` | `neutral` | `warm`.
+- `sourceLang` — `auto` (default) | `en` | `is`.
+
+## The non-negotiable contract — read the outcome, not one field
+
+An Icelandic→Icelandic call ends in one of three ways. Tell them apart before you
+use the output:
+
+| outcome | how to recognise it |
+|---|---|
+| **Rewritten and verified** | `output` differs from your text, `meaningPreserved: true`, `rejectionReason` empty |
+| **Rewrite refused — original returned** | `rewriteAttempted: true` and `rejectionReason` set. Causes: `MEANING DRIFT`, `HARD INVARIANT LOST`, `UNVERIFIED`, or `CANDIDATE VETO` (then `candidateVetoFired: true`, `candidateVetoSignal` says why) |
+| **Already fine — nothing to change** | `rewriteAttempted: false` |
+
+- **`meaningPreserved` alone is not enough.** A vetoed rewrite returns your
+  original with `meaningPreserved` still `true`: the meaning check passed, but the
+  rewrite was broken in another way. Check `rewriteAttempted` and `rejectionReason`.
+- `meaningPreserved: null` means **unverified**, not safe. For Icelandic input the
+  original comes back; for English input the translation comes back marked
+  unverified — do not present it as verified.
+- **When the original comes back, say so.** Don't report "Altalandi improved
+  this" when it declined to.
+- **Show the diffs.** When you apply Altalandi's output, surface what changed and
+  why, never silently replace the user's text.
+
+## The nativeness score is a hint, not a verdict
+
+`quality.nativenessScore` and `translationeseTells` point at likely problems, but
+the score has been measured to be confidently wrong in both directions: it gave a
+rewrite containing an invented word 82/100, and a perfectly fine rewrite 18/100.
+Treat a low score as "look at the tells", never as proof of bad Icelandic — and
+never as permission to override a refusal. A tell that **quotes** a specific phrase
+is far more trustworthy than the number.
+
+## When to use it
+
+- Producing or polishing user-facing Icelandic (web copy, UI strings, emails,
+  product text, children's prose).
+- You translated something to Icelandic and want it to not "sound translated".
+- Many strings at once: `POST /refine/batch`.
+
+## When NOT to use it
+
+- Non-Icelandic output. Code, identifiers, or data that must stay literal. Quotes
+  you must preserve verbatim (it may rephrase — check the diff).
+
+## `--fast` removes the safety net
+
+`--fast` (`scoreNativeness:false`, `scoring:"none"`) skips the meaning gate **and**
+leaves the candidate veto blind: with no BÍN morphology check and no nativeness
+tells, it cannot catch an invented or wrong word. Only mojibake is still caught.
+Use it only for throwaway text you will read yourself — never for anything shipped.
+
+## Notes
+
+- Usage is metered by a daily **word budget** per key (default 10,000 words/day;
+  429 when spent, resets 00:00 UTC).
+- A full call makes several model passes and is slower; that is the price of the
+  checks above.
+- Data is processed and discarded — not stored or trained on.

package/update.mjs

@@ -0,0 +1,271 @@
+// `altalandi update` — check for a newer CLI, ask before installing it, then
+// offer to install or refresh the /altalandi skill for Claude Code.
+//
+// Nothing is ever changed without consent. Interactive terminals get a y/N
+// prompt; non-interactive callers (agents, CI, pipes) are only told what is
+// available, unless they pass --yes, which is itself the explicit consent.
+//
+// Zero dependencies, like the rest of the CLI.
+
+import { spawn } from "node:child_process";
+import { copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { existsSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+
+export const PACKAGE = "altalandi";
+export const REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE}/latest`;
+
+// Exit codes. 10 is deliberately distinct from the refine command's 1/2/3 so a
+// script can tell "an update exists" apart from "something failed".
+export const EXIT_OK = 0;
+export const EXIT_CHECK_FAILED = 1;
+export const EXIT_UPDATE_AVAILABLE = 10;
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+export const BUNDLED_SKILL = path.join(HERE, "skill", "SKILL.md");
+
+export async function currentVersion() {
+  const pkg = JSON.parse(await readFile(path.join(HERE, "package.json"), "utf8"));
+  return pkg.version;
+}
+
+/** Semver-ish compare: -1 if a<b, 0 if equal, 1 if a>b. A prerelease sorts
+ *  before its release (0.2.0-beta < 0.2.0). */
+export function compareVersions(a, b) {
+  const parse = (v) => {
+    const [core, pre = ""] = String(v).trim().replace(/^v/, "").split("-", 2);
+    return { nums: core.split(".").map((n) => Number.parseInt(n, 10) || 0), pre };
+  };
+  const x = parse(a);
+  const y = parse(b);
+  for (let i = 0; i < 3; i++) {
+    const d = (x.nums[i] || 0) - (y.nums[i] || 0);
+    if (d !== 0) return d < 0 ? -1 : 1;
+  }
+  if (x.pre === y.pre) return 0;
+  if (!x.pre) return 1;
+  if (!y.pre) return -1;
+  return x.pre < y.pre ? -1 : 1;
+}
+
+export async function fetchLatestVersion({ fetchImpl = globalThis.fetch, timeoutMs = 8000 } = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetchImpl(REGISTRY_URL, {
+      signal: controller.signal,
+      headers: { accept: "application/json" },
+    });
+    if (!res.ok) throw new Error(`npm registry answered ${res.status}`);
+    const body = JSON.parse(await res.text());
+    if (!body || typeof body.version !== "string") throw new Error("npm registry returned no version");
+    return body.version;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+const norm = (p) => {
+  let out = path.resolve(p);
+  try { out = realpathSync(out); } catch { /* keep the resolved path */ }
+  return process.platform === "win32" ? out.toLowerCase() : out;
+};
+
+/** How is this copy of the CLI being run? That decides what "update" means.
+ *
+ *  npx    — lives in npm's _npx cache; there is nothing to install, but a bare
+ *           `npx altalandi` can keep reusing an old cached copy
+ *  global — `npm install -g altalandi`
+ *  local  — a project dependency
+ *  source — a checkout of the repository; npm cannot update that
+ */
+export function detectInstall({ scriptPath, globalRoot }) {
+  const p = norm(scriptPath);
+  const sep = path.sep === "\\" ? /[\\/]/ : /\//;
+  const parts = p.split(sep);
+  if (parts.includes("_npx")) return "npx";
+  const nm = parts.lastIndexOf("node_modules");
+  if (nm === -1) return "source";
+  if (globalRoot && p.startsWith(norm(globalRoot) + (process.platform === "win32" ? "\\" : "/"))) {
+    return "global";
+  }
+  return "local";
+}
+
+/** The exact command that updates this install. Constants only — never built
+ *  from user input. */
+export function updatePlan(kind, { projectDir } = {}) {
+  switch (kind) {
+    case "global":
+      return { cmd: "npm", args: ["install", "-g", `${PACKAGE}@latest`], show: `npm install -g ${PACKAGE}@latest` };
+    case "local":
+      return { cmd: "npm", args: ["install", `${PACKAGE}@latest`], cwd: projectDir, show: `npm install ${PACKAGE}@latest` };
+    case "npx":
+      return { cmd: "npx", args: ["--yes", `${PACKAGE}@latest`, "--version"], show: `npx ${PACKAGE}@latest` };
+    default:
+      return null;
+  }
+}
+
+/** Where Claude Code looks for personal skills. */
+export function skillTarget({ env = process.env, home = homedir() } = {}) {
+  const root = env.CLAUDE_CONFIG_DIR || path.join(home, ".claude");
+  return { root, file: path.join(root, "skills", PACKAGE, "SKILL.md") };
+}
+
+/** missing | current | outdated. `absent` means Claude Code itself is not set
+ *  up, in which case the skill is not offered at all — never create ~/.claude
+ *  for someone who does not use it. */
+export async function skillStatus({ bundled = BUNDLED_SKILL, target = skillTarget() } = {}) {
+  if (!existsSync(bundled)) return "unbundled";
+  if (!existsSync(target.root)) return "absent";
+  if (!existsSync(target.file)) return "missing";
+  const [a, b] = await Promise.all([readFile(bundled, "utf8"), readFile(target.file, "utf8")]);
+  const clean = (s) => s.replace(/\r\n/g, "\n").trim();
+  return clean(a) === clean(b) ? "current" : "outdated";
+}
+
+/** Install or refresh the skill. An existing copy is always backed up first:
+ *  people edit their skills, and an update must never silently eat that. */
+export async function writeSkill({ bundled = BUNDLED_SKILL, target = skillTarget(), now = new Date() } = {}) {
+  await mkdir(path.dirname(target.file), { recursive: true });
+  let backup = null;
+  if (existsSync(target.file)) {
+    const stamp = now.toISOString().replace(/[:.]/g, "-");
+    backup = `${target.file}.bak-${stamp}`;
+    await copyFile(target.file, backup);
+  }
+  await writeFile(target.file, await readFile(bundled, "utf8"), "utf8");
+  return { file: target.file, backup };
+}
+
+function run(plan) {
+  return new Promise((resolve) => {
+    // npm and npx are .cmd shims on Windows, which need a shell. The arguments
+    // are constants from updatePlan(), so there is nothing to inject.
+    const child = spawn(plan.cmd, plan.args, {
+      cwd: plan.cwd,
+      stdio: "inherit",
+      shell: process.platform === "win32",
+    });
+    child.on("error", () => resolve(1));
+    child.on("close", (code) => resolve(code ?? 1));
+  });
+}
+
+function npmGlobalRoot() {
+  return new Promise((resolve) => {
+    const child = spawn("npm", ["root", "-g"], { shell: process.platform === "win32" });
+    let out = "";
+    child.stdout?.setEncoding("utf8").on("data", (c) => { out += c; });
+    child.on("error", () => resolve(null));
+    child.on("close", () => resolve(out.trim() || null));
+  });
+}
+
+async function ask(question, { input = process.stdin, output = process.stderr } = {}) {
+  const rl = createInterface({ input, output });
+  try {
+    const answer = (await rl.question(`${question} [y/N] `)).trim().toLowerCase();
+    return answer === "y" || answer === "yes" || answer === "j" || answer === "já";
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * The whole command. Every side effect is injectable so it can be tested
+ * without touching npm, the network or the real home directory.
+ */
+export async function runUpdate(flags, io = {}) {
+  const log = io.log || ((m) => process.stderr.write(`${m}\n`));
+  const interactive = io.interactive ?? Boolean(process.stdin.isTTY && process.stderr.isTTY);
+  const confirm = io.confirm || ask;
+  const execute = io.run || run;
+  const target = io.skillTarget || skillTarget();
+  const bundled = io.bundledSkill || BUNDLED_SKILL;
+
+  // --check never changes anything. Without a terminal and without --yes there
+  // is nobody to ask, so the same rule applies: report, don't act.
+  const mayAct = !flags.check && (flags.yes || interactive);
+  const consent = async (q) => (flags.yes ? true : confirm(q));
+
+  const installed = io.currentVersion || await currentVersion();
+
+  if (!flags.skillOnly) {
+    let latest;
+    try {
+      latest = io.latestVersion || await fetchLatestVersion({ fetchImpl: io.fetch });
+    } catch (e) {
+      log(`Could not check for updates: ${e.message}`);
+      return EXIT_CHECK_FAILED;
+    }
+
+    if (compareVersions(installed, latest) < 0) {
+      const scriptPath = io.scriptPath || fileURLToPath(new URL("./altalandi.mjs", import.meta.url));
+      // `npm root -g` spawns npm, so only ask it when the answer matters: a copy
+      // inside some node_modules that is not npx's cache.
+      const inNodeModules = /[\\/]node_modules[\\/]/.test(scriptPath) && !/[\\/]_npx[\\/]/.test(scriptPath);
+      const globalRoot = io.globalRoot !== undefined ? io.globalRoot
+        : (inNodeModules ? await (io.npmGlobalRoot || npmGlobalRoot)() : null);
+      const kind = io.installKind || detectInstall({ scriptPath, globalRoot });
+      const plan = updatePlan(kind, { projectDir: io.projectDir || process.cwd() });
+      log(`A new version of ${PACKAGE} is available: ${installed} → ${latest}`);
+
+      if (!plan) {
+        log("This copy runs from a source checkout, so npm cannot update it. Pull the repository instead.");
+        return EXIT_UPDATE_AVAILABLE;
+      }
+      if (!mayAct) {
+        log(`Update with:  ${plan.show}`);
+        return EXIT_UPDATE_AVAILABLE;
+      }
+      if (!(await consent(`Update ${PACKAGE} to ${latest} now?`))) {
+        log(`Skipped. Update later with:  ${plan.show}`);
+        return EXIT_UPDATE_AVAILABLE;
+      }
+      log(`Running: ${plan.show}`);
+      const code = await execute(plan);
+      if (code !== 0) {
+        log(`Update failed (exit ${code}). Try running it yourself:  ${plan.show}`);
+        return EXIT_CHECK_FAILED;
+      }
+      log(`Updated to ${latest}.`);
+      // The skill that ships with the NEW version is the one worth installing,
+      // and this process is still the old one. Hand over to the new CLI.
+      const handoff = kind === "npx"
+        ? { cmd: "npx", args: ["--yes", `${PACKAGE}@latest`, "update", "--skill-only", ...(flags.yes ? ["--yes"] : [])] }
+        : { cmd: PACKAGE, args: ["update", "--skill-only", ...(flags.yes ? ["--yes"] : [])] };
+      await execute(handoff);
+      return EXIT_OK;
+    }
+    log(`${PACKAGE} ${installed} is up to date.`);
+  }
+
+  const status = await skillStatus({ bundled, target });
+  if (status === "unbundled" || status === "absent") return EXIT_OK;
+  if (status === "current") {
+    log("The /altalandi skill for Claude Code is up to date.");
+    return EXIT_OK;
+  }
+  const what = status === "missing"
+    ? `Install the /altalandi skill for Claude Code (${target.file})?`
+    : "Your /altalandi skill for Claude Code differs from this version. Replace it (your copy is backed up first)?";
+  if (!mayAct) {
+    log(status === "missing"
+      ? "The /altalandi skill for Claude Code is not installed. Run `altalandi update` in a terminal to install it."
+      : "Your /altalandi skill for Claude Code is out of date. Run `altalandi update` in a terminal to refresh it.");
+    return flags.skillOnly ? EXIT_OK : EXIT_UPDATE_AVAILABLE;
+  }
+  if (!(await consent(what))) {
+    log("Skill left unchanged.");
+    return EXIT_OK;
+  }
+  const written = await writeSkill({ bundled, target, now: io.now });
+  log(`Skill ${status === "missing" ? "installed" : "updated"}: ${written.file}`);
+  if (written.backup) log(`Previous copy saved as: ${written.backup}`);
+  return EXIT_OK;
+}