From c5fef6b07157d3e61389a8bbb4e744d4ec0b0148 Mon Sep 17 00:00:00 2001
From: jonathanpopham <jonathan.popham@gmail.com>
Date: Thu, 30 Apr 2026 18:17:01 -0400
Subject: [PATCH 1/4] docs: make CLI quickstart watcher-first

---
 cli/quickstart.mdx | 43 ++++++++++++++++++++++++++++++-------------
 index.mdx          | 19 +++++++------------
 2 files changed, 37 insertions(+), 25 deletions(-)

diff --git a/cli/quickstart.mdx b/cli/quickstart.mdx
index e170f5e..e71b0cf 100644
--- a/cli/quickstart.mdx
+++ b/cli/quickstart.mdx
@@ -1,31 +1,38 @@
 ---
 title: 'Quickstart'
-description: 'Authenticate and run your first analysis'
+description: 'Start the live graph watcher'
 icon: 'bolt'
 ---
 
-## 1. Authenticate
+## 1. Run Supermodel in your repo
 
 ```bash
-supermodel login
+cd /path/to/your/repo
+supermodel
 ```
 
-Opens your browser, creates an API key, and saves it to `~/.supermodel/config.yaml`. For CI, pass the key directly:
+On first run, `supermodel` opens the setup flow automatically. It authenticates you, confirms the repo, offers to install the Claude Code hook, and enables `.graph.*` sidecar files.
 
-```bash
-supermodel login --token smsk_live_...
+After setup, the same command starts the live graph watcher:
+
+```text
+[supermodel] [step:1] Building code graph
+[supermodel] [step:2] Starting listeners
+[supermodel] [step:3] Ready — listening on UDP :7734
 ```
 
-## 2. Analyze a repo
+Leave it running while you code. It updates the graph when files change, writes graph sidecars next to source files, and cleans generated sidecars when you stop it with `Ctrl+C`.
+
+## 2. Tell your agent the graph files exist
 
 ```bash
-cd /path/to/your/repo
-supermodel analyze
+supermodel skill >> CLAUDE.md
+# or AGENTS.md, .cursorrules, etc.
 ```
 
-Uploads the repo, runs call graph + dependency + domain analysis, caches the result locally by content hash, and writes `.graph.*` sidecar files next to each source file.
+The prompt explains the naming convention (`Foo.py` → `Foo.graph.py`) and tells your agent to read the graph file before the source file.
 
-## 3. Use the results
+## 3. Use the live graph
 
 | Goal | Command |
 |---|---|
@@ -36,9 +43,19 @@ Uploads the repo, runs call graph + dependency + domain analysis, caches the res
 | Token-efficient context for one file | `supermodel focus path/to/file.go` |
 | Print the full graph | `supermodel graph` |
 
-Subsequent commands reuse the cached graph automatically. Pass `--force` to any command to bypass the cache.
+These commands reuse the cached graph automatically. Pass `--force` to bypass the cache.
+
+## 4. One-shot analysis
+
+Use `analyze` when you want to build or refresh the graph once and exit instead of keeping the watcher running:
+
+```bash
+supermodel analyze
+```
+
+`analyze` uploads the repo, runs call graph + dependency + domain analysis, caches the result locally by content hash, and writes `.graph.*` sidecar files next to source files. Add `--no-shards` to skip writing sidecars.
 
-## 4. Configure (optional)
+## 5. Configure (optional)
 
 Settings live at `~/.supermodel/config.yaml`. Environment variables override file values.
 
diff --git a/index.mdx b/index.mdx
index 1319444..e0788c6 100644
--- a/index.mdx
+++ b/index.mdx
@@ -13,7 +13,7 @@ title: Introduction
 
 ## CLI quickstart
 
-The fastest path: install the binary and run `setup`. The wizard authenticates you, detects your repo, offers to install the Claude Code hook, and starts the live graph daemon — one command, end to end.
+The fastest path: install the binary, go to your repo, and run `supermodel`. On first run it handles setup automatically; after that it starts the live graph watcher.
 
 ### 1. Install
 
@@ -23,21 +23,16 @@ curl -fsSL https://supermodeltools.com/install.sh | sh
 
 Other options: `npm install -g @supermodeltools/cli` or build from source. See [Installation](/cli/install).
 
-### 2. Run the setup wizard
+### 2. Start the live graph watcher
 
 ```bash
 cd /path/to/your/repo
-supermodel setup
+supermodel
 ```
 
-The wizard walks four steps:
-
-1. **Authentication** — opens your browser to create an API key and saves it to `~/.supermodel/config.yaml`.
-2. **Repository** — detects the git root and confirms the directory.
-3. **Agent hook** — if Claude Code is installed, offers to add a `PostToolUse` hook so `.graph.*` files refresh on every `Write`/`Edit`. Cursor, Copilot, Windsurf, and Aider read the files directly — no hook needed.
-4. **Shard mode** — enables writing `.graph.*` sidecars next to your source files.
+If this is your first run, `supermodel` launches setup automatically. It authenticates you, confirms the repo, offers to install the Claude Code hook, and enables writing `.graph.*` sidecars next to source files.
 
-It then runs the live graph daemon for you. Press `Ctrl+C` to stop.
+Then `supermodel` builds the graph and stays running as the live watcher. Press `Ctrl+C` to stop and clean generated sidecars.
 
 ### 3. Tell your agent the sidecars exist
 
@@ -52,7 +47,7 @@ The prompt explains the naming convention (`Foo.py` → `Foo.graph.py`), the thr
 
 ### 4. What you get
 
-After setup runs, each source file gets one `.graph.*` sidecar with dependency, call, and impact sections:
+After the watcher runs, each source file gets one `.graph.*` sidecar with dependency, call, and impact sections:
 
 ```
 src/
@@ -85,7 +80,7 @@ Your agent reads these via `cat` and `grep` like any other file. No prompt chang
 
 ### 5. Keep it running
 
-The bare `supermodel` command is the live graph daemon. Run it any time you want graph files to stay fresh as you code:
+The bare `supermodel` command is the live graph watcher. Run it any time you want graph files to stay fresh as you code:
 
 ```bash
 supermodel

From 8348a2d0fee9e1ec0217f7181c88505bb4efb5c1 Mon Sep 17 00:00:00 2001
From: jonathanpopham <jonathan.popham@gmail.com>
Date: Thu, 30 Apr 2026 18:19:54 -0400
Subject: [PATCH 2/4] docs: address quickstart review comments

---
 cli/quickstart.mdx | 2 +-
 index.mdx          | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/cli/quickstart.mdx b/cli/quickstart.mdx
index e71b0cf..35eaf3f 100644
--- a/cli/quickstart.mdx
+++ b/cli/quickstart.mdx
@@ -68,4 +68,4 @@ shards: true                                 # set false (or SUPERMODEL_SHARDS=f
 
 ## Next
 
-See the [command reference](/cli/commands/analyze) for every command, flag, and example.
+See the [`analyze` command reference](/cli/commands/analyze) for one-shot flags and examples.
diff --git a/index.mdx b/index.mdx
index e0788c6..57b6be6 100644
--- a/index.mdx
+++ b/index.mdx
@@ -86,7 +86,7 @@ The bare `supermodel` command is the live graph watcher. Run it any time you wan
 supermodel
 ```
 
-For one-shot analysis (no daemon), use:
+For one-shot analysis (no watcher), use:
 
 ```bash
 supermodel analyze
@@ -104,4 +104,4 @@ Once a graph is cached, every other command reuses it instantly:
 | Find usages of a symbol | `supermodel find handleRequest` |
 | Token-efficient context for one file | `supermodel focus path/to/file.go` |
 
-See the [command reference](/cli/commands/analyze) for every flag and example.
+Start with the [`supermodel` watcher reference](/cli/commands/supermodel) or the [`analyze` one-shot reference](/cli/commands/analyze).

From e99712a7a73463e12f4b5938b25b6e26b36f2f4b Mon Sep 17 00:00:00 2001
From: jonathanpopham <jonathan.popham@gmail.com>
Date: Thu, 30 Apr 2026 18:22:23 -0400
Subject: [PATCH 3/4] docs: clarify agent prompt append behavior

---
 cli/quickstart.mdx | 2 ++
 index.mdx          | 2 ++
 2 files changed, 4 insertions(+)

diff --git a/cli/quickstart.mdx b/cli/quickstart.mdx
index 35eaf3f..dd68e7d 100644
--- a/cli/quickstart.mdx
+++ b/cli/quickstart.mdx
@@ -30,6 +30,8 @@ supermodel skill >> CLAUDE.md
 # or AGENTS.md, .cursorrules, etc.
 ```
 
+Use `>>` to append to existing instructions instead of replacing them. If the Supermodel block is already present, skip this step or remove the old block before running it again.
+
 The prompt explains the naming convention (`Foo.py` → `Foo.graph.py`) and tells your agent to read the graph file before the source file.
 
 ## 3. Use the live graph
diff --git a/index.mdx b/index.mdx
index 57b6be6..2475e47 100644
--- a/index.mdx
+++ b/index.mdx
@@ -43,6 +43,8 @@ supermodel skill >> CLAUDE.md
 # or AGENTS.md, .cursorrules, etc.
 ```
 
+Use `>>` to append to existing instructions instead of replacing them. If the Supermodel block is already present, skip this step or remove the old block before running it again.
+
 The prompt explains the naming convention (`Foo.py` → `Foo.graph.py`), the three sections inside each sidecar (`[deps]`, `[calls]`, `[impact]`), and tells the agent to read the sidecar before the source file.
 
 ### 4. What you get

From 2ea3bb5e02ac39b8aefa027010a3e2e9f5f1db1e Mon Sep 17 00:00:00 2001
From: jonathanpopham <jonathan.popham@gmail.com>
Date: Thu, 30 Apr 2026 18:26:28 -0400
Subject: [PATCH 4/4] docs: clarify watcher refresh behavior

---
 cli/quickstart.mdx | 6 +++---
 index.mdx          | 6 ++++--
 2 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/cli/quickstart.mdx b/cli/quickstart.mdx
index dd68e7d..24d6faa 100644
--- a/cli/quickstart.mdx
+++ b/cli/quickstart.mdx
@@ -11,9 +11,9 @@ cd /path/to/your/repo
 supermodel
 ```
 
-On first run, `supermodel` opens the setup flow automatically. It authenticates you, confirms the repo, offers to install the Claude Code hook, and enables `.graph.*` sidecar files.
+If no config exists, `supermodel` opens the setup flow automatically. It authenticates you, confirms the repo, offers to install the Claude Code hook, and enables `.graph.*` sidecar files.
 
-After setup, the same command starts the live graph watcher:
+After setup, or on any already configured repo, the same command starts the live graph watcher:
 
 ```text
 [supermodel] [step:1] Building code graph
@@ -21,7 +21,7 @@ After setup, the same command starts the live graph watcher:
 [supermodel] [step:3] Ready — listening on UDP :7734
 ```
 
-Leave it running while you code. It updates the graph when files change, writes graph sidecars next to source files, and cleans generated sidecars when you stop it with `Ctrl+C`.
+Leave it running while you code. It refreshes from hook notifications; if you are not using a hook, run `supermodel --fs-watch` to watch local file changes directly. It writes graph sidecars next to source files and cleans generated sidecars when you stop it with `Ctrl+C`.
 
 ## 2. Tell your agent the graph files exist
 
diff --git a/index.mdx b/index.mdx
index 2475e47..97c7915 100644
--- a/index.mdx
+++ b/index.mdx
@@ -13,7 +13,7 @@ title: Introduction
 
 ## CLI quickstart
 
-The fastest path: install the binary, go to your repo, and run `supermodel`. On first run it handles setup automatically; after that it starts the live graph watcher.
+The fastest path: install the binary, go to your repo, and run `supermodel`. If no config exists, it handles setup automatically; after that it starts the live graph watcher.
 
 ### 1. Install
 
@@ -30,7 +30,7 @@ cd /path/to/your/repo
 supermodel
 ```
 
-If this is your first run, `supermodel` launches setup automatically. It authenticates you, confirms the repo, offers to install the Claude Code hook, and enables writing `.graph.*` sidecars next to source files.
+If no config exists, `supermodel` launches setup automatically. It authenticates you, confirms the repo, offers to install the Claude Code hook, and enables writing `.graph.*` sidecars next to source files.
 
 Then `supermodel` builds the graph and stays running as the live watcher. Press `Ctrl+C` to stop and clean generated sidecars.
 
@@ -88,6 +88,8 @@ The bare `supermodel` command is the live graph watcher. Run it any time you wan
 supermodel
 ```
 
+Live refreshes are driven by hook notifications. If you are not using a hook, run `supermodel --fs-watch` to watch local file changes directly.
+
 For one-shot analysis (no watcher), use:
 
 ```bash