node · 2026-06-04 · upd 06-05 documentation public
The basic unit

# 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