altalandi 0.4.0 → 0.6.0

package/README.md

@@ -96,6 +96,9 @@ altalandi "Some English or Icelandic text."
 echo "some text" | altalandi --domain marketing
 altalandi --json "..."                 # full JSON response
 altalandi --fast "..."                 # skip the meaning + nativeness gates
+altalandi --diff --file draft.txt      # show before, after and every change with its reason
+altalandi --review --file in.txt --out out.txt   # for agents: one block to show as it is
+altalandi --report --file draft.txt    # also write a Markdown report to ./altalandi-reports/
 ```
 
 | flag | default | meaning |
@@ -103,8 +106,116 @@ altalandi --fast "..."                 # skip the meaning + nativeness gates
 | `--domain` | `general` | `general` \| `marketing` \| `data-analysis` \| `childrens-fiction` |
 | `--register` | `neutral` | `formal` \| `neutral` \| `warm` |
 | `--json` | off | print the full API response |
+| `--diff` | off | print the text before and after, then each change with its reason, on `stderr` (coloured in a terminal; `NO_COLOR` turns colour off) |
+| `--review` | off | print one Markdown block on `stdout`, made to be shown as it is: the verdict, the text before and after, each change with its reason, what the call cost and the balance and free units left. Exits on the outcome: `0` rewritten and verified or no change needed, `3` refused or unverified, `4` out of credit |
+| `--no-store` | off | send `contribute: false`: this text is never kept. Without it, free use (calls covered by the free daily units) is kept with personal data scrubbed, to improve the service; paid use is kept only with consent ([privacy](https://altalandi.is/personuvernd#textabanki)) |
+| `--out <file>` | | write the refined text to `<file>` (UTF-8); with `--review` the block names it when the text is shortened |
+| `--report` | off | also write `./altalandi-reports/altalandi-<time>-<id>.md`: input, output, a table of every change (before, after, reason, layer), warnings and the verdict |
+| `--report-dir <dir>` | | write the report to `<dir>` instead (implies `--report`) |
 | `--fast` | off | `preserveMeaning:false`, `scoreNativeness:false`, `onlyImprove:false`, `polishPass:false`, `scoring:"none"` — normally one model call (structured input can still add a structure-preserving retry) |
 
+## Folders, i18n catalogs and websites
+
+One command for a whole folder, one web page, or a site. The input is never
+written to.
+
+```bash
+altalandi ./docs                        # every .md .txt .html .json under ./docs → ./docs-is
+altalandi ./locales --out ./locales-is  # i18n catalogs: values only, placeholders kept
+altalandi ./docs --dry-run              # every passage and the estimate; sends nothing
+altalandi https://example.com/pricing --out pricing-is.md   # one page → Markdown
+altalandi https://example.com/docs/ --site --max-pages 50    # a site → ./example.com-is/
+```
+
+Each passage (a paragraph, list item, table cell, heading or string) is its own
+call. Everything outside the passages is written back byte for byte:
+
+| format | refined | never touched |
+|--------|---------|---------------|
+| Markdown | paragraphs, list items, table cells, heading text, front-matter `title`/`description`-style values | code blocks, inline code, URLs, link targets, HTML tags, front-matter keys, heading markup |
+| HTML | text in elements (inline tags travel as numbered markers and come back exactly) | tags, attributes, entities, `script`, `style`, `pre`, `code`, `translate="no"` |
+| JSON | string values of i18n catalogs | keys, `@`/`$` metadata, `{name}` `{{name}}` `%s` `%(name)s`, ICU plural/select structure, HTML in strings |
+| Text | paragraphs (re-wrapped to their width) and lines | |
+
+Passages with nothing to refine (code, numbers, URLs or placeholders alone) are
+skipped, and a passage that appears twice is sent once. `node_modules`, `.git`,
+`dist`, `build`, `altalandi-reports`, hidden files and folders and symlinks are
+skipped. JSON config (`package.json`, `tsconfig.json`, …) and JSON with numbers
+or booleans is copied unchanged; other file types are not copied.
+
+Pages are fetched one at a time with a User-Agent naming altalandi, only where
+robots.txt allows it for `altalandi` and for `*` (`Crawl-delay` is honoured).
+The readable part (`<main>` or `<article>`, else `<body>` without navigation,
+header, footer, sidebars, forms, scripts and hidden elements) becomes Markdown.
+`--site` reads `/sitemap.xml`, or follows links when there is none, staying on
+the same origin and under the URL's folder.
+
+**Cost and safety.** Before anything is sent, the CLI prints an estimate, priced
+from the public tariff:
+
+```text
+5 files, 24 passages, about 851 characters (23 calls: repeated passages are sent once).
+1 more file has nothing to refine and is copied unchanged.
+Billing: about 920 units (at least 40 a call), about 74 kr if paid from credit. The free allowance is 2,000 units a day.
+```
+
+Every call costs at least the per-call minimum, so many short strings cost more
+than their word count. In a terminal it asks before sending; without one (CI,
+agents) it sends nothing unless you pass `--yes`.
+
+| flag | default | meaning |
+|------|---------|---------|
+| `--out <path>` | `<folder>-is` | output folder, refused if it is the input, inside it or around it; for one page, the `.md` file |
+| `--dry-run` | off | list every passage and the estimate; send nothing, write nothing |
+| `--yes`, `-y` | off | send without asking |
+| `--max-chars <n>` | | files are sent in order until the next would go over n characters; the rest are neither sent nor written |
+| `--concurrency <n>` | `2` | calls at once, 1–4 |
+| `--site` / `--max-pages <n>` | off / `20` | read a site from the URL, up to n pages |
+| `--no-store` | off | keep none of the passages (free use is otherwise kept, scrubbed of personal data) |
+| `--json` | off | a machine-readable summary of every file and passage on stdout |
+
+A `429` waits as long as `Retry-After` asks (up to 5 minutes) and retries. A
+`402` stops the run cleanly: finished files are written, the rest are listed and
+not written; run the same command again after topping up.
+
+**Results.** Only verified changes are written. A passage keeps its original
+text when its meaning check did not pass (`meaningCheck` other than `passed`, or
+`meaningPreserved` not `true`), or when the refined text lost or changed code, a
+URL, a placeholder or a tag. One report next to the output
+(`altalandi-reports/altalandi-<time>-<input>.md`) lists every file and every
+changed passage with its meaning verdict, and the kept passages under their own
+heading with the unused suggestion and the reason.
+
+| exit | meaning |
+|------|---------|
+| `0` | done |
+| `2` | done, but some passages kept their original text (see the report) |
+| `4` | stopped: out of credit or allowance |
+| `1` | error, or not everything was done (a failed call, `--max-chars`, no `--yes`) |
+
+## Before and after
+
+`--diff` prints what the website shows inline, in the terminal:
+
+```text
+── Fyrir ───────────────────────────────────
+Vertu viss um að ná út til okkar ef þú hefur einhverjar spurningar.
+
+── Eftir ───────────────────────────────────
+Ekki hika við að hafa samband ef einhverjar spurningar vakna.
+
+── Breytingar (1) ──────────────────────────
+1. − Vertu viss um að ná út til okkar ef þú hefur einhverjar spurningar.
+   + Ekki hika við að hafa samband ef einhverjar spurningar vakna.
+   ↳ <the reason the engine gives>
+
+Endurskrifað og merking staðfest · innfæddni 91/100
+```
+
+`--report` (or `ALTALANDI_REPORT=1`) writes the same content as a Markdown file
+you can keep or share. Reports are off by default because they contain your text.
+`stdout` stays the refined text alone either way, so piping is unaffected.
+
 ## The meaning guarantee
 
 Altalandi never silently changes meaning. For Icelandic input where the rewrite
@@ -138,6 +249,9 @@ 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) |
+| `ALTALANDI_DIFF` | — | `1` = always print the before/after (as `--diff`) |
+| `ALTALANDI_REPORT` | — | `1` = always write a report (as `--report`) |
+| `ALTALANDI_REPORT_DIR` | `./altalandi-reports` | where reports go |
 
 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