Use graph when the question is about file/module boundaries, not one symbol.
It builds a reusable map of local import relationships, then lets you focus files inside that map.

Good for:
- mapping an unfamiliar directory or subsystem
- seeing which files are hubs, entrypoints, or leaves
- comparing a few known areas without mapping all src
- choosing files/entities to inspect next
- checking module boundaries when ownership is unclear

Use deps for one entity's outgoing dependencies.
Use usages for real incoming references.
Use graph for file-level connectivity.

Model:
build graph: scope + view + save
query graph: from + focus + output toggles

view controls what enters the saved graph.
focus only expands details for files already inside it.
If focus misses a file, rebuild with wider scope or view.

Default view:
directory scope -> local
file or multiple scopes -> neighbors
from -> uses the saved graph

Views:
local      only files inside scope; best directory map
neighbors  direct import neighborhood; best file-centered map
expanded   wider neighborhood; more output

Scope choice:
scope=src creates a broad reusable map for src.
scope=src/services is cheaper for local work.
scope=[src/services,src/components] compares known areas without mapping all src.

After you understand which graph sections matter, hide the rest with flags or prefs.
Graph can be noisy; shape it for the current task.

Controls:
scope, view, from, focus, symbolUsage, edges, hubs, entrypoints, leaves, exclude, save

Specific:
view         local|neighbors|expanded
from         reuse saved graph index; from=aib:graph:<name>
focus        focus a file inside the graph; focus=path
symbolUsage  show imported symbols on edges; +symbolUsage

edges/hubs/entrypoints/leaves  output section toggles; +name or -name

Run:
aib inspect --stdin

Input:
graph scope=@svc view=local >services-graph
graph from=aib:graph:services-graph focus=[@svc/users.ts,@svc/admins.ts] +symbolUsage -edges

Focus saved graph later:
inspect graph --from-file aib:graph:services-graph --focus @svc/messages.ts --focus @svc/posts.ts --symbol-usage

Inline graph focus can add focus and symbolUsage.
Use DSL, request files, or prefs to hide sections such as edges/hubs/entrypoints/leaves.

Specialized graph command:
Run:
aib inspect graph --stdin

Input:
graph scope=@svc view=local >services-graph
graph from=aib:graph:services-graph focus=[@svc/users.ts,@svc/admins.ts] +symbolUsage -edges

Multiple scopes:
Run:
aib inspect --stdin

Input:
graph scope=[src/main/server,src/services/ws] view=local >server-ws-graph

scope accepts one file/dir or an array.

Skip noisy files:
Run:
aib inspect --stdin

Input:
graph scope=src view=local exclude=["**/*.test.ts","**/* copy.ts"] >src-graph

Graph prefs:
inspect.graph.edges boolean
inspect.graph.hubs boolean
inspect.graph.entrypoints boolean
inspect.graph.leaves boolean
inspect.graph.symbols boolean
inspect.graph.symbolUsage boolean

symbolUsage is usually the better first choice when imported names matter.

Example:
session prefs set inspect.graph.edges false inspect.graph.hubs false inspect.graph.symbolUsage true

Output fields:
summary       file/edge/package counts
paths         compact path aliases used in text output
focus         selected files with imports/importedBy
hubs          highly connected files
entrypoints   scoped files imported by nobody in graph
leaves        scoped files importing nobody in graph
edges         local file-to-file imports
saved         reusable aib:graph handle
