# 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`** | `pnpm 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` → `pnpm install --frozen-lockfile && pnpm 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 `pnpm 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.