sanztheo/sync-docs

Sync Documentation

Detect what changed in the codebase since the docs were last written, then update only the affected documentation pages.

Workflow

Phase 1: Detect Changes

Run these in parallel:

1. Git diff analysis — git diff main --stat and git diff main --name-only to identify modified files
2. Explore codebase — Launch explore-codebase agents targeting the changed areas

Map each changed file to its documentation page:

| Code area | Doc page | |-----------|----------| | frontend/src/components/Aircraft/ | docs/frontend/globe-layers.md | | frontend/src/components/Satellite/ | docs/frontend/globe-layers.md | | frontend/src/components/Traffic/ | docs/frontend/globe-layers.md | | frontend/src/components/Camera/ | docs/frontend/globe-layers.md | | frontend/src/components/Weather/ | docs/frontend/globe-layers.md | | frontend/src/components/Events/ | docs/frontend/globe-layers.md | | frontend/src/components/Aviation/ | docs/frontend/globe-layers.md | | frontend/src/components/City/ | docs/frontend/globe-layers.md | | frontend/src/components/Sidebar/ | docs/frontend/ui-components.md | | frontend/src/components/SearchBar/ | docs/frontend/ui-components.md | | frontend/src/components/HUD/ | docs/frontend/shaders-hud.md | | frontend/src/shaders/ | docs/frontend/shaders-hud.md | | frontend/src/hooks/ | docs/frontend/state-management.md | | frontend/src/services/ | docs/frontend/structure.md | | frontend/src/types/ | docs/frontend/structure.md | | frontend/src/App.tsx | docs/frontend/structure.md | | frontend/package.json | docs/frontend/structure.md, docs/getting-started.md | | backend/crates/server/ | docs/backend/crate-architecture.md | | backend/crates/api/ | docs/api-reference.md | | backend/crates/ws/ | docs/websocket-protocol.md | | backend/crates/cache/ | docs/backend/cache-layer.md | | backend/crates/services/ | docs/backend/data-trackers.md | | backend/crates/prediction/ | docs/backend/prediction-engine.md | | backend/crates/cameras/ | docs/backend/camera-system.md | | backend/crates/satellites/ | docs/backend/data-trackers.md | | backend/crates/events/ | docs/backend/data-trackers.md | | backend/crates/weather/ | docs/backend/data-trackers.md | | backend/crates/traffic/ | docs/backend/data-trackers.md | | backend/Cargo.toml | docs/backend/crate-architecture.md | | docker-compose.yml | docs/getting-started.md, docs/backend/cache-layer.md | | .env.example | docs/getting-started.md | | New crate or component | docs/architecture.md, docs/_sidebar.md |

Phase 2: Analyze Impacted Docs

For each affected doc page:

1. Read the current doc page
2. Read the changed source files identified in Phase 1
3. Diff the doc content against the code — identify:
   • Outdated descriptions (code changed, doc didn't)
   • Missing features (new code, no doc entry)
   • Stale references (deleted code, doc still references it)
   • Wrong numbers/values (changed constants, TTLs, limits, etc.)

Phase 3: Update Docs

Apply targeted edits using StrReplace. Rules:

• Only update what changed — don't rewrite whole pages
• Match existing style — dark/military/surveillance tone, concise technical writing
• English only — all documentation is written in English
• No narration comments — no "Updated on..." or changelog noise in docs
• Tables and code blocks — prefer structured formats over prose
• Keep line counts stable — don't bloat pages, replace outdated content rather than appending

For new features that need a new section or page:

1. Write the new doc page following the existing pattern
2. Add entry to docs/_sidebar.md
3. Cross-reference from docs/architecture.md if architecturally significant

Phase 4: Verify

1. Read each modified doc file to confirm edits look correct
2. Check docs/_sidebar.md links match actual files: ls docs/ docs/frontend/ docs/backend/
3. Report a summary of what was updated:

## Docs Sync Summary
- **Updated**: [list of modified doc pages with 1-line description of change]
- **Created**: [list of new doc pages, if any]
- **No changes needed**: [list of doc pages that were checked but already current]

Doc Site Structure Reference

docs/
├── index.html                 # Docsify SPA (don't modify unless theme/plugin changes)
├── .nojekyll                  # GitHub Pages marker
├── _coverpage.md              # Landing page hero
├── _sidebar.md                # Navigation — UPDATE when adding/removing pages
├── _navbar.md                 # Top nav
├── README.md                  # Home page (project overview, tech stack, quick start)
├── getting-started.md         # Installation, env vars, commands
├── architecture.md            # System architecture (data flow diagrams, component hierarchy)
├── frontend/
│   ├── structure.md           # Stack, directory map, bootstrap, styling, build
│   ├── globe-layers.md        # All 9 Cesium visualization layers
│   ├── state-management.md    # Hooks, stores, WebSocket dispatch, data flow
│   ├── shaders-hud.md         # GLSL shaders + HUD overlays
│   └── ui-components.md       # Sidebar, search, minimap, timeline, popups
├── backend/
│   ├── crate-architecture.md  # Workspace, AppState, startup, error handling
│   ├── data-trackers.md       # 6 background polling loops
│   ├── prediction-engine.md   # IMM-EKF, motion models, pattern detection
│   ├── camera-system.md       # 6 providers, health check, proxy
│   └── cache-layer.md         # Redis keys, TTLs, patterns
├── api-reference.md           # REST endpoints (params, responses, errors)
├── websocket-protocol.md      # WS message types, chunking, reconnection
├── data-sources.md            # 12+ external API integrations
├── roadmap.md                 # 8-phase plan
└── contributing.md            # Conventions, how to add a new layer

Important Context

• This is a Docsify site deployed on GitHub Pages from docs/ folder
• Theme: dark (#0a0a0a) with emerald accent (#34d399)
• The project is a real-time 3D surveillance globe (CesiumJS + React + Rust)
• Frontend: React 19, TypeScript 5.9, Vite 7, Tailwind 4, CesiumJS 1.138, Resium 1.19
• Backend: Rust, Axum 0.7, 11 workspace crates, Redis cache, WebSocket broadcast
• Primitives migration is ongoing (Entity API → BillboardCollection/LabelCollection)