Deployment Overlays¶

A deployment overlay lets one base artifact render into several different runtime shapes — Claude Code, Codex, Hermes, or the AOS runtime — at deploy time. Instead of maintaining a separate copy of an artifact per platform, you keep a single source of truth and declare per-target transformation rules in an OverlayConfig. At deploy time, SkillMeat consults the matching overlay for each target profile and renders the artifact accordingly. This guide explains the overlay model, every OverlayConfig field, the in-app editor and render-preview, the feature flag, and the multi-runtime migration workflow.

Overview¶

The core idea is one base, many shapes:

You author and version a single base artifact (a skill, agent, or soul).
You attach one or more OverlayConfig entries — one per target_profile (claude, codex, hermes, aos-runtime).
At deploy time, the PAL adapter for that profile applies the overlay's declarative rules and writes the runtime-ready output to the deploy destination.

Rendered output is a build product — never versioned

This is the central invariant of the overlay system (FR-9). The rendered variant a target receives is a build product: it is never stored as a versioned artifact and no ArtifactVersion row is created for it. Provenance for a rendered output is captured separately (via the materialization record and a SkillBOM sidecar), not by versioning the rendered bytes. Your versioned source of truth is always the base artifact.

Feature flag — default OFF

Deployment overlay rendering is gated by the deployment_overlays_enabled feature flag, which defaults to OFF. Enable it by setting SKILLMEAT_DEPLOYMENT_OVERLAYS_ENABLED to a truthy value before starting the API. When disabled, deploy performs a verbatim copy (the unchanged pre-feature behavior); overlays are stored but not applied.

The `OverlayConfig`¶

Each overlay covers exactly one target_profile and carries declarative rules only — it stores what to transform, never render state. The fields:

Field	Type	Purpose
`substitution_table`	map (string → string)	Ordered literal-token substitution map: `source_token → replacement`, applied left-to-right. Keys and values are plain non-empty strings (e.g. `".claude" → ".agents"`). These are literal string rewrites, not `{{VAR}}` placeholders.
`do_not_rewrite`	list of glob patterns	`fnmatch` glob patterns that protect matching content lines from the substitution pass. Use this to exempt lines that happen to contain a substitution token but must stay verbatim.
`frontmatter_remap`	map (string → string \| null)	Remaps the rendered output's frontmatter: `source_key → target_key` renames the field; `source_key → null` drops the field entirely. Fields not listed pass through unchanged.
`footer`	string (optional)	Text appended verbatim to the end of the rendered output, separated by a blank line. Typically per-platform attribution or a compatibility note.
`deploy_path_template`	string (optional)	Overrides the default deploy path. Uses Jinja2-style `{{ var }}` placeholders resolved from the deploy-time binding values. Only simple identifier references are allowed — no filters, attribute access, or expressions.
`override_file_ref`	string (optional)	A relative path to a source override file whose body replaces the base artifact content for this target (e.g. `overlays/hermes/SKILL.md`). Used when a target's format diverges enough to warrant a hand-authored body. Must not start with `/`.

Multiple overlays for one artifact are expressed as an ordered OverlayConfigList; each target_profile may appear at most once. Example shape:

{
  "overlays": [
    {
      "target_profile": "codex",
      "substitution_table": { ".claude": ".agents" },
      "do_not_rewrite": ["*.md"]
    },
    {
      "target_profile": "hermes",
      "override_file_ref": "overlays/hermes/SKILL.md",
      "frontmatter_remap": { "skill_type": "type", "version": null },
      "footer": "<!-- hermes-generated -->",
      "deploy_path_template": "{{ category }}/{{ name }}.md"
    }
  ]
}

How the Rules Combine¶

When rendering for a target, the adapter applies the rules in a defined order: an override_file_ref body (if set) replaces the base content first; frontmatter_remap rewrites the YAML frontmatter; substitution_table rewrites the body (skipping any lines matched by do_not_rewrite); footer is appended last; and deploy_path_template determines the output path. When substitution_table is empty and no other rule applies, the render is a no-op producing byte-identical output to the base.

Editing Overlays in the Web UI¶

SkillMeat ships an overlay editor for managing an artifact's overlays without hand-editing JSON. From an artifact's detail view, the editor exposes every OverlayConfig field (substitution table, do-not-rewrite patterns, frontmatter remap, footer, deploy-path template, and override file reference) and persists changes through the overlay API.

Render Preview¶

Alongside the editor, a render-preview panel shows exactly what a target will receive before you deploy. It renders the artifact for a chosen target_profile entirely in memory — there are no side effects (consistent with the FR-9 build-product invariant) — and displays a unified diff between the base content and the rendered output so you can confirm substitutions, frontmatter changes, and footer placement at a glance.

Multi-Runtime Migration Scenario (aos-operator)¶

Overlays shine when one agent identity must run on several runtimes. Consider migrating an aos-operator agent so the same identity is deployed to Claude Code, Codex, and Hermes:

Keep one base. Author the agent (and its soul) once as the versioned source of truth.
Declare a Codex overlay. Add an OverlayConfig with target_profile: codex and a substitution_table entry ".claude" → ".agents" so the Codex runtime sees its expected directory convention. Add do_not_rewrite patterns for any docs that mention .claude literally and must stay verbatim.
Declare a Hermes / aos-runtime overlay. Add target_profile: hermes with a frontmatter_remap to produce the Hermes metadata schema, an override_file_ref if the Hermes body diverges, a footer for attribution, and a deploy_path_template to land the file where the runtime expects it.
Preview each target in the render-preview panel to confirm the diffs.
Deploy. With deployment_overlays_enabled on, each target receives its rendered shape; the base artifact remains the single versioned source.

The result: one identity, three runtime shapes, zero duplicated source artifacts — and the rendered outputs stay disposable build products.

v1 Limitation: Enterprise Renders Verbatim¶

In the current v1 release there is an important edition gap:

Enterprise edition stores overlays but does not yet render them on deploy

Enterprise edition persists OverlayConfig data and logs a warning when an overlay is present at deploy time, but it does not apply the overlay transformation during deploy — it renders the artifact verbatim. Per-target overlay rendering on deploy is currently a local-edition capability. Track the Edition Feature Matrix for when enterprise render support lands.