Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

docs: position high-level workflow commands as preferred entry points

riley0227e9231d3d8b6d
diff --git a/AGENTS.md b/AGENTS.md
index f9357d0f..a6b5319a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -53,7 +53,28 @@ Each result entity in `results` includes:
## Command routing
-### Finding code
+### Start here — high-level workflow commands
+
+These are the preferred entry points. Use them first; drop to low-level commands only when you need fine-grained control.
+
+```
+ix impact <target> --format json # Blast radius / dependency consequences
+ix rank --by <metric> --kind <kind> --top N --format json # Hotspot discovery
+ix overview <target> --format json # One-shot structural summary of a component
+ix inventory --kind <kind> --format json # Scoped entity listing
+```
+
+**When to use which:**
+- "What breaks if I change X?" → `ix impact X`
+- "What are the most important classes?" → `ix rank --by dependents --kind class --top 10`
+- "Tell me about UserService" → `ix overview UserService`
+- "List all functions in auth.py" → `ix inventory --kind function --path auth.py`
+
+### Low-level structural primitives
+
+Useful for debugging, fine-grained inspection, or when high-level commands don't cover your case.
+
+#### Finding code
```
ix search <term> --format json --limit 10
ix text <term> --format json --language python
@@ -61,13 +82,13 @@ ix locate <symbol> --format json
ix read <file:lines>
```
-### Understanding entities
+#### Understanding entities
```
ix explain <symbol> --format json
ix entity <id> --format json
```
-### Navigating relationships
+#### Navigating relationships
```
ix callers <symbol> --format json
ix callees <symbol> --format json
@@ -93,10 +114,9 @@ ix diff <from> <to> --format json
## Chaining pattern
-1. Search: `ix search MyClass --format json --limit 5`
-2. Pick the result with `resolved: true` and extract `id`
-3. Drill in: `ix explain MyClass --format json` or `ix entity <id> --format json`
-4. Navigate: `ix callers MyClass --format json`
+1. Start broad: `ix overview MyClass --format json` or `ix impact MyClass --format json`
+2. If you need more detail, drill in: `ix explain MyClass --format json` or `ix entity <id> --format json`
+3. Navigate edges: `ix callers MyClass --format json`
## Handling unresolved references
diff --git a/CLAUDE.md b/CLAUDE.md
index 921e42cf..b94fb62f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -21,7 +21,22 @@ All commands support `--format json` for machine-readable output. Use JSON when
Use bounded, composable CLI commands — never broad queries.
-### Finding & Understanding Code
+### High-Level Workflow Commands (Preferred)
+
+Start here. These aggregate multiple graph operations into single bounded responses.
+
+| Goal | Command | Example |
+|---|---|---|
+| Blast radius / impact | `ix impact` | `ix impact UserService --format json` |
+| Hotspot discovery | `ix rank` | `ix rank --by dependents --kind class --top 10` |
+| One-shot summary | `ix overview` | `ix overview IngestionService --format json` |
+| Scoped entity listing | `ix inventory` | `ix inventory --kind function --path auth.py` |
+
+### Low-Level Primitives
+
+Underlying structural commands — useful for debugging or fine-grained inspection.
+
+#### Finding & Understanding Code
| Goal | Command | Example |
|---|---|---|
| Find entity by name | `ix search` | `ix search IngestionService --kind class --limit 10` |
@@ -31,7 +46,7 @@ Use bounded, composable CLI commands — never broad queries.
| Fast text search | `ix text` | `ix text "verify_token" --language python --limit 20` |
| Find symbol (graph+text) | `ix locate` | `ix locate AuthProvider --limit 10` |
-### Navigating Relationships
+#### Navigating Relationships
| Goal | Command | Example |
|---|---|---|
| What calls a function | `ix callers` | `ix callers verify_token --format json` |
@@ -64,24 +79,28 @@ Use bounded, composable CLI commands — never broad queries.
**"How does ingestion work?"**
```bash
-ix search IngestionService --kind class --format json
-ix explain IngestionService --format json
+ix overview IngestionService --format json # start here
+# If you need more detail:
ix contains IngestionService --format json
ix callees parseFile --format json
```
**"What depends on verify_token?"**
```bash
-ix depends verify_token --format json
+ix impact verify_token --format json # one-shot answer
# or manually:
ix callers verify_token --format json
ix imported-by verify_token --format json
```
-**"List all files and their imports"**
+**"What are the most important classes?"**
+```bash
+ix rank --by dependents --kind class --top 10 --format json
+```
+
+**"List all functions"**
```bash
-ix search "" --kind file --limit 50 --format json
-ix imports <filename> --format json # for each file
+ix inventory --kind function --format json
```
### Best Practices
@@ -95,7 +114,6 @@ ix imports <filename> --format json # for each file
## Do NOT Use
- `ix query` — deprecated, produces oversized low-signal responses
- MCP tools (`ix_query`, `ix_search`, etc.) — deprecated, use CLI instead
-- Broad repo-wide inventory queries
- NLP-style QA in a single command
## Confidence Scores
diff --git a/README.md b/README.md
index a65ba600..30bc2a87 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,7 @@ MCP is still present for compatibility, but the primary interface is `ix` CLI co
- File ingestion: `.py`, `.ts`, `.tsx`, `.scala`, `.sc`, `.json`, `.yaml`, `.yml`, `.toml`, `.md`
- Graph navigation: search, explain, callers/callees, imports/imported-by, contains, depends
+- High-level workflow: impact analysis, hotspot ranking, one-shot overviews, scoped inventory
- Decision and intent tracking: `ix decide`, `ix decisions`, `ix truth ...`
- Provenance + history: `ix patches`, `ix history`, `ix diff`, `ix conflicts`
- GitHub ingestion: `ix ingest --github owner/repo` (issues/PRs/commits/comments)
@@ -81,8 +82,13 @@ ix ingest ./src --recursive
All commands support `--format json`.
```bash
-ix status
-ix ingest ./src --recursive
+# Start with high-level workflow commands
+ix overview UserService # one-shot summary
+ix impact UserService # what depends on it
+ix rank --by dependents --kind class --top 10 # most important classes
+ix inventory --kind function --path "src/" # list functions
+
+# Low-level primitives for fine-grained inspection
ix search IngestionService --kind class --format json
ix explain IngestionService --format json
ix callers parseFile --format json