Repository navigation
Trim the README from the newcomer read-through - #15
Merged
Merged
Conversation
A colleague followed the quick start cold on 2026-10-20. It worked end to end, but step 2 described Slack app screens that no longer exist (Install to Workspace, then OAuth & Permissions), so he had to find the user token on his own in a "Slackline is ready!" window that also offers an App Token. The quick start now walks the current screens, splits handing over the token from checking it, and shows what whoami should print, so a newcomer can tell success from a wrong token. The README read as if 1Password were the only way to give an agent a token. It never was: SLACK_USER_TOKEN set any way works, including the quick start's own read -rs. Using with Claude Code now leads with that, and 1Password is shown as one option with a note to use your own account and item. No new credential source was added. Reference detail moved out so the README stays a front door: the credential chain to docs/credentials.md; output rules, exit codes, the audit log and the directory cache to docs/reference.md. Added an Uninstall section, which the reviewer found missing. The Phase 2.0 plan's steps that edit the moved sections now point at the new file. Two checks stay open before the flip, recorded in the roadmap: someone clicks through the new step 2 against Slack's real screens, and a non-admin tries the install to learn whether Slack blocks it.
When an agent finds no token, the skill tells it to quote a relaunch command to the user, and the only command it offered was the 1Password one. That repeats the impression the README trim just removed: any SLACK_USER_TOKEN in the environment works. The plain read -rs relaunch now comes first, with 1Password as the alternative. Also drops the roadmap item to click through the new quick start step 2 before the flip. The owner trusts the reviewer's walkthrough it was written from.
The owner tried the install as a non-admin in two other workspaces on 2026-10-25. One allowed it; Tech DNA refused with "You don't have permission to install apps", while still offering to create the app and request the install. Whether a non-admin can install is a workspace setting, so the README keeps "may need an admin" and now quotes the refusal and says what to do next, which is where a newcomer would otherwise stall.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Acts on a colleague's cold read of the quick start (2026-10-20). Docs only; no code changes.
Quick start
read -rs, which shows no prompt) is now its own step, andwhoamiis checked separately, with its expected output shown.#generalfor a channel that exists.1Password is not required
SLACK_USER_TOKENin its environment, set any way. Using with Claude Code now leads with the quick start's ownread -rsand startingclaudefrom that shell; 1Password is shown as one option, with a note to use your own account and item. No new credential method was added.Moved out of the README (text unchanged, apart from the clarifications above)
docs/credentials.md: the resolution chain,--token-file, agent and unattended use, Keychain setup.docs/reference.md: reading the output, exit codes, the audit log, the directory cache.Added: an Uninstall section (binary, skill, local cache and audit log, Keychain item, and deleting the Slack app via Delete App on its Basic Information page, confirmed by the owner).
Non-admin install, tested by the owner in two workspaces: one allowed it, one refused with "You don't have permission to install apps". Step 2 now quotes that and says to request the install.
Also updated: the manifest's header comment (same steps), the slackline skill's relaunch hint (plain
read -rsfirst, 1Password as the alternative), the roadmap's Go public checklist, and the Phase 2.0 plan's pointers to the moved sections.Offline suite: 512 passed. All internal links and anchors resolve.