docs: add a troubleshooting FAQ for common first-run failures - #358
Draft
tildesrc wants to merge 1 commit into
Draft
docs: add a troubleshooting FAQ for common first-run failures#358tildesrc wants to merge 1 commit into
tildesrc wants to merge 1 commit into
Conversation
Add docs/troubleshooting.md, a top-level FAQ covering the failures new installs hit most: the Claude login/paid-account gate, a missing GH_TOKEN, a workflow missing from the picker, a task stuck at `awaiting`, services that seem gone (the -L panopticon tmux server), a mid-task auth 401, and how to read `panopticon doctor`. Each entry links the owning doc's detail section rather than duplicating it. Link it from the README (Managing your install) and overview.md (Where to go next). 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.
Adds
docs/troubleshooting.md, a top-level FAQ for the failures new installs hit most, and links it from the README anddocs/overview.md.Why
Troubleshooting help existed only inside per-topic docs (
container.md,hooks.md) — there was no central page for a stuck first-run user to check.What
docs/troubleshooting.mdcovers, in FAQ style (question → short answer → link to the owning doc's detail):ANTHROPIC_API_KEYghfails → addGH_TOKENto the env-fileg→ edit → check)awaiting/ never reacheslive→ Docker daemon + base image;panopticon doctortmux lsempty) → the-L panopticonserver;panopticon start/consolesetup-repo, respawn withRpanopticon doctorEach entry links the owning doc rather than duplicating it. Wired in from the README ("Managing your install") and
overview.md("Where to go next").Plan: see the task's
plan.mdartifact.