@automaton-labs/aib 0.0.2 → 0.0.4

package/dist/help/dsl/docs/patterns.md

@@ -154,10 +154,19 @@ shortestAlias  rewrite to the shortest valid alias specifier
 preferAlias:
 @shared/*      prefer one alias pattern when several aliases can resolve the same file
 
-inspect.graph.exclude skips files before graph builds the model.
-Use it for generated files, backups, local copies, or other paths that make graph output noisy.
+AIB has four config exclude fields:
+inspect.graph.exclude
+inspect.tree.files.exclude
+inspect.tree.onlyDirs.exclude
+sync.tsconfig.exclude
 
-Excluded files do not affect graph counts, hubs, entrypoints, leaves, edges, imports, importedBy, or saved graph files.
+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.
 

package/dist/help/dsl/full.md

@@ -177,10 +177,19 @@ shortestAlias  rewrite to the shortest valid alias specifier
 preferAlias:
 @shared/*      prefer one alias pattern when several aliases can resolve the same file
 
-inspect.graph.exclude skips files before graph builds the model.
-Use it for generated files, backups, local copies, or other paths that make graph output noisy.
-
-Excluded files do not affect graph counts, hubs, entrypoints, leaves, edges, imports, importedBy, or saved graph files.
+AIB has four config exclude fields:
+inspect.graph.exclude
+inspect.tree.files.exclude
+inspect.tree.onlyDirs.exclude
+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.
 
@@ -640,24 +649,25 @@ Inspect Tree
 Use tree to list a compact directory layout.
 It is useful before focused inspect when you know the area but not the exact file.
 
-node_modules, .git, dist, build, out, and .tmp are skipped by default.
-
 Controls:
-scope, depth, minDepth, limit, include, exclude, onlyDirs
+scope, depth, minDepth, limit, only, exclude, onlyDirs, ned, nec
 
 Specific:
 depth     max nesting depth; depth=N
 minDepth  hide shallower paths; minDepth=N
 onlyDirs  show directories only; +onlyDirs
-exclude   skip matching files/dirs
-include   only matching files/dirs; include=[...]
+only      keep only matching files/dirs; only=[...]
+exclude   skip matching files/dirs; exclude=[...]
+ned       no-default-exclude; show paths hidden by built-in excludes; +ned
+nec       no-config-exclude; ignore inspect.tree.*.exclude from aib.json; +nec
 
 Run:
 aib inspect --stdin
 
 Input:
-tree src depth=4 +onlyDirs limit=200
-tree @svc depth=3 include=["**/*.ts"] exclude=["**/*.test.ts","**/* copy.ts"]
+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
 

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

@@ -0,0 +1,275 @@
+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
+
+Run:
+
+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";
+- 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
+
+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": [
+  {
+    "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 import normalization
+
+Add importNormalize only for cleanup commands the agent is likely to run more than once.
+
+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.
+
+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.
+
+8. Configure TypeScript config discovery
+
+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:
+
+"sync.tsconfig.exclude": [
+  "dev-seed/**",
+  "snapshots/**"
+]
+
+Do not exclude real package/app configs just to reduce output.
+
+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
+
+9. 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.
+
+10. 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.
+
+11. 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 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/dsl/topics/inspect.tree.md

@@ -1,20 +1,22 @@
 Use tree to list a compact directory layout.
 It is useful before focused inspect when you know the area but not the exact file.
 
-node_modules, .git, dist, build, out, and .tmp are skipped by default.
-
 Controls:
-scope, depth, minDepth, limit, include, exclude, onlyDirs
+scope, depth, minDepth, limit, only, exclude, onlyDirs, ned, nec
 
 Specific:
 depth     max nesting depth; depth=N
 minDepth  hide shallower paths; minDepth=N
 onlyDirs  show directories only; +onlyDirs
-include   only matching files/dirs; include=[...]
+only      only matching files/dirs; only=[...]
+exclude   skip matching files/dirs; exclude=[...]
+ned       no-default-exclude; ignore built-in excludes; +ned
+nec       no-config-exclude; ignore aib.json tree excludes; +nec
 
 Run:
 aib inspect --stdin
 
 Input:
-tree src depth=4 +onlyDirs limit=200
-tree @svc depth=3 include=["**/*.ts"] exclude=["**/*.test.ts","**/* copy.ts"]
+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

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

@@ -152,10 +152,19 @@ shortestAlias  rewrite to the shortest valid alias specifier
 preferAlias:
 @shared/*      prefer one alias pattern when several aliases can resolve the same file
 
-inspect.graph.exclude skips files before graph builds the model.
-Use it for generated files, backups, local copies, or other paths that make graph output noisy.
+AIB has four config exclude fields:
+inspect.graph.exclude
+inspect.tree.files.exclude
+inspect.tree.onlyDirs.exclude
+sync.tsconfig.exclude
 
-Excluded files do not affect graph counts, hubs, entrypoints, leaves, edges, imports, importedBy, or saved graph files.
+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.
 

package/dist/help/full.md

@@ -177,10 +177,19 @@ shortestAlias  rewrite to the shortest valid alias specifier
 preferAlias:
 @shared/*      prefer one alias pattern when several aliases can resolve the same file
 
-inspect.graph.exclude skips files before graph builds the model.
-Use it for generated files, backups, local copies, or other paths that make graph output noisy.
-
-Excluded files do not affect graph counts, hubs, entrypoints, leaves, edges, imports, importedBy, or saved graph files.
+AIB has four config exclude fields:
+inspect.graph.exclude
+inspect.tree.files.exclude
+inspect.tree.onlyDirs.exclude
+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.
 
@@ -640,24 +649,25 @@ Inspect Tree
 Use tree to list a compact directory layout.
 It is useful before focused inspect when you know the area but not the exact file.
 
-node_modules, .git, dist, build, out, and .tmp are skipped by default.
-
 Controls:
-scope, depth, minDepth, limit, include, exclude, onlyDirs
+scope, depth, minDepth, limit, only, exclude, onlyDirs, ned, nec
 
 Specific:
 depth     max nesting depth; depth=N
 minDepth  hide shallower paths; minDepth=N
 onlyDirs  show directories only; +onlyDirs
-exclude   skip matching files/dirs
-include   only matching files/dirs; include=[...]
+only      keep only matching files/dirs; only=[...]
+exclude   skip matching files/dirs; exclude=[...]
+ned       no-default-exclude; show paths hidden by built-in excludes; +ned
+nec       no-config-exclude; ignore inspect.tree.*.exclude from aib.json; +nec
 
 Run:
 aib inspect --stdin
 
 Input:
-tree src depth=4 +onlyDirs limit=200
-tree @svc depth=3 include=["**/*.ts"] exclude=["**/*.test.ts","**/* copy.ts"]
+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
 

package/dist/help/help-meta.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "helpVersion": "0.1.0",
-  "generatedAt": "2026-05-25T01:01:46+03:00",
-  "sourceCommit": "51c652c",
-  "contentHash": "sha256:fa654cee3287525d7a9dce2fd8d4fa159138898ee4b7c8ebf6fed43bde58074a",
+  "generatedAt": "2026-05-25T15:50:58+03:00",
+  "sourceCommit": "d81ed9b",
+  "contentHash": "sha256:78fb61b48b619be94f6a1461ed221736190f510e4f09a18dfd2e3a877500e835",
   "topics": {
     "help-format": {
       "contentHash": "sha256:771a21ea7d2818812f9cedc17183c62c74975d0d04267b015c08c086488b03d5",
@@ -13,13 +13,17 @@
       "contentHash": "sha256:e9c53461377826c660b9c79b6f6b88c21c37899cf6c97e90acccc56ef8bb9ce2",
       "docsHash": "sha256:b029006c90a1809532b8de49dee9f0bb0f0fc9fd97543159a81be81a66b8a2f6"
     },
+    "first-setup": {
+      "contentHash": "sha256:77617a6c3bc3f335e42142240522ed1a204d640d5fe46a20f21be9ef1c1823b2",
+      "docsHash": "sha256:4a85dd189d5cf66ca4e5c74e20a591a82990080299279ccf0d5bf013d6995046"
+    },
     "dsl": {
       "contentHash": "sha256:2256703eb851fe0c6deaed62cbfa8b7a651f42a028c25c5ee68351ae173b4c55",
       "docsHash": "sha256:c62461472e8312429d46005d5a50fa2ba449318ee652e887047df60eb6fe5a46"
     },
     "patterns": {
-      "contentHash": "sha256:0e87f84b1e2a4d75b8e7a568b07fb98054cbc48f57e9327a4a73a77d05fec0e8",
-      "docsHash": "sha256:319378d8787b4e21dc4047435e1130a44ebbfe2f8e0bc6d1628712167351478a"
+      "contentHash": "sha256:e3d6df223c5647c7b93c15a902aee92b6ce0c4031028e6014136c5fa5d9260d2",
+      "docsHash": "sha256:23cf1a65f924e1c8ea98e89c907946128e8a62bdc10067a8d7c8ff666bc3c58d"
     },
     "session": {
       "contentHash": "sha256:c2a231e53defb09e165649d101d31a3797a3ee7a02d892b194f0c2e4805f9b4d",
@@ -102,8 +106,8 @@
       "docsHash": "sha256:2912898abad7c64b3e8f5669a86a70249c4d2fe742aaf3bd9b662cbaa1225a23"
     },
     "inspect.tree": {
-      "contentHash": "sha256:711eb0748f5d70258fb9f0e0eaf046e860955dfc00f4c93d705c9c04284fc31e",
-      "docsHash": "sha256:9ce8cda143b1a4952ece88a51be0cbcb36ea7e694d3d9fb3c1fba13f74588dc1"
+      "contentHash": "sha256:db064a9b7ddc8ba2530fadc7aebf214d0cf9551f2fc771b113cbd4b4511254d1",
+      "docsHash": "sha256:91c81dae81527cc7e1ddce28810540543a19487a49294402787d384c7abd4a9d"
     },
     "inspect.duplicates": {
       "contentHash": "sha256:08b6216d3c4ccd2460befec53559451b34af7157f2742b026bfe2a6babda1033",

package/dist/help/index.md

@@ -6,6 +6,8 @@
 - Docs help-format: [File](<docs/help-format.md>)
 - Help basics: [File](<topics/basics.md>)
 - Docs basics: [File](<docs/basics.md>)
+- Help first-setup: [File](<topics/first-setup.md>)
+- Docs first-setup: [File](<docs/first-setup.md>)
 - Help dsl: [File](<topics/dsl.md>)
 - Docs dsl: [File](<docs/dsl.md>)
 - Help patterns: [File](<topics/patterns.md>)
@@ -61,6 +63,8 @@
 - json Docs help-format: [File](<json/docs/help-format.md>)
 - json Help basics: [File](<json/topics/basics.md>)
 - json Docs basics: [File](<json/docs/basics.md>)
+- json Help first-setup: [File](<json/topics/first-setup.md>)
+- json Docs first-setup: [File](<json/docs/first-setup.md>)
 - json Help dsl: [File](<json/topics/dsl.md>)
 - json Docs dsl: [File](<json/docs/dsl.md>)
 - json Help patterns: [File](<json/topics/patterns.md>)
@@ -116,6 +120,8 @@
 - dsl Docs help-format: [File](<dsl/docs/help-format.md>)
 - dsl Help basics: [File](<dsl/topics/basics.md>)
 - dsl Docs basics: [File](<dsl/docs/basics.md>)
+- dsl Help first-setup: [File](<dsl/topics/first-setup.md>)
+- dsl Docs first-setup: [File](<dsl/docs/first-setup.md>)
 - dsl Help dsl: [File](<dsl/topics/dsl.md>)
 - dsl Docs dsl: [File](<dsl/docs/dsl.md>)
 - dsl Help patterns: [File](<dsl/topics/patterns.md>)

package/dist/help/json/bootstrap.md

@@ -178,10 +178,19 @@ shortestAlias  rewrite to the shortest valid alias specifier
 preferAlias:
 @shared/*      prefer one alias pattern when several aliases can resolve the same file
 
-inspect.graph.exclude skips files before graph builds the model.
-Use it for generated files, backups, local copies, or other paths that make graph output noisy.
-
-Excluded files do not affect graph counts, hubs, entrypoints, leaves, edges, imports, importedBy, or saved graph files.
+AIB has four config exclude fields:
+inspect.graph.exclude
+inspect.tree.files.exclude
+inspect.tree.onlyDirs.exclude
+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.
 
@@ -744,24 +753,25 @@ Inspect Tree
 Use tree to list a compact directory layout.
 It is useful before focused inspect when you know the area but not the exact file.
 
-node_modules, .git, dist, build, out, and .tmp are skipped by default.
-
 Controls:
-scope, depth, minDepth, limit, include, exclude, onlyDirs
+scope, depth, minDepth, limit, only, exclude, onlyDirs, ned, nec
 
 Specific:
 depth     max nesting depth; depth=N
 minDepth  hide shallower paths; minDepth=N
 onlyDirs  show directories only; +onlyDirs
-exclude   skip matching files/dirs
-include   only matching files/dirs; include=[...]
+only      keep only matching files/dirs; only=[...]
+exclude   skip matching files/dirs; exclude=[...]
+ned       no-default-exclude; show paths hidden by built-in excludes; +ned
+nec       no-config-exclude; ignore inspect.tree.*.exclude from aib.json; +nec
 
 Run:
 aib inspect --stdin
 
 Input:
-tree src depth=4 +onlyDirs limit=200
-tree @svc depth=3 include=["**/*.ts"] exclude=["**/*.test.ts","**/* copy.ts"]
+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