#miao 庙 — the temple of versions

A version control system written in the Ling language, with its lexicon drawn from ling 灵 — the numinous — in Chinese religion. Where git has repos, branches, commits and tags, miao has temples, souls, rites and talismans; where git clones, pulls and pushes, miao practices spirit division (分灵), pilgrimage (进香) and tribute (回香) — the actual vocabulary of how temple networks spread efficacy in the real world. It does diffs, branches, three-way merges, content-addressed storage, and secure repo sharing over real SSH. Everything is ROYGBIV.

One codebase gives you:

• a CLI (miao.bat / miao.sh) with truecolor rainbow output,
• a GUI — LingMiao, in the LingStationX / LingDev design system,
• a LingOS edition — the traveling shrine built into lsh, plus a zsh-style ROYGBIV prompt that shows your soul and altar the way zsh shows a git branch.

The tutorial poster above is drawn by miao's own design system — regenerate it any time with ling run --interp tools/infographic.ling.

#The cosmology

A repository is a temple (.miao/). Every version of every file is a spirit, named by the BLAKE3 hash of its content. Staging is an altar; committing seals a rite; branches are the temple's souls (HEAD is the living soul); tags are talismans. Untracked files are wandering spirits, modified files are restless, merge conflicts are discord.

Every command answers to three names — english · pinyin · git:

miao help prints this in color. --plain or MIAO_PLAIN=1 silences the rainbow.

#Quickstart

cd my-project
miao consecrate
miao offer .
miao rite -m "genesis"
miao soul feature && miao summon feature     # branch & switch
...edit...
miao yinyang                                 # colored diff
miao offer . && miao rite -m "the work"
miao summon main && miao harmonize feature   # merge (conflicts become discord)

#Adaptive versioning — the diviner

miao does not store every version the same way. At offer time a diviner inspects each file — size, text-or-binary (by UTF-8 validity, not extension), its previous incarnation, the delta chain depth — and chooses an enshrinement per spirit:

Identity is separate from representation: a spirit's name is always the BLAKE3 of its full content (so divine is one fast hash per file), while how it is stored lives in a small manifest. Measured on this machine: a 2-byte edit to a 1.2 MB binary re-stored 88 KiB, not 1.2 MB; a 1-line edit to a 200-line file stored a ~60-byte delta. Bytes are exact on the way back out — binary round-trips are hash-verified in tests.

#Sharing: the temple fair (real SSH)

miao fair                 # read-only; prints a link like
                          #   miao+ssh://pilgrim:SECRET@yourhost:7447/temple
miao fair --tribute       # also prints a second link whose holders may push

miao fair runs a real SSH server (russh, built into the Ling runtime) with:

• its own generated host key under .miao/fair/ — your personal SSH keys are never read, never served, never at risk;
• one-time credentials baked into the link (fresh every fair);
• no shell, no exec, no filesystem — the server answers only the five MIAO protocol ceremonies (HELLO / BUNDLE / SINCE / TRIBUTE / nothing else), so a link-holder can take a copy of the repo and nothing more;
• read-only by default — pushes need the separate --tribute secret, are hash-verified object by object, and only ever fast-forward souls;
• a QR code of the link in .miao/fair/link.svg, and a LAN beacon — nearby friends can run miao enshrine near to discover your fair (the beacon carries no secret).

Collaborators then:

miao enshrine "miao+ssh://pilgrim:SECRET@host:7447/temple"   # clone
miao pilgrimage                                              # pull (ff or “diverged — harmonize”)
miao tribute                                                 # push (entrusted seal, or tribute link)

#Selecting who may push: the keeper's seal 印

Instead of (or alongside) the shared --tribute link, you can grant push rights to chosen people, each by their own Ed25519 identity:

# the collaborator, once per machine:
miao seal                       # cuts a personal seal, prints its 64-hex "seal print"

# you, in your temple:
miao entrust ming <seal print>  # select them
miao entrust                    # list the entrusted
miao entrust --revoke ming      # withdraw (takes effect immediately, even mid-fair)

From then on miao tribute from ming signs the bundle with their seal, and your fair accepts it even in read-only mode — no push secret ever travels or gets shared. The server verifies the signature over the bundle hash and the temple name, checks the seal against .miao/entrusted live on every request, applies objects hash-verified and fast-forward-only, and the chronicle records who pushed (tribute-from ming). Private keys never leave the Ling runtime; only a seed sits in ~/.miao-seal (override the path with MIAO_SEAL to hold several identities).

No network? miao vessel out.miao seals the whole temple into one file you can carry on anything; miao vessel --open out.miao unpacks it, verifying every object hash.

#ROYGBIV

The seven colors are semantic, identical in CLI and GUI (the LingStationX key palette):

red errors/deletions/discord · orange warnings/restless spirits · yellow the altar · green additions/success · blue souls/info · indigo rite ids/metadata · violet talismans/wandering spirits. Every rite gets an aura — its 7-char short id rendered rainbow in the CLI, seven colored tiles in the GUI.

#The GUI — LingMiao

miao gui (or LingMiao.bat). Built from the same design system as LingStationX / LingDev / LingModeler (theme.ling, core.ling, ds.ling, icons.ling): egui-dark chrome, hatched tabs with corner brackets, tile-letter headers. Tabs: Divine (stage/unstage by double-click, live yinyang pane, seal rites), Lineage (auras, soul chips, per-rite manifests with storage glyphs, summon), Souls (kindle, summon, harmonize, release), Fair (open/close the SSH fair inside the window — it serves pilgrims from the frame loop — plus pilgrimage/tribute buttons). F5 re-divines; Ctrl+Q quits. The window narrates every ceremony to the terminal it was launched from.

#LingOS

Three integrations, shaped to what lingfs can actually hold (32 entries/dir, 4096 objects) and what kernel .ling can actually do (no binary reads):

1. The prompt — lsh shows a zsh-style segment when the cwd holds a shrine: (miao:main +) — violet miao:, cyan soul name, yellow + when the altar holds offerings. The help screen is color-grouped, rainbow [words] paints text across the VGA rainbow, and unknown commands answer in the temple's voice.
2. The traveling shrine (行宫) in lsh — a native miao command in the text-mode kernels: kai · wen · gong · ji · pu · hun · zhao (init/status/add/commit/log/ branch/checkout, same aliases, ROYGBIV VGA output). History lives in a handful of files — an append-only book of rites with hash-dedup of unchanged files — instead of per-object files. Text spirits only.
3. os/miao_os.ling — the same shrine (identical on-disk book format, so the two interoperate) as a standalone, arch-neutral LingOS program. It is this spirit's entry_os, so ling build . produces bootable miao images for x86-64 (--platform kernel) and the Raspberry Pi 5 (--platform rpi): booted bare they run a self-demonstration against lingfs and rest. Inside a full LingOS it is a one-shot CLI from the Terminal or Pi shell:

      ling run <path-to-miao_os.ling> wen
      ling run <path-to-miao_os.ling> gong sutra.txt
      ling run <path-to-miao_os.ling> ji the first rite

Rebuild the LingOS kernels themselves (from LingOS/) to get the lsh integration:

../ling/target/release/ling build kernel/x86_64 --platform kernel --out dist
bash live/build-iso-x86_64.sh

The .ling side of these builds (including the patched lsh) AOT-compiles clean; the Rust link stage additionally needs the sibling repos (bring-browser, horizon-browser, ling-messenger, LingDev, LingModeler, ling-wallet) reachable at Programs/ — junctions to Programs/LingApps/ work.

#Publishing

lingfu publish from this folder hands the spirit to the ling registry (its build farm builds the targets list). lingfu login first if the registry asks.

#Inside .miao/

MIAO                 format marker          SOUL        the living soul (HEAD)
souls/<name>         one tip per soul       talismans/  tags
altar                staged overlay         DISCORD     open merge, if any
relics/rite/<id>     rites (commits)        chronicle   reflog
relics/spirit/<id>   per-version manifests (whole|delta|chunks)
relics/pay/<id>      raw payload bytes, BLAKE3-named    mothers / mtips   remotes & their tips

.miaoignore (plus any ling.ignore) controls what counts as a spirit; .miao, .git, cache/, screenshots/, .ling-ssh, .ling-build are always ignored.

#Building & running

• From source (all platforms): ling run --interp ling/main.ling <command> — the launchers miao.bat / miao.sh do exactly this (release exes built by ling build carry no console on Windows, so the CLI lives on the interpreter like every Ling app's run.bat).
• Distributable: ling build . --platform win,lin,mac --out dist builds the portable LingMiao app per Ling.toml.
• Put the folder on your PATH (or alias miao), set your name once: miao keeper "Your Name".

#Honest limits (v1)

• One process at a time per temple (no lock file yet — don't run two rites at once).
• harmonize has no rename detection; add/delete vs edit clashes keep ours and flag discord rather than guessing.
• The SSH fair authenticates by link secret (password auth), not client keys; run fairs on networks you trust or over a VPN/tunnel, and re-open the fair to rotate secrets.
• Tribute transfers the bundle as one message — fine for source trees, not for gigabyte temples.
• History walks are linear-scan; a temple with tens of thousands of rites will want the pack/index pass that is sketched but not built.