docs: fix onboarding dead ends and navigation#343
Merged
Conversation
From a user-facing docs review: - README "Your first task": the suggested workflows are opt-in and hidden from the picker by default. Explain that spike is always available, that the change-shipping workflows are enabled per repo in the repos form (g -> edit -> check), and that GitHub workflows need a GH_TOKEN. - README Requirements: minting a Claude token needs a paid subscription / Console login (or an ANTHROPIC_API_KEY); link auth.md. Note macOS needs Docker Desktop and link macos-setup.md. - README: add a "Managing your install" section (start/stop/console, doctor, upgrade + migrate, uninstall/cleanup) and a License section. - overview.md hub: add the missing auth.md and macos-setup.md links. - workflows/setup-repo.md: fix the broken ../container-auth.md link (now ../auth.md) and name the launch keys (g -> highlight -> s). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
tildesrc
commented
Jul 15, 2026
Correcting the "Your first task" step per review: quickstart enables the coding workflow that matches the repo (github-peer-reviewed for a GitHub remote, local-git-self-reviewed for a local-only one), so it's already in the picker — no hand-enable needed for the happy path. Keep the "enable a different one in the repos form" note for other workflows. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
tildesrc
commented
Jul 15, 2026
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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
1 participant
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.
From a review of the user-facing docs (new-user + evaluator perspectives, links, missing topics). This PR takes the concrete, blocking fixes; the larger prose cleanup is called out as follow-up below.
Fixes
github-peer-reviewed/local-git-self-reviewed, but those are opt-in and hidden from the picker by default. Rewrote it:spikeis always available; the change-shipping workflows are enabled per repo in the repos form (g→ edit → check); and GitHub workflows need aGH_TOKEN.claude setup-tokenneeds a paid Claude subscription / Console login (or anANTHROPIC_API_KEY), and linksdocs/auth.md— so the token step in quickstart isn't a dead end.docs/macos-setup.md(a Mac user on Docker Engine used to bounce after installing).panopticon start/stop/console,panopticon doctor(what it checks), upgrade (pipx upgrade+panopticon migrate), and uninstall/cleanup — none of which was documented for users.overview.md's "Where to go next" was missingauth.mdandmacos-setup.md— added both.docs/workflows/setup-repo.mdlinked../container-auth.md(renamed to../auth.md) — fixed, and named the launch keys (g→ highlight →s).Deliberately deferred (recommend a focused follow-up PR)
tasks.md,container.md,repos.md,hooks.md,layers.md,overview.md) — 167 em-dashes plus heavy semicolon-chaining and**Bold.**-lead bullets. This is a large, subjective restyle best reviewed on its own rather than mixed with functional fixes.tasks.mdandcontainer.md; theenv_filemechanics in bothrepos.mdandauth.md; the "name-relative-to-dir / per-host" template repeats acrossrepos/layers/hooks. Ownership consolidation belongs with the prose pass.🤖 Generated with Claude Code