From d70642b4073cbdff48e83a682ee6d2faa9b701e5 Mon Sep 17 00:00:00 2001 From: Charlie Scherer Date: Wed, 15 Jul 2026 17:50:02 -0500 Subject: [PATCH 1/3] docs: fix onboarding dead ends and navigation 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 --- README.md | 36 ++++++++++++++++++++++++++++++------ docs/overview.md | 2 ++ docs/workflows/setup-repo.md | 6 +++--- 3 files changed, 35 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index a474d1c3..856babbc 100644 --- a/README.md +++ b/README.md @@ -61,9 +61,12 @@ shells out to a few host tools. You need: `tmux -L panopticon` server - **git:** the session service clones a per-task workspace for each agent - The **`claude` CLI:** first-time setup runs `claude setup-token` on the host to mint the - Claude auth token each agent uses inside its container + Claude auth token each agent uses inside its container. Minting a token needs a **paid Claude + subscription or Console login**; an `ANTHROPIC_API_KEY` works instead. See + [`docs/auth.md`](docs/auth.md). -`panopticon quickstart` checks these first; run `panopticon doctor` to re-check any time. +`panopticon quickstart` checks these first; run `panopticon doctor` to re-check any time. On macOS +you need Docker **Desktop** specifically; see [`docs/macos-setup.md`](docs/macos-setup.md). ## Install @@ -101,10 +104,13 @@ fleet from the dashboard. On the dashboard: -1. **Create it.** Press `n`, then pick the repo and a workflow: `github-peer-reviewed` (opens a PR - to merge) or `local-git-self-reviewed` (stays on local git, no GitHub needed). Describe - the work in a sentence or two. See [`docs/workflows/`](docs/workflows/README.md) for the full - catalog and how to choose. +1. **Create it.** Press `n`, then pick the repo and a workflow. `spike` (open-ended, no gates) + works on every repo out of the box. The change-shipping workflows (`github-peer-reviewed` and + `github-self-reviewed`, which open a PR, and `local-git-self-reviewed`, which keeps commits + local) are **opt-in**: enable them for the repo first in the repos form (press `g`, edit the + repo, and check the workflows you want). GitHub workflows also need a `GH_TOKEN` in the repo's + env-file so the container's `gh` can open PRs (see [`docs/auth.md`](docs/auth.md)). Describe the + work in a sentence or two; the [workflow catalog](docs/workflows/README.md) explains how to choose. 2. **Watch it start.** The task's `container` column moves `queued → … → live` as the runner spawns its container; once it's `live` the agent starts on its own branch and begins planning automatically. Press `a` to open its plan when it's ready. @@ -129,3 +135,21 @@ variable (resolution is `$PANOPTICON_*` → `$XDG_*_HOME/panopticon` → the def | Artifacts + per-task clones | `~/.local/share/panopticon/` | `PANOPTICON_DATA` | | Layers, secrets, workflows | `~/.config/panopticon/` | `PANOPTICON_CONFIG` (workflows also via the `--workflows-path` flag) | | Per-repo clone cache | `~/.cache/panopticon/repos/` | `PANOPTICON_CACHE` | + +## Managing your install + +- **Bring it back up** after a reboot or after you quit: `panopticon start` starts the services and + opens the dashboard. `panopticon console` re-attaches when the services are already running. +- **Stop everything:** `panopticon stop` removes the task containers and the `-L panopticon` tmux + server. Your data under `~/.local/share/panopticon` is left in place. +- **Check your host:** `panopticon doctor` verifies Python, Docker (and a running daemon), tmux, + git, and the `claude` CLI, printing a line per check and exiting non-zero if anything is missing. +- **Upgrade:** `pipx upgrade panopticon-app` (or `pip install --upgrade panopticon-app`), then + `panopticon migrate` to apply any new database migrations. +- **Uninstall:** `panopticon stop`, then `pipx uninstall panopticon-app`. To remove state too, + delete `~/.local/share/panopticon`, `~/.config/panopticon`, and `~/.cache/panopticon`, and remove + the `panopticon-*` Docker images. + +## License + +MIT. See [`LICENSE`](LICENSE). diff --git a/docs/overview.md b/docs/overview.md index 56fc63f8..6f8da05b 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -135,7 +135,9 @@ This page is the map; these guides are the detail: - **[Tasks](tasks.md)** — the task object in full: its properties, states, and lifecycle. - **[Containers](container.md)** — the container lifecycle, every dashboard status, and recovery. - **[Repos](repos.md)** — configuring a repo: secrets, image layers, and capabilities. +- **[Container auth](auth.md)** — giving each repo's agents their Claude token (and a GitHub token for PRs). - **[Image layers](layers.md)** — the composed `base → workflow → repo` image, and adding your own. - **[Hooks](hooks.md)** — the per-repo host hook that runs before a container spawns. +- **[macOS setup](macos-setup.md)** — the Docker Desktop specifics for running on a Mac. - **[Developing](dev.md)** — working *on* panopticon: setup, the check loop, and CI. - **[README](../README.md)** — install, quickstart, your first task, and configuration. diff --git a/docs/workflows/setup-repo.md b/docs/workflows/setup-repo.md index 10b82e4e..5f6848f9 100644 --- a/docs/workflows/setup-repo.md +++ b/docs/workflows/setup-repo.md @@ -17,8 +17,8 @@ token lands in the repo's env-file. ## How you launch it This workflow is **hidden** from the normal task-creation picker. You start it from the -**repos screen's setup hotkey**, which creates a `setup-repo` task for the highlighted -repo. (It's available for every repo; there's nothing to enable.) +**repos screen**: press `g` to open it, highlight the repo, and press `s`. That creates a +`setup-repo` task for that repo. (It's available for every repo; there's nothing to enable.) ## Lifecycle @@ -39,6 +39,6 @@ task has no agent to gate. ## Related -- [Container authentication](../container-auth.md): what the token is for and how to set +- [Container authentication](../auth.md): what the token is for and how to set it by hand instead. - [Workflow catalog](README.md). From e553c48cbc38084297ff0d532d5d4bef607b9965 Mon Sep 17 00:00:00 2001 From: Charlie Scherer Date: Wed, 15 Jul 2026 17:56:46 -0500 Subject: [PATCH 2/3] docs: quickstart already enables the matching workflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- README.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 856babbc..3c2cd848 100644 --- a/README.md +++ b/README.md @@ -104,13 +104,14 @@ fleet from the dashboard. On the dashboard: -1. **Create it.** Press `n`, then pick the repo and a workflow. `spike` (open-ended, no gates) - works on every repo out of the box. The change-shipping workflows (`github-peer-reviewed` and - `github-self-reviewed`, which open a PR, and `local-git-self-reviewed`, which keeps commits - local) are **opt-in**: enable them for the repo first in the repos form (press `g`, edit the - repo, and check the workflows you want). GitHub workflows also need a `GH_TOKEN` in the repo's - env-file so the container's `gh` can open PRs (see [`docs/auth.md`](docs/auth.md)). Describe the - work in a sentence or two; the [workflow catalog](docs/workflows/README.md) explains how to choose. +1. **Create it.** Press `n`, then pick the repo and a workflow. `quickstart` already enabled the + coding workflow that matches your repo: `github-peer-reviewed` for a GitHub repo (opens a PR), or + `local-git-self-reviewed` for a local-only one (keeps commits local). `spike` (open-ended, no + gates) is always available too. To use a different workflow, enable it for the repo first in the + repos form (press `g`, edit the repo, and check the workflows you want). GitHub workflows need a + `GH_TOKEN` in the repo's env-file so the container's `gh` can open PRs (see + [`docs/auth.md`](docs/auth.md)). Describe the work in a sentence or two; the + [workflow catalog](docs/workflows/README.md) explains how to choose. 2. **Watch it start.** The task's `container` column moves `queued → … → live` as the runner spawns its container; once it's `live` the agent starts on its own branch and begins planning automatically. Press `a` to open its plan when it's ready. From 6ab454d47f6c95ef4a7ecf6823a52a419e7fe0e5 Mon Sep 17 00:00:00 2001 From: Charlie Scherer Date: Wed, 15 Jul 2026 18:00:36 -0500 Subject: [PATCH 3/3] =?UTF-8?q?docs:=20apply=20review=20suggestion=20?= =?UTF-8?q?=E2=80=94=20tighten=20workflow-enable=20wording?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 3c2cd848..19d1252d 100644 --- a/README.md +++ b/README.md @@ -107,7 +107,7 @@ On the dashboard: 1. **Create it.** Press `n`, then pick the repo and a workflow. `quickstart` already enabled the coding workflow that matches your repo: `github-peer-reviewed` for a GitHub repo (opens a PR), or `local-git-self-reviewed` for a local-only one (keeps commits local). `spike` (open-ended, no - gates) is always available too. To use a different workflow, enable it for the repo first in the + gates) is always available too. To use a different workflow, enable it for your repo in the repos form (press `g`, edit the repo, and check the workflows you want). GitHub workflows need a `GH_TOKEN` in the repo's env-file so the container's `gh` can open PRs (see [`docs/auth.md`](docs/auth.md)). Describe the work in a sentence or two; the