diff --git a/README.md b/README.md
index e1acfc3..0e10b00 100644
--- a/README.md
+++ b/README.md
@@ -2,10 +2,10 @@
# Smith
-**Read-only code investigation for AI coding agents.**
+**Let your AI coding agent investigate code anywhere β without cloning, and without write access.**
-Search code, grep exact lines, inspect PRs, scan CI logs, and look up issues across
-**GitHub**, **GitLab**, **Azure DevOps**, and **YouTrack** from one CLI.
+One CLI to search code, grep exact lines, inspect PRs, scan CI logs, and look up
+issues across **GitHub**, **GitLab**, **Azure DevOps**, and **YouTrack**.
[](LICENSE)
[](https://www.python.org)
@@ -16,50 +16,50 @@ Search code, grep exact lines, inspect PRs, scan CI logs, and look up issues acr
-Smith gives an agent a safe, token-efficient way to answer questions like:
+## What is Smith?
-- Where is this setting defined?
-- Which repos still use this dependency?
-- What changed in this PR?
-- Why did this pipeline fail?
-- Is there an issue or story that explains this work?
+AI coding agents are great at answering questions about the repo in front of
+them β and blind to everything else. The answer to "why did CI fail?" or "which
+repos still use this dependency?" usually lives in *other* repos, PR threads,
+pipeline logs, or an issue tracker.
-It does that without cloning every repo, downloading whole files, or switching
-between provider-specific tools.
+Smith fixes that. It gives your agent **read-only eyes on all your remotes**, so
+it can answer questions like:
-Think of Smith as a read-only remote investigation layer for AI agents: similar
-in spirit to a provider MCP like the GitHub MCP, but optimized for token efficient
-cross-remote search, grep-sized evidence, PR context, CI logs, and issue lookup.
+- π *Where is this setting defined?*
+- π¦ *Which repos still use this dependency?*
+- π *What changed in this PR, and what did reviewers say?*
+- π¦ *Why did this pipeline fail?*
+- π *Is there an issue or story that explains this work?*
-## Why Smith Helps
+β¦and it does so without cloning repos, downloading whole files, or juggling
+provider-specific tools.
-- **Fewer tokens wasted.** Smith returns search hits and grep context windows
- instead of full files.
-- **One workflow across providers.** The same verbs work across GitHub, GitLab,
- Azure DevOps, and YouTrack.
-- **Read-only by contract.** There are no create, update, approve, comment, or
- post commands.
-- **Local credentials.** Tokens stay in your environment, keychain, or provider
- CLI login. Smith is not a hosted proxy.
-- **Agent-ready output.** We emit minimalist compact responses optimised for the LLMs.
+### Why teams like it
-## Golden Paths
+| | |
+|---|---|
+| πͺΆ **Token-efficient** | Returns search hits and grep-sized context windows, not full files. Built for LLM context budgets. |
+| π **One workflow, four providers** | The same verbs (`code search`, `code grep`, `prs`, `pipelines`, `stories`) work on GitHub, GitLab, Azure DevOps, and YouTrack. |
+| π **Read-only by contract** | There are no create, update, approve, comment, or post commands. Smith cannot change anything. |
+| π **Your credentials stay local** | Tokens live in your environment, OS keychain, or provider CLI login. Smith is not a hosted proxy. |
-The first two paths are for you: install Smith and connect your remotes. After
-that, the examples show the behavior encoded in `skills/smith/SKILL.md` β the
-workflow your AI agent should follow once the Smith skill is loaded.
+Think of it as a provider MCP (like the GitHub MCP) reimagined for one job:
+fast, cross-remote, evidence-first investigation.
-### Install and Connect
+## Quick Start
-#### 1. Install Smith
+### 1. Install
-Recommended for macOS and Linux:
+macOS / Linux (recommended):
```bash
brew install faustodavid/tap/smith
-smith config init
```
+
+Other install options (standalone installer, Windows)
+
Standalone installer:
```bash
@@ -72,155 +72,80 @@ Windows PowerShell:
irm https://raw.githubusercontent.com/faustodavid/smith/main/scripts/install.py | python -
```
-`smith config init` syncs the Smith agent skill to `~/.agents/skills/smith`.
-The standalone installer does this during install too. The skill stays current
-on its own after upgrades (set `SMITH_SKILL_CHECK=0` to opt out); to refresh it
-manually run:
-
-```bash
-smith skill sync
-```
-
-#### 2. Add Remotes
-
-`smith config init` starts a guided terminal onboarding flow. It scans for
-existing provider auth, helps add remotes, and can store pasted tokens in the OS
-secure credential store. Token values are never written to `config.yaml`.
-
-To create an empty config for manual editing, run `smith config init --manual`.
-`smith config init --format json` is also noninteractive for automation and
-creates the same empty config shape.
+
-To change remotes later, run `smith config edit`. If you prefer manual edits:
+### 2. Connect your remotes
```bash
-smith config path
-$EDITOR ~/.config/smith/config.yaml
+smith config init
```
-Minimal config shape:
-
-```yaml
-defaults:
- timeout_seconds: 30
- max_output_chars: 20000
-
-remotes:
- github-public:
- provider: github
- org: acme
- enabled: true
-
- gitlab-platform:
- provider: gitlab
- org: acme/platform
- enabled: true
-
- azdo-main:
- provider: azdo
- org: acme
- enabled: true
+This starts a guided onboarding flow: it scans for existing provider auth
+(`gh`, `glab`, `az`, env vars), helps you add remotes, and stores pasted tokens
+in your OS secure credential store β never in the config file.
- youtrack-main:
- provider: youtrack
- host: https://youtrack.acme.com
- enabled: true
-```
+### 3. Let your agent use it
-Set `SMITH_CONFIG=/path/to/config.yaml` when a workspace needs a different
-config file.
+`smith config init` also installs the **Smith agent skill** to
+`~/.agents/skills/smith`, which teaches your AI agent how to investigate:
+search broad, grep for exact proof, then corroborate with PRs, pipelines, or
+issues. The skill keeps itself current after upgrades (set
+`SMITH_SKILL_CHECK=0` to opt out, or run `smith skill sync` to refresh
+manually).
-Auth options:
+That's it β ask your agent a question that spans repos and watch it work.
-- `smith config show ` prints the persisted remote fields only. If
- `token_env` is absent, Smith may still authenticate through runtime fallback
- sources below.
-- `token_env` is optional when a provider has an implicit env fallback or CLI
- login. Add it when you want Smith to read a specific environment variable or
- secure-store entry.
-- GitHub: configured env/secure-store token, public GitHub's implicit
- `GITHUB_TOKEN`, then host-scoped `gh auth token`. GitHub Enterprise uses
- host-scoped `gh` auth unless you configure `token_env`.
-- GitLab: configured env/secure-store token, implicit `GITLAB_TOKEN`, then host-scoped
- `glab config get token`.
-- Azure DevOps: configured `AZURE_DEVOPS_PAT` env/secure-store PAT when
- `token_env` is set, otherwise `az login` / Azure DefaultAzureCredential.
-- YouTrack: configured env/secure-store token, or implicit `YOUTRACK_TOKEN`
- when `token_env` is omitted.
-
-### For Your Agent: Skill-Led Investigation
+## What an Investigation Looks Like
-The Smith skill teaches your AI agent a broad-to-narrow investigation loop:
-search first, avoid full-file reads, extract proof with grep, then corroborate
-with PRs, pipelines, or issues when needed.
+These are the moves the Smith skill teaches your agent (and they work just as
+well typed by hand). Examples assume remotes named `github-public`,
+`gitlab-platform`, `azdo-main`, and `youtrack-main`.
-#### 3. Search Everywhere, Then Narrow
+### Find where something lives
-When you ask an agent where something lives or how something is configured, the
-skill should make it start broad across all enabled remotes:
+Start broad across all enabled remotes, then grep the likely repo for exact
+proof:
```bash
+# Broad: search every remote at once
smith code search "auth middleware" --take 30
smith code search "python==3.10" --glob "pyproject.toml"
-```
-
-After search finds likely repos or paths, the skill should make the agent grep
-the likely repository for exact proof:
-```bash
+# Narrow: grep one repo for the exact lines
smith github-public code grep api-service "timeout_seconds" --path src --context-lines 2
smith gitlab-platform code grep acme/platform/api "resources:" --glob "*.yaml" --context-lines 5
-smith azdo-main code grep SRE api-service "TODO" --path src
```
-For larger areas, the skill can map a subtree before reading matches:
+Map a subtree before reading matches:
```bash
smith github-public code grep api-service ".*" --path src/auth --output-mode files_with_matches
```
-#### 4. Inspect PRs and Review Threads
-
-When your request points at a PR, review, or implementation history, the skill
-guides the agent toward PR search, details, and review threads:
+### Understand a PR
```bash
smith prs search "auth middleware" --status active --exclude-drafts
smith github-public prs list api-service --status active
smith github-public prs get api-service 123
-smith github-public prs threads api-service 123
+smith github-public prs threads api-service 123 # review comments
```
-Provider repo arguments matter. These examples assume remotes named `gh`, `gl`,
-`azdo`, and `yt`:
-
-| Provider | Repo argument shape | Example |
-|---|---|---|
-| GitHub | bare repo name | `smith gh code grep api-service "TODO"` |
-| GitLab | full group/project path | `smith gl code grep acme/platform/api "TODO"` |
-| Azure DevOps | project then repo | `smith azdo code grep SRE api-service "TODO"` |
-| YouTrack | issue IDs and queries only | `smith yt stories get RAD-1055` |
-
-#### 5. Debug a Failing Pipeline
+### Debug a failing pipeline
-When your request is about a CI failure, the skill tells the agent to list the
-run first, then grep logs instead of dumping entire job output:
+List the run first, then grep the logs β never dump entire job output:
```bash
smith github-public pipelines list api-service 123456789
smith github-public pipelines grep api-service 123456789 "error|fatal|Traceback" --reverse --context-lines 3
-```
-Target one job or log when needed:
-
-```bash
+# Target one job or log when needed
smith azdo-main pipelines grep SRE 6789 "timeout" --log-id 42 --context-lines 3
```
-#### 6. Find Issues and Stories
+### Look up issues and stories
-When story or issue context is needed, the skill gives the agent one shape for
-GitHub, GitLab, Azure DevOps, and YouTrack lookups:
+One shape across all four providers:
```bash
smith github-public stories search api-service --query "rate limit"
@@ -229,28 +154,98 @@ smith youtrack-main stories search --query "patch rollout" --state Open
smith youtrack-main stories get RAD-1055
```
+### How each provider names a repo
+
+The only per-provider difference to remember:
+
+| Provider | Repo argument shape | Example |
+|---|---|---|
+| GitHub | bare repo name | `smith gh code grep api-service "TODO"` |
+| GitLab | full group/project path | `smith gl code grep acme/platform/api "TODO"` |
+| Azure DevOps | project, then repo | `smith azdo code grep SRE api-service "TODO"` |
+| YouTrack | issue IDs and queries only | `smith yt stories get RAD-1055` |
+
## Supported Providers
| Provider | Code search | Code grep | PRs / MRs | Pipelines | Issues / stories | Discovery |
|---|---:|---:|---:|---:|---:|---:|
-| GitHub | Yes | Yes | Yes | Yes | Yes | Orgs, repos |
-| GitLab | Yes | Yes | Yes | Yes | Yes | Groups, repos |
-| Azure DevOps | Yes | Yes | Yes | Yes | Yes | Orgs, repos |
-| YouTrack | - | - | - | - | Yes | - |
+| GitHub | β
| β
| β
| β
| β
| Orgs, repos |
+| GitLab | β
| β
| β
| β
| β
| Groups, repos |
+| Azure DevOps | β
| β
| β
| β
| β
| Orgs, repos |
+| YouTrack | β | β | β | β | β
| β |
+
+## Configuration
+
+To change remotes later, run `smith config edit`, or edit the file directly:
+
+```bash
+smith config path
+$EDITOR ~/.config/smith/config.yaml
+```
+
+Minimal config shape:
+
+```yaml
+defaults:
+ timeout_seconds: 30
+ max_output_chars: 20000
+
+remotes:
+ github-public:
+ provider: github
+ org: acme
+ enabled: true
+
+ gitlab-platform:
+ provider: gitlab
+ org: acme/platform
+ enabled: true
+
+ azdo-main:
+ provider: azdo
+ org: acme
+ enabled: true
+
+ youtrack-main:
+ provider: youtrack
+ host: https://youtrack.acme.com
+ enabled: true
+```
+
+Set `SMITH_CONFIG=/path/to/config.yaml` when a workspace needs a different
+config file. To create an empty config for manual editing, use
+`smith config init --manual` (or `--format json` for noninteractive
+automation).
+
+
+How authentication resolves per provider
+
+- `smith config show ` prints the persisted remote fields only. If
+ `token_env` is absent, Smith may still authenticate through the runtime
+ fallbacks below.
+- `token_env` is optional when a provider has an implicit env fallback or CLI
+ login. Add it when you want Smith to read a specific environment variable or
+ secure-store entry.
+- **GitHub:** configured env/secure-store token β public GitHub's implicit
+ `GITHUB_TOKEN` β host-scoped `gh auth token`. GitHub Enterprise uses
+ host-scoped `gh` auth unless you configure `token_env`.
+- **GitLab:** configured env/secure-store token β implicit `GITLAB_TOKEN` β
+ host-scoped `glab config get token`.
+- **Azure DevOps:** configured `AZURE_DEVOPS_PAT` env/secure-store PAT when
+ `token_env` is set, otherwise `az login` / Azure DefaultAzureCredential.
+- **YouTrack:** configured env/secure-store token, or implicit
+ `YOUTRACK_TOKEN` when `token_env` is omitted.
+
+
## Troubleshooting
-- `401` or `403`: check `smith config show ` for persisted fields. If
- the remote has `token_env`, set that env var or store a token with
- `smith config edit`. Otherwise check implicit provider env vars where
- supported (`GITHUB_TOKEN`, `GITLAB_TOKEN`, `YOUTRACK_TOKEN`) and refresh
- provider login/status as appropriate: `gh auth login`,
- `glab auth login --hostname `, or `az login`.
-- `429`: lower `--take`, narrow `--path` or `--glob`, or reduce GitHub grep
- workers with `GITHUB_GREP_MAX_WORKERS`.
-- Truncated output: reduce `--context-lines`, narrow the path, or page with
- `--from-line` and `--to-line`.
-- Empty results: broaden the search query, then grep candidate repos again.
+| Symptom | What to do |
+|---|---|
+| `401` / `403` | Check `smith config show `. If the remote has `token_env`, set that env var or store a token with `smith config edit`. Otherwise check implicit env vars (`GITHUB_TOKEN`, `GITLAB_TOKEN`, `YOUTRACK_TOKEN`) and refresh provider login: `gh auth login`, `glab auth login --hostname `, or `az login`. |
+| `429` rate limited | Lower `--take`, narrow `--path` or `--glob`, or reduce GitHub grep workers with `GITHUB_GREP_MAX_WORKERS`. |
+| Truncated output | Reduce `--context-lines`, narrow the path, or page with `--from-line` and `--to-line`. |
+| Empty results | Broaden the search query, then grep candidate repos again. |
## Development