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

![LingMiao — Divine tab](screenshots/lingmiao-divine.png)
![LingMiao — Lineage tab](screenshots/lingmiao-lineage.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 (tribute link required)
```

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

Two integrations, matching what lingfs can actually hold (32 entries/dir, 4096 objects):

1. **The prompt** — `lsh` now 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 (行宫)** — a native `miao` command in `lsh`: `kai · wen ·
   gong · ji · pu · hun · zhao` (init/status/add/commit/log/branch/checkout, same
   aliases). History lives in a handful of files (an append-only *book of rites* with
   hash-dedup of unchanged files) instead of per-object files, so it respects lingfs
   limits. Text spirits only — the kernel cannot read binaries into .ling. The full
   temple — deltas, chunks, SSH fairs — is the desktop edition.

Rebuild the text-mode kernels to get it (from `LingOS/`):

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

The `.ling` side of this build (including the patched lsh) AOT-compiles clean; the Rust
link stage additionally needs the sibling repos `bring-browser`, `horizon-browser` and
`ling-messenger` reachable at `Programs/` (junctions to `Programs/LingApps/` work).

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