@automaton-labs/aib 0.0.6 → 0.0.8

package/dist/help/json/snippets/agents.md

@@ -1,14 +0,0 @@
-Recommended:
-For TS/JS code work, use aib. Start with {{docsPath}}.
-
-Strict:
-For TS/JS code work in this repo, prefer aib before broad file reads. Start with {{docsPath}}.
-
-Minimal:
-Use {{docsPath}} when working with TS/JS code.
-
-Help fallback:
-For TS/JS code work, use aib. Start with {{docsPath}}. If local docs are not enough, run `aib help bootstrap`.
-
-Refactor-focused:
-When changing TS/JS code, use aib for semantic discovery, usages, graph, rename, move, and modulePlan. Start with {{docsPath}}.

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

@@ -1,13 +0,0 @@
-Use the active session while you work.
-Reuse captured inputs when editing them is cheaper than rebuilding large JSON.
-
-Examples are patterns, not limits.
-Feature sections show common high-value uses, not every valid use.
-Adapt requests to the task: combine features, batch related questions, and skip steps when you already have enough context.
-
-Prefer batch JSON instead of inline calls.
-One request can inspect/mutate several files/entities and save reusable outputs.
-Use one-off commands only for small checks/changes.
-
-For mutations, aib asks TS/IDE refactors to update affected references and imports.
-After a successful mutation, do not manually patch the same imports unless aib reports a follow-up or the build/checks show a real issue.

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

@@ -1,54 +0,0 @@
-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/json/topics/config-setup.excludes.md

@@ -1,43 +0,0 @@
-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/json/topics/config-setup.import-normalize.md

@@ -1,84 +0,0 @@
-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/json/topics/config-setup.import-rules.md

@@ -1,94 +0,0 @@
-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/json/topics/config-setup.tsconfigs.md

@@ -1,31 +0,0 @@
-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

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

@@ -1,23 +0,0 @@
-DSL request model:
-- directives set defaults for following requests
-- each request line can override defaults with key=value
-- +flag means true
-- -flag means false
-- file/imports/exports/members/code/deps accept a path as the first positional argument; examples below use this shape.
-- Use @file when several following operations share the same file.
-- For one-off file operations, pass the path directly.
-
-Syntax:
-@file <path>               default file
-@source <path>             default sourceFile for mutations
-op arg arg key=value       request
-+flag                      boolean true
--flag                      boolean false
->name                      save reusable artifact when supported
-old->new                   rename pair
-Parent.member              parent-qualified member
-Parent.{a,b}               several members under one parent
-key=[a,b]                  list value for repeatable fields
-file="path with spaces.ts" quote values with spaces
-detail=sum|loc|code        aliases for summary|locations|code
-from=...                   alias for fromFile

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

@@ -1,290 +0,0 @@
-Use this when the user asks you to set up AIB for a repository.
-
-If you have not loaded the current bootstrap, run:
-aib help bootstrap
-
-1. Detect existing setup
-
-Run:
-
-aib config
-
-If AIB reports that no config exists, continue to initialization.
-
-If config exists:
-- verify that root is the intended repository root;
-- keep existing settings if they are still valid and useful;
-- only add missing project-specific aliases, rules, or excludes;
-- do not regenerate aib.json.
-
-If config resolves from a parent directory, verify that this is intentional.
-Do not continue setup inside a nested worktree or copied project if AIB is using the parent repository config.
-
-2. Initialize if missing
-
-From the repository root, run:
-
-aib init --session-dir .tmp/aib
-
-Use the output to check:
-- root is the intended repository root;
-- config is <root>/aib.json;
-- sessionDir is set;
-- cleanup/deletion/runtime TTLs are shown;
-- not set includes the setup sections that still need decisions.
-
-Do not create sessions yet.
-
-3. Configure repository-specific behavior
-
-Edit aib.json directly.
-
-Keep existing settings if they are still valid and useful.
-Update settings that are stale, noisy, too broad, or no longer match the repository.
-
-Use not set as the checklist for the setup sections below.
-
-4. Configure path aliases
-
-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"
-}
-
-5. Configure import 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.
-
-6. Configure tree and graph excludes
-
-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.
-
-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 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
-
-8. Sync and verify
-
-After all aib.json edits, run:
-
-aib sync
-
-If sync fails, fix aib.json and rerun sync.
-
-Check the final config summary:
-
-aib config
-
-Run one compact tree batch using important aliases:
-
-aib inspect --stdin
-
-Input:
-tree @<important-alias> depth=3 +onlyDirs limit=80
-tree @<another-important-alias> depth=3 +onlyDirs limit=80
-
-Check final TypeScript config discovery:
-
-aib reveal tsconfigs
-
-Confirm:
-- aliases resolve;
-- obvious tree noise is hidden;
-- visible tsconfigs match the active project surface;
-- config sections are set intentionally.
-
-9. Note operational constraints
-
-Before reporting back, identify any constraints the user should know.
-
-Worktrees:
-AIB resolves config from the nearest parent aib.json.
-If the repository uses nested copied projects or worktrees inside the repo root, AIB may resolve the parent config.
-Do not set up AIB inside nested worktrees that should behave as independent repositories.
-Independent worktrees should live outside the main repo root or have their own intended aib.json boundary.
-
-TTL:
-Sessions and managed runtime are cleaned up after inactivity according to aib config session.
-Tell the user if you changed these defaults or left them as-is.
-
-Watchers:
-AIB watches aib.json and visible tsconfig files after sync.
-If config changes are not reflected, run aib sync.
-
-10. Report to user
-
-Report:
-- whether AIB config already existed or was initialized;
-- which aliases were added and why;
-- 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-format.md

@@ -1,7 +0,0 @@
-Inline commands below omit the aib prefix.
-Run them as: aib <command>
-
-Stdin examples show command and input separately to avoid shell-specific syntax.
-Stdin Run lines include the aib prefix to avoid confusion.
-
-{{stdin.examples}}

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

@@ -1,24 +0,0 @@
-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