Review: Render docs/ markdown + mermaid at -docs URL

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type -- Feature
• [x] Lineage -- Standalone
• [x] Repo -- ldraney/pal-enterprises
• [x] User Story -- present, well-formed
• [x] Context -- present, adequate
• [x] File Targets -- 4 files listed
• [x] Acceptance Criteria -- 5 criteria
• [x] Test Expectations -- present
• [x] Constraints -- present
• [x] Checklist -- present
• [x] Related -- present

Traceability

• [x] story:sso-gateway label -- Single login grants access to all platform tools
• [x] story note verified -- found in project-pal-enterprises user-stories section (row: sso-gateway, role: Authenticated user)
• [x] arch:rails-app label -- Rails application component
• [ ] arch note MISSING -- [SCOPE] Create architecture note arch-rails-app for component rails-app
• [x] Forgejo issue -- https://forgejo.tail5b443a.ts.net/ldraney/pal-enterprises/issues/8, open

File Targets

• [x] app/controllers/docs_controller.rb -- to be created, does not exist yet (correct)
• [x] app/views/docs/ -- to be created, directory does not exist yet (correct)
• [x] config/routes.rb -- verified exists, no /docs route present yet (correct)
• [x] Gemfile -- verified exists, no markdown gem present yet (correct)
• [x] docs/ content files -- verified: README.md, onboarding.md, architecture.md, dashboards.md all present
• [ ] docs/ mermaid content -- NOTE: no docs currently contain mermaid diagrams, so AC #3 (mermaid rendering) cannot be visually validated against existing content. Consider adding a sample mermaid block to one doc file, or noting this limitation.

Repo Placement

Dependencies

• No blocking dependencies on the board. This ticket is independent of other backlog items.
• Auth infrastructure (Keycloak OIDC, require_login pattern) already exists and is in done column (Phase 3: Keycloak OIDC authentication, item #1180).
• No test directory exists (test/ and spec/ both missing). The Test Expectations section references bin/rails test but no test infrastructure is set up. The implementing agent will need to create the test directory and test helper as part of the work, or this should be a separate prerequisite ticket.

Acceptance Criteria

• [x] AC1: /docs renders docs/README.md as index -- verifiable via integration test
• [x] AC2: /docs/:slug renders individual docs -- verifiable via integration test
• [ ] AC3: Mermaid diagrams render -- NOT verifiable against current docs content (no mermaid blocks exist). Agent can verify mermaid.js is included in the view, but cannot confirm visual rendering without test content.
• [x] AC4: Route behind Keycloak auth -- verifiable via redirect test for unauthenticated user
• [x] AC5: Navigation between docs -- verifiable via link presence in rendered HTML

Blast Radius

• No existing markdown rendering or file-serving patterns in the app. This is net-new functionality.
• Security risk: the docs controller will read files from disk based on user-supplied slugs. Path traversal protection is not mentioned in Constraints or AC. The implementing agent must sanitize the slug parameter to prevent directory traversal attacks.
• No downstream consumers affected -- this is a new route.

Decomposition Assessment

Recommendations

• [BODY] Add acceptance criterion: "Requests for slugs containing path traversal sequences (e.g., ../) return 404 or 400, not file contents outside docs/"
• [BODY] Add constraint: "Sanitize slug parameter to prevent directory traversal -- reject any slug containing .., /, or characters outside [a-z0-9_-]"
• [BODY] Note in Test Expectations that test/ directory does not exist yet and must be created (or rely on Rails generator defaults)
• [SCOPE] Create architecture note arch-rails-app for component rails-app
• [SCOPE] The convention convention-client-project-structure referenced in Context and Related does not exist in pal-e-docs. Create it or update the reference.