littlebearapps · Nathan Schram (nathanschram) · May 8, 2026 · May 8, 2026
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "contextdocs",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Your AI agent maintains its own context files — a Claude Code plugin with an AGENTS-first model that covers Codex, Copilot, Cursor, Gemini, and 3 more tools. Signal Gate filtering, Context Guard hooks, health scoring, and MEMORY.md promotion.",
   "author": {
     "name": "Little Bear Apps",

diff --git a/.release-please-manifest.json b/.release-please-manifest.json
@@ -1,3 +1,3 @@
 {
-  ".": "1.5.0"
+  ".": "1.6.0"
 }
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,49 +5,63 @@ All notable changes to ContextDocs will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.5.0](https://github.com/littlebearapps/contextdocs/compare/v1.4.0...v1.5.0) (2026-03-15)
+## [1.6.0](https://github.com/littlebearapps/contextdocs/compare/v1.5.0...v1.6.0) (2026-05-08)
 
+> Modernises ContextDocs for the May 2026 AI-coding-tool ecosystem. Headlines: Cursor `.cursor/rules/*.mdc` migration so projects work in Cursor's Agent mode again, Cline `.clinerules/` directory mode with path-scoped rules, opt-in six-section AGENTS.md scaffold, three new health checks (16 total), richer skill activation via `when_to_use` frontmatter, and Copilot bridge marked optional now that Copilot's coding agent loads AGENTS.md natively.
 
 ### Added
 
-* add UserPromptSubmit hook for context-related skill activation ([#15](https://github.com/littlebearapps/contextdocs/issues/15)) ([98c3106](https://github.com/littlebearapps/contextdocs/commit/98c31066185275d7267f0123678924ba8383602e))
+* **Modern Cursor support** — `ai-context` now emits `.cursor/rules/agents.mdc` with `description` / `globs` / `alwaysApply` frontmatter so projects work in Cursor's Agent mode (legacy `.cursorrules` is no longer documented upstream and is ignored in Agent mode). Legacy file is preserved when already present. ([8d72344](https://github.com/littlebearapps/contextdocs/commit/8d72344d8c6f766d95025e11297be519a77d52d5))
+* **Modern Cline directory mode** — `ai-context` now defaults to `.clinerules/agents.md` directory layout with optional `paths:` per-file frontmatter for path-scoped rules. Flat `.clinerules` is preserved when already present. ([8d72344](https://github.com/littlebearapps/contextdocs/commit/8d72344d8c6f766d95025e11297be519a77d52d5))
+* **Six-section AGENTS.md scaffold** — opt-in `--scaffold=six-section` flag for `/ai-context init` generates the GitHub Blog Apr 2026 template (commands · testing · project structure · code style · git workflow · boundaries). Default scaffold unchanged for existing users. ([8d72344](https://github.com/littlebearapps/contextdocs/commit/8d72344d8c6f766d95025e11297be519a77d52d5))
+* **3 new context-verify checks (16 total)** — modern Cursor layout (deducts 2 if only `.cursorrules`), modern Cline layout (deducts 2 if flat `.clinerules`), and Copilot bridge optionality (advisory). ([decac12](https://github.com/littlebearapps/contextdocs/commit/decac12b223b9f950f2f8bbcf71f5801fe5f9003))
+* **Hook `if:` permission-rule matchers** — Tier 2 commit guard registration now uses `if: "Bash(git commit*)"` (Claude Code v2.1.85+) so hooks fire only on actual commit commands; older Claude Code versions fall back to in-script substring guards. ([cb9f160](https://github.com/littlebearapps/contextdocs/commit/cb9f160f49a63ad1b3d1a88d61abfff7c4f311a7))
+* **Skill `when_to_use` frontmatter** — all three skills now split activation hints between `description` (key use case) and `when_to_use` (trigger phrases + skip-when negatives), matching the Claude Code v2.1.119 1,536-character combined cap for richer NL activation. ([8d72344](https://github.com/littlebearapps/contextdocs/commit/8d72344d8c6f766d95025e11297be519a77d52d5))
+* **Plugin `$schema` field** — `.claude-plugin/plugin.json` now declares `"$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json"` for editor autocomplete and `claude plugin validate` validation. Claude Code ignores this field at load time. ([0fc3324](https://github.com/littlebearapps/contextdocs/commit/0fc3324) / [05050ba](https://github.com/littlebearapps/contextdocs/commit/05050ba))
+* **Cross-platform context drift cleanup + standalone verify CLI** ([#28](https://github.com/littlebearapps/contextdocs/issues/28)) ([1527dbe](https://github.com/littlebearapps/contextdocs/commit/1527dbe974397c4652fb8f64d8052d0e9f097332))
+
+### Changed
 
+* **Copilot bridge marked optional** — Copilot's coding agent has supported AGENTS.md natively [since Aug 2025](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/); `.github/copilot-instructions.md` is only emitted when needed for tool-specific scoping. `context-verify` adds an advisory check. ([510720f](https://github.com/littlebearapps/contextdocs/commit/510720f16d61cdc8e9e06b128668afd5d488418a))
+* **`context-updater` agent pinned to haiku** for cheap surgical edits; `disallowedTools: [WebSearch, WebFetch]` made explicit. ([5c7ffb5](https://github.com/littlebearapps/contextdocs/commit/5c7ffb5))
+* **FAQ filename renamed** `docs/faq/index.md` → `docs/faq/faq.md` ([#29](https://github.com/littlebearapps/contextdocs/issues/29)) for cleaner help-centre URL `/help/contextdocs/faq/` (was `/help/contextdocs/index/`). Pure file rename — no content change. Marketing-site 301 redirect handled separately. ([0fc3324](https://github.com/littlebearapps/contextdocs/commit/0fc3324))
 
 ### Fixed
 
-* align SKILL.md and CLAUDE.md with canonical description ([bb4b750](https://github.com/littlebearapps/contextdocs/commit/bb4b750b7916359a15184aea18462e2eec76b02e))
-* Context Guard hooks false positive on infrastructure rule files ([#13](https://github.com/littlebearapps/contextdocs/issues/13)) ([ab0cd47](https://github.com/littlebearapps/contextdocs/commit/ab0cd4728bffb386d93e7742b6262a04a28115a3))
+* Context Guard hooks no longer flag infrastructure rule files as false positives ([#13](https://github.com/littlebearapps/contextdocs/issues/13))
+* `ai-context` skill triggers more reliably when you describe stale context or MEMORY.md promotion scenarios
+* `SKILL.md` and `CLAUDE.md` descriptions now match the canonical product definition across all tools
 
-## [Unreleased]
+### Verified Safe Against
 
-### Added
+This release was verified against four open Claude Code plugin issues — none affect ContextDocs:
 
-* **Modern Cursor support** — `ai-context` now emits `.cursor/rules/agents.mdc` with `description` / `globs` / `alwaysApply` frontmatter so projects work in Cursor's Agent mode (legacy `.cursorrules` is no longer documented upstream and is ignored in Agent mode). Legacy file is preserved when already present.
-* **Modern Cline directory mode** — `ai-context` now defaults to `.clinerules/agents.md` directory layout with optional `paths:` per-file frontmatter for path-scoped rules. Flat `.clinerules` is preserved when already present.
-* **Six-section AGENTS.md scaffold** — opt-in `--scaffold=six-section` flag for `/ai-context init` generates the GitHub Blog Apr 2026 template (commands · testing · project structure · code style · git workflow · boundaries). Default scaffold unchanged for existing users.
-* **3 new context-verify checks (16 total)** — modern Cursor layout (deducts 2 if only `.cursorrules`), modern Cline layout (deducts 2 if flat `.clinerules`), and Copilot bridge optionality (advisory).
-* **Hook `if:` permission-rule matchers** — Tier 2 commit guard registration now uses `if: "Bash(git commit*)"` (Claude Code v2.1.85+) so hooks fire only on actual commit commands; older Claude Code versions fall back to in-script substring guards.
-* **Skill `when_to_use` frontmatter** — all three skills now split activation hints between `description` (key use case) and `when_to_use` (trigger phrases + skip-when negatives), matching the Claude Code v2.1.119 1,536-character combined cap for richer NL activation.
-* **Plugin `$schema` field** — `.claude-plugin/plugin.json` now declares `"$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json"` for editor autocomplete and `claude plugin validate` validation. Claude Code ignores this field at load time.
+* [anthropics/claude-code#44120](https://github.com/anthropics/claude-code/issues/44120) — plugin skills not discovered when `.claude/` directory exists in plugin (caveat noted; same family as known [#32184](https://github.com/anthropics/claude-code/issues/32184) headless-mode limitation)
+* [anthropics/claude-code#46664](https://github.com/anthropics/claude-code/issues/46664) — `WorktreeCreate` hooks in plugin `hooks/hooks.json` never fire (we don't register this event)
+* [anthropics/claude-code#49990](https://github.com/anthropics/claude-code/issues/49990) — bare `{type, command}` hook entry silently breaks entire hooks config (every entry wraps `{type, command}` in a `hooks: []` array under `matcher:` or `if:` scope)
+* [anthropics/claude-code#54532](https://github.com/anthropics/claude-code/issues/54532) — SessionStart hook "ToolUseContext is required for prompt hooks" error (all hooks use `type: command`, never `type: prompt`)
 
-### Changed
+### Documentation
 
-* **Copilot bridge marked optional** in docs and skill output — Copilot's coding agent has supported AGENTS.md natively since Aug 2025; `.github/copilot-instructions.md` is only emitted when needed for tool-specific scoping. `context-verify` adds an advisory check.
-* **`context-updater` agent pinned to haiku** for cheap surgical edits; `disallowedTools: [WebSearch, WebFetch]` made explicit.
-* **FAQ filename renamed** `docs/faq/index.md` → `docs/faq/faq.md` ([#29](https://github.com/littlebearapps/contextdocs/issues/29)) for cleaner help-centre URL `/help/contextdocs/faq/` (was `/help/contextdocs/index/`). Pure file rename — no content change. Marketing-site 301 redirect handled separately.
+* Polish release notes and modernise guides for v1.6.0 — bridge file tables, check counts, version refs, FAQ entry on `.cursorrules` vs `.cursor/rules/agents.mdc` coexistence (this commit)
+* Add `docs/faq/faq.md` for help-centre FAQPage schema ([#26](https://github.com/littlebearapps/contextdocs/issues/26)) ([130e103](https://github.com/littlebearapps/contextdocs/commit/130e1035f7785fc757f6f6f0082b99b204d67a21))
+* AGENTS-first refresh for v1.6.0 + Copilot bridge marked optional ([510720f](https://github.com/littlebearapps/contextdocs/commit/510720f16d61cdc8e9e06b128668afd5d488418a))
+* Document v1.6.0 unreleased changes ([bfd03c3](https://github.com/littlebearapps/contextdocs/commit/bfd03c3883dce76896f0d6340e4010100304a780))
+* Include `$schema` in llms.txt plugin manifest entry ([05050ba](https://github.com/littlebearapps/contextdocs/commit/05050bae75107b26ccb7b034070d7ec5a10a69ae))
+* Protect synced FAQ path in AGENTS.md and CLAUDE.md ([#27](https://github.com/littlebearapps/contextdocs/issues/27)) ([d48b09c](https://github.com/littlebearapps/contextdocs/commit/d48b09cafb536a7f14d4b053f061fb79d1d65982))
 
-### Fixed
+## [1.5.0](https://github.com/littlebearapps/contextdocs/compare/v1.4.0...v1.5.0) (2026-03-15)
 
-* Context Guard hooks no longer flag infrastructure rule files as false positives ([#13](https://github.com/littlebearapps/contextdocs/issues/13))
-* ai-context skill triggers more reliably when you describe stale context or MEMORY.md promotion scenarios
-* SKILL.md and CLAUDE.md descriptions now match the canonical product definition across all tools
 
-### Verified Safe Against
+### Added
+
+* add UserPromptSubmit hook for context-related skill activation ([#15](https://github.com/littlebearapps/contextdocs/issues/15)) ([98c3106](https://github.com/littlebearapps/contextdocs/commit/98c31066185275d7267f0123678924ba8383602e))
 
-* [anthropics/claude-code#44120](https://github.com/anthropics/claude-code/issues/44120) — plugin skills not discovered when `.claude/` directory exists in plugin
-* [anthropics/claude-code#46664](https://github.com/anthropics/claude-code/issues/46664) — `WorktreeCreate` hooks in plugin `hooks/hooks.json` never fire (we don't use this event)
-* [anthropics/claude-code#49990](https://github.com/anthropics/claude-code/issues/49990) — bare `{type, command}` hook entry silently breaks entire hooks config
-* [anthropics/claude-code#54532](https://github.com/anthropics/claude-code/issues/54532) — SessionStart hook "ToolUseContext is required for prompt hooks" error
+
+### Fixed
+
+* align SKILL.md and CLAUDE.md with canonical description ([bb4b750](https://github.com/littlebearapps/contextdocs/commit/bb4b750b7916359a15184aea18462e2eec76b02e))
+* Context Guard hooks false positive on infrastructure rule files ([#13](https://github.com/littlebearapps/contextdocs/issues/13)) ([ab0cd47](https://github.com/littlebearapps/contextdocs/commit/ab0cd4728bffb386d93e7742b6262a04a28115a3))
 
 ## [1.4.0](https://github.com/littlebearapps/contextdocs/compare/v1.3.0...v1.4.0) (2026-03-13)
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -26,7 +26,7 @@ contextdocs/
 │       ├── context-guard/SKILL.md # Hook installation
 │       └── context-verify/SKILL.md # Health scoring
 ├── commands/                      # Slash commands
-├── hooks/                         # 6 opt-in shell scripts (Claude Code only)
+├── hooks/                         # 7 opt-in shell scripts (Claude Code only)
 └── upstream-versions.json         # Pinned AGENTS.md spec + Claude Code release versions
 ```
 

diff --git a/README.md b/README.md
@@ -11,7 +11,7 @@
 </p>
 
 <p align="center">
-  <a href="CHANGELOG.md"><img src="https://img.shields.io/static/v1?label=version&message=1.5.0&color=blue" alt="Version" /></a> <!-- x-release-please-version -->
+  <a href="CHANGELOG.md"><img src="https://img.shields.io/static/v1?label=version&message=1.6.0&color=blue" alt="Version" /></a> <!-- x-release-please-version -->
   <a href="LICENSE"><img src="https://img.shields.io/github/license/littlebearapps/contextdocs" alt="License" /></a>
   <a href="https://code.claude.com/docs/en/plugins"><img src="https://img.shields.io/badge/Claude_Code-Plugin-D97757?logo=claude&logoColor=white" alt="Claude Code Plugin" /></a>
   <a href="https://opencode.ai/"><img src="https://img.shields.io/badge/OpenCode-Compatible-22c55e" alt="OpenCode Compatible" /></a>
@@ -69,13 +69,13 @@ ContextDocs solves the full lifecycle. It scans your codebase, generates `AGENTS
 
 **For Claude Code users:** Claude Code auto-loads `CLAUDE.md` every session. The generated `CLAUDE.md` starts with `@AGENTS.md`, which imports the canonical shared context directly — so you get the full conventions plus Claude-specific additions without duplication. Other tools (Codex CLI, Gemini CLI, Copilot, Cursor) load their own bridge files or `AGENTS.md` directly.
 
-Then it keeps them fresh: `update` patches drift incrementally, `promote` moves Claude's auto-learned MEMORY.md patterns into CLAUDE.md, `context-verify` scores health 0–100 across 6 dimensions with 13 checks, and Context Guard hooks enforce freshness at session start, session end, and commit time — with the context-updater agent applying fixes automatically.
+Then it keeps them fresh: `update` patches drift incrementally, `promote` moves Claude's auto-learned MEMORY.md patterns into CLAUDE.md, `context-verify` scores health 0–100 across 6 dimensions with 16 checks, and Context Guard hooks enforce freshness at session start, session end, and commit time — with the context-updater agent applying fixes automatically.
 
 ---
 
 ## 🎯 Features
 
-ContextDocs generates AGENTS-first context for 8 AI coding tools from a single codebase scan, applies Signal Gate filtering to strip discoverable content, enforces line budgets (AGENTS.md <120, CLAUDE.md <80, other bridges <60), and scores health 0–100 across 6 dimensions with 13 verification checks. Context Guard hooks catch drift at session start, session end, and commit time.
+ContextDocs generates AGENTS-first context for 8 AI coding tools from a single codebase scan, applies Signal Gate filtering to strip discoverable content, enforces line budgets (AGENTS.md <120, CLAUDE.md <80, other bridges <60), and scores health 0–100 across 6 dimensions with 16 verification checks (including modern Cursor `.cursor/rules/*.mdc` and Cline `.clinerules/` directory layouts). Context Guard hooks catch drift at session start, session end, and commit time.
 
 - 🧠 **Signal Gate filtering** — strips out discoverable content (directory listings, file trees, architecture overviews) so your context files contain only what actually helps AI tools, keeping them lean and under budget
 - 📋 **AGENTS-first generation + thin bridges** — shared conventions live once in `AGENTS.md`, while `CLAUDE.md`, `.cursor/rules/*.mdc`, `.clinerules/`, optional Copilot instructions, and compatibility bridges stay minimal and tool-specific

diff --git a/SKILL.md b/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: contextdocs
 description: Your AI agent maintains its own context files — a Claude Code plugin with an AGENTS-first model that covers Codex, Copilot, Cursor, Gemini, and 3 more tools. Signal Gate filtering, Context Guard hooks, health scoring, and MEMORY.md promotion.
-version: "1.5.0" # x-release-please-version
+version: "1.6.0" # x-release-please-version
 author: Little Bear Apps
 tags:
   - ai-context

diff --git a/docs/faq/faq.md b/docs/faq/faq.md
@@ -11,7 +11,7 @@ description: "Common questions about ContextDocs: installation, supported AI too
 
 ## What is ContextDocs and why should I use it?
 
-ContextDocs is a Claude Code plugin that generates and maintains AI context files for your project — `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, `.github/copilot-instructions.md`, `.windsurfrules`, `.clinerules`, and `GEMINI.md` — from a single codebase scan. It applies the **Signal Gate principle** so the files only contain what AI agents cannot already discover by reading source code on their own.
+ContextDocs is a Claude Code plugin that generates and maintains AI context files for your project — `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/agents.mdc` (modern Cursor with frontmatter), `.clinerules/agents.md` (modern Cline directory mode), `.windsurfrules`, `GEMINI.md`, and an optional `.github/copilot-instructions.md` (Copilot loads AGENTS.md natively since Aug 2025) — from a single codebase scan. Legacy formats (`.cursorrules`, flat `.clinerules`) are preserved only when a project already uses them. It applies the **Signal Gate principle** so the files only contain what AI agents cannot already discover by reading source code on their own.
 
 The motivation is concrete: research from ETH Zurich (2026) shows that bloated context files reduce AI task success by roughly 3% and increase token costs by around 20%. Most teams either write too much, write the wrong things, or let context files go stale within a week. ContextDocs covers the full lifecycle — generation, drift patching, MEMORY.md promotion, freshness hooks, and 0–100 health scoring — so the files stay lean and accurate as your project evolves.