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

[brandonjackson]

Short Description

Adds an AGENTS.md and four short skills under .agents/skills/ so an LLM agent can review, update, and translate the docs. Also adds glossary.yml (a seed list) and translation-rules.yml (empty, with a schema comment).

Where to focus review: translation. The other three skills are short and high level on purpose, and they only ever touch English pages through a normal PR. The translation workflow is where the real decisions are.

Details

The skills

Skill	What it does
Identify gaps	Reviews the docs and returns a report. It doesn't edit anything. It looks at four things: is it accurate against the code, can a newcomer follow it, what's missing, and what has changed. Every recommendation is marked Must change, Should change, or Could change, and anything it can't decide goes under Questions.
Update content	Makes the edits and opens a PR. It works from direct instructions or from an identify-gaps report. With a report, it makes every Must change and makes Should changes where the right text is clear. If it's only told to "improve the docs", it runs identify gaps first and then updates, as one loop that ends in one PR.
Release review	Plumbing only. It reads the changelogs in Lightning, kit, and adaptors (default: the last month), turns them into a list of changes users would notice, and passes that list to identify gaps. Designed for a monthly trigger, which isn't part of this PR.
Translate	Generates Spanish and French versions of English pages, with governance around it (see below).

The default scope is the whole site. A user can narrow it to a sidebar category, a folder, or a single page. Update content stops at 20 changed files and lists any remaining work in the PR for the next run.

Lint's core checks now live in the House style section of AGENTS.md (glossary terms, site-absolute links, front matter titles, alt text) and in identify gaps (dead external links, orphan pages). Internal links are covered by yarn build, which already fails on broken links.

Translation (please look closely)

• Source tracking. translation_source_hash is the content hash of the English file (git hash-object), not a commit SHA. This repo squash-merges, so a hash pointing at a branch commit would stop resolving as soon as the PR lands. A content hash is the same wherever the file lives, and a reviewer can recover the English they approved with git cat-file -p <hash>.
• Review status. Pages are machine, needs-review, or human-reviewed. The agent never edits human-reviewed pages. When their English changes, it proposes a diff in a separate PR instead.
• Do-not-retranslate fences protect text a reviewer corrected by hand.
• Glossary. Terms marked translate: false stay in English in every locale. The seed goes a little beyond the original spec (dataclip, Canvas, Inspector, CLI, project, state, operation, collection, sandbox), based on terms already used across docs/. It's easy to trim.
• Scope. Generated adaptor pages, the job library, v1 docs, articles, and blog posts are never translated.
• Build. Run a full yarn build. yarn build --locale <x> builds the locale at the site root, which makes every correct /es/... link show up as broken (learned from the i18n PoC).
• PRs. Translations get their own PR per locale and don't count toward the 20-file cap.

Things to look at carefully

• .gitignore no longer ignores /i18n. The old rule contradicted keeping translations in the repo. There's no i18n/ directory yet, so nothing changes until the translate skill runs.
• docusaurus.config.js has no i18n block, and I haven't added one: enabling locales changes what yarn build produces and deploys. The translate skill treats a missing locale as a blocking question. I'd suggest the first real translation PR enables the locale alongside the first translated content.

No existing docs pages were modified.

AI Usage

• I have used Claude Code
• I have used another model
• I have not used AI

You can read more details in our
Responsible AI Policy

🤖 Generated with Claude Code

https://claude.ai/code/session_014z5Y9vFQSL1as9VQrMvQux

[lmac-1]

This is a great start, thank you! I went through it, checked a few assumptions against the code and a test build, and pushed some changes straight to the branch:

Structure

• Each skill is now a folder with a SKILL.md and front matter (name, and a description of when to use it), so agents can find them.
• .claude/skills links to .agents/skills, so Claude Code finds them too.
• update-content and translate only run when asked for by name, since they open PRs.

Skills

• translate: skips pages whose English hasn't changed; keeps links as in the English (tested); exact save folder; app labels stay English; clearer rule for approved pages; model goes in the PR, not the page; builds the whole site like CI (building one locale reports every /es/ link as broken)
• update-content: builds like CI
• identify-gaps: checks the house style again
• release-review: kit dates from tags, reads Lightning -pre entries

Rules

• AGENTS.md: blank lines around :::tip and other admonitions, so Prettier doesn't break them
• glossary.yml: removed Kafka from triggers (Lightning only has webhook and cron now)

Still to do, happy for these to be follow-ups:

• AGENTS.md: only adaptors/library/jobs/auto/ is generated; the rest of adaptors/library/ is hand-written
• AGENTS.md: can the agent edit articles/?
• Prettier: add as a dependency, reformat docs/ in its own PR (tracking in #866)
• #848: update it to match the new translate rules
• Relative links clean-up (tracked in #867)
• Language guidance (e.g. only use US English)