Narrate

The Narrate phase composes repo-facing content — README badges, shields, and included fragments — and commits it back. Presence-enabled: configure narrate and it runs.

Key	What it does
narrate	Badge/shield generation, content items (kind: badge · shield · text · component · props · break · include), placement rules, and the commit that lands them.

Two badge systems

StageFreight has two ways to put a badge in your README, and they're easy to confuse. Both are narrator item kinds and can sit on the same line:

	kind: badge	kind: props
What	A local SVG generator you own	A registry of external provider badges
Powered by	the badge package (renders SVG)	the props package (resolver/composer)
Output	committed .svg files — branded, version-stamped	markdown → an external URL with live data
Sources	your own data	shields.io, codecov, Go Report Card, docker-pulls, SLSA…
CLI	stagefreight badge generate	stagefreight props list · props render
Use when	you control the data and want branded assets	you want live ecosystem data in a standard format

In short: badge = "I'll draw my own." props = "give me the shields.io one for docker pulls." Both compose through the narrator, so they coexist happily in one README.

Discovering props

stagefreight props categories and stagefreight props list enumerate every available prop type (e.g. docker-pulls, codecov, slsa). Each is a typed, validated resolver — unknown types and params are rejected at run time, not silently ignored.

Reference

narrate

Narrate configures the Narrate phase (badges, patches, commit). Presence-enabled; dissolves the old docs:/badges:/narrator: surface. Reference docs are a kind: command build committed via narrate.commit.builds, not a subsystem here.

narrate:
  badges:   # Badges are SVG badge definitions rendered from build metadata (was top-level `badges.items`).…
    - id: <string>   # stable user-defined ID for narrator reference · required
      text: <string>   # left side label · required
      value: <string>   # right side value (templates: {env:*}, {sha}, {base}, etc.) · required
      color: <string>   # hex color or "auto" · required
      output: <string>   # SVG output path (required) · required
      link: <string>   # clickable URL
      font: <string>   # font name override
      font_size: <int>   # font size override
  patches:   # Patches are generic marked-region replacements in files (was `narrator:`): each entry names a file…
    - file: <string>   # File is the path to the target file (required). · required
      link_base: <string>   # LinkBase is the base URL for relative link rewriting.
      items: []   # discriminated union by kind — see per-kind blocks below
  commit:   # Commit is the auto-commit action for generated output (was `docs.commit`).
    type: <string>   # conventional type; default: engine's
    message: <string>
    add: [<string>]
    push: false
    skip_ci: false
    run_from:   # gate mutation to declared origin
      allow: [<string>]   # permitted origins: "primary"
      mismatch: <string>   # "read-only" (default), "exit", "ignore"

patches items · kind: badge

- id: <string>   # ID is the item identifier (unique within file). · required
  kind: badge   # Kind is the item type: badge, shield, text, component, break, include. · required
  text: <string>   # Text is the badge label (left side text).
  value: <string>   # Value is the badge value (right side text, supports templates).
  color: <string>   # Color is the badge color (hex or "auto").
  font: <string>   # Font is the badge font name override.
  font_size: <int>   # FontSize is the badge font size override.
  output: <string>   # Output is the SVG output path for badge generation.
  link: <string>   # Link is the clickable URL (kind: badge, shield).
  placement:   # Placement declares where this item goes in the target file. · required
    between: <value>   # Between is a two-element array: [start_marker, end_marker]. Content is placed relative to these…
    after: <string>   # After is a regex/literal line match (reserved for future use).
    before: <string>   # Before is a regex/literal line match (reserved for future use).
    heading: <string>   # Heading is a markdown heading match (reserved for future use).
    mode: <string>   # Mode controls how content is placed: replace (default), append, prepend, above, below.
    inline: false   # Inline renders items side-by-side when true (default: false).

patches items · kind: shield

- id: <string>   # ID is the item identifier (unique within file). · required
  kind: shield   # Kind is the item type: badge, shield, text, component, break, include. · required
  shield: <string>   # Shield is the shields.io path (kind: shield).
  link: <string>   # Link is the clickable URL (kind: badge, shield).
  placement:   # Placement declares where this item goes in the target file. · required
    between: <value>   # Between is a two-element array: [start_marker, end_marker]. Content is placed relative to these…
    after: <string>   # After is a regex/literal line match (reserved for future use).
    before: <string>   # Before is a regex/literal line match (reserved for future use).
    heading: <string>   # Heading is a markdown heading match (reserved for future use).
    mode: <string>   # Mode controls how content is placed: replace (default), append, prepend, above, below.
    inline: false   # Inline renders items side-by-side when true (default: false).

patches items · kind: text

- id: <string>   # ID is the item identifier (unique within file). · required
  kind: text   # Kind is the item type: badge, shield, text, component, break, include. · required
  content: <string>   # Content is raw text/markdown content (kind: text).
  placement:   # Placement declares where this item goes in the target file. · required
    between: <value>   # Between is a two-element array: [start_marker, end_marker]. Content is placed relative to these…
    after: <string>   # After is a regex/literal line match (reserved for future use).
    before: <string>   # Before is a regex/literal line match (reserved for future use).
    heading: <string>   # Heading is a markdown heading match (reserved for future use).
    mode: <string>   # Mode controls how content is placed: replace (default), append, prepend, above, below.
    inline: false   # Inline renders items side-by-side when true (default: false).

patches items · kind: component

- id: <string>   # ID is the item identifier (unique within file). · required
  kind: component   # Kind is the item type: badge, shield, text, component, break, include. · required
  spec: <string>   # Spec is the component spec file path (kind: component).
  placement:   # Placement declares where this item goes in the target file. · required
    between: <value>   # Between is a two-element array: [start_marker, end_marker]. Content is placed relative to these…
    after: <string>   # After is a regex/literal line match (reserved for future use).
    before: <string>   # Before is a regex/literal line match (reserved for future use).
    heading: <string>   # Heading is a markdown heading match (reserved for future use).
    mode: <string>   # Mode controls how content is placed: replace (default), append, prepend, above, below.
    inline: false   # Inline renders items side-by-side when true (default: false).

patches items · kind: include

- id: <string>   # ID is the item identifier (unique within file). · required
  kind: include   # Kind is the item type: badge, shield, text, component, break, include. · required
  path: <string>   # Path is the file path to include verbatim (kind: include).
  placement:   # Placement declares where this item goes in the target file. · required
    between: <value>   # Between is a two-element array: [start_marker, end_marker]. Content is placed relative to these…
    after: <string>   # After is a regex/literal line match (reserved for future use).
    before: <string>   # Before is a regex/literal line match (reserved for future use).
    heading: <string>   # Heading is a markdown heading match (reserved for future use).
    mode: <string>   # Mode controls how content is placed: replace (default), append, prepend, above, below.
    inline: false   # Inline renders items side-by-side when true (default: false).

patches items · kind: build-contents

- id: <string>   # ID is the item identifier (unique within file). · required
  kind: build-contents   # Kind is the item type: badge, shield, text, component, break, include. · required
  build: <string>   # Build is the id of the build whose manifest this item renders (kind: build-contents). Ownership is…
  source: <string>   # Source is an optional path to a manifest JSON file (kind: build-contents). If omitted, uses the…
  section: <string>   # Section is the dot-path into the manifest (kind: build-contents). e.g., "inventories.pip"…
  renderer: <string>   # Renderer is the rendering format (kind: build-contents). Supported: "table", "list", "kv".
  placement:   # Placement declares where this item goes in the target file. · required
    between: <value>   # Between is a two-element array: [start_marker, end_marker]. Content is placed relative to these…
    after: <string>   # After is a regex/literal line match (reserved for future use).
    before: <string>   # Before is a regex/literal line match (reserved for future use).
    heading: <string>   # Heading is a markdown heading match (reserved for future use).
    mode: <string>   # Mode controls how content is placed: replace (default), append, prepend, above, below.
    inline: false   # Inline renders items side-by-side when true (default: false).

patches items · kind: break

- id: <string>   # ID is the item identifier (unique within file). · required
  kind: break   # Kind is the item type: badge, shield, text, component, break, include. · required
  placement:   # Placement declares where this item goes in the target file. · required
    between: <value>   # Between is a two-element array: [start_marker, end_marker]. Content is placed relative to these…
    after: <string>   # After is a regex/literal line match (reserved for future use).
    before: <string>   # Before is a regex/literal line match (reserved for future use).
    heading: <string>   # Heading is a markdown heading match (reserved for future use).
    mode: <string>   # Mode controls how content is placed: replace (default), append, prepend, above, below.
    inline: false   # Inline renders items side-by-side when true (default: false).

---