Rewrite the README and add a recorded demo

Rework the README into the house style: badges, a one-line pitch, an anchor nav, a commands table, and dedicated sections for clone, pack, and the native viewer. Every flag and default is checked against the current binary so the docs match what kage actually does. Add a demo recorded with ascii-gif. The tape clones example.com, packs it to a ZIM and to a self-contained binary, and serves it back offline, so the whole loop reads in one frame. It sits at the top of the README and on the docs home. While reviewing the docs, fix the output path everywhere: the default is $HOME/data/kage, not the kage-out the pages claimed, including a few fabricated 'done kage-out/...' lines. Document pack, open, and the native viewer in the release notes.
2026-06-14 22:25:31 +07:00
parent 5b7f7d9f31
commit 3af26ae0e5
11 changed files with 209 additions and 95 deletions
@@ -15,9 +15,11 @@ inert.

 ```bash
 kage clone example.com
-kage serve kage-out/example.com
+kage serve $HOME/data/kage/example.com
 ```

+![kage cloning a site, packing it into one file, and serving it back offline](/demo.gif)
+
 ## What it does

 - **Renders first, saves second.** Each page goes through real headless Chrome,
@@ -37,5 +39,7 @@ kage serve kage-out/example.com
  the [quick start](/getting-started/quick-start/).
 - Want to install it? See [installation](/getting-started/installation/).
 - Looking for a specific task? The [guides](/guides/) cover scoping a crawl,
-  serving a mirror, and resuming an interrupted run.
+  serving a mirror, resuming an interrupted run, and
+  [packing a mirror](/guides/packing-a-mirror/) into one file or a self-contained
+  viewer.
 - Need every flag? The [CLI reference](/reference/cli/) is the full surface.
@@ -46,7 +46,7 @@ folder anywhere, open it with no network, and click around.

 kage crawls breadth-first from a seed URL, staying within the seed's host (and
 optionally its subdomains). It is polite by default: it honours `robots.txt` and
-seeds itself from `sitemap.xml`. Output lands in `kage-out/<host>/`, with pages
+seeds itself from `sitemap.xml`. Output lands in `$HOME/data/kage/<host>/`, with pages
 as `<path>/index.html` and assets under a reserved `_kage/` directory alongside
 the crawl state that powers `--resume`.

@@ -19,15 +19,15 @@ errors as it goes; the final summary tells you where the mirror landed.

 ```
 kage cloning https://example.com
-done kage-out/example.com
+done $HOME/data/kage/example.com
  pages 12   assets 38
-  open kage serve kage-out/example.com
+  open kage serve $HOME/data/kage/example.com
 ```

 ## 2. Look at what landed

 ```bash
-ls kage-out/example.com
+ls $HOME/data/kage/example.com
 ```

 ```
@@ -46,7 +46,7 @@ serve` runs a local static server so everything resolves exactly as it would
 live:

 ```bash
-kage serve kage-out/example.com
+kage serve $HOME/data/kage/example.com
 # open http://127.0.0.1:8800
 ```

@@ -16,7 +16,7 @@ ZIM is the open, single-file offline-archive format Kiwix uses. `kage pack`
 writes one from a cloned host directory:

 ```bash
-kage pack kage-out/example.com
+kage pack $HOME/data/kage/example.com
 ```

 ```
@@ -65,7 +65,7 @@ opens your browser; it ignores its arguments, because the binary is the site, no
 the kage CLI.

 ```bash
-kage pack kage-out/example.com --format binary
+kage pack $HOME/data/kage/example.com --format binary
 ```

 ```
@@ -95,7 +95,7 @@ packed binary feels like a standalone app:

 ```bash
 CGO_ENABLED=1 go build -tags webview -o kage ./cmd/kage
-kage pack kage-out/example.com --format binary --base kage
+kage pack $HOME/data/kage/example.com --format binary --base kage
 ./example   # opens a window, no browser
 ```

@@ -113,7 +113,7 @@ machine:

 ```bash
 # From macOS, build a Windows viewer
-kage pack kage-out/example.com --format binary --base kage-windows-amd64.exe
+kage pack $HOME/data/kage/example.com --format binary --base kage-windows-amd64.exe
 # -> example.exe
 ```

@@ -129,7 +129,7 @@ xattr -d com.apple.quarantine ./example
 ## Metadata and options

 ```bash
-kage pack kage-out/example.com \
+kage pack $HOME/data/kage/example.com \
  --title "Example, offline" \
  --description "A snapshot taken for archival" \
  --language eng \
@@ -37,7 +37,7 @@ existing host folder first with `--force`:
 kage clone example.com --force
 ```

-This removes `kage-out/example.com/` before crawling, so nothing from a prior run
+This removes `$HOME/data/kage/example.com/` before crawling, so nothing from a prior run
 carries over.

 To run without reading or writing any resume state at all, for a strictly
@@ -12,11 +12,11 @@ when served from the root of a host. `kage serve` gives you that root.
 ## Serve a clone

 ```bash
-kage serve kage-out/example.com
+kage serve $HOME/data/kage/example.com
 ```

 ```
-kage serve /…/kage-out/example.com
+kage serve $HOME/data/kage/example.com
  open http://127.0.0.1:8800
  press Ctrl-C to stop
 ```
@@ -31,10 +31,10 @@ By default kage serves on `127.0.0.1:8800`. Change it with `--addr`:

 ```bash
 # A different port
-kage serve kage-out/example.com --addr 127.0.0.1:9000
+kage serve $HOME/data/kage/example.com --addr 127.0.0.1:9000

 # Reachable from other machines on your network (be deliberate about this)
-kage serve kage-out/example.com --addr 0.0.0.0:8800
+kage serve $HOME/data/kage/example.com --addr 0.0.0.0:8800
 ```

 ## Serve the current directory
@@ -43,6 +43,6 @@ With no argument, `kage serve` serves the current directory, which is handy from
 inside an output folder:

 ```bash
-cd kage-out/example.com
+cd $HOME/data/kage/example.com
 kage serve
 ```
@@ -24,7 +24,7 @@ A clone of `example.com` lands under `$HOME/data/kage/example.com/` (override th
 root with `-o/--out`):

 ```
-kage-out/example.com/
+$HOME/data/kage/example.com/
 ├── index.html                  # the home page (/), scripts stripped
 ├── about/index.html            # /about
 ├── blog/
@@ -9,6 +9,25 @@ The authoritative, commit-level history lives in
 [releases page](https://github.com/tamnd/kage/releases). This page summarises
 each version.

+## Unreleased
+
+Packing, so a clone can travel as one file instead of a folder.
+
+- **`kage pack <mirror-dir>`** collapses a mirror into a single distributable
+  file. `--format zim` (the default) writes an open ZIM archive, the same format
+  Kiwix uses; `--format binary` appends that archive to a copy of kage to make a
+  self-contained executable that serves the site offline when run. Packing is
+  deterministic, so the same mirror produces a byte-identical file.
+- **`kage open <file.zim>`** serves a packed ZIM back over a local HTTP server,
+  the read side of `kage pack --format zim`.
+- **An optional native-window viewer.** Built with `-tags webview`, `kage open`
+  and a packed binary show the site in a real window backed by the operating
+  system's WebView instead of a browser tab. The default build stays pure Go and
+  opens the browser, so the release pipeline is unchanged.
+- **A pure-Go `zim` package** that reads and writes the ZIM format: a fixed
+  header, MIME and pointer lists, zstd or stored clusters, redirects, and a
+  trailing MD5.
+
 ## v0.1.0

 The first release. kage clones a live website into a self-contained folder you
@@ -0,0 +1,34 @@
+# Demo tape for kage. Rendered with ascii-gif (github.com/tamnd/ascii-gif),
+# which supplies the window chrome and theme; this file is just the action.
+#
+#   ascii-gif render docs/demo/kage.tape -o docs/static/demo.gif
+#
+# kage must be on PATH inside the recording shell, and Chrome available.
+
+Hide
+Type "export PS1='$ ' && cd $(mktemp -d) && clear"
+Enter
+Show
+
+Sleep 600ms
+Type "kage clone example.com --out ."
+Sleep 700ms
+Enter
+Sleep 4.5s
+
+Type "kage pack example.com"
+Sleep 700ms
+Enter
+Sleep 2.5s
+
+Type "kage pack example.com --format binary -o example"
+Sleep 700ms
+Enter
+Sleep 3s
+
+Type "kage open example.com.zim --open=false"
+Sleep 700ms
+Enter
+Sleep 3s
+Ctrl+C
+Sleep 1.2s