Doctrine & Prototype Boundary
The Q1–Q10 doctrine principles that shape the insigz UX, what is real versus simulated in the prototype, and the development roadmap.
The doctrine principles (Q1–Q10)
These decisions shape the UX; each is encoded in the product, not just stated. They are the load-bearing product convictions — keep them when extending.
| # | Principle | How it shows up |
|---|---|---|
| Q1 | Workspace/Overview is the landing — no vanity "Today" dashboard | /overview is the default authenticated route |
| Q2 | Live by default; time-pinning is explicit and unmistakable | <AsOfControl>: green pulse when live, amber when pinned, one-click ↻ RETURN TO LIVE banner |
| Q3 | No standing cross-tenant staff console; support gets per-incident, time-boxed, named, read-only access | /settings/security · PER-INCIDENT SUPPORT ACCESS grant modal + scope + expiry + revoke; "no cross-tenant staff console exists" |
| Q4 | The wargame is a tenant extension, not core | Sessions/Workshop are per-project surfaces; toggled in project Modes & Surfaces |
| Q5 | No public customer logos by default | customers.html is the "no public references yet — by design" page |
| Q6 | No standalone inject-library surface in the live product | injects authored in Workshop flow into the alert/notification model; surface in the 🔔 inbox |
| Q7 | Reports can stand alone; case-derived is one option of three | + DRAFT REPORT → STAND-ALONE (default) / DERIVED FROM CASE / IMPORTED |
| Q8 | AI supports, never decides; customer-facing artifacts require human approval | AAR PDF export locked until all 5 sections human-approved; agent outputs queue for review |
| Q9 | Onboarding is agent-drafted, human-committed | the Ontology Agent proposes a diff; the Steward approves before anything touches the canonical model; no silent schema changes or entity merges |
| Q10 | Autonomy is bounded and reversible. A watch's agent may act without a human only on internal, reversible state above a confidence threshold; everything customer-facing or irreversible stages for review. | Watch autonomy.auto_allowed_kinds is restricted; the band function and the server both refuse to auto-apply report/customer-facing drafts; every auto-apply is reversible and audited. |
Q8 and Q9 together are the "AI supports, never decides" spine across both the analysis layer (Q8) and the data layer (Q9). Q10 extends that spine from one-off approvals to always-on monitoring (the Autonomy Layer — see 13-autonomy-layer.md): an agent may detect and draft continuously, but a human still commits. The same line runs through the newer surfaces: in the Entity Network (14) an agent-suggested tie renders dashed until a human confirms it; Pattern of Life (15) scores a deviation but the Watch it feeds still stages for a human; and the chat-first experience (16) renders every Q8/Q9/Q10 gate as an inline Accept / Modify / Explain / Show Logic button rather than a separate page — simpler front, identical rigor.
What's real vs. simulated (prototype boundary)
Real and demonstrable now:
- Routing, theme system (dark/light), every UI state and interaction.
- The full Organization → Project → Surfaces model; 7 seed projects with their own sources/cases/reports/sessions.
- MapLibre + Carto basemap with theme-aware styling and
flyTo. - The analyst chat calling Claude (
window.claude.complete) with grounding, citations, provenance drawer, prompt library, projects & history — now the chat-first command surface (16):launch/form/decisionwidgets that commit through the real stores, a six-step journey rail, and canvas pop-outs to map / network / arena. - The Entity Network (14): the
graphDataseam, the 3D force-graph renderer, community/centrality colouring, tie filters, and the geo/timeline views — plus Pattern of Life (15): baseline bands and robust-z anomaly scoring with brush/inspect. - The Ontology Agent 8-stage wizard (seeded), the chat in-progress gate, and wizard persistence.
- The wargame surfaces: sessions list + detail, Workshop editors, AAR drafting with the Q8 export gate + print stylesheet, team-view artboards.
- The control plane (17): the standalone platform-owner console (
insigz Control.html) — fleet overview, tenant detail (instance/usage/contract/support/danger), the provisioning wizard (configure → terraform-style preview → idempotent live run with friendly steps + rawgcloudlog + failure/retry), infrastructure & per-tenant release pinning, billing/finance with margin, support, observability, audit log, RBAC capability-gating, and the break-glass consent gate. - All detail views (session / source / report), all settings sub-routes incl. the security ConfigureModal, the toast/status system, the notification inbox + merge-review, the ⌘K palette.
- localStorage persistence for projects, cases, reports, chats, chat folders, theme, chat panel state, onboarding state.
Deliberately deferred (not bugs):
- Backend + real persistence (all data is mocked in-memory / localStorage).
- Real feed connections (AIS, OFAC, Reuters, Nord Pool, ENTSO-E, ADS-B, PubMed/WHO, …).
- Real cloud provisioning behind the control plane (17) — the provisioning wizard renders the exact
gcloud/Terraform sequence and an idempotent run, but does not execute GCP calls; control-plane metrics (health/usage/cost) are seeded, not streamed; the operator login has no real IdP/IP-allowlist yet; a newly-provisioned tenant isn't written back into the live Tenants list. - Real Claude token streaming (a simulated reveal sits on top of
window.claude.complete); the Ontology Agent's reasoning, schema inference, and the production entity-resolution scoring service. - Real session-join / live multi-user arena (team-view artboards stand in for it).
- Server-side PDF generation (the AAR/report print stylesheet produces a browser-printable window).
- Real Cal.com on
/contact; i18n (English-only by design for the prototype). - The
TESTING_ALL_SURFACES_ONtesting override becomes real per-tenant entitlement. - Settings actions (configure, create-key, invite, plan changes, etc.) confirm via modals/toasts with mock outcomes rather than fully-persisted CRUD.
Development & research roadmap (suggested next moves)
Backend foundation — implement the canonical schema (the Observation contract in 02), the bitemporal store, the provenance signing, and the entity-resolution service (deterministic + probabilistic bands with the MERGE-REVIEW queue).
Agents — wire the four agents to real Claude tool-use against the store: analyst chat (grounded query), Ontology Agent (profile/map/dry-run), Adjudicator (consequence drafting), After-Action (AAR drafting). Keep the human gates (Q8/Q9).
Ingestion — build connectors per source family; the Ontology Agent's stage 2 connector draft becomes a real ingestor scaffold.
Per-tenant deploy — single-tenant provisioning automation; data residency; BYOK; the security posture rows become real controls.
Tighten the prototype — promote the highest-traffic confirming-toast actions (create key, new session, invite) into fully-persisted multi-field forms; add real session-join; add i18n if a non-English customer lands.
Research directions to explore with Claude tools — (a) entity-resolution scoring models and threshold tuning per type; (b) the Adjudicator's consequence-generation prompt + historical-analog retrieval; (c) base-rate benchmarking for the AAR; (d) the Ontology Agent's reuse-vs-new type-matching (embedding + ontology-diff); (e) grounding/citation enforcement and refusal behavior; (f) the bitemporal AsOf query patterns.
This package, plus USE-CASES-AND-FLOWS.md (worked use cases) and the in-product docs.html/knowledge.html, is the complete specification surface for that work.
Design System
A three-mode design system (light, dark, theatre) with type, color tokens, spacing, motion, and component vocabulary for insigz marketing and app.
The Autonomy Layer — Watches, Proposals, Trust Evals & Analyst Studio
How insigz watches the live feed by automating detection and drafting while a human commits, through Standing Watches, a Proposal Inbox, Trust Evals, and Analyst Studio.