Where markdown has syntax, the dialect uses it: headings, paragraphs, lists, block quotes, fenced code, math, images, links, tables, bold, italic, strikethrough and inline code all look like ordinary markdown and render fine on GitHub.

Every block ends with an HTML comment carrying its identity, <!-- id:X -->. Identity is what makes an edit an update of an existing block instead of a replacement. Two optional keys ride in the same comment when markdown has no syntax for something: type: names a block type such as Video, File, Button, Embed or Query, and attrs: holds a JSON object of attributes such as an image width or a query definition. A block with nothing special looks like plain markdown plus its id.

Nesting is indentation. A block's children sit two spaces deeper, or at the content column of a list marker. A heading's children follow it at the same indentation, and <!-- end:X --> closes a heading when a non-heading sibling follows. Frontmatter carries every metadata key of the document, including keys the client does not know about.

Text is escaped so that markdown syntax characters survive. Newlines inside a block are written as
. Style annotations that markdown lacks, such as underline, highlight and colors, are written as inline HTML tags.

A hand-written file needs none of the comments. A new file with no ids is matched to an existing document by position, so editing a paragraph in place updates that paragraph and does not replace the page. The ids appear the next time the document is exported. Links between files of the directory are relative file links ([Keys](./keys.md)), which render on GitHub and become hm:// links to the corresponding documents when published. The dialect is implemented once, in the SDK.

space export writes every document of a space into a directory: the home document as index.md and a document at /a/b as a/b.md. It only touches files whose content changed. Links between documents of the space become relative file links, so they work on GitHub too.

space import publishes a directory into a space. For each file it fetches the current document, diffs the blocks by id, and publishes a change on the document's existing history. Unchanged documents produce no change at all, so running it repeatedly never spams versions. A hand-written file with no ids is matched to the existing document by position, so editing a paragraph in place updates that paragraph and does not replace the page. Relative links to other files in the directory become links to the corresponding documents.

--check, and the --no-watch and --keep-stale flags of space dev below, are newer than the npm release of mid-September 2026 (0.2.9). See Seed CLI.

self means the signing key's own space. The signing key comes from the vault or keyring, or from the environment, which is how CI signs: SEED_CLI_KEYFILE holds the contents of an unencrypted .hmkey.json exported from the app, or SEED_CLI_MNEMONIC holds a BIP-39 phrase.

A file renamed in git (git mv) keeps its block ids, so the import publishes a move: a version Ref at the new path and a redirect at the old one. Nothing is imported while a relative link in the directory would break. A document that carries a schema definition travels with it. On export the schema blob is written beside the page as a/b.schema.json, and schemaDefinition is left out of the page's frontmatter. On import the file is encoded back to DAG-CBOR, published, and bound as the document's schemaDefinition. The schema file is the only source for it, so don't write schemaDefinition in frontmatter. Two limits apply as of September 2026. The signing key must own the space, and importing with a delegated key is refused. Removing a file does not by itself unpublish the document (see the retire step below).

space dev turns the desktop dev app into the editor for a directory. It creates a throwaway key under .dev/ in the directory, registers it in the app's own daemon, publishes the directory there, and then watches the daemon. Every document you publish in the app is written straight back as a file, so git diff shows the edit within seconds. Only the dev app is watched. The production Seed app registers the same hm:// scheme, so do not open the site from a link. The loop warns that an edit made there never reaches the directory.

While the loop runs, the app is the writer and git is where you commit.

The loop talks to the dev app's API on http://localhost:58004 and to its daemon on http://localhost:58001 (both configurable with --api and --daemon), polls every two seconds, and also pushes files you change on disk while it runs (--no-watch to stop that, --no-push to skip the initial publish). The key lives in <dir>/.dev/dev-key.mnemonic, ignored by git, and is registered in the daemon under the name hm-sync-<dirname>-<account tail>. The accounts the directory has used are recorded in <dir>/.dev/accounts.json so that a regenerated key's stale dev site can be retired next time (--keep-stale leaves it). The dev daemon is a peer like any other, so the dev site propagates to whatever network it is on. Use a development build of the app.

The folder hypermedia/ in the Seed repository is this site. A small script in the CLI package, sync-hypermedia.ts, wraps space import, space export and space dev with the folder's layout: index.md is the home document, README.md stays on GitHub, every other <x>.md publishes at /<x>, and a *.schema.json beside a page is the schema that page defines. Before anything is published the script encodes every schema file and checks its CID against schemas.lock.json, then publishes the schema blobs first.

From frontend/apps/cli the same commands are bun run src/sync-hypermedia.ts push [--dry-run] [--server <url>] [--key <name>] [--keep-stale], pull [--server <url>] [--space <uid>] and dev [--api <url>] [--daemon <url>] [--interval <ms>] [--no-push] [--no-watch] [--keep-stale].

Naming. The folder never names the space it publishes to. Pages link to each other with relative links. Absolute references to the docs space, such as schema bindings in frontmatter and links in examples, use hm://hyper.media/…. The layout sets selfAuthority to hyper.media: push swaps it for the signing key's account in page links and in every hm:// string in frontmatter, and pull swaps the key back. So in git an attributesSchema says hm://hyper.media/example/person, and on the published site it says hm://<key>/example/person. Schema blobs keep hm://hyper.media unchanged, so their CIDs match the lockfile. hyper.media is a name the SDK and the sync understand. The network does not resolve domains in hm:// URLs yet, and support is planned. The space is the signing key's own: main by default, --key <name> to choose, or the key in the environment in CI. A dry run without a key needs --space <uid>. pull takes --space <uid>, or else uses the space of the main key.

Retiring pages. The folder is the truth about what the site publishes, so push also retires every document of the site whose file is gone. The document is tombstoned. The dry run lists these as retire. Redirects left by moves are kept, and the home document is never retired. --keep-stale skips the step. Rename a page with git mv and the push publishes a move.

Pull. pull exports every document of the site back into the folder, schema files included, and regenerates the lockfile and the bundled schema registry when a schema changed. When the dev loop starts it also compares the folder with the main key's site on hyper.media and warns when that site is behind.

CI. A push to main that touches hypermedia/ runs the consistency checks and then the publish, signing with a repository secret that holds the contents of an exported .hmkey.json in SEED_CLI_KEYFILE. The site is that key's own space, and no key is written in the repository.

In the Seed app

CLI

SDK

Web API

Agents