Includes, inheritance and extensions
This page is for developers who reuse one instruction in another. It covers ::include, which copies part of another document in place, and extends, which builds on a base and patches it. It also covers live and pinned references, where each tool reads the sources from, what an agent receives, and how extensions are declared.
Composition happens when an instruction is delivered. The authored text keeps its ::include and extends as written. The agent receives one text with the other documents' content in it and a record of every change.
Include part of another document
::include inserts the body of another instruction, or a selected part of it, where the leaf stands:
# Morning assistant
::include{src="./team.md#id=privacy" as=privacy required}
Before you share a meeting, check :ref[the privacy policy]{ref=#privacy/privacy}. Delivered next to the base below (agents/team.md), it reads:
# Morning assistant
### Policy: Calendar privacy
NEVER: reveal a private event to another person.
Before you share a meeting, check the privacy policy (ref; #privacy/privacy). | Attribute | Value | Effect |
|---|---|---|
src |
A target: a relative or absolute URI with an optional fragment, or a name from the front matter's references. A name takes no fragment: base#id=x is read as the path base |
What to include. Required |
as |
An alias, [A-Za-z0-9][A-Za-z0-9._-]* |
The included instance's name. Required, and unique in the document among includes and bases |
required |
Flag | A source that can't be read is an error. Without it, a warning and a partial result |
mode |
live (default) or pinned |
See Live and pinned |
sha256 |
sha256: and 64 lowercase hex digits |
The pinned digest |
version |
A string | Checked against the version the source reports |
Besides these and the common attributes (id, title, class, style, description), an include takes none. It has no select and no with: select with the fragment of src, and an included document's parameters take their defaults.
The included content keeps its own scope:
- Its ids are addressed from the including document as
#alias/id::ref[…]{ref=#privacy/privacy}above. - Its own includes and bases resolve against its own URI, not the including file's.
- Its front matter stays its own. Its parameters, references and extensions apply to its content only.
- Including the same document twice, with two aliases, makes two separate instances.
::include can stand inside a container, such as a policy. An include that can't be read stays in the delivered text as ### include: include with its attributes, so the agent sees that something is missing.
Select a part
A fragment on src selects part of the source:
::include{src="./team.md#id=privacy" as=a}
::include{src="./team.md#heading=Team guidance" as=b}
::include{src="./team.md#privacy" as=c} | Fragment | Selects |
|---|---|
#id=privacy |
The block with the explicit id privacy, with the policies around it |
#heading=Team guidance |
The section under the first heading with exactly that visible text, from that heading to the next heading of the same level or higher. Only headings in the source's own Markdown count, not headings inside a container |
#privacy |
An explicit id first, then a generated heading anchor |
A selected block keeps its enclosing policies, so a rule never loses the policy it belongs to. A fragment that matches nothing is reference-missing for a required include, else reference-optional.
A base record selects with select instead: { id: … }, { heading: …, occurrence: n } or { lines: [a, b] }. Lines count from 1, include the end, and count the source's front matter:
extends:
- { uri: ./team.md, as: rules, select: { lines: [8, 8] } } An instruction document has no other selectors. pointer, page, time and region select parts of resources, and a base record given one fails with invalid-attributes.
Include or embed
::embed{src=…}, and its shorthand ![[target|label]], shows a resource in place: a PDF page, a video, another document. It imports nothing: its ids don't join the document's, its rules aren't the document's rules, and nothing is copied into the agent's text. Use ::include for guidance the agent follows. See Inline references, links and annotations.
Inherit from a base
extends in the front matter names one or more bases. The base below is agents/team.md:
---
spec: "1"
title: Team guidance
---
# Team guidance
MUST[status]: keep tentative appointments tentative.
:::policy{id=brief title="Daily brief"}
SHOULD: keep the daily brief under 300 words.
:::
:::policy{id=priorities title="Priorities"}
MUST: identify the day's commitments.
:::
:::policy{id=mail title="Mail"}
SHOULD: review the inbox.
:::
:::policy{id=privacy title="Calendar privacy"}
NEVER: reveal a private event to another person.
::: The child builds on it, and patches three of its blocks:
---
spec: "1"
title: Morning assistant
extends:
- uri: ./team.md
as: team
mode: live
---
:::replace{target="#team/brief" reason="Mornings are short."}
SHOULD: keep the daily brief under 150 words.
:::
:::extend{target="#team/priorities" position=append}
MUST: identify an uninterrupted work period.
:::
::remove{target="#team/mail" reason="Calendar only."}
Start with the first meeting of the day. extends is a list of records:
| Key | Value | Effect |
|---|---|---|
uri |
A target, as for src |
The base. Required |
as |
An alias | The base's instance name. Required, and unique among the document's bases and includes |
mode |
live (default) or pinned |
See Live and pinned |
sha256 |
sha256: and 64 lowercase hex digits |
The pinned digest |
version |
A string | Checked against the version the source reports |
select |
{ id }, { heading, occurrence } or { lines: [a, b] } |
Inherit only part of the base. Without it, the fragment of uri, else all of it |
with |
A mapping | Values for the base's parameters. A base gets no other values |
A base is always required: one that can't be read is an error.
The effective body is built in this order:
- Each base in declared order, each resolved on its own first: its own bases, patches and includes.
- The child's
replace,extendandremovepatches, in source order, against the inherited tree as it stands after the patches before them. - The child's own body, with its includes resolved.
instruction deliver agents/morning.md # Team guidance
MUST: keep tentative appointments tentative.
### Policy: Daily brief
SHOULD: keep the daily brief under 150 words.
### Policy: Priorities
MUST: identify the day's commitments.
MUST: identify an uninterrupted work period.
### Policy: Calendar privacy
NEVER: reveal a private event to another person.
Start with the first meeting of the day.
### Composition changes
- replace team/brief (origin: agents/morning.md) — Mornings are short.
- extend team/priorities (origin: agents/morning.md)
- remove team/mail (origin: agents/morning.md) — Calendar only. The child's metadata never overwrites a base's. Each source keeps its own front matter, parameters, references and extension aliases. A child passes values to a base only through with:
---
spec: "1"
references:
base: { uri: "instruction://acme/support-base" }
extends:
- { uri: base, as: base, mode: live, with: { team: Billing } }
--- Patch what you inherit
A patch names its target as #alias/id: an explicit id in a base, qualified by the base's alias. A base's base is #alias/alias/id. A generated heading anchor can't be a target, and neither can an id of the child itself.
| Patch | Form | Effect |
|---|---|---|
replace |
Container | The target's content is replaced by the patch's children, at the target's place. The target keeps its id, kind and attributes |
extend |
Container | The patch's children are added to the target's: position=append (default) after them, position=prepend before |
remove |
Leaf | The target and everything in it are removed |
Each takes target (required) and reason, a line of text that goes into the record of changes. A reason is attribution, never a rule.
- A
replacekeeps the target's kind. To turn a policy into something else,removeit and add a new block of your own. - A target with a YAML or JSON body is replaced whole, in the same format, and can't be extended:
:::replace{target="#base/limits" format=yaml}
max_refund: 150
::: - To change a Markdown target's attributes too, put a
propertiesblock withpatch=truein the replacement. Its mapping overrides the target's attributes. It can't change the id. The replacement's fence is longer than the inner block's:
::::replace{target="#team/privacy"}
:::properties{patch=true}
title: Privacy
:::
NEVER: share a private event.
:::: - An
allowancein the child with the id of an inherited allowance takes its place, and may only narrow it. See Allowances and wallets.
Ids in a composed document
- A base's ids stay qualified. Two bases with the same local id stay two blocks:
#a/privacyand#b/privacy. Neither overrides the other. - A document inherited twice, by two paths, makes two instances.
- An unqualified
#idnames an id of the document itself, and never searches the bases. - A patch looks its target up in the tree as it stands. After a
remove, later patches and references to that id fail.
Live and pinned
mode: live, the default, reads the source as it is when the instruction is delivered. Each delivery reads each source once, and the resolved artifact records the digest it read in dependencies.
mode: pinned also needs sha256: the digest of the source's bytes. A source whose bytes have another digest stops delivery with pin-mismatch. Get the digest of a file with instruction digest:
instruction digest agents/team.md sha256:c1610971508b4baaddfc331921ad3e90ac68761335ee3791461743453a449b4b A released version's digest is the digest that instructions_versions_get and instructions_versions_read return.
---
spec: "1"
title: Morning assistant
extends:
- uri: ./team.md
as: team
mode: pinned
sha256: sha256:c1610971508b4baaddfc331921ad3e90ac68761335ee3791461743453a449b4b
---
:::replace{target="#team/brief" reason="Mornings are short."}
SHOULD: keep the daily brief under 150 words.
:::
:::extend{target="#team/priorities" position=append}
MUST: identify an uninterrupted work period.
:::
::remove{target="#team/mail" reason="Calendar only."}
Start with the first meeting of the day. After a change to agents/team.md, the pinned child stops:
line 1: the base "team" is pinned to sha256:c1610971508b4baaddfc331921ad3e90ac68761335ee3791461743453a449b4b, and ./team.md is sha256:79592fa637c6c10d586097228e7d25fb5279b99e2f674407dd499a4d28daee88 [pin-mismatch]
line 11: :::replace: nothing inherited has the id #team/brief [patch-target]
line 15: :::extend: nothing inherited has the id #team/priorities [patch-target]
line 19: :::remove: nothing inherited has the id #team/mail [patch-target] A base that fails its pin isn't composed, so each patch of it also reports patch-target. Fix the pin, and those errors go too.
version alone pins nothing: it is a label, compared with the version the source reports when the source reports one. Another version stops delivery with pin-mismatch. The CLI's files report none, so it isn't checked there. The registry reports a version's id (ver_…), so a version given for a registry source must be that id.
Where sources come from
A target resolves against the URI of the document it is written in. A bare name, such as base, is first looked up in the front matter's references mapping, then read as a relative path. Write ./name to skip the lookup.
| Where it is delivered | The document's URI | Sources it reads |
|---|---|---|
instruction deliver <file> |
The file's file:// URL |
Files under the file's own folder. Never a file above it, never a URL |
instructions_versions_read with resolve: true |
instruction://<owner>/<name> |
Instructions you may read, at instruction://<owner>/<name>, with @<ref> or @vN for one version and latest without. Never a web address or a file |
spec_deliver |
None | Nothing: a base or a required include is an error, an optional include stays unresolved |
| The renderer's delivered view | None | Nothing: a base or a required include is an error, an optional include stays unresolved |
Over the registry, ./team.md in instruction://acme/morning is instruction://acme/team: a trailing .md is dropped. A relative path never leaves the owner. Name another organization's instruction with its whole address, such as instruction://globex/base@stable.
A source you may not read is reported the same way as one that doesn't exist: could not be read. A diagnostic never says whether a private instruction exists or what it holds. Each source read is recorded as a read.
What the agent receives
The agent's text is the effective body: the inherited content with the patches applied, the included content in place, and the child's own body. Removed and replaced content is gone from it. After the body, a ### Composition changes list names every patch, in the order it was applied:
- <operation> <alias/id> (origin: <URI of the document that patched it>) — <reason>
The section is left out when there are no patches. It records the changes. It doesn't restore what was removed.
The resolved artifact (instruction deliver --resolved, instruction-resolved/1) also records each source read, and each inherit, include and patch:
{
"dependencies": [
{
"uri": "./team.md",
"resolved_uri": "agents/team.md",
"sha256": "sha256:c1610971508b4baaddfc331921ad3e90ac68761335ee3791461743453a449b4b",
"mode": "live",
"instance": "root/team"
}
],
"provenance": [
{
"instance": "root/team",
"uri": "agents/team.md",
"operation": "inherit"
},
{
"instance": "root/team",
"uri": "agents/morning.md",
"range": {
"start": 10,
"end": 12
},
"operation": "replace",
"target": "team/brief",
"reason": "Mornings are short.",
"modified_by": "agents/morning.md"
},
{
"instance": "root/team",
"uri": "agents/morning.md",
"range": {
"start": 14,
"end": 16
},
"operation": "extend",
"target": "team/priorities",
"modified_by": "agents/morning.md"
},
{
"instance": "root/team",
"uri": "agents/morning.md",
"range": {
"start": 18,
"end": 18
},
"operation": "remove",
"target": "team/mail",
"reason": "Calendar only.",
"modified_by": "agents/morning.md"
}
]
} Every node of its body carries its instance: root for the document, root/team for the base, root/team/<alias> for the base's own. A provenance record of a patch also keeps the target as it was before the patch, in original. See What an agent receives.
Cycles, depth and limits
- A document that composes itself, directly or through others, fails with
composition-cycle. Links between documents are not composition and may form cycles. - Composition is at most 8 documents deep. Deeper fails with
limit-exceeded. - A delivery reads at most 64 sources. Later ones are reported as could not be read.
Extensions
An extension adds block and inline kinds, written with the alias the document gives it: charts:metric. Declare each alias in the front matter's extensions, with the extension's exact id and version:
---
spec: "1"
extensions:
charts: { id: dev.example/charts, version: 1.0.0 }
---
:::charts:metric{id=open label="Open tickets" value=12}
Tickets open now.
::: instruction.md's resolver retrieves no extension manifests. An optional extension's blocks are delivered as written and the result is partial:
### charts:metric: open
Attributes: {"label":"Open tickets","value":"12"}
Tickets open now. A binding with required: true stops delivery:
line 1: the extension dev.example/charts ("charts") is required, and this resolver binds no extension manifests [extension-unavailable] - A kind with an alias the front matter doesn't declare is an error,
extension-unavailable. - A binding without both
idandversionisinvalid-metadata. requires, a list of aliases, must name declared aliases.- Aliases are scoped to their document: a base's aliases don't apply in the child, and two documents may use one alias for two extensions.
A manifest has format: instruction-extension/1, an id of the form reverse.domain/name, an exact version, spec: ["1"], its roles (syntax, semantic, presentation, resolver, test-adapter or binding) and provides, the block and inline kinds it adds. Its schema is schemas/extension.schema.json in the specification.
Bundles and exports
The specification defines a bundle: a ZIP file with an instruction.json manifest (format: instruction-bundle/1), a main document, and each resource's path, media type, digest and original URI. Its schema is schemas/bundle.schema.json in the specification. The front matter's exports maps a name to an adapter, a profile and bindings to explicit block ids, for a compiler that writes runtime files.
instruction.md doesn't build bundles or compile exports. It checks that exports is a mapping and keeps it in the text. To save every version of an instruction, see Export.
If it doesn't work
| What you see | Why | What to do |
|---|---|---|
the include "<alias>": <src> could not be read [reference-missing] |
The source doesn't exist, you may not read it, or the tool reads no such sources | Check the address and your access; see Where sources come from |
… could not be read [reference-optional] |
The same, for an include without required: the result is partial |
As above, or leave it optional |
the base "<alias>" is pinned to <digest>, and <uri> is <digest> [pin-mismatch] |
The pinned source changed | Review the change, then pin the new digest |
the base "<alias>" asks for version <version>, and <uri> is <id> [pin-mismatch] |
The source reports another version than version |
Give the version's id (ver_…), or leave version out |
:::remove: its target is an inherited explicit id, #alias/id (it is "#mail") [patch-target] |
The target isn't qualified with a base's alias | Write #<alias>/<id> |
:::<patch>: nothing inherited has the id #<alias>/<id> [patch-target] |
No such id in the base, an earlier patch removed it, or the base didn't load | Check the base's ids |
… composes itself: <a> → <b> → <a> [composition-cycle] |
Two documents include or extend each other | Move the shared part into a third document |
the alias "<alias>" is used twice in <uri> [duplicate-id] |
Two includes or bases share an alias | Give each its own |
::include: "with" is not an attribute this kind takes [invalid-attributes] |
Includes take no values | Use extends with with, or give the included parameters defaults |
The diagnostics, as the resolver reports them:
line 1: the include "other": ./other.md could not be read [reference-missing]
line 1: the include "other": ./other.md could not be read [reference-optional]
line 6: :::remove: its target is an inherited explicit id, #alias/id (it is "#mail") [patch-target]
agents/morning.md: agents/morning.md composes itself: agents/morning.md → agents/a.md → agents/morning.md [composition-cycle] Every code is on Diagnostics and fixes. Still stuck: Support.