diff --git a/AGENTS.md b/AGENTS.md
index 6583dce..8af7f35 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,44 +1,28 @@
 # Repository Guidelines
 
-## Project Structure & Module Organization
-`backend/` contains FastAPI and worker code. Main logic is in `backend/app/`: routes in `api/`, business logic in `services/`, persistence in `db/` and `models/`, and jobs in `worker/`.  
-`frontend/` is a Vite + React + TypeScript app with UI code in `frontend/src/` (`components/`, `lib/api.ts`, `types.ts`, styles).  
-`doc/` stores project documentation, with `doc/README.md` as the entrypoint.  
-`docker-compose.yml` defines API, worker, frontend, Postgres, Redis, and Typesense. Runtime data is persisted in `./data/`.
+## Stack Snapshot
+- DMS monorepo with FastAPI API + RQ worker (`backend/`) and React + Vite + TypeScript frontend (`frontend/`).
+- Services in `docker-compose.yml`: `api`, `worker`, `frontend`, `db` (Postgres), `redis`, `typesense`.
+- Runtime persistence uses Docker named volumes (`db-data`, `redis-data`, `dcm-storage`, `typesense-data`).
 
-## Build, Test, and Development Commands
-Docker workflow (required):
-- `multipass shell dcm-dev` - enter the Linux VM used for Docker.
-- `cd ~/dcm` - move to the project directory inside the VM.
-- `docker compose up --build -d` - build and start all services.
-- `docker compose down` - stop and remove containers.
-- `docker compose logs -f` - stream logs across services.
-- `DCM_DATA_DIR=/data docker compose up --build -d` - override host data directory.
-- `exit` - leave the VM after Docker operations.
+## Project Layout
+- Backend app code: `backend/app/` (`api/`, `services/`, `db/`, `models/`, `schemas/`, `worker/`).
+- Backend dependencies: `backend/requirements.txt`.
+- Frontend app code: `frontend/src/` (`components/`, `lib/api.ts`, `types.ts`, styles).
+- Technical docs live in `doc/` with `doc/README.md` as the index.
 
-Frontend-only workflow:
-- `cd frontend && npm run dev` - start Vite dev server.
-- `cd frontend && npm run build` - run TypeScript checks and build production assets.
-- `cd frontend && npm run preview` - serve built frontend locally.
+## Working Commands
+- Start full stack: `docker compose up --build -d`
+- Stop stack: `docker compose down`
+- Tail logs: `docker compose logs -f`
+- Frontend dev only: `cd frontend && npm run dev`
+- Frontend production build: `cd frontend && npm run build`
 
-## Coding Style & Naming Conventions
-Follow existing module boundaries; keep files focused.  
-Python style in `backend/`: 4-space indentation, type hints, and docstrings for modules and functions; use `snake_case` for functions/modules and `PascalCase` for classes.  
-TypeScript style in `frontend/`: strict compiler settings (`strict`, `noFallthroughCasesInSwitch`, ES2022 target). Use `PascalCase` for React components (`DocumentCard.tsx`) and `camelCase` for variables/functions.
+## Validation
+- No automated test suite is currently committed.
+- Manual checks for code changes: `GET /api/v1/health`, upload + processing flow, search, document preview/download, and clean `docker compose logs -f` output for `api` and `worker`.
 
-## Testing Guidelines
-This repository currently has no committed automated test suite. For each change, run the stack and validate impacted API/UI flows manually. Verify:
-- API health at `GET /api/v1/health`
-- document upload and search behavior in the frontend
-- service logs for processing failures (`docker compose logs -f` inside the VM)
-
-When introducing automated tests, place them near the relevant module and document execution commands in `README.md`.
-Use `test_*.py` naming for backend tests and `*.test.tsx` for frontend tests.
-
-## Commit & Pull Request Guidelines
-Git history is not available in this workspace snapshot, so no local message pattern can be inferred. Use concise, imperative commit subjects scoped to one change.  
-PRs should include:
-- what changed and why
-- linked issue/task ID
-- manual verification steps and outcomes
-- screenshots or short recordings for UI changes
+## If You Add Tests
+- Backend: place near changed module, use `test_*.py`.
+- Frontend: use `*.test.tsx`.
+- Update `README.md` and `doc/README.md` with test run commands.