# MCPedia Phase 11 — CRUD + Auth + UI/UX Improvement

## Plan (spec BEFORE implementation, per user rule)

### Scope: 4 areas
1. **CRUD**: Create/Read/Update/Delete documents from web UI + MCP
2. **Auth**: Session-based auth for web edits; API key auth for MCP writes
3. **UI/UX**: Polish doc page, edit forms, search UX, dark mode
4. **Agent integration**: MCP tools for CRUD with auth

## Requirements:
1. **Source of truth is the filesystem** — each doc is a markdown file under `content/{section}/{slug}.md` with YAML frontmatter (parsed/striped by gray-matter).
2. **DB mirrors disk** — `documents` table has slug/title/section/body/status/tags/etc; `document_chunks` stores embeddings; `document_revisions` snapshots body+meta.
3. **Single indexing path** — `indexContentFile` in `@mcpedia/core` writes DB + revisions + chunks; CRUD ops call it (or its pieces) after writing the file.
4. **Auth** — MCP/API writes require `x-webhook-secret` matching `WEBHOOK_SECRET` (Phase 4 pattern). Web CRUD uses cookie-based auth (Phase 11 addition: `ADMIN_PASSWORD`).
5. **Slug rules** — `[a-z0-9][a-z0-9/_-]*`, no `//`, no path traversal (`..`). The slug in the URL is `<section>/<slug-parts>`.
6. **No breaking existing features** — read tools/routes unchanged; existing 32 tests still green.
7. **UI/UX** — edit button on doc pages (auth-gated), `?edit=1` inline form, `/create` page, login page, table of contents auto-generated from h2, dark mode toggle.

### Schema changes:
- Optional: `users` table if auth is user-based
- OR: simple `WEB_AUTH_TOKEN` env for admin access (simpler, fits single-author KB)

### Backend surface:
- **Web auth**: Cookie-based session OR single admin token in localStorage
  - Simpler approach: `POST /api/auth/login` (checks `ADMIN_PASSWORD` env) → sets cookie
  - Edit UI gated behind cookie check in server components
- **MCP auth**: `x-api-key` header for write tools (create/update/delete)
  - Read tools (list, get, search) — public
  - Write tools (create, update, delete, index_document, reindex_all, restore_revision) — require key
  - `createMcpServer(authKey?)` threads the header, same pattern as `x-webhook-secret`

### CRUD operations:
- **Create**: `POST /trpc/createDocument` (title, slug, section, body, tags)
  - Writes markdown file to `content/{section}/{slug}.md`
  - Triggers indexer (enqueues job or calls directly)
- **Update**: `POST /trpc/updateDocument` (slug, body, title, tags, status)
  - Updates file + creates revision + reindexes
- **Delete**: `POST /trpc/deleteDocument` (slug)
  - Removes file, DB rows, chunks; creates revision tombstone
- All mutations require auth (web cookie OR webhook secret OR MCP api-key)

### UI improvements:
- Edit button on doc pages (auth-gated) → link to `/docs/{slug}/edit`
- Create page: `/docs/create` with form (section dropdown, slug, title, tags, markdown editor)
- Edit page: `/docs/{slug}/edit` pre-fills from getDocument
- Search page: live search results with keyboard nav, better empty states
- Doc page: table of contents (auto-generated from h2), dark mode toggle

### Verification steps:
1. TDD: write failing tests for each new API endpoint/method first
2. `bun run typecheck` — green
3. `bun run test` — 32 existing + new tests green
4. `bun run build` — green
5. CI + Deploy passes
6. Browser: create doc → search sees it → edit doc → changes reflect → delete doc → gone
7. MCP: create_document tool with key → doc appears; without key → unauthorized

### Acceptance criteria:
- [ ] createDocument tRPC + MCP
- [ ] updateDocument tRPC + MCP  
- [ ] deleteDocument tRPC + MCP
- [ ] Web auth (cookie-based login)
- [ ] MCP write-tool auth (api-key)
- [ ] UI: edit/create pages
- [ ] UI: TOC + dark mode on doc pages
- [ ] All tests green, CI+Deploy passes