From bf3db0747c5329f7754c54c431b53e3d142e5cdb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jakub=20Kova=C4=BE?= <kuba.koval@gmail.com>
Date: Thu, 11 Jun 2026 18:20:10 +0200
Subject: [PATCH] docs: align bundle.md example with real umbel build output
 (#10)

The resolved-bundle.md example in docs/bundles-spec.md diverged from the
emitter in ways that could mislead consumers parsing bundle.md: wrong
frontmatter key order, flow-style lists, de-qualified refs, no hooks/
settings fields, and an always-shown mergeMcp.

Regenerate the block verbatim from `umbel build` output (yaml block-style
lists, fixed key order name/hash/description/skills/agents/hooks/mcps/
mergeMcp?/settings?, qualified <source>/<leaf> refs, hooks + settings) and
single-space the invocation to match formatClaudeInvocation. Add a note
documenting the key order, the conditional fields, and that refs stay
qualified.
---
 docs/bundles-spec.md | 41 +++++++++++++++++++++++++++++++----------
 1 file changed, 31 insertions(+), 10 deletions(-)

diff --git a/docs/bundles-spec.md b/docs/bundles-spec.md
index a8e2d72..86a2bdd 100644
--- a/docs/bundles-spec.md
+++ b/docs/bundles-spec.md
@@ -234,14 +234,22 @@ Shape:
 
 ```markdown
 ---
-# resolved frontmatter — composed, defaulted, no `extends:` field
 name: data-science
-description: Tools for data science work
-skills: [base-skill, pandas-cheatsheet]
-agents: [data-scientist]
-mcps: [local/duckdb]
-mergeMcp: false
-hash: abc123def456
+hash: 9f3c1a2b7e04
+description: Tools for data-science work
+skills:
+  - claude/base-skill
+  - cc-plugin-superpowers/pandas-cheatsheet
+agents:
+  - claude/data-scientist
+hooks:
+  - base/preflight
+mcps:
+  - local/duckdb
+settings:
+  model: claude-opus-4-8
+  env:
+    PYTHONHASHSEED: "0"
 ---
 
 [verbatim markdown body from the source bundle.md, if any]
@@ -250,13 +258,26 @@ hash: abc123def456
 
 \`\`\`bash
 claude \
-  --plugin-dir   /Users/.../.cache/umbel/bundles/data-science-abc123 \
-  --settings     /Users/.../.cache/umbel/bundles/data-science-abc123/settings.json \
-  --mcp-config   /Users/.../.cache/umbel/bundles/data-science-abc123/.mcp.json \
+  --plugin-dir /home/you/.cache/umbel/bundles/data-science-9f3c1a2b7e04 \
+  --settings /home/you/.cache/umbel/bundles/data-science-9f3c1a2b7e04/settings.json \
+  --mcp-config /home/you/.cache/umbel/bundles/data-science-9f3c1a2b7e04/.mcp.json \
   --strict-mcp-config
 \`\`\`
 ```
 
+This block is **verbatim `umbel build` output**: `yaml` serializes lists
+block-style (one `-` per line), and the frontmatter key order is fixed by the
+emitter:
+
+- **Key order:** `name`, `hash`, `description`, then any non-empty `skills`,
+  `agents`, `hooks`, `mcps` lists, then `mergeMcp` (only when the bundle sets
+  it), then `settings` (only when non-empty). Unset fields and empty lists are
+  omitted; the `extends:` field is composed away and never appears.
+- **Refs stay qualified** (`<source>/<leaf>`), exactly as written in the
+  manifest — never canonicalized to bare names. (The on-disk cache *directories*
+  use the canonical frontmatter `name:` — see above — but the `bundle.md` refs
+  do not.)
+
 Rules for the `## Invocation` block:
 
 - One flag per line, backslash-continued, so consumers can grep flag-by-flag.