diff --git a/.github/rulesets/README.md b/.github/rulesets/README.md index d1d22c29ec..3c2057dcd3 100644 --- a/.github/rulesets/README.md +++ b/.github/rulesets/README.md @@ -19,15 +19,16 @@ gh api repos/Agent-Field/codeaf/rulesets --jq '.[] | "\(.id)\t\(.name)"' gh api -X PUT repos/Agent-Field/codeaf/rulesets/ --input .github/rulesets/dev.json ``` -## They do not work yet +## When they can be applied -`Agent-Field` is on the **free** plan and this repository is **private**, and -that combination has no branch rules at all — both the rulesets API and the -older protection API answer `403 Upgrade to GitHub Pro`. Until the org moves to -**GitHub Team**, everything in `docs/rules/` is convention that a careless -`git push --force` can undo without being asked a question. +While `Agent-Field` is on the **free** plan and this repository is **private**, +that combination has no branch rules at all — both the rulesets API and the older +protection API answer `403 Upgrade to GitHub Pro`. Until the org moves to **GitHub +Team** or the repository is **public**, everything in `docs/rules/` is convention +that a careless `git push --force` can undo without being asked a question. -Check whether it has started working: +Apply both rulesets with the commands above the day the repository goes public. +Until then, check whether the API has started working: ```sh gh api repos/Agent-Field/codeaf/rulesets diff --git a/CLAUDE.md b/CLAUDE.md index 2aefabf890..6db996f7d9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -109,8 +109,9 @@ in `.github/known-red.txt`, [docs/rules/changelog.md](docs/rules/changelog.md) for what an entry carries, [docs/rules/promotion.md](docs/rules/promotion.md) for the promote-and-release runbook. -None of it is enforced by the server yet — the org is on the free plan and a -private repository gets no branch rules there, so today every line above is +Server enforcement depends on the repository's visibility or plan — the org is +on the free plan, and a private repository gets no branch rules there. Until the +org moves to GitHub Team or the repository is public, every line above is convention. `.github/rulesets/` holds the rules ready to apply. ## Build and ship — the owner's standing orders diff --git a/README.md b/README.md index c881c592fe..2c869beb46 100644 --- a/README.md +++ b/README.md @@ -68,11 +68,11 @@ goes to home from a conversation and `esc` comes back untouched. ### Build from the repository -The road that works today is a source checkout. The module needs Go 1.26.5, and -`make build` is the one supported build command; it writes `bin/codeaf`. +The source road needs nothing published. The module needs Go 1.26.5, and `make +build` is the one supported build command; it writes `bin/codeaf`. ```bash -git clone https://github.com/Agent-Field/codeaf.git # needs repository access while it is private +git clone https://github.com/Agent-Field/codeaf.git # while the repository is private, this needs access cd codeaf make build # fetches the pinned Furrow artifact, so it needs the network; # FURROW_ARTIFACT=/path/to/furrow supplies it offline @@ -82,25 +82,28 @@ bin/codeaf ### The installer, and what it is waiting on ```bash -curl -fsSL https://agentfield.ai/get/codeaf | bash # the preferred form -curl -fsSL https://raw.githubusercontent.com/Agent-Field/codeaf/main/scripts/install.sh | bash # the script under it +curl -fsSL https://raw.githubusercontent.com/Agent-Field/codeaf/main/scripts/install.sh | bash # works once public and on main +curl -fsSL https://agentfield.ai/get/codeaf | bash # supported once it serves ``` -The first is the road that will be supported, and it is not serving yet — the route is -written and unmerged. The second answers 404 to anyone not signed in, and starts working -when the repository is public and `scripts/install.sh` has reached `main`. +While the repository is private, the raw GitHub address answers 404 to anyone not signed +in; once it is public and `scripts/install.sh` is on `main`, that road works. The proxied +address is not serving yet and will be the supported form once it serves.
Installer channels, flags, and checks -The repository currently has no rc or staging publication. Those channel selections -therefore stop with `no build has been published yet`. Recognizing a channel -does not mean a matching release exists. +A push to `dev` publishes a `dev-*` build, a push to `staging` publishes a `staging-*` +build, and a push to `main` publishes an rc; all three are marked as prereleases. Stable +exists only when a person dispatches `Release` on `main`. A channel with nothing +published stops with `no build has been published yet`, and because `--stable` +is the default and reads GitHub's `releases/latest`, which excludes prereleases, the bare +curl line says `no stable build has been published yet` until that stable dispatch lands. ```bash -curl -fsSL https://agentfield.ai/get/codeaf/dev | bash -curl -fsSL https://agentfield.ai/get/codeaf/staging | bash -curl -fsSL https://agentfield.ai/get/codeaf/rc | bash +curl -fsSL https://raw.githubusercontent.com/Agent-Field/codeaf/main/scripts/install.sh | bash -s -- --dev +curl -fsSL https://raw.githubusercontent.com/Agent-Field/codeaf/main/scripts/install.sh | VERSION= bash +curl -fsSL https://agentfield.ai/get/codeaf/dev | bash # once the proxy serves, /dev, /staging and /rc pick a channel curl -fsSL https://agentfield.ai/get/codeaf | VERSION= bash ``` @@ -326,6 +329,15 @@ language to reach an answering page. - `codeaf exec [""]` runs one worker for one pass, with no planning. - `codeaf run --input ` runs one saved typed program and writes typed output to stdout. +When `codeaf do` starts local workers, no rtk is resolvable, and `CODEAF_RTK` is unset, +it begins a background fetch of the pinned third-party rtk executable from +`github.com/rtk-ai/rtk` on the four supported macOS and Linux architectures, to compress +eligible shell output before the model reads it. Nothing waits for the fetch: the whole +attempt has two minutes, each downloaded response is capped at 64 MB, its sha256 must +match the published checksums, and calls to rtk have telemetry switched off. It installs +at `$CODEAF_HOME/bin/rtk`, or `~/.codeaf/bin/rtk` when that variable is unset or empty; +set `CODEAF_RTK=off` to refuse it, or set `CODEAF_RTK` to the path of your own executable. + None takes `--yolo`, and all three end the same way — `--json` carries the reason in its `stop` field. diff --git a/docs/changes/unreleased/1050-release-day-truth.md b/docs/changes/unreleased/1050-release-day-truth.md new file mode 100644 index 0000000000..921bd440ef --- /dev/null +++ b/docs/changes/unreleased/1050-release-day-truth.md @@ -0,0 +1,12 @@ +--- +kind: changed +title: The install story, the compiled-in manual and the branch rules say what is true on release day +pr: 1050 +surface: [docs, build] +invalidates: + - "The README said the repository has no rc or staging publication, so those channel selections stop with `no build has been published yet`. A push to `dev`, `staging` or `main` now publishes that channel, all of them marked prereleases; only the bare curl line still stops, because `--stable` is the default and reads `releases/latest`, which excludes prereleases, until a person dispatches `Release` on `main`." + - "The README and `internal/manual/chat/running-from-the-terminal.md` both said the repository is private today and the raw installer URL answers 404. Both now state that as a condition rather than a date — 404 while the repository is private, working once it is public with `scripts/install.sh` on `main` — so neither sentence goes stale when the repository flips." + - "`https://agentfield.ai/get/codeaf` was the first line of the README's install block and was labelled the preferred form. It still is not serving, so the raw GitHub road goes first and the proxied address is described as the form that will be supported once it serves." + - "Nothing in the README or the chat manual said that codeaf downloads a third party's executable. `codeaf do` fetches the pinned rtk v0.45.0 from `github.com/rtk-ai/rtk` in the background when none is resolvable and `CODEAF_RTK` is unset, and both surfaces now say so with its bounds: two minutes, 64 MB per response, sha256 against the published checksums, four platform pairs, `$CODEAF_HOME/bin/rtk`, and `RTK_TELEMETRY_DISABLED=1` on every call. `CODEAF_RTK=off` refuses it." + - "`.github/rulesets/README.md`, `docs/rules/ci.md` and `CLAUDE.md` said branch rules are unavailable until the org moves to GitHub Team. GitHub Free enforces rulesets on public repositories, so the condition is GitHub Team or a public repository, and the two checked-in rulesets are applied the day this one goes public." +--- diff --git a/docs/rules/ci.md b/docs/rules/ci.md index cedd6c0455..2be1166f10 100644 --- a/docs/rules/ci.md +++ b/docs/rules/ci.md @@ -220,10 +220,11 @@ adding their job names to `required_status_checks` in `.github/rulesets/promotion-pointers.json` as soon as each has been green twice in a row.** That is the next piece of work here, not a someday. -## None of it is enforced yet - -`Agent-Field` is on the free plan with a private repository, and that combination -has no branch rules — the API answers `403 Upgrade to GitHub Pro`. The checks -above run and show red, but nothing stops a merge on top of red, and nothing -stops a direct push. **Until the org moves to GitHub Team, all of this is -convention.** `.github/rulesets/README.md` has the state of that. +## When GitHub enforces it + +While `Agent-Field` is on the free plan and the repository is private, that +combination has no branch rules — the API answers `403 Upgrade to GitHub Pro`; +the checks above run and show red, but nothing stops a merge on top of red, and +nothing stops a direct push. **Until the org moves to GitHub Team or the +repository is public, all of this is convention.** `.github/rulesets/README.md` +has the state of that. diff --git a/internal/manual/chat/running-from-the-terminal.md b/internal/manual/chat/running-from-the-terminal.md index fb950446fe..cb6bc70c71 100644 --- a/internal/manual/chat/running-from-the-terminal.md +++ b/internal/manual/chat/running-from-the-terminal.md @@ -2,35 +2,65 @@ ## How do I install or update codeaf to the latest version — the curl line, dev, staging, rc and stable -Today, clone the repository and run `make build`. It writes `bin/codeaf`; run that -binary from the checkout. - -The curl installer exists at `scripts/install.sh` and installs into -`~/.codeaf/bin/codeaf`, but the repository is private today, so the published URL -answers 404 to anyone who is not signed in. When the repository is public, the -line to use is: +Build from source needs nothing published: clone the repository, run `make build`, +then run `bin/codeaf` from the checkout. While the repository is private, both the +clone and the raw installer need repository access and the raw address answers 404 +to anyone who is not signed in. Once it is public and `scripts/install.sh` is on +`main`, this road works: ```sh -curl -fsSL https://agentfield.ai/get/codeaf | bash +curl -fsSL https://raw.githubusercontent.com/Agent-Field/codeaf/main/scripts/install.sh | bash ``` -Add `/dev`, `/staging` or `/rc` to that URL for another channel. To pin one -complete tag, replace the final pipe with `| VERSION= bash`; for example: - -```sh -curl -fsSL https://agentfield.ai/get/codeaf | VERSION=v0.3.0 bash -``` +A push to `dev` publishes a `dev-*` build, a push to `staging` publishes a +`staging-*` build, and a push to `main` publishes an rc. Each is marked as a +prerelease. Stable is published only when a person dispatches `Release` on `main`. +A channel with nothing published stops with `no build has been published +yet`. -That address is a proxy for the script kept here, and it is not serving yet -either. The script itself is: +Once the script can be read, `--stable` is the default and reads GitHub's +`releases/latest`, which excludes prereleases. The bare curl line therefore stops +with `no stable build has been published yet` until a person dispatches `Release` +on `main` for stable. Pass `--dev`, `--staging`, or `--rc` after `bash -s --` for +another channel. To pin one complete tag, replace the final pipe with +`| VERSION= bash`; for example: ```sh -curl -fsSL https://raw.githubusercontent.com/Agent-Field/codeaf/main/scripts/install.sh | bash -``` - -The installer's last line is `codeaf version`; it shows the tag installed, when it -was built, and the Go and operating-system target. Nothing self-updates: run the -installer again when you want a newer build. +curl -fsSL https://raw.githubusercontent.com/Agent-Field/codeaf/main/scripts/install.sh | VERSION=v0.3.0 bash +``` + +`https://agentfield.ai/get/codeaf` is not serving yet. Once it serves, it is the +supported proxy for the same script, with `/dev`, `/staging`, or `/rc` selecting +another channel. The installer writes `~/.codeaf/bin/codeaf`; its last line is +`codeaf version`. Nothing self-updates: run it again when you want a newer build. + +## Why codeaf do may download rtk — compressed shell output and how to turn it off + +When `codeaf do` starts local workers, it starts one background attempt to find or +fetch rtk v0.45.0. rtk is a third party's program from `github.com/rtk-ai/rtk`; it +compresses the output of its named read and check filters before the work model pays +to read it. Anything that writes runs plain, and a wrapped result codeaf cannot trust +is run again without rtk. + +If no rtk is already resolvable and `CODEAF_RTK` is unset, codeaf downloads +`rtk-.tar.gz` and `checksums.txt` from that repository's release. The whole +fetch has two minutes and every downloaded response is capped at 64 MB. Its sha256 +must match the published checksums; a mismatch or missing entry is refused. The +managed fetch supports only macOS arm64, macOS amd64, Linux amd64, and Linux arm64; +on any other platform it fetches nothing. A copy you name or put on `PATH` can still +be used there. + +The archive contributes only its file named `rtk`. It is installed atomically with +mode `0700` at `$CODEAF_HOME/bin/rtk`, or `~/.codeaf/bin/rtk` when `CODEAF_HOME` is +unset or empty. Nothing waits for it: commands run plain until it lands. Success logs +once per process as `note: installed rtk v0.45.0 for compressed shell output`; failure +logs once as `note: shell output will not be compressed — `. + +`CODEAF_RTK=off` disables rtk everywhere. Set `CODEAF_RTK` to an executable path to +use your own; naming a path that is not executable also prevents fallback and fetch. +Without that variable, codeaf looks for `rtk` on `PATH`, then its managed copy. Calls +to rtk carry `RTK_TELEMETRY_DISABLED=1` and `RTK_NO_TOML=1`: codeaf does not opt you +into a third party's collection. ## Running codeaf from the terminal — can I run this without the chat