canned-prompts/reference/README.md

# canned-prompts reference CLI

This is intentionally a **small reference implementation**, not the intended final architecture.

It demonstrates seven verbs:

```text
add      PATH
search   QUERY
show     ID
resolve  ID --set key=value
render   ID --set key=value
install  ID [--version VERSION]
publish  PATH
```

The implementation uses a local catalog plus a filesystem registry and performs no model calls.

`resolve` and `render` are separate because the specification separates them
(§ 5.1): resolution decides each value and may be non-deterministic, rendering
substitutes and always is. `resolve` prints where every value came from —
supplied, default, or fallback — before any prompt is produced.

## Stores

Default locations:

```text
~/.canned-prompts/catalog
~/.canned-prompts/registry
```

Catalog and registry both store packages as:

```text
<store>/<id path>/<version>/...
```

For example:

```text
~/.canned-prompts/catalog/practice/pqrst-estimate/0.1.0/
```

## Design choices

- YAML manifest via PyYAML.
- `{{ name }}` template substitution only.
- No arbitrary expression/code execution.
- Published versions are immutable by default.
- `install` copies from registry to catalog.
- `add` copies a package directly to catalog.
- `search`, `show`, `resolve`, and `render` operate on catalog packages.
- Static input defaults are applied; **derived** defaults (§ 6.1) are not. This
  tool never calls a model, so a derived default is satisfied only by its
  static fallback `value`. Without one, `resolve` reports the input as
  unresolved and `render` refuses rather than substituting empty text.

Use this implementation to challenge the format. Replace it once real usage reveals the right architecture.