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

package/HOW-TO-USE.md

@@ -1,78 +1,93 @@
-# Markdown AI CLI
+# Markdown AI CLI Manual
 
-`@markdown-ai/cli` gives you one small command: `mda`.
+`@markdown-ai/cli` gives you one command: `mda`.
 
-It takes a `.mda` source file and turns it into the Markdown files that agents already know how to read: `SKILL.md`, `AGENTS.md`, and `MCP-SERVER.md`.
+Use it to create, validate, compile, sign, verify, and release Markdown AI
+(MDA) artifacts. The CLI is built for two readers at the same time: a human at a
+terminal, and an AI agent that needs stable JSON and clear next actions.
 
-The most useful path is simple:
+The short version:
 
 ```sh
-npx @markdown-ai/cli init hello-skill --out hello.mda
-npx @markdown-ai/cli validate hello.mda
-npx @markdown-ai/cli compile hello.mda --target SKILL.md AGENTS.md --out-dir out --integrity
+mda init hello-skill --out hello.mda
+mda validate hello.mda
+mda compile hello.mda --target SKILL.md AGENTS.md --out-dir out --integrity
+mda validate out/SKILL.md --target SKILL.md
+mda integrity verify out/SKILL.md --target SKILL.md
 ```
 
-That is the main flow. Start there.
+That is the center of the tool. Everything else is there to make the same flow
+safer, more explicit, or easier to automate.
 
-Run the command with no arguments whenever you are lost:
+## Install And Help
+
+Run without installing:
 
 ```sh
-npx @markdown-ai/cli
+npx @markdown-ai/cli --help
 ```
 
-No arguments means help. It does not validate files, write files, sign anything, verify anything, or touch the network.
-
-After installation, the binary name is `mda`:
+Install globally:
 
 ```sh
 npm install -g @markdown-ai/cli
 mda --help
 ```
 
-## Quick Start
+The installed binary is `mda`.
+
+Running `mda` with no arguments prints help. It does not validate, write, sign,
+verify, or touch the network.
+
+## Main Human Flow
 
-Create a source file:
+Start with a source file:
 
 ```sh
 mda init hello-skill --out hello.mda
 ```
 
-Validate it:
+Open `hello.mda`. Edit the name, description, metadata, and body. Then validate
+it:
 
 ```sh
 mda validate hello.mda
 ```
 
-Compile it into agent-readable Markdown:
+Compile it:
 
 ```sh
 mda compile hello.mda --target SKILL.md AGENTS.md --out-dir out --integrity
 ```
 
-Validate the output:
+Validate the emitted files:
 
 ```sh
 mda validate out/SKILL.md --target SKILL.md
 mda validate out/AGENTS.md --target AGENTS.md
+mda integrity verify out/SKILL.md --target SKILL.md
 ```
 
-Check the integrity field:
+Human output includes `Next:` guidance when the next command is obvious. You can
+turn that off with `--no-next`:
 
 ```sh
-mda integrity verify out/SKILL.md --target SKILL.md
+mda validate hello.mda --no-next
 ```
 
-For most users, that is enough. You create one `.mda`, compile it, and hand the output files to the system that needs them.
-
-## For AI Agents
+## Main AI Agent Flow
 
 Use `--json` almost every time.
 
-Human output is for eyes. JSON output is for code. It gives you stable fields: `ok`, `command`, `exitCode`, and `diagnostics`.
+Human output is for eyes. JSON output is for code. It contains stable fields:
 
-There are two good ways for an agent to use this CLI.
-
-The first is authoring. The agent creates or edits `.mda`, validates it, compiles it, then validates the outputs.
+- `ok`
+- `command`
+- `exitCode`
+- `summary`
+- `artifacts`
+- `diagnostics`
+- `nextActions`
 
 Recommended authoring flow:
 
@@ -86,154 +101,259 @@ mda validate out/MCP-SERVER.md --target MCP-SERVER.md --json
 mda integrity verify out/SKILL.md --target SKILL.md --json
 ```
 
-The second is runtime checking. This does not mean your application should depend on `@markdown-ai/cli`, or shell out from a library loader. It means an AI agent can run `mda` as an external gate before it trusts, edits, compiles, or acts on an MDA artifact.
+Agent rules:
+
+- Continue only when `ok` is `true` and `exitCode` is `0`.
+- Stop on any non-zero exit.
+- Read `diagnostics[0].code` before reading human messages.
+- Use `artifacts` for paths produced by a command.
+- Use `nextActions` for the next safe command.
+- Pass `--target` when the filename is not exact.
+- Write generated files into a temp or staging directory first.
+
+Do not scrape human text when JSON is available. That is noise in the signal
+chain. The JSON is the signal.
+
+## Targets
+
+Targets tell the CLI what kind of artifact a file is.
+
+Allowed targets:
+
+- `source`
+- `SKILL.md`
+- `AGENTS.md`
+- `MCP-SERVER.md`
+- `auto`
+
+Auto-detection is exact:
+
+- `*.mda` means `source`
+- `SKILL.md` means `SKILL.md`
+- `AGENTS.md` means `AGENTS.md`
+- `MCP-SERVER.md` means `MCP-SERVER.md`
+- any other Markdown filename needs `--target`
+
+When in doubt, pass `--target`.
 
-Good runtime agent checks:
+## MCP Sidecars
+
+Plain validation of `MCP-SERVER.md` does not need a sidecar:
 
 ```sh
-mda validate config.mda --target source --json
-mda integrity verify config.mda --target source --json
-mda validate SKILL.md --target SKILL.md --json
-mda validate AGENTS.md --target AGENTS.md --json
-mda canonicalize SKILL.md --target SKILL.md --json
+mda validate out/MCP-SERVER.md --target MCP-SERVER.md --json
 ```
 
-For MCP multi-file artifacts:
+Canonical bytes and integrity checks need the sidecar when the artifact is
+multi-file:
 
 ```sh
-mda validate MCP-SERVER.md --target MCP-SERVER.md --json
-mda integrity verify MCP-SERVER.md --target MCP-SERVER.md --sidecar mcp-server.json --json
+mda canonicalize out/MCP-SERVER.md --target MCP-SERVER.md --sidecar out/mcp-server.json --json
+mda integrity verify out/MCP-SERVER.md --target MCP-SERVER.md --sidecar out/mcp-server.json --json
 ```
 
-An agent should treat these checks as a gate:
+## Integrity
 
-- If `ok` is `true` and `exitCode` is `0`, continue.
-- If the command exits non-zero, stop using that artifact and report `diagnostics`.
-- If the file is a Markdown file with a non-standard name, pass `--target`.
-- If the command needs to write files, write into a temp or staging directory first.
+Integrity is a stable fingerprint of the canonical artifact bytes. It tells you
+whether the bytes changed. It does not prove who wrote them.
 
-Do not use this CLI as the only runtime trust boundary for an application. `mda verify` is not a complete cryptographic verifier in this MVP, and `mda sign` is intentionally unavailable. Use library-level verifier hooks for application runtime trust decisions.
+Compute a digest:
 
-Read success like this:
+```sh
+mda integrity compute hello.mda --target source --json
+```
 
-- `ok: true`
-- `exitCode: 0`
+Write the digest into frontmatter:
 
-Read failure like this:
+```sh
+mda integrity compute hello.mda --target source --write
+```
 
-- Check `diagnostics[0].code` first.
-- Then read `diagnostics[0].message`.
-- Do not scrape human text from stderr when `--json` is available.
+Verify it later:
 
-Use explicit targets when the filename is not obvious. The CLI can detect `hello.mda`, `SKILL.md`, `AGENTS.md`, and `MCP-SERVER.md`. Any other Markdown filename needs `--target`.
+```sh
+mda integrity verify hello.mda --target source
+```
+
+For compiled output:
+
+```sh
+mda compile hello.mda --target SKILL.md AGENTS.md MCP-SERVER.md --out-dir out --integrity --manifest out/compile-manifest.json
+```
+
+The compile manifest records source digest, output digests, compiler version,
+capability summary, and compatibility diagnostics.
 
-Good:
+Use `--strict-compat` when warnings should block output:
 
 ```sh
-mda validate generated.md --target SKILL.md --json
+mda compile hello.mda --target SKILL.md AGENTS.md --out-dir out --manifest out/compile-manifest.json --strict-compat
 ```
 
-Ambiguous:
+## Signing And Verification
+
+Signing proves the artifact came from an expected signer. Verification checks
+the signature, payload digest, and local trust policy.
+
+### GitHub Actions Sigstore/Rekor
+
+Most teams should start here. The production trust shape is GitHub Actions OIDC
+identity, Sigstore/Rekor evidence, and a policy pinned to repository, workflow,
+and exact ref.
+
+The CLI 1.1 local gate is deterministic. It consumes explicit evidence through
+`--offline-sigstore-fixture <path>` so signing, verification, release planning,
+and doctor checks do not depend on hidden environment variables or live network
+services.
+
+Production shape:
+
+- GitHub Actions keyless signing identity.
+- Sigstore bundle or Rekor evidence retained with the release.
+- Trust policy pinned to `repo`, `workflow`, and `ref`.
+
+Offline and test shape:
+
+- `--offline-sigstore-fixture <path>` supplies explicit replayable evidence.
+- Tests and local release gates should use deterministic evidence files.
+
+Create a GitHub Actions policy:
 
 ```sh
-mda validate generated.md --json
+mda release trust policy --target llmix-registry --profile github-actions --repo owner/repo --workflow release.yml --ref refs/heads/main --out gha-policy.json
 ```
 
-For MCP multi-file commands, always pass the sidecar when canonicalizing or checking integrity:
+Sign with explicit GitHub Actions evidence:
 
 ```sh
-mda canonicalize out/MCP-SERVER.md --target MCP-SERVER.md --sidecar out/mcp-server.json --json
-mda integrity verify out/MCP-SERVER.md --target MCP-SERVER.md --sidecar out/mcp-server.json --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
 ```
 
-Plain validation of `MCP-SERVER.md` does not need the sidecar:
+Verify with the same explicit evidence:
 
 ```sh
-mda validate out/MCP-SERVER.md --target MCP-SERVER.md --json
+mda verify release.signed.mda --policy gha-policy.json --offline-sigstore-fixture sigstore-evidence.json --json
 ```
 
-## For Humans
+`mda verify --offline` is intentionally unsupported. Use
+`--offline-sigstore-fixture <path>` so the evidence is visible in the command.
+No hidden environment, no repo-local default key path.
+
+### did:web
 
-The easiest way is to run one command at a time and look at the file it produced.
+Use did:web when your team manages release keys and DID documents directly.
 
-Start with:
+Create a did:web policy:
 
 ```sh
-mda init hello-skill --out hello.mda
+mda release trust policy --target llmix-registry --profile did-web --domain tools.example.com --out did-policy.json
 ```
 
-Open `hello.mda`. Edit the name, description, and body. Then run:
+Sign with explicit key material:
 
 ```sh
-mda validate hello.mda
+mda sign release.mda --profile did-web --did did:web:tools.example.com --key-id did:web:tools.example.com#release --key-file did-web-private.pem --out release.signed.mda
 ```
 
-If it passes, compile:
+Verify with an explicit DID document:
 
 ```sh
-mda compile hello.mda --target SKILL.md AGENTS.md --out-dir out --integrity
+mda verify release.signed.mda --policy did-policy.json --did-document did.json --json
 ```
 
-You will get files under `out/`. Use those files where your agent runtime expects them.
+There is a compatibility alias for older scripts:
 
-The word `integrity` sounds like cryptography. Here it mostly means "make a stable fingerprint of the file, then check that the file still matches it." It is like a checksum on a downloaded file. It tells you whether bytes changed. It does not prove who wrote the file.
+```sh
+mda sign release.mda --method did-web --key did-web-private.pem --identity tools.example.com --out release.signed.mda
+```
 
-Signing and full trust verification are not ready in this MVP. The CLI fails closed instead of pretending. That is intentional.
+## Release Workflow For LLMix Registry
 
-## What To Use Most
+The LLMix flow is there to help a user move from signed source presets to an
+external deployment trust manifest. It does not publish the registry for you.
+It tells you when the inputs are ready, then points to the next step.
 
-Use these commands day to day:
+### 1. Scaffold An LLMix Preset
 
 ```sh
-mda
-mda init <name> --out <file.mda>
-mda validate <file> [--target <target>]
-mda compile <file.mda> --target SKILL.md AGENTS.md --out-dir out --integrity
-mda integrity verify <file> --target <target>
+mda init --template llmix-preset --module search_summary --preset openai_fast --provider openai --model gpt-5-mini --out authoring/search_summary/openai_fast.mda
 ```
 
-Use these when you need exact bytes or automated checks:
+Validate and add integrity:
 
 ```sh
-mda canonicalize <file> --target <target> --json
-mda integrity compute <file> --target <target> --algorithm sha256 --json
-mda conformance --level V --json
+mda validate authoring/search_summary/openai_fast.mda --target source
+mda integrity compute authoring/search_summary/openai_fast.mda --target source --write
 ```
 
-Use these carefully:
+### 2. Sign And Verify The Source
 
 ```sh
-mda verify <file> --policy <policy.json> --json
-mda sign <file> --method did-web --key <key.pem> --identity <domain> --out <signed.md>
+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
 ```
 
-`verify` validates policy shape and integrity, then fails when real signature verification is required. `sign` is unavailable in this MVP. Both commands exist so scripts can depend on the shape without getting a fake security result.
+### 3. Create The Release Plan
 
-## Targets
+```sh
+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
+```
 
-Targets tell the CLI what kind of artifact a file is.
+The release plan checks validation, integrity, signatures, signer identity, and
+the expected registry entry identity. It writes deterministic release evidence.
+It does not modify the registry and does not publish registry files.
 
-Allowed targets:
+After this step, run the LLMix publisher with `trustedRuntime: true`. The
+publisher owns registry writes. After publishing or staging the registry, sign
+the registry root. Then use `mda release finalize --target llmix-registry` to verify the signed
+registry root and produce the external deployment trust manifest.
 
-- `source`
-- `SKILL.md`
-- `AGENTS.md`
-- `MCP-SERVER.md`
-- `auto`
+### 4. Create The External Trust Manifest
 
-Auto-detection is exact:
+```sh
+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` means `source`
-- `SKILL.md` means `SKILL.md`
-- `AGENTS.md` means `AGENTS.md`
-- `MCP-SERVER.md` means `MCP-SERVER.md`
-- any other `.md` file needs `--target`
+The trust manifest must be outside the registry directory. The CLI rejects
+direct paths, relative traversal, and symlink cases that put trust authority back
+inside the registry.
 
-When in doubt, pass `--target`. It removes ambiguity for humans and agents.
+### 5. Generate Deployment Snippets
+
+```sh
+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 release finalize --target llmix-registry --registry-dir registry --manifest release/llmix-trust.json --snippet-format env --snippet-out release/llmix-trust.env
+mda release finalize --target llmix-registry --registry-dir registry --manifest release/llmix-trust.json --snippet-format kubernetes --snippet-out release/llmix-trust.yaml
+```
+
+Supported snippet formats:
+
+- `json`
+- `env`
+- `kubernetes`
+- `github-actions`
+- `terraform`
+- `typescript`
+- `python`
+- `rust`
+
+Snippets reference external trust anchors. They do not tell you to put authority
+inside `config/llm/`.
+
+### 6. Run Doctor Before Deployment
+
+```sh
+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
+```
+
+`doctor release` is read-only. It checks source readiness, registry root evidence,
+signature trust, manifest placement, manifest schema, freshness, high-watermark,
+and recovery next actions.
 
 ## Command Reference
 
-Print full help:
+Print help:
 
 ```sh
 mda
@@ -246,10 +366,11 @@ Create a source scaffold:
 mda init <name> [--out <file>] [--json]
 ```
 
-Options:
+Create an LLMix preset source scaffold:
 
-- `--out <file>` writes the scaffold to a file and refuses to overwrite.
-- `--json` returns the scaffold inside JSON instead of raw `.mda` text.
+```sh
+mda init --template llmix-preset --module <name> --preset <name> --provider <provider> --model <model> [--out <file>] [--json]
+```
 
 Validate a source or output file:
 
@@ -257,91 +378,54 @@ Validate a source or output file:
 mda validate <file> [--target source|SKILL.md|AGENTS.md|MCP-SERVER.md|auto] [--json]
 ```
 
-Options:
-
-- `--target <target>` sets the artifact type. Default: `auto`.
-- `--json` prints machine-readable output.
-
 Compile a source file:
 
 ```sh
-mda compile <file.mda> --target <target...> [--out-dir <dir>] [--integrity] [--json]
+mda compile <file.mda> --target <target...> [--out-dir <dir>] [--integrity] [--manifest <path>] [--strict-compat] [--json]
 ```
 
-Options:
-
-- `--target <target...>` is required. Use one or more of `SKILL.md`, `AGENTS.md`, `MCP-SERVER.md`.
-- `--out-dir <dir>` writes outputs into a directory. Default: current directory.
-- `--integrity` adds a `sha256` integrity field to emitted artifacts.
-- `--json` lists planned and written output files.
-
 Canonicalize a file:
 
 ```sh
 mda canonicalize <file> [--target source|SKILL.md|AGENTS.md|MCP-SERVER.md|auto] [--sidecar <path>] [--json]
 ```
 
-Options:
-
-- `--target <target>` sets the artifact type. Default: `auto`.
-- `--sidecar <path>` is required only for MCP multi-file canonical bytes.
-- `--json` returns base64 canonical bytes and metadata. Without `--json`, raw canonical bytes are printed.
-
 Compute integrity:
 
 ```sh
-mda integrity compute <file> [--target source|SKILL.md|AGENTS.md|MCP-SERVER.md|auto] [--sidecar <path>] [--algorithm sha256|sha384|sha512] [--json]
+mda integrity compute <file> [--target source|SKILL.md|AGENTS.md|MCP-SERVER.md|auto] [--sidecar <path>] [--algorithm sha256|sha384|sha512] [--write] [--json]
 ```
 
-Options:
-
-- `--target <target>` sets the artifact type. Default: `auto`.
-- `--sidecar <path>` is required only for `MCP-SERVER.md` multi-file integrity.
-- `--algorithm <name>` chooses `sha256`, `sha384`, or `sha512`. Default: `sha256`.
-- `--json` prints the digest in JSON.
-
 Verify integrity:
 
 ```sh
 mda integrity verify <file> [--target source|SKILL.md|AGENTS.md|MCP-SERVER.md|auto] [--sidecar <path>] [--json]
 ```
 
-Options:
-
-- `--target <target>` sets the artifact type. Default: `auto`.
-- `--sidecar <path>` is required only for `MCP-SERVER.md` multi-file integrity.
-- `--json` prints the verification result in JSON.
-
-Verify trust policy and signatures:
+Sign an artifact:
 
 ```sh
-mda verify <file> --policy <path> [--target source|SKILL.md|AGENTS.md|MCP-SERVER.md|auto] [--sidecar <path>] [--json]
+mda sign <file> --profile did-web --did <did> --key-id <key-id> --key-file <path> (--out <file>|--in-place) [--json]
+mda sign <file> --profile github-actions --repo <owner/repo> --workflow <workflow> --ref <ref> --rekor --offline-sigstore-fixture <path> (--out <file>|--in-place) [--json]
+mda sign <file> --method did-web --key <path> --identity <domain> (--out <file>|--in-place) [--json]
 ```
 
-Options:
-
-- `--policy <path>` is required.
-- `--target <target>` sets the artifact type. Default: `auto`.
-- `--sidecar <path>` is required only for `MCP-SERVER.md` multi-file integrity.
-- `--json` prints the result in JSON.
-- `--offline` exists only as an unsupported MVP flag. It exits with a usage error.
-
-Sign an artifact:
+Verify signatures:
 
 ```sh
-mda sign <file> --method did-web --key <path> --identity <domain> (--out <file>|--in-place) [--json]
+mda verify <file> --policy <path> [--did-document <path>] [--offline-sigstore-fixture <path>] [--target source|SKILL.md|AGENTS.md|MCP-SERVER.md|auto] [--sidecar <path>] [--json]
 ```
 
-Options:
-
-- `--method did-web` is required.
-- `--key <path>` is required.
-- `--identity <domain>` is required.
-- `--out <file>` writes signed output to a new file.
-- `--in-place` replaces the input file.
-- `--json` prints the result in JSON.
+Run release workflow helpers:
 
-Signing is intentionally unavailable in this MVP. The command exits non-zero with `signing-unavailable`.
+```sh
+mda release trust policy --target llmix-registry --profile did-web --domain <domain> [--min-signatures <n>] [--out <file>] [--json]
+mda release trust policy --target llmix-registry --profile github-actions --repo <owner/repo> --workflow <workflow> --ref <ref> [--out <file>] [--json]
+mda release prepare --target llmix-registry --source <dir> --registry-dir <dir> --policy <path> --out <file> [--did-document <path>] [--offline-sigstore-fixture <path>] [--json]
+mda release finalize --target llmix-registry --registry-dir <dir> --registry-root <file> --release-plan <file> --policy <path> (--expected-root-digest <digest>|--derive-root-digest) --out <file> [--did-document <path>] [--offline-sigstore-fixture <path>] [--json]
+mda release finalize --target llmix-registry --registry-dir <dir> --manifest <path> --snippet-format json|env|kubernetes|github-actions|terraform|typescript|python|rust --snippet-out <path> [--json]
+mda doctor release --target llmix-registry --source <dir> --registry-dir <dir> --release-plan <path> --manifest <path> [--did-document <path>] [--offline-sigstore-fixture <path>] [--json]
+```
 
 Run conformance:
 
@@ -349,21 +433,14 @@ Run conformance:
 mda conformance [--suite <path>] [--level V|C] [--json]
 ```
 
-Options:
-
-- `--suite <path>` points to a conformance suite directory.
-- `--level V|C` selects validation or compile conformance. Default: `V`.
-- `--json` prints pass and fail counts in JSON.
-
 ## Global Flags
 
-These flags work across commands:
-
 - `--json` prints stable JSON only on stdout.
 - `--quiet` suppresses non-essential human output.
 - `--verbose` includes extra diagnostic context where available.
 - `--no-color` disables ANSI color.
-- `-h`, `--help` prints full help.
+- `--no-next` hides human `Next:` guidance. JSON `nextActions` are unchanged.
+- `-h`, `--help` prints help.
 
 For agents, prefer `--json`. For humans, plain output is easier to read.
 
@@ -375,12 +452,41 @@ For agents, prefer `--json`. For humans, plain output is easier to read.
 - `3`: IO or configuration error, such as overwrite refusal or unreadable policy
 - `4`: internal bug
 
-Agents should use the exit code and JSON fields together. Humans can usually read the printed diagnostic and fix the command.
+Agents should use the exit code and JSON fields together. Humans can usually
+read the printed diagnostic and follow `Next:`.
 
-## Status
+## Conformance And Release Gates
+
+Use validation conformance:
 
-This is the MVP CLI.
+```sh
+mda conformance --level V --json
+```
+
+Use compile/equality conformance:
+
+```sh
+mda conformance --level C --json
+```
+
+For local development of this CLI package, the useful gates are:
+
+```sh
+pnpm -C apps/cli build
+pnpm -C apps/cli test
+node scripts/validate-conformance.mjs
+pnpm -C apps/cli smoke:package
+```
+
+The package smoke test installs the packed package in a temporary directory
+outside the repository and runs the real `mda` binary. That matters. A local
+source tree can hide problems a packed package cannot.
+
+## Status
 
-Validation, compilation, canonicalization, integrity checks, and level V conformance are the useful parts today.
+This is the 1.1 CLI.
 
-Full signing and cryptographic trust verification are not complete. The CLI says no when it cannot prove the answer. Quietly, but clearly.
+The covered path is source authoring, validation, compile, integrity, GitHub
+Actions Sigstore/Rekor signing evidence, did:web signing and verification,
+LLMix release planning, external trust manifests, deployment snippets, doctor
+checks, and Level V/Level C conformance.