From 3ccd68c7f7fabca3e79897ef2bfcc373ac088e57 Mon Sep 17 00:00:00 2001
From: Roanny Lamas <roannylamaslopez@gmail.com>
Date: Sun, 11 Oct 2026 18:35:58 -0300
Subject: [PATCH] docs: AGENTS.md at the root, imported by CLAUDE.md

A root AGENTS.md, one screen and tool-neutral, now carries what the
site is and must never do, how it is previewed and checked (the same
commands as CI), the language split and where the dictionaries live,
the design tokens mirrored from Coabana's DESIGN.md, the commit, author
and landing conventions, and where the rules live. .claude/CLAUDE.md
imports it on its first line and keeps only what holds for a Claude
Code session: the rulesets, the coupling check, the index, the
settings sentence. rules-discipline.md's paths list AGENTS.md (the
shared block's hash does not move); README lists the file
(operator-sites-agents-md).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WYawTHteKW5v8W8ZYNrycG
---
 .claude/CLAUDE.md                 | 36 ++++++-------------------------
 .claude/rules/rules-discipline.md |  2 +-
 AGENTS.md                         | 33 ++++++++++++++++++++++++++++
 README.md                         |  2 ++
 4 files changed, 43 insertions(+), 30 deletions(-)
 create mode 100644 AGENTS.md

diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
index fa05817..a6a4b66 100644
--- a/.claude/CLAUDE.md
+++ b/.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.
diff --git a/.claude/rules/rules-discipline.md b/.claude/rules/rules-discipline.md
index 9624409..da158db 100644
--- a/.claude/rules/rules-discipline.md
+++ b/.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 -->
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..9283275
--- /dev/null
+++ b/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.
diff --git a/README.md b/README.md
index c269a80..38a4bb6 100644
--- a/README.md
+++ b/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