pal-e-docs

Review: Update stale docs, add CLAUDE.md, iOS docs, and app icon

review-1808-2026-07-05 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type -- Feature
  • [x] Lineage
  • [x] Repo
  • [x] User Story
  • [x] Context
  • [x] File Targets
  • [x] Feature Flag -- none (appropriate for docs-only)
  • [x] Acceptance Criteria -- 6 items
  • [x] Test Expectations
  • [x] Constraints
  • [x] Checklist
  • [x] Related
All required sections present.

Traceability

  • [x] story:ios-distribution label -- Turbo Native iOS shell + TestFlight + App Store
  • [x] story note verified -- found in project-palinks user-stories section ("in progress")
  • [x] arch:palinks label -- present on board item
  • [ ] arch note MISSING -- [SCOPE] Create architecture note arch-palinks in pal-e-docs
  • [x] Forgejo issue -- ldraney/palinks#57, open

File Targets

  • [x] docs/architecture.md -- exists
  • [x] docs/infrastructure.md -- exists
  • [x] docs/custom-domain.md -- exists
  • [x] docs/pipeline.md -- exists
  • [x] docs/rails-notes.md -- exists
  • [x] docs/user-stories.md -- exists
  • [ ] CLAUDE.md -- ISSUE: listed as "create" but already exists (committed in f602330). References port 3000 but Dockerfile sets PORT=80
  • [ ] docs/ios.md -- ISSUE: listed as "create" but already exists (committed in f602330)
  • [ ] app-icon.png -- ISSUE: listed as "create" but already exists (46k, committed in f602330)
Critical finding: Commit f602330 ("Update docs for current state, add CLAUDE.md, iOS docs, and app icon") on a worktree branch has already done this work, but introduced inaccuracies. The docs now say port 3000 everywhere, but the Dockerfile still sets PORT=80 and EXPOSE 80. Puma binds to ENV.fetch("PORT", 3000), so production actually serves on port 80.

Repo Placement

OK. Issue filed on ldraney/palinks, work is docs-only in the palinks repo. No cross-repo changes needed.

Dependencies

  • Board item #1530 (issue #56, 8 pts) is in validation column, same story:ios-distribution. This is the iOS distribution implementation ticket. No hard dependency -- docs can be written independently.
  • Board items #1809, #1810, #1811 (issues #59, #60, #61) are also in backlog with story:ios-distribution. No blocking relationship for docs work.
  • No dependencies documented in the issue. None needed -- docs work is independent.

Acceptance Criteria

  • [ ] AC #1: "All port 80 references updated to 3000" -- INVALID. The Dockerfile sets PORT=80 and EXPOSE 80. Port 80 IS the current reality. The spike in pipeline.md recommended switching to 3000 but this has not been implemented. The pipeline.md spike section header falsely claims "Recommendations implemented: palinks uses single-stage build from ruby-rails-build, serves on port 3000, CMD is bundle exec puma." All three claims are wrong: runtime stage uses ruby:3.4.9-slim (not ruby-rails-runtime), port is 80 (not 3000), CMD is rails server (not bundle exec puma).
  • [x] AC #2: "Custom domain status reflects reality (live)" -- verifiable, docs/infrastructure.md already says "Custom domain is live"
  • [x] AC #3: "CLAUDE.md exists with build commands and architecture" -- verifiable
  • [x] AC #4: "docs/ios.md covers Turbo Native workflow" -- verifiable
  • [x] AC #5: "User stories annotated with implementation status" -- verifiable, docs/user-stories.md already annotated
  • [x] AC #6: "1024x1024 app icon included" -- verifiable (file exists, 46k)

Blast Radius

Docs-only ticket. No runtime code changes. No downstream consumers affected. Low blast radius.
One concern: if docs are updated to say port 3000 but the Dockerfile still uses port 80, future agents working on deployment configuration could be misled by the inaccurate docs.

Decomposition Assessment

9 file targets (6 modify + 3 create) across 1 repo. 6 acceptance criteria. Estimated agent work under 5 minutes for docs-only changes. No decomposition needed.

Recommendation

  • [BODY] AC #1 is wrong. The Dockerfile sets PORT=80 -- port 80 is the production reality. Change AC to: "Docs accurately reflect current port configuration" (keep port 80 in docs). Alternatively, create a separate code ticket to implement the spike recommendations (switch Dockerfile to ruby-rails-runtime, port 3000, bundle exec puma) BEFORE this docs ticket updates port references.
  • [BODY] Fix pipeline.md spike section header: "Recommendations implemented" is false. Should read "Recommendations analyzed, implementation pending" or reference a future implementation ticket.
  • [BODY] The three "Files to create" (CLAUDE.md, docs/ios.md, app-icon.png) already exist in commit f602330. If this commit is the implementation of this ticket, the issue should note that. If f602330 predates this ticket, the file targets section should say "modify" not "create."
  • [SCOPE] Create architecture note arch-palinks for component palinks in pal-e-docs.
  • [BODY] Context section claims "nginx is referenced (doesn't exist)" but no nginx references were found in any docs file. Remove or clarify this claim.