Skip to content

docs: align bundle.md example with real umbel build output#24

Merged
vessux merged 1 commit into
mainfrom
worktree-fix-10-bundle-md-example
Jun 11, 2026
Merged

docs: align bundle.md example with real umbel build output#24
vessux merged 1 commit into
mainfrom
worktree-fix-10-bundle-md-example

Conversation

@vessux

@vessux vessux commented Jun 11, 2026

Copy link
Copy Markdown
Owner

Closes #10

What

The resolved-bundle.md example in docs/bundles-spec.md ("Self-describing bundle.md") diverged from what umbel build actually emits, in ways that could mislead machine consumers parsing bundle.md. Regenerate the example block verbatim from real output and add a note documenting the contract.

Discrepancies fixed (spec → actual)

  • Key order: was name, description, skills, agents, mcps, mergeMcp, hash; now matches the emitter's name, hash, description, skills, agents, hooks, mcps[, mergeMcp][, settings] (resolvedFrontmatter in src/bundle/compile.ts).
  • Qualified refs: was de-qualified (skills: [base-skill, pandas-cheatsheet]); now keeps qualified <source>/<leaf> refs as actually emitted, with an explicit note that they stay qualified (the cache dirs use canonical names; the bundle.md refs do not).
  • List style: was flow [a, b]; now block-style (one - per line) — that's what yaml's stringify produces.
  • hooks field: added (was omitted).
  • mergeMcp / settings: documented as appearing only when set / non-empty (no longer always-shown mergeMcp: false); example now includes a settings block.
  • Invocation block: single-space flag/value separation to match formatClaudeInvocation (was aligned columns).

Verification

  • Frontmatter block reproduced verbatim by running the real yaml stringify over resolvedFrontmatter's output — byte-faithful.
  • Invocation format cross-checked against computeClaudeArgs + formatClaudeInvocation.
  • test/unit/bundle/compile.test.ts: 32/32 pass.

Scope

Docs only — the emitter is unchanged (the example follows the code, per the issue). The stale "Implementation status" section is out of scope (tracked in #8).

Note: while verifying, hit a pre-existing intermittent flake in the GC test gcBundles "does nothing special when the symlink is absent" (mtime tie under full-file runs). Not caused by this change; captured separately for discovery.

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.
@vessux vessux merged commit cd8d2ae into main Jun 11, 2026
4 checks passed
@vessux vessux deleted the worktree-fix-10-bundle-md-example branch June 11, 2026 16:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

bundle.md example in spec doesn't match real emitted output

1 participant