Migrate site to Hugo markdown and add agent guidance

.cursor/rules/autonomous-workflow.mdc

@@ -0,0 +1,17 @@
+---
+description: End-to-end execution policy after plan approval
+alwaysApply: true
+---
+
+# MOSAIC Autonomous Workflow
+
+Policy: see `AGENTS.md`. Verification: see `verifiable-goals.mdc`.
+
+- For big changes, wait for human plan approval (`multi-agent-workflow.mdc` Phase 1) before editing.
+- After approval, execute end-to-end unless blocked by auth/secrets, destructive actions, or material plan deviations.
+- Prefer small, safe changes; avoid unrelated refactors.
+- Use `npm run build:site` to verify Hugo output after substantive changes.
+- Run long commands in background; monitor until completion.
+- Do NOT commit or push unless explicitly asked.
+- In commits do not add "made with cursor" lines.
+- On substantive changes, recommend or run judge/subagent review before handoff.

.cursor/rules/complete-ticket.mdc

@@ -0,0 +1,26 @@
+---
+description: Requires complete tickets before coding - asks clarifying questions if requirements are missing
+globs: "**/*.{md,txt}"
+alwaysApply: false
+---
+
+# Complete Ticket Requirement
+
+When the user submits a ticket or task via a `.md` or `.txt` file (including `AGENTS.md`):
+
+1. **Check** for: goal, success criteria, context, constraints — same rules as `requirements-gate.mdc`
+2. **If missing** → ask clarifying questions; offer the **Requirements template** in `requirements-gate.mdc`; do NOT code
+3. **If complete** → follow the decision tree in `multi-agent-workflow.mdc`:
+   - Trivial (typo, rename, one-liner) → implement directly
+   - Non-trivial → Plan Mode per `plan-first-workflow.mdc` or Phase 1 per `multi-agent-workflow.mdc` when both apply
+   - Wait for approval before implementation when planning is required
+4. **Never assume** missing details — see `never-assume.mdc`
+
+Verification after implementation: `verifiable-goals.mdc`.
+
+## Coding standards (not covered elsewhere)
+
+- **Stack:** Hugo (markdown content + HTML layouts); CSS in `static/assets/styles.css`; Node scripts for deploy helpers.
+- **Content:** Markdown with YAML front matter; layout via shortcodes in `layouts/shortcodes/`.
+- **Clean edits:** Match existing shortcode and front-matter patterns on sibling pages.
+- **Documentation:** For website tasks, follow and update `docs/website.md` when adding shortcodes or new page patterns.

.cursor/rules/context-management.mdc

@@ -0,0 +1,30 @@
+---
+description: Keep agent context focused across tasks and stale threads
+alwaysApply: true
+---
+
+# Context Management
+
+## Do
+
+- Use `/clear` between unrelated tasks or features.
+- Reference files with `@path` instead of pasting entire file contents.
+- Use `@Past Chats` to pull in prior work instead of copy-pasting old conversations.
+- Start fresh after **2 failed corrections** on the same issue: `/clear`, then write a better prompt that incorporates what you learned.
+- Point website editors at `@docs/website.md` for file locations and shortcodes.
+
+## Don't
+
+- Let context accumulate across unrelated features in one long thread.
+- Describe files vaguely when an `@` reference exists.
+- Keep correcting the same mistake in a degrading context — reset instead.
+
+## When context is stale
+
+Signs you should `/clear` and re-prompt:
+
+- Repeated fixes on the same bug without progress
+- Agent confuses requirements from an earlier, unrelated task
+- Plan has drifted significantly from what was approved
+
+After clearing, restate: goal, approved plan (or link to `.cursor/plans/*.md`), relevant `@` files, and acceptance criteria.

.cursor/rules/multi-agent-workflow.mdc

@@ -0,0 +1,71 @@
+---
+description: Two-phase planning for big changes; builder must not be sole judge
+alwaysApply: true
+---
+
+# Multi-Agent Workflow (Human Plan → Agent Execute)
+
+For **big changes**, split work into two phases. Do not skip Phase 1.
+
+## What counts as a big change
+
+- New page, new shortcode library, or new site-wide layout
+- Expected to touch **3+ files** or **>500 lines** of diff
+- Refactor of Hugo layouts/shortcodes with behavioral risk
+- Touches critical paths (deploy workflows, Firebase, maintainer scripts, secrets)
+- Incomplete requirements or meaningful product/design choices
+
+Small fixes: single-file typo, one markdown paragraph, clear one-liner → `plan-first-workflow.mdc` only.
+
+## Phase 1 — Human-led planning (no code)
+
+**Stop before editing.**
+
+1. Acknowledge this is a big change; planning comes first.
+2. Ask minimum questions: goal, pages affected, pattern to mirror, acceptance criteria, out of scope.
+3. Draft a plan: steps, `@` file paths, similar pages/shortcodes, validation plan, risks.
+4. Wait for explicit approval ("proceed", "approved", or confirmed edited plan).
+5. No commits, push, or implementation code in Phase 1. Read-only research is fine.
+
+## Phase 2 — Agent execution
+
+After approval:
+
+1. Execute per `autonomous-workflow.mdc`.
+2. Follow the approved plan; pause if material deviation is needed.
+3. Implement incrementally; verify as you go (`verifiable-goals.mdc`).
+4. Hand off with checklist including build evidence.
+
+## Builder ≠ Judge (required on substantive work)
+
+| Role | Responsibility |
+|------|----------------|
+| **Builder** | Implements approved plan |
+| **Judge** | Independent review — broken links, layout regressions, deploy impact |
+
+Invoke judge via subagent, parallel agent, or fresh context:
+
+- "Use a subagent to review this change for broken links and layout regressions."
+
+Do not mark substantive work complete without independent review or documented reason to skip.
+
+**Re-review:** Required only when judge findings change behavior, content, or deploy posture materially.
+
+## Decision tree
+
+```
+User request received
+  │
+  ├─ Missing goal / criteria / context / constraints?
+  │     └─ STOP → ask questions OR offer Requirements template (requirements-gate.mdc)
+  │
+  ├─ Typo / rename / one-sentence fix?
+  │     └─ Implement → quality checks → show evidence
+  │
+  ├─ Multi-file / new page / layout refactor / deploy path?
+  │     └─ Plan Mode → detailed plan → WAIT for approval → implement
+  │           → quality checks → subagent review → handoff with evidence
+  │
+  └─ Otherwise
+        └─ Brief plan → implement → quality checks → handoff with evidence
+```

.cursor/rules/never-assume.mdc

@@ -0,0 +1,33 @@
+---
+description: Verify or ask — no guessing packages, APIs, patterns, or incomplete code
+alwaysApply: true
+---
+
+# Never Assume
+
+| Do NOT | Instead |
+|--------|---------|
+| Assume file paths, shortcode names, or menu structure | Read `docs/website.md`; grep `content/mosaic/` |
+| Add new dependencies without explanation | State why, alternatives considered, and get approval |
+| Edit `content/mosaic/public/` | Build output is generated; edit source in `content/` and `layouts/` |
+| Replace code with placeholders, TODOs, or stubs | Ship complete markdown, layouts, and styles |
+| Write incomplete page content | Finish the page or stop and explain what's blocked |
+| Commit or push unless asked | Wait for explicit user request |
+| Commit secrets (`firebase-service-account.json`, tokens) | Use gitignored local files or CI secrets only |
+
+## Scope and diff discipline
+
+- Minimize scope — smallest correct diff; no drive-by refactors.
+- Match surrounding naming, shortcode style, and documentation level.
+- Comments only for non-obvious Hugo/template logic.
+- Do not add markdown/docs files the user did not ask for.
+- Do not use "made with cursor" or similar in commits.
+
+## MOSAIC conventions
+
+- Page content lives in `content/mosaic/content/*.md` only.
+- Navigation lives in `content/mosaic/data/menu.yaml`.
+- Internal links use ugly URLs: `/roadmap.html`, `/team.html`, etc.
+- Images go in `content/mosaic/static/assets/` and are referenced as `/assets/filename.ext`.
+- Use existing shortcodes before inventing new ones — see `docs/website.md`.
+- Prefer `npm run build:site` over ad-hoc Hugo invocations.

.cursor/rules/plan-first-workflow.mdc

@@ -0,0 +1,52 @@
+---
+description: Require Plan Mode and user approval before non-trivial implementation
+alwaysApply: true
+---
+
+# Plan-First Workflow
+
+Apply before non-trivial edits. When criteria overlap with `multi-agent-workflow.mdc` (e.g. new page, 3+ files), follow **multi-agent** Phase 1 — it is the stricter superset.
+
+## Skip planning only for
+
+- Typos, renames, obvious single-line fixes
+- Tasks fully specified with no design choices
+
+## MUST plan before implementing when ANY apply
+
+- New page, new shortcode, or new site-wide layout pattern
+- Multi-file change (3+ files) or >500 lines expected
+- Refactor of layouts/shortcodes with behavioral risk
+- Touches critical paths (deploy workflows, Firebase config, maintainer scripts, secrets)
+- Requirements have meaningful design choices
+
+## Plan output MUST include
+
+1. **Goal** — restated in one sentence
+2. **Files** — exact paths to create/modify/delete
+3. **Dependencies** — new npm packages, Hugo version, Firebase changes
+4. **Steps** — ordered implementation sequence
+5. **Content impact** — which markdown pages and menu entries change
+6. **Edge cases** — broken links, missing assets, mobile layout
+7. **Verification** — `npm run build:site`, optional `npm run serve`, CI
+8. **Risks** — what could break and how to detect it
+
+## Approval gate
+
+After presenting the plan, **wait for explicit user approval** ("proceed", "approved",
+or an edited plan confirmed by the user) before writing implementation code.
+
+Read-only research (grep, read files, explore codebase, read `docs/website.md`) is allowed during planning.
+
+Save approved plans to `.cursor/plans/<feature>.md` when scope is substantial.
+
+## Before editing (Agent Mode)
+
+- Brief plan with reasoning: goal, steps, files touched, validation approach.
+- For website work, consult `docs/website.md` for shortcodes and file locations.
+
+## While editing
+
+- Only modify code relevant to the request.
+- Never use placeholders — include complete, working content and templates.
+- **Reference patterns specifically:** e.g. mirror `@content/mosaic/content/news.md` for a new list page, or `@content/mosaic/layouts/shortcodes/card.html` for a new shortcode.

.cursor/rules/requirements-gate.mdc

@@ -0,0 +1,52 @@
+---
+description: Stop and ask clarifying questions before coding when requirements are incomplete
+alwaysApply: true
+---
+
+# Requirements Gate
+
+If ANY of the following is missing or ambiguous, **STOP and ask clarifying questions**.
+Do NOT write, edit, or delete code until the gaps are filled.
+
+| Required | What to ask |
+|----------|-------------|
+| **Clear goal** | What outcome does the user want? What problem are we solving? |
+| **Verifiable success criteria** | Which checks must pass? (Hugo build, CI, manual preview) |
+| **Context references** | Which files, pages, or prior chats apply? Prefer `@path/to/file` refs when ambiguous. |
+| **Constraints** | Out of scope, URL compatibility, no new deps, Firebase/deploy impact, etc. |
+
+## Context references — when `@` refs are required
+
+- **Satisfied without `@`** when the message names specific paths or pages clearly (e.g. "update the hero text on the home page in `content/mosaic/content/_index.md`").
+- **Ask for `@` refs** when multiple files could apply, the shortcode/layout pattern to mirror is unclear, or prior chat/issue context is needed.
+
+## Skip the gate only when
+
+The request is fully specified in one sentence with obvious success criteria and unambiguous context, e.g.
+"Fix typo in README line 42" or "Change the Roadmap subtitle in `content/mosaic/content/roadmap.md`."
+
+## Requirements template (offer when info is missing)
+
+```
+## Task
+<One-sentence goal>
+
+## Success criteria (all must pass)
+- [ ] `npm run build:site`
+- [ ] Visual check via `npm run serve` (if layout/CSS changed)
+- [ ] CI green (`gh pr checks` or Actions UI)
+- [ ] Other: ___
+
+## Context
+- Files: @content/mosaic/content/roadmap.md
+- Pattern to mirror: @content/mosaic/content/news.md
+- Prior work: @Past Chats / issue # / PR #
+- Editing guide: @docs/website.md (for website work)
+
+## Constraints
+- In scope: ___
+- Out of scope: ___
+- Dependencies: none / explain before adding
+- Deploy: content-only / workflow / maintainer script
+- Secrets: never commit service account JSON
+```

.cursor/rules/verifiable-goals.mdc

@@ -0,0 +1,45 @@
+---
+description: Non-negotiable Hugo build and CI checks with evidence in handoff
+alwaysApply: true
+---
+
+# Verifiable Goals
+
+Agents need pass/fail checks to close the loop. Without verification, the human becomes the verification loop.
+
+## Required checks (site / content / layout changes)
+
+Run in order unless clearly irrelevant (explain why if skipped):
+
+1. `npm run build:site` — Hugo must build with zero errors
+2. `npm run serve` — optional visual spot-check at http://localhost:3000 when layout or CSS changed
+
+## Required checks (scripts / workflow changes)
+
+1. `npm run build:site` — ensure site still builds
+2. If `scripts/set-hosting-retention.js` changed: dry-run logic review; do not run against production without credentials and explicit user request
+
+## CI
+
+When preparing or fixing a PR: all workflow jobs must be green.
+Use `gh pr checks` or the GitHub Actions UI. Fix failures iteratively.
+
+Deploy workflows build Hugo from `content/mosaic/` and publish `public/` to Firebase Hosting.
+
+## Iterate until green
+
+- If any check fails, fix the failure and rerun from the failed step.
+- Do not hand off with failing checks unless blocked; document the blocker explicitly.
+- Before commit (when user asks): all relevant checks must pass.
+
+## Handoff evidence (mandatory)
+
+Report what you ran and the outcome — not assertions:
+
+```
+npm run build:site  — passed (N pages)
+npm run serve       — checked /roadmap.html (if applicable)
+gh pr checks        — all green (if PR-related)
+```
+
+If a check failed, show the Hugo error, the fix, and the rerun result.