altalandi 0.4.0 → 0.5.0

package/report.mjs

@@ -1,114 +1,280 @@
-// Before/after for people: a terminal view and an optional Markdown report.
-//
-// The website shows each change inline; in a terminal or an editor the
-// before/after got lost. This module renders it the same way everywhere:
-//   beforeAfterText()  plain (or coloured) block for a terminal or a tool result
-//   reportMarkdown()   the report file: input, output, every change with its
-//                      reason, and the verdict
-//   writeReport()      writes it to ./altalandi-reports/ (or ALTALANDI_REPORT_DIR)
-//
-// Reports are opt-in (--report, or ALTALANDI_REPORT=1): they contain the text.
-
-import { mkdir, writeFile } from "node:fs/promises";
-import { join, resolve } from "node:path";
-
-const VERDICT = {
-  rewritten: "Endurskrifað og merking staðfest",
-  refused: "Endurskrift hafnað: upprunalega textanum skilað óbreyttum",
-  unchanged: "Engin breyting þurfti",
-  unverified: "Merking ekki staðfest: farðu yfir áður en þú notar textann",
-};
-
-export function outcomeOf(data) {
-  if (data?.rejectionReason) return "refused";
-  if (data?.meaningPreserved === false) return "refused";
-  if (data?.rewriteAttempted === false) return "unchanged";
-  if (data?.meaningPreserved !== true) return "unverified";
-  return "rewritten";
-}
-
-export function reportEnabled(flag) {
-  if (flag !== undefined && flag !== null) return Boolean(flag);
-  return ["1", "true", "yes"].includes(String(process.env.ALTALANDI_REPORT || "").toLowerCase());
-}
-
-const paint = (on) => ({
-  red: (s) => (on ? `\x1b[31m${s}\x1b[0m` : s),
-  green: (s) => (on ? `\x1b[32m${s}\x1b[0m` : s),
-  dim: (s) => (on ? `\x1b[2m${s}\x1b[0m` : s),
-  bold: (s) => (on ? `\x1b[1m${s}\x1b[0m` : s),
-});
-
-/** A before/after block with the list of changes. `color` adds ANSI colours. */
-export function beforeAfterText(input, data, { color = false } = {}) {
-  const c = paint(color);
-  const diffs = Array.isArray(data?.diffs) ? data.diffs : [];
-  const rule = (label) => c.dim(`── ${label} ${"─".repeat(Math.max(4, 40 - label.length))}`);
-  const lines = [
-    rule("Fyrir"), String(input ?? ""), "",
-    rule("Eftir"), String(data?.output ?? ""), "",
-    rule(`Breytingar (${diffs.length})`),
-  ];
-  if (!diffs.length) lines.push(c.dim("Engar breytingar."));
-  diffs.forEach((d, i) => {
-    lines.push(`${i + 1}. ${c.red("− " + String(d.before ?? "").trim())}`);
-    lines.push(`   ${c.green("+ " + String(d.after ?? "").trim())}`);
-    if (d.reason) lines.push(`   ${c.dim("↳ " + String(d.reason))}`);
-  });
-  const q = data?.quality || {};
-  lines.push("", c.bold(VERDICT[outcomeOf(data)]) + (q.nativenessScore != null ? c.dim(` · innfæddni ${q.nativenessScore}/100`) : ""));
-  return lines.join("\n");
-}
-
-const fence = (s) => {
-  const text = String(s ?? "");
-  const ticks = text.includes("```") ? "````" : "```";
-  return `${ticks}text\n${text}\n${ticks}`;
-};
-const cell = (s) => String(s ?? "").replace(/\|/g, "\\|").replace(/\r?\n/g, " ").trim();
-
-export function reportMarkdown(input, data, options = {}) {
-  const q = data?.quality || {};
-  const diffs = Array.isArray(data?.diffs) ? data.diffs : [];
-  const warnings = Array.isArray(data?.warnings) ? data.warnings : [];
-  const tier = data?.billedTier || data?.tier || {};
-  const when = new Date().toISOString().replace("T", " ").slice(0, 19);
-  const out = [
-    `# Altalandi: ${data?.id || "yfirlestur"}`,
-    "",
-    `| | |`, `|---|---|`,
-    `| Tími | ${when} UTC |`,
-    `| Niðurstaða | ${VERDICT[outcomeOf(data)]} |`,
-    `| Frummál | ${data?.sourceLang || "?"} |`,
-    `| Tegund texta | ${options.domain || "general"} |`,
-    `| Málsnið | ${options.register || "neutral"} |`,
-    `| Innfæddni | ${q.nativenessScore ?? "n/a"}/100 |`,
-    `| Ritill | ${tier.writer || "standard"} / ${tier.scoring || "?"} |`,
-    `| Auðkenni | ${data?.id || "?"} |`,
-    "",
-    "## Fyrir", "", fence(input), "",
-    "## Eftir", "", fence(data?.output), "",
-    `## Breytingar (${diffs.length})`, "",
-  ];
-  if (diffs.length) {
-    out.push("| # | Fyrir | Eftir | Ástæða | Lag |", "|---|---|---|---|---|");
-    diffs.forEach((d, i) => out.push(`| ${i + 1} | ${cell(d.before)} | ${cell(d.after)} | ${cell(d.reason)} | ${cell(d.layer)} |`));
-  } else {
-    out.push("Engar breytingar.");
-  }
-  if (data?.rejectionReason) out.push("", "## Af hverju var endurskriftinni hafnað", "", cell(data.rejectionReason));
-  if (warnings.length) out.push("", "## Viðvaranir", "", ...warnings.map((w) => `- ${cell(w)}`));
-  if (data?.meaningNotes) out.push("", "## Athugun á merkingu", "", cell(data.meaningNotes));
-  return out.join("\n") + "\n";
-}
-
-/** Write the report; returns its path. */
-export async function writeReport(input, data, options = {}, dir) {
-  const base = resolve(dir || process.env.ALTALANDI_REPORT_DIR || join(process.cwd(), "altalandi-reports"));
-  await mkdir(base, { recursive: true });
-  const stamp = new Date().toISOString().replace(/[-:]/g, "").replace("T", "-").slice(0, 15);
-  const id = String(data?.id || "yfirlestur").replace(/[^A-Za-z0-9_-]/g, "");
-  const path = join(base, `altalandi-${stamp}-${id}.md`);
-  await writeFile(path, reportMarkdown(input, data, options), "utf8");
-  return path;
-}
+// Before/after for people: a terminal view and an optional Markdown report.
+//
+// The website shows each change inline; in a terminal or an editor the
+// before/after got lost. This module renders it the same way everywhere:
+//   beforeAfterText()  plain (or coloured) block for a terminal or a tool result
+//   reportMarkdown()   the report file: input, output, every change with its
+//                      reason, and the verdict
+//   writeReport()      writes it to ./altalandi-reports/ (or ALTALANDI_REPORT_DIR)
+//
+// Reports are opt-in (--report, or ALTALANDI_REPORT=1): they contain the text.
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+const VERDICT = {
+  rewritten: "Endurskrifað og merking staðfest",
+  refused: "Endurskrift hafnað: upprunalega textanum skilað óbreyttum",
+  unchanged: "Engin breyting þurfti",
+  unverified: "Merking ekki staðfest: farðu yfir áður en þú notar textann",
+};
+
+export function outcomeOf(data) {
+  if (data?.rejectionReason) return "refused";
+  if (data?.meaningPreserved === false) return "refused";
+  if (data?.rewriteAttempted === false) return "unchanged";
+  if (data?.meaningPreserved !== true) return "unverified";
+  return "rewritten";
+}
+
+export function reportEnabled(flag) {
+  if (flag !== undefined && flag !== null) return Boolean(flag);
+  return ["1", "true", "yes"].includes(String(process.env.ALTALANDI_REPORT || "").toLowerCase());
+}
+
+const paint = (on) => ({
+  red: (s) => (on ? `\x1b[31m${s}\x1b[0m` : s),
+  green: (s) => (on ? `\x1b[32m${s}\x1b[0m` : s),
+  dim: (s) => (on ? `\x1b[2m${s}\x1b[0m` : s),
+  bold: (s) => (on ? `\x1b[1m${s}\x1b[0m` : s),
+});
+
+/** A before/after block with the list of changes. `color` adds ANSI colours. */
+export function beforeAfterText(input, data, { color = false } = {}) {
+  const c = paint(color);
+  const diffs = Array.isArray(data?.diffs) ? data.diffs : [];
+  const rule = (label) => c.dim(`── ${label} ${"─".repeat(Math.max(4, 40 - label.length))}`);
+  const lines = [
+    rule("Fyrir"), String(input ?? ""), "",
+    rule("Eftir"), String(data?.output ?? ""), "",
+    rule(`Breytingar (${diffs.length})`),
+  ];
+  if (!diffs.length) lines.push(c.dim("Engar breytingar."));
+  diffs.forEach((d, i) => {
+    lines.push(`${i + 1}. ${c.red("− " + String(d.before ?? "").trim())}`);
+    lines.push(`   ${c.green("+ " + String(d.after ?? "").trim())}`);
+    if (d.reason) lines.push(`   ${c.dim("↳ " + String(d.reason))}`);
+  });
+  const q = data?.quality || {};
+  lines.push("", c.bold(VERDICT[outcomeOf(data)]) + (q.nativenessScore != null ? c.dim(` · innfæddni ${q.nativenessScore}/100`) : ""));
+  return lines.join("\n");
+}
+
+const fence = (s) => {
+  const text = String(s ?? "");
+  const ticks = text.includes("```") ? "````" : "```";
+  return `${ticks}text\n${text}\n${ticks}`;
+};
+const cell = (s) => String(s ?? "").replace(/\|/g, "\\|").replace(/\r?\n/g, " ").trim();
+
+export function reportMarkdown(input, data, options = {}) {
+  const q = data?.quality || {};
+  const diffs = Array.isArray(data?.diffs) ? data.diffs : [];
+  const warnings = Array.isArray(data?.warnings) ? data.warnings : [];
+  const tier = data?.billedTier || data?.tier || {};
+  const when = new Date().toISOString().replace("T", " ").slice(0, 19);
+  const out = [
+    `# Altalandi: ${data?.id || "yfirlestur"}`,
+    "",
+    `| | |`, `|---|---|`,
+    `| Tími | ${when} UTC |`,
+    `| Niðurstaða | ${VERDICT[outcomeOf(data)]} |`,
+    `| Frummál | ${data?.sourceLang || "?"} |`,
+    `| Tegund texta | ${options.domain || "general"} |`,
+    `| Málsnið | ${options.register || "neutral"} |`,
+    `| Innfæddni | ${q.nativenessScore ?? "n/a"}/100 |`,
+    `| Ritill | ${tier.writer || "standard"} / ${tier.scoring || "?"} |`,
+    `| Auðkenni | ${data?.id || "?"} |`,
+    "",
+    "## Fyrir", "", fence(input), "",
+    "## Eftir", "", fence(data?.output), "",
+    `## Breytingar (${diffs.length})`, "",
+  ];
+  if (diffs.length) {
+    out.push("| # | Fyrir | Eftir | Ástæða | Lag |", "|---|---|---|---|---|");
+    diffs.forEach((d, i) => out.push(`| ${i + 1} | ${cell(d.before)} | ${cell(d.after)} | ${cell(d.reason)} | ${cell(d.layer)} |`));
+  } else {
+    out.push("Engar breytingar.");
+  }
+  if (data?.rejectionReason) out.push("", "## Af hverju var endurskriftinni hafnað", "", cell(data.rejectionReason));
+  if (warnings.length) out.push("", "## Viðvaranir", "", ...warnings.map((w) => `- ${cell(w)}`));
+  if (data?.meaningNotes) out.push("", "## Athugun á merkingu", "", cell(data.meaningNotes));
+  return out.join("\n") + "\n";
+}
+
+/** Write the report; returns its path. */
+export async function writeReport(input, data, options = {}, dir) {
+  const base = resolve(dir || process.env.ALTALANDI_REPORT_DIR || join(process.cwd(), "altalandi-reports"));
+  await mkdir(base, { recursive: true });
+  const stamp = new Date().toISOString().replace(/[-:]/g, "").replace("T", "-").slice(0, 15);
+  const id = String(data?.id || "yfirlestur").replace(/[^A-Za-z0-9_-]/g, "");
+  const path = join(base, `altalandi-${stamp}-${id}.md`);
+  await writeFile(path, reportMarkdown(input, data, options), "utf8");
+  return path;
+}
+
+// ── The review block ─────────────────────────────────────────────────────────
+// One Markdown block an agent pastes into the chat as it is: verdict, the text
+// before and after, every change with its reason, what the call cost and what
+// is left. `--review` prints it; the MCP tool returns it. The agent does not
+// rebuild it from JSON, so every run looks the same.
+
+const REJECTION = [
+  ["MEANING DRIFT", "merkingin breyttist í endurskriftinni"],
+  ["HARD INVARIANT LOST", "tala, dagsetning, nafn eða neitun hefði glatast"],
+  ["UNVERIFIED", "ekki tókst að staðfesta að merkingin héldist"],
+  ["CANDIDATE VETO", "endurskriftin reyndist ekki betri en frumtextinn"],
+];
+
+export function rejectionText(reason) {
+  const raw = String(reason ?? "").trim();
+  if (!raw) return "";
+  const hit = REJECTION.find(([code]) => raw.toUpperCase().startsWith(code));
+  return hit ? `${hit[1][0].toUpperCase()}${hit[1].slice(1)} (${raw})` : raw;
+}
+
+/** 1688 → "1.688" (Icelandic thousands separator). */
+export function formatInt(n) {
+  return String(Math.round(Number(n))).replace(/\B(?=(\d{3})+(?!\d))/g, ".");
+}
+
+/** 487.5 → "487,50 kr.", 500 → "500 kr." */
+export function formatIsk(n) {
+  const v = Math.round(Number(n) * 100) / 100;
+  const sign = v < 0 ? "−" : "";
+  const abs = Math.abs(v);
+  const whole = formatInt(Math.trunc(abs));
+  const cents = Math.round((abs - Math.trunc(abs)) * 100);
+  return `${sign}${whole}${cents ? "," + String(cents).padStart(2, "0") : ""} kr.`;
+}
+
+const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : null);
+
+/**
+ * What the call cost and what is left. `data.billing` (sent by newer engines)
+ * is exact; otherwise the cost is the balance difference between /v1/me
+ * before and after the call, which parallel calls on the same account blur.
+ */
+export function costLines(data, before, after) {
+  if (data?.test) return ["- Prófunarlykill: ekkert var rukkað og ekkert líkan keyrði."];
+  const b = data?.billing || {};
+  let charged = num(b.chargedIsk);
+  const exact = charged != null;
+  if (charged == null && num(before?.balanceIsk) != null && num(after?.balanceIsk) != null) {
+    charged = Math.round((before.balanceIsk - after.balanceIsk) * 100) / 100;
+  }
+  const units = num(b.units);
+  const unitsText = units != null ? ` · ${formatInt(units)} einingar` : "";
+  const lines = [];
+  if (charged == null) lines.push(`- Þetta kall: kostnaður óþekktur${unitsText}`);
+  else if (charged < 0) lines.push(`- Þetta kall: ekki hægt að reikna (inneignin breyttist á meðan)${unitsText}`);
+  else if (charged === 0) lines.push(b.paidFrom === "credit"
+    ? `- Þetta kall: 0 kr. af inneign${unitsText}`
+    : `- Þetta kall: 0 kr., ókeypis dagskammtur${unitsText}`);
+  else lines.push(`- Þetta kall: ${formatIsk(charged)} af inneign${exact ? "" : " (mismunur á inneign fyrir og eftir)"}${unitsText}`);
+
+  const balance = num(b.balanceIsk) ?? num(after?.balanceIsk);
+  const left = num(b.freeUnitsLeftToday) ?? num(after?.freeUnitsLeftToday);
+  const daily = num(after?.freeDailyUnits) ?? num(before?.freeDailyUnits);
+  const parts = [];
+  if (balance != null) parts.push(`inneign ${formatIsk(balance)}`);
+  if (left != null && daily != null) parts.push(`ókeypis eftir í dag ${formatInt(left)} af ${formatInt(daily)} einingum`);
+  else if (left != null) parts.push(`ókeypis eftir í dag ${formatInt(left)} einingar`);
+  else if (daily != null && daily > 0) parts.push(`ókeypis ${formatInt(daily)} einingar á dag`);
+  if (parts.length) lines.push(`- Staða: ${parts.join(" · ")}`);
+  else lines.push("- Staða: náðist ekki að sækja (`npx altalandi whoami`)");
+  if (balance != null && balance < 50) lines.push("- Bæta við inneign: https://altalandi.is/portal");
+  return lines;
+}
+
+function clip(text, max) {
+  const s = String(text ?? "");
+  if (!max || s.length <= max) return { text: s, clipped: false };
+  const cut = s.lastIndexOf(" ", max);
+  return { text: s.slice(0, cut > max * 0.6 ? cut : max).trimEnd() + " …", clipped: true };
+}
+
+// A quoted line that starts with "#" or ">" would render as a heading or a
+// nested quote; escape that first character.
+const quote = (s) => String(s).split(/\r?\n/)
+  .map((l) => (l.trim() ? `> ${l.replace(/^(\s*)([#>])/, "$1\\$2")}` : ">")).join("\n");
+const inline = (s) => String(s ?? "").replace(/\s+/g, " ").trim().replace(/([\\`*_~[\]<>|#])/g, "\\$1");
+
+/**
+ * The block to show the user. `before`/`after` are /v1/me responses (either
+ * may be null). Long texts are shortened for the chat; `fullTextAt` names the
+ * file that holds the whole output.
+ */
+export function reviewMarkdown(input, data, { before = null, after = null, maxChars = 1500, maxChanges = 30, fullTextAt = "" } = {}) {
+  const q = data?.quality || {};
+  const outcome = outcomeOf(data);
+  const diffs = Array.isArray(data?.diffs) ? data.diffs : [];
+  const score = q.nativenessScore != null ? ` · innfæddni ${q.nativenessScore}/100` : "";
+  const out = [`**Altalandi:** ${VERDICT[outcome]}${score}`, ""];
+
+  const inText = clip(input, maxChars);
+  out.push("**Fyrir**", quote(inText.text), "");
+  const same = String(data?.output ?? "").trim() === String(input ?? "").trim();
+  if (same) {
+    out.push("**Eftir**", outcome === "refused" ? "> Óbreytt: upprunalega textanum var skilað." : "> Óbreytt.", "");
+  } else {
+    const outText = clip(data?.output, maxChars);
+    out.push("**Eftir**", quote(outText.text), "");
+    if (outText.clipped || inText.clipped) {
+      out.push(`_Textinn er styttur hér${fullTextAt ? `; allur textinn er í ${fullTextAt}` : ""}._`, "");
+    }
+  }
+
+  if (outcome === "refused" && data?.rejectionReason) {
+    out.push(`**Af hverju óbreytt:** ${inline(rejectionText(data.rejectionReason))}`, "");
+  }
+
+  if (diffs.length) {
+    out.push(`**Breytingar (${diffs.length})**`);
+    diffs.slice(0, maxChanges).forEach((d, i) => {
+      out.push(`${i + 1}. „${inline(d.before)}“ → „${inline(d.after)}“`);
+      if (d.reason) out.push(`   Ástæða: ${inline(d.reason)}`);
+    });
+    if (diffs.length > maxChanges) out.push(`   … og ${diffs.length - maxChanges} í viðbót (sjá \`--report\`).`);
+    out.push("");
+  } else if (data?.diffStatus === "translation" || (data?.sourceLang === "en" && !same)) {
+    out.push("**Breytingar:** þýðing úr ensku, svo allur textinn er nýr.", "");
+  } else if (!same && data?.diffStatus === "unavailable") {
+    out.push("**Breytingar:** textinn breyttist en listi yfir breytingar fékkst ekki. Berðu saman fyrir og eftir.", "");
+  } else if (outcome !== "refused") {
+    out.push("**Breytingar:** engar.", "");
+  }
+
+  // The refusal reason is already shown above; its warning repeats it.
+  const code = REJECTION.find(([c]) => String(data?.rejectionReason ?? "").toUpperCase().startsWith(c))?.[0];
+  const warnings = (Array.isArray(data?.warnings) ? data.warnings : [])
+    .filter((w) => !String(w).startsWith("TEST KEY") && !(code && String(w).toUpperCase().startsWith(code)));
+  if (warnings.length && outcome !== "rewritten") {
+    out.push("**Athugasemdir**", ...warnings.slice(0, 3).map((w) => `- ${inline(w)}`), "");
+  }
+
+  const term = data?.terminology;
+  if (term?.dictionaries?.length) {
+    // Offered is not used: only a term verified in the output (by form or BÍN
+    // lemma) is "í textanum"; a stem-only match is "líklega"; an older engine
+    // without `usage` is listed as offered. The caller's glossary wins.
+    const usage = (x) => x.status === "overridden" ? "overridden"
+      : x.usage ?? (x.inOutput === true ? "verified" : x.inOutput === false ? "absent" : "unchecked");
+    const tag = { verified: "í textanum", probable: "líklega í textanum", absent: "ekki notað",
+                  unchecked: "boðið", overridden: "þitt orðasafn gekk framar" };
+    const shown = (term.terms || []).filter((x) => !x.inText);
+    out.push(`**Íðorð:** ${inline(term.dictionaries.map((d) => d.name).join(", "))} (úr Íðorðabanka Árnastofnunar)`);
+    if (!shown.some((x) => x.status !== "overridden")) out.push("- Ekkert íðorð var boðið fyrir þennan texta.");
+    shown.slice(0, 12).forEach((x) => {
+      const u = usage(x);
+      const is = u === "verified" || u === "probable" ? (x.used ?? x.is) : x.is;
+      out.push(`- ${inline(x.source)} → ${inline(is)} (${tag[u]})`);
+    });
+    if (shown.length > 12) out.push(`- … og ${shown.length - 12} í viðbót`);
+    out.push("");
+  }
+
+  out.push("**Kostnaður**", ...costLines(data, before, after));
+  if (data?.id) out.push(`- Auðkenni: \`${data.id}\``);
+  return out.join("\n") + "\n";
+}

package/skill/SKILL.md

@@ -1,117 +1,93 @@
----
-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 (every account gets 2,000 free words a day, and new accounts 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. Never silently replace the user's text. Apply changes
-  to files only after showing them, unless the user asked for that directly.
-
-## 4. Show the before and after
-
-After every call, show the user this, in the chat, before anything else:
-
-```text
-Fyrir:  <the text you sent, or its first lines if long>
-Eftir:  <output>
-Breytingar:
-1. − <before>  → + <after>   (<reason>)
-...
-<the verdict: rewritten and verified / refused, original returned / no change needed / unverified>
-```
-
-For a long text, show the first few changes and say how many there were in all.
-For a quick look in a terminal, `--diff` prints the same block (coloured) on stderr.
-
-**Reports (optional).** When the user wants a record, add `--report` (or they set
-`ALTALANDI_REPORT=1`): the CLI writes `./altalandi-reports/altalandi-<time>-<id>.md`
-with the input, the output, every change with its reason and layer, warnings and
-the verdict. Tell the user the path it prints (`Skýrsla: …`). Reports contain the
-text, so don't write them unless asked or the setting is on. The MCP tool takes
-`report: true` for the same thing.
-- `quality.nativenessScore` is a hint, not a verdict. It has been confidently wrong
-  in both directions; never use it to override a refusal.
-
-## 5. 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
+---
+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 Icelandic so it reads as if a native wrote
+it, checks that the meaning held, and lists every change with its reason. Each
+call is paid from the user's free daily units or their credit.
+
+**Follow this procedure exactly, every time.** The user must always see the same
+thing: the verdict, the text before and after, each change with its reason, what
+the call cost and what is left. Do not improvise scripts, parse the JSON
+yourself or summarise the result in your own words.
+
+## The procedure
+
+1. **Save the text** to a UTF-8 temporary file, e.g. `altalandi-in.txt` in the
+   system temp folder. Never put the text on the command line.
+2. **Run one command** and wait for it to finish:
+
+   ```bash
+   npx -y altalandi@latest --review --file <temp>/altalandi-in.txt --out <temp>/altalandi-out.txt
+   ```
+
+   Add `--domain marketing` for website and product copy, `--register formal`
+   for official text, `--register warm` for friendly customer messages.
+3. **Paste its stdout into your reply exactly as printed**, as the first thing in
+   your reply. It is Markdown: a verdict line, **Fyrir**, **Eftir**,
+   **Breytingar** (each change and its reason), **Kostnaður** (cost of this call,
+   balance and free units left) and the request id. Do not shorten, reorder,
+   translate or reword it.
+4. **Then act on the exit code:**
+
+   | Exit | What happened | What you do |
+   |---|---|---|
+   | 0 | rewritten and verified, or no change needed | the result is in `altalandi-out.txt`. If the user asked you to update a file, apply it from there; otherwise ask whether to apply it |
+   | 3 | the rewrite was refused or the meaning could not be verified | keep the user's original text. Say in one sentence that Altalandi left it unchanged and why (the block says why). Do not apply anything |
+   | 4 | out of credit | stop. The block shows the balance and the link to add credit. Do not retry |
+   | 2 | not logged in | connect (below), then run step 2 again |
+   | 1 | other error (network, too many calls) | the block says what happened. For "too many calls", wait a minute and retry once |
+
+5. **Stop there.** After the block and the action, at most one or two sentences
+   of your own.
+
+## Rules
+
+- **Never hand-edit the Icelandic and present it as Altalandi's.** If you think
+  something should still change, say so separately under a heading such as
+  "Mín tillaga (ekki yfirfarin af Altalandi)", or ask before running it again.
+- **One call per coherent text** (a page section, an email, one UI string). For
+  many strings, run them one by one, at most 4 at a time, and paste each block.
+  Keep keys, placeholders (`{name}`, `%s`), HTML and code out of the text you send.
+- **Product names and coined words** the meaning check cannot recognise can make
+  it refuse a rewrite (exit 3, "ekki tókst að staðfesta"). That is the safe
+  result: keep the original and tell the user.
+- **A long text** is shortened in the block; the whole result is in
+  `altalandi-out.txt`. Use `--report` when the user wants a full record: it
+  writes `./altalandi-reports/altalandi-<time>-<id>.md`, and the block shows
+  its path. Reports contain the text, so write them only when asked.
+- **Don't use `--fast`** for text people will read: it skips the meaning check.
+- If the user only wants spelling fixed and every other word kept, tell them
+  Altalandi may rephrase, and go through the changes with them.
+- Free use (the free daily units) is kept by Altalandi, with personal data
+  scrubbed, to improve the service; paid use is kept only with consent. Add
+  `--no-store` when the user asks that their text not be kept, or when it is
+  confidential.
+
+## Connect this computer (once)
+
+Only when a call exits with 2 (`Not logged in`):
+
+1. Run `npx -y altalandi@latest login` **in the background**. It waits up to 10
+   minutes.
+2. As soon as it prints a link (`https://altalandi.is/tengja?kodi=XXXX-XXXX`) and
+   a code, show both to the user. Tell them to sign in or create an account
+   (2,000 free units a day, and new accounts get 500 kr. of trial credit) and
+   click **Tengja**.
+3. When it prints `✓ Tengt sem <username>`, run step 2 of the procedure again.
+
+Never ask the user for an API key, and do not tell them to set
+`ALTALANDI_API_KEY`. `npx -y altalandi@latest whoami` shows the account, the
+balance and the free units at any time.
+
+Docs for building the API into an app: https://altalandi.is/agents.md