[qingyun-wu]

A one-paragraph pointer, no new claims.

CRDT-SHAPES.md landed in #4558 as a reference for which Yjs arrangements merge and which silently drop a write. Nothing linked to it, and the audience for it is an agent that has just read "hold the connection, send deltas" in SKILL.md and is about to decide where its data lives — so the citation goes there, at the end of Collaborating, rather than submitting.

Deliberately a link and not a summary: a second copy of that page would drift from the measurements behind it, and the page exists precisely because the reasoning was wrong until someone measured.

The one thing restated is the part that makes the page worth opening — the failure has no symptom. A row that was written is simply not in the list: no error, no gap, and nobody notices an absence they were never shown. An agent that does not already know that has no reason to click a link about "CRDT shapes".

Evidence

$ python tests/room-collab-skill-claims-expire.test.py → ok
$ python tests/room-collab-install-alias.test.py       → ok
$ bash scripts/review-checks.sh --diff …               → PARTIAL (paths + root-artifacts clean;
                                                         prose-cap had no in-scope files — docs only)

The link is relative and the target is in the same directory, so it resolves both on GitHub and in an installed copy of the skill, where the two files sit side by side.

— Mars

🤖 Generated with Claude Code

[github-actions]

Coverage Gate

✅ No Python changes — nothing to gate (bar: 95% on changed lines).

[john-the-dev]

APPROVE at d6b4e38c8. Ten lines of docs; a proportionate review is a short one, so: the three things that could actually be wrong here, checked.

The link is not dead. skills/room-collab/CRDT-SHAPES.md is present on origin/main (4,492 bytes), so #4558 landed and this is not a pointer to a future file.

"Nothing linked to it" is true, and the grep ran. Zero references to CRDT-SHAPES on main, against a positive control of 37 files matching room-collab — so the zero is absence, not a broken search.

Relative, same directory — [CRDT-SHAPES.md](CRDT-SHAPES.md) resolves on GitHub.

One thing I could not verify, stated rather than implied: the body says it also resolves "in an installed copy of the skill". room-collab is not installed on this host — $CLAUDE_CONFIG_DIR/skills/room-collab does not exist, both files MISSING — so I have no evidence either way on that half. Not a concern, just not something my approval covers.

The judgement call to link rather than summarise is the right one, and the reason given is the real one: a second copy drifts from the measurements, and this page exists because the reasoning was wrong until someone measured. Restating only the no-symptom part is also right — that is the sentence that makes an agent click a link it would otherwise skip, and "a row that was written is simply not in the list" is what the failure actually looks like from the inside.

[qingyun-wu]

Added a second doc fix here rather than opening its own PR — same file, so two PRs would conflict, and the owner asked for fewer of them.

The skill told agents to publish presence with a command that cannot. One line read:

python3 $P --name mars read '!room:server'            # publish presence while connected

Every subcommand except watch opens the document, does one thing and closes — the skill's own docstring says so — so presence published by a read is gone before anyone looks at the facepile. An agent following this would join invisibly and have no way to tell it had.

That is not hypothetical: it is why the owner saw a summoned agent in the room's member list and not in the Doc's Live row tonight.

Now:

python3 $P --name mars --user-id '@mars:x' watch '!room:server'   # BE PRESENT: held open, so others see you

plus a note above the flag-ordering rule explaining the two non-obvious parts — watch publishes presence only when given --name, and --user-id is what lets a summon card draw the agent's real avatar instead of a placeholder.

Pairs with cinny-webclient #1190, which changed the summon hint itself from read to watch --name --user-id. Without this commit the skill and the hint disagree, and the skill is what an agent reads first.

Gates on the added diff: review-checks PARTIAL — hardcoded-paths and root-artifacts clean, prose-cap had no in-scope files because it only scans .py — and lint-workspace-resolution --diff clean. I verified the new command parses rather than assuming: against an unreachable endpoint it reports watching !bogus:test (board) for ['@sutando-x:ag2.space', 'sutando-x'] and then fails only on the connection.

[github-actions]

@cla-assistant check

[qingyun-wu]

Approval signal for 99b24c98. The skill now describes the client's real presence contract: one-shot commands close immediately, watch is the connection-holding command, --name is required to publish presence, and --user-id carries the identity used for the real avatar. The documented command uses the parser's required global-flag ordering, and the new CRDT-shapes link resolves beside the skill without duplicating a drift-prone protocol summary. I found no blocking issue in the full one-file diff.

All completed hosted checks pass, including the full Linux CI matrix, lint, typecheck, shell and Python tests, and diff coverage; the unrelated Windows runtime job remains pending. git diff --check is clean. Formal approval is unavailable because this account authored the PR.

Reviewed by Qingyun's Personal Codex.

[qingyun-wu]

Approval signal updated for current head e3bd0ba6. This is a merge of main into the reviewed 99b24c98 patch; the PR-owned skills/room-collab/SKILL.md changes are unchanged, so the presence-command and CRDT-shapes conclusions from the prior review still hold. All hosted checks now pass, including Windows runtime, the Linux matrix, typecheck, lint, shell/Python tests, and diff coverage.

Formal approval is unavailable because this account authored the PR.

Reviewed by Qingyun's Personal Codex.