@automaton-labs/aib 0.0.4 → 0.0.6

package/dist/help/dsl/full.md

@@ -13,13 +13,10 @@ 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
+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
 
@@ -36,9 +33,28 @@ 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
-
+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:
@@ -52,9 +68,9 @@ If output hides data and shows `view: aib:res_<id>`, use `aib view ...` to fetch
 
 Compact output is a starting point, not a substitute for needed code.
 Fetch exact code when correctness depends on implementation details.
-
-Use prefs when the current phase repeats the same output shape.
-Turn details off when they stop helping.
+
+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.
@@ -65,15 +81,30 @@ 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.
+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:
 
@@ -110,72 +141,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.
-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
+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
@@ -189,9 +166,10 @@ Use config excludes for generated files, backups, local copies, nested workspace
 
 Graph excludes affect graph counts, hubs, entrypoints, leaves, edges, imports, importedBy, and saved graph files.
 Tree excludes affect directory/file discovery output.
-Tsconfig excludes affect which TypeScript configs AIB syncs and watches.
+AIB syncs and watches visible tsconfigs.
+sync.tsconfig.exclude affects which TypeScript configs AIB syncs and watches.
 
-Leave feedback while working.
+Important: leave feedback while working.
 
 aib is built for agents. Agent feedback is the main signal for improving output, docs, mutations, and token efficiency.
 
@@ -347,6 +325,10 @@ 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 DSL request for related questions.
 
@@ -701,6 +683,9 @@ 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.
@@ -762,6 +747,9 @@ Move is semantic; it moves supported declarations and updates affected imports/r
 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
@@ -777,6 +765,9 @@ 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.
@@ -901,12 +892,16 @@ 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.
+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.
 
-qr is not a replacement for inspect.
+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
@@ -932,3 +927,9 @@ 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

package/dist/help/dsl/topics/config-setup.aliases.md

@@ -0,0 +1,54 @@
+If you have not just checked the full config, check current aliases:
+
+aib config aliases
+
+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.
+
+Check TypeScript aliases for hints:
+
+aib reveal tsaliases
+
+Use this to see existing tsconfig paths and baseUrl values.
+They can reveal stable work areas, but they are not a list to copy.
+
+Add pathAliases for long paths that are likely to appear repeatedly in AIB requests.
+Prefer aliases for real work areas, package roots, or deep directories.
+
+A good alias:
+- saves meaningful path tokens;
+- points to a stable work area;
+- is easy to recognize later.
+
+A bad alias:
+- duplicates a short path like "src": "src", "packages": "packages", "scripts": "scripts";
+- points to a rarely used folder;
+- mirrors the directory tree without a workflow reason.
+
+Having 20-30 good aliases is fine for a large repo or monorepo.
+
+Example:
+
+"pathAliases": {
+  "wstore": "apps/web/src/shared/store",
+  "wapi": "apps/web/src/shared/api",
+  "whooks": "apps/web/src/shared/utils/hooks",
+  "pmail": "packages/email/src",
+  "putils": "packages/utils/src",
+  "arules": "docs/agent/rules"
+}
+
+After editing aib.json, run:
+
+aib sync
+
+Verify aliases with a small tree or inspect request:
+
+aib inspect --stdin
+
+Input:
+tree @<alias> depth=3 +onlyDirs limit=80

package/dist/help/dsl/topics/config-setup.excludes.md

@@ -0,0 +1,43 @@
+Tree excludes affect directory and file discovery output.
+Graph excludes affect graph counts, hubs, entrypoints, leaves, edges, imports, importedBy, and saved graph views.
+
+Built-in excludes already skip common noise such as node_modules, .git, dist, build, out, and .tmp.
+Add config excludes for repository-specific noise.
+
+For example, if the user often creates hard-copy directories or backup files before risky edits, those copies can make tree and graph output noisy.
+Exclude them explicitly:
+
+"inspect.tree.onlyDirs.exclude": [
+  "**/*copy",
+  "**/*copy/**"
+],
+"inspect.tree.files.exclude": [
+  "**/* copy.ts",
+  "**/*.generated.ts"
+],
+"inspect.graph.exclude": [
+  "**/* copy.ts",
+  "**/*.generated.ts",
+  "src/generated/**"
+]
+
+Prefer narrow patterns for known noise:
+- generated files;
+- local copy/backup folders;
+- build artifacts not already skipped by defaults;
+- vendored or checked-in output.
+
+These are common cases, not mandatory rules.
+If the repository needs one of these areas for reasoning or mutation impact checks, do not exclude it.
+
+Do not exclude broad source areas to make output smaller.
+If output is too large, use scope, depth, limit, graph view, or graph toggles first.
+
+After editing aib.json, run:
+
+aib sync
+
+Then verify with a compact tree request and the graph view that was noisy.
+
+If excluded paths still appear, check the glob pattern against repo-relative paths.
+If important source disappeared, narrow or remove the exclude.

package/dist/help/dsl/topics/config-setup.import-normalize.md

@@ -0,0 +1,84 @@
+Configure import normalization intent.
+
+importNormalize defines default normalization rules for explicit aib imports normalize commands.
+Use it before broad or important import cleanup so the scope, target style, preferred alias, and excludes are stored in aib.json instead of repeated in command arguments.
+
+It does not run automatically during move/modulePlan.
+Use importRules for mutation-time import cleanup.
+
+Set importNormalize when the intended cleanup has project meaning:
+- adopting a new tsconfig alias across a project area;
+- converting an area to aliases;
+- converting scripts/tools or extracted modules to relative imports;
+- excluding generated or bundled output from normalization.
+
+For tiny one-file checks, inline options are fine.
+Before wider cleanup, put the intended rule in config and preview the smallest useful scope.
+
+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
+
+Alias cleanup:
+
+"importNormalize": [
+  {
+    "scope": "src",
+    "to": "shortestAlias",
+    "preferAlias": "@/*",
+    "exclude": [
+      "src/generated",
+      "src/**/dist"
+    ]
+  }
+]
+
+Relative cleanup for scripts/tools:
+
+"importNormalize": [
+  {
+    "scope": "scripts",
+    "to": "relative",
+    "exclude": [
+      "scripts/**/*.cjs",
+      "scripts/**/*.mjs"
+    ]
+  }
+]
+
+If you have not just checked config rules, run:
+
+aib config rules
+
+After editing aib.json, run:
+
+aib sync
+
+Then preview the smallest useful scope before applying:
+
+aib imports normalize preview <scope>
+
+Preview shows counts, sample import rewrites, a planId, and the apply command.
+It does not change project files.
+
+If preview changes imports outside the intended area, narrow scope or add exclude.
+
+If preview does not use the expected alias, check tsconfig aliases:
+
+aib reveal tsaliases
+
+If the config and aliases look correct but preview still looks stale or strange, run:
+
+aib sync
+
+Then preview again.

package/dist/help/dsl/topics/config-setup.import-rules.md

@@ -0,0 +1,94 @@
+Use this when move/modulePlan creates imports that do not match the repository style.
+
+Do not keep fixing the same generated import style by hand.
+Tune importRules, sync config, then retry the smallest useful mutation before continuing larger mutation work.
+
+Check current config:
+
+aib config rules
+
+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.
+
+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
+
+If the repository has one import style, use one broad rule:
+
+"importRules": [
+  {
+    "scope": ".",
+    "specifier": "shortest",
+    "ending": "auto",
+    "builtin": "node",
+    "unusedImports": "remove"
+  }
+]
+
+Use scoped rules only when areas differ by style, for example packages use aliases but scripts use relative imports:
+
+"importRules": [
+  {
+    "scope": "packages",
+    "specifier": "shortest",
+    "ending": "auto",
+    "builtin": "node",
+    "unusedImports": "remove"
+  },
+  {
+    "scope": "scripts",
+    "specifier": "relative",
+    "ending": "auto",
+    "builtin": "node",
+    "unusedImports": "remove"
+  }
+]
+
+Use the most specific scope that matches the real convention.
+Do not add scoped rules just because directories exist.
+
+After editing aib.json, run:
+
+aib sync
+
+Then rerun the smallest affected move/modulePlan preview or execute request.
+If imports are still wrong, update importRules again before doing more manual cleanup.

package/dist/help/dsl/topics/config-setup.tsconfigs.md

@@ -0,0 +1,31 @@
+AIB syncs and watches visible tsconfigs.
+Keep real app/package configs visible.
+Exclude nested workspaces, seed projects, snapshots, backups, copied apps, or other non-primary projects.
+
+Do not exclude real package/app configs just to reduce output.
+
+Check which TypeScript configs AIB will sync and watch:
+
+aib reveal tsconfigs +all
+
+If output includes non-primary projects, exclude them:
+
+"sync.tsconfig.exclude": [
+  "dev-seed/**",
+  "snapshots/**"
+]
+
+After editing aib.json, run:
+
+aib sync
+
+Then check again:
+
+aib reveal tsconfigs +all
+
+Visible tsconfigs should describe the active project surface.
+Excluded tsconfigs should be things the agent should not use for setup decisions.
+
+Use +nec only when you need to compare visible configs with config-excluded configs:
+
+aib reveal tsconfigs +nec