UCCO Ops Mode System Brief v1¶

GUIDED + COMPLIANCE Annotation Renderer¶

Date: 15 March 2026, Session 8 Author: Pace (Claude, Anthropic) For: Alex (Claude Code execution)

SURFACE: ops.ucco.foundation (ucco-ops repo)
CLOUDFLARE ACCOUNT: aed3398a4e698767328cc3a9e698721d (FOUNDATION)
DO NOT TOUCH: ucca.online, ops.ucca.online, ir.ucca.online, keys.ucca.online,
              rtopacks.com.au, pr.ucco.foundation, pioneer.ucco.foundation,
              ucco.foundation — or ANY worker/repo on UCCA account e5a9830215a8d88961dc6c80a8c7442a

Context¶

The ops header already has three mode tabs: LIVE, GUIDED, COMPLIANCE. LIVE is functional. GUIDED and COMPLIANCE are stubs. This brief wires them up.

The principle: one surface, three audiences.

LIVE — the operator. Clean workspace. No annotations. This is the default.
GUIDED — the learner. "L Plate" mode. Every element on screen gets a contextual explanation: what it is, why it's there, what to do with it. Turn it on to learn the system, turn it off when you know it.
COMPLIANCE — the auditor. Every element gets a governance anchor: policy reference, framework clause, requirement ID. The auditor sees the same screen the board member uses daily, just with the compliance lens on. The JSON export IS the control register.

Part 1 — Annotation Schema¶

File location¶

Create a directory: src/annotations/

One JSON file per ops section:

src/annotations/
├── foundation.json
├── pioneer.json
├── standard.json
├── compliance.json
├── membership.json
├── infrastructure.json
├── resources.json
└── access-control.json

Schema per element¶

{
  "element_id": {
    "guided": {
      "en": "Plain English explanation of what this element is and what the user should do with it.",
      "zh": "",
      "fr": ""
    },
    "compliance": {
      "ref": "GF-001",
      "title": "Infrastructure Monitoring",
      "clause": "Governance Framework §3.1",
      "summary": "Requires real-time visibility into all foundation infrastructure zones.",
      "framework": "UCCO Governance Framework v1.0"
    }
  }
}

Field definitions:

element_id — stable identifier matching the data-annotation-id attribute on the HTML element. Snake_case, dot-separated hierarchy: section.page.element. Examples: - foundation.overview.zone_health - pioneer.voyager.key_table - membership.press.inbound_requests - infrastructure.surfaces.worker_list

guided — object keyed by locale. en is required. All others optional, empty string = not yet translated. The renderer falls back to en if the user's locale isn't populated.

compliance.ref — short reference ID (e.g., GF-001, INF-003, PIO-004). This is the auditor's anchor.

compliance.title — human-readable policy name.

compliance.clause — specific section/clause reference.

compliance.summary — one sentence explaining WHY this element satisfies the requirement.

compliance.framework — which framework this maps to. Initially "UCCO Governance Framework v1.0". Future: add parallel entries for ISO 27001, NIST, etc.

Multiple framework support (future)¶

When we add additional frameworks, the compliance object becomes an array:

"compliance": [
  {
    "ref": "GF-001",
    "title": "Infrastructure Monitoring",
    "clause": "Governance Framework §3.1",
    "summary": "...",
    "framework": "UCCO Governance Framework v1.0"
  },
  {
    "ref": "A.12.1.3",
    "title": "Capacity Management",
    "clause": "ISO 27001:2022 A.12.1.3",
    "summary": "...",
    "framework": "ISO/IEC 27001:2022"
  }
]

Do NOT build the array version now. Single object is enough. Just don't make architectural decisions that prevent the upgrade later. Use a render function that can handle both shapes.

Part 2 — HTML Element Tagging¶

Every annotatable element in the ops UI needs a data-annotation-id attribute:

<!-- Before -->
<div class="zone-health-card">
  ...
</div>

<!-- After -->
<div class="zone-health-card" data-annotation-id="foundation.overview.zone_health">
  ...
</div>

Tagging rules:

Tag the outermost container of each logical element (card, table, form field, stat block, section header).
Don't tag every <span> and <div> — tag the things a user would point at and ask "what's this?"
Sidebar section headers get tagged: foundation._section, pioneer._section, etc.
Stat cards, data tables, form groups, action buttons, status indicators — all tagged.
The annotation ID is permanent. Once assigned, it never changes, even if the element moves or gets restyled. This is how compliance mappings stay stable across UI revisions.

Starter element list¶

Tag these elements in the current UI. This is the initial set — more will be added as sections are built out.

Foundation: - foundation.overview.zone_health — zone health status cards - foundation.overview.pioneer_stats — pioneer key statistics - foundation.overview.foundation_status — foundation status cards (jurisdiction, incorporation, etc.) - foundation.settings.user_preferences — user preference controls

Pioneer: - pioneer.overview.programme_status — programme overview card - pioneer.voyager.key_table — full pioneer key table - pioneer.voyager.key_stats — aggregate key statistics

Membership: - membership.overview._section — overview section header - membership.outreach._section — outreach section header - membership.broadcast._section — broadcast section header - membership.media_library._section — media library section header - membership.channels._section — channels section header - membership.press.surface_card — press office surface/assets/contact card - membership.press.inbound_requests — inbound media requests table - membership.press.subscriber_stats — press subscriber/asset/photo/document counters

Infrastructure: - infrastructure.surfaces.worker_list — deployed workers table - infrastructure.traffic.analytics — traffic analytics display - infrastructure.github.repo_list — GitHub repository list

Access Control (L1 only): - access_control.members.member_list — board member management table - access_control.members.invite_form — member invitation form - access_control.activity.log_table — activity log

Part 3 — Annotation Renderer¶

Mode state¶

The current mode (LIVE / GUIDED / COMPLIANCE) is already stored somewhere (header tab state). The renderer reads this value.

LIVE mode (default)¶

No annotations rendered. All data-annotation-id elements render normally. No visual change.

GUIDED mode¶

When GUIDED is active:

Find all elements with data-annotation-id on the current page.
For each, look up the annotation in the corresponding JSON file.
If a guided entry exists for the current locale (default en), render an annotation badge.

Annotation badge — GUIDED:

┌─────────────────────────────────────────────────┐
│ ℹ️  Shows the live status of each Cloudflare    │
│     zone. Green = healthy, red = action needed. │
└─────────────────────────────────────────────────┘

Appears directly below (or beside, if space permits) the annotated element
Light blue background (#E8F4FD), subtle border, small text (13px)
ℹ️ icon prefix
Dismissible per-element (small × button). Dismissal state stored in localStorage per user. If a user dismisses an annotation, it stays dismissed across sessions — they've "learned" that element. A "Reset all guided annotations" option in Settings re-shows everything.
Subtle entrance animation (fade in + slight slide down) when GUIDED mode is toggled on

COMPLIANCE mode¶

When COMPLIANCE is active:

Same element discovery as GUIDED.
Look up compliance entry.
Render a compliance badge.

Compliance badge:

┌─────────────────────────────────────────────────┐
│ 🔖 GF-001 · Infrastructure Monitoring           │
│    Governance Framework §3.1                     │
│    Requires real-time visibility into all         │
│    foundation infrastructure zones.              │
└─────────────────────────────────────────────────┘

Appears in the same position as GUIDED annotations
Cream/amber background (#FFF8E7), left border accent in Prussian blue (#01497C)
🔖 icon prefix with the ref ID in bold
NOT dismissible (unlike GUIDED). Compliance annotations are always visible in COMPLIANCE mode. This is the auditor's view — nothing can be hidden.
Each badge is a subtle link/anchor — clicking it could future-link to the governance document. For now, just render the text.

No annotation found¶

If an element has data-annotation-id but no matching entry in the JSON file:

GUIDED mode: Show a grey placeholder: "ℹ️ Documentation pending for this element."
COMPLIANCE mode: Show an amber warning: "⚠️ No compliance mapping yet — [element_id]"

This is intentional. It makes gaps visible. When the auditor toggles COMPLIANCE and sees amber warnings, those are the elements that still need governance mapping. The JSON file becomes a to-do list.

Part 4 — Compliance Export¶

Export button¶

In COMPLIANCE mode, add an "Export" button in the header bar (next to the mode tabs):

[LIVE] [GUIDED] [COMPLIANCE]  [📥 Export]     ◁ Blueprint     08:33 UTC     Tim Rignold · Admin

The Export button is ONLY visible in COMPLIANCE mode.

Export format¶

Clicking Export generates a JSON file download:

{
  "export_date": "2026-03-15T08:33:00Z",
  "framework": "UCCO Governance Framework v1.0",
  "surface": "ops.ucco.foundation",
  "total_elements": 18,
  "mapped_elements": 14,
  "unmapped_elements": 4,
  "coverage_percentage": 77.8,
  "mappings": [
    {
      "element_id": "foundation.overview.zone_health",
      "ref": "GF-001",
      "title": "Infrastructure Monitoring",
      "clause": "Governance Framework §3.1",
      "summary": "Requires real-time visibility into all foundation infrastructure zones.",
      "framework": "UCCO Governance Framework v1.0",
      "status": "mapped"
    },
    {
      "element_id": "membership.broadcast._section",
      "ref": null,
      "title": null,
      "clause": null,
      "summary": null,
      "framework": null,
      "status": "unmapped"
    }
  ]
}

The export IS the control register. Hand it to an auditor. They can see every element, its governance mapping, and which elements still need mapping. Coverage percentage at the top tells them how complete the compliance surface is.

Future: CSV export¶

Add a CSV export option later (auditors love spreadsheets). Not in this brief.

Part 5 — Starter Annotation Content¶

Populate the JSON files with initial annotations for all tagged elements. These are LLM-generated first drafts — the content will be enriched later by a human writer who can contextualise beyond technical descriptions.

For GUIDED annotations: Write clear, plain English explanations. Assume the reader is a board member who is not technical but is intelligent. No jargon. Tell them what the thing is, why it matters, and what (if anything) they should do with it.

For COMPLIANCE annotations: Use placeholder reference IDs in the format GF-NNN (Governance Framework) and INF-NNN (Infrastructure). Write a one-sentence summary of the requirement. These will be mapped to actual governance documents later — the structure matters more than the specific clause numbers right now.

Mark every annotation with a comment: "_draft": true — so we can grep for enrichment-ready entries later.

{
  "foundation.overview.zone_health": {
    "guided": {
      "en": "Shows the live health status of each domain zone managed by the foundation. Green means operational, red means attention needed. You don't need to action anything here — this is for situational awareness.",
      "_draft": true
    },
    "compliance": {
      "ref": "INF-001",
      "title": "Infrastructure Monitoring",
      "clause": "Governance Framework §3.1",
      "summary": "Foundation infrastructure must provide real-time operational visibility to all L1 administrators.",
      "framework": "UCCO Governance Framework v1.0",
      "_draft": true
    }
  }
}

Generate starter content for ALL tagged elements from Part 2. Don't leave any empty.

Part 6 — Layer Interaction¶

L1 (Admin): Sees all three mode tabs. Can toggle freely between LIVE, GUIDED, COMPLIANCE. Sees the Export button in COMPLIANCE mode.

L2 (Board Members): Sees LIVE and GUIDED only. No COMPLIANCE tab. Board members use GUIDED to learn the system (L plates), then turn it off. They don't need the auditor's compliance view. Their mode preference is stored in localStorage.

L3/L4: Not applicable — stub pages only, no mode tabs rendered.

Impersonation: When an L1 admin is viewing as an L2 board member, the mode tabs should show what the L2 member would see: LIVE and GUIDED only. The yellow impersonation bar remains visible but the mode system respects the impersonated layer. This lets the admin verify exactly what the board member's experience is.

Deployment Sequence¶

Element tagging — add data-annotation-id to all listed elements
JSON files — create annotation directory and files with starter content
Renderer — build the annotation overlay system for GUIDED and COMPLIANCE
Mode wiring — connect header tabs to renderer, GUIDED dismissal to localStorage
Export — compliance JSON export button and generator
Layer rules — L2 sees LIVE+GUIDED only, impersonation respects target layer

Each step is independently testable. Don't skip the element tagging — the renderer needs those IDs before anything else works.

The Bigger Picture¶

This is not a help system. This is not a tooltip library. This is a documentation surface that lives on top of the operational surface.

The JSON files are the source of truth. Today they're LLM-generated starters. Tomorrow a governance writer enriches them with real policy language. Next month they get translated. Next year they map to ISO 27001 and NIST controls alongside the foundation's own governance framework.

The ops panel becomes three things at once: - A workspace (LIVE) - A training environment (GUIDED) - An audit surface (COMPLIANCE)

Same screen. Same data. Three lenses. The content is decoupled from the code — anyone with a text editor can enrich the annotations without touching TypeScript.

→ ALEX¶

Create src/annotations/ directory with one JSON file per ops section.
Define the annotation schema exactly as specified in Part 1.
Add data-annotation-id attributes to all elements listed in Part 2. Use the exact IDs specified.
Build the renderer (Part 3): GUIDED shows blue info badges (dismissible, localStorage), COMPLIANCE shows amber policy badges (not dismissible).
Elements with no annotation entry show placeholder badges — grey for GUIDED ("documentation pending"), amber for COMPLIANCE ("no compliance mapping yet").
Wire the Export button in COMPLIANCE mode (Part 4) — JSON download with coverage stats.
Generate starter annotation content for ALL tagged elements (Part 5). Every entry gets "_draft": true.
L2 users see LIVE + GUIDED only. No COMPLIANCE tab. Impersonation respects target layer's mode options.
GUIDED dismissals persist in localStorage per user. Add "Reset guided annotations" in Settings.
The JSON files are the product. Treat them as first-class source files, not config. They will be edited by non-developers.

→ TIM¶

This brief wires up the GUIDED and COMPLIANCE mode tabs that are currently stubs in the ops header.

GUIDED mode puts L plates on everything — every card, table, and control on the screen gets a blue info badge explaining what it is in plain English. Board members use this to learn the system. They can dismiss individual annotations as they learn each element, and the dismissals stick across sessions. It's training wheels they remove themselves.

COMPLIANCE mode puts governance anchors on everything — every element gets an amber badge showing its policy reference, clause number, and a one-sentence explanation of why it exists. Toggle it on and the auditor sees a compliance map of the entire operational surface. Hit Export and they get a JSON file that IS the control register — every element, its mapping, and a coverage percentage showing how complete the governance surface is.

The annotations live in JSON files that anyone can edit with a text editor. Alex generates the first draft. Later, a governance writer or UI writer can enrich them — you hand them the JSON file and a screenshot in GUIDED mode and say "make this better." Translations are just additional locale keys in the same file. The code never changes — only the content.

Brief: UCCO-Ops-Mode-System-Brief-v1 Author: Pace (Claude, Anthropic) Date: 15 March 2026, Session 8 For: Alex (Claude Code execution)