diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..b706f0a
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,59 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this repository.
+
+## Project Overview
+
+LinkDesk is a VFX/animation production management system: FastAPI backend + Vue 3 frontend, run as separate dev servers with a Vite proxy bridging them.
+
+## Architecture
+
+**Backend** (`backend/`) — FastAPI + SQLAlchemy (SQLite by default, set via `DATABASE_URL` env var).
+- `main.py` — entry point; registers all routers and mounts `/uploads` static dir.
+- `database.py` — SQLAlchemy engine and `get_db` session dependency.
+- `models/` — ORM models: project, shot, asset, task, episode, user, notification, activity, api_key.
+- `routers/` — one file per resource, each prefixed in `main.py`.
+- `schemas/` — Pydantic request/response schemas (separate from ORM models).
+- `utils/` — shared helpers (file handling, notifications).
+
+**Frontend** (`frontend/src/`) — Vue 3 + TypeScript + Pinia + Vue Router + shadcn-vue + TanStack Table.
+- `router/index.ts` — routes with `requiresAuth`, role (`roles: [...]`), and admin-only (`adminPermission: 'required'`) guards.
+- `stores/` — Pinia stores per domain (auth, projects, assets, tasks, episodes, notifications, user, settings, taskStatuses).
+- `services/` — axios wrappers per resource; `api.ts` is the base client. All calls use `/api` prefix, proxied by Vite to `http://localhost:8000`.
+- `components/` — domain folders (`asset/`, `shot/`, `project/`, `layout/`, `auth/`, `episode/`, `task/`) + `ui/` for shadcn primitives.
+- `views/` — page-level components; project detail uses nested child routes under `/projects/:projectId`.
+- `composables/` — shared composition logic.
+- `types/` — shared TypeScript interfaces.
+
+**Auth**: JWT access + refresh tokens in `localStorage`. `api.ts` interceptor auto-refreshes on 401. Router guard initializes auth from stored token on first navigation.
+
+**Roles**: `coordinator`, `director`, `developer` + `isAdmin` flag. Admins can access any role-gated route.
+
+## Commands
+
+### Backend
+```bash
+cd backend
+# Windows: .venv\Scripts\activate  |  bash/mac: source .venv/bin/activate
+uvicorn main:app --reload --port 8000
+```
+
+### Frontend
+```bash
+cd frontend
+npm install
+npm run dev          # http://localhost:5173
+npm run type-check   # vue-tsc --noEmit
+npm run build
+```
+
+### First-time setup
+Copy `backend/.env.example` to `backend/.env` and set `SECRET_KEY`. The database schema is created automatically on first run via `Base.metadata.create_all`.
+
+## Coding conventions
+
+- Backend: follow existing router/schema/model separation. Pydantic schemas live in `schemas/`, ORM models in `models/`. Never mix them.
+- Frontend: services call the API; stores hold state; components consume stores. Don't call `apiClient` directly from components.
+- Use `@/` alias for all frontend imports (maps to `frontend/src/`).
+- Match existing style exactly — don't refactor adjacent code while fixing something.
+- Minimum code that solves the problem. No speculative features or abstractions.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..fc574fa
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,118 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+LinkDesk is a VFX/animation production management system. It has a FastAPI backend and a Vue 3 frontend, running as separate dev servers with a Vite proxy.
+
+## Architecture
+
+**Backend** (`backend/`) — FastAPI + SQLAlchemy (SQLite by default, configurable via `DATABASE_URL`).
+- `main.py` — app entry point; mounts routers and static uploads.
+- `database.py` — SQLAlchemy engine and `get_db` dependency.
+- `models/` — SQLAlchemy ORM models (project, shot, asset, task, episode, user, notification, activity, api_key).
+- `routers/` — one file per resource; each router is `include_router`'d with a prefix in `main.py`.
+- `schemas/` — Pydantic request/response schemas (separate from models).
+- `utils/` — shared helpers (file handling, notifications).
+
+**Frontend** (`frontend/src/`) — Vue 3 + TypeScript + Pinia + Vue Router + shadcn-vue (Radix UI) + TanStack Table.
+- `main.ts` — app bootstrap.
+- `router/index.ts` — route definitions; guards enforce `requiresAuth`, role-based (`roles: [...]`), and admin-only (`adminPermission: 'required'`) access.
+- `stores/` — Pinia stores (auth, projects, assets, tasks, episodes, notifications, user, settings, taskStatuses).
+- `services/` — axios wrappers per resource (`api.ts` is the base client). All calls go through `/api` which Vite proxies to `http://localhost:8000`.
+- `components/` — organized by domain (`asset/`, `shot/`, `project/`, `layout/`, `auth/`, `episode/`, `task/`) plus `ui/` for shadcn primitives.
+- `views/` — page-level components; project detail uses nested child routes under `/projects/:projectId`.
+- `composables/` — shared Vue composition logic (`useDetailPanel`, `useAvatarUrl`).
+- `types/` — shared TypeScript interfaces.
+
+**Auth flow**: JWT access + refresh tokens stored in `localStorage`. `api.ts` interceptor auto-refreshes on 401. Router guard initializes auth from stored token on first navigation.
+
+**Role model**: `coordinator`, `director`, `developer` roles + `isAdmin` flag. Admin can access any role-gated route.
+
+## Commands
+
+### Backend
+```bash
+cd backend
+# Activate venv first (Windows)
+.venv\Scripts\activate   # or: source .venv/bin/activate on bash
+uvicorn main:app --reload --port 8000
+```
+
+### Frontend
+```bash
+cd frontend
+npm install
+npm run dev          # http://localhost:5173
+npm run type-check   # TypeScript check (vue-tsc --noEmit)
+npm run build
+```
+
+### Setup
+Copy `.env.example` to `.env` in `backend/` and set `SECRET_KEY`. Database auto-creates on first run via SQLAlchemy `create_all`.
+
+---
+
+# CLAUDE.md — 12-rule template
+
+These rules apply to every task in this project unless explicitly overridden.
+Bias: caution over speed on non-trivial work. Use judgment on trivial tasks.
+
+## Rule 1 — Think Before Coding
+State assumptions explicitly. If uncertain, ask rather than guess.
+Present multiple interpretations when ambiguity exists.
+Push back when a simpler approach exists.
+Stop when confused. Name what's unclear.
+
+## Rule 2 — Simplicity First
+Minimum code that solves the problem. Nothing speculative.
+No features beyond what was asked. No abstractions for single-use code.
+Test: would a senior engineer say this is overcomplicated? If yes, simplify.
+
+## Rule 3 — Surgical Changes
+Touch only what you must. Clean up only your own mess.
+Don't "improve" adjacent code, comments, or formatting.
+Don't refactor what isn't broken. Match existing style.
+
+## Rule 4 — Goal-Driven Execution
+Define success criteria. Loop until verified.
+Don't follow steps. Define success and iterate.
+Strong success criteria let you loop independently.
+
+## Rule 5 — Use the model only for judgment calls
+Use me for: classification, drafting, summarization, extraction.
+Do NOT use me for: routing, retries, deterministic transforms.
+If code can answer, code answers.
+
+## Rule 6 — Token budgets are not advisory
+Per-task: 4,000 tokens. Per-session: 30,000 tokens.
+If approaching budget, summarize and start fresh.
+Surface the breach. Do not silently overrun.
+
+## Rule 7 — Surface conflicts, don't average them
+If two patterns contradict, pick one (more recent / more tested).
+Explain why. Flag the other for cleanup.
+Don't blend conflicting patterns.
+
+## Rule 8 — Read before you write
+Before adding code, read exports, immediate callers, shared utilities.
+"Looks orthogonal" is dangerous. If unsure why code is structured a way, ask.
+
+## Rule 9 — Tests verify intent, not just behavior
+Tests must encode WHY behavior matters, not just WHAT it does.
+A test that can't fail when business logic changes is wrong.
+
+## Rule 10 — Checkpoint after every significant step
+Summarize what was done, what's verified, what's left.
+Don't continue from a state you can't describe back.
+If you lose track, stop and restate.
+
+## Rule 11 — Match the codebase's conventions, even if you disagree
+Conformance > taste inside the codebase.
+If you genuinely think a convention is harmful, surface it. Don't fork silently.
+
+## Rule 12 — Fail loud
+"Completed" is wrong if anything was skipped silently.
+"Tests pass" is wrong if any were skipped.
+Default to surfacing uncertainty, not hiding it.
\ No newline at end of file