@softspark/ai-toolkit 2.12.0 → 3.0.1

package/scripts/generate_copilot.py

@@ -1,7 +1,34 @@
 #!/usr/bin/env python3
-"""Generate .github/copilot-instructions.md from app/agents/*.md and app/skills/*/SKILL.md.
+"""Generate GitHub Copilot customization files.
 
-Usage: ./scripts/generate_copilot.py > .github/copilot-instructions.md
+This generator produces three surfaces, all on the OSS/Free/Pro tier
+(no Business/Enterprise gating, no server-side MCP config):
+
+1. ``.github/copilot-instructions.md`` — always-on repository instructions.
+   Supported by GitHub.com Copilot Chat, Copilot cloud agent, and VS Code
+   Copilot. Generated to stdout by default (backwards compatible).
+
+2. ``.github/instructions/*.instructions.md`` — path-specific instructions.
+   Each file has ``applyTo`` frontmatter with a glob pattern. Supported
+   by VS Code Copilot and Copilot cloud agent / code review on GitHub.com.
+   Written only when ``generate()`` is called with a target directory.
+
+3. ``.github/prompts/*.prompt.md`` — prompt files (slash commands).
+   Invoked manually in VS Code Copilot Chat via ``/name``. Written only
+   when ``generate()`` is called with a target directory.
+
+Features that live on Pro/Pro+/Business/Enterprise tiers are intentionally
+not generated (classified as class C in the ecosystem-sync SOP):
+  * ``.github/agents/*.agent.md`` — custom agent profiles (tier-gated)
+  * repo-level MCP configuration (GitHub repo Settings UI, tier-gated)
+  * organization-wide and enterprise-wide instructions
+
+Usage:
+  # Legacy stdout mode (repo-wide instructions only)
+  python3 scripts/generate_copilot.py > .github/copilot-instructions.md
+
+  # Directory mode (repo-wide + path-specific + prompt files)
+  python3 scripts/generate_copilot.py <target-dir>
 """
 from __future__ import annotations
 
@@ -9,22 +36,273 @@ import sys
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
+from dir_rules_shared import (
+    LANG_GLOBS,
+    PREFIX,
+    build_language_rules,
+    build_registered_rules,
+    rule_code_style,
+    rule_quality_standards,
+    rule_security,
+    rule_testing,
+    rule_workflow,
+)
+from emission import (
+    agents_dir,
+    skills_dir,
+)
+from frontmatter import frontmatter_field
 from generator_base import render_generator
 
-if __name__ == "__main__":
-    render_generator({
-        "title": "# GitHub Copilot Instructions",
-        "intro_template": (
-            "This repository uses the ai-toolkit — a shared AI development toolkit"
-            " with specialized agent personas and skills."
+# ---------------------------------------------------------------------------
+# Shared configuration for the legacy stdout output
+# ---------------------------------------------------------------------------
+
+_STDOUT_CONFIG: dict = {
+    "title": "# GitHub Copilot Instructions",
+    "intro_template": (
+        "This repository uses the ai-toolkit — a shared AI development toolkit"
+        " with specialized agent personas and skills."
+    ),
+    "agents_section": "## Available Agent Personas",
+    "agents_intro": "Apply the expertise of these agents when working on relevant tasks:",
+    "agents_format": "headings",
+    "agents_level": "###",
+    "skills_section": "## Available Skills",
+    "skills_intro": "The following skills are available as slash commands or knowledge sources:",
+    "skills_format": "headings",
+    "skills_level": "###",
+    "guidelines": ["quality"],
+}
+
+
+# ---------------------------------------------------------------------------
+# Path-specific .instructions.md emission
+# ---------------------------------------------------------------------------
+
+def _instructions_file(content: str, *, apply_to: str,
+                       description: str = "") -> str:
+    """Wrap markdown content with Copilot ``.instructions.md`` frontmatter."""
+    lines = ["---"]
+    lines.append(f'applyTo: "{apply_to}"')
+    if description:
+        lines.append(f"description: {description}")
+    lines.append("---")
+    lines.append("")
+    lines.append(content.rstrip("\n"))
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _make_instruction_files() -> dict[str, callable]:
+    """Build the ``.instructions.md`` file registry.
+
+    Filenames use the standard ai-toolkit prefix so they can be cleaned up
+    on re-run without touching user files.
+    """
+    return {
+        # Always applies (repo-wide)
+        f"{PREFIX}security.instructions.md": lambda: _instructions_file(
+            rule_security(),
+            apply_to="**",
+            description="Security rules — OWASP, secrets, input validation",
+        ),
+        f"{PREFIX}quality-standards.instructions.md": lambda: _instructions_file(
+            rule_quality_standards(),
+            apply_to="**",
+            description="Quality standards — tests, safety, operational integrity",
+        ),
+        f"{PREFIX}workflow.instructions.md": lambda: _instructions_file(
+            rule_workflow(),
+            apply_to="**",
+            description="Development workflow — planning, commits, quality gates",
         ),
-        "agents_section": "## Available Agent Personas",
-        "agents_intro": "Apply the expertise of these agents when working on relevant tasks:",
-        "agents_format": "headings",
-        "agents_level": "###",
-        "skills_section": "## Available Skills",
-        "skills_intro": "The following skills are available as slash commands or knowledge sources:",
-        "skills_format": "headings",
-        "skills_level": "###",
-        "guidelines": ["quality"],
-    })
+        f"{PREFIX}code-style.instructions.md": lambda: _instructions_file(
+            rule_code_style(),
+            apply_to="**",
+            description="Code style conventions for all languages",
+        ),
+        # Scoped to test files only
+        f"{PREFIX}testing.instructions.md": lambda: _instructions_file(
+            rule_testing(),
+            apply_to="**/*.test.*,**/*.spec.*,**/test_*,**/tests/**",
+            description="Testing standards and patterns",
+        ),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Prompt-file emission (.github/prompts/*.prompt.md)
+# ---------------------------------------------------------------------------
+
+def _prompt_file(description: str, body: str, *,
+                 agent: str | None = None) -> str:
+    """Wrap a skill body with Copilot ``.prompt.md`` frontmatter."""
+    lines = ["---"]
+    # Description is required for visibility in the slash menu.
+    lines.append(f"description: {description}")
+    if agent:
+        lines.append(f"agent: {agent}")
+    lines.append("---")
+    lines.append("")
+    lines.append(body.rstrip("\n"))
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _read_skill_body(skill_file: Path) -> str:
+    """Read SKILL.md body after the closing frontmatter delimiter."""
+    lines: list[str] = []
+    fence_count = 0
+    with open(skill_file, encoding="utf-8") as f:
+        for line in f:
+            stripped = line.rstrip("\n")
+            if stripped == "---":
+                fence_count += 1
+                continue
+            if fence_count >= 2:
+                lines.append(line.rstrip("\n"))
+    while lines and not lines[-1]:
+        lines.pop()
+    return "\n".join(lines)
+
+
+def _user_invocable_skills() -> list[tuple[str, str, str]]:
+    """Return user-invocable skills as (name, description, body) tuples.
+
+    Only skills whose SKILL.md is suitable for slash-command invocation
+    are returned. Knowledge-only skills (``user-invocable: false`` or
+    ``disable-model-invocation: true``) are filtered out.
+    """
+    if not skills_dir.is_dir():
+        return []
+    result: list[tuple[str, str, str]] = []
+    for skill_dir in sorted(skills_dir.iterdir()):
+        if skill_dir.name.startswith("_") or not skill_dir.is_dir():
+            continue
+        skill_file = skill_dir / "SKILL.md"
+        if not skill_file.is_file():
+            continue
+        name = frontmatter_field(skill_file, "name")
+        description = frontmatter_field(skill_file, "description")
+        if not name or not description:
+            continue
+        # Honour the same visibility filter used by generate_opencode_commands
+        user_invocable = frontmatter_field(skill_file, "user-invocable")
+        disable_model = frontmatter_field(skill_file, "disable-model-invocation")
+        if user_invocable == "false":
+            continue
+        # Task skills (disable-model-invocation: true) are still fine as
+        # slash commands; knowledge skills with user-invocable: false are not.
+        del disable_model  # not used beyond inspection
+        body = _read_skill_body(skill_file)
+        if not body:
+            continue
+        result.append((name, description, body))
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Directory-mode generation
+# ---------------------------------------------------------------------------
+
+def _cleanup_prefixed(directory: Path, suffix: str,
+                      keep: set[str]) -> None:
+    """Remove ai-toolkit-prefixed files in ``directory`` that aren't in ``keep``."""
+    if not directory.is_dir():
+        return
+    for f in directory.iterdir():
+        if f.name.startswith(PREFIX) and f.name.endswith(suffix) and f.name not in keep:
+            f.unlink()
+            rel = f.relative_to(directory.parent.parent) if len(directory.parents) >= 2 else f
+            print(f"  Removed stale: {rel}")
+
+
+def generate(target_dir: Path, *,
+             language_modules: list[str] | None = None,
+             rules_dir: Path | None = None,
+             emit_prompts: bool = True,
+             emit_instructions: bool = True) -> None:
+    """Write Copilot path-specific instructions and prompt files.
+
+    ``.github/copilot-instructions.md`` is intentionally not written here —
+    the legacy ``main()`` entry point still emits it to stdout so existing
+    scripts (including ``ai-toolkit install``) keep working unchanged.
+    """
+    github_dir = target_dir / ".github"
+
+    if emit_instructions:
+        instr_dir = github_dir / "instructions"
+        instr_dir.mkdir(parents=True, exist_ok=True)
+
+        instruction_files: dict[str, callable] = dict(_make_instruction_files())
+
+        # Language-specific instructions (auto-applied by file glob)
+        for filename, content_fn in build_language_rules(language_modules).items():
+            lang = filename.removeprefix(f"{PREFIX}lang-").removesuffix(".md")
+            globs = LANG_GLOBS.get(lang)
+            apply_to = ",".join(globs) if globs else "**"
+            new_name = f"{PREFIX}lang-{lang}.instructions.md"
+            instruction_files[new_name] = (lambda fn, l, a: lambda: _instructions_file(
+                fn(),
+                apply_to=a,
+                description=f"{l.title()} language rules",
+            ))(content_fn, lang, apply_to)
+
+        # User-registered custom rules (always-on)
+        for filename, content_fn in build_registered_rules(rules_dir).items():
+            stem = filename.removeprefix(f"{PREFIX}custom-").removesuffix(".md")
+            new_name = f"{PREFIX}custom-{stem}.instructions.md"
+            instruction_files[new_name] = (lambda fn, n: lambda: _instructions_file(
+                fn(),
+                apply_to="**",
+                description=f"Custom rule: {n}",
+            ))(content_fn, stem)
+
+        _cleanup_prefixed(instr_dir, ".instructions.md", set(instruction_files.keys()))
+
+        for name, content_fn in instruction_files.items():
+            (instr_dir / name).write_text(content_fn(), encoding="utf-8")
+            print(f"  Generated: .github/instructions/{name}")
+
+    if emit_prompts:
+        prompt_dir = github_dir / "prompts"
+        prompt_dir.mkdir(parents=True, exist_ok=True)
+
+        skills = _user_invocable_skills()
+        prompt_filenames: set[str] = set()
+        for name, description, body in skills:
+            filename = f"{PREFIX}{name}.prompt.md"
+            prompt_filenames.add(filename)
+            content = _prompt_file(description, body)
+            (prompt_dir / filename).write_text(content, encoding="utf-8")
+            print(f"  Generated: .github/prompts/{filename}")
+
+        _cleanup_prefixed(prompt_dir, ".prompt.md", prompt_filenames)
+
+
+# ---------------------------------------------------------------------------
+# Entry points
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    """Main entry point.
+
+    With no argument: emit the repo-wide ``copilot-instructions.md`` to stdout
+    (preserves the historical contract).
+
+    With a directory argument: write the path-specific ``instructions/`` and
+    ``prompts/`` files under ``<target>/.github/``. The caller is responsible
+    for redirecting the stdout generator separately if they want the full set.
+    """
+    if len(sys.argv) > 1:
+        target = Path(sys.argv[1])
+        from paths import RULES_DIR
+        generate(target, rules_dir=RULES_DIR)
+        return
+
+    render_generator(_STDOUT_CONFIG)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/generate_cursor_agents.py

@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+"""Generate ``.cursor/agents/ai-toolkit-*.md`` files for Cursor IDE.
+
+Each ai-toolkit agent is mirrored as a Cursor custom agent. Per Cursor's
+docs (docs.cursor.com -> custom agents), agent files use YAML frontmatter:
+
+    ---
+    name: <slug>
+    description: "<one-line summary shown in the picker>"
+    model: <model-id>     # optional, inherits user default if absent
+    color: <color-name>   # optional UI hint
+    tools: [Read, Write, ...]  # list of allowed tool names
+    ---
+
+    <system prompt body>
+
+Design choices:
+
+* ``model`` is omitted. Our agents store short aliases (``opus``, ``sonnet``,
+  ``haiku``) that do not map to Cursor's provider-qualified model ids.
+  Omitting the field makes Cursor fall back to the user's default model,
+  which is the same behaviour our opencode generator uses.
+* ``tools`` is emitted as a YAML flow-list parsed verbatim from the source.
+* Files are prefixed ``ai-toolkit-`` so install/uninstall can identify ours.
+* Regeneration removes stale ``ai-toolkit-*.md`` files whose source agent
+  no longer exists, but leaves user-authored agents untouched.
+
+Usage:
+  python3 scripts/generate_cursor_agents.py [target-dir]
+
+Writes files to ``target-dir/.cursor/agents/``.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from emission import agents_dir
+from frontmatter import frontmatter_field
+
+AGENT_PREFIX = "ai-toolkit-"
+
+
+def _agent_body(agent_file: Path) -> str:
+    """Return the markdown body of an agent file (content after frontmatter)."""
+    text = agent_file.read_text(encoding="utf-8")
+    if not text.startswith("---"):
+        return text.strip() + "\n"
+    parts = text.split("---", 2)
+    if len(parts) < 3:
+        return text.strip() + "\n"
+    return parts[2].lstrip("\n")
+
+
+def _parse_tools(tools_raw: str) -> list[str]:
+    """Parse the comma-separated ``tools:`` frontmatter value into a list."""
+    if not tools_raw:
+        return []
+    return [t.strip() for t in tools_raw.split(",") if t.strip()]
+
+
+def _render_cursor_agent(agent_file: Path) -> str:
+    """Render a single Cursor custom agent .md file."""
+    name = frontmatter_field(agent_file, "name")
+    description = frontmatter_field(agent_file, "description")
+    color = frontmatter_field(agent_file, "color")
+    tools_raw = frontmatter_field(agent_file, "tools")
+    tools = _parse_tools(tools_raw)
+
+    safe_desc = description.replace('"', "'")
+
+    lines: list[str] = ["---"]
+    lines.append(f"name: {name}")
+    lines.append(f'description: "{safe_desc}"')
+    # model intentionally omitted — Cursor falls back to the user default.
+    if color:
+        lines.append(f"color: {color}")
+    if tools:
+        tools_flow = ", ".join(tools)
+        lines.append(f"tools: [{tools_flow}]")
+    else:
+        lines.append("tools: []")
+    lines.append("---")
+    lines.append("")
+    body = _agent_body(agent_file).rstrip()
+    if body:
+        lines.append(body)
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _cleanup_stale(agents_out: Path) -> int:
+    """Remove stale ai-toolkit-* agent files whose source no longer exists."""
+    if not agents_out.is_dir():
+        return 0
+    removed = 0
+    for f in sorted(agents_out.glob(f"{AGENT_PREFIX}*.md")):
+        source_name = f.stem[len(AGENT_PREFIX):]
+        source = agents_dir / f"{source_name}.md"
+        if not source.is_file():
+            f.unlink()
+            removed += 1
+    return removed
+
+
+def generate(
+    target_dir: Path, config_root: Path | None = None
+) -> tuple[int, int]:
+    """Write Cursor agent files and return (written, removed_stale).
+
+    By default writes to ``target_dir/.cursor/agents/`` (project-local).
+    Pass ``config_root=~/.cursor`` for the global layout.
+    """
+    base = config_root if config_root is not None else target_dir / ".cursor"
+    agents_out = base / "agents"
+    agents_out.mkdir(parents=True, exist_ok=True)
+
+    written = 0
+    for agent_file in sorted(agents_dir.glob("*.md")):
+        name = frontmatter_field(agent_file, "name")
+        description = frontmatter_field(agent_file, "description")
+        if not name or not description:
+            continue
+        out_path = agents_out / f"{AGENT_PREFIX}{name}.md"
+        out_path.write_text(_render_cursor_agent(agent_file), encoding="utf-8")
+        written += 1
+
+    removed = _cleanup_stale(agents_out)
+    return written, removed
+
+
+def main() -> None:
+    target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
+    written, removed = generate(target)
+    msg = f"Generated: .cursor/agents/ ({written} agents"
+    if removed:
+        msg += f", {removed} stale removed"
+    msg += ")"
+    print(msg)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/generate_cursor_hooks.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""Generate .cursor/hooks.json for Cursor Agent / Tab.
+
+Writes `<target>/.cursor/hooks.json`. Existing user-authored hook entries are
+preserved; entries tagged `_source: ai-toolkit` are the only ones replaced on
+regeneration. Top-level `version` is set to 1 (current Cursor schema).
+
+Cursor hook events (per cursor.com/docs/hooks.md):
+    Agent:    sessionStart, sessionEnd, preToolUse, postToolUse,
+              postToolUseFailure, subagentStart, subagentStop,
+              beforeShellExecution, afterShellExecution,
+              beforeMCPExecution, afterMCPExecution,
+              beforeReadFile, afterFileEdit, beforeSubmitPrompt,
+              preCompact, stop, afterAgentResponse, afterAgentThought
+    Tab:      beforeTabFileRead, afterTabFileEdit
+Entry schema: {"command": "...", "matcher"?: "...", "timeout"?: number}
+Exit code 2 blocks the action, so `guard-destructive.sh` continues to work.
+
+Hook scripts are shared with Claude Code and live under
+`~/.softspark/ai-toolkit/hooks/`. Cursor runs commands via the shell so the
+`"$HOME/..."` expansion works identically.
+
+Usage:
+    python3 scripts/generate_cursor_hooks.py [target-dir]
+"""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+HOOKS_PREFIX = '"$HOME/.softspark/ai-toolkit/hooks/'
+SOURCE_TAG = "ai-toolkit"
+SCHEMA_VERSION = 1
+
+# Event -> list of (matcher, script). Empty matcher = omit the field.
+CURSOR_HOOKS: dict[str, list[tuple[str, str]]] = {
+    "sessionStart": [
+        ("", "session-start.sh"),
+        ("", "mcp-health.sh"),
+        ("", "session-context.sh"),
+    ],
+    "beforeShellExecution": [
+        ("", "guard-destructive.sh"),
+        ("", "commit-quality.sh"),
+    ],
+    "beforeReadFile": [
+        ("", "guard-path.sh"),
+    ],
+    "afterFileEdit": [
+        ("", "post-tool-use.sh"),
+        ("", "governance-capture.sh"),
+    ],
+    "beforeSubmitPrompt": [
+        ("", "user-prompt-submit.sh"),
+        ("", "track-usage.sh"),
+    ],
+    "beforeMCPExecution": [
+        ("", "guard-config.sh"),
+    ],
+    "preCompact": [
+        ("", "pre-compact.sh"),
+        ("", "pre-compact-save.sh"),
+    ],
+    "subagentStart": [
+        ("", "subagent-start.sh"),
+    ],
+    "subagentStop": [
+        ("", "subagent-stop.sh"),
+    ],
+    "stop": [
+        ("", "quality-check.sh"),
+        ("", "save-session.sh"),
+    ],
+    "sessionEnd": [
+        ("", "session-end.sh"),
+    ],
+}
+
+
+def build_hook_entry(matcher: str, script: str) -> dict:
+    entry: dict = {
+        "_source": SOURCE_TAG,
+        "command": f"{HOOKS_PREFIX}{script}\"",
+    }
+    if matcher:
+        entry["matcher"] = matcher
+    return entry
+
+
+def build_toolkit_hooks() -> dict[str, list[dict]]:
+    result: dict[str, list[dict]] = {}
+    for event, entries in CURSOR_HOOKS.items():
+        result[event] = [build_hook_entry(m, s) for m, s in entries]
+    return result
+
+
+def _is_toolkit_entry(entry: dict) -> bool:
+    return isinstance(entry, dict) and entry.get("_source") == SOURCE_TAG
+
+
+def strip_toolkit_hooks(hooks: dict) -> dict:
+    kept: dict = {}
+    for event, entries in hooks.items():
+        if not isinstance(entries, list):
+            kept[event] = entries
+            continue
+        survivors = [e for e in entries if not _is_toolkit_entry(e)]
+        if survivors:
+            kept[event] = survivors
+    return kept
+
+
+def merge_hooks(existing: dict, toolkit: dict) -> dict:
+    merged = strip_toolkit_hooks(existing)
+    for event, entries in toolkit.items():
+        merged.setdefault(event, []).extend(entries)
+    return merged
+
+
+def generate(target_dir: Path) -> Path:
+    cursor_dir = target_dir / ".cursor"
+    cursor_dir.mkdir(parents=True, exist_ok=True)
+    path = cursor_dir / "hooks.json"
+
+    doc: dict = {}
+    if path.is_file():
+        try:
+            with open(path, encoding="utf-8") as f:
+                doc = json.load(f)
+            if not isinstance(doc, dict):
+                doc = {}
+        except (json.JSONDecodeError, OSError):
+            doc = {}
+
+    existing_hooks = doc.get("hooks") if isinstance(doc.get("hooks"), dict) else {}
+    doc["version"] = SCHEMA_VERSION
+    doc["hooks"] = merge_hooks(existing_hooks or {}, build_toolkit_hooks())
+
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(doc, f, indent=4, ensure_ascii=False, sort_keys=True)
+        f.write("\n")
+    return path
+
+
+def main() -> None:
+    target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
+    path = generate(target)
+    total = sum(len(v) for v in CURSOR_HOOKS.values())
+    print(f"Generated: {path.relative_to(target) if path.is_relative_to(target) else path} "
+          f"({total} hooks across {len(CURSOR_HOOKS)} events)")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/generate_cursor_mdc.py

@@ -1,14 +1,26 @@
 #!/usr/bin/env python3
-"""Generate .cursor/rules/*.mdc files for Cursor IDE.
+"""Generate ``.cursor/rules/*.mdc`` files for Cursor IDE.
 
-Cursor reads rules from .cursor/rules/*.mdc (since Cursor 0.45).
-Each .mdc file has YAML frontmatter controlling when the rule applies:
-  - alwaysApply: true  — always in context
-  - globs: ["**/*.ts"] — auto-attached for matching files
-  - description: "..." — AI decides whether to include (Agent Requested)
+Cursor reads rules from ``.cursor/rules/`` (since Cursor 0.45). Both ``.mdc``
+and plain ``.md`` extensions are accepted; we emit ``.mdc`` because only it
+carries the full YAML frontmatter used to control activation:
 
-The legacy .cursorrules format is still generated separately by
-generate_cursor_rules.py for backwards compatibility.
+  - ``alwaysApply: true``   — always in context
+  - ``globs: ["**/*.ts"]``  — auto-attached for matching files
+  - ``description: "..."``  — Agent Requested (AI decides whether to include)
+  - manual (no description, no globs, ``alwaysApply: false``) — ``@rule-name``
+
+Rule types map to Cursor's UI labels as follows:
+
+  Always Apply            → ``alwaysApply: true``
+  Apply to Specific Files → ``globs: [...]``
+  Apply Intelligently     → ``description: ...``
+  Apply Manually          → none of the above
+
+The legacy ``.cursorrules`` single-file format is still generated separately
+by ``generate_cursor_rules.py`` for backwards compatibility. Cursor also
+supports ``AGENTS.md`` (root + nested subdirectories) as an alternative to
+``.cursor/rules/``; ``generate_agents_md.py`` covers that surface.
 
 Usage:
   python3 scripts/generate_cursor_mdc.py [target-dir]