@markdown-ai/cli 1.0.0-rc.3 → 1.1.0

package/README.md

@@ -2,13 +2,14 @@
 
 `@markdown-ai/cli` installs one command: `mda`.
 
-Use it to create, validate, compile, canonicalize, and integrity-check Markdown AI
-(MDA) artifacts before humans, AI agents, CI jobs, or publishing pipelines use
-them.
+It helps you create, validate, compile, sign, verify, and release Markdown AI
+(MDA) artifacts. The main job is simple: keep the source clean, keep the output
+predictable, and give humans or AI agents a clear next step when something is
+wrong.
 
-The CLI is most useful at design time and CI time. It helps you write one `.mda`
-source file, then produce the Markdown files that agent systems already know how
-to read: `SKILL.md`, `AGENTS.md`, and `MCP-SERVER.md`.
+Most users start with one `.mda` source file. From that file, the CLI can emit
+the Markdown files agent systems already understand: `SKILL.md`, `AGENTS.md`,
+and `MCP-SERVER.md`.
 
 ## Install
 
@@ -27,8 +28,8 @@ mda --help
 
 The installed binary is `mda`.
 
-Running `mda` with no arguments prints complete help. That is intentional. A
-human or an AI agent can discover the command surface quickly without guessing.
+Running `mda` with no arguments prints help. It does not write files, validate
+files, sign anything, verify anything, or touch the network.
 
 ## Quick Start
 
@@ -58,14 +59,49 @@ mda validate out/AGENTS.md --target AGENTS.md
 mda integrity verify out/SKILL.md --target SKILL.md
 ```
 
-That is the main flow. Start there.
+That is the everyday flow. Create the source. Check it. Compile it. Check what
+came out.
 
-## For AI Agents
+## Release Quick Path For LLMix Registry
 
-Use `--json` almost every time.
+For LLMix releases, most teams should start with the GitHub Actions profile. It
+matches the CI identity shape people already expect from package provenance:
+GitHub Actions OIDC identity, explicit Sigstore/Rekor evidence, and a local
+policy pinned to repository, workflow, and ref.
 
-Human output is for eyes. JSON output is for code. It gives agents stable fields
-such as `ok`, `command`, `exitCode`, and `diagnostics`.
+```sh
+mda init --template llmix-preset --module search_summary --preset openai_fast --provider openai --model gpt-5-mini --out authoring/search_summary/openai_fast.mda
+mda validate authoring/search_summary/openai_fast.mda --target source
+mda integrity compute authoring/search_summary/openai_fast.mda --target source --write
+mda release trust policy --target llmix-registry --profile github-actions --repo owner/repo --workflow release.yml --ref refs/heads/main --out gha-policy.json
+mda sign authoring/search_summary/openai_fast.mda --profile github-actions --repo owner/repo --workflow release.yml --ref refs/heads/main --rekor --offline-sigstore-fixture sigstore-evidence.json --out authoring/search_summary/openai_fast.signed.mda
+mda verify authoring/search_summary/openai_fast.signed.mda --policy gha-policy.json --offline-sigstore-fixture sigstore-evidence.json --json
+mda release prepare --target llmix-registry --source authoring --registry-dir registry --policy gha-policy.json --offline-sigstore-fixture sigstore-evidence.json --out release-plan.json
+# Run the LLMix publisher with trustedRuntime: true. mda does not publish registry files.
+mda release finalize --target llmix-registry --registry-dir registry --registry-root registry/snapshots/current/registry-root.json --release-plan release-plan.json --policy gha-policy.json --derive-root-digest --out release/llmix-trust.json --offline-sigstore-fixture sigstore-evidence.json
+mda release finalize --target llmix-registry --registry-dir registry --manifest release/llmix-trust.json --snippet-format json --snippet-out release/llmix-trust-snippet.json
+mda doctor release --target llmix-registry --source authoring --registry-dir registry --release-plan release-plan.json --manifest release/llmix-trust.json --offline-sigstore-fixture sigstore-evidence.json
+```
+
+The `--offline-sigstore-fixture` option is the CLI 1.1 deterministic evidence
+input for local and CI gates. Production release automation can keep using
+GitHub Actions keyless signing and Sigstore/Rekor evidence; this CLI gate makes
+that evidence explicit and repeatable.
+
+## AI Agent Usage
+
+Use `--json` when another program is driving the CLI.
+
+Human output is meant to be read. JSON output is meant to be used. It gives
+stable fields:
+
+- `ok`
+- `command`
+- `exitCode`
+- `summary`
+- `artifacts`
+- `diagnostics`
+- `nextActions`
 
 Recommended agent flow:
 
@@ -82,25 +118,56 @@ Agent rules:
 
 - Treat exit code `0` and `ok: true` as success.
 - Treat any non-zero exit as a stop signal.
-- Read `diagnostics[0].code` before scraping human text.
-- Pass `--target` when the filename is not exact.
+- Read `diagnostics[0].code` before parsing messages.
+- Use `artifacts` and `nextActions` to decide the next command.
+- Pass `--target` when a Markdown filename is not exact.
 - Write generated files into a temp or staging directory first.
 
-This keeps the CLI useful as an external gate. Application runtime loaders should
-keep their own verifier hooks instead of shelling out to `mda`.
+The CLI is a good external gate. Application runtime loaders should still keep
+their own verifier hooks instead of shelling out to `mda`.
+
+## Secure Release Flow
+
+For signed MDA and LLMix releases, the default path is GitHub Actions OIDC plus
+Sigstore/Rekor evidence:
+
+```sh
+mda release trust policy --target llmix-registry --profile github-actions --repo owner/repo --workflow release.yml --ref refs/heads/main --out gha-policy.json
+mda sign release.mda --profile github-actions --repo owner/repo --workflow release.yml --ref refs/heads/main --rekor --offline-sigstore-fixture sigstore-evidence.json --out release.signed.mda
+mda verify release.signed.mda --policy gha-policy.json --offline-sigstore-fixture sigstore-evidence.json --json
+mda release prepare --target llmix-registry --source authoring --registry-dir registry --policy gha-policy.json --offline-sigstore-fixture sigstore-evidence.json --out release-plan.json
+mda release finalize --target llmix-registry --registry-dir registry --registry-root registry/snapshots/current/registry-root.json --release-plan release-plan.json --policy gha-policy.json --derive-root-digest --out release/llmix-trust.json --offline-sigstore-fixture sigstore-evidence.json
+mda release finalize --target llmix-registry --registry-dir registry --manifest release/llmix-trust.json --snippet-format json --snippet-out release/llmix-trust-snippet.json
+mda doctor release --target llmix-registry --source authoring --registry-dir registry --release-plan release-plan.json --manifest release/llmix-trust.json --offline-sigstore-fixture sigstore-evidence.json
+```
+
+Use did:web as an advanced or alternate signing profile when your team manages
+release keys and DID documents directly.
+
+Keep private keys and deployment trust manifests outside the registry directory.
+Trust authority should live outside `config/llm/`. The CLI checks that because
+it is the kind of mistake that looks fine until it matters.
 
 ## Common Commands
 
-| Command | Use it for |
-| --- | --- |
-| `mda` | Print full help. |
-| `mda init <name> --out <file.mda>` | Create a source scaffold. |
-| `mda validate <file> [--target <target>]` | Validate source or generated Markdown. |
-| `mda compile <file.mda> --target SKILL.md AGENTS.md --out-dir out --integrity` | Compile source into agent-readable artifacts. |
-| `mda canonicalize <file> --target <target>` | Produce deterministic canonical bytes. |
-| `mda integrity compute <file> --target <target>` | Compute a stable digest. |
-| `mda integrity verify <file> --target <target>` | Check the declared digest against current content. |
-| `mda conformance --level V --json` | Run the conformance suite. |
+| Command                                                                        | Use it for                                                                           |
+| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
+| `mda`                                                                          | Print help.                                                                          |
+| `mda init <name> --out <file.mda>`                                             | Create a source scaffold.                                                            |
+| `mda init --template llmix-preset ...`                                         | Create an LLMix preset source scaffold.                                              |
+| `mda validate <file> [--target <target>]`                                      | Validate source or generated Markdown.                                               |
+| `mda compile <file.mda> --target SKILL.md AGENTS.md --out-dir out --integrity` | Compile source into agent-readable artifacts.                                        |
+| `mda canonicalize <file> --target <target>`                                    | Produce deterministic canonical bytes.                                               |
+| `mda integrity compute <file> --target <target>`                               | Compute a stable digest.                                                             |
+| `mda integrity verify <file> --target <target>`                                | Check the declared digest against current content.                                   |
+| `mda sign <file> --profile did-web ...`                                        | Sign an artifact with explicit did:web key material.                                 |
+| `mda sign <file> --profile github-actions ...`                                 | Sign with explicit GitHub Actions Sigstore/Rekor evidence.                           |
+| `mda verify <file> --policy <policy.json>`                                     | Verify signatures against a local trust policy and explicit evidence.                |
+| `mda release prepare --target llmix-registry ...`                              | Verify signed LLMix presets and write a deterministic release plan.                  |
+| `mda release finalize --target llmix-registry ...`                             | Verify signed registry-root evidence, write an external trust manifest, or snippets. |
+| `mda doctor release --target llmix-registry ...`                               | Check release state before deployment.                                               |
+| `mda conformance --level V --json`                                             | Run validation conformance.                                                          |
+| `mda conformance --level C --json`                                             | Run compile/equality conformance.                                                    |
 
 Allowed targets:
 
@@ -120,9 +187,9 @@ Auto-detection is exact:
 
 ## Full Manual
 
-Read [HOW-TO-USE.md](./HOW-TO-USE.md) for the complete command manual, including
-all parameters, exit codes, MCP sidecar handling, integrity examples, and
-agent-oriented usage patterns.
+Read [HOW-TO-USE.md](./HOW-TO-USE.md) for the complete manual. It covers the
+human flow, AI agent JSON flow, signing, verification, LLMix secure release,
+MCP sidecars, integrity commands, global flags, exit codes, and conformance.
 
 For the broader project context, read the repository
 [README](https://github.com/sno-ai/mda#readme) and the
@@ -130,8 +197,10 @@ For the broader project context, read the repository
 
 ## Status
 
-This is the reference CLI for the Markdown AI / MDA artifact format.
+This is the 1.1 reference CLI for the Markdown AI / MDA artifact format.
 
-The useful path today is clear: author `.mda`, validate it, compile it, validate
-the outputs, and run integrity checks before publishing or handing files to an
-agent.
+The useful path is covered: author `.mda`, validate it, compile it, validate the
+outputs, run integrity checks, sign and verify release artifacts with explicit
+GitHub Actions Sigstore/Rekor evidence or did:web key material, and use the
+LLMix release/manifest/snippet/doctor commands before publishing or handing
+files to an agent.