mcpedia/.hermes/plans/phase11-crud-auth-ui.md

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