agentsmesh 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,16 +1,97 @@
 # Changelog
 
-## 0.5.0
+## 0.7.0
 
 ### Minor Changes
 
-- ec5e3a6: **Breaking (descriptor authors):** Built-in targets now declare global mode under `globalSupport` (capabilities, detection paths, layout, optional `scopeExtras`) instead of separate `global`, `globalCapabilities`, and `globalDetectionPaths` fields. Command/workflow and Gemini settings generation are modeled with capability **flavors** on the canonical generators; Copilot/Cursor root mirrors use `layout.outputFamilies` for rewrite cache keys.
+- 5179de0: Native Windows support is now first-class. `windows-latest` × Node 22 joins `ubuntu-latest` × Node 20/22/24 and `macos-latest` × Node 22 in the CI quality matrix, the `os: ["darwin", "linux"]` restriction is removed from `package.json`, and the README/website call out Linux, macOS, and Windows as equally supported platforms.
 
-  **CLI / docs:** `pnpm matrix:generate` refreshes README and website support-matrix blocks from the catalog; `pnpm matrix:verify` fails on drift (also runs in CI). Init detection uses `collectDetectionPaths` from the catalog.
+  The install/pack persistence layer is now separator-agnostic: `installs.yaml` `source`/`path`/`paths` and `pack.yaml` local-source fields are always serialized as POSIX through the new `src/install/core/portable-paths.ts` helper, regardless of the host separator. `agentsmesh install <local-path>` parses Windows paths (including cross-drive sources and `.agentsmesh/` segments split by backslashes) into portable manifest entries, and legacy manifests written on Windows are normalized on read so existing repos converge without migration. `agentsmesh import --from windsurf` and `--from codex-cli` now detect nested `AGENTS.md` / `AGENTS.override.md` via `basename(srcPath)`; the previous `srcPath.endsWith('/AGENTS.md')` check silently skipped nested rules on Windows because `readDirRecursive` returns native separators. `scripts/flake-check.ts` resolves `pnpm.cmd` on `win32`, and `tests/helpers/node-bin.ts` is the single source for `node_modules/.bin/<name>` shim resolution across platforms.
 
-- ec5e3a6: Add public library entry points (`./engine`, `./canonical`, `./targets`) for programmatic use, introduce the parametrized target contract matrix under `tests/contract/`, and document coverage exclusions in `tasks/coverage-gaps.md`.
+  A new Windows path-safety contract (`src/utils/filesystem/windows-path-safety.ts` plus `tests/contract/windows-path-safety.matrix.test.ts`) asserts that every generated artifact path emitted by every builtin target — in both project and global scope — survives a Windows clone/checkout/write cycle. Reserved device names (case-insensitive `CON`/`PRN`/`AUX`/`NUL`/`COM1-9`/`LPT1-9`), reserved characters (`<>:"|?*` plus ASCII control chars), trailing dots/spaces, and case-only collisions on default NTFS / APFS volumes are now regression-locked across 48 contract assertions.
 
-## 0.4.1 - 2026-04-23
+  `agentsmesh lint` warns when `hooks.yaml` is non-empty for `cline` or `copilot`, because both targets emit `.sh` wrapper scripts (`.clinerules/hooks/*.sh`, `.github/hooks/scripts/*.sh`) with `#!/usr/bin/env bash` headers that need a POSIX shell (git-bash or WSL) to execute on Windows. Other targets (claude-code, cursor, windsurf, kiro, gemini-cli) embed the user's `command` string directly into JSON config and stay fully portable. The Windows portability story for hooks is documented in `website/src/content/docs/canonical-config/hooks.mdx`.
+
+  Also fixed: `tests/integration/lint.integration.test.ts` stops hardcoding `shell: '/bin/sh'` plus `2>&1` for stderr capture (which ENOENTed on Windows runners) — it now spawns `process.execPath` via `spawnSync` and concatenates the captured streams.
+
+  Fixed a long-latent race in `acquireProcessLock` (`src/utils/filesystem/process-lock.ts`) that surfaced the test failure `ENOENT: rename .agentsmesh/.lock.tmp -> .agentsmesh/.lock` under parallel `agentsmesh generate` invocations. Between `mkdir(lockPath)` succeeding and `writeFile(holder.json)` completing, a competing acquirer would treat the metadata-less lock dir as orphaned, evict it, and silently steal the mutex — letting both processes into the critical section and racing their `writeFileAtomic` writes. The lock now treats lock dirs younger than a 2-second grace window as held even when `holder.json` is missing, and only evicts genuinely orphaned older directories. Covered by `tests/integration/generate-process-lock.integration.test.ts` plus a new unit test in `tests/unit/utils/process-lock.test.ts`.
+
+  Fixed a generator-side Windows path bug surfaced by the Windows CI matrix: rule slug extraction in `src/targets/{claude-code,codex-cli,copilot,cursor,continue,catalog}/...` used `rule.source.split('/').pop()!.replace(/\.md$/, '')`, which on Windows where `rule.source` uses `\` separators returned the _entire absolute path_ and produced `.cursor\rules\C:\Users\...\.agentsmesh\rules` ENOENT crashes during `writeFileAtomic`. All 10 occurrences across 8 files now use `basename(rule.source, '.md')` from `node:path`, which is platform-aware. Watch mode in `src/cli/commands/watch.ts` now sets `usePolling: process.platform === 'win32'` because Windows native `ReadDirectoryChangesW` misses events for files newly created in just-watched subdirectories under the GitHub Actions `AppData\Local\Temp` short-name path.
+
+  Fixed a second Windows path bug in the reference rewriter: `buildArtifactPathMap`, `addPackSkillArtifactMappings`, `applyCopilotInstructionArtifactRefs`, `collectPlannedPaths`, and the validator in `src/core/reference/validate-generated-markdown-links.ts` were using native `node:path.join`/`normalize` directly. The rebaser itself uses `pathApi(projectRoot)` which picks `win32` or `posix` based on the _path format_, not the host platform. Synthetic POSIX project roots (used in unit tests) and real Windows project roots could produce mismatched keys vs. lookups, so the rewriter silently no-op'd. All five sites now share one `pathApi(projectRoot)` so map keys and lookups always agree.
+
+## 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.
+  - `loadProjectContext(projectRoot, options?)` — loads the same execution context the CLI uses: scoped config, plugin descriptors, `extends`, packs, and local canonical content. The returned object is directly usable with `generate`, `lint`, and `diff`.
+  - `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` (26 strict assertions) exercises every public function and every error class against real fixture state: shape inventory, `loadConfig` happy/missing/invalid-schema paths, `loadCanonical`, `loadProjectContext` CLI-parity loading, `generate` with exact-paths assertion, `targetFilter` narrowing, `registerTargetDescriptor` plugin wiring through `generate`, plugin `importFrom` end-to-end, `lint` shape, `diff` + `computeDiff` summary parity, `check` for `hasLock=false` / `inSync=true` / modified-drift, immutable 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 (`loadProjectContext`, `loadConfig`, `loadConfigFromDirectory`, `loadCanonical`, `loadCanonicalFiles`, `lint`, `diff`, `check`, `computeDiff`, `formatDiffSummary`, `ProjectContext`, `LoadProjectContextOptions`, `LoadCanonicalOptions`, `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 recommended `loadProjectContext` generate pattern, per-function signatures and examples for `loadProjectContext` / `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 and matches CLI setup for plugins, `extends`, and packs.
+
+### 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
+
+- **Programmatic API parity gaps** — `loadCanonical()` now mirrors CLI canonical loading by merging `extends` and packs when config is available (`loadCanonicalFiles()` remains the local-only helper); public `importFrom()` now resolves registered plugin descriptors as well as built-ins; plugin `buildImportPaths()` hooks now participate in shared import reference normalization; `getTargetCatalog()` returns immutable catalog snapshots instead of the live built-in array; descriptor registration now rejects non-`none` capabilities that do not have a generator or settings sidecar emitter.
+- **`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
 

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,107 +26,132 @@ 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**, **macOS**, and **Windows**.
 
 ```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
-
-# Generate output for all configured targets
-agentsmesh generate
+agentsmesh init --global
+agentsmesh import --global --from claude-code
+agentsmesh generate --global          # writes to ~/.claude/, ~/.cursor/, etc.
 ```
 
-### Personal global config (user home)
+---
+
+## 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
-# Initialize canonical home config
 agentsmesh init --global
-
-# Import a user-level tool setup into ~/.agentsmesh/
 agentsmesh import --global --from claude-code
-agentsmesh import --global --from antigravity
-agentsmesh import --global --from codex-cli
-agentsmesh import --global --from cursor
-
-# Install shared packs into ~/.agentsmesh/
-agentsmesh install --global github:org/shared-rules
-
-# Work against home-level canonical config
-agentsmesh diff --global
-agentsmesh lint --global
-agentsmesh watch --global
-agentsmesh check --global
-agentsmesh merge --global
-agentsmesh matrix --global
-agentsmesh generate --global
+agentsmesh generate --global   # writes ~/.claude/CLAUDE.md, ~/.cursor/, ~/.codex/, ~/.windsurf/, etc.
 ```
 
-Global mode uses `~/.agentsmesh/` as the canonical source of truth instead of a project-local `.agentsmesh/`. **All** built-in targets support `--global`; `agentsmesh generate --global` writes user-level outputs for whichever targets are enabled in `agentsmesh.yaml`. Typical paths include:
+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)
 
-- **Claude Code** — `~/.claude/CLAUDE.md` (with `# Global Instructions` framing), `~/.claude/settings.json` (permissions), `~/.claude/hooks.json` (hooks), `~/.claude/agents/`, `~/.claude/skills/`, optional mirror to `~/.agents/skills/` when Codex is **not** also a global target (otherwise Codex owns `~/.agents/skills/`), `~/.claude/commands/`, optional `~/.claude/output-styles/` when `outputStyle: true` on an agent or command, `~/.claudeignore`, and `~/.claude.json` for MCP
-- **Cursor** — `~/.cursor/rules/*.mdc`, `~/.cursor/AGENTS.md` (aggregate), `~/.cursor/mcp.json`, `~/.cursor/hooks.json`, `~/.cursorignore`, plus skills, agents, and commands under `~/.cursor/`; legacy `~/.agentsmesh-exports/cursor/user-rules.md` is still read on import when present; `agentsmesh import --global --from cursor` maps those paths back into `~/.agentsmesh/`
-- **Copilot** — `~/.copilot/copilot-instructions.md` (all rules merged, including glob-scoped instructions), `~/.copilot/AGENTS.md` (compat mirror), `~/.copilot/agents/*.agent.md`, `~/.copilot/skills/`, `~/.copilot/prompts/*.prompt.md`, skills mirrored to `~/.agents/skills/` and `~/.claude/skills/` when Codex is **not** also a global target
-- **Continue** — `~/.continue/rules/`, `~/.continue/prompts/`, `~/.continue/skills/`, `~/.continue/mcpServers/agentsmesh.json`, `~/.continue/AGENTS.md` (compat mirror), `~/.continue/config.yaml` (global config)
-- **Junie** — `~/.junie/AGENTS.md` (aggregate), `~/.junie/skills/`, `~/.junie/agents/*.md`, `~/.junie/commands/*.md`, `~/.junie/mcp/mcp.json`, optional mirror to `~/.agents/skills/` when Codex is **not** also a global target
-- **Kiro** — `~/.kiro/steering/AGENTS.md` (aggregate), `~/.kiro/steering/*.md` (per-rule files), `~/.kiro/agents/*.md`, `~/.kiro/skills/`, `~/.kiro/settings/mcp.json`, `~/.kiro/settings/kiroignore`, optional mirror to `~/.agents/skills/` when Codex is **not** also a global target
-- **Gemini CLI** — `~/.gemini/GEMINI.md`, `~/.gemini/AGENTS.md` (compatibility aggregate), `~/.gemini/settings.json` (includes MCP and hooks), `~/.gemini/commands/*.toml`, `~/.gemini/skills/`, `~/.gemini/agents/*.md` (experimental), optional mirror to `~/.agents/skills/` when Codex is **not** also a global target
-- **Cline** — `~/Documents/Cline/Rules/`, `~/Documents/Cline/Workflows/`, `~/Documents/Cline/Hooks/`, `~/.cline/skills/`, `~/.cline/cline_mcp_settings.json`, `~/.clineignore`, optional mirror to `~/.agents/skills/`
-- **Codex CLI** — `~/.codex/AGENTS.md`, `~/.codex/config.toml`, `~/.codex/agents/*.toml`, `~/.codex/rules/*.rules` when rules use execution semantics, and `~/.agents/skills/` for skills
-- **Windsurf** — `~/.codeium/windsurf/memories/global_rules.md`, `~/.codeium/windsurf/skills/`, `~/.codeium/windsurf/global_workflows/`, `~/.codeium/windsurf/hooks.json`, `~/.codeium/windsurf/mcp_config.json`, `~/.codeium/.codeiumignore`, optional mirror to `~/.agents/skills/` when Codex is **not** also a global target
-- **Antigravity** — `~/.gemini/antigravity/GEMINI.md`, `~/.gemini/antigravity/skills/`, `~/.gemini/antigravity/workflows/`, and `~/.gemini/antigravity/mcp_config.json`
-- **Roo Code** — `~/.roo/AGENTS.md` (compatibility aggregate), `~/.roo/rules/*.md`, `~/.roo/commands/*.md`, `~/.roo/skills/`, `~/mcp_settings.json`, `~/.rooignore`, `~/.roo/settings/custom_modes.yaml` (agents → custom modes), optional mirror to `~/.agents/skills/` when Codex is **not** also a global target
+### Plugins — add any AI tool
 
-See the [supported tools matrix](https://samplexbro.github.io/agentsmesh/reference/supported-tools/#global-mode) for project vs global capability notes per target.
+Ship new target support as a standalone npm package — no fork, no core PR:
 
-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.
+```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
+## Supported tools — feature matrix
 
 ### Project scope (`agentsmesh generate`)
 
@@ -141,7 +169,7 @@ That's it. Your `.agentsmesh/` directory is now the single source of truth, and
 | Permissions | Native | Partial | — | — | — | — | Partial | — | — | — | — | — |
 <!-- /agentsmesh:support-matrix:project -->
 
-### Global scope (`agentsmesh matrix --global`)
+### 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 |
@@ -157,26 +185,80 @@ That's it. Your `.agentsmesh/` directory is now the single source of truth, and
 | Permissions | Native | — | — | — | — | — | — | — | — | — | — | — |
 <!-- /agentsmesh:support-matrix:global -->
 
-See the [full feature matrix docs](https://samplexbro.github.io/agentsmesh/reference/supported-tools/) for details on native vs. embedded support and global paths.
+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.
+
+---
+
+## 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 {
+  loadProjectContext,
+  generate,
+  lint,
+  diff,
+  check,
+  importFrom,
+  registerTargetDescriptor,
+  type GenerateResult,
+  type LintResult,
+  type LockSyncReport,
+  type TargetDescriptor,
+} from 'agentsmesh';
+
+// CLI-parity generate pattern: config, plugins, extends, packs, then generation.
+const project = await loadProjectContext(process.cwd());
+const results: GenerateResult[] = await generate(project);
+
+// Lint — pure, returns structured diagnostics + hasErrors.
+const lintResult: LintResult = await lint(project);
+
+// Diff — runs generate internally, returns unified diffs + summary.
+const { diffs, summary } = await diff(project);
+
+// Check — lock-file vs current canonical drift report.
+const drift: LockSyncReport = await check({
+  config: project.config,
+  configDir: project.configDir,
+  canonicalDir: project.canonicalDir,
+});
+
+// Import a built-in or registered plugin target back into canonical form.
+await importFrom('claude-code', { root: process.cwd() });
+
+// Register a custom target descriptor at runtime (same shape plugins ship).
+const myDescriptor: TargetDescriptor = /* ... */;
+registerTargetDescriptor(myDescriptor);
+```
+
+Subpath imports are available when you want narrower bundles:
 
-**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.
+```ts
+import { generate, lint, diff, check, loadProjectContext } from 'agentsmesh/engine';
+import { loadCanonical, loadCanonicalFiles } from 'agentsmesh/canonical';
+import { getAllDescriptors } from 'agentsmesh/targets';
+```
+
+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.d.ts

@@ -1,4 +1,6 @@
-import { C as CanonicalFiles } from './canonical-types-gdrUi3bD.js';
+import { b as CanonicalFiles, V as ValidatedConfig } from './schema-B7ZSqkrS.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 './schema-B7ZSqkrS.js';
+import 'zod';
 
 /**
  * Load all canonical files from a canonical directory into CanonicalFiles.
@@ -17,7 +19,23 @@ declare function loadCanonicalFiles(canonicalDirOrProjectRoot: string): Promise<
  * 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>;
+interface LoadCanonicalOptions {
+    /** Preloaded config. Must be provided together with `configDir`. */
+    readonly config?: ValidatedConfig;
+    /** Directory containing `agentsmesh.yaml`. Must be provided together with `config`. */
+    readonly configDir?: string;
+    /** Override canonical directory; defaults to `<configDir>/.agentsmesh`. */
+    readonly canonicalDir?: string;
+    /** Defaults to true when config is available. Set false for local-only `.agentsmesh/`. */
+    readonly includeExtends?: boolean;
+    /** Refresh remote extend cache before loading. */
+    readonly refreshRemoteCache?: boolean;
+}
+/**
+ * Load canonical content for a project. When an `agentsmesh.yaml` can be found,
+ * this mirrors CLI generation by merging extends and installed packs before
+ * local `.agentsmesh/` content. Use `loadCanonicalFiles()` for local-only reads.
+ */
+declare function loadCanonical(projectRoot: string, options?: LoadCanonicalOptions): Promise<CanonicalFiles>;
 
-export { loadCanonical, loadCanonicalFiles };
+export { CanonicalFiles, type LoadCanonicalOptions, loadCanonical, loadCanonicalFiles };