Agents

Author: gunta

AGENTS.md

@@ -0,0 +1,37 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `src/app` hosts Next.js App Router routes: `(home)` for the landing page, `docs` for the spec, and `api` for server handlers.
+- Shared React lives in `src/components`; cross-cutting layout and data helpers sit in `src/lib`.
+- Canonical docs and examples live under `content/docs` and `content/references`; keep folder slugs stable to preserve OG images and LLM exports.
+- ReScript sources (`*.res`) output tracked `.res.mjs`; edit the `.res`, commit the pair, and treat the artefact as a snapshot check.
+- Root configs (`next.config.mjs`, `middleware.ts`, `source.config.ts`) handle routing and static generation—mirror their patterns when extending.
+
+## Build, Test, and Development Commands
+- `bun install` refreshes dependencies after pulling.
+- `bun run docs:dev` launches the Turbo dev server at `http://localhost:3000`.
+- `bun run docs:build` runs the production pipeline; execute before every PR.
+- `bun run docs:start` serves the build for smoke-testing.
+- `bun run res:dev` watches ReScript; `bun run res:build` performs a clean compile; pair with `bun run res:clean` if artefacts drift.
+
+## Coding Style & Naming Conventions
+- TypeScript/TSX follows Prettier defaults (2-space indent, semicolons, single quotes); rely on format-on-save or `bunx prettier`.
+- Export React components in PascalCase and keep route file names lowercase.
+- Prefer explicit bindings in ReScript and TitleCase module names; avoid unchecked external calls.
+- MDX files need concise frontmatter and relative links so the Fumadocs loader resolves correctly.
+
+## Testing Guidelines
+- No automated suite yet—ensure `bun run docs:build` succeeds and manually spot-check `/` and `/docs`.
+- Review the generated `.res.mjs` diff for ReScript changes to catch compiler regressions.
+- Add MDX demos for new interactive components and document manual QA steps in PRs.
+
+## Commit & Pull Request Guidelines
+- Commit history skews toward short descriptive subjects; keep messages imperative, ≤72 characters, with detail in the body.
+- Reference related issues and note affected routes or content directories.
+- PRs should include a summary, verification checklist, and visuals for UI or content shifts; request review from domain owners and wait for a clean build.
+
+## Architecture Overview
+- Next.js 15 powers the app, with Fumadocs loaders defined in `src/lib/source.ts`; OG images and LLM extracts rely on stable slugs, so avoid renaming docs without redirects.
+
+## Issues
+We track work in Beads instead of Markdown. Run `bd quickstart` to see how.