# Task 01 — Astro scaffold, gates, and the publishing decision

**Agent**: `astro-architect` · **Model**: Codex · **Depends on**: nothing
**Blocks**: everything · **Worktree**:
`.agents/scripts/worktree.sh start 01 scaffold`

## Goal

A working Astro project that builds, serves one page correctly from the real
host under `/ai-for-dummies/`, and has all three gate tiers live.

## Scope

`astro.config.mjs`, `package.json`, `tsconfig.json`,
`src/layouts/BaseLayout.astro`, `.husky/`, `.lintstagedrc.json`, lint configs,
`.gitea/workflows/verify.yml`, `docs/operations-guide.md`.

Copy the configs from `.agents/templates/config/` — they are written for this
project (correct ignores for `hands-on/`, `submitted-skills/`, `vote-service/`).

## Steps

1. `pnpm create astro@latest` into the worktree — minimal template, TypeScript
   strict, **no UI framework, no CSS framework**.
2. Set `base: '/ai-for-dummies'`. Every internal link goes through
   `import.meta.env.BASE_URL` from here on.
3. `src/layouts/BaseLayout.astro`: `<html lang>`, viewport meta, title,
   description, global styles slot. Nothing clever.
4. Merge `.agents/templates/config/package.scripts.json` into `package.json`.
   **`"prepare": "husky"` is what makes hooks exist** — without it every hook is
   inert.
5. `pnpm install husky lint-staged prettier eslint stylelint …`, then
   `pnpm exec husky init`.
6. Copy the three hooks and the lint configs into place. Verify with
   `.agents/scripts/verify-hooks.sh`.
7. Migrate **one** page (`summary/` — smallest, zero JS) as a smoke test.
8. Copy `hands-on/` into `public/` (task 17 does this properly; a stub is fine
   here).
9. **Make the publishing decision** per `.agents/context/publishing.md`.
   Recommended: Gitea Actions builds `dist/` and pushes `pages`. Copy
   `.agents/templates/config/gitea-ci.yaml` to `.gitea/workflows/verify.yml`.
10. Rewrite the publishing section of `docs/operations-guide.md` to match.

## Done when

- [ ] `pnpm run build` succeeds; `pnpm run gate` passes
- [ ] `.agents/scripts/verify-hooks.sh` reports hooks live
- [ ] A bad commit message is rejected; a raw hex in a `.astro` file is rejected
- [ ] `/ai-for-dummies/summary/` serves correctly **from the real host**, not
      just preview
- [ ] `docs/operations-guide.md` describes the actual publishing path

## Do not

- Do not migrate more than one page. That is tasks 12–16.
- Do not add a UI framework, CSS framework, or any runtime dependency.
- Do not touch `hands-on/` contents, `submitted-skills/`, or `vote-service/`.

## Watch for

The base path is the #1 production-only failure in this migration.
`pnpm run preview` will lie to you. Deploy the smoke-test page and curl it with
a `?v=<sha>` cache-buster.
