@automaton-labs/aib 0.0.6 → 0.0.7

package/dist/help/{json/bootstrap.md → bootstrap.bash.md}

@@ -1,34 +1,40 @@
-AIB
-
-aib is a local CLI for TS/JS code work backed by IDE and TypeScript APIs.
-It can inspect symbols, usages, dependencies, duplicates, focused code, and run IDE-backed mutations.
+AIB
+
+aib is a local CLI for TS/JS code work backed by IDE and TypeScript APIs.
+It can inspect symbols, usages, dependencies, duplicates, focused code, and run IDE-backed mutations.
+
+aib is designed for agent workflows:
+batch requests, compact text output, session handles, and reusable artifacts.
 
-aib is designed for agent workflows:
-batch requests, compact text output, session handles, captured inputs, and reusable outputs.
+Inline commands omit the aib prefix.
+When you see:
+session clear
 
-Inline commands omit the aib prefix.
-When you see:
-session prefs get
-
-Run:
-aib session prefs get
+Run:
+aib session clear
 
 Stdin examples show command and input separately to avoid shell-specific syntax.
 Stdin Run lines include the aib prefix to avoid confusion.
 
-{{stdin.examples}}
+Bash/Zsh:
+aib <command> --stdin <<'EOF'
+<input>
+EOF
+
+aib inspect --stdin <<'EOF'
+tree . +onlyDirs limit=20
+EOF
 
 Basics
 
-Use the active session while you work.
-Reuse captured inputs when editing them is cheaper than rebuilding large JSON.
+Use the active session while you work.
 
 Examples are patterns, not limits.
 Feature sections show common high-value uses, not every valid use.
 Adapt requests to the task: combine features, batch related questions, and skip steps when you already have enough context.
 
-Prefer batch JSON instead of inline calls.
-One request can inspect/mutate several files/entities and save reusable outputs.
+Prefer batch DSL instead of one-off inline calls.
+One request can inspect/mutate several files/entities and save reusable artifacts when supported.
 Use one-off commands only for small checks/changes.
 
 For mutations, aib asks TS/IDE refactors to update affected references and imports.
@@ -60,7 +66,7 @@ Use normal text search when the question is just text.
 
 For a first pass in a new codebase, map directories before reading files:
 
-tree src depth=5 +onlyDirs limit=200
+aib inspect tree src --depth 5 --only-dirs --limit 200
 
 Start compact for broad scans.
 Use summary, locations, or local graph views first when output could be large.
@@ -70,10 +76,6 @@ If output hides data and shows `view: aib:res_<id>`, use `aib view ...` to fetch
 Compact output is a starting point, not a substitute for needed code.
 Fetch exact code when correctness depends on implementation details.
 
-Use prefs when the current phase repeats the same output shape.
-Turn details off when they stop helping.
-Turn them back on when they matter.
-
 For mutation commands, set the shell/tool harness timeout to 3 minutes.
 
 If a mutation command times out or returns no final output, use:
@@ -99,7 +101,7 @@ If move/modulePlan imports do not match the repo style, run:
 aib help config-setup.import-rules
 
 If you are about to change import style across files, add or adopt tsconfig aliases, or clean imports repeatedly, run:
-aib help config-setup.import-normalize
+aib help config-setup.import-normalize imports.normalize
 
 If tree/graph output includes known repo noise, run:
 aib help config-setup.excludes
@@ -194,7 +196,7 @@ Start by creating or selecting your session.
 Create it once, then reuse it.
 Do not create a new session for every command or subtask.
 
-Session stores captured inputs, saved outputs, aliases, and prefs.
+Session stores saved artifacts and aliases.
 
 Prefer short session names:
 aa, tr, qa, a2
@@ -209,7 +211,7 @@ aib -s <name> <command>
 Or bind this shell:
 AIB=<name>
 
-If you want to prune session inputs/outputs, use:
+If you want to prune session data, use:
 session clear
 
 After clear, keep using the same session.
@@ -222,62 +224,6 @@ Reusable index handles look like:
 
 Pass index handles back to the matching inspect command with `--from-file` or `from` in DSL.
 
-Every JSON stdin/from request is captured in the active session.
-
-Latest captured input:
-<session-dir>/inputs/<kind>/_last.json
-
-Handle:
-aib:input:<kind>:last
-
-Use --from when editing the captured input costs less than rebuilding the request.
-This is usually true for large batches, partial failures, or multi-step mutation plans.
-For small one-off requests, write a corrected request instead.
-
-Example:
-A refactor batch moves symbols into 5 files.
-The first 2 moves are done, and the 3rd fails in TypeScript.
-Edit <session-dir>/inputs/refactor/_last.json:
-- remove the already completed moves
-- change or remove the failed move
-- keep the remaining moves
-
-Then rerun:
-aib refactor batch <command> --from aib:input:refactor:last
-
-Prefs
-
-Prefs change defaults for the active session.
-Use them when you want repeated CLI behavior without repeating request fields.
-
-Set prefs:
-session prefs set <name> <value> [<name> <value>...]
-
-Example:
-session prefs set inspect.graph.hubs false inspect.graph.leaves false
-
-Show prefs:
-session prefs get [prefix] [--all]
-
-By default, get shows session overrides.
---all includes defaults.
-prefix filters keys.
-
-boolean = true|false
-N = integer
-
-Available prefs:
-inspect.code.maxNonEmptyLines N
-inspect.usages.maxLocations N
-inspect.usages.maxCodeBlocks N
-inspect.members.maxItems N
-inspect.members.all boolean
-inspect.graph.hubs boolean
-inspect.graph.entrypoints boolean
-inspect.graph.leaves boolean
-inspect.graph.edges boolean
-inspect.graph.symbolUsage boolean
-
 Selectors identify symbols when names are ambiguous.
 Use plain names when they are unambiguous.
 Use selectors when aib reports ambiguity or when different symbol kinds share a name.
@@ -296,9 +242,10 @@ c-Name  class
 i-Name  interface
 t-Name  type
 v-name  variable
-e-Name  enum
-m-name  method, usually with parent in JSON
-p-name  property, usually with parent in JSON
+e-Name  enum
+ns-Name namespace
+m-name  method, usually with parent
+p-name  property, usually with parent
 
 DSL request model:
 - directives set defaults for following requests
@@ -310,9 +257,10 @@ DSL request model:
 - For one-off file operations, pass the path directly.
 
 Syntax:
-@file <path>               default file
-@source <path>             default sourceFile for mutations
-op arg arg key=value       request
+@file <path>               default file
+@source <path>             default sourceFile for mutations
+@base <dir>                default base dir for file mutations
+op arg arg key=value       request
 +flag                      boolean true
 -flag                      boolean false
 >name                      save reusable artifact when supported
@@ -354,67 +302,51 @@ local import cycles              cycles
 Cycles are available but not expanded in bootstrap:
 aib help inspect.cycles
 
-Prefer one batch JSON request for related questions.
-Top-level fields are defaults for every request.
-A request without op uses the top-level op.
-A request without file/scope/target uses the top-level value when applicable.
-Each request may override any default.
-
-Batch example:
-
-Run:
-aib inspect --stdin
-
-Input:
-{
-  "file": "src/service.ts",
-  "requests": [
-    { "op": "file" },
-    { "op": "members", "entity": "Service" },
-    {
-      "op": "code",
-      "entities": [
-        { "parent": "Service", "entities": ["render", "reset"] },
-        "normalize"
-      ],
-      "show": true,
-      "save": "service-focus"
-    },
-    {
-      "op": "usages",
-      "target": "src/service.ts",
-      "entity": "normalize",
-      "scope": "src",
-      "detail": "locations"
-    },
-    {
-      "op": "duplicates",
-      "scope": "src/scripts",
-      "detail": "summary",
-      "limit": 20
-    }
-  ]
-}
+Prefer one batch DSL request for related questions.
+
+Batch example:
+
+Run:
+aib inspect --stdin
 
-Inspect controls:
-
-file        default file for requests
-target      file, dir, or symbol area to analyze
-scope       where to search; JSON scope:string|string[]
-entity      one symbol
-entities    several target symbols; JSON entities:[...]
-parent      class/interface parent for methods/properties
-ranges      include line/range metadata; JSON ranges:boolean; CLI --ranges
-localOnly   show local declarations and reexports without resolving facade API; JSON localOnly:boolean; CLI --local-only
-resolveStar resolve export * through re-exported modules; JSON resolveStar:boolean; CLI --resolve-star
-limit       max items in one page; JSON limit:N; CLI --limit N
-offset      page offset; JSON offset:N; CLI --offset N
-all         return all items; JSON all:boolean; CLI --all
-detail      output level; JSON detail:summary|locations|code; CLI --detail summary|locations|code
-show        include code output; JSON show:boolean; CLI --show
-save        save reusable output; JSON save:"name"; CLI --save name
-exclude     skip names/selectors; JSON exclude:[...]
-kinds       restrict selector kinds; JSON kinds:["f","t"]
+Input:
+@file @svc/service.ts
+file
+file @svc/serviceB.ts
+members Service
+code entities=[Service.{render,reset},normalize,default,IIFE#1]
+code @svc/serviceC.ts ServiceC -ranges
+usages target=@svc/service.ts normalize scope=src detail=loc
+duplicates scope=src/scripts detail=sum limit=20
+
+How inheritance works above:
+@file sets the default file for following file-like inspect requests.
+file uses @svc/service.ts.
+file @svc/serviceB.ts overrides the default for that one request.
+members Service uses @svc/service.ts because it has no file override.
+code entities=[...] also uses @svc/service.ts.
+code @svc/serviceC.ts ServiceC overrides the file and disables ranges for that request.
+usages sets its own target/scope/detail because it searches references instead of reading the default file.
+duplicates sets its own scope because it scans a directory.
+
+Inspect request fields:
+
+file      source file; first positional path, @file path, or file=path
+target    file or directory to analyze; target=path
+scope     where to search; scope=path or scope=[a,b]
+entity    one symbol selector; entity=name or positional selector
+entities  several symbol selectors; entities=[...] or positional selectors
+parent    parent class/interface for methods/properties; Parent.member or parent=Name
+ranges    include line/range metadata
+exclude   skip paths or names depending on operation; exclude=[...]
+detail    output level; detail=sum|loc|code
+all       return all items; +all
+limit     max items in one page; limit=N
+offset    page offset; offset=N
+save      save reusable artifact where supported; >name
+
+Operation sections list their supported controls.
+Specific explains controls whose meaning is local to that operation.
 
 Inspect File
 
@@ -423,8 +355,9 @@ Exported declarations are marked in the output.
 It shows what lives in the file before you decide whether to read code.
 
 Good for:
-- mapping an unfamiliar file
+- mapping a file
 - listing top-level declarations
+- seeing default exports, decorators, IIFEs, and runtime calls
 - checking whether a file contains real declarations or mostly re-exports
 
 Do not add limit just in case.
@@ -443,15 +376,9 @@ Use -ranges to show names without ranges.
 Run:
 aib inspect --stdin
 
-Input:
-{
-  "op": "file",
-  "file": "src/service.ts",
-  "requests": [
-    { "ranges": true },
-    { "file": "src/index.ts", "localOnly": true }
-  ]
-}
+Input:
+file @svc/service.ts +localOnly
+file src/index.ts
 
 inspect file src/service.ts [--ranges] [--local-only]
 
@@ -501,14 +428,8 @@ Run:
 aib inspect --stdin
 
 Input:
-{
-  "op": "exports",
-  "file": "src/service.ts",
-  "requests": [
-    { "ranges": true },
-    { "file": "src/index.ts", "resolveStar": true }
-  ]
-}
+exports src/service.ts +ranges
+exports src/index.ts +resolveStar
 
 inspect exports src/service.ts [--ranges] [--resolve-star]
 
@@ -528,16 +449,8 @@ file, entity, entities, ranges, limit, offset, all
 Run:
 aib inspect --stdin
 
-Input:
-{
-  "file": "src/service.ts",
-  "op": "members",
-  "limit": 12,
-  "requests": [
-    { "entity": "Service" },
-    { "entities": ["ServiceOptions", "WsOptions"], "all": true }
-  ]
-}
+Input:
+members @svc/service.ts entities=[Service,ServiceOptions] +all +ranges
 
 inspect members src/service.ts Service [--limit N] [--offset N] [--all] [--ranges]
 
@@ -547,7 +460,7 @@ Use code to fetch exact declarations or members.
 It returns focused code without reading the whole file.
 
 Good for:
-- reading a known function, class, method, or declaration
+- reading a known function, class, method, declaration, `default`, or `IIFE#N`
 - fetching several related code blocks in one request
 - keeping context focused on code needed for the current task
 
@@ -561,55 +474,33 @@ Defaults: +show +ranges
 Use -show for names/ranges only.
 Use -ranges for source without ranges.
 
-Run:
-aib inspect --stdin
-
-Input:
-{
-  "file": "src/service.ts",
-  "op": "code",
-  "requests": [
-    {
-      "entities": [
-        { "parent": "Service", "entities": ["render", "reset"] },
-        "normalize"
-      ],
-      "show": true,
-      "save": "service-focus"
-    }
-  ]
-}
+Run:
+aib inspect --stdin
+
+Input:
+code @svc/service.ts Service.{render,reset} normalize
+code @svc/serviceB.ts ServiceB.{constructor} default IIFE#1
 
 Inspect Deps
 
 Use deps to see what one entity depends on inside its file.
 It separates type-only dependencies from runtime value dependencies.
 
-Good for:
-- checking what a symbol may need when moved or extracted
-- spotting nearby types, constants, or helpers tied to one entity
-- deciding whether one symbol is standalone or tied to nearby declarations
+Good for:
+- checking what a symbol may need when moved or extracted
+- spotting nearby types, constants, or helpers tied to one entity
+- deciding whether one symbol is standalone or tied to nearby declarations
 - debugging mutation failures caused by local dependency shape
 
 Controls:
 file, entity, entities, parent
 
-Run:
-aib inspect --stdin
-
-Input:
-{
-  "file": "src/service.ts",
-  "op": "deps",
-  "requests": [
-    { "entity": "createService" },
-    {
-      "entities": [
-        { "parent": "Service", "entities": ["render", "reset"] }
-      ]
-    }
-  ]
-}
+Run:
+aib inspect --stdin
+
+Input:
+deps @svc/service.ts entities=[createService,normalize,Service.{render,reset}]
+deps @svc/serviceB.ts ServiceB.{constructor} getConfig
 
 Inspect Usages
 
@@ -624,8 +515,8 @@ Good for:
 - confirming whether extracted or renamed code still has callers
 - getting caller locations or caller code without broad file scans
 
-Use locations for broad impact checks.
-Use code when usage count is small or caller context matters now.
+Use detail=code directly when you already need caller code.
+Use detail=loc + save when the first question is impact shape and you may expand only part of it later.
 
 Controls:
 target, scope, entity, entities, parent, detail, limit, all, save, includeTarget
@@ -637,17 +528,10 @@ Run:
 aib inspect --stdin
 
 Input:
-{
-  "op": "usages",
-  "target": "src/service.ts",
-  "entities": [
-    "createService",
-    { "parent": "Service", "entities": ["render", "reset"] }
-  ],
-  "scope": ["src/app", "src/tests"],
-  "detail": "locations",
-  "save": "service-usages"
-}
+usages target=@svc/service.ts entities=[createService,normalize,Service.{render,reset}] scope=[src/app,src/tests] detail=loc >service-usages
+
+Expand saved usages when needed:
+inspect usages --from-file aib:usages:service-usages --focus createService --detail code --limit 20
 
 Inspect Graph
 
@@ -667,7 +551,7 @@ Use graph for file-level connectivity.
 
 Model:
 build graph: scope + view + save
-query graph: fromFile + focus + output toggles
+query graph: from + focus + output toggles
 
 view controls what enters the saved graph.
 focus only expands details for files already inside it.
@@ -676,7 +560,7 @@ If focus misses a file, rebuild with wider scope or view.
 Default view:
 directory scope -> local
 file or multiple scopes -> neighbors
-fromFile -> uses the saved graph
+from -> uses the saved graph
 
 Views:
 local      only files inside scope; best directory map
@@ -684,11 +568,11 @@ 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: [...] compares known areas without mapping all src.
+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 JSON fields or prefs.
+After you understand which graph sections matter, hide the rest with flags.
 Graph can be noisy; shape it for the current task.
 
 Controls:
@@ -706,29 +590,14 @@ Run:
 aib inspect --stdin
 
 Input:
-{
-  "op": "graph",
-  "requests": [
-    {
-      "scope": "src/services",
-      "view": "local",
-      "save": "services-graph"
-    },
-    {
-      "fromFile": "aib:graph:services-graph",
-      "focus": ["src/services/users.ts", "src/services/admins.ts"],
-      "symbolUsage": true,
-      "edges": false
-    }
-  ]
-}
+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 src/services/messages.ts --focus src/services/posts.ts --symbol-usage
+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.
-Inline cannot hide graph sections such as edges/hubs/entrypoints/leaves.
-Use JSON request fields or prefs for section control.
+Inline graph focus can add focus and symbolUsage.
+Use DSL or request flags to hide sections such as edges/hubs/entrypoints/leaves.
 
 Inspect Tree
 
@@ -777,30 +646,37 @@ Run:
 aib inspect --stdin
 
 Input:
-{
-  "scope": "src",
-  "detail": "summary",
-  "limit": 20
-}
+duplicates scope=src detail=sum exclude=[config,baseUrl] kinds=[t,i] limit=20
+duplicates scope=@svc detail=loc pathExclude=[src/generated,"**/* copy.ts"] limit=20
 
 Mutation
 
-Mutation commands change code through TS/IDE refactors.
-Successful mutations update affected references and imports.
-
+Mutation commands change code and files through TS/IDE-backed operations.
+Successful mutations update affected references and imports.
+
+Semantic mutations change TypeScript symbols/declarations.
+File mutations change file layout.
+
 After a successful mutation, do not manually patch the same imports unless aib reports a follow-up or checks show a real issue.
 
-If move/modulePlan imports do not match the repo style, run:
+If mutation imports do not match the repo style, run:
 aib help config-setup.import-rules
 
-AIB mutations are designed to reduce manual checking.
-Your job is to express the intent in DSL.
-AIB's job is to convert that intent into code changes.
-
-Do not read all changed files just because a mutation touched them.
-That defeats the purpose of using AIB for mechanical refactors.
-
-If the command succeeds, the requested mechanical change was applied.
+AIB mutations are designed to reduce manual checking.
+Your job is to express the intent in DSL.
+AIB's job is to convert that intent into code changes.
+
+Choose the mutation by intent:
+rename - rename TypeScript symbols
+move toFile - move TypeScript declarations into one file
+modulePlan - split one source file into several modules
+file move toDir - move whole files into directories
+file rename - rename whole files.
+
+Do not read all changed files just because a mutation touched them.
+That defeats the purpose of using AIB for mechanical refactors.
+
+If the command succeeds, the requested mechanical change was applied.
 After failure or partial success, use the output to decide the next request.
 
 When running mutation commands, set the harness timeout to 3 minutes.
@@ -813,7 +689,7 @@ preview  inspect planned edits, then apply by id
 apply    write a previewed change
 execute  write immediately
 
-Use execute for routine rename/move/modulePlan requests.
+Use execute for routine requests.
 
 Use preview/apply when you are learning a mutation command, or when one request contains a large multi-step change that you want to inspect before writing files.
 Typical examples: a huge modulePlan or refactor batch.
@@ -822,13 +698,10 @@ preview/apply uses more tool calls and more output tokens.
 preview validates input and planned edits, but writing files can still hit a TS/IDE refactor error.
 execute writes immediately and reports what changed.
 
-If a mutation cannot be completed, aib reports the failed part and the captured input.
-For large or partial requests, edit the captured input and rerun the remaining or changed intent.
-For small requests, write a corrected request instead.
+If a mutation cannot be completed, aib reports the failed part.
 
-Prefer batch JSON for related mutations.
-One request can describe several related changes.
-aib captures JSON input automatically so large failed or partial requests can be edited and rerun.
+Prefer batch DSL for related mutations.
+One request can describe several related changes.
 
 When a batch mutation partly fails, split the next request by failure type.
 
@@ -847,13 +720,8 @@ Run:
 aib rename execute --stdin
 
 Input:
-{
-  "file": "src/service.ts",
-  "renames": {
-    "oldName": "newName",
-    "OldService": "NewService"
-  }
-}
+@file src/service.ts
+rename oldName->newName OldService->NewService
 
 Move
 
@@ -869,12 +737,9 @@ Move several entities into one target:
 Run:
 aib move toFile execute --stdin
 
-Input:
-{
-  "sourceFile": "src/service.ts",
-  "targetFile": "src/service.helpers.ts",
-  "entities": ["oldHelper", "OtherHelper"]
-}
+Input:
+@source src/service.ts
+move src/service.helpers.ts: oldHelper OtherHelper
 
 Module Plan
 
@@ -886,7 +751,7 @@ modulePlan orchestrates semantic moves and updates affected references/imports.
 If imports created by modulePlan do not match the repo style, run:
 aib help config-setup.import-rules
 
-Use expectEmpty when your modulePlan intent is to move all declarations out of the source file.
+Use +expectEmpty when your modulePlan intent is to move all declarations out of the source file.
 It does not change the move behavior; it only asks output to report remaining source declarations if any remain.
 Use it only when remaining declarations would mean the split did not match your intent.
 Do not use it for partial extractions.
@@ -895,21 +760,15 @@ Split one large source file into several targets:
 Run:
 aib modulePlan execute --stdin
 
-Input:
-{
-  "sourceFile": "src/large-service.ts",
-  "expectEmpty": true,
-  "modules": [
-    {
-      "target": "src/large-service.types.ts",
-      "entities": ["ServiceOptions", "ServiceMode"]
-    },
-    {
-      "target": "src/large-service.core.ts",
-      "entities": ["LargeService", "createLargeService"]
-    }
-  ]
-}
+Input:
+@source src/large-service.ts +expectEmpty
+module src/large-service.types.ts: ServiceOptions ServiceMode
+module src/large-service.core.ts: LargeService createLargeService
+
+How inheritance works above:
+@source sets the source file once.
++expectEmpty says no declarations should remain in the source after the plan.
+Each module line declares one target and the entities that should move there.
 
 Refactor Batch
 
@@ -924,77 +783,33 @@ Example: rename and move in one request
 Run:
 aib refactor batch execute --stdin
 
-Input:
-{
-  "sourceFile": "src/service.ts",
-  "requests": [
-    {
-      "op": "rename",
-      "renames": {
-        "oldHelper": "newHelper",
-        "oldType": "newType"
-      }
-    },
-    {
-      "op": "move",
-      "targetFile": "src/service.helpers.ts",
-      "entities": ["newHelper"]
-    },
-    {
-      "op": "move",
-      "targetFile": "src/service.types.ts",
-      "entities": ["newType"]
-    }
-  ]
-}
+Input:
+@source src/service.ts
+rename oldHelper->newHelper oldType->newType
+move src/service.helpers.ts: newHelper
+move src/service.types.ts: newType
 
-Imports Normalize
+This keeps related mutation intent together:
+rename first, then move the renamed symbols.
 
-Use imports normalize for explicit import-style cleanup.
-It rewrites resolved local import/export specifiers inside a chosen file or directory.
-
-Use importNormalize in aib.json for repeated defaults.
+File Move and File Rename
 
-Good for:
-- converting one area to aliases or relative imports
-- cleaning import style after manual edits or broad refactors
-- applying the same import style to a directory without hand-editing files
-- applying new tsconfig aliases after they are added
-
-Controls:
-scope        file/dir scope to normalize
-to           relative|alias|shortestAlias
-preferAlias  select one tsconfig paths pattern when several aliases can resolve the same file
-exclude      files, directories, or glob-like patterns to skip
-all          show all planned edits; avoid on broad directory scopes
+Use file move/rename when the filesystem layout is the intent.
+Do not change filesystem layout manually.
 
-Run:
-aib imports normalize preview --stdin
-
-Input:
-{
-  "scope": "src/services",
-  "to": "shortestAlias",
-  "exclude": ["src/services/generated", "**/* copy.ts"]
-}
-
-Rewrite imports found inside src/core.
-When an imported file can be expressed through @features/*, prefer that alias.
-
-Run:
-aib imports normalize preview --stdin
-
-Input:
-{
-  "scope": "src/core",
-  "to": "alias",
-  "preferAlias": "@features/*"
-}
-
-With matching importNormalize config for this scope or a parent scope, use inline CLI commands:
-
-imports normalize preview @svc
-imports normalize execute @svc
+Focused topics:
+aib help file.move file.rename
+
+Layout smell trigger:
+If a directory has many related files sharing a prefix, mixed responsibilities, or files that should be grouped by feature, read:
+aib help recipe.file-layout
+
+Imports Normalize
+
+Use imports normalize for explicit import-style cleanup.
+
+Focused topic:
+aib help imports.normalize
 
 JS/TS compatibility
 
@@ -1053,30 +868,37 @@ For focused text reads, prefer qr over cat/Get-Content/type, especially when ali
 Use shell reads only when piping into shell tooling or qr is unavailable.
 
 Controls:
--h N    head; first N lines
--t N    tail; last N lines
--o N    offset; starting line, 1-based
--l N    limit; line count for offset reads
--a      all; whole file
+h=N        head; first N lines
+t=N        tail; last N lines
+o=N l=N    range; starting line and line count
+all        whole file
 
-If no window is provided, qr uses -h 80.
-If -a is present, it wins over other window flags.
+If no window is provided, qr uses h=80.
+If all is present, it wins over other window flags.
 
-Run:
-aib qr --stdin
+Inline:
+aib qr @scripts/a.txt h=80 @scripts/b.py o=300 l=50 @logs/app.log all
 
-Input:
-qr @scripts/a.txt h=80
-qr @scripts/b.py o=300 l=50
-qr @scripts/c.md t=120
-qr @logs/app.log all
+aib rg
 
-Inline:
-aib qr @scripts/a.txt -h 80
-aib qr @scripts/b.py -o 300 -l 50
-aib qr @logs/app.log -a
+Run ripgrep through AIB.
+
+Regular rg:
+  rg <args>
+
+AIB rg:
+  aib rg -- <args>
+
+Everything after `--` is passed as normal ripgrep arguments.
+Use the same args you would pass to `rg`.
+Use normal paths in input. Do not use AIB path aliases here.
+
+Examples:
+  rg -n "TODO" src/core
+  aib rg -- -n "TODO" src/core
 
-Use stdin for several reads.
+  rg -n --column "SomeValue" ws/commands ws/config
+  aib rg -- -n --column "SomeValue" ws/commands ws/config
 
 Need to see TypeScript configs in the repo:
 aib reveal tsconfigs