CLI Visual Studio & Interactive TUI Subsystem Operational Architecture Guide

Overview

The CLI Visual Studio & Interactive TUI Subsystem (cmd/zqk/ui) provides the primary real-time operational interface and visual observation membrane for the ZQK Knowledge Kernel. It unifies three complementary operational modalities into a single command surface:

  1. Interactive Full-Screen Mission Control Terminal UI (TUI): Powered by the terminal engine (pkg/tui), providing real-time telemetry, mutation stream visualization (WAL), audit event inspection, swarm coordination telemetry, and system health status.
  2. Headless Model Projection Engine: Emits instant structured JSON, JSONL, or YAML snapshots of kernel state for programmatic consumption by scripts, CI/CD runners, and autonomous AI agents without allocating terminal file descriptors.
  3. Embedded Web Visual Studio (--web): Spawns an in-process HTTP dashboard server (pkg/studio) featuring dynamic port conflict auto-probing, real-time REST telemetry endpoints, and signal-driven graceful shutdown.

Whether an operator is interactively triaging project state or an autonomous agent is capturing a structured snapshot of system health, the UI subsystem provides consistent, high-performance, and non-blocking access to kernel telemetry.


Subsystem Command Taxonomy

The UI subsystem is exposed through the root zqk ui command and two canonical aliases:

zqk ui [flags]
zqk dashboard [flags]
zqk console [flags]

Command Flags & Defaults

Flag Shorthand Type Default Description
--web -w bool false Launch the embedded Web Visual Studio HTTP server instead of the terminal TUI.
--port -p int 8080 Port for the Web Visual Studio server. Auto-probes port..port+15 unless explicitly set.
--tab -t string seismograph Initial active tab view in the interactive TUI or headless snapshot.
--format -f string table Output format: table (interactive TUI), json, jsonl, or yaml.

Tab View Taxonomy

The UI model exposes 8 specialized observability lenses across the knowledge kernel:

Tab Identifier Number View Title Telemetry Domain
seismograph 1 Seismograph Real-time state mutation stream (WAL), shockwaves, and drift metrics.
state 1 State Engine In-flight mutations, buffer depth, auto-scroll status, and WAL events.
audit 2 Audit Stream Security audit events, authorization boundaries, and command traces.
swarm 3 Swarm Mesh Active agent seats, claimed tasks, instruction queues, and throughput hints.
pm 4 Program Management Goals, priority plans, workstreams, backlog items, and blockers.
metrics 5 Metrics & TSDB Time-series telemetry, storage volume, file descriptors, and hygiene stats.
scheduler 6 Scheduler Daemons Background daemons (ambient, fswatcher, steward, etc.) and scheduled jobs.
qa 7 QA & Verification Test cases, criteria satisfaction chains, DoD compliance, and regressions.
health 8 System Health Integrity radar, active violations, daemon run-states, and remedy action items.

Core Architecture

The UI subsystem coordinates interaction between user requests, the active project context, storage providers, and rendering targets:

flowchart TD
    User["Operator / AI Agent / Browser"] --> Dispatch["cmd/zqk/ui.NewUICmd()"]
    Dispatch --> Proc["cli.WithProcessor() Context Resolution"]

    Proc --> Branch{"Execution Mode?"}

    subgraph WebMode["Embedded Web Visual Studio (--web)"]
        Branch -->|"--web flag present"| WebInit["studio.NewServer(projectRoot)"]
        WebInit --> PortCheck{"Explicit --port?"}
        PortCheck -->|Yes| BindExplicit["server.Start(127.0.0.1:port)"]
        PortCheck -->|No| ScanPorts["Port Scanner (8080..8095)"]
        BindExplicit --> WaitSig["signal.NotifyContext(SIGINT, SIGTERM)"]
        ScanPorts --> WaitSig
        WaitSig --> GracefulShutdown["server.Shutdown(opCtx)"]
    end

    subgraph HeadlessMode["Headless Model Projection (--format json|yaml)"]
        Branch -->|"Structured Format"| ModelInit["tui.NewUIModel(projectRoot, tab)"]
        ModelInit --> RefreshDomain["Domain Refreshes (Mutations, Objects, QA, Swarm, PM, Health)"]
        RefreshDomain --> FormatOut["cli.FormatOutput(cmd, m)"]
    end

    subgraph TUIMode["Interactive Terminal UI (Default)"]
        Branch -->|"Default (table)"| TermCheck{"Terminal Allocated?"}
        TermCheck -->|Interactive TTY| RawTerm["SetupRawTerminal() + Bubbletea Loop"]
        TermCheck -->|Non-Interactive| SingleFrame["Single-Shot Render Frame to os.Stdout"]
    end

1. Interactive Terminal UI Engine (pkg/tui)

When executed in a standard terminal without --web or structured formatting, the subsystem invokes tui.RunTUI:

  • Terminal Setup: Detects terminal capabilities via term.IsTerminal(). When running interactively, puts the terminal into raw mode (SetupRawTerminal) and queries terminal dimensions (term.GetSize).
  • Non-Interactive Fallback: If standard input or output is not a terminal (e.g., inside CI scripts, piped commands, or automated testing harnesses), the engine gracefully falls back to generating a single-shot formatted frame directly to standard output without attempting raw terminal control.
  • Navigation Controls:
  • 1-8 or Tab: Switch active lenses (State, Audit, Swarm, PM, Metrics, Sched, QA, Health).
  • ↑ / ↓: Navigate active lists, mutations, or backlog items.
  • Enter: Inspect selected object detail or trigger diagnostic view.
  • r: Force instant cache refresh across all kernel telemetry providers.
  • q or Ctrl+C: Restore terminal state cleanly and exit.

2. Web Visual Studio Server (pkg/studio)

When invoked with --web, the command switches to HTTP daemon mode:

  • Server Construction: Instantiates an embedded HTTP server bound to the local loopback address (127.0.0.1).
  • Port Conflict Scanning:
  • Default Port Range: If no explicit --port is supplied, the server attempts port 8080. If 8080 is occupied, it automatically increments through ports 8081 up to 8095 (port+15), logging an advisory notice to the console once bound.
  • Explicit Port Enforcement: If --port is explicitly set by the operator, automatic fallback is disabled; if the specified port is occupied, the command immediately halts fail-closed with an actionable collision message.
  • Signal Trapping & Graceful Shutdown: Intercepts os.Interrupt (SIGINT) and syscall.SIGTERM via signal.NotifyContext. Upon receipt of a termination signal, the server executes server.Shutdown(ctx) with the operation context, releasing socket listeners and flushing background telemetry buffers before exiting cleanly.

3. Headless Structured Model Projection

When --format json, --format jsonl, or --format yaml is specified, the subsystem activates the headless pipeline:

  • Bypasses terminal allocation and server startup.
  • Synthesizes an in-memory tui.UIModel seeded with the target project root and tab identifier.
  • Executes synchronous domain telemetry refreshes:
  • RefreshMutations(): Aggregates real-time write-ahead log entries and mutation rates.
  • RefreshAuditEvents(): Loads security and operational audit records.
  • RefreshObjects(): Scans object counts and ontological classification totals.
  • RefreshQA(): Evaluates requirement-to-criteria chains, DoD gates, and test case pass rates.
  • RefreshHealth(): Checks active kernel violations, stale lock counts, and daemon run-states.
  • RefreshSwarm(): Summarizes active priority plans, agent instructions, and throughput indicators.
  • RefreshPM(): Aggregates backlog status tallies (draft, planned, in-progress, completed, blocked).
  • RefreshMetrics(): Collects TSDB time-series points, storage volumes, and file descriptor hygiene.
  • RefreshScheduler(): Scans registered background daemons and autonomous jobs.
  • Emits the complete synthesized snapshot via cli.FormatOutput(cmd, m).

Operational Workflows & CLI Recipes

Recipe 1: Launching Interactive Mission Control

Start the interactive full-screen dashboard starting on the default Seismograph view:

# Standard interactive launch
zqk ui

# Using canonical aliases
zqk dashboard
zqk console

Recipe 2: Launching Directly into a Specific Lens

Open the terminal console directly focused on System Health, Swarm Coordination, or Program Management:

# Jump directly to system integrity and daemon health
zqk ui --tab health

# Jump directly to swarm mesh and agent instruction status
zqk ui --tab swarm

# Jump directly to program management and backlog breakdown
zqk ui --tab pm

Recipe 3: Starting Web Visual Studio with Automatic Port Resolution

Launch the embedded web dashboard with automatic port fallback across 8080..8095:

# Start Web Studio on 127.0.0.1 (auto-scanning from 8080)
zqk ui --web

# If port 8080 is occupied, automatically selects 8081:
# â„šī¸  Port 8080 was in use; automatically selected port 8081 (use --port / -p to override)
# ⚡ ZQK Knowledge Kernel Visual Studio running at http://127.0.0.1:8081 (Press Ctrl+C to stop)

Recipe 4: Binding Web Studio to a Dedicated Port

Enforce a specific port with immediate fail-closed error reporting if in use:

# Bind strictly to port 9090
zqk ui --web --port 9090

# Using shorthands
zqk ui -w -p 9090

Recipe 5: Programmatic State Ingestion for AI Agents & Automation

Capture a structured telemetry snapshot in JSON or YAML for machine parsing:

# Output full kernel state snapshot as JSON
zqk ui --format json

# Extract health summary and violation counts with jq
zqk ui --format json --tab health | jq '.healthsummary'

# Output snapshot as YAML for human review or CI logging
zqk ui --format yaml --tab qa

Verification & Statement Coverage Invariant

The ZQK Knowledge Kernel enforces strict test-driven development (TDD) and verification invariants across all CLI subsystems:

  • Statement Test Coverage Floor: The cmd/zqk/ui package is bounded by a mandatory \(\ge 85.0\%\) statement test coverage gate.
  • Current Verification Benchmark: Elevated to 90.9% statement test coverage across all execution paths, port collision loops, headless projection routines, and signal handling boundaries.
  • Three-Fold Verification Proof: 1. Static Floor Invariant: Command construction, aliases (dashboard, console), flag configurations (--web, --port, --tab, --format), and default values are verified structurally. 2. Operational Dynamic Proof: Interactive TUI fallback execution, all 8 tab lens initializations, Web Studio server instantiation, automatic port probing (8080..8095), structured format serialization (json, yaml, jsonl), and context format inheritance are verified on hermetic isolated project fixtures. 3. Negative Adversarial Boundary: Port conflict detection on explicit ports, total port exhaustion across the entire fallback range, invalid flag syntax, and graceful context cancellation/SIGTERM termination are verified fail-closed without resource leaks.

Autonomous Agent Integration (AGENTS.md)

When autonomous AI agent swarms operate inside a ZQK repository, they are bound by the Universal Agent Directives:

Headless Telemetry Rule: Autonomous agents operating in headless environments MUST NOT invoke zqk ui without --format json or --format yaml. Because agent execution environments lack interactive TTY allocation, running in interactive mode relies on single-shot fallback rendering. For deterministic agent decision-making and telemetry ingestion, agents MUST supply --format json to receive strongly typed, parseable kernel state projections.