install.sh: shallow clone, about 215 MB to download instead of 351

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+**The installer downloads less: a shallow clone**
+- Why: after #51 a full clone is about 550 MB on disk (351 MB to download), 336 MB of it `.git`, because earlier versions of the sample films stay in the history (`showcase/04-intro-film/media/final.mp4` alone is 48 MB, and v3's media moved to `v3/`).
+- `install.sh` clones with `--depth 1 --single-branch`: about 215 MB to download and 420 MB on disk (measured 2026-10-04 at a881f4f). Re-running it on such a checkout fetches the newest commit with `--depth 1` and moves to it with `git reset --keep`, since there is nothing to fast-forward along: untracked and ignored files (`LOCAL.md`, `projects/`) and edits to files the update doesn't touch stay. Before fetching, it stops if the checkout has commits of your own or isn't on a branch that tracks the repo (a detached HEAD, a branch of your own). When the update would overwrite an edited file, or an untracked one that isn't ignored, it stops with a hint and puts `origin/main` back, so `git status` and the next run see the checkout as it was. A full clone (made by hand, or by an earlier installer) is still updated with `git pull --ff-only`, because a depth-1 fetch would make it shallow.
+- README (en/zh): the clone and total sizes (about 825 MB on disk instead of 935), the "What gets downloaded" row, a note that contributors who want the history clone normally, and "To update" says to re-run the install command with the same options (and how to pass them to the one-line install). `showcase/04-intro-film/v3/README*`: in the installer's clone, v3's source has to be fetched before `git checkout 7057c74`. The wiki's Getting Started pages follow.
+
 **The intro film v5: a Blender-rendered galaxy of films, then one take through the repo (150.5 s)**
 - Why: at gate ① the maintainer found the old opening "not stunning enough… the waterfall looks like the same film over and over" and asked for glass, cosmos and a starry sky that makes you dizzy; after a WebGL look-dev, "a bit of a cheap-effects feel… could the films be shown as a galaxy, as stars? Or use Blender? Hollywood blockbuster quality"; after the first Blender version, less jitter, Blender only for the first 15 s, "just make the final version". The old film also showed stale numbers (8 types, 9 playbook docs).
 - `showcase/04-intro-film/` is now v5 (v3's docs and media are kept in `v3/`, its source at 7057c74). The opening (0–15.8 s) is path-traced in Blender 5.2 (Cycles, Metal) by `blender/galaxy.py` (GPL-3.0-or-later): numpy computes 1.18 million stars and 16,000 film cards per frame, with `velocity` attributes for motion blur and volume shaders written as expressions (`blender/nodexpr.py`); it runs sandboxed in resumable chunks (`tools/bl.sh`, `tools/bl_render.sh`). Over 15.0–15.6 s it dissolves into a WebGL grid that redraws the same cards through the same camera (`tools/export_state.py` exports both from `galaxy.py` without Blender). The body is v3's one-take world at 80 BPM instead of 90, with 26 holds stretched so every read meets the reading-time floor (`js/tmap.js`; `tools/retime.py` moves the score and the SFX by the same map), today's counts, a wall of the 31 style samples, the opening's films drifting beside the path, and a workflow section rebuilt after review (9 reads instead of 17; gates as doors made of what they review). 109 film sources: 28 shaders (`opening/`), 41 cuts of the repo's own films, 40 AI stills (`assets/ai/`, prompts kept). `tools/build_audio.sh` rebuilds the soundtrack byte for byte; `tools/deliver.sh` renders and encodes.

README.md

@@ -48,12 +48,12 @@ curl -fsSL https://raw.githubusercontent.com/ZLHad/OpenVideoHarness/main/install
 ```
 
 This one command:
-- clones the repo into `~/OpenVideoHarness` (about 530 MB; the sample films are in it);
+- clones the newest version of the repo into `~/OpenVideoHarness`, without its history (about 420 MB; the sample films are in it);
 - installs the dependencies of the built-in hand-drawn engine and the style renderer (about 210 MB);
 - fetches 30 read-only reference repos (about 195 MB; `--no-refs` skips them);
 - registers the `open-video-harness` skill for Claude Code and Codex, so saying "make a video" in any folder leads the agent here.
 
-That is about 935 MB on disk. The first render and the sound tools download more the first time you use them: [what gets downloaded](#what-gets-downloaded) lists how much and where. New here? The wiki's [Getting Started](https://github.com/ZLHad/OpenVideoHarness/wiki/Getting-Started) page goes from nothing to a first video.
+That is about 825 MB on disk. The first render and the sound tools download more the first time you use them: [what gets downloaded](#what-gets-downloaded) lists how much and where. New here? The wiki's [Getting Started](https://github.com/ZLHad/OpenVideoHarness/wiki/Getting-Started) page goes from nothing to a first video.
 
 Then open Claude Code (or Codex) and say what you want:
 
@@ -343,7 +343,7 @@ bash install.sh --no-refs                        # skip references for now (run
 bash install.sh --no-skill                       # don't register the global skill
 ```
 
-By hand:
+The installer's clone has only the newest commit, which is all you need to make videos. To contribute, or to look through the history, clone it normally instead (about 550 MB, since earlier versions of the sample films stay in the history), then install the rest by hand:
 
 ```bash
 git clone https://github.com/ZLHad/OpenVideoHarness.git && cd OpenVideoHarness
@@ -359,15 +359,15 @@ npx skills add https://github.com/ZLHad/OpenVideoHarness --skill open-video-harn
 
 The skill is only a pointer. The first time it's used, it asks before installing the full workbench.
 
-To update: `git pull` in the repo, then `references/fetch.sh`.
+To update, run the install command again with the same options (the one-line install takes them after `bash -s --`: `curl -fsSL https://raw.githubusercontent.com/ZLHad/OpenVideoHarness/main/install.sh | bash -s -- --no-refs`). In the installer's clone it fetches only the newest commit; it keeps `LOCAL.md` and `projects/`, and stops rather than overwrite a file you changed. In a full clone you can also `git pull`, then `references/fetch.sh`.
 
 ### What gets downloaded
 
 Sizes are approximate, measured on macOS (Apple Silicon); `du -sh` will show slightly different numbers.
 
 | What | When | Where | Size |
 |---|---|---|---|
-| This repo, with the sample films and style samples | install | `~/OpenVideoHarness` | about 530 MB |
+| This repo's newest commit, with the sample films and style samples | install | `~/OpenVideoHarness` | about 215 MB to download, 420 MB on disk |
 | Node packages of the hand-drawn engine and the style renderer | install | `node_modules` inside the repo | about 210 MB |
 | 30 read-only reference repos | install, unless `--no-refs` | `references/repos/` | about 195 MB |
 | Chrome for HyperFrames (`chrome-headless-shell`) | the first `hyperframes render` | `~/.cache/hyperframes` | about 100 MB to download, 200 MB on disk |

README.zh-CN.md

@@ -48,12 +48,12 @@ curl -fsSL https://raw.githubusercontent.com/ZLHad/OpenVideoHarness/main/install
 ```
 
 这一条命令会：
-- 把仓库克隆到 `~/OpenVideoHarness`（约 530 MB，样片和示例片都在里面）；
+- 把仓库的最新版本克隆到 `~/OpenVideoHarness`，不带历史（约 420 MB，样片和示例片都在里面）；
 - 装好自带手绘引擎和风格样片渲染器的依赖（约 210 MB）；
 - 拉取 30 个只读的参考仓库（约 195 MB，加 `--no-refs` 可以先不拉）；
 - 把 `open-video-harness` skill 注册给 Claude Code 和 Codex，之后在任何目录说"做个视频"，agent 都能找到这里。
 
-一共占约 935 MB 磁盘。第一次渲染和第一次用声音工具时还会再下载一批，各有多大、放在哪里，见[会下载什么](#会下载什么)。不知道从哪开始？看 wiki 里的[快速开始](https://github.com/ZLHad/OpenVideoHarness/wiki/%E5%BF%AB%E9%80%9F%E5%BC%80%E5%A7%8B)，从零走到第一支视频。
+一共占约 825 MB 磁盘。第一次渲染和第一次用声音工具时还会再下载一批，各有多大、放在哪里，见[会下载什么](#会下载什么)。不知道从哪开始？看 wiki 里的[快速开始](https://github.com/ZLHad/OpenVideoHarness/wiki/%E5%BF%AB%E9%80%9F%E5%BC%80%E5%A7%8B)，从零走到第一支视频。
 
 然后打开 Claude Code（或 Codex），直接说你要什么：
 
@@ -343,7 +343,7 @@ bash install.sh --no-refs                        # 先不拉参考资料，之
 bash install.sh --no-skill                       # 不注册全局 skill
 ```
 
-手动安装：
+安装脚本克隆的仓库只有最新的一个提交，做视频用这些就够了。想参与贡献，或者要翻历史，就正常克隆（约 550 MB，因为样片的旧版本都留在历史里），其余的手动装：
 
 ```bash
 git clone https://github.com/ZLHad/OpenVideoHarness.git && cd OpenVideoHarness
@@ -359,15 +359,15 @@ npx skills add https://github.com/ZLHad/OpenVideoHarness --skill open-video-harn
 
 这个 skill 只是一个指针，第一次用时会征得你同意，再把完整的工作台装好。
 
-更新：在仓库目录运行 `git pull`，再运行 `references/fetch.sh`。
+更新：用和上次一样的参数再运行一次安装命令（一键安装的参数写在 `bash -s --` 后面：`curl -fsSL https://raw.githubusercontent.com/ZLHad/OpenVideoHarness/main/install.sh | bash -s -- --no-refs`）。安装脚本克隆的仓库只拉最新的一个提交；`LOCAL.md` 和 `projects/` 都不动，要覆盖你改过的文件时会停下来，不会硬改。完整克隆的仓库也可以 `git pull`，再运行 `references/fetch.sh`。
 
 ### 会下载什么
 
 大小都是约数，在 macOS（Apple Silicon）上量的，你那边 `du -sh` 会差一点。
 
 | 下载的东西 | 什么时候 | 放在哪里 | 大小 |
 |---|---|---|---|
-| 本仓库，样片和示例片都在里面 | 安装时 | `~/OpenVideoHarness` | 约 530 MB |
+| 本仓库的最新提交，样片和示例片都在里面 | 安装时 | `~/OpenVideoHarness` | 下载约 215 MB，占磁盘约 420 MB |
 | 手绘引擎和风格样片渲染器的 Node 依赖 | 安装时 | 仓库里的 `node_modules` | 约 210 MB |
 | 30 个只读参考仓库 | 安装时，加 `--no-refs` 可跳过 | `references/repos/` | 约 195 MB |
 | HyperFrames 用的 Chrome（`chrome-headless-shell`） | 第一次 `hyperframes render` | `~/.cache/hyperframes` | 下载约 100 MB，解压后约 200 MB |

install.sh

@@ -3,7 +3,7 @@
 #   curl -fsSL https://raw.githubusercontent.com/ZLHad/OpenVideoHarness/main/install.sh | bash
 #   bash install.sh [--dir ~/OpenVideoHarness] [--no-refs] [--no-skill] [--skill claude|codex|all]
 # What it does, and where it puts things:
-#   1. clone (or fast-forward) the repo into --dir (about 530 MB)
+#   1. clone the repo into --dir, newest commit only (about 420 MB; a re-run moves it to the newest commit, keeping LOCAL.md and projects/)
 #   2. npm install in engines/ClaudeAnimationBase and npm ci in styles/_swatch (HyperFrames 0.8.82), both inside --dir (about 210 MB of
 #      node_modules; npm also writes its own cache, ~/.npm); unless --no-refs, fetch 30 read-only reference repos into references/repos/
 #      (about 195 MB, git-ignored; references/fetch.sh <name> fetches one later)
@@ -30,8 +30,25 @@ need() { command -v "$1" >/dev/null 2>&1 || { echo "✗ $1 is required ($2)"; MI
 MISSING=0
 need git "https://git-scm.com"; need node "Node.js ≥ 22: https://nodejs.org"; need ffmpeg "macOS: brew install ffmpeg"
 [ "$MISSING" = 0 ] || { echo "install the missing tools above, then re-run"; exit 1; }
-if [ -d "$DIR/.git" ]; then say "updating $DIR"; git -C "$DIR" pull --ff-only -q
-else say "cloning into $DIR"; git clone -q "$REPO" "$DIR"; fi
+if [ -d "$DIR/.git" ]; then say "updating $DIR"
+  if [ -f "$DIR/.git/shallow" ]; then
+    # A shallow install: fetch the newest commit alone and move to it. Its parent isn't fetched, so there is nothing to fast-forward
+    # along; reset --keep leaves untracked and ignored files (LOCAL.md, projects/) and edits to files this update doesn't touch as they
+    # are, and stops rather than overwrite an edited file. It would leave commits of your own behind, so look for those first.
+    up=$(git -C "$DIR" rev-parse -q --verify '@{u}' 2>/dev/null) ||
+      { echo "✗ $DIR is not on a branch that tracks the repo (a detached HEAD, or a branch of your own): git -C \"$DIR\" switch main, then re-run"
+        echo "  (already on main? then origin/main is missing: git -C \"$DIR\" fetch, then re-run)"; exit 1; }
+    own=$(git -C "$DIR" rev-list '@{u}..HEAD')
+    grep -qx "$(git -C "$DIR" rev-parse HEAD)" "$DIR/.git/shallow" || [ -z "$own" ] ||
+      { echo "✗ $DIR has commits of your own, which this update would leave behind; update it yourself: git -C \"$DIR\" pull --rebase"; exit 1; }
+    git -C "$DIR" fetch -q --depth 1
+    git -C "$DIR" reset -q --keep '@{u}' || {
+      # put origin/main back where it was, so git status and the next run see the checkout as it was before this run
+      git -C "$DIR" update-ref "$(git -C "$DIR" rev-parse --symbolic-full-name '@{u}')" "$up"
+      echo "✗ $DIR not updated: it would overwrite the files named above. Edited ones: git -C \"$DIR\" stash, re-run, then git -C \"$DIR\" stash pop."
+      echo "  Untracked ones: move them out of the way, then re-run."; exit 1; }
+  else git -C "$DIR" pull --ff-only -q; fi   # a full clone (made by hand, or by an installer from before shallow clones) keeps its history
+else say "cloning into $DIR (newest commit only)"; git clone -q --depth 1 --single-branch "$REPO" "$DIR"; fi
 cd "$DIR"
 say "installing the bundled engine (ClaudeAnimationBase)"; (cd engines/ClaudeAnimationBase && npm install --silent)
 if [ "$REFS" = 1 ]; then say "fetching 30 reference repos (about 195 MB, read-only, git-ignored; --no-refs skips them)"; references/fetch.sh; fi

showcase/04-intro-film/v3/README.md

@@ -1,6 +1,6 @@
 # 04 · promo — OpenVideoHarness intro film (one-take 3D, code-composed score)
 
-> This is the v3 film (2026-09-29), kept for the record. The current intro film is [v5](../README.md); its body is this film's world, updated and slowed from 90 to 80 BPM. The v5 files replaced v3's in the film folder; v3's own source (`js/`, `tools/`, `audio/` below) is at commit 7057c74: `git checkout 7057c74 -- showcase/04-intro-film`.
+> This is the v3 film (2026-09-29), kept for the record. The current intro film is [v5](../README.md); its body is this film's world, updated and slowed from 90 to 80 BPM. The v5 files replaced v3's in the film folder; v3's own source (`js/`, `tools/`, `audio/` below) is at commit 7057c74: `git checkout 7057c74 -- showcase/04-intro-film` (the installer's clone has only the newest commit, so fetch it there first: `git fetch --depth 1 origin 7057c74725c42b38fe545d85916cab11fe78bed4`).
 
 ![OpenVideoHarness intro film](preview.gif)
 

showcase/04-intro-film/v3/README.zh-CN.md

@@ -1,6 +1,6 @@
 # OpenVideoHarness 介绍片 v3：一镜到底 · 产品宣传片
 
-> 这是 v3（2026-09-29），留作记录。现在的介绍片是 [v5](../README.zh-CN.md)：正文沿用这支片子的世界，更新了数字，速度从 90 降到 80 BPM。片子目录里的文件已换成 v5 的；下文提到的 v3 源码（`js/`、`tools/`、`audio/`）在提交 7057c74：`git checkout 7057c74 -- showcase/04-intro-film`。
+> 这是 v3（2026-09-29），留作记录。现在的介绍片是 [v5](../README.zh-CN.md)：正文沿用这支片子的世界，更新了数字，速度从 90 降到 80 BPM。片子目录里的文件已换成 v5 的；下文提到的 v3 源码（`js/`、`tools/`、`audio/`）在提交 7057c74：`git checkout 7057c74 -- showcase/04-intro-film`（安装脚本克隆的仓库只有最新的提交，要先 `git fetch --depth 1 origin 7057c74725c42b38fe545d85916cab11fe78bed4`）。
 
 成片 `final.mp4`（网页版 20.8 MB，带立体声和中英软字幕轨）· 1920×1080 · 30 fps · **81.333 s（2440 帧）** · fx 预设 B · −14.0 LUFS