gud

1 files changed, 52 insertions, 0 deletions

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..2893e8e
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,52 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `src/`: application code.
+  - `components/`: UI components (e.g., `Flashcard/`, `tones/`, `ui/`).
+  - `actions/`: server actions (data fetching/mutations).
+  - `lib/`: shared types, helpers, config.
+- `public/`: static assets served as-is.
+- `dist/`: build output (generated).
+- `waku.config.ts`: Waku app configuration.
+- `bulkdata/`: project data assets.
+
+Use absolute imports with `@/` (configured via tsconfig paths).
+
+## Build, Test, and Development Commands
+- Setup: `bun install` — install dependencies.
+- Dev: `bunx --bun waku dev` — start the dev server with hot reload.
+- Build: `bunx --bun waku build` — produce production build in `dist/`.
+- Start: `bunx --bun waku start` — run the production server.
+
+Example: `BUN_INSTALL_CACHE=1 bun install && bunx --bun waku dev`
+
+## Coding Style & Naming Conventions
+- Language: TypeScript + React 19, Tailwind CSS 4.
+- Components: `.tsx`, PascalCase filenames (e.g., `ToneSelectorClient.tsx`).
+- Utilities/types: camelCase files in `lib/`.
+- Client components must begin with `"use client"` when using hooks/browser APIs.
+- Prefer functional components and hooks; keep side-effects in `useEffect`.
+- Follow existing Tailwind class patterns; co-locate small helpers with components.
+
+## Testing Guidelines
+- No formal test suite is enforced yet. If adding tests:
+  - Place unit tests next to source (`Component.test.tsx`) or under `src/__tests__/`.
+  - Use Bun’s test runner (`bun test`) or Vitest if introduced.
+  - Keep tests fast and focused; mock network/IO.
+
+## Commit & Pull Request Guidelines
+- Commit messages in history are informal; prefer concise, imperative subject lines.
+- Recommended: Conventional Commits (e.g., `feat: add tone keyboard nav`).
+- PRs should include:
+  - What/why summary and screenshots or clips for UI changes.
+  - Linked issues or TODO references.
+  - Scope-limited diffs and notes on breaking changes or migrations.
+
+## Security & Configuration Tips
+- Avoid committing secrets; prefer environment variables (configure via hosting env).
+- Validate inputs in server actions under `src/actions/`.
+- Keep client-only code behind `"use client"`; avoid leaking server internals to the browser.
+
+## Architecture Notes
+- App is a Waku + Bun React app. Pages and interactive views live under `src/components/**`. UI patterns like 3D flip (see `components/Flashcard/`) are shared across features (e.g., `tones/`). Reuse existing utilities and styles for consistency.
+