@softspark/ai-toolkit 4.10.1 → 4.11.0

package/AGENTS.md

@@ -653,3 +653,138 @@ Default response mode is **concise**. The `brand-voice` skill (when present) aut
 * Cite as `path:line` — instead of paragraphs describing where things live.
 * Escalate to verbose only for: architecture / RFC / ADR / trade-off documents, or when the user asks for detail.
 <!-- TOOLKIT:ai-toolkit END -->
+
+<!-- TOOLKIT:jira-mcp START -->
+<!-- Auto-injected by ai-toolkit. Re-run to update. -->
+
+# Jira MCP Server
+
+Tools: `sync_tasks`, `read_cached_tasks`, `update_task_status`, `update_task`, `add_task_comment`, `delete_task`, `delete_comment`, `reassign_task`, `get_task_statuses`, `get_task_details`, `get_project_language`, `log_task_time`, `get_task_time_tracking`, `list_comment_templates`, `add_templated_comment`, `list_task_templates`, `create_task`, `create_monthly_tasks`, `search_tasks`
+
+## Key Rules
+
+- **Always `sync_tasks` first** before reading, because the cache may be stale.
+- **Language first:** before writing ANY comment, description, or task content, call `get_project_language(project_key)` or check the `language` field in `get_task_details` response. Write ALL content in the project's configured language. Never assume Polish or English. Always check first.
+- **Time format:** `"2h 30m"`, using hours and minutes only, never days.
+- **Status changes:** call `get_task_statuses` first to check valid transitions.
+- **Multi-instance:** project key determines which Jira instance is used (mapped in config.json).
+- **Comments are ADF:** `add_task_comment` converts markdown to ADF (Atlassian Document Format) automatically.
+- **Delete guard:** `delete_task` is allowed only for the task creator, and `delete_comment` is allowed only for the comment author. Both require explicit `user_approved=true`.
+- **Templates:** use `list_comment_templates` to discover available templates, then `add_templated_comment` with `template_id` + `variables`.
+
+## Writing Style
+
+- **Write like a real team member:** use plain, direct language that sounds like an engineer writing to another human, not like polished AI copy or marketing text.
+- **No em dash and no double-hyphen separator in prose:** do not use those punctuation patterns in generated comments, descriptions, docs, or summaries. Use commas, periods, or parentheses instead.
+- **Avoid stock AI phrases:** do not use phrases like "worth noting", "it is important to understand", "in today's dynamic environment", "overall", "in conclusion", or similar generic filler.
+- **Prefer concrete wording:** use specific facts, actions, examples, and decisions instead of abstract claims or padded qualifiers.
+- **Avoid repetitive rhythm:** do not make every sentence or bullet sound structurally identical. Vary sentence length and openings when writing longer text.
+- **Keep summaries short:** do not add forced wrap-up paragraphs unless the user explicitly asks for a summary.
+- **Use a workmanlike tone:** prefer a slightly rough, practical style over text that sounds overly smooth, symmetrical, or "LLM-clean".
+
+## Workflow
+
+1. `sync_tasks(jql="assignee=currentUser() AND status!=Done")` to fetch fresh data
+2. `read_cached_tasks()` to work offline
+3. `get_task_details(task_key="PROJ-123")` for a deep dive into description and comments as markdown
+4. `update_task_status(...)` / `add_task_comment(...)` / `log_task_time(...)` to mutate data
+
+## Comment Templates (built-in)
+
+| ID | Use for |
+|----|---------|
+| `status-update` | Progress report with completed/next/blockers |
+| `blocker-notification` | Escalate blocking issue |
+| `handoff-transition` | Task handoff between people |
+| `review-request` | Request code review |
+| `sprint-update` | Sprint progress report |
+| `bug-report` | Structured bug report |
+| `deployment-note` | Deployment documentation |
+| `time-log-summary` | Time logging with description |
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `jira-mcp` | Start MCP server (default) |
+| `jira-mcp serve` | Start MCP server (explicit) |
+| `jira-mcp create <path>` | Create tasks from config file (dry-run by default) |
+| `jira-mcp create-monthly` | Create monthly admin tasks from built-in templates |
+| `jira-mcp template add <type> <path>` | Install a template override from a local markdown file |
+| `jira-mcp template list [type]` | List active comment/task templates |
+| `jira-mcp template show <type> <id>` | Show the active template file content |
+| `jira-mcp template remove <type> <id>` | Remove a user-installed template override |
+| `jira-mcp config init` | Initialize global config (~/.softspark/jira-mcp/) |
+| `jira-mcp config add-project <key> <url>` | Add Jira project mapping |
+| `jira-mcp config remove-project <key>` | Remove a project |
+| `jira-mcp config list-projects` | Show configured projects with language |
+| `jira-mcp config set-credentials` | Set API credentials |
+| `jira-mcp config set-default <key>` | Set default project |
+| `jira-mcp config set-language <lang>` | Set global default language |
+| `jira-mcp config set-project-language <key> <lang>` | Set language for a specific project |
+| `jira-mcp cache sync-workflows` | Cache status transitions |
+| `jira-mcp cache sync-users` | Cache user list for reassignment |
+| `jira-mcp cache list-workflows` | Show cached workflows |
+| `jira-mcp cache list-users` | Show cached users |
+
+## Architecture
+
+Four layers. Each depends only on layers below.
+
+1. **Types & Config** (`config/`, `errors/`, `*/types.ts`), pure data with zero runtime deps
+2. **Infrastructure** (`connector/`, `cache/`, `adf/`, `templates/`), I/O and external APIs
+3. **Business Logic** (`operations/`, `bulk/`), orchestrating infrastructure
+4. **Entry Points** (`tools/`, `cli/`, `server.ts`), thin dispatchers
+
+## Coding Conventions
+
+- **Strict TypeScript**: `strict: true`, NO `any`, `readonly` interfaces, `import type`, `.js` imports
+- **Zod schemas** for all external data: `type Foo = z.infer<typeof FooSchema>`
+- **Error classes**: extend `JiraMcpError` with `code` property
+- **ADF round-trip**: `markdownToAdf()` for writes and `adfToMarkdown()` for reads. NEVER throw.
+- **InstancePool**: singleton, lazy connectors, dedup by URL
+- **Dual-write**: after Jira mutation, update local cache, return API result
+- **Dry-run default**: `--execute` required for destructive operations
+- **DI pattern**: handlers accept `deps?` parameter for testing
+- **Config path**: ALWAYS `~/.softspark/jira-mcp/` via `GLOBAL_CONFIG_DIR`, with no manual config and no env vars in MCP client setup
+- **SoftSpark standard**: all open-source tools use `~/.softspark/<tool-name>/`. See SOP in rag-mcp `kb/procedures/softspark-config-standard.md`
+
+## Testing
+
+- **Vitest**: 70% coverage threshold, `vi.fn()` for mocks
+- **No real Jira API calls** in tests, use `tests/fixtures/mocks.ts`
+- **Filesystem tests**: `os.tmpdir()` + `mkdtemp()`, NEVER write to `~/.softspark/`
+- Quick pre-commit: `npm run typecheck && npm run lint && npm test && npm run build`
+
+## KB & SOPs
+
+- `kb/reference/` for architecture, API, configuration, ADF, caching, and templates
+- `kb/howto/` for setup, multi-instance usage, and CLI usage
+- `kb/procedures/` for `sop-pre-commit`, `sop-release`, and `sop-post-release-testing`
+
+<!-- TOOLKIT:jira-mcp END -->
+
+<!-- TOOLKIT:rag-mcp-rules START -->
+<!-- Auto-injected by ai-toolkit. Re-run to update. -->
+
+## INSTANT ACTION RULE (GOLDEN RULE)
+
+**ANY technical question? -> INSTANTLY call `smart_query()` OR `hybrid_search_kb()` BEFORE outputting text!**
+
+1. **Search First:** `smart_query()` or `hybrid_search_kb()` (NEVER skip, even if you "know").
+2. **Cite Sources:** always include `[PATH: kb/...]`.
+3. **Strict Order:** Semantic Search -> Files -> External Docs -> General Knowledge.
+
+Default tool: `smart_query()`. Use `hybrid_search_kb()` for speed, `crag_search()` for vague queries, `multi_hop_search()` for complex reasoning.
+
+## kb_id vs file_path
+
+- `get_document(path=...)` takes `kb_id` from search results (e.g., `local/softspark/project/reference/api.md`)
+- `Read`/`Edit` take filesystem `file_path` (e.g., `./reference/api.md`)
+- **DO NOT CONFUSE** these fields.
+
+## SOPs
+
+ALWAYS check `kb/procedures/` first: `smart_query("SOP for <task>")`.
+
+<!-- TOOLKIT:rag-mcp-rules END -->

package/CHANGELOG.md

@@ -7,6 +7,20 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.11.0 — Claude rules-space fix + editor registry parity (2026-06-30)
+
+Minor release. Reduces Claude Code startup context pressure by moving ai-toolkit rules out of global/project `CLAUDE.md` inline blocks and into Claude Code rule files. Also finishes the editor registry sync by recording all Gemini generators in the canonical ecosystem registry. Test count: 1198 → 1203.
+
+### Changed
+- **Claude Code global rules now use `~/.claude/rules/ai-toolkit-*.md`.** `ai-toolkit install/update` writes toolkit rules from `app/rules/*.md` and registered rules from `~/.softspark/ai-toolkit/rules/*.md` into Claude Code user-level rule files, keeps `~/.claude/CLAUDE.md` as a compact index, and removes legacy inline rule markers during migration. The `ai-toolkit-*` prefix is installer-managed.
+- **Claude Code common rules now use `.claude/rules/ai-toolkit-*.md`.** `install --local` writes `ai-toolkit-coding-style.md`, `ai-toolkit-git-workflow.md`, `ai-toolkit-performance.md`, `ai-toolkit-security.md`, and `ai-toolkit-testing.md` under `.claude/rules/` with `paths: ["**/*"]` frontmatter, while `.claude/CLAUDE.md` stays a compact index. This follows Claude Code's current guidance to keep `CLAUDE.md` concise and move larger instruction sets into scoped rules.
+- **Language rules reference updated.** `kb/reference/language-rules.md` now documents the Claude-specific split: common rules as project-local Claude rules, per-language rules as knowledge skills, and other editors still receiving native rule files from their generators.
+- **Ecosystem registry reflects Gemini native surfaces.** `scripts/ecosystem_tools.json` now includes `generate_gemini_hooks.py`, `generate_gemini_commands.py`, and `generate_gemini_skills.py` alongside `generate_gemini.py`, matching the installer and supported-tools registry.
+- **Ecosystem doctor baseline refreshed.** Snapshot updated after class A/C upstream documentation drift review; no additional generator contract changes were required.
+
+### Fixed
+- **Claude rules-space regression.** Global Claude installs no longer inline toolkit/registered rules into `~/.claude/CLAUDE.md`, and project-local Claude installs no longer inflate `.claude/CLAUDE.md` with the full common-rule corpus. Regression tests now assert compact CLAUDE.md indexes, generated rule files, legacy marker cleanup, and managed `.claude/rules/ai-toolkit-*.md` refresh behavior.
+
 ## v4.10.1 — Copilot AGENTS.md install + Claude KB-first rule (2026-06-23)
 
 Patch release. Fixes two governance regressions found in the editor-update audit: Copilot installs now emit the root `AGENTS.md` surface documented in the registry, and Claude Code receives the KB-first rule in `CLAUDE.md`, which it actually reads. Test count: 1195 → 1198.

package/README.md

@@ -6,18 +6,17 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-108-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-1198%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-1203%20passing-success)](tests/)
 
-## What's New in v4.10.1
+## What's New in v4.11.0
 
-v4.10.1 fixes editor-governance gaps found in the release audit.
+v4.11.0 reduces Claude Code startup/global rule pressure and refreshes the editor registry.
 
-- **Copilot local installs now emit root `AGENTS.md`**: `ai-toolkit install --local --editors copilot` writes the generated agent catalog into a `TOOLKIT:copilot-agents` section while preserving existing Codex/opencode sections and user text.
-- **Claude Code KB-first enforcement restored**: `CLAUDE.md` now carries the mandatory `smart_query()` / `hybrid_search_kb()` rule before technical/project answers, instead of relying on generated `AGENTS.md`.
-- **Codex PostToolUse hook output fixed**: `loop-guard.sh` no longer forces Claude-style JSON with `suppressOutput` under quiet Codex hooks.
-- **Release packaging hardened**: local `.claude` session artifacts under `app/` are excluded from `npm pack`, even if they exist in a maintainer checkout.
-- **Docs and ecosystem baseline refreshed**: README, registry, and architecture docs now match the Copilot implementation; ecosystem-doctor snapshot is refreshed for upstream Claude/Gemini docs hash drift.
-- **Test count**: 1195 → 1198.
+- **Claude rules-space fix**: global `ai-toolkit install/update` now writes toolkit and registered rules to `~/.claude/rules/ai-toolkit-*.md`, while `install --local` writes common project rules to `.claude/rules/ai-toolkit-*.md` with Claude Code `paths` frontmatter.
+- **Language/global rules docs refreshed**: the KB now documents the split between Claude global user rules, project rules, language-rule skills, and other editors' native rule files.
+- **Gemini registry parity restored**: `scripts/ecosystem_tools.json` now lists the Gemini hooks, commands, and skills generators already used by installer profiles.
+- **Ecosystem snapshot refreshed**: the doctor baseline is updated after class A/C upstream documentation drift review.
+- **Test count**: 1198 → 1203.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -102,7 +101,7 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 
 | Platform | Config Files | Hooks | Scope |
 |----------|-------------|:-----:|-------|
-| Claude Code | `~/.claude/` | ✅ | global |
+| Claude Code | `~/.claude/agents`, `~/.claude/skills`, `~/.claude/rules/*.md`, `~/.claude/settings.json` | ✅ | global |
 | Cursor | `.cursor/rules/*.mdc` + `.cursor/mcp.json` + `.cursor/skills/*` | ✅ | project (`~/.cursor/mcp.json` for MCP only) |
 | Windsurf (Devin Desktop) | `~/.codeium/.../global_rules.md` + `~/.codeium/windsurf/skills/*` + `.devin/rules/*.md` + `.windsurf/rules/*.md` (legacy) | ✅ | global + project |
 | Gemini CLI | `~/.gemini/GEMINI.md` | ✅ | global |
@@ -130,7 +129,7 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 | `hooks/` | 29 entries / 14 events | Quality gates, path safety, prompt governance, loop guard, session lifecycle |
 | `plugins/` | 11 packs | Opt-in domain bundles (security, research, frontend, enterprise, 6 language packs) |
 | `constitution.md` | 7 articles | Machine-enforced safety rules |
-| `rules/` | auto-injected | Language-specific and custom rules injected into your configs |
+| `rules/` | auto-synced | Global/project rule files for Claude and other editors |
 | `kb/` | reference docs | Architecture, procedures, and best practices |
 
 ---
@@ -142,7 +141,7 @@ ai-toolkit/
 ├── app/
 │   ├── agents/          # 44 agent definitions
 │   ├── skills/          # 108 skills (task / hybrid / knowledge)
-│   ├── rules/           # Auto-injected into your CLAUDE.md
+│   ├── rules/           # Source rules synced into Claude/editor rule files
 │   ├── hooks/           # Hook scripts (29 entries, 14 lifecycle events)
 │   ├── plugins/         # 11 experimental plugin packs (opt-in)
 │   ├── output-styles/   # System prompt output style overrides
@@ -150,7 +149,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats test suite (1198 tests)
+├── tests/               # Bats test suite (1203 tests)
 └── CHANGELOG.md
 ```
 

package/app/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-toolkit",
   "description": "Professional-grade Claude Code toolkit with persona presets, skill security auditor, expanded lifecycle hooks, experimental opt-in plugin packs, benchmark harvesting, and multi-tool support.",
-  "version": "4.10.1",
+  "version": "4.11.0",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/benchmarks/ecosystem-doctor-snapshot.json

@@ -1,5 +1,5 @@
 {
-  "last_run": "2026-06-23T07:06:46Z",
+  "last_run": "2026-06-30T16:52:43Z",
   "schema_version": 1,
   "tools": {
     "aider": {
@@ -24,7 +24,7 @@
       }
     },
     "augment": {
-      "docs_hash": "a0c51061febc16c4",
+      "docs_hash": "1140b2d05814d7fd",
       "headings": [
         "Admin",
         "Auggie CLI",
@@ -66,7 +66,7 @@
       }
     },
     "claude-code": {
-      "docs_hash": "c20e5688ed230a66",
+      "docs_hash": "3101b3cd58375aec",
       "headings": [
         "Core concepts",
         "Documentation Index",
@@ -122,15 +122,18 @@
         "slash command": true,
         "sub-agent": true
       },
-      "version": "2.1.186 (Claude Code)"
+      "version": "2.1.196 (Claude Code)"
     },
     "cline": {
-      "docs_hash": "858fa542e2aacde5",
+      "docs_hash": "a934200d22b48f17",
       "headings": [
         "API Reference",
         "Best Practices",
+        "Bring Your Own Key",
         "CLI",
+        "Cline (usage-billing)",
         "Cline Overview",
+        "ClinePass",
         "Configurations",
         "Documentation Index",
         "Features",
@@ -149,6 +152,7 @@
         "\u200bAgent Core (SDK)",
         "\u200bApplications",
         "\u200bEnterprise Solutions",
+        "\u200bModel access",
         "\u200bOther IDE Supports",
         "\u200bWhat is Cline?"
       ],
@@ -168,7 +172,7 @@
       }
     },
     "codex-cli": {
-      "docs_hash": "eeb0e17a839b09bd",
+      "docs_hash": "36f437b3356b4706",
       "headings": [
         "API",
         "API Reference",
@@ -208,6 +212,7 @@
         "Resources",
         "Run and scale",
         "Search the Codex docs",
+        "Spaces",
         "Specialized models",
         "Suggested",
         "Tools",
@@ -238,7 +243,7 @@
       "version": "codex-cli 0.142.0"
     },
     "cursor": {
-      "docs_hash": "86b6d48e8ab40d90",
+      "docs_hash": "d8aed06363805889",
       "headings": [],
       "markers": {
         ".cursor/rules": false,
@@ -254,7 +259,7 @@
       }
     },
     "gemini-cli": {
-      "docs_hash": "c3ba6d09d810f9c3",
+      "docs_hash": "85e8f47e8ef0acda",
       "headings": [
         "Breadcrumbs",
         "Directory actions",
@@ -269,6 +274,7 @@
         "Provide feedback",
         "Saved searches",
         "Search code, repositories, users, issues, pull requests...",
+        "Uh oh!",
         "Use saved searches to filter your results more quickly",
         "docs",
         "parent directory"
@@ -296,7 +302,7 @@
       }
     },
     "github-copilot": {
-      "docs_hash": "df7c22e121dbb3d1",
+      "docs_hash": "df772638c69033d7",
       "headings": [
         "About Copilot auto model selection",
         "About Copilot automations",
@@ -330,7 +336,7 @@
       }
     },
     "google-antigravity": {
-      "docs_hash": "e6c90b9d937dd9f0",
+      "docs_hash": "4d2e384b2c2add18",
       "headings": [],
       "markers": {
         "AGENTS.md": false,
@@ -347,7 +353,7 @@
       }
     },
     "opencode": {
-      "docs_hash": "302de3ac69940747",
+      "docs_hash": "791633f4156abbe8",
       "headings": [
         "Add features",
         "Ask questions",
@@ -407,7 +413,7 @@
       }
     },
     "windsurf": {
-      "docs_hash": "cdd657d4d684c68a",
+      "docs_hash": "bb6e6119f2c068d6",
       "headings": [
         "Accounts",
         "Advanced",

package/bin/ai-toolkit.js

@@ -66,7 +66,7 @@ const COMMANDS = {
   reset: 'Wipe and recreate project-local configs from scratch (requires --local)',
   uninstall: 'Remove ai-toolkit from ~/.claude/',
   'add-rule': 'Register a rule file or URL in ~/.softspark/ai-toolkit/rules/ (URL rules auto-refresh on update)',
-  'remove-rule': 'Unregister a rule from ~/.softspark/ai-toolkit/rules/ and remove its block from CLAUDE.md',
+  'remove-rule': 'Unregister a rule and remove its generated Claude rule file',
   'inject-hook': 'Inject external hooks (file or URL) into ~/.claude/settings.json (URL hooks auto-refresh on update)',
   'remove-hook': 'Remove injected hooks by source name from ~/.claude/settings.json (also unregisters URL source)',
   'inject-mcp': 'Inject external MCP template (file or URL) into ~/.mcp.json + all editor MCP configs (URL templates auto-refresh on update)',

package/kb/procedures/maintenance-sop.md

@@ -87,7 +87,8 @@ What `install` and `update` do (merge-friendly — user content never overwritte
 | `settings.json` hooks | JSON merge via `merge-hooks.py` | User hooks + settings preserved, toolkit entries tagged `_source: ai-toolkit` |
 | `constitution.md` | Marker injection via `inject_section_cli.py` | User content outside `<!-- TOOLKIT:* -->` markers untouched |
 | `ARCHITECTURE.md` | Marker injection via `inject_section_cli.py` | Same as above |
-| `CLAUDE.md` | Marker injection of `app/rules/*.md` via `inject_rule_cli.py` | User content outside markers untouched |
+| `CLAUDE.md` | Compact index for managed global rules | User content outside toolkit markers untouched |
+| `rules/ai-toolkit-*.md` | File-based Claude Code user-level rules from `app/rules/*.md` and registered rules | `ai-toolkit-*` prefix reserved for installer-managed files |
 
 Re-running updates only toolkit content. Old whole-directory symlinks are auto-upgraded to per-file on next run.
 
@@ -135,7 +136,7 @@ ai-toolkit add-rule ./my-project-rules.md
 # → copies to ~/.softspark/ai-toolkit/rules/my-project-rules.md
 
 ai-toolkit update
-# → injects the rule into ~/.claude/CLAUDE.md and all global editor configs
+# → syncs the rule into ~/.claude/rules/ai-toolkit-registered-*.md and all global editor configs
 
 ai-toolkit update --local
 # → also propagates as ai-toolkit-custom-<name> to directory-based editors (Cursor, Windsurf, Cline, Roo, Augment, Antigravity)
@@ -430,5 +431,6 @@ What `uninstall` does:
 - Removes per-directory skill symlinks (user skills preserved)
 - Strips toolkit hook entries from `settings.json` (user hooks + settings preserved)
 - Strips toolkit markers from `constitution.md` and `ARCHITECTURE.md` (user content preserved; empty files removed)
-- `~/.claude/CLAUDE.md` preserved (contains your custom rules + toolkit rule markers)
+- `~/.claude/CLAUDE.md` preserved (contains your custom content + compact toolkit index)
+- `~/.claude/rules/` preserved unless explicitly removed
 - Empty `agents/` and `skills/` directories cleaned up

package/kb/reference/architecture-overview.md

@@ -32,7 +32,7 @@ ai-toolkit/
   app/                       # All toolkit components
     agents/                  # Agent definitions (.md + YAML frontmatter)
     skills/                  # skills: task, hybrid, knowledge
-    rules/                   # Rules auto-injected into ~/.claude/CLAUDE.md
+    rules/                   # Source rules synced into Claude/editor rule files
     hooks/                   # Hook scripts (copied to ~/.softspark/ai-toolkit/hooks/)
     hooks.json               # Hook definitions (merged into ~/.claude/settings.json)
     constitution.md          # Immutable safety rules, 7 articles (marker-injected)
@@ -85,8 +85,9 @@ Machine (global)                              Project (local)
   skills/*/      → per-dir symlinks              hooks/     ← hook scripts (copied)
   settings.json  ← hooks merged here
   constitution.md ← marker injection            my-project/
-  ARCHITECTURE.md ← marker injection              CLAUDE.md            ← project rules
-  CLAUDE.md       ← marker injection (rules)      .claude/
+  ARCHITECTURE.md ← marker injection              CLAUDE.md            ← project index
+  CLAUDE.md       ← compact rule index            .claude/
+  rules/*.md      ← Claude user-level rules
                                                     settings.local.json  ← MCP, perms
                                                     constitution.md     ← marker injection
 ```
@@ -123,7 +124,7 @@ If a project already has `.mcp.json`, local install mirrors its `mcpServers` ent
 | `update --local` | `./` | Re-apply + refresh project-local configs |
 | `uninstall` | `~/.claude/` | Strips toolkit components (preserves user content) |
 | `add-rule <file>` | `~/.softspark/ai-toolkit/rules/` | Register rule — auto-applied on every `update` |
-| `remove-rule <name>` | `~/.softspark/ai-toolkit/rules/` + `~/.claude/CLAUDE.md` | Unregister rule and remove its block |
+| `remove-rule <name>` | `~/.softspark/ai-toolkit/rules/` + `~/.claude/rules/` | Unregister rule and remove generated Claude rule file |
 | `mcp add <name...>` | `./.mcp.json` | Merge canonical MCP template(s) into project config |
 | `mcp install --editor <name...>` | native editor config | Render MCP template(s) into editor-native config files |
 | `validate` | toolkit | Integrity check |

package/kb/reference/extension-api.md

@@ -21,19 +21,19 @@ This design is intentional: ai-toolkit is a generic toolkit. Consumers (MCP serv
 
 | Command | Target File | Mechanism | Idempotent |
 |---------|-------------|-----------|------------|
-| `inject-rule <file.md>` | `~/.claude/CLAUDE.md` | HTML comment markers (`<!-- TOOLKIT:name -->`) | Yes |
-| `remove-rule <name>` | `~/.claude/CLAUDE.md` | Strip markers by block name | Yes |
+| `inject-rule <file.md>` | `~/.claude/CLAUDE.md` | Legacy HTML comment markers (`<!-- TOOLKIT:name -->`) | Yes |
+| `remove-rule <name>` | `~/.softspark/ai-toolkit/rules/` + `~/.claude/rules/` | Unregister and remove generated Claude rule file | Yes |
 | `inject-hook <file.json\|url> [name]` | `~/.claude/settings.json` | JSON `_source` tag per entry, URL cached + registered | Yes |
 | `remove-hook <name>` | `~/.claude/settings.json` | Strip all entries with matching `_source`, unregister URL source | Yes |
 | `inject-mcp <file.json\|url> [name] [--force]` | `~/.mcp.json` + every editor with `global_path` | JSON `_source` tag per server, URL cached + registered, full editor propagation | Yes |
 | `remove-mcp <name>` | `~/.mcp.json` + every editor with `global_path` | Strip all servers with matching `_source`, clean editor configs, unregister URL | Yes |
-| `add-rule <file.md\|url>` | `~/.softspark/ai-toolkit/rules/` | File copy + re-inject all rules on next `update` | Yes |
+| `add-rule <file.md\|url>` | `~/.softspark/ai-toolkit/rules/` | File copy + sync to `~/.claude/rules/ai-toolkit-registered-*.md` on next `update` | Yes |
 | `mcp add <name...>` | `.mcp.json` | Merge `mcpServers` block from built-in template | Yes |
 | `mcp install --editor <name...>` | Native editor MCP config | Render canonical template into editor format | Yes |
 
 ## inject-rule
 
-Injects a Markdown rules file into `~/.claude/CLAUDE.md` between named HTML comment markers.
+Legacy direct injection: injects a Markdown rules file into `~/.claude/CLAUDE.md` between named HTML comment markers. Prefer `add-rule` for persistent global rules; `ai-toolkit update` syncs those into Claude Code user-level rule files under `~/.claude/rules/`.
 
 ```bash
 npx @softspark/ai-toolkit inject-rule ./my-tool-rules.md
@@ -52,7 +52,7 @@ The block name is derived from the file stem (`my-tool-rules.md` → `my-tool-ru
 
 ## remove-rule
 
-Strips a previously injected rule block from `~/.claude/CLAUDE.md`.
+Unregisters a persistent rule, removes `~/.claude/rules/ai-toolkit-registered-<name>.md`, and strips any legacy injected rule block from `~/.claude/CLAUDE.md`.
 
 ```bash
 npx @softspark/ai-toolkit remove-rule my-tool-rules

package/kb/reference/global-install-model.md

@@ -3,9 +3,9 @@ title: "Global Install Model"
 category: reference
 service: ai-toolkit
 tags: [install, global, claude, codex, plugins, local-setup]
-version: "3.0.1"
+version: "3.1.0"
 created: "2026-03-26"
-last_updated: "2026-04-28"
+last_updated: "2026-06-30"
 description: "Reference description of the global install target, project-local editor setup, global Codex plugin layering, and command responsibilities in ai-toolkit."
 ---
 
@@ -15,7 +15,7 @@ description: "Reference description of the global install target, project-local
 
 `ai-toolkit` installs globally into `~/.claude/` by default.
 
-That means one machine-level install provides agents, skills, hooks, and rules to every project without committing toolkit boilerplate into each repository.
+That means one machine-level install provides agents, skills, hooks, constitution, and rule files to every project without committing toolkit boilerplate into each repository.
 
 Other editor targets are opt-in and only use documented file surfaces. Cursor
 rules stay project-local because Cursor's global user rules are managed through
@@ -57,6 +57,19 @@ The `--profile` flag controls how much of each editor's native surface is activa
 
 ## Global Editor Targets
 
+Claude Code's default global install writes these managed surfaces:
+
+- `~/.claude/agents/*.md` — per-file symlinks to toolkit agents.
+- `~/.claude/skills/*/` — per-directory symlinks to toolkit skills.
+- `~/.claude/settings.json` — merged hook configuration and global settings.
+- `~/.claude/constitution.md` — marker-injected safety constitution.
+- `~/.claude/ARCHITECTURE.md` — marker-injected architecture reference.
+- `~/.claude/rules/ai-toolkit-*.md` — toolkit rules from `app/rules/*.md`.
+- `~/.claude/rules/ai-toolkit-registered-*.md` — rules registered with `ai-toolkit add-rule`.
+- `~/.claude/CLAUDE.md` — compact index pointing at the managed rule files.
+
+The `ai-toolkit-*` prefix in `~/.claude/rules/` is reserved for installer-managed files. User-authored Claude rules should use another filename prefix, or be registered through `ai-toolkit add-rule` so they are emitted as `ai-toolkit-registered-*.md`.
+
 `ai-toolkit install --editors <name>` can write global files only for editors
 with documented, file-based config surfaces:
 
@@ -103,6 +116,8 @@ These files still stay local to a repository as part of the core install model:
 - `.git/hooks/pre-commit` (fallback)
 - project-specific documentation or safety overlays
 
+Project-local Claude Code language rules live in `.claude/rules/ai-toolkit-*.md` with `paths` frontmatter. They are separate from the global user-level `~/.claude/rules/ai-toolkit-*.md` files above.
+
 Hooks do **not** live in project-local settings. They are merged only into global `~/.claude/settings.json`.
 
 Codex is the exception in terms of file location, not hook ownership: its local

package/kb/reference/integrations.md

@@ -3,15 +3,15 @@ title: "AI Toolkit - External Integrations"
 category: reference
 service: ai-toolkit
 tags: [integrations, rules, add-rule]
-version: "1.0.5"
+version: "1.1.0"
 created: "2026-03-26"
-last_updated: "2026-03-26"
-description: "How external repos inject rules into ~/.claude/CLAUDE.md via ai-toolkit"
+last_updated: "2026-06-30"
+description: "How external repos register rules that ai-toolkit syncs into Claude Code user-level rules and other editor configs."
 ---
 
 # External Integrations
 
-Repos that register rules with ai-toolkit so they are automatically injected into `~/.claude/CLAUDE.md` on every `update`.
+Repos that register rules with ai-toolkit so they are automatically synced into Claude Code user-level rules and other editor configs on every `update`.
 
 ---
 
@@ -25,9 +25,11 @@ ai-toolkit add-rule ./jira-rules.md
 ai-toolkit update   # inject now
 ```
 
-After registration, `ai-toolkit update` will always re-inject the rule. Registry location: `~/.softspark/ai-toolkit/rules/`.
+After registration, `ai-toolkit update` will always re-sync the rule. Registry location: `~/.softspark/ai-toolkit/rules/`.
 
-To unregister a rule (removes from `~/.softspark/ai-toolkit/rules/` and strips the block from `CLAUDE.md`):
+For Claude Code, registered rules are written to `~/.claude/rules/ai-toolkit-registered-<name>.md`. The `ai-toolkit-*` prefix in `~/.claude/rules/` is installer-managed; use another prefix for hand-written Claude rules.
+
+To unregister a rule (removes from `~/.softspark/ai-toolkit/rules/`, deletes the generated Claude rule file, and strips any legacy block from `CLAUDE.md`):
 
 ```bash
 ai-toolkit remove-rule jira-rules
@@ -37,17 +39,13 @@ ai-toolkit remove-rule jira-rules
 
 ## How It Works
 
-Both mechanisms use marker-based idempotent injection. Rule name = filename without `.md`.
+Claude Code uses file-based user-level rules:
 
 ```
-<!-- TOOLKIT:jira-rules START -->
-
-...rule content...
-
-<!-- TOOLKIT:jira-rules END -->
+~/.claude/rules/ai-toolkit-registered-jira-rules.md
 ```
 
-Content outside markers is never touched. Re-running updates only the marked block.
+Other editors receive the same registered rule through their native generated rule surfaces. Legacy `CLAUDE.md` marker sections are removed during migration, but content outside toolkit-managed markers is never touched.
 
 ---
 
@@ -56,8 +54,9 @@ Content outside markers is never touched. Re-running updates only the marked blo
 1. Create `<name>-rules.md` in your repo with Claude-relevant conventions
 2. Register it: `ai-toolkit add-rule ./<name>-rules.md`
 3. Verify it appears in: `~/.softspark/ai-toolkit/rules/<name>-rules.md`
-4. On next `install` it will be listed in: `Rules injected: ... <name>-rules`
-5. Add an entry below documenting the integration
+4. On next `install` it will be listed in: `Rules synced: ... <name>-rules`
+5. Verify Claude receives it at: `~/.claude/rules/ai-toolkit-registered-<name>-rules.md`
+6. Add an entry below documenting the integration
 
 ---
 
@@ -66,7 +65,7 @@ Content outside markers is never touched. Re-running updates only the marked blo
 ### rag-mcp
 
 **Rule file:** `rag-mcp.md`
-**Marker:** `TOOLKIT:rag-mcp`
+**Claude rule file:** `~/.claude/rules/ai-toolkit-registered-rag-mcp.md`
 
 Teaches Claude Code the RAG-MCP search protocol: always call `smart_query()` before answering, `kb_id` vs `file_path` distinction, available MCP tools.
 
@@ -78,7 +77,7 @@ ai-toolkit add-rule ./rag-mcp-rules.md
 ### jira-mcp
 
 **Rule file:** `jira-rules.md`
-**Marker:** `TOOLKIT:jira-rules`
+**Claude rule file:** `~/.claude/rules/ai-toolkit-registered-jira-rules.md`
 
 Teaches Claude Code the Jira MCP tool set: `sync_tasks`, `read_cached_tasks`, `update_task_status`, `log_task_time`, and key rules (sync first, hours only, check transitions).