diff --git a/.gitignore b/.gitignore index 93003107..f3f25c5f 100644 --- a/.gitignore +++ b/.gitignore @@ -84,6 +84,23 @@ tmp/ # added there). No trailing slash so it still matches the symlink, not just dirs. /public +# Video never goes to GitHub (docs/media-assets.md). The only tracked moving +# images are the GIFs a public page embeds, in docs/images/; masters, promo cuts, +# drafts and captures live in the local media library pr/media/ (ignored above). +# The promo branch tracks its Remotion render inputs, so those stay addable. +# A deliberate exception elsewhere takes `git add -f`. +*.mp4 +*.webm +*.mov +*.m4v +*.mkv +*.avi +*.gif +!/docs/images/*.gif +!/scripts/remotion/public/**/*.mp4 +!/scripts/remotion/public/**/*.webm +!/scripts/remotion/public/**/*.gif + # Opt-in gesture overlay runtime assets: large MediaPipe wasm + model (~27 MB) # fetched at build/install by scripts/fetch-gesture-assets.mjs, kept out of git. # (The gesture bundle itself, gesture-codeman.js, IS tracked — built from diff --git a/CLAUDE.md b/CLAUDE.md index baec6e82..adb38400 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -302,6 +302,8 @@ All in `~/.codeman/`: `state.json` (sessions, settings, respawn, orchestrator, c **Generated top-level dirs** (all gitignored — don't edit or commit): `dist/` (esbuild output), `out/`, `coverage/`, `test-results/`, `tmp/`, `screenshots-echo-diag/`. The committed gesture bundle (`src/web/public/gesture/gesture-codeman.js`) IS tracked, but its runtime wasm/model assets (`src/web/public/gesture/wasm/`, `*.task`) are fetched and gitignored. +**Videos and GIFs**: only GIFs a public page embeds are tracked (`docs/images/`), and `.gitignore` blocks `*.mp4`/`*.webm`/`*.mov`/`*.gif` everywhere else. Masters, promo cuts, drafts and captures live in the local, gitignored media library `pr/media/` (guide `pr/media/README.md`, generated `INVENTORY.md` via `node pr/media/inventory.mjs`); never leave a render in `tmp/` or `out/`. A GIF leaving `docs/images/` needs a hotlink check first (articles embed raw `master` URLs). → `docs/media-assets.md` + ## Testing **`npm test` is the gate and is safe to run bare** — it runs `config/vitest.ci.config.ts`, exactly what CI runs, so local green means CI green. diff --git a/docs/images/codeman-demo.gif b/docs/images/codeman-demo.gif deleted file mode 100644 index 73eb7c4d..00000000 Binary files a/docs/images/codeman-demo.gif and /dev/null differ diff --git a/docs/images/codeman-skill-20261010.gif b/docs/images/codeman-skill-20261010.gif deleted file mode 100644 index 9da1963d..00000000 Binary files a/docs/images/codeman-skill-20261010.gif and /dev/null differ diff --git a/docs/images/subagent-demo-new.gif b/docs/images/subagent-demo-new.gif deleted file mode 100644 index 8c7c52b5..00000000 Binary files a/docs/images/subagent-demo-new.gif and /dev/null differ diff --git a/docs/images/subagent-demo-opt.gif b/docs/images/subagent-demo-opt.gif deleted file mode 100644 index a9b30202..00000000 Binary files a/docs/images/subagent-demo-opt.gif and /dev/null differ diff --git a/docs/images/tab-alerts-glow-20260815.gif b/docs/images/tab-alerts-glow-20260815.gif deleted file mode 100644 index 12230447..00000000 Binary files a/docs/images/tab-alerts-glow-20260815.gif and /dev/null differ diff --git a/docs/images/tiles-crt-20261010.gif b/docs/images/tiles-crt-20261010.gif deleted file mode 100644 index de5cd335..00000000 Binary files a/docs/images/tiles-crt-20261010.gif and /dev/null differ diff --git a/docs/images/tiles-crt-stats-20261010.gif b/docs/images/tiles-crt-stats-20261010.gif deleted file mode 100644 index d8caa519..00000000 Binary files a/docs/images/tiles-crt-stats-20261010.gif and /dev/null differ diff --git a/docs/media-assets.md b/docs/media-assets.md new file mode 100644 index 00000000..fab60f35 --- /dev/null +++ b/docs/media-assets.md @@ -0,0 +1,68 @@ +# Media assets: videos and GIFs + +Codeman produces a lot of video: README GIFs, website loops, release-note clips, promo videos and their drafts, raw screen captures. This page says where each kind lives and which of them belong in git. + +## The rule + +**Only media that a public page embeds is pushed to GitHub. Everything else stays on the maintainer's machine, in the local media library.** + +| Kind | Where it lives | On GitHub? | +| --- | --- | --- | +| GIFs the README, the wiki or a published article embeds | `docs/images/` on `master` | yes | +| Release-note and media-kit clips | the orphan `design-assets` branch | yes, but never on `master` | +| getcodeman.com videos and GIFs | `pr/website/assets/` (local, deployed to Cloudflare Pages) | no | +| Masters, promo videos, drafts, shorts, feature clips, raw captures | `pr/media/` (the local media library) | no | +| Remotion render inputs for the promo videos | `scripts/remotion/public/` on the unpushed promo branch | no | + +`.gitignore` enforces it: `*.mp4`, `*.webm`, `*.mov`, `*.m4v`, `*.mkv`, `*.avi` and `*.gif` are ignored everywhere except `docs/images/*.gif`, plus `scripts/remotion/public/`, whose render inputs the promo branch tracks. A video that really must be committed needs `git add -f`, which makes the exception visible in review. + +A GIF that leaves `docs/images/` stays in git history, so removing it does not shrink a clone. The rule keeps new weight out and the tree honest about what is actually used. + +## Tracked GIFs (`docs/images/`) + +| File | Embedded in | Shows | +| --- | --- | --- | +| `tiles-crt-stats-1600-20261010.gif` | README hero (en + zh-CN) | six live agents in the tile grid, powering on and off with the CRT animation, header stats on | +| `tile-grid-20261009.gif` | README, Tile Grid section | the Tiles button opening six live sessions side by side, and closing them | +| `zerolag-demo-20260728.gif` | README, wiki `Input-And-Voice`, `packages/xterm-zerolag-input/README.md`, CHANGELOG, getcodeman.com docs | instant local echo next to slow server echo, on two phones | +| `codeman-tab-states-20261010.gif` | README, Tab Alerts section | annotated tab states: working, blocked on a question, idle | +| `codeman-skill-crt-20261010.gif` | README, agent skill section | one prompt to Claude Code spawning and driving two worker sessions through the skill | +| `subagent-demo-20260724.gif` | the "mission control" article on dev.to, Hashnode and Medium (hotlinked from `master`) | subagent windows fanning out | + +Before removing one, search for hotlinks: `README*.md`, `docs/wiki/`, `packages/*/README.md`, `CHANGELOG.md`, the site (`pr/website/`), and published articles, which link `raw.githubusercontent.com/Ark0N/Codeman/master/docs/images/` and break silently. + +On 2026-10-13, seven GIFs that no page embedded left `docs/images/` and moved into the library: `codeman-demo.gif`, `codeman-skill-20261010.gif`, `subagent-demo-new.gif`, `subagent-demo-opt.gif`, `tab-alerts-glow-20260815.gif`, `tiles-crt-20261010.gif`, `tiles-crt-stats-20261010.gif`. + +### Adding or replacing a README GIF + +1. Keep the master (the lossless MP4 or the full-size GIF) in `pr/media/clips//`, or in the project folder it came from. +2. Commit only the size the README shows, named `-.gif`, and keep it lean: the current ones are 0.8 to 7 MB. +3. A replaced GIF leaves `docs/images/` in the same commit, unless something outside the repo hotlinks it (see above). + +## Website media (getcodeman.com) + +The site is built and deployed from `pr/website/` (gitignored) with `pr/deploy-site.sh`. Its videos and GIFs sit in `pr/website/assets/` because that directory is what gets uploaded: they are web cuts (1280 to 1600 px wide, high CRF, posters next to them) derived from masters in the library. `pr/site-notes.md` records how each one was cut and from which master. A few superseded files stay deployed on purpose, so links that point at them keep resolving. + +## Release notes and the media kit (`design-assets` branch) + +GitHub releases and the Announcements discussions embed clips from the orphan `design-assets` branch (`release-1.40/`, `release-1.41/`, `media-kit-2026-10/`). They are referenced by a commit-pinned raw URL, so the branch can change later without breaking old notes, and none of it ever touches `master`. + +## The local media library (`pr/media/`) + +`pr/` is gitignored, so the library is never pushed. It holds every master, every finished promo cut and every superseded draft in one tree: + +``` +pr/media/ + README.md curated guide: what each collection is, which cut is current, where it is published + INVENTORY.md generated list of every file (size, length, resolution, fps, date, published-or-not) + inventory.mjs regenerates INVENTORY.md: node pr/media/inventory.mjs + videos// finished promo videos; superseded renders in drafts/ + shorts// per-feature cuts of a promo; older sets in drafts/ + clips// feature loops and GIF masters (README / site / release clips start here) + crt-gifs/ CRT tile-animation loops + files-one-click-20261011/ the Files panel loop project (own README) + screenshots-hq/ high-res stills and their capture masters + raw-captures/ unedited screen recordings, safe to prune +``` + +Two working directories keep files the library only archives, because tools read them from fixed paths: `pr/website/assets/` (the deploy upload) and the promo worktree's `scripts/remotion/public/` (Remotion's `staticFile()` inputs). Renders still land in `scripts/remotion/out/` and are filed into `pr/media/videos//` once checked. A finished render never goes to `tmp/`.