altalandi 0.2.0 → 0.3.0

package/README.md

@@ -6,14 +6,18 @@ native wrote it—from your terminal or application. This package provides the
 [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 login        # once: opens altalandi.is, you sign in or sign up and click "Tengja"
 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`.
+`login` stores the key in your config directory (`%APPDATA%ltalandi` on
+Windows, `~/.config/altalandi` elsewhere) and installs the Claude Code skill, so
+afterwards you can just tell Claude *"write this in proper Icelandic with
+Altalandi"*. `altalandi whoami` shows the account and credit; `altalandi logout`
+forgets the key. On servers and in CI, set `ALTALANDI_API_KEY` instead; it takes
+precedence over the stored login. For agents, `--file draft.txt` avoids shell
+quoting entirely.
 
 `stdout` is the refined text (pipe it anywhere); `stderr` carries the 0–100
 nativeness score, the meaning verdict, every API warning, and the diff.
@@ -135,8 +139,8 @@ the explicit verification opt-out and exits 0 after a successful API response.
 | `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
+MIT licensed. Calls are paid from the account's prepaid credit (a 500 kr trial,
+then credit bought in the portal); a call the credit cannot cover exits with the
+server's `402 insufficient_balance` message. 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

@@ -2,7 +2,7 @@
 // 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
+//   npx altalandi login                 # once: connects this computer to your account
 //   altalandi "Make sure to reach out to us today."
 //   echo "some text" | altalandi --domain marketing
 //
@@ -10,6 +10,7 @@
 // meaning verdict, API warnings, and the diff.
 
 import { refine } from "./client.mjs";
+import { readCredentials, resolveKey, runLogin, runLogout, runWhoami } from "./auth.mjs";
 
 const args = process.argv.slice(2);
 
@@ -32,6 +33,22 @@ if (args[0] === "update") {
     skillOnly: rest.includes("--skill-only"),
   });
 }
+if (!handled && ["login", "setup", "logout", "whoami"].includes(args[0])) {
+  handled = true;
+  const rest = args.slice(1);
+  const flag = (name) => { const i = rest.indexOf(name); return i >= 0 ? rest[i + 1] : undefined; };
+  if (args[0] === "login" || args[0] === "setup") {
+    process.exitCode = await runLogin({
+      noBrowser: rest.includes("--no-browser"),
+      noSkill: rest.includes("--no-skill"),
+      baseUrl: flag("--base-url"),
+    });
+  } else if (args[0] === "logout") {
+    process.exitCode = await runLogout();
+  } else {
+    process.exitCode = await runWhoami({ json: rest.includes("--json"), baseUrl: flag("--base-url") });
+  }
+}
 if (!handled && (args.includes("-v") || args.includes("--version"))) {
   const { currentVersion } = await import("./update.mjs");
   console.log(await currentVersion());
@@ -65,6 +82,7 @@ for (let i = 0; i < args.length; 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 if (a === "--file") opts.file = args[++i];
   else positional.push(a);
 }
 
@@ -72,11 +90,17 @@ function help() {
   console.log(`altalandi — native Icelandic from your terminal
 
 Usage:
+  altalandi login                       connect this computer to your account (once)
   altalandi "text to refine"
+  altalandi --file draft.txt            read the text from a file (best for agents)
   echo "text" | altalandi
   altalandi --domain marketing --register warm "text"
 
 Commands:
+  altalandi login      open altalandi.is, sign in or sign up, approve; stores the key
+                       and installs the Claude Code skill (--no-skill, --no-browser)
+  altalandi whoami     show the account and balance behind the stored key
+  altalandi logout     forget the stored key on this computer
   altalandi update     check for a newer version and update if you agree
   altalandi --version  print the installed version
 
@@ -86,6 +110,7 @@ Options:
   --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
+  --file       read the text from a UTF-8 file instead of an argument
   --base-url   API base  (default $ALTALANDI_BASE_URL or https://altalandi.is/api)
 
 stdout = refined text; stderr = nativeness / meaning / warnings / diff.
@@ -102,16 +127,23 @@ function readStdin() {
   });
 }
 
-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 stored = readCredentials();
+const baseUrl = (opts.baseUrl || process.env.ALTALANDI_BASE_URL || stored?.baseUrl || "https://altalandi.is/api").replace(/\/$/, "");
+const { key } = resolveKey({ flag: opts.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();
+let text = positional.join(" ").trim();
+if (opts.file) {
+  const { readFile } = await import("node:fs/promises");
+  try { text = (await readFile(opts.file, "utf8")).replace(/^/, "").trim(); }
+  catch (e) { console.error(`Could not read ${opts.file}: ${e.message}`); process.exit(2); }
+}
+if (!text) text = (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); }
+if (!key) { console.error("Not logged in. Run once:  npx altalandi login   (or set ALTALANDI_API_KEY)"); process.exit(2); }
 
 const requestOptions = {
   apiKey: key,
@@ -164,6 +196,8 @@ try {
   if (verificationFailed) process.exitCode = 3;
 } catch (e) {
   console.error("Request failed:", e.message);
-  process.exit(1);
+  if (e.status === 402) console.error("→ Add credit at https://altalandi.is/portal (automatic top-up is available there).");
+  if (e.status === 401) console.error("→ The key is invalid or revoked. Run:  npx altalandi login");
+  process.exit(e.status === 402 ? 4 : 1);
 }
 }

package/auth.mjs

@@ -0,0 +1,215 @@
+// `altalandi login` — connect this computer to an Altalandi account once.
+//
+// Device login, the same pattern as `gh auth login`: the CLI asks the API for a
+// short code, the user opens altalandi.is/tengja, signs in or creates an
+// account, and approves. The CLI then receives a key for that account exactly
+// once and stores it in the user's config directory. The key never passes
+// through a chat, a prompt, the clipboard or shell history.
+//
+// Afterwards every `altalandi` call finds the key on its own, so an agent (the
+// Claude Code skill, a script) needs no environment variable at all.
+//
+// Zero dependencies, like the rest of the CLI.
+
+import { spawn } from "node:child_process";
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir, hostname } from "node:os";
+import path from "node:path";
+
+import { skillStatus, skillTarget, writeSkill } from "./update.mjs";
+
+export const DEFAULT_BASE_URL = "https://altalandi.is/api";
+
+/** Where the key is stored. ALTALANDI_CONFIG_DIR overrides (tests, CI). */
+export function configDir({ env = process.env, home = homedir(), platform = process.platform } = {}) {
+  if (env.ALTALANDI_CONFIG_DIR) return env.ALTALANDI_CONFIG_DIR;
+  if (platform === "win32") return path.join(env.APPDATA || path.join(home, "AppData", "Roaming"), "altalandi");
+  return path.join(env.XDG_CONFIG_HOME || path.join(home, ".config"), "altalandi");
+}
+
+export function credentialsFile(opts) {
+  return path.join(configDir(opts), "credentials.json");
+}
+
+/** The stored credentials, or null. Never throws. */
+export function readCredentials(opts) {
+  try {
+    const data = JSON.parse(readFileSync(credentialsFile(opts), "utf8"));
+    return data && typeof data.apiKey === "string" && data.apiKey ? data : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Key resolution order: explicit flag, ALTALANDI_API_KEY, stored login. */
+export function resolveKey({ flag, env = process.env, ...opts } = {}) {
+  if (flag) return { key: flag, source: "flag" };
+  const fromEnv = env.ALTALANDI_API_KEY || env.ALTALANDI_KEY;
+  if (fromEnv) return { key: fromEnv, source: "env" };
+  const stored = readCredentials({ env, ...opts });
+  return stored ? { key: stored.apiKey, source: "login", username: stored.username } : { key: "", source: "none" };
+}
+
+async function saveCredentials(data, opts) {
+  const dir = configDir(opts);
+  await mkdir(dir, { recursive: true });
+  const file = credentialsFile(opts);
+  await writeFile(file, JSON.stringify(data, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+  try { await chmod(file, 0o600); } catch { /* Windows: the per-user profile directory is the protection */ }
+  return file;
+}
+
+function clientName(env = process.env) {
+  const where = (hostname() || "").split(".")[0].slice(0, 24);
+  const who = env.CLAUDECODE || env.CLAUDE_CODE_ENTRYPOINT ? "Claude Code" : "altalandi CLI";
+  return where ? `${who} á ${where}` : who;
+}
+
+function openBrowser(url) {
+  try {
+    const [cmd, args] = process.platform === "win32" ? ["cmd", ["/c", "start", "", url]]
+      : process.platform === "darwin" ? ["open", [url]] : ["xdg-open", [url]];
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true, windowsHide: true });
+    child.on("error", () => {});
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+async function postJson(fetchImpl, url, body) {
+  const res = await fetchImpl(url, {
+    method: "POST",
+    headers: { "content-type": "application/json", accept: "application/json" },
+    body: JSON.stringify(body),
+  });
+  let data = {};
+  try { data = await res.json(); } catch { /* keep {} */ }
+  return { status: res.status, data };
+}
+
+/**
+ * Run the device login. Returns an exit code.
+ *   0 logged in · 1 failed or expired · 2 bad usage
+ */
+export async function runLogin(flags = {}, io = {}) {
+  const env = io.env || process.env;
+  const fetchImpl = io.fetch || globalThis.fetch;
+  const log = io.log || ((m) => console.error(m));
+  const base = (flags.baseUrl || env.ALTALANDI_BASE_URL || DEFAULT_BASE_URL).replace(/\/$/, "");
+  const wait = io.sleep || sleep;
+
+  let start;
+  try {
+    start = await postJson(fetchImpl, `${base}/v1/device/start`, { clientName: clientName(env) });
+  } catch (e) {
+    log(`Náði ekki sambandi við Altalandi (${e.message}).`);
+    return 1;
+  }
+  if (start.status !== 200 || !start.data.deviceCode) {
+    log(`Innskráning fór ekki af stað: ${start.data.detail || `HTTP ${start.status}`}`);
+    return 1;
+  }
+  const { deviceCode, userCode, verificationUriComplete, verificationUri, interval = 3, expiresIn = 600 } = start.data;
+
+  log("");
+  log("  Tengdu þessa tölvu við Altalandi-aðganginn þinn:");
+  log("");
+  log(`    1. Opnaðu   ${verificationUriComplete}`);
+  log(`    2. Skráðu þig inn eða stofnaðu aðgang (500 kr. prufuinneign fylgir)`);
+  log(`    3. Staðfestu kóðann   ${userCode}`);
+  log("");
+  log(`  (Connect this computer: open the link, sign in or sign up, confirm the code.`);
+  log(`   Code page: ${verificationUri})`);
+  log("");
+  if (!flags.noBrowser && !io.noBrowser) openBrowser(verificationUriComplete);
+  log("  Bíð eftir staðfestingu…");
+
+  const deadline = Date.now() + expiresIn * 1000;
+  let result = null;
+  while (Date.now() < deadline) {
+    await wait(Math.max(1, interval) * 1000);
+    let poll;
+    try {
+      poll = await postJson(fetchImpl, `${base}/v1/device/token`, { deviceCode });
+    } catch {
+      continue; // transient network error: keep waiting until the code expires
+    }
+    if (poll.status === 200 && poll.data.status === "approved") { result = poll.data; break; }
+    if (poll.status === 200 && poll.data.status === "pending") continue;
+    if (poll.status === 429) { await wait(10_000); continue; }
+    log(`  Kóðinn rann út eða var hafnað. Keyrðu \`altalandi login\` aftur.`);
+    return 1;
+  }
+  if (!result) {
+    log(`  Kóðinn rann út. Keyrðu \`altalandi login\` aftur.`);
+    return 1;
+  }
+
+  const file = await saveCredentials({
+    apiKey: result.apiKey,
+    username: result.username,
+    baseUrl: base === DEFAULT_BASE_URL ? undefined : base,
+    savedAt: new Date().toISOString(),
+  }, { env });
+  log("");
+  log(`  ✓ Tengt sem ${result.username}. Lykillinn er vistaður í ${file}`);
+
+  // Install or refresh the Claude Code skill — the point of logging in for most
+  // people. Only where Claude Code exists; never create ~/.claude for someone who
+  // does not use it. --no-skill opts out.
+  if (!flags.noSkill) {
+    const target = skillTarget({ env });
+    const status = await skillStatus({ target });
+    if (status === "missing" || status === "outdated") {
+      const { file: skillFile, backup } = await writeSkill({ target });
+      log(`  ✓ Claude Code-hæfnin „altalandi" sett upp: ${skillFile}${backup ? ` (eldri útgáfa afrituð í ${backup})` : ""}`);
+    } else if (status === "current") {
+      log(`  ✓ Claude Code-hæfnin „altalandi" er þegar uppfærð.`);
+    } else if (status === "absent") {
+      log(`  (Claude Code fannst ekki á þessari tölvu, svo hæfnin var ekki sett upp.)`);
+    }
+  }
+  log("");
+  log(`  Prófaðu:   altalandi "Make sure to reach out to us today."`);
+  log(`  Eða segðu Claude:  „Skrifaðu þetta á góðri íslensku með Altalandi."`);
+  return 0;
+}
+
+export async function runLogout(io = {}) {
+  const env = io.env || process.env;
+  const log = io.log || ((m) => console.error(m));
+  const file = credentialsFile({ env });
+  if (!existsSync(file)) { log("Engin vistuð innskráning."); return 0; }
+  await rm(file, { force: true });
+  log(`Innskráning fjarlægð (${file}). Lykillinn sjálfur er enn virkur þar til þú afturkallar hann á https://altalandi.is/portal`);
+  return 0;
+}
+
+export async function runWhoami(flags = {}, io = {}) {
+  const env = io.env || process.env;
+  const fetchImpl = io.fetch || globalThis.fetch;
+  const out = io.out || ((m) => console.log(m));
+  const log = io.log || ((m) => console.error(m));
+  const { key, source } = resolveKey({ flag: flags.key, env });
+  if (!key) { log("Ekki innskráð(ur). Keyrðu: npx altalandi login"); return 2; }
+  const stored = readCredentials({ env });
+  const base = (flags.baseUrl || env.ALTALANDI_BASE_URL || stored?.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, "");
+  let res;
+  try {
+    res = await fetchImpl(`${base}/v1/me`, { headers: { authorization: `Bearer ${key}`, accept: "application/json" } });
+  } catch (e) {
+    log(`Náði ekki sambandi við Altalandi (${e.message}).`);
+    return 1;
+  }
+  if (res.status === 401) { log("Lykillinn er ógildur eða afturkallaður. Keyrðu: npx altalandi login"); return 1; }
+  if (!res.ok) { log(`Villa: HTTP ${res.status}`); return 1; }
+  const me = await res.json();
+  if (flags.json) out(JSON.stringify({ ...me, keySource: source }, null, 2));
+  else out(`${me.username ?? "(lykill án aðgangs)"} · inneign ${me.balanceIsk ?? "—"} kr. · lykill ${me.keyId} (${source})`);
+  return 0;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "altalandi",
-  "version": "0.2.0",
-  "description": "Hosted Altalandi API client and CLI for native-sounding Icelandic with meaning verification.",
+  "version": "0.3.0",
+  "description": "Native-sounding Icelandic from your terminal or AI agent: one-time login, a Claude Code skill, and meaning verification.",
   "type": "module",
   "main": "./client.mjs",
   "types": "./client.d.ts",
@@ -17,6 +17,7 @@
   },
   "files": [
     "altalandi.mjs",
+    "auth.mjs",
     "update.mjs",
     "skill/SKILL.md",
     "client.mjs",
@@ -25,7 +26,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test test/cli.test.mjs test/client.test.mjs test/update.test.mjs"
+    "test": "node --test test/cli.test.mjs test/client.test.mjs test/update.test.mjs test/auth.test.mjs"
   },
   "keywords": [
     "icelandic",

package/skill/SKILL.md

@@ -1,105 +1,95 @@
----
-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.
+---
+name: altalandi
+description: >-
+  Turn English or stiff, translated or AI-written Icelandic into natural native
+  Icelandic through the Altalandi API, with a meaning check and a diff of every
+  change. Use when the user mentions Altalandi, or asks for text in proper,
+  natural, correct or native Icelandic ("á góðri íslensku", "á réttri íslensku",
+  "láttu þetta hljóma eðlilega á íslensku", "translate this into proper
+  Icelandic"), including website copy, UI strings, emails and documents meant for
+  Icelandic readers. Not for incidental Icelandic in conversation.
+---
+
+# Altalandi: native Icelandic, with a meaning check
+
+Altalandi rewrites English or stiff/AI-translated Icelandic into Icelandic that
+reads as if a native wrote it. It checks that the meaning survived (numbers,
+dates, names, negation, obligations and a back-translation) and returns every
+change with a reason. Each call is paid from the user's Altalandi credit.
+
+## 1. Make sure this computer is connected (once)
+
+Everything goes through the `altalandi` CLI, which finds the user's key by itself.
+If a call prints `Not logged in` (exit code 2), connect the computer:
+
+1. Run `npx -y altalandi@latest login` **in the background** (it waits up to 10
+   minutes for the user).
+2. Read its output as soon as it appears. It prints a link
+   (`https://altalandi.is/tengja?kodi=XXXX-XXXX`) and a code, and opens the
+   browser. Show the user the link and the code, and tell them to sign in or
+   create an account (new accounts get 500 kr. of trial credit) and click
+   **Tengja**.
+3. Wait for the command to finish. `✓ Tengt sem <username>` means done. Then
+   continue with the task.
+
+Never ask the user to paste an API key into the chat. If they have one and
+prefer it, they can set `ALTALANDI_API_KEY` themselves.
+
+## 2. Refine text
+
+Write the text to a UTF-8 temporary file and pass the file. Never put the text on
+the command line: quotes, `$`, backticks and Icelandic characters break shell
+quoting.
+
+```bash
+npx -y altalandi@latest --json --file /tmp/altalandi-in.txt
+```
+
+Options: `--domain general|marketing|data-analysis|childrens-fiction`,
+`--register formal|neutral|warm`. Pick `marketing` for website and product copy,
+`formal` for official or legal text, `warm` for friendly customer messages.
+
+One call per coherent text (a page section, an email, one UI string). For many
+strings, run them one by one or at most 4 at a time, and keep keys, placeholders
+(`{name}`, `%s`), HTML and code exactly as they were: send only the human text.
+
+## 3. Read the result correctly
+
+| Exit code | Meaning | What to do |
+|---|---|---|
+| 0 | done and verified | use `output`, show the diffs |
+| 3 | meaning not verified: JSON still printed | read the table below; don't present it as verified |
+| 4 | out of credit (`402 insufficient_balance`) | stop; tell the user to add credit at https://altalandi.is/portal. Don't retry |
+| 2 | not logged in / no input | step 1 |
+| 1 | other error (network, 429 usage limit) | on 429 wait for the time given and retry once; otherwise report it |
+
+For Icelandic input, one of three things happened. Tell them apart before using `output`:
+
+| Outcome | How to recognise it |
+|---|---|
+| **Rewritten and verified** | `output` differs from the input, `meaningPreserved: true`, `rejectionReason` empty |
+| **Rewrite refused, original returned** | `rewriteAttempted: true` and `rejectionReason` set (`MEANING DRIFT`, `HARD INVARIANT LOST`, `UNVERIFIED`, `CANDIDATE VETO`) |
+| **Already fine** | `rewriteAttempted: false` |
+
+- `meaningPreserved` alone is not enough: a vetoed rewrite returns the original with
+  `meaningPreserved: true`. Check `rewriteAttempted` and `rejectionReason`.
+- `meaningPreserved: null` means unverified, not safe. For English input the
+  translation still comes back; say it is unverified.
+- When the original comes back, say so. Don't claim Altalandi improved it.
+- Always show what changed (`diffs`: before, after, reason). Never silently replace
+  the user's text. Apply changes to files only after showing them, unless the user
+  asked for that directly.
+- `quality.nativenessScore` is a hint, not a verdict. It has been confidently wrong
+  in both directions; never use it to override a refusal.
+
+## 4. Good to know
+
+- Altalandi rewrites for natural Icelandic. If the user only wants spelling and
+  grammar fixed and every other word left alone, tell them it may rephrase, and
+  review the diffs with them.
+- `npx -y altalandi@latest whoami` shows the connected account and its credit.
+- Leave code, identifiers, legal quotations and anything that must stay verbatim
+  out of the text you send.
+- Don't use `--fast` for text people will read: it skips the meaning check.
+- Text is processed and discarded, not stored or used for training.
+- Docs for integrating the API into an app: https://altalandi.is/agents.md