Documentation

Architecture decisions, design specs, and the pivot moments that shaped how blacklight builds. Authored alongside the source, every claim grep-cites a file in the repo.

8 docsDESIGN.md (canonical)github.com/rfxn/blacklight

Architecture

The shape of the system. What blacklight is, the layer boundaries, and the contracts that bind them.

Architecture

The three-layer contract: bash on the host, Managed Agent session, defensive primitives. Layer boundary rules, runtime flow, and the full command namespace.

/blacklight/docs/architecture

Action Tiers & Safety Gates

Five tiers, read-only, auto, suggested, destructive, unknown. Agent-authored, runner-enforced. Every gate behavior, every backup contract.

/blacklight/docs/action-tiers

Skills Architecture

Operator-voice markdown loaded as read-only memory at session creation. Authoring discipline, third-party extensibility, the index of all 20 domains.

/blacklight/docs/skills

Operating

How blacklight runs in production. Setup, evidence formats, security model.

Setup Flow

Authoritative call sequence for `bl setup`. Agent create, environment, two memory stores, skills sync. Idempotency contract. --sync delta-detection.

/blacklight/docs/setup-flow

Security Model

Auth surface, prompt-injection hardening, agent output validation, operator ledger. The threats blacklight defends against, including the curator itself.

/blacklight/docs/security-model

Evidence Format

JSONL on the wire, bundle shape, summary.md convention. How raw logs reach the curator without raw logs reaching the curator.

/blacklight/docs/evidence-format

Build History

How the project got to its current shape. The pivots that mattered, the build provenance, the patterns and anti-patterns.

Pivot Moments

How blacklight got to its current shape. Hunter-dispatch cut, single-curator collapse, the API-surface migration mid-build.

/blacklight/docs/pivots

Built with Claude Code

Provenance: how a 1000-line bash Runner, 65 skill files, and a verified live-trace shipped during a hackathon. Patterns, anti-patterns, what we'd do differently.

/blacklight/docs/build-with-claude