@@ -17,164 +17,19 @@ Tenant First Aid is a chatbot for Oregon housing/eviction legal information. Fla
 - **Frontend** (`frontend/`): React 19 + TypeScript + Vite + Tailwind CSS 4. Uses `@langchain/core` message types (`HumanMessage`/`AIMessage`) directly for chat state. Streaming via native `ReadableStream`.
 - **Type bridge**: Frontend TypeScript types in `src/types/` are auto-generated from backend Pydantic models via `generate-types` and gitignored. Must regenerate before building or type-checking.
 
-## Backend workflow (run from `backend/`)
-
-```bash
-make fmt                  # Format + sort imports (ruff)
-make lint                 # Lint (ruff)
-make typecheck            # Type-check (ty)
-make test                 # Run tests (pytest)
-make --keep-going check   # All of the above in one shot
-
-# Single test
-uv run pytest -s -k <test_name>
-
-# LangChain-specific tests
-uv run pytest -m langchain
-
-# Coverage
-make test TEST_OPTIONS="--cov tenantfirstaid --cov-report html --cov-branch"
-```
-
-All python commands should be run via `uv run python ...`
-
-### Environment variables
-
-See `backend/.env.example`. Key ones: `MODEL_NAME`, `GOOGLE_APPLICATION_CREDENTIALS`, `VERTEX_AI_DATASTORE_LAWS`, `LANGSMITH_API_KEY`.
-
-### LangSmith evaluations
-
-```bash
-# Run LangChain-specific tests
-uv run pytest -m langchain
-
-# Run with LangSmith tracing (requires API key)
-LANGSMITH_TRACING=true LANGCHAIN_TRACING_V2=true uv run pytest -m langchain
-
-# Run evaluations (see backend/evaluate/EVALUATION.md)
-uv run python -m evaluate.run_langsmith_evaluation --num-repetitions 20
-```
-
-See `docs/EVALUATION.md` for details.
-
-## Frontend workflow (run from `frontend/`)
-
-```bash
-npm run generate-types    # Required before build/typecheck — generates src/types/models.ts
-npm run lint              # Lint (eslint)
-npm run format            # Format (prettier)
-npm run typecheck         # Type-check (tsc)
-npm run build             # Build (auto-generates types first)
-npm run test -- --run     # Run tests (vitest)
-npm run test -- --run --coverage  # With coverage
-```
-
-`generate-types` requires `uv` to be installed (it runs backend Python to emit JSON Schema, piped through `json2ts`).
-
 ## Style notes
 
 - Write comments as full sentences and end them with a period.
 
-## Document files (`backend/scripts/documents/`)
-
-All `.txt` law documents must be **pure ASCII**. Vertex AI RAG ingestion has produced mojibake when UTF-8 is present. Before adding or modifying any `.txt` file in this directory, verify with:
-
-```bash
-LC_ALL=C grep -n '[^[:print:][:space:]]' path/to/file.txt  # must produce no output
-```
-
-Common offenders and their ASCII replacements (see `ASCII_REPLACEMENTS` in `backend/scripts/generate_metadata_jsonl.py` for the full list):
-
-| Character | Unicode | Replace with |
-|---|---|---|
-| `'` | U+2019 right single quote | `'` |
-| `"` `"` | U+201C/U+201D double quotes | `"` |
-| `§` | U+00A7 section sign | `Section ` |
-| `§§` | U+00A7 U+00A7 | `Sections ` |
-| `—` | U+2014 em dash | `--` |
-| `–` | U+2013 en dash | `-` |
-| `•` | U+2022 bullet | `-` |
-
-`make generate-metadata` auto-converts all known offenders in place and warns with a suggested replacement for any it cannot handle.
-
-### Publication cadence
-
-Oregon publishes statutes and annotations on offset biennial cycles, which is why statutes and annotations live in different year subfolders:
-
-- **Statutes** (`ORS*.txt`, `OAR*.txt`) — published in odd years after each long legislative session. See the [current edition](https://www.oregonlegislature.gov/bills_laws/pages/ors.aspx).
-- **Annotations** (`ORS*_annotations.txt`) — published in the fall of each even-numbered year as a Cumulative Supplement. See the [current edition](https://www.oregonlegislature.gov/bills_laws/Pages/Annotations.aspx).
-
-Statute and annotation chapter pages are accessible at predictable URLs that aren't directly enumerated from the landing pages (which route through PDFs and SharePoint volume groupings):
-
-- Statutes: `https://www.oregonlegislature.gov/bills_laws/ors/orsNNN.html`
-- Annotations: `https://www.oregonlegislature.gov/bills_laws/ors/anoNNN.html`
-
-`NNN` is the three-digit zero-padded chapter number, with lowercase letter suffix for sub-chapters. Examples: chapter 90 → `ors090.html` / `ano090.html`; chapter 659A → `ors659a.html` / `ano659a.html`.
-
-## Commit messages
-
-Concise, imperative mood, small focused commits. Write like a humble experienced engineer — casual, no listicles, highlight non-obvious choices. No robot speak, marketing buzzwords, or vague fluff.
-
-## Pull Request expectations
-
-Use the PR template. For frontend, backend, and backend/scripts changes:
-- Add tests when needed
-- Update documentation
-- Run `make lint` and `make fmt`
-- Full test suite passes
-
-### Pull Request reviews
-
-Perform a comprehensive code review of the modified code with the following focus areas:
-
-1. **Code Quality**
-   - Consistent style: formatted with `ruff format`, imports sorted, type hints passing `make typecheck`
-   - Clean code principles and best practices
-   - Suggest improvements to modularity, composition and dependency inversion where appropriate
-   - Identify opportunities for refactoring or simplification
-   - Check for code duplication and suggest DRY improvements
-   - Identify and suggest removal of dead code or redundant logic
-   - Proper error handling and edge cases
-   - Code readability and maintainability, including type hints where appropriate
-   - Prefer strongly typed interfaces and data structures over stringly-typed where possible
-   - Consistent environment variable declarations across GitHub Actions, `.env.example`, tests, and docs — no orphaned secrets/variables
-2. **Security**
-   - Check for potential security vulnerabilities
-   - Validate input sanitization
-   - Review authentication/authorization logic
-   - Ensure secrets are handled securely and not exposed in code or logs
-   - Flag obsolete secrets/configuration/environment variables
-3. **Performance**
-   - Identify potential performance bottlenecks
-   - Review database queries for efficiency
-   - Check for memory leaks or resource issues
-4. **Testing**
-   - Verify adequate test coverage
-   - Tests covering new behaviour
-   - Review test quality and edge cases
-   - Check for missing test scenarios
-5. **Documentation**
-   - Ensure code is properly documented
-   - Clear documentation for public API changes
-   - Verify README updates for new features
-   - Check API documentation accuracy
-   - Clean history and helpful PR description
-
-Provide detailed feedback using inline comments for specific issues.
-Use top-level comments for general observations or praise.
-
-
-
-## GitHub Actions Security
-
-We pin all third-party actions to commit SHAs to prevent supply chain attacks:
-
-```yaml
-# Good: SHA with version comment
-uses: appleboy/scp-action@ff85246acaad7bdce478db94a363cd2bf7c90345 #v1.0.0
+## Skills
 
-# Bad: floating tag
-uses: appleboy/scp-action@v1.0.0
-```
+Load these on demand -- don't include their content in every response, just invoke them when the task calls for it.
 
-Exceptions: Astral (uv) actions may use fully qualified semver tags (e.g. `astral-sh/setup-uv@7.3.0`), and immutable tags are allowed.
+| Skill | When to use |
+|---|---|
+| `/onboarding` | Setting up the repo for the first time or helping a new contributor |
+| `/backend` | Working on backend code (commands, env vars, Docker) |
+| `/frontend` | Working on frontend code (commands, type generation, Docker) |
+| `/corpus-dataset` | Adding, modifying, or reviewing `.txt` law files in `backend/scripts/documents/` (includes ASCII enforcement rules) |
+| `/evaluation` | Running, analyzing, or improving LangSmith evaluations |
+| `/pr` | Writing commit messages, opening PRs, or reviewing code |
@@ -36,6 +36,7 @@
         "frontend-design@claude-plugins-official": true,
         "github@claude-plugins-official": true,
         "typescript-lsp@claude-plugins-official": true,
-        "legal@knowledge-work-plugins": true
+        "legal@knowledge-work-plugins": true,
+        "ultrareview@claude-plugins-official": true
     }
 }
@@ -1,13 +1,13 @@
 # Analyze LangSmith Experiment
 
-Analyze an evaluation experiment using the `langsmith_dataset` CLI.
+Analyze an evaluation experiment using the `langsmith_dataset` CLI. Use the `/langsmith` skills for LangSmith-specific guidance (tracing, datasets, evaluators).
 The argument is an experiment name or UUID (e.g. `/analyze-experiment tfa-2026-04-13` or `/analyze-experiment c663e09e-...`).
 
 ## Instructions
 
 The CLI entry point is:
 ```
-uv run python -m evaluate.langsmith_dataset <noun> <verb> [args]
+uv run langsmith-dataset <noun> <verb> [args]
 ```
 Run all CLI commands from `backend/` with `dangerouslyDisableSandbox: true` (requires network access to LangSmith).
 
 
@@ -0,0 +1,74 @@
+# Backend
+
+Reference for backend development workflow. Run all commands from `backend/`.
+
+## Commands
+
+```bash
+make fmt                  # Format + sort imports (ruff)
+make lint                 # Lint (ruff)
+make typecheck            # Type-check (ty)
+make test                 # Run tests (pytest)
+make --keep-going check   # All of the above in one shot
+
+# Single test
+uv run pytest -s -k <test_name>
+
+# LangChain-specific tests
+uv run pytest -m langchain
+
+# Coverage
+make test TEST_OPTIONS="--cov tenantfirstaid --cov-report html --cov-branch"
+```
+
+All Python commands must be run via `uv run python ...`. Use the `/uv` skill for uv-specific guidance.
+
+## Environment variables
+
+See `backend/.env.example`. Key ones:
+
+| Variable | Description |
+|---|---|
+| `MODEL_NAME` | LLM model name (e.g. `gemini-2.5-pro`) |
+| `GOOGLE_APPLICATION_CREDENTIALS` | Path to GCP credentials JSON |
+| `VERTEX_AI_DATASTORE_LAWS` | Vertex AI Search datastore ID for the laws corpus |
+| `LANGSMITH_API_KEY` | LangSmith API key (required for evaluations) |
+| `LANGSMITH_TRACING` | Set to `true` to enable LangSmith tracing |
+| `LANGCHAIN_TRACING_V2` | Set to `true` for detailed tracing |
+| `LANGSMITH_PROJECT` | LangSmith project name for traces |
+
+## LangSmith evaluations
+
+```bash
+# Run LangChain-specific tests
+uv run pytest -m langchain
+
+# Run with LangSmith tracing
+LANGSMITH_TRACING=true LANGCHAIN_TRACING_V2=true uv run pytest -m langchain
+
+# Run full evaluation suite
+uv run run-langsmith-evaluation --num-repetitions 20
+```
+
+See `/evaluation` for the full evaluation workflow.
+
+## Docker
+
+Backend Dockerfile targets (`backend/Dockerfile`):
+
+| Target | Purpose |
+|---|---|
+| `runtime` | Production image (gunicorn, no dev deps) |
+| `ci` | Full dev environment for running checks |
+
+Build a specific target:
+
+```sh
+docker build -f backend/Dockerfile --target runtime -t tenantfirstaid-backend:runtime backend
+```
+
+Run checks via compose:
+
+```sh
+RUNTIME_TARGET=ci docker compose run backend uv run --dev pytest -q
+```
@@ -0,0 +1,45 @@
+# Corpus Dataset
+
+Reference for adding or modifying law documents in `backend/scripts/documents/`.
+
+## ASCII requirement
+
+All `.txt` files must be **pure ASCII**. Vertex AI RAG ingestion has produced mojibake when UTF-8 is present. Before committing any `.txt` file, verify:
+
+```bash
+LC_ALL=C grep -n '[^[:print:][:space:]]' path/to/file.txt  # must produce no output
+```
+
+`make generate-metadata` auto-converts all known offenders in place and warns with a suggested replacement for any it cannot handle.
+
+### Common replacements
+
+| Character | Unicode | Replace with |
+|---|---|---|
+| `'` | U+2019 right single quote | `'` |
+| `"` `"` | U+201C/U+201D double quotes | `"` |
+| `§` | U+00A7 section sign | `Section ` |
+| `§§` | U+00A7 U+00A7 | `Sections ` |
+| `—` | U+2014 em dash | `--` |
+| `–` | U+2013 en dash | `-` |
+| `•` | U+2022 bullet | `-` |
+
+See `ASCII_REPLACEMENTS` in `backend/scripts/generate_metadata_jsonl.py` for the full list.
+
+## Publication cadence
+
+Oregon publishes statutes and annotations on offset biennial cycles:
+
+- **Statutes** (`ORS*.txt`, `OAR*.txt`) — published in odd years after each long legislative session. [Current edition](https://www.oregonlegislature.gov/bills_laws/pages/ors.aspx).
+- **Annotations** (`ORS*_annotations.txt`) — published in the fall of each even-numbered year as a Cumulative Supplement. [Current edition](https://www.oregonlegislature.gov/bills_laws/Pages/Annotations.aspx).
+
+This is why statutes and annotations live in different year subfolders.
+
+## URL patterns
+
+Chapter pages are at predictable URLs (`NNN` = three-digit zero-padded chapter number, lowercase letter suffix for sub-chapters):
+
+- Statutes: `https://www.oregonlegislature.gov/bills_laws/ors/orsNNN.html`
+- Annotations: `https://www.oregonlegislature.gov/bills_laws/ors/anoNNN.html`
+
+Examples: chapter 90 → `ors090.html` / `ano090.html`; chapter 659A → `ors659a.html` / `ano659a.html`.
Original file line number	Diff line number	Diff line change
`@@ -36,6 +36,7 @@`
`36`	`36`	`"frontend-design@claude-plugins-official": true,`
`37`	`37`	`"github@claude-plugins-official": true,`
`38`	`38`	`"typescript-lsp@claude-plugins-official": true,`
`39`		`- "legal@knowledge-work-plugins": true`
	`39`	`+ "legal@knowledge-work-plugins": true,`
	`40`	`+ "ultrareview@claude-plugins-official": true`
`40`	`41`	`}`
`41`	`42`	`}`