From c8e176bebe2e5453366808727706ada20c41cc89 Mon Sep 17 00:00:00 2001 From: jonathanpopham Date: Wed, 29 Apr 2026 14:07:10 -0400 Subject: [PATCH 1/2] Add CLI quickstart to the welcome page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Verified against the actual CLI: ran 'supermodel analyze' on the cli repo (3207 nodes cached, 178 source files → 151 .graph.* sidecars) and inspected a real sidecar from cmd/login.graph.go. The quickstart leads with 'supermodel setup' because the wizard handles the entire onboarding in one command — auth → repo detect → hook offer → starts the watch daemon. Then shows what a real .graph.go sidecar looks like, and lists the common follow-up commands (dead-code, blast-radius, audit, find, focus). --- index.mdx | 105 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 97 insertions(+), 8 deletions(-) diff --git a/index.mdx b/index.mdx index 0925a1e..3dc3592 100644 --- a/index.mdx +++ b/index.mdx @@ -3,21 +3,110 @@ title: Introduction description: 'Welcome to the Supermodel API documentation' --- +## Documentation Index + +Fetch the complete documentation index at: [https://docs.supermodeltools.com/llms.txt](https://docs.supermodeltools.com/llms.txt) + +Use this file to discover all available pages before exploring further. + ## Welcome Supermodel provides a unified graph representation of your codebase, enabling powerful analysis and visualization tools. - - **Try the API Playground**: Each endpoint in our API Reference includes an interactive playground. To use it, you'll need an API key from the [Supermodel Dashboard](https://dashboard.supermodeltools.com/). - - -## Where to start +Two ways to use it: - - View the OpenAPI specification and endpoints. + + Hit the endpoints directly. Best for SDKs, services, and CI integrations. - Install the Supermodel CLI and start analyzing repositories from your terminal. + A local binary that analyzes your repo and writes graph sidecars next to your source files. Best for day-to-day work in the terminal. + +## 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 watch daemon — one command, end to end. + +### 1. Install + +```bash +curl -fsSL https://supermodeltools.com/install.sh | sh +``` + +Other options: `brew install supermodeltools/tap/supermodel`, `npm install -g @supermodeltools/cli`, or build from source. See [Installation](/cli/install). + +### 2. Run the setup wizard + +```bash +cd /path/to/your/repo +supermodel setup +``` + +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. + +It then runs the watch daemon for you. Press `Ctrl+C` to stop. + +### 3. What you get + +After setup runs, every source file has a sidecar with its call graph, dependencies, and blast-radius data: + +``` +src/ +├── login.go +├── login.graph.go ← generated +├── client.go +└── client.graph.go ← generated +``` + +A real sidecar (excerpt from `cmd/login.graph.go` in the CLI repo itself): + +```go +//go:build ignore +package ignore +// @generated supermodel-shard — do not edit +// [deps] +// imports internal/auth/handler.go +// imported-by main.go +// [calls] +// init → Login internal/auth/handler.go:29 +// [impact] +// risk LOW +// domains CLI +// affects main.go +``` + +Your agent reads these via `cat` and `grep` like any other file. No prompt changes, no extra context windows. + +### 4. Keep it running + +The bare `supermodel` command is the watch daemon. Run it any time you want sidecars to stay fresh as you code: + +```bash +supermodel +``` + +For one-shot analysis (no daemon), use: + +```bash +supermodel analyze +``` + +### 5. What to do with the graph + +Once a graph is cached, every other command reuses it instantly: + +| Goal | Command | +|---|---| +| Find unreachable functions | `supermodel dead-code` | +| See what a change impacts | `supermodel blast-radius path/to/file.go` | +| Codebase health report | `supermodel audit` | +| 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. From 4cf8d8edaa98e9f643cb22b40f37b267b8c3a941 Mon Sep 17 00:00:00 2001 From: jonathanpopham Date: Wed, 29 Apr 2026 14:15:59 -0400 Subject: [PATCH 2/2] Verify welcome quickstart against v0.6.10 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reinstalled the CLI (was on stale v0.5.1 — current latest is v0.6.10 on supermodeltools/cli) and re-ran every step: - All 22 documented subcommands are present in v0.6.10. - Every flag in the per-command pages matches ` --help` exactly. - `supermodel skill` exists and is real — added it to step 3. - `analyze --three-file` produces three separate files (.calls / .deps / .impact), not one .graph file. Replaced the single-file sample with the actual three-file output from `cmd/login.*.go` on the CLI repo (336 shards, 178 source files, 3173 nodes, 7195 relationships). Real sample is verbatim from running the binary, including the "MEDIUM" risk and "CoreConfig · SupermodelAPI" multi-domain format introduced in v0.6.x. --- index.mdx | 47 ++++++++++++++++++++++++++++++++--------------- 1 file changed, 32 insertions(+), 15 deletions(-) diff --git a/index.mdx b/index.mdx index 3dc3592..b9e5e7e 100644 --- a/index.mdx +++ b/index.mdx @@ -52,38 +52,55 @@ The wizard walks four steps: It then runs the watch daemon for you. Press `Ctrl+C` to stop. -### 3. What you get +### 3. Tell your agent the sidecars exist -After setup runs, every source file has a sidecar with its call graph, dependencies, and blast-radius data: +Pipe the awareness prompt into your agent's instructions file: + +```bash +supermodel skill >> CLAUDE.md +# or AGENTS.md, .cursorrules, etc. +``` + +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 + +After setup runs with `--three-file` (recommended), each source file gets three sidecars: ``` src/ ├── login.go -├── login.graph.go ← generated -├── client.go -└── client.graph.go ← generated +├── login.calls.go ← who calls what, with file:line +├── login.deps.go ← imports and imported-by +└── login.impact.go ← risk level, domains, blast radius ``` -A real sidecar (excerpt from `cmd/login.graph.go` in the CLI repo itself): +Real output from running the CLI on its own source (`cmd/login.*.go`): ```go -//go:build ignore -package ignore -// @generated supermodel-shard — do not edit +// cmd/login.deps.go // [deps] +// imports internal/auth/doc.go // imports internal/auth/handler.go // imported-by main.go + +// cmd/login.calls.go // [calls] -// init → Login internal/auth/handler.go:29 +// init → LoginWithToken internal/auth/handler.go:109 +// init → Login internal/auth/handler.go:29 + +// cmd/login.impact.go // [impact] -// risk LOW -// domains CLI +// risk MEDIUM +// domains CoreConfig · SupermodelAPI +// direct 1 +// transitive 1 // affects main.go ``` Your agent reads these via `cat` and `grep` like any other file. No prompt changes, no extra context windows. -### 4. Keep it running +### 5. Keep it running The bare `supermodel` command is the watch daemon. Run it any time you want sidecars to stay fresh as you code: @@ -94,10 +111,10 @@ supermodel For one-shot analysis (no daemon), use: ```bash -supermodel analyze +supermodel analyze --three-file ``` -### 5. What to do with the graph +### 6. What to do with the graph Once a graph is cached, every other command reuses it instantly: