docs: add AGENTS.md so a new project inherits the rules on day one

[owjs3901]

Why

A project created from this template (fun-deposit, cloned 2026-09-13) was implemented as a Vite SPA — a main.tsx swapping screens on local state, with authored .css files beside code that has globalCss() — by an agent that had been given the devup-ui skill and nothing else.

Neither mistake was unreasonable from inside the repository:

• vinext runs Next App Router on Vite. So apps/front has a vite.config.ts, no next.config.ts, and uses @devup-ui/vite-plugin. An agent that does not know vinext reads that as a Vite SPA — and the devup-ui skill lists Vite first among its build plugins, which confirms the misreading.
• devup-ui is a styling skill and correctly says nothing about project structure. The rules that would have caught it live in devfive-frontend, which that machine did not have.

A skill only helps a machine that has it installed. AGENTS.md travels with the clone.

What this adds

A single root AGENTS.md, 131 lines, covering only what has actually been broken plus the minimum needed to act on it:

1. This is App Router despite vite.config.ts — with the evidence from this repo's own package.json (vinext dev/build/start) and layout.tsx (import type { Metadata } from 'next'). States plainly that there is no main.tsx or index.html, and shows the state-machine anti-pattern next to the file-routing fix.
2. Never author a CSS file — there is none in this template and none should be added. Points at resetCss(), already called in apps/front/src/app/layout.tsx, and globalCss().
3. File placement — app/ holds only layout.tsx and page.tsx; the Server Component default; the public/icons/*.svg rule.
4. Theme tokens — notes that apps/admin has a devup.json and apps/front does not yet, and that $token only resolves in a JSX prop.
5. Verification commands — taken from the actual package.json (oxlint, bun test, cargo clippy), including the cd apps/front && bun dev vs bun -F front dev zombie-process note.
6. How to get the full skills — devup_skills { "action": "install" }, which carries devfive-frontend, devup-ui, vespera and vespertide and installs them with no network.

The file is explicitly scoped as "the minimum that has to be true even when no skill is loaded" — the depth stays in the skills.

Related

• feat(skills): carry devfive-frontend and let a skill be more than one file devup-mcp#63 — carries devfive-frontend in the binary so devup_skills install can deliver it to a bare machine
• docs(skill): say what decides static extraction, and never author a CSS file devup-ui#665 — adds the vinext note, the no-CSS-file rule and the extraction rule to the devup-ui skill

Note

Docs only, no code touched. One thing I noticed while reading and did not change: apps/front/vite.config.ts calls DevupUI() without include: ['@devup-ui/reset-css'], while layout.tsx does call resetCss(). If the plugin does not auto-process that package at 1.0.69, the reset classes may not be emitted — worth a separate check, but I did not want to touch build config in a docs PR.