From 947f860bc00d9c919e2d27d65047bec01c209489 Mon Sep 17 00:00:00 2001 From: S'Bussiso Dube <80188685+Sbussiso@users.noreply.github.com> Date: Wed, 9 Sep 2026 18:45:38 -0700 Subject: [PATCH] Docs: make the project map true, and label the orphaned specs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Checked the docs against the filesystem rather than reading them, on the theory that a map is worth exactly what its worst entry is worth. AGENTS.md's Project Structure documented **12 frontend files that do not exist**: LandingPage, DocsPage, SecurityPage, LegalPage, SentinelPage, PublicLayout, LandingNav, LandingFooter, DocsDiagrams, EmptyState, and a DocsPage test. They are the public marketing site, which moved to the standalone site at sentinel-command.com and left the map behind. This is the worst place in the doc set to be wrong. The project map is the first thing a developer or an LLM reads to orient, and a third of the frontend section was fiction — so the reader's first act is to look for files that aren't there, and their conclusion is that the docs cannot be trusted. Rewritten from the real tree, which also captures two structural changes that were never recorded: the Sentinel agent's config UI now lives in McpPage.jsx (there is no SentinelPage), and AdminPage gained the motion history tab. The tests/ listing was equally stale — it named three files and there are thirteen. The backend half of the map was accurate and is untouched. Separately, docs/image-specs/ is 2.1 MB across 17 files that NOTHING in this repository references. They fed DocsDiagrams.jsx, which left with the marketing site, and several still say "SourceBox Sentry" in their titles. I did not delete them: whether the standalone site regenerates from these or holds its own copies is not knowable from here, and the safe wrong answer is cheaper than the unsafe one. Added a README stating what they are, why they are orphaned, and the question whose answer decides their fate — so the next person inherits a decision rather than a mystery. Co-Authored-By: Claude Opus 5 --- AGENTS.md | 79 +++++++++++++++----------------------- docs/image-specs/README.md | 17 ++++++++ 2 files changed, 49 insertions(+), 47 deletions(-) create mode 100644 docs/image-specs/README.md diff --git a/AGENTS.md b/AGENTS.md index 06c17ea6..059d09bc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -223,62 +223,47 @@ docs/ # Supplementary docs that don't belong in READ frontend/ ├── tests/ # vitest + @testing-library/react + happy-dom -│ ├── setup.js # @testing-library/jest-dom matchers + cleanup +│ ├── setup.js # jest-dom matchers + cleanup │ ├── sanity.test.js # runner + DOM + matcher wiring smoke +│ ├── auth/local.test.jsx # self-hosted login + background token refresh │ ├── services/api.test.js # fetchWithAuth shape contract (4 wire shapes) -│ ├── components/ # DocsDiagrams, UpgradeModal, EmptyState -│ └── pages/DocsPage.test.jsx # split structural smoke (every section id renders) +│ ├── components/ # IncidentReportModal, UpgradeModal, OrgAuditLogPanel, +│ │ # InstallCameraNodeCard, CameraRecordingControls, HelpTooltip +│ └── pages/ # IncidentsPage, SettingsPage (camera groups), SignInPage (local) └── src/ ├── pages/ - │ ├── LandingPage.jsx # Public landing page - │ ├── DashboardPage.jsx # Camera grid with status cards + controls - │ ├── SettingsPage.jsx # Nodes, groups, recording, danger zone - │ ├── McpPage.jsx # MCP keys (scope picker) + activity (live SSE) - │ ├── IncidentsPage.jsx # AI- and human-filed incident reports + create flow - │ ├── AdminPage.jsx # Stream logs, MCP activity, audit trail - │ ├── PricingPage.jsx # Public pricing tiers - │ ├── SecurityPage.jsx # Public privacy + security claims page (/security) - │ ├── SentinelPage.jsx # Sentinel agent dashboard — config (triggers, - │ │ # schedule, cooldown, scope), run history, - │ │ # manual "Run now" - │ ├── LegalPage.jsx # /legal/:page — Terms, Privacy, etc. - │ ├── DocsPage.jsx # /docs — slim composition shell that renders 19 sections - │ ├── docs/ # one file per
on /docs (extracted from the - │ │ # 1,747-line monolith); shared state lives in - │ │ # docs/context.jsx (DocsProvider + OsTabs + useDocs) + │ ├── DashboardPage.jsx # Camera grid with status cards + controls + │ ├── SettingsPage.jsx # Nodes, groups, recording, notifications, danger zone + │ ├── McpPage.jsx # MCP keys (scope picker) + activity (live SSE), AND the + │ │ # Sentinel agent surface: config, run history, manual + │ │ # "Run now", per-org `osa_` agent keys + │ ├── IncidentsPage.jsx # AI- and human-filed incident reports + create flow + │ ├── AdminPage.jsx # Stream logs, org audit, MCP activity, motion history + │ ├── IntegrationsPage.jsx # Home Assistant integration keys + │ ├── PricingPage.jsx # Plan tiers + upgrade │ ├── SignInPage.jsx / SignUpPage.jsx - │ └── TestHlsPage.jsx # Admin-only HLS debug view - ├── components/ - │ ├── HlsPlayer.jsx # HLS.js player with Clerk JWT xhrSetup - │ ├── CameraCard.jsx # Live thumbnail + status + actions - │ ├── IncidentReportModal.jsx # Markdown + evidence viewer + │ └── TestHlsPage.jsx # Admin-only HLS debug view + ├── components/ # 27 files; the ones worth knowing: + │ ├── HlsPlayer.jsx # hls.js player with Clerk JWT xhrSetup + │ ├── CameraCard.jsx # Live thumbnail + status + actions + │ ├── AppSidebar.jsx # Nav + plan badge + viewer-hours usage panel + │ ├── MotionEventsPanel.jsx # Motion history (Admin → Motion tab) + │ ├── OrgAuditLogPanel.jsx # Org audit trail (Admin → Organization Audit) + │ ├── IncidentReportModal.jsx # Markdown + evidence viewer │ ├── NotificationBell.jsx # Unread badge + inbox popover (SSE-fed) - │ ├── AddNodeModal.jsx # Node creation flow (shows one-time API key) + │ ├── AddNodeModal.jsx # Node creation flow (shows one-time API key) │ ├── KeyRotationModal.jsx # Rotate node API key - │ ├── UpgradeModal.jsx # Paywall prompt (plan gating) - │ ├── HeartbeatBanner.jsx # "Waiting for first heartbeat" banner shown - │ │ # after node creation; polls /api/nodes/{id} - │ │ # until it sees a last_seen, persists its - │ │ # dismissed state in localStorage - │ ├── WelcomeHero.jsx # Dashboard empty-state hero — exports - │ │ # AdminWelcomeHero (3-step "set up your first - │ │ # camera" checklist) and MemberWelcomeHero - │ │ # (capability-focused welcome for non-admins) - │ ├── Layout.jsx / PublicLayout.jsx - │ ├── LandingNav.jsx / LandingFooter.jsx - │ ├── ToastContainer.jsx / LoadingSpinner.jsx - │ ├── DocsDiagrams.jsx # 8 inline-SVG diagrams embedded on /docs - │ │ # (System Architecture / HLS Pipeline / Motion FSM / - │ │ # Config Precedence / Incident Lifecycle / MCP Workflow / - │ │ # Security Model rings / Dashboard IA tree) - │ └── EmptyState.jsx + │ ├── UpgradeModal.jsx # Paywall prompt (plan gating) + │ ├── HeartbeatBanner.jsx # "Waiting for first heartbeat" after node creation + │ └── WelcomeHero.jsx # Dashboard empty-state hero (admin + member variants) + ├── auth/ # Clerk / local-auth provider switch (VITE_AUTH_PROVIDER) ├── hooks/ - │ ├── useNotifications.jsx # SSE inbox + unread count - │ ├── useMotionAlerts.jsx # Motion SSE + toast fan-out - │ ├── usePlanInfo.jsx # Plan info + node quotas - │ ├── useSharedToken.jsx # Shared Clerk token provider (HLS + fetch) + │ ├── useNotifications.jsx # SSE inbox + unread count + │ ├── useMotionAlerts.jsx # Motion SSE + toast fan-out + │ ├── usePlanInfo.jsx # Plan info + node quotas + │ ├── useSharedToken.jsx # Shared token provider (HLS + fetch) │ └── useToasts.jsx - └── services/api.js # Typed client for every backend endpoint + └── services/api.js # Typed client for every backend endpoint ``` ## Architecture diff --git a/docs/image-specs/README.md b/docs/image-specs/README.md new file mode 100644 index 00000000..db22474f --- /dev/null +++ b/docs/image-specs/README.md @@ -0,0 +1,17 @@ +# Image specs — status: orphaned, kept deliberately + +JSON generation specs for the marketing and documentation diagrams (system architecture, HLS pipeline, motion FSM, incident lifecycle, MCP workflow, security model, dashboard IA, plus hero and OG-card art). + +**Nothing in this repository references them.** They were consumed by `DocsDiagrams.jsx`, which rendered eight inline SVGs on `/docs` — and that component, along with the whole public site (`LandingPage`, `DocsPage`, `SecurityPage`, `LegalPage`), moved to the standalone site at sentinel-command.com. The specs stayed behind. + +They also predate the rename: several carry `"SourceBox Sentry"` in their `meta.title`. + +## Why they're still here + +Deleting 2.1 MB of unreferenced files is easy; deleting the only copy of the design source for diagrams the marketing site still displays is not recoverable from this repo. Whether the standalone site regenerates from these or has its own copies is not knowable from here. + +**If you own the standalone site:** confirm where its diagrams come from. If it has its own copies, delete this directory — it is dead weight and its brand strings are wrong. If it regenerates from these, move them there and delete this directory anyway, so the specs live beside the thing that renders them. + +Either way this directory should not exist long-term. It is kept only because the safe wrong answer (keep) is cheaper than the unsafe one (delete). + +*Assessed 2026-09-09.*