altalandi 0.4.0 → 0.6.0

package/skill/SKILL.md

@@ -1,117 +1,112 @@
----
-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
+  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

package/update.mjs

@@ -166,7 +166,9 @@ function npmGlobalRoot() {
   });
 }
 
-async function ask(question, { input = process.stdin, output = process.stderr } = {}) {
+/** A y/N question on stderr; only y/yes (or j/já) is a yes. Shared with the
+ *  folder and site runs, which ask before sending anything. */
+export 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();