ling-miao

# miao 庙 — the temple of versions

A version control system written in the [Ling language](https://ling-lang.org), 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.

![miao — tutorial infographic](screenshots/miao-tutorial.png)

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

![LingMiao — Divine tab](screenshots/lingmiao-divine2.png)
![LingMiao — Lineage tab](screenshots/lingmiao-lineage.png)
![LingMiao — Fair tab](screenshots/lingmiao-fair.png)

## 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:

| command | pinyin | git | what it does |
|---|---|---|---|
| `miao consecrate [dir]` | `kai` 开光 | `init` | found a temple |
| `miao divine` | `wen` 问 | `status` | ask the oracle what changed |
| `miao offer <paths\|.>` | `gong` 供 | `add` | place spirits on the altar |
| `miao withdraw <paths>` | `che` 撤 | `unstage` | take an offering back |
| `miao rite -m "..."` | `ji` 祭 | `commit` | seal the altar into history |
| `miao lineage [-n N] [--all]` | `pu` 谱 | `log` | the genealogy of rites |
| `miao yinyang [a] [b] [--altar]` | 阴阳 | `diff` | dark removed · light added |
| `miao soul [name] [-d name]` | `hun` 魂 | `branch` | the temple's souls |
| `miao summon <soul\|rite>` | `zhao` 召 | `switch` / `checkout` | call a soul into the worktree |
| `miao harmonize <soul>` | `he` 合 | `merge` | bring two souls into harmony |
| `miao talisman [name] [rite]` | `fu` 符 | `tag` | fix a name to a moment |
| `miao manifest [rite\|path]` | `xian` 显 | `show` | let a spirit manifest |
| `miao restore <paths>` | `huan` 还 | `restore` | return a file to its enshrined form |
| `miao fair [--tribute] [--port N]` | `hui` 庙会 | `serve` | open your temple over SSH |
| `miao enshrine <link\|near> [dir]` | `fenling` 分灵 | `clone` | found a daughter temple |
| `miao mother [add n link \| rm n]` | `zumiao` 祖庙 | `remote` | the ancestral temples you follow |
| `miao pilgrimage [mother]` | `jinxiang` 进香 | `pull` | fetch + fast-forward |
| `miao tribute [mother]` | `huixiang` 回香 | `push` | carry your rites up |
| `miao vessel <file> [--open]` | 法器 | `bundle` | the whole temple in one file |
| `miao keeper [name]` | 守庙人 | `config` | who signs your rites |
| `miao chronicle` | 编年 | `reflog` | what the temple remembers doing |
| `miao gui` | | | open the LingMiao window |

`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:

| strategy | glyph | chosen for | how it works |
|---|---|---|---|
| **whole** | ○ | small spirits (≤ 256 KiB), first versions | full content, stored raw |
| **delta** | ◐ | text files with a previous version | a line-delta script against the prior spirit; chains are capped at depth 8 and fall back to whole when the script wouldn't save ≥ 55%, so summoning stays O(1)-ish |
| **chunks** 分身 | ◍ | large files (> 256 KiB), binaries | content-defined chunking (anchor-based, 64–256 KiB chunks): chunks dedup across versions *and* across files |

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.