## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

# Publishing Recipes

Recipes can ship at three tiers. The tier is set by the loader from the recipe’s source path, not by what the manifest declares. Where you put the recipe directory determines who can run it and how.

## Three Distribution Models

### 1. Personal — User Folder

    ~/.pretorin/recipes/<id>/

Drop a recipe directory there and `pretorin recipe list` shows it immediately. Loaded as `tier: community`. No further setup.

Use this when:

- You’re prototyping a recipe.
- The recipe encodes a personal workflow no one else needs.
- You’re working through the 10-minute walkthrough.

The user folder isn’t synced anywhere — it lives on your machine.

### 2. Team — Project Folder

    <repo>/.pretorin/recipes/<id>/

Checked into your team’s compliance repo (the same repo with `pretorin.yaml` or your team’s CLAUDE.md). The loader walks up from CWD looking for a `.pretorin/recipes/` directory, so any teammate working in the repo gets the recipes automatically.

Use this when:

- The recipe encodes a team-specific procedure (e.g., “pull our internal IAM audit log endpoint”).
- You want your CI to validate the recipes alongside the rest of the compliance repo.
- The recipe is too domain-specific to belong upstream but everyone on the team needs it.

Loaded as `tier: community`. The project folder has higher precedence than the user folder, so a team-shared recipe shadows a teammate’s personal copy with the same id.

### 3. Upstream — First-Party in pretorin-cli

    src/pretorin/recipes/_recipes/<id>/

Forced to `tier: official` by the loader. Distributed with every pretorin-cli install.

Use this when:

- The recipe is broadly useful to anyone running pretorin (a new scanner wrapper, a generic capture pattern).
- You’re willing to maintain it — official recipes get tested in CI and block releases on regressions.
- The procedure is stable enough that a SemVer bump with backwards- incompatible changes would be unusual.

## How to Submit a First-Party Recipe

1. Open an issue first. Describe what the recipe does and why it belongs in the upstream set rather than as a community recipe. The first-party set is intentionally small — it’s a curation surface, not a catch-all.

2. Scaffold under `_recipes/` — clone pretorin-cli and create the recipe directory:

       pretorin recipe new my-new-scanner --location builtin

   This drops the recipe under `src/pretorin/recipes/_recipes/<id>/` with the right structure.

3. Set `tier: official` in the manifest. The loader will override from the source path anyway, but it documents intent.

4. Add a smoke test. Every built-in recipe has at least one test under `tests/recipes/` that loads it through the registry and verifies the basic shape. Copy the pattern from `tests/recipes/test_builtin_scanner_recipes.py`.

5. Run quality gates locally:

       pretorin recipe validate my-new-scanner
       pytest tests/recipes/
       ./tools/check.sh quick

6. PR the recipe. Include in the description: what the recipe does, when an agent should pick it (your `use_when` text is a good start), and what scanners or platform APIs it depends on. Reference the issue from step 1.

7. Maintenance commitment. Once merged, the recipe ships with every pretorin-cli release. Be prepared to respond to issues against it.

## How to Share a Community Recipe

There’s no central registry yet (pretorin’s `recipe install <pkg>` is v1.5). For now, share a community recipe by:

- Posting the recipe directory in a gist or repo. Anyone can clone it into their `~/.pretorin/recipes/` or `<repo>/.pretorin/recipes/` and use it.
- Opening a PR against your team’s compliance repo. The recipe lands under `<repo>/.pretorin/recipes/<id>/` and is loaded automatically by every teammate.

When you publish a community recipe, fill out:

- `license` — required for anything you share publicly. SPDX identifier (`Apache-2.0`, `MIT`, etc.).
- `author` — your name or your team’s name. Stamped in the audit metadata of every evidence record the recipe writes.
- `description` — clear enough that someone else’s agent can decide whether to pick it without needing to read your team’s wiki.

## Tier and Trust

The calling agent sees `tier` on every recipe in `pretorin_list_recipes` output. v1 doesn’t gate execution by tier — a community recipe runs just like an official one. What tier does is:

- Audit signal. Every evidence record stamped by a community recipe carries the recipe id, version, and author. A reviewer can trace which recipes contributed to a system’s evidence set.
- Selection signal. When two recipes both fit a task, the agent prefers the official one unless the community one’s `description` makes a stronger case.

`partner` tier is reserved for recipes shipped via installed Python packages (deferred to v1.5). The shape is: a Python package declares an entry point pointing at a recipe directory inside the package; the loader picks it up at install time.

## Versioning Your Recipe

Bump `version` in the manifest when:

- The recipe’s behavior changes in a way that would surprise a previous consumer (different output shape, different side effects, different redaction rules).
- A bug fix changes results materially.

Don’t bump for cosmetic edits to the body or doc-only changes. Recipe version stamps every evidence record, so a version bump means the audit trail reflects “results from a different procedure.”

`recipe_schema_version` is independent — it tracks the frontmatter shape, not the recipe’s behavior. Most recipes pin this to `"1.0"` and never touch it.