Review: Review playground + API alignment for SvelteKit port

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type -- Feature
• [x] Lineage -- references pal-e-docs-playground#1
• [x] Repo -- forgejo_admin/pal-e-app
• [x] User Story -- well-formed As/I want/So that
• [x] Context -- thorough background
• [x] File Targets -- present with read-only and do-not-touch sections
• [x] Acceptance Criteria -- 6 criteria listed
• [x] Test Expectations -- N/A acknowledged (review ticket)
• [x] Constraints -- present
• [x] Checklist -- present
• [x] Related -- present with story and board references

Traceability

• [x] story:reader-browse label -- matches user story for note browsing
• [x] arch:frontend label -- correct, this is frontend alignment work
• [x] Forgejo issue -- forgejo_admin/pal-e-app#65, open

File Targets

• [x] ~/pal-e-docs-playground/*.html -- verified: 6 HTML files exist (index.html, notes.html, note.html, note-board.html, note-project.html, graph.html)
• [x] ~/pal-e-docs-playground/app.css -- verified: exists
• [x] ~/pal-e-app/src/app.css -- verified: exists
• [x] ~/pal-e-app/src/lib/components/blocks/ -- verified: 7 files (BlockRenderer.svelte + 6 type-specific components)
• [x] ~/pal-e-app/src/routes/ -- verified: exists with dashboard, notes, boards, projects, repos, search, tags routes
• [ ] ~/pal-e-app/src/lib/api.ts -- WRONG PATH: file does not exist. Actual path is ~/pal-e-app/src/lib/api-client.ts
• [x] ~/pal-e-docs/src/pal_e_docs/routes/ -- verified: exists with notes.py, boards.py, blocks.py, projects.py, tags.py, repos.py, links.py, health.py

Repo Placement

Dependencies

• Board item #422 (pal-e-docs-playground#1 -- "Playground: note detail page prototype") is in todo column with same labels. The issue Lineage says this ticket follows that playground prototype. If playground#1 is incomplete, this review may be premature or scoped to only the pages that exist.
• Board item #93 (Phase F11: Design System Overhaul) is in_progress with story:reader-browse. Active design work could change what the alignment review finds.
• Board item #297 (Playground: kanban prototype) is in_progress. Kanban board page may evolve during this review.
• Dependencies are not documented in the issue scope. The Lineage section mentions the playground prerequisite but does not flag these as blocking risks.

Acceptance Criteria

• Criterion 1 ("Every @data field maps to a real API response field") -- Testable by an agent. Can compare data contracts against API response schemas.
• Criterion 2 ("Every @api endpoint exists in backend") -- Testable. However, already partially falsifiable: the playground index.html references GET /api/boards/items?column=in_progress but the actual endpoint is GET /boards/activity?column=in_progress. The notes list endpoint has no sort parameter -- it always sorts by updated_at desc by default. The graph page has no corresponding backend API endpoint at all.
• Criterion 3 ("Block types match BlockRenderer dispatch, 6 types, no callouts") -- Contradicts the playground data contract at note.html:18 which lists "callout" as a block type. The playground CSS also has callout styles (.block--callout, .callout-label, variants). The BlockRenderer handles 6 types (heading, paragraph, code, table, list, mermaid) with no callout. This contradiction should be resolved in the issue scope.
• Criterion 4 ("Gap list produced") -- Agent-verifiable as a deliverable.
• Criterion 5 ("Search page spec added to playground") -- This is a code change, not a review. The issue says "Read-only review -- no code changes" in Constraints, but this criterion requires creating a new playground page. Contradiction.
• Criterion 6 ("Alignment doc written") -- Agent-verifiable as a deliverable.

Blast Radius

• The wrong API client path (api.ts vs api-client.ts) is a minor issue but if an agent follows the ticket literally, it will fail to find the file.
• The callout block type discrepancy between playground and app needs resolution -- either the playground contract is aspirational (add callout support later) or the playground is wrong. If callout is needed, that is new scope for the port.
• The graph page has no backend endpoint. The existing /notes/{slug}/links endpoint returns per-note links, not a full graph. Building a graph API would be significant new scope not captured here.
• The existing pal-e-app already has a search route, but the playground does not have a search page. The ticket flags this gap correctly but mixing "add search page to playground" with "review alignment" conflates review and implementation scope.

Recommendation

• Fix file path: Change ~/pal-e-app/src/lib/api.ts to ~/pal-e-app/src/lib/api-client.ts in File Targets.
• Resolve callout contradiction: Acceptance criterion 3 says "no callouts" but the playground data contract and CSS include callouts. Clarify whether the review should flag callout as a gap or confirm its exclusion.
• Remove or split search page criterion: Acceptance criterion 5 ("Search page spec added to playground") is a code change that contradicts the "Read-only review -- no code changes" constraint. Either remove it from this ticket and create a separate issue, or remove the no-code-changes constraint.
• Document dependency risk: Board item #422 (playground#1) is still in todo. If this review depends on a complete playground, that dependency should be explicit. If it can proceed with the 6 existing pages, state that.