@automaton-labs/aib 0.0.6 → 0.0.8

package/dist/help/json/bootstrap.md

@@ -1,1085 +0,0 @@
-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.
-
-{{stdin.examples}}
-
-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
-
-Help refresh
-
-After context compaction, always run:
-aib help help-protocol quick-map
-aib config aliases
-
-Use focused help when you would otherwise guess how a known AIB capability works.
-
-Reread bootstrap when you need to restore the overall AIB workflow faster than piecing it together from focused topics.
-If you just reread bootstrap, do not also read focused topics unless you need details that bootstrap does not cover.
-
-Do not reread bootstrap automatically if focused help is enough.
-When refreshing multiple areas, request them together instead of one by one.
-
-Example:
-aib help patterns mutation inspect inspect.file inspect.code imports.normalize
-
-Use aib before broad file reads when the question is about TS/JS structure, references, dependencies, or focused code.
-Use qr for cross-OS quick reads of text files, logs, JSON, scripts, and line windows.
-It is not a replacement for inspect.
-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.
-
-After reading bootstrap for the first time in a repo, run:
-
-aib config
-
-Use the output as the repo-local AIB map:
-- pathAliases show short paths to use in AIB requests;
-- importRules show how move/modulePlan should create imports;
-- importNormalize shows defaults for explicit imports normalize;
-- excludes show which noise is intentionally hidden from tree/graph/sync.
-
-If pathAliases are missing, stale, or weak for repeated paths, run:
-aib help config-setup.aliases
-
-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
-
-If tree/graph output includes known repo noise, run:
-aib help config-setup.excludes
-
-If sync or reveal shows too many visible TypeScript configs, run:
-aib help config-setup.tsconfigs
-
-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.
-
-importNormalize defines default rules for explicit aib imports normalize commands.
-
-It does not run automatically during move/modulePlan; use importRules for mutation-time cleanup.
-
-AIB has four config exclude fields:
-inspect.graph.exclude
-inspect.tree.files.exclude
-inspect.tree.onlyDirs.exclude
-sync.tsconfig.exclude
-
-For all of them, node_modules, .git, dist, build, out, and .tmp are skipped by default.
-
-Use config excludes for generated files, backups, local copies, nested workspaces, seed projects, or other repository-specific noise.
-
-Graph excludes affect graph counts, hubs, entrypoints, leaves, edges, imports, importedBy, and saved graph files.
-Tree excludes affect directory/file discovery output.
-AIB syncs and watches visible tsconfigs.
-sync.tsconfig.exclude affects which TypeScript configs AIB syncs and watches.
-
-Important: 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
-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
-    }
-  ]
-}
-
-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.
-
-Controls:
-scope, depth, minDepth, limit, only, exclude, onlyDirs, ned, nec
-
-Specific:
-depth     max nesting depth; depth=N
-minDepth  hide shallower paths; minDepth=N
-onlyDirs  show directories only; +onlyDirs
-only      keep only matching files/dirs; only=[...]
-exclude   skip matching files/dirs; exclude=[...]
-ned       no-default-exclude; show paths hidden by built-in excludes; +ned
-nec       no-config-exclude; ignore inspect.tree.*.exclude from aib.json; +nec
-
-Run:
-aib inspect --stdin
-
-Input:
-tree src depth=4 +onlyDirs limit=200 +ned +nec
-tree @svc depth=3 only=["**/*.ts"] exclude=["**/*.test.ts","**/* copy.ts"]
-tree src depth=3 only=["src/services/**"] limit=80
-
-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.
-
-If move/modulePlan 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.
-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.
-
-If imports created by move do not match the repo style, run:
-aib help config-setup.import-rules
-
-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.
-
-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.
-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 for cross-OS quick reads of text files: ts, js, cmd, sh, json, log, txt, ndjson, etc.
-Use it for compact line windows and batching.
-qr supports AIB path aliases.
-
-It is not a replacement for inspect.
-Use it as a token-efficient way to read text data when semantic inspect is not needed.
-
-For focused text reads, prefer qr over cat/Get-Content/type, especially when aliases, line windows, or batching help.
-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
-
-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.
-
-Need to see TypeScript configs in the repo:
-aib reveal tsconfigs
-
-Need to see TypeScript aliases across the repo:
-aib reveal tsaliases