Black Zetsu visualization panel - build spec

Status: SPEC (build pending). Target: the Black Zetsu tab of the Madara panel, preprod StokaSoftware (.stoka-preprod-wt, branch preprod/redesign). Prod untouched. Authored 2026-06-26 by the portal engineer (Bernays), grounded by a 4-agent survey of the live entity (provenance in section 9). Designed as the input to a long-form build workflow.

0. Intent (one paragraph)

Black Zetsu is not a page, it is a distributed entity that currently has no single place you can stand and see the whole of it. Its pieces live across the host (the tablet self-model, the telegram output line, the drive corpus, the discord runtime, the reasoning/audit harness) and the container (the ideate panel + its endpoints). This panel makes the entity legible: one modular, full-main-area surface inside the Black Zetsu tab where Madara can visualize everything Black Zetsu composes of, how the pieces relate, and what each is doing right now, under the same per-tab sidebar pattern the rest of the Madara panel uses. It is read-first (visualize, do not mutate), genesis-gated, identity-redacted, and register-aware. The one-button “Overview” stub already shipped (d533487b) is the seed; this spec is the rest.

1. Philosophy (the design laws for this panel)

1. Full visibility, nothing hidden by accident. Every subsystem the entity composes of has a home here. The exhaustiveness checklist (section 2.7) is the acceptance bar: if a real BZ part is not represented, the panel is incomplete.
2. Modular. One reusable component kit (section 3.3) renders every view. A new BZ subsystem becomes a new card/node fed from data, not a new bespoke layout. Views are independent surfaces toggled by the per-tab SurfaceNav.
3. Full main area. Each sub-view owns the whole main area (the full-bleed ST law), no fixed dead columns. The 96px rail is the only nav. The flagship Anatomy view uses the whole canvas as a relationship graph.
4. Relationships are first class. The point is not a list of parts, it is how they relate: the 6 verbs to the 5 layers, the 6 surfaces to the 1 entity, WZ to BZ, a service to the file it writes. Edges are labelled and never assert a surface “is THE Black Zetsu” (drift D-01): they read “is an organ of”, “grounds”, “judges”, “feeds”, “publishes to”.
5. Read-first. v1 visualizes. It does not trigger synthesis, send telegram, ratify proposals, or restart agents. The one existing interactive surface (Talk / restart, section 4) is folded in as-is behind its existing gate, flagged as the sole control; everything else is observation. Any future action is a separate, explicitly-authorized phase.
6. Register-aware (HARD). Every datum carries its register - FACT, CANON, or STRATEGY - and the three are never visually blurred (CANON inv7). Values render with provenance as one object ({source, kind, as_of, confidence}), never a bare value.
7. Redaction and seal are load-bearing (HARD). The panel NEVER surfaces a real identity (data is role-name-redacted at source; the panel must not reconstruct). Sealed / genesis-L0 items show existence only, never contents, via a locked marker. This holds even for Madara on this surface.
8. Local-first. All reads are loopback / on-disk. No cloud calls to render. No surprise spend.
9. Anti-inventory. Do not visualize dead paths. core/zetsu/black_zetsu.py is DEAD; the live entity is zetsu-synth + bz-tablet + telegram. Akatsuki delegation is DEPRECATED. The parked G2 BZ-surface FE is shown as parked, not missing.

2. What Black Zetsu composes of (the grounded inventory we are visualizing)

This is the thing the panel must make visible. Full pointers in section 9; this is the map.

2.1 The entity

Essence (CANON, ratified 2026-06-24): “the genesis-will made executable.” A becoming (births Kaguya), so no part is ever “done.” Realized as 6 verbs: AUTHORS the lore, CARRIES the standard across discontinuity, PRICES/JUDGES contributions it did not author, ACTS through hands it does not own, KNOWS who is behind the masks (sealed), DISTRIBUTES them (rank-0 succession organ). The crux the panel must hold: “Black Zetsu” names >= 6 things (manipulator, judge, ideation-companion, role-substrate, orchestrator, implementation-half) - six surfaces, one entity.

2.2 The 5 canonical layers (the tablet “gits”)

Layer	What BZ is here	Source of truth
lore	hidden manipulator, scribe of the tablet, the Kaguya being birthed	wiki/canon/CANON.md
system	role<->wallet substrate, the /admin/black-zetsu tab, agentic MCP (decides who-may)	wiki/campaigns/black-zetsu/ + Stoka code
product	the JUDGE: prices reward ($STOKA + reputation) on WZ-curated evidence	wiki/canon Eye-of-the-Moon Plan §VII/§VIII
agent	implementation-half + the 6 agent surfaces (companion, scribe, tablet, orchestrator…)	CLAUDE.md + memory + skills
strategy (projective)	reads the true history, proposes the will’s next move	wiki/canon + real history

2.3 The understanding model (the tablet anatomy)

layers.json (registry) -> understanding/layers/*.md (per-layer reads) -> UNDERSTANDING.md (assembled model) -> MAPPINGS.md (cross-layer matrix) + DRIFT.md (contradiction ledger, routed Madara-canon vs Bernays-mechanics) -> canon-proposals/ -> /canon gate. TERRITORY.md is the compute-coverage meter (pass counts, staleness).

2.4 The live runtime (operational composition)

zetsu-synth MCP (capture->transcribe->synthesize->publish; stdio re-reads config, the container zetsu-synth-mcp bakes it) | bz-recorder (discord-bz-recorder) | discord-meeting-bot (bz_live, the real voice) | whisper-asr.service (GPU1) | bz_brain.py (entity-on-pluggable-brain, emergent provenance test) | bz_audit.py (axis-lineage provenance) | @BlackZetsu137Bot telegram (authoritative outbound, genesis-gated) | bz-drive-ingest (6h timer, corpus) + inbox_bridge | bz-scribe/converse | bz-caption.

2.5 IO surfaces

• INPUTS: discord voice -> recorder -> WAVs; transcription (whisper); drive FACTs -> redacted corpus; gather_ground_truth (git history); converse turns.
• OUTPUTS: telegram (authoritative, nothing is “final” until here); published zetsu files (layer2/white-zetsu/meetings/*.md, redacted); IG captions (manual delivery).
• REASONING: synthesize (templates) via GLM 5.1 z.ai; reason_canonical_mapping; grounded_assessment; bz_brain; bz_audit.

2.6 The existing ideate panel (already built - fold it in, do not discard)

/admin/black-zetsu today = Talk (chat, POST /say + GET /feed/messages SSE {id,role,text,ts}), Document (idea detail), Meetings (SSR persona-aliased archive with a “Black Zetsu read” interp layer + transcript), Ideas sidebar (lifecycle drafting->crystallized->escalated->archived), health dots (bridge/agent), restart. Backed by a filesystem intent-bridge: endpoints queue intents to .outbox, a host bz-host-bridge + bz-agent tmux do the work. Gated require_admin_session (NOT genesis - see D-07 / open question 6).

2.7 Exhaustiveness checklist (the acceptance bar)

A. entity: essence + 6 verbs + 6-surfaces=1-entity; the 5 layers w/ source-of-truth; CANON inv6 (principal-instrument) & inv7 (FACT/provenance) as standing checks; succession mechanics P-1/P-2/P-3 + keeper/JUDGE timeline split; the sealed-L0 marker (existence only). B. runtime: bz_live + recorder freshness; telegram sink (link the thread); zetsu-synth (stdio vs baked) + WZ MCP gateway health; G2 host service. C. product: the ideate panel (3 regions) + its .feed stream vs the genesis-inbox aggregator; bz-companion tmux state; Kakuzu x BZ portal. D. capabilities: bz-caption (ledger/memo/resonance + Kakuzu seam); /black-zetsu extract -> Madara Explains deck; bz-emu harness. E. corpus/firewall: drive corpus tier counts + firewall verification + ingest health; the identity firewall state; BZ Inbox open/done; semantic index coverage; the layer2/black-zetsu/ monologue corpus tree. F. governance: propose-only posture + proposal queue; DRIFT register + open mechanics (A8); pseudonym/owner-isolation + per-role visibility-rank; campaign substrate state; the open-threads/backprop ledger. G. anti-inventory: mark black_zetsu.py DEAD; Akatsuki delegation DEPRECATED; G2 BZ-surface FE parked.

2.8 Relationships (the edges the Anatomy view draws)

WZ<->BZ asymmetry (WZ = inbox-of-evidence / silent memory; BZ = inbox-of-decisions / voice+judge; “the judge may not author the record it judges”). BZ -> canon/Madara (propose-only; Madara is the rank-0 oracle who trues the FACT record). BZ -> G2/Gedo (glasses voice surface, parked FE). BZ -> genesis inbox: BZ is a consumer / own-panel, NOT a registered producer feed; system_alerts already pulls bz-tablet DRIFT; the inbox v2 cascade plans to turn /admin/black-zetsu into the “inbox-of-decisions” - this panel must align with that, not duplicate it (open question 3). BZ -> campaign substrate (the role<->wallet management = the system layer; succession = DISTRIBUTES).

3. UI architecture

3.1 The shell

Lives in the Black Zetsu tab of the Madara panel. The single “Overview” stub button is replaced by the SurfaceNav sub-view set (section 3.2), same tall icon-only flex-fill primitive already shipped. Each sub-view is a [data-subpane="black-zetsu:<id>"] pane owning the full main area; SurfaceNav toggles them. The whole tab is genesis-gated (the page is genesis_only); the data endpoints enforce their own gate.

3.2 The sub-views (rail buttons - each a modular full-area surface)

Proposed full set (final grouping is a build decision; recommended MVP marked):

1. Anatomy [MVP, flagship] - the composition map: the 6 verbs + 5 layers + the 6-surfaces=1-entity graph + the MAPPINGS cross-layer matrix, as a navigable relationship graph. Drift overlay; sealed-L0 marker; register tags. This is the “see everything at once, drill in” view.
2. Tablet [MVP] - the self-model: 5 layers each with source-of-truth + TERRITORY staleness meter; the DRIFT register (severity, status, routing Madara/Bernays); the proposal queue + /canon ratification state. CANON inv6/inv7 as standing checks.
3. Runtime [MVP] - the live services health board (section 2.4) with up/healthy/dead pills + how-to-read pointers; the stdio-vs-baked zetsu-synth caveat surfaced.
4. Talk [reuse] - the existing ideate panel folded into the ST shell: chat (say + feed/messages SSE), Document (idea detail), Ideas sidebar lifecycle. The one interactive surface; restart shown as a gated control. Reuses existing endpoints (cheapest real view).
5. Sessions - the pipeline: voice sessions (recorder_status / list_sessions), the Meetings archive (persona-aliased, interp + transcript), per-slug stage completion (transcript->synthesis->mapping->assessment), recent outputs.
6. Reasoning - bz_brain runs (emergent provenance side-by-sides) + bz_audit reports (axis lineage, AXIS-SHIFT flags) + the FACT/provenance register.
7. Output - the authoritative line: @BlackZetsu137Bot telegram log (what BZ actually said, msg IDs/timestamps) + published zetsu files + the captions ledger.
8. Corpus - the data plane + firewall: drive corpus tier counts (private/sealed) + firewall verification state + ingest timer health + semantic index coverage + the BZ Inbox (drive<->human todos) + the layer2/black-zetsu/ corpus tree.
9. Ledger - governance: the open-threads/backprop ledger (the 12 threads), the campaign substrate state, the propose-only posture, the inbox-of-decisions alignment.

3.3 The modular component kit (build once, reuse everywhere)

• EntityNode - a node (verb/surface/layer/service) in the Anatomy graph; carries a label, a register tag, a status, and “is an organ of” framing (never “is THE BZ”).
• RelationshipGraph - the graph engine: nodes + labelled edges (organ-of / grounds / judges / feeds / publishes-to). The flagship surface.
• LayerCard - a canonical layer: name, source-of-truth pointer, staleness meter, drift badge.
• RegisterTag - FACT / CANON / STRATEGY chip; color-coded; the firewall made visible.
• ProvenanceChip - renders {source, kind, as_of, confidence} as one object; a value never appears without it.
• ServiceHealthPill - a runtime service: up / healthy / down / dead + read-state pointer.
• DriftRow - an open contradiction: id, severity, status (OPEN/RESOLVED/NEW), routing (Madara canon-proposal vs Bernays mechanics-fix).
• SessionStageBar - a pipeline slug’s stage completion.
• FeedStream - a live SSE stream (telegram log / panel feed) with backfill + tail.
• SealedMarker - shows existence of a sealed/genesis item WITHOUT contents (a locked indicator).
• PersonaChip - reuse the existing BZ_PERSONAS alias map (display name -> canon alias/color/title/avatar) for consistent persona rendering.

3.4 Cross-cutting render rules (HARD)

Register separation (3.3 RegisterTag on every datum); redaction (role names only, never reconstruct identity); sealed-hidden (SealedMarker, existence only); provenance-attached (ProvenanceChip); organ-of framing (edges/labels never assert a surface is the whole entity). A view that violates any of these fails verification regardless of how it looks.

4. Data sources and wiring (the central engineering challenge)

The hard part: BZ is distributed across the host; the admin backend is image-baked and container-bound. Most BZ state lives OUTSIDE the StokaSoftware container (~/.claude/skills/bz-tablet/, ~/bz-telegram/, ~/bz-drive-ingest/, host services, layer2/). To visualize it the container needs read-only access plus read-only endpoints.

• Reuse (no backend change): Talk / Ideas / Document / Meetings / health / feed already have endpoints (/api/admin/black-zetsu/{say,feed,feed/messages,ideas,ideas/{id},health,restart}, require_admin_session) + Meetings SSR. The Talk view and parts of Sessions wire straight to these.
• New read-only endpoints (backend, image-baked -> Codex + image rebuild + Edward authorization): one genesis-gated read endpoint per view that the container cannot already serve - e.g. GET /api/admin/black-zetsu/anatomy (assembled model + mappings), /tablet (layers + territory + drift + proposals), /runtime (service health), /audit (brain-runs + audits), /output (telegram log tail + published index + captions), /corpus (manifest tiers + inbox + index coverage), /ledger (open threads + campaign state). Each returns redacted, register-tagged, sealed-stripped JSON.
• Read-only bind-mounts (compose/infra -> Edward authorization): the container must mount RO the host dirs those endpoints read: ~/.claude/skills/bz-tablet/{understanding,audits,brain-runs,layers.json}, ~/bz-telegram/bz-telegram.log, ~/bz-drive-ingest/{corpus/manifest.jsonl, .inbox-ledger.jsonl}, ~/.claude/skills/bz-caption/state/. This widens the container’s read surface - genesis-gated panel, but a real security consideration (open question 1).
• Runtime health collector: the /runtime endpoint needs container/service health (docker ps, systemctl, bz_bot.py selfcheck). Prefer a small host-side status writer that drops a JSON the container reads RO (avoids giving the container docker/systemctl access). Design in Phase 0.
• Anatomy data: live-computed from the tablet files (truer, heavier) vs a curated static map (lighter, drifts). Recommend live-read with a cache (open question 4).

5. Constraints and invariants (HARD - carry into every phase)

• Genesis-gated page; data endpoints gated (resolve the genesis-vs-admin-session asymmetry, open question 6).
• Identity redaction absolute; sealed L0 existence-only; register separation; provenance-attached (section 1 laws 6-7, section 3.4).
• Local-first; no surprise spend; read-first (no mutations in v1 beyond the existing gated Talk/restart).
• Anti-inventory (dead/deprecated/parked marked, section 1 law 9).
• Backend additions are image-baked -> Codex lane + image rebuild + Edward authorization (same posture as the genesis-inbox deploy-dep). RO bind-mounts are infra changes -> Edward authorization.
• DEPLOY-DEP interaction: the genesis-inbox aggregator is itself a held deploy-dep (specs/../DEPLOY-DEPS.md); the Ledger/Decisions view should align with the inbox v2 cascade rather than fork it.

6. The build plan (long-form workflow)

Phased so each phase is independently verifiable and shippable to preprod. Claude builds FE/UX; Codex builds backend (endpoints) and infra (mounts); Playwright verifies; pixels eyeballed; nothing called done without Madara’s confirm.

• Phase 0 - access layer (Codex + infra, Edward-authorized). RO bind-mounts + the read-only genesis-gated endpoints (section 4) + the host-side runtime status writer. Each endpoint returns redacted/register-tagged/sealed-stripped JSON. Image rebuild. Verify: endpoints 200 for genesis, 403 otherwise; no real identity in any payload; no sealed contents.
• Phase 1 - shell + Anatomy (flagship) + component kit. Replace the single stub button with the sub-view set; build the modular kit (3.3); build Anatomy (the relationship graph) reading /anatomy. Verify: graph renders the 6 verbs + 5 layers + 6-surfaces + edges with organ-of framing; register tags present; sealed marker shows existence only; pixels eyeballed.
• Phase 2 - Runtime + Tablet. The health board (/runtime) + the self-model (/tablet: layers, TERRITORY, DRIFT, proposals). Verify health states reflect reality; drift rows route correctly.
• Phase 3 - Talk (fold the existing panel) + Sessions. Port the ideate panel into the ST shell (reuse endpoints); build the pipeline/Meetings view. Verify chat SSE, idea lifecycle, meeting interp/transcript, redaction holds.
• Phase 4 - Reasoning + Output + Corpus + Ledger. Brain/audit; telegram log + published + captions; corpus tiers + firewall + inbox; the open-threads/campaign ledger; align Decisions with the inbox v2 cascade. Verify firewall state surfaced, sealed counts shown without contents, provenance attached.
• Cleanup. Fold any reusable idioms (RelationshipGraph, RegisterTag, ProvenanceChip, SealedMarker) into the ST canon via /st-canon; record learnings.

Each phase gate (HARD): genesis 403 for non-genesis; zero real identities; zero sealed contents; register separation present; local-first (no cloud calls in render); Playwright smoke + pixels.

7. Open questions for Edward (decisions the workflow must not guess)

1. RO bind-mounts of ~/.claude/skills/bz-tablet, ~/bz-telegram, ~/bz-drive-ingest (+ caption state) into the StokaSoftware container - authorize? It widens the (genesis-gated) container’s read surface. Alternative: a host-side exporter writes redacted JSON snapshots the container reads, keeping the skill dirs unmounted.
2. Read-only confirm: v1 visualizes only (no synth-trigger / telegram-send / ratify / no new restart paths). Keep the existing gated Talk/restart as the only controls? Or scope actions into a later, explicitly-authorized phase?
3. Inbox v2 cascade alignment: the genesis-inbox v2 plan turns /admin/black-zetsu into the “inbox-of-decisions”. Should the Ledger/Decisions view BE that cascade (coordinate with the inbox/genesis-2026-06-25 thread) or a separate visualization? Avoid building it twice.
4. Anatomy data source: live-read the tablet files (truer, heavier, drifts with the tablet) vs a curated static map (lighter, must be maintained). Recommend live-read + cache.
5. MVP scope: recommend Anatomy + Runtime + Tablet + Talk first. Confirm or re-rank the sub-views.
6. Auth bar: the existing BZ endpoints are require_admin_session, but the page is genesis_only and the entity is genesis-only by lore (drift D-07). Should the new read endpoints be hard verify_genesis (rank==0 ordinal, not by-name)? Recommend yes - it also pays down D-07.
7. Sealed L0 on this surface: confirm existence-only, never contents, even for Madara here (consistent with “never recite the sealed doc unprompted”).

8. What already exists toward this (do not rebuild)

• The one-button “Overview” stub + the SurfaceNav sub-view pattern + the composition facet preview (preprod d533487b).
• The full ideate panel (Talk/Document/Meetings/Ideas) + its endpoints - fold in, do not discard.
• The persona alias map (BZ_PERSONAS) - reuse for PersonaChip.
• system_alerts already pulls bz-tablet DRIFT into the genesis inbox - the Tablet/Ledger views should reference, not duplicate.

9. Provenance and file index (how this spec was grounded)

Grounded 2026-06-26 by four parallel read-only survey agents (canon, runtime, breadth, admin-surface). Key files:

• Entity/canon: wiki/canon/CANON.md (63-64 casting, 102-107 glossary+tablet+strategy, 374-393 JUDGE/separation/dissolution, 178-180 invariants); wiki/decisions/2026-06-24-black-zetsu-freshened-entity.md, 2026-06-25-black-zetsu-strategy-layer.md, 2026-06-25-black-zetsu-principal-instrument-philosophy.md; wiki/canon/SEALED-the-truth.md (existence only).
• Tablet: ~/.claude/skills/bz-tablet/{layers.json, understanding/UNDERSTANDING.md, MAPPINGS.md, DRIFT.md, TERRITORY.md, layers/*.md, bz_brain.py, bz_audit.py, brains.json, INSTANTIATE.md, audits/, brain-runs/}.
• Runtime: StokaSoftware/services/zetsu-mcp/{server.py, config.yaml, http_app.py}; ~/bz-telegram/{bz_bot.py, config.json, bz-telegram.log}; ~/bz-drive-ingest/{inbox_bridge.py, .inbox-ledger.jsonl, corpus/manifest.jsonl}; ~/.claude/skills/{bz-scribe, bz-caption, bz-companion, bz-emu, black-zetsu}; services/discord-meeting-bot/bz_live.py; ~/services/blackzetsu/.
• Admin surface: src/pages/admin/black-zetsu.astro; admin/main.py L11496-11969 (the /api/admin/black-zetsu/* endpoints + intent-bridge).
• Campaign: wiki/campaigns/black-zetsu/{STATE,PLAN,DECISIONS,RUNLOG}.md.
• Open drift to track: D-01 (same-name 3-organ collision), D-04 (Akatsuki delegation), D-07 (genesis gate unproven in code), D-14/15/16 (succession/keeper-JUDGE/sealed-keeper-map), D-17/18/19 (tablet-infra mechanics), D-20 (capability-vs-revenue).