* 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.
72 lines
2.9 KiB
Markdown
72 lines
2.9 KiB
Markdown
---
|
|
title: "bd cook"
|
|
description: "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
|
|
```
|