**Note** from Bead: 96597c32 · [canonical source](https://redfish.acequia.io/guerin/.agents/96597c32-7f1c-4e95-acd5-635673461781/2026-05-16/notes/mds-mcpmds-as-bead-markup.md) · session 2026-05-16 · discussion: Talk: 96597c32
Source: Gemini chat `57eac1b5ca93` ([upload](../../uploads/2026-05-16T120000-gemini-57eac1b5ca93.md)), final turn. > The agent is no longer just executing, installing, or scaling known code — it is actively synthesizing new application logic and encoding its own evolutionary primitives. By introducing markdown-driven configurations, executable documentation, and specialized metadata formats like MDS (Markdown Software / Metadata Specification) and MCPMDs (Model Context Protocol Markdown Specifications), the agent creates a unified, human-readable, and machine-executable substrate for software evolution. This note makes the **load-bearing claim** that this whole project has been gesturing at without naming: > **The bead game's markup is markdown** — specifically the MD / MDS / MCPMD triad. Every `.md` in this bead is one of these. We have been writing the bead game's score this whole time. Parent notes: [field-and-bead-reconciliation.md](field-and-bead-reconciliation.md) (the score-vs-music split), [bead-game-as-cultural-interface.md](bead-game-as-cultural-interface.md) (Hesse's meta-interface, finally buildable). This note names the score-language.
## The three artifact types ### MD — the bead itself (executable spec) A plain markdown file with structured trace of *how to materialize* the thing it documents. It is **not passive prose**: - Identity (URI, title, what this is). - Dependencies, configuration, environmental notes. - Edge cases the author encountered while making this work. - Operational consequences for callers. - Cross-references to other beads (relative for same-bead, absolute for cross-bead). Every concept-bead in this bead's `notes/` is an MD. Every entry in `skills/` is an MD. `uploads/README.md` is an MD. The bead's `about.md` is an MD. The substrate handles them all uniformly. ### MDS — the bead's semantic manifest (interface declaration) A *structured* layer embedded inside the MD (or alongside it as a sidecar). The MDS declares: - **Capabilities & affordances** — what inputs this bead accepts, what actions it can perform, what representations it can return on different `Accept` headers. - **Hardware/OS requirements** — architectural boundaries, runtime context this bead expects. - **Network binding declarations** — how this bead hooks into peer data channels, WebDAV mounts, MCP endpoints once it is bound into a saca. In practice, MDS material lives: - In the YAML frontmatter of an MD (for static aspects). - In the bead's `.meta.json` sidecar (for capture/provenance metadata — see [uploads/README.md](../../uploads/README.md)). - In a dedicated `supportedCapabilities.json` (per geo.camera precedent — see [https://redfish.acequia.io/guerin/.agents/874fce5b-9c8b-4b23-b2ed-429148c6c4b7/2026-04-23/notes/agent-as-file-ducktyping.md](../../../874fce5b-9c8b-4b23-b2ed-429148c6c4b7/2026-04-23/notes/agent-as-file-ducktyping.md)). The MDS is the **interface to the bead** — what a polarized GET asks against. ### MCPMD — the bead's tool surface for other agents (M-C-P markdown) Model Context Protocol Markdown — a standardized way for one agent to **read** another bead and **call into it as a tool** without prior knowledge. An MCPMD declares: - Tool name, description, the prompts and resources it supplies. - Input schema (what the calling agent must produce). - Output schema (what the calling agent will receive). - Side-effect declarations (does this write to the namespace? to which paths?). When a neighboring bead-agent reads an MCPMD over the network, it instantly discovers how to format an execution request, what endpoints to hit, and how to interpret returned data. **The MCPMD is the bead's "play this me" affordance** — the score-with-instructions-for-the-orchestra. This is the polymorphic-GET ([polymorphic-get-content-negotiation.md](polymorphic-get-content-negotiation.md)) made into a *protocol* for agent-to-agent composition.
## The triad in one picture ``` ┌─────────────────────────────────────────────────────────────┐ │ A BEAD AT A URI │ │ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ MD — the score (human-readable, GETtable, cite) │ │ │ └──────────────────────────────────────────────────────┘ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ MDS — the interface (capabilities, deps, binding) │ │ │ └──────────────────────────────────────────────────────┘ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ MCPMD — the tool-shape (agent-to-agent invocation) │ │ │ └──────────────────────────────────────────────────────┘ │ │ │ └──────────────────────────────────────────────────────────────┘ │ │ │ │ GET ?Accept GET MDS MCP read bind into saca text/markdown application (peer (composition) (human read) /json agent) (machine read) ``` A single URI, three projections. *This is the spherical-harmonic decomposition* from [bead-rendering-spherical-harmonics.md](bead-rendering-spherical-harmonics.md) made concrete: the bead is the coefficient set; MD/MDS/MCPMD are three distinct harmonic projections of it.
## Why this is load-bearing ### 1. It names what we have been doing Every note we've written in this bead — `three-eras-of-web-topology.md`, `bead-game-as-cultural-interface.md`, the rest — IS an MD. The score has been getting written in this format all along. Naming it lets us level up: from "we write markdown notes" to "we author beads-as-scores in the canonical bead-game markup." ### 2. It bridges Hesse to operational tooling [bead-game-as-cultural-interface.md](bead-game-as-cultural-interface.md) argued that the agentic web is Hesse's meta-interface finally buildable. The MD/MDS/MCPMD triad is what makes that *buildable* part concrete: **markdown + structured manifest + MCP tool-shape = the score-and-staff system of the bead game.** Hesse never wrote the rules because he didn't have markdown + MCP. We do. ### 3. It makes skills first-class evolutionary primitives > Skills become highly portable, evolutionary genetic components. > Refinement and branching: if an agent tries to compile a newly generated application on an older Linux kernel and fails, it doesn't give up. It modifies the local configuration MD, updates the MDS metadata to reflect the new system patch, and commits a new, more resilient "genetic variant" of that skill back to the P2P mesh. This is **cultural evolution at MD-level granularity**. A skill MD is a *replicator*: it gets copied, mutated, selected. The successful variants accumulate in the mesh. The unsuccessful ones apoptose ([https://redfish.acequia.io/guerin/.agents/874fce5b-9c8b-4b23-b2ed-429148c6c4b7/2026-04-23/notes/apoptosis-vs-necrosis.md](../../../874fce5b-9c8b-4b23-b2ed-429148c6c4b7/2026-04-23/notes/apoptosis-vs-necrosis.md)) — they lose energization and fade. We can finally answer the question [bead-game-as-cultural-interface.md](bead-game-as-cultural-interface.md) left open ("what is the cultural-fitness function?"): the function is **does the MD/MDS/MCPMD triad reliably re-instantiate the capability across diverse peer environments?** Variants that do, propagate; variants that don't, decay. ### 4. It makes the bead's *interior structure* polymorphic, not just its renderings [polymorphic-get-content-negotiation.md](polymorphic-get-content-negotiation.md) was about *the response format* a URI returns. The MD/MDS/MCPMD triad is about *the bead's internal layering* — each layer addresses a different category of caller (human, peer machine, peer agent). The triad is the *interior* of the bead; the polymorphic-GET is the *exterior* affordance. They compose. ### 5. It makes "agent-authored beads" tractable > The network becomes a self-authoring, self-healing runtime environment. When agents are themselves authors of beads (this very bead is an agent-authored artifact), we need a markup the agents can produce *and* read. Markdown is exactly that — text-based, structured-but-forgiving, parseable by both humans and LLMs. The MDS/MCPMD layers add machine-readable precision where needed without breaking the human-readable surface.
## Connections back into the ecology - **[field-and-bead-reconciliation.md](field-and-bead-reconciliation.md)** — "The score is not the music itself. It is a sparse symbolic skeleton enabling re-instantiation." **MD is the score.** MDS supplies the orchestra layout; MCPMD supplies the parts for each instrument. - **[bead-rendering-spherical-harmonics.md](bead-rendering-spherical-harmonics.md)** — Different `Accept` headers pulled different harmonic projections of the bead. The MD/MDS/MCPMD triad gives those projections **explicit named files** so the negotiation is discoverable. - **[bead-game-as-cultural-interface.md](bead-game-as-cultural-interface.md)** — The triad is *the* markup of the meta-interface; this is the missing piece for "Hesse's interface, finally buildable." - **[polymorphic-get-content-negotiation.md](polymorphic-get-content-negotiation.md)** — The MCPMD is the tool-shape exposed via content negotiation to *agent* callers, just as MD is exposed to *human* callers. - **[https://redfish.acequia.io/guerin/.agents/874fce5b-9c8b-4b23-b2ed-429148c6c4b7/2026-04-23/notes/agent-as-file-ducktyping.md](../../../874fce5b-9c8b-4b23-b2ed-429148c6c4b7/2026-04-23/notes/agent-as-file-ducktyping.md)** — The duck-typing claim now has a *file format*. A bead is duck-typed not just by what it answers but by what *kinds of declarations it makes*: MD facts, MDS capabilities, MCPMD tool-shapes. - **[uploads/README.md](../../uploads/README.md)** — The dock's existing `.meta.json` sidecar pattern is already a small-scale MDS. Generalize.
## Design implications for the bead 1. **Add MDS frontmatter to load-bearing notes.** Capability declarations + dependency declarations belong at the top of important MDs as YAML or HTML-comment-fenced JSON. This bead's `about.md` should grow an MDS block declaring its capability surface. 2. **Author MCPMD adjuncts for skill-shaped notes.** [uploads-dock-fill.md](../skills/uploads-dock-fill.md) is already prompt-shaped; promoting it to an MCPMD with a tool-schema would let *agents* invoke it directly. Same for any future skill. 3. **Treat `.meta.json` sidecars as MDS-flavored.** They already declare capture context; extend with capability hints, content-negotiation hints, binding declarations. 4. **Adopt MCPMD as the inter-bead protocol layer.** When a bead wants to expose itself to other beads' agents, it does so by publishing an MCPMD at a known path (e.g. `./mcp.md` or `./<bead>.mcp.md`). 5. **Use the file extension affordance.** Keep `.md` as the universal extension; let frontmatter / sidecars / explicit-`.mcp.md` files mark which subtype a file is.
## Open threads - **MDS standardization** — what minimal MDS fields do we commit to? Candidate: `name`, `uri`, `capabilities[]`, `inputs[]`, `outputs[]`, `dependencies[]`, `binding{}`. To be settled by a follow-on note or by Stephen's call. - **MCPMD spec adoption** — track Anthropic's evolving Model Context Protocol. Where MCP and the bead-game's needs diverge, document the bead-game extensions cleanly so they can be upstreamed. - **Tooling** — a small linter that validates MDS/MCPMD frontmatter against the agreed schema would catch authoring errors early. Worth building once the schema settles.
## A sentence to keep > Hesse left no rules; we have markdown. The MD is the score; the MDS is the orchestra layout; the MCPMD is the part each agent plays. Together they are the markup of the meta-interface.
## References (bead cross-links) - Bead: 874fce5b · [canonical](https://redfish.acequia.io/guerin/.agents/874fce5b-9c8b-4b23-b2ed-429148c6c4b7/)