ci: merge staging to master

.matrixai/matrixai-standards/standards/HOTSET.md

@@ -7,11 +7,11 @@
 - [MXS-TOOL-003] Linting MUST surface `matrixai-lint`; auto-fix uses `npm run lintfix`.
 - [MXS-ARCH-001] Source code MUST live under `src/` with domain subfolders where needed and barrels exporting domain surfaces.
 - [MXS-ARCH-002] Tests MUST mirror exported domains under `tests/` with matching subjects (class/domain-focused).
-- [MXS-ARCH-003] Public surface MUST be re-exported via `src/index.ts` plus optional `types.ts`, `errors.ts`, `events.ts` to keep a single import locus.
+- [MXS-ARCH-003] Public surface MUST be re-exported via `src/index.ts` plus optional `types.ts`, `errors.ts`, `events.ts` to keep a single import locus. Barrels SHOULD prefer direct re-exports (`export ... from`).
 - [MXS-ARCH-004] Domain error/event classes MUST be defined in-repo (e.g., `errors.ts` or domain files) and exported through barrels; shared bases may be local to the library.
 - [MXS-TS-001] For NodeNext-based profiles (e.g. `library-js`, `application-js`), TypeScript MUST target `ES2022` with `module` + `moduleResolution` `NodeNext`.
 - [MXS-TS-002] `strictNullChecks` MUST remain true. Emit behavior is profile-specific (e.g. NodeNext profiles compile to `dist/`; Cloudflare Worker profiles are IDE-only).
-- [MXS-TS-003] For NodeNext-based profiles, path alias `#*` MUST resolve to `./dist/*` via package `imports` and TS `paths` to `src/*`; preserve aliases in imports.
+- [MXS-TS-003] For `library-js` and `application-js`, internal import specifiers `#*` MUST resolve to `./dist/*` via package `imports`; therefore `#*` MUST be used only by code under `tests/` and those tests MUST run after a build step. TypeScript `paths` MAY map `#*` to `./src/*` for typechecking. This does not apply to `worker-js-cloudflare` or `docusaurus-js-cloudflare`.
 - [MXS-TS-004] Decorators MAY be enabled when the library uses them; when enabled keep `experimentalDecorators: true` across TS and Jest/SWC.
 - [MXS-TEST-001] Jest config MUST retain SWC transform with module-aware mapper stripping `.js` extensions and setup hooks.
 - [MXS-TEST-002] Default test timeout is 20s and should be overridden per slow test via Jest timeouts.

.matrixai/matrixai-standards/standards/architecture/repo-ontology.md

@@ -4,7 +4,7 @@
 - [MXS-ARCH-ONT-003] Tests MUST mirror exported domains (class/domain-focused) under `tests/` with matching subjects and barrel coverage.
 - [MXS-ARCH-ONT-004] Generated artifacts stay in `dist/`; docs in `docs/`; benches under `benches/` writing to `benches/results/` when present.
 - [MXS-ARCH-ONT-005] Public exports of error/event classes MUST be defined locally (per-domain files or `errors.ts`/`events.ts`) and aggregated via barrels; shared bases MAY be local to the library.
-- [MXS-ARCH-ONT-006] Use path alias `#*` for intra-repo imports (`imports` map to `./dist/*`, TS `paths` to `src/*`) to avoid brittle relatives and keep ESM compatibility.
+- [MXS-ARCH-ONT-006] For repos using profiles `library-js` or `application-js`, `#...` imports are internal-only and MUST be used only under `tests/` (not in `src/` nor scripts). In these profiles, `package.json` `imports` maps `#*` to `./dist/*`, so `#...` resolves to compiled output in `dist/`; build/compile MUST occur before running tests that import via `#...`. This rule does not apply to `worker-js-cloudflare` nor `docusaurus-js-cloudflare`.
 - [MXS-ARCH-ONT-007] Package boundaries MUST declare `type: module`, an `exports` map for `.` plus `./*.js` patterns and wildcard passthrough `./*` to `dist`; deep imports are only allowed where the wildcard is intentionally exposed.
 - [MXS-ARCH-ONT-008] Module ontology SHOULD favor class-per-file domain objects with shared helpers (`utils`, `types`, optional `errors`, optional `events`) and domain submodules when needed.
 - [MXS-ARCH-ONT-009] When a repo uses profile `worker-js-cloudflare`, the Worker deploy surface MUST be treated as architecture (repo boundary / deploy contract): Worker entrypoint [`src/worker.ts`](../profiles/worker-js-cloudflare.md#rules) and Worker module subtree `src/worker/**` define the boundary consumed by Wrangler via `wrangler.toml`; agents MUST route placement/layout decisions for this surface to architecture standards, not coding standards. See also: [`../profiles/worker-js-cloudflare.md`](../profiles/worker-js-cloudflare.md), [`worker-js-cloudflare.md`](worker-js-cloudflare.md).
@@ -46,7 +46,7 @@
     }
   }
   ```
-- Test layout mirroring domain barrels `tests/locks/Barrier.test.ts`:
+- Test layout mirroring domain barrels `tests/locks/Barrier.test.ts` (library-js/application-js: `#...` in tests resolves to `dist/` via package `imports`; build first):
   ```ts
   import { Barrier } from '#locks/Barrier.js';
 

.matrixai/matrixai-standards/standards/architecture/testing-quality.md

@@ -1,5 +1,6 @@
 # Rules
 - [MXS-ARCH-TQ-001] All tests MUST run via `npm test` to ensure the TypeScript build step precedes Jest and shares the same compiler options.
+- [MXS-ARCH-TQ-009] For repos using profiles `library-js` or `application-js`, `#...` imports are internal-only and MUST be used only under `tests/` (not in `src/` nor scripts). In these profiles, `package.json` `imports` maps `#*` to `./dist/*`, so `#...` resolves to compiled output in `dist/`; build/compile MUST occur before running tests that import via `#...`. This rule does not apply to `worker-js-cloudflare` nor `docusaurus-js-cloudflare`.
 - [MXS-ARCH-TQ-002] Jest config MUST keep SWC transform with decorator flag, Node env, and ESM extensions to match TS settings.
 - [MXS-ARCH-TQ-003] Default timeout is 20s; long-running tests MUST override per-test timeout argument.
 - [MXS-ARCH-TQ-004] Tests MUST mirror domain layout (e.g., `tests/client/handlers/*` for client handlers) to keep coverage traceable.
@@ -37,7 +38,7 @@
     jest.useRealTimers();
   });
   ```
-- Test wrapper pattern mirroring domain layout `tests/client/handlers/agent.test.ts`:
+- Test wrapper pattern mirroring domain layout `tests/client/handlers/agent.test.ts` (library-js/application-js: `#...` in tests resolves to `dist/` via package `imports`; build first):
   ```ts
   import { handleAgent } from '#client/handlers/agent.js';
 

.matrixai/matrixai-standards/standards/coding/typescript/HOTSET.md

@@ -3,23 +3,28 @@
 - [MXS-TS-HOT-002] Keep `strictNullChecks: true`; `noImplicitAny` MAY remain false if inherited; `noEmit: true` in dev, emit only in build config.
 - [MXS-TS-HOT-003] Decorators MAY be enabled where used; when enabled, keep `experimentalDecorators: true` across TS and Jest/SWC.
 - [MXS-TS-HOT-004] Use ESM imports with explicit `.js` extensions in local paths; Jest mapper MUST strip `.js` to real sources.
-- [MXS-TS-HOT-005] Path alias `#*` MUST point to `src/*` (TS `paths`) and `./dist/*` (package `imports`); prefer aliases over deep relatives.
+- [MXS-TS-HOT-005] Path alias `#*` MUST point to `src/*` (TS `paths`) and `./dist/*` (package `imports`).
 - [MXS-TS-HOT-006] Keep `noEmit: true` in dev tsconfig; emit only in `tsconfig.build.json` with `rootDir: ./src`.
 - [MXS-TS-HOT-007] Include `src`, `tests`, `scripts`, optional `benches` in TS includes; avoid stray TS outside these roots.
 - [MXS-TS-HOT-008] Use `esModuleInterop` and `allowSyntheticDefaultImports` for compatibility with CJS deps.
 - [MXS-TS-HOT-009] Use `resolveJsonModule: true` for config JSON imports; keep JSON colocated in `src` when bundled.
 - [MXS-TS-HOT-010] Prefer explicit type exports (`export type *` or named type exports) in barrels to avoid runtime cost and circulars.
+- [MXS-TS-HOT-010A] Barrel modules (e.g., `src/index.ts` and per-domain `index.ts`) SHOULD prefer direct re-exports (`export ... from`) instead of `import ...` only to immediately re-export. Use `import` + `export` when composition is needed (e.g., merging namespaces, computed constants, side-effectful setup ordering).
 - [MXS-TS-HOT-011] Error classes MUST be defined in-repo and exported via barrels; shared bases MAY be library-local (no external base coupling).
 - [MXS-TS-HOT-012] Event classes MUST be defined in-repo and exported via barrels when present; avoid external base dependencies.
 - [MXS-TS-HOT-013] Shared utility types SHOULD live in `types.ts` or equivalent namespaces; prefer reuse over ad-hoc definitions.
-- [MXS-TS-HOT-014] Tests MUST import via aliases (`#...`) or barrel paths to mirror production imports; avoid brittle relatives.
+- [MXS-TS-HOT-014] Tests SHOULD import via aliases (`#...`) or barrel paths to mirror production imports; avoid brittle relatives.
 - [MXS-TS-HOT-015] Jest ESM configs MUST rely on SWC without requiring `NODE_OPTIONS=--experimental-vm-modules` unless the project explicitly needs it; prefer mapper-based resolution.
 - [MXS-TS-HOT-016] Async tests MUST respect shared timeouts (20s default) and override per case; avoid unbounded waits.
 - [MXS-TS-HOT-017] SWC transform SHOULD keep class names (`keepClassNames: true`) when identity matters for errors/events.
 - [MXS-TS-HOT-018] Module name mapper MUST strip `.js` extensions for TS resolution in tests.
 - [MXS-TS-HOT-019] Avoid implicit globals; pass dependencies (e.g., loggers, fs, options) explicitly into functions/constructors.
 - [MXS-TS-HOT-020] Maintain `skipLibCheck: true` unless library types are fully clean.
-- [MXS-TS-HOT-021] Exports SHOULD be consolidated at the end of the module. Prefer `const thing = ...; export default thing;` over inline default exports like `export default { ... }` so the module's declarations read top-down and the export surface is easy to audit.
+- [MXS-TS-HOT-021] Exports SHOULD be consolidated at the end of the module. Avoid `export default` except for singleton-style domain objects/classes (e.g., a single container or domain instance) or module-level constants where a default is more ergonomic; otherwise prefer named exports.
+- [MXS-TS-HOT-022] Use `@matrixai/errors` and keep error classes/types per domain in domain-local `errors.ts` (or equivalent) modules; export them through the domain barrel and the public barrel.
+- [MXS-TS-HOT-023] `types.ts` SHOULD export types only. If runtime enums/values are also exported, place type exports before value exports (`export type { ... };` then `export { ... };`).
+- [MXS-TS-HOT-024] Barrel re-export of `types.ts`: use `export type * as types from './types.js';` when `types.ts` is types-only; use `export * as types from './types.js';` when it exports runtime values (e.g., enums).
+- [MXS-TS-HOT-025] Prefer shallow domain layering. Wire dependency injection in a higher-level container (e.g., app/worker/server container), not inside lower domains. Domains must not instantiate the logger; pass logging and other infra via DI.
 
 ## Exhibits (non-normative)
 - Exhibit: NodeNext tsconfig sketch

.matrixai/matrixai-standards/standards/profiles/application-js.md

@@ -19,6 +19,7 @@
 - `src/` domain folders: `agent/`, `bootstrap/`, `identities/`, `keys/`, `nodes/`, `notifications/`, `secrets/`, `vaults/`, `utils/`, plus supporting `audit/`, `auth/`, `Command*.ts`, `polykey.ts`, `errors.ts`, `types.ts`, any worker manifest files, and a barrel at `src/index.ts` exporting per-domain entrypoints.
 - Tests mirror domains under `tests/` with global harness files (`globalSetup.ts`, `setup.ts`, `setupAfterEnv.ts`, `globalTeardown.ts`) and integration suites under `tests/integration/docker/` (or equivalent integration roots).
 - Build artifacts in `dist/`; docs in `docs/`; tmp outputs under `tmp/jest` and `tmp/junit` as per Jest config.
+- Local dev env (when using Nix flakes + direnv): keep `.envrc` committed (loads `use flake` and optional `.envr`), keep `.envr` local-only (gitignored), and never commit `/.direnv`.
 
 ## Golden commands
 - Install deps: `npm install` (within `nix develop` when applicable).

.matrixai/matrixai-standards/standards/profiles/library-js.md

@@ -8,7 +8,7 @@
 - [MXS-PROF-LIBJS-007] Public API MUST be aggregated through `src/index.ts` plus optional `types.ts`, `errors.ts`, `events.ts`; per-domain barrels SHOULD exist when domains are present.
 - [MXS-PROF-LIBJS-008] Directory layout SHOULD keep domain subfolders when domains exist (e.g., handlers, tracer, locks) with matching tests under `tests/`.
 - [MXS-PROF-LIBJS-009] TypeScript config MUST target `ES2022`, `moduleResolution`/`module` `NodeNext`, `strictNullChecks: true`, `noEmit: true` in dev; decorators MAY be enabled when used; build overrides only `rootDir`/`noEmit`.
-- [MXS-PROF-LIBJS-010] Path alias `#*` MUST resolve to `src/*` in TS and `./dist/*` in package `imports`; use aliases in source and tests.
+- [MXS-PROF-LIBJS-010] Path alias `#*` MUST resolve to `src/*` in TS and `./dist/*` in package `imports`.
 - [MXS-PROF-LIBJS-011] Jest config MUST keep SWC transform, module-aware mapper stripping `.js`, Node env, and setup hooks; decorator flag only when decorators are used.
 - [MXS-PROF-LIBJS-012] Default test timeout is 20s; override per test as needed using Jest timeout parameter.
 - [MXS-PROF-LIBJS-013] Shell linting is out of scope for this profile.
@@ -22,6 +22,7 @@
 - Barrel files: `src/index.ts`, optional `src/types.ts`, optional `src/errors.ts`, optional `src/events.ts`, and per-domain `index.ts` that re-export types/utils/errors/events when present.
 - Tests mirror domains under `tests/` with matching subjects (class/domain-focused) and barrel coverage.
 - Build artifacts in `dist/`; docs in `docs/`; optional benches in `benches/` writing to `benches/results/`.
+- Local dev env (when using Nix flakes + direnv): keep `.envrc` committed (loads `use flake` and optional `.envr`), keep `.envr` local-only (gitignored), and never commit `/.direnv`.
 
 ## Golden commands
 - Install: `npm install --package-lock-only --ignore-scripts --silent` (for versioning).

.matrixai/matrixai-standards/standards/profiles/worker-js-cloudflare.md

@@ -19,6 +19,7 @@
 - Worker entry at `src/worker.ts` with Worker modules under `src/worker/**`.
 - `package.json` with scripts `dev`, `deploy`, `lint`, `lintfix`, and any project-specific tasks.
 - `tsconfig.json` using `moduleResolution: "bundler"`, `noEmit: true`, and `ES2022` libs for IDE tooling only.
+- Local dev env (when using Nix flakes + direnv): keep `.envrc` committed (loads `use flake` and optional `.envr`), keep `.envr` local-only (gitignored), and never commit `/.direnv`.
 
 ## Golden commands
 - Dev server: `npm run dev` (invokes `wrangler dev`, pass-through args supported).

.matrixai/matrixai-standards/templates/.gitignore.template

@@ -5,8 +5,145 @@
 .env*
 !.env.example
 !.envrc
+# nix
 /result*
 /builds
+# node-gyp
+/build
+# prebuildify
+/prebuilds
+# docusaurus
+/public
+.docusaurus
+.cache-loader
+# wrangler
+.wrangler
+.dev.vars
+/wrangler.deploy.toml
+# github output
+/output
+
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+web_modules/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Microbundle cache
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variables file
+.env
+.env.test
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+.parcel-cache
+
+# Next.js build output
+.next
+out
+
+# Nuxt.js build / generate output
+.nuxt
+dist
+
+# Gatsby files
+.cache/
+# Comment in the public line in if your project uses Gatsby and not Next.js
+# https://nextjs.org/blog/next-9-1#public-directory-support
+# public
+
+# vuepress build output
+.vuepress/dist
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# TernJS port file
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+.vscode-test
+.vscode
+
+# Neo4j Local DB files
+neo4j/
+
+# yarn v2
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
+.yarn/install-state.gz
+.pnp.*
+
 .DS_Store
 .idea
 .aider*

.matrixai/matrixai-standards/templates/README.md

@@ -6,7 +6,8 @@
 
 ## Baseline files (always include)
 - [.editorconfig](.editorconfig.template) - enforce LF, 2-space indent, trim whitespace.
-- [.gitignore](.gitignore.template) - general ignores; extend per language as needed.
+- [.gitignore](.gitignore.template) - general ignores; includes `/.direnv` ignore and `.env*` ignore with `!.envrc` and `!.env.example` so local env files stay uncommitted while examples remain tracked.
+- [.envrc](.envrc.template) - direnv entrypoint; uses `use flake` and optionally loads `.envr` for local-only overrides.
 - [AGENTS.md](AGENTS.md.template) - entrypoint for automation; fill golden commands per repo.
 - [.aider.conf.yml](.aider.conf.yml.template) - aider wiring; points aider at repo-root `AGENTS.md`.
 - [./.matrixai/repo-profile.yml](.matrixai/repo-profile.yml.template) - select profile (`library-js` default; others listed inside template).
@@ -24,7 +25,7 @@ Generated artifacts (do **not** template):
 - Add additional overlays by creating subfolders under `templates/<profile>/` with only the files that differ from baseline.
 
 ## How to apply
-1) Copy baseline files into the new repo root and fill placeholders (golden commands, profile selection).
+1) Copy baseline files into the new repo root and fill placeholders (golden commands, profile selection). When using Nix flakes + direnv, keep `.envrc` committed, use `.envr` for local secrets/overrides (gitignored), and never commit `/.direnv`.
 2) Choose a profile overlay and copy its files; extend [.gitignore](.gitignore.template) if the language/toolchain needs more ignores. For Cloudflare profiles, the overlays include:
    - `worker-js-cloudflare`: TypeScript config (`tsconfig.json.template`) with `types` set to `node` and `@cloudflare/workers-types` (nodejs_compat), plus `@types/node` and `@cloudflare/workers-types` in devDependencies.
    - `docusaurus-js-cloudflare`: TypeScript config with Docusaurus + Worker ambient `types`, optional `global.d.ts` stubs for resource-query imports (`?raw`, `?inline`, `?url`), and Webpack-friendly typing. Remove `global.d.ts` if you do not use those queries.

.matrixai/matrixai-standards/templates/application-js/tsconfig.json.template

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "incremental": true,
+    "sourceMap": true,
+    "allowJs": true,
+    "strictNullChecks": true,
+    "noImplicitAny": false,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "moduleResolution": "NodeNext",
+    "module": "NodeNext",
+    "target": "ES2022",
+    "baseUrl": "./src",
+    "paths": {
+      "#*": ["*"]
+    },
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": [
+    "./src/**/*",
+    "./tests/**/*",
+    "./scripts/**/*",
+    "./benches/**/*"
+  ]
+}

.matrixai/matrixai-standards/templates/library-js/tsconfig.json.template

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "incremental": true,
+    "sourceMap": true,
+    "allowJs": true,
+    "strictNullChecks": true,
+    "noImplicitAny": false,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "moduleResolution": "NodeNext",
+    "module": "NodeNext",
+    "target": "ES2022",
+    "baseUrl": "./src",
+    "paths": {
+      "#*": ["*"]
+    },
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": [
+    "./src/**/*",
+    "./tests/**/*",
+    "./scripts/**/*",
+    "./benches/**/*"
+  ]
+}