Product specification · PMs and engineers implementing against a contract

OBS-001 · Light Station Product specification v0.2.0 Reference implementation

Operator Console Specification

Authoritative summary of what Light Station is, what it does, and what it explicitly does not do. Light Station observes Vigil governance and relays Steward commands — it does not evaluate proposals or issue verdicts.

Source binding ✓ reconciled

Bound to: lightstation-docs @ v0.2.0 · API_CONTRACT.md · WATCHSTATION_PRD_v3.md
Scope: Product requirements summary. Full source docs on GitHub.
Author: Stephen Sweeney

Light Station does not govern. A console outage does not weaken enforcement. Vigil continues to evaluate proposals and deny unauthorized actions independently of whether the operator is watching.

Vigil jurisdiction spec →

Architecture overview → Full source docs ↗

Product definition

Light Station (product name; repo: LightStation) is the Principal interface for Vigil-governed autonomous agents. It is a locally-hosted web application that surfaces governance state, approval queues, sprint-scoped work authorization, audit trails, and the knowledge substrate the agent navigates.

Two load-bearing pillars

Governance observability

The Principal sees what the agent is doing, what Vigil has decided, what requires human judgment, and what the budget and enforcement posture look like at any moment.

Knowledge substrate

Structured context the agent navigates — goals, constraints, prior decisions, operational history. With the governed write path, the agent proposes memory; the Principal commits.

Non-goals

Light Station does not	Rationale
Modify Vigil governance policy	YAML config is edited directly in Vigil
Orchestrate agents	Observes and relays Steward commands only
Issue verdicts	Evaluation is Vigil's exclusive authority
Host in the cloud (MVP)	Local only; Tailscale for remote access
Support multi-user access (MVP)	Single Principal operator
Override governance when disconnected	Fail-closed; no "proceed anyway"

Personas

P1 · Principal at desk

Full-density operator

MacBook or Mac mini. Full-screen browser. Reviewing sprint progress, reading audit trails, updating the knowledge chart, dispatching missions. Wants density and detail across all 13 views.

P2 · Principal in field

Mobile approver

iPhone via Tailscale. Agent hit an approval gate. Reviews the suspended action, approves or rejects in two taps. Time-scarce — critical information above the fold on a 390pt screen.

P3 · The agent

Briefing API consumer

Not human, but a real consumer of Light Station outputs. Reads structured briefing before sessions. Proposes memory candidates for Principal review. Quality of output proportional to knowledge substrate quality.

Feature inventory

Thirteen lighthouse views, each mapping to a distinct governance or knowledge function. Canonical naming per the lighthouse metaphor.

View	ViewId	Acceptance summary
Lantern Room	`lantern`	Enforcement badge, budget gauge, pending approvals, active sprint, recent events, chart status
Lookout	`lookout`	Live SSE event stream; filterable by agent, law, verdict; virtual scroll for 10k+ entries
Clearance	`clearance`	HOLD items within 5s via SSE; approve/reject with mandatory reason on reject; STEWARD attribution
Logbook	`logbook`	Write-once steward record; auto-ingest on significant events; no update/delete endpoint
Ledger	`ledger`	Hash-chained audit log proxied from Vigil; searchable, replayable
Chartroom	`chartroom`	Knowledge graph (Landmark / Chart / Sounding); Memory Proposals with per-edge accept/reject
Beacon	`beacon`	AI-assisted Signal intake; severity triage; suggests route — never auto-acts
Sounding Report	`sounding`	Deep research briefs; promotable from Logbook or Beacon
Voyage	`voyage`	Kanban sprint board; authorization is explicit Principal act
Manifest	`manifest`	Ticket CRUD; atomic unit of authorized work
Crew	`crew`	Agent roster and status from Vigil `/agents`
Provisions	`provisions`	Token budget console; Normal → Degraded → Gated → Halted ladder
Registry	`registry`	Vigil configuration viewer (read-only)

Principle 9 — The agent proposes; the Principal commits. Memory Proposals, Signal Cards, and Clearance decisions all follow this pattern. The agent or system suggests; only the Principal authorizes state changes.

Vigil contract

Light Station consumes Vigil's HTTP governance contract via interface.ts — the language boundary seam between TypeScript and Swift. The mock client (VIGIL_MOCK=true) must never break; it enables offline development and CI.

Environment

Variable	Default	Purpose
`VIGIL_BASE_URL`	`http://127.0.0.1:18820`	Vigil daemon endpoint
`VIGIL_MOCK`	`false`	Use mock client for dev/CI
`VIGIL_API_KEY`	—	Optional Bearer auth
`PORT`	`7789`	Light Station API port

Legacy CLAWLAW_* env aliases remain supported. VIGIL_* takes precedence when both are set.

Verdict mapping

Vigil decision	Light Station verdict	Operator surface
`allow`	ALLOW	Lookout (observe)
`deny`, `reject`	DENY	Lookout, Ledger
`escalate`	HOLD	Clearance (resolve)
(informational)	INFO	Lookout, Logbook auto-ingest

Upstream endpoints consumed

Endpoint	Purpose
`GET /health`	Connectivity check
`GET /governance/state`	Enforcement level, budget, queue depth
`GET /queue`	Pending HOLD approvals
`POST /queue/:id/approve\|reject`	Steward decision relay
`GET /audit`	Hash-chained decision log
`POST /budget/increase\|reset`	Budget management
`GET /agents`	Agent roster
`POST /sprint/authorize`	Sprint authorization (audit in Vigil)
`GET /events` (SSE)	Real-time governance event stream

Light Station API (canonical)

Routes mount at /api/{viewId}. Deprecated aliases (/api/queue, /api/watchlog, etc.) supported for one release.

Fail-closed contract. When Vigil is unreachable, routes return 502 with { "error": "Vigil unreachable" }. The UI shows a Disconnected banner. No stale approval data is served as current.

Knowledge model

The knowledge substrate is a relational graph — not a filing cabinet. Three layers organize information by permanence and authority.

Layer	Role	Write authority
Landmark	Immutable reference points — goals, constraints, constitutional facts	Principal only
Chart	Operational context — current state, active decisions, working knowledge	Principal; agent via proposals
Sounding	Deep research — promoted from Logbook or Beacon when warranted	Principal promotion

Governed write path

1Agent proposes kg_proposal with proposed edges via Briefing API context

2Proposal appears in Chartroom Proposals tab

3Principal reviews per-edge accept/reject

4On approve → kg_node and kg_edges created

5Briefing API returns recentlyCommittedProposals to agent on next session

Logbook discipline

Logbook entries are write-once. No update or delete endpoint exists. Significant governance events (DENY, HOLD, enforcement transitions, budget thresholds at 80/90/100%) auto-ingest via the State Bridge. Principal may promote entries to Sounding layer.

Beacon & Sounding

v0.2.0 adds AI-assisted intake modules. Both follow Principle 9: propose routes, never auto-act.

Beacon · Signal intake

Raw inbound text analyzed by LLM. Creates Signal Cards with severity (ADV / WARN / CRIT / EMER). Suggested routes: create ticket, propose knowledge, log to watchlog, or dismiss. Principal selects action.

Sounding · Research briefs

Deep research on a topic. Generated from Beacon escalation or Logbook promotion. Stored in research_briefs. Available in Chartroom as Sounding layer nodes.

Data model

SQLite via better-sqlite3. Schema source of truth: src/server/db/schema.ts. Deliberate choice: single-user, local, zero infrastructure.

Table group	Tables	Purpose
Work management	`sprints`, `tickets`, `ticket_events`, `ticket_comments`	Sprint board and ticket lifecycle
Knowledge graph	`kg_nodes`, `kg_edges`, `kg_fts`, `kg_proposals`, `kg_proposed_edges`	Chartroom substrate and governed write path
Steward record	`watchlog_entries`, `steward_actions`	Write-once logbook; local approve/reject record with Vigil audit linkage
AI intake	`signal_cards`, `research_briefs`	Beacon and Sounding modules
Agent context	`agent_briefing_timestamps`	Per-agent briefing cursor for session continuity

Multi-table writes must use db.transaction(). Schema must stay synchronized between schema.ts (boot) and migrate.ts (existing databases).

Invariants & QA

P0 invariants are release gates. Violation of any invariant is a blocker.

INV-01 Light Station outage does not weaken Vigil enforcement

INV-02 Vigil unreachable → 502 on queue routes; Disconnected banner; no stale queue data

INV-03 Logbook is write-once — no update or delete endpoint

INV-04 Every Steward action recorded with STEWARD attribution and Vigil audit linkage

INV-05 No governance override controls in the UI — agent cannot bypass Vigil via console

INV-06 Reject in Clearance requires mandatory reason field

INV-07 Signal/Beacon never auto-acts — Principal commits all routes

INV-08 Mock client path must never break CI (VIGIL_MOCK=true)

Test tiers

Tier	Environment	Scope
Automated	CI	Vitest (12 suites), typecheck, lint, Playwright E2E
Tier 1 · Mock	`VIGIL_MOCK=true`	~16 manual cases — all views, queue, proposals, fail-closed
Tier 2 · Live	Vigil on :18820	5-experiment demo, live approve/reject, kill-Vigil disconnect test

Pre-release P0 gate target: under 45 minutes. Full manual test catalog (~80 cases) and traceability matrix live in the repository under docs/qa/.

Version & status

Attribute	Value
Version	v0.2.0
npm package	`steward-desk`
Repository	github.com/stephen-sweeney/lightstation-docs
Jurisdiction	Vigil · OBS-001
Deployment	macOS launchd + Tailscale (Forge lab)
Contract version	API Contract v1.0.0 (Vigil v0.6.1+)

Shipped vs deferred

Shipped · v0.2.0	Deferred
13 lighthouse views	Plugin architecture (post-core-ship)
Beacon / Signal intake	Native iOS/macOS app
Sounding research briefs	Multi-user / team access
Memory Proposals governed write path	Cloud hosting
Live + mock Vigil integration	K3s cross-runtime observability
5-experiment deterministic demo	Audit log virtual scroll above ~50k entries

Architecture overview → Source repository ↗