The Node

Every piece of work in Streetlight is a folder of exactly four files: two surfaces (one per audience) and two signals (a state machine and a ledger). No central database — each node is self-routing and self-auditing.

The four files

■ surface · human ■ surface · agent ■ signal · state ■ signal · ledger

<slug>.html

The human-facing, self-contained, beautiful page. Exactly one per node.

<slug>.md

The agent-facing summary. Self-titled so [[wikilinks]] resolve uniquely vault-wide. Carries Tags: + cross-links.

feedback.md

A single-state token — empty / 👍 / 👎 / comment. Never an event log.

provenance.md

An append-only audit trail. Never rewritten, never deleted.

feedback.md — the state machine

One file, exactly one value at a time. The state is the content — no timestamps, no mtime checks, no race conditions.

Update 2026-06-05: the 👎 (bare "redo") state was removed from the viewer — there is no thumbs-down button. Every refactor signal now carries steering as a comment. Three states remain.

State	Means	Written by
empty	"showme" — not yet reviewed	agent (after refactor) / default
👍	resting state, no work owed	human, via viewer
comment	refactor signal with steering	human, via viewer
👎	bare refactor signal — removed 2026-06-05; use a `comment`	—

The human writes empty → {👍/comment} in one replace-write. The next agent draining the queue reads a comment, rewrites the HTML + MD, records both halves in provenance (verbatim feedback + the fix), then truncates feedback back to empty. 👍 has no edge out — it rests until overwritten. The whole refactor queue is one grep:

grep -l 'comment' nodes/**/feedback.md

feedback.md as a state machine — the human pushes empty into 👍 (rests) or comment; only comment has an edge back, through an agent refactor that truncates to empty. The dashed 👎 box is the retired bare-redo state.

provenance.md — the audit log

Every agentic session that touches the node appends one entry — <timestamp> <verb> [context] plus an indented body. Nothing is overwritten. It answers why does this node look the way it does now?

provenanceagent semantics — the why behind every refactor

gitfile bytes — the what of every diff

feedbackpending human signal — the what's owed

Three files, three questions, no overlap. The viewer renders provenance as a colored timeline via the zero-dep local-viewer/provenance-render.mjs.

Synthesizes the former node-anatomy + the-feedback-loop + provenance-trail docs. Part of the 5-node public-doc synthesis (2026-06-04). · ← Overview