docs: dedupe the See-also block and group it by what a reader wants

coilyco-ops commented

2026-08-24 01:29:50 +00:00

Owner

The See-also block carried twenty-odd links with five doubled: jobs, identity, deploy, compose, and access each appeared twice. Configuration linked the tuning doc three times in one paragraph, once as "tuning" and once as "tuning a deployment", which are the same page.

Regrouped into start here, what bounds it, and how it runs.

Also surfaced three security-adjacent docs that were never linked from the README: untrusted-input (links out, files in, and the values a reply may never echo), the content gate, and grounding. For a service that feeds Discord text to a model and files issues from it, those belong on the front door.

pre-commit run --all-files passes clean.

Part of a cross-repo README pass, parent audit coilysiren/inbox#397.

The See-also block carried twenty-odd links with five doubled: jobs, identity, deploy, compose, and access each appeared twice. Configuration linked the tuning doc three times in one paragraph, once as "tuning" and once as "tuning a deployment", which are the same page. Regrouped into start here, what bounds it, and how it runs. Also surfaced three security-adjacent docs that were never linked from the README: `untrusted-input` (links out, files in, and the values a reply may never echo), the content gate, and grounding. For a service that feeds Discord text to a model and files issues from it, those belong on the front door. `pre-commit run --all-files` passes clean. Part of a cross-repo README pass, parent audit `coilysiren/inbox#397`.

coilyco-ops added 1 commit

2026-08-24 01:29:50 +00:00

docs: dedupe the See-also block and group it by what a reader wants

ci / test (pull_request) Failing after 1m2s

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 39s

Details

c81082151a

The block carried twenty-odd links with five doubled: jobs, identity, deploy,
compose, and access each appeared twice. Configuration linked the tuning doc
three times in one paragraph, once as "tuning" and once as "tuning a
deployment", which are the same page.

Repeats read as generated litter and buried the four links that matter.
Regrouped into start here, what bounds it, and how it runs, and cut it to the
pages a reader actually opens first.

Surfaced three security-adjacent docs that were never linked: untrusted-input,
which covers links out, files in, and the values a reply may never echo,
the content gate, and grounding. For a service that feeds Discord text to a
model and files issues from it, those belong on the front door.

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-24 01:31:37 +00:00

Author

Owner

Not merging this. CI is red for a reason that is not this diff.

ci.yml run 25886 fails in role-drift-check:

stage-compose-sources: baking 8 roster roles
stage-compose-sources: baking 1 community roles from agent/compose/person
role "engineer": pattern "tooling-ops-*" matches nothing in /tmp/.../aos-catalog
error: recipe `role-drift-check` failed on line 91 with exit code 1

This diff changes one file, README.md, and touches no role graph, no compose source, and no catalog. It cannot move role-drift-check.

The check clones the aos catalog fresh at run time, so it measures upstream state rather than this branch. engineer is one of the two roles #1148 names as removed by agent-compose's Core Roster reflow in 12c7198, and #1148 says outright that a red build here is the intended alarm rather than a defect.

So this is the alarm firing, on the wrong PR. Leaving this open and unmerged rather than merging past a red gate or arguing the check should be weakened for a docs change.

Merge order: land the roles.kdl remapping tracked on #1147, then #1148, then this rebases and goes green on its own. If someone wants this sooner it is a clean cherry-pick, since the diff is one file.

## Not merging this. CI is red for a reason that is not this diff. `ci.yml` run 25886 fails in `role-drift-check`: ``` stage-compose-sources: baking 8 roster roles stage-compose-sources: baking 1 community roles from agent/compose/person role "engineer": pattern "tooling-ops-*" matches nothing in /tmp/.../aos-catalog error: recipe `role-drift-check` failed on line 91 with exit code 1 ``` This diff changes one file, `README.md`, and touches no role graph, no compose source, and no catalog. It cannot move `role-drift-check`. The check clones the aos catalog fresh at run time, so it measures upstream state rather than this branch. `engineer` is one of the two roles #1148 names as removed by agent-compose's Core Roster reflow in `12c7198`, and #1148 says outright that a red build here is the intended alarm rather than a defect. So this is the alarm firing, on the wrong PR. Leaving this open and unmerged rather than merging past a red gate or arguing the check should be weakened for a docs change. Merge order: land the `roles.kdl` remapping tracked on #1147, then #1148, then this rebases and goes green on its own. If someone wants this sooner it is a clean cherry-pick, since the diff is one file.

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