Skip to content

docs: deduplicate Slack setup, tunnel, and Linear stop sections - #82

Merged
ThomasK33 merged 3 commits into
mainfrom
docs/dedupe-setup
Sep 23, 2026
Merged

ThomasK33 merged 3 commits into
mainfrom
docs/dedupe-setup

Conversation

@ThomasK33

Copy link
Copy Markdown
Member

Removes copied Slack setup text from the example READMEs and fixes a setup gap it was hiding. PR 3 of a docs cleanup; stacked on #80 (base docs/fix-stale-facts). 9 files, +79 / −396.

What changed

  1. Tutorial is the one full Slack setup walkthrough. The four Slack example READMEs (hello-world, Redis, Postgres, NATS) each carried ~110 near-identical lines of scopes, App Home, events, credentials, Tailscale, and Slack links. They now link to the tutorial steps and keep a compact settings table plus their backend-specific run instructions.
  2. Unique details moved, not lost. The tutorial gains the App Home "Sending messages to this app has been turned off" hint, Funnel-vs-Serve and funnel reset notes, and the Slack doc links. docs/reference.md gains the im:write note for ephemeral DM fallback.
  3. Setup gap fixed. The durable-state examples promise that follow-ups in a subscribed thread get a reply, but their setup never added the channels:history scope or the message.channels event, so those follow-ups never reach the bot. The new table includes both.
  4. Linear example README. Drops the duplicated Run block and Tailscale section (links to tutorial Step 5), and removes the maintainer-only "Dogfooding Evidence" checklist (moving to CONTRIBUTING.md in docs: rewrite README landing page and add CONTRIBUTING.md #81).
  5. Smaller dedupes. The Linear capability-gaps stop section now points to the how-to instead of repeating it (the copy that drifted in docs: fix stale facts found in a docs accuracy audit #80), and a repeated adapter-tier row is removed from the explanation's concept map.

Considered and kept: the per-adapter bullet lists in docs/reference.md overlap the capability table but also carry details the table lacks (signature and replay checks, identity discovery, payload tolerance), so they stay.

Validation

  • go test -run 'Documentation|README|Snippets' . passes.
  • Relative-link and anchor check over all user-facing Markdown: 0 broken, including the new #step-5-expose-the-bot-to-slack and #use-the-full-activity-surface anchors.
  • git diff --check clean.

Generated with xum • Model: anthropic:claude-opus-5-5 • Thinking: high

ThomasK33 added a commit that referenced this pull request Sep 23, 2026
Moves the Linear example's maintainer-only dogfooding checklist into
contributor docs (removed from the example README in #82).

_Generated with [`xum`](https://github.com/coder/xum) • Model: `anthropic:claude-opus-5-5` • Thinking: `high`_
@ThomasK33

Copy link
Copy Markdown
Member Author

@codex review

@ThomasK33

Copy link
Copy Markdown
Member Author

@codex security review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 23, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-09-23T15:39:36.284361Z a1e423b Manual request
🔒 Security Review ✅ Completed 2026-09-23T15:39:45.701949Z a1e423b Manual request
ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8fcd7577cc

ℹ️ 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".

Comment thread examples/linear-agent-hello-world/README.md
@chatgpt-codex-connector

Copy link
Copy Markdown

🛡️ Codex Security Review

Security review completed. No security issues were found in this pull request.

Reviewed commit: 8fcd7577cc

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ 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.

@ThomasK33

Copy link
Copy Markdown
Member Author

@codex review

@ThomasK33

Copy link
Copy Markdown
Member Author

@codex security review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Nice work!

Reviewed commit: daafe8a3e6

ℹ️ 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".

@chatgpt-codex-connector

Copy link
Copy Markdown

🛡️ Codex Security Review

Security review completed. No security issues were found in this pull request.

Reviewed commit: daafe8a3e6

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ 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.

@ThomasK33

Copy link
Copy Markdown
Member Author

@codex review

@ThomasK33

Copy link
Copy Markdown
Member Author

@codex security review

@ThomasK33

Copy link
Copy Markdown
Member Author

Rendered-docs evidence (GitHub preview of the branch at 8fcd757; documentation check only, not a live Slack run). The slimmed example README with its settings table, and tutorial Step 5 with the moved Funnel notes:

Redis example setup
Tutorial Step 5


Generated with xum • Model: anthropic:claude-opus-5-5 • Thinking: high

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Chef's kiss.

Reviewed commit: a1e423b451

ℹ️ 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".

@chatgpt-codex-connector

Copy link
Copy Markdown

🛡️ Codex Security Review

Security review completed. No security issues were found in this pull request.

Reviewed commit: a1e423b451

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ 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.

@ThomasK33

Copy link
Copy Markdown
Member Author

Readiness record: ready. Removes duplicated Slack setup text; stacked on #80.


Generated with xum • Model: anthropic:claude-opus-5-5 • Thinking: high

Make the Slack tutorial the one full walkthrough of Slack app setup.
The four Slack example READMEs now link to its steps and keep a compact
settings table plus their backend-specific instructions. The tutorial
absorbs the unique details they carried (App Home troubleshooting,
Funnel vs Serve, funnel reset, Slack doc links), and the reference
absorbs the im:write note for DM fallback.

The durable-state example READMEs promised subscribed-thread follow-ups
but never asked for the channels:history scope or message.channels
event, without which those follow-ups never reach the bot; the new
settings table includes both.

Also: drop the duplicated Run block and Tailscale section from the
Linear example README, move its maintainer-only "Dogfooding Evidence"
checklist out of user docs, point the Linear capability-gaps stop
section at the how-to instead of repeating it, and remove a repeated
adapter-tier row from the explanation's concept map.

_Generated with [`xum`](https://github.com/coder/xum) • Model: `anthropic:claude-opus-5-5` • Thinking: `high`_
_Generated with [`xum`](https://github.com/coder/xum) • Model: `anthropic:claude-opus-5-5` • Thinking: `high`_
Restores two details the deduplicated example READMEs carried.

_Generated with [`xum`](https://github.com/coder/xum) • Model: `anthropic:claude-opus-5-5` • Thinking: `high`_
@ThomasK33
ThomasK33 changed the base branch from docs/fix-stale-facts to main September 23, 2026 15:47
@ThomasK33
ThomasK33 merged commit b09fec4 into main Sep 23, 2026
1 check passed
@ThomasK33
ThomasK33 deleted the docs/dedupe-setup branch September 23, 2026 15:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant