altalandi 0.6.0 → 0.6.2

package/client.d.ts

@@ -87,6 +87,10 @@ export interface RefineResult {
   warnings: string[];
   /** true when a test key made the call: no model ran, nothing was charged, output = input. */
   test?: boolean | null;
+  /** Characters billed (= billing.characters); absent from engines before character billing. */
+  characters?: number;
+  /** /v1 only: what the call cost and what is left (characters, chargedIsk, balanceIsk, freeCharsLeftToday, …). */
+  billing?: Record<string, unknown> | null;
 }
 
 export type VerifiedRefineResult = RefineResult & { meaningPreserved: true };
@@ -113,6 +117,59 @@ export class MeaningVerificationError extends AltalandiError {
 /** Refine text and return the full hosted API response. */
 export function refine(text: string, options?: RefineOptions): Promise<RefineResult>;
 
+export interface BatchItem {
+  /** Your key for the string; defaults to its index, as a string. */
+  id?: string;
+  /** At most 2,000 characters. */
+  text: string;
+}
+
+export interface BatchOptions {
+  sourceLang?: SourceLang;
+  domain?: Domain;
+  register?: Register;
+  preserveMeaning?: boolean;
+  scoreNativeness?: boolean;
+  onlyImprove?: boolean;
+  glossary?: GlossaryTerm[];
+  autoTerminology?: boolean;
+  contribute?: boolean;
+  apiKey?: string;
+  baseUrl?: string;
+  timeoutMs?: number;
+  fetch?: FetchLike;
+}
+
+export interface BatchItemResult {
+  id: string;
+  output: string;
+  sourceLang: "en" | "is";
+  diffs: RefineDiff[];
+  meaningCheck: "passed" | "changed" | "reverted" | "skipped" | "unavailable";
+  meaningPreserved: boolean | null;
+  warnings: string[];
+  /** true: refined in one model call with other strings, then checked on its own. */
+  packed: boolean;
+  /** Set when this string could not be refined: it came back unchanged and was not billed. */
+  error?: string | null;
+}
+
+export interface BatchResult {
+  id: string;
+  runUrl: string | null;
+  items: BatchItemResult[];
+  /** Characters billed for the whole batch (= billing.characters); absent from engines before character billing. */
+  characters?: number;
+  /** @deprecated The word equivalent of `characters` (= billing.units). */
+  units: number;
+  billing: Record<string, unknown> | null;
+  quality: RefineQuality;
+  warnings: string[];
+}
+
+/** Refine many short strings in one call (POST /v1/refine/batch). */
+export function refineBatch(items: BatchItem[], options?: BatchOptions): Promise<BatchResult>;
+
 /** Refine text and throw unless meaningPreserved is strict true. */
 export function refineVerified(text: string, options?: RefineOptions): Promise<VerifiedRefineResult>;
 

package/client.mjs

@@ -14,6 +14,18 @@ const REQUEST_FIELDS = [
   "returnDiffs",
   "contribute",
 ];
+// /v1/refine/batch takes fewer options: no writer/scoring tiers, polish or diffs switch.
+const BATCH_REQUEST_FIELDS = [
+  "sourceLang",
+  "domain",
+  "register",
+  "preserveMeaning",
+  "scoreNativeness",
+  "onlyImprove",
+  "glossary",
+  "autoTerminology",
+  "contribute",
+];
 
 export class AltalandiError extends Error {
   constructor(message, { code = "ALTALANDI_ERROR", status, retryAfterMs } = {}) {
@@ -80,16 +92,10 @@ function requestBody(text, options) {
   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" });
-  }
-
+/** POST a JSON body to `${baseUrl}${route}` with the key, base URL, timeout and
+ *  error handling every call shares. Returns the payload when `validShape`
+ *  accepts it; throws an AltalandiError (with status and Retry-After) otherwise. */
+async function post(route, body, options, validShape) {
   const explicitKey = options.apiKey;
   const selectedKey = explicitKey === undefined ? env("ALTALANDI_API_KEY") : explicitKey;
   if (selectedKey !== undefined && typeof selectedKey !== "string") {
@@ -129,13 +135,13 @@ export async function refine(text, options = {}) {
   try {
     let response;
     try {
-      response = await fetchImpl(`${baseUrl}/v1/refine`, {
+      response = await fetchImpl(`${baseUrl}${route}`, {
         method: "POST",
         headers: {
           "content-type": "application/json",
           authorization: `Bearer ${apiKey}`,
         },
-        body: JSON.stringify(requestBody(text, options)),
+        body: JSON.stringify(body),
         signal: controller.signal,
       });
     } catch {
@@ -190,7 +196,7 @@ export async function refine(text, options = {}) {
       );
     }
 
-    if (!payload || typeof payload !== "object" || Array.isArray(payload) || typeof payload.output !== "string") {
+    if (!payload || typeof payload !== "object" || Array.isArray(payload) || !validShape(payload)) {
       throw new AltalandiError("Altalandi returned an invalid response shape.", {
         code: "INVALID_RESPONSE",
         status: response.status,
@@ -203,6 +209,39 @@ export async function refine(text, options = {}) {
   }
 }
 
+/**
+ * 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" });
+  }
+  return post("/v1/refine", requestBody(text, options), options, (p) => typeof p.output === "string");
+}
+
+/**
+ * Refine many short strings in one call (POST /v1/refine/batch): at most 500
+ * items of at most 2,000 characters each, 20,000 characters together. Each item
+ * comes back with its own output and meaning verdict; an item with `error` came
+ * back unchanged and was not billed. Same key, limits and errors as refine().
+ */
+export async function refineBatch(items, options = {}) {
+  if (!Array.isArray(items) || !items.length
+    || !items.every((it) => it && typeof it.text === "string" && (it.id === undefined || typeof it.id === "string"))) {
+    throw new AltalandiError("Altalandi refineBatch requires a non-empty list of { id?, text } items.", {
+      code: "INVALID_INPUT",
+    });
+  }
+  const body = { items: items.map((it) => (it.id === undefined ? { text: it.text } : { id: it.id, text: it.text })) };
+  for (const field of BATCH_REQUEST_FIELDS) {
+    if (options[field] !== undefined) body[field] = options[field];
+  }
+  return post("/v1/refine/batch", body, options, (p) => Array.isArray(p.items)
+    && p.items.every((it) => it && typeof it === "object" && typeof it.output === "string"));
+}
+
 /** Assert that an existing result carries a completed, positive meaning check. */
 export function assertMeaningVerified(result) {
   if (result?.meaningPreserved !== true) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "altalandi",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "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",

package/report.mjs

@@ -88,7 +88,7 @@ export function reportMarkdown(input, data, options = {}) {
     `| Málsnið | ${options.register || "neutral"} |`,
     `| Innfæddni | ${q.nativenessScore ?? "n/a"}/100 |`,
     `| Ritill | ${tier.writer || "standard"} / ${tier.scoring || "?"} |`,
-    `| Auðkenni | ${data?.id || "?"} |`,
+    `| Auðkenni | ${data?.runUrl ? `[${data.id}](${data.runUrl})` : data?.id || "?"} |`,
     "",
     "## Fyrir", "", fence(input), "",
     "## Eftir", "", fence(data?.output), "",
@@ -154,6 +154,64 @@ export function formatIsk(n) {
 
 const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : null);
 
+// ── characters (stafir) ─────────────────────────────────────────────────────
+// Billing is in characters. Engines from before the switch send only word
+// units; those are shown as characters too (units × charsPerWord, rounded to
+// tens and marked "um"). The per-100-characters rate is never shown: amounts
+// in krónur and friendly equivalents (an A4 page) only.
+
+/** Characters per word, when an engine does not say (`charsPerWord`). */
+export const CHARS_PER_WORD = 6.5;
+/** A normal A4 page (display only). */
+export const CHARS_PER_A4_PAGE = 3200;
+
+const singular = (n) => { const k = Math.round(Math.abs(n)); return k % 10 === 1 && k % 100 !== 11; };
+
+/** 2690 → "2.690 stafir", 21 → "21 stafur". */
+export function formatChars(n) {
+  return `${formatInt(n)} ${singular(n) ? "stafur" : "stafir"}`;
+}
+
+/** One friendly equivalent: "um 7 A4-síður", "um 1 A4-síða", "innan við hálfa A4-síðu". */
+export function charsEquivalent(n) {
+  const pages = Math.round(Number(n) / CHARS_PER_A4_PAGE);
+  if (pages < 1) return "innan við hálfa A4-síðu";
+  return `um ${formatInt(pages)} ${singular(pages) ? "A4-síða" : "A4-síður"}`;
+}
+
+/** Word units of an older engine as characters, rounded to tens. */
+export function unitsToChars(units, charsPerWord = CHARS_PER_WORD) {
+  return Math.round((Number(units) * charsPerWord) / 10) * 10;
+}
+
+const perWord = (...from) => from.map((o) => num(o?.charsPerWord)).find((v) => v != null && v > 0) ?? CHARS_PER_WORD;
+
+/** The first source with a characters field wins; else the first with word
+ *  units, converted. → { n, approx } or null. */
+function charsOf(sources, charsKey, unitsKey, cpw) {
+  for (const s of sources) if (num(s?.[charsKey]) != null) return { n: s[charsKey], approx: false };
+  for (const s of sources) if (num(s?.[unitsKey]) != null) return { n: unitsToChars(s[unitsKey], cpw), approx: true };
+  return null;
+}
+
+/** Today's free allowance: "ókeypis eftir í dag 9.800 af 15.000 stöfum".
+ *  `billing` is a call's billing block, `after`/`before` the /v1/me answers
+ *  after and before it; any may be null. "" when nothing is known. */
+export function freeCharsText(billing, after = null, before = null) {
+  const cpw = perWord(billing, after, before);
+  const left = charsOf([billing, after], "freeCharsLeftToday", "freeUnitsLeftToday", cpw);
+  const daily = charsOf([after, before], "freeDailyChars", "freeDailyUnits", cpw);
+  // One "um", before the first converted number that is not 0.
+  const um = (c) => (c?.approx && c.n ? "um " : "");
+  if (left && daily) {
+    const [a, b] = um(left) ? ["um ", ""] : ["", um(daily)];
+    return `ókeypis eftir í dag ${a}${formatInt(left.n)} af ${b}${formatInt(daily.n)} ${singular(daily.n) ? "staf" : "stöfum"}`;
+  }
+  if (left) return `ókeypis eftir í dag ${um(left)}${formatChars(left.n)}`;
+  if (daily && daily.n > 0) return `ókeypis ${um(daily)}${formatChars(daily.n)} á dag`;
+  return "";
+}
+
 /**
  * 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
@@ -167,27 +225,24 @@ export function costLines(data, before, after) {
   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 chars = charsOf([b, data], "characters", "units", perWord(b, data, after, before));
+  const charsText = chars ? ` · ${chars.approx ? "um " : ""}${formatChars(chars.n)}` : "";
   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}`);
+  if (charged == null) lines.push(`- Þetta kall: kostnaður óþekktur${charsText}`);
+  else if (charged < 0) lines.push(`- Þetta kall: ekki hægt að reikna (inneignin breyttist á meðan)${charsText}`);
   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}`);
+    ? `- Þetta kall: 0 kr. af inneign${charsText}`
+    : `- Þetta kall: 0 kr., ókeypis dagskammtur${charsText}`);
+  else lines.push(`- Þetta kall: ${formatIsk(charged)} af inneign${exact ? "" : " (mismunur á inneign fyrir og eftir)"}${charsText}`);
 
   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 free = freeCharsText(b, after, before);
   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 (free) parts.push(free);
   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");
+  if (balance != null && balance < 50) lines.push("- Bæta við inneign: https://altalandi.is/stjornbord/inneign");
   return lines;
 }
 
@@ -279,7 +334,9 @@ export function reviewMarkdown(input, data, { before = null, after = null, maxCh
   }
 
   out.push("**Kostnaður**", ...costLines(data, before, after));
-  if (data?.id) out.push(`- Auðkenni: \`${data.id}\``);
+  // The run's own page: the text sent, the result, the checks and the review.
+  if (data?.runUrl) out.push(`- Verkið: ${data.runUrl}`);
+  else if (data?.id) out.push(`- Auðkenni: \`${data.id}\``);
   return out.join("\n") + "\n";
 }
 
@@ -327,6 +384,8 @@ export function batchReportMarkdown(summary) {
     `| Kaflar | ${count(t.passages)}: ${count(t.changed)} breyttir, ${count(t.unchangedPassages)} þurftu ekki breytingu, `
       + `${count(t.kept)} héldu frumtextanum, ${count(t.failed)} mistókust |`,
     `| Stafir sendir | ${count(t.characters)} |`,
+    ...(Number.isFinite(t.billedCharacters)
+      ? [`| Stafir rukkaðir | ${t.billedCharactersApprox ? "um " : ""}${count(t.billedCharacters)} |`] : []),
     `| Tegund texta | ${cell(summary?.domain || "general")} |`,
     `| Málsnið | ${cell(summary?.register || "neutral")} |`,
   ];

package/skill/SKILL.md

@@ -1,112 +1,187 @@
----
-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
-  a few 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.
-  For a whole folder, i18n catalog or website, use the folder run below instead.
-- **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.
-
-## A whole folder, i18n catalog or website
-
-One command refines every `.md`, `.txt`, `.html` and `.json` file in a folder,
-or a web page, or a site. It keeps code, URLs, placeholders, tags and JSON keys
-byte for byte, never writes to the input, and writes only changes whose meaning
-check passed.
-
-1. **Estimate first:** `npx -y altalandi@latest <folder or URL> --dry-run` (add
-   `--site` for a whole site). Show the user the estimate it prints: files,
-   passages, characters, units and the price if paid from credit.
-2. **Only when the user agrees,** run the same command with `--yes` in place of
-   `--dry-run`. The result goes to `<folder>-is` unless they name a place
-   (`--out <path>`).
-3. **Show the summary it prints and the report's path.** Exit 0: done. Exit 2:
-   done, but some passages kept their original text; the report lists them and
-   why. Exit 4: out of credit; the finished files are written, and the same
-   command finishes the rest after a top-up.
-
-## 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
+---
+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 characters 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.
+
+## Which way to call it
+
+- **A shell is available (Claude Code, Codex, a terminal):** use the command
+  line, below. It waits up to 5 minutes per call and handles long texts.
+- **No shell, only the Altalandi tools** (`refine_icelandic`,
+  `proofread_icelandic`, `get_refinement_status`, for example in claude.ai or
+  ChatGPT): use the tools, and follow "Long texts through the tools" below. The
+  tools cannot wait as long as the command line, so long texts go in parts.
+
+How long a call takes: a few seconds for a sentence, 10–30 seconds for a
+paragraph, and one to two minutes for a full page of English. A text that fails
+a check is rewritten once more, which can double that.
+
+## The procedure (command line)
+
+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 give it time to finish.** Set the shell tool's timeout
+   to 10 minutes (600000 ms) or run it in the background and wait for it. Never
+   stop it early and never start a second call for the same text while one is
+   running: Altalandi is still working and the second call is charged again.
+
+   ```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 characters left) and **Verkið**, the run's own page. Do not
+   shorten, reorder, translate or reword it. The run page shows the user the
+   text sent, the result and the checks, and lets them approve, reject or edit
+   the result there; point them to it when they want to review the work.
+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, timeout) | the block says what happened. For "too many calls", wait a minute and retry once. For a timeout, see "If a call times out" |
+
+5. **Stop there.** After the block and the action, at most one or two sentences
+   of your own.
+
+A document of several sections (more than about 3,000 characters) goes better
+through the folder run below: it refines and checks each passage on its own,
+and a passage that fails keeps its original without holding up the rest. Save
+the text as a `.md` file in an empty temporary folder and run the folder steps.
+
+## Long texts through the tools
+
+1. **Split the text into parts** at paragraph breaks, never inside a sentence:
+   at most **1,000 characters** a part for English, **1,500** for Icelandic.
+   Keep a heading with the paragraph under it. A list or a table stays in one
+   part when it fits.
+2. **Call the tool once per part,** at most 3 at a time, in order. Give every
+   part its own new `operationId` (a fresh UUID). Keep a note of which ID
+   belongs to which part.
+3. **Join the results in the original order** and give the user the whole text,
+   then each part's verdict and changes, as the tool returns them.
+4. **A part that is refused or unverified keeps its original text.** Say which
+   part, and why (the tool says why). Never rewrite it yourself.
+5. **Terms must match across parts.** If two parts translate the same term
+   differently, point it out and ask which to keep; do not quietly change one.
+
+## If a call times out
+
+A timeout means the answer did not reach you, not that the work stopped.
+Altalandi keeps working and charges for the call once.
+
+With the command line this is rare (it waits 5 minutes). If it happens, do
+not run the text again: tell the user, and that they can see whether it was
+charged at https://altalandi.is/stjornbord/notkun. With the tools:
+
+1. **Call `get_refinement_status` with the same `operationId`.** It costs
+   nothing.
+2. **Act on the status:**
+
+   | Status | What you do |
+   |---|---|
+   | `completed` with the result | use the result as if the call had answered |
+   | `completed` without the result | the call finished and was charged, but the text was not kept. Tell the user, and ask before sending that part again with a new `operationId` (it is charged again) |
+   | `pending` | still working. Wait 30 seconds and check again, up to 4 times. Do not send the text again meanwhile |
+   | `rejected` or `not_found` (`retryable: true`) | nothing was charged. Send the same part again with the **same** `operationId` |
+   | `uncertain` | do not retry. Tell the user the call may or may not have finished, and that they can check their usage at https://altalandi.is/stjornbord/notkun |
+
+3. **Never get round the protection** by inventing a new `operationId` for a
+   text that may still be running. It charges the user twice.
+4. **Next time, send smaller parts** (see above).
+
+## 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). Keep keys,
+  placeholders (`{name}`, `%s`), HTML and code out of the text you send. For a
+  whole folder, i18n catalog or website, use the folder run below instead.
+- **Many short strings** (UI strings, an i18n catalog, a list of labels or
+  messages): **never call Altalandi once per string.** Put them in a JSON file
+  (`{"key": "English text", …}`) in an empty temporary folder, or use the
+  project's existing catalog folder, and run the folder run below on that folder
+  (`--dry-run` first). It sends short strings together in batches, which is
+  cheaper and faster, and still checks each string on its own.
+- **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.
+- **Cost is in characters and krónur,** as the block and the estimate show it.
+  Never work out or quote a price per 100 characters.
+- If the user only wants spelling fixed and every other word kept, use the
+  `proofread_icelandic` tool where it is available. The command line rewrites:
+  tell the user it may rephrase, and go through the changes with them.
+- Every call from a signed-in account is kept in that account's history for
+  as long as they keep it, so the run page can show it; only the account and its team see it,
+  and it can be deleted on the page or switched off in Settings. Separately,
+  free use is kept, with personal data scrubbed, to improve the service; paid
+  use only with consent. Add `--no-store` when the user asks that their text
+  not be kept, or when it is confidential: the call is then kept nowhere, and
+  its run page shows only the figures.
+
+## A whole folder, i18n catalog or website
+
+One command refines every `.md`, `.txt`, `.html` and `.json` file in a folder,
+or a web page, or a site. It keeps code, URLs, placeholders, tags and JSON keys
+byte for byte, never writes to the input, and writes only changes whose meaning
+check passed.
+
+1. **Estimate first:** `npx -y altalandi@latest <folder or URL> --dry-run` (add
+   `--site` for a whole site). Show the user the estimate it prints: files,
+   passages, the characters billed and the price if paid from credit.
+2. **Only when the user agrees,** run the same command with `--yes` in place of
+   `--dry-run`, with the shell timeout set to 10 minutes or in the background.
+   The result goes to `<folder>-is` unless they name a place (`--out <path>`).
+3. **Show the summary it prints and the report's path.** Exit 0: done. Exit 2:
+   done, but some passages kept their original text; the report lists them and
+   why. Exit 4: out of credit; the finished files are written, and the same
+   command finishes the rest after a top-up.
+
+## 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
+   (a free daily allowance of characters, and 500 kr. of trial credit once they confirm their email) 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 characters left today at any time.
+
+Docs for building the API into an app: https://altalandi.is/agents.md