instruction.md 0.2.0__tar.gz

instruction_md-0.2.0/LICENSE-APACHE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

instruction_md-0.2.0/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TSOK Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

instruction_md-0.2.0/MANIFEST.in

@@ -0,0 +1,3 @@
+# The source distribution runs its own tests: they read only the vendored conformance data (conformance/README.md),
+# which carries its own licences. The wheel holds the package alone (pyproject.toml's package data).
+graft conformance

instruction_md-0.2.0/NOTICE

@@ -0,0 +1,28 @@
+instruction.md (Python)
+Copyright (c) 2026 TSOK Inc.
+
+This package (sdks/python) is licensed under either of the MIT licence
+(LICENSE-MIT) or the Apache License, Version 2.0 (LICENSE-APACHE), at your
+option. That is the package's own licence: the rest of the repository it is
+built from keeps its own (the Business Source License 1.1), and does not
+apply to this package.
+
+The package additionally redistributes material from the Instruction
+Specification, under a different licence:
+
+  The instruction.md specification's registries
+  (`instruction_md/registry.json` and `instruction_md/workflow-registry.json`,
+  verbatim)
+    Source:  https://github.com/instruction-md/specification
+    Licence: Creative Commons Attribution 4.0 International (CC BY 4.0)
+             https://creativecommons.org/licenses/by/4.0/
+    Author:  instruction.md (TSOK Inc.)
+    Changes: none; redistributed verbatim.
+
+The source distribution also carries the data its tests read (`conformance/`,
+listed in `conformance/README.md`): the specification's conformance cases
+(Apache License 2.0, `conformance/specification/conformance/LICENSE`), its
+schemas and samples (CC BY 4.0, as above, verbatim), and the TypeScript
+reference implementation's vectors (MIT, `conformance/vectors/LICENSE`).
+
+CC BY 4.0 requires attribution, and attribution has to arrive with the copy.

instruction_md-0.2.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: instruction.md
+Version: 0.2.0
+Summary: Read, check, resolve and verify instruction.md files (the specification's first edition, instruction/1), and follow them from a registry
+Author: TSOK Inc.
+License-Expression: MIT OR Apache-2.0
+Project-URL: Homepage, https://instruction.md
+Project-URL: Documentation, https://instruction.md/docs/
+Project-URL: Specification, https://instruction.md/specification/
+Project-URL: Issues, https://github.com/instruction-md/specification/issues
+Keywords: instruction.md,agents,mcp,markdown
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE-MIT
+License-File: LICENSE-APACHE
+License-File: NOTICE
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: sign
+Requires-Dist: cryptography>=38; extra == "sign"
+Provides-Extra: mcp
+Requires-Dist: mcp>=2.3; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: cryptography>=38; extra == "dev"
+Requires-Dist: jsonschema>=4.20; extra == "dev"
+Dynamic: license-file
+
+# instruction.md (Python)
+
+The [instruction.md](https://instruction.md) specification's [first edition](https://instruction.md/specification/)
+(`instruction/1`) in Python: the reader and its checks, the inline syntax, resolution and the agent's text profile,
+the registry, the formatter, digests and signature verification — and a follower for instructions served over MCP. It
+is a port of the TypeScript reference, `instruction.md` on npm, byte-exact with its vectors and with the
+specification's conformance data.
+
+```sh
+pip install instruction.md               # Python 3.9 or later; PyYAML is its one dependency
+pip install 'instruction.md[sign]'       # signature verification (cryptography)
+pip install 'instruction.md[mcp]'        # following over MCP (the official mcp SDK 2.3 or later, Python 3.10 or later)
+```
+
+```python
+from instruction_md import check, digest, read, resolve
+
+text = """---
+spec: "1"
+title: House style
+parameters:
+  audience: { type: string, default: developers }
+---
+
+# House style
+
+You write for ${audience}.
+
+MUST: write in the second person.
+BECAUSE: the reader is the one acting.
+
+NEVER: promise a date you cannot keep.
+"""
+
+r = read(text)
+print(r.document.to_json()["format"])  # instruction/1: the authored tree, as the schema has it
+print(check(r))                         # []: no diagnostics
+res = resolve(text, uri="house-style.md", params={"audience": "support engineers"})
+print(res.ok)                           # True
+print(res.text, end="")                 # what the agent receives (instruction-text/1)
+print(digest(text))                     # sha256:… of the stored bytes
+```
+
+prints
+
+```text
+instruction/1
+[]
+True
+# House style
+
+You write for support engineers.
+
+MUST: write in the second person.
+BECAUSE: the reader is the one acting.
+
+NEVER: promise a date you cannot keep.
+sha256:20f4f08abec3d38ca9b2324884e1063fd1b0eb1751da2a5c08b29945b775ae84
+```
+
+- `read(text, fragment=False, uri=None)` → `ReadResult`: `document`, `diagnostics`, `identities`, `parameters`,
+  `footnotes`, and which Markdown nodes are prose, which keyword a rule was written with, where its reason was.
+  Nodes are `MarkdownNode` and `DirectiveNode` (`to_json()` gives the reference's JSON: `{format: "instruction/1",
+  metadata: {front, back}, body: [...]}`); a structured body is a `StructuredValue` with its `source` and, parsed,
+  its `data`. Metadata and structured bodies are YAML 1.2's Core Schema restricted to JSON: no anchors, aliases,
+  custom tags, non-string keys, non-finite numbers or second document, duplicate keys refused.
+- `check(text | ReadResult)` → `list[Diagnostic]`, the reader's diagnostics (§18) with the inline checks, in source
+  order: `code`, `severity`, `message`, `range` (and `uri` for another source's).
+- `inline_tokens(source)` → the inline forms — `:kind[label]{attrs}`, `[[target|label]]`, `![[…]]`, `[^note]`,
+  `$math$`, `${parameter}` — read where CommonMark reads text: never in code, raw HTML, an autolink, a link
+  destination or title, or a definition (the tokenizer is a port of micromark's, with GFM's tables, task list items
+  and autolink literals).
+- `resolve(text, uri=, version=, params=, load=)` composes bases (`extends`) with their patches, includes as separate
+  instances, pins and parameters; `load` is a callable (`uri → Source | str | None`) or a mapping of resolved URIs to
+  sources, and nothing is ever fetched. `res.text` is the agent text, `res.resolved.to_json()` the resolved artifact
+  (`instruction-resolved/1`, its `resolved_digest` in RFC 8785 form). `resolve_with(text, sources)` takes the sources
+  already loaded, `resolve_tree(tree, trees)` authored trees (as `AuthoredDocument` or JSON).
+- `to_text(tree, params=, parameters=, prose=, identities=, known=)` → the text profile of any tree, authored or
+  resolved; `canonical_json` / `json_digest` → RFC 8785; `format(text)` → the conservative formatter; `digest(text)`
+  → `sha256:` of the stored bytes, nothing stripped; the registry → `KINDS`, `INLINE`, `KEYWORDS`, `PATTERNS`, …
+  (the specification's `registry.json`, shipped with the package).
+- The workflow registry (`workflow-registry.json`, shipped with the package): `WORKFLOW_KINDS`,
+  `WORKFLOW_COMMON_FIELDS`, `WORKFLOW_LIMITS`; `WORKFLOW_SCOPES`, the kinds whose `body` or `branches` hold nested steps
+  (foreach, batch, iterate, subgraph; parallel, race), from reference/workflows.md, since the registry doesn't say:
+  another kind's field of that name (an `http` request's `body`) is data. The reader checks each `:::workflow{dialect="instruction/workflow"}` body
+  against it (unknown kinds and fields, required fields, triggers, dependencies, routes, cycles, scopes and limits:
+  `invalid-workflow`, `limit-exceeded`, `extension-unavailable`); `workflow_diagnostics(definition)` checks a
+  definition on its own.
+
+Offsets (an inline token's, a range's lines) index the Python string, by code point.
+
+## Signatures
+
+With the `sign` extra, `verify_author(jws, text, keys, doc=, pub=)` checks an author signature over the stored bytes;
+`verify_delivery(jws, delivered, delivery_keys, author_keys, aud=, authored_text=, pub=)` a delivery signature over
+what one reader received, with the author signature it embeds. A delivery binds its resolution: its `manifest` is
+`{format: "instruction-resolved/1", status, document: {uri, sha256, version?}, dependencies, resolved_digest}`
+(`Resolved.manifest()`), and the author's digest must be its document's `sha256`. `sign_jws` and `public_jwk` are for
+tests and tooling.
+
+## Following
+
+Following (asyncio, any MCP client with `read_resource` / `call_tool` / `subscribe_resource`): `InstructionFollower`;
+`McpSessionClient` adapts the official `mcp` SDK's session (the `mcp` extra). On the 2026-07-28 wire its subscription
+is a `subscriptions/listen` stream that calls `follower.notify`, and reopens after a drop; `mcp_auth.ClientCredentials`
+signs an agent in (the client-credentials grant, renewed before its five minutes are up).
+
+`watch` speaks MCP 2026-07-28, statelessly: `Client(transport, mode="2026-07-28")`. There is no `initialize` and no
+session id, so any replica of the server answers each request. It is the only protocol instruction.md supports, so
+pin it in your own code too: `mode="auto"` falls back to the older session handshake when its `server/discover`
+probe is answered with an error.
+
+## Command line
+
+```sh
+python -m instruction_md check FILE        # diagnostics on stderr; exit 1 on an error (warnings pass)
+python -m instruction_md tree FILE         # the authored tree as JSON
+python -m instruction_md deliver FILE [--param NAME=VALUE ...] [--resolved]
+                                           # the text a model receives; its bases and includes are read from the files
+                                           # beside it, under its directory (never above it, never a URL)
+python -m instruction_md format FILE       # the formatted text
+```
+
+and `watch` (the `mcp` extra) to follow an instruction on an instruction.md server. Each version applied is a JSON
+line on stdout, and each one held is a JSON line on stderr. The follower declares a binding and reports what it
+applied, so the instruction's maintainers see it among its consumers.
+
+```sh
+# as an agent: the studio's Settings ▸ Security makes the credential, and shows its id, secret and token URL once
+export INSTRUCTION_MD_CLIENT_ID=… INSTRUCTION_MD_TOKEN_URL=… INSTRUCTION_MD_CLIENT_SECRET=…
+python -m instruction_md watch instruction://acme/support-agent@latest \
+  --require-signature --require-delivery-signature --out AGENTS.md
+# once, in CI, with a token you already hold: exit 0 applied, 6 held
+python -m instruction_md watch instruction://ins_…@stable --token "$TOKEN" --once --require-signature
+```
+
+## Conformance
+
+The tests run the vendored data (`conformance/`, listed in its README): the specification's source, model (with
+`jsonschema` installed), resolution and text cases and its samples, and the reference's vectors — every read case's
+tree, diagnostics, identities, parameters and text, every resolution's artifact and text, the inline tokens — compared
+exactly. The source distribution carries both, so an unpacked sdist runs them:
+
+```sh
+python3 -m venv .venv && .venv/bin/pip install '.[dev]'
+.venv/bin/pytest
+```
+
+In the repository the package is built from, `scripts/sync-fixtures.sh [--check]` keeps those copies, the package's
+`registry.json` and `workflow-registry.json` in step with their sources. Malformed YAML is reported under the same code and line as
+the reference does, its message PyYAML's.
+
+## Licence
+
+Licensed under either of the MIT licence (`LICENSE-MIT`) or the Apache License, Version 2.0 (`LICENSE-APACHE`), at
+your option; the repository it is built from keeps its own licence, which does not apply to this package. It redistributes the specification's
+registries (`instruction_md/registry.json`, `instruction_md/workflow-registry.json`), unchanged, from
+[instruction-md/specification](https://github.com/instruction-md/specification) by instruction.md (TSOK Inc.), under
+the Creative Commons Attribution 4.0 International licence (https://creativecommons.org/licenses/by/4.0/); `NOTICE`
+says so, and lists the licences of the conformance data the source distribution carries.

instruction_md-0.2.0/README.md

@@ -0,0 +1,160 @@
+# instruction.md (Python)
+
+The [instruction.md](https://instruction.md) specification's [first edition](https://instruction.md/specification/)
+(`instruction/1`) in Python: the reader and its checks, the inline syntax, resolution and the agent's text profile,
+the registry, the formatter, digests and signature verification — and a follower for instructions served over MCP. It
+is a port of the TypeScript reference, `instruction.md` on npm, byte-exact with its vectors and with the
+specification's conformance data.
+
+```sh
+pip install instruction.md               # Python 3.9 or later; PyYAML is its one dependency
+pip install 'instruction.md[sign]'       # signature verification (cryptography)
+pip install 'instruction.md[mcp]'        # following over MCP (the official mcp SDK 2.3 or later, Python 3.10 or later)
+```
+
+```python
+from instruction_md import check, digest, read, resolve
+
+text = """---
+spec: "1"
+title: House style
+parameters:
+  audience: { type: string, default: developers }
+---
+
+# House style
+
+You write for ${audience}.
+
+MUST: write in the second person.
+BECAUSE: the reader is the one acting.
+
+NEVER: promise a date you cannot keep.
+"""
+
+r = read(text)
+print(r.document.to_json()["format"])  # instruction/1: the authored tree, as the schema has it
+print(check(r))                         # []: no diagnostics
+res = resolve(text, uri="house-style.md", params={"audience": "support engineers"})
+print(res.ok)                           # True
+print(res.text, end="")                 # what the agent receives (instruction-text/1)
+print(digest(text))                     # sha256:… of the stored bytes
+```
+
+prints
+
+```text
+instruction/1
+[]
+True
+# House style
+
+You write for support engineers.
+
+MUST: write in the second person.
+BECAUSE: the reader is the one acting.
+
+NEVER: promise a date you cannot keep.
+sha256:20f4f08abec3d38ca9b2324884e1063fd1b0eb1751da2a5c08b29945b775ae84
+```
+
+- `read(text, fragment=False, uri=None)` → `ReadResult`: `document`, `diagnostics`, `identities`, `parameters`,
+  `footnotes`, and which Markdown nodes are prose, which keyword a rule was written with, where its reason was.
+  Nodes are `MarkdownNode` and `DirectiveNode` (`to_json()` gives the reference's JSON: `{format: "instruction/1",
+  metadata: {front, back}, body: [...]}`); a structured body is a `StructuredValue` with its `source` and, parsed,
+  its `data`. Metadata and structured bodies are YAML 1.2's Core Schema restricted to JSON: no anchors, aliases,
+  custom tags, non-string keys, non-finite numbers or second document, duplicate keys refused.
+- `check(text | ReadResult)` → `list[Diagnostic]`, the reader's diagnostics (§18) with the inline checks, in source
+  order: `code`, `severity`, `message`, `range` (and `uri` for another source's).
+- `inline_tokens(source)` → the inline forms — `:kind[label]{attrs}`, `[[target|label]]`, `![[…]]`, `[^note]`,
+  `$math$`, `${parameter}` — read where CommonMark reads text: never in code, raw HTML, an autolink, a link
+  destination or title, or a definition (the tokenizer is a port of micromark's, with GFM's tables, task list items
+  and autolink literals).
+- `resolve(text, uri=, version=, params=, load=)` composes bases (`extends`) with their patches, includes as separate
+  instances, pins and parameters; `load` is a callable (`uri → Source | str | None`) or a mapping of resolved URIs to
+  sources, and nothing is ever fetched. `res.text` is the agent text, `res.resolved.to_json()` the resolved artifact
+  (`instruction-resolved/1`, its `resolved_digest` in RFC 8785 form). `resolve_with(text, sources)` takes the sources
+  already loaded, `resolve_tree(tree, trees)` authored trees (as `AuthoredDocument` or JSON).
+- `to_text(tree, params=, parameters=, prose=, identities=, known=)` → the text profile of any tree, authored or
+  resolved; `canonical_json` / `json_digest` → RFC 8785; `format(text)` → the conservative formatter; `digest(text)`
+  → `sha256:` of the stored bytes, nothing stripped; the registry → `KINDS`, `INLINE`, `KEYWORDS`, `PATTERNS`, …
+  (the specification's `registry.json`, shipped with the package).
+- The workflow registry (`workflow-registry.json`, shipped with the package): `WORKFLOW_KINDS`,
+  `WORKFLOW_COMMON_FIELDS`, `WORKFLOW_LIMITS`; `WORKFLOW_SCOPES`, the kinds whose `body` or `branches` hold nested steps
+  (foreach, batch, iterate, subgraph; parallel, race), from reference/workflows.md, since the registry doesn't say:
+  another kind's field of that name (an `http` request's `body`) is data. The reader checks each `:::workflow{dialect="instruction/workflow"}` body
+  against it (unknown kinds and fields, required fields, triggers, dependencies, routes, cycles, scopes and limits:
+  `invalid-workflow`, `limit-exceeded`, `extension-unavailable`); `workflow_diagnostics(definition)` checks a
+  definition on its own.
+
+Offsets (an inline token's, a range's lines) index the Python string, by code point.
+
+## Signatures
+
+With the `sign` extra, `verify_author(jws, text, keys, doc=, pub=)` checks an author signature over the stored bytes;
+`verify_delivery(jws, delivered, delivery_keys, author_keys, aud=, authored_text=, pub=)` a delivery signature over
+what one reader received, with the author signature it embeds. A delivery binds its resolution: its `manifest` is
+`{format: "instruction-resolved/1", status, document: {uri, sha256, version?}, dependencies, resolved_digest}`
+(`Resolved.manifest()`), and the author's digest must be its document's `sha256`. `sign_jws` and `public_jwk` are for
+tests and tooling.
+
+## Following
+
+Following (asyncio, any MCP client with `read_resource` / `call_tool` / `subscribe_resource`): `InstructionFollower`;
+`McpSessionClient` adapts the official `mcp` SDK's session (the `mcp` extra). On the 2026-07-28 wire its subscription
+is a `subscriptions/listen` stream that calls `follower.notify`, and reopens after a drop; `mcp_auth.ClientCredentials`
+signs an agent in (the client-credentials grant, renewed before its five minutes are up).
+
+`watch` speaks MCP 2026-07-28, statelessly: `Client(transport, mode="2026-07-28")`. There is no `initialize` and no
+session id, so any replica of the server answers each request. It is the only protocol instruction.md supports, so
+pin it in your own code too: `mode="auto"` falls back to the older session handshake when its `server/discover`
+probe is answered with an error.
+
+## Command line
+
+```sh
+python -m instruction_md check FILE        # diagnostics on stderr; exit 1 on an error (warnings pass)
+python -m instruction_md tree FILE         # the authored tree as JSON
+python -m instruction_md deliver FILE [--param NAME=VALUE ...] [--resolved]
+                                           # the text a model receives; its bases and includes are read from the files
+                                           # beside it, under its directory (never above it, never a URL)
+python -m instruction_md format FILE       # the formatted text
+```
+
+and `watch` (the `mcp` extra) to follow an instruction on an instruction.md server. Each version applied is a JSON
+line on stdout, and each one held is a JSON line on stderr. The follower declares a binding and reports what it
+applied, so the instruction's maintainers see it among its consumers.
+
+```sh
+# as an agent: the studio's Settings ▸ Security makes the credential, and shows its id, secret and token URL once
+export INSTRUCTION_MD_CLIENT_ID=… INSTRUCTION_MD_TOKEN_URL=… INSTRUCTION_MD_CLIENT_SECRET=…
+python -m instruction_md watch instruction://acme/support-agent@latest \
+  --require-signature --require-delivery-signature --out AGENTS.md
+# once, in CI, with a token you already hold: exit 0 applied, 6 held
+python -m instruction_md watch instruction://ins_…@stable --token "$TOKEN" --once --require-signature
+```
+
+## Conformance
+
+The tests run the vendored data (`conformance/`, listed in its README): the specification's source, model (with
+`jsonschema` installed), resolution and text cases and its samples, and the reference's vectors — every read case's
+tree, diagnostics, identities, parameters and text, every resolution's artifact and text, the inline tokens — compared
+exactly. The source distribution carries both, so an unpacked sdist runs them:
+
+```sh
+python3 -m venv .venv && .venv/bin/pip install '.[dev]'
+.venv/bin/pytest
+```
+
+In the repository the package is built from, `scripts/sync-fixtures.sh [--check]` keeps those copies, the package's
+`registry.json` and `workflow-registry.json` in step with their sources. Malformed YAML is reported under the same code and line as
+the reference does, its message PyYAML's.
+
+## Licence
+
+Licensed under either of the MIT licence (`LICENSE-MIT`) or the Apache License, Version 2.0 (`LICENSE-APACHE`), at
+your option; the repository it is built from keeps its own licence, which does not apply to this package. It redistributes the specification's
+registries (`instruction_md/registry.json`, `instruction_md/workflow-registry.json`), unchanged, from
+[instruction-md/specification](https://github.com/instruction-md/specification) by instruction.md (TSOK Inc.), under
+the Creative Commons Attribution 4.0 International licence (https://creativecommons.org/licenses/by/4.0/); `NOTICE`
+says so, and lists the licences of the conformance data the source distribution carries.

instruction_md-0.2.0/conformance/README.md

@@ -0,0 +1,17 @@
+# Conformance data
+
+Vendored from `packages/spec` by `scripts/sync-fixtures.sh` (`--check` fails when a copy differs); never edited
+here. The SDK's tests run against these files alone, so they need no Node.
+
+| Here | From | What | Licence |
+|---|---|---|---|
+| `specification/conformance/` | `packages/spec/specification/conformance/` | the specification's conformance cases: source structure, the model's schema, resolution of trees, workflow definitions, the text profile | Apache-2.0 (`specification/conformance/LICENSE`) |
+| `specification/instruction.schema.json`, `specification/schemas/` | `packages/spec/specification/` | the authored tree's schema, the resolved snapshot's and the others | CC BY 4.0 |
+| `specification/samples/` | `packages/spec/specification/samples/` | the specification's sample documents | CC BY 4.0 |
+| `vectors/` | `packages/spec/vectors/` | what the reference implementation produces, byte for byte: reading, resolution, inline tokens, workflow diagnostics (`vectors/README.md`) | MIT (`vectors/LICENSE`) |
+
+The specification's data (the conformance cases, the schemas, the samples, and the registries the package ships as
+`instruction_md/registry.json` and `instruction_md/workflow-registry.json`) is [instruction-md/specification](https://github.com/instruction-md/specification)'s,
+branch `codex/first-specification` at `af8400f` — by instruction.md (TSOK Inc.), redistributed unchanged; the
+registry, schemas and samples under the Creative Commons Attribution 4.0 International licence
+(https://creativecommons.org/licenses/by/4.0/). The vectors are written by the TypeScript reference (`packages/spec`, `instruction.md` on npm).