docs: add a Quick start section to README.md - #408
Conversation
Closes #407 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NV7Vhip7N5QPuSuwvUvVpw
luce-unsup
left a comment
There was a problem hiding this comment.
Requesting changes on docs-structure grounds. The content itself is accurate — I checked the Makefile and make sync/make start/make stop all exist with the descriptions given — but the placement and framing collide with what the README and docs already establish:
-
Two getting-started paths with confusable titles. This README already has an end-user path: Install → Quickstart (
pipx install panopticon-app, thenpanopticon quickstart). This PR adds a second, near-identically-titled## Quick startteaching the contributor path (make sync/make start) without saying it is for developing panopticon itself. A newcomer reading top-down now meets two contradicting flows, and the repo already documents the split explicitly: docs/dev.md is titled "Developing panopticon" and opens with "Just want to use panopticon? Start with the README." That division is worth preserving. -
Lower-fidelity duplicate of docs/dev.md. The new section drops git and the
claudeCLI from prerequisites (needed once you actually create a task) and omitsmake build, which dev.md's stack-up flow calls out as required before spawning task containers — so a reader following onlymake sync/make startgets a dashboard but can hit a missing base image on their first task. -
Duplicate link. The closing sentence re-links docs/overview.md, which the intro paragraph immediately above the new section already links.
Suggested shape — keep the copy-paste path from #407 but frame it and defer the details:
Working on panopticon
Set up a dev environment and bring the stack up with
make sync, thenmake start(make stoptears it down). The full development loop — checks, base-image build, migrations — is indocs/dev.md; to use panopticon, see Install below.
That honors the issue, avoids the Quickstart title collision, and leaves prerequisites and make build to the doc that already documents them correctly.
Retitle to 'Working on panopticon' so it cannot be confused with the end-user Install → Quickstart flow, defer prerequisites, make build, and the rest of the loop to docs/dev.md, and drop the duplicate overview link. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NV7Vhip7N5QPuSuwvUvVpw
luce-unsup
left a comment
There was a problem hiding this comment.
Approved — the reframe addresses all three points: the section is now unambiguously the contributor path ("Working on panopticon"), prerequisites and make build are deferred to docs/dev.md which documents them correctly, and the duplicate overview.md link is gone. I re-checked the wording against the Makefile: make sync / make start / make stop descriptions all hold, and the #install anchor resolves to the existing Install heading.
One optional tidy-up, non-blocking: the PR description still describes the first revision (prerequisites list, "where the dashboard appears", overview pointer) — refreshing it to match the final section would keep the record straight for future readers.
Closes #407
Adds the copy-paste path from clone to a running dashboard right after the intro: prerequisites (uv, tmux, Docker),
make sync/make start, where the dashboard appears,make stop, and a pointer todocs/overview.mdfor the concepts. Matches the existing Makefile targets.Panopticon task: 8643a7031187448eac14276fa82e2c74
🤖 Generated with Claude Code
https://claude.ai/code/session_01NV7Vhip7N5QPuSuwvUvVpw