HMD — Human Markdown for Hyper Documents

HMD (.hmd) is a proposed Markdown superset for AI-era human/agent collaboration: readable as text, stable in Git diffs, semantically structured for AI agents, and renderable into beautiful interactive HTML.

Current documents

• SPEC.md — v0.1 core specification: file structure, frontmatter, semantic blocks, profile loading, diagnostics, security, and HMD↔HTML roundtrip modes.
• IR.md — v0.1 intermediate representation contract for parser, validator, renderer, importer, formatter, LSP, WASM, and patch engine.
• HMD_BLUEPRINT.md — v0.1 product/spec blueprint: syntax, profiles, roundtrip model, CLI, AI workflow, and roadmap.
• HMD_TECH_STACK.md — v0.1 technical stack decision: Rust-first core, native CLI/LSP, WASM, Tree-sitter, and distribution plan.
• RELEASE.md — Rust package architecture, crates.io alpha publishing, GitHub Actions release flow, tags, and release verification.
• CONTRIBUTING.md — contribution workflow, local checks, PR expectations, and spec-first rules.
• SECURITY.md — supported versions, vulnerability reporting, response targets, and security scope.
• CHANGELOG.md — user-facing release history.
• COMPATIBILITY.md — compatibility surfaces for syntax, IR, profiles, CLI, Rust APIs, WASM, and MSRV.
• GOVERNANCE.md — maintainer model, decision process, and RFC requirements.
• SUPPORT.md — support channels and current alpha support scope.
• ROADMAP.md — public product and infrastructure roadmap.
• CODE_OF_CONDUCT.md — community behavior and enforcement expectations.
• docs/development.md — local development, verification commands, fixture workflow, and contribution hygiene.
• docs/parser.md — Rust parser architecture, source span strategy, diagnostics, and parser/profile validation boundary.
• docs/profiles.md — official profile descriptors, metadata validation, reference rules, schema export, and extension boundaries.
• docs/roundtrip.md — view, semantic, and exact HTML roundtrip modes, importer behavior, assets, and security boundaries.
• docs/interactive-patch.md — semantic HTML action metadata, PatchIntent, CLI/WASM/local/editor host flow, and safety gates.
• docs/CONFORMANCE.md — conformance sources, fixture policy, and future suite shape.
• docs/PROFILE_REGISTRY.md — official profile and third-party profile policy.
• docs/SUPPLY_CHAIN.md — dependency, artifact, checksum, and future provenance policy.
• docs/REPOSITORY_SETTINGS.md — recommended GitHub branch protection, security settings, labels, and merge policy.
• rfcs/README.md — RFC process for format, compatibility, security, release, and governance changes.
• research/agent-workflows.md — research brief for HMD in human-AI collaboration workflows.

v0 profile scope

HMD v0 is planned to ship these official profiles together:

• general@0.1
• decision@0.1
• progress@0.1
• todo@0.1

Examples

• examples/general.hmd
• examples/decision.hmd
• examples/progress.hmd
• examples/todo.hmd

Implementation fixtures

• fixtures/conformance.toml — machine-readable manifest of portable fixture expectations.
• fixtures/valid/ — valid parser inputs for the first implementation sprint.
• fixtures/invalid/ — invalid inputs that should produce diagnostics.
• fixtures/ir/ — hand-authored expected IR snapshots for early hmd ast tests.
• fixtures/intents/ and fixtures/patches/ — portable interaction-to-patch fixtures.

Core direction

HMD is designed as Rust-first, native-core, WASM-capable infrastructure. TypeScript is reserved for thin editor/web/npm glue layers, not the parser or renderer core.

Distribution

The current alpha release is available through crates.io, native GitHub Release artifacts, and npm:

cargo install hmd-cli --version 0.1.0-alpha.8
hmd --help
npm exec --yes --package @humanmd/cli@alpha -- hmd --help
npm install @humanmd/wasm@alpha

Native release artifacts are configured with cargo-dist for macOS, Linux, and Windows. The npm wrapper in packages/npm-cli downloads those native binaries during install and exposes the hmd command for npm and npx users without reimplementing parser logic in JavaScript. npm packages use the same alpha version as the Rust workspace and should be installed from the alpha dist-tag during prerelease testing.

Interactive patch example

cargo run -p hmd-cli -- render examples/decision.hmd --interactive -o examples/decision.interactive.html
cargo run -p hmd-cli -- action fixtures/valid/decision-basic.hmd fixtures/intents/decision-select-rust.json --print-patch
cat fixtures/patches/decision-select-rust.json | cargo run -p hmd-cli -- patch fixtures/valid/decision-basic.hmd - -o /tmp/decision-patched.hmd
cargo run -p hmd-cli -- validate /tmp/decision-patched.hmd

Semantic HTML carries data-hmd-actions and data-hmd-target; write-capable hosts still apply changes through Rust patch logic with stale-hash and validation checks.