Files

T

Marcos Paulo aae4d42229 docs: add .agents workspace and the Astro refactor plan

Adds the agent-facing workspace and a 20-task plan for migrating the site
to Astro. Nothing here implements the refactor; these are briefs, rules and
templates that the task agents read.

- .agents/ holds context, rules, checklists, skills, specialist agents,
  component/page/config templates and gate scripts. It is vendor-neutral so
  MiniMax, Gemini and Codex can all read it; CLAUDE.md just points at
  AGENTS.md.
- .husky/ plus .lintstagedrc.json wire the three gate tiers. gate.sh locks on
  the shared git-common-dir so parallel worktrees serialise, and guards the
  assertion count in scripts/verify.mjs against a coverage drop.
- plans/astro-refactor/ carries the phase graph, per-task briefs and the
  model-routing recommendation.

These files must be tracked before fanning out: a worktree only checks out
tracked files, so an untracked plan is invisible to every agent working in one.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-09-05 01:18:27 +00:00

2.8 KiB

Raw Blame History

Context: publishing, and what a build step changes

How it works today

The Gitea Pages Server serves the pages branch tree directly. There is no build. main and pages end up with byte-identical trees; pages exists only because the Pages Server publishes a branch, not a directory.

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

Full procedure, including the fact that merge --ff-only main fails (the histories diverged), is in ../../docs/operations-guide.md.

What Astro changes

Astro emits dist/. The Pages Server cannot run a build, so something has to put built output on pages. Pick one, deliberately, in task 01:

Option	How	Cost
A. Build locally, commit `dist/` to `pages`	`npm run build`, copy `dist/*` into the `pages` worktree, commit	`pages` stops being "the exact source". Diffs become unreadable. Publishing depends on one workstation. Simple, no new infra.
B. Gitea Actions builds and pushes `pages`	workflow on `main` → `npm ci && npm run build` → force-push `dist/` to `pages`	`pages` becomes a machine-owned branch (force-push is fine because nothing else writes it). Needs the act-runner to be healthy. Recommended.
C. Serve from a container instead	drop Pages Server for an nginx pod behind the existing ingress	most control, most infra, changes the URL story

Recommended: B, with A as the documented manual fallback for when the runner is down. Note the known failure mode: this Gitea's act-runner registration lives in an emptyDir, so a pod restart silently kills CI until re-registered. The runbook must say "if the site stopped updating, check the runner first".

Whichever you pick, docs/operations-guide.md must be rewritten in the same task — it currently promises pages is "the exact published source", and that stops being true under A and B.

Base path

The site is served from a subdirectory: /ai-for-dummies/. Astro needs base: '/ai-for-dummies' in astro.config.mjs, and every internal link must go through import.meta.env.BASE_URL or Astro's <a href={...}> helpers rather than a hand-written absolute /models/.

This is the single most likely source of "works locally, 404s in production" in this migration. Verify it on the real host, not just npm run preview.

Verification before you call it published

curl -sS -o /dev/null -w '%{http_code}\n' \
  "https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/?v=$(git rev-parse --short HEAD)"

The ?v= cache-buster matters: the Pages Server caches, and a stale 200 looks exactly like a successful deploy. Check one nested route (/ai-for-dummies/skills-review/) and one static asset too — the base-path bug shows up on assets first.

2.8 KiB Raw Blame History