Marcos Paulo
aae4d42229
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>
55 lines
2.8 KiB
Markdown
55 lines
2.8 KiB
Markdown
# 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`](../../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
|
|
|
|
```bash
|
|
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.
|