ai-for-dummies/AGENTS.md

AGENTS.md

Entry point for any AI agent or new engineer working in this repository. Read this file, then follow the links you need. Full map: .agents/ORCHESTRATOR.md.

What is this project?

"AI For Dummies" — a bilingual (EN/PT-BR) presentation and workshop about working with coding agents: model routing, subagents, git worktrees, skills, 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/) — migration in progress
• Languages: English and Brazilian Portuguese, toggled client-side
• Companion service: vote-service/ (Go + Kubernetes) — separate lifecycle, see its own README

Essential commands

pnpm run verify     # content + interaction contracts (scripts/verify.mjs) — the gate
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 .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.

Adding a build step changes this contract. Read .agents/context/publishing.md before doing so.

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.
• 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
• dist/, node_modules/ — build output, never committed
• pnpm-lock.yaml — committed, but never hand-edited. Change it only as a side effect of pnpm install. Every worktree spins up with pnpm install --frozen-lockfile, which fails outright without it.
• This project is pnpm-only (packageManager in package.json pins the version). Never run npm install or bun install here — the gate rejects a package-lock.json, yarn.lock, or bun.lock outright. pnpm settings live in pnpm-workspace.yaml, not in a pnpm field in package.json; pnpm 11 ignores that field silently.

Rules

Binding. Read the one that covers what you are about to do.

Rule	When
astro.md	any .astro file
theming.md	any colour, font, or spacing value
componentization.md	creating or splitting a component
animation.md	any motion, transition, or transform
accessibility.md	any interactive element
content-i18n.md	any user-visible string
code-style.md	always
git-worktrees.md	starting or finishing a task

The one thing to understand first

This site's styling is not a design system today. Three near-duplicate palettes have drifted apart (--ink exists as #172f42, #122534, and #173044), and the @font-face rule in styles.css:1 is malformed, so the intended Manrope/DM Mono typography has never actually rendered. "Maintain the same styles" therefore needs a deliberate decision, not a copy-paste. Read .agents/context/design-system.md before touching any CSS.