Marcos Paulo
dc6cb5a0a3
Pushing main now rebuilds the site and force-pushes dist/ to pages. .agents/scripts/publish-pages.sh does the work. It never checks pages out: it writes a tree straight from dist/ with write-tree and commit-tree, so the working tree is untouched and a failure halfway through leaves nothing behind. The commit is parented on the current pages tip, so the branch keeps its history and a rollback is one force-push to an earlier commit -- which the script prints before it pushes. It refuses to publish when the working tree is dirty, when HEAD is not main, when HEAD is not the commit being pushed, or when any of the ten routes is missing or empty in dist/. A build can succeed and still emit a stub; that is exactly how this site would go down. The hook guards three ways. AF_PUBLISHING short-circuits it so the publisher's own push does not re-enter it forever. AF_NO_PUBLISH=1 lets you push main without publishing. And because git has no post-push hook, the publish necessarily runs before main lands -- so it first checks that the remote tip is an ancestor of what is being pushed, and skips publishing when the push could still be rejected as a non-fast-forward. Also rewrites the operations guide's rollback section, which still described merging main into pages with --ff-only. That has not been true since pages started carrying build output. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
97 lines
5.3 KiB
Markdown
97 lines
5.3 KiB
Markdown
# 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`](.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.
|
|
|
|
- **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**: a Go + Kubernetes vote API, reached over
|
|
`window.SKILLS_REVIEW_VOTE_API`. Its source is no longer in this repository
|
|
|
|
## Essential commands
|
|
|
|
```bash
|
|
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 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 it now carries **build output**, not a copy of `main`'s
|
|
tree.
|
|
|
|
**Pushing `main` republishes the live site.** The `pre-push` hook runs the gate,
|
|
then `.agents/scripts/publish-pages.sh`, which builds and force-pushes `dist/`
|
|
to `pages`. Use `AF_NO_PUBLISH=1 git push` to land a commit without publishing.
|
|
`pages` keeps its history, so rollback is a single force-push to an earlier tip;
|
|
`pages-backup-2026-09-06` is the last commit of the hand-written site. 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
|
|
|
|
- `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
|
|
- `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`](.agents/rules/astro.md) | any `.astro` file |
|
|
| [`theming.md`](.agents/rules/theming.md) | any colour, font, or spacing value |
|
|
| [`componentization.md`](.agents/rules/componentization.md) | creating or splitting a component |
|
|
| [`animation.md`](.agents/rules/animation.md) | any motion, transition, or transform |
|
|
| [`accessibility.md`](.agents/rules/accessibility.md) | any interactive element |
|
|
| [`content-i18n.md`](.agents/rules/content-i18n.md) | any user-visible string |
|
|
| [`code-style.md`](.agents/rules/code-style.md) | always |
|
|
| [`git-worktrees.md`](.agents/rules/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`](.agents/context/design-system.md) before
|
|
touching any CSS.
|