Project vs Ad‑hoc

Two ways to use BPM depending on how much state you want.

Project mode (stateful)

Base directory: ctx.project_dir (materialized from project.yaml:project_path).
Render path: ${ctx.project.name}/${ctx.template.id}/ by default (or your render.into).
State: persists final params and published outputs in project.yaml.
Hooks: runs post_render, pre_run, post_run if configured.
Commands: bpm template render, bpm template run, bpm template publish.

Example

cd /abs/path/250903_TEST
bpm template render --param sample_id=NA12878 hello
bpm template run hello
bpm template publish hello

Ad‑hoc mode (stateless)

Base directory: --out <dir>.
Render path: treats render.into as . (files land directly in --out).
State: does not modify project.yaml; writes bpm.meta.yaml into --out with params and source info.
Hooks: skipped (no post_render/pre_run/post_run).
Commands: bpm template render --out <dir> … (no BPM run/publish in ad‑hoc).

Example

bpm template render --out /tmp/out --param sample_id=NA12878 hello
# Then, if needed, run manually:
cd /tmp/out && ./run.sh

Pick the right mode

Use Project mode for tracked studies, sharing results, and repeatability.
Use Ad‑hoc mode for quick utilities, testing, scratch work, or when no project is needed.

Differences at a glance

Paths: Project uses ${ctx.project.name}/${ctx.template.id}/; Ad‑hoc writes into --out.
Params: Both honor precedence (descriptor < project < CLI), but Ad‑hoc has no project layer and no persistence.
Publish: Project writes publish keys to project.yaml; Ad‑hoc does not publish.
Hooks: Project runs hooks; Ad‑hoc skips them.

Tip

Keep render.into relative and placeholder‑based for project mode. In ad‑hoc, BPM ignores it and writes directly to --out.
Avoid relying on ctx.project.* inside parameter defaults if you plan to use ad‑hoc; the project is not present there.