<!-- BEGIN:nextjs-agent-rules -->

## This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.

This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.

<!-- END:nextjs-agent-rules -->

# Repository conventions

Marketing and documentation site for **Aloha Social** (aloha.social). Static export: `next build` emits `out/`, `postbuild` adds `sitemap.xml` + `robots.txt`. Source: https://github.com/AlohaSocial/website (branch `main`).

## Commands

| Command | What it does |
|---|---|
| `npm run docs` | Regenerates `src/generated/*` from `content/` (also runs automatically via `predev`/`prebuild`) |
| `npm run lint` | ESLint — must be clean |
| `npm test` | Vitest — 20 tests, all must pass |
| `npm run build` | Full verification build incl. sitemap generation |
| `npm run dev` | Dev server (re-runs `npm run docs` first) |

**Verification loop for every change:** edit → `npm run docs` → `npm run lint` → `npm test` → `npm run build` → internal link check → commit → push. Do not push without a green build.

## Content architecture

- `content/pages/*.md` — hand-written site pages. Frontmatter: `path`, `title`, `description` (first h1 is redundant but kept). The `path` defines the route.
- `content/upstream/*.md` — synced docs from `AlohaSocial/social`. **Never hand-edit**; changes are overwritten on the next sync.
- `scripts/build-docs.mjs` generates `src/generated/{docs,pages,search}.ts`. **Never edit these by hand** — regenerate with `npm run docs`.
- Search index is generated too; curated extras live in `src/lib/search.ts` (`SITE_PAGES`, `FEATURE_PAGES`).

## Adding a page

1. `content/pages/<name>.md` with frontmatter `path: /<name>`
2. `src/app/<name>/page.tsx` — the 7-line `StaticMarkdownPage` pattern (copy an existing one, e.g. `src/app/gdpr/page.tsx`)
3. Link it in `src/components/site-footer.tsx` and in `content/pages/sitemap-page.md`
4. `npm run docs` + build — `sitemap.xml` picks it up automatically (generated by scanning `out/*.html`, do not maintain route lists by hand)

## House style

- **Native apps (Android/Apple) are written in the present tense as available and working** — this is an explicit editorial decision, do not "correct" it to future tense based on upstream READMEs that say "not released".
- Branding is **Aloha Social** / **your Aloha**; upstream docs still contain "Nextcloud Social" wording — replace on the site, keep upstream files untouched.
- No new dependencies unless unavoidable (search is hand-rolled on purpose).
- External sources: raw READMEs from `AlohaSocial/{social,Android,Apple}` on GitHub.

## Design system

- Tailwind 4 tokens via `@theme inline` in `src/app/globals.css`: `canvas`, `surface`, `surface-2`, `ink`, `ink-strong`, `muted`, `line`, `coral`, `coral-soft`, `sea`, `sand`, `deepsea`.
- Utility classes: `btn btn-primary/outline/quiet/sea`, `card`, `eyebrow`, `pill`, `segmented`, `md-prose`.
- Shared components in `src/components/ui.tsx`: `Container`, `PageHeader`, `SectionHeading`, `CtaBand`, `CheckList`, `Screenshot`, `RelatedPages`.
- New components follow the existing file style; server components by default, `"use client"` only when state/interaction is required.

## Git

- Plain imperative commit subjects, no conventional-commit prefix (e.g. `Add a native command-palette search across the whole site`).
- Commit and push to `main` after a green verification loop when a task is finished; include regenerated `src/generated/*` and the `AGENTS.md` block in the same commit.
