Cette page n’est pas encore traduite.

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:

agents/morning.md
# 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:

Delivered
# 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:

Markdown
::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:

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:

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:

agents/morning.md
---
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.
How a base and a child's patches become one delivered text.

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:

  1. Each base in declared order, each resolved on its own first: its own bases, patches and includes.
  2. The child's replace, extend and remove patches, in source order, against the inherited tree as it stands after the patches before them.
  3. The child's own body, with its includes resolved.
Shell
instruction deliver agents/morning.md
Output
# 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:

Front matter
---
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 replace keeps the target's kind. To turn a policy into something else, remove it 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:
Markdown
:::replace{target="#base/limits" format=yaml}
max_refund: 150
:::
  • To change a Markdown target's attributes too, put a properties block with patch=true in 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:
Markdown
::::replace{target="#team/privacy"}
:::properties{patch=true}
title: Privacy
:::
NEVER: share a private event.
::::
  • An allowance in 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/privacy and #b/privacy. Neither overrides the other.
  • A document inherited twice, by two paths, makes two instances.
  • An unqualified #id names 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:

Shell
instruction digest agents/team.md
Output
sha256:c1610971508b4baaddfc331921ad3e90ac68761335ee3791461743453a449b4b

A released version's digest is the digest that instructions_versions_get and instructions_versions_read return.

agents/morning.md, pinned
---
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:

stderr (exit code 1)
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:

text
- <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:

instruction-resolved/1 (part)
{
  "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:

Markdown
---
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:

Delivered (status: partial)
### charts:metric: open

Attributes: {"label":"Open tickets","value":"12"}

Tickets open now.

A binding with required: true stops delivery:

stderr (exit code 1)
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 id and version is invalid-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:

Diagnostics
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.

Last checked against the product:

Was this page helpful? Report a problem