docs: AGENTS.md at the root, imported by CLAUDE.md

.claude/CLAUDE.md

@@ -1,42 +1,20 @@
-# roanny-site
+@../AGENTS.md
 
-The operator's personal CV and portfolio, served at https://roanny.github.io/. The repository is `roanny/roanny.github.io`, under his personal GitHub account rather than the Coabana organization. It is a site, not a product: nothing consumes it, and it names no fleet product.
+# roanny-site — Claude Code
 
-## The tree
+`AGENTS.md`, imported above, says what the site is, how it is previewed and checked, and the conventions a change respects; this file adds what holds only for a Claude Code session.
 
-- `index.html` — the whole site: content, styles, the `i18n` dictionaries and the script. No framework, no build step.
-- `404.html` — the themed not-found page, self-contained.
-- `favicon.svg`, `favicon-32.png`, `og-image-2.jpg` (the 1200×630 social card), `robots.txt`, `sitemap.xml`, `googlede4b53d1c977dbfc.html` (Search Console verification; never removed).
-- `.nojekyll` — Pages serves the tree as it is, without Jekyll.
-- `.github/scripts/check_site.py`, `.github/htmlvalidate.json` — the site's own gates, run by `Validate`.
+## Serving and landing
 
-## Editing and previewing
-
-- Text lives in the `i18n` object at the end of `index.html`: two dictionaries, `en` and `es`, with the same keys; each translatable element carries `data-i18n="<key>"`, and the English default in the HTML stays aligned with `en`.
-- Preview: `python3 -m http.server 8000`, then http://localhost:8000 (`?lang=en|es` and `?theme=light|dark` force the language and the theme).
-- The gates by hand, as CI runs them: `npx --yes html-validate@11.16.0 --config .github/htmlvalidate.json index.html 404.html`, `python3 .github/scripts/check_site.py i18n`, `python3 .github/scripts/check_site.py sitemap`.
-- A content change updates `lastmod` in `sitemap.xml`.
-- A changed social card takes a new filename (`og-image-<n>.jpg`) and the three references in `index.html` (`og:image`, `twitter:image`, the JSON-LD `image`): LinkedIn, WhatsApp and X cache a card by its URL. After it is live, LinkedIn's Post Inspector (https://www.linkedin.com/post-inspector/) refetches it.
-
-## Serving
-
-GitHub Pages serves the root of `main`; a push to `main` is live in 1–2 minutes. Two rulesets guard `main`: "Protect main branch" (24806684: no deletion, no force push, linear history; no bypass) and "Require Validate" (24807145: `Validate` green; the repository admin bypasses it so the operator can fix by hand — a session never does, `git-hygiene.md`). There is no release and no `/release`: the fleet's `release` shared block does not apply, and a landing that changes the pages is a deploy (`git-hygiene.md`).
+Two rulesets guard `main`: "Protect main branch" (24806684: no deletion, no force push, linear history; no bypass) and "Require Validate" (24807145: `Validate` green; the repository admin bypasses it so the operator can fix by hand — a session never does, `git-hygiene.md`). There is no release and no `/release`: the fleet's `release` shared block does not apply, and a landing that changes the pages is a deploy (`git-hygiene.md`).
 
 ## The one coupling
 
-The design tokens (palette, type, chips, buttons, motion) mirror `DESIGN.md` of `coabana-site` (`Coabana/coabana.github.io`), the canonical source, copied by hand into the `<style>` of `index.html`; `coabana-site`'s `CLAUDE.md` says the same from its side. Before stating what that file holds now, read it or verify it with the `contract-checker` agent. The JSON-LD names Coabana as the affiliation, and a call to action links to https://coabana.github.io/.
-
-## Language
-
-The content is English by default with Spanish, by audience; the working documents — README, this file, rules, code comments and commit subjects — are English. Spanish text quoted from the content stays Spanish.
-
-## Git identity
-
-Commits are authored as `Roanny Lamas <roannylamaslopez@gmail.com>`, set in this checkout's local git config; the corporate address is never used here.
+The design tokens mirror `DESIGN.md` of `coabana-site` (checkout `coabana/`); `coabana-site`'s `CLAUDE.md` says the same from its side. Before stating what that file holds now, read it or verify it with the `contract-checker` agent. The JSON-LD names Coabana as the affiliation, and a call to action links to https://coabana.github.io/.
 
 ## Index
 
-- `.claude/rules/git-hygiene.md` — linear history, the 72-character subject, no force push or remote-ref deletion, landing as a deploy, Dependabot, the round authorization (every session).
+- `.claude/rules/git-hygiene.md` — linear history, the 72-character subject, the commit author, no force push or remote-ref deletion, landing as a deploy, the two rulesets, Dependabot, the round authorization (every session).
 - `.claude/rules/rules-discipline.md` — what a rule file may hold (fleet shared block).
 - `.claude/rules/markdown-docs.md` — the shape of the Markdown working documents (fleet shared block).
 - No commands and no agents: there is no release and no code to review beyond the page's script.

.claude/rules/rules-discipline.md

@@ -1,6 +1,6 @@
 ---
 description: Rules content discipline — what a rule may hold (invariants, constraints, patterns) and what it may not (history, status, changelog fragments)
-paths: [".claude/**", "CLAUDE.md"]
+paths: [".claude/**", "CLAUDE.md", "AGENTS.md"]
 ---
 
 <!-- rules-discipline:shared begin -->

AGENTS.md

@@ -0,0 +1,33 @@
+# roanny.github.io
+
+The operator's personal CV and portfolio, served at https://roanny.github.io/ by GitHub Pages from the root of `main`. The repository is `roanny/roanny.github.io`, under his personal GitHub account rather than the Coabana organization; it is a site, not a product, and nothing consumes it. Every push to `main` is live within minutes, so a change a visitor would see never lands without the operator's word. `googlede4b53d1c977dbfc.html` (the Search Console verification) is never renamed or removed.
+
+## The tree
+
+- `index.html` — the whole site: content, styles, the `i18n` dictionaries and the script. No framework, no build step.
+- `404.html` — the themed not-found page, self-contained.
+- `favicon.svg`, `favicon-32.png`, `og-image-2.jpg` (the 1200×630 social card), `robots.txt`, `sitemap.xml`; `.nojekyll` makes Pages serve the tree as it is.
+- `.github/scripts/check_site.py`, `.github/htmlvalidate.json` — the site's own gates.
+
+## Previewing and checking
+
+- Preview: `python3 -m http.server 8000`, then http://localhost:8000 (`?lang=en|es` and `?theme=light|dark` force the language and the theme).
+- The gates, as CI runs them: `npx --yes html-validate@11.16.0 --config .github/htmlvalidate.json index.html 404.html`, `python3 .github/scripts/check_site.py i18n`, `python3 .github/scripts/check_site.py sitemap`.
+- A content change updates `lastmod` in `sitemap.xml`. A changed social card takes a new filename (`og-image-<n>.jpg`) and the three references in `index.html` (`og:image`, `twitter:image`, the JSON-LD `image`), because LinkedIn, WhatsApp and X cache a card by its URL; LinkedIn's Post Inspector refetches it once it is live.
+
+CI (`Validate`, `.github/workflows/ci.yml`) refuses invalid HTML in either page, an `i18n` key missing from either language, a malformed sitemap, a changed shared block under `.claude/`, on pull requests a commit subject over 72 characters or with a trailing period, and a commit author other than the one below.
+
+## Conventions
+
+- **Language.** The content is English by default with Spanish, by audience: the text lives in the `en` and `es` dictionaries of the `i18n` object at the end of `index.html`, with the same keys, and each translatable element carries `data-i18n="<key>"`; the English default in the HTML stays aligned with `en`. The working documents — README, this file, the rules, code comments and commit subjects — are English; Spanish text quoted from the content stays Spanish.
+- **Design.** The design tokens (palette, type, chips, buttons, motion) mirror `DESIGN.md` of `Coabana/coabana.github.io`, the canonical source, copied by hand into the `<style>` of `index.html`.
+- **Commits.** The whole subject line at most 72 characters, no trailing period. Authored as `Roanny Lamas <roannylamaslopez@gmail.com>`, set in this checkout's local git config; the employer's address is never used here.
+- **Landing.** Work on a branch, open a pull request, and land it on `main` by fast-forward (`git push origin <branch>:main`) once `Validate` is green on its head. No merge commits, no force push, no remote-ref deletion.
+
+## Where the rules live
+
+- `.claude/rules/git-hygiene.md` — the landing, commit, ruleset and authorization rules in full.
+- `.claude/rules/markdown-docs.md` and `.claude/rules/rules-discipline.md` — the shape of the working documents and of a rule file.
+- `.claude/CLAUDE.md` — the rest of the repository's instructions and their index.
+
+As a site it carries no `docs/specs/`, no `CONTRIBUTING.md` and no release.

README.md

@@ -28,6 +28,7 @@ python3 -m http.server 8000
 ├── sitemap.xml       # Site map (update lastmod on content changes)
 ├── googlede4b53d1c977dbfc.html  # Google Search Console verification
 ├── .nojekyll         # Pages serves the tree as it is, without Jekyll
+├── AGENTS.md         # Instructions for coding agents (imported by .claude/CLAUDE.md)
 ├── LICENSE           # Apache-2.0, for the code only (see License)
 └── .github/          # Validate (ci.yml), its scripts, Dependabot
 ```
@@ -69,6 +70,7 @@ GitHub Pages serves the root of `main`: every push to `main` is live in 1–2 mi
 
 | File | What it holds |
 |---|---|
+| `AGENTS.md` | What any coding agent needs: what the site is, the checks, the conventions |
 | `.claude/CLAUDE.md` | How a Claude Code session works in this repository |
 
 ## The solution