@@ -1,14 +1,18 @@
 # 📝 MDA Open Spec — Markdown for Agent
 
-> A Markdown superset that compiles one authored source into portable, verifiable artifacts every major agent runtime can load — replacing cross-vendor copy-paste with one source of truth, a real dependency graph, and reproducible artifact identity.
+> A Markdown superset for agent-facing documents. One source, compiled into the `.md` files every major agent runtime already loads. Add a real dependency graph and reproducible signed identity if you need them.
 
 [![CI](https://img.shields.io/github/actions/workflow/status/sno-ai/mda/sync-mdx.yml?branch=main)](https://github.com/sno-ai/mda/actions/workflows/sync-mdx.yml)
 [![License](https://img.shields.io/github/license/sno-ai/mda)](https://github.com/sno-ai/mda/blob/main/LICENSE)
 [![Spec](https://img.shields.io/badge/spec-v1.0--rc.1-blue)](SPEC.md)
 
 ## What MDA is
 
-AI Agent or you author one rich `.mda` source. The MDA compiler emits one or more `.md` outputs, each drop-in compatible with whichever third-party agent standard the filename names:
+Until now, you shipped the same skill four times. Once as `SKILL.md` for the agentskills.io runtimes. Once as `AGENTS.md` for the AAIF ecosystem. Once as `MCP-SERVER.md` with a sidecar JSON. Once as `CLAUDE.md`. Same content, four frontmatter shapes. Update one, forget the others, and a month in, the four files have quietly drifted into four slightly different instruction files.
+
+You write one `.mda`. The compiler emits the rest.
+
+![One .mda source compiled through a deterministic pipeline into SKILL.md, AGENTS.md, MCP-SERVER.md, and CLAUDE.md](images/hero-compile-pipeline.png)
 
 ```
                 ┌─────────────────────────┐
@@ -25,27 +29,44 @@ AI Agent or you author one rich `.mda` source. The MDA compiler emits one or mor
                        drop-in compatible
 ```
 
-`.mda` adds three things on top of standard Markdown:
+![Three MDA additions on top of standard Markdown: rich frontmatter, typed footnote relationships, signed identity](images/three-additions.png)
+
+`.mda` adds three things on top of standard Markdown. All of them optional.
+
+1. **Rich YAML frontmatter.** Beyond the open-standard `name` and `description` baseline, MDA carries `doc-id`, `version`, `requires`, `depends-on`, `relationships`, and `tags`. Agent-aware tools use these for routing, dependency resolution, and graph traversal. See [`spec/v1.0/02-frontmatter.md`](spec/v1.0/02-frontmatter.md) and [`spec/v1.0/10-capabilities.md`](spec/v1.0/10-capabilities.md).
+2. **Typed footnote relationships.** Standard Markdown footnotes whose payload is a JSON object: `parent`, `child`, `related`, `cites`, `supports`, `contradicts`, `extends`. Mirrored to `metadata.mda.relationships` in body order on compile. See [`spec/v1.0/03-relationships.md`](spec/v1.0/03-relationships.md).
+3. **Optional cryptographic identity.** A JCS-canonicalized `integrity` digest plus DSSE-enveloped, Sigstore-anchored `signatures[]`. The compiled `.md` carries reproducible tamper detection without bolting it on later. See [`spec/v1.0/08-integrity.md`](spec/v1.0/08-integrity.md) and [`spec/v1.0/09-signatures.md`](spec/v1.0/09-signatures.md).
+
+A `.mda` source with only the open-standard frontmatter compiles unchanged into a `.md`. Use as much or as little of MDA as your project needs.
+
+## Why this exists
 
-1. **Rich YAML frontmatter** — beyond the open-standard `name` / `description` floor, MDA carries `doc-id`, `version`, `requires`, `depends-on`, `relationships`, `tags`, and other fields that agent-aware tools use for routing, dependency resolution, and knowledge-graph construction.
-2. **Typed footnote relationships** — standard Markdown footnotes whose payload is a JSON relationship object (`parent`, `child`, `related`, `cites`, `supports`, `contradicts`, `extends`). Mirrored to `metadata.mda.relationships` on compile.
-3. **Optional cryptographic identity** — JCS-canonicalized `integrity` digest plus DSSE / Sigstore-anchored `signatures[]`, so a `.md` artifact carries reproducible tamper detection. Source-mode anchoring is also supported as authorial evidence.
+The honest version. I kept shipping the same skill four times. Same content, four wrappers. Each runtime had its own opinions about what frontmatter belonged at the top and what counted as vendor-specific. The third or fourth time I copy-pasted a paragraph between `SKILL.md` and `AGENTS.md` and then watched them drift, I started writing this.
 
-All three are optional. A `.mda` source with only the open-standard frontmatter compiles to a byte-identical `.md`.
+The thing is, the duplication isn't the worst part. The worst part is what you can't say in any of those formats. You can't say "this skill depends on that one, version `^1.2.0`, with this content digest." You can't say "this file was signed by this identity at this Rekor index." You can't say "the relationship between this document and that one is `supports`, not `cites`." There's nowhere to put that information, so it sits in prose, where neither agents nor humans can act on it reliably.
+
+MDA puts those things in the frontmatter and footnotes, in shapes a JSON Schema can validate. The Markdown body still renders. The standard fields still load. Everything new is optional. That's the whole pitch.
+
+For the long version, two documents go deeper. Both trace every claim back to a section of the spec, and both call out current ecosystem gaps inline. Read them if you're deciding whether to adopt.
+
+- [**`ai-doc/ai-agent-core-value.md`**](ai-doc/ai-agent-core-value.md) — five points framed for runtimes, harnesses, validators, and dispatchers. What MDA gives an agent at load time: structured `requires` for typed dispatch, verifiable trust at load, machine-readable graph edges, filename-based one-lookup target dispatch, and the same validation contract for agent-authored and compiler-emitted output.
+- [**`ai-doc/human-curator-user-core-value.md`**](ai-doc/human-curator-user-core-value.md) — six points framed for the people who write and curate agent-facing instruction libraries. What MDA gives an author at ship time: one source into multiple ecosystems, tamper-evidence and publisher attribution, machine-readable dependency graph and version pinning, LLM-mediated authoring without learning every runtime's frontmatter, smaller (not zero) vendor lock-in, and strict validation that catches almost-conformant artifacts before they ship.
 
 ## Three authoring modes
 
-MDA documents MAY be produced in any of three equivalent ways:
+MDA artifacts may be produced three ways. They're equivalent under validation.
 
-1. **Agent mode** — an AI agent writes the `.md` directly (the primary 2026 use case).
-2. **Human mode** — a human writes the `.md` directly with standard tooling (`sha256sum`, `cosign`).
+1. **Agent mode** — an AI agent writes the `.md` directly. The primary near-term use case.
+2. **Human mode** — a human writes the `.md` directly, with `sha256sum` and `cosign`.
 3. **Compiled mode** — an author writes a `.mda` source; the MDA compiler emits one or more `.md` outputs.
 
-See [`docs/manual-workflow.md`](docs/manual-workflow.md) for the hand- and agent-authoring paths without the reference CLI.
+Whichever path you take, the artifact is judged against the same JSON Schema 2020-12 target schema and the same conformance suite. There's no second code path for "this came from an agent."
+
+See [`docs/manual-workflow.md`](docs/manual-workflow.md) for the manual and agent-authored paths without the reference CLI, and [`spec/v1.0/00-overview.md §0.5–§0.6`](spec/v1.0/00-overview.md) for the normative statement of priority and modes.
 
 ## Minimal example
 
-`intro.mda`:
+`pdf-tools.mda`:
 
 ```yaml
 ---
@@ -64,11 +85,11 @@ metadata:
 …
 ```
 
-Compiles to `pdf-tools/SKILL.md` byte-equivalent to the input — the source above is already in the strict target shape (every MDA-extended field already nested under `metadata.mda.*`). Worked examples in [`examples/`](examples/).
+Compiles to `pdf-tools/SKILL.md`. The source already sits in the strict target shape, with every MDA-extended field nested under `metadata.mda.*`, so the compile is essentially a rename. More worked examples live in [`examples/`](examples/) and [`docs/mda-examples/`](docs/mda-examples/).
 
 ## Compatibility
 
-A compiled `SKILL.md` is loadable by every agentskills.io v1 consumer:
+A compiled `SKILL.md` is loadable by the major agentskills.io v1 consumers:
 
 - **Claude Code** — https://code.claude.com/docs/en/skills
 - **OpenCode** — https://opencode.ai/docs/skills/
@@ -78,13 +99,13 @@ A compiled `SKILL.md` is loadable by every agentskills.io v1 consumer:
 - **skills.sh / Skills Directory** — https://www.skillsdirectory.com/
 - **Cursor**, **Windsurf**, and other 2026 SKILL.md consumers
 
-Per-vendor extensions live under reserved `metadata.<vendor>.*` namespaces — see [`REGISTRY.md`](REGISTRY.md).
+A compiled `AGENTS.md` lands in the AAIF-aligned ecosystem (the Linux Foundation's Agentic AI Foundation): Codex CLI, GitHub Copilot, Cursor, Windsurf, Amp, Devin, Gemini CLI, VS Code, Jules, Factory.
 
-## The Open Spec
+Per-vendor extensions live under reserved `metadata.<vendor>.*` namespaces. Loaders read only their own namespace, and consumers must not reject a document solely because it carries an unregistered one. See [`REGISTRY.md`](REGISTRY.md) for the namespace registry, standard `requires` keys, reserved Sigstore OIDC issuers, and reserved DSSE `payload-type` values.
 
-The normative MDA Open Spec lives at [**SPEC.md**](SPEC.md) → [`spec/v1.0/`](spec/v1.0/)
+## The Open Spec
 
-Quick links:
+The normative MDA Open Spec lives at [**SPEC.md**](SPEC.md) → [`spec/v1.0/`](spec/v1.0/).
 
 - [§00 Overview](spec/v1.0/00-overview.md) — terms, RFC 2119, P0 > P1 > P2 priority, three authoring modes, governance, versioning
 - [§01 Source and output](spec/v1.0/01-source-and-output.md)
@@ -97,18 +118,38 @@ Quick links:
 - [§08 Integrity](spec/v1.0/08-integrity.md)
 - [§09 Signatures](spec/v1.0/09-signatures.md) — Sigstore OIDC default, did:web fallback
 - [§10 Capabilities](spec/v1.0/10-capabilities.md) — `metadata.mda.requires`
+- [§11 Implementer's Guide](spec/v1.0/11-implementer-guide.md) (informative)
+- [§12 Sigstore tooling integration](spec/v1.0/12-sigstore-tooling.md) (informative)
 
-JSON Schemas: [`schemas/`](schemas/). Conformance suite: [`conformance/`](conformance/) (`node scripts/validate-conformance.mjs`).
+JSON Schemas live in [`schemas/`](schemas/) — `frontmatter-source`, `frontmatter-skill-md`, `frontmatter-agents-md`, `frontmatter-mcp-server-md`, `relationship-footnote`, plus shared `_defs/` for `integrity`, `signature`, `requires`, `depends-on`, and `version-range`. Conformance fixtures and the validation runner live in [`conformance/`](conformance/) (`node scripts/validate-conformance.mjs`).
 
 ## Reference implementation
 
-The TypeScript reference CLI lives at [`packages/mda/`](packages/mda/) (npm: `@mda/cli`). Architecture spec: [`packages/mda/IMPL-SPEC.md`](packages/mda/IMPL-SPEC.md). The CLI matures across `v1.0.0-rc.N` tags; the `1.0.0` final lands when it passes 100% of the conformance suite.
+The TypeScript CLI lives in [`packages/mda/`](packages/mda/) (npm package: `@mda/cli`). The architecture spec is [`packages/mda/IMPL-SPEC.md`](packages/mda/IMPL-SPEC.md). The CLI matures across `v1.0.0-rc.N` tags. The final `1.0.0` lands when the CLI passes 100% of the conformance suite.
 
-## Contributing
+![v1.0 ships the contract — schemas, conformance, and compiler — with verifier, resolver, registry, graph indexer, and runtime routing as future ecosystem work](images/status-contract-and-ecosystem.png)
+
+## Status, honestly
+
+v1.0 ships the **contract**, not the entire ecosystem around it.
+
+**What works today:** you can author a `.mda`, compile it to one or more conforming `.md` outputs, and validate them against the target JSON Schemas and the 35-fixture conformance suite.
 
-We welcome contributions. Major changes — especially to the Open Spec or the vendor registry — should be discussed in an issue first. See [`CONTRIBUTING.md`](CONTRIBUTING.md).
+**What's still being built:**
+
+- A bundled verifier for signatures isn't shipped yet. Operators currently glue `cosign` and a JCS library together themselves.
+- A working dependency resolver and a central artifact registry don't exist yet.
+- A graph indexer that consumes `metadata.mda.relationships` isn't shipped.
+- No 2026 multi-agent harness is known to route through `metadata.mda.requires` today.
+- v1.0 covers the agentskills.io and AAIF subset. It does not target Cursor MDC, Windsurf rules, Continue, Aider, or `*.instructions.md`. Those still need parallel maintenance.
+
+The `.mda` you write today still produces conforming `.md` outputs that load in every runtime listed above. The verification, resolution, and graph-traversal pieces are work in progress. The contract that lets them be built without further negotiation is what v1.0 freezes.
+
+For the full gap between the spec and the consumer-side ecosystem, see [`ai-doc/what-v1.0-does-not-ship.md`](ai-doc/what-v1.0-does-not-ship.md). That distinction, between an honest spec freeze and a marketing freeze, is the one this project tries to keep.
+
+## Contributing
 
-For vendor namespace assignment, see [`REGISTRY.md`](REGISTRY.md).
+Contributions welcome. Major changes to the Open Spec or the vendor registry should start as a discussion before code. See [`CONTRIBUTING.md`](CONTRIBUTING.md), [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md), and [`SECURITY.md`](SECURITY.md). For vendor namespace assignment, see [`REGISTRY.md`](REGISTRY.md). Recent changes are logged in [`CHANGELOG.md`](CHANGELOG.md).
 
 ## License