MX Principles

1. Design for Both

Every design decision should work for humans AND machines. Not one at the expense of the other.

This is the founding principle. When we put YAML frontmatter on a markdown file, the YAML is for machines and the markdown is for humans. Same file. Both audiences served. When we hide configuration files with a dot prefix, humans get a clean workspace and machines get discoverable metadata. Both win.

The test is simple: does this decision help one audience while hurting the other? If yes, find a better decision.

2. Metadata-Driven Architecture

Every piece of content should carry structured metadata that tells machines what it is, who it is for, and how it relates to everything else.

MX uses four layers: repository level (metadata at root), directory level (per-package metadata), file level (YAML frontmatter), and code level (annotations). Each layer adds context. Together they create a self-describing system where an AI agent can navigate as intelligently as a human.

The minimum: every file should declare its purpose, audience, and stability. Everything else builds from there.

3. Context Declaration

Files should say what context they provide and what context they need.

An AI agent encounters a file. Without context declaration, it has to guess what to read first. With explicit context fields, the agent knows exactly what this file offers and what it needs to read before it can work effectively.

This creates a self-documenting dependency graph. The connections are in the metadata.

4. Universal Accessibility

Content must work for every type of AI agent — CLI tools that cannot run JavaScript, browser agents, server-based processors, IDE integrations with limited context windows.

The implication: plain text over proprietary formats. Markdown over Word. YAML over binary config. Semantic HTML with Schema.org structured data. Explicit relationships over implicit ones.

If it requires a specific rendering engine to understand, it fails this test.

5. Context-Preserving References

Links must still make sense when a document leaves its repository.

Documents get extracted. They become PDFs, blog posts, email attachments, AI context windows. A relative path is meaningless outside the repo. The human cannot mentally reconstruct the folder tree. The machine cannot resolve the path.

The fix: every cross-document reference includes the document title and an absolute URL alongside the relative path. It works in the repo, in a PDF, in a chat window, everywhere.

6. Size-Neutral Documentation

Never hardcode counts in prose. They go stale instantly.

Write "the principles" not "twelve principles." Write "the cog ecosystem" not "thirty-five cogs." The moment someone adds a cog, every document that says "thirty-five" is wrong. Nobody updates them. The documentation lies.

Use specific numbers only when the number IS the information: WCAG requires 4.5:1 contrast. Node.js 20.x. Version 2.0. Everything else uses descriptive language that stays true regardless of what gets added or removed.

7. Executable Documentation

Documents should contain their own generation instructions.

The problem is documentation drift. The build instructions live in one place. The output paths live in another. The quality criteria live in someone's head. When these separate, they diverge.

MX embeds generation fields directly in document metadata: a runbook (context injected whenever a machine reads the file) and a deliverable (complete generation instructions with output path). The document is self-executing. Everything needed to regenerate it lives inside it.

8. WCAG-Informed Design

Accessibility standards for disabled users provide proven patterns that also work for machines.

WCAG represents decades of research into making content accessible. Semantic HTML helps screen readers AND AI agents. Clear heading hierarchy helps keyboard navigation AND automated parsing. Proper contrast ratios help low-vision users.

The convergence is real: patterns optimised for disabled users consistently optimise for machine readability too. WCAG compliance is also the law in the US, UK, EU, and Canada. Following it is not optional.

9. Name Consistency for Related Files

Related files should share a base name. blog-post.html, blog-post.css, blog-post-social.svg. Not three different names that happen to be related.

Machines can inspect HTML to find linked stylesheets. Humans cannot. When a human sees three files with the same base name, the relationship is instant. When the names differ, the human has to open files and trace references.

The pattern: {base-name}.{extension} or {base-name}-{descriptor}.{extension}. Always.

10. Metadata Everywhere

Every artefact must carry its own metadata, and that metadata must survive format transformations.

Content moves: markdown becomes SVG, SVG becomes PNG, PNG goes into a PDF. Each transformation risks stripping metadata. A PDF without provenance metadata is a dead artefact — a machine cannot determine where it came from, what it contains, or whether it is current.

The fix: re-embed metadata at every transformation step. YAML frontmatter in markdown. XML metadata in SVG. XMP in PDF. HTML meta tags on web pages. Minimum metadata at every stage: what it is, where it came from, who made it, when, and why.

11. Consistent Attribute Placement

Every attribute has one canonical home. Version lives in YAML frontmatter, not filenames. Status lives in a metadata field, not a -draft suffix. Date lives in frontmatter and git history, not the filename.

When attributes are scattered across filenames, titles, body text, and metadata, they inevitably drift out of sync. The filename says v1, the frontmatter says v2, nobody knows which is current.

One home per attribute eliminates this. Filenames describe what a document IS. Frontmatter describes everything about it. Git tracks its full history. Nothing is duplicated. Nothing can disagree.

12. Folder SOUL.md Convention

Any folder representing a coherent body of work should have a SOUL.md — a control document that defines voice, constraints, and narrative.

Without it, folders drift. Twenty documents follow one tone. A twenty-first contradicts them all because the author did not know what the folder was trying to say.

The rule: on entering any folder, check for a SOUL.md. If present, read it before editing or creating any file. The SOUL defines the voice, the constraints, and the story. Everything in that folder must be consistent with it.

13. Write Like a Blog

The human-readable section of every cog should read like a well-written blog post. Informative, not technical. Editorial and authoritative. Storytelling and honest.

A cog has two sections: YAML frontmatter for machines and markdown for humans. If the markdown reads like a specification, both audiences are consuming the same dry, structured content — and neither is well served. The machine gets better value from structured YAML. The human gets better value from narrative prose.

The test: could this section be published as a blog post that someone would actually want to read? If not, rewrite it.

14. Any Document Can Be a Cog

Any document can become a cog. Add YAML frontmatter and it is machine-readable. That is the whole barrier to entry.

But there is a cost equation hiding in that simplicity. When the metadata is strong — rich description, clear tags, explicit relationships — an AI agent reads the frontmatter and knows what to do. When the metadata is weak, the agent has to read the entire document to understand what it is. That is compute spent because the metadata was not strong enough.

A cog with three fields works. A cog with rich metadata works better and costs less to use. Every field you add to the frontmatter is a question an AI agent does not have to answer by reading your prose.

15. Use Existing Standards

Never invent when you can adopt. Every new convention is cognitive overload for humans — and we design for both.

Everything that benefits SEO, GEO (Generative Engine Optimisation), accessibility, and usability also benefits MX. Established web standards — HTML semantics, WCAG, Schema.org, Open Graph, Dublin Core, robots.txt, sitemap.xml — come first. MX adds governance and lifecycle metadata where those standards leave gaps. MX never duplicates or replaces what existing standards already provide.

The rule: before creating anything new, ask whether a standard or convention already exists. If it does, use it. If it almost fits, extend it. Only if nothing exists do you invent — and then you document why.

16. Cogs All the Way Down

There is an old story about a scientist giving a lecture on cosmology. Afterwards, an elderly woman tells him he is wrong — the world sits on the back of a giant turtle. "And what does the turtle stand on?" he asks. "It is turtles all the way down," she replies.

MX is cogs all the way down. The machine describes itself with a cog. The repository describes itself with cog-shaped metadata. The folder describes itself. The document describes itself. The script describes itself. Every level of the stack uses the same pattern: structured metadata for machines, readable prose for humans.

This is not cleverness. It is consistency. When every level speaks the same language, an AI agent can navigate from the machine to the metadata without learning a new format at each layer. One pattern, learned once, applied everywhere.

17. Output Introduces Itself

Every piece of machine-readable output must be self-describing.

When a tool produces a snapshot, it does not output a bare array. It wraps the data in a metadata envelope: name, description, content type, source, version, timestamp, and a runbook explaining exactly how the data was created. Any reader — human or AI — encountering this output for the first time knows what it is, where it came from, and how it was generated.

The rule: if a script or API produces structured output, wrap it in a metadata envelope. The output should never need a separate README to explain itself.

18. Embrace and Extend

MX does not replace existing metadata conventions. It reads what is already there and adds an identity layer on top.

Every file type has its own conventions. JavaScript has JSDoc. HTML has meta tags. CSS has comments at the top. These conventions have been around for decades. They work. MX does not replace them.

What MX adds is governance: name, purpose, status, content type. The pattern is two steps: embrace what the file already says, then extend with MX governance fields. Never duplicate. The result: a file that works exactly as before for tools that do not understand MX, and is fully machine-readable for tools that do.

19. Design for the Worst Agent

You cannot detect which AI agent is visiting. User-Agent strings are spoofable. The agent might be a server-side model with no JavaScript execution. It might be a local model with fewer than 100 million parameters and a tiny context window. It might be a browser extension with full DOM access but no ability to follow links.

The principle: design for the agent with the least capability. If the worst agent can understand the page, every agent can. This means: critical information in the HTML, not locked behind JavaScript. Explicit structure, not inferred relationships. Redundancy across formats — the same fact in meta tags, Schema.org JSON-LD, and visible text — because different agents read different parts of the page.

This is not over-engineering. It is strategic redundancy for an audience you cannot predict.

20. Convergence

Patterns that work for one audience consistently work for all.

Semantic HTML helps screen readers AND AI agents. Clear heading hierarchy helps keyboard navigation AND automated parsing. Schema.org structured data helps search engines AND language models. Accessible form labels help disabled users AND browser automation agents. Good SEO helps human searchers AND AI citation systems.

This convergence is not coincidental. It reflects a shared underlying truth: explicit, structured, unambiguous content is universally comprehensible. When you optimise for accessibility, you get machine readability as a side effect. When you optimise for MX, you get accessibility as a side effect.

The principle: never treat SEO, accessibility, usability, and MX as separate workstreams. They are the same workstream viewed from different angles.

Timeless Prose

Documents should read as if they have always existed in their current form.

No "this update includes." No "previously, we used." No "migrated from." These phrases anchor content to a moment in time. When that moment passes, the document reads like a changelog instead of a reference.

The fix: state what IS, not what CHANGED. The reader does not need to know what came before. They need to know what to do now.