refactor: retire the hand-written site

Deletes the pre-Astro pages, scripts, and stylesheets that the migration
replaced, and moves the ones it did not replace out of the way.

Deleted (32 files): app.js, responsive.css, landing.css, rules/app.js,
rules/styles.css, skills/app.js, the ten route index.html files, and the
root hands-on/ copy, which is byte-identical to public/hands-on/ -- the
one the build actually ships.

Moved to legacy/ (12 files): styles.css, full-guide/audit.css,
chapters.css, skills/styles.css, skills-review/styles.css,
skills-review/change-lens.css, and the skills-review/app.js module graph.
These are not dead. The Astro pages import them and the build fails
without them, which the plan had not accounted for. They go to legacy/
rather than src/ because check-tokens.mjs sweeps src, and these files are
full of raw hex and unnamed breakpoints: moving one into src/ should mean
migrating it to tokens in the same change, not adding a scan exclusion.
The prettier, stylelint, and eslint ignore lists that already named these
files at their old paths now name legacy/ instead.

verify.mjs no longer reads app.js. The 102 Portuguese strings were
extracted from its translations.pt object before deletion into
.agents/snapshots/full-guide-pt.json -- a legacy capture, not a snapshot
of the Astro build, so the assertion still compares against an
independent source. The brace-matching helper's assertion is replaced by
one that rejects an empty snapshot entry, without which trimming the
snapshot would make the presence check pass vacuously. Count stays at 84.

audit-ui.mjs reads the ten pages from dist/ and resolves Astro's
base-absolute hrefs against it.

Before deleting anything, rendered-text-diff was run across all ten
routes plus both Portuguese pages: every one at parity, 0 missing and 0
extra. That comparison is not repeatable once the legacy files are gone.
computed-style-diff on /full-guide/ stays at 32 differences, so the moves
are style-neutral.

Docs updated to match: README, AGENTS.md, GATES.md, the architecture
context, the operations guide's lab instructions, and the three skills
that told you to serve the vanilla site.

Publishing is not part of this commit.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Marcos Paulo
2026-09-06 08:30:27 +00:00
parent 12c32d2fd7
commit 580293867d
57 changed files with 367 additions and 1287 deletions
+21 -20
View File
@@ -12,11 +12,11 @@ rules, and verification.** It is published as a static site on a self-hosted
Gitea Pages Server, and it doubles as its own teaching artifact: the hands-on
labs are dependency-free HTML/CSS/JS that workshop attendees point an agent at.
- **Current stack**: hand-written HTML + CSS + ES modules, no build step, no
dependencies
- **Target stack**: Astro (see
[`plans/astro-refactor/`](plans/astro-refactor/README.md)) — migration in
progress
- **Stack**: Astro, static output, no runtime dependencies. The migration
recorded in [`plans/astro-refactor/`](plans/astro-refactor/README.md) is
complete; the hand-written pages it replaced are gone. What remains unmigrated
is the editorial CSS and the review-desk modules under `legacy/`, still
imported by the pages that need them.
- **Languages**: English and Brazilian Portuguese, toggled client-side
- **Companion service**: `vote-service/` (Go + Kubernetes) — separate lifecycle,
see its own README
@@ -24,33 +24,34 @@ labs are dependency-free HTML/CSS/JS that workshop attendees point an agent at.
## Essential commands
```bash
pnpm run verify # content + interaction contracts (scripts/verify.mjs) — the gate
pnpm run dev # http://localhost:4321/ai-for-dummies/
pnpm run build # writes dist/ — every check below reads it
bash .agents/scripts/gate.sh # the full gate: check, build, verify, audit, tokens
pnpm run verify # content + interaction contracts (scripts/verify.mjs)
node scripts/audit-ui.mjs # responsive / no-external-dependency audit
node scripts/build-skill-review.mjs # regenerate skill-reviews/improved/ from src/content/reviews/
pnpm run serve # python3 -m http.server 4173
```
`pnpm run verify` is not a formality. It is a set of ~42 string-token assertions
that pin the site's real content and interactions. **A refactor that "passes" by
deleting assertions has failed.** See
`pnpm run verify` is not a formality. It is a set of 84 string-token assertions
that pin the site's real content and interactions, read from the built output.
**A refactor that "passes" by deleting assertions has failed.** See
[`.agents/context/verification.md`](.agents/context/verification.md).
## Publishing
`main` is the source of truth. The `pages` branch is what the Gitea Pages Server
actually serves, and its tree must end up identical to `main`'s. The full
procedure — including why `merge --ff-only` does _not_ work here — is in
[`docs/operations-guide.md`](docs/operations-guide.md).
Adding a build step changes this contract. Read
[`.agents/context/publishing.md`](.agents/context/publishing.md) before doing
so.
actually serves, and it now carries **build output**, not a copy of `main`'s
tree. The publish job force-pushes `dist/` over it. The full procedure is in
[`docs/operations-guide.md`](docs/operations-guide.md); read
[`.agents/context/publishing.md`](.agents/context/publishing.md) before changing
it.
## Never touch
- `hands-on/starter/` and `hands-on/rules/`**lab fixtures.** The exercise
_is_ that they are dependency-free vanilla HTML/CSS/JS an attendee can hand to
an agent. Componentizing them destroys the lesson. They ship as static assets.
- `public/hands-on/starter/` and `public/hands-on/rules/`**lab fixtures.**
The exercise _is_ that they are dependency-free vanilla HTML/CSS/JS an
attendee can hand to an agent. Componentizing them destroys the lesson. They
ship as static assets.
- `submitted-skills/` — other people's submitted work, reproduced verbatim
- `skill-reviews/improved/` — generated; edit `src/content/reviews/*.md` instead
- `vote-service/` — separate deploy lifecycle; do not fold into the site build