agentsmesh 0.21.0 → 0.23.0

package/CHANGELOG.md

@@ -1,5 +1,249 @@
 # Changelog
 
+## 0.23.0
+
+### Minor Changes
+
+- 6a2e415: feat(lessons)!: JSON graph store, universal CLI primitives, clean break from YAML+MD
+
+  **BREAKING.** The lessons subsystem is now a single normalized JSON graph at
+  `.agentsmesh/lessons/lessons.json`. The previous YAML-index + per-topic
+  Markdown + journal store is removed entirely. The legacy public API is
+  removed.
+
+  **Why a clean break:** dragging a deprecation window along would leave two
+  parallel surfaces (CLI + library) that have to stay in sync forever, and the
+  old recall ritual (read 400+ line YAML index + matching topic Markdown files)
+  encouraged agents to skip it. The new single-command primitives — `lessons
+query` to recall, `lessons add` to capture — are hard to rationalize past and
+  return only matched rules (~100–500 tokens) instead of the whole index.
+
+  ## What's new
+
+  **CLI** (`agentsmesh lessons …`):
+  - `query --file <p> --cmd <c> [--keyword <k>] [--format plain|md|json]` —
+    recall primitive. Returns only matched lesson rules; defaults to one rule
+    per line.
+  - `add "<rule>" --topic <id> --trigger-file <glob> [--trigger-cmd <regex>]
+[--trigger-kw <text>] [--evidence <ref>] [--new-topic --topic-summary
+"<text>"]` — capture primitive. Lock-serialized, atomic, idempotent on
+    repeat.
+  - `topics`, `show <topic>`, `deprecate <id> [--superseded-by <id>]`,
+    `journal`, `validate`, `import-md`.
+
+  **MCP tools.** `lessons_query` and `lessons_add` register with the embedded
+  MCP server. Same surface as the CLI primitives.
+
+  **Programmatic API** (`agentsmesh/lessons`):
+  - `loadLessonsGraph` / `tryLoadLessonsGraph` / `saveLessonsGraph` /
+    `serializeGraph` / `graphFilePath` — deterministic load/save.
+  - `queryLessons(graph, { file, command, keyword })` — recall.
+  - `addLesson(root, input, opts?)` — capture; throws `UnknownTopicError` when
+    the topic is missing without `allowNewTopic`.
+  - `validateLessonsGraph(graph)` →
+    `{ ok, findings: [{ level, code, message, … }] }`. Codes: `SCHEMA_INVALID`,
+    `DANGLING_TOPIC`, `DANGLING_TRIGGER`, `DANGLING_SUPERSEDER`,
+    `DUPLICATE_RULE`, `SUPERSEDED_WITHOUT_TARGET`, `ACTIVE_WITH_SUPERSEDER`,
+    `ORPHAN_TOPIC`, `ORPHAN_TRIGGER`.
+  - `importLegacyLessons(root, { migratedAt })` — one-shot upgrade migrator.
+  - `acquireLessonsLock(root)` — process lock; same primitive as
+    `.generate.lock` / `.install.lock`.
+
+  ## Upgrade path
+
+  If you used the previous YAML+MD store, the first `agentsmesh lessons`
+  invocation auto-migrates: parses `index.yaml` + `topics/*.md` + `journal.md`,
+  writes `lessons.json`, and **deletes the legacy files** so the project lands
+  in a clean state. The migrator preserves provenance — every imported lesson
+  gets `evidence[0] = "legacy:.agentsmesh/lessons/topics/<topic>.md#rule-N"`
+  plus any inlined `(Evidence L<n>)` references parsed verbatim as `legacy:L<n>`.
+
+  Run `agentsmesh lessons import-md` explicitly if you prefer to migrate at a
+  specific point in time, e.g. inside a release-prep script.
+
+  ## Removed (breaking)
+  - **Files removed.** `.agentsmesh/lessons/index.yaml`,
+    `.agentsmesh/lessons/journal.md`, `.agentsmesh/lessons/topics/`, plus the
+    separate distill tracker (`distill-ledger.yaml`, `distill-proposal.md`).
+    All are recreated under the new single-file graph by the migrator.
+  - **Public API removed.** `loadLessonsIndex`, `readTriggeredLessons`,
+    `appendLessonToJournal`, `formatLessonBullet`, `parseIndex`,
+    `LessonsIndexSchema`, `LessonsCluster`, `LessonsIndex`, `matchTriggers`,
+    `ToolEvent`, `parseBullets`, `ParsedBullet`, `hashBullet`, `loadLedger`,
+    `saveLedger`, `Ledger`, `scoreBullet`, `ScoredCluster`,
+    `LESSONS_JOURNAL_TEMPLATE`, `LESSONS_INDEX_TEMPLATE`, `AppendLessonResult`,
+    `LessonCaptureInput`, `TriggeredLesson`.
+  - **package.json scripts removed.** `distill`, `distill:apply`. The distill
+    flow is subsumed by direct `lessons add`.
+
+  ## Compatibility
+  - The CLI surface is **additive** for the `lessons` subcommand tree — no
+    existing CLI command changes shape.
+  - `agentsmesh init --lessons` still scaffolds the subsystem; it now writes
+    an empty graph instead of empty YAML+MD shells.
+  - The procedural rule in `_root.md` is regenerated by `agentsmesh generate`
+    into every target's root file; agents call the same two shell commands in
+    every harness.
+
+  ## Constraints
+  - The graph at `.agentsmesh/lessons/lessons.json` is the single source of
+    truth — never edit it by hand; go through the CLI or `addLesson`.
+  - Writers serialize through a process lock at
+    `.agentsmesh/lessons/.lessons.lock` — concurrent captures cannot lose data.
+  - Output is deterministic (alphabetical keys at every depth, trailing
+    newline) so diffs stay clean.
+
+- 60dbbd9: feat(lessons): public-readiness hardening — discoverable flags, safer capture/recall, clearer errors
+
+  The lessons subsystem is polished for general use, closing the gaps a first-time
+  external user would hit. No breaking changes to the documented happy path.
+
+  **Added**
+  - `agentsmesh lessons query` now documents `--session`, `--no-dedup`, and `--ids`
+    in `--help` (they were parsed but invisible), and every `lessons` subcommand
+    **rejects unknown flags** with the correct usage instead of silently ignoring
+    them — a typoed `--trigger-flie` no longer drops a trigger from a capture.
+  - Running a `lessons` command from a subdirectory of a project now **warns**
+    (`query` finds no graph here; `add` flags that it is about to create a stray
+    `.agentsmesh`) instead of silently returning empty or writing to the wrong place.
+  - Running a `lessons` command in a project initialized **without** `--lessons` no
+    longer dead-ends silently: reads hint to run `agentsmesh init --lessons`, and
+    `lessons add` still captures but warns that recall isn't wired into your AI
+    tools until you activate the subsystem.
+  - A present-but-malformed `.agentsmesh/lessons/config.json` now surfaces a stderr
+    warning rather than silently reverting to defaults.
+
+  **Changed**
+  - Capture rejects a rule longer than 2000 characters (`OVERSIZED_RULE`), and the
+    recall hook truncates any over-long rule before injecting it into agent context,
+    so a graph from a cloned third-party repo cannot flood the context with one
+    giant rule. The lessons reference now documents this **trust model**.
+  - `agentsmesh lessons hook` bounds the stdin payload it reads, so a runaway pipe
+    cannot exhaust memory.
+  - `lessons` errors now surface verbatim in `--json` output (e.g.
+    `"Recall needs a predicate…"`) instead of a generic `Command 'lessons' failed`.
+  - `agentsmesh init --lessons` only prints "the graph starts empty" when it
+    actually created the graph on this run.
+
+- 0091779: feat(lessons): two-tier delivery — trimmed always-on trigger + on-demand `lessons` skill
+
+  The lessons recall/capture contract now ships in two tiers, using agentsmesh's
+  native primitives (rules + skills) rather than a single oversized root paragraph:
+  - **Tier 1 — always-on trigger.** `LESSONS_PROCEDURAL_RULE` is trimmed to the
+    binding essentials (both commands, the BLOCKING framing, the recall scope
+    including read-only, the broad capture scope, the graph path, the MCP
+    fallback). It is still injected into `.agentsmesh/rules/_root.md` as a managed
+    block, so it reaches every target through canonical rule generation.
+  - **Tier 2 — on-demand manual.** `agentsmesh init --lessons` now also seeds
+    `.agentsmesh/skills/lessons/SKILL.md`, a `lessons` skill carrying the full
+    operating manual (complete command set, topic workflow, trigger-flag
+    mechanics, the exhaustive rejected-excuse enumeration). It generates to every
+    skill-capable target and can grow without bloating always-on context.
+  - **Graceful degradation.** Targets without skills still receive the Tier-1
+    trigger, so the binding contract stays universal.
+
+  The skill is **create-if-missing** — once present it is your canonical,
+  user-owned content and is never clobbered. Projects generated with the previous
+  single-tier block upgrade to the trimmed block exactly once on the next
+  `generate`/scaffold (legacy form retained for clean strip/upgrade).
+
+### Patch Changes
+
+- 3d59e52: fix: six correctness bugs surfaced by a full feature review
+  - **lessons recall on symlinked roots**: `normalizeRecallFile` now realpaths the
+    project root and an absolute `--file` before relativizing. The CLI derives the
+    root from the physical `process.cwd()` while harnesses pass logical paths
+    (macOS `/tmp` → `/private/tmp`), so on a symlinked checkout `relative()`
+    escaped the root and recall — including the PostToolUse recall hook — silently
+    matched zero lessons. Recall now resolves correctly.
+  - **MCP lessons tools error codes**: failures (unknown topic, predicate-less
+    query, unknown lesson id, capture-guardrail rejections) now return
+    `NOT_FOUND` / `VALIDATION_FAILED` with the domain code in `details`, instead of
+    mislabeling every failure as `IO_ERROR`.
+  - **`generate` scoped-settings feature gating**: disabling a feature (e.g. `mcp`)
+    no longer leaks it into the gemini / zed / amp / augment `settings.json`
+    sidecars — `emitScopedSettings` is now gated by the enabled-feature set, for
+    plugin descriptors as well as builtins.
+  - **`matrix --global` accuracy**: targets without `globalSupport` (cloud-only
+    Jules, Replit Agent) now report `none` in global scope instead of falsely
+    claiming project-level support that `generate --global` never produces.
+  - **`install --sync` consent**: elevated-artifact consent is now persisted
+    (`accepted_elevated`) and replayed, so a sync no longer silently strips
+    previously-consented hooks / permissions / mcp while `installs.yaml` and
+    `pack.yaml` still claim them.
+  - **`refresh` / `install --sync` branch pins**: a branch pin (`@main`) keeps
+    tracking the branch across refreshes instead of freezing to a SHA after the
+    first refresh and never advancing again.
+
+- 6a5fc7e: fix(install): retry the git-source cache finalize on Windows transient locks
+
+  Fetching a git `extends:`/`install` source could intermittently fail on Windows
+  with `EPERM: operation not permitted, rename '<cache>.tmp' -> '<cache>'`. The
+  fetcher finalizes the cache by renaming the freshly-cloned staging directory
+  into place; on Windows the just-exited `git clone` handle (or an antivirus /
+  search-indexer scan) can still pin those files for a few milliseconds, so the
+  rename is rejected. The finalize rename now retries on the transient codes
+  Windows raises (`EPERM`/`EACCES`/`EBUSY`/`ENOTEMPTY`/`EEXIST`) with a short
+  backoff, so the lock clears instead of surfacing a spurious "fetch failed".
+  POSIX behavior is unchanged (a single rename).
+
+## 0.22.0
+
+### Minor Changes
+
+- c2a13ad: Add `agentsmesh init --lessons` and a new `agentsmesh/lessons` public API for
+  the lessons recall + capture subsystem.
+
+  The subsystem keeps agents from repeating past mistakes via a procedural rule
+  that lives in every target's root file: before any edit or command, scan
+  `.agentsmesh/lessons/index.yaml` and read every matched
+  `.agentsmesh/lessons/topics/<topic>.md`; after any failure, append to
+  `.agentsmesh/lessons/journal.md`. The optional repo-local `pnpm distill` /
+  `pnpm distill:apply` scripts can help maintain AgentsMesh's own topic routing,
+  but the generated rule does not require package-manager-specific tooling.
+
+  **Using it:**
+  - **Fresh init:** `agentsmesh init --lessons` — creates the canonical scaffold
+    AND the lessons subsystem in one command.
+  - **Retroactive add (existing project):** the same `agentsmesh init --lessons`
+    — when `agentsmesh.yaml` already exists, init only scaffolds the lessons
+    artifacts and appends the procedural rule to `_root.md`. Idempotent.
+  - After either flow, run `agentsmesh generate` to project the procedural rule
+    to every target's root file.
+
+  **Public API** (importable from `agentsmesh/lessons`):
+  - `scaffoldLessons(projectRoot)` — idempotent scaffolder used internally by
+    `init --lessons`; reusable from custom tooling.
+  - `loadLessonsIndex(projectRoot)`, `readTriggeredLessons(projectRoot, event)`,
+    `appendLessonToJournal(projectRoot, input)`, and `formatLessonBullet(input)` —
+    one high-level, target-agnostic read/write layer for integrations that should
+    not hand-roll filesystem access.
+  - `lessonsPaths(projectRoot)`, `LESSONS_PROCEDURAL_RULE`,
+    `LESSONS_JOURNAL_TEMPLATE`, `LESSONS_INDEX_TEMPLATE` — paths and templates.
+  - `parseIndex`, `LessonsIndexSchema`, `matchTriggers`, `scoreBullet`,
+    `loadLedger`, `saveLedger`, `hashBullet`, `parseBullets` — building blocks
+    for downstream tooling (custom distillers, recall hooks, IDE plugins).
+
+  **Universal across every target.** The subsystem uses plain markdown files
+  read via standard file I/O — no `Skill` tool, no description-match, no
+  per-target projection. Works in Claude Code, Codex CLI, Cline, Roo Code,
+  Cursor, Gemini CLI, Aider, Goose, and every other supported harness.
+
+  **Linter integration:** `agentsmesh lint` now validates the lessons subsystem
+  when present — checks that `index.yaml` parses, topic files referenced in the
+  index exist, and the journal file is well-formed.
+
+  **Constraints:**
+  - `--lessons` is project-mode only. Combining with `--global` errors out.
+  - Removal: `rm -rf .agentsmesh/lessons/` and strip the `## Lessons` paragraph
+    from `.agentsmesh/rules/_root.md`.
+
+### Patch Changes
+
+- c75a424: Surface marketplace sub-pack install failures instead of swallowing them silently, and route skill-pack sub-packs through the correct install path.
+- c75a424: Fix qwen-code global-mode rule embedding. Rules were silently dropped when generating in global mode; they are now embedded inline using the same pattern as other global-mode targets.
+- c75a424: Restructure the generation contract paragraph to lead with an explicit **NEVER edit generated files** prohibition naming the generated paths (`.claude/`, `.cursor/`, `AGENTS.md`, etc.), followed by **All changes MUST go through `.agentsmesh` first**. Agents were initially understanding the contract but forgetting it over multi-step conversations — front-loading the prohibition makes it stickier. All legacy contract body versions (v1-v10) remain detected for safe in-place upgrade.
+
 ## 0.21.0
 
 ### Minor Changes

package/README.md

@@ -16,9 +16,11 @@
 
 </div>
 
-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.
+Every AI coding assistant has its own configuration format — `CLAUDE.md`, `AGENTS.md`, `.cursor/rules/*.mdc`, `.github/copilot-instructions.md`, and more. Keeping the same rules, prompts, MCP servers, hooks, and permissions in sync across all of them by hand is tedious, and they drift apart fast.
 
-**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.
+**AgentsMesh** fixes this. It is an open-source CLI and TypeScript library: write your rules, commands, agents, skills, MCP servers, hooks, ignore files, and permissions once in `.agentsmesh/`, run `agentsmesh generate`, and every tool gets its native config. `agentsmesh import` pulls existing tool configs back into the one source, and `agentsmesh check` catches drift in CI.
+
+**And your agents learn from your repo.** With [lessons](#teach-your-agents-lessons), an agent saves a short rule every time something goes wrong — a failing test, a code review comment, a wrong assumption — and recalls it automatically before it touches the same files again. One shared memory, read and written by every AI tool you use.
 
 > **Full documentation: [samplexbro.github.io/agentsmesh](https://samplexbro.github.io/agentsmesh)**
 
@@ -87,6 +89,8 @@ AGENTS.md
   hooks.yaml
   permissions.yaml
   ignore
+  lessons/
+    lessons.json
 ```
 
 ```bash
@@ -111,10 +115,57 @@ agentsmesh check      # CI-friendly drift gate against .agentsmesh/.lock
 - **`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.
 
+Want your agents to learn from this repo too? Add the optional lessons memory:
+
+```bash
+agentsmesh init --lessons   # adds a shared memory: recall before edits, capture after failures
+```
+
+See [Teach your agents: lessons](#teach-your-agents-lessons) just below for how it works.
+
 If you installed via `npm install -D agentsmesh` (also `pnpm add -D` / `yarn add -D`), prefix each command with `npx`. The CLI ships as both `agentsmesh` and the shorter alias `amsh`.
 
 ---
 
+## Teach your agents: lessons
+
+Lessons give your AI coding agents a **memory of past mistakes**. An agent reads that memory *before* it touches anything, and writes to it *after* something goes wrong — so the same mistake doesn't happen twice, in any tool.
+
+The memory is one git-tracked file: `.agentsmesh/lessons/lessons.json`. Every agent — Claude Code, Cursor, Codex CLI, Copilot, and the rest — reads and writes the *same* file through two commands:
+
+- **Recall** — before editing a file or running a state-changing command, the agent asks `agentsmesh lessons query --file <path> --cmd <command>`, gets back the rules that match, and follows them.
+- **Capture** — right after a failure (a red test, a lint error, a review comment, a wrong assumption), the agent saves the rule with `agentsmesh lessons add "<rule>" --topic <id> --trigger-file <glob>`.
+
+A 30-second example:
+
+```bash
+# 1. One-time setup
+agentsmesh init --lessons && agentsmesh generate
+
+# 2. You hit a bug: a Windows path broke because of a backslash.
+#    Capture the lesson so it never bites again:
+agentsmesh lessons add "Normalize CLI display paths to forward slashes" \
+  --topic windows-paths \
+  --new-topic --topic-summary "Cross-platform path handling" \
+  --trigger-file "src/cli/**/*.ts"
+
+# 3. Later, before editing a CLI file, the agent recalls it automatically:
+agentsmesh lessons query --file src/cli/foo.ts
+#   -> Normalize CLI display paths to forward slashes
+```
+
+**Works in every tool.** `init --lessons` wires the loop once. A small always-on rule lands in `.agentsmesh/rules/_root.md` — rules are native in every target, so every agent gets the recall/capture habit — and the full operating manual ships as a `lessons` skill on tools that support skills. Agents without shell access use the matching MCP tools (`lessons_query` / `lessons_add`).
+
+**Team-shared and reviewable.** The graph is a normal git-tracked file: a lesson your agent learns today helps every teammate's agent tomorrow, and every change shows up in code review like any other diff.
+
+**Trust model.** `lessons.json` is checked into the repo, so its rules are project content — trusted at the same level as the code and `CLAUDE.md`. Review a lesson graph from a cloned third-party repo as you would any other code you run. As a guardrail, recall truncates any single rule to 2000 characters before injecting it and capture rejects longer rules, so a malformed rule cannot flood the agent's context.
+
+**Upgrading from the legacy store?** Run `agentsmesh lessons import-md` once to migrate `index.yaml` + `topics/*.md` + `journal.md` into the graph; the CLI deletes the legacy files after a successful migration.
+
+Full walkthrough: [Teach your AI agents with lessons](https://samplexbro.github.io/agentsmesh/guides/lessons/) · every subcommand and flag: [`agentsmesh lessons` CLI reference](https://samplexbro.github.io/agentsmesh/cli/lessons/).
+
+---
+
 ## 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`.
@@ -132,7 +183,7 @@ What this gets you:
 - `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 any built-in target ID listed in the [Supported Tools matrix](#feature-support-matrix). Plugin targets are valid too.
+`import --from` accepts any built-in target ID listed in the [Supported Tools matrix](#supported-tools--feature-matrix). Plugin targets are valid too.
 
 ---
 
@@ -169,6 +220,7 @@ AgentsMesh generates native config for every major AI coding assistant — plus
 ## 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.
+- **Agents that learn** — the optional [lessons memory](#teach-your-agents-lessons) recalls past-mistake rules before each edit and captures new ones after each failure, shared across every tool and every teammate.
 - **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.
@@ -208,6 +260,7 @@ AgentsMesh canonicalizes all of these — rules, commands, agents, skills, MCP s
 - `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.
+- `lessons/` — optional recall/capture memory: a single JSON graph (`lessons.json`) of lessons + topics + triggers. Agents talk to it via `agentsmesh lessons query` / `agentsmesh lessons add` rather than hand-editing files.
 
 Configuration:
 
@@ -222,7 +275,7 @@ Detailed contracts: [Canonical Config](https://samplexbro.github.io/agentsmesh/c
 ## CLI usage
 
 ```bash
-agentsmesh init [--global] [--yes]
+agentsmesh init [--global | --lessons] [--yes]    # --lessons is project-mode only (rejected with --global)
 agentsmesh generate [--global] [--targets <csv>] [--check] [--dry-run] [--force] [--refresh-cache]
 agentsmesh import --from <target> [--global]
 agentsmesh convert --from <target> --to <target> [--global] [--dry-run]
@@ -239,10 +292,17 @@ agentsmesh installs list [--global]
 agentsmesh refresh [<name>[,<name>...]] [--dry-run] [--force] [--json] [--global]
 agentsmesh plugin add|list|remove|info [--version <v>] [--id <id>]
 agentsmesh target scaffold <id> [--name <displayName>] [--force]
+agentsmesh lessons query [--file <p>] [--cmd <c>] [--keyword <k>] [--format plain|md|json] [--top <n>] [--max-tokens <n>] [--all] [--session <id>] [--no-dedup] [--ids]
+agentsmesh lessons add "<rule>" --topic <id> --trigger-file <glob> [--trigger-cmd <regex>] [--trigger-kw <text>] [--evidence <ref>] [--rationale <text>] [--new-topic --topic-summary "<one line>"]
+agentsmesh lessons topics | show <topic|id> | deprecate <id> | merge <loser> <keeper> | untrigger <lesson> <trigger> | strip-markers | journal | validate | stats | prune [--apply] | import-md
 ```
 
 `agentsmesh --help` prints the same surface; `agentsmesh <cmd> --help` is also supported.
 
+Lessons recall (`query`) is relevance-ranked and lean by default (top 10 results, ~400-token budget); capture (`add`) requires at least one trigger that can actually fire and rejects rules over 2000 characters. Every flag, warning, and maintenance subcommand is documented in the [`agentsmesh lessons` CLI reference](https://samplexbro.github.io/agentsmesh/cli/lessons/).
+
+Per-project recall tuning lives in `.agentsmesh/lessons/config.json`, written by `init --lessons` with every field at its default: `{ "recallLimit": 10, "recallMaxTokens": 400, "autoPrune": false }`. Lower the caps to keep recall lean on a large graph; set `"autoPrune": true` to garbage-collect dead triggers and orphan topics automatically after each capture (safe and fully git-reversible). `--top`/`--max-tokens`/`--all` override the caps per call.
+
 ### Machine-readable output
 
 All commands support `--json` for CI pipelines and scripting:
@@ -356,6 +416,7 @@ installs against their declared sources. They are orthogonal.
 | `agentsmesh.local.yaml` | **gitignore** | Per-developer overrides. |
 | `.agentsmesh/.lock.tmp` | **gitignore** | Transient. |
 | `.agentsmeshcache` | **gitignore** | Remote-extends cache. |
+| `.agentsmesh/lessons/recall-log.jsonl` | **gitignore** | Opt-in recall telemetry (`AGENTSMESH_LESSONS_TELEMETRY=1`) — a runtime artifact, not the canonical graph. Added by `init --lessons`. |
 | 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.
@@ -381,9 +442,10 @@ Every config file ships with a generated JSON Schema, so VS Code, JetBrains, and
 | Variable | Default | Description |
 |---|---|---|
 | `AGENTSMESH_GITHUB_TOKEN` | — | GitHub personal access token for private repo installs and `extends`. |
-| `AGENTSMESH_CACHE` | `~/.agentsmeshcache` | Override the remote-extends / tarball cache directory. |
+| `AGENTSMESH_CACHE` | `~/.agentsmesh/cache` | Override the remote-extends / tarball cache directory (the gitignored `.agentsmeshcache` in the project is a symlink to it). Must be an absolute path. |
 | `AGENTSMESH_MAX_TARBALL_MB` | `500` | Maximum GitHub tarball size in MiB the install command will accept. Allowed range: `1`–`4096`. Increase this when installing from large monorepos. |
 | `AGENTSMESH_STRICT_PLUGINS` | `0` | When set to `1`, a failed plugin descriptor import fails the build instead of warning-and-skip. Useful in CI where a missing plugin target is a regression. |
+| `AGENTSMESH_ALLOW_LOCAL_GIT` | `0` | When set to `1`, enables `git+file://` sources in `extends` and `install`. Disabled by default because on shared hosts a world-writable repo could be planted by another user and combined with elevated-artifact emission for local privilege escalation. |
 
 ---
 
@@ -468,11 +530,11 @@ Every public symbol resolves to a real `.d.ts` under strict TypeScript. Full ref
 <!-- agentsmesh:support-matrix:global -->
 | Feature | Aider | Amazon Q Developer | Amp | Antigravity | Augment Code | Claude Code | Cline | Codex CLI | Continue | GitHub Copilot | Crush | Cursor | Deep Agents CLI | Factory Droid | Gemini CLI | Goose | Jules | Junie | Kilo Code | Kiro | OpenCode | Pi Agent | Qwen Code | Replit Agent | Roo Code | Rovo Dev | Trae | Warp | Windsurf | Zed |
 |---|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|
-| Rules | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | — | Native | — |
-| Additional Rules | Embedded | — | Embedded | Embedded | Native | Native | Native | Embedded | Native | Native | Embedded | Embedded | Embedded | Embedded | Embedded | Embedded | Embedded | Embedded | Native | Native | Native | Embedded | Embedded | Embedded | Native | Embedded | Native | — | Partial | — |
+| Rules | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | — | Native | Native | Native | Native | Native | Native | — | Native | Native | Native | — | Native | — |
+| Additional Rules | Embedded | — | Embedded | Embedded | Native | Native | Native | Embedded | Native | Native | Embedded | Embedded | Embedded | Embedded | Embedded | Embedded | — | Embedded | Native | Native | Native | Embedded | Embedded | — | Native | Embedded | Native | — | Partial | — |
 | Commands | — | — | — | Partial (workflows) | Native | Native | Native (workflows) | Embedded | Native | Native | — | Native | — | — | Native | — | — | Native | Native | — | Native | — | Native | — | Native | — | — | — | Native (workflows) | — |
 | Agents | — | — | — | — | — | Native | Embedded | Native | — | Native | — | Native | — | Native | Native | — | — | Native | Native | Native | Native | — | Native | — | Partial | — | — | — | Embedded | — |
-| Skills | Native | — | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | — | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | — |
+| Skills | Native | — | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | — | Native | Native | Native | Native | Native | Native | — | Native | Native | Native | Native | Native | — |
 | MCP Servers | — | Native | Native | Native | Native | Native | Native | Native | Native | — | Native | Native | Native | Native | Native | — | — | Native | Native | Native | Native | — | Native | — | Native | Native | Native | — | Partial | Native |
 | Hooks | — | — | — | — | — | Native | Native | — | — | — | Native | Native | — | — | Partial | — | — | — | — | — | — | — | — | — | — | — | — | — | Native | — |
 | Ignore | Native | — | — | — | — | Native | Native | — | — | — | — | Native | — | — | — | Native | — | — | Native | Native | — | — | — | — | Native | — | — | — | Native | — |
@@ -489,7 +551,7 @@ See the [full feature matrix docs](https://samplexbro.github.io/agentsmesh/refer
 - **[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`, `convert`, `install`, `uninstall`, `installs`, `refresh`, `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**
+- **[Guides](https://samplexbro.github.io/agentsmesh/guides/existing-project/)** — adopting in existing projects · **teaching agents with lessons** · 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
 
 ---

package/dist/canonical.d.ts

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