agentsmesh 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # Changelog
 
+## 0.9.0
+
+### Minor Changes
+
+- b3f702d: Adds three new `agentsmesh lint` diagnostics, a recommended `.gitignore` policy for materialized packs, and a one-step `agentsmesh target-scaffold` workflow.
+
+  Added:
+  - New lint diagnostics, all emitted as warnings (do not change `lint`'s exit code):
+    - `silent-drop-guard` flags canonical content a target would otherwise drop without trace based on its capability map.
+    - `hook-script-references` warns when a hook command references a script path for any target whose generator does not copy hook scripts into its output. **All built-in targets except Copilot fall under this rule today.** Existing hook configs that reference local script paths (e.g. `./scripts/pre-commit.sh`) will surface a new warning per matching target on the first lint after upgrade. The script must already exist relative to the hook execution directory or the generated config will fail at runtime — the diagnostic just makes the gap visible.
+    - `rule-scope-inversion` catches manual-activation rules whose scope contradicts the target's projection rules.
+      All three are wired into `runLint` for every target via descriptor capabilities; no existing rule has been removed and no diagnostic is upgraded to error severity.
+  - `agentsmesh init` now writes `.agentsmesh/packs/` into `.gitignore` alongside `agentsmesh.local.yaml`, `.agentsmeshcache`, and `.agentsmesh/.lock.tmp`, and skips entries already covered by a broader pre-existing pattern (e.g. an existing `.agentsmesh/` line covers `.agentsmesh/packs/`). Materialized packs are treated like `node_modules` — `installs.yaml` is committed and `agentsmesh install --sync` reproduces the tree deterministically post-clone.
+  - `agentsmesh target-scaffold` post-steps collapse the previous three-edit sequence into one `pnpm catalog:generate` invocation, backed by a new auto-discovered builtin-target catalog (`scripts/generate-target-catalog.ts` + `pnpm catalog:verify` drift guard in CI).
+
+  Changed:
+  - The `agentsmesh.json` and `pack.json` schemas now list `targets` enums alphabetically. Schema consumers that pin order will see a one-time diff; values are unchanged.
+  - README documents the commit-vs-gitignore convention for generated tool folders and clarifies native Windows support (no WSL).
+
+  Internal:
+  - Per-target importers (`antigravity`, `claude-code`, `continue`, `copilot`, `cursor`, `gemini-cli`, `junie`, `kiro`, `roo-code`) migrated to the descriptor-driven import runner with mapper functions extracted into `import-mappers.ts` to keep `index.ts` ↔ `importer.ts` cycles out of the TDZ.
+  - New shared link-format registry (`src/core/reference/link-format-registry.ts`) consolidates per-target link rendering rules.
+  - `writeFileAtomic` now refuses to follow a pre-existing symlink at the target path (closes a TOCTOU window where a swapped symlink could redirect writes outside the project tree).
+  - `agentsmesh plugin add` now warns that plugins load as trusted Node.js modules with full process privileges.
+
+### Patch Changes
+
+- 08ef1b0: Security hardening and correctness fixes across install, generate, reference rewriting, plugin loading, and caching subsystems.
+
+  Fixed:
+  - `agentsmesh install --path` now rejects paths that traverse outside the install source root, closing a directory-escape vulnerability where `--path ../../outside` could read files outside the fetched source.
+  - Pack names are validated as single directory segments before materialization — values containing path separators (e.g. `../../escape`) are rejected, preventing writes outside `.agentsmesh/packs/`.
+  - `writeFileAtomic` now checks the `.tmp` staging path for symlinks before writing, closing a TOCTOU window where a symlink at `${path}.tmp` could redirect writes to an attacker-controlled location.
+  - `agentsmesh generate --targets` now validates filter values against configured targets and errors on unknown names. Previously a misspelled target silently produced zero outputs and `--check` reported success, allowing CI to pass while checking nothing.
+  - Project-scope skill mirrors now receive source-map entries for reference rewriting. Previously only global-scope mirrors were mapped, leaving Markdown links inside project-mirrored skill files unrewritten.
+  - Plugin targets declaring `sharedArtifacts` are now recognized during global reference rewriting. Previously only builtin target descriptors were consulted, so plugin-owned shared paths could be rebased through the wrong artifact map.
+  - `runDescriptorImport` is now exported from `agentsmesh/targets` as documented in the plugin guide.
+  - Importer fallback sources are now tried when configured primary files are absent on disk, not only when the primary source list is empty.
+  - `flatFile` and `mcpJson` import modes now honor `canonicalDir` when `canonicalFilename` is a bare filename, matching the documented directory-plus-filename contract for plugin descriptor authors.
+  - Rule path mapping uses POSIX `basename` with backslash normalization instead of host `node:path`, preventing broken slugs when Windows-shaped canonical paths appear on a POSIX host.
+  - Relative `file:` plugin sources now resolve against `projectRoot` instead of the filesystem root.
+  - Remote cache keys now preserve dots and use double-separator delimiters so distinct refs like `v1.0.0` and `v1_0_0` no longer collide. Existing cached entries will be re-fetched once after upgrade.
+
+## 0.8.0
+
+### Minor Changes
+
+- b3f702d: Adds three new `agentsmesh lint` diagnostics, a recommended `.gitignore` policy for materialized packs, and a one-step `agentsmesh target-scaffold` workflow.
+
+  Added:
+  - New lint diagnostics: `silent-drop-guard` flags canonical content a target would otherwise drop without trace, `hook-script-references` reports hook commands pointing at missing wrapper scripts, and `rule-scope-inversion` catches manual-activation rules whose scope contradicts the target's projection rules. They are wired into `runLint` for every target via descriptor capabilities, so existing configs may surface new warnings; no rule has been removed.
+  - `agentsmesh init` now writes `.agentsmesh/packs/` into `.gitignore` alongside `agentsmesh.local.yaml`, `.agentsmeshcache`, and `.agentsmesh/.lock.tmp`. Materialized packs are treated like `node_modules` — `installs.yaml` is committed and `agentsmesh install --sync` reproduces the tree deterministically post-clone.
+  - `agentsmesh target-scaffold` post-steps collapse the previous three-edit sequence into one `pnpm catalog:generate` invocation, backed by a new auto-discovered builtin-target catalog (`scripts/generate-target-catalog.ts` + `pnpm catalog:verify` drift guard in CI).
+
+  Changed:
+  - The `agentsmesh.json` and `pack.json` schemas now list `targets` enums alphabetically. Schema consumers that pin order will see a one-time diff; values are unchanged.
+  - README documents the commit-vs-gitignore convention for generated tool folders and clarifies native Windows support (no WSL).
+
+  Internal:
+  - Per-target importers (`antigravity`, `claude-code`, `continue`, `copilot`, `cursor`, `gemini-cli`, `junie`, `kiro`, `roo-code`) migrated to the descriptor-driven import runner with mapper functions extracted into `import-mappers.ts` to keep `index.ts` ↔ `importer.ts` cycles out of the TDZ.
+  - New shared link-format registry (`src/core/reference/link-format-registry.ts`) consolidates per-target link rendering rules.
+
 ## 0.7.0
 
 ### Minor Changes

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-# AgentsMesh — One AI Coding Config for Every Tool
+# AgentsMesh — One `.agentsmesh/` Directory for Every AI Coding 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,94 +12,189 @@
 [![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.**
-
-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.
+</div>
 
-**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/).
+AI coding assistants now ship with their own configuration formats — `CLAUDE.md`, `AGENTS.md`, `.cursor/rules/*.mdc`, `.github/copilot-instructions.md`, `.gemini/settings.json`, `.windsurf/rules/*.md`, `.codex/config.toml`, `.kiro/steering/*.md`, and more. Maintaining the same rules, prompts, MCP servers, hooks, and permissions across all of them by hand causes config drift fast.
 
-</div>
+**AgentsMesh** is an open-source CLI and TypeScript library that fixes this. You write canonical rules, commands, agents, skills, MCP, hooks, ignore files, and permissions once in `.agentsmesh/`, then `agentsmesh generate` projects them out as native config for every supported assistant. `agentsmesh import` brings existing tool configs back into canonical form, and `agentsmesh check` catches drift in CI.
 
 > **Full documentation: [samplexbro.github.io/agentsmesh](https://samplexbro.github.io/agentsmesh)**
 
 ---
 
-## Why AgentsMesh
+## Before / After
 
-- **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/).
+**Before — fragmented assistant-native config in one repo:**
 
----
-
-## Install
+```text
+CLAUDE.md
+AGENTS.md
+.cursor/rules/*.mdc
+.github/copilot-instructions.md
+.gemini/settings.json
+.windsurf/rules/*.md
+.codex/config.toml
+.kiro/steering/*.md
+```
 
-Requires **Node.js 20+**. Supported platforms: **Linux**, **macOS**, and **Windows**.
+**After — one canonical source, generated everywhere:**
+
+```text
+.agentsmesh/
+  rules/
+    _root.md
+  commands/
+  agents/
+  skills/
+  mcp.json
+  hooks.yaml
+  permissions.yaml
+  ignore
+```
 
 ```bash
-npm install -D agentsmesh       # or: pnpm add -D / yarn add -D
-npx agentsmesh --help           # run without installing
+npx agentsmesh generate
 ```
 
-CLI aliases: `agentsmesh` and `amsh`.
+The native files above are still emitted — AgentsMesh writes them for you from `.agentsmesh/`. Edit canonical sources, regenerate, and every tool stays in sync.
 
 ---
 
-## Quick start
+## 60-second quickstart
 
-### New project
+Requires Node.js 20+. Works on Linux, macOS, and Windows (native, not WSL).
 
 ```bash
-agentsmesh init                 # scaffold .agentsmesh/
-# edit .agentsmesh/rules/_root.md
-agentsmesh generate             # produce configs for every enabled tool
+npx agentsmesh init       # scaffold .agentsmesh/ + agentsmesh.yaml
+npx agentsmesh generate   # produce native configs for every enabled tool
+npx agentsmesh check      # CI-friendly drift gate against .agentsmesh/.lock
 ```
 
-### Existing project — adopt with one import
+- **`init`** — creates `agentsmesh.yaml`, `agentsmesh.local.yaml`, and the canonical `.agentsmesh/` directory.
+- **`generate`** — writes `CLAUDE.md`, `AGENTS.md`, `.cursor/`, `.github/copilot-instructions.md`, etc. from canonical sources.
+- **`check`** — exits non-zero if generated files have drifted from `.agentsmesh/.lock`. Drop into CI.
+
+Prefer a local install? `npm install -D agentsmesh` (also `pnpm add -D` / `yarn add -D`). The CLI ships as `agentsmesh` and the shorter alias `amsh`.
+
+---
+
+## Safe adoption in an existing repository
+
+If your repo already has `.cursor/`, `.claude/`, `.github/copilot-instructions.md`, or other native files, you don't have to delete them. The recommended flow imports them into `.agentsmesh/` first, lets you preview the projection, and only then trusts `generate`.
 
 ```bash
-agentsmesh import --from cursor       # or claude-code, copilot, codex-cli, ...
-agentsmesh generate
+npx agentsmesh import --from cursor   # or claude-code, copilot, codex-cli, gemini-cli, windsurf, ...
+npx agentsmesh diff                   # patch-style preview of what generate would change
+npx agentsmesh generate               # write native configs (back) from canonical
+npx agentsmesh check                  # add to CI to detect drift
 ```
 
-### Personal global config
+What this gets you:
+
+- `import` reads existing tool configs and writes equivalent canonical files into `.agentsmesh/` — round-trip metadata is preserved so re-import doesn't lose information.
+- `diff` shows the unified patch every output file would receive, so you can review before any write.
+- `check` reads `.agentsmesh/.lock` and fails the build if the canonical sources and the generated files disagree.
+
+`import --from` accepts the built-in target IDs: `claude-code`, `cursor`, `copilot`, `codex-cli`, `gemini-cli`, `windsurf`, `continue`, `cline`, `kiro`, `junie`, `roo-code`, `antigravity`. Plugin targets are valid too.
+
+---
+
+## Demo
+
+<!-- TODO: Add terminal demo GIF showing init → generate → diff → check. -->
+
+A quick sample of the canonical → native projection:
 
 ```bash
-agentsmesh init --global
-agentsmesh import --global --from claude-code
-agentsmesh generate --global          # writes to ~/.claude/, ~/.cursor/, etc.
+npx agentsmesh init
+find .agentsmesh -maxdepth 2 -type f      # see the canonical scaffold
+npx agentsmesh generate
+npx agentsmesh diff                       # preview future changes
+npx agentsmesh check                      # CI-style drift gate
 ```
 
+On macOS/Linux you can also run `tree .agentsmesh` if you have `tree` installed.
+
+---
+
+## Supported AI coding tools
+
+AgentsMesh currently generates native config for every major AI coding assistant — Claude Code, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Continue, Cline, Kiro, Codex CLI, Junie, Roo Code, Antigravity — plus plugin targets you can ship as standalone npm packages. Each tool's native vs. embedded support per feature is tracked in the [supported tools matrix](https://samplexbro.github.io/agentsmesh/reference/supported-tools/). The full matrix table is also embedded [further down this README](#supported-tools--feature-matrix).
+
+---
+
+## Why developers use AgentsMesh
+
+- **Bidirectional sync** — `import` reads existing tool configs into `.agentsmesh/`; `generate` projects them back out. Round-trips are loss-free, so adopting AgentsMesh in an existing repo never throws away data.
+- **Automatic link rebasing** — references like `.agentsmesh/skills/foo/SKILL.md` are rewritten to target-relative paths in every generated artifact, so cross-file links stay valid from `.claude/`, `.cursor/`, `.github/`, `.codex/`, and the rest.
+- **Managed embedding with round-trip metadata** — when a target has no native slot for a feature (e.g. commands in Codex CLI, agents in Cline), AgentsMesh embeds it with frontmatter that survives the next `import`. No silent data loss; the full feature-by-feature breakdown lives in the [supported tools matrix](https://samplexbro.github.io/agentsmesh/reference/supported-tools/).
+- **Team-safe collaboration** — `agentsmesh check` is a CI drift gate against `.agentsmesh/.lock`, `agentsmesh diff` previews changes, `agentsmesh merge` rebuilds the lock after three-way Git conflicts, and `lock_features` + per-feature `strategy` prevent accidental overrides.
+- **Global mode** — `~/.agentsmesh/` syncs personal AI config to `~/.claude/`, `~/.cursor/`, `~/.codex/`, `~/.windsurf/`, and other user-level folders. Every CLI command accepts `--global`.
+- **Extensible** — community packs (`agentsmesh install ...`), remote `extends`, runtime plugins (`agentsmesh plugin add`), schema-validated config files, and a typed programmatic API for scripts, IDE extensions, and CI.
+
+---
+
+## Why not just `AGENTS.md`?
+
+[`AGENTS.md`](https://agents.md) is great as a shared, human-readable instruction file. AgentsMesh uses `AGENTS.md` natively where the target supports it (Codex CLI, Cursor, Copilot, Junie, Windsurf, …) and treats it as a first-class output, not a competitor.
+
+The reason `AGENTS.md` alone is not enough: most AI coding assistants expose configuration surfaces beyond a single instruction markdown file, and those surfaces don't all overlap.
+
+- **Cursor** has `.cursor/rules/*.mdc` (with frontmatter scopes), `.cursorignore`, MCP config, and hooks.
+- **Claude Code** has `CLAUDE.md`, `.claude/agents/`, `.claude/skills/`, `.claude/commands/`, `.claude/settings.json`, hooks, and permissions.
+- **GitHub Copilot** has `.github/copilot-instructions.md`, `.github/instructions/*.instructions.md`, agents, prompts, and (partial) hooks.
+- **Gemini CLI** has `GEMINI.md`, `.gemini/settings.json` (MCP + hooks), `.gemini/commands/*.toml`, and agents.
+- **Codex CLI** has `AGENTS.md` plus `.codex/config.toml`, `.codex/agents/*.toml`, and `.codex/rules/`.
+- **Windsurf**, **Continue**, **Cline**, **Kiro**, **Junie**, **Roo Code**, **Antigravity** each have their own native rules, workflows, MCP servers, skills, and ignore files.
+
+AgentsMesh canonicalizes all of these — rules, commands, agents, skills, MCP servers, hooks, ignore patterns, permissions — so you don't pick one tool's surface as the lowest common denominator. When a tool has no native slot for a feature, AgentsMesh embeds it with round-trip metadata instead of dropping it.
+
 ---
 
-## Features
+## Core concepts
+
+`.agentsmesh/` is the canonical source of truth. Generated tool files are artifacts. The directory contains:
+
+- `rules/_root.md` — the root rule every target projects (typically becomes `CLAUDE.md`, `AGENTS.md`, `.cursor/rules/_root.mdc`, etc.).
+- `rules/*.md` — additional scoped rules.
+- `commands/*.md` — reusable slash-style prompts/commands.
+- `agents/*.md` — agent definitions (where the target supports them).
+- `skills/<name>/SKILL.md` (+ supporting files) — composable skills.
+- `mcp.json` — MCP server definitions.
+- `hooks.yaml` — pre/post tool hooks.
+- `permissions.yaml` — allow/deny rules where the target supports them.
+- `ignore` — paths the assistant should not read or modify.
+
+Configuration:
+
+- `agentsmesh.yaml` — selects which targets and features are enabled.
+- `agentsmesh.local.yaml` — per-developer overrides (gitignored by default).
+- `.agentsmesh/.lock` — drift-detection lock file consumed by `agentsmesh check`.
 
-### One config, every AI coding tool
+Detailed contracts: [Canonical Config](https://samplexbro.github.io/agentsmesh/canonical-config/) · [Generation pipeline](https://samplexbro.github.io/agentsmesh/reference/generation-pipeline/).
 
-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**:
+---
+
+## CLI usage
 
-| 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` |
+```bash
+agentsmesh init [--global] [--yes]
+agentsmesh generate [--global] [--targets <csv>] [--check] [--dry-run] [--force] [--refresh-cache]
+agentsmesh import --from <target> [--global]
+agentsmesh diff [--global] [--targets <csv>]
+agentsmesh lint [--global] [--targets <csv>]
+agentsmesh watch [--global] [--targets <csv>]
+agentsmesh check [--global]
+agentsmesh merge [--global]
+agentsmesh matrix [--global] [--targets <csv>] [--verbose]
+agentsmesh install <source> [--sync] [--path <dir>] [--target <id>] [--as <kind>] [--name <id>] [--extends] [--dry-run] [--global] [--force]
+agentsmesh plugin add|list|remove|info [--version <v>] [--id <id>]
+agentsmesh target scaffold <id> [--name <displayName>] [--force]
+```
 
-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.
+`agentsmesh --help` prints the same surface; `agentsmesh <cmd> --help` is also supported.
 
-### Global mode — personal setup, same workflow
+### Global mode (personal AI assistant config)
 
 `.agentsmesh/` at the project level is for teams. `~/.agentsmesh/` at the home level is for personal setup across every repo you touch:
 
@@ -109,9 +204,9 @@ agentsmesh import --global --from claude-code
 agentsmesh generate --global   # writes ~/.claude/CLAUDE.md, ~/.cursor/, ~/.codex/, ~/.windsurf/, etc.
 ```
 
-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)
+Every built-in target with a global layout 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
+### Plugins for new AI coding tools
 
 Ship new target support as a standalone npm package — no fork, no core PR:
 
@@ -125,12 +220,14 @@ Plugins have full parity with built-in targets: project + global layouts, featur
 
 ### 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
+- **`agentsmesh check`** — CI gate that exits 1 if generated files drifted from the lock.
+- **`agentsmesh diff`** — preview what the next `generate` would change.
+- **`agentsmesh lint`** — validate canonical config against target-specific constraints; also surfaces cross-target warnings (`silent-drop-guard`, `hook-script-references`, `rule-scope-inversion`) for content a target would silently drop or mishandle. [Lint reference →](https://samplexbro.github.io/agentsmesh/cli/lint/)
+- **`agentsmesh watch`** — regenerate target files on save during local editing.
+- **`agentsmesh merge`** — recover from three-way `.lock` conflicts after `git merge`.
+- **Collaboration config** — `lock_features` and `strategy` prevent accidental overrides.
 
-### Community packs
+### Community packs and shared config
 
 Install shared skills, rules, agents, and commands from any git repo:
 
@@ -142,57 +239,46 @@ 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
+### What to commit and what to gitignore
 
-- **`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
+`agentsmesh init` writes a `.gitignore` that follows the recommended convention. The defaults are deliberate:
 
-[Extending guide →](https://samplexbro.github.io/agentsmesh/guides/extending/) · [Building plugins →](https://samplexbro.github.io/agentsmesh/guides/building-plugins/)
+| Path | In git? | Why |
+|---|---|---|
+| `.agentsmesh/` (canonical) | **commit** | The source of truth — must be in git. |
+| `.agentsmesh/.lock` | **commit** | Drift detection contract. `agentsmesh check` compares against this. |
+| `.agentsmesh/packs/` | **gitignore** | Materialized from `installs.yaml`. Same model as `node_modules` — `agentsmesh install --sync` reproduces them deterministically post-clone. |
+| `agentsmesh.local.yaml` | **gitignore** | Per-developer overrides. |
+| `.agentsmesh/.lock.tmp` | **gitignore** | Transient. |
+| `.agentsmeshcache` | **gitignore** | Remote-extends cache. |
+| Generated tool folders (`.claude/`, `.cursor/`, `.github/`, `.gemini/`, `CLAUDE.md`, `AGENTS.md`, etc.) | **commit** | AI tools read these at runtime. Committing means a fresh clone has working AI configs without a build step. `agentsmesh check` in CI catches drift between canonical and generated. |
 
----
+Why generated configs stay committed: the same reason `package-lock.json` does. They're deterministic build output that downstream consumers (in this case, the AI tool itself) read directly. Gitignoring them breaks fresh-clone UX and makes `agentsmesh check` meaningless. PR reviewers also benefit from seeing the projected diff in the format Claude/Cursor/Copilot will actually consume.
 
-## Supported tools — feature matrix
+If your team has a strong reason to gitignore generated configs (e.g., monorepo size concerns, regenerate-on-checkout hooks), add the target-specific entries manually — but expect to wire `agentsmesh generate` into your post-checkout flow.
 
-### Project scope (`agentsmesh generate`)
+### Schema-validated configs (IDE autocomplete)
 
-<!-- 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 -->
+Every config file ships with a generated JSON Schema, so VS Code, JetBrains, and other editors give you autocomplete and validation out of the box:
 
-### 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 -->
+| Config file | JSON Schema |
+|---|---|
+| `agentsmesh.yaml` / `.local.yaml` | `node_modules/agentsmesh/schemas/agentsmesh.json` |
+| `.agentsmesh/hooks.yaml` | `schemas/hooks.json` |
+| `.agentsmesh/permissions.yaml` | `schemas/permissions.json` |
+| `.agentsmesh/mcp.json` | `schemas/mcp.json` |
+| `.agentsmesh/packs/*/pack.json` | `schemas/pack.json` |
 
-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.
+`agentsmesh init` writes the appropriate `# yaml-language-server: $schema=...` directive (or `$schema` field for JSON) into each canonical file, so editors pick up validation immediately.
 
 ---
 
-## Programmatic API
+## TypeScript / 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`.
 
+`loadProjectContext()` mirrors what the CLI does on startup: resolves config, applies local overrides, loads plugins, materializes `extends` and installed packs, and reads the canonical directory. The result is a single context value you can pass to `generate`, `lint`, or `diff` — the same surface the CLI uses.
+
 ```ts
 import {
   loadProjectContext,
@@ -241,7 +327,45 @@ 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+.
+Every public symbol resolves to a real `.d.ts` under strict TypeScript. Full reference in the [programmatic API docs](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+.
+
+---
+
+## Supported tools — feature matrix
+
+### Project scope (`agentsmesh generate`)
+
+<!-- agentsmesh:support-matrix:project -->
+| Feature | Antigravity | Claude Code | Cline | Codex CLI | Continue | Copilot | Cursor | Gemini CLI | Junie | Kiro | Roo Code | Windsurf |
+|---|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|
+| Rules | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native |
+| Additional Rules | Native | Native | Native | Native | Native | Native | Embedded | Embedded | Native | Native | Native | Native |
+| Commands | Partial (workflows) | Native | Native (workflows) | Embedded | Embedded | Native | Native | Native | Native | — | Native | Native (workflows) |
+| Agents | — | Native | Embedded | Native | — | Native | Native | Native | Native | Native | Partial | Embedded |
+| Skills | Native | Native | Native | Native | Embedded | Native | Native | Native | Native | Native | Native | Native |
+| MCP Servers | — | Native | Native | Native | Native | — | Native | Native | Native | Native | Native | Partial |
+| Hooks | — | Native | Native | — | — | Partial | Native | Partial | — | Native | — | Native |
+| Ignore | — | Native | Native | — | — | — | Native | Native (settings-embedded) | Native | Native | Native | Native |
+| Permissions | — | Native | — | — | — | — | Partial | Partial | — | — | — | — |
+<!-- /agentsmesh:support-matrix:project -->
+
+### Global scope (`agentsmesh generate --global`)
+
+<!-- agentsmesh:support-matrix:global -->
+| Feature | Antigravity | Claude Code | Cline | Codex CLI | Continue | Copilot | Cursor | Gemini CLI | Junie | Kiro | Roo Code | Windsurf |
+|---|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|
+| Rules | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native |
+| Additional Rules | Embedded | Native | Native | Embedded | Native | Native | Embedded | Embedded | Embedded | Native | Native | Partial |
+| Commands | Partial (workflows) | Native | Native (workflows) | Embedded | Native | Native | Native | Native | Native | — | Native | Native (workflows) |
+| Agents | — | Native | Embedded | Native | — | Native | Native | Native | Native | Native | Partial | Embedded |
+| Skills | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native |
+| MCP Servers | Native | Native | Native | Native | Native | — | Native | Native | Native | Native | Native | Partial |
+| Hooks | — | Native | Native | — | — | — | Native | Partial | — | — | — | 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.
 
 ---
 

package/dist/canonical.d.ts

@@ -1,5 +1,5 @@
-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 { b as CanonicalFiles, V as ValidatedConfig } from './schema-BeGiBqbB.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-BeGiBqbB.js';
 import 'zod';
 
 /**