Chris Sells
d2f87d50de
* docs(pipeline): pin the generated CLI docs to the released bd; repair main's CLI reference The #4874 squash-merge raced the docs-autofix bot: the bot had pushed a regeneration from main's source onto the PR branch, so the squash landed a contradictory mix — the release-aligned hand-written docs plus a CLI reference re-documenting unreleased commands and flags, with docs.json referencing four pages (heartbeat, migrate-personal, reclaim, unclaim) whose files do not exist. That broken nav fails the docsync guard on main and on every branch cut from it. This restores the intended end state of #4874 and lands the pin that prevents the race from recurring. - Regenerate the CLI reference from a bd built from the v1.1.0 tag (CI's canonical pure-Go build), removing the unreleased commands/flags and fixing the dangling nav entries. - docs/cli-docs.pin names the release tag; scripts/resolve-docs-bd.sh builds and caches a canonical pure-Go bd from that tag, fetching the tag first in shallow CI checkouts. - generate-cli-docs.sh, check-doc-flags.sh, and check-cli-docs-drift.sh resolve bd through the pin and ignore a supplied binary while pinned (BD_DOCS_IGNORE_PIN=1 bypasses), so the drift gates and the autofix bot now enforce docs-match-release instead of docs-match-main. - tools/docsmint detects the pre-overhaul Docusaurus staging layout that bd <= v1.1.0 emits and converts it to the generic form before its normal Mintlify transform (tested); removable once the pin reaches a release whose emitter writes build/cli-docs. - check-doc-flags.sh: run without timeout(1) on macOS instead of failing Check 4. - Decision record: engdocs/decisions/2026-07-17-docs-release-pin.md; the beads-docs skill §8 updated to match. * lint: annotate gosec G705 false positive in the docsmint legacy bridge Same class as the existing nav-splice annotation: a developer tool writing repo Markdown, not a web-output sink.
2.9 KiB
title, description
| title | description |
|---|---|
| bd cook | Cook transforms a .formula.json file into a proto. |
{/* AUTO-GENERATED: do not edit manually */}
Generated from bd help --doc cook.
Cook transforms a .formula.json file into a proto.
By default, cook outputs the resolved formula as JSON to stdout for ephemeral use. The output can be inspected, piped, or saved to a file.
Two cooking modes are available:
COMPILE-TIME (default, --mode=compile): Produces a proto with {{variable}} placeholders intact. Use for: modeling, estimation, contractor handoff, planning. Variables are NOT substituted - the output shows the template structure.
RUNTIME (--mode=runtime or when --var flags provided): Produces a fully-resolved proto with variables substituted. Use for: final validation before pour, seeing exact output. Requires all variables to have values (via --var or defaults).
Formulas are high-level workflow templates that support:
- Variable definitions with defaults and validation
- Step definitions that become issue hierarchies
- Composition rules for bonding formulas together
- Inheritance via extends
The --persist flag enables the legacy behavior of writing the proto to the database. This is useful when you want to reuse the same proto multiple times without re-cooking.
For most workflows, prefer ephemeral protos: pour and wisp commands accept formula names directly and cook inline.
Examples: bd cook mol-feature.formula.json # Compile-time: keep {{vars}} bd cook mol-feature --var name=auth # Runtime: substitute vars bd cook mol-feature --mode=runtime --var name=auth # Explicit runtime mode bd cook mol-feature --dry-run # Preview steps bd cook mol-release.formula.json --persist # Write to database bd cook mol-release.formula.json --persist --force # Replace existing
Output (default): JSON representation of the resolved formula with all steps.
Output (--persist): Creates a proto bead in the database with:
- ID matching the formula name (e.g., mol-feature)
- The "template" label for proto identification
- Child issues for each step
- Dependencies matching depends_on relationships
bd cook <formula-file> [flags]
Flags:
--dry-run Preview what would be created
--force Replace existing proto if it exists (requires --persist)
--mode string Cooking mode: compile (keep placeholders) or runtime (substitute vars)
--persist Persist proto to database (legacy behavior)
--prefix string Prefix to prepend to proto ID (e.g., 'gt-' creates 'gt-mol-feature')
--search-path strings Additional paths to search for formula inheritance
--var stringArray Variable substitution (key=value), enables runtime mode