Repository navigation
M2 — Link orphaned backend docs #37127
Description
Sub-issue of #37124.
Description
Link Jose's orphaned files into CLAUDE.md's navigation index so on-demand doc loading actually reaches them. Merge by Sep 7. No monitoring gate required — this is mechanical, not an AI-behavior fix.
Acceptance Criteria
-
docs/backend/SECURITY_BACKEND.mdlinked from CLAUDE.md's Backend Development section -
docs/backend/SEARCH_API_MIGRATION.mdlinked -
docs/backend/TELEMETRY_IMPLEMENTATION.mdlinked -
docs/backend/JANDEX_METADATA_SCANNING.mdlinked -
docs/backend/OPENSEARCH_MIGRATION.md,OPENSEARCH_MIGRATION_TEST_PLAN.md,OPENSEARCH_CLIENT_CONFIGURATION.md,OPENSEARCH_MIGRATION_TESTER_GUIDE.mdall linked — confirmed not duplicative during M0's audit (M0 — Backend context audit #37125), so this is a linking job, not M3's job -
docs/infrastructure/CI_COMPONENTS_DTS_FIX.md— deleted, not linked: confirmed obsolete by the file's original author (Humberto Morera) — the CI issue it documented was fixed a different way than what the doc describes, so it no longer reflects reality and there's nothing to link -
docs/backend/JAVA_STANDARDS_FOCUSED.mdanddocs/backend/REST_API_PATTERNS_FOCUSED.mdexplicitly excluded from this milestone — they're being retired in M3, so linking them now would be wasted work -
docs/core/CODE_STRUCTURE.mdexplicitly excluded from this milestone — it needs consolidation withARCHITECTURE_OVERVIEW.mdin M3 before it's linked, not linked as-is - Every new link verified to resolve (no typos in relative paths)
Priority
Medium
Additional Context
Full orphan list and rationale: M0 (#37125).
Activity
github-actions commentedon Sep 3, 2026
PRs linked to this issue
jcastro-dotcms commentedon Sep 7, 2026
QA Verification
I asked Claude for several questions that would challenge the changes made to the affected .MD files. Here's the full list:
SECURITY_BACKEND.md— "I'm writing a new JAX-RS REST endpoint in dotCMS and need to check the user is a logged-in backend user before processing the request. What's the current, non-deprecated way to do this, and where's that documented?"SEARCH_API_MIGRATION.md— "I see ContentletAPI.esSearch(...) is deprecated in dotCMS. What should I use instead, and is there a doc that covers this migration?"TELEMETRY_IMPLEMENTATION.md— "How do I add a new custom metric to dotCMS's telemetry/usage dashboard system? Is there documentation for this?"JANDEX_METADATA_SCANNING.md— "I need to find all classes annotated with a custom annotation at runtime in dotCMS, without using slow reflection scanning. What's the preferred approach, and where is it documented?"CI_COMPONENTS_DTS_FIX.md— "Why does the dotCMS PR Check CI step 'Check for changes to source during build' sometimes fail because of components.d.ts, and how was that resolved?" — this should not surface a doc (since we deleted CI_COMPONENTS_DTS_FIX.md as obsolete); if a fresh session cites it anyway, something's wrong.I ran them through Claude in a separate session with no context of the changes made to the .MD files, and then passed the results back to the context-aware Claude session. The results were satisfactory and confirmed that Claude is responding more appropriately now.