Skip to content

docs: add a Quick start section to README.md - #408

Merged
ncrmro merged 2 commits into
mainfrom
docs/readme-quick-start
Sep 4, 2026
Merged

docs: add a Quick start section to README.md#408
ncrmro merged 2 commits into
mainfrom
docs/readme-quick-start

Conversation

@ncrmro

@ncrmro ncrmro commented Sep 4, 2026

Copy link
Copy Markdown
Contributor

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 to docs/overview.md for the concepts. Matches the existing Makefile targets.

Panopticon task: 8643a7031187448eac14276fa82e2c74

🤖 Generated with Claude Code

https://claude.ai/code/session_01NV7Vhip7N5QPuSuwvUvVpw

Closes #407

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NV7Vhip7N5QPuSuwvUvVpw
@ncrmro
ncrmro marked this pull request as ready for review September 4, 2026 02:03
@ncrmro
ncrmro requested a review from luce-unsup September 4, 2026 02:03

@luce-unsup luce-unsup left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

  1. Two getting-started paths with confusable titles. This README already has an end-user path: Install → Quickstart (pipx install panopticon-app, then panopticon quickstart). This PR adds a second, near-identically-titled ## Quick start teaching 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.

  2. Lower-fidelity duplicate of docs/dev.md. The new section drops git and the claude CLI from prerequisites (needed once you actually create a task) and omits make build, which dev.md's stack-up flow calls out as required before spawning task containers — so a reader following only make sync/make start gets a dashboard but can hit a missing base image on their first task.

  3. 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, then make start (make stop tears it down). The full development loop — checks, base-image build, migrations — is in docs/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
@ncrmro
ncrmro requested a review from luce-unsup September 4, 2026 03:35

@luce-unsup luce-unsup left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@ncrmro
ncrmro merged commit afa12e1 into main Sep 4, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: add a Quick start section to README.md

2 participants