Files

T

Marcos Paulo 580293867d 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>

2026-09-06 08:30:27 +00:00

5.1 KiB

Raw Blame History

AI For Dummies

A lightweight, presentation-style field guide to AI-assisted engineering.

It explains how to combine a strong planning/review model with faster workers, reusable skills, subagent handoffs, Git worktrees, and explicit verification. An interactive field kit compares common behavior skills such as ponytail-lite, caveman, unlazy, research, debugging, and review. The skill-forge workflow covers discovery, triggers, package anatomy, progressive instructions, structural validation, and behavioral iteration. The hands-on lab provides a tiny starter project and copy-ready baseline and skill-enabled prompts for a short side-by-side exercise. An interactive model gearbox separates capability tier from reasoning effort across OpenAI, Claude, and Gemini, and every featured skill links to a pinned source with an approval-first installation prompt.

Run locally

This is an Astro static site. It builds to dist/ and ships no runtime dependencies.

pnpm install
pnpm run dev        # http://localhost:4321/ai-for-dummies/
pnpm run build      # writes dist/
pnpm run preview    # serves the built output

Verify the content and interaction contracts with:

pnpm run verify     # reads dist/, so build first

The full gate — astro check, astro build, verify.mjs, audit-ui.mjs, check-tokens.mjs, and the assertion-count floor — runs as:

bash .agents/scripts/gate.sh

Project structure

src/pages/ — one file per route: the landing route map, the complete bilingual full-guide, the chapter pages, rules, skills, and skills-review
src/components/ — blocks and islands; the interactive diagrams, selectors, and the language toggle
src/content/ — the content collections every page renders from
src/styles/tokens.css — the design tokens
legacy/ — the editorial visual system and the review-desk modules, not yet migrated into components. Still imported by the pages that need them; see .agents/context/architecture.md
public/ — assets copied to the site root verbatim: fonts, the hands-on labs, and submitted-skills/
docs/references/ — bundled research sources and notes
docs/operations-guide.md — canonical SilverBullet operations and skills guide
public/hands-on/starter/ — dependency-free Tiny Tasks exercise
public/hands-on/rules/ — dependency-free Guardrails lab; toggles rule sources into the prompt
skills/ — reusable design and rules-case-study skills
vote-service/ — small Go API + Kubernetes manifests backing the skills-review vote widget (see vote-service/README.md)
GATES.md — acceptance ledger for the project

Publishing

The Gitea instance has a Pages Server configured to publish a repository’s pages branch under pages.marcospaulo.dev.br. pages now carries the built site — the contents of dist/ — not a copy of main. The intended site address is:

https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/

If the URL is not available yet, verify that the pages branch exists and that the repository’s pages branch exists. Gitea itself does not provide a built-in Pages server; this setup uses the instance’s separate Pages Server and Actions deployment path.

For the complete authoring, verification, publication, rollback, worktree, and skill workflow, see docs/operations-guide.md.

Reader voting on the skills-review desk

skills-review/ is static, so its "which draft would you ship?" vote widget calls a separate stateful service — vote-service/, a small Go API on its own pod, one vote per visitor enforced server-side by IP (a MAC address is never visible to a server across the internet, so it cannot be used). See vote-service/README.md for the API, the anti-abuse design, and the build/push/deploy steps; src/pages/skills-review.astro sets window.SKILLS_REVIEW_VOTE_API to point at it once deployed.

Research

See docs/references/README.md for official Claude, Codex, and Git documentation. The additional reading path bundles 12 verified articles and guides, including Medium and practitioner sources. See model routing for current provider controls and verified skill sources for commit-pinned provenance.

Rules and enforcement case study

Open /rules/ for a concise walkthrough grounded in the netcracker/interview repository. It shows how AGENTS.md, project-local skills, machine-readable repo ledgers, a UI contract ratchet, lint-staged, Husky, commitlint, specialist verifier agents, and PR review reinforce one another. Every example links to its source file in Gitea, and the page includes a copy-ready prompt for mapping the same layers in another repository.

The implementation patterns are also packaged as project-local skills in skills/. Use editorial-playbook when adding chapters or sections, and rules-case-study when turning repository controls into a source-linked teaching page.

5.1 KiB Raw Blame History Unescape Escape