From 2d9708cc36d97e1c77db8414464a2ba5d9259107 Mon Sep 17 00:00:00 2001 From: Oddur Sigurdsson Date: Fri, 11 Sep 2026 02:15:23 -0400 Subject: [PATCH] docs: make the README work for someone arriving at the repo It was written for someone who already had the working copy: no clone step, no toolchain requirement, no licence, no contributing section, and nothing saying the workflow is worktree-and-PR rather than commit-to-main. Also states that the build is ad-hoc signed and meant to be built locally, rather than letting someone find that out through a quarantine dialog. --- README.md | 35 +++++++++++++++++++++++++++++++++-- 1 file changed, 33 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f8e948d..0b9537d 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ # Windflow -A macOS screensaver that draws your aerial photographs out of moving wind. +[![ci](https://github.com/oddurs/windflow/actions/workflows/ci.yml/badge.svg)](https://github.com/oddurs/windflow/actions/workflows/ci.yml) + +A macOS screensaver that paints your aerial photographs out of moving wind. The photograph is never drawn. It exists only as a palette that the wind *samples*. The screen starts black; coloured streaks appear and begin flowing @@ -14,14 +16,23 @@ on the photograph. There is no layer of the real image anywhere in the frame. ## Install +Requires macOS 13 or later and the Xcode Command Line Tools (`xcode-select +--install`). There is no Xcode project to open. + ```sh -scripts/build.sh # builds a universal Windflow.saver + a preview harness +git clone https://github.com/oddurs/windflow.git +cd windflow +scripts/build.sh # universal Windflow.saver, ad-hoc signed, plus the tools scripts/install.sh # copies it to ~/Library/Screen Savers and restarts the host ``` Then **System Settings → Screen Saver → Other → Windflow**, and **Options…** to add your photographs. +The build is ad-hoc signed, which is enough for a screensaver you compiled +yourself. It is not notarised, so a copy downloaded from the internet would be +quarantined — build it locally. + ## Adding photographs Use **Options… → Add Photos…** in System Settings. Files are *copied* into @@ -133,3 +144,23 @@ required. The renderer is entirely CPU-side, which avoids the Metal toolchain | Exposure | line brightness | | Bloom | halo around the brightest lines | | Time per image | reveal plus the hold before it dissolves | + +## Contributing + +```sh +scripts/setup # once: wires the git hooks +scripts/task check # fmt, lint, test, build — the gate CI runs +``` + +`main` advances only through a merged pull request. Start a unit of work with +`scripts/agent start fix/the-thing`, which puts it in its own worktree and +branch. Commits are Conventional Commits; the hooks enforce that and the full +check before a push. + +If you are changing anything visual, render frames and look at them — see the +`render-frames` skill in `.claude/skills/`. Every aesthetic bug in this project's +history was invisible in the code and obvious in a PNG. + +## Licence + +MIT. See [LICENSE](LICENSE).