Review: API endpoints -- Rails serves the REST surface for MCP

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type -- Feature
• [x] Lineage -- depends on paldocs#49
• [x] Repo -- ldraney/paldocs
• [x] User Story -- present, well-formed
• [x] Context -- good background on MCP proxy pattern
• [x] File Targets -- present (app/controllers/api/, config/routes.rb, app/serializers/)
• [x] Feature Flag -- none, justified (new namespace)
• [x] Acceptance Criteria -- 7 criteria present
• [x] Test Expectations -- request tests + integration tests specified
• [x] Constraints -- JSON shape matching, tsvector, semantic stub
• [x] Checklist -- present
• [x] Related -- present

Traceability

• [ ] story:consolidation label -- story NOT listed in project-paldocs user-stories section. Only kanban, project-pages, and auth stories exist. [SCOPE] Create user story entry on project-paldocs user-stories section for "consolidation" (pal-e-docs into Rails monolith).
• [ ] arch:rails-api label -- no arch note arch-rails-api found in pal-e-docs. [SCOPE] Create architecture note arch-rails-api for the Rails API layer.
• [x] Forgejo issue -- ldraney/paldocs#51, open

File Targets

• [x] app/controllers/api/ -- does not exist yet, will be created. Correct for new API namespace.
• [x] config/routes.rb -- exists. Currently has UI-only routes (projects, notes, boards, board_items). API namespace will be added.
• [x] app/serializers/ -- does not exist yet, will be created. No jbuilder or serializer gem in Gemfile currently; ticket should specify which approach (jbuilder vs active_model_serializers vs plain as_json).
• [x] app/models/ -- correctly marked as "do not touch." Models exist: note, block, board_item, project, repo, tag, note_tag.

Repo Placement

Dependencies

• Upstream: paldocs#49 (schema ownership transfer) -- correctly documented, still open.
• Parallel: paldocs#50 (sprint UI, wave:1), paldocs#52 (embedding pipeline, wave:2) -- documented.
• Downstream: paldocs#53 (repoint MCP + deprecate pal-e-docs, wave:3) -- documented.
• Board items #1559 (schema, wave:0), #1560 (sprint UI, wave:1), #1562 (embeddings, wave:2), #1563 (repoint, wave:3) all present on board-paldocs.

Acceptance Criteria

• AC7 ("compare Rails API responses to pal-e-docs responses, then JSON shapes match") is vague -- which endpoints? All 47? The issue lists only ~6 endpoint groups but the actual pal-e-docs API surface is 47 endpoints across 8 route files.
• AC cover only notes, boards, projects, and search -- missing repos, links, blocks (toc, section, compiled page, rebalance), board advanced endpoints (sync, sync-issues, activity, backlog).
• Test command "rails test" conflicts with Gemfile which uses rspec-rails. Should be "bundle exec rspec".

Blast Radius

• pal-e-mcp uses PalEDocsClient SDK (pal-e-sdk) which constructs HTTP calls to PALDOCS_BASE_URL. The SDK parses JSON responses and expects exact shapes. Any deviation in Rails JSON output will break all 36 MCP tools.
• Existing paldocs UI routes (projects, notes, boards, board_items) must not be affected. The /api/ namespace provides proper isolation.
• The pal-e-docs FastAPI Pydantic response models (NoteOut, BoardItemOut, ProjectOut, etc.) define the contract. Rails serializers must match these exactly.

Decomposition Assessment

• File targets: 6+ new controller files + serializers + routes + request specs = 15+ files in 1 repo. Exceeds the >3 file threshold.
• Acceptance criteria: 7 AC listed, but actual surface is 47 endpoints. Far exceeds the >5 AC threshold.
• Estimated agent work: 47 endpoints with JSON shape matching, request specs for each -- well beyond 5 minutes. Estimated 30-60 minutes of agent work.

• Notes CRUD + search (8 endpoints) -- 8pts
• Boards + Board Items (14 endpoints) -- 8pts
• Blocks (toc, section, compiled, CRUD, rebalance -- 8 endpoints) -- 5pts
• Projects + Repos + Tags + Links (14 endpoints) -- 5pts
• Search: semantic stub (1 endpoint) -- 2pts

Recommendation

• [SCOPE] Create user story entry "consolidation" on project-paldocs user-stories section.
• [SCOPE] Create architecture note arch-rails-api for the Rails API layer.
• [BODY] Fix test command: "rails test" should be "bundle exec rspec" (project uses rspec-rails).
• [BODY] Issue claims "14 MCP tools" but actual surface is 36 MCP tools mapping to 47 HTTP endpoints. Update Context section with accurate endpoint count. Add missing groups: repos CRUD (5 endpoints), links (2 endpoints), blocks/toc/section/compiled/rebalance (8 endpoints), board advanced (activity, backlog, sync-issues).
• [BODY] Specify JSON serialization approach -- jbuilder, active_model_serializers, or plain as_json. No serializer gem currently in Gemfile.
• [DECOMPOSE] 47 endpoints across 6+ controllers with full JSON shape matching and request specs. Far exceeds 5-minute rule. Route to skill-decompose-ticket with 5-sub-ticket split (notes, boards, blocks, projects+repos+tags+links, search).