From 4ec189635c5583a309f6508e02d14f5bc3487c10 Mon Sep 17 00:00:00 2001
From: Roanny Lamas <roanny.lamaslopez@viajeseci.es>
Date: Fri, 9 Oct 2026 15:13:09 -0300
Subject: [PATCH] chore: fleet scaffolding, Validate and English README

The artifact profile of the scaffolding standard, adapted to a static
site that GitHub Pages serves from main (operator-sites-scaffolding):

- .claude/CLAUDE.md: what the site is, how it is edited, previewed and
  served, the language split, the design tokens mirrored from
  Coabana/coabana.github.io's DESIGN.md, no release.
- .claude/settings.json: the fleet's deny groups A-C, worktree.baseRef
  head, an allow list for the daily work and the three site gates.
- Rules: git-hygiene, rules-discipline and markdown-docs, with the two
  shared blocks at the workspace's hashes and their manifest.
- Validate: HTML validity (html-validate 11.16.0, standard preset), i18n
  key parity, sitemap well-formed, shared blocks, commit subjects.
- Dependabot for github-actions.
- README in English per the README standard; og-image.png corrected to
  og-image.jpg; sitemap lastmod 2026-10-09.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .claude/.shared-blocks.sha256     |   2 +
 .claude/CLAUDE.md                 |  43 ++++++++++
 .claude/rules/git-hygiene.md      |  23 +++++
 .claude/rules/markdown-docs.md    |  34 ++++++++
 .claude/rules/rules-discipline.md |  40 +++++++++
 .claude/settings.json             | 136 ++++++++++++++++++++++++++++++
 .github/dependabot.yml            |  31 +++++++
 .github/htmlvalidate.json         |   3 +
 .github/scripts/check_site.py     |  86 +++++++++++++++++++
 .github/workflows/ci.yml          | 103 ++++++++++++++++++++++
 .gitignore                        |   4 +
 README.md                         |  81 +++++++++++++-----
 sitemap.xml                       |   2 +-
 13 files changed, 564 insertions(+), 24 deletions(-)
 create mode 100644 .claude/.shared-blocks.sha256
 create mode 100644 .claude/CLAUDE.md
 create mode 100644 .claude/rules/git-hygiene.md
 create mode 100644 .claude/rules/markdown-docs.md
 create mode 100644 .claude/rules/rules-discipline.md
 create mode 100644 .claude/settings.json
 create mode 100644 .github/dependabot.yml
 create mode 100644 .github/htmlvalidate.json
 create mode 100644 .github/scripts/check_site.py
 create mode 100644 .github/workflows/ci.yml
 create mode 100644 .gitignore

diff --git a/.claude/.shared-blocks.sha256 b/.claude/.shared-blocks.sha256
new file mode 100644
index 0000000..3431a36
--- /dev/null
+++ b/.claude/.shared-blocks.sha256
@@ -0,0 +1,2 @@
+0ed3ffb3d7e2fe3fecb9a161bf25e157a37d65f1d28939c875a7d619c8457f70  rules-discipline  .claude/rules/rules-discipline.md
+7d4f2112a43515d458f232108532c7b52ab270129792119a73588c5b35c8ba50  markdown-docs  .claude/rules/markdown-docs.md
diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
new file mode 100644
index 0000000..872f13e
--- /dev/null
+++ b/.claude/CLAUDE.md
@@ -0,0 +1,43 @@
+# roanny-site
+
+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.
+
+## 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.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`.
+
+## 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`.
+
+## Serving
+
+GitHub Pages serves the root of `main`; a push to `main` is live in 1–2 minutes. 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 the operator's global git config has it: `Roanny Lamas <roanny.lamaslopez@viajeseci.es>`.
+
+## 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/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/settings.json` is hand-written: `allow` holds the daily work (the git and `gh` reads, the branch push, the preview server, the three gates), `deny` holds the fleet's groups A–C; there is no group D.
diff --git a/.claude/rules/git-hygiene.md b/.claude/rules/git-hygiene.md
new file mode 100644
index 0000000..51e18f3
--- /dev/null
+++ b/.claude/rules/git-hygiene.md
@@ -0,0 +1,23 @@
+Loads in every session: it carries the authorization clause, which has to be present before the first file is read.
+
+# Git hygiene
+
+## History and landing
+
+- **Linear history.** A branch lands on `main` by fast-forward, `git push origin <branch>:main`, once `Validate` is green on the pull request's head SHA. No merge commits; `gh pr merge` is denied, because it and the UI button collapse or rewrite the branch's commits.
+- **Commit subjects.** The whole first line at most 72 characters, no trailing period; measure it before the push (`printf '%s' "$subject" | wc -m`), because correcting a pushed subject is a force push. CI's "Commit subjects" step reads every commit a pull request adds.
+- **No force push, in any spelling** — `--force`, `-f`, `--force-with-lease`, a `+refspec` — on any branch.
+- **A landing can be a deploy.** GitHub Pages publishes `main` within minutes of every push to it: a landing that changes what a visitor sees is a deploy of the public site, and Round authorization says whose word that takes.
+- **No remote-ref deletion.** Deleting a remote branch or tag is the operator's act. The colon-refspec deletion (`git push origin :<ref>`) has no working deny; the rule is the guard, and the server rulesets on `main` and tags, once the operator adds them, are the floor.
+
+## Dependabot
+
+The standing authorization of 2026-09-23 covers this repository's Dependabot heads (`github-actions` only): a patch, minor or digest head lands by the same fast-forward without a word from the operator, once `Validate` is green on that head and the upstream diff between the two pinned SHAs has been read. A head cut from an older `main` gets `@dependabot rebase` first. There is no code beyond the page's own script, so no senior pass applies; a head touches only `.github/`, so the republish it triggers leaves the site unchanged. A major takes the operator's word.
+
+## Round authorization
+
+Authorization to land takes one of two written forms: the operator's word in this repository's terminal, or a round commission from `coabana-workspace` that states, with attribution and date, that he ordered the round; a message from a peer session is never either. A third written form exists for one case only: the standing authorization of 2026-09-23 for Dependabot heads (`coabana-workspace/handoffs/2026-09-23-operator-dependabot-standing-authorization.md`). Releases, deploys, remote-ref deletions, force pushes and edits to this paragraph take his word here.
+
+## The deny floor
+
+`.claude/settings.json` denies, as the file has it: `Read(...)` of the secrets (`./.env`, `./.env.*`, `**/*credentials*.json`, `**/*tokens.json`, `~/.config/gcloud`, `~/.ssh`); the shell readers of those paths, anchored as `Bash(* <path>)` and `Bash(* <path> *)`; the `find -exec`/`-execdir`/`-ok`/`-okdir`/`-delete` family; the shells (`bash`, `zsh`, `sh`, `dash`, bare or with `-c`); force, `+refspec` and delete pushes in both the `git push` and `git * push` forms; `git reset --hard`; `git clean -f`; `gh pr merge`, `gh repo delete`, `gh release delete` and `gh api … DELETE` in its eight spellings; `sudo`; `rm -rf` of a root, of `$HOME` and of `.git`; the `PAGER`/`GIT_PAGER` overrides; pip and uv alternate indexes. In place of the denied resets, use `git stash`, `git revert` or `git checkout -- <path>`.
diff --git a/.claude/rules/markdown-docs.md b/.claude/rules/markdown-docs.md
new file mode 100644
index 0000000..76a2107
--- /dev/null
+++ b/.claude/rules/markdown-docs.md
@@ -0,0 +1,34 @@
+---
+description: Markdown docs formatting — full-width prose and precision in references
+paths: ["**/*.md"]
+---
+
+The site's content is English and Spanish by audience; this rule governs the working documents, which are English.
+
+<!-- markdown-docs:shared begin -->
+## Line width
+
+In `.md` files, **prose and bullets go full width**: one logical line is one physical line, with no manual hard wrap at ~80 columns. The editor or viewer does the visual wrapping. Hard wrapping at ~80 columns applies **only to code files** and to code fragments embedded in the document inside a fence; documentation prose is never wrapped by hand.
+
+**Why**: manually wrapping prose produces noisy diffs — changing one word reflows the whole paragraph — complicates merges, and produces the mix of short and long lines that reads as inconsistent. Full width keeps the diff honest, one logical line changed being one change, and delegates the wrapping to the renderer.
+
+## What to always preserve
+
+When reflowing or editing, never touch:
+
+- **Code fences** (blocks delimited by triple backticks) and their contents — code does respect its language's width.
+- **GFM tables** (`| … |`) — each row is one line.
+- **YAML frontmatter** (the `---` … `---` block at the start of the file).
+- **List structure** — one bullet (`- ` / `N. `) per logical item; an item's continuations join its bullet.
+- **Blockquotes** (`>`), **headings** (`#`) and **horizontal rules** (`---`).
+
+## Precision in references
+
+Documentation here names exact things all the time: secrets, environment variables, service accounts, flags, roles, files. Imprecision in those references misleads, above all when one name resembles another — a secret against the environment variable it is mounted as is the usual pair. Two rules follow.
+
+**No ad-hoc abbreviations.** Use the full, readable name, not an invented contraction: the project number is written `project_number`, **not** `projnum` nor `project-num`. Standard acronyms defined at first use (SA = service account, ADC = Application Default Credentials, OTel) are acceptable; contractions that save characters at the cost of clarity are not.
+
+**No prefix wildcard for a finite set.** A prefix wildcard loses precision and can mislead — it is how the name of a secret gets read as the name of the variable it is mounted as. When the set is **known, finite and the exact names matter**, enumerate the names. A wildcard is for a genuinely open or extensible family, where the full list adds nothing and the immediate context defines it unambiguously; never as a shortcut for a finite, specific set.
+
+**Why**: a reader copies and applies literally what the document says, and a wildcard sends them looking for a name that exists nowhere.
+<!-- markdown-docs:shared end -->
diff --git a/.claude/rules/rules-discipline.md b/.claude/rules/rules-discipline.md
new file mode 100644
index 0000000..9624409
--- /dev/null
+++ b/.claude/rules/rules-discipline.md
@@ -0,0 +1,40 @@
+---
+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"]
+---
+
+<!-- rules-discipline:shared begin -->
+A rule file is loaded when Claude reads a file its `paths:` frontmatter matches; a rule file with no `paths:` is loaded at the start of the session. Either way the whole body is then paid for in context on every turn that follows, so what is in it has to earn the place.
+
+The drift this exists to stop is specific: after a fix, the tempting thing to write into the rule is the **history of the change** rather than the **invariant it left behind**. That turns a rule into a second changelog — duplicating what `CHANGELOG.md` and `git log` already hold, and growing with nothing pushing back.
+
+## A rule may contain
+
+- **Invariants** — what must always or never be true.
+- **Constraints** — bounds the work has to respect, and why.
+- **Patterns** — the shape a solution takes here.
+- **Decisions**, so they are not re-litigated — including designs deliberately rejected, which is what stops them coming back a third time.
+- **Pointers** to where the authoritative answer lives — a constant, a test module, a gate, a command that computes the list.
+
+## A rule must not contain
+
+- Commit SHAs, dates, or release history. That is `git log` and `CHANGELOG.md`.
+- Status labels — "done", "pending", "new in the last release". A rule describes the standing state, not a moment in it.
+- Changelog fragments or migration narratives.
+- Enumerations that drift: test names, counts, file inventories. Name the command or the constant that produces the list instead.
+- **Anything already enforced mechanically.** If a test, a schema, a gate or CI rejects it, the rule only needs to say where the enforcement lives. A rule restating a guard is a second copy free to disagree with the first, and the copy in prose is the one nobody re-runs.
+- **Anything another rule already owns.** Point at the rule that owns the subject rather than repeating it here — the same discipline this file asks for.
+
+## Self-check before adding a line
+
+1. Will this still be true in three months without editing?
+2. Does it change what someone would *do*, or is it background?
+3. Is it already enforced by a test, a schema, a gate or CI?
+4. Could it live closer to what it governs, as a comment where the constraint applies?
+
+If the answers are no, no, yes, or yes — leave it out. When editing a rule after a change, write the end state and delete the narration of the journey.
+
+## Keep the index honest
+
+This repository's `CLAUDE.md` indexes these rules and must name every one of them; it should not restate their content. When a rule is added or changes scope, update that line rather than copying the rule into it. An index that silently omits a file teaches readers the directory is smaller than it is.
+<!-- rules-discipline:shared end -->
diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 0000000..c76a544
--- /dev/null
+++ b/.claude/settings.json
@@ -0,0 +1,136 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(diff:*)",
+      "Bash(gh api repos/*/commits/*/check-runs*)",
+      "Bash(gh pr checks:*)",
+      "Bash(gh pr create:*)",
+      "Bash(gh pr list:*)",
+      "Bash(gh pr view:*)",
+      "Bash(gh run list:*)",
+      "Bash(gh run view:*)",
+      "Bash(git add:*)",
+      "Bash(git branch:*)",
+      "Bash(git checkout -- :*)",
+      "Bash(git commit:*)",
+      "Bash(git diff:*)",
+      "Bash(git fetch:*)",
+      "Bash(git log:*)",
+      "Bash(git ls-files:*)",
+      "Bash(git pull --ff-only:*)",
+      "Bash(git push:*)",
+      "Bash(git rev-parse:*)",
+      "Bash(git revert:*)",
+      "Bash(git show:*)",
+      "Bash(git stash:*)",
+      "Bash(git status:*)",
+      "Bash(git switch:*)",
+      "Bash(npx --yes html-validate@11.16.0 --config .github/htmlvalidate.json:*)",
+      "Bash(python3 -m http.server:*)",
+      "Bash(python3 .github/scripts/check_site.py:*)"
+    ],
+    "deny": [
+      "Bash(* $HOME/.config/gcloud/* *)",
+      "Bash(* $HOME/.config/gcloud/*)",
+      "Bash(* $HOME/.ssh/* *)",
+      "Bash(* $HOME/.ssh/*)",
+      "Bash(* */.env *)",
+      "Bash(* */.env)",
+      "Bash(* */.env.* *)",
+      "Bash(* */.env.*)",
+      "Bash(* *credentials*.json *)",
+      "Bash(* *credentials*.json)",
+      "Bash(* *tokens.json *)",
+      "Bash(* *tokens.json)",
+      "Bash(* .env *)",
+      "Bash(* .env)",
+      "Bash(* .env.* *)",
+      "Bash(* .env.*)",
+      "Bash(* /Users/*/.config/gcloud/* *)",
+      "Bash(* /Users/*/.config/gcloud/*)",
+      "Bash(* /Users/*/.ssh/* *)",
+      "Bash(* /Users/*/.ssh/*)",
+      "Bash(* ~/.config/gcloud/* *)",
+      "Bash(* ~/.config/gcloud/*)",
+      "Bash(* ~/.ssh/* *)",
+      "Bash(* ~/.ssh/*)",
+      "Bash(GIT_PAGER=*)",
+      "Bash(PAGER=*)",
+      "Bash(bash -c*)",
+      "Bash(bash)",
+      "Bash(dash -c*)",
+      "Bash(dash)",
+      "Bash(find * -delete*)",
+      "Bash(find * -exec*)",
+      "Bash(find * -execdir*)",
+      "Bash(find * -ok*)",
+      "Bash(find * -okdir*)",
+      "Bash(gh api * --method DELETE*)",
+      "Bash(gh api * --method=DELETE*)",
+      "Bash(gh api * -X DELETE*)",
+      "Bash(gh api * -XDELETE*)",
+      "Bash(gh api --method DELETE*)",
+      "Bash(gh api --method=DELETE*)",
+      "Bash(gh api -X DELETE*)",
+      "Bash(gh api -XDELETE*)",
+      "Bash(gh pr merge*)",
+      "Bash(gh release delete*)",
+      "Bash(gh repo delete*)",
+      "Bash(git * push * +*)",
+      "Bash(git * push * --delete*)",
+      "Bash(git * push * --force*)",
+      "Bash(git * push * -d*)",
+      "Bash(git * push * -f*)",
+      "Bash(git * push +*)",
+      "Bash(git * push --delete*)",
+      "Bash(git * push --force*)",
+      "Bash(git * push -d*)",
+      "Bash(git * push -f*)",
+      "Bash(git clean -f*)",
+      "Bash(git push * +*)",
+      "Bash(git push * --delete*)",
+      "Bash(git push * --force*)",
+      "Bash(git push * -d*)",
+      "Bash(git push * -f*)",
+      "Bash(git push +*)",
+      "Bash(git push --delete*)",
+      "Bash(git push --force*)",
+      "Bash(git push -d*)",
+      "Bash(git push -f*)",
+      "Bash(git reset --hard*)",
+      "Bash(pip * --extra-index-url*)",
+      "Bash(pip * --index-url*)",
+      "Bash(pip install --extra-index-url*)",
+      "Bash(pip install --index-url*)",
+      "Bash(pip install -i *)",
+      "Bash(rm -rf $HOME*)",
+      "Bash(rm -rf .git)",
+      "Bash(rm -rf .git/*)",
+      "Bash(rm -rf /)",
+      "Bash(rm -rf /*)",
+      "Bash(rm -rf ~)",
+      "Bash(rm -rf ~/*)",
+      "Bash(sh -c*)",
+      "Bash(sh)",
+      "Bash(sudo:*)",
+      "Bash(uv * --default-index*)",
+      "Bash(uv * --extra-index-url*)",
+      "Bash(uv * --index *)",
+      "Bash(uv * --index-url*)",
+      "Bash(uv * --index=*)",
+      "Bash(zsh -c*)",
+      "Bash(zsh)",
+      "Read(**/*credentials*.json)",
+      "Read(**/*tokens.json)",
+      "Read(./.env)",
+      "Read(./.env.*)",
+      "Read(//Users/*/.config/gcloud/**)",
+      "Read(//Users/*/.ssh/**)",
+      "Read(~/.config/gcloud/**)",
+      "Read(~/.ssh/**)"
+    ]
+  },
+  "worktree": {
+    "baseRef": "head"
+  }
+}
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
new file mode 100644
index 0000000..08b53b7
--- /dev/null
+++ b/.github/dependabot.yml
@@ -0,0 +1,31 @@
+# Weekly version updates for the one ecosystem this repository pins: the
+# GitHub Actions of `.github/workflows/`. The site has no package manifest;
+# html-validate is pinned in `ci.yml` and moved by hand.
+# Docs: https://docs.github.com/en/code-security/dependabot/dependabot-version-updates
+
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:00"
+      timezone: "America/Montevideo"
+    open-pull-requests-limit: 5
+    assignees:
+      - "roanny"
+    groups:
+      actions:
+        applies-to: version-updates
+        patterns:
+          - "*"
+      actions-security:
+        applies-to: security-updates
+        patterns:
+          - "*"
+    labels:
+      - "dependencies"
+      - "github-actions"
+    commit-message:
+      prefix: "chore(ci)"
diff --git a/.github/htmlvalidate.json b/.github/htmlvalidate.json
new file mode 100644
index 0000000..3699e42
--- /dev/null
+++ b/.github/htmlvalidate.json
@@ -0,0 +1,3 @@
+{
+  "extends": ["html-validate:standard"]
+}
diff --git a/.github/scripts/check_site.py b/.github/scripts/check_site.py
new file mode 100644
index 0000000..3d422bc
--- /dev/null
+++ b/.github/scripts/check_site.py
@@ -0,0 +1,86 @@
+"""The site's own cheap gates, run by `Validate` and by hand.
+
+    python3 .github/scripts/check_site.py i18n      # en and es carry the same keys, and every key the page uses
+    python3 .github/scripts/check_site.py sitemap   # sitemap.xml is well-formed and every <loc> is on the site
+
+Errors print as GitHub annotations; the exit code is 1 on any failure.
+"""
+
+import re
+import sys
+import xml.etree.ElementTree as ET
+
+SITE = "https://roanny.github.io/"
+
+
+def check_i18n() -> bool:
+    html = open("index.html", encoding="utf-8").read()
+    block = re.search(r"^const i18n = \{\n(.*?)^\};", html, re.S | re.M)
+    if not block:
+        print("::error file=index.html::no `const i18n = {` … `};` block")
+        return False
+    ok = True
+    langs = {}
+    for lang, body in re.findall(r"^  (\w+): \{\n(.*?)^  \}", block.group(1), re.S | re.M):
+        # A key starts a line or follows the closing quote and comma of the previous value.
+        keys = re.findall(r"(?:^|['\"],)\s*([A-Za-z_]\w*)\s*:\s*['\"]", body, re.M)
+        dupes = sorted({k for k in keys if keys.count(k) > 1})
+        if dupes:
+            print(f"::error file=index.html::{lang} repeats keys: {dupes}")
+            ok = False
+        langs[lang] = set(keys)
+    if sorted(langs) != ["en", "es"]:
+        print(f"::error file=index.html::expected the dictionaries en and es, found {sorted(langs)}")
+        return False
+    # Keys the page uses: every data-i18n attribute, plus the quoted keys a script picks with a ternary
+    # inside `i18n[lang][…]`.
+    used = set(re.findall(r'data-i18n="([^"]+)"', html))
+    for lookup in re.findall(r"i18n\[\w+\]\[([^\]]+)\]", html):
+        used |= set(re.findall(r"[?:]\s*'(\w+)'", lookup))
+    for a, b in (("en", "es"), ("es", "en")):
+        missing = sorted(langs[a] - langs[b])
+        if missing:
+            print(f"::error file=index.html::keys in {a} but not in {b}: {missing}")
+            ok = False
+    for lang in ("en", "es"):
+        missing = sorted(used - langs[lang])
+        if missing:
+            print(f"::error file=index.html::keys the page uses but {lang} lacks: {missing}")
+            ok = False
+    print(f"i18n: en {len(langs['en'])} keys, es {len(langs['es'])} keys, {len(used)} used by the page")
+    return ok
+
+
+def check_sitemap() -> bool:
+    ns = "{http://www.sitemaps.org/schemas/sitemap/0.9}"
+    try:
+        root = ET.parse("sitemap.xml").getroot()
+    except ET.ParseError as e:
+        print(f"::error file=sitemap.xml::not well-formed: {e}")
+        return False
+    if root.tag != f"{ns}urlset":
+        print(f"::error file=sitemap.xml::the root is {root.tag}, not a sitemaps.org urlset")
+        return False
+    ok = True
+    urls = root.findall(f"{ns}url")
+    if not urls:
+        print("::error file=sitemap.xml::no <url> entries")
+        ok = False
+    for url in urls:
+        loc = (url.findtext(f"{ns}loc") or "").strip()
+        lastmod = (url.findtext(f"{ns}lastmod") or "").strip()
+        if not loc.startswith(SITE):
+            print(f"::error file=sitemap.xml::<loc> {loc!r} is not under {SITE}")
+            ok = False
+        if lastmod and not re.fullmatch(r"\d{4}-\d{2}-\d{2}", lastmod):
+            print(f"::error file=sitemap.xml::<lastmod> {lastmod!r} is not YYYY-MM-DD")
+            ok = False
+    print(f"sitemap: {len(urls)} url(s)")
+    return ok
+
+
+if __name__ == "__main__":
+    checks = {"i18n": check_i18n, "sitemap": check_sitemap}
+    if len(sys.argv) != 2 or sys.argv[1] not in checks:
+        sys.exit(f"usage: {sys.argv[0]} {{{'|'.join(checks)}}}")
+    sys.exit(0 if checks[sys.argv[1]]() else 1)
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..1c6c6dc
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,103 @@
+name: Validate
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+# A newer push to a pull request supersedes its run; a push run on `main`
+# always finishes.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  validate:
+    name: Validate
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          # Full history: the Commit subjects step reads the pull request's
+          # commits.
+          fetch-depth: 0
+
+      - name: HTML valid
+        # Both pages against html-validate's `standard` preset (the HTML
+        # standard's content models, attributes and nesting; no style rules),
+        # pinned here and in `.claude/settings.json`'s allow line.
+        if: '!cancelled()'
+        run: npx --yes html-validate@11.16.0 --config .github/htmlvalidate.json index.html 404.html
+
+      - name: i18n keys in both languages
+        if: '!cancelled()'
+        run: python3 .github/scripts/check_site.py i18n
+
+      - name: Sitemap well-formed
+        if: '!cancelled()'
+        run: python3 .github/scripts/check_site.py sitemap
+
+      - name: Shared blocks unchanged
+        # Each line of the manifest is `<sha256>  <name>  <path>`: the block
+        # between `<!-- <name>:shared begin -->` and `<!-- <name>:shared end -->`
+        # in <path>, marker lines included, must hash to <sha256>. A marker is
+        # a line that equals the marker text, present exactly once.
+        if: '!cancelled()'
+        shell: bash
+        run: |
+          fail=0
+          manifest=.claude/.shared-blocks.sha256
+          if [ ! -s "$manifest" ]; then
+            echo "::error::$manifest is missing or empty"; exit 1
+          fi
+          while read -r want name path; do
+            [ -n "$want" ] || continue
+            begin="<!-- ${name}:shared begin -->"
+            end="<!-- ${name}:shared end -->"
+            if [ ! -f "$path" ]; then
+              echo "::error::$manifest names $path, which does not exist"; fail=1; continue
+            fi
+            if [ "$(grep -c -x -F "$begin" "$path")" != 1 ] || [ "$(grep -c -x -F "$end" "$path")" != 1 ]; then
+              echo "::error file=$path::the $name markers must each appear exactly once"; fail=1; continue
+            fi
+            block="$RUNNER_TEMP/$name.block"
+            awk -v b="$begin" -v e="$end" '$0==b{p=1} p{print} $0==e{p=0}' "$path" > "$block"
+            if [ ! -s "$block" ]; then
+              echo "::error file=$path::the $name block is empty"; fail=1; continue
+            fi
+            got=$(sha256sum "$block" | cut -d' ' -f1)
+            if [ "$got" != "$want" ]; then
+              echo "::error file=$path::the $name block changed (sha256 $got, manifest $want)"; fail=1
+            else
+              echo "$name: ok"
+            fi
+          done < "$manifest"
+          exit "$fail"
+
+      - name: Commit subjects
+        # The whole first line of every commit the pull request adds: at most
+        # 72 characters, no trailing period. A pull request opened by
+        # Dependabot is exempt; its subjects are the bot's.
+        if: "!cancelled() && github.event_name == 'pull_request' && github.event.pull_request.user.login != 'dependabot[bot]'"
+        shell: bash
+        env:
+          LC_ALL: C.UTF-8
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          fail=0
+          while IFS= read -r subject; do
+            if [ "${#subject}" -gt 72 ]; then
+              echo "::error::${#subject} characters (max 72): $subject"; fail=1
+            fi
+            case "$subject" in
+              *.) echo "::error::trailing period: $subject"; fail=1 ;;
+            esac
+          done < <(git log --no-merges --format=%s "$BASE_SHA..$HEAD_SHA")
+          exit "$fail"
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..b52002d
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,4 @@
+.DS_Store
+.claude/settings.local.json
+.claude/.cc-writes/
+.claude/worktrees/
diff --git a/README.md b/README.md
index 81d9629..558498c 100644
--- a/README.md
+++ b/README.md
@@ -1,44 +1,79 @@
-# 📊 roanny.github.io — CV / portfolio
+# roanny.github.io
 
-Portfolio profesional de **Roanny Lamas López** (Data Engineer · Google Cloud), publicado con GitHub Pages en **https://roanny.github.io/**.
+The professional CV and portfolio of **Roanny Lamas López** (Data Engineer · Google Cloud), published with GitHub Pages at **https://roanny.github.io/**. One hand-written HTML file in plain HTML, CSS and JavaScript, with no framework and no build step. The site is in English by default, with Spanish.
 
-Construido con HTML, CSS y JavaScript puros en un único archivo — sin frameworks ni paso de build.
+[![Validate](https://github.com/roanny/roanny.github.io/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/roanny/roanny.github.io/actions/workflows/ci.yml)
 
-## Estructura
+## What it does
 
+- Presents the profile, experience, certifications, skills and contact in a single page.
+- Speaks English and Spanish from one set of keys, and follows the visitor's system theme (dark by default, a light "Caribbean day" variant).
+- Carries the SEO a personal site needs: canonical URL, `hreflang`, Open Graph and Twitter cards, `Person` structured data, `robots.txt` and `sitemap.xml`.
+
+## Quick start
+
+```bash
+python3 -m http.server 8000
+# open http://localhost:8000
 ```
-├── index.html       # Todo el sitio: contenido, estilos, i18n y lógica
-├── favicon.svg      # Favicon (sol sobre olas) + favicon-32.png de respaldo
-├── og-image.png     # Social card 1200×630 (previews en LinkedIn/WhatsApp/X)
-├── robots.txt       # Permite indexación y enlaza el sitemap
-├── sitemap.xml      # Mapa del sitio (actualiza lastmod al hacer cambios)
-└── .nojekyll        # GitHub Pages sirve el sitio tal cual, sin Jekyll
+
+## The tree
+
+```
+├── index.html        # The whole site: content, styles, i18n and script
+├── 404.html          # Themed not-found page, self-contained
+├── favicon.svg       # Favicon (sun over waves), with favicon-32.png as fallback
+├── og-image.jpg      # 1200×630 social card (LinkedIn, WhatsApp, X previews)
+├── robots.txt        # Allows indexing and points at the sitemap
+├── 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
+└── .github/          # Validate (ci.yml), its scripts, Dependabot
 ```
 
-## Cómo editar los textos
+## Editing the text
 
-Todo vive en `index.html`. Los textos bilingües están en el objeto **`i18n`** del `<script>` final, en dos diccionarios (`en` y `es`) con las mismas claves; cada elemento traducible lleva `data-i18n="clave"`. Edita el valor en ambos idiomas y, si el cambio es grande, actualiza también el texto por defecto (inglés) en el HTML para mantenerlos alineados.
+Everything lives in `index.html`. The bilingual text is in the **`i18n`** object of the final `<script>`, in two dictionaries (`en` and `es`) with the same keys; every translatable element carries `data-i18n="key"`. Edit the value in both languages and, for a large change, update the default (English) text in the HTML as well so the two stay aligned. CI refuses a key present in one dictionary and missing from the other, and a `data-i18n` key that either one lacks.
 
-## Idioma y tema
+## Language and theme
 
-- **Idioma**: se detecta del navegador (EN por defecto), se fuerza con `?lang=en|es` y se cambia con el botón **EN/ES**; la elección se recuerda.
-- **Tema**: arranca según la apariencia del sistema (oscuro por defecto), se fuerza con `?theme=light|dark` y se cambia con el botón **🌙/☀️**; la elección se recuerda. El tema claro es la variante "caribe de día".
+- **Language**: detected from the browser (English otherwise), forced with `?lang=en|es`, switched with the **EN/ES** button. Only a manual choice is remembered; automatic detection is not stored.
+- **Theme**: starts from the system appearance (dark otherwise), forced with `?theme=light|dark`, switched with the **🌙/☀️** button, which remembers the choice. Until the visitor picks one and while no `?theme=` is in the URL, the theme follows the system live.
 
-## Sistema de diseño
+## Design system
 
-El sitio comparte identidad con [Coabana](https://coabana.github.io/): misma paleta caribeño-tech, tipografías, chips, botones y motion. La referencia canónica de tokens y componentes es el **[DESIGN.md del repo de Coabana](https://github.com/Coabana/coabana.github.io/blob/main/DESIGN.md)** — si cambias un token allí, replícalo en el `<style>` de `index.html`.
+The site shares its identity with [Coabana](https://coabana.github.io/): the same Caribbean-tech palette, typefaces, chips, buttons and motion. The canonical reference for tokens and components is **[`DESIGN.md` in the Coabana site's repository](https://github.com/Coabana/coabana.github.io/blob/main/DESIGN.md)**. A token changed there is copied by hand into the `<style>` of `index.html`.
 
 ## SEO
 
-`index.html` incluye canonical, hreflang (`en`/`es`/`x-default` vía `?lang=`), Open Graph y Twitter cards con `og-image.png`, y JSON-LD de tipo `Person` (con la afiliación a Coabana). Tras cambios de contenido, actualiza `lastmod` en `sitemap.xml`.
+`index.html` carries the canonical URL, `hreflang` (`en`, `es` and `x-default` through `?lang=`), Open Graph and Twitter cards with `og-image.jpg`, and `Person` JSON-LD (with the Coabana affiliation). After a content change, update `lastmod` in `sitemap.xml`.
+
+## Development
 
-## Probar en local
+The gates CI runs, by hand:
 
 ```bash
-python3 -m http.server 8000
-# abre http://localhost:8000
+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
 ```
 
-## Publicación
+`Validate` (`.github/workflows/ci.yml`) runs on every pull request and every push to `main`: HTML validity of both pages, the `i18n` key parity, the sitemap, the fleet's shared blocks and the commit subjects (at most 72 characters, no trailing period). Changes land on `main` by fast-forward once `Validate` is green.
+
+## Deployment
+
+GitHub Pages serves the root of `main`: every push to `main` is live in 1–2 minutes. There are no releases.
+
+## Documentation
+
+| File | What it holds |
+|---|---|
+| `.claude/CLAUDE.md` | How a Claude Code session works in this repository |
+
+## The solution
+
+This site is not part of the Looker Developer Agent and names none of its products. It belongs to the Coabana working set as a site, beside the Coabana site, whose `DESIGN.md` is the source of its design tokens.
+
+## License
 
-GitHub Pages sirve la rama `main` (raíz) automáticamente — al hacer merge, el sitio se despliega solo en 1–2 minutos.
+No license file: the content is the author's, all rights reserved.
diff --git a/sitemap.xml b/sitemap.xml
index 9d2b5ba..b63e8d4 100644
--- a/sitemap.xml
+++ b/sitemap.xml
@@ -2,7 +2,7 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
   <url>
     <loc>https://roanny.github.io/</loc>
-    <lastmod>2026-07-11</lastmod>
+    <lastmod>2026-10-09</lastmod>
     <changefreq>monthly</changefreq>
     <priority>1.0</priority>
   </url>