diff --git a/.claude/skills/add-contest-table-provider/SKILL.md b/.agents/skills/add-contest-table-provider/SKILL.md
similarity index 100%
rename from .claude/skills/add-contest-table-provider/SKILL.md
rename to .agents/skills/add-contest-table-provider/SKILL.md
diff --git a/.claude/skills/add-contest-table-provider/instructions.md b/.agents/skills/add-contest-table-provider/instructions.md
similarity index 100%
rename from .claude/skills/add-contest-table-provider/instructions.md
rename to .agents/skills/add-contest-table-provider/instructions.md
diff --git a/.claude/skills/dep-upgrade/SKILL.md b/.agents/skills/dep-upgrade/SKILL.md
similarity index 100%
rename from .claude/skills/dep-upgrade/SKILL.md
rename to .agents/skills/dep-upgrade/SKILL.md
diff --git a/.claude/skills/dep-upgrade/instructions.md b/.agents/skills/dep-upgrade/instructions.md
similarity index 80%
rename from .claude/skills/dep-upgrade/instructions.md
rename to .agents/skills/dep-upgrade/instructions.md
index 8b3ea9343..c73cb98a4 100644
--- a/.claude/skills/dep-upgrade/instructions.md
+++ b/.agents/skills/dep-upgrade/instructions.md
@@ -2,8 +2,7 @@
 
 ## 1. Breaking Changes Analysis
 
-Fetch the official migration guide via WebFetch. For each breaking change, grep `src/`, config files,
-and `package.json` to determine applicability. Produce two tables:
+Fetch the official migration guide via WebFetch. For each breaking change, grep `src/`, config files, and `package.json` to determine applicability. Produce two tables:
 
 **問題なし（対応不要）**
 
@@ -26,14 +25,12 @@ Key areas to check:
 
 ## 2. Companion Package Check
 
-Some packages must be upgraded together in the same commit to avoid version mismatch.
-Check `package.json` for known companion pairs:
+Some packages must be upgraded together in the same commit to avoid version mismatch. Check `package.json` for known companion pairs:
 
 - `@sveltejs/kit` + `@sveltejs/vite-plugin-svelte`
 - `eslint` + `@eslint/js`
 
-Also verify peer dependency compatibility (`"eslint": "^8 || ^9 || ^10"` style) for all
-related packages already installed.
+Also verify peer dependency compatibility (`"eslint": "^8 || ^9 || ^10"` style) for all related packages already installed.
 
 If companion packages are found, include them in the upgrade scope.
 
@@ -66,9 +63,6 @@ pnpm check
 pnpm test:unit
 ```
 
-> **`pnpm check` tip:** If type errors appear and you have uncommitted changes, run
-> `git stash && pnpm check 2>&1 | tail -5` to confirm whether errors are pre-existing.
-> Restore with `git stash pop`. If there is nothing to stash, skip this check — without
-> a baseline to compare against, it gives no useful signal.
+> **`pnpm check` tip:** If type errors appear and you have uncommitted changes, run `git stash && pnpm check 2>&1 | tail -5` to confirm whether errors are pre-existing. Restore with `git stash pop`. If there is nothing to stash, skip this check — without a baseline to compare against, it gives no useful signal.
 
 Update the plan.md `- [ ]` checklist and add a verification results table when done.
diff --git a/.agents/skills/extract-approach/SKILL.md b/.agents/skills/extract-approach/SKILL.md
new file mode 100644
index 000000000..c4fcdb996
--- /dev/null
+++ b/.agents/skills/extract-approach/SKILL.md
@@ -0,0 +1,14 @@
+---
+name: extract-approach
+description: Use when a non-trivial problem has just been solved (bug fixed after debugging, tricky implementation completed, blocker resolved) and the session is about to move on. A solution without its learnings note is unfinished work.
+argument-hint: '[task-name-en]'
+---
+
+Extract the approach from the just-solved problem into a learnings note for: $ARGUMENTS
+
+**Skip when:** trivial fixes (typo, rename, config tweak), dependency bumps, or the insight is already covered by `docs/guides/agent-rules/` or the task's `plan.md`.
+
+1. **Identify the problem** — the symptom from this session and what made it non-trivial; multiple candidates → confirm which one with AskUserQuestion
+2. **Extract** — 問題 / 有効だったアプローチ / ハマった点 / 教訓 only; apply the extraction and abstraction rules in [instructions.md](instructions.md)
+3. **Write the note** — `docs/dev-notes/YYYY-MM-DD/{task-name-en}/learning.md`; naming and format rules in [instructions.md](instructions.md)
+4. **Escalate durable rules** — propose target file and exact wording for project-wide conventions; **do not apply without user confirmation**
diff --git a/.agents/skills/extract-approach/instructions.md b/.agents/skills/extract-approach/instructions.md
new file mode 100644
index 000000000..625b89fd5
--- /dev/null
+++ b/.agents/skills/extract-approach/instructions.md
@@ -0,0 +1,34 @@
+# extract-approach instructions
+
+## What to extract
+
+Record only what changes future behavior. No session log, no timestamps, no narration of the order things happened in.
+
+| Section              | Content                                       |
+| -------------------- | --------------------------------------------- |
+| 問題                 | Symptom and root cause, one line each         |
+| 有効だったアプローチ | What worked, and **why** it worked            |
+| ハマった点           | Dead ends actually tried, and why each failed |
+| 教訓                 | Reusable rules that apply beyond this task    |
+
+Omit a section that has nothing real to say. An empty ハマった点 is a signal the problem may have been trivial — reconsider the skip condition.
+
+## Align abstraction (抽象度を揃える)
+
+State every 教訓 at the same level of generality:
+
+- One general rule per bullet, optionally followed by a single concrete example from this session.
+- Never mix operational steps and principles in the same list.
+- A bullet that only makes sense for this one file or this one bug is not a 教訓 — move it to 有効だったアプローチ or drop it.
+
+## Note format
+
+- Path: `docs/dev-notes/YYYY-MM-DD/{task-name-en}/learning.md`, using today's date.
+- Directory name: `$ARGUMENTS` if given; else the `plan.md` directory name of the task this problem belongs to (when the session is executing one); else a short kebab-case name.
+- Japanese prose, English code identifiers, 30 lines or fewer.
+- One semantic paragraph or list item per line; no width-based hard line breaks.
+- If the file already exists, append a `---`-separated entry instead of rewriting it.
+
+## Escalating to a durable rule
+
+A 教訓 belongs in a rules document when it would apply to an unrelated future task in the same path. Propose the target file under `docs/guides/agent-rules/` (or `AGENTS.md` for a project-wide principle) and the exact wording, then wait for the user's decision.
diff --git a/.claude/skills/verify-test-strength/SKILL.md b/.agents/skills/verify-test-strength/SKILL.md
similarity index 100%
rename from .claude/skills/verify-test-strength/SKILL.md
rename to .agents/skills/verify-test-strength/SKILL.md
diff --git a/.claude/skills/verify-test-strength/instructions.md b/.agents/skills/verify-test-strength/instructions.md
similarity index 94%
rename from .claude/skills/verify-test-strength/instructions.md
rename to .agents/skills/verify-test-strength/instructions.md
index e531e8305..acd9a135b 100644
--- a/.claude/skills/verify-test-strength/instructions.md
+++ b/.agents/skills/verify-test-strength/instructions.md
@@ -36,4 +36,4 @@ Read stdout from `--reporter=default` / `--reporter=verbose`. **Never read a cac
 - **A test catching nothing that other tests miss** — a deletion candidate. Confirm by re-running the full mutant set without it.
 - **N tests failing on one mutant** — not N times the value. Parameterized cases over one fixture usually report the same fact N times; the count is a proxy, not evidence.
 
-Record the matrix in the commit message or `plan.md` when it justifies removing tests — it is the evidence `.claude/rules/testing.md` requires for a deliberate test-count drop.
+Record the matrix in the commit message or `plan.md` when it justifies removing tests — it is the evidence `docs/guides/agent-rules/testing.md` requires for a deliberate test-count drop.
diff --git a/.claude/rules/accessibility.md b/.claude/rules/accessibility.md
deleted file mode 100644
index 8d386c757..000000000
--- a/.claude/rules/accessibility.md
+++ /dev/null
@@ -1,45 +0,0 @@
----
-description: Accessibility rules for UI components
-paths:
-  - 'src/**/*.svelte'
-  - 'src/lib/components/**'
-  - 'src/features/**/components/**'
----
-
-# Accessibility
-
-## Tables
-
-Always declare header scope:
-
-```html
-<th scope="col">Grade</th>
-<th scope="row">abc001</th>
-```
-
-## Color
-
-Never use color as the sole indicator of meaning. Grade badges and status icons must
-include a visible text label or `aria-label` — screen readers and users with color
-vision differences depend on it.
-
-## Interactive Elements
-
-Every `<button>` and `<a>` must have an accessible name: visible text, `aria-label`,
-or `aria-labelledby`. Icon-only buttons require `aria-label`.
-
-## Dynamic Content
-
-When `{#if}` reveals a modal, dialog, or focus-trap region, move focus programmatically
-on open and restore it on close.
-
-## Flowbite Svelte
-
-Icon-only `<Button>` variants require an explicit `aria-label`; Flowbite Svelte does
-not generate one automatically. Omitting `color` only applies the `'primary'` default
-style — it has no effect on `aria-label`.
-
-## Form Labels
-
-Every `<input>`, `<select>`, and `<textarea>` must have an associated `<label>` (via
-`for`/`id`) or `aria-label`. Placeholder text does not substitute for a label.
diff --git a/.claude/rules/accessibility.md b/.claude/rules/accessibility.md
new file mode 120000
index 000000000..00b449991
--- /dev/null
+++ b/.claude/rules/accessibility.md
@@ -0,0 +1 @@
+../../docs/guides/agent-rules/accessibility.md
\ No newline at end of file
diff --git a/.claude/rules/auth.md b/.claude/rules/auth.md
deleted file mode 100644
index 7bcac6d04..000000000
--- a/.claude/rules/auth.md
+++ /dev/null
@@ -1,60 +0,0 @@
----
-description: Authentication rules
-paths:
-  - 'src/routes/(auth)/**'
-  - 'src/routes/(admin)/**'
-  - 'src/features/auth/**'
-  - 'src/features/auth/server/**'
-  - 'src/hooks.server.ts'
----
-
-# Authentication
-
-## Self-Managed Session Auth
-
-Auth is a self-managed implementation (no external auth library), kept compatible with the retired lucia v2 so existing sessions and password hashes stay valid. See `## Key Files` for the module map.
-
-- Session validation in `src/hooks.server.ts`; session data attached to `event.locals.user`
-- User properties: `id`, `name`, `role`, `atcoder_name`, `is_validated`
-
-## Protected Routes
-
-- Validate `event.locals.user` in `+page.server.ts` load functions
-- Redirect unauthenticated users to `/login`
-- Validate `role` for admin-only routes
-
-## Form Validation
-
-- Use Superforms + Zod for auth forms
-- Server-side validation is authoritative
-- Return structured error responses
-
-## Key Files
-
-- `src/hooks.server.ts`: Global request handler
-- `src/features/auth/server/auth.ts`: `createAuthRequest` (request-scoped session handle)
-- `src/features/auth/server/session.ts` / `src/features/auth/server/password.ts`: self-managed session + password crypto (`random.ts` provides salt/session-id generation)
-- `src/features/auth/services/credentials.ts`: `registerUser` / `authenticateUser`
-- `src/features/auth/services/session_guards.ts`:
-  - `getLoggedInUser(locals, url?)` — returns logged-in user or redirects to `/login`
-  - `ensureSessionOrRedirect(locals, url?)` — guard-only; redirects if no session
-- `src/features/auth/services/admin_access.ts`:
-  - `validateAdminAccess(locals, url?)` — for page routes; redirects to `/login` for both unauthenticated and non-admin users (do not use in `+server.ts`)
-  - `validateAdminAccessForApi(locals)` — for API routes (`+server.ts`); throws `error(401)` if unauthenticated, `error(403)` if not admin
-- `src/features/auth/utils/login.ts`: `buildLoginPath(url?)` — generates `/login` or `/login?redirectTo=...`
-- `src/features/auth/utils/signup.ts`: `buildSignupPath(url?)` — generates `/signup` or `/signup?redirectTo=...` (same signature as `buildLoginPath`)
-- `prisma/schema.prisma`: User, Session, Key models
-
-## Redirect After Login Pattern
-
-After login/signup, redirect users back to their original intended page instead of hardcoding `/`.
-
-- Protected `load()`: pass `url` to `getLoggedInUser(locals, url)` — appends `?redirectTo=` automatically
-- Login/signup actions: validate `redirectTo` with `isSameOriginRedirect()` before using (see `src/lib/utils/url.ts`)
-
-## Security
-
-- Never expose session secrets in client code
-- Use HTTPS in production
-- Validate all user inputs server-side
-- **SvelteKit's `redirect()` does not validate origin** — always validate user-provided redirect destinations with `isSameOriginRedirect()`
diff --git a/.claude/rules/auth.md b/.claude/rules/auth.md
new file mode 120000
index 000000000..0ee2d9c85
--- /dev/null
+++ b/.claude/rules/auth.md
@@ -0,0 +1 @@
+../../docs/guides/agent-rules/auth.md
\ No newline at end of file
diff --git a/.claude/rules/coding-style.md b/.claude/rules/coding-style.md
deleted file mode 100644
index db6c904d3..000000000
--- a/.claude/rules/coding-style.md
+++ /dev/null
@@ -1,96 +0,0 @@
-# Coding Style
-
-## Pre-Implementation Layer Check
-
-Before writing logic, decide which layer it belongs to:
-
-| Layer          | Directory                                   | Constraints                                             |
-| -------------- | ------------------------------------------- | ------------------------------------------------------- |
-| DB schema      | `prisma/`                                   | Migrations immutable after apply                        |
-| DB access      | `src/lib/server/`                           | Server-only; never in client                            |
-| Validation     | `src/**/zod/`                               | `z.number().int()` for Int; dual-enforce with SQL CHECK |
-| Domain types   | `src/**/types/`                             | Plural aliases; TSDoc; avoid `any`                      |
-| Test data      | `src/**/fixtures/`                          | Write before impl (TDD); realistic values               |
-| Business logic | `src/**/services/`                          | Pure values/`null`; no `Response`/`json()`              |
-| External APIs  | `src/lib/clients/` or `*/internal_clients/` | Shared → `lib`; feature-scoped → `internal_clients`     |
-| Utilities      | `src/**/utils/`                             | No side effects; adjacent unit test required            |
-| State          | `src/**/stores/`                            | `.svelte.ts`; class + `$state()`; singleton export      |
-| Route handlers | `src/routes/`                               | Page: `redirect()`; API: `error()`                      |
-| Components     | `src/**/*.svelte`                           | Svelte 5 Runes; logic → `utils/`                        |
-
-## Naming
-
-- **No abbreviations** unless standard (e.g., `id`, `url`)
-- **Lambda params**: no single-char (except `i` for loops)
-- **Function verbs**: `get` (read), `build`/`create` (construct), `calc`/`compute` (derive), `update`, `fetch`, `resolve`
-- **Domain enums**: use domain type, not `string` (validates at boundary, stays typed inside)
-- **Constants**: reflect content not purpose; extract magic numbers/strings
-- **Files**: `snake_case` in routes, `kebab-case` dirs, underscore-prefix helpers (`_utils/`, `_types/`)
-
-## Syntax
-
-- **Braces**: always for single-statement `if` blocks
-- **Catch blocks**: never silent; re-throw, log, or comment
-- **Plural aliases**: `type Items = Item[]` in signatures
-- **TSDoc**: add when behavior, constraints, or params are non-obvious; omit when names are self-explanatory (`getTaskById(id: string)` needs no `@param id` comment)
-
-## Type Guards at API Boundaries
-
-When receiving enum values from external APIs, validate with a type guard:
-
-```typescript
-// Good: `isValidTaskGrade(value): value is TaskGrade`
-const grade = isValidTaskGrade(data.grade) ? data.grade : null;
-```
-
-Extract to `src/lib/utils/` with adjacent tests.
-
-## Guard Clause Reachability
-
-Ensure guard clauses don't make later code unreachable. If an early return covers all remaining cases, delete the dead code below it rather than leaving it.
-
-## Dispatcher and Handler Domains
-
-A classifier must not match more broadly than its handler accepts (`startsWith` classifier → anchored-regex handler throws on the gap). Fix both sides: tighten the classifier, and return `null` instead of throwing.
-
-## Dead Code: Three-Condition Rule
-
-Delete function only if: (1) zero callers, (2) replacement exists, (3) dependent fields also deleted.
-
-Before removing an import, grep the entire file for all usages — removing one call site doesn't mean no others exist.
-
-## Barrel Exports
-
-`index.ts` re-exports public API only. Files within the same module import each other directly — never through the barrel (circular dependency).
-
-## Residual-Reference Sweeps
-
-When removing a dependency or renaming a symbol, sweep the **whole repo**, not just `src`:
-
-- `grep --include='*.{ts,svelte,md}'` does NOT brace-expand — it silently matches nothing.
-  Use `rg -ni 'name' -g '*.ts' -g '*.svelte' -g '*.md'` instead.
-- Include root files (CONTRIBUTING.md, README), `e2e/`, and config (`vite.config.ts`) —
-  not only `src prisma .claude`.
-
-## Documentation
-
-- **Plans/dev-notes**: Japanese
-- **Code/commits/tests**: English
-- **TSDoc**: add when behavior, constraints, or params are non-obvious
-- **Code blocks**: specify language (`typescript`, `sql`, `bash`)
-
-## Security
-
-- No user-identifiable data in logs
-- No Prisma imports in route handlers
-- Validate input at system boundaries
-- Return safe defaults on service errors
-
-## Comments: Why, Not What
-
-Comment the **why** (non-obvious reason), not the **what** (code already says).
-
-- Bad: `// increment counter`
-- Good: `// use task_id as deterministic ID to avoid SSR/hydration mismatch`
-
-Keep to one line. If longer, refactor code (naming, structure) instead.
diff --git a/.claude/rules/coding-style.md b/.claude/rules/coding-style.md
new file mode 120000
index 000000000..335c04198
--- /dev/null
+++ b/.claude/rules/coding-style.md
@@ -0,0 +1 @@
+../../docs/guides/agent-rules/coding-style.md
\ No newline at end of file
diff --git a/.claude/rules/github-actions.md b/.claude/rules/github-actions.md
deleted file mode 100644
index 54b01941d..000000000
--- a/.claude/rules/github-actions.md
+++ /dev/null
@@ -1,13 +0,0 @@
----
-description: GitHub Actions workflow rules
-paths:
-  - '.github/workflows/**'
----
-
-# GitHub Actions
-
-## workflow_dispatch Requires the Default Branch
-
-The GitHub Actions UI only shows `workflow_dispatch` workflows that exist on the **default branch** (staging in this repo). A workflow file that only exists on a feature branch cannot be triggered from the UI.
-
-For one-time operational workflows (e.g. migration fixes): merge to staging first, then trigger the dispatch.
diff --git a/.claude/rules/github-actions.md b/.claude/rules/github-actions.md
new file mode 120000
index 000000000..caaedcf3e
--- /dev/null
+++ b/.claude/rules/github-actions.md
@@ -0,0 +1 @@
+../../docs/guides/agent-rules/github-actions.md
\ No newline at end of file
diff --git a/.claude/rules/prisma-db.md b/.claude/rules/prisma-db.md
deleted file mode 100644
index 0189c0125..000000000
--- a/.claude/rules/prisma-db.md
+++ /dev/null
@@ -1,163 +0,0 @@
----
-description: Prisma and database rules
-paths:
-  - 'prisma/**'
-  - 'src/lib/server/**'
-  - 'src/lib/services/**'
-  - 'src/features/**/services/**'
----
-
-# Prisma & Database
-
-## Schema Changes
-
-1. Edit `prisma/schema.prisma`
-2. Run `pnpm exec prisma migrate dev --name <snake_case_description>`
-
-## Naming
-
-- Models: `PascalCase` | Fields: `camelCase` (preferred) or `snake_case` (legacy)
-
-## Server-Only Code
-
-- Import DB client only in `src/lib/server/` via `$lib/server/database`
-- Never import server code in client components
-
-## Service Layer
-
-- All CRUD through the service layer (`src/lib/services/` or `src/features/**/services/`)
-- Route handlers call service methods — no direct Prisma in `+server.ts` / `+page.server.ts`
-- Service functions return pure values (`{ error: string } | null`), never `Response` / `json()`
-
-## Transactions
-
-Use `prisma.$transaction()` for multi-step operations.
-
-## Parallel Queries
-
-When `+page.server.ts` `load` makes multiple independent queries, run them concurrently with `Promise.all` to reduce page load latency:
-
-```typescript
-// NG: sequential — each awaits the previous
-const workbooks = await getWorkBooksWithAuthors();
-const tasks = await getTasksByTaskId();
-const results = await getTaskResultsOnlyResultExists(userId, true);
-
-// OK: all three fire at once
-const [workbooks, tasks, results] = await Promise.all([
-  getWorkBooksWithAuthors(),
-  getTasksByTaskId(),
-  getTaskResultsOnlyResultExists(userId, true),
-]);
-```
-
-Only applies when queries are **independent** (no output of one used as input to another).
-
-## N+1 Queries
-
-Replace per-item DB calls in loops with a bulk fetch + `Map`:
-
-```typescript
-const records = await prisma.foo.findMany({ where: { id: { in: ids } } });
-const map = new Map(records.map((r) => [r.id, r]));
-```
-
-## Enum Types
-
-Prisma-generated enums and app-defined enums are distinct TypeScript types even with identical members. Keep explicit casts at the boundary — do not remove them as "redundant".
-
-## Idempotent Writes
-
-Prefer `createMany({ skipDuplicates: true })` over catching P2002 for expected unique violations (e.g., double-submit). Maps to `INSERT ... ON CONFLICT DO NOTHING`. Top-level only (not nested); PostgreSQL/CockroachDB/SQLite only.
-
-## Zod Schema for Int Fields
-
-`z.number().positive()` passes decimals. For Prisma `Int` fields use `z.number().int().positive()`.
-
-## Relation Filter Exclusion
-
-Filtering on a relation field (e.g. `where: { placement: { type: 'CURRICULUM' } }`)
-performs an INNER JOIN internally — rows without a matching relation record are
-automatically excluded. This is not an IS NOT NULL check; the mechanism is the JOIN.
-
-When documenting this behavior, write "excluded by INNER JOIN" rather than
-"implicitly includes IS NOT NULL".
-
-## FK Relations: Always Define @relation
-
-Any field that references another model's ID must have an explicit `@relation` defined. Without `@relation`, Prisma does not generate FK constraints automatically, leading to referential integrity gaps.
-
-```prisma
-// Bad: FK without @relation
-userId String
-
-// Good: explicit @relation generates FK constraint
-userId String
-user   User @relation(fields: [userId], references: [id])
-```
-
-## DB-Level Value Constraints
-
-Add `CHECK` constraints via manual migration SQL. Document with inline `schema.prisma` comments (e.g., `/// CHECK: count >= 0`). Note: `prisma generate` (via `prisma-markdown`) overwrites `ERD.md`—always keep the constraint definition in `schema.prisma` as the source of truth.
-
-## Service Layer Error Handling
-
-Catch Prisma errors in service functions, return domain values:
-
-- `P2025` (record not found) → `null` (no exception)
-- Other errors → re-throw (caller handles as 500)
-
-This removes Prisma imports from route handlers and enables easy testing with mocked returns.
-
-## Dual-Enforcement Constraints
-
-When the same constraint is enforced in both Zod (early validation) and SQL `CHECK` (last line of defense), add an inline comment stating each layer's role and the obligation to keep them in sync:
-
-```typescript
-// XOR constraint: dual enforcement via Zod (early validation) and a CHECK in migration.sql (last line of defense).
-// Prisma lacks @@check, so the SQL constraint is maintained manually. Keep both in sync.
-.refine(...)
-```
-
-## @@map and Manual Migration SQL
-
-When writing manual migration SQL for models that use `@@map`, always use the `@@map` value (the actual DB table name), not the Prisma model name. PostgreSQL treats quoted identifiers as case-sensitive, so `"VotedGradeCounter"` and `"votedgradecounter"` refer to different tables.
-
-```sql
--- Bad: Prisma model name does not exist as a table
-ALTER TABLE "VotedGradeCounter" ADD CONSTRAINT ...
-
--- Good: use the @@map value
-ALTER TABLE "votedgradecounter" ADD CONSTRAINT ...
-```
-
-## P3009: Recovering from a Failed Migration
-
-When a migration leaves `finished_at = NULL` in `_prisma_migrations`:
-
-1. **Delete the broken migration file** from git (`git rm -r prisma/migrations/<name>/`) — leaving it causes `migrate dev` to fail on other machines.
-2. Mark it as rolled back: `pnpm exec prisma migrate resolve --rolled-back <name>`
-3. Create a **new migration with a new timestamp** containing the corrected SQL and deploy it.
-
-A `--rolled-back` migration is permanently skipped by `migrate deploy`; fixing the original file has no effect.
-
-## Merged Data: Document Uniqueness Loss
-
-Service functions that merge records from multiple sources (e.g., `getMergedTasksMap()` combining base tasks + `ContestTaskPair` entries) lose individual field uniqueness. Document that results contain duplicates in "unique" DB fields.
-
-Example: `getMergedTasksMap()` returns multiple entries with same `task_id` but different `contest_id` — callers must not assume `task_id` is unique. UI layer must use composite keys (see svelte-components.md `{#each}` patterns).
-
-## Validate Constraints
-
-Prisma does not support `@@check`. To add one:
-
-1. `pnpm exec prisma migrate dev --create-only --name <description>` — generate migration without applying
-2. Edit the generated `migration.sql` to add the CHECK constraint manually
-3. Add an inline comment in `schema.prisma` (e.g., `/// CHECK: constraint description`)
-4. `pnpm exec prisma migrate dev` — apply
-
-For visibility, also document complex constraints in `prisma/ERD.md`:
-
-```mermaid
-%% XOR constraint: workbookplacement_xor_grade_category — exactly one of taskGrade or solutionCategory must be non-null
-```
diff --git a/.claude/rules/prisma-db.md b/.claude/rules/prisma-db.md
new file mode 120000
index 000000000..b4efa214f
--- /dev/null
+++ b/.claude/rules/prisma-db.md
@@ -0,0 +1 @@
+../../docs/guides/agent-rules/prisma-db.md
\ No newline at end of file
diff --git a/.claude/rules/server-cache.md b/.claude/rules/server-cache.md
deleted file mode 100644
index f52599379..000000000
--- a/.claude/rules/server-cache.md
+++ /dev/null
@@ -1,98 +0,0 @@
----
-description: Server-side caching rules
-paths:
-  - 'src/lib/clients/cache.ts'
-  - 'src/lib/server/**/cache.ts'
-  - 'src/features/**/server/cache.ts'
----
-
-# Server-Side Cache
-
-## Core Pattern: `Cache<T>.getOrFetch()`
-
-Use `cache.getOrFetch(key, fetchFn)` for all get-or-fetch operations. Never inline the get/set/if pattern manually — it duplicates logic that `getOrFetch` already provides.
-
-```typescript
-export function getCachedFoo(fetchFn: () => Promise<Foo>): Promise<Foo> {
-  return fooCache.getOrFetch(KEY, fetchFn);
-}
-```
-
-## Domain Cache Module Structure
-
-Place cache modules at `server/cache.ts` within each domain:
-
-| Domain  | Path                                  |
-| ------- | ------------------------------------- |
-| Shared  | `src/lib/server/{domain}/cache.ts`    |
-| Feature | `src/features/{name}/server/cache.ts` |
-
-Each module exports:
-
-- `getCached*()` — thin wrapper around `cache.getOrFetch()`
-- `invalidate*Caches()` — clears all related cache instances
-- `dispose*Caches()` — disposes all related cache instances (for test cleanup)
-
-## Invalidation Rules
-
-- Call `invalidate*Caches()` immediately after the DB write (`create`, `update`, `delete`) succeeds — not before, not in a `finally` block.
-- Group related caches in a single invalidation function (e.g., `invalidateTaskCaches()` clears both `tasksCache` and `mergedTasksCache`).
-- Never invalidate from route handlers — invalidation belongs in the service layer, co-located with the write operation.
-
-## TTL Guidelines
-
-| Data characteristics           | TTL        |
-| ------------------------------ | ---------- |
-| Rarely changes (tasks, grades) | 1 hour     |
-| Moderately changes (votes)     | 10 minutes |
-
-Adjust based on production metrics after deployment.
-
-## Testing
-
-Core cache behavior (hit, miss, TTL, error propagation) is tested on `Cache<T>.getOrFetch()` in `src/lib/clients/cache.test.ts`. Domain cache tests cover only domain-specific concerns:
-
-- **Wiring**: wrapper delegates correctly and returns cached value on subsequent calls
-- **Key isolation**: different parameters produce different cache keys (e.g., `buildPlacementKey`)
-- **Invalidation grouping**: `invalidate*()` clears all related caches
-
-Do not duplicate TTL or error propagation tests in domain cache test files.
-
-Always call `afterAll(() => dispose*Caches())` to prevent timer leaks. Isolate tests with `beforeEach(() => invalidate*Caches())`.
-
-## Type Constraint
-
-`Cache<T extends {}>` — never use `null` or `undefined` as `T`. The cache uses `=== undefined` to detect misses; storing `undefined` would silently bypass the cache on every call.
-
-## Stampede Prevention
-
-`Cache<T>.getOrFetch()` shares a single in-flight `Promise` across concurrent callers for the same key. Do not implement manual dedup on top of it.
-
-## Invalidation Audit
-
-When adding a new DB write function, audit every write path in the same domain for missing `invalidate*Caches()` calls. Initial implementation of `upsertVoteGradeTables()` missed this and served stale data for up to 10 minutes.
-
-## Service Layer Integration
-
-Services call `getCached*()` with a `fetchFn` that performs the DB query. The service does not import `Cache` directly.
-
-```typescript
-// In service file
-import { getCachedTasksMap } from '$lib/server/tasks/cache';
-
-export async function getTasksByTaskId(): Promise<Map<string, Task>> {
-  return getCachedTasksMap(async () => {
-    const tasks = await db.task.findMany();
-    return new Map(tasks.map((task) => [task.task_id, task]));
-  });
-}
-```
-
-Mock cache in service tests to bypass caching:
-
-```typescript
-vi.mock('$lib/server/tasks/cache', () => ({
-  getCachedTasksMap: (fetchFn: () => Promise<unknown>) => fetchFn(),
-  invalidateTaskCaches: vi.fn(),
-}));
-```
diff --git a/.claude/rules/server-cache.md b/.claude/rules/server-cache.md
new file mode 120000
index 000000000..69a466ff3
--- /dev/null
+++ b/.claude/rules/server-cache.md
@@ -0,0 +1 @@
+../../docs/guides/agent-rules/server-cache.md
\ No newline at end of file
diff --git a/.claude/rules/svelte-components.md b/.claude/rules/svelte-components.md
deleted file mode 100644
index ad3bb9fb2..000000000
--- a/.claude/rules/svelte-components.md
+++ /dev/null
@@ -1,111 +0,0 @@
----
-description: Svelte component development rules
-paths:
-  - 'src/**/*.svelte'
-  - 'src/lib/components/**'
-  - 'src/lib/stores/**/*.svelte.ts'
----
-
-# Svelte Components
-
-## Runes (Required)
-
-Use `$props()`, `$state()`, `$derived()`, `$effect()` in all components:
-
-```svelte
-<script lang="ts">
-  interface Props {
-    title: string;
-    count?: number;
-  }
-  let { title, count = 0 }: Props = $props();
-</script>
-```
-
-## File Naming
-
-- Components: `PascalCase.svelte`
-- Stores: `snake_case.svelte.ts`; class-based with `$state()`, singleton export
-
-## Props & Reactivity
-
-- Pass **model objects**, not individual fields; derive computed values inside
-- For `data.*` in `+page.svelte`: use `$derived` to sync after `load()` re-runs
-- Use `$derived` for computed values over `$state` + `$effect`
-- Capture state **before** first `await` for safe rollback
-
-## `{#each}` Patterns
-
-- Always key: `(item.id)` or `(i)`
-- **Key MUST be unique per iteration** — if domain allows duplicates, use composite key (e.g. `contest_id + '-' + task_id`)
-- Filter **before**, not inside with `{#if}`
-- Use `{:else}` for empty lists
-
-```svelte
-{#each visibleItems as item (item.id)}
-  <Row {item} />
-{:else}
-  <p>No items.</p>
-{/each}
-```
-
-**Common Trap:** `task_id` alone is NOT unique when same task appears in multiple contests. Use `contest_id + '-' + task_id` as composite key (see issue #3460 & PR #3442).
-
-## Snippets vs Components
-
-- **Snippet**: needs `$state` access, pure display, same-file; params require explicit type `{#snippet label(item: Item)}`
-- **Component**: independent logic, >30 lines, multi-file reuse
-- Define snippets at **top level** (outside tags)
-
-**Context trap:** Snippets capture context at definition site, not render site. Never define a snippet outside a context provider (e.g. `<Tabs>`) and `{@render}` it inside — `TabItem` calls `getContext` on init and throws during HMR when `<Tabs>` is not in its ancestor chain. Place children directly inside the provider.
-
-## Async/Abort Handling
-
-When user can trigger same action multiple times, use `AbortController`:
-
-1. New abort on each submission: `voteAbortController?.abort(); voteAbortController = new AbortController()`
-2. Pass signal to fetches: `fetchMedian(taskId, signal)`
-3. Validate `signal?.aborted` in `.then()` to silently drop intentional aborts
-
-## SSR Safety
-
-- No `crypto.randomUUID()` or `Math.random()` at component init (hydration mismatch)
-- Derive IDs deterministically: `const id = item.task_id`
-- Browser APIs: check `globalThis.location?.origin` before `browser` flag; warn only as last resort
-
-## Flowbite Svelte
-
-Import from `flowbite-svelte`. Use Tailwind v4 `dark:` prefix. When copying button styles, check `color`, `size`, `class`. Omitting `color` applies Flowbite's filled blue default.
-
-`ButtonGroup` uses `flex` internally (no wrap). For wrapping, use `<div class="flex flex-wrap gap-1">` with individual `Button` components.
-
-## Component Structure
-
-- Extract conditional logic to private functions: `function isCrossRouteNavigation() { ... }`
-- Move business logic to `_utils/` or `utils/` with tests
-- Keep components thin: one responsibility
-
-## `{@const}` Placement Restriction
-
-`{@const}` is only valid as the immediate child of a control-flow block (`{#if}`, `{#each}`, `{:else}`, etc.) — placing it at the template top level is a compile error.
-
-When you need a derived value in both a `{#if}` condition and its body, declare it with `$derived` in `<script>` instead:
-
-```typescript
-// ✅ in <script>
-let groupMetadata = $derived(store?.getMetadata());
-```
-
-```svelte
-{#if groupMetadata?.title}
-  <Heading>{groupMetadata.title}</Heading>
-{/if}
-```
-
-This also avoids calling the getter twice per render.
-
-## Reactive Data Pitfalls
-
-- `let` captures initial value only; use `$derived` for derived/prop data
-- Inside `$effect`, use `$store` syntax, not `get(store)` (bypasses reactivity)
-- `$derived.by(() => { ... })` for multi-statement logic
diff --git a/.claude/rules/svelte-components.md b/.claude/rules/svelte-components.md
new file mode 120000
index 000000000..8544da302
--- /dev/null
+++ b/.claude/rules/svelte-components.md
@@ -0,0 +1 @@
+../../docs/guides/agent-rules/svelte-components.md
\ No newline at end of file
diff --git a/.claude/rules/svelte-runes.md b/.claude/rules/svelte-runes.md
deleted file mode 100644
index bfea707a0..000000000
--- a/.claude/rules/svelte-runes.md
+++ /dev/null
@@ -1,64 +0,0 @@
----
-description: Svelte 5 Runes and reactivity rules
-paths:
-  - 'src/**/*.svelte'
-  - 'src/lib/stores/**/*.svelte.ts'
-  - 'src/features/**/stores/**'
----
-
-# Svelte Runes & Reactivity
-
-## `$state()` & `$props()`
-
-- `let` captures initial value only; use `$derived` for props/server data
-- Referencing `$props()` in `$state()` initializer? Wrap with `untrack` if intentional (seed-only)
-- `pnpm check` warns: "This reference only captures the initial value"
-
-## `SvelteMap<K, V>` — Always Type
-
-`SvelteMap` without type params makes `.get()` return `unknown`. Always declare:
-
-```typescript
-const map = new SvelteMap<TaskGrade, TaskResults>();
-```
-
-`$state()` wrapping unnecessary — `SvelteMap` is reactive. Reset with `.clear()` not reassign.
-
-Inside `$derived`, plain `new Map()` suffices — reactive dependency tracked at `$derived` level.
-
-## `$derived` & `$effect`
-
-- Prefer `$derived` over `$state` + `$effect` for computed values
-- No arrow functions: `$derived(() => fn(x))` stores the function, doesn't call it
-- Use `.by()` for multi-statement: `$derived.by(() => { ... })`
-- Inside `$effect`, use `$store` syntax, not `get(store)` (bypasses signal graph)
-
-## `$derived` Tracks Reactive Reads Inside Called Functions
-
-`$derived(fn)` tracks every reactive read inside `fn`, **including reads inside helper functions** called by `fn`. If a helper reads a `$state` array, the derived re-runs whenever that array changes.
-
-**Accumulation trap**: if the helper transforms data (e.g. `{ ...item, title: prefix + item.title }`) and the result is later written back to the source array (optimistic update), the next re-run reads the already-transformed value and transforms it again.
-
-Fix: put display formatting only in the leaf view (e.g. `$derived displayTitle` in a cell component), never inside a derived that feeds mutable state.
-
-## Optimistic Updates
-
-Derive computed fields from canonical data source, not re-implement inline. Divergence → "works after reload" bugs.
-
-Diagnostic: "Not reflected live, but fixed after reload" → check optimistic update payload.
-
-## Async Rollback
-
-Capture state **before** first `await`:
-
-```typescript
-const previous = items;
-
-try {
-  await saveToServer(items);
-} catch {
-  items = previous;
-}
-```
-
-Concurrent updates can overwrite variable while awaiting; capturing prevents data loss.
diff --git a/.claude/rules/svelte-runes.md b/.claude/rules/svelte-runes.md
new file mode 120000
index 000000000..66fb27e1d
--- /dev/null
+++ b/.claude/rules/svelte-runes.md
@@ -0,0 +1 @@
+../../docs/guides/agent-rules/svelte-runes.md
\ No newline at end of file
diff --git a/.claude/rules/sveltekit.md b/.claude/rules/sveltekit.md
deleted file mode 100644
index c04634b8b..000000000
--- a/.claude/rules/sveltekit.md
+++ /dev/null
@@ -1,138 +0,0 @@
----
-description: SvelteKit routing and navigation patterns
-paths:
-  - 'src/routes/**'
-  - 'src/**/*.svelte'
----
-
-# SvelteKit Patterns
-
-## Routes vs API Endpoints
-
-- Page routes: use `redirect()` to navigate
-- API routes (`+server.ts`): use `error()` — `redirect()` returns 3xx; `fetch` follows and gets HTML not JSON
-
-## User-Provided Redirect Destinations
-
-**SvelteKit's `redirect()` does NOT validate origin.** If the redirect destination comes from user input (URL query params, form data), always validate with `isSameOriginRedirect(redirectTo, url.origin)` from `src/lib/utils/url.ts` before redirecting.
-
-## Internal Navigation: `resolve()`
-
-All internal navigation must use `resolve()` from `$app/paths`:
-
-- **Parameterized** (preferred): `resolve('/workbooks/[slug]', { slug: workbook.slug })`
-- **Static**: `resolve('/')` + `@ts-expect-error` (AppTypes merging quirk)
-- **With search/hash**: `resolve(pathname + search + hash)` (concatenate inside, not outside)
-- **External**: no `resolve()`, use `rel="noreferrer external"`
-
-## HTTP Cache Headers (`setHeaders`)
-
-**Never set `s-maxage` / `stale-while-revalidate` on a route whose content varies by session.**
-Shared caches key on URL + method + the headers named by `Vary` (RFC 9111), so without
-`Vary: Cookie` an anonymous response is served to logged-in users (#3862).
-
-- Setting the header only when logged out controls the write side, not delivery of an
-  already-cached entry to a request with a session cookie.
-- `Vary: Cookie` matches the whole header; with `_ga` present every returning visitor gets a
-  unique key and the cache barely hits.
-- No `s-maxage` means no CDN caching, so `private` / `no-store` are unnecessary (YAGNI).
-- Estimate the saved invocations first. At this site's traffic the `/problems` header saved
-  single-digit dollars a month and cost two weeks of a production bug.
-
-## Form Data Validation
-
-`formData.get()` returns `string | File | null`. Always validate before casting:
-
-```typescript
-// Bad: unsafe cast, null reaches DB layer
-const taskId = data.get('taskId') as string;
-
-// Good: validate first
-const taskId = data.get('taskId');
-
-if (typeof taskId !== 'string' || !taskId) return fail(...);
-```
-
-For enum fields:
-
-```typescript
-const gradeRaw = data.get('grade');
-
-if (!(Object.values(TaskGrade) as string[]).includes(gradeRaw)) {
-  return fail(BAD_REQUEST, { message: 'Invalid grade.' });
-}
-
-const grade = gradeRaw as TaskGrade; // Safe now
-```
-
-## Form Actions: `url` Parameter
-
-Form action handlers receive the full `RequestEvent`, including `url`. Destructure it directly:
-
-```typescript
-export const actions = {
-  default: async ({ request, locals, url }) => {
-    const redirectTo = url.searchParams.get('redirectTo');
-  },
-};
-```
-
-`url` is guaranteed non-null. `new URL(request.url)` is an equivalent alternative but unnecessary when `url` is already available.
-
-## Page Component Props
-
-`+page.svelte` accepts only `data` and `form` props (`svelte/valid-prop-names-in-kit-pages`).
-
-## load() Return Structure
-
-Group domain model fields as objects with defaults absorbed at boundary:
-
-```typescript
-// Bad: scattered fields
-export async function load() {
-  return {
-    username: user?.name ?? '',
-    atcoderHandle: user?.atCoder?.handle ?? '',
-    isValidated: user?.atCoder?.isValidated ?? false,
-  };
-}
-
-// Good: grouped by model
-export async function load() {
-  return {
-    username: user?.name ?? '',
-    atCoderAccount: {
-      handle: user?.atCoder?.handle ?? '',
-      isValidated: user?.atCoder?.isValidated ?? false,
-    },
-  };
-}
-```
-
-Consume with `$derived` in `+page.svelte` to sync after `load()` re-runs.
-
-## Error Handling in load()
-
-All async operations must be inside the try-catch block, not before it. Errors from async calls outside propagate unhandled.
-
-**Exception:** Functions that throw `redirect()` or `error()` as control flow must be placed **before** the try-catch. A bare `catch` swallows them, silently disabling redirects and error responses.
-
-## Auth Audit
-
-When protecting one action (in `load()` or form actions), audit all others. Asymmetric guards are a critical vulnerability.
-
-## success Flag & message Consistency
-
-When action returns `success: false`, `message` and `message_type` must reflect failure. Contradicting flags are silent bugs:
-
-```typescript
-// Bad: success contradicts message
-return { success: true, message: 'Failed to save' };
-
-// Good
-return { success: false, message: 'Failed to save' };
-```
-
-## navigating State
-
-`navigating` from `$app/state` always exists (never null). Check idle: `navigating.from === null`. For cross-route navigation only: compare `navigating.from.route.id` with `navigating.to?.route.id` (same-route param changes have equal ids).
diff --git a/.claude/rules/sveltekit.md b/.claude/rules/sveltekit.md
new file mode 120000
index 000000000..95c80f5cd
--- /dev/null
+++ b/.claude/rules/sveltekit.md
@@ -0,0 +1 @@
+../../docs/guides/agent-rules/sveltekit.md
\ No newline at end of file
diff --git a/.claude/rules/testing-e2e.md b/.claude/rules/testing-e2e.md
deleted file mode 100644
index f61df69eb..000000000
--- a/.claude/rules/testing-e2e.md
+++ /dev/null
@@ -1,152 +0,0 @@
----
-description: E2E testing rules and patterns (Playwright)
-paths:
-  - '**/*.spec.ts'
-  - 'e2e/**'
----
-
-# E2E Tests (Playwright)
-
-## Setup
-
-- File extension: **must** be `.spec.ts` (`.test.ts` not detected by `playwright.config.ts`)
-- No path aliases (`$lib`, `$features` not resolved outside SvelteKit). Use type-only imports for types:
-
-```typescript
-// Bad: runtime import fails in E2E
-import { TAB_SOLUTION } from '$features/workbooks/types/workbook';
-
-// Good: type-only import + local constant
-import type { WorkBookTab } from '$features/workbooks/types/workbook';
-
-const TAB_SOLUTION: WorkBookTab = 'solution';
-```
-
-## Describe Hierarchy
-
-Split large `describe` blocks by behavioral dimension, not flat `test()` calls:
-
-```typescript
-test.describe('logged-in user', () => {
-  test.describe('tab visibility', () => { ... });
-  test.describe('URL parameters', () => { ... });
-  test.describe('navigation', () => { ... });
-});
-```
-
-## Parameterized Tests
-
-Playwright has no native `test.each`. Use `for...of` loops (official pattern):
-
-**Single test with loop** — testing a sequence within one test:
-
-```typescript
-const GRADES = ['Q10', 'Q9', 'Q8'] as const;
-
-for (const grade of GRADES) {
-  await gradeButton(page, grade).click();
-  await expect(page).toHaveURL(`?grades=${grade}`);
-}
-```
-
-**Multiple tests from parameters** — independent cases:
-
-```typescript
-for (const grade of GRADES) {
-  test(`filters by ${grade}`, async ({ page }) => {
-    await page.goto('/tasks');
-    await gradeButton(page, grade).click();
-    await expect(page).toHaveURL(`?grades=${grade}`);
-  });
-}
-```
-
-## Selectors & Assertions
-
-### Stable Selectors
-
-Prefer in order:
-
-1. Semantic: `getByRole('button', { name: /submit/i })`
-2. Test IDs: `getByTestId('save-button')`
-3. Avoid CSS classes (refactor-fragile) and internal text unless content is stable
-
-### Assertion Best Practices
-
-- After interaction (click tab, toggle), assert **new state** not just visibility
-- Assert via accessibility attributes (`aria-pressed`, `aria-selected`, `data-*`), not CSS classes
-- `toBeVisible()` may have been true before; assert the change instead:
-
-  ```typescript
-  // Bad: doesn't confirm interaction changed state
-  await tab.click();
-  await expect(content).toBeVisible();
-
-  // Good: asserts content became visible
-  await tab.click();
-  await expect(page).toHaveURL('?tab=details');
-  ```
-
-## Setup & Teardown
-
-- Use `test.beforeEach` / `test.afterEach` for per-test setup
-- Use `test.describe.configure({ mode: 'parallel' })` for parallelization within a describe block
-- Clean up auth state / fixtures after each test (`test.afterEach(() => { ... })`)
-
-## Debugging
-
-- `page.screenshot()` to capture state at assertion
-- `page.pause()` for interactive debugging
-- Logs: `page.on('console', msg => console.log(msg.text()))`
-
-## Multi-Route Infrastructure Changes: Test Ordering
-
-When implementing infrastructure changes that span multiple routes (e.g., redirect behavior, auth flow), write E2E tests **after** the core mechanism is implemented but **before** applying it to all routes:
-
-1. **Implement core mechanism** (unit-tested) — e.g., `isSameOriginRedirect()`, `redirect()` logic
-2. **Write E2E tests** (RED state) — tests fail until all routes are updated
-3. **Apply to all routes** (GREEN state) — update each load/action function to use the mechanism
-
-**Why this order?**
-
-- If you write E2E tests before the mechanism exists, they'll fail immediately and block progress
-- E2E tests verify integration end-to-end; unit tests verify the building blocks
-- The RED→GREEN cycle for E2E tests spans multiple phases, unlike unit tests which turn GREEN immediately
-
-**Example:** Redirect After Login pattern
-
-- Phase 1-2: Unit test `isSameOriginRedirect()` (GREEN)
-- Phase 3-4: Unit test auth helpers (GREEN)
-- Phase 5-6: Implement login/signup actions (GREEN)
-- Phase 7: Write E2E tests for all routes (RED)
-- Phase 8-9: Update all load functions to pass `url` (GREEN)
-
-## Testing Form Action Access Control
-
-Use `page.evaluate(async (url) => fetch(url, { method: 'POST', ... }))` — not `page.request.post()` — to test form action security. In practice, `page.request.post()` fails to carry the session (cookies or `origin` header are not sent as expected), causing auth guards to redirect even for logged-in users.
-
-SvelteKit's response format for form actions differs by outcome:
-
-- `redirect()` → HTTP 200 + JSON body `{"type":"redirect","status":307,"location":"..."}`
-- `error(N)` → HTTP status N
-
-Parse the response body with a typed deserialize helper — not raw `JSON.parse`. `$app/forms` (`deserialize`) is not resolvable outside SvelteKit, so define a local `ActionResultLike` type and a `deserializeActionResult(text)` wrapper in the E2E helper (see `e2e/workbook_edit.spec.ts` for reference). Assert `type` and `location` from the deserialized result for redirect checks, and `response.status` for error checks.
-
-## E2E Lessons from Votes Tests
-
-Recent fixes (detailed in plan.md):
-
-- Dropdown selectors drift when UI changes; re-verify on refactors
-- Abort signal prevents stale response race; update signal if fetch signature changes
-- Toast messages are temporary; use waiter pattern, not fixed delay
-
-## Timeout: Element Not Found
-
-When `page.locator()` or `getByRole()` times out:
-
-1. Verify element exists in DevTools
-2. Check ARIA roles in component UI libraries often lack semantic role definitions
-3. If `role="menuitem"` fails: use href pattern or functional marker instead (e.g., `a[href^="/login?redirectTo"]` vs navbar's `/login`)
-4. Never use `.first()` / `.last()` (DOM order is unstable)
-
-**Example:** `getByRole('menuitem')` times out because DropdownItem renders as `<li><a>` without the role. Use `a[href^="/login?redirectTo"]` to distinguish dropdown from navbar.
diff --git a/.claude/rules/testing-e2e.md b/.claude/rules/testing-e2e.md
new file mode 120000
index 000000000..3a28e7997
--- /dev/null
+++ b/.claude/rules/testing-e2e.md
@@ -0,0 +1 @@
+../../docs/guides/agent-rules/testing-e2e.md
\ No newline at end of file
diff --git a/.claude/rules/testing.md b/.claude/rules/testing.md
deleted file mode 100644
index c8b063393..000000000
--- a/.claude/rules/testing.md
+++ /dev/null
@@ -1,165 +0,0 @@
----
-description: Testing rules and patterns
-paths:
-  - '**/*.test.ts'
-  - '**/*.spec.ts'
-  - 'e2e/**'
-  - 'src/test/**'
----
-
-# Testing
-
-## Principles
-
-- **Tests ship with implementation** — same commit; feature not done until tests pass. Never defer tests for non-trivial logic
-- **English only** — describe expected behavior (e.g., `'returns empty array when workbooks is empty'`)
-- **Test integrity** — never weaken assertions to make tests pass; fix implementation instead. Never let the expected value be computed by the code under test: `expect(f(x)).toBe(map.get(expected))` where `f` is `map.get(classify(x))`, or a fixture whose `expected` calls a production function. Both pass unconditionally. Expected values are literals
-- **Unused imports** — signal missing tests, not dead code — add the test case first
-- **TDD exceptions** — skip test-first for exploratory spikes, type-only changes, and config files with no branching logic
-- **Component testing** — extract logic to `utils/`; omit component Vitest if template-only **and** E2E covers rendering paths
-- **Coverage** — cover happy path, error cases, and domain edge cases of the input values (empty arrays, null, enum extremes); for registry coverage see Assertions & Structure. Treat low coverage as a signal to review, not a target
-
-## File Layout & Environment
-
-| Type | Tool       | Location                  | Command          |
-| ---- | ---------- | ------------------------- | ---------------- |
-| Unit | Vitest     | `src/test/` or co-located | `pnpm test:unit` |
-| E2E  | Playwright | `e2e/`                    | `pnpm test:e2e`  |
-
-- E2E files **must** use `.spec.ts` (`.test.ts` not detected)
-- Route unit tests: name `page_server.test.ts`, never `+page.server.test.ts` (SvelteKit reserves `+` prefix)
-- Both centralized (`src/test/`) and co-located (`src/features/`, `src/lib/`) test locations are supported — see `vite.config.ts` `include`
-
-**Environment:** Default `node`. Only opt in to jsdom (`// @vitest-environment jsdom` at file top) when touching `window` / `document` / `localStorage`. Never set jsdom globally — per-file construction is ~5.5× slower.
-
-## Assertions & Structure
-
-- `toBe(true)` / `toBe(false)`, not `toBeTruthy()` / `toBeFalsy()`
-- DB query tests: assert `orderBy`, `include` with `expect.objectContaining`, not just `where`
-- Enum membership: `Object.hasOwn(Enum, value)`, not `in` (avoids prototype chain)
-- `Promise<void>`: use `await fn()` to assert no throw, or `.resolves.toBeUndefined()`. **Never** bare `.resolves` (false-positive)
-- **Stubs**: parameter types must match production signature — use domain types (`TaskGrade`), not `string`
-- **Test data**: realistic values (real task IDs, grade names). Extract shared fixtures to file/describe scope; inline for single-use
-- **Registry exhaustiveness**: `Record<string, T>` and `new Map([...])` give no compile-time enum coverage — assert it at runtime, with a named, commented exception list so deliberate gaps stay documented: `expect(Object.values(Enum).filter((key) => !REGISTRY.has(key))).toEqual(KNOWN_GAPS)` (`Record` registries: swap `REGISTRY.has(key)` for the `Object.hasOwn` form above)
-- **Test count as a proxy**: after a file split, compare counts (`--reporter=verbose`) — a drop means a describe block was lost in the move. A deliberate drop is valid only when mutation analysis shows detection is unchanged; record the evidence in the commit
-
-Group by scenario, not flat:
-
-```typescript
-describe('validate', () => {
-  describe('successful case', () => { ... });
-  describe('error cases', () => {
-    describe('returns false', () => { ... });
-    describe('throws', () => { ... });
-  });
-});
-```
-
-Parameterized: test enum boundaries + typical value, then separate test for distinct behavior:
-
-```typescript
-test.each([TaskGrade.PENDING, TaskGrade.Q11, TaskGrade.Q10, TaskGrade.D6])(
-  'returns grade %s', (grade) => { ... }
-);
-```
-
-## Mocking
-
-### Cleanup (Vitest v5)
-
-- `clearMocks: true` is the v5 default — **never add `vi.clearAllMocks()`**; it clears call history only — `mockResolvedValue` / `vi.when()` implementations persist, so each test re-sets what it needs
-- `restoreMocks` is still `false` — `vi.restoreAllMocks()` remains needed for `vi.spyOn`
-
-### Service Layer (Prisma)
-
-Mock with `vi.mock('$lib/server/database', ...)`. Use helpers:
-
-```typescript
-const mockFindUnique = (data) => db.task.findUnique.mockResolvedValue(data);
-```
-
-When the same mock is called with different arguments in one test, use `vi.when()` instead of `mockResolvedValueOnce` chains:
-
-```typescript
-vi.when(vi.mocked(prisma.workBook.findMany))
-  .calledWith(
-    expect.objectContaining({
-      where: expect.objectContaining({ workBookType: WorkBookType.CURRICULUM }),
-    }),
-  )
-  .thenResolve(curriculumRows);
-```
-
-### Cache Modules
-
-```typescript
-afterAll(() => disposeDomainCaches());
-beforeEach(() => invalidateDomainCaches());
-
-// Bypass caching in service tests:
-vi.mock('$lib/server/tasks/cache', () => ({
-  getCachedTasksMap: (fetchFn: () => Promise<unknown>) => fetchFn(),
-  invalidateTaskCaches: vi.fn(),
-}));
-```
-
-### HTTP (Nock)
-
-Extract setup into helpers at describe scope:
-
-```typescript
-const mockGetUser = (statusCode, user?) => {
-  nock('http://localhost')
-    .get('/api/user')
-    .reply(statusCode, user ? { user } : undefined);
-};
-```
-
-### Environment Variables
-
-Use `vi.stubEnv()` + `vi.unstubAllEnvs()` in `afterEach`.
-
-### globalThis / Mutable Exports
-
-Save and restore `globalThis` state via `Object.defineProperty` in `beforeEach`/`afterEach`.
-
-For mutable module-level `const` objects (override maps), mutate directly in `beforeEach`/`afterEach` — no `vi.mock` needed.
-
-## SvelteKit-Specific
-
-### Browser Toggle per Describe
-
-**Never register `vi.mock('$app/environment')` twice in one file** — the second hoisted call silently overwrites the first, pinning the whole file to one value. Use one dynamic mock with a `vi.hoisted` flag:
-
-```typescript
-// @vitest-environment jsdom
-const browserState = vi.hoisted(() => ({ value: false }));
-vi.mock('$app/environment', () => ({
-  get browser() {
-    return browserState.value;
-  },
-}));
-
-// In browser describe: browserState.value = true; construct fresh instance
-// In SSR describe: browserState.value = false
-```
-
-**Never assert a browser branch on the import-time singleton** — it is always constructed in SSR mode. Construct a fresh instance inside the browser `describe`.
-
-In jsdom files, use jsdom's real `Storage` and assert state (`localStorage.getItem(key)`), not spy calls. Cover SSR guards separately:
-
-- **read guard**: pre-seed localStorage, construct store, expect the default
-- **write guard**: empty localStorage, call setter, expect `getItem(key)` still null
-
-### Route load() Tests
-
-Call `load` directly with a mock event. Pass `setHeaders` as `vi.fn()` to assert header behavior. Wire assertions cannot be verified in unit tests — cover in E2E.
-
-```typescript
-const createMockEvent = ({ session = null } = {}) =>
-  ({
-    locals: { auth: { validate: vi.fn().mockResolvedValue(session) } },
-    url: { searchParams: { get: vi.fn().mockReturnValue(null) } },
-    setHeaders: vi.fn(),
-  }) as unknown as Parameters<typeof load>[0] & { setHeaders: ReturnType<typeof vi.fn> };
-```
diff --git a/.claude/rules/testing.md b/.claude/rules/testing.md
new file mode 120000
index 000000000..5f6b1c213
--- /dev/null
+++ b/.claude/rules/testing.md
@@ -0,0 +1 @@
+../../docs/guides/agent-rules/testing.md
\ No newline at end of file
diff --git a/.claude/settings.json b/.claude/settings.json
index 0edc5ffd2..602db4f4e 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -3,7 +3,13 @@
     "enabled": true,
     "allowUnsandboxedCommands": false,
     "filesystem": {
-      "denyRead": ["~/.ssh"]
+      "denyRead": [
+        "~/.ssh",
+        "~/.claude/.credentials.json",
+        "~/.codex/auth.json",
+        "**/.env",
+        "**/.env.*"
+      ]
     }
   },
   "permissions": {
@@ -20,6 +26,9 @@
       "Bash(gh release delete *)",
       "Bash(gh repo delete *)",
       "Bash(chmod 777 *)",
+      "Read(~/.ssh/**)",
+      "Read(~/.claude/.credentials.json)",
+      "Read(~/.codex/auth.json)",
       "Read(**/.env)",
       "Read(**/.env.*)",
       "Read(**/secrets/**)",
@@ -27,16 +36,5 @@
       "Read(**/*.pem)",
       "Read(**/*.key)"
     ]
-  },
-  "enabledPlugins": {
-    "superpowers@superpowers-dev": true
-  },
-  "extraKnownMarketplaces": {
-    "superpowers-dev": {
-      "source": {
-        "source": "git",
-        "url": "https://github.com/obra/superpowers.git"
-      }
-    }
   }
 }
diff --git a/.claude/skills/add-contest-table-provider b/.claude/skills/add-contest-table-provider
new file mode 120000
index 000000000..b45f6d447
--- /dev/null
+++ b/.claude/skills/add-contest-table-provider
@@ -0,0 +1 @@
+../../.agents/skills/add-contest-table-provider
\ No newline at end of file
diff --git a/.claude/skills/dep-upgrade b/.claude/skills/dep-upgrade
new file mode 120000
index 000000000..9e9d7a98b
--- /dev/null
+++ b/.claude/skills/dep-upgrade
@@ -0,0 +1 @@
+../../.agents/skills/dep-upgrade
\ No newline at end of file
diff --git a/.claude/skills/extract-approach b/.claude/skills/extract-approach
new file mode 120000
index 000000000..f82843d34
--- /dev/null
+++ b/.claude/skills/extract-approach
@@ -0,0 +1 @@
+../../.agents/skills/extract-approach
\ No newline at end of file
diff --git a/.claude/skills/refactor-plan/SKILL.md b/.claude/skills/refactor-plan/SKILL.md
deleted file mode 100644
index 46141ec29..000000000
--- a/.claude/skills/refactor-plan/SKILL.md
+++ /dev/null
@@ -1,13 +0,0 @@
----
-name: refactor-plan
-description: Analyze a GitHub issue or file path and produce a phased refactoring plan. Outputs a TODO list only — does not make code changes.
-disable-model-invocation: true
-argument-hint: '[issue-number | file-path]'
----
-
-Produce a refactoring plan for: $ARGUMENTS
-
-1. **Gather context** — number: `gh issue view $ARGUMENTS --comments` (if `gh` unavailable, fetch the issue via WebFetch); path: read source files under that path
-2. **Investigate** — read relevant source files; apply the checklist in [instructions.md](instructions.md)
-3. **Plan** — group findings into phases (lowest → highest risk); each phase is a `- [ ]` checklist; note inter-phase dependencies
-4. **Stop — output the plan only. Do not implement any changes.**
diff --git a/.claude/skills/refactor-plan/instructions.md b/.claude/skills/refactor-plan/instructions.md
deleted file mode 100644
index 9a3725920..000000000
--- a/.claude/skills/refactor-plan/instructions.md
+++ /dev/null
@@ -1,66 +0,0 @@
-# Refactoring Investigation Checklist
-
-Scan the target code in this order (lowest risk first). List every concrete finding — do not skip ambiguous cases.
-
-## 1. Naming and Style
-
-- Abbreviated/single-character names (`res`, `btn`, etc.) → expand to full names
-- Single-statement `if` without braces → add braces
-- Hardcoded string literals matching enum values → replace with enum constants
-- `toBeTruthy()` / `toBeFalsy()` in tests → replace with `toBe(true)` / `toBe(false)`
-
-## 2. Type Definitions
-
-- `Hoge[]` in signatures → define a plural type alias
-- Inline union literals repeated in multiple places → extract to a named type
-- Function argument types broader than needed → narrow to minimum fields used
-
-## 3. Pure Function Extraction
-
-- Side effects mixed with business logic → extract logic as a pure function to `utils/` (use `_utils/` inside `src/routes/`; same rule applies below)
-- Extracted `utils/` functions with no adjacent tests → add tests at extraction time
-
-## 4. Component Bloat
-
-- Static constants inside `<script>` → move to `utils/`
-- Transformation/calculation logic inside `<script>` → move to `utils/`
-- `if (activeTab === '...')` branching → replace with `Record<EnumKey, Config>`
-- Snippet vs. component cases → apply `.claude/rules/svelte-components.md` criteria
-
-## 5. Service Layer Structure
-
-- DB query + business logic + DB write in one function → split by responsibility
-- Route handlers or `seed.ts` calling Prisma directly → delegate to service layer
-- Service functions returning `Response` or `json()` → change to `{ error: string } | null`
-
-## 6. Test Coverage
-
-- Abstract test data (`'t1'`, `'t2'`) → replace with real fixture values
-- Test data duplicated across cases → extract to a fixture file
-- Repeated `vi.mocked(...).mockResolvedValue(...)` patterns → extract to a helper
-- `utils/` functions with no adjacent tests → add tests
-
-## 7. Documentation (always last)
-
-- New patterns not yet in `.claude/rules/` → note which rule file to update
-- Record key decisions in dev-note; discard completed plans after the session
-
----
-
-## Phase Design Principles
-
-- Order phases by risk: isolated mechanical changes first, structural changes last
-- State inter-phase dependencies explicitly
-- For uncertain changes, add an **investigation sub-step** before the implementation task
-- Each task must have single responsibility — implement one logical change (e.g., "add a field", "rename a type") even if it spans multiple layers; avoid mixing unrelated changes in one task
-- "Implementation + test + commit" should fit within one task; if not, split further
-
-## When to Skip Tests
-
-Skip unit tests when:
-
-- The function has no logic (e.g., `if (!res.ok) throw`)
-- The target is `seed.ts` (integration-level scope)
-- Testing requires mocking the entire framework (auth redirects, DnD events)
-
-Note "covered by E2E" or "no testable logic" next to these tasks.
diff --git a/.claude/skills/session-close/SKILL.md b/.claude/skills/session-close/SKILL.md
deleted file mode 100644
index a9773cee1..000000000
--- a/.claude/skills/session-close/SKILL.md
+++ /dev/null
@@ -1,10 +0,0 @@
----
-name: session-close
-description: Standard closing routine for an implementation session. Verifies tests, updates the plan checklist, proposes rule/skill additions, checks for bloat, and detects repeated instructions.
-disable-model-invocation: true
-argument-hint: '[plan-file-path]'
----
-
-Run the session-close routine described in [instructions.md](instructions.md).
-
-Arguments: path to the active `plan.md` (optional — defaults to the most recently modified `docs/dev-notes/**/plan.md`).
diff --git a/.claude/skills/session-close/instructions.md b/.claude/skills/session-close/instructions.md
deleted file mode 100644
index a32a3850d..000000000
--- a/.claude/skills/session-close/instructions.md
+++ /dev/null
@@ -1,60 +0,0 @@
-# Session Close — Detailed Instructions
-
-## Step 1: Verify Tests and Types
-
-Run both checks and fix any failures before proceeding:
-
-```bash
-pnpm test:unit
-pnpm test:e2e
-pnpm check
-```
-
-Only errors introduced by this session need fixing. Pre-existing errors (visible in git diff baseline) may be left as-is with a note.
-
-## Step 2: Update plan.md
-
-Target file: the path passed as `$ARGUMENTS`, or the most recently modified `docs/dev-notes/**/plan.md`.
-
-- Mark completed tasks: `- [ ]` → `- [x]`
-- If all tasks in the plan are done, append a one-line completion note, then delete the file or replace its body with a single-line summary. Stale plan files must not be left behind.
-
-## Step 3: Propose Rule / Skill Additions
-
-Read all files in `.claude/rules/` and `.claude/skills/`. Then review the session's changes and identify lessons that meet **all** of the following criteria:
-
-1. Generic enough to apply in future sessions (not specific to this PR's domain)
-2. Not already covered by an existing rule or skill
-3. Grounded in something that actually happened in this session (a bug caught, a type error, a pattern extracted)
-
-Present each candidate as:
-
-```
-→ Add to `<filename>`: under section `<section>`
-<code example>
-<one-sentence rationale>
-```
-
-Do not apply changes until the user confirms.
-
-## Step 4: Validate Rules / Skills for Bloat
-
-For each file in `.claude/rules/`:
-
-- Flag sections that duplicate content in another rule file
-- Flag files exceeding 150 lines where consolidation is possible
-- Flag outdated or project-specific content that no longer applies
-
-Present a concrete diff proposal for each issue. Do not apply without confirmation.
-
-## Step 5: Detect Repeated User Instructions
-
-Scan the conversation history for instructions the user gave more than once across this or prior sessions (visible in memory or chat context). Categorize each as:
-
-| Pattern                                | Suggested fix                             |
-| -------------------------------------- | ----------------------------------------- |
-| Always applies to every session        | Add to `AGENTS.md` workflow               |
-| Applies to a specific file type        | Add to the relevant `.claude/rules/` file |
-| A multi-step workflow called on demand | Promote to a new Skill                    |
-
-Report findings as a short bulleted list. Do not modify files without confirmation.
diff --git a/.claude/skills/verify-test-strength b/.claude/skills/verify-test-strength
new file mode 120000
index 000000000..54655fed6
--- /dev/null
+++ b/.claude/skills/verify-test-strength
@@ -0,0 +1 @@
+../../.agents/skills/verify-test-strength
\ No newline at end of file
diff --git a/.coderabbit.yaml b/.coderabbit.yaml
index ef1487b36..e85513904 100644
--- a/.coderabbit.yaml
+++ b/.coderabbit.yaml
@@ -29,7 +29,7 @@ reviews:
     # --- Schema / validation ---
     - path: 'src/**/zod/**'
       instructions: |
-        - Use `z.number().int().positive()` for Prisma `Int` fields (not `z.number().positive()`, which passes decimals).
+        - Use `z.number().int()` for Prisma `Int` fields (not `z.number().positive()`, which passes decimals); add `.positive()` only where the domain requires a positive value.
         - When a Zod constraint mirrors a SQL CHECK, add an inline comment noting both layers and the obligation to keep them in sync.
     # --- Domain types ---
     - path: 'src/**/*types/**'
diff --git a/.codex/config.toml b/.codex/config.toml
new file mode 100644
index 000000000..08e6abfc4
--- /dev/null
+++ b/.codex/config.toml
@@ -0,0 +1,31 @@
+approval_policy = "on-request"
+default_permissions = "project-edit"
+
+[permissions.project-edit]
+description = "Edit this project without exposing mounted credentials."
+extends = ":workspace"
+
+[permissions.project-edit.filesystem]
+glob_scan_max_depth = 8
+"~/.codex/auth.json" = "deny"
+"~/.claude/.credentials.json" = "deny"
+"~/.ssh/**" = "deny"
+
+# Keep the denied set aligned with `.claude/settings.json`. Both files are committed and
+# therefore apply to host clones and cloud agents, not only to this devcontainer.
+[permissions.project-edit.filesystem.":workspace_roots"]
+".env" = "deny"
+".env.*" = "deny"
+# A leading `**/` does not match a top-level path in every glob implementation, so the
+# bare and recursive forms are both listed on purpose.
+"**/.env" = "deny"
+"**/.env.*" = "deny"
+"**/secrets/**" = "deny"
+"**/config/credentials.json" = "deny"
+"**/*.pem" = "deny"
+"**/*.key" = "deny"
+
+[shell_environment_policy]
+inherit = "core"
+# Same as the current default; stated explicitly to pin the intent if that default ever changes.
+ignore_default_excludes = false
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
index 937ab0897..b743d2d1f 100644
--- a/.devcontainer/devcontainer.json
+++ b/.devcontainer/devcontainer.json
@@ -7,8 +7,8 @@
   // Use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
   "dockerComposeFile": ["../compose.yaml"],
   "mounts": [
-    "source=${localEnv:HOME}/.ssh,target=/home/node/.ssh,type=bind,consistency=cached",
     "source=${localEnv:HOME}/.claude,target=/home/node/.claude,type=bind,consistency=cached",
+    "source=${localEnv:HOME}/.codex-devcontainer/AtCoderNoviSteps,target=/home/node/.codex,type=bind,consistency=cached",
     "source=${localEnv:HOME}/.gitconfig,target=/home/node/.gitconfig,type=bind,consistency=cached"
   ],
   // Features to add to the dev container. More info: https://containers.dev/features.
@@ -25,7 +25,7 @@
   // "shutdownAction": "none",
   //
   // Use 'initializeCommand' to run commands before the container is created.
-  "initializeCommand": "mkdir -p ~/.claude && touch ~/.gitconfig",
+  "initializeCommand": "mkdir -p ~/.claude ~/.codex-devcontainer/AtCoderNoviSteps && touch ~/.gitconfig",
   //
   // Use 'postCreateCommand' to run commands after the container is created.
   "postCreateCommand": "bash .devcontainer/setup-devcontainer.sh",
@@ -76,7 +76,8 @@
           "editor.defaultFormatter": "Prisma.prisma"
         },
         "[markdown]": {
-          "editor.formatOnSave": false
+          "editor.formatOnSave": false,
+          "editor.wordWrap": "on"
         },
         "svelte.enable-ts-plugin": true
       },
@@ -89,6 +90,7 @@
         "esbenp.prettier-vscode",
         "formulahendry.auto-rename-tag",
         "ms-playwright.playwright",
+        "openai.chatgpt",
         "Prisma.prisma",
         "streetsidesoftware.code-spell-checker",
         "svelte.svelte-vscode",
@@ -98,7 +100,8 @@
   },
   "containerEnv": {
     "NODE_OPTIONS": "--max-old-space-size=4096 --dns-result-order=ipv4first",
-    "CLAUDE_CONFIG_DIR": "/home/node/.claude"
+    "CLAUDE_CONFIG_DIR": "/home/node/.claude",
+    "CODEX_HOME": "/home/node/.codex"
   }
   //
   // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
diff --git a/.devcontainer/setup-devcontainer.sh b/.devcontainer/setup-devcontainer.sh
index 4a4f1fd2d..b54f1a157 100644
--- a/.devcontainer/setup-devcontainer.sh
+++ b/.devcontainer/setup-devcontainer.sh
@@ -1,14 +1,35 @@
 #!/bin/bash
 set -euo pipefail
 
-# Install Claude Code CLI
-npm install -g @anthropic-ai/claude-code
+# Install agent CLIs independently so one unavailable registry package does not block setup.
+npm install -g @anthropic-ai/claude-code || echo 'Claude Code CLI installation failed, continuing...'
+
+npm install -g @openai/codex || echo 'OpenAI Codex CLI installation failed, continuing...'
+
+# Keep the mounted Codex state private.
+# Non-blocking: a mount whose owner does not match must not stop `pnpm install` below.
+# A default is required because `set -u` aborts on an unset variable before `||` can run.
+codex_home="${CODEX_HOME:-/home/node/.codex}"
+
+install -d -m 700 "${codex_home}" || echo "Could not secure ${codex_home}, continuing..."
+
+if [[ -e "${codex_home}/auth.json" ]]; then
+  chmod 600 "${codex_home}/auth.json" || echo 'Could not secure the Codex auth file, continuing...'
+fi
 
 # Install CodeRabbit CLI (continue if fails)
 curl -fsSL https://cli.coderabbit.ai/install.sh | sh || echo 'CodeRabbit CLI installation failed, continuing...'
 
-# Install RTK — token optimization proxy for AI coding assistants (60-90% reduction)
-curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/master/install.sh | sh || echo 'RTK installation failed, continuing...'
+# RTK is an agent-independent CLI. Do not report setup success when its binary is absent.
+curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/master/install.sh | sh
+
+# Disable telemetry both for this setup process and persistently for later RTK invocations.
+export RTK_TELEMETRY_DISABLED=1
+rtk telemetry disable
+rtk --version
+rtk gain >/dev/null
+
+# Agent integration is optional and separate from installing the RTK CLI.
 rtk init -g --auto-patch || echo 'RTK init failed, continuing...'
 
 # Install project dependencies
diff --git a/.dockerignore b/.dockerignore
index f1377f106..bf9573774 100644
--- a/.dockerignore
+++ b/.dockerignore
@@ -1,8 +1,13 @@
 .history
+.git
+.claude/settings.local.json
+.env
+.env.*
+!.env.example
 .pnpm-store
 .svelte-kit
 node_modules
 package-lock.json
 LICENSE
 CONTRIBUTING.md
-README.md
\ No newline at end of file
+README.md
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 89aa631e7..3a2597e88 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -59,6 +59,9 @@ jobs:
       - name: Lint
         run: pnpm lint
 
+      - name: Check
+        run: pnpm check
+
       - name: Unit test
         run: pnpm test:unit
 
diff --git a/AGENTS.md b/AGENTS.md
index 8f9c26345..d246694ee 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -2,115 +2,97 @@
 
 A web service for tracking submissions on AtCoder and other competitive programming sites, which are graded by difficulty (Q11-D6).
 
-## Guidelines
+## Principles
 
-Always prefer simplicity over pathological correctness. YAGNI, KISS, DRY. No backward-compat shims or fallback paths unless they come free without adding cyclomatic complexity.
+- Prefer simple designs: YAGNI, KISS, DRY.
+- Do not add compatibility shims or fallback paths unless they are effectively free.
+- Write plans and dev notes in Japanese. Write source comments, test names, and commits in English.
+- Write Markdown with one semantic paragraph or list item per line; rely on editor soft wrapping instead of width-based hard line breaks.
 
-**When implementing:**
+## Implementation Workflow
 
-1. Use `/writing-plans` to generate a phased plan (lower risk → higher risk order). Store the plan at `docs/dev-notes/YYYY-MM-DD/{task-name-en}/plan.md`. Split into `phase-N.md` files when the plan exceeds 200 lines or has 5+ phases. Each plan must include: overview, design rationale, rejected alternatives, and a per-phase summary. Write plans in Japanese; source code comments in English. Verify each task before starting:
-   - Which layer? (prisma / server / zod / types / fixtures / services / utils / stores / routes / components) — split if 2+ layers
-   - Single responsibility: one purpose per task
-   - Existing util/service/type? Search before creating
-   - Test name: state it in the task description
-2. Before writing a new function, search `src/lib/utils/`, `src/lib/services/`, `src/features/*/utils/` and `src/features/*/services/` for existing implementations; extract shared logic there when it appears in 2+ places
-3. Write tests first, then implement production code, then verify with `pnpm test:unit`
-4. Review critically after implementing: flag YAGNI violations, over-abstraction, missing tests
-5. After all phases complete (feature and refactor branches only — not hotfixes or dependency bumps): run a mandatory refactor cycle. Write to `plan.md`: novel lessons (implementation blockers, non-obvious patterns not already in rules) and remaining tasks. Discard `phase-N.md` files. Run `coderabbit review --plain`; write all findings of `critical` / `high` / `potential_issue` (medium) to a `## CodeRabbit Findings` section in `plan.md`. The user decides which to fix before opening a PR; do not fix any finding unilaterally. `nitpick` findings defer to PR CI.
-6. Run `/session-close` at the end of feature and refactor branches (not hotfixes, deps bumps, or single-session fixes): updates plan checklist, proposes rule/skill additions, checks for bloat, and detects repeated instructions
+1. Before implementation, create a lower-risk-to-higher-risk phased plan at `docs/dev-notes/YYYY-MM-DD/{task-name-en}/plan.md`. Keep it concise without omitting the overview, design rationale, rejected alternatives, or per-phase summary; split it only when that makes the plan easier to understand. For new features, show the proposed signatures of key functions and interfaces, and the props and events contracts of key components.
+2. Planning does not authorize implementation. Wait for explicit approval such as "implement" or "let's start".
+3. Before each task, identify its layer and single responsibility, search for an existing util/service/type, and state the test name. Split tasks that span multiple layers.
+4. Write tests first, implement production code, then run `pnpm test:unit`. Configuration, documentation, type-only changes, and exploratory spikes may skip test-first when they have no branching behavior.
+5. Review the result for YAGNI violations, over-abstraction, and missing tests.
 
-**Plan Approval ≠ Implementation Start:** Generating a plan (`/writing-plans`) does NOT authorize implementation. Always:
+Before adding a function, search `src/lib/utils/`, `src/lib/services/`, `src/features/*/utils/`, and `src/features/*/services/`. Extract shared logic when it is used in two or more places.
 
-- Wait for explicit user consent ("let's start", "implement", etc.)
-- Use AskUserQuestion before starting if requirements are ambiguous (data model, preferences, test scope, etc.)
+## Architecture
 
-## Working with the User
+SvelteKit 2 + Svelte 5 Runes + TypeScript | PostgreSQL + Prisma | Flowbite Svelte + Tailwind 4 | Vitest + Playwright | oxlint + ESLint
 
-### Communication
+Layers: `prisma/` | `src/**/server/` | `src/**/zod/` | `src/**/types/`, `src/**/fixtures/` | `src/**/services/` | `src/**/utils/` | `src/**/stores/` | `src/routes/` | `src/**/*.svelte`. Each layer's constraints are in the layer table of `coding-style.md`; read it before writing logic.
 
-- **No social pleasantries:** Skip opening remarks like "お疲れ様です", "了解しました", "ありがとうございます"
-- **Direct & concise:** Lead with substance (findings, next steps, decisions)
-- **Task-focused:** Avoid flattery, apologizing, or performative agreement
-- **Respect the work:** Speak plainly about tradeoffs and real issues; don't sugar-coat
+- Put code used by one domain in `src/features/{feature}/`; put code shared by two or more domains in `src/lib/`.
+- Feature-to-feature imports are not allowed. Move shared code to `src/lib/`.
+- Route-local `_components/`, `_types/`, `_fixtures/`, and `_utils/` are exceptions for an admin page whose code is tightly coupled to that route's authorization or layout.
+- Services return data or `null`; they never call `error()`, `redirect()`, or return HTTP responses. Routes translate service results into HTTP behavior.
+- Route handlers do not import Prisma directly.
+- Use `$props()`, `$state()`, and `$derived()` in new Svelte components.
+- Load server data in `+page.server.ts` and consume it through the `data` prop.
+- Use Superforms with Zod for forms.
 
-### Responding to Feedback
+See `docs/guides/architecture.md` for detailed placement rules.
 
-- **Verify before accepting:** Check for misunderstanding, missing context, or counterpoints
-- **Question, don't defer:** Ask clarifying questions or offer alternatives with reasoning—don't blindly follow
+## Path-specific Rules
 
-### Critical Review as Default
+Before planning or changing a matching path, read the corresponding document under `docs/guides/agent-rules/`.
 
-When proposing approaches, designs, or solutions:
+| Path                                 | Rules                                                         |
+| ------------------------------------ | ------------------------------------------------------------- |
+| All source and plans                 | `coding-style.md`                                             |
+| `prisma/**`, server and service code | `prisma-db.md`                                                |
+| `**/*.test.ts`, `src/test/**`        | `testing.md`                                                  |
+| `**/*.spec.ts`, `e2e/**`             | `testing-e2e.md`                                              |
+| Svelte components and stores         | `svelte-components.md`, `svelte-runes.md`, `accessibility.md` |
+| SvelteKit routes                     | `sveltekit.md`                                                |
+| Authentication and admin paths       | `auth.md`                                                     |
+| Server cache modules                 | `server-cache.md`                                             |
+| `.github/workflows/**`               | `github-actions.md`                                           |
 
-- **Lead with the proposal:** State the recommendation clearly
-- **Then critique it:** Point out tradeoffs, risks, limitations, and when it fails
-- **Offer alternatives:** Present 2–3 viable options with reasoning for each
-- **Let user decide:** Don't pretend one option is obviously best if it isn't
+Use project-specific workflows from `.agents/skills/` when a task matches a skill description. Each `.agents/skills/<name>/instructions.md` is a plain Markdown checklist — read it directly when doing that task by hand, not only when an agent loads it automatically.
 
-## Tech Stack
+| Skill                        | Purpose                                          |
+| ---------------------------- | ------------------------------------------------ |
+| `add-contest-table-provider` | Add a ContestType / ContestTableProvider via TDD |
+| `dep-upgrade`                | Analyze and execute a major dependency upgrade   |
+| `extract-approach`           | Extract learnings from a just-solved problem     |
+| `verify-test-strength`       | Verify test detection power via mutation testing |
 
-SvelteKit 2 + Svelte 5 (Runes) + TypeScript | PostgreSQL + Prisma | Flowbite Svelte + Tailwind 4 | Vitest + Playwright | oxlint (JS/TS) + ESLint (Svelte)
+Add a row here whenever a skill is added, renamed, or removed.
+
+## Testing
+
+Test layout, mocking, and assertion rules are in `testing.md` and `testing-e2e.md`. Use `@quramy/prisma-fabbrica` only in `prisma/seed.ts`, never in service unit tests.
 
 ## Commands
 
+Scripts are defined in `package.json`; run them with `pnpm <script>` (`dev`, `build`, `test`, `test:unit`, `test:e2e`, `coverage`, `lint`, `format`, `check`, `db:seed`). Prisma commands are not scripts:
+
 ```bash
-pnpm dev              # Start dev server (localhost:5174)
-pnpm build            # Build for production
-pnpm test             # Run all tests
-pnpm test:unit        # Vitest unit tests
-pnpm test:e2e         # Playwright E2E tests
-pnpm coverage         # Report test coverage
-pnpm lint             # Prettier + oxlint (JS/TS) + ESLint (.svelte) check
-pnpm format           # Prettier format
-pnpm check            # Svelte type check
-pnpm exec prisma generate           # Generate Prisma client
-pnpm exec prisma migrate dev --name # Create migration (with description)
-pnpm db:seed          # Seed database
+pnpm exec prisma generate
+pnpm exec prisma migrate dev --name <description>
 ```
 
-## Project Structure
-
-```md
-src/routes/ # SvelteKit file-based routing
-src/lib/
-├── actions/ # SvelteKit actions
-├── clients/ # External API clients (AtCoder Problems, AOJ)
-├── components/ # Svelte components
-├── constants/
-├── server/ # Server-only (auth.ts, database.ts)
-├── services/ # Business logic
-├── stores/ # Svelte stores (.svelte.ts with Runes)
-├── types/ # TypeScript types
-├── utils/ # Pure utility functions
-└── zod/ # Validation schemas
-src/features/ # Feature-scoped code (single domain)
-├── {feature}/
-│ ├── components/ # Feature UI (list/, detail/, shared/)
-│ ├── fixtures/ # Test data
-│ ├── services/ # Feature business logic (CRUD via Prisma)
-│ │ └── _.test.ts # Tests co-located next to source (not in src/test/)
-│ ├── stores/ # Feature stores
-│ ├── types/ # Feature types
-│ └── utils/ # Feature utilities
-│ └── _.test.ts # Tests co-located next to source
-src/test/ # Unit tests (mirrors src/lib/)
-e2e/ # E2E tests (Playwright)
-prisma/schema.prisma # Database schema
-```
+Lefthook runs Prettier, oxlint for JS/TS, and ESLint for Svelte before commit.
+
+## Verification and Cross-review Before a PR
+
+Every PR must pass the CI build, lint, type/Svelte check, and unit test jobs. Before handing work off, run `pnpm format`, `pnpm lint`, `pnpm check`, relevant tests, and `git diff --check`.
+
+Cross-review is required for AI-led non-trivial changes when any of these apply:
 
-## Key Conventions
+- 30 or more hand-edited source, test, or configuration files
+- Authentication, authorization, or secret handling changes
+- DB schema, migrations, or data transformations
+- Shared architecture or public interface changes
 
-- **Svelte 5 Runes**: Use `$props()`, `$state()`, `$derived()` in all new components
-- **Service layer**: Services return data or `null`; never call `error()` or `redirect()`. HTTP error translation belongs in the route handler — the service must stay framework-agnostic and unit-testable.
-- **Server data**: `+page.server.ts` → `+page.svelte` via `data` prop
-- **Forms**: Superforms + Zod validation
-- **Tests**: Write tests before implementation (TDD). Use `@quramy/prisma-fabbrica` for factories only in `prisma/seed.ts`. For service-layer unit tests, mock the DB with `vi.mock('$lib/server/database', ...)` — do not use fabbrica there. Use Nock for HTTP mocking
-- **Naming**: `camelCase` variables, `PascalCase` types/components, `snake_case` files/routes, `kebab-case` directories
-- **Pre-commit**: Lefthook runs Prettier + oxlint (JS/TS) + ESLint (.svelte only) (bypass: `LEFTHOOK=0 git commit`)
+Exclude typo-only, formatting-only, generated, lockfile, snapshot, and other trivial changes from the file count. AI review is optional for changes outside these conditions because the mechanical gate still applies. Codex-led work is reviewed with Claude; Claude-led work is reviewed with Codex. If the other agent is unavailable, use `coderabbit review --plain`. Do not fix review findings without the user's selection; prioritize Critical/Severe findings when recording them in a plan.
 
 ## References
 
-- See `package.json` for versions and scripts
-- See `prisma/schema.prisma` for database models
-- See `docs/guides/` for detailed documentation
-- See `docs/guides/architecture.md` for directory structure and colocation guide
+- `package.json`: dependency versions and scripts
+- `prisma/schema.prisma`: database models
+- `docs/guides/`: detailed project guides
diff --git a/CLAUDE.md b/CLAUDE.md
index 8d78f5789..7e6d971f0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -5,5 +5,5 @@
 ## Claude Code Specific
 
 - Path-specific rules are in `.claude/rules/`
-- Run `pnpm format` before committing
-- When uncertain about project conventions, see existing code in `src/lib/`
+- Project-specific workflows are symlinked from `.agents/skills/` into `.claude/skills/`
+- Setup details are in `docs/guides/claude-code.md`
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index df11b70c6..9dacbc83f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -68,12 +68,12 @@
 
 ### AI 支援ツール
 
-- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) - AI コーディングアシスタント（VS Code 拡張: `anthropic.claude-code`）
-  - [superpowers plugin](https://github.com/obra/superpowers) - `/writing-plans` スキルによる実装前の詳細計画生成
-  - [RTK](https://github.com/rtk-ai/rtk) - AI コーディングアシスタント向けトークン最適化プロキシ（60–90% 削減）
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code)（VS Code 拡張: `anthropic.claude-code`）
+- [Codex](https://developers.openai.com/codex/)（VS Code 拡張: `openai.chatgpt`）
+- [RTK](https://github.com/rtk-ai/rtk) - AI コーディングアシスタント向けトークン最適化プロキシ
 - [CodeRabbit](https://coderabbit.ai/) - AI コードレビュー
-  - CodeRabbit CLI (`coderabbit review --plain`) — milestone 区切りでのローカルレビュー
-  - CodeRabbit CI — PR 作成後の自動レビュー（最終品質ゲート）
+
+Claude Code と Codex は用途や利用可能な契約に応じて選択でき、同時利用は必須ではありません。共通規約は `AGENTS.md`、固有の設定は `docs/guides/claude-code.md` と `docs/guides/codex.md` を参照してください。[Superpowers plugin](https://github.com/obra/superpowers) はプロジェクトでは有効化せず、必要な場合に各自で導入します。
 
 ### ホスティング、CI・CD関連
 
@@ -160,6 +160,27 @@
    - Windows: `Ctrl + Shift + P`
 3. ローカルサーバを動作させるために必要な環境が自動的に構築され、VS Codeの拡張機能もインストールされます。
 
+#### (SSH で GitHub を利用する場合) ホスト側で鍵を ssh-agent へ登録
+
+秘密鍵はコンテナに mount せず、SSH agent forwarding でホストの `ssh-agent` に署名だけを依頼します。ホスト側で鍵が agent に載っていないと、コンテナ内の Git 操作が `Permission denied (publickey)` で失敗します。HTTPS 利用時は不要です。
+
+ホストの `~/.ssh/config` に次を書いておくと、ホストで `ssh` を使うたびに鍵が自動で agent に載ります。`IdentityFile` は実際の鍵の path に置き換えてください（`ls -la ~/.ssh/` で確認。`.pub` が付かない方が秘密鍵）。
+
+```text
+Host *
+  AddKeysToAgent yes              # ssh-add 相当を自動実行する
+  UseKeychain yes                 # macOS のみ。passphrase を Keychain から読む
+  IdentityFile ~/.ssh/id_ed25519
+```
+
+この設定が有効になるのは**ホストで `ssh` を実行したとき**だけです。コンテナ内の `ssh` はホストの設定も鍵も読まず agent に問い合わせるだけなので、ホストで一度 `ssh -T git@github.com` を実行して agent に載せてください。以降は転送済みの socket 経由でコンテナからも見えます。`ssh-agent` はホスト側のプロセスなので、**コンテナを rebuild するときには再登録不要**です。
+
+macOS では `ssh-agent` が launchd により自動起動するため、起動操作は不要です。Windows では `ssh-agent` サービスが既定で無効なため、初回だけ PowerShell で有効化します。
+
+```powershell
+Set-Service ssh-agent -StartupType Automatic; Start-Service ssh-agent
+```
+
 ### (共通) ローカルの開発サーバを起動
 
 - 新しいターミナルを開いてください。
@@ -243,11 +264,15 @@
 
   `pnpm dev`
 
-- 文法・フォーマットの確認および自動修正
+- フォーマットの自動修正と、全PRで必須の機械的検証
+
+  `pnpm format`
 
   `pnpm lint`
 
-  `pnpm format`
+  `pnpm check`
+
+  `pnpm test:unit`
 
 - アプリの製品バージョンの作成と動作確認
 
@@ -273,6 +298,8 @@
 
    `git diff origin <your-current-branch>`
 
+   CI の build、lint、check、unit test は全PRで必須です。AI 主導の非軽微な変更では、30ファイル以上の編集、認証・認可・秘密情報、DB schema・migration・データ変換、共通 architecture・公開 interface のいずれかを変更した場合に、実装した agent とは別の agent でレビューします。この条件に該当しない軽微な変更のAIレビューは任意です。別 agent を利用できない場合は `coderabbit review --plain` で代用できます。指摘は自動修正せず、対応項目を選んでから修正します。
+
 5. 本レポジトリに更新内容を反映させます。
 
    `git push origin <your-current-branch>`
@@ -311,6 +338,10 @@ pnpm exec lefthook install
 
 ### トラブルシューティング
 
+- エラー: コンテナ内の `git fetch` / `git push` が `Permission denied (publickey)` で失敗する
+  - 原因: ホストの `ssh-agent` に鍵が未登録。コンテナ内の `ssh-add -l` が `The agent has no identities` を返すかで判別できる
+  - 対処方法: ホストで `ssh -T git@github.com` を一度実行する。手順と注意点は「(SSH で GitHub を利用する場合) ホスト側で鍵を ssh-agent へ登録」を参照
+
 - エラー: ローカル環境で開発用サーバを立ち上げても、ブラウザに表示されない
   - 前提条件: Docker Desktop 4.30.0 以上、かつ、VSCode DevContainer で Vite を動かす場合。Windows、macOS で発生する
   - 原因: Dockerで、ホストが IPv4 のみを使用している場合でも、`::1` を返すようになったため
diff --git a/Dockerfile b/Dockerfile
index c8d2a968e..1264b1b27 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -7,10 +7,12 @@ WORKDIR /usr/src/app
 COPY . /usr/src/app
 
 RUN apt-get update \
-    && apt-get -y install --no-install-recommends fish
+    && apt-get -y install --no-install-recommends bubblewrap fish \
+    && chmod u+s /usr/bin/bwrap \
+    && rm -rf /var/lib/apt/lists/*
 
 ENV NODE_PATH=/node_modules
-ENV PATH=$PATH:/node_modules/.bin
+ENV PATH=/home/node/.local/bin:$PATH:/node_modules/.bin
 
 RUN pnpm install
 
diff --git a/compose.yaml b/compose.yaml
index 28e479c63..33624c0b9 100644
--- a/compose.yaml
+++ b/compose.yaml
@@ -1,6 +1,18 @@
 services:
   web:
     build: .
+    # Codex creates its narrower bubblewrap sandbox inside this development container.
+    # Keep these aligned with OpenAI's secure devcontainer requirements.
+    cap_add:
+      - NET_ADMIN
+      - SETGID
+      - SETUID
+      - SYS_ADMIN
+      - SYS_CHROOT
+      - SYS_PTRACE
+    security_opt:
+      - apparmor=unconfined
+      - seccomp=unconfined
     ports:
       - '5173:5173'
       - '5555:5555'
diff --git a/docs/guides/agent-rules/accessibility.md b/docs/guides/agent-rules/accessibility.md
new file mode 100644
index 000000000..bf39e8ea0
--- /dev/null
+++ b/docs/guides/agent-rules/accessibility.md
@@ -0,0 +1,38 @@
+---
+description: Accessibility rules for UI components
+paths:
+  - 'src/**/*.svelte'
+  - 'src/lib/components/**'
+  - 'src/features/**/components/**'
+---
+
+# Accessibility
+
+## Tables
+
+Always declare header scope:
+
+```html
+<th scope="col">Grade</th>
+<th scope="row">abc001</th>
+```
+
+## Color
+
+Never use color as the sole indicator of meaning. Grade badges and status icons must include a visible text label or `aria-label` — screen readers and users with color vision differences depend on it.
+
+## Interactive Elements
+
+Every `<button>` and `<a>` must have an accessible name: visible text, `aria-label`, or `aria-labelledby`. Icon-only buttons require `aria-label`.
+
+## Dynamic Content
+
+When `{#if}` reveals a modal, dialog, or focus-trap region, move focus programmatically on open and restore it on close.
+
+## Flowbite Svelte
+
+Icon-only `<Button>` variants require an explicit `aria-label`; Flowbite Svelte does not generate one automatically. Omitting `color` only applies the `'primary'` default style — it has no effect on `aria-label`.
+
+## Form Labels
+
+Every `<input>`, `<select>`, and `<textarea>` must have an associated `<label>` (via `for`/`id`) or `aria-label`. Placeholder text does not substitute for a label.
diff --git a/docs/guides/agent-rules/auth.md b/docs/guides/agent-rules/auth.md
new file mode 100644
index 000000000..7bcac6d04
--- /dev/null
+++ b/docs/guides/agent-rules/auth.md
@@ -0,0 +1,60 @@
+---
+description: Authentication rules
+paths:
+  - 'src/routes/(auth)/**'
+  - 'src/routes/(admin)/**'
+  - 'src/features/auth/**'
+  - 'src/features/auth/server/**'
+  - 'src/hooks.server.ts'
+---
+
+# Authentication
+
+## Self-Managed Session Auth
+
+Auth is a self-managed implementation (no external auth library), kept compatible with the retired lucia v2 so existing sessions and password hashes stay valid. See `## Key Files` for the module map.
+
+- Session validation in `src/hooks.server.ts`; session data attached to `event.locals.user`
+- User properties: `id`, `name`, `role`, `atcoder_name`, `is_validated`
+
+## Protected Routes
+
+- Validate `event.locals.user` in `+page.server.ts` load functions
+- Redirect unauthenticated users to `/login`
+- Validate `role` for admin-only routes
+
+## Form Validation
+
+- Use Superforms + Zod for auth forms
+- Server-side validation is authoritative
+- Return structured error responses
+
+## Key Files
+
+- `src/hooks.server.ts`: Global request handler
+- `src/features/auth/server/auth.ts`: `createAuthRequest` (request-scoped session handle)
+- `src/features/auth/server/session.ts` / `src/features/auth/server/password.ts`: self-managed session + password crypto (`random.ts` provides salt/session-id generation)
+- `src/features/auth/services/credentials.ts`: `registerUser` / `authenticateUser`
+- `src/features/auth/services/session_guards.ts`:
+  - `getLoggedInUser(locals, url?)` — returns logged-in user or redirects to `/login`
+  - `ensureSessionOrRedirect(locals, url?)` — guard-only; redirects if no session
+- `src/features/auth/services/admin_access.ts`:
+  - `validateAdminAccess(locals, url?)` — for page routes; redirects to `/login` for both unauthenticated and non-admin users (do not use in `+server.ts`)
+  - `validateAdminAccessForApi(locals)` — for API routes (`+server.ts`); throws `error(401)` if unauthenticated, `error(403)` if not admin
+- `src/features/auth/utils/login.ts`: `buildLoginPath(url?)` — generates `/login` or `/login?redirectTo=...`
+- `src/features/auth/utils/signup.ts`: `buildSignupPath(url?)` — generates `/signup` or `/signup?redirectTo=...` (same signature as `buildLoginPath`)
+- `prisma/schema.prisma`: User, Session, Key models
+
+## Redirect After Login Pattern
+
+After login/signup, redirect users back to their original intended page instead of hardcoding `/`.
+
+- Protected `load()`: pass `url` to `getLoggedInUser(locals, url)` — appends `?redirectTo=` automatically
+- Login/signup actions: validate `redirectTo` with `isSameOriginRedirect()` before using (see `src/lib/utils/url.ts`)
+
+## Security
+
+- Never expose session secrets in client code
+- Use HTTPS in production
+- Validate all user inputs server-side
+- **SvelteKit's `redirect()` does not validate origin** — always validate user-provided redirect destinations with `isSameOriginRedirect()`
diff --git a/docs/guides/agent-rules/coding-style.md b/docs/guides/agent-rules/coding-style.md
new file mode 100644
index 000000000..d7382a385
--- /dev/null
+++ b/docs/guides/agent-rules/coding-style.md
@@ -0,0 +1,96 @@
+<!-- No `paths` frontmatter on purpose: this rule applies to all source and plans, so it must be loaded at all times. The other rules in this directory are path-scoped. -->
+
+# Coding Style
+
+## Pre-Implementation Layer Check
+
+Before writing logic, decide which layer it belongs to:
+
+| Layer          | Directory                                   | Constraints                                             |
+| -------------- | ------------------------------------------- | ------------------------------------------------------- |
+| DB schema      | `prisma/`                                   | Migrations immutable after apply                        |
+| DB access      | `src/lib/server/`                           | Server-only; never in client                            |
+| Validation     | `src/**/zod/`                               | `z.number().int()` for Int; dual-enforce with SQL CHECK |
+| Domain types   | `src/**/types/`                             | Plural aliases; TSDoc; avoid `any`                      |
+| Test data      | `src/**/fixtures/`                          | Write before impl (TDD); realistic values               |
+| Business logic | `src/**/services/`                          | Pure values/`null`; no `Response`/`json()`              |
+| External APIs  | `src/lib/clients/` or `*/internal_clients/` | Shared → `lib`; feature-scoped → `internal_clients`     |
+| Utilities      | `src/**/utils/`                             | No side effects; adjacent unit test required            |
+| State          | `src/**/stores/`                            | `.svelte.ts`; class + `$state()`; singleton export      |
+| Route handlers | `src/routes/`                               | Page: `redirect()`; API: `error()`                      |
+| Components     | `src/**/*.svelte`                           | Svelte 5 Runes; logic → `utils/`                        |
+
+## Naming
+
+- **No abbreviations** unless standard (e.g., `id`, `url`)
+- **Lambda params**: no single-char (except `i` for loops)
+- **Function verbs**: `get` (read), `build`/`create` (construct), `calc`/`compute` (derive), `update`, `fetch`, `resolve`
+- **Domain enums**: use domain type, not `string` (validates at boundary, stays typed inside)
+- **Constants**: reflect content not purpose; extract magic numbers/strings
+- **Files**: `snake_case` in routes, `kebab-case` dirs, underscore-prefix helpers (`_utils/`, `_types/`)
+
+## Error and Type Clarity
+
+- **Braces**: always for single-statement `if` blocks.
+- **Catch blocks**: never silent; re-throw, log, or comment.
+- **Plural aliases**: `type Items = Item[]` in signatures.
+- **TSDoc**: add only when behavior or constraints are non-obvious.
+
+## Type Guards at API Boundaries
+
+When receiving enum values from external APIs, validate with a type guard:
+
+```typescript
+// Good: `isValidTaskGrade(value): value is TaskGrade`
+const grade = isValidTaskGrade(data.grade) ? data.grade : null;
+```
+
+Extract to `src/lib/utils/` with adjacent tests.
+
+## Guard Clause Reachability
+
+Ensure guard clauses don't make later code unreachable. If an early return covers all remaining cases, delete the dead code below it rather than leaving it.
+
+## Dispatcher and Handler Domains
+
+A classifier must not match more broadly than its handler accepts (`startsWith` classifier → anchored-regex handler throws on the gap). Fix both sides: tighten the classifier, and return `null` instead of throwing.
+
+## Dead Code: Three-Condition Rule
+
+Delete function only if: (1) zero callers, (2) replacement exists, (3) dependent fields also deleted.
+
+Before removing an import, grep the entire file for all usages — removing one call site doesn't mean no others exist.
+
+## Barrel Exports
+
+`index.ts` re-exports public API only. Files within the same module import each other directly — never through the barrel (circular dependency).
+
+## Residual-Reference Sweeps
+
+When removing a dependency or renaming a symbol, sweep the **whole repo**, not just `src`:
+
+- `grep --include='*.{ts,svelte,md}'` does NOT brace-expand — it silently matches nothing. Use `rg -ni 'name' -g '*.ts' -g '*.svelte' -g '*.md'` instead.
+- Include root files (CONTRIBUTING.md, README), `e2e/`, and config (`vite.config.ts`) — not only `src prisma .claude`.
+
+## Documentation
+
+- **Plans/dev-notes**: Japanese
+- **Code/commits/tests**: English
+- **TSDoc**: add when behavior, constraints, or params are non-obvious
+- **Code blocks**: specify language (`typescript`, `sql`, `bash`)
+
+## Security
+
+- No user-identifiable data in logs
+- No Prisma imports in route handlers
+- Validate input at system boundaries
+- Convert expected domain errors (e.g. Prisma `P2025`) to safe default values; re-throw unexpected service errors (see prisma-db.md Service Layer Error Handling)
+
+## Comments: Why, Not What
+
+Comment the **why** (non-obvious reason), not the **what** (code already says).
+
+- Bad: `// increment counter`
+- Good: `// use task_id as deterministic ID to avoid SSR/hydration mismatch`
+
+Keep to one line. If longer, refactor code (naming, structure) instead.
diff --git a/docs/guides/agent-rules/github-actions.md b/docs/guides/agent-rules/github-actions.md
new file mode 100644
index 000000000..54b01941d
--- /dev/null
+++ b/docs/guides/agent-rules/github-actions.md
@@ -0,0 +1,13 @@
+---
+description: GitHub Actions workflow rules
+paths:
+  - '.github/workflows/**'
+---
+
+# GitHub Actions
+
+## workflow_dispatch Requires the Default Branch
+
+The GitHub Actions UI only shows `workflow_dispatch` workflows that exist on the **default branch** (staging in this repo). A workflow file that only exists on a feature branch cannot be triggered from the UI.
+
+For one-time operational workflows (e.g. migration fixes): merge to staging first, then trigger the dispatch.
diff --git a/docs/guides/agent-rules/prisma-db.md b/docs/guides/agent-rules/prisma-db.md
new file mode 100644
index 000000000..d2b8126b9
--- /dev/null
+++ b/docs/guides/agent-rules/prisma-db.md
@@ -0,0 +1,166 @@
+---
+description: Prisma and database rules
+paths:
+  - 'prisma/**'
+  - 'src/lib/server/**'
+  - 'src/lib/services/**'
+  - 'src/features/**/services/**'
+---
+
+# Prisma & Database
+
+## Schema Changes
+
+1. Edit `prisma/schema.prisma`
+2. Run `pnpm exec prisma migrate dev --name <snake_case_description>`
+
+## Naming
+
+- Models: `PascalCase` | Fields: `camelCase` (preferred) or `snake_case` (legacy)
+
+## Server-Only Code
+
+- Import the DB client (`$lib/server/database`) only in `src/lib/server/**` and in server-only services under `src/lib/services/**` and `src/features/**/services/**`
+- Route handlers must not import the DB client directly — call service methods instead
+- Never import server-only code in client components
+
+## Service Layer
+
+- All CRUD through the service layer (`src/lib/services/` or `src/features/**/services/`)
+- Route handlers call service methods — no direct Prisma in `+server.ts` / `+page.server.ts`
+- Service functions return pure values (`{ error: string } | null`), never `Response` / `json()`
+
+## Transactions
+
+Use `prisma.$transaction()` for multi-step operations.
+
+## Parallel Queries
+
+When `+page.server.ts` `load` makes multiple independent queries, run them concurrently with `Promise.all` to reduce page load latency:
+
+```typescript
+// NG: sequential — each awaits the previous
+const workbooks = await getWorkBooksWithAuthors();
+const tasks = await getTasksByTaskId();
+const results = await getTaskResultsOnlyResultExists(userId, true);
+
+// OK: all three fire at once
+const [workbooks, tasks, results] = await Promise.all([
+  getWorkBooksWithAuthors(),
+  getTasksByTaskId(),
+  getTaskResultsOnlyResultExists(userId, true),
+]);
+```
+
+Only applies when queries are **independent** (no output of one used as input to another).
+
+## N+1 Queries
+
+Replace per-item DB calls in loops with a bulk fetch + `Map`:
+
+```typescript
+const records = await prisma.foo.findMany({ where: { id: { in: ids } } });
+const map = new Map(records.map((record) => [record.id, record]));
+```
+
+## Enum Types
+
+Prisma-generated enums and app-defined enums are distinct TypeScript types even with identical members. Keep explicit casts at the boundary — do not remove them as "redundant".
+
+## Idempotent Writes
+
+Prefer `createMany({ skipDuplicates: true })` over catching P2002 for expected unique violations (e.g., double-submit). Maps to `INSERT ... ON CONFLICT DO NOTHING`. Top-level only (not nested); PostgreSQL/CockroachDB/SQLite only.
+
+## Zod Schema for Int Fields
+
+`z.number().positive()` passes decimals. For Prisma `Int` fields default to `z.number().int()`, adding `.positive()` only where the domain explicitly requires a positive value (e.g. a 1-based `priority`) — many `Int` fields (e.g. a `count` guarded by `CHECK count >= 0`) allow zero.
+
+## Relation Filter Exclusion
+
+Filtering on a relation field (e.g. `where: { placement: { type: 'CURRICULUM' } }`) performs an INNER JOIN internally — rows without a matching relation record are automatically excluded. This is not an IS NOT NULL check; the mechanism is the JOIN.
+
+When documenting this behavior, write "excluded by INNER JOIN" rather than "implicitly includes IS NOT NULL".
+
+## FK Relations: Always Define @relation
+
+Any field that references another model's ID must have an explicit `@relation` defined. Without `@relation`, Prisma does not generate FK constraints automatically, leading to referential integrity gaps.
+
+```prisma
+// Bad: FK without @relation
+userId String
+
+// Good: explicit @relation generates FK constraint
+userId String
+user   User @relation(fields: [userId], references: [id])
+```
+
+## DB-Level Value Constraints
+
+Add `CHECK` constraints via manual migration SQL. Document with inline `schema.prisma` comments (e.g., `/// CHECK: count >= 0`). Note: `prisma generate` (via `prisma-markdown`) overwrites `ERD.md`—always keep the constraint definition in `schema.prisma` as the source of truth.
+
+## Service Layer Error Handling
+
+Catch Prisma errors in service functions, return domain values:
+
+- `P2025` (record not found) → `null` (no exception)
+- Other errors → re-throw (caller handles as 500)
+
+This removes Prisma imports from route handlers and enables easy testing with mocked returns.
+
+## Dual-Enforcement Constraints
+
+When the same constraint is enforced in both Zod (early validation) and SQL `CHECK` (last line of defense), add an inline comment stating each layer's role and the obligation to keep them in sync:
+
+```typescript
+// XOR constraint: dual enforcement via Zod (early validation) and a CHECK in migration.sql (last line of defense).
+// Prisma lacks @@check, so the SQL constraint is maintained manually. Keep both in sync.
+.refine(...)
+```
+
+## @@map and Manual Migration SQL
+
+When writing manual migration SQL for models that use `@@map`, always use the `@@map` value (the actual DB table name), not the Prisma model name. PostgreSQL treats quoted identifiers as case-sensitive, so `"VotedGradeCounter"` and `"votedgradecounter"` refer to different tables.
+
+```sql
+-- Bad: Prisma model name does not exist as a table
+ALTER TABLE "VotedGradeCounter" ADD CONSTRAINT ...
+
+-- Good: use the @@map value
+ALTER TABLE "votedgradecounter" ADD CONSTRAINT ...
+```
+
+## P3009: Recovering from a Failed Migration
+
+When a migration leaves `finished_at = NULL` in `_prisma_migrations`:
+
+**Shared environments** (staging/production, or any DB other developers also migrate):
+
+1. Keep the migration directory — other machines already have it; deleting it causes drift.
+2. Manually roll back whatever the failed migration partially applied.
+3. Mark it as rolled back: `pnpm exec prisma migrate resolve --rolled-back <name>`
+4. Create a **new migration with a new timestamp** containing the corrected SQL and deploy it.
+
+**Local-only database** (no one else depends on its migration history): reset the database (`pnpm exec prisma migrate reset`) and recreate the migration as needed.
+
+A `--rolled-back` migration is permanently skipped by `migrate deploy`; fixing the original file has no effect.
+
+## Merged Data: Document Uniqueness Loss
+
+Service functions that merge records from multiple sources (e.g., `getMergedTasksMap()` combining base tasks + `ContestTaskPair` entries) lose individual field uniqueness. Document that results contain duplicates in "unique" DB fields.
+
+Example: `getMergedTasksMap()` returns multiple entries with same `task_id` but different `contest_id` — callers must not assume `task_id` is unique. UI layer must use composite keys (see svelte-components.md `{#each}` patterns).
+
+## Validate Constraints
+
+Prisma does not support `@@check`. To add one:
+
+1. `pnpm exec prisma migrate dev --create-only --name <description>` — generate migration without applying
+2. Edit the generated `migration.sql` to add the CHECK constraint manually
+3. Add an inline comment in `schema.prisma` (e.g., `/// CHECK: constraint description`)
+4. `pnpm exec prisma migrate dev` — apply
+
+For visibility, also document complex constraints in `prisma/ERD.md`:
+
+```mermaid
+%% XOR constraint: workbookplacement_xor_grade_category — exactly one of taskGrade or solutionCategory must be non-null
+```
diff --git a/docs/guides/agent-rules/server-cache.md b/docs/guides/agent-rules/server-cache.md
new file mode 100644
index 000000000..f52599379
--- /dev/null
+++ b/docs/guides/agent-rules/server-cache.md
@@ -0,0 +1,98 @@
+---
+description: Server-side caching rules
+paths:
+  - 'src/lib/clients/cache.ts'
+  - 'src/lib/server/**/cache.ts'
+  - 'src/features/**/server/cache.ts'
+---
+
+# Server-Side Cache
+
+## Core Pattern: `Cache<T>.getOrFetch()`
+
+Use `cache.getOrFetch(key, fetchFn)` for all get-or-fetch operations. Never inline the get/set/if pattern manually — it duplicates logic that `getOrFetch` already provides.
+
+```typescript
+export function getCachedFoo(fetchFn: () => Promise<Foo>): Promise<Foo> {
+  return fooCache.getOrFetch(KEY, fetchFn);
+}
+```
+
+## Domain Cache Module Structure
+
+Place cache modules at `server/cache.ts` within each domain:
+
+| Domain  | Path                                  |
+| ------- | ------------------------------------- |
+| Shared  | `src/lib/server/{domain}/cache.ts`    |
+| Feature | `src/features/{name}/server/cache.ts` |
+
+Each module exports:
+
+- `getCached*()` — thin wrapper around `cache.getOrFetch()`
+- `invalidate*Caches()` — clears all related cache instances
+- `dispose*Caches()` — disposes all related cache instances (for test cleanup)
+
+## Invalidation Rules
+
+- Call `invalidate*Caches()` immediately after the DB write (`create`, `update`, `delete`) succeeds — not before, not in a `finally` block.
+- Group related caches in a single invalidation function (e.g., `invalidateTaskCaches()` clears both `tasksCache` and `mergedTasksCache`).
+- Never invalidate from route handlers — invalidation belongs in the service layer, co-located with the write operation.
+
+## TTL Guidelines
+
+| Data characteristics           | TTL        |
+| ------------------------------ | ---------- |
+| Rarely changes (tasks, grades) | 1 hour     |
+| Moderately changes (votes)     | 10 minutes |
+
+Adjust based on production metrics after deployment.
+
+## Testing
+
+Core cache behavior (hit, miss, TTL, error propagation) is tested on `Cache<T>.getOrFetch()` in `src/lib/clients/cache.test.ts`. Domain cache tests cover only domain-specific concerns:
+
+- **Wiring**: wrapper delegates correctly and returns cached value on subsequent calls
+- **Key isolation**: different parameters produce different cache keys (e.g., `buildPlacementKey`)
+- **Invalidation grouping**: `invalidate*()` clears all related caches
+
+Do not duplicate TTL or error propagation tests in domain cache test files.
+
+Always call `afterAll(() => dispose*Caches())` to prevent timer leaks. Isolate tests with `beforeEach(() => invalidate*Caches())`.
+
+## Type Constraint
+
+`Cache<T extends {}>` — never use `null` or `undefined` as `T`. The cache uses `=== undefined` to detect misses; storing `undefined` would silently bypass the cache on every call.
+
+## Stampede Prevention
+
+`Cache<T>.getOrFetch()` shares a single in-flight `Promise` across concurrent callers for the same key. Do not implement manual dedup on top of it.
+
+## Invalidation Audit
+
+When adding a new DB write function, audit every write path in the same domain for missing `invalidate*Caches()` calls. Initial implementation of `upsertVoteGradeTables()` missed this and served stale data for up to 10 minutes.
+
+## Service Layer Integration
+
+Services call `getCached*()` with a `fetchFn` that performs the DB query. The service does not import `Cache` directly.
+
+```typescript
+// In service file
+import { getCachedTasksMap } from '$lib/server/tasks/cache';
+
+export async function getTasksByTaskId(): Promise<Map<string, Task>> {
+  return getCachedTasksMap(async () => {
+    const tasks = await db.task.findMany();
+    return new Map(tasks.map((task) => [task.task_id, task]));
+  });
+}
+```
+
+Mock cache in service tests to bypass caching:
+
+```typescript
+vi.mock('$lib/server/tasks/cache', () => ({
+  getCachedTasksMap: (fetchFn: () => Promise<unknown>) => fetchFn(),
+  invalidateTaskCaches: vi.fn(),
+}));
+```
diff --git a/docs/guides/agent-rules/svelte-components.md b/docs/guides/agent-rules/svelte-components.md
new file mode 100644
index 000000000..f7093edc3
--- /dev/null
+++ b/docs/guides/agent-rules/svelte-components.md
@@ -0,0 +1,112 @@
+---
+description: Svelte component development rules
+paths:
+  - 'src/**/*.svelte'
+  - 'src/lib/components/**'
+  - 'src/lib/stores/**/*.svelte.ts'
+---
+
+# Svelte Components
+
+## Runes (Required)
+
+Use `$props()`, `$state()`, `$derived()`, `$effect()` in all components:
+
+```svelte
+<script lang="ts">
+  interface Props {
+    title: string;
+    count?: number;
+  }
+  let { title, count = 0 }: Props = $props();
+</script>
+```
+
+## File Naming
+
+- Components: `PascalCase.svelte`
+- Stores: `snake_case.svelte.ts`; class-based with `$state()`, singleton export
+
+## Props & Reactivity
+
+- Pass **model objects**, not individual fields; derive computed values inside
+- For `data.*` in `+page.svelte`: use `$derived` to sync after `load()` re-runs
+- Use `$derived` for computed values over `$state` + `$effect`
+- Capture state **before** first `await` for safe rollback
+
+## `{#each}` Patterns
+
+- Always key: `(item.id)` or `(i)`
+- **Key MUST be unique per iteration** — if domain allows duplicates, use composite key (e.g. `contest_id + '-' + task_id`)
+- `(i)` is only safe when the list's order and length never change (e.g. a fixed split of a string into lines). For a mutable list — reorderable, insertable, or deletable — use a persistent unique ID or composite key; `(i)` there causes Svelte to reuse DOM/state across the wrong items after a mutation.
+- Filter **before**, not inside with `{#if}`
+- Use `{:else}` for empty lists
+
+```svelte
+{#each visibleItems as item (item.id)}
+  <Row {item} />
+{:else}
+  <p>No items.</p>
+{/each}
+```
+
+**Common Trap:** `task_id` alone is NOT unique when same task appears in multiple contests. Use `contest_id + '-' + task_id` as composite key (see issue #3460 & PR #3442).
+
+## Snippets vs Components
+
+- **Snippet**: needs `$state` access, pure display, same-file; params require explicit type `{#snippet label(item: Item)}`
+- **Component**: independent logic, >30 lines, multi-file reuse
+- Define snippets at **top level** (outside tags)
+
+**Context trap:** Snippets capture context at definition site, not render site. Never define a snippet outside a context provider (e.g. `<Tabs>`) and `{@render}` it inside — `TabItem` calls `getContext` on init and throws during HMR when `<Tabs>` is not in its ancestor chain. Place children directly inside the provider.
+
+## Async/Abort Handling
+
+When user can trigger same action multiple times, use `AbortController`:
+
+1. New abort on each submission: `voteAbortController?.abort(); voteAbortController = new AbortController()`
+2. Pass signal to fetches: `fetchMedian(taskId, signal)`
+3. Validate `signal?.aborted` in `.then()` to silently drop intentional aborts
+
+## SSR Safety
+
+- No `crypto.randomUUID()` or `Math.random()` at component init (hydration mismatch)
+- Derive IDs deterministically: `const id = item.task_id`
+- Browser APIs: check `globalThis.location?.origin` before `browser` flag; warn only as last resort
+
+## Flowbite Svelte
+
+Import from `flowbite-svelte`. Use Tailwind v4 `dark:` prefix. When copying button styles, check `color`, `size`, `class`. Omitting `color` applies Flowbite's filled blue default.
+
+`ButtonGroup` uses `flex` internally (no wrap). For wrapping, use `<div class="flex flex-wrap gap-1">` with individual `Button` components.
+
+## Component Structure
+
+- Extract conditional logic to private functions: `function isCrossRouteNavigation() { ... }`
+- Move business logic to `_utils/` or `utils/` with tests
+- Keep components thin: one responsibility
+
+## `{@const}` Placement Restriction
+
+`{@const}` is only valid as the immediate child of a control-flow block (`{#if}`, `{#each}`, `{:else}`, etc.) — placing it at the template top level is a compile error.
+
+When you need a derived value in both a `{#if}` condition and its body, declare it with `$derived` in `<script>` instead:
+
+```typescript
+// ✅ in <script>
+let groupMetadata = $derived(store?.getMetadata());
+```
+
+```svelte
+{#if groupMetadata?.title}
+  <Heading>{groupMetadata.title}</Heading>
+{/if}
+```
+
+This also avoids calling the getter twice per render.
+
+## Reactive Data Pitfalls
+
+- `let` captures initial value only; use `$derived` for derived/prop data
+- Inside `$effect`, use `$store` syntax, not `get(store)` (bypasses reactivity)
+- `$derived.by(() => { ... })` for multi-statement logic
diff --git a/docs/guides/agent-rules/svelte-runes.md b/docs/guides/agent-rules/svelte-runes.md
new file mode 100644
index 000000000..bfea707a0
--- /dev/null
+++ b/docs/guides/agent-rules/svelte-runes.md
@@ -0,0 +1,64 @@
+---
+description: Svelte 5 Runes and reactivity rules
+paths:
+  - 'src/**/*.svelte'
+  - 'src/lib/stores/**/*.svelte.ts'
+  - 'src/features/**/stores/**'
+---
+
+# Svelte Runes & Reactivity
+
+## `$state()` & `$props()`
+
+- `let` captures initial value only; use `$derived` for props/server data
+- Referencing `$props()` in `$state()` initializer? Wrap with `untrack` if intentional (seed-only)
+- `pnpm check` warns: "This reference only captures the initial value"
+
+## `SvelteMap<K, V>` — Always Type
+
+`SvelteMap` without type params makes `.get()` return `unknown`. Always declare:
+
+```typescript
+const map = new SvelteMap<TaskGrade, TaskResults>();
+```
+
+`$state()` wrapping unnecessary — `SvelteMap` is reactive. Reset with `.clear()` not reassign.
+
+Inside `$derived`, plain `new Map()` suffices — reactive dependency tracked at `$derived` level.
+
+## `$derived` & `$effect`
+
+- Prefer `$derived` over `$state` + `$effect` for computed values
+- No arrow functions: `$derived(() => fn(x))` stores the function, doesn't call it
+- Use `.by()` for multi-statement: `$derived.by(() => { ... })`
+- Inside `$effect`, use `$store` syntax, not `get(store)` (bypasses signal graph)
+
+## `$derived` Tracks Reactive Reads Inside Called Functions
+
+`$derived(fn)` tracks every reactive read inside `fn`, **including reads inside helper functions** called by `fn`. If a helper reads a `$state` array, the derived re-runs whenever that array changes.
+
+**Accumulation trap**: if the helper transforms data (e.g. `{ ...item, title: prefix + item.title }`) and the result is later written back to the source array (optimistic update), the next re-run reads the already-transformed value and transforms it again.
+
+Fix: put display formatting only in the leaf view (e.g. `$derived displayTitle` in a cell component), never inside a derived that feeds mutable state.
+
+## Optimistic Updates
+
+Derive computed fields from canonical data source, not re-implement inline. Divergence → "works after reload" bugs.
+
+Diagnostic: "Not reflected live, but fixed after reload" → check optimistic update payload.
+
+## Async Rollback
+
+Capture state **before** first `await`:
+
+```typescript
+const previous = items;
+
+try {
+  await saveToServer(items);
+} catch {
+  items = previous;
+}
+```
+
+Concurrent updates can overwrite variable while awaiting; capturing prevents data loss.
diff --git a/docs/guides/agent-rules/sveltekit.md b/docs/guides/agent-rules/sveltekit.md
new file mode 100644
index 000000000..4335aae94
--- /dev/null
+++ b/docs/guides/agent-rules/sveltekit.md
@@ -0,0 +1,133 @@
+---
+description: SvelteKit routing and navigation patterns
+paths:
+  - 'src/routes/**'
+  - 'src/**/*.svelte'
+---
+
+# SvelteKit Patterns
+
+## Routes vs API Endpoints
+
+- Page routes: use `redirect()` to navigate
+- API routes (`+server.ts`): use `error()` — `redirect()` returns 3xx; `fetch` follows and gets HTML not JSON
+
+## User-Provided Redirect Destinations
+
+**SvelteKit's `redirect()` does NOT validate origin.** If the redirect destination comes from user input (URL query params, form data), always validate with `isSameOriginRedirect(redirectTo, url.origin)` from `src/lib/utils/url.ts` before redirecting.
+
+## Internal Navigation: `resolve()`
+
+All internal navigation must use `resolve()` from `$app/paths`:
+
+- **Parameterized** (preferred): `resolve('/workbooks/[slug]', { slug: workbook.slug })`
+- **Static**: `resolve('/')` + `@ts-expect-error` (AppTypes merging quirk)
+- **With search/hash**: `resolve(pathname + search + hash)` (concatenate inside, not outside)
+- **External**: no `resolve()`, use `rel="noreferrer external"`
+
+## HTTP Cache Headers (`setHeaders`)
+
+**Never set `s-maxage` / `stale-while-revalidate` on a route whose content varies by session.** Shared caches key on URL + method + the headers named by `Vary` (RFC 9111), so without `Vary: Cookie` an anonymous response is served to logged-in users (#3862).
+
+- Setting the header only when logged out controls the write side, not delivery of an already-cached entry to a request with a session cookie.
+- `Vary: Cookie` matches the whole header; with `_ga` present every returning visitor gets a unique key and the cache barely hits.
+- The absence of `s-maxage` is not proof a shared cache won't store the response — RFC 9111 allows heuristic freshness without explicit directives. For session-dependent routes, set `private` or `no-store` explicitly rather than relying on omission; skip them only when the response genuinely doesn't depend on session.
+- Estimate the saved invocations first. At this site's traffic the `/problems` header saved single-digit dollars a month and cost two weeks of a production bug.
+
+## Form Data Validation
+
+`formData.get()` returns `string | File | null`. Always validate before casting:
+
+```typescript
+// Bad: unsafe cast, null reaches DB layer
+const taskId = data.get('taskId') as string;
+
+// Good: validate first
+const taskId = data.get('taskId');
+
+if (typeof taskId !== 'string' || !taskId) return fail(...);
+```
+
+For enum fields:
+
+```typescript
+const gradeRaw = data.get('grade');
+
+if (!(Object.values(TaskGrade) as string[]).includes(gradeRaw)) {
+  return fail(BAD_REQUEST, { message: 'Invalid grade.' });
+}
+
+const grade = gradeRaw as TaskGrade; // Safe now
+```
+
+## Form Actions: `url` Parameter
+
+Form action handlers receive the full `RequestEvent`, including `url`. Destructure it directly:
+
+```typescript
+export const actions = {
+  default: async ({ request, locals, url }) => {
+    const redirectTo = url.searchParams.get('redirectTo');
+  },
+};
+```
+
+`url` is guaranteed non-null. `new URL(request.url)` is an equivalent alternative but unnecessary when `url` is already available.
+
+## Page Component Props
+
+`+page.svelte` accepts only `data` and `form` props (`svelte/valid-prop-names-in-kit-pages`).
+
+## load() Return Structure
+
+Group domain model fields as objects with defaults absorbed at boundary:
+
+```typescript
+// Bad: scattered fields
+export async function load() {
+  return {
+    username: user?.name ?? '',
+    atcoderHandle: user?.atCoder?.handle ?? '',
+    isValidated: user?.atCoder?.isValidated ?? false,
+  };
+}
+
+// Good: grouped by model
+export async function load() {
+  return {
+    username: user?.name ?? '',
+    atCoderAccount: {
+      handle: user?.atCoder?.handle ?? '',
+      isValidated: user?.atCoder?.isValidated ?? false,
+    },
+  };
+}
+```
+
+Consume with `$derived` in `+page.svelte` to sync after `load()` re-runs.
+
+## Error Handling in load()
+
+All async operations must be inside the try-catch block, not before it. Errors from async calls outside propagate unhandled.
+
+**Exception:** Functions that throw `redirect()` or `error()` as control flow must be placed **before** the try-catch. A bare `catch` swallows them, silently disabling redirects and error responses.
+
+## Auth Audit
+
+When protecting one action (in `load()` or form actions), audit all others. Asymmetric guards are a critical vulnerability.
+
+## success Flag & message Consistency
+
+When action returns `success: false`, `message` and `message_type` must reflect failure. Contradicting flags are silent bugs:
+
+```typescript
+// Bad: success contradicts message
+return { success: true, message: 'Failed to save' };
+
+// Good
+return { success: false, message: 'Failed to save' };
+```
+
+## navigating State
+
+`navigating` from `$app/state` always exists (never null). Check idle: `navigating.from === null`. For cross-route navigation only: compare `navigating.from.route.id` with `navigating.to?.route.id` (same-route param changes have equal ids).
diff --git a/docs/guides/agent-rules/testing-e2e.md b/docs/guides/agent-rules/testing-e2e.md
new file mode 100644
index 000000000..f61df69eb
--- /dev/null
+++ b/docs/guides/agent-rules/testing-e2e.md
@@ -0,0 +1,152 @@
+---
+description: E2E testing rules and patterns (Playwright)
+paths:
+  - '**/*.spec.ts'
+  - 'e2e/**'
+---
+
+# E2E Tests (Playwright)
+
+## Setup
+
+- File extension: **must** be `.spec.ts` (`.test.ts` not detected by `playwright.config.ts`)
+- No path aliases (`$lib`, `$features` not resolved outside SvelteKit). Use type-only imports for types:
+
+```typescript
+// Bad: runtime import fails in E2E
+import { TAB_SOLUTION } from '$features/workbooks/types/workbook';
+
+// Good: type-only import + local constant
+import type { WorkBookTab } from '$features/workbooks/types/workbook';
+
+const TAB_SOLUTION: WorkBookTab = 'solution';
+```
+
+## Describe Hierarchy
+
+Split large `describe` blocks by behavioral dimension, not flat `test()` calls:
+
+```typescript
+test.describe('logged-in user', () => {
+  test.describe('tab visibility', () => { ... });
+  test.describe('URL parameters', () => { ... });
+  test.describe('navigation', () => { ... });
+});
+```
+
+## Parameterized Tests
+
+Playwright has no native `test.each`. Use `for...of` loops (official pattern):
+
+**Single test with loop** — testing a sequence within one test:
+
+```typescript
+const GRADES = ['Q10', 'Q9', 'Q8'] as const;
+
+for (const grade of GRADES) {
+  await gradeButton(page, grade).click();
+  await expect(page).toHaveURL(`?grades=${grade}`);
+}
+```
+
+**Multiple tests from parameters** — independent cases:
+
+```typescript
+for (const grade of GRADES) {
+  test(`filters by ${grade}`, async ({ page }) => {
+    await page.goto('/tasks');
+    await gradeButton(page, grade).click();
+    await expect(page).toHaveURL(`?grades=${grade}`);
+  });
+}
+```
+
+## Selectors & Assertions
+
+### Stable Selectors
+
+Prefer in order:
+
+1. Semantic: `getByRole('button', { name: /submit/i })`
+2. Test IDs: `getByTestId('save-button')`
+3. Avoid CSS classes (refactor-fragile) and internal text unless content is stable
+
+### Assertion Best Practices
+
+- After interaction (click tab, toggle), assert **new state** not just visibility
+- Assert via accessibility attributes (`aria-pressed`, `aria-selected`, `data-*`), not CSS classes
+- `toBeVisible()` may have been true before; assert the change instead:
+
+  ```typescript
+  // Bad: doesn't confirm interaction changed state
+  await tab.click();
+  await expect(content).toBeVisible();
+
+  // Good: asserts content became visible
+  await tab.click();
+  await expect(page).toHaveURL('?tab=details');
+  ```
+
+## Setup & Teardown
+
+- Use `test.beforeEach` / `test.afterEach` for per-test setup
+- Use `test.describe.configure({ mode: 'parallel' })` for parallelization within a describe block
+- Clean up auth state / fixtures after each test (`test.afterEach(() => { ... })`)
+
+## Debugging
+
+- `page.screenshot()` to capture state at assertion
+- `page.pause()` for interactive debugging
+- Logs: `page.on('console', msg => console.log(msg.text()))`
+
+## Multi-Route Infrastructure Changes: Test Ordering
+
+When implementing infrastructure changes that span multiple routes (e.g., redirect behavior, auth flow), write E2E tests **after** the core mechanism is implemented but **before** applying it to all routes:
+
+1. **Implement core mechanism** (unit-tested) — e.g., `isSameOriginRedirect()`, `redirect()` logic
+2. **Write E2E tests** (RED state) — tests fail until all routes are updated
+3. **Apply to all routes** (GREEN state) — update each load/action function to use the mechanism
+
+**Why this order?**
+
+- If you write E2E tests before the mechanism exists, they'll fail immediately and block progress
+- E2E tests verify integration end-to-end; unit tests verify the building blocks
+- The RED→GREEN cycle for E2E tests spans multiple phases, unlike unit tests which turn GREEN immediately
+
+**Example:** Redirect After Login pattern
+
+- Phase 1-2: Unit test `isSameOriginRedirect()` (GREEN)
+- Phase 3-4: Unit test auth helpers (GREEN)
+- Phase 5-6: Implement login/signup actions (GREEN)
+- Phase 7: Write E2E tests for all routes (RED)
+- Phase 8-9: Update all load functions to pass `url` (GREEN)
+
+## Testing Form Action Access Control
+
+Use `page.evaluate(async (url) => fetch(url, { method: 'POST', ... }))` — not `page.request.post()` — to test form action security. In practice, `page.request.post()` fails to carry the session (cookies or `origin` header are not sent as expected), causing auth guards to redirect even for logged-in users.
+
+SvelteKit's response format for form actions differs by outcome:
+
+- `redirect()` → HTTP 200 + JSON body `{"type":"redirect","status":307,"location":"..."}`
+- `error(N)` → HTTP status N
+
+Parse the response body with a typed deserialize helper — not raw `JSON.parse`. `$app/forms` (`deserialize`) is not resolvable outside SvelteKit, so define a local `ActionResultLike` type and a `deserializeActionResult(text)` wrapper in the E2E helper (see `e2e/workbook_edit.spec.ts` for reference). Assert `type` and `location` from the deserialized result for redirect checks, and `response.status` for error checks.
+
+## E2E Lessons from Votes Tests
+
+Recent fixes (detailed in plan.md):
+
+- Dropdown selectors drift when UI changes; re-verify on refactors
+- Abort signal prevents stale response race; update signal if fetch signature changes
+- Toast messages are temporary; use waiter pattern, not fixed delay
+
+## Timeout: Element Not Found
+
+When `page.locator()` or `getByRole()` times out:
+
+1. Verify element exists in DevTools
+2. Check ARIA roles in component UI libraries often lack semantic role definitions
+3. If `role="menuitem"` fails: use href pattern or functional marker instead (e.g., `a[href^="/login?redirectTo"]` vs navbar's `/login`)
+4. Never use `.first()` / `.last()` (DOM order is unstable)
+
+**Example:** `getByRole('menuitem')` times out because DropdownItem renders as `<li><a>` without the role. Use `a[href^="/login?redirectTo"]` to distinguish dropdown from navbar.
diff --git a/docs/guides/agent-rules/testing.md b/docs/guides/agent-rules/testing.md
new file mode 100644
index 000000000..85ecca23e
--- /dev/null
+++ b/docs/guides/agent-rules/testing.md
@@ -0,0 +1,163 @@
+---
+description: Testing rules and patterns
+paths:
+  - '**/*.test.ts'
+  - 'src/test/**'
+---
+
+# Testing
+
+## Principles
+
+- **Tests ship with implementation** — same commit; feature not done until tests pass. Never defer tests for non-trivial logic
+- **English only** — describe expected behavior (e.g., `'returns empty array when workbooks is empty'`)
+- **Test integrity** — never weaken assertions to make tests pass; fix implementation instead. Never let the expected value be computed by the code under test: `expect(f(x)).toBe(map.get(expected))` where `f` is `map.get(classify(x))`, or a fixture whose `expected` calls a production function. Both pass unconditionally. Expected values are literals
+- **Unused imports** — signal missing tests, not dead code — add the test case first
+- **TDD exceptions** — skip test-first for exploratory spikes, type-only changes, and config files with no branching logic
+- **Component testing** — extract logic to `utils/`; omit component Vitest if template-only **and** E2E covers rendering paths
+- **Coverage** — cover happy path, error cases, and domain edge cases of the input values (empty arrays, null, enum extremes); for registry coverage see Assertions & Structure. Treat low coverage as a signal to review, not a target
+
+## File Layout & Environment
+
+| Type | Tool       | Location                  | Command          |
+| ---- | ---------- | ------------------------- | ---------------- |
+| Unit | Vitest     | `src/test/` or co-located | `pnpm test:unit` |
+| E2E  | Playwright | `e2e/`                    | `pnpm test:e2e`  |
+
+- E2E files **must** use `.spec.ts` (`.test.ts` not detected)
+- Route unit tests: name `page_server.test.ts`, never `+page.server.test.ts` (SvelteKit reserves `+` prefix)
+- Both centralized (`src/test/`) and co-located (`src/features/`, `src/lib/`) test locations are supported — see `vite.config.ts` `include`
+
+**Environment:** Default `node`. Only opt in to jsdom (`// @vitest-environment jsdom` at file top) when touching `window` / `document` / `localStorage`. Never set jsdom globally — per-file construction is ~5.5× slower.
+
+## Assertions & Structure
+
+- `toBe(true)` / `toBe(false)`, not `toBeTruthy()` / `toBeFalsy()`
+- DB query tests: assert `orderBy`, `include` with `expect.objectContaining`, not just `where`
+- Enum membership: `Object.hasOwn(Enum, value)`, not `in` (avoids prototype chain)
+- `Promise<void>`: use `await fn()` to assert no throw, or `.resolves.toBeUndefined()`. **Never** bare `.resolves` (false-positive)
+- **Stubs**: parameter types must match production signature — use domain types (`TaskGrade`), not `string`
+- **Test data**: realistic values (real task IDs, grade names). Extract shared fixtures to file/describe scope; inline for single-use
+- **Registry exhaustiveness**: `Record<string, T>` and `new Map([...])` give no compile-time enum coverage — assert it at runtime, with a named, commented exception list so deliberate gaps stay documented: `expect(Object.values(Enum).filter((key) => !REGISTRY.has(key))).toEqual(KNOWN_GAPS)` (`Record` registries: swap `REGISTRY.has(key)` for the `Object.hasOwn` form above)
+- **Test count as a proxy**: after a file split, compare counts (`--reporter=verbose`) — a drop means a describe block was lost in the move. A deliberate drop is valid only when mutation analysis shows detection is unchanged; record the evidence in the commit
+
+Group by scenario, not flat:
+
+```typescript
+describe('validate', () => {
+  describe('successful case', () => { ... });
+  describe('error cases', () => {
+    describe('returns false', () => { ... });
+    describe('throws', () => { ... });
+  });
+});
+```
+
+Parameterized: test enum boundaries + typical value, then separate test for distinct behavior:
+
+```typescript
+test.each([TaskGrade.PENDING, TaskGrade.Q11, TaskGrade.Q10, TaskGrade.D6])(
+  'returns grade %s', (grade) => { ... }
+);
+```
+
+## Mocking
+
+### Cleanup (Vitest v5)
+
+- Vitest defaults `clearMocks` to `true`, so **never add `vi.clearAllMocks()`**. Clearing resets call history only; `mockResolvedValue` / `vi.when()` implementations persist, so each test must set the behavior it needs.
+- `restoreMocks` still defaults to `false`; use `vi.restoreAllMocks()` for `vi.spyOn` when needed.
+
+### Service Layer (Prisma)
+
+Mock with `vi.mock('$lib/server/database', ...)`. Use helpers:
+
+```typescript
+const mockFindUnique = (data) => db.task.findUnique.mockResolvedValue(data);
+```
+
+When the same mock is called with different arguments in one test, use `vi.when()` instead of `mockResolvedValueOnce` chains:
+
+```typescript
+vi.when(vi.mocked(prisma.workBook.findMany))
+  .calledWith(
+    expect.objectContaining({
+      where: expect.objectContaining({ workBookType: WorkBookType.CURRICULUM }),
+    }),
+  )
+  .thenResolve(curriculumRows);
+```
+
+### Cache Modules
+
+```typescript
+afterAll(() => disposeDomainCaches());
+beforeEach(() => invalidateDomainCaches());
+
+// Bypass caching in service tests:
+vi.mock('$lib/server/tasks/cache', () => ({
+  getCachedTasksMap: (fetchFn: () => Promise<unknown>) => fetchFn(),
+  invalidateTaskCaches: vi.fn(),
+}));
+```
+
+### HTTP (Nock)
+
+Extract setup into helpers at describe scope:
+
+```typescript
+const mockGetUser = (statusCode, user?) => {
+  nock('http://localhost')
+    .get('/api/user')
+    .reply(statusCode, user ? { user } : undefined);
+};
+```
+
+### Environment Variables
+
+Use `vi.stubEnv()` + `vi.unstubAllEnvs()` in `afterEach`.
+
+### globalThis / Mutable Exports
+
+Save and restore `globalThis` state via `Object.defineProperty` in `beforeEach`/`afterEach`.
+
+For mutable module-level `const` objects (override maps), mutate directly in `beforeEach`/`afterEach` — no `vi.mock` needed.
+
+## SvelteKit-Specific
+
+### Browser Toggle per Describe
+
+**Never register `vi.mock('$app/environment')` twice in one file** — the second hoisted call silently overwrites the first, pinning the whole file to one value. Use one dynamic mock with a `vi.hoisted` flag:
+
+```typescript
+// @vitest-environment jsdom
+const browserState = vi.hoisted(() => ({ value: false }));
+vi.mock('$app/environment', () => ({
+  get browser() {
+    return browserState.value;
+  },
+}));
+
+// In browser describe: browserState.value = true; construct fresh instance
+// In SSR describe: browserState.value = false
+```
+
+**Never assert a browser branch on the import-time singleton** — it is always constructed in SSR mode. Construct a fresh instance inside the browser `describe`.
+
+In jsdom files, use jsdom's real `Storage` and assert state (`localStorage.getItem(key)`), not spy calls. Cover SSR guards separately:
+
+- **read guard**: pre-seed localStorage, construct store, expect the default
+- **write guard**: empty localStorage, call setter, expect `getItem(key)` still null
+
+### Route load() Tests
+
+Call `load` directly with a mock event. Pass `setHeaders` as `vi.fn()` to assert header behavior. Wire assertions cannot be verified in unit tests — cover in E2E.
+
+```typescript
+const createMockEvent = ({ session = null } = {}) =>
+  ({
+    locals: { auth: { validate: vi.fn().mockResolvedValue(session) } },
+    url: { searchParams: { get: vi.fn().mockReturnValue(null) } },
+    setHeaders: vi.fn(),
+  }) as unknown as Parameters<typeof load>[0] & { setHeaders: ReturnType<typeof vi.fn> };
+```
diff --git a/docs/guides/architecture.md b/docs/guides/architecture.md
index 88710bb36..eb652fa4f 100644
--- a/docs/guides/architecture.md
+++ b/docs/guides/architecture.md
@@ -1,253 +1,170 @@
 # アーキテクチャガイド
 
-## 1. 3層ディレクトリモデル
+この文書では、実装済みの構成と将来案を分けて記載する。配置判断では「現在の構成・規約」を正とし、「将来案・未実装」は新規タスクの承認なしに適用しない。
 
-コードの配置先を **routes / features / lib** の3層で判断する。
+## 現在の構成・規約
+
+### 1. routes / features / lib
+
+コードの配置先は、責務と利用範囲で判断する。
 
 ```text
 src/
-├── routes/      # ルート定義。薄く保つ
-├── features/    # 機能スコープのコード（1つの機能ドメインに閉じるもの）
-└── lib/         # 真に共通のコード（2つ以上の機能から使われるもの）
+├── routes/      # SvelteKit の route と HTTP 境界
+├── features/    # 1つの機能ドメインに閉じるコード
+└── lib/         # 2つ以上の機能から使う共通コード
 ```
 
-### 判定基準
-
 ```text
-このコードはどの機能ドメインで使われるか？
-│
-├── 1つの機能ドメインに属する
-│   → features/{feature}/ に配置
-│
-└── 複数の機能ドメインで使う
-    → lib/ に配置
+SvelteKit の route 自体か？
+├── yes → routes/
+└── no
+    ├── 1つの機能ドメインだけで使う → features/{feature}/
+    └── 2つ以上の機能で使う       → lib/
 ```
 
-`routes/` にはルーティングファイル（`+page.svelte`, `+page.server.ts`, `+layout.svelte` 等）のみ置く。
-
-**例:**
-
-- `WorkBookForm.svelte` → workbooks ドメイン → `features/workbooks/`
-- `TaskTable.svelte` → tasks ドメイン（problems ページで表示） → `features/tasks/`
-- `GradeLabel.svelte` → problems・workbooks・admin で使う → `lib/components/`
-- `UserService` → auth・admin・users で使う → `lib/server/services/`
-
----
+- `features/` から `lib/` への参照は許可する。
+- `features/A/` から `features/B/` は参照しない。共通化が必要なら `lib/` へ移す。
+- `routes/` から `features/` と `lib/` への参照は許可する。
+- route は認証・入力・HTTP 応答の変換を担当し、ビジネスロジックを持たない。
 
-## 2. src/features/ の構造
-
-feature ディレクトリの内部は技術スタックベースで整理する。`components/` はページ単位でサブディレクトリに分割し、テストはファイル隣接で配置する。
+### 2. 実装済み feature
 
 ```text
 src/features/
-├── workbooks/
-│   ├── components/
-│   │   ├── list/                    # 一覧ページ
-│   │   │   ├── WorkBookList.svelte
-│   │   │   ├── WorkBookList.test.ts
-│   │   │   └── WorkBookBaseTable.svelte
-│   │   ├── detail/                  # 詳細ページ
-│   │   │   ├── CommentAndHint.svelte
-│   │   │   └── PublicationStatusLabel.svelte
-│   │   └── shared/                  # feature 内で複数ページから使うもの
-│   │       ├── WorkBookForm.svelte
-│   │       ├── WorkBookForm.test.ts
-│   │       └── WorkBookInputFields.svelte
-│   ├── fixtures/                    # テスト用データ
+├── account/
+│   ├── components/{delete,settings}/
+│   └── services/
+├── auth/
+│   ├── server/
 │   ├── services/
-│   │   ├── workbooks.ts
-│   │   ├── workbooks.test.ts
-│   │   ├── workbook_placements.ts   # WorkBookPlacement の取得・更新・新規の問題集を追加
-│   │   └── workbook_placements.test.ts
-│   ├── stores/
-│   │   └── active_workbook_tab.ts
-│   ├── types/
-│   │   └── workbook.ts
 │   └── utils/
-│       ├── workbook.ts
-│       └── workbook.test.ts
 ├── tasks/
+│   ├── components/contest-table/
+│   ├── fixtures/contest-table/
+│   ├── stores/
+│   ├── types/contest-table/
+│   └── utils/contest-table/
+├── votes/
+│   ├── actions/
 │   ├── components/
-│   │   ├── contest-table/           # コンテスト別
-│   │   ├── grade-list/              # グレード別
-│   │   ├── detail/
-│   │   │   ├── statistics/          # AtCoder Problems の difficulty、JOI 難易度、AC人数 など
-│   │   │   └── comments/            # (要確認) 管理者: 解説、一般ユーザ: コメント
-│   │   └── shared/
-├── votes/                           # AtCoder NoviSteps における難易度、タグを投票
-├── admin/
-│   ├── components/
-│   │   ├── account-transfer/
-│   │   ├── tasks-for-import/
-│   │   └── shared/
-│   ...
-├── auth/
-└── user-profile/
-```
-
-**components/ のサブディレクトリ規約:**
-
-- `list/` — 一覧ページ用コンポーネント
-- `detail/` — 詳細ページ用コンポーネント
-- `shared/` — feature 内で複数ページから使うコンポーネント
-
-**`server/` サブディレクトリ規約:**
-
-feature 内のサーバ専用・非サービスコード(リクエストスコープのハンドル、cookie 書き込み、
-crypto ユーティリティなど、`services/` の「純粋な値/`null` を返す framework 非依存」規約に
-収まらないもの)は `features/{feature}/server/` に置く(`votes/server/`・`workbooks/server/`・
-`auth/server/` が前例)。
-
-- `$lib/server/` を出るため SvelteKit のクライアント import 禁止(ビルド時エラー)は**効かない**。
-  保護は規約ベース + 推移的依存(`$lib/server/database` の import や `node:crypto` 依存)に委ねる
-- 2つ以上の feature で使うサーバコードは `src/lib/server/` に昇格させる(例: `database.ts`)
-
-### ルート固有の `_types/` / `_utils/` ディレクトリ
-
-SvelteKit のルートディレクトリ内で、そのページ専用の型やユーティリティを colocate するために `_types/` と `_utils/` を使う。アンダースコアプレフィックスにより SvelteKit のルーティング対象外となる。
-
-```text
-src/routes/(admin)/workbooks/order/
-├── +page.svelte
-├── +page.server.ts
-├── +server.ts
-├── _components/        # ページ専用コンポーネント
-│   ├── KanbanBoard.svelte
-│   └── ...
-├── _types/             # ページ専用の型定義
-│   └── kanban.ts
-└── _utils/             # ページ専用のユーティリティ（純粋関数）
-    ├── kanban.ts
-    └── kanban.test.ts  # ユーティリティにはテストを隣接配置
+│   ├── constants/
+│   ├── internal_clients/
+│   ├── server/
+│   ├── services/
+│   ├── types/
+│   ├── utils/
+│   └── zod/
+└── workbooks/
+    ├── components/{list,detail,shared}/
+    ├── fixtures/
+    ├── server/
+    ├── services/
+    ├── stores/
+    ├── types/
+    ├── utils/
+    └── zod/
 ```
 
-**ルール:**
-
-- `_types/` には型定義のみ置く。ランタイムコードは含めない
-- `_utils/` には純粋関数のみ置く。副作用やサーバー専用コードは含めない
-- `_utils/` の関数には単体テストを隣接配置する
-- 他のルートから参照する場合は `features/` または `lib/` に昇格させる
-
-### Feature 分割案
-
-現在の `src/lib/` からの抽出候補:
-
-| Feature          | 抽出対象                                                                                                                             |
-| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| **tasks**        | `TaskGrades/*`, `stores/active_problem_list_tab.svelte.ts`（※ `TaskGradeList`, `TaskList` 等は複数ドメインで使うため `lib/` に残す） |
-| **admin**        | `TagForm`, `TagListForEdit`, `TaskForm`, `TaskListForEdit`, `services/tags.ts`, `services/task_tags.ts`                              |
-| **auth**         | `AuthForm`, `utils/auth_forms.ts`, `types/auth_forms.ts`                                                                             |
-| **user-profile** | `UserProfile`, `UserAccountDeletionForm`                                                                                             |
-
-### Feature 間の依存ルール
+feature 内は技術的な役割で分ける。必要なディレクトリだけ作り、空の標準構成を先に作らない。
 
-- `features/` → `lib/` の参照: OK
-- `features/A/` → `features/B/` の参照: NG（共通化が必要なら `lib/` に移す）
-- `routes/` → `features/` の参照: OK
-- `routes/` → `lib/` の参照: OK
+- `components/`: UI。必要なら `list/`、`detail/`、`shared/` で分割する。
+- `services/`: framework 非依存のビジネスロジック。値または `null` を返す。
+- `server/`: request-scoped handle、cookie、crypto、cache などのサーバ専用コード。
+- `internal_clients/`: feature 内だけで使う外部 API client。
+- `utils/`: 副作用のない関数。テストを隣接配置する。
+- `stores/`: Svelte Runes を使う `.svelte.ts`。
 
----
+`features/{feature}/server/` は `$lib/server/` と違い、SvelteKit が client import を自動では禁止しない。規約と推移的な server-only dependency により client から分離する。複数 feature で使うサーバコードは `src/lib/server/` へ移す。
 
-## 3. src/lib/ に残すもの
+### 3. src/lib
 
-2つ以上の feature から使われるコードのみ配置する。
+`src/lib/services/` は廃止予定の移行先ではなく、複数 feature から利用する business logic の現行配置である。
 
 ```text
 src/lib/
-├── actions/        # SvelteKit アクション
-├── clients/        # 外部 API クライアント（AtCoder Problems, AOJ）
-├── components/     # 共通 UI コンポーネント（GradeLabel, TaskGradeList, TaskList, FormWrapper 等）
-├── constants/      # アプリ定数
-├── contests/       # コンテスト分類・ラベル生成・優先度
-│   ├── types/      # ContestType, ContestPrefix 等の型定義
-│   ├── utils/      # classification, priority, task_index_label
-│   │   ├── labels/ # 種別ごとのラベル生成（axc, joi, past, aoj, ...）
-│   │   └── prefixes.ts # 定数辞書（ABC_LIKE, AOJ_COURSES 等）
-│   └── fixtures/   # テストデータ
-├── server/         # サーバー専用の共有インフラ
-│   ├── database.ts # Prisma クライアント（14+ サービスが依存）
-│   ├── tasks/      # cache.ts など複数 feature 共有のサーバ処理
-│   └── services/   # 複数 feature で使うビジネスロジック
-├── stores/         # 共通ストア（error_message 等）
-├── types/          # 共通型定義
-├── utils/          # 共通ユーティリティ
-└── zod/            # バリデーションスキーマ
+├── actions/        # 共通 SvelteKit actions
+├── clients/        # 共通の外部 API clients
+├── components/     # 共通 UI components
+├── constants/      # 共通定数
+├── contests/       # コンテスト分類ドメイン
+├── server/         # 共通の server-only infrastructure
+│   ├── database.ts
+│   └── tasks/
+├── services/       # 複数 feature で使う business logic
+├── stores/         # 共通 stores
+├── types/          # 共通 domain types
+├── utils/          # 共通 pure utilities
+└── zod/            # 共通 validation schemas
 ```
 
-`lib/server/` 内のコードはクライアントからインポートできない（SvelteKit が自動でビルド時エラーにする）。
+`src/lib/server/` は SvelteKit の server-only module として client import がビルド時に拒否される。route handler は Prisma を直接 import せず、service を呼び出す。
 
----
+### 4. admin route の colocation 例外
 
-## 4. テストコロケーション
-
-### 方針: ファイル隣接配置
-
-テストは対象ファイルの隣に置く。変更時にテストが目に入り、更新忘れを防ぐ。
+管理画面の単一ページにだけ属し、認証・認可やページ固有 layout と強く結びつくコードは、route 直下へ colocate してよい。
 
 ```text
-features/workbooks/services/
-├── workbooks.ts
-└── workbooks.test.ts       ← 隣接
+src/routes/(admin)/workbooks/order/
+├── +page.svelte
+├── +page.server.ts
+├── +server.ts
+├── _components/
+├── _fixtures/
+├── _types/
+└── _utils/
+    ├── kanban.ts
+    └── kanban.test.ts
 ```
 
-### 共通テスト資産は src/test/ に残す
+- `_types/` は型だけ、`_utils/` は pure function だけを置く。
+- `_utils/` のテストは隣接配置する。
+- 他ページから使い始めたら `features/` または `lib/` へ移す。
+- 一般 route の標準配置にはしない。
 
-- テストファクトリ（`@quramy/prisma-fabbrica`）
-- テストヘルパー・フィクスチャ
-- E2E テスト（`e2e/`）
+### 5. テストの配置と検出
 
-### Vitest 設定
+- feature、lib、route-local utility のテストは対象ファイルに隣接させる。
+- 段階移行中の共通テストは `src/test/` に残してよい。
+- E2E test は `e2e/` に置き、`.spec.ts` を使う。
 
-`vite.config.ts` の `include` パターンを更新する:
+`vite.config.ts` は現在、次の unit test を検出する。
 
-```ts
+```typescript
 include: [
-  'src/test/**/*.test.ts', // 既存テスト（段階移行）
-  'src/features/**/*.test.ts', // feature 内テスト
+  'src/lib/**/*.test.ts',
+  'src/test/**/*.test.ts',
+  'src/features/**/*.test.ts',
+  'src/routes/**/*.test.ts',
 ];
 ```
 
----
-
-## 5. パスエイリアス
-
-`svelte.config.js` でカスタムエイリアスを設定する:
+### 6. path alias
 
-```js
-kit: {
-  alias: {
-    $lib:      './src/lib',
-    $features: './src/features',
-  },
-}
-```
+`svelte.config.js` で `$lib` と `$features` を定義している。
 
-```ts
-// インポート例
-import WorkBookForm from '$features/workbooks/components/WorkBookForm.svelte';
+```typescript
 import { formatDate } from '$lib/utils/format';
-import type { PageServerLoad } from './$types'; // フレームワーク型は ./$types から
+import WorkBookForm from '$features/workbooks/components/shared/WorkBookForm.svelte';
+import type { PageServerLoad } from './$types';
 ```
 
-`$types` は SvelteKit が `.svelte-kit/types/` に自動生成するフレームワーク型（`PageServerLoad` 等）。ビジネスドメイン型は `$lib/types/` に置く。
-
----
-
-## 6. 参考資料
+`$types` は SvelteKit が生成する route 型専用で、domain type は `src/**/types/` に置く。
 
-### SvelteKit 公式
+## 将来案・未実装
 
-- [プロジェクト構造](https://svelte.dev/docs/kit/project-structure)
-- [ルーティング](https://svelte.dev/docs/kit/routing)
-- [高度なルーティング](https://svelte.dev/docs/kit/advanced-routing)
-- [サーバー専用モジュール](https://svelte.dev/docs/kit/server-only-modules)
+以下は候補であり、現在の必須構成ではない。
 
-### 設計の参考
+- 管理画面の複数 route で共有される UI や service が増えた場合に、`features/admin/` を作る。
+- account と auth から独立した公開プロフィール機能が必要になった場合に、 `features/user-profile/` を作る。
+- `src/lib/` の既存コードを、利用箇所の監査後に各 feature へ段階的に移す。
+- feature 間依存を ESLint 等で機械的に検査する。
 
-- [Next.js App Router アーキテクチャ設計ガイド](https://zenn.dev/yukionishi/articles/cd79e39ea6c172) — `src/features/` パターン、ESLint によるアーキテクチャ境界の自動強制
-- [サンプルリポジトリ](https://github.com/YukiOnishi1129/next-app-router-architecture) — 上記記事の実装例
-- [Immich](https://github.com/immich-app/immich/tree/main/web/src) — 大規模 SvelteKit アプリの実例（`lib/components/{domain}/` パターン）
+ディレクトリを先に作ると境界が形骸化するため、2つ目の実利用が生じた時点で共通化を判断する。
 
-### 関連 Issue
+## 参考資料
 
-- [#601: ディレクトリ構造＆コロケーション](https://github.com/AtCoder-NoviSteps/AtCoderNoviSteps/issues/601)
+- [SvelteKit project structure](https://svelte.dev/docs/kit/project-structure)
+- [SvelteKit routing](https://svelte.dev/docs/kit/advanced-routing)
+- [SvelteKit server-only modules](https://svelte.dev/docs/kit/server-only-modules)
+- [Issue #601: ディレクトリ構造＆コロケーション](https://github.com/AtCoder-NoviSteps/AtCoderNoviSteps/issues/601)
diff --git a/docs/guides/claude-code.md b/docs/guides/claude-code.md
index 46b8725c9..7ef9cb102 100644
--- a/docs/guides/claude-code.md
+++ b/docs/guides/claude-code.md
@@ -1,175 +1,32 @@
-# Claude Code 機能ガイド
+# Claude Code 設定ガイド
 
-Claude Code の拡張ポイントの使い分けをまとめる。
+共通規約とrules / skillsの利用方法は [AGENTS.md](../../AGENTS.md) を参照する。
 
-## 機能の概要と使い分け
+## 設定と保存先
 
-| 機能                      | 場所                    | 読み込みタイミング                                                 | 主な用途                                           |
-| ------------------------- | ----------------------- | ------------------------------------------------------------------ | -------------------------------------------------- |
-| `CLAUDE.md` / `AGENTS.md` | プロジェクトルート      | セッション開始時・常時                                             | プロジェクト全体の規約・コマンド                   |
-| `.claude/rules/*.md`      | `.claude/rules/`        | `paths` 指定なし → 常時、`paths` 指定あり → 対象ファイルを開いた時 | トピック別ルール（コーディングスタイル・テスト等） |
-| Skills (`/skill-name`)    | `.claude/skills/`       | 呼び出し時のみ                                                     | 再利用可能なワークフロー手順                       |
-| Hooks                     | `.claude/settings.json` | ツール呼び出しイベント時                                           | 自動フォーマット・保護ファイルブロック等の自動処理 |
+- project共通設定は原本 [.claude/settings.json](../../.claude/settings.json) だけで管理し、sandboxとdenyを定義する。個人設定と環境固有の緩和は `.claude/settings.local.json` へ置き、Gitとdocker build contextに含めない。
+- `CLAUDE.md` は `AGENTS.md` をimportし、Claude固有の入口だけを定義する。
+- `.claude/rules/` は `docs/guides/agent-rules/` の共通本文へのsymlinkで、`paths` frontmatterでpathごとに読み込む。`coding-style.md` は計画時にも必要なため常時適用する。
+- `.claude/skills/` は `.agents/skills/` の共通skillへのsymlinkで、project固有workflowを必要な時だけ読み込む。本文をLLM別に複製しない。
+- devcontainerではhostの `~/.claude` を `/home/node/.claude`（`CLAUDE_CONFIG_DIR`）へmountし、認証やsessionをrebuild後も保持する。
 
-## 各機能の詳細
+## 実行権限
 
-### CLAUDE.md / AGENTS.md
+sandboxは有効化し、利用できない場合のunsandboxed実行へのfallbackを禁止する。具体的なdeny対象は原本を参照し、`.codex/config.toml` と揃える。denyはsandbox層（`sandbox.filesystem.denyRead`）とRead tool層（`permissions.deny`）の両方へ書く。sandboxはbash経路しか止めない。
 
-- セッション開始時に全文読み込まれる（トークン消費）
-- **200行以内を目安**にする
-- プロジェクト全体に常に適用したい規約・コマンド一覧・アーキテクチャ概要を置く
-- `CLAUDE.md` から `@AGENTS.md` のように別ファイルを読み込める
+`.claude/settings.json` はGit管理されproject scopeで適用されるため、denyはdevcontainerだけでなくhost cloneやcloud agentにも効く。devcontainerに存在しない秘密でも、他環境で実在するものはdenyを外さない。
 
-### `.claude/rules/` ファイル
+Linux sandboxには `bubblewrap` を使い、Dockerfileで導入する。SSH秘密鍵はmountせず、hostの `ssh-agent` からDev Containersのagent forwardingを使う。projectのMCP serverは登録しない。
 
-- フロントマターで `paths` を指定すると、対象ファイルを開いた時だけ読み込まれる（コンテキスト節約）
-- `paths` を指定しないと常時読み込まれる（CLAUDE.md と同じ扱い）
-- **`globs` は非推奨。`paths` を使う**
+## Skillsとplugin
 
-```yaml
----
-description: Testing rules and patterns
-paths:
-  - '**/*.test.ts'
-  - 'e2e/**'
----
-```
+project固有skillの正本は `.agents/skills/` に置く。Superpowersはproject設定で自動導入せず、必要な利用者だけがuser scopeで導入する。標準のplan / review / subagent機能で足りない場合は、重複の少ない `systematic-debugging` や `verification-before-completion` を個別に検討する。
 
-適しているもの:
+## 動作確認
 
-- Linter/Formatter でカバーできない「意思決定ルール」（アーキテクチャ方針、命名判断基準）
-- ファイル種別ごとに分けたい規約（テスト、DB、Svelte コンポーネント等）
-
-**このプロジェクトの rules ファイル:**
-
-| ファイル               | スコープ                                                 |
-| ---------------------- | -------------------------------------------------------- |
-| `coding-style.md`      | 言語レベルの記述スタイル（ブレース・命名・型エイリアス） |
-| `testing.md`           | `*.test.ts`, `*.spec.ts`, `e2e/**` のテストパターン      |
-| `svelte-components.md` | `*.svelte` コンポーネント設計方針                        |
-| `prisma-db.md`         | `prisma/**`, `src/lib/server/**` の DB・サービス層規約   |
-| `auth.md`              | 認証関連                                                 |
-
-### Skills（カスタムスラッシュコマンド）
-
-- `/skill-name` で呼び出す再利用可能な手順書
-- 呼び出し時のみフル読み込みされるためコンテキストに優しい
-- CLAUDE.md に常時書くほどではないが、繰り返し使うワークフローに向く
-
-**ビルトイン skills（`~/.claude/skills/`）:**
-
-| スキル      | 用途                               |
-| ----------- | ---------------------------------- |
-| `/commit`   | git コミット作成ワークフロー       |
-| `/simplify` | 変更済みコードの品質レビュー・改善 |
-
-**本プロジェクトの skills（`.claude/skills/` および superpowers plugin）:**
-
-| スキル                        | 用途                                                                                                                                                            |
-| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `/writing-plans`              | 新機能・追加実装の詳細計画を生成（2-5分単位のタスク分解）。superpowers plugin 提供                                                                              |
-| `/add-contest-table-provider` | 新しい ContestType と ContestTableProvider を TDD で 5 層実装（Prisma → 型 → ユーティリティ → Provider → グループ登録）。3 パターン対応。実装前に要件を確認する |
-| `/refactor-plan`              | Issue 番号またはパスを渡してリファクタリング計画を出力（実装はしない）                                                                                          |
-| `/session-close`              | セッション終了時のルーティン：テスト確認 → plan.md 更新 → rules 候補提示 → 肥大化チェック → 繰り返し指示検出                                                    |
-| `/dep-upgrade`                | ライブラリのメジャーバージョンアップ分析：破壊的変更の整理・本プロジェクトへの影響・新機能提案 → plan.md 生成 → アップグレード実行                              |
-| `/extract-approach`           | 非自明な問題を解決した直後に、アプローチと教訓を `docs/dev-notes/YYYY-MM-DD/{task}/learning.md` へ問題単位で抽出（モデル自動起動可）                            |
-
-**`/dep-upgrade` の使い方:**
-
-```bash
-/dep-upgrade <package-name> <old-major> <new-major>
-例: /dep-upgrade eslint 9 10
-```
-
-実行内容:
-
-1. 公式マイグレーションガイドを WebFetch で取得
-2. 破壊的変更を `src/` / 設定ファイルに対して grep し、問題なし / 要対応を分類
-3. 同時更新が必要なコンパニオンパッケージを確認（例: `eslint` + `@eslint/js`）
-4. 新バージョンで使える機能を推奨度付きで提案
-5. `docs/dev-notes/YYYY-MM-DD/{package}-upgrade/plan.md` を生成し、確認後にアップグレードを実行
-
-**`/writing-plans` と `/refactor-plan` の使い分け:**
-
-- `/writing-plans`: 新機能・追加実装の実装前の詳細計画生成（2-5分単位のタスク分解）
-- `/refactor-plan`: リファクタリング調査チェックリスト（実装はしない）
-
-**プロジェクトローカルスキルと `Skill` ツールの違い:**
-
-- `Skill` ツール（Claude 内部のツール）はシステムプロンプトに列挙されたビルトインスキルのみ対象
-- `.claude/skills/` のプロジェクトローカルスキルは `/skill-name` スラッシュコマンドでのみ起動（Claude Code CLI が直接読み込む）
-- `/session-close` などを Claude に `Skill` ツール経由で呼ばせようとしても動作しない
-
-### Hooks
-
-- `PreToolUse` / `PostToolUse` 等のイベントで自動実行されるシェルコマンド
-- LLM の判断を介さず**確実に**実行される（deterministic）
-- `.claude/settings.json` の `hooks` セクションに設定
-
-適しているもの:
-
-- **コード編集後の自動フォーマット**（PostToolUse: Edit/Write → `pnpm format`）
-- 保護すべきファイルへの書き込みブロック
-- 通知
-
-> **このプロジェクトでは** Lefthook が pre-commit で Prettier + ESLint を実行するため、
-> hooks による PostToolUse フォーマットは必須ではない。
-> 編集中にリアルタイムでフォーマットしたい場合のみ hooks を検討する。
-
-## 既存ツールで十分なもの
-
-以下は **Linter / Formatter / CI で既にカバーされている**ため、Claude Code の機能で重複して設定しない:
-
-| 問題                 | 対応ツール                                 |
-| -------------------- | ------------------------------------------ |
-| コードフォーマット   | Prettier（Lefthook で pre-commit 実行）    |
-| 未使用変数・型エラー | ESLint + `pnpm check`（Svelte 型チェック） |
-| ブレース強制         | ESLint `curly` ルールで対応可能            |
-| import 順序          | ESLint で対応可能                          |
-
-## 作業フロー規約
-
-Claude Code を使ってリファクタリング・機能追加を行う際の標準フロー:
-
-1. **計画**: `/writing-plans` で 2-5 分単位のフェーズ分け TODO を生成する
-2. **実装**: プロダクションコード → テスト → `pnpm test:unit` で確認
-3. **TODO 更新**: 完了タスクにチェックを入れる
-4. **milestone レビュー**: Phase の区切り（独立したゴールと完了条件を持つタスク群が終わった時点）で `coderabbit review --plain` を実行し、critical/high のみ対応する
-5. **レビュー**: 実装後に批判的な観点でレビューする（忖度しない。YAGNI / KISS / DRY 違反、過剰な抽象化を指摘する）
-6. **教訓整理**: 次回以降も有用な知見を `.claude/rules/` または `docs/guides/` などに記録する
-7. **クリーンアップ**: 完了した計画書・古い TODO は削除または要約する
-
-## レビューチェーン
-
-```text
-/writing-plans で plan 生成（2-5 分タスク単位）
-  → 実装
-  → Phase 区切りで coderabbit review --plain（milestone レビュー）
-  → PR 作成後に CodeRabbit CI（最終ゲート）
-```
-
-| レイヤー            | タイミング        | 対応コスト | 目的                           |
-| ------------------- | ----------------- | ---------- | ------------------------------ |
-| `/writing-plans`    | 実装前            | 低         | アーキテクチャ違反を事前に防ぐ |
-| `coderabbit review` | Phase 区切り      | 中         | critical/high を早期に潰す     |
-| CodeRabbit CI       | PR 作成後（自動） | 高         | 最終品質ゲート                 |
-
-**milestone タスクのテンプレート（writing-plans で Phase を締めるとき）:**
-
-```markdown
-## Milestone: Phase N complete
-
-- [ ] Run `coderabbit review --plain` on changed files
-- [ ] Address critical/high severity issues before next phase
-- [ ] Log CodeRabbit comment count (for metrics)
-```
-
-> **初回セットアップ**: `coderabbit auth login` でブラウザ認証。devcontainer の `postCreateCommand` でインストール済み。
-
-> severity ごとの対応基準は `.claude/rules/coding-style.md` の "CodeRabbit Review: Severity Triage" を参照。
+設定変更後はdummy secretだけを使って検証し、実credentialの内容は表示しない。`.env` とmountされる認証fileのreadが、bash経路とRead tool経路の両方で拒否されることを確認する。
 
 ## 参考
 
-- [Claude Code 公式ドキュメント](https://docs.anthropic.com/en/docs/claude-code)
-- [CLAUDE.md の書き方](https://docs.anthropic.com/en/docs/claude-code/memory)
-- [Hooks の設定](https://docs.anthropic.com/en/docs/claude-code/hooks)
+- [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings)
+- [Claude Code sandboxing](https://docs.anthropic.com/en/docs/claude-code/sandboxing)
diff --git a/docs/guides/codex.md b/docs/guides/codex.md
new file mode 100644
index 000000000..97c331bcb
--- /dev/null
+++ b/docs/guides/codex.md
@@ -0,0 +1,32 @@
+# Codex 設定ガイド
+
+共通規約とrules / skillsの利用方法は [AGENTS.md](../../AGENTS.md) を参照する。
+
+## 設定と保存先
+
+- 共通設定は原本 [.codex/config.toml](../../.codex/config.toml) だけで管理する。CLIとVS Code拡張が直接読み、trusted projectではuser設定より優先される。コピーや別のlocal設定fileは作らない。
+- `$CODEX_HOME/config.toml` は個人のmodel設定、trust、TUI状態の保存用とし、共通設定を重複させない。
+- devcontainerではhostの `~/.codex-devcontainer/AtCoderNoviSteps` を `/home/node/.codex`（`CODEX_HOME`）へmountする。CLIと拡張の認証・sessionなどを共有し、rebuild後も保持する。hostの通常の `~/.codex` とは分離する。
+- CodexにはClaude Codeの `.claude/skills/` のようなsymlink層はない（`.codex/skills/` は存在しない）。project固有workflowは正本 `.agents/skills/<name>/instructions.md` を直接参照する。
+
+## 実行権限
+
+`project-edit` profileはworkspaceの編集を許可し、`.env*`、credential、秘密鍵などのreadを拒否する。具体的なdeny対象は原本を参照し、`.claude/settings.json` と揃える。子processの環境変数は `core` を基準に、既定のsecret名filterも有効にする。
+
+Linux sandboxには `bubblewrap` を使う。Dockerfileでsetuid付きで導入し、composeのweb serviceにnested sandbox用のcapabilityとseccomp / AppArmorの緩和を設定する。
+
+`on-request` はsandbox外の操作に対する承認方針であり、sandboxの代替ではない。credentialを保護するため、`danger-full-access` と `--dangerously-bypass-approvals-and-sandbox` は使用しない。
+
+SSH秘密鍵はmountせず、hostの `ssh-agent` からDev Containersのagent forwardingを使う。projectのMCP serverは登録しない。
+
+## 動作確認
+
+sandboxの実行基盤を変更したらclean rebuildし、通常のcontainer terminalで確認する。
+
+```bash
+command -v bwrap
+bwrap --unshare-user --dev-bind / / true
+codex sandbox -- true
+```
+
+CLIとVS Code拡張の両方で新規sessionを開始し、command実行とdummy credentialのread拒否を確認する。
diff --git a/docs/guides/how-to-add-contest-table-provider.md b/docs/guides/how-to-add-contest-table-provider.md
index 23c90c82d..5a72e7463 100644
--- a/docs/guides/how-to-add-contest-table-provider.md
+++ b/docs/guides/how-to-add-contest-table-provider.md
@@ -1,6 +1,6 @@
 # ContestTableProvider 実装・テストガイド
 
-タスク一覧をコンテスト別テーブルとして描画するための `ContestTableProvider`（フィルタ条件 + メタデータ + レイアウト定義）を新規に追加するときのリファレンス。基底クラスは `ContestTableProviderBase`。TDD フロー・テスト規約は AGENTS.md、コーディングスタイルは `.claude/rules/` を参照。
+タスク一覧をコンテスト別テーブルとして描画するための `ContestTableProvider`（フィルタ条件 + メタデータ + レイアウト定義）を新規に追加するときのリファレンス。基底クラスは `ContestTableProviderBase`。TDD・コーディング規約は `AGENTS.md`、配置規約は `docs/guides/architecture.md` を参照。
 
 ---