@automaton-labs/aib 0.0.1

package/dist/help/json/bootstrap.md

@@ -0,0 +1,1074 @@
+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, captured inputs, and reusable outputs.
+
+Inline commands omit the aib prefix.
+When you see:
+session prefs get
+
+Run:
+aib session prefs get
+
+Stdin examples show command and input separately to avoid shell-specific syntax.
+Stdin Run lines include the aib prefix to avoid confusion.
+
+PowerShell stdin shape:
+@'
+<input>
+'@ | aib <command> --stdin
+
+Basics
+
+Use the active session while you work.
+Reuse captured inputs when editing them is cheaper than rebuilding large JSON.
+
+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.
+Use one-off commands only for small checks/changes.
+
+For mutations, aib asks TS/IDE refactors to update affected references and imports.
+After a successful mutation, do not manually patch the same imports unless aib reports a follow-up or the build/checks show a real issue.
+
+Working patterns
+
+Use aib before broad file reads when the question is about TS/JS structure, references, dependencies, or focused code.
+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
+
+Start compact for broad scans.
+Use summary, locations, or local graph views first when output could be large.
+Expand to code or wider graph views only for the parts that matter now.
+If output hides data and shows `view: aib:res_<id>`, use `aib view ...` to fetch only the hidden part instead of repeating the original request.
+
+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:
+
+aib execution status last
+
+This is an escape hatch for recovering the latest mutation status/result.
+
+Before repeated mutation work, check aib config:
+
+aib config
+
+Set pathAliases for repeated request paths.
+Set importRules so move/modulePlan create imports in the project style.
+
+This avoids repeating long paths in requests and avoids manual import cleanup after mutations.
+Do this before large move/modulePlan work, not after cleanup becomes repetitive.
+
+Example aib.json config:
+
+{
+  "pathAliases": {
+    "svc": "src/services",
+    "cli": "packages/cli/src",
+    "ext": "packages/extension/src"
+  },
+  "importRules": [
+    {
+      "scope": ".",
+      "specifier": "shortest",
+      "ending": "auto",
+      "builtin": "bare",
+      "unusedImports": "remove"
+    }
+  ],
+  "importNormalize": [
+    {
+      "scope": "src",
+      "to": "shortestAlias",
+      "exclude": ["src/generated"]
+    }
+  ],
+  "inspect.graph.exclude": [
+    "**/* copy.ts"
+  ]
+}
+
+pathAliases define short request aliases for paths agents repeat in aib commands.
+Use them to reduce input tokens for repeated inspect and mutation work.
+
+Aliases are for aib request paths. They do not change TypeScript imports by themselves.
+For import style after mutations, use importRules.
+
+importRules control imports created or expanded by move/modulePlan mutation cleanup.
+They do not rewrite the whole project.
+
+AIB starts from IDE/TS import preferences.
+For mutation cleanup, matching importRules in aib.json take priority.
+
+Do not assume IDE/TS defaults match the repo style.
+Set importRules before large move/modulePlan work so imports do not need manual cleanup.
+
+Fields:
+scope      repo-relative file or directory scope; most specific scope wins
+specifier  relative|shortest|project-relative|non-relative
+ending     auto|minimal|index|js
+builtin    node|bare
+unusedImports  remove|preserve
+
+Defaults:
+specifier omitted      IDE/TS decides
+ending omitted         IDE/TS decides
+builtin omitted        keep TS/project builtin style
+unusedImports omitted  keep unused imports
+
+specifier:
+relative          best for local relative imports
+shortest          best for shortest valid alias/path output
+project-relative  best for root-relative project imports
+non-relative      best for package or alias imports
+
+ending:
+minimal  best for extensionless TS imports
+js       best for ESM-style TS projects that require .js
+auto     leaves the decision to TypeScript
+index    best for explicit index import style
+
+builtin:
+node        path -> node:path; best for explicit Node builtin imports
+bare        node:path -> path; best for bare Node builtin imports
+omit field  keeps TypeScript/project output; add builtin if agents keep fixing this manually
+
+unusedImports:
+remove    clean unused imports in mutation-touched files
+preserve  keep unused imports
+omit      same as preserve
+
+Mutation-touched files are files where TS produced edits: source/target files and any reference/update files TS changed.
+Recommended value: remove
+
+importNormalize defines reusable defaults for aib imports normalize.
+Use it when the same normalize request would otherwise be repeated.
+
+It affects explicit import normalize commands only.
+It does not run automatically during move/modulePlan; use importRules for mutation-time cleanup.
+
+Fields:
+scope        repo-relative file or directory scope; most specific scope wins
+to           relative|alias|shortestAlias
+preferAlias  tsconfig paths pattern used when to=alias
+exclude      files, directories, or glob-like patterns to skip
+
+to:
+relative       rewrite resolved local imports to relative paths
+alias          rewrite resolved local imports to a matching tsconfig alias
+shortestAlias  rewrite to the shortest valid alias specifier
+
+preferAlias:
+@shared/*      prefer one alias pattern when several aliases can resolve the same file
+
+inspect.graph.exclude skips files before graph builds the model.
+Use it for generated files, backups, local copies, or other paths that make graph output noisy.
+
+Excluded files do not affect graph counts, hubs, entrypoints, leaves, edges, imports, importedBy, or saved graph files.
+
+Leave feedback while working.
+
+aib is built for agents. Agent feedback is the main signal for improving output, docs, mutations, and token efficiency.
+
+Use feedback when something is wrong, unclear, noisy, or could be more efficient.
+
+Format:
+feedback "kind | message"
+feedback "kind | topic | message"
+
+Kinds:
+bug, confusion, friction, idea, other
+
+Topic is optional. Choose any short topic that helps classify the feedback.
+
+Example:
+feedback "friction | imports | normalize required manual cleanup"
+
+Session
+
+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.
+
+Prefer short session names:
+aa, tr, qa, a2
+
+Create:
+session init --name <name>
+
+Follow the command output.
+If aib says multiple sessions exist, use the session you created explicitly:
+aib -s <name> <command>
+
+Or bind this shell:
+AIB=<name>
+
+If you want to prune session inputs/outputs, use:
+session clear
+
+After clear, keep using the same session.
+
+Check:
+session status
+
+Reusable index handles look like:
+`aib:graph:<name>`  `aib:usages:<name>`
+
+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.
+
+Example:
+type WsOptions
+class WsOptions
+
+If aib needs the exact entity, use:
+t-WsOptions
+c-WsOptions
+
+Selectors list:
+f-name  function
+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
+
+DSL request model:
+- directives set defaults for following requests
+- each request line can override defaults with key=value
+- +flag means true
+- -flag means false
+- file/imports/exports/members/code/deps accept a path as the first positional argument; examples below use this shape.
+- Use @file when several following operations share the same file.
+- 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
++flag                      boolean true
+-flag                      boolean false
+>name                      save reusable artifact when supported
+old->new                   rename pair
+Parent.member              parent-qualified member
+Parent.{a,b}               several members under one parent
+key=[a,b]                  list value for repeatable fields
+file="path with spaces.ts" quote values with spaces
+detail=sum|loc|code        aliases for summary|locations|code
+from=...                   alias for fromFile
+
+Inspect
+
+Inspect helps you turn an unknown code area into a small working model.
+
+Use it to understand what exists, how pieces connect, what repeats, where a change can spread, and which exact code should enter context next.
+
+One useful flow:
+map -> focus -> code
+
+map: learn what exists and how it connects
+focus: choose files/entities/usages that matter
+code: fetch exact code needed
+
+Choose inspect operation:
+
+declarations in one file         file
+static/dynamic imports           imports
+public API                       exports
+methods/properties of parent     members
+exact implementation             code
+outgoing deps of one entity      deps
+incoming references/callers      usages
+file/module connectivity         graph
+compact directory layout         tree
+repeated declarations/helpers    duplicates
+
+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
+    }
+  ]
+}
+
+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"]
+
+Inspect File
+
+Use file to map top-level declarations physically present in one file.
+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
+- listing top-level declarations
+- checking whether a file contains real declarations or mostly re-exports
+
+Do not add limit just in case.
+file output is compact and most files have far fewer than 100 top-level declarations.
+Use limit only after file output is actually too large.
+
+Controls:
+file, ranges, localOnly
+
+Specific:
+localOnly   show local declarations and reexports without resolving facade API; +localOnly
+
+Defaults: +ranges
+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 }
+  ]
+}
+
+inspect file src/service.ts [--ranges] [--local-only]
+
+Inspect Imports
+
+Use imports to inspect static and dynamic imports in a file.
+If there are no dynamic imports, the dynamic imports block is omitted.
+
+Controls:
+file, ranges
+
+Defaults: +ranges
+
+Run:
+aib inspect --stdin
+
+Input:
+imports @svc/service.ts
+
+Inspect Exports
+
+Use exports to see the public API of one file.
+It answers what other files can import from that file.
+
+Important:
+inspect.file marks exported declarations already.
+
+Do not batch this for a plain implementation file:
+file src/service.ts
+exports src/service.ts
+
+Use exports when you need public module surface, barrels, re-exports, export *, or resolveStar.
+
+Good for:
+- checking a module boundary or public surface
+- understanding facade/barrel files
+- resolving export * when the local file only re-exports from elsewhere
+- comparing API shape when public imports matter
+
+Controls:
+file, ranges, resolveStar
+
+Specific:
+resolveStar  resolve export * through re-exported modules; +resolveStar
+
+Run:
+aib inspect --stdin
+
+Input:
+{
+  "op": "exports",
+  "file": "src/service.ts",
+  "requests": [
+    { "ranges": true },
+    { "file": "src/index.ts", "resolveStar": true }
+  ]
+}
+
+inspect exports src/service.ts [--ranges] [--resolve-star]
+
+Inspect Members
+
+Use members to map a class/interface/object-like symbol without reading its body.
+It shows the internal shape of a parent entity without reading its full body.
+
+Good for:
+- listing member names when the parent entity is known
+- narrowing a large parent entity to relevant members
+- understanding object shape before changing or moving related code
+
+Controls:
+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 }
+  ]
+}
+
+inspect members src/service.ts Service [--limit N] [--offset N] [--all] [--ranges]
+
+Inspect Code
+
+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
+- fetching several related code blocks in one request
+- keeping context focused on code needed for the current task
+
+Controls:
+file, entity, entities, parent, show, ranges
+
+Specific:
+show  include source output
+
+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"
+    }
+  ]
+}
+
+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
+- 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"] }
+      ]
+    }
+  ]
+}
+
+Inspect Usages
+
+Use usages to find who references a file, directory, or entity inside a scope.
+It reports real references, not unused imports or text matches.
+For broad impact checks, target-local usages are hidden automatically when the target is inside a wider scope.
+Use includeTarget only when references inside the target file or directory matter.
+
+Good for:
+- checking impact before changing behavior
+- finding consumers of an entity or module area
+- 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.
+
+Controls:
+target, scope, entity, entities, parent, detail, limit, all, save, includeTarget
+
+Specific:
+includeTarget  include references inside the target file/directory; +includeTarget
+
+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"
+}
+
+Inspect Graph
+
+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: fromFile + 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
+fromFile -> 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: [...] compares known areas without mapping all src.
+
+After you understand which graph sections matter, hide the rest with JSON fields 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:
+{
+  "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
+    }
+  ]
+}
+
+Focus saved graph later:
+inspect graph --from-file aib:graph:services-graph --focus src/services/messages.ts --focus src/services/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.
+
+Inspect Tree
+
+Use tree to list a compact directory layout.
+It is useful before focused inspect when you know the area but not the exact file.
+
+node_modules, .git, dist, build, out, and .tmp are skipped by default.
+
+Controls:
+scope, depth, minDepth, limit, include, exclude, onlyDirs
+
+Specific:
+depth     max nesting depth; depth=N
+minDepth  hide shallower paths; minDepth=N
+onlyDirs  show directories only; +onlyDirs
+exclude   skip matching files/dirs
+include   only matching files/dirs; include=[...]
+
+Run:
+aib inspect --stdin
+
+Input:
+tree src depth=4 +onlyDirs limit=200
+tree @svc depth=3 include=["**/*.ts"] exclude=["**/*.test.ts","**/* copy.ts"]
+
+Inspect Duplicates
+
+Use duplicates to find repeated top-level names and exact declaration copies.
+It is useful when many files may contain copied local helpers, duplicated types, or repeated declarations.
+
+Start with summary for broad scopes.
+Use locations when you need files/lines.
+Use code only for duplicate names you are ready to inspect.
+
+Controls:
+scope, detail, limit, offset, kinds, entities, exclude, pathExclude
+
+Specific:
+entities    only these duplicate names/selectors
+exclude     skip these names/selectors
+pathExclude skip files or path/glob-like patterns
+kinds       selector kinds, e.g. f, t, c, etc.; kinds=[...]
+
+Run:
+aib inspect --stdin
+
+Input:
+{
+  "scope": "src",
+  "detail": "summary",
+  "limit": 20
+}
+
+Mutation
+
+Mutation commands change code through TS/IDE refactors.
+Successful mutations update affected references and imports.
+
+After a successful mutation, do not manually patch the same imports unless aib reports a follow-up or checks show a real issue.
+
+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.
+After failure or partial success, use the output to decide the next request.
+
+When running mutation commands, set the harness timeout to 3 minutes.
+If the harness stops waiting before final output appears, recover with:
+
+aib execution status last
+
+Modes:
+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 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.
+
+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.
+
+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.
+
+When a batch mutation partly fails, split the next request by failure type.
+
+If the failure is wrong input, fix the selector/entity/file and run the corrected remaining intent.
+If TS/IDE cannot apply one part of the batch, do not treat the whole intent as failed.
+Run the next request without the failed part and let aib report any later failures.
+Then decide whether failed parts need smaller requests or manual fallback.
+
+Rename
+
+Rename is for semantic symbol renames.
+It follows TypeScript references.
+It is not plain-text replacement.
+
+Run:
+aib rename execute --stdin
+
+Input:
+{
+  "file": "src/service.ts",
+  "renames": {
+    "oldName": "newName",
+    "OldService": "NewService"
+  }
+}
+
+Move
+
+Move transfers one or more symbols from one file to another.
+Move is semantic; it moves supported declarations and updates affected imports/references.
+Use it for focused extraction into a single target file.
+For large file splitting across several target files, use modulePlan.
+
+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"]
+}
+
+Module Plan
+
+modulePlan is for splitting large files into smaller modules.
+Use it when a large file should be refactored into several target files.
+
+modulePlan orchestrates semantic moves and updates affected references/imports.
+
+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.
+
+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"]
+    }
+  ]
+}
+
+Refactor Batch
+
+refactor batch runs related mutation requests together.
+Use it when one workflow needs ordered steps, such as rename plus move.
+
+Use modulePlan when the main intent is only to split one large file into target modules.
+Use refactor batch when the split also includes coordinated renames or mixed mutation steps.
+
+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"]
+    }
+  ]
+}
+
+Imports Normalize
+
+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.
+
+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
+
+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
+
+JS/TS compatibility
+
+With tsconfig:
+TS/TSX              inspect + rename + move + modulePlan
+JS/MJS/JSX ESM      inspect + rename + move + modulePlan
+CJS / JS CommonJS   inspect + rename
+
+Without tsconfig:
+JS/MJS/JSX/CJS      inspect only
+rename/move/modulePlan require tsconfig
+
+CommonJS means .cjs or module.exports / exports.*.
+
+View Hidden Output
+
+AIB keeps large outputs compact.
+When part of a result is hidden, output may include:
+
+view: aib:res_<id>
+
+Use view to fetch the hidden part without repeating what you already saw.
+
+When a batch has several hidden results of the same kind, output may include:
+
+view all code: aib:res_<id>
+view all members: aib:res_<id>
+
+A `view all` handle covers hidden parts from all results of that kind.
+
+For code views, narrow what you fetch:
+only    show only these hidden code entities
+except  show all hidden code except these entities
+
+Run:
+aib view --stdin
+
+Input:
+view aib:res_<id_1> only=[ClassA.{bigA,bigB},bigQ,ClassB.bigB]
+view aib:res_<id_2> except=[ClassC.bigC]
+
+Inline:
+aib view aib:res_<id_1> --only bigQ --only "ClassA.{bigA,bigB}"
+aib view aib:res_<id_2> --except ClassB.bigB --except ClassC.bigC
+
+Quick Read
+
+Use qr to read arbitrary text files with compact, cross-platform line windows.
+qr supports AIB path aliases.
+
+qr is not a replacement for inspect.
+Use it as a token-efficient way to read text data when semantic inspect is not needed.
+
+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
+
+If no window is provided, qr uses -h 80.
+If -a is present, it wins over other window flags.
+
+Run:
+aib qr --stdin
+
+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
+
+Inline:
+aib qr @scripts/a.txt -h 80
+aib qr @scripts/b.py -o 300 -l 50
+aib qr @logs/app.log -a
+
+Use stdin for several reads.