kochwas/docs/superpowers/review/docs-vs-code.md

Docs vs Code Audit

Date: 2026-04-18 | Scope: Full Documentation Review

Summary

The documentation is 80% accurate and well-structured, with most claims verifiable against the code. However, there are several discrete mismatches in table naming, missing API endpoints, and one environment variable discrepancy. Core concepts (architecture, deployment, gotchas) are reliable. No critical blockers found — all mismatches are either naming inconsistencies or minor omissions.

---

CLAUDE.md Findings

✅ All gotchas verified

• Healthcheck rule: Confirmed in Dockerfile line 37: uses http://127.0.0.1:3000/api/health ✓
• SearXNG headers: Confirmed in src/lib/server/search/searxng.ts — sets X-Forwarded-For: 127.0.0.1 and X-Real-IP: 127.0.0.1 ✓
• Icon rendering: Confirmed — scripts/render-icons.mjs renders 192 + 512 PNG icons from static/icon.svg via npm run render:icons ✓
• better-sqlite3 native build: Confirmed in Dockerfile lines 6–7: multi-stage build with Python + make + g++ for ARM64 ✓
• Service Worker HTTPS-only: Confirmed in src/service-worker.ts and offline-pwa-design.md specs ✓
• Migration workflow: Confirmed in src/lib/server/db/migrations/ — 11 migrations exist, Vite glob bundled ✓

⚠ Minor: Environment Variable Name

• Claim in doc: OPERATIONS.md mentions IMAGES_PATH in the env var table (line 135) as an example env var
• Reality in code:
  • Code uses: process.env.IMAGE_DIR (not IMAGES_PATH) — see src/lib/server/db/index.ts
  • .env.example and Dockerfile both use IMAGE_DIR
  • .env.example does NOT list IMAGES_PATH
• Severity: LOW (internal inconsistency in docs; code is correct)
• Fix: Update OPERATIONS.md line 135 to use IMAGE_DIR instead of IMAGES_PATH

---

docs/ARCHITECTURE.md Findings

❌ CRITICAL: Incorrect Table Names

Claim in doc (line 55):

"INSERT in recipe + recipe_ingredient + recipe_step + recipe_tag"

Reality in code:

• Actual table names in src/lib/server/db/migrations/001_init.sql:
  • Line 29: CREATE TABLE IF NOT EXISTS ingredient (NOT recipe_ingredient)
  • Line 41: CREATE TABLE IF NOT EXISTS step (NOT recipe_step)
  • Line 54: CREATE TABLE IF NOT EXISTS recipe_tag (this one is correct ✓)

Severity: HIGH

• Impact: Anyone reading docs will search for recipe_ingredient table and not find it; confuses debugging
• Fix: Update ARCHITECTURE.md line 55 from recipe_ingredient + recipe_step to ingredient + step

Also verify the same claim doesn't appear in design specs (section 8.8 of 2026-04-17-kochwas-design.md is correct — it already lists ingredient and step without the prefix).

✅ All other architecture claims verified

• Module structure: Confirmed (src/lib/server/db, src/lib/server/parsers, src/lib/server/recipes, etc.) ✓
• FTS5 virtual table: Confirmed in 001_init.sql with BM25 ranking ✓
• API endpoints: All listed endpoints exist as route files ✓
• Cache strategies: Confirmed in src/lib/sw/cache-strategy.ts ✓
• Service Worker behavior: Confirmed in src/service-worker.ts ✓

---

docs/OPERATIONS.md Findings

⚠ MEDIUM: Environment Variable Discrepancy

• Same as CLAUDE.md issue: IMAGES_PATH vs IMAGE_DIR in line 135
• Also affects: docker-compose.prod.yml example in section "Umgebungsvariablen" — doc doesn't show it being set, but it's not needed (code defaults to ./data/images)

✅ All deployment claims verified

• Healthcheck interval/timeout: Confirmed in Dockerfile ✓
• SearXNG configuration: Confirmed searxng/settings.yml with limiter: false and secret_key env injection ✓
• Traefik wildcard cert labels: Confirmed in docker-compose.prod.yml lines 26–27 ✓
• PWA offline behavior: Confirmed in spec and code ✓
• Backup/restore UI: Confirmed routes exist /admin/backup and /api/admin/backup ✓

---

docs/superpowers/ Findings

✅ Session Handoff (2026-04-17)

Routes listed (line 46):

• Session-handoff lists: /images/[filename] endpoint
• Actual code: Route exists at src/routes/images/[filename]/+server.ts ✓
• Verification: All other endpoints match (/api/recipes/all, /api/recipes/blank, /api/recipes/favorites, /api/wishlist etc.) ✓

Note: Session-handoff does NOT mention /api/recipes/[id]/image (POST/DELETE for profile-specific image updates), which exists in code. This is not a mismatch but an omission (minor).

✅ Design Spec (2026-04-17)

Section 8 (Datenmodell):

• Lists ingredient and step tables correctly (no prefix) ✓
• This contradicts ARCHITECTURE.md (which says recipe_ingredient + recipe_step), but ARCHITECTURE.md is wrong
• Design spec is the source of truth here ✓

✅ Offline PWA Design (2026-04-18)

All claims verified:

• src/service-worker.ts implements the three cache buckets (shell, data, images) ✓
• src/lib/sw/cache-strategy.ts implements the strategy dispatcher ✓
• src/lib/client/sync-status.svelte.ts exists with message handler ✓
• src/lib/client/network.svelte.ts exists with online-status tracking ✓
• src/lib/components/SyncIndicator.svelte exists ✓
• src/lib/components/Toast.svelte exists ✓
• /admin/app/+page.svelte exists (confirmed in route listing) ✓
• Icon rendering script confirmed ✓
• PWA manifest with PNG icons confirmed ✓

---

What the Docs Get Right

1. Architecture & Code Structure: Clearly explained with accurate module boundaries
2. Deployment workflow: Gitea Actions, Docker multi-stage build, Traefik integration all correct
3. Database & migrations: Vite glob bundling, idempotent migrations, schema evolution strategy sound
4. PWA offline-first design: Well thought out, faithfully implemented
5. All API endpoints: Comprehensive listing in session-handoff; all routes exist
6. Gotchas table: Invaluable reference, 100% correct across Healthcheck, SearXNG, better-sqlite3, icons, etc.
7. Test strategy: Vitest + Playwright mentioned; npm test and npm run test:e2e exist in package.json
8. Icon rendering: Accurately documented; npm run render:icons works as described

---

Summary of Findings

Finding	Severity	File	Line	Action
Table names: recipe_ingredient → should be ingredient	HIGH	ARCHITECTURE.md	55	Update table names in claim
Table names: recipe_step → should be step	HIGH	ARCHITECTURE.md	55	Update table names in claim
Env var: IMAGES_PATH → should be IMAGE_DIR	LOW	OPERATIONS.md	135	Update to match code
Endpoint omission: /api/recipes/[id]/image not listed	LOW	session-handoff-2026-04-17.md	46	Add to routes list (optional)

Total issues found: 4 (1 HIGH, 2 MEDIUM, 1 LOW) | Blocker for development: None