yuno-proofreader 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2b9c1ba0d2da16cc90dd1280f5c90ed7174c16402def0aa09707495d0bccd0a2
+  data.tar.gz: 3c174ff4a4cf13f8864a1b10ff09374d488b4b14dd818569b1926a091c77b56d
+SHA512:
+  metadata.gz: cfa0b61cd10747628ce5dce680d3c2b1b01daaaeeb706ec936b80c71e576b7a581c5c43e0c86ed3254a8163b2efa9654806ff6877eca7e23b42b9b2bfdd8dd8c
+  data.tar.gz: e99babee2e1dae3e11f808048647fb6bd6b972e16ffe7f922c6f8bcefc5d1054093bb047f87fa8f834bdb21af00dc934792934aca9e1aa040be1f8ddafd48ad6

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## [0.1.0]
+2026/10/26
+
+First release. It is early, and details may still change before 1.0.
+
+- Reads your sitemap and language versions, and helps you set up your settings file.
+- Ranks your pages by importance and works out which are due for another audit, so the most important ones are checked most often.
+- Audits the pages of a website with an AI model (Gemini) and an independent second review, and lists the suggested fixes in a Google Sheet for manual review.
+- Checks that every suggestion quotes text that is really on the page, and closes suggestions whose text is gone from the live page.
+
+[0.1.0]: https://gitlab.com/alsen-ca/yuno-proofreader/-/tags/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sebastian Alsen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,435 @@
+# yuno-proofreader
+
+AI-powered website proofreader that collects suggestions in Google Sheets.
+
+It reads your public web pages, asks an AI model (only Gemini so far) to look for typos, grammar problems, HTML structure issues, SEO basics and differences between language versions, and lists the suggested fixes in a Google Sheet for you to review.
+Only Makes suggestions and doesn't do any actual changes to the website.
+
+## How it works
+
+1. Reads your sitemap and pairs each page with its language versions.
+2. Audits one page per run in two independent passes: a step-by-step audit, then a second review by a different model that has not seen the first result. A page that has not changed since its last complete audit is skipped without calling a model.
+3. Merges both answers, checks that every quoted text really appears on the page, and writes new suggestions to the sheet. Suggestions it already knows are not added again.
+4. On later runs, closes suggestions whose text is no longer on the live page.
+
+You review the sheet and mark each suggestion as `open`, `on staging`, `done` or `rejected`.
+
+## What you need
+
+- Ruby 4.0 or newer, or a container runtime such as Podman or Docker
+- An API key for a supported AI model provider (Gemini so far)
+- A Google Cloud service account with the Sheets API enabled, and a spreadsheet shared with that account
+- A sitemap on the site you want to check
+
+## Getting started
+
+```
+gem install yuno-proofreader
+yuno-proofreader init                     # asks about your site and writes proofreader.yml
+yuno-proofreader settings                 # what is still needed for an audit
+yuno-proofreader sitemap                  # check that your pages are found and paired by language
+```
+
+The commands that only read your site (`init`, `settings`, `sitemap`, `fetch` and `prompt`) need nothing more. The ones that use your sheet and your model need access, which lives outside `proofreader.yml`. You can put it in a `.env` file in the folder where you run the tool (see "Configuration"):
+
+```
+SPREADSHEET_ID=...
+GEMINI_API_KEY=...
+GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json
+```
+
+`SPREADSHEET_ID` is the part of your sheet's address between `/d/` and `/edit`. `GEMINI_API_KEY` is the API key of your model provider. `GOOGLE_APPLICATION_CREDENTIALS` points to the credentials file of a Google account that may edit the sheet, so share the sheet with that account as an editor. On Google Cloud it should not be needed, because the service account the job runs as is used instead. See "Connecting to Google". `yuno-proofreader init` lists which of these are set, `yuno-proofreader models` tests your model key, and `prepare` is the first command that tests the access to the sheet.
+
+```
+yuno-proofreader prepare                  # creates the Pages, Suggestions and Analysis tabs in your sheet
+yuno-proofreader pages import             # adds your pages to the sheet
+yuno-proofreader analyze                  # ranks the pages by importance (optional, but it orders the audits)
+yuno-proofreader queue                    # shows which pages are due, and why
+yuno-proofreader audit --next             # audits the page that is due first
+```
+
+Start with `audit --next --dry-run` and a single page, and read what it would do: every audit makes two model calls, so cost depends on your pages and your models.
+Review the suggestions in the sheet, set each one's `status`, and call `audit --next` again whenever you like: it picks the next page that is due. A cron job, a Kubernetes CronJob or Cloud Scheduler can do that for you.
+
+## Privacy and responsible use
+
+- The content of your pages, and the text of the settings that describe your site, is sent to the model provider you configure. Providers' terms sometimes differ between free and paid use, including whether prompts may be used to improve their products, so read the current terms before you start.
+- Only check sites you own or have permission to fetch.
+- You pay for the model calls yourself. Cost depends on the model and on the size of your pages.
+- `yuno-proofreader prompt PAGE` shows exactly what is sent to the model for a page, so you can check it before any request is made.
+- `yuno-proofreader audit` sends the pages and the settings that describe your site to the model provider, and writes to your sheet. Try it on one small page first, and read `yuno-proofreader prompt PAGE` to see what is sent.
+
+## Usage
+
+```
+yuno-proofreader <command>
+```
+
+| Command | What it does |
+|---|---|
+| `help` | Shows the commands |
+| `version` | Prints the version |
+| `doctor` | Checks that `SPREADSHEET_ID` is set and prints the configuration |
+| `sitemap [FILE] [--all]` | Reads the sitemap of the site described in `FILE` (default `./proofreader.yml`) and shows how its pages were paired by language. `--all` lists every page. Needs no API keys. |
+| `fetch PAGE [FILE] [--html=LANG]` | Downloads all language versions of one page and shows status, size and a content fingerprint of each. `PAGE` is a name from `sitemap --all`, or any address of the page. `--html=LANG` also prints the cleaned HTML that would be sent to the model. |
+| `settings [FILE]` | Shows which of the settings that describe your site are filled in, and whether an audit can start. Exits with 1 when it cannot. |
+| `models [FILE]` | Lists the models your API key can use for text generation, marks the ones in use, and shows whether the list comes from your settings or the built-in default. Needs the API key of your provider. |
+| `prompt PAGE [FILE] [--review] [--full]` | Shows exactly what would be sent to the model for one page, with a size estimate, without calling it. Needs no API key. Refuses to run while the settings that describe your site are unfinished. |
+| `audit PAGE [FILE] [--dry-run] [--force] [--verbose]` | Audits one page in all its language versions and updates the sheet. `--dry-run` writes nothing, but the model is still called and costs the same. `--force` audits a page that has not changed. `--verbose` lists everything that was decided. Needs a model API key, the sheet and the finished settings. |
+| `prepare [FILE]` | Creates the `Pages` and `Suggestions` tabs in your Google Sheet. Safe to run again. |
+| `pages import [FILE]` | Adds the pages of the sitemap to the `Pages` tab. Safe to run again. |
+| `analyze [FILE] [--dry-run] [--no-ai] [--reuse-ai]` | Ranks every page by importance and writes `importance`, `tier` and `importance_notes` to the Pages tab, and the measurements to the Analysis tab. `--dry-run` writes nothing, `--no-ai` skips the AI models, `--reuse-ai` takes their judgement from the last run instead of asking again. |
+| `init [FILE] [OPTIONS]` | Asks about your site and writes a settings file (default `proofreader.yml`). With `--template` it shows the full commented template instead, or writes it to `FILE` when one is named. For scripts: `--website`, `--language CODE[:PREFIX]`, `--note CODE=TEXT`, `--business`, `--audience`, `--tone`, `--sitemap`, `--skip-path`, `--rule`, `--ignore-term` and `--difference`. `--yes` accepts what was detected, `--offline` makes no request. Does not overwrite a file. |
+
+Exit codes: `0` success, `1` an error such as missing configuration, `2` unknown command.
+
+How to run it:
+
+- As an installed gem: `gem install yuno-proofreader`, then `yuno-proofreader help`
+- In a checkout or the dev container: `bundle exec exe/yuno-proofreader help`
+
+## Configuration
+
+Secrets and ids come from environment variables. The settings of the site you check come from a YAML file.
+
+| Variable | Required | Meaning |
+|---|---|---|
+| `GEMINI_API_KEY` | for the Gemini models | The API key of your model provider. Each provider names its own variable, and only the one you use is needed. |
+| `SPREADSHEET_ID` | for the sheet commands and `doctor` | The id of the Google Sheet that receives the suggestions |
+| `GOOGLE_APPLICATION_CREDENTIALS` | locally | Path to a Google credentials file. Where the tool runs on Google Cloud, the attached service account is used instead. |
+| `LOG_LEVEL` | no | `debug`, `info`, `warn` (default) or `error`. At `info`, every run, batch and audited page gets a line. At `debug`, each model call gets a line as well, with its model, seconds and tokens. At `warn`, only problems. At `error`, only failures. |
+| `LOG_FORMAT` | no | `text` (default, `key=value` pairs) or `json` (one JSON object per line, which Google Cloud Logging reads as a structured entry) |
+
+**Where the variables come from.** Set them the way you set any environment variable: in your shell, in the configuration of your CI or job, or in the secret settings of your platform (on Google Cloud, Secret Manager). On your own machine you can also put them in a `.env` file in the folder where you run the tool, which it reads when it starts:
+
+```
+SPREADSHEET_ID=...
+GEMINI_API_KEY=...
+GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json
+```
+
+A variable that is already set always wins over the file, and `PROOFREADER_ENV_FILE=/path/to/file` names another file.
+
+For the site, run `yuno-proofreader init` (see "Setting up your site"). The commands read `proofreader.yml` from the current folder, or from the path you give as `FILE`. `yuno-proofreader init --template` shows every setting with an explanation. Keep your `proofreader.yml` out of version control if it holds anything you don't want to share.
+
+## Setting up your site
+
+```
+yuno-proofreader init
+```
+
+Asks about your site and writes `proofreader.yml` in the current folder, or the file you name. It does not overwrites a file that already exists. What it does:
+
+1. Asks for the address of the site, and reads the homepage once, honoring. If the address leads to another host, such as the `www` form, it offers to use that one.
+2. Proposes the languages from the `hreflang` tags of the homepage, with the prefix of each and the default first. If the page announces none, or you decline, you type them: `de, es:/es, en:/en`, the default first.
+3. Asks for a note per language (variant and form of address), what the site offers (suggesting the meta description of the homepage), the audience and the tone, and then four lists with one entry per line: pages to skip, writing rules, words that must never be flagged, and intended differences between the languages. An empty answer skips what is optional.
+4. Looks for your sitemap. If none is found, asks for its address.
+5. Writes a short file with your answers. Then it says what an audit still needs, which of `SPREADSHEET_ID` and the API key of your provider are set, and what to run next.
+
+### Without questions
+
+Without a terminal, or with `--yes`, `init` asks nothing and takes everything from options:
+
+| Option | What it sets |
+|---|---|
+| `--website ADDRESS` | The address of the site. Needed when nobody can be asked. |
+| `--language CODE[:PREFIX]` | A language of the site, once for each, the default first: `--language de --language es:/es`. When left out, the languages the homepage announces are used. |
+| `--note CODE=TEXT` | A note for one language: its variant and form of address |
+| `--business TEXT` | What the site is and offers. An audit needs it. |
+| `--audience TEXT`, `--tone TEXT` | Who reads the site, and how the text should sound |
+| `--sitemap ADDRESS` | Your sitemap, when it is not found on its own |
+| `--skip-path PATH`, `--rule TEXT`, `--ignore-term TEXT`, `--difference TEXT` | One entry of a list each. Repeat the option for more entries. |
+| `--yes` | Accepts what was detected and asks nothing, also on a terminal |
+| `--offline` | Makes no request, so nothing is detected: give `--website` and `--language` |
+| `--template` | Shows the full commented template instead, with every setting explained. With a file name (`--template NAME.yml`) it writes the template there |
+
+```
+yuno-proofreader init --website example.com --language de --language en:/en --business "A small shop." --yes
+```
+
+This reads the homepage and the sitemap of the site, which is how the languages and the sitemap are checked. Add `--offline` to make no request at all.
+
+Good to know:
+
+- Languages are told apart by the start of the address (`/en/...`). A version on another domain, or deeper than one path segment, can't be described, and `init` says which versions it left out.
+- Language codes are written in lowercase (`de-DE` becomes `de-de`). Run `yuno-proofreader sitemap` afterwards to check that your pages are paired.
+- With `--yes`, the meta description of your homepage becomes the description of the business, unless you give `--business`. It is marketing copy, so read it. If the page has no description, or one longer than 300 characters, the business stays empty, and `yuno-proofreader settings` says that an audit still needs it.
+- The file holds only your answers. Settings you were not asked about, such as the models, `analysis` and `cadence`, are not in it and use their defaults. `yuno-proofreader init --template` shows every setting.
+
+## Describing your site
+
+Besides the technical settings, `proofreader.yml` tells the tool what your site is about, so the model can judge text in context. Everything here is sent to the AI model together with each page, so keep it short and free of secrets. Every setting is explained in `proofreader.example.yml`.
+
+| Setting | Required | Purpose |
+|---|---|---|
+| `business` | for an audit | What the site is and offers, in a sentence or two |
+| `audience` | no | Who reads the site |
+| `tone` | no | How the text should sound overall, such as warm and professional |
+| `rules` | no | Writing rules that apply to every language, one per entry, such as how prices or dates are written |
+| `ignore_terms` | no | Words that are correct as written and must not be flagged, such as brand and place names |
+| `intentional_differences` | no | Deliberate differences between language versions, such as a section that exists in one language only |
+| `notes` (inside each language) | no | What is specific to that language: its variant (Latin American Spanish) and its form of address (Sie or du, usted or tú) |
+
+The example file marks each of these with `[FILL IN]`. The audit refuses to start while any value still contains that text: replace it with your own, or delete the setting. `yuno-proofreader settings` shows what is set and what is still missing.
+
+Limits: 500 characters per text, 200 per list entry or language note, and 50 entries per list.
+
+
+## Choosing the models
+
+The tool calls an AI model through a small wrapper for each family of models. Only `gemini` is included so far. Which models it uses is up to you, in `proofreader.yml`:
+
+```yaml
+provider: gemini
+models:
+  - first-choice-model
+  - second-choice-model
+review_models:
+  - another-model
+```
+
+- `models` is tried in order. A model that is overloaded, over its limit or not available to your key is skipped, and the next one is used.
+- `review_models` is optional. The independent second review prefers a model different from the first audit. Without this setting it uses `models`.
+- Without `models`, the tool falls back on a built-in list. Model names change often, so set your own. `yuno-proofreader models` shows which models your key can use.
+- Leave out `provider` while only one is installed.
+
+## Previewing what is sent
+
+```
+yuno-proofreader prompt PAGE [FILE] [--review] [--full]
+```
+
+Shows exactly what would be sent to the model for one page, before any model is called.
+It makes no model request and needs neither an API key nor a spreadsheet.
+It only fetches the page (its `robots.txt`, your sitemap and each language version of the page), so use it on sites you own.
+
+- `PAGE` is a page name from `sitemap --all`, or any address of the page.
+- `FILE` is your settings file. Without it, `proofreader.yml` in the current folder is read.
+- `--review` shows the prompt of the independent second review instead of the audit.
+- `--full` prints the whole HTML of each language version. Without it, each version is shortened to its first 300 characters on screen. The sizes in the first lines always count the full text.
+
+The command refuses to run while the settings that describe your site are unfinished (see "Describing your site"), because the audit would refuse too.
+`yuno-proofreader settings` shows what is missing.
+
+## Auditing a page
+
+```
+yuno-proofreader audit PAGE [FILE] [--dry-run] [--force] [--verbose]
+```
+
+Audits one page, in all its language versions, and updates the sheet. It needs the tabs from `prepare`, the pages from `pages import`, a model API key and the finished settings that describe your site. `PAGE` is a page name from the first column of the `Pages` tab, or any address of the page.
+
+What happens:
+
+1. The page is fetched in every language. If its content has not changed since its last complete audit, it is skipped and no model is called.
+2. A model audits it step by step. A second model, different from the first when your `models` list has another, reviews it independently without seeing the first result.
+3. Both lists are merged. Each new suggestion records who found it in `found_by`: `both`, `audit`, `review`, or `audit (unreviewed)` when the review failed.
+4. The findings are compared with the suggestions already in the sheet for that page:
+   - A suggestion that is already `open` or `on staging` is counted as seen again (`last_seen`, `amount_seen`), not added twice.
+   - One you marked `rejected` is not added again. One you marked `done` whose text comes back is added as a new row, with "[Reappeared after being marked done]" in the reason.
+   - An `open` or `on staging` suggestion whose quoted text is no longer on the live page is closed and set to `done`. It only closes when the page loaded completely and the suggestion's text had been found on the page when it was written.
+5. The page's row records `last_audited` and, after a complete audit, a `fingerprint`.
+
+Reading a suggestion: `verified` says whether the quoted text is on the page (`yes`), only matches when spaces are ignored (`loose`) or is not there at all (`no`, which usually means the model misquoted). `approximate_place` is the heading path of the text, worked out by the tool.
+
+An audit is complete when every language version was fetched and not cut at the size limit, every audit step was answered, and the review answered. Only then is the fingerprint stored. Anything less is written, but the page is audited again next time. `last_audited` means the last time the tool checked the page, and it is also set when an unchanged page is skipped.
+
+Options:
+
+- `--dry-run` runs everything except the writing. The model is still called, so it costs the same as a real run.
+- `--force` audits the page even if it has not changed. Use it after you change your settings or the prompt files, which the fingerprint does not notice.
+- `--verbose` lists every decision, including suggestions that were seen again or suppressed, and the items in the model answers that could not be used.
+
+Each audit makes two model calls with the whole HTML of every language version, so cost depends on your pages and models. The report shows the tokens of each call.
+
+### What is in the output
+
+The first lines give the size of the prompt: its characters and a very rough token estimate (four characters per token).
+Then come two parts:
+
+- **System prompt:** the same for every page of your site. It holds the role, the description of your site and your language notes, your rules, ignore terms and intentional differences (each only if you set them), the rules about effort and about what to report, the audit steps with the categories they may use, and the exact JSON shape the answer must have. For the review, the steps give way to a checklist and one flat list.
+- **User message:** one block per language version of the page, from `=== DE | address ===` to `=== END DE ===`. The header names the versions included. A version that could not be fetched is listed as not available, so the model does not report differences it cannot check. A version that was cut at the size limit says so.
+
+The text the model sees is the page's HTML with scripts, styles, SVG images and comments removed, and runs of whitespace joined. Everything else stays, including the head, the navigation and the footer.
+
+The explanation the model gives for each suggestion (the reason column) is written in English, even when your site is in German or Spanish.
+The quoted text and the suggested replacement stay in the language of your page.
+
+### Changing the wording
+
+The instructions are plain files in `lib/yuno/proofreader/audit/prompts/`:
+
+- `instructions.yml`: the role, the rules and the two procedures.
+- `steps.yml`: the checks of the audit, in order. Each has a `number`, a `name`, the `categories` its findings may have, and a `text` that says what to look for. A step with the category `parity` is left out for a site with one language.
+
+Edit them in a checkout or a fork, since an installed gem keeps them in its own folder. Run `prompt` to see the effect.
+
+Everything in the output is sent to your model provider. See "Privacy and responsible use".
+
+### Respecting robots.txt
+
+Before it fetches a page of your site, the tool checks your `robots.txt`. It identifies itself as `yuno-proofreader`, and it does not fetch a page that the rules for that name, or for all crawlers (`User-agent: *`), disallow. When rules conflict, the longest matching path wins, and `Allow` wins a tie. It also waits half a second between requests. There is nothing to configure, and no setting turns this off.
+
+A page that is blocked is reported as "blocked by robots.txt". `fetch` shows it, an audit treats that language version as not available (the model is told, no differences involving it are reported, and the audit does not count as complete), and the analysis leaves the page out.
+
+If the tool cannot read a page of your own site, check your `robots.txt`. To let it in while keeping other crawlers out, add a group for it:
+
+```
+User-agent: yuno-proofreader
+Allow: /
+```
+
+## Ranking the pages by importance
+
+```
+yuno-proofreader analyze [FILE] [--dry-run] [--no-ai] [--reuse-ai]
+```
+
+Ranks every page of the site by how much it matters, so the most important pages can be audited most often. It needs the tabs from `prepare` and the pages from `pages import`.
+
+How a page is scored:
+
+- **The structure of the site** (most of the score): how the homepage leads to the page through its navigation and the lists of the index pages, where earlier entries count more; whether the homepage shows it; how many pages list it; and how recently it changed. Lists are read from structured data (`ItemList`, `OfferCatalog`), and from the cards of a page when there is none. Only the default language is read, usually a few dozen pages.
+- **The judgement of an AI model:** how well known the places are among your audience, and how much a reader would want each page. It sees only the names the site lists the pages under, not the pages themselves. A second model judges independently. The less the structure of the site says, the more the judgement counts.
+- **Your own points:** `priority_paths` in the `analysis:` block of `proofreader.yml`, and the `boost` column of the Pages tab.
+
+What is written:
+
+- **Pages tab:** `importance` (0 to 100), `tier` (1 is the most important, about the top tenth), `importance_notes` (why, in a few words) and `analyzed_at`. `boost` is yours: a number of points added to the score. The tool reads it and never writes it.
+- **Analysis tab:** one row per page with each measurement and the model's view (kind, place, value, certainty, reason, and how far apart the two models were). It is rewritten on every run.
+
+The homepage always ranks first. Run it again after big changes to the site. To try other weights, `priority_paths` or boosts without asking the models again, use `--reuse-ai`, which takes their last judgement from the Analysis tab. The weights are in `lib/yuno/proofreader/analysis/weights.yml`, and the model's wording in `analysis/judge.yml`.
+
+## Logging
+
+The tool writes a log to stderr, next to the report it prints on stdout. It is meant for runs nobody watches: it says which page was audited, what came of it and what the models used. Set `LOG_LEVEL=info` for one line per run, batch and page, or `debug` to add a line per model call. The default, `warn`, shows only problems.
+
+```
+time=2026-10-25T12:00:05Z level=info msg="page audited" run=3fa91c2e page=about status=audited complete=true added=3 closed=1 model_calls=2 input_tokens=62000 output_tokens=9000
+```
+
+With `LOG_FORMAT=json` each line is one JSON object with `severity`, `message` and `time`, plus the same fields. Every line of a run carries the same `run` id.
+
+| Message | Level | What it tells you |
+|---|---|---|
+| `run started`, `run finished` | info | The command, and `result=ok` with the exit code and seconds |
+| `run failed` | error | A run that did not succeed, with its exit code (and the error, when it reached the log) |
+| `page audited`, `page skipped` | info | The page, what was added, seen again, closed or suppressed, and the models' tokens |
+| `audit incomplete` | warn | Why the page's fingerprint was not recorded, so it will be tried again |
+| `page failed` | error | A page that failed for its own reason and was set aside |
+| `batch finished` | info | Pages audited, skipped and failed, how many are still due, and the tokens |
+| `batch stopped` | error | A problem that ended the batch, such as no model being available |
+| `nothing is due` | info | The queue was empty |
+| `analysis finished` | info | What `analyze` ranked and wrote |
+| `model failed`, `model paused`, `model answer unusable` | warn | A model that errored, was set aside for a while, or answered without usable JSON |
+| `model answered` | debug | One model call: the model, seconds and tokens |
+
+Page content, prompts, model answers and keys are never logged.
+
+On Google Cloud, set `LOG_LEVEL=info` and `LOG_FORMAT=json`. Cloud Logging reads a JSON line on stdout or stderr as a structured entry: `severity` becomes the entry's severity, `message` its text, and the other fields can be searched, for example `jsonPayload.page="about"`. An alert on entries with `severity>=ERROR` catches failed runs and failed pages. The exit code (`0` when a run succeeded, `1` for an error, `2` for a usage error) is what marks a Cloud Run job execution as failed.
+
+## How the sitemap is read
+
+The tool needs your sitemap to know which pages exist and which of them are language versions of each other.
+
+**Finding it.** Unless `sitemap_url` is set, the tool reads the `Sitemap:` lines of your `robots.txt` (all of them), and falls back to `/sitemap.xml`.
+A sitemap index is followed two levels deep. At most 25 sitemaps and 50,000 pages are read.
+Sitemaps on another host are ignored, and `www.example.com` counts as the same host as `example.com`.
+Compressed sitemaps (`.xml.gz`) are not supported yet.
+The `sitemap` command shows what was found and any warnings.
+
+**Pairing the languages.** Each page must be matched with its other language versions. The tool uses the first method that fits:
+
+1. **hreflang alternates in the sitemap:** if at least half of the entries list alternates, they decide the pairs.
+2. **Language prefix and position:** otherwise, pages are grouped by the prefixes in your `languages` setting and matched by their position. All pages of one language must be listed in the same order as in the other languages, and every language must have the same number of pages.
+
+Pages that exist in one language only go under `default_language_only_paths`, and pages you don't want checked under `skip_paths`. If the lists don't match up, the tool says so and writes nothing, because a wrong pairing would produce wrong findings on every page.
+
+## Working with the sheet
+
+The tool keeps its work in one Google Sheet: a queue of pages and a list of suggestions.
+Both commands below need `SPREADSHEET_ID` and working Google access (see "Connecting to Google"), and neither needs a Gemini key.
+
+```
+yuno-proofreader prepare
+yuno-proofreader pages import
+```
+
+Run them in this order, from the folder that contains your `proofreader.yml` (or pass the path of the settings file as the last argument).
+
+### prepare
+
+Creates two tabs in your spreadsheet:
+
+- **Pages**: one row per page of your site. Columns: `page_name`, one `<code>_url` column per language of your settings, `last_audited`, `fingerprint`, `note` and `sitemap_lastmod`.
+- **Suggestions**: one row per suggested fix. Columns: `timestamp`, `page`, `language`, `category`, `effort`, `approximate_place`, `original`, `suggested`, `reason`, `verified`, `status`, `found_by`, `last_seen` and `amount_seen`. `status` is a dropdown with `open`, `on staging`, `done` and `rejected`.
+
+Both tabs get a frozen header row and date formats. An empty default tab (`Sheet1`) is removed.
+
+It is safe to run again. A tab that already has a header row is left as it is, and the tool only checks that its required columns exist.
+To apply the formatting again, delete the tab and run `prepare` once more.
+
+### pages import
+
+Reads your sitemap and adds each page to the `Pages` tab, with its address in every language. It needs the tabs from `prepare`.
+
+- Pages that are already in the sheet are skipped (they are recognised by their address in the default language), so running it again only adds new pages.
+- Nothing is overwritten. Pages that have left the sitemap stay in the sheet, and the command tells you how many.
+- If the pages cannot be paired by language, it writes nothing. The `sitemap` command shows why.
+- A row you delete comes back at the next import. To exclude a page for good, add it to `skip_paths` in your settings file.
+
+### Editing the sheet
+
+Columns are found by their header names, so you can reorder them or add columns of your own. Don't rename the columns listed above. Times are stored in UTC.
+
+## Development
+
+Assuming Podman:
+
+```
+cp .env.example .env        # then fill in your values
+podman build -t yuno-proofreader:dev -f Dockerfile.dev .
+sh start-dev.sh
+podman exec -it proofreader-dev bash
+```
+
+Inside the container:
+
+```
+bundle exec rake test
+bundle exec rubocop
+gem build yuno-proofreader.gemspec
+```
+
+To build the production image:
+
+```
+podman build -t yuno-proofreader .
+```
+
+### Trying it on your own site
+
+```
+bundle exec ruby -Ilib scripts/try_sitemap.rb
+```
+
+The sitemap command shows how the pages were paired.
+This script also fetches a sample of pages in every language and compares each page’s own hreflang tags with the pairing.
+Options are environment variables:
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `SAMPLE` | `2,2,4` | First pages, last pages and random pages to check (`0,0,0` skips the page checks) |
+| `SEED` | random | Repeat a random sample |
+| `DELAY` | `0.5` | Seconds to wait between requests |
+
+To see how the tool reads one page (its headings, and where a text sits under them), run `bundle exec ruby -Ilib scripts/try_place.rb PAGE LANG ["quoted text"]`.
+
+## Connecting to Google
+This gem connects to Google Sheets and an AI model provider (Gemini so far).
+I will not try to document the way to do it, because it differs by permissions, type of Accounts, etc.
+Misconfiguring it could become costly, so make sure you do it correctly.
+
+## Contributing
+
+See CONTRIBUTING.md. It is provided as is, and replies may take a while.

data/exe/yuno-proofreader

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "yuno/proofreader"
+
+$stdout.sync = true
+$stderr.sync = true
+
+begin
+  Yuno::Proofreader::EnvFile.load&.warnings&.each { |warning| warn "Warning: #{warning}" }
+rescue Yuno::Proofreader::ConfigError => e
+  warn "Error: #{e.message}"
+  exit 1
+end
+
+exit Yuno::Proofreader::CLI.run(ARGV)

data/lib/yuno/proofreader/analysis/adjustments.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Yuno
+  module Proofreader
+    module Analysis
+      # Points a person adds to the score of a page, and where they come from.
+      Adjustment = Data.define(:points, :notes)
+
+      # Turns priority_paths from the settings and the boost of each page into adjustments, keyed by page key.
+      # The most specific path wins, and a boost adds to it. Pages without either get no adjustment.
+      module Adjustments
+        module_function
+
+        # boosts: the boost of each page, keyed by page key.
+        def call(pages:, language:, settings:, boosts: {})
+          pages.each_with_object({}) do |page, found|
+            key = Links.key(page.urls[language] || page.urls.values.first)
+            parts = [priority(Reasons.shown(key), settings.priority_paths), boost(boosts[key])].compact
+            found[key] = Adjustment.new(points: parts.sum(&:first), notes: parts.map(&:last)) unless parts.empty?
+          end
+        end
+
+        def priority(path, rules)
+          match = rules.select { |prefix, _points| covers?(prefix, path) }.max_by { |prefix, _points| prefix.length }
+          return if match.nil? || match.last.zero?
+
+          [match.last, "#{signed(match.last)} from priority_paths (#{match.first})"]
+        end
+
+        def covers?(prefix, path) = prefix == "/" || path == prefix || path.start_with?("#{prefix}/")
+
+        def boost(value)
+          return if value.nil? || value.zero?
+
+          [value, "#{signed(value)} from boost"]
+        end
+
+        def signed(number)
+          shown = number == number.round ? number.round : number.round(1)
+          number.positive? ? "+#{shown}" : shown.to_s
+        end
+      end
+    end
+  end
+end

data/lib/yuno/proofreader/analysis/crawler.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Yuno
+  module Proofreader
+    module Analysis
+      # What the crawl found. facts and failures are keyed by Links.key of a page's address. unread holds the index
+      # pages that were left out because the limit was reached.
+      Inventory = Data.define(:home, :facts, :failures, :tree, :unread) do
+        def facts_for(url) = facts[Links.key(url)]
+        def read?(url) = facts.key?(Links.key(url))
+      end
+
+      # Reads the structure of a site, starting at its homepage: the homepage, the pages its header, navigation and
+      # footer link to, any index pages named in the settings, the pages that have other pages under them, and the
+      # entries of the lists it reads that are index pages themselves. Only the default language is read, because
+      # the pairing already knows each page's other language versions
+      class Crawler
+        MAX_PAGES = 80
+        INDEX_TYPES = %w[CollectionPage ItemList].freeze
+
+        def initialize(site:, pages:, fetcher:, extra_hubs: [], max_pages: MAX_PAGES, progress: ->(_message) {})
+          @site = site
+          @language = site.default_language
+          @tree = UrlTree.new(pages.filter_map { |page| page.urls[@language] || page.urls.values.first })
+          @fetcher = fetcher
+          @extra = extra_hubs.map { |path| "#{site.website}/#{path.to_s.delete_prefix('/')}" }
+          @max = max_pages
+          @progress = progress
+        end
+
+        def call
+          @facts = {}
+          @failures = {}
+          read(home)
+          queue = unique([*from_home, *@extra, *@tree.hubs])
+          until queue.empty? || visited >= @max
+            url = queue.shift
+            next if done?(url)
+
+            read(url)
+            queue = unique(queue + listed_index_pages(url))
+          end
+          Inventory.new(home:, facts: @facts, failures: @failures, tree: @tree,
+                        unread: queue.reject { |url| done?(url) })
+        end
+
+        private
+
+        # The default language's homepage, written as the sitemap writes it when the sitemap has it.
+        def home
+          @home ||= begin
+            address = "#{@site.website}#{@site.prefixes[@language]}"
+            @tree.urls.find { |url| Links.key(url) == Links.key(address) } || address
+          end
+        end
+
+        def from_home
+          facts = @facts[Links.key(home)]
+          facts ? facts.chrome_links.values.flatten.select { |url| @tree.include?(url) } : []
+        end
+
+        # Entries of the lists a page publishes that are index pages themselves: typed as a collection, or with
+        # pages under them. Only pages the tool tracks are followed.
+        def listed_index_pages(url)
+          facts = @facts[Links.key(url)]
+          return [] unless facts
+
+          entries = facts.lists.flat_map(&:list_members)
+          entries.select { |entry| @tree.include?(entry.url) && index_like?(entry) }.map(&:url)
+        end
+
+        def index_like?(entry)
+          entry.types.intersect?(INDEX_TYPES) || !@tree.children(entry.url).empty?
+        end
+
+        def read(url)
+          @progress.call("Reading #{url}")
+          page = Sitemap::Page.new(name: url, urls: { @language => url }, lastmod: "", notes: [])
+          snapshot = @fetcher.fetch(page).snapshots.first
+          if snapshot.ok?
+            @facts[Links.key(url)] = Extractor.call(snapshot.raw, url:, base: snapshot.final_url)
+          else
+            @failures[Links.key(url)] = snapshot.problem
+          end
+        end
+
+        def done?(url) = @facts.key?(Links.key(url)) || @failures.key?(Links.key(url))
+
+        def visited = @facts.size + @failures.size
+
+        def unique(urls) = urls.uniq { |url| Links.key(url) }
+      end
+    end
+  end
+end