1 files changed, 49 insertions, 0 deletions
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..b746b14
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,49 @@
+# Neko — Agent Guidelines
+
+## Project Overview
+
+Neko is a self-hosted, single-user RSS reader. Go backend, SQLite storage, vanilla JavaScript frontend (v3). The legacy Backbone.js frontend (v1) lives in `web/static/` — don't touch it unless asked.
+
+## TDD Workflow
+
+Write tests before or alongside code. Every change should have a corresponding test.
+
+- **Go tests**: `go test -cover ./...`
+- **Frontend tests**: `cd frontend-vanilla && npm test -- --run`
+- **Both at once**: `make test`
+- **Lint + tests**: `make check`
+
+Run `make test` before every commit. If tests fail, fix them before committing.
+
+## Check-in Rules
+
+1. Run `make test` — all tests must pass.
+2. If you changed anything under `frontend-vanilla/src/`, run `make all` to rebuild production assets in `web/dist/v3/`. These built assets must be committed alongside your source changes.
+3. Run `make all` for any UI change. The build output is checked into the repo.
+4. Write a clear, concise commit message.
+5. Never commit broken tests.
+
+## Code Layout
+
+```
+api/            REST API handlers
+cmd/neko/       Main entry point
+config/         Configuration
+internal/       Crawler, exporter, importer, utilities
+models/         Database layer (item, feed)
+web/            Web server, static assets, embedded dist
+frontend-vanilla/   v3 frontend source (TypeScript, CSS, Vite)
+```
+
+## Testing Conventions
+
+- Go test files live next to the code they test (`*_test.go`).
+- Frontend tests use Vitest and live next to source files (`*.test.ts`).
+- Use table-driven tests in Go where appropriate.
+- Mock `fetch` in frontend tests — don't hit real endpoints.
+
+## Style Notes
+
+- Keep it simple. This is intentionally minimal software.
+- No frameworks in the frontend — vanilla JS/TS only.
+- Prefer small, focused changes over large refactors.