docs: restructure along Diátaxis — maturity tiers, non-goals, tutorial, how-tos - #11
Conversation
|
@codex review |
|
@codex security review |
|
@codex review |
|
@codex security review |
d460fd3 to
533e296
Compare
|
@codex review |
|
@codex security review |
|
Security 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. |
![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: 533e296c59
ℹ️ 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 review |
|
@codex security review |
|
Security 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: b7b268c0f2
ℹ️ 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 review |
|
@codex security review |
|
Security 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: d6d710de37
ℹ️ 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 review |
|
@codex security review |
|
Security 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: a2c6dd5207
ℹ️ 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 review |
|
@codex security review |
|
Security 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: e83eee50f8
ℹ️ 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 review |
|
@codex security review |
|
Security 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: 3dc1566a07
ℹ️ 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 review |
|
@codex security review |
|
Security 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: 6b7564e3ce
ℹ️ 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 review |
|
@codex security review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5297d6eaef
ℹ️ 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".
There was a problem hiding this comment.
💡 Codex Security Review
Here are some automated security review suggestions for this pull request.
Reviewed commit: 5297d6eaef
ℹ️ About Codex security reviews in GitHub
This is an experimental Codex feature. Security reviews are triggered when:
- You comment "@codex security review"
- A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review
Once complete, Codex will leave suggestions, or a comment if no findings are found.
…l, how-tos Closes #9 - README: honest adapter maturity tiers (Slack supported, Linear experimental, Teams spike), Non-Goals section with ADR rationales, Diátaxis docs index, and staleness fixes (rate-limit retry, multi-tenant installs, HistoryReader, DispatchDeferred, ConcurrencyQueue, NATS state, Linear full activity surface are all implemented and now documented as such). - docs/: Diátaxis skeleton — verified Slack bot tutorial, six how-to guides, reference (pkg.go.dev pointers + capability matrix), explanation index over CONTEXT.md and the ADRs. - docs/agents/issue-tracker.md: GitHub issues are the public source of truth; .scratch/ demoted to internal working notes.
… guides - slash commands: respond via RespondURL (channel commands have a synthetic channel root that Thread.Post cannot post to) - deferred dispatch: build options from DefaultRuntimeOptions (WithRuntimeOptions replaces, not merges); describe Shutdown as cancel-then-drain, not graceful completion - interactive components: actor ID mention instead of unset Actor.Name; accurate sync-vs-deferred ack ordering; view_submission payloads are dropped, not observable; OpenModalForTenant in multi-tenant mode - README: accurate ack ordering for command/interaction events under DispatchSync - AGENTS.md: align issue-tracker policy with GitHub issues as public source of truth
- slash commands: channel command lock scope is the synthetic channel root, distinct from message thread scopes — no cross-serialization claim - interactive components: document the missing public trigger_id accessor as a known gap (tracked in #12) instead of an un-followable example - linear agent sessions: check every activity error before continuing - deferred dispatch (and siblings): describe the detached tail as launched at ack time / concurrent with the response, not strictly after the 2xx
- tutorial: Step 8 adds message.channels + channels:history (or DM path) before promising unmentioned follow-ups - linear-agent-capabilities.md: rewritten to match ADR 0008/0013 reality (GraphQL, full activity surface, signals, stop, session updates all ship); remaining gaps are proactive session creation, repo suggestions, activity history/HistoryReader parity, workflow helpers, UX examples - interactive components: chat.Text renders <@id> literally — no mention claim - multi-tenant: distinguish Slack's verified lookup from Linear's untrusted pre-verification routing lookup - deferred dispatch + README: queue coalescing is per-process; cross-replica superseded events can each run - linear agent sessions: concurrent-ack phrasing; stop check cannot preempt in-flight handlers — document app-owned cancellation
- deferred dispatch: document loss-of-exclusivity when lock renewal fails (renewal stops, handler keeps running; overlap possible after TTL) - linear agent sessions: first activity must be a thought, not a response — a response is a completion signal that ends the session - interactive components: PostNative example compiles and checks its error; menu selected-option values share the unexported-payload gap (#12 extended)
- linear agent sessions: session-handler example posts a genuinely final response; elicitation/error/response presented as mutually exclusive completion branches after nonterminal progress activities - ADR 0006: implementation note — Slack verifies the shared signature before tenant parse/lookup; unverified routing reads apply to per-install-signed platforms (Linear) - README non-goals: streaming framed as deferred-not-foreclosed per ADR 0011, not a permanent boundary - multi-tenant: Linear BotUserID/BotActorID documented as required for mention detection and self-filtering, with OAuth capture guidance
- deferred dispatch: a queued follow-up's DetachTimeout starts before the lock wait, so queue time consumes its budget and an exhausted wait cancels the (already-deduped) follow-up without running it
- slash commands: channel-wide queue coalescing caveat (one pending slot per channel scope supersedes independent commands) - linear stop signal: state plainly that Stop cannot cancel in-flight work through the adapter today; short-turn or out-of-band patterns instead - multi-tenant: per-install bot identity required on Slack too (self-filter loop risk with message events), not just Linear - capability tracker: lazy token refresh applies to client-credential installs only - README: state-module go get commands fail externally until a tagged release; document the replace workaround - CONTEXT.md: thread-lock relationship now matches implemented drop/queue strategy behavior instead of forbidding drops
- interactive components: document that repeat activations of the same action_id on one message dedupe to a single event for DedupeTTL (identity anchors on message ts, not the activation); tracked in #43 with interim distinct-action_id guidance
- interactive components: scope block_actions support to message-based blocks (modal-view containers are rejected before routing); attribution vs real-mention distinction - multi-tenant: thread reconstruction validates only; credential lookup happens at post time - reference: agent activities are thought/response/action/elicitation/error; plans/external URLs are session updates - linear generic comments: subscription precedence over mention routing - tutorial: qualify follow-up echoes under the default drop strategy
Main gained Linear HistoryReader (#37), OpenModalFromRaw (#42), and v0.1.0 tags with externally consumable submodules (#15); rebased and reconciled: - README/reference/tracker: Linear HistoryReader now supported; go get caveat removed (v0.1.0 tags exist); modal-open documented via OpenModalFromRaw / OpenModalForTenantFromRaw - capability tracker: roadmap section replaced with issue links (#47-#49); activity-history section removed (implemented); subscription precedence qualified in routing rows - reference matrix: Linear PostEphemeral marked unsupported (thoughts are a separate Linear-specific surface); block_actions scoped to messages - state backend guide: per-application namespace section (shared-backend record collisions) with Prefix/Namespace set in every production snippet - interactive components: action-value gap re-tracked as #46 (follow-up to closed #12)
5297d6e to
266747e
Compare
|
@codex review |
|
@codex security review |
|
Security 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: 266747e336
ℹ️ 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".
- explanation + linear guide: plans are session updates, not a sixth agent activity; the five activities are thought/response/action/elicitation/error - interactive components: queued interactions can outlive trigger_id's 3-second lifetime before the handler runs; modal opens then fail
|
@codex review |
|
@codex security review |
|
Security 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. |
|
Codex Review: Didn't find any major issues. 🚀 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". |
1 participant
Closes #9
Restructures user-facing documentation along Diátaxis and makes the public story honest and tiered. In-repo markdown only — no website, no workflow changes.
What changed
README
supported: dedicated hardening suites (ratelimit_hardening_test.go,multitenant_harden_test.go,history_hardening_test.go,interactive_hardening_test.go), Web API rate-limit retry with typedRateLimitederrors (ADR 0005,adapters/slack/retry.go), multi-tenant installs (ADR 0006),HistoryReader(ADR 0009), comprehensivedoc.go. The one honest caveat is stated in the table: no live end-to-end Slack test in CI.experimental: broad and hardened (full agent activity surface, generic comments, rate-limit retry, multi-tenant), but the upstream Linear agent API is itself in developer preview,HistoryReaderparity is missing, and several operations are GraphQL-escape-hatch only (tracked indocs/linear-agent-capabilities.md).Proposedand gated on a live-tenant spike (draft Spike: Microsoft Teams Adapter (Bot Framework) (ADR 0007) #4, tracked in feat(adapters/msteams): land Microsoft Teams adapter as experimental (needs live-tenant validation) #6).docs/ (Diátaxis skeleton)
docs/README.md— index, reachable from the README.docs/tutorials/slack-bot.md— zero → running Slack bot in under 30 minutes, verified (see below).docs/how-to/— six guides: state backends, deferred dispatch, slash commands, interactive components, multi-tenant installs, Linear agent sessions. All code snippets checked against real symbols (ValidateThreadID/PostNative,RespondURL,linear.ActionInput,chat.InstallStore, …).docs/reference.md— pkg.go.dev pointers for all seven packages (each already hasdoc.go; no Go changes needed) plus a per-adapter capability matrix.docs/explanation.md— index overCONTEXT.mdand all 14 ADRs with statuses.docs/agents/issue-tracker.md
GitHub issues are now the public source of truth for roadmap/bugs;
.scratch/is demoted to internal working notes (kept, not deleted).Tutorial verification
A live Slack workspace is not available in this environment, so the tutorial was verified up to the live-token boundary:
go build ./examples/slack-hello-worldandgo test ./examples/slack-hello-worldpass.CHAT_DEMO_IN_MEMORY_STATEand missingSLACK_SIGNING_SECRETeach panic with the documented messages.auth.testand fails withinvalid_auth— proving adapter construction, identity discovery, and the documented failure mode up to the point where a real token is required.Validation
go build ./...andgo test ./...(root module: 9 packages, all pass).TestDocumentationCoversIntentionalVercelDifferencesetc.) pass — all required README phrases preserved.No Go code changes. No
.github/workflows/changes.Generated with
mux• Model:anthropic:claude-fable-5• Thinking:xhigh