#249 docs: make SETUP.md more user-friendly

[Anonymous]

Originally created by: QY-25123

Problem

docs/SETUP.md has grown into a long, dense reference (400+ lines) that's hard to skim for a
first-time user. Specific pain points:

• No "at a glance" summary at the top — a new user has to read past the TOC into section 1
  before finding out how many steps are involved or how long it takes.
• The Troubleshooting: wrong or stale doberman on PATH section sits between "Install" and
  "Wrap your tool server," even though it's an edge case most readers will never hit on a first
  read. It pushes the actual integration steps (MCP proxy, Claude Code hooks) further down the
  page.
• Heavy duplication of intent with the README Quick Start — it's not
  always obvious which doc to read first, or what's different between them.
• Long prose paragraphs (e.g. the doberman hook pre/doberman hook post explanation) mix
  conceptual explanation with reference-level detail in the same block, making it hard to skim
  for "what do I actually run."
• No visual aid for the overall flow (agent → Doberman proxy/hook → tool server) — it's all text.

Proposal

• Add a short "at a glance" cheat-sheet near the top: install → wrap/hook → verify (doberman doctor), with time estimate, before the detailed walkthrough.
• Move the PATH troubleshooting section to an appendix/collapsible section (or its own doc) so
  the happy path isn't interrupted by an edge case.
• Clarify the README vs. SETUP.md split explicitly (e.g. "README = 30 second version, this doc =
  full walkthrough with troubleshooting").
• Break long explanatory paragraphs into short lead-ins + bullet lists, consistent with the rest
  of the doc's style.
• Consider a simple diagram (even ASCII) of the request flow through Doberman for the MCP proxy
  and Claude Code hook paths.

Non-goals

• No behavior/CLI changes — this is a documentation-only issue.

[Anonymous]

Originally posted by: fu351

Thanks for this. You didn't just say the docs are hard to read, you pointed at the exact friction: the PATH-troubleshooting section wedged between install and integration, the README/SETUP overlap, reference detail tangled into conceptual prose. That makes the fix obvious.

I tagged it good first issue, level-2, documentation. It's doc-only and self-contained, a good first surface to learn the repo's bar on. Want to take it yourself? Say the word and it's yours, no pressure either way.

There's a friendly crowd in the Discord if you'd like to talk it through: https://discord.gg/Sfy5XGNqty

[Anonymous]

Ticket changed by: QY-25123

• status: open --> closed