Filelayer AGENTS.md changelog

https://raw.githubusercontent.com/filelayer/filelayer/HEAD/AGENTS.md

− npm run verify && git push                  # everything else− `benchmark/gate4/RESULTS.md` searched for this project on 16 October 2026 and got− ## And verify BEFORE you push− npm run verify && git push− The `&&` only protects the step that comes after it. Put the irreversible one− last, always: this is the same shape as `npm run verify` ending in a stamp that− `prepublishOnly` refuses to publish without.− - `npm publish`, `npm deprecate`, or moving a dist-tag+ npm run verify                              # before a push, see below+ A search measurement run on 16 October 2026 looked for this project and got+ ## How a push happens+ A push is what makes a commit public, so it is the step a human approves. An+ agent working in this repository may push its own commits to `main`, and only+ this way:+ 1. `npm run verify` is green on the tree being pushed.+ 2. Refresh what the remote has, and show exactly what would go out, one line+    per commit saying what it changes publicly:+    ```+    git fetch https://github.com/filelayer/filelayer.git main:refs/remotes/origin/main+    git log --oneline origin/main..HEAD+    ```+    If any of those commits touches `.github/workflows/`, say so on its own+    line: `this push changes CI: <what>`. CI holds the live-storage secrets,+    and a workflow change is the one way a push could expose them. Without+    that line, no push.+ 3. Wait for the maintainer to write **ok push** for that list. No "ok push",+    no push. A new commit after the approval needs a new approval.+ 4. Push over HTTPS with the token in `.env.github-push` at the repository root+    (the token alone, ignored by git). It goes to git through a credential+    helper that reads the file, so it never appears in a URL, a command line,+    an environment listing or any output:+    ```+    git -c credential.helper= -c credential.helper='!f() { echo username=x-access-token; printf "password=%s\n" "$(tr -d "\r\n" < .env.github-push)"; }; f' push https://github.com/filelayer/filelayer.git HEAD:main+    ```+    Never print, copy, log, commit or move that file or any part of it. Not+    its first characters either: a prefix is part of the secret.+ Never force-push and never push another branch or repository. A rejected push+ stops the work and is reported, not retried another way.+ ### How a release happens+ A release is a tag, and the tag is what publishes. Show the maintainer the+ version, the CHANGELOG headline and the tarball's file count+ (`npm pack --dry-run` in `packages/core`), wait for **ok publish** for that+ version, then push the tag `vX.Y.Z` the same way as a commit:+ git tag -a vX.Y.Z -m "@filelayer/core X.Y.Z"+ git -c credential.helper= -c credential.helper='!f() { echo username=x-access-token; printf "password=%s\n" "$(tr -d "\r\n" < .env.github-push)"; }; f' push https://github.com/filelayer/filelayer.git refs/tags/vX.Y.Z+ `.github/workflows/publish.yml` refuses a tag that does not name the version in+ `packages/core/package.json` or does not point at a commit on `main`, runs both+ verification chains, and publishes with npm trusted publishing. Its

https://raw.githubusercontent.com/filelayer/filelayer/HEAD/AGENTS.md

− 2. **Some files exist twice and must be byte-identical.** The npm package ships−    its own copies of the README, the guides, `llms.txt` and others under−    `packages/core/`. `npm run check:copies` compares them. Change one, copy it−    to the other, in the same commit.− Five rules account for most review comments here, and they are worth+ ## Check the credential FIRST, not last -- but only when you are PUBLISHING+ ```+ npm whoami && npm run verify:release        # before a publish+ npm run verify && git push                  # everything else+ ```+ The first version of this section put `npm whoami` in front of every `verify`,+ and the first time that fired it blocked a `git push` -- which does not need an+ npm session at all. A guard that stops work it has no business stopping is a+ guard somebody deletes. The credential check belongs in front of the PUBLISH+ sequence and nowhere else; the read-only registry gates (`check:published`,+ `check:since`, `check:mcp-live`) need no session either.+ `npm whoami` costs a second. The npm session expired on two consecutive days in+ October 2026, and both times the only step in a release that fails on+ authentication is the IRREVERSIBLE one -- `npm publish` -- which arrives after+ six minutes of `verify` and two of `verify:release`. The second time it failed+ with `404 Not Found` on the PUT rather than a 401, because npm answers 404 to an+ unauthenticated publish so as not to reveal whether a package exists, which+ reads as "the package is gone" and is not.+ Put the cheap check that can fail in front of the expensive work, not behind it.+ ## A release note is read by strangers, so write its first paragraph for one+ `benchmark/gate4/RESULTS.md` searched for this project on 16 October 2026 and got+ ten results: the repository, and **nine release pages**. Not the website, which+ has eight pages, six rendered guides, a sitemap and JSON-LD and did not appear+ at all.+ So the release notes are the most-read documents this project has, and they are+ written as a changelog — for somebody who already knows what Filelayer is and+ wants to know what changed. The people and crawlers reading them do not know.+ **The first paragraph of a release note has to make sense cold.** One sentence+ on what the thing is, before the first sentence about what moved in it. The rest+ can stay exactly as it is: the defect, the reasoning, the measurement. That part+ is why anybody trusts the changelog.+ This is not an instruction to market in a changelog. It is an instruction to+ stop assuming context the reader does not have, which is the same rule the rest+ of this file applies to everything else.+ ## And verify BEFORE you push+ ```+ npm run verify && git push+ ```+ That order, not the other one. `git push && npm run verify` reads as a safe+ chain and is not one: it publishes first and objects afterwards, so a failing