@automaton-labs/aib 0.0.6 → 0.0.8

package/dist/help/full.md

@@ -6,12 +6,12 @@ It can inspect symbols, usages, dependencies, duplicates, focused code, and run
 aib is designed for agent workflows:
 batch requests, compact text output, session handles, and reusable artifacts.
 
-Inline commands omit the aib prefix.
-When you see:
-session prefs get
-
-Run:
-aib session prefs get
+Inline commands omit the aib prefix.
+When you see:
+session clear
+
+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.
@@ -30,50 +30,18 @@ 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.
+For mutations, aib asks TypeScript semantic 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.
+Working patterns
+
+Use aib before broad file reads when the question is about TS/JS structure, references, dependencies, or focused code.
+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.
+Set the command timeout to 5 minutes for AIB requests.
 
 If a mutation command times out or returns no final output, use:
 
@@ -81,38 +49,37 @@ 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:
+After reading bootstrap for the first time in a repo, run:
+
+aib config; aib help help-protocol recipes rules
+
+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 imports.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"
+    "svc": "src/services",
+    "cli": "packages/cli/src"
   },
   "importRules": [
     {
@@ -141,17 +108,18 @@ 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.
+importRules control imports created or expanded by move/modulePlan mutation cleanup.
+They do not rewrite the whole project.
+
+A non-empty importRules block in aib.json is the complete AIB import-style authority.
+Omitted fields keep TypeScript/AIB defaults; they are not filled from editor settings.
+When importRules is empty, AIB may reuse explicit workspace-local IDE/TS preferences.
+
+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.
-
+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:
@@ -169,31 +137,13 @@ 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 saved artifacts, aliases, and prefs.
+Session stores saved artifacts and aliases.
 
 Prefer short session names:
 aa, tr, qa, a2
@@ -221,39 +171,6 @@ Reusable index handles look like:
 
 Pass index handles back to the matching inspect command with `--from-file` or `from` in DSL.
 
-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.
@@ -272,8 +189,9 @@ c-Name  class
 i-Name  interface
 t-Name  type
 v-name  variable
-e-Name  enum
-m-name  method, usually with parent
+e-Name  enum
+ns-Name namespace
+m-name  method, usually with parent
 p-name  property, usually with parent
 
 DSL request model:
@@ -286,9 +204,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
@@ -313,18 +232,19 @@ 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
+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
+path alias candidates            aliasCandidates
+repeated declarations/helpers    duplicates
 local import cycles              cycles
 
 Cycles are available but not expanded in bootstrap:
@@ -333,16 +253,16 @@ aib help inspect.cycles
 Prefer one batch DSL request for related questions.
 
 Batch example:
-
-Run:
-aib inspect --stdin
-
+
+Run:
+aib inspect --stdin
+
 Input:
 @file @svc/service.ts
 file
 file @svc/serviceB.ts
 members Service
-code entities=[Service.{render,reset},normalize]
+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
@@ -382,33 +302,19 @@ 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
+Good for:
+- 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.
-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:
-file @svc/service.ts +localOnly
+Input:
+file @svc/service.ts
 file src/index.ts
 
-inspect file src/service.ts [--ranges] [--local-only]
-
 Inspect Imports
 
 Use imports to inspect static and dynamic imports in a file.
@@ -481,50 +387,34 @@ members @svc/service.ts entities=[Service,ServiceOptions] +all +ranges
 
 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.
-
+Inspect Code
+
+Use code when you know file path and declaration/member selector, but do not know ranges.
+
 Run:
 aib inspect --stdin
 
-Input:
-code @svc/service.ts Service.{render,reset} normalize
-code @svc/serviceB.ts ServiceB.{constructor}
+Input:
+code @svc/service.ts Service.{render,reset} normalize
+code @svc/serviceB.ts ServiceB.{constructor} default
 
 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
-
+Run:
+aib inspect --stdin
+
 Input:
 deps @svc/service.ts entities=[createService,normalize,Service.{render,reset}]
 deps @svc/serviceB.ts ServiceB.{constructor} getConfig
@@ -560,71 +450,14 @@ usages target=@svc/service.ts entities=[createService,normalize,Service.{render,
 Expand saved usages when needed:
 inspect usages --from-file aib:usages:service-usages --focus createService --detail code --limit 20
 
-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: from + focus + output toggles
-
-view controls what enters the saved graph.
-focus only expands details for files already inside it.
-If focus misses a file, rebuild with wider scope or view.
-
-Default view:
-directory scope -> local
-file or multiple scopes -> neighbors
-from -> uses the saved graph
-
-Views:
-local      only files inside scope; best directory map
-neighbors  direct import neighborhood; best file-centered map
-expanded   wider neighborhood; more output
-
-Scope choice:
-scope=src creates a broad reusable map for src.
-scope=src/services is cheaper for local work.
-scope=[src/services,src/components] compares known areas without mapping all src.
-
-After you understand which graph sections matter, hide the rest with flags or prefs.
-Graph can be noisy; shape it for the current task.
-
-Controls:
-scope, view, from, focus, symbolUsage, edges, hubs, entrypoints, leaves, exclude, save
-
-Specific:
-view         local|neighbors|expanded
-from         reuse saved graph index; from=aib:graph:<name>
-focus        focus a file inside the graph; focus=path
-symbolUsage  show imported symbols on edges; +symbolUsage
-
-edges/hubs/entrypoints/leaves  output section toggles; +name or -name
-
-Run:
-aib inspect --stdin
-
-Input:
-graph scope=@svc view=local >services-graph
-graph from=aib:graph:services-graph focus=[@svc/users.ts,@svc/admins.ts] +symbolUsage -edges
+Inspect Graph
 
-Focus saved graph later:
-inspect graph --from-file aib:graph:services-graph --focus @svc/messages.ts --focus @svc/posts.ts --symbol-usage
+Graph is a strong tool for file/module connectivity.
+Use it when the question is about boundaries, ownership, hubs, entrypoints, or how files relate through imports.
+Do not use graph for one symbol; use deps/usages instead.
 
-Inline graph focus can add focus and symbolUsage.
-Use DSL, request files, or prefs to hide sections such as edges/hubs/entrypoints/leaves.
+Focused topic:
+aib help inspect.graph
 
 Inspect Tree
 
@@ -651,81 +484,68 @@ 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
-
+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.
+
+Focused topic:
+aib help inspect.duplicates
 
-Controls:
-scope, detail, limit, offset, kinds, entities, exclude, pathExclude
+Mutation
 
-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=[...]
+Mutation commands change code and files through TS/IDE-backed operations.
+Successful mutations update affected references and imports.
 
-Run:
-aib inspect --stdin
+Semantic mutations change TypeScript symbols/declarations.
+File mutations change file layout.
 
-Input:
-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
+After a successful mutation, do not manually patch the same imports unless aib reports a follow-up or checks show a real issue.
+
+If mutation imports do not match the repo style, run:
+aib help config-setup.import-rules
 
-Mutation
+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.
 
-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.
+The DSL inside the request describes the intent:
+rename      rename TypeScript symbols
+move        move TypeScript declarations into target files
+moveToDir   move whole files into directories
+renameFile  rename whole files
+module      full-file split: move all declarations from one source into target modules
 
-If move/modulePlan imports do not match the repo style, run:
-aib help config-setup.import-rules
+Mix rename, move, moveToDir, and renameFile when they belong to the same workflow.
+Run module splits as a separate mutate request.
 
-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.
+Do not read all changed files just because a mutation touched them.
+That defeats the purpose of using AIB for mechanical refactors.
+
+When the command completes, use its output as the source of truth for what changed and what remains.
 After failure or partial success, use the output to decide the next request.
 
-When running mutation commands, set the harness timeout to 3 minutes.
+Set the command timeout to 5 minutes for AIB requests.
 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.
+Modes:
+preview  review DSL intent, then apply by id
+apply    execute from preview
+execute  execute immediately
 
-Prefer batch DSL for related mutations.
-One request can describe several related changes.
+Use preview/apply when you are learning a mutation command.
+Use execute for routine requests.
 
-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.
+preview/apply uses more tool calls and more output tokens.
+preview checks the DSL intent; execute/apply writes files and can still hit mutation errors.
+execute writes immediately and reports what changed.
+
+Prefer one mutate DSL request for related changes.
+For mixable operations, batch the ordered workflow instead of sending one command per symbol or file.
+
+If a mutation cannot be fully completed, aib reports what failed, what was applied, and what did not run.
+Fix wrong input before retrying; do not repeat provider/manual-extraction failures unchanged.
 
 Rename
 
@@ -733,129 +553,96 @@ 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
+Run:
+aib mutate execute --stdin
+
+Input:
+@source src/service.ts
 rename 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 transfers declarations from one source file to target files.
+Move is semantic; it moves supported declarations and updates affected imports/references.
+Use move as the default operation for moving declarations, including multi-target extractions.
 
 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
-
+Run:
+aib mutate execute --stdin
+
 Input:
 @source src/service.ts
 move src/service.helpers.ts: oldHelper OtherHelper
+move src/service.types.ts: ServiceOptions
 
-Module Plan
-
-modulePlan is for splitting large files into smaller modules.
-Use it when a large file should be refactored into several target files.
+Module Plan
 
-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
+Use module only for a full-file split: moving all declarations from one source file into target modules.
 
-Input:
-@source src/large-service.ts +expectEmpty
-module src/large-service.types.ts: ServiceOptions ServiceMode
-module src/large-service.core.ts: LargeService createLargeService
+Focused topic:
+aib help modulePlan
 
-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.
+Mixed Mutation
 
-Refactor Batch
+Use one mutate request for one ordered workflow.
+Mix rename, move, moveToDir, and renameFile when they belong to the same workflow.
+Order lines the way the workflow should run.
+Do not include module lines in mixed requests.
 
-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.
+Run:
+aib mutate execute --stdin
 
-Example: rename and move in one request
-
-Run:
-aib refactor batch execute --stdin
-
 Input:
 @source src/service.ts
-rename oldHelper->newHelper oldType->newType
+rename oldHelper->newHelper AUser->AdminUser
 move src/service.helpers.ts: newHelper
-move src/service.types.ts: newType
+move src/service.types.ts: AdminUser
 
-This keeps related mutation intent together:
-rename first, then move the renamed symbols.
+@base src/main
+moveToDir facade: ../services/fileA.ts fileB.ts
+moveToDir ../core/services: fileC.ts classes/main/fileD.ts
 
-Imports Normalize
+@base src
+renameFile svc/ws-cli.ts->cli.ts svc/ws-command.ts->command.ts
 
-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 Layout
 
-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 moveToDir and renameFile when the filesystem layout is the intent.
+Do not change filesystem layout manually.
 
-Run:
-aib imports normalize preview --stdin
-
-Input:
-imports.normalize scope=@svc to=shortestAlias exclude=[@svc/generated,"**/* copy.ts"]
-
-Rewrite imports found inside src/core.
-When an imported file can be expressed through @features/*, prefer that alias.
+Focused topics:
+aib help moveToDir renameFile
 
-Input:
-imports.normalize scope=src/core to=alias preferAlias=@features/*
+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
+
+Import Boundaries
 
-With matching importNormalize config for this scope or a parent scope, use inline CLI commands:
+When you create a barrel/index file and want consumers to import through it,
+or when consumers import through a barrel but should use direct source imports, read:
 
-imports normalize preview @svc
-imports normalize execute @svc
+aib help recipe.import-boundary
 
 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
+With tsconfig:
+TS/TSX              inspect + mutate rename/move/module
+JS/MJS/JSX ESM      inspect + mutate rename/move/module
+CJS / JS CommonJS   inspect + mutate rename
+
+Without tsconfig:
+JS/MJS/JSX/CJS      inspect only
+mutate rename/move/module require tsconfig
 
 CommonJS means .cjs or module.exports / exports.*.
 
@@ -896,37 +683,49 @@ Use qr for cross-OS quick reads of text files: ts, js, cmd, sh, json, log, txt,
 Use it for compact line windows and batching.
 qr supports AIB path aliases.
 
-It is not a replacement for inspect.
+It is not a replacement for aib inspect in TS/JS cases.
 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
+h=N              head; first N lines
+t=N              tail; last N lines
+r=A:B,C:D,E      ranges; A with next B lines, C with next D lines, E with default 80 lines
+s=A:B,C:D,E      slices; inclusive A through B, C through D, and line E
+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 reads the whole file.
+Avoid `all` for files whose size/content is unknown; it can dump unnecessary context.
+Overlapping windows are merged.
 
-Run:
-aib qr --stdin
+Use s= when copying ranges from inspect file.
+Combine windows for the same file instead of repeating the path.
 
-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
+{{qr.inline.examples}}
 
-Inline:
-aib qr @scripts/a.txt -h 80
-aib qr @scripts/b.py -o 300 -l 50
-aib qr @logs/app.log -a
+aib rg
+
+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