Repository navigation
docs: rewrite guides, reference, and explanation in the README's style - #84
Conversation
Rewrite the six how-to guides in the README's style: lead with what the
reader needs, use short sentences and plain terms instead of internal
vocabulary ("dispatch spine", "slice", "single-slot"), and move limits and
edge cases after the main task.
- deferred-dispatch: options table, separate "How it works",
concurrency-strategy table, and an overload section with a response table.
- choose-a-state-backend: decision table first; namespace rules as bullets.
- slash-commands, interactive-components: plain intros; interactive limits
(modal clicks, view_submission) collected in one section.
- multi-tenant-install: headed subsections for bot user IDs and Linear's
unverified tenant lookup.
- linear-agent-sessions: numbered timing steps and a shorter stop section;
source-marked snippets unchanged.
Facts are unchanged, except the slash-command guide now says RespondURL
always sends ephemeral responses (it hardcodes response_type).
_Generated with [`xum`](https://github.com/coder/xum) • Model: `anthropic:claude-opus-5-5` • Thinking: `high`_
…ties - explanation: lead with the short version; group the intentional gaps by area (every item kept); move the CONTEXT.md and ADR index to the end. - reference: plainer intro and event wording; move the testing contract to CONTRIBUTING.md, where contributors look for it. - docs index: shorter section blurbs; "For Contributors" heading. - linear-agent-capabilities: linked Linear docs instead of bare URLs, ADR links, the setup workaround points at the example README instead of repeating it, and a one-line "Planned Work" section. _Generated with [`xum`](https://github.com/coder/xum) • Model: `anthropic:claude-opus-5-5` • Thinking: `high`_
- Slack tutorial Step 5: show ngrok and Tailscale Funnel as two parallel options, with the Funnel cleanup note after its commands. - Linear example README: a short intro with a numbered list of what the example does, linked ADRs, and plain wording in the notes. _Generated with [`xum`](https://github.com/coder/xum) • Model: `anthropic:claude-opus-5-5` • Thinking: `high`_
Restore facts the rewrite weakened: Linear completion signals are per-session, burst batches run in join order and in the order they close, the documentation-coverage test family names what it covers, slash commands share tenant scoping and replace handlers atomically, and the Linear capabilities page keeps the note that #47-#49 shipped. Put Linear's deferred-dispatch setup before the per-event steps, note that strategy options must be positive, and restore the softer "production-shaped" and "equivalent for the runtime" wording. _Generated with [`xum`](https://github.com/coder/xum) • Model: `anthropic:claude-opus-5-5` • Thinking: `high`_
|
@codex review |
|
@codex security review |
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
🛡️ Codex Security ReviewSecurity review completed. No security issues were found in this pull request. Reviewed commit: Only the user who started this review can view the report in Codex. ℹ️ About Codex security reviews in GitHubThis is an experimental Codex feature. Security reviews are triggered when:
Once complete, Codex will leave suggestions, or a comment if no findings are found. |
…after it Deferred handlers launch at acknowledgement time and may start before the 2xx is written, so "runs after the acknowledgement" overstated the order. _Generated with [`xum`](https://github.com/coder/xum) • Model: `anthropic:claude-opus-5-5` • Thinking: `high`_
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f7365a768b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Dedupe marks record accepted events, written before handlers run, not handled events. Under ConcurrencyConcurrent an event waiting for a slot spends its DetachTimeout and is dropped if it runs out. _Generated with [`xum`](https://github.com/coder/xum) • Model: `anthropic:claude-opus-5-5` • Thinking: `high`_
|
@codex review |
|
@codex security review |
🛡️ Codex Security ReviewSecurity review completed. No security issues were found in this pull request. Reviewed commit: Only the user who started this review can view the report in Codex. ℹ️ About Codex security reviews in GitHubThis is an experimental Codex feature. Security reviews are triggered when:
Once complete, Codex will leave suggestions, or a comment if no findings are found. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e2b17d8f4d
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…rategy ConcurrencyConcurrent takes no thread lock, so commands and interactions follow the configured strategy rather than always being serialized. _Generated with [`xum`](https://github.com/coder/xum) • Model: `anthropic:claude-opus-5-5` • Thinking: `high`_
|
@codex review |
|
@codex security review |
🛡️ Codex Security ReviewSecurity review completed. No security issues were found in this pull request. Reviewed commit: Only the user who started this review can view the report in Codex. ℹ️ About Codex security reviews in GitHubThis is an experimental Codex feature. Security reviews are triggered when:
Once complete, Codex will leave suggestions, or a comment if no findings are found. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 403f127ce4
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Codex: the debounce quiet period and the lock wait after it consume the event's DetachTimeout, as do queue and concurrent-slot waits; state this once for all waiting strategies. Readiness review: restore that MaxDetached must be positive under deferred dispatch, that modal clicks are not normalized yet, and that Linear's experimental tier and developer preview are separate facts. _Generated with [`xum`](https://github.com/coder/xum) • Model: `anthropic:claude-opus-5-5` • Thinking: `high`_
|
@codex review |
|
@codex security review |
|
Codex Review: Didn't find any major issues. Hooray! Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
🛡️ Codex Security ReviewSecurity review completed. No security issues were found in this pull request. Reviewed commit: Only the user who started this review can view the report in Codex. ℹ️ About Codex security reviews in GitHubThis is an experimental Codex feature. Security reviews are triggered when:
Once complete, Codex will leave suggestions, or a comment if no findings are found. |
|
Readiness record: ready (not merged — see below).
Why not merged: Rendered-docs evidence (GitHub preview of the branch at
Recording: a scroll-through of the deferred-dispatch guide, the explanation page, and the Linear agent sessions guide. The recorder writes frames only on visual change, so playback (about 7 s) is compressed. Generated with tour.webm |
1 participant
Rewrites the rest of the user docs in the style of the new README (#81): result first, short sentences, plain terms instead of internal vocabulary ("dispatch spine", "slice", "single-slot"), and limits after the main task. Docs-only; facts are unchanged except one correction noted below.
Changes
deferred-dispatch: options table with defaults, a separate "How it works", a concurrency-strategy table, and an overload section with a per-platform response table.choose-a-state-backend: decision table first; namespace rules as two bullets.slash-commands,interactive-components: plain intros; interactive limits (modal clicks,view_submission) collected in one section.multi-tenant-install: subsections for storing the bot user ID and for Linear's unverified tenant lookup.linear-agent-sessions: numbered timing steps and a shorter Stop section. Source-marked snippets are unchanged.CONTEXT.md/ADR index moved to the end.CONTRIBUTING.md("What Tests Must Cover").Review focus
RespondURLresponses are always ephemeral (adapters/slack/interactive.gohardcodesresponse_type: "ephemeral"); the old text said "ephemeral by default".origin/mainand the Go source found no blockers; its should-fix items (Linear completion signals are per session, burst join order, documentation-coverage wording) are fixed in the last commit.Validation
go test -run 'TestDocumentation|TestLinearHowTo|TestREADME|TestAdapterDocumentation' .passes (with-race).go vet ./...,go test ./...inexamples/linear-agent-hello-world, andgit diff --checkpass.Not changed on purpose:
CONTEXT.mdand the ADRs (vocabulary and decision records).Generated with
xum• Model:anthropic:claude-opus-5-5• Thinking:high