@automaton-labs/aib 0.0.7 → 0.0.9

package/dist/help/dsl/bootstrap.md

@@ -30,46 +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:
-
-aib inspect tree src --depth 5 --only-dirs --limit 200
-
-Start compact for broad scans.
-Use summary, locations, or local graph views first when output could be large.
-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.
 
-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:
 
@@ -77,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 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:
+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": [
     {
@@ -137,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:
@@ -165,24 +137,6 @@ 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.
@@ -278,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:
@@ -347,34 +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 a file
-- listing top-level declarations
-- seeing default exports, decorators, IIFEs, and runtime calls
+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.
@@ -447,32 +387,16 @@ 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, declaration, `default`, or `IIFE#N`
-- 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:
-code @svc/service.ts Service.{render,reset} normalize
-code @svc/serviceB.ts ServiceB.{constructor} default IIFE#1
+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} default
 
 Inspect Deps
 
@@ -526,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.
-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
+Inspect Graph
 
-Input:
-graph scope=@svc view=local >services-graph
-graph from=aib:graph:services-graph focus=[@svc/users.ts,@svc/admins.ts] +symbolUsage -edges
+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.
 
-Focus saved graph later:
-inspect graph --from-file aib:graph:services-graph --focus @svc/messages.ts --focus @svc/posts.ts --symbol-usage
-
-Inline graph focus can add focus and symbolUsage.
-Use DSL or request flags to hide sections such as edges/hubs/entrypoints/leaves.
+Focused topic:
+aib help inspect.graph
 
 Inspect Tree
 
@@ -617,30 +484,12 @@ 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.
-
-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:
-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
+Focused topic:
+aib help inspect.duplicates
 
 Mutation
 
@@ -649,59 +498,54 @@ Successful mutations update affected references and imports.
 
 Semantic mutations change TypeScript symbols/declarations.
 File mutations change file layout.
-
-After a successful mutation, do not manually patch the same imports unless aib reports a follow-up or checks show a real issue.
-
-If mutation imports do not match the repo style, run:
+
+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
 
 AIB mutations are designed to reduce manual checking.
 Your job is to express the intent in DSL.
 AIB's job is to convert that intent into code changes.
 
-Choose the mutation by intent:
-rename - rename TypeScript symbols
-move toFile - move TypeScript declarations into one file
-modulePlan - split one source file into several modules
-file move toDir - move whole files into directories
-file rename - rename whole files.
+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
+
+Mix rename, move, moveToDir, and renameFile when they belong to the same workflow.
+Run module splits as a separate mutate request.
 
 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.
+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
-
+Modes:
+preview  review DSL intent, then apply by id
+apply    execute from preview
+execute  execute immediately
+
+Use preview/apply when you are learning a mutation command.
 Use execute for routine requests.
-
-Use preview/apply when you are learning a mutation command, or when one request contains a large multi-step change that you want to inspect before writing files.
-Typical examples: a huge modulePlan or refactor batch.
-
-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.
 
-Prefer batch DSL for related mutations.
-One request can describe several related changes.
+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.
 
-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.
+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
 
@@ -709,92 +553,70 @@ 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
+
+@base src/main
+moveToDir facade: ../services/fileA.ts fileB.ts
+moveToDir ../core/services: fileC.ts classes/main/fileD.ts
 
-This keeps related mutation intent together:
-rename first, then move the renamed symbols.
+@base src
+renameFile svc/ws-cli.ts->cli.ts svc/ws-command.ts->command.ts
 
-File Move and File Rename
+File Layout
 
-Use file move/rename when the filesystem layout is the intent.
+Use moveToDir and renameFile when the filesystem layout is the intent.
 Do not change filesystem layout manually.
 
 Focused topics:
-aib help file.move file.rename
-
-Layout smell trigger:
-If a directory has many related files sharing a prefix, mixed responsibilities, or files that should be grouped by feature, read:
+aib help moveToDir renameFile
+
+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
@@ -804,16 +626,23 @@ Use imports normalize for explicit import-style cleanup.
 Focused topic:
 aib help imports.normalize
 
-JS/TS compatibility
+Import Boundaries
+
+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:
 
-With tsconfig:
-TS/TSX              inspect + rename + move + modulePlan
-JS/MJS/JSX ESM      inspect + rename + move + modulePlan
-CJS / JS CommonJS   inspect + rename
+aib help recipe.import-boundary
+
+JS/TS compatibility
 
-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.*.
 
@@ -854,20 +683,26 @@ 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 l=N    range; starting line and line count
-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 all is present, it wins over other window flags.
+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.
+
+Use s= when copying ranges from inspect file.
+Combine windows for the same file instead of repeating the path.
 
 {{qr.inline.examples}}