Marcos Paulo
79920c9e6c
Three strands of work on the chapter surface, all reading from the same constraint: this site ships no runtime dependencies, so every effect below is native CSS or an .astro component. Motion (src/styles/motion.css, DrawRule.astro). A scroll-driven layer of reveals, hero parallax, section depth, and a hairline that paints itself along its path, scrubbed by `animation-timeline: view()` — 0KB against lottie-web's ~60KB gzipped on the main thread. Every scrubbed rule sits inside `prefers-reduced-motion: no-preference` and `@supports`, so a Firefox reader or an opted-out one gets the complete static page rather than one with holes in it. Ranges key to `cover 40%`-`cover 75%` where the motion is meant to be watched: `view()` ranges key to first visibility, which on a 2600px page is long before anyone is reading the section. `.agents/skills/motion/references/scroll-driven.md` records the technique and the two ways `pathLength` normalisation was broken while building it. Diagrams (StepFlow.astro, WorktreeMap.astro). The `.steps` stack on /skills/, /models/, and /agents/ becomes a numbered flow with connectors, and /agents/ grows the worktree map it was describing in prose — reusing the `trees` collection rather than a second set of strings. The map's static variant is gated one class deeper than full-guide's page styles, so the interactive copy renders byte-identical. Connectors are pseudo-elements, not SVG: a stretched path desynchronises its own dash pattern, and a straight line does not need one. Mermaid was considered and rejected at ~1MB of runtime. Retrieval practice (/rules/, /skills/). A "check yourself" section of native `<details>` question/answer pairs plus a citation row, both bilingual through the existing `data-copy` toggle, and both JavaScript-free. Two audit blind spots surfaced and are closed rather than worked around: `build.inlineStylesheets: 'never'`, because Astro inlined sheets under ~4kB and audit-ui.mjs reads its colour and size baseline from dist/_astro/*.css; and `--columns` declared in the grid components, because an element-level custom property is not a declaration the audit can resolve. legacy/styles/skills.css is renamed and imported for its side effect. Inside a *page*, `?url` resolves to that page's own CSS chunk whatever file it names, so the link pointed at the wrong asset and the sheet was emitted but never loaded — the package preview had been rendering unstyled and overflowing since the Astro cutover. verify.mjs gains 5 assertions for the recall sections and their Portuguese copy: 89 now, against the 84 baseline. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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 bilingualfull-guide, the chapter pages,rules,skills, andskills-reviewsrc/components/— blocks and islands; the interactive diagrams, selectors, and the language togglesrc/content/— the content collections every page renders fromsrc/styles/tokens.css— the design tokenslegacy/— 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.mdpublic/— assets copied to the site root verbatim: fonts, the hands-on labs, andsubmitted-skills/docs/references/— bundled research sources and notesdocs/operations-guide.md— canonical SilverBullet operations and skills guidepublic/hands-on/starter/— dependency-free Tiny Tasks exercisepublic/hands-on/rules/— dependency-free Guardrails lab; toggles rule sources into the promptskills/— reusable design and rules-case-study skillsGATES.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 — 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). Its source no longer lives in this
repository; the deployed service is unchanged. src/pages/skills-review.astro
sets window.SKILLS_REVIEW_VOTE_API to point at it.
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.