@automaton-labs/aib 0.0.4 → 0.0.5

package/dist/help/json/topics/first-setup.md

@@ -46,7 +46,7 @@ Use not set as the checklist for the setup sections below.
 
 4. Configure path aliases
 
-Run:
+Check TypeScript aliases for hints:
 
 aib reveal tsaliases
 
@@ -62,7 +62,7 @@ A good alias:
 - is easy to recognize later.
 
 A bad alias:
-- duplicates a short path like "src": "src";
+- 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.
 
@@ -81,9 +81,52 @@ Example:
 
 5. Configure import rules
 
-Set importRules to the import style this repository should use after move/modulePlan mutations.
-
-If the repository has one style, use one broad rule:
+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": [
   {
@@ -117,42 +160,10 @@ Use scoped rules only when areas differ by style, for example packages use alias
 Use the most specific scope that matches the real convention.
 Do not add scoped rules just because directories exist.
 
-6. Configure import normalization
-
-Add importNormalize only for cleanup commands the agent is likely to run more than once.
+6. Configure tree and graph excludes
 
-Use it when the repo has a clear normalization target:
-
-"importNormalize": [
-  {
-    "scope": "src",
-    "to": "shortestAlias",
-    "preferAlias": "@/*",
-    "exclude": [
-      "src/generated",
-      "src/**/dist"
-    ]
-  },
-  {
-    "scope": "scripts",
-    "to": "relative",
-    "exclude": [
-      "scripts/**/*.cjs",
-      "scripts/**/*.mjs"
-    ]
-  }
-]
-
-Choose scopes from real repo conventions.
-Do not copy importRules into importNormalize automatically.
-Leave it unset if normalization is not a repeated workflow.
-
-7. Configure tree and graph excludes
-
-Add excludes for noise the repository is known to contain.
-
-Use tree excludes for what the agent should not see while mapping folders.
-Use graph excludes for files that should not affect graph counts, hubs, entrypoints, leaves, edges, or saved graph views.
+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.
@@ -186,21 +197,25 @@ If the repository needs one of these areas for reasoning or mutation impact chec
 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.
 
-8. Configure TypeScript config discovery
+7. Configure TypeScript config discovery
+
+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 nested workspaces, seed projects, snapshots, backups, copied apps, or other non-primary projects, exclude them:
+If output includes non-primary projects, exclude them:
 
 "sync.tsconfig.exclude": [
   "dev-seed/**",
   "snapshots/**"
 ]
 
-Do not exclude real package/app configs just to reduce output.
-
 After editing aib.json, run:
 
 aib sync
@@ -216,7 +231,7 @@ Use +nec only when you need to compare visible configs with config-excluded conf
 
 aib reveal tsconfigs +nec
 
-9. Sync and verify
+8. Sync and verify
 
 After all aib.json edits, run:
 
@@ -246,7 +261,7 @@ Confirm:
 - visible tsconfigs match the active project surface;
 - config sections are set intentionally.
 
-10. Note operational constraints
+9. Note operational constraints
 
 Before reporting back, identify any constraints the user should know.
 
@@ -264,12 +279,12 @@ Watchers:
 AIB watches aib.json and visible tsconfig files after sync.
 If config changes are not reflected, run aib sync.
 
-11. Report to user
+10. Report to user
 
 Report:
 - whether AIB config already existed or was initialized;
 - which aliases were added and why;
-- which importRules/importNormalize settings were added or intentionally left unset;
+- which importRules settings were added or intentionally left unset;
 - which tree/graph/tsconfig excludes were added;
 - whether sync and verification passed;
 - any worktree, TTL, watcher, or tsconfig discovery constraints the user should know.

package/dist/help/json/topics/help-protocol.md

@@ -0,0 +1,24 @@
+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.
+
+If you are about to change import style across files, add or adopt tsconfig aliases, or clean imports repeatedly, read:
+aib help config-setup.import-normalize imports.normalize
+
+Refresh focused config help by signal:
+- repeated long paths: aib help config-setup.aliases
+- wrong move/modulePlan imports: aib help config-setup.import-rules
+- noisy tree/graph output: aib help config-setup.excludes
+- too many visible tsconfigs: aib help config-setup.tsconfigs
+
+When refreshing multiple areas, request them together instead of one by one.
+
+Example:
+aib help patterns mutation inspect inspect.file inspect.code imports.normalize

package/dist/help/json/topics/inspect.cycles.md

@@ -0,0 +1,36 @@
+Use cycles to find import cycles in a file or directory scope.
+
+Cycles reports cyclic components, not every possible path through a dense graph.
+It classifies cycles as runtime, type-only, or mixed.
+
+Start broad with summary output.
+Use detail=imports when you need the import edges that explain a cycle.
+Use detail=files when file membership is enough.
+
+Controls:
+scope   file or directory scope
+files   focus cycles that include one or more files
+detail  summary|imports|files
+limit   max cyclic components shown
+
+Run:
+aib inspect cycles <scope>
+
+Inline:
+aib inspect cycles src/features --limit 20
+aib inspect cycles src/features --detail imports --limit 20
+aib inspect cycles --files src/features/service.ts --detail imports
+
+Stdin:
+aib inspect --stdin
+
+Input:
+cycles src/features limit=20
+cycles src/features detail=imports limit=20
+cycles scope=src/features files=[src/features/service.ts] detail=imports
+
+If output hides components and shows a view handle, inspect only the hidden part:
+
+aib view <handle> --offset 2 --limit 2
+aib view <handle> --index 4 --detail imports
+aib view <handle> --index 5 --detail files

package/dist/help/json/topics/inspect.md

@@ -21,6 +21,7 @@ incoming references/callers      usages
 file/module connectivity         graph
 compact directory layout         tree
 repeated declarations/helpers    duplicates
+local import cycles              cycles
 
 Prefer one batch JSON request for related questions.
 Top-level fields are defaults for every request.

package/dist/help/json/topics/modulePlan.md

@@ -10,6 +10,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.

package/dist/help/json/topics/move.md

@@ -10,6 +10,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 to file:
 move toFile preview --stdin
 move toFile execute --stdin

package/dist/help/json/topics/mutation.md

@@ -3,6 +3,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.

package/dist/help/json/topics/patterns.md

@@ -1,4 +1,9 @@
+To refresh help protocol:
+aib help help-protocol
+
 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:
@@ -40,117 +45,7 @@ aib execution status last
 
 This is an escape hatch for recovering the latest mutation status/result.
 
-Before repeated mutation work, check aib config:
-
-aib config
-
-Set pathAliases for repeated request paths.
-Set importRules so move/modulePlan create imports in the project style.
-
-This avoids repeating long paths in requests and avoids manual import cleanup after mutations.
-Do this before large move/modulePlan work, not after cleanup becomes repetitive.
-
-Example aib.json config:
-
-{
-  "pathAliases": {
-    "svc": "src/services",
-    "cli": "packages/cli/src",
-    "ext": "packages/extension/src"
-  },
-  "importRules": [
-    {
-      "scope": ".",
-      "specifier": "shortest",
-      "ending": "auto",
-      "builtin": "bare",
-      "unusedImports": "remove"
-    }
-  ],
-  "importNormalize": [
-    {
-      "scope": "src",
-      "to": "shortestAlias",
-      "exclude": ["src/generated"]
-    }
-  ],
-  "inspect.graph.exclude": [
-    "**/* copy.ts"
-  ]
-}
-
-pathAliases define short request aliases for paths agents repeat in aib commands.
-Use them to reduce input tokens for repeated inspect and mutation work.
-
-Aliases are for aib request paths. They do not change TypeScript imports by themselves.
-For import style after mutations, use importRules.
-
-importRules control imports created or expanded by move/modulePlan mutation cleanup.
-They do not rewrite the whole project.
-
-AIB starts from IDE/TS import preferences.
-For mutation cleanup, matching importRules in aib.json take priority.
-
-Do not assume IDE/TS defaults match the repo style.
-Set importRules before large move/modulePlan work so imports do not need manual cleanup.
-
-Fields:
-scope      repo-relative file or directory scope; most specific scope wins
-specifier  relative|shortest|project-relative|non-relative
-ending     auto|minimal|index|js
-builtin    node|bare
-unusedImports  remove|preserve
-
-Defaults:
-specifier omitted      IDE/TS decides
-ending omitted         IDE/TS decides
-builtin omitted        keep TS/project builtin style
-unusedImports omitted  keep unused imports
-
-specifier:
-relative          best for local relative imports
-shortest          best for shortest valid alias/path output
-project-relative  best for root-relative project imports
-non-relative      best for package or alias imports
-
-ending:
-minimal  best for extensionless TS imports
-js       best for ESM-style TS projects that require .js
-auto     leaves the decision to TypeScript
-index    best for explicit index import style
-
-builtin:
-node        path -> node:path; best for explicit Node builtin imports
-bare        node:path -> path; best for bare Node builtin imports
-omit field  keeps TypeScript/project output; add builtin if agents keep fixing this manually
-
-unusedImports:
-remove    clean unused imports in mutation-touched files
-preserve  keep unused imports
-omit      same as preserve
-
-Mutation-touched files are files where TS produced edits: source/target files and any reference/update files TS changed.
-Recommended value: remove
-
-importNormalize defines reusable defaults for aib imports normalize.
-Use it when the same normalize request would otherwise be repeated.
-
-It affects explicit import normalize commands only.
-It does not run automatically during move/modulePlan; use importRules for mutation-time cleanup.
-
-Fields:
-scope        repo-relative file or directory scope; most specific scope wins
-to           relative|alias|shortestAlias
-preferAlias  tsconfig paths pattern used when to=alias
-exclude      files, directories, or glob-like patterns to skip
-
-to:
-relative       rewrite resolved local imports to relative paths
-alias          rewrite resolved local imports to a matching tsconfig alias
-shortestAlias  rewrite to the shortest valid alias specifier
-
-preferAlias:
-@shared/*      prefer one alias pattern when several aliases can resolve the same file
+Config excludes can hide files from tree/graph/sync output.
 
 AIB has four config exclude fields:
 inspect.graph.exclude
@@ -160,13 +55,7 @@ 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.
-Tsconfig excludes affect 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.
 

package/dist/help/json/topics/qr.md

@@ -1,9 +1,13 @@
-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

package/dist/help/json/topics/quick-map.md

@@ -0,0 +1,28 @@
+Read:
+  qr              quick reads: ts, js, cmd, sh, json, log, txt, etc.
+  view            hidden/truncated output
+
+Inspect:
+  file
+  imports
+  exports
+  members
+  code
+  deps
+  usages
+  graph
+  tree
+  duplicates
+  cycles
+
+Mutate:
+  rename
+  move
+  modulePlan
+  refactor batch
+  imports normalize
+
+Other:
+  config
+  prefs
+  reveal         tsconfig and tsconfig alias discovery

package/dist/help/json/topics/reveal.md

@@ -0,0 +1,28 @@
+Use reveal to inspect TypeScript config discovery used by AIB.
+
+Reveal is for config/setup diagnosis.
+Use it when aliases, sync, imports normalize, or tsconfig excludes depend on which tsconfig files AIB sees.
+
+Commands:
+aib reveal tsconfigs
+aib reveal tsaliases
+
+tsconfigs shows visible TypeScript configs and config-excluded configs.
+tsaliases shows baseUrl, paths, extends, inherited paths, duplicated inherited paths, and overridden inherited paths.
+
+Controls:
+all    show all output instead of compact output
+nec    no config excludes; ignore sync.tsconfig.exclude
+ned    no default excludes
+limit  max visible groups/items before + N more
+
+Examples:
+aib reveal tsconfigs
+aib reveal tsconfigs +all
+aib reveal tsconfigs +nec limit=20
+aib reveal tsaliases
+aib reveal tsaliases +all
+aib reveal tsaliases +nec
+
+Use tsconfigs before tuning sync.tsconfig.exclude.
+Use tsaliases before creating AIB pathAliases or configuring import normalization.

package/dist/help/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/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/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.