@softspark/ai-toolkit 4.10.0 → 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,34 @@ 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.
+
+### Fixed
+- **GitHub Copilot local install now emits root `AGENTS.md`.** `ai-toolkit install --local --editors copilot` writes the generated agent catalog into a `TOOLKIT:copilot-agents` section without clobbering existing Codex/opencode `TOOLKIT:ai-toolkit` sections or user-authored content. Dry-run output and tests now cover the `.github/copilot-instructions.md + AGENTS.md` contract.
+- **Claude Code KB-first rule restored in the right instruction file.** `CLAUDE.md` now explicitly requires `smart_query()` or `hybrid_search_kb()` before technical/project answers; the prior generated `AGENTS.md` placement was not sufficient for Claude Code runtime enforcement.
+- **Codex PostToolUse no longer emits unsupported `suppressOutput`.** `loop-guard.sh` no longer forces `AI_TOOLKIT_HOOK_FORMAT=json`; under Codex it stays quiet/plain unless the generator explicitly opts into a supported JSON schema.
+- **Npm package excludes local Claude session artifacts.** `package.json` now excludes `app/**/.claude/**` so ignored maintainer-local session files cannot leak into `npm pack`.
+
+### Changed
+- **Editor registry/docs aligned with implementation.** README, architecture overview, and the supported-tools registry now describe Copilot's root `AGENTS.md` emission consistently.
+- **Ecosystem doctor baseline refreshed.** Snapshot updated for upstream Claude Code and Gemini CLI documentation content hash drift; no generator changes were required.
+
 ## v4.10.0 — Per-repo session storage outside the repo + drop dead session-context hook (2026-06-17)
 
 Minor release. Session lifecycle hooks stop writing auto-generated files into each project's `.claude/` directory and store them per-repo under `~/.softspark/ai-toolkit/`. The dead `session-context.sh` hook (write-only, no consumer) is removed across all editor generators. Test count: 1197 → 1195.

package/README.md

@@ -6,16 +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-1195%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-1203%20passing-success)](tests/)
 
-## What's New in v4.10.0
+## What's New in v4.11.0
 
-v4.10.0 gets auto-generated session files out of your repositories and removes a dead lifecycle hook.
+v4.11.0 reduces Claude Code startup/global rule pressure and refreshes the editor registry.
 
-- **Per-repo session storage outside the repo**: `save-session.sh`, `session-end.sh`, `session-start.sh`, and `pre-compact.sh` now keep `session-context.md`, `session-end.md`, checkpoints, and `decisions.md` under `~/.softspark/ai-toolkit/sessions/<repo-key>/` instead of each project's `.claude/` — no more generated files piling up in every repo. Keyed per repo (git root with `/` → `-`) so projects stay isolated.
-- **No silent migration**: the new store starts fresh; pre-existing in-repo `.claude/session-*.md` are left for you to delete.
-- **Dropped the dead `session-context.sh` hook**: it wrote a `${SESSION}.json` environment snapshot nobody ever read (Constitution Art. VI.1). Removed across `app/hooks.json` and all 7 editor hook generators (cursor, windsurf, codex, devin, augment, gemini, opencode).
-- **Test count**: 1197 → 1195.
+- **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.
 
@@ -100,11 +101,11 @@ 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 |
-| GitHub Copilot | `.github/copilot-instructions.md` | — | project |
+| GitHub Copilot | `.github/copilot-instructions.md` + `.github/instructions/*` + `.github/prompts/*` + `AGENTS.md` | — | project |
 | Cline | `~/Documents/Cline/Rules/*.md` + `~/.cline/skills/*` + `.clinerules/*.md` | — | global + project |
 | Roo Code | `~/.roo/rules/*.md` + `.roomodes` + `.roo/rules/*.md` | — | global rules + project |
 | Aider | `~/.aider.conf.yml` + `.aider.conf.yml` + `CONVENTIONS.md` | — | global + project |
@@ -128,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 |
 
 ---
@@ -140,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
@@ -148,7 +149,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats test suite (1195 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.0",
+  "version": "4.11.0",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/hooks/loop-guard.sh

@@ -53,7 +53,6 @@ fi
 COUNT=$(grep -cxF "$HASH" "$LOG" 2>/dev/null | tr -d ' ')
 [ -z "$COUNT" ] && COUNT=0
 if [ "$COUNT" -ge "$THRESHOLD" ]; then
-    export AI_TOOLKIT_HOOK_FORMAT=json
     hook_emit_context "PostToolUse" \
         "Loop guard: the same ${TOOL_NAME} action has repeated ${COUNT}x within the last ${WINDOW} steps. If you are not making progress, stop and reassess — try a different approach or ask the user — instead of retrying the identical action."
 fi

package/benchmarks/ecosystem-doctor-snapshot.json

@@ -1,5 +1,5 @@
 {
-  "last_run": "2026-06-09T22:04:06Z",
+  "last_run": "2026-06-30T16:52:43Z",
   "schema_version": 1,
   "tools": {
     "aider": {
@@ -24,7 +24,7 @@
       }
     },
     "augment": {
-      "docs_hash": "f4c5995e8333a4d5",
+      "docs_hash": "1140b2d05814d7fd",
       "headings": [
         "Admin",
         "Auggie CLI",
@@ -66,7 +66,7 @@
       }
     },
     "claude-code": {
-      "docs_hash": "e6f6b4d9d4057cb0",
+      "docs_hash": "3101b3cd58375aec",
       "headings": [
         "Core concepts",
         "Documentation Index",
@@ -122,15 +122,18 @@
         "slash command": true,
         "sub-agent": true
       },
-      "version": "2.1.170 (Claude Code)"
+      "version": "2.1.196 (Claude Code)"
     },
     "cline": {
-      "docs_hash": "806fa530c90e227d",
+      "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": "1b4a56a8e918d721",
+      "docs_hash": "36f437b3356b4706",
       "headings": [
         "API",
         "API Reference",
@@ -208,6 +212,7 @@
         "Resources",
         "Run and scale",
         "Search the Codex docs",
+        "Spaces",
         "Specialized models",
         "Suggested",
         "Tools",
@@ -235,10 +240,10 @@
         "mcp_servers": false,
         "sandbox": true
       },
-      "version": "codex-cli 0.138.0"
+      "version": "codex-cli 0.142.0"
     },
     "cursor": {
-      "docs_hash": "b68e4adf6e21f543",
+      "docs_hash": "d8aed06363805889",
       "headings": [],
       "markers": {
         ".cursor/rules": false,
@@ -254,7 +259,7 @@
       }
     },
     "gemini-cli": {
-      "docs_hash": "a0e9a213229063c8",
+      "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": "ead818d74ead1f2e",
+      "docs_hash": "df772638c69033d7",
       "headings": [
         "About Copilot auto model selection",
         "About Copilot automations",
@@ -317,6 +323,7 @@
         "Still need help?"
       ],
       "markers": {
+        "AGENTS.md": false,
         "Copilot Chat": true,
         "Copilot Workspace": false,
         "Copilot cloud agent": true,
@@ -329,7 +336,7 @@
       }
     },
     "google-antigravity": {
-      "docs_hash": "5ea5426c4445e746",
+      "docs_hash": "4d2e384b2c2add18",
       "headings": [],
       "markers": {
         "AGENTS.md": false,
@@ -346,7 +353,7 @@
       }
     },
     "opencode": {
-      "docs_hash": "f546c8b741790cb8",
+      "docs_hash": "791633f4156abbe8",
       "headings": [
         "Add features",
         "Ask questions",
@@ -406,8 +413,9 @@
       }
     },
     "windsurf": {
-      "docs_hash": "91034c064d9f8290",
+      "docs_hash": "bb6e6119f2c068d6",
       "headings": [
+        "Accounts",
         "Advanced",
         "Agent Command Center",
         "App Deploys",
@@ -420,15 +428,15 @@
         "On this page",
         "Recommended Plugins",
         "Releases",
+        "Security",
         "Terminal",
         "Usage",
         "Welcome to Devin Desktop",
         "Windsurf Plugins",
         "Workflows",
-        "\u200b1. Select setup flow",
-        "\u200b2. Choose editor theme",
-        "\u200b3. Sign up / Log in",
-        "\u200b4. Let\u2019s Surf!",
+        "\u200b1. Select your preferred theme",
+        "\u200b2. Log In / Sign Up",
+        "\u200b3. Start Building with Devin!",
         "\u200bCustom App Icons (beta)",
         "\u200bDevin Desktop Next",
         "\u200bForgot to Import VS Code Configurations?",
@@ -436,8 +444,7 @@
         "\u200bOnboarding",
         "\u200bSet Up",
         "\u200bThings to Try",
-        "\u200bUninstall Devin Desktop",
-        "\u200bUpdate Devin Desktop"
+        "\u200bUninstall Devin Desktop"
       ],
       "markers": {
         "AGENTS.md": true,

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)
@@ -54,7 +54,7 @@ ai-toolkit/
     generate_agents_md.py    # Regenerates AGENTS.md
     generate_cursor_rules.py # Generates .cursorrules (sources _common.py)
     generate_windsurf.py     # Generates .windsurfrules (sources _common.py)
-    generate_copilot.py      # Generates .github/copilot-instructions.md (sources _common.py)
+    generate_copilot.py      # Generates Copilot .github/* surfaces; install also injects AGENTS.md
     generate_gemini.py       # Generates GEMINI.md (sources _common.py)
     generate_cline.py        # Generates .clinerules (sources _common.py)
     generate_roo_modes.py    # Generates .roomodes
@@ -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
 ```
@@ -109,7 +110,7 @@ Machine (global)                              Project (local)
 - `--editors cursor,aider` — install only selected editors
 - (no flag) — auto-detect from existing project files; `update --local` picks up whatever editors already have configs
 
-Each editor gets directory-based format (`.cursor/rules/*.mdc`, `.devin/rules/*.md` + `.windsurf/rules/*.md` (dual-emit since the Devin Desktop rebrand), `.clinerules/*.md`, `.roo/rules/*.md`, `.augment/rules/ai-toolkit-*.md`, `.agents/rules/*.md`, `CONVENTIONS.md`). Full-profile installs also emit native skill pointer catalogues for Cursor, Windsurf, and Cline. Codex local install additionally generates `AGENTS.md` (universal coding rules inlined — Codex reads only AGENTS.md, not `.agents/rules/`), `.agents/skills/*`, and `.codex/hooks.json`. Hooks are global-only — not merged into project settings except for editor-native local hook files such as Codex `.codex/hooks.json`. Experimental plugin packs can also layer a global Codex target in `HOME` (`~/AGENTS.md`, `~/.agents/`, `~/.codex/hooks.json`) when installed with `ai-toolkit plugin install --editor codex`.
+Each editor gets directory-based format (`.cursor/rules/*.mdc`, `.devin/rules/*.md` + `.windsurf/rules/*.md` (dual-emit since the Devin Desktop rebrand), `.github/instructions/*.instructions.md` + `.github/prompts/*.prompt.md` + root `AGENTS.md` for Copilot agent instructions, `.clinerules/*.md`, `.roo/rules/*.md`, `.augment/rules/ai-toolkit-*.md`, `.agents/rules/*.md`, `CONVENTIONS.md`). Full-profile installs also emit native skill pointer catalogues for Cursor, Windsurf, and Cline. Codex local install additionally generates `AGENTS.md` (universal coding rules inlined — Codex reads only AGENTS.md, not `.agents/rules/`), `.agents/skills/*`, and `.codex/hooks.json`. Hooks are global-only — not merged into project settings except for editor-native local hook files such as Codex `.codex/hooks.json`. Experimental plugin packs can also layer a global Codex target in `HOME` (`~/AGENTS.md`, `~/.agents/`, `~/.codex/hooks.json`) when installed with `ai-toolkit plugin install --editor codex`.
 
 If a project already has `.mcp.json`, local install mirrors its `mcpServers` entries into `.claude/settings.local.json` plus any selected editors with project-scoped native MCP files (`.cursor/mcp.json`, `.github/mcp.json`).
 
@@ -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/codex-cli-compatibility.md

@@ -116,16 +116,22 @@ by default because Codex currently renders `additionalContext` as visible hook
 context in the TUI. This keeps prompt-submit output quiet while preserving hook
 side effects and blocking decisions such as search-first Stop enforcement.
 
-Codex `UserPromptSubmit` JSON output is event-specific. When emitting context,
-the hook must include the event name alongside the context:
+Codex hooks must not force Claude-only JSON output fields such as
+`suppressOutput`. In particular, advisory `PostToolUse` hooks like
+`loop-guard.sh` run in quiet/plain mode under Codex; they keep side effects but
+do not emit hidden Claude-style context unless a future Codex runtime explicitly
+supports that schema.
+
+If a future Codex runtime enables JSON context output for `UserPromptSubmit`,
+the output must be event-specific and include the event name alongside the
+context:
 
 ```json
 {
   "hookSpecificOutput": {
     "hookEventName": "UserPromptSubmit",
     "additionalContext": "..."
-  },
-  "suppressOutput": true
+  }
 }
 ```
 

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