chore: tell the truth about what installs today, and clear scratch out of the repo root

[AetherAI3]

The defect

Two things, both about what this repository tells the public.

1. The install instructions do not give you the software they describe

The README's very first code block — and install.sh's default AETHER_VERSION=latest — resolve to 0.1.0:

$ npm view aether-agents dist-tags versions --json
{ "dist-tags": { "latest": "0.1.0" }, "versions": [ "0.1.0" ] }

main has been at 0.2.0 since 2026-08-19. So every feature documented under v0.2.0 — portable handoffs, --resume reaching the brain, aether agent --local "<task>" working straight after an install instead of dying on spawn python ENOENT — is unreachable to anyone who installs the way the README says. They install 0.1.0, read release notes describing 0.2.0, and have no way to tell which one they have.

Supporting facts, all checked rather than assumed:

• Repository tags are only v0.1.0 and frozen-seam-v1 (git ls-remote --tags). There is no v0.2.0.
• gh release list is empty. No GitHub release has ever been created, which means release.yml — the entire publish rail — has never fired once.
• RELEASE_NOTES.md, linked from the README's badge, led with August 14, 2026 while the v0.2.0 / August 19 entry sat below it. The content was present but mis-ordered, so the file read as though it stopped a release early.
• install.sh told users to AETHER_VERSION=0.2.0 to "pin an exact release". That version is not on the registry, so anyone following that comment gets No matching version found — the installer only offered EACCES advice in response.

2. The root listing — the storefront of a public repo — shipped scratch

aether-agents-0.2.0.tgz (576 KB, a committed npm tarball of the version that was never published), a stray commands.jsx (21 KB) that no build references, and _loopstate/** (87 files of internal agent-run audit dumps) sat in the root. .gitignore covered dist/, _tmp/ and .hermes/, and none of these.

This is repo hygiene, not a package defect, and I want to be precise about that: none of it ever reached npm. package.json's files allowlist is dist/src plus four docs, and scripts/verify-production.ts enforces it. The cost is to an outside contributor reading the root listing, not to anyone installing the package.

Separately, src/generated/agent_capabilities.ts told contributors to regenerate it with node scratchpad gen_fallback.mjs and pointed at "docs/releases/skills-health notes". Neither exists anywhere in the tree — so a generated file was effectively unregenerable by anyone outside the original author's machine.

⚠️ Owner gate — publishing 0.2.0 is NOT in this PR

This PR makes the docs honest about the gap. It cannot close the gap. Cutting the 0.2.0 release is owner-gated: gh secret list shows zero repo secrets, and the only environment that exists is github-pages. The following require repository-owner credentials and remain outstanding after this merges:

1. Create the npm-production environment.
2. Add an NPM_TOKEN secret with publish rights to aether-agents.
3. Tag v0.2.0 and cut the GitHub release that triggers release.yml.
4. Confirm the registry's latest dist-tag moves to 0.2.0.

Everything up to that credential gate is green and was verified on this branch:

$ npm ci && npm run build
copied 18 built-in skill assets -> dist/src/skills/builtin

$ node dist/scripts/verify-production.js
{"ok":true,"package":"aether-agents","version":"0.2.0","packedFiles":524,"packedBytes":2410189,"workflows":3}

When 0.2.0 is actually published, the honesty notes this PR adds should be removed — the README block, and the Availability paragraph in the v0.2.0 release-notes entry. They are deliberately worded to be easy to find and delete.

What changed

README.md — a short block under the beta line states that npm i -g gives you 0.1.0 today, names the 0.2.0 features that are therefore absent, and gives the build-from-source path. The installer paragraph no longer advertises pinning to an unpublished version, and says what pinning to one does.

RELEASE_NOTES.md — the v0.2.0 / August 19 entry is moved above the August 14 entry, so the log is newest-first throughout. Its closing "Upgrade with npm i -g aether-agents" (which today upgrades you to nothing) is replaced by an Availability paragraph stating that 0.2.0 is on main but not on npm, with the source build, and what will be true once it is published. No release-note prose was rewritten.

install.sh — the pin comment says published release and uses a published example. A failed pinned install now explains No matching version found, points at npm view aether-agents versions, and mentions the source build, before the existing EACCES advice.

.gitignore — adds *.tgz, so npm pack output cannot be committed again.

Deleted:

• aether-agents-0.2.0.tgz — 576 KB npm tarball of the unpublished version. Nothing references it.
• commands.jsx — 504 lines of browser React (/* global React, ReactDOM, ... */, JSX, navigator.clipboard) for a marketing command-card UI. No bundler, no build step, no test, and no config references it, and the package has no React dependency. grep -rn "commands.jsx" across the repo returns nothing.

Moved, not deleted — _loopstate/ → docs/loops/ (87 files): these are internal agent-run audit dumps, and I read them before touching them. They are governance-ledger.md (a verdict table: run id, retries, debate rounds, tool-success %, hallucinations caught, confidence) plus six loop directories:

Directory	Contents
LOOP-01/sc-a0-2026-08-19	Skills/health integration semantic-conflict matrix, verdict BLOCKED-PENDING-IMPLEMENTATION
LOOP-07/2026-07-20T13-53-25-0400	Hosted-CI repair, topology drift, 9 node JSONs, trace
LOOP-11/2026-07-20T14-04-43-0400	Critique/revision/score debate rounds, verdict
LOOP-12/2026-07-20T14-12-13-0400	Chaos grade matrix, coverage-gap map, mutation report, 9 node JSONs
LOOP-13/2026-07-20T14-19-07-0400	Complexity/delta/duplication reports, structural drift, scorecard, debt trend
LOOP-17/2026-07-20T13-58-39-0400	8 breaker rounds, 3 builder rounds, 8 convergence rounds, human report, queue

I did not delete them, because docs/specs/2026-07-20-devops-production-hardening-design.md:59 cites them by path as that spec's evidence trail — deleting them would have silently broken a documented audit trail in a public repo. Moving them under docs/ keeps the trail intact and takes the scratch out of the root listing. All 87 are staged as renames (git status shows R, zero content change), and the citing spec's path reference is updated in the same commit.

src/generated/agent_capabilities.ts — header comment only. The phantom gen_fallback.mjs line is replaced with the actual four-step procedure, including the canonical digest recipe: sha256 over the JSON with object keys sorted recursively and no whitespace. I verified that recipe reproduces the declared digest rather than describing it from the variable name:

computed: 8da094234a370a28dfd6206f039425f086307aa9ca0a67bc004d3d453716ac04
declared: 8da094234a370a28dfd6206f039425f086307aa9ca0a67bc004d3d453716ac04
match: true

What I deliberately did not touch

• The model fleet table (README.md, Models & pricing). A scout note flagged it as possibly stale on the grounds that "Claude Opus 4.8" corresponds to no real Claude family. That reasoning is wrong — Opus 4.8 is real — and I did not act on it. More importantly, the table describes AETHER-CLOUD's hosted fleet, which cannot be queried from here without credentials. Editing it on a guess would make the README less accurate, not more. It still needs a cross-check against the live GET /models catalog by someone with credentials; that is a genuine open item, just not one that can be closed from an unauthenticated checkout.
• Publishing anything. See the owner gate above. No tag was created, no release cut, no version bumped.
• src/core/tool_executor.ts, src/core/git_commit_guard.ts, src/core/brain_cloud.ts, src/commands/** — a sibling lane owns those.
• scripts/verify-production.ts — its pack guard regex still names _loopstate rather than docs/loops. Harmless (the files allowlist already excludes both, and the stale name still guards against the directory reappearing at the root), but worth a one-line follow-up by whoever owns that script. Out of this lane.

Test evidence

$ npm ci && npm run build
copied 18 built-in skill assets -> dist/src/skills/builtin

$ node --test --test-isolation=none "dist/test/**/*.test.js"
# tests 1117 | pass 1116 | fail 0 | skipped 1 | duration_ms 198415

$ node dist/scripts/verify-production.js
{"ok":true,"package":"aether-agents","version":"0.2.0","packedFiles":524,"packedBytes":2410189,"workflows":3}

The suite was run with TEMP/TMP/TMPDIR pointed at a directory outside any git repository, because the worktree tests otherwise interact badly with a temp directory inside a checkout on this machine. Environment workaround, no test changes.

packedBytes is 2410189 against a 2408615 baseline: +1574 bytes, which is the expanded regeneration comment in src/generated/agent_capabilities.ts, since dist/src is inside the packed allowlist and tsc preserves comments. packedFiles is unchanged at 524 — no file entered or left the tarball.

Blast radius

No behavior change of any kind. Documentation prose, one shell comment plus one extra shell error-hint branch that runs only on an already-failed install, a .gitignore line, one TypeScript comment, and file moves/deletions of assets that nothing in the build, tests, or package references. verify-production reports the same 524 packed files before and after, and the full suite is green. The _loopstate move is the only change touching many paths, and every one of them is a pure rename.