# Spec v0 scope

# Context

Petitgen is entering Wave 1 of its roadmap: prove the .remedy substrate by shipping a minimum spec, tooling, sovereign runtime, and a first dogfood. Earlier iterations in Complaintery/code/remedy built a multi-file workspace layout (features/<slug>/{feature.yml, complaint.yml, code.yml, …}) and a VS-Code-style workbench; a parallel FEATURE_MODEL.md in the strategy hub proposed a single-YAML-per-remedy model with embeddings baked in from day one.

Reconciling those two shapes required a product decision.

# Decision

1. Remedy is a specification for directories, not a single-file format. The unit is the folder; the .remedy file at its root is the entry-point contract.
2. File syntax is YAML with canonical key order enforced by remedy fmt.
3. Embeddings ship in v0, not v1. Local-first via Ollama nomic-embed-text; OpenAI as opt-in.
4. Kinds are fixed in v0 to five values (feature, tool, product, workspace, doc-set). Extensible in v1.
5. Marketplace is deferred to v1. v0 proves the spec + tooling + sovereign runtime; marketplace is additive.
6. First dogfood is TimeBill (not Complaintery), because it is smaller, Sebastien runs it weekly, and failure modes will surface within a week of shipping.
7. Surfaces in v0: CLI, MCP server for Claude Code, Tauri Mac Desktop app, Astro-based web surface at remedy.build. All four consume remedy-core.

# Consequences

• The existing Complaintery/code/remedy and Complaintery/code/remedy-web are reclassified as prior-art. Salvageable UI components (workbench, xyflow constellation view, command palette) get cherry-picked into packages/remedy-desktop and packages/remedy-web during Wave 1d/1e. The multi-file per-feature layout is rewritten — each feature is either inline under features: or a sub-remedy folder with its own .remedy.
• admin/docs/petitgen/FEATURE_MODEL.md becomes a pointer to this repo’s SPEC.md instead of being the authoritative spec itself.
• npm package name remedy is taken; we use @petitgen/remedy-* for library packages. The CLI binary name remedy is unaffected.
• Domain remedy.build is registered and owned by Petitgen Ltd.

# Alternatives considered

• Single-YAML-per-remedy (as in the old FEATURE_MODEL.md). Rejected: does not match Sebastien’s mental model of a folder-with-contract; loses the ability to hand-off a whole directory as a unit.
• TOML instead of YAML. Rejected: Petitgen is YAML-first (knowledge shards, brand guide, admin configs); consistency beats mild correctness wins.
• Defer embeddings to v0.5. Rejected: embedding-based routing is what makes Remedy qualitatively different from a schema-validated YAML folder. Without it, Wave 1 proves nothing the market hasn’t already seen.
• Complaintery as first dogfood. Rejected as too large; deferred to Wave 1.5.

# Follow-ups

• Update admin/docs/petitgen/FEATURE_MODEL.md to point here.
• Update admin/docs/petitgen/products/remedy.md with the new shape.
• ollama pull nomic-embed-text on Sebastien’s Mac before Wave 1b.