rewrite the README around current Koh workflows

@@ -1,116 +1,234 @@11 # Koh22 3-**Version control designed for the solo developer.**3+Koh is version control for a solo developer working across a few machines.4+Save your project, see what changed, and bring back earlier work when you need5+it. Each repository keeps its history in one SQLite file, `.koh`, with one line6+of saves. Koh is written in V.47 5-Most version control is built for teams, with branches to keep people out of6-each other's way, pull requests to argue in, and merge tools for when two people7-edited the same line. On your own you need none of that. You need to save your8-work, see what changed, go back when something breaks, and pick up on your9-laptop where you left off on your desktop.8+## Install109 11-That's all Koh does.10+Koh runs on Apple silicon macOS and Linux on ARM64 or x86_64. New releases do11+not support Intel macOS or Windows.1212 1313 ```sh14+curl -fsSL https://koh.asha.software/install.sh | sh15+```16+17+The installer verifies the release checksum and offers an optional zsh plugin.18+For later updates, run `koh update`. Use `koh update --check` to check without19+installing.20+21+## Start saving22+23+Run these commands in your project folder:24+25+```sh1426 koh init15-koh save "sketch the parser"27+koh save "record the first working version"1628 koh status1729 koh view18-koh undo            # step back one save, without losing it19-koh offer           # send your saves to your bucket20-koh steal           # on the other machine: bring them in2130 ```2231 23-## How it thinks32+`init` creates `.koh` and a starter `.kohignore`. Check the ignore rules before33+your first save. Each save snapshots every file Koh tracks, including new34+files; unchanged contents are stored only once. `save` refuses when nothing35+changed.2436 25-**Nothing is erased.** Your history is one straight line, and every command adds26-to it. Undo, revert and load don't rewind anything. They record a new save27-that puts the files back, so the save you stepped away from is still there28-tomorrow. The only exception is `strip`, for the day a secret gets saved,29-and it makes you type the path twice before it does anything.37+Before a change you may want to undo, make a checkpoint:3038 31-**Everything lives in one file.** A repo's whole history is `.koh`, a single32-SQLite file at the root, and there's nothing else to maintain. Copy that file33-and you've copied the whole history.39+```sh40+koh checkpoint "before changing the parser"41+```3442 35-**Your machines, not a server.** Point Koh at an S3 bucket or a folder on a36-disk once per machine with `koh remote`, and every save is offered to it37-automatically. If you worked on both machines without syncing, `koh steal`38-combines them file by file. A file changed on only one side just comes along.39-A file changed on both sides is shown to you, and you pick which version to40-keep. Your version isn't thrown away either way: the save it came from stays41-in history.43+A checkpoint records the project even when nothing changed. After editing,44+`koh diff` shows the changes and `koh save "describe the result"` records them.45+Commands work from subfolders too.4246 43-**Safe to hand to an agent.** Every command has `--json`, never waits for44-input when nothing is typing, and exits 0, 1 or 2. Saves record which agent45-made them and in which session, so `koh undo --session` can take back an46-agent's whole run in one step. A person has to be at the keyboard to `strip`.47+`koh view` opens an interactive history browser in a terminal. Use the arrow48+keys or `j` and `k` to move, `/` to search, Enter for details, and Tab to switch49+between saves and checkpoints. With `--json` or when piped, it prints history.50+`LOG.md` is a generated summary of the latest 20 saves.4751 48-**Small on purpose.** Koh 3 has 20 commands plus the manual, down from Koh 2's 45, and a hard49-ceiling of 12,000 lines of V. A feature that doesn't fit gets cut, so one50-person can still read all of it.52+## Bring back earlier work5153 52-## Setting up sync54+| Command | What it does |55+| --- | --- |56+| `koh undo` | Restore the previous save. |57+| `koh undo 3` | Step back three saves. |58+| `koh load <id>` | Restore a particular save. |59+| `koh load --checkpoint` | Restore the latest checkpoint. |60+| `koh revert` | Discard unsaved changes, keeping them in a checkpoint first. |61+| `koh peek <id>` | Unpack a save into a temporary folder for inspection. |62+| `koh pluck <id>` | Apply one save's changes to the current tree as a new save. |5363 64+Restoring earlier work adds a new save. The saves you stepped away from remain65+available, so you can load them again. Koh has no branches or lanes.66+67+`undo`, `load`, and `pluck` require a clean working tree. Commands that rewrite68+your files show a preview and ask for confirmation. Enter cancels; only `y` or69+`Y` approves. Scripts must supply `--yes` to approve the action.70+71+## Sync your machines72+73+Choose an S3 bucket or a folder remote once per machine. Every repository on74+that machine uses the same remote.75+76+For a folder, such as one on a removable drive:77+5478 ```sh55-koh remote          # asks: a folder, or an S3 bucket?79+koh remote folder /Volumes/usb/koh5680 ```5781 58-It tests the remote before saving anything. Scripts can skip the questions:82+For S3, supply the endpoint, bucket, and region. Koh asks for the access keys83+and tests the connection before keeping the settings:5984 6085 ```sh61-KOH_ACCESS_KEY=... KOH_SECRET_KEY=... \62-  koh remote s3 https://s3.fr-par.scw.cloud my-bucket fr-par63-koh remote folder /Volumes/usb/koh86+koh remote s3 https://s3.fr-par.scw.cloud my-bucket fr-par6487 ```6588 66-Or write the two files yourself. `koh man remote` shows the format.89+If you run a [Kepr](https://kepr.uk/), `koh remote <kepr-host>` opens its sign-in90+page and lets you connect with the code it supplies. `koh remote` shows the91+current setting. Replacing or forgetting an existing remote requires consent.6792 93+Once configured, saves and checkpoints offer their history automatically.94+A failed transfer leaves the local save intact; run `koh offer` to retry.95+On another machine, fetch a repository from outside an existing repo:96+97+```sh98+koh steal my-project99+cd my-project68100 ```69-~/.config/koh/remote        kind, endpoint, bucket, region (or path)70-~/.config/koh/credentials   access_key, secret_key, mode 600101+102+Inside it, `koh steal` brings in new history. If both machines changed a file,103+Koh shows both versions and asks which one to keep. It resolves clashes per104+file, without blending lines. The original saves remain available, and the105+result names the save you can load to return to your previous state.106+107+Incoming changes require confirmation. For scripts, `--mine` or `--theirs`108+chooses a side for every clash; `--yes` separately approves applying the changes.109+110+You can also fetch a public repository with `koh steal <kepr-host>/<repo>`.111+That copy syncs from its public source and cannot offer back until you sign in112+to that Kepr as its operator.113+114+## Ignore files and remove saved content115+116+`.kohignore` holds rules for the repository and travels with its saves.117+`~/.kohignore` adds rules for every repository on this machine and stays local.118+Koh also excludes its own history files, `LOG.md`, and symlinks.119+120+```sh121+koh ignore cache/ output/ notes.txt122+koh ignore --global scratch.txt71123 ```72124 73-## In your prompt125+`ignore` previews the exact rules and asks once for the batch. A path already126+matched in the selected ignore file proposes removing its matching rules;127+removing a broad rule can affect other files, which the preview explains.128+Local paths are relative to the current directory. Global names and paths129+match at any depth in every repository.74130 75-`shell/koh3.plugin.zsh` puts the repo in your zsh prompt and adds tab76-completion:131+Ignoring a file leaves its earlier saved versions in history.132+`koh strip <path>` permanently removes a file or folder from all saves and133+bans that path from future saves. It propagates the removal to the remote and other machines134+as they sync. The working file stays on disk. `--save <id>` limits removal to135+one save and does not ban the path.77136 137+Strip is the exception to Koh's growing history: it cannot be undone. It138+requires a terminal and each affected path typed exactly. `--yes` skips only139+the yes/no question. See `koh man strip` before using it.140+141+## Work with coding agents142+143+Saves can record the agent's model and a session name:144+145+```sh146+koh save --agent gpt-6 --session "fix parser errors" "reject incomplete input"147+koh view --session "fix parser errors" --json148+koh diff --session "fix parser errors"78149 ```79-kiln · v2.1.0 · 6 saves · 4.2 MB !80-→81-```82150 83-`!` means unsaved changes, and `⚑` means the save you're on has been flagged.84-Source it from `~/.zshrc`. The comments at the top cover Starship,85-Powerlevel10k and using your own prompt.151+`koh undo --session` restores the state before the current session. Use the152+actual model identifier and keep one session name for related work.86153 87-## Status154+Commands that print data support `--json`. Koh refuses when a required prompt155+cannot be answered, so unattended commands never wait for input. Exit codes156+are `0` for success, `1` for refusal or failure, and `2` for bad usage.88157 89-Koh supports Apple silicon macOS and Linux on x86_64 and ARM64.90-Intel macOS is no longer supported for new releases.158+## Build projects and publish releases91159 92-Install Koh with:160+A project's `koh.build` file names its build command, output, and platforms.161+`koh build` runs it for the current machine without uploading or installing162+anything. The toolchain must already be on `PATH`.93163 164+`koh offer --builds` builds every configured platform and publishes the165+artifacts as a release. It requires a saved tree and a version in the project's166+own files, such as `VERSION`, `v.mod`, or `package.json`. Ordinary saves never167+publish builds. See the [specification](docs/koh-kepr-3-master-spec.md) for the168+file format, and `koh man build` or `koh man offer` for command options.169+170+## Back up a repository171+94172 ```sh95-curl -fsSL https://koh.asha.software/install.sh | sh173+koh doctor174+koh doctor --backup /path/to/new-backup.koh96175 ```97176 98-The installer checks the release checksum and offers the optional zsh plugin.99-Koh 2 users can run `koh update` and confirm the upgrade, then `koh migrate`100-in each repository. Save unfinished work with Koh 2 first. Migration keeps101-save IDs and archives the old data in `.koh-v2/`; Koh 3 refuses repository102-commands until migration is complete. The specification is103-`docs/koh-kepr-3-master-spec.md`.177+`doctor` checks database integrity, object hashes, and saved file references.178+Its backup command writes a consistent copy of `.koh`. Use it instead of179+copying the database while Koh is using it. Keep a live `.koh` out of cloud180+folder sync services; use `offer` and `steal` between machines.104181 105-## Building182+Koh does not encrypt history. Anyone who can read the database or remote can183+read its saved files. Koh is intended for code and text; individual files over184+512 MiB are refused.106185 186+## Upgrade from Koh 2187+188+Save unfinished work with Koh 2 first. Run `koh update` in a terminal and189+confirm the upgrade, then run `koh migrate` in each repository.190+191+Migration keeps save IDs and archives the old repository in `.koh-v2/`. It192+imports the `dev` ancestry by default, falling back to `main` if `dev` has no193+saves; `--lane main` selects the other line. Koh 3 refuses repository commands194+in an unmigrated Koh 2 repository. See `koh man migrate` for missing file195+recovery and other options.196+197+## Build from source198+199+Use the pinned compiler, `V 0.5.2 b9a2d87`. A different V revision can break200+Koh, and the tests reject it. The [agent guide](AGENTS.md) covers installing201+the pin and preparing a Linux build environment.202+107203 ```sh108-v -o build/koh3 src/koh.v            # or -prod for a release build109-v test src/ && v test tests/204+mkdir -p build205+v -o build/koh3 src/koh.v206+v test src/207+v test tests/110208 v fmt -verify src/ tests/111209 ```112210 113-Koh is pinned to V master at `b9a2d87`, because V master can break it. SQLite114-3.49.1 is vendored and compiled in, so there are no other dependencies.115-`AGENTS.md` has the install steps for the pinned V, the Linux notes and the116-layout.211+SQLite 3.49.1 is vendored and compiled into the executable. Every Koh build212+requires Boehm garbage collection. Release builds use `sh build.sh` or213+`koh build` on the target OS and CPU; Linux releases also need Zig on `PATH`214+for the static musl toolchain. Cross-compiling Koh with the pinned V disables215+garbage collection, so the release script refuses it.216+217+Source lives under `src/`, grouped by responsibility. `tests/` holds CLI and218+library checks; `vendor/` holds SQLite and C shims. The [master219+specification](docs/koh-kepr-3-master-spec.md) records the storage, history,220+sync, and release contracts. Changes here follow [Strict Koh221+Discipline](AGENTS.md): checkpoint first, verify the build and tests, and save222+one coherent result at a time.223+224+## Manual and shell integration225+226+Run `koh man` for the full manual or `koh man <command>` for one command. The227+[manual source](docs/koh3-man.txt) is also available in this repository.228+229+Source [shell/koh3.plugin.zsh](shell/koh3.plugin.zsh) from `~/.zshrc` for a230+prompt segment and tab completion. `!` marks unsaved changes; `⚑` marks a231+flagged head save. The plugin's header covers custom prompts, Starship, and232+Powerlevel10k.233+234+Made by [Asha Software](https://asha.software/).