Skip to content

Guides

Reference and methodology guides — companions to the design docs (RFCs/ADRs/concept package). Where the design docs argue what and why, guides explain how a topic is approached in practice.

For users

Day-to-day usage:

  • Cookbook — intent-driven worked recipes: "I want X look" → numbered steps. Pulls from the 114-entry vocabulary, 9 named maskdefs, the mask trilogy, and the v1.10.0 workflow primitives. ~60 recipes grouped by genre (cinematic / portrait / landscape / B&W / wildlife / food / mask-driven moves / workflow primitives). The first stop for "how do I do X."
  • Darkroom-session checklist — sequential, checkbox-driven actionable doc for the periodic visual-validation passes. 11 items across 3 batches (v1.10.0 ADRs / v1.10.0 vocab / pre-v1.10 debt). 4–6 hours total; can be split across sessions. Companion: darkroom-session-debt.md for the per-item rationale.
  • Tastes quickstart — your first taste file in 5 minutes; what goes in _default.md, when to add genre files
  • Vocabulary patterns — recipes for combining primitives ("for X intent, reach for Y composition")
  • Visual proofs — auto-generated before/after gallery for every vocabulary entry, rendered against the synthetic ColorChecker + grayscale chart in isolation. For human visual validation that each primitive does what its description claims.
  • Mask-applicable controls — what every vocabulary primitive does through a drawn mask: the engine path, a per-module compatibility matrix, and how to mask an arbitrary primitive (CLI / authoring / Python).
  • Mask shapes from words — the spatial-English-to-mask_spec mapping. "Bottom third" → gradient with anchor at 0.67. RFC-029 / ADR-084 build-by-words reference.
  • LLM vision for masks — the build-by-vision workflow: photographer says "lift the iguana's face," the chat-client LLM looks at the photo and constructs the mask spec. RFC-026 / ADR-086.
  • Recipes / common how-do-I — cross-cutting tasks: reset to baseline, find by tag, export multiple sizes, replay a session

CLI reference (the scripting / agent-loop surface):

  • CLI reference — auto-generated; every verb, every flag, every exit code
  • CLI output schema — NDJSON event format reference for callers that parse --json output
  • CLI env vars — every CHEMIGRAM_* env var the CLI and engine respect
  • config.toml reference — ~/.chemigram/config.toml schema (vocabulary sources, L1 bindings)

For contributors

Authoring vocabulary:

Testing:

  • Standardized testing — companion to RFC-019 / ADR-067. Industry methodology for reference-image validation, the Calibrite ColorChecker reference values, Delta E 2000 interpretation, and synthetic-fixture generation.

Adding a guide

A guide is appropriate when:

  • A topic spans multiple design docs and a single landing reference helps readers connect them.
  • An external standard, methodology, or tooling reference is cited often enough to deserve a curated summary.
  • A how-to is non-trivial and benefits from being a stable, linkable artifact rather than scattered comments.

Conventions:

  • One topic per file. Slug-cased filename.
  • Lead with a one-line summary identifying the design doc this guide companions (if any).
  • Cross-link from the originating RFC/ADR.
  • Treat external references as canonical — link out, don't restate.
  • Group in this index by audience (users vs. contributors), not by alphabetical order.