Add docs maintenance agent: AGENTS.md, skills, and rule files

.agents/skills/identify-gaps/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: identify-gaps
+description:
+  Reviews OpenFn docs pages and reports what to fix, marked Must, Should, or
+  Could change. Checks accuracy against the Lightning, kit, and adaptors code,
+  clarity for newcomers, missing coverage, and product changes. Does not edit
+  anything. Use when asked to review or audit the docs, check whether a page is
+  accurate or out of date, find gaps, or as the first step of "improve the
+  docs".
+---
+
+# Identify gaps
+
+Look at the docs and work out what should be improved. The output is a report of
+recommendations. This skill does not edit anything; that is the job of
+`update-content/SKILL.md`.
+
+## Input
+
+By default, the whole site. The user can narrow it to a section: one sidebar
+category, one folder under `docs/`, or one page.
+
+You may also be handed context, such as the list of product changes from
+`release-review/SKILL.md`. If so, focus on the pages that context points to.
+
+## Four ways to look
+
+For a general review, use all four. When you are given a list of changes, start
+with the last one.
+
+### Is it accurate?
+
+Pick out the things a reader would act on: code samples, function names, flags,
+button labels, defaults, versions, limits. Check each against the code:
+`OpenFn/lightning` for the web app, `OpenFn/kit` for the CLI, `OpenFn/adaptors`
+for adaptor functions. Note the file and line. Anything you cannot check from
+code, such as pricing, policy, or per-deployment settings, is a question for the
+product team. Try each external link twice: a 404 or 410 means it is dead, but a
+403 or 429 does not.
+
+### Can a newcomer follow it?
+
+Read the page as someone who knows what an API, JSON, and a terminal are, but
+has never heard of OpenFn. Try to do what it says. Note every place you had to
+guess: an undefined term, a missing prerequisite, steps in the wrong order, no
+way to tell you had succeeded.
+
+### What is missing?
+
+Compare what the docs cover with what the product has: commands, screens,
+settings. Before calling something missing, search the whole site the way a user
+would type it; it may be documented elsewhere. If you can see user evidence
+(issues, forum posts), note how often the topic comes up. Do not invent demand.
+Feature-flagged or deliberately hidden things are not gaps. A page that is in no
+sidebar and linked from nowhere is an orphan; recommend adding or removing it,
+since someone may be drafting it.
+
+### What has changed?
+
+For each product change you were given, search `docs/`, `articles/`, and
+`adaptors/*.md` for it, using both the old and new names. Decide whether each
+page it touches is now wrong or now incomplete. A change with no home in the
+docs at all is a missing page.
+
+## House style
+
+In a general review, also list the pages that break the house style in
+`AGENTS.md` or use a `variants` spelling from `glossary.yml`. These are Could
+change. Group them by rule, with the pages under each, so one rule broken on 30
+pages is one recommendation, not 30.
+
+## Classify every recommendation
+
+- **Must change.** A reader following the page will fail or be misled: it
+  contradicts the code, the steps do not work, or it describes something that no
+  longer exists.
+- **Should change.** The page works, but a newcomer will struggle or miss
+  something important: a missing prerequisite, an undefined term, a shipped
+  feature it does not mention.
+- **Could change.** A nice improvement with little evidence of need: an extra
+  example, clearer wording, a small gap.
+
+If you are torn between two levels, pick the lower one. If you cannot decide
+what is right (the docs and code disagree and either could be wrong), list it
+under **Questions** instead.
+
+## The report
+
+Start with one line: what you covered, the repos and commits you checked, and
+the count at each level. Then list Must, Should, Could, and Questions, one line
+each:
+
+```
+[must] docs/build/triggers.md:42 — says the flag is -f; kit's cli.ts:88 says --force — change -f to --force
+```
+
+For a missing page, add where it should go and a short outline. Problems in
+generated adaptor pages go in their own list, as issues for `OpenFn/adaptors`.

.agents/skills/release-review/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: release-review
+description:
+  Finds what shipped recently in OpenFn/lightning, OpenFn/kit, and
+  OpenFn/adaptors by reading their changelogs, then runs identify-gaps on the
+  docs those changes affect. Use when asked what shipped or changed this month,
+  whether the docs are up to date with a release, or for the monthly docs check.
+---
+
+# Release review
+
+Work out what the product shipped recently, then hand that list to
+`identify-gaps/SKILL.md` to find the docs that need to catch up.
+
+By default, cover every release in the last month across `OpenFn/lightning`,
+`OpenFn/kit`, and `OpenFn/adaptors`. Someone can narrow it to one repo, a date
+range, a release tag, or a single PR.
+
+## Get the repos
+
+Clone the product repos you need outside this repo, with tags. Never change
+them. If you are running inside a product repo instead, clone `OpenFn/docs` the
+same way; docs changes always go in a PR on the docs repo.
+
+## Build the list of changes
+
+1. **Read the changelogs, not the diffs.** Lightning has one `CHANGELOG.md`,
+   with a date on each release. Kit and adaptors have one per package, under
+   `packages/<name>/CHANGELOG.md`. Kit's have no dates, so get them from the
+   release tags:
+   `git tag --sort=-creatordate --format='%(creatordate:short) %(refname:short)'`.
+   Read every entry released in the period. Skip the Unreleased section.
+   Lightning often lists a release's changes under its `-pre` heading, such as
+   `2.18.2-pre`, and leaves the final `2.18.2` empty, so read the `-pre`
+   entries too and report them under the final version.
+2. **Rewrite each entry as a change a user would notice**: a new feature, a
+   renamed button, a new CLI flag, a changed default, a removed option. Drop
+   internal changes like refactors, dependency bumps, and tests. Open the linked
+   PR only if an entry is too vague.
+3. **For adaptors, keep only two kinds of change**: a new adaptor, and a change
+   that could break a tutorial or guide. Adaptor function reference pages are
+   generated from code, so they update themselves.
+
+Each item on the list should give the repo, the release, what changed for the
+user, and the old and new names if something was renamed.
+
+## Hand it on
+
+Run `identify-gaps/SKILL.md` with this list as its context. Put the list at the
+top of the report, after one line saying which repos, releases, and dates you
+covered.
+
+If nothing user-facing shipped in the period, say so and stop.
+
+If you were asked to update the docs as well, pass the report to
+`update-content/SKILL.md`.

.agents/skills/translate/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: translate
+description:
+  Translates English docs pages into Spanish and French under i18n/, respecting
+  glossary.yml, translation-rules.yml, review status, and do-not-retranslate
+  fences, and opens one PR per locale. Use when asked to translate or refresh
+  translations.
+disable-model-invocation: true
+---
+
+# Translate
+
+Translate English docs into Spanish (`es`) and French (`fr`). The English is
+always the source of truth. Translations are generated files that live in
+this repo. Save each one at the same path as the English page, under
+`i18n/<locale>/docusaurus-plugin-content-docs/current/`. For example,
+`docs/build/triggers.md` goes to
+`i18n/es/docusaurus-plugin-content-docs/current/build/triggers.md`.
+Docusaurus ignores a file anywhere else without an error, and the page stays
+English.
+
+The sidebar headings come from `sidebars-main.js`, not from the pages. If it
+has new or renamed entries, run
+`yarn docusaurus write-translations --locale <locale>`. This adds them to
+`i18n/<locale>/docusaurus-plugin-content-docs/current.json` in English and
+keeps the ones already translated. Translate the new ones.
+
+Never translate the generated adaptor pages, the job library, the old v1
+docs, or articles and blog posts.
+
+## Before you start
+
+Check these three things. If any fails, stop and ask.
+
+- The locale is enabled in `docusaurus.config.js`. Do not enable it yourself;
+  that changes what gets deployed.
+- `i18n/` is not in `.gitignore`.
+- `glossary.yml` and `translation-rules.yml` are valid YAML.
+
+Translate the English page as it is on disk after any fixes and after
+Prettier has run, so the hash you record matches what you translated.
+
+## Front matter
+
+Copy the English page's front matter. Translate only `title` and
+`sidebar_label`. Then add:
+
+```yaml
+translation_source_hash: <git hash-object of the English file>
+translation_review_status: machine
+```
+
+The hash is the content hash of the English file, from
+`git hash-object docs/<path>.md`, not a commit. Commits do not survive squash
+merges: a hash pointing at a commit made on a branch dangles as soon as the
+branch is squashed onto main. A content hash is the same wherever the file
+lives, and it answers the only question the field exists to answer: is the
+English still the version this was translated from? To compare, hash the
+current English file and check it against the recorded value.
+
+`translation_review_status` can be `machine`, `needs-review`, or
+`human-reviewed`. Only a human ever sets `human-reviewed`, and when they do
+they also add `translation_reviewer` and `translation_review_date`.
+
+## Decide what to do with each page
+
+- **No translation yet.** Translate the whole page.
+- **The hash matches the current English file.** Skip it, whatever its
+  status. The English has not changed since it was translated. The one
+  exception: if `glossary.yml` or `translation-rules.yml` was committed more
+  recently than the translation (compare `git log -1 --format=%ct -- <file>`),
+  treat a `machine` page as if the hash no longer matches, so it picks up the
+  new rules.
+- **The hash no longer matches, and the status is `machine`, `needs-review`,
+  or missing.** Translate the whole page again, but keep any fenced blocks
+  (see below) exactly as they were.
+- **The hash no longer matches, and the status is `human-reviewed`.** Leave
+  the file out of the translation PR. Instead, open a separate PR for the
+  named reviewer that changes only the affected parts. Recover the English the
+  reviewer saw with `git cat-file -p <recorded hash>`, diff it against the
+  current English, and translate only what changed. In the same PR, set
+  `translation_source_hash` to the current English hash and leave the status
+  as `human-reviewed`: the reviewer merging it approves it. If the old version
+  is no longer in the repo, say so and offer a full retranslation in that PR
+  instead.
+
+## Fenced blocks
+
+A human can wrap part of a translation like this:
+
+```markdown
+<!-- do-not-retranslate -->
+Text a reviewer has corrected by hand.
+<!-- /do-not-retranslate -->
+```
+
+Copy those blocks into the new translation exactly, in the same place. If the
+English they correspond to has been deleted, keep the block anyway and ask
+what to do with it.
+
+## How to translate
+
+- Words in `glossary.yml` stay in English. For ordinary words that are also
+  product terms, like "run" or "step", keep the English only when the word
+  means the OpenFn thing.
+- Follow any rules for the locale in `translation-rules.yml`. By default,
+  Spanish uses "tú" and French uses "vous".
+- Copy code blocks and inline code exactly. You may translate comments inside
+  code.
+- Keep the names of things in the app, like buttons, menus, tabs, and field
+  labels, exactly as they are in the English. The app is English only, so a
+  translated button name points the reader at a button that does not exist.
+- Keep the same structure: same headings at the same levels, same lists,
+  same callouts, same components.
+- Keep internal links as they are in the English. Do not add `/es/` or
+  `/fr/`; Docusaurus adds the locale when it builds the page.
+- The one exception: a relative link like `../deploy/portability.md` breaks
+  if the page it points to has no translation yet. Write it as the page's
+  full address instead, like `/documentation/deploy/portability`. If the
+  target page sets a `slug` in its front matter, the address is
+  `/documentation` plus the slug: `slug: /api-tokens` gives
+  `/documentation/api-tokens`, not the folder path.
+- Give translated headings the original English anchor so existing links
+  still work.
+
+## Before you commit
+
+Check that the fixed glossary terms (the ones without `product_noun: true`,
+such as OpenFn, Lightning, adaptor, webhook) appear as many times as in the
+English. Product nouns like "run" and "step" are allowed to differ, since
+their ordinary-English uses get translated. Before counting, join each file
+into one line with single spaces: Prettier wraps prose at 80 columns, and
+English and Spanish wrap at different points, so a multi-word term like "work
+order" can sit across a line break in one file and not the other. Check the
+code blocks are identical. Check the counts of headings, code blocks,
+callouts, images, and tables match. Check the front matter is complete. Check
+every fenced block survived. Then build the site and make sure it passes:
+
+```bash
+yarn generate-library
+yarn generate-adaptors
+yarn build
+```
+
+Build the whole site, not just your locale. `yarn build --locale <locale>`
+builds the locale at the site root, so every correct `/es/...` link shows up
+as broken.
+
+Open one PR per locale, separate from the English PR. Translated files do not
+count toward the 20-file limit, because a locale's translations are reviewed
+as a set. In the PR description, say which tool and model translated the
+pages. If you spot a problem in the English while translating, note it for
+the next English pass; do not fix it here.

.agents/skills/update-content/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: update-content
+description:
+  Edits English docs pages and opens a PR, working from direct instructions or
+  from an identify-gaps report. Use when asked to fix, update, or improve the
+  docs.
+disable-model-invocation: true
+---
+
+# Update content
+
+Change docs pages and open a PR.
+
+## What to change
+
+- **You were given instructions.** Do what they say.
+- **You were given a report from `identify-gaps/SKILL.md`.** Make every Must
+  change. Make Should changes where the right text is clear. Leave Could changes
+  unless someone asked for them. Anything you did not do goes in the PR
+  description with a reason.
+- **You were only told to improve the docs.** Run `identify-gaps/SKILL.md`
+  first, then work from its report here. One loop, one PR.
+
+## How to change it
+
+- Follow the house style in `AGENTS.md`.
+- Keep each edit small. Match the page's voice and structure. Do not rewrite a
+  page and call it a fix.
+- Only write a new page or section if the report or the person asked for it.
+- If the docs and the code disagree and you cannot tell which is right, ask.
+
+## Finish
+
+Stop when you are done or reach 20 changed files. If work is left, list it in
+the PR for the next run. Run Prettier on the files you changed, then build the
+site as CI does, which fails on broken links:
+
+```bash
+yarn generate-library
+yarn generate-adaptors
+yarn build
+```
+
+Open a PR using the template in `.github/` and tick "I have used Claude Code".
+Say what changed, what you left and why, and any questions. If the work came
+from a report, paste the report in, collapsed.
+
+Translations are separate. See `translate/SKILL.md`.

.claude/skills

@@ -0,0 +1 @@
+../.agents/skills

.gitignore

@@ -13,8 +13,7 @@
 .docusaurus
 .cache-loader
 
-# translation
-/i18n
+# translation: i18n/ is committed (translations are generated artefacts kept in-repo, see .agents/skills/translate/SKILL.md)
 
 # Misc
 .DS_Store