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.

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

Milestone vernacular

M13 / M14 / M15 / M16 / Path C — decoded once

expand

M13 · Path C / Skills realignment: Day 5 (2026-04-25). Retired the flat bl-skills read_only memory store and moved skill content onto the Anthropic Skills primitive (description-routed) plus eight reference Files mounted at session create. Older docs that name bl-skills predate this.
M14 · Substrate-hook (LMD trigger): Day 6 morning (2026-04-26). Closed-loop response: LMD post_scan_hook adapter, the bl trigger verb, vendored alert_lib + tlog_lib, cPanel Stage 4 ModSec userdata, unattended-mode tier gate. Closed with the v0.4.0 version bump.
M15 · Live-API correctness: Day 6 afternoon (2026-04-26). Eight phases of drift remediation against the live Anthropic API: archive-not-delete retire verb, POST-with-CAS agent updates (not PATCH), sessions.create field rename agent_id → agent, environments body shape correction. v0.5.0 stamps on this.
M16 · Collectors + bridge + adapter: Day 6 evening (2026-04-26). Five phases that close the curator-prescription → collector-execution loop: modsec parser fix, cron --from-file fixture adapter, session-event → memstore-pending bridge, writeback emits user.custom_tool_result, args translator + 11 per-verb observe adapters. Two sentinel/FP cycles applied. Ships at v0.6.0; 399/399 hermetic on debian12 + rocky9.
Path C · Skills + Files architecture: The shipped skill-delivery shape: 6 description-routed routing Skills + 8 reference Files mounted at /skills/<basename>. Path A would have been the read_only memstore (retired on M13); Path B (callable_agents hunters) was deferred for API stability. Path C is what shipped.

Full milestone arc · M0–M16 on the Build Timeline

Reference

First-class quick-lookup surfaces. Every verb, every flag, every config primitive bl reads. Start here if you're integrating bl into existing tooling.

CLI Reference

Every verb, every flag, every exit code. Nine verbs (observe, consult, run, defend, clean, case, setup, trigger, flush) with synopsis, sub-commands, examples, tier classification, and cross-references. The first place to look when integrating bl into existing tooling.

/blacklight/docs/cli

Configuration Reference

Every config primitive bl reads. Environment variables (ANTHROPIC_API_KEY + BL_* overrides), /etc/blacklight/blacklight.conf allowlist, the state.json schema, /var/lib/bl/ layout, and the precedence rules between them.

/blacklight/docs/configuration

Architecture

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

Architecture

Three-layer contract, Runner / Curator / Substrate. Layer boundary rules. Path C primitives map. Polled-async runtime. The nine-verb command surface and bash SDK.

/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

Path C / M13: six description-routed Skills, eight reference Files mounted at session create, the 70-file research substrate. The retired bl-skills memstore explained in place.

/blacklight/docs/skills

Operating

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

Setup Flow

Authoritative call sequence for `bl setup`. CAS-versioned agent updates, archive-not-delete retire, the M15 live-API corrections, idempotency, --sync delta.

/blacklight/docs/setup-flow

Security Model

Auth surface, prompt-injection fence, agent output validation, dual-write operator ledger. The threats blacklight bounds, 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

Anthropic API Notes

Operator-log of Managed Agents friction hit during the build, ten observations against the live `managed-agents-2026-04-01` beta, severity-tagged, with the compressed-timeline caveat called out up front.

/blacklight/docs/anthropic-api-notes

Build History

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

Roadmap (FUTURE.md)

Capability-driven roadmap beyond v0.6.0. Five phases, operational hygiene, detection breadth, fleet operation, skill extensibility, commercial control plane, and the phase gates that move work between them.

/blacklight/docs/roadmap

Build Timeline

How v0.6.0 unfolded. Six days, 296 commits, the v1→v2 pivot, the M0–M16 milestone arc, off-plan triage cycles, day-by-day commit + session-log volume.

/blacklight/docs/timeline

Pivot Moments

How blacklight got to its current shape. Hunter-dispatch cut, single-curator collapse, the API-surface migration mid-build, the things we'd do differently.

/blacklight/docs/pivots

Built with Claude Code

Provenance, how the v0.6.0 codebase, the skills bundle, and a verified live-trace shipped during a six-day hackathon. Patterns, anti-patterns, what we'd do differently.

/blacklight/docs/build-with-claude