netcracker/ai-for-dummies

Fork 0

Files

T

Marcos Paulo dc6cb5a0a3

verify-and-publish / gate (push) Successful in 22m13s

Details

verify-and-publish / publish (push) Has been skipped

Details

ci: publish to pages from a pre-push hook

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>

2026-09-06 09:06:21 +00:00

5.3 KiB

Raw Blame History

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.

Stack: Astro, static output, no runtime dependencies. The migration recorded in plans/astro-refactor/ 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

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.

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; read .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`	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.

5.3 KiB Raw Blame History