From 6323a3f41c69ed5e42289bf520bff978acac42e4 Mon Sep 17 00:00:00 2001
From: kenneth <kenneth@nym.sh>
Date: Sun, 21 Sep 2025 16:05:39 +0000
Subject: [PATCH] docs: add project guidelines and commit conventions

- Add AGENTS.md with tech stack, project structure, and code styles
- Add dev/docs/dashboard.md with frontend-specific guidelines
- Include conventional commit types with examples

Co-authored-by: Ona <no-reply@ona.com>
---
 AGENTS.md             | 27 +++++++++++++++++++++++++++
 dev/docs/dashboard.md | 19 +++++++++++++++++++
 2 files changed, 46 insertions(+)
 create mode 100644 AGENTS.md
 create mode 100644 dev/docs/dashboard.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..e053194
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,27 @@
+# Project tech stack
+frontend: react, shadcn, tailwindcss
+backend: convex
+
+# Project structure
+This project uses npm workspaces.
+- `packages/convex` - convex functions and models
+- `packages/web` - frontend dashboard
+- `packages/path` - path utils
+
+# General Guidelines
+
+- For frontend dashboard guidelines, refer to dev/docs/dashboard.md
+- Always use bun for package management and running npm scripts.
+- When commiting, follow conventional commits: `[type]: msg` and clarify in commit body if necessary. keep your commit header to <= 50 characters.
+  - `feat:` for new features
+  - `fix:` for bug fixes  
+  - `docs:` for documentation
+  - `refactor:` for code restructuring
+  - `style:` for formatting changes
+  - `test:` for adding tests
+  - `ci:` for CI/CD pipeline changes
+  - `build:` for build system or dependency changes
+
+# Code styles
+
+- file names should always be kebab-case except in convex code, in which case try to use single word file names.
diff --git a/dev/docs/dashboard.md b/dev/docs/dashboard.md
new file mode 100644
index 0000000..828de09
--- /dev/null
+++ b/dev/docs/dashboard.md
@@ -0,0 +1,19 @@
+# Context
+
+- tech stack: react, tailwindcss, shadcn, tanstack router, tanstack table, jotai
+- `@/` maps to `src/`
+
+# Key files
+
+- `src/components`: reusable React components
+- `src/lib`: reusable util code
+- `src/routes`: tanstack file routes
+
+# Guidelines
+
+- ALWAYS use absolute import using `@/`, unless the file is in the same directory.
+- ALWAYS use kebab-case for file names
+- when importing useQuery/useMutation from convex/react, alias them with useConvexQuery/useConvexMutation
+- Do not attempt to create a preview server. There is one running already at port 3001.
+- After create a new file route, run `bunx tsr generate`
+- No testing is in place right now, so skip that for now.