docs: correct the README behavior list and lead with the summon boundary

coilyco-ops commented

2026-08-25 07:52:15 +00:00

Owner

Kai read the README behavior list and said half of it was wrong or irrelevant. Audited every line against docs/FEATURES.md and docs/sirens-echo-admission.md. She was right.

What was wrong

"Per-user, per-guild, and global limits bound spend" - wrong twice. The limits are rate and concurrency, not cost. SIRENS_ECHO_RATE_USER 3/30s, SIRENS_ECHO_RATE_CONTEXT 10/10s, SIRENS_ECHO_RATE_GLOBAL 20/5s, over eight execution slots with a bounded queue behind them. Neither "spend" nor "cost" appears anywhere in FEATURES.md, and the only uses of "budget" there are a history budget and a send budget, neither of which is money. Also per-context, not per-guild.
"Twelve earlier messages give continuity" - stale. FEATURES.md describes a definition-selected history budget, so the number is configuration rather than a constant.
"Unanswered questions and corrections become sanitized Forgejo issues" - not in FEATURES.md. What exists is a canonical link appended for every issue a turn observed or filed, built only from returned tool results.
"The action surface stays repository-scoped, with no moderation or roles" - half right. FEATURES.md states no assumed domain, MCP, automatic issue tracking, or default write surface.

The spend claim had already reached the resume. Corrected in coilysiren/website#127.

What changed

Six checked bullets replace ten, under a new ## Behavior heading. The two worth keeping regardless of length are "No Forgejo token in the Echo pod" and the gateway heartbeat that counts observed, admitted, and replied so a quiet guild and a stopped ingress differ. Both concrete, neither a thing most projects can say.

The opening also changes shape, aligning with the other three showcase repositories:

Banner and claim swap into standard order, claim first.
## About is dropped. The opening needs no heading.
The summon boundary is promoted out of a bullet into a bolded invariant, because a reader assumes by default that a bot sitting in a channel is reading the channel, and that assumption matters to anyone deciding whether to add it to their community.

Scope

README.md only. No code, no configuration, no behavior change.

Checks

Full pre-commit suite passes, including documentation-layout, catalog-trifecta, dead-cross-links, and typos.

Part of coilysiren/inbox#422, which aligns all four showcase README openings to one shape.

Kai read the README behavior list and said half of it was wrong or irrelevant. Audited every line against `docs/FEATURES.md` and `docs/sirens-echo-admission.md`. She was right. ## What was wrong - **"Per-user, per-guild, and global limits bound spend"** - wrong twice. The limits are rate and concurrency, not cost. `SIRENS_ECHO_RATE_USER` `3/30s`, `SIRENS_ECHO_RATE_CONTEXT` `10/10s`, `SIRENS_ECHO_RATE_GLOBAL` `20/5s`, over eight execution slots with a bounded queue behind them. Neither "spend" nor "cost" appears anywhere in `FEATURES.md`, and the only uses of "budget" there are a history budget and a send budget, neither of which is money. Also per-context, not per-guild. - **"Twelve earlier messages give continuity"** - stale. `FEATURES.md` describes a definition-selected history budget, so the number is configuration rather than a constant. - **"Unanswered questions and corrections become sanitized Forgejo issues"** - not in `FEATURES.md`. What exists is a canonical link appended for every issue a turn observed or filed, built only from returned tool results. - **"The action surface stays repository-scoped, with no moderation or roles"** - half right. `FEATURES.md` states no assumed domain, MCP, automatic issue tracking, or default write surface. **The spend claim had already reached the resume.** Corrected in `coilysiren/website#127`. ## What changed Six checked bullets replace ten, under a new `## Behavior` heading. The two worth keeping regardless of length are "No Forgejo token in the Echo pod" and the gateway heartbeat that counts observed, admitted, and replied **so a quiet guild and a stopped ingress differ**. Both concrete, neither a thing most projects can say. The opening also changes shape, aligning with the other three showcase repositories: - Banner and claim swap into standard order, claim first. - `## About` is dropped. The opening needs no heading. - The summon boundary is promoted out of a bullet into a bolded invariant, because a reader assumes by default that a bot sitting in a channel is reading the channel, and that assumption matters to anyone deciding whether to add it to their community. ## Scope `README.md` only. No code, no configuration, no behavior change. ## Checks Full `pre-commit` suite passes, including `documentation-layout`, `catalog-trifecta`, `dead-cross-links`, and `typos`. Part of `coilysiren/inbox#422`, which aligns all four showcase README openings to one shape.

coilyco-ops added 1 commit

2026-08-25 07:52:15 +00:00

docs: correct the README behavior list and lead with the summon boundary

ci / test (pull_request) Failing after 1m11s

Details

ci / publish-echo-image (pull_request) Has been skipped

Details

ci / publish-observed (pull_request) Has been skipped

Details

ci / image-build (pull_request) Failing after 48s

Details

76f476553d

Kai read this list and said half of it was wrong or irrelevant. Audited every
line against docs/FEATURES.md and docs/sirens-echo-admission.md. She was right.

- "Per-user, per-guild, and global limits bound spend" was wrong twice. The
  limits are rate and concurrency, not cost: RATE_USER 3/30s, RATE_CONTEXT
  10/10s, RATE_GLOBAL 20/5s, over eight execution slots with a bounded queue.
  Neither "spend" nor "cost" appears anywhere in FEATURES.md. That same wrong
  claim had already reached the resume and is corrected in
  coilysiren/website#127.
- "Twelve earlier messages" was stale. The history budget is
  definition-selected, so the number is configuration rather than a constant.
- "Unanswered questions and corrections become sanitized Forgejo issues" is not
  in FEATURES.md. What exists is a canonical link appended for every issue a
  turn observed or filed, built only from returned tool results.
- The action-surface line half-matched what FEATURES.md actually states.

Six checked bullets replace ten, and the opening changes shape: the banner and
claim swap into the order the other three showcase repositories use, ## About
goes, and the summon boundary is promoted out of a bullet into the invariant,
because a reader assumes by default that a bot in a channel is reading the
channel, and that assumption matters to anyone deciding whether to add it.

Ref: coilysiren/inbox#422

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Agent-Role: devrel

coilyco-ops commented

2026-08-25 07:58:35 +00:00

Author

Owner

Not merging. Blocked by a pre-existing red main, not by this change.

This repository runs pull-request-and-merge, so I would normally merge this myself once green. It is not green, and the failure is not mine.

What failed

test (job 42727) and image-build (job 42728) on run 26422. The Go tests passed. The failure is at the compose staging step:

2026/08/25 07:53:17 role "engineer": pattern "tooling-ops-*" matches nothing in /tmp/.../aos-catalog
error: recipe `role-drift-check` failed on line 91 with exit code 1

image-build fails from the same root, with scripts/stage-compose-sources.sh returning 1.

Why it is not this change

This branch's diff is README.md only, 23 insertions and 13 deletions. git diff --name-only main...HEAD returns one file.
composed-skill "tooling-ops-*" sits at agent/compose/roles.kdl:35 on main, untouched by this branch.
Running just role-drift-check against detached main locally fails with exit 1 on the same recipe at the same line, with nothing of mine in the tree. It reports a different symptom there, a changed role selection rather than the missing pattern, because a local aos-catalog checkout is not the fresh clone CI takes. Same recipe, same branch, no involvement from this PR either way.

So main is red and every pull request against this repository is blocked behind it, this one included.

Where it belongs

This is the live consequence of #1147, filed 2026-08-23: roles.kdl names engineer and creator, and agent-compose reflowed its Core Roster to seven bonded seats in 12c7198, so neither role exists any more. tooling-ops-* is one of the engineer block's patterns. Confirmed against the current agentic-os catalog, which ships thirteen tooling-* skills and no tooling-ops-* family at all.

That issue predicted the cost as every core role composing bare once the image caught up. The observed cost is higher than predicted: the drift check hard-fails, so the build stops rather than quietly producing empty bundles. Recording that on #1147 rather than duplicating it here.

What I am doing

Leaving this open and unmerged. The content is reviewed and approved by Kai, the full pre-commit suite passes including documentation-layout, catalog-trifecta, dead-cross-links and typos, and it merges as soon as main is green.

Fixing roles.kdl is not mine to do. A composed-skill pattern is a data contract rather than content, which the Developer Advocate charter excludes.

## Not merging. Blocked by a pre-existing red main, not by this change. This repository runs `pull-request-and-merge`, so I would normally merge this myself once green. It is not green, and the failure is not mine. ## What failed `test` (job 42727) and `image-build` (job 42728) on run 26422. The Go tests passed. The failure is at the compose staging step: ``` 2026/08/25 07:53:17 role "engineer": pattern "tooling-ops-*" matches nothing in /tmp/.../aos-catalog error: recipe `role-drift-check` failed on line 91 with exit code 1 ``` `image-build` fails from the same root, with `scripts/stage-compose-sources.sh` returning 1. ## Why it is not this change * This branch's diff is **`README.md` only**, 23 insertions and 13 deletions. `git diff --name-only main...HEAD` returns one file. * `composed-skill "tooling-ops-*"` sits at `agent/compose/roles.kdl:35` **on `main`**, untouched by this branch. * Running `just role-drift-check` against detached `main` locally fails with exit 1 on the same recipe at the same line, with nothing of mine in the tree. It reports a different symptom there, a changed role selection rather than the missing pattern, because a local `aos-catalog` checkout is not the fresh clone CI takes. Same recipe, same branch, no involvement from this PR either way. So `main` is red and every pull request against this repository is blocked behind it, this one included. ## Where it belongs This is the live consequence of **#1147**, filed 2026-08-23: `roles.kdl` names `engineer` and `creator`, and agent-compose reflowed its Core Roster to seven bonded seats in `12c7198`, so neither role exists any more. `tooling-ops-*` is one of the `engineer` block's patterns. Confirmed against the current agentic-os catalog, which ships thirteen `tooling-*` skills and no `tooling-ops-*` family at all. That issue predicted the cost as every core role composing bare once the image caught up. The observed cost is higher than predicted: the drift check hard-fails, so the build stops rather than quietly producing empty bundles. Recording that on #1147 rather than duplicating it here. ## What I am doing Leaving this open and unmerged. The content is reviewed and approved by Kai, the full `pre-commit` suite passes including `documentation-layout`, `catalog-trifecta`, `dead-cross-links` and `typos`, and it merges as soon as `main` is green. Fixing `roles.kdl` is not mine to do. A `composed-skill` pattern is a data contract rather than content, which the Developer Advocate charter excludes.

coilyco-ops referenced this pull request

2026-08-25 08:38:24 +00:00

Both roles.kdl entries name roles the reflowed roster no longer has, so every core role will compose bare when the image catches up #1147

coilyco-ops referenced this pull request

2026-08-25 08:47:20 +00:00

fix(compose): follow the composed-source renames the roster reflow made #1151

coilyco-ops referenced this pull request

2026-08-25 10:58:26 +00:00

fix(compose): follow the composed-source renames the roster reflow made #1151

coilyco-ops referenced this pull request

2026-08-25 14:26:40 +00:00

fix(compose): follow the composed-source renames the roster reflow made #1151