agentsmesh 0.3.1 → 0.6.0

package/CHANGELOG.md

@@ -1,6 +1,114 @@
 # Changelog
 
-## Next version
+## 0.6.0 - 2026-04-25
+
+### Added
+
+- **Full plugin parity with built-in targets** — plugin targets now have access to the same runtime capabilities as built-in targets:
+  - **Conversion support**: plugins can declare `supportsConversion: { commands: true, agents: true }` and users can configure `commands_to_skills` / `agents_to_skills` for plugin target IDs in `agentsmesh.yaml`. The conversion schema now accepts arbitrary target IDs alongside hardcoded builtins. Conversion values support per-scope control: `foo-ide: { project: true, global: false }` or the shorthand `foo-ide: true` for both scopes.
+  - **Global mode**: plugin descriptors that define `global` or `globalSupport` layouts, `globalCapabilities`, and `globalDetectionPaths` are fully resolved by the engine — `generate --global`, `import --global`, `lint --global`, and `matrix --global` all work with plugin targets.
+  - **Scoped settings emission**: `emitScopedSettings` hooks on plugin descriptors are now called during generation (previously only checked on builtins).
+  - **Hook post-processing**: `postProcessHookOutputs` hooks on plugin descriptors are now called during the hook generation pass.
+  - **Per-feature lint hooks**: `lint.commands`, `lint.mcp`, `lint.permissions`, `lint.hooks`, and `lint.ignore` on plugin descriptors receive `{ scope }` context for project vs global differentiation.
+  - **Unified generator resolution**: a single code path (`resolveTargetFeatureGenerator`) resolves generators for both builtins and plugins, removing duplicate resolution logic from the engine.
+- **Plugin support in all CLI commands** — `diff`, `check`, `matrix`, and `import --from <plugin-id>` now bootstrap and resolve plugin targets. Previously only `generate` and `lint` supported plugins.
+- **Richer target scaffold** — `agentsmesh target scaffold` now generates descriptors with global layout, `globalCapabilities`, `globalDetectionPaths`, `supportsConversion`, per-feature lint hook stubs, and `rewriteGeneratedPath` for global path rewriting.
+- **Comprehensive plugin test fixture** (`tests/fixtures/plugins/rich-plugin/`) — covers 100% of `TargetDescriptor` fields including all 8 feature generators, per-feature lint hooks, project and global layouts with output families, shared artifacts, scope extras, scoped settings, hook post-processing, and conversion support.
+- **Typed root barrel export** — `import { generate, importFrom, loadCanonical, registerTargetDescriptor } from 'agentsmesh'` now resolves to a proper `.d.ts` under strict TypeScript. The root `exports."."` is a conditional block with `types`, `import`, and `default`, pointing at a new public barrel (`src/public/index.ts`). Closes `TS7016: Could not find a declaration file for module 'agentsmesh'` that appeared for any downstream TS consumer.
+- **Typed error taxonomy exported from the public API** — `AgentsMeshError` base class plus 8 concrete subclasses (`ConfigNotFoundError`, `ConfigValidationError`, `TargetNotFoundError`, `ImportError`, `GenerationError`, `RemoteFetchError`, `LockAcquisitionError`, `FileSystemError`), each carrying a stable `code` field (`AM_CONFIG_NOT_FOUND`, `AM_CONFIG_INVALID`, `AM_TARGET_NOT_FOUND`, `AM_IMPORT_FAILED`, `AM_GENERATION_FAILED`, `AM_REMOTE_FETCH_FAILED`, `AM_LOCK_ACQUISITION_FAILED`, `AM_FILESYSTEM`). Programmatic consumers can branch on `err instanceof ConfigNotFoundError` or `err.code === 'AM_CONFIG_INVALID'` without parsing error message strings. Error throw sites in `src/config/core/loader.ts` and `src/utils/filesystem/fs.ts` now emit typed errors; stack-trace context and `cause` chains preserved.
+- **Canonical domain types in the public barrel** — 14 types (`CanonicalFiles`, `CanonicalRule`, `CanonicalCommand`, `CanonicalAgent`, `CanonicalSkill`, `SkillSupportingFile`, `Permissions`, `IgnorePatterns`, `McpServer`, `StdioMcpServer`, `UrlMcpServer`, `McpConfig`, `Hooks`, `HookEntry`) are now exported from `agentsmesh` and `agentsmesh/canonical`. Programmatic consumers can finally type the result of `loadCanonical()` without reaching into internal modules.
+- **Process-level lock for concurrent `generate`** — `agentsmesh generate` acquires an atomic mkdir-based lock at `.agentsmesh/.generate.lock` before writing. Concurrent generates serialize cleanly; stale locks (dead PID on the same host, or age > 60 seconds) are evicted automatically; `SIGINT`/`SIGTERM`/normal exit release the lock idempotently. Dry-run and check-only modes skip the lock. Watch mode's lock-file ignore list was extended so self-triggered generate passes do not retrigger the watcher.
+- **Cross-platform CI matrix** — quality gates now run on `ubuntu-latest` × Node 20/22/24, plus `windows-latest` × Node 22 and `macos-latest` × Node 22. Previously only `ubuntu-latest` × Node 22. E2E tests run on Linux and macOS; Windows runs lint/typecheck/unit/build.
+- **Packaging guards in CI** — three new gates run on every push in a dedicated `smoke` job:
+  - `publint` — package.json metadata sanity (exports ordering, `files`, module type).
+  - `@arethetypeswrong/cli` with the `esm-only` profile — verifies every public entrypoint resolves to types under `node16 (from ESM)` and `bundler` module resolution.
+  - `tests/consumer-smoke/` — packs the tarball, installs it into a throwaway strict-mode TS project, and runs `tsc --noEmit` against every public symbol (runtime functions, canonical types, target-descriptor types, and error classes). Catches `TS7016` and type-resolution regressions that packaging-metadata checks miss.
+  - Also runnable locally via `pnpm publint`, `pnpm attw`, `pnpm consumer-smoke`.
+- **Post-pack smoke test in CI** — the `smoke` job installs the packed tarball with `npm install -g` and verifies `agentsmesh --version`, `agentsmesh --help`, `amsh --version`, and `agentsmesh init --yes` all succeed in a clean temp project. Catches broken shebangs, missing files from the `files` array, and bin misconfiguration before publish.
+- **`docs/add-new-target-playbook.md`** — self-contained guide for adding a new target (built-in or external plugin, project and global mode) designed to be handed to an AI coding agent. Covers research checklist, scaffold workflow, descriptor filling, realistic fixtures, strict-assertion test patterns, registration file wiring, matrix/docs updates, and a verification one-liner. Referenced by the canonical `add-agent-target` skill as the authoritative workflow document.
+- **Boot-time guard against ambiguous shared-artifact ownership** — `BUILTIN_TARGETS` initialization now runs `assertSharedArtifactOwnersUnique()` (`src/targets/catalog/shared-artifact-owner.ts`) and throws if two descriptors claim the same or overlapping `sharedArtifacts: { '<prefix>': 'owner' }` entry. Previously the rewriter would silently pick the first match by iteration order, so a misconfigured plugin or future builtin could quietly route global skill writes to the wrong target. The error names both target IDs and both prefixes and suggests changing one role to `'consumer'` or namespacing the prefix. Covered by `tests/unit/targets/catalog/shared-artifact-owner.test.ts` (9 cases including identical-prefix conflicts, prefix-overlap conflicts, owner-vs-consumer non-conflicts, and the live builtin set).
+- **Cross-process race coverage for the generate lock** — `tests/integration/generate-process-lock.integration.test.ts` now proves two parallel `node dist/cli.js generate` invocations against the same project serialize via the existing process lock, both exit `0`, produce deterministic output, and release `.agentsmesh/.generate.lock` after the run. Complements the existing unit tests that exercise `acquireProcessLock` directly.
+- **End-to-end Copilot dual-mirror coverage** — `tests/unit/targets/copilot/global-layout.test.ts` adds two engine-level assertions that prove Copilot's `mirrorGlobalPath` emits the exact set `.copilot/skills/<name>/`, `.agents/skills/<name>/`, and `.claude/skills/<name>/` in global mode when codex-cli is not active, and skips the `.agents/skills/` mirror when codex-cli is generated alongside (so codex-cli's `'owner'` claim wins).
+- **Programmatic API: complete `lint`, `diff`, `check`, and config-loader surface** — every CLI capability is now callable as a typed function. New exports from `agentsmesh` and `agentsmesh/engine`:
+  - `loadConfig(projectRoot)` and `loadConfigFromDirectory(configDir)` — load + validate `agentsmesh.yaml` (merging `agentsmesh.local.yaml`) and return `{ config: ValidatedConfig, configDir }`. Throws `ConfigNotFoundError` / `ConfigValidationError` with stable `code` fields.
+  - `lint(opts)` — runs target linters, returns `{ diagnostics, hasErrors }`. Pure: no I/O, no logging.
+  - `diff(ctx)` — runs generate internally, returns `{ results, diffs, summary }`. Plus `computeDiff(results)` and `formatDiffSummary(summary)` helpers for callers that already have generate results.
+  - `check(opts)` — pure lock-vs-current drift detection backed by the new shared `src/core/check/lock-sync.ts` module. Returns a structured `LockSyncReport` (`inSync`, `hasLock`, `modified`, `added`, `removed`, `extendsModified`, `lockedViolations`). The `agentsmesh check` CLI command was refactored to use the same helper so CLI and Programmatic API can never drift.
+  - New types: `ValidatedConfig`, `TargetLayoutScope`, `LintOptions`, `LintResult`, `LintDiagnostic`, `ComputeDiffResult`, `DiffEntry`, `DiffSummary`, `CheckLockSyncOptions`, `LockSyncReport`.
+- **Programmatic API runtime coverage** — new `tests/integration/programmatic-api.integration.test.ts` (21 strict assertions) exercises every public function and every error class against real fixture state: shape inventory, `loadConfig` happy/missing/invalid-schema paths, `loadCanonical`, `generate` with exact-paths assertion, `targetFilter` narrowing, `registerTargetDescriptor` plugin wiring through `generate`, `importFrom` end-to-end, `lint` shape, `diff` + `computeDiff` summary parity, `check` for `hasLock=false` / `inSync=true` / modified-drift, catalog inspection, `resolveOutputCollisions`. Replaces the previous shallow `public-export-smoke.integration.test.ts` (which only checked `typeof === 'function'` and used loose `length > 0` assertions).
+- **Programmatic API type contract coverage** — `tests/consumer-smoke/src/smoke.ts` extended to import every new symbol (`loadConfig`, `loadConfigFromDirectory`, `lint`, `diff`, `check`, `computeDiff`, `formatDiffSummary`, `ValidatedConfig`, `LintOptions`, `LintResult`, `CheckLockSyncOptions`, `LockSyncReport`, `ComputeDiffResult`, `DiffEntry`, `DiffSummary`) and exercise them with no `unknown` casts (the previous `as unknown as ValidatedConfig` hack is gone now that the type is public). `pnpm consumer-smoke` packs the tarball, installs into a strict-mode TS project, and `tsc --noEmit`s the full surface — catches `TS7016` and signature regressions before publish.
+- **Dedicated Programmatic API reference page** at `website/src/content/docs/reference/programmatic-api.mdx` — entrypoint table, the canonical 4-line generate pattern, per-function signatures and examples for `loadConfig` / `loadCanonical` / `generate` / `importFrom` / `lint` / `diff` / `check` / `registerTargetDescriptor` / catalog inspection, full error taxonomy table, canonical types, target-descriptor types, and stability guarantees. Linked from the landing page and sidebar Reference section. README "Programmatic API" section rewritten so the example actually compiles (the previous snippet omitted the required `config` and `canonical` fields of `GenerateContext`).
+
+### Changed
+
+- **Production-grade build output** — `tsup.config.ts` reworked with a split policy that matches the two artifact families:
+  - **CLI binary (`dist/cli.js`)**: minified with `keepNames: true` so stack traces still reference real function/class names. Sourcemap no longer shipped to npm — with `keepNames` the minified stack traces remain debuggable from error text alone, and the 1.6 MB sourcemap was dead weight for the 99% of users who never debug into CLI internals (maintainers reproduce locally with sourcemap on).
+  - **Library entries (`dist/{index,engine,canonical,targets}.js`)**: unminified (consumers' bundlers minify their own output — standard convention used by React, Vue, Vitest, tsup itself), sourcemaps shipped (consumers stepping into library code from their own debugger get a usable experience).
+  - Explicit `treeshake: true` on both bundle families.
+  - Net effect: `dist/cli.js` 643 KB → 325 KB (-49%); compressed npm tarball 1.21 MB → 923 KB (-24%); unpacked install 6.0 MB → 4.75 MB (-21%). CLI cold-start parse time drops correspondingly.
+- **Conversion config schema**: inner `commands_to_skills` and `agents_to_skills` objects changed from `.strict()` to `.passthrough()`, allowing plugin target IDs without validation errors. The outer `conversions` object remains strict. Conversion values now accept either `boolean` (both scopes) or `{ project?: boolean, global?: boolean }` for per-scope control.
+- **Conversion helpers**: `shouldConvertCommandsToSkills` and `shouldConvertAgentsToSkills` accept optional `defaultEnabled` and `scope` parameters. Per-scope config values are resolved against the active scope, with missing scope keys falling back to builtin defaults.
+- **Builtin-targets module**: five lookup functions (`getTargetCapabilities`, `getTargetDetectionPaths`, `getTargetLayout`, `getEffectiveTargetSupportLevel`, `resolveTargetFeatureGenerator`) now fall back to the plugin registry via `getDescriptor()` when no builtin match is found.
+- **Registry**: `builtinDescriptors` map is now lazily initialized to avoid circular-dependency crashes between `builtin-targets.ts` and `registry.ts`.
+- **JSON Schema**: `schemas/agentsmesh.json` updated — conversion inner objects now use `"additionalProperties": {}` (passthrough) instead of `"additionalProperties": false`.
+- **`agentsmesh generate --global` log output** — generated file paths now display with a `~/` prefix (e.g. `✓ updated ~/.claude/settings.json`) so users cannot mistake a home-directory write for a project-local write. Applies to dry-run, check-only, and success output. Project-mode display is unchanged.
+- **`writeFileAtomic` safety hardening** — orphaned `.tmp` sidecars are now removed on rename failure. Target paths that already exist as directories throw `FileSystemError` with `errnoCode: 'EISDIR'` instead of leaking the raw rename error. Readable error messages preserved with original errors as `cause`.
+- **Remote tar extraction hardening** — `tar.extract` for GitHub tarballs now runs with `strict: true` (promotes warnings to errors) and explicitly rejects `Link` and `SymbolicLink` entries in addition to the existing zip-slip `..` / absolute-path filter. Defense-in-depth against malicious remote packs.
+- **Package metadata**: `main` and `types` point at `./dist/index.{js,d.ts}`; root `exports."."` is a full conditional block. `@arethetypeswrong/cli` and `publint` added as devDependencies. New npm scripts: `publint`, `attw`, `consumer-smoke`.
+- **README**: new **Programmatic API** section with typed import examples for the root barrel and the three subpath entrypoints (`agentsmesh/engine`, `agentsmesh/canonical`, `agentsmesh/targets`).
+- **`--global` commands now throw a scope-aware error when `~/.agentsmesh/agentsmesh.yaml` is missing.** The message points at the exact missing path and suggests `agentsmesh init --global` to create the global canonical root, or dropping `--global` to operate on the current project. Applies uniformly to `generate`, `import`, `lint`, `check`, `diff`, `watch`, and `matrix`. Previously a generic "config not found" error left first-time global users guessing. Covered by `tests/unit/config/scope.test.ts`.
+- **`ConfigNotFoundError` constructor accepts an optional `message` override** (`{ cause?, message? }`) so wrappers can supply scope-aware copy without losing the typed error class, `code`, or `path`. Existing callers that pass only `path` (and optional `cause`) are unchanged.
+
+### Removed
+
+- **Native Windows support deferred to a later release.** `package.json` now declares `"os": ["darwin", "linux"]`, the CI matrix dropped `windows-latest`, and the README's Install section calls this out with WSL2 as a workaround. The deferral path and re-enablement checklist are tracked in `docs/roadmap.md` under "Windows support (deferred)". Three POSIX-correctness fixes that landed in this release as defense-in-depth — `installs.yaml` `source` field always written as POSIX (`src/install/source/parse-install-local.ts`), plugin file-URL conversion via `fileURLToPath` instead of `URL.pathname` (`src/plugins/load-plugin.ts`), and `path.join` used in the canonical extend-load test expectations — already pave the way for the eventual re-enablement.
+
+### Fixed
+
+- **`TS7016` on root import** — `import { ... } from 'agentsmesh'` previously resolved to `./dist/cli.js`, which was built with `dts: false`. Root exports now point at the typed library barrel, and `attw` + `publint` + consumer-smoke guards prevent regression.
+- **Stale coverage exclusion paths in `vitest.config.ts`** — 15 excluded files referenced stale paths after a folder restructure (`src/utils/fs.ts` → `src/utils/filesystem/fs.ts`, `src/config/lock.ts` → `src/config/core/lock.ts`, `src/install/git-pin.ts` → `src/install/source/git-pin.ts`, and others). Paths corrected; one entry for a deleted file (`src/install/local-source.ts`) removed.
+- **Canonical `add-agent-target` skill** — restored mangled prose references (``` `../../` ``` back to ``` `.agentsmesh/` ```); updated stale code touchpoints (`src/config/schema.ts` → `src/config/core/schema.ts`, `src/cli/help.ts` → `src/cli/help-data.ts`, `src/core/matrix/matrix.ts` → `src/core/matrix/data.ts`); added missing registration-file pointers (`target-ids.ts`, `builtin-targets.ts`, `import-maps/index.ts`); named the `agentsmesh target scaffold <id>` scaffold command as the starting step; referenced `docs/add-new-target-playbook.md` for the step-by-step workflow; added `pnpm matrix:verify`, `pnpm publint`, `pnpm attw`, and `pnpm consumer-smoke` to the required verification list.
+
+## 0.5.0 - 2026-04-23
+
+### Added
+
+- **JSON Schema for all config files** — `agentsmesh.yaml`, `agentsmesh.local.yaml`, `.agentsmesh/permissions.yaml`, `.agentsmesh/hooks.yaml`, `.agentsmesh/mcp.json`, and `.agentsmesh/packs/*/pack.yaml` now ship with JSON Schemas derived directly from Zod source schemas. Enables full IDE autocomplete, enum validation, and hover docs in VS Code, JetBrains, and any YAML/JSON Language Server with zero user configuration. Schemas are published to `schemas/` in the npm package and accessible at `https://unpkg.com/agentsmesh/schemas/*.json`. Run `pnpm schemas:generate` to regenerate after schema changes.
+- **`$schema` comment in generated config files** — `agentsmesh init` now writes a `# yaml-language-server: $schema=...` comment as the first line of both `agentsmesh.yaml` and `agentsmesh.local.yaml`, activating IDE validation without any manual setup.
+- **Global mode** (`--global`, canonical `~/.agentsmesh/`) for **all** built-in targets — Claude Code, Cursor, Copilot, Continue, Junie, Kiro, Gemini CLI, Cline, Codex CLI, Windsurf, Antigravity, and Roo Code. Each target has a `descriptor.global` layout with project→user path rewriting, import/generate alignment, optional `~/.agents/skills/` mirroring when Codex CLI is not a global target, reference/link rewriting, and comprehensive test coverage.
+- **Roo Code agents → custom modes**: canonical agents now generate `.roomodes` (project) and `settings/custom_modes.yaml` (global) with a `customModes` YAML structure. Roo Code agents capability upgraded from `—` to `partial`.
+- **Copilot global extras**: `~/.copilot/AGENTS.md` is now generated in global mode as a root-instructions compat file.
+- **Continue global config**: global mode generates `~/.continue/config.yaml` (aggregating rules as `rules:`, commands as `prompts:`, MCP as `mcpServers:`) and `~/.continue/AGENTS.md`.
+- **Copilot global skill mirror**: skills are now mirrored to both `~/.agents/skills/` and `~/.claude/skills/` in global mode.
+- **Cline global hooks round-trip**: `agentsmesh import --from cline` now reads hook scripts from `~/Documents/Cline/Hooks/` (global mode) and `.clinerules/hooks/` (project mode). Hook scripts embed a `# agentsmesh-event: <event>` metadata comment for lossless round-trip; the generator also includes this comment going forward.
+- `sharedArtifacts` field added to target descriptor — enables collision-free generation when multiple targets share an output path (e.g. `.agents/skills/`).
+- Lint hooks wired to all target descriptors.
+- Contributor skill **`add-global-mode-target`** for scoped work when extending or validating one target’s global-mode behavior.
+- Comprehensive structure validation test coverage for all 12 targets in both project and global modes.
+- Shared validation helpers library (`tests/unit/targets/validation-helpers.ts`) with reusable helpers for JSON, Markdown, YAML, frontmatter, and file structure validation.
+
+### Fixed
+
+- **Claude Code output-styles**: generated output-style files no longer carry `agent-` / `command-` filename prefixes — now `{name}.md` as documented.
+- **Windsurf**: `src/AGENTS.md` removed from `managedOutputs` (was incorrectly tracked as a managed file).
+- **Cline**: `.clinerules/` directory added to `managedOutputs.dirs` for correct stale-artifact cleanup after `generate`.
+- **Copilot global instructions**: path-specific instructions now aggregate into `~/.copilot/copilot-instructions.md` in global mode (previously suppressed).
+- **Windsurf MCP capability**: both project and global scopes now consistently `partial` (global was incorrectly `native`).
+- **Codex CLI detection**: detection paths expanded to include `AGENTS.md`, `AGENTS.override.md`, `.codex/config.toml`, `.codex/agents`, and `.codex/rules`.
+- **Link rebaser**: `.agentsmesh/` anchor preserved correctly in generated prose.
+
+### Changed
+
+- **Init scaffold:** example files created by `agentsmesh init` are now prefixed with `_` (`_example.md`, `skills/_example/SKILL.md`). Files and directories with a `_` prefix are excluded from generation, so the starter templates serve as visible reference only and do not produce tool-specific output. `_root.md` remains the sole `_`-prefixed file that is always included in generation.
+- **Documentation:** README and website updated to reflect Roo Code agents support, Copilot and Continue global extras, and the new `schemas/` package contents. `generate.mdx` documents global mode path resolution (how `--global` maps to `homedir()` as `projectRoot`).
+
+### Refactored
+
+- Extracted `mirrorSkillsToAgents()` shared helper (`src/targets/catalog/skill-mirror.ts`) — replaces repeated `!activeTargets.includes(‘codex-cli’)` guards inline across 8 target files.
+- Consolidated import map builders; removed duplicate validation tests.
+- Extracted shared skill-import pipeline; deleted obsolete `skills-helpers` files.
+- Improved link rebaser resolution and managed embedding.
+- Removed unused `COPILOT_GLOBAL_MCP` / `COPILOT_GLOBAL_CONFIG` constants.
 
 ## 0.3.1 - 2026-04-12
 

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-# AgentsMesh
+# AgentsMesh — One AI Coding Config for Every Tool
 
 [![CI](https://github.com/sampleXbro/agentsmesh/actions/workflows/ci.yml/badge.svg)](https://github.com/sampleXbro/agentsmesh/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/agentsmesh.svg)](https://www.npmjs.com/package/agentsmesh)
@@ -12,8 +12,11 @@
 [![Docs](https://img.shields.io/badge/docs-website-brightgreen.svg)](https://samplexbro.github.io/agentsmesh)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/sampleXbro/agentsmesh/pulls)
 
+**One canonical `.agentsmesh/` directory replaces scattered rules, prompts, agents, skills, MCP servers, hooks, ignore files, and permissions across every major AI coding tool.**
 
-AgentsMesh maintains a single canonical configuration in `.agentsmesh/` and syncs it bidirectionally to Claude Code, Cursor, Copilot, Continue, Junie, Kiro, Gemini CLI, Cline, Codex CLI, Windsurf, Antigravity, and Roo Code. Rules, commands, agents, skills, MCP servers, hooks, ignore patterns, and permissions -- all from one source of truth.
+Edit once — generate `CLAUDE.md`, `AGENTS.md`, `.cursor/rules`, `.github/copilot-instructions.md`, `.gemini/settings.json`, `.windsurf/rules`, `.codex/config.toml`, `.kiro/steering`, and more from the same source. Bidirectional import so you can adopt it on existing projects with one command.
+
+**Works with** Claude Code · Cursor · GitHub Copilot · Gemini CLI · Windsurf · Continue · Cline · Kiro · Codex CLI · Junie · Roo Code · Antigravity — and new tools as the ecosystem grows. See the [full feature matrix](https://samplexbro.github.io/agentsmesh/reference/supported-tools/).
 
 </div>
 
@@ -23,97 +26,246 @@ AgentsMesh maintains a single canonical configuration in `.agentsmesh/` and sync
 
 ## Why AgentsMesh
 
-- **One source of truth** -- edit `.agentsmesh/`, generate everywhere. No more copy-pasting rules between tool directories.
-- **Bidirectional sync** -- import existing configs into canonical form and generate back out. No data loss, no manual reformatting.
-- **Team-safe collaboration** -- lock files track generated state, `check` catches drift in CI, `merge` resolves conflicts after `git merge`.
-- **Lossless feature projection** -- when a tool lacks native support for a feature, AgentsMesh projects it as an embedded skill with enough metadata to round-trip on re-import.
+- **One source of truth** — edit `.agentsmesh/`, generate everywhere. No more copy-pasting rules between tool directories.
+- **Bidirectional sync** — import existing configs into canonical form and generate back out. Lossless round-trip, no manual reformatting.
+- **Project + Global modes** — sync team config via project-local `.agentsmesh/` *and* personal config via user-level `~/.agentsmesh/`.
+- **Plugin system** — add support for any AI coding tool via an npm package. No fork, no core PR.
+- **Team-safe collaboration** — lock files track generated state, `check` catches drift in CI, `merge` resolves conflicts after `git merge`.
+- **Community packs** — install shared skills, rules, agents, and commands from GitHub / GitLab / git URLs.
+- **Growing tool coverage** — new AI coding tools are added as the ecosystem evolves. See the [matrix](https://samplexbro.github.io/agentsmesh/reference/supported-tools/).
 
 ---
 
-## Installation
+## Install
 
-Requires **Node.js 20** or later.
+Requires **Node.js 20+**. Supported platforms: **Linux** and **macOS**. Native Windows support is deferred — track [the Windows support roadmap entry](docs/roadmap.md) for status. WSL2 works as a workaround.
 
 ```bash
-# npm
-npm install -D agentsmesh
-
-# pnpm
-pnpm add -D agentsmesh
-
-# yarn
-yarn add -D agentsmesh
-
-# or run directly
-npx agentsmesh --help
+npm install -D agentsmesh       # or: pnpm add -D / yarn add -D
+npx agentsmesh --help           # run without installing
 ```
 
-The CLI is available as both `agentsmesh` and `amsh`.
+CLI aliases: `agentsmesh` and `amsh`.
 
 ---
 
-## Quick Start
+## Quick start
 
 ### New project
 
 ```bash
-# Scaffold the canonical config directory
-agentsmesh init
+agentsmesh init                 # scaffold .agentsmesh/
+# edit .agentsmesh/rules/_root.md
+agentsmesh generate             # produce configs for every enabled tool
+```
 
-# Edit your root rule
-# vi .agentsmesh/rules/_root.md
+### Existing project — adopt with one import
 
-# Generate configs for all enabled targets
+```bash
+agentsmesh import --from cursor       # or claude-code, copilot, codex-cli, ...
 agentsmesh generate
 ```
 
-### Existing project with tool configs already in place
+### Personal global config
 
 ```bash
-# Import your existing Cursor config (or any supported tool)
-agentsmesh import --from cursor
+agentsmesh init --global
+agentsmesh import --global --from claude-code
+agentsmesh generate --global          # writes to ~/.claude/, ~/.cursor/, etc.
+```
 
-# Generate output for all configured targets
-agentsmesh generate
+---
+
+## Features
+
+### One config, every AI coding tool
+
+AgentsMesh generates native configuration for every major AI coding assistant. Each tool's files are produced from a single `.agentsmesh/` directory with support for **rules, commands, agents, skills, MCP servers, hooks, ignore patterns, and permissions**:
+
+| Tool | Main files generated |
+|------|---------------------|
+| **Claude Code** | `CLAUDE.md`, `.claude/agents/`, `.claude/skills/`, `.claude/commands/`, `.claude/settings.json`, `.claude/hooks.json`, MCP via `.claude.json` |
+| **Cursor** | `.cursor/rules/*.mdc`, `AGENTS.md`, `.cursor/mcp.json`, `.cursor/hooks.json`, `.cursorignore` |
+| **GitHub Copilot** | `.github/copilot-instructions.md`, `.github/instructions/*.instructions.md`, `.github/agents/`, `.github/prompts/` |
+| **Gemini CLI** | `GEMINI.md`, `.gemini/settings.json` (MCP + hooks), `.gemini/commands/*.toml`, `.gemini/agents/` |
+| **Windsurf** | `.windsurf/rules/*.md`, `.windsurf/workflows/`, `.windsurf/mcp_config.json`, `.windsurf/hooks.json` |
+| **Continue** | `.continue/rules/`, `.continue/prompts/`, `.continue/mcpServers/`, `.continue/config.yaml` |
+| **Cline** | `.clinerules/`, `.cline/skills/`, `.cline/cline_mcp_settings.json`, hooks |
+| **Kiro** | `.kiro/steering/`, `.kiro/skills/`, `.kiro/hooks/*.kiro.hook`, `.kiro/settings/mcp.json` |
+| **Codex CLI** | `AGENTS.md`, `.codex/config.toml`, `.codex/agents/*.toml`, `.codex/rules/` |
+| **Junie** | `AGENTS.md`, `.junie/agents/`, `.junie/commands/`, `.junie/skills/`, `.junie/mcp/mcp.json` |
+| **Roo Code** | `.roo/rules/`, `.roomodes` (agents → custom modes), `.roo/commands/`, `.roo/skills/` |
+| **Antigravity** | `.agents/rules/general.md`, `.agents/skills/`, `.agents/workflows/`, `.agents/mcp_config.json` |
+
+When a tool lacks native support for a feature, AgentsMesh embeds it with round-trip metadata — no data loss on re-import. See the [supported tools matrix](https://samplexbro.github.io/agentsmesh/reference/supported-tools/) for per-tool native vs. embedded breakdown.
+
+### Global mode — personal setup, same workflow
+
+`.agentsmesh/` at the project level is for teams. `~/.agentsmesh/` at the home level is for personal setup across every repo you touch:
+
+```bash
+agentsmesh init --global
+agentsmesh import --global --from claude-code
+agentsmesh generate --global   # writes ~/.claude/CLAUDE.md, ~/.cursor/, ~/.codex/, ~/.windsurf/, etc.
 ```
 
-That's it. Your `.agentsmesh/` directory is now the single source of truth, and the generated files for each tool stay in sync with it.
+Every built-in target and every plugin supports global mode. Every CLI command (`diff`, `lint`, `watch`, `check`, `merge`, `matrix`) accepts `--global`. [Global mode paths per tool →](https://samplexbro.github.io/agentsmesh/reference/supported-tools/#global-mode)
+
+### Plugins — add any AI tool
+
+Ship new target support as a standalone npm package — no fork, no core PR:
+
+```bash
+agentsmesh plugin add agentsmesh-target-my-tool
+agentsmesh generate            # plugin targets run alongside built-ins
+agentsmesh generate --global   # global mode works for plugins too
+```
+
+Plugins have full parity with built-in targets: project + global layouts, feature conversions, scoped settings, per-feature lint hooks, and hook post-processing. [Build a plugin →](https://samplexbro.github.io/agentsmesh/guides/building-plugins/)
+
+### Team-safe collaboration & CI drift detection
+
+- **`agentsmesh check`** — CI gate that exits 1 if generated files drifted from the lock
+- **`agentsmesh diff`** — preview what the next `generate` would change
+- **`agentsmesh merge`** — recover from three-way `.lock` conflicts after `git merge`
+- **Collaboration config** — `lock_features` and `strategy` prevent accidental overrides
+
+### Community packs
+
+Install shared skills, rules, agents, and commands from any git repo:
+
+```bash
+agentsmesh install github:org/shared-config@v1.0.0
+agentsmesh install --path rules --as rules github:team/standards
+agentsmesh install --sync       # restore all packs after clone
+```
+
+Packs live in `.agentsmesh/packs/`, track in `installs.yaml`, and merge into canonical config on every `generate`.
+
+### Extending AgentsMesh
+
+- **`agentsmesh target scaffold foo-ide`** — generate a built-in target skeleton (10 files, ready to contribute upstream) with global mode, conversion support, and lint hooks pre-wired
+- **`agentsmesh plugin add <pkg>`** — load third-party npm packages as runtime targets with full built-in parity
+
+[Extending guide →](https://samplexbro.github.io/agentsmesh/guides/extending/) · [Building plugins →](https://samplexbro.github.io/agentsmesh/guides/building-plugins/)
+
+---
+
+## Supported tools — feature matrix
+
+### Project scope (`agentsmesh generate`)
+
+<!-- agentsmesh:support-matrix:project -->
+| Feature | Claude Code | Cursor | Copilot | Continue | Junie | Kiro | Gemini CLI | Cline | Codex CLI | Windsurf | Antigravity | Roo Code |
+|---|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|
+| Rules | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native |
+| Additional Rules | Native | Embedded | Native | Native | Native | Native | Embedded | Native | Native | Native | Native | Native |
+| Commands | Native | Native | Native | Embedded | Native | — | Native | Native (workflows) | Embedded | Native (workflows) | Partial (workflows) | Native |
+| Agents | Native | Native | Native | — | Native | Native | Native | Embedded | Native | Embedded | — | Partial |
+| Skills | Native | Native | Native | Embedded | Native | Native | Native | Native | Native | Native | Native | Native |
+| MCP Servers | Native | Native | — | Native | Native | Native | Native | Native | Native | Partial | — | Native |
+| Hooks | Native | Native | Partial | — | — | Native | Partial | Native | — | Native | — | — |
+| Ignore | Native | Native | — | — | Native | Native | Native (settings-embedded) | Native | — | Native | — | Native |
+| Permissions | Native | Partial | — | — | — | — | Partial | — | — | — | — | — |
+<!-- /agentsmesh:support-matrix:project -->
+
+### Global scope (`agentsmesh generate --global`)
+
+<!-- agentsmesh:support-matrix:global -->
+| Feature | Claude Code | Cursor | Copilot | Continue | Junie | Kiro | Gemini CLI | Cline | Codex CLI | Windsurf | Antigravity | Roo Code |
+|---|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|
+| Rules | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native |
+| Additional Rules | Native | Embedded | Native | Native | Embedded | Native | Embedded | Native | Embedded | Partial | Embedded | Native |
+| Commands | Native | Native | Native | Native | Native | — | Native | Native (workflows) | Embedded | Native (workflows) | Partial (workflows) | Native |
+| Agents | Native | Native | Native | — | Native | Native | Native | Embedded | Native | Embedded | — | Partial |
+| Skills | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native |
+| MCP Servers | Native | Native | — | Native | Native | Native | Native | Native | Native | Partial | Native | Native |
+| Hooks | Native | Native | — | — | — | — | Partial | Native | — | Native | — | — |
+| Ignore | Native | Native | — | — | — | Native | — | Native | — | Native | — | Native |
+| Permissions | Native | — | — | — | — | — | — | — | — | — | — | — |
+<!-- /agentsmesh:support-matrix:global -->
+
+See the [full feature matrix docs](https://samplexbro.github.io/agentsmesh/reference/supported-tools/) for native vs. embedded support details and per-tool global paths.
 
 ---
 
-## Supported Tools
+## Programmatic API
+
+AgentsMesh is also importable as a typed ESM library, so you can drive every CLI capability — `generate`, `import`, `lint`, `diff`, `check` — from scripts, IDE extensions, MCP servers, or CI without spawning the CLI. Public entrypoints: `agentsmesh` (full surface), `agentsmesh/engine`, `agentsmesh/canonical`, `agentsmesh/targets`.
+
+```ts
+import {
+  loadConfig,
+  loadCanonical,
+  generate,
+  lint,
+  diff,
+  check,
+  importFrom,
+  registerTargetDescriptor,
+  type GenerateResult,
+  type LintResult,
+  type LockSyncReport,
+  type TargetDescriptor,
+} from 'agentsmesh';
+
+// Canonical 4-line generate pattern: load config → load canonical → call engine.
+const { config } = await loadConfig(process.cwd());
+const canonical = await loadCanonical(process.cwd());
+const results: GenerateResult[] = await generate({
+  config,
+  canonical,
+  projectRoot: process.cwd(),
+  scope: 'project',
+});
+
+// Lint — pure, returns structured diagnostics + hasErrors.
+const lintResult: LintResult = await lint({ config, canonical, projectRoot: process.cwd() });
+
+// Diff — runs generate internally, returns unified diffs + summary.
+const { diffs, summary } = await diff({ config, canonical, projectRoot: process.cwd() });
+
+// Check — lock-file vs current canonical drift report.
+const drift: LockSyncReport = await check({
+  config,
+  configDir: process.cwd(),
+  canonicalDir: `${process.cwd()}/.agentsmesh`,
+});
+
+// Import a tool's native config back into canonical form (writes to disk).
+await importFrom('claude-code', { root: process.cwd() });
+
+// Register a custom target descriptor at runtime (same shape plugins ship).
+const myDescriptor: TargetDescriptor = /* ... */;
+registerTargetDescriptor(myDescriptor);
+```
 
-| Feature       | Claude Code | Cursor  | Copilot | Continue | Junie    | Kiro   | Gemini CLI | Cline   | Codex CLI | Windsurf | Antigravity | Roo Code |
-|---------------|:-----------:|:-------:|:-------:|:--------:|:--------:|:------:|:----------:|:-------:|:---------:|:--------:|:-----------:|:--------:|
-| Rules         | Native      | Native  | Native  | Native   | Native   | Native | Native     | Native  | Native    | Native   | Native      | Native   |
-| Commands      | Native      | Native  | Native  | Embedded | Embedded | --     | Native     | Native  | Embedded  | Native   | Partial     | Native   |
-| Agents        | Native      | Native  | Native  | --       | Embedded | --     | Native     | Embedded| Native    | Embedded | --          | --       |
-| Skills        | Native      | Native  | Native  | Embedded | Embedded | Native | Native     | Native  | Native    | Native   | Native      | Native   |
-| MCP Servers   | Native      | Native  | --      | Native   | Native   | Native | Native     | Native  | Native    | Partial  | --          | Native   |
-| Hooks         | Native      | Native  | Partial | --       | --       | Native | Partial    | --      | --        | Native   | --          | --       |
-| Ignore        | Native      | Native  | --      | --       | Native   | Native | Native     | Native  | --        | Native   | --          | Native   |
-| Permissions   | Native      | Partial | --      | --       | --       | --     | Partial    | --      | --        | --       | --          | --       |
+Subpath imports are available when you want narrower bundles:
 
-See the [full feature matrix docs](https://samplexbro.github.io/agentsmesh/reference/supported-tools/) for details on native vs. embedded support.
+```ts
+import { generate, lint, diff, check, loadConfig } from 'agentsmesh/engine';
+import { loadCanonical } from 'agentsmesh/canonical';
+import { getAllDescriptors } from 'agentsmesh/targets';
+```
 
-**Note:** The canonical root rule always lives at `.agentsmesh/rules/_root.md`. Some targets write that content to a tool-specific main file named `general` (for example `.continue/rules/general.md` and `.agents/rules/general.md` for Antigravity) instead of `_root.md` on disk.
+Every public symbol resolves to a real `.d.ts` under strict TypeScript. Full reference at [agentsmesh.dev/reference/programmatic-api](https://samplexbro.github.io/agentsmesh/reference/programmatic-api/) — entrypoint table, every function signature, the typed error taxonomy, and the canonical/target type lists. ESM-only; requires Node.js 20+.
 
 ---
 
 ## Documentation
 
-The documentation site covers everything in detail:
+- **[Getting Started](https://samplexbro.github.io/agentsmesh/getting-started/installation/)** — installation, quick start
+- **[Canonical Config](https://samplexbro.github.io/agentsmesh/canonical-config/)** — rules, commands, agents, skills, MCP, hooks, ignore, permissions
+- **[CLI Reference](https://samplexbro.github.io/agentsmesh/cli/)** — `init`, `generate`, `import`, `install`, `diff`, `lint`, `watch`, `check`, `merge`, `matrix`, `plugin`, `target`
+- **[Configuration](https://samplexbro.github.io/agentsmesh/configuration/agentsmesh-yaml/)** — `agentsmesh.yaml`, local overrides, extends, collaboration, conversions
+- **[Guides](https://samplexbro.github.io/agentsmesh/guides/existing-project/)** — adopting in existing projects · multi-tool teams · sharing config · CI drift detection · community packs · **building plugins**
+- **[Reference](https://samplexbro.github.io/agentsmesh/reference/generation-pipeline/)** — supported tools matrix · generation pipeline · managed embedding
 
-- **[Getting Started](https://samplexbro.github.io/agentsmesh/getting-started/installation/)** -- installation, quick start
-- **[Canonical Config](https://samplexbro.github.io/agentsmesh/canonical-config/)** -- rules, commands, agents, skills, MCP, hooks, ignore, permissions
-- **[CLI Reference](https://samplexbro.github.io/agentsmesh/cli/)** -- all commands: init, generate, import, install, diff, lint, watch, check, merge, matrix
-- **[Configuration](https://samplexbro.github.io/agentsmesh/configuration/agentsmesh-yaml/)** -- agentsmesh.yaml, local overrides, extends, collaboration, conversions
-- **[Guides](https://samplexbro.github.io/agentsmesh/guides/existing-project/)** -- adopting in existing projects, multi-tool teams, sharing config, CI drift detection, community packs
-- **[Reference](https://samplexbro.github.io/agentsmesh/reference/generation-pipeline/)** -- how the generation pipeline works
+---
 
 ## Contributing
 
-Contributions are welcome. Keep changes small, test them, and prefer editing canonical `.agentsmesh/` sources over generated files.
+Contributions welcome. Keep changes small, test them, and prefer editing canonical `.agentsmesh/` sources over generated files.
 
 ```bash
 pnpm install

package/dist/canonical-types-CZwrJoBX.d.ts

@@ -0,0 +1,146 @@
+/** Hook definition */
+interface HookEntry {
+    matcher: string;
+    command: string;
+    timeout?: number;
+    type?: 'command' | 'prompt';
+    prompt?: string;
+}
+interface Hooks {
+    PreToolUse?: HookEntry[];
+    PostToolUse?: HookEntry[];
+    Notification?: HookEntry[];
+    UserPromptSubmit?: HookEntry[];
+    SubagentStart?: HookEntry[];
+    SubagentStop?: HookEntry[];
+    [key: string]: HookEntry[] | undefined;
+}
+
+interface BaseMcpServer {
+    description?: string;
+    type: string;
+    env: Record<string, string>;
+}
+/** Stdio MCP server configuration */
+interface StdioMcpServer extends BaseMcpServer {
+    command: string;
+    args: string[];
+}
+/** URL-based MCP server configuration (HTTP/SSE/streamable HTTP) */
+interface UrlMcpServer extends BaseMcpServer {
+    url: string;
+    headers: Record<string, string>;
+}
+/** MCP server configuration */
+type McpServer = StdioMcpServer | UrlMcpServer;
+interface McpConfig {
+    mcpServers: Record<string, McpServer>;
+}
+
+/** A parsed rule from .agentsmesh/rules/ (glob: *.md) */
+interface CanonicalRule {
+    /** Source file path (for error reporting) */
+    source: string;
+    /** If true, this is the root/always-applied rule */
+    root: boolean;
+    /** Which targets receive this rule. Empty = all */
+    targets: string[];
+    /** Human description for AI context */
+    description: string;
+    /** Glob patterns for file scoping */
+    globs: string[];
+    /** Markdown body content */
+    body: string;
+    /** Activation mode hint for tools that support it (e.g. Windsurf) */
+    trigger?: 'always_on' | 'model_decision' | 'glob' | 'manual';
+    /**
+     * Codex CLI: `advisory` (default) → nested `AGENTS.md` / `AGENTS.override.md`.
+     * `execution` → `.codex/rules/{slug}.rules` body must be Starlark (`prefix_rule`, …).
+     * @see docs/agent-structures/codex-cli-project-level-advanced.md §6.2, §6.10
+     */
+    codexEmit?: 'advisory' | 'execution';
+    /**
+     * Codex nested instruction filename: `override` → `AGENTS.override.md` (advisory only).
+     */
+    codexInstructionVariant?: 'default' | 'override';
+}
+/** A parsed command from .agentsmesh/commands/ (glob: *.md) */
+interface CanonicalCommand {
+    source: string;
+    /** Command name (derived from filename) */
+    name: string;
+    description: string;
+    /** Tool permissions: ["Read", "Grep", "Bash(git diff)"] */
+    allowedTools: string[];
+    /** When true, also emit ~/.claude/output-styles/{name}.md in Claude global mode */
+    outputStyle?: boolean;
+    body: string;
+}
+/** A parsed subagent from .agentsmesh/agents/ (glob: *.md) */
+interface CanonicalAgent {
+    source: string;
+    name: string;
+    description: string;
+    /** Tools this agent can use */
+    tools: string[];
+    /** Tools explicitly denied */
+    disallowedTools: string[];
+    /** AI model preference */
+    model: string;
+    /** Permission mode */
+    permissionMode: string;
+    /** Max conversation turns */
+    maxTurns: number;
+    /** MCP servers available to this agent */
+    mcpServers: string[];
+    /** Hooks specific to this agent */
+    hooks: Hooks;
+    /** Skills available to this agent */
+    skills: string[];
+    /** Memory file path */
+    memory: string;
+    /** System prompt (markdown body) */
+    body: string;
+    /** When true, also emit ~/.claude/output-styles/{name}.md in Claude global mode */
+    outputStyle?: boolean;
+}
+/** Supporting file for a skill */
+interface SkillSupportingFile {
+    relativePath: string;
+    absolutePath: string;
+    /** File content (utf-8) for generation; empty if unreadable */
+    content: string;
+}
+/** A parsed skill from .agentsmesh/skills/{name}/SKILL.md */
+interface CanonicalSkill {
+    source: string;
+    /** Skill name (derived from directory name) */
+    name: string;
+    description: string;
+    /** SKILL.md content */
+    body: string;
+    /** Paths to supporting files (relative to skill dir) */
+    supportingFiles: SkillSupportingFile[];
+}
+/** Permission allow/deny/ask lists */
+interface Permissions {
+    allow: string[];
+    deny: string[];
+    /** Present in parsed YAML; omitted in some legacy fixtures */
+    ask?: string[];
+}
+/** Ignore patterns (gitignore syntax lines) */
+type IgnorePatterns = string[];
+/** All canonical files loaded from .agentsmesh/ */
+interface CanonicalFiles {
+    rules: CanonicalRule[];
+    commands: CanonicalCommand[];
+    agents: CanonicalAgent[];
+    skills: CanonicalSkill[];
+    mcp: McpConfig | null;
+    permissions: Permissions | null;
+    hooks: Hooks | null;
+    ignore: IgnorePatterns;
+}
+
+export type { CanonicalAgent as C, HookEntry as H, IgnorePatterns as I, McpConfig as M, Permissions as P, SkillSupportingFile as S, UrlMcpServer as U, CanonicalCommand as a, CanonicalFiles as b, CanonicalRule as c, CanonicalSkill as d, Hooks as e, McpServer as f, StdioMcpServer as g };

package/dist/canonical.d.ts

@@ -0,0 +1,24 @@
+import { b as CanonicalFiles } from './canonical-types-CZwrJoBX.js';
+export { C as CanonicalAgent, a as CanonicalCommand, c as CanonicalRule, d as CanonicalSkill, H as HookEntry, e as Hooks, I as IgnorePatterns, M as McpConfig, f as McpServer, P as Permissions, S as SkillSupportingFile, g as StdioMcpServer, U as UrlMcpServer } from './canonical-types-CZwrJoBX.js';
+
+/**
+ * Load all canonical files from a canonical directory into CanonicalFiles.
+ */
+
+/**
+ * Load all canonical files from a canonical directory or project root.
+ * Missing directories/files yield empty arrays or null as per each parser.
+ *
+ * @param canonicalDirOrProjectRoot - Absolute path to canonical directory or project root
+ * @returns CanonicalFiles with all parsed data
+ */
+declare function loadCanonicalFiles(canonicalDirOrProjectRoot: string): Promise<CanonicalFiles>;
+
+/**
+ * Public API — canonical loading (package.json "exports"."./canonical").
+ */
+
+/** Load `.agentsmesh/` from a project root (or an explicit canonical directory). */
+declare function loadCanonical(projectRoot: string): Promise<CanonicalFiles>;
+
+export { CanonicalFiles, loadCanonical, loadCanonicalFiles };