@softspark/ai-toolkit 4.14.1 → 4.15.1

package/scripts/injection.py

@@ -15,12 +15,35 @@ import re
 from pathlib import Path
 
 
+_MARKER_RE = re.compile(
+    r"^<!-- TOOLKIT:(?P<section>.+) (?P<kind>START|END) -->$"
+)
+_EMPTY_LEGACY_MARKER_RE = re.compile(
+    r"^<!-- TOOLKIT: (?P<kind>START|END) -->$"
+)
+
+
 # ---------------------------------------------------------------------------
 # Markers
 # ---------------------------------------------------------------------------
 
+def _validate_section_name(section: str) -> str:
+    """Validate a section name that can be represented by one marker line."""
+    if not section or "\n" in section or "\r" in section:
+        raise ValueError("section name must be non-empty and single-line")
+    return section
+
+
+def _section_names_for_update(section: str) -> set[str]:
+    """Return current and pre-Unicode marker names for update migration."""
+    section = _validate_section_name(section)
+    legacy_section = re.sub(r"[^a-zA-Z0-9_-]", "", section)
+    return {section, legacy_section}
+
+
 def markers_start(section: str = "ai-toolkit") -> str:
     """Return the TOOLKIT start marker block."""
+    section = _validate_section_name(section)
     return (
         f"<!-- TOOLKIT:{section} START -->\n"
         f"<!-- Auto-injected by ai-toolkit. Re-run to update. -->\n"
@@ -29,6 +52,7 @@ def markers_start(section: str = "ai-toolkit") -> str:
 
 def markers_end(section: str = "ai-toolkit") -> str:
     """Return the TOOLKIT end marker."""
+    section = _validate_section_name(section)
     return f"\n<!-- TOOLKIT:{section} END -->"
 
 
@@ -38,21 +62,72 @@ def markers_end(section: str = "ai-toolkit") -> str:
 
 def strip_section(content: str, section: str) -> str:
     """Remove a TOOLKIT marker section from content."""
-    start = f"<!-- TOOLKIT:{section} START -->"
-    end = f"<!-- TOOLKIT:{section} END -->"
-    lines: list[str] = []
-    skip = False
-    for line in content.splitlines(keepends=True):
-        stripped = line.rstrip("\n")
-        if stripped == start:
-            skip = True
-            continue
-        if stripped == end:
-            skip = False
+    return _strip_sections(content, {_validate_section_name(section)})
+
+
+def strip_all_sections(content: str) -> str:
+    """Remove every balanced TOOLKIT section and any orphan marker lines.
+
+    Balanced spans are discovered before content is removed, so nested legacy
+    sections are handled without leaving an outer END marker behind. An
+    unmatched START marker does not consume unrelated user content after it.
+    """
+    return _strip_sections(content, None)
+
+
+def _strip_sections(
+    content: str,
+    sections: set[str] | None,
+    *,
+    migrate_empty_legacy: bool = False,
+) -> str:
+    lines = content.splitlines(keepends=True)
+    stack: list[tuple[str, int]] = []
+    marker_names: dict[int, str] = {}
+    intervals: list[tuple[int, int, str]] = []
+
+    for index, line in enumerate(lines):
+        marker_line = line.rstrip("\r\n")
+        match = _MARKER_RE.fullmatch(marker_line)
+        if match:
+            name = _validate_section_name(match.group("section"))
+            kind = match.group("kind")
+        elif migrate_empty_legacy:
+            empty_match = _EMPTY_LEGACY_MARKER_RE.fullmatch(marker_line)
+            if not empty_match:
+                continue
+            name = ""
+            kind = empty_match.group("kind")
+        else:
             continue
-        if not skip:
-            lines.append(line)
-    return "".join(lines)
+        marker_names[index] = name
+        if kind == "START":
+            stack.append((name, index))
+        elif stack and stack[-1][0] == name:
+            _, start = stack.pop()
+            intervals.append((start, index, name))
+        elif stack:
+            # Crossed or otherwise mismatched markers make every open span
+            # ambiguous. Keep their non-marker content instead of guessing.
+            stack.clear()
+
+    coverage_delta = [0] * (len(lines) + 1)
+    for start, end, name in intervals:
+        if sections is None or name in sections:
+            coverage_delta[start] += 1
+            coverage_delta[end + 1] -= 1
+
+    result: list[str] = []
+    coverage = 0
+    for index, line in enumerate(lines):
+        coverage += coverage_delta[index]
+        marker_name = marker_names.get(index)
+        remove_marker = marker_name is not None and (
+            sections is None or marker_name in sections
+        )
+        if coverage == 0 and not remove_marker:
+            result.append(line)
+    return "".join(result)
 
 
 def trim_trailing_blanks(text: str) -> str:
@@ -98,8 +173,7 @@ def inject_section(
     content_file = Path(content_file)
     target_file = Path(target_file)
 
-    # Sanitize section name
-    section = re.sub(r"[^a-zA-Z0-9_-]", "", section)
+    section = _validate_section_name(section)
 
     # Create parent dir and target if missing
     target_file.parent.mkdir(parents=True, exist_ok=True)
@@ -112,8 +186,13 @@ def inject_section(
     # Read existing content
     existing = target_file.read_text(encoding="utf-8")
 
-    # Strip existing section
-    existing = strip_section(existing, section)
+    # Strip both the current marker and the legacy ASCII-sanitized marker.
+    section_names = _section_names_for_update(section)
+    existing = _strip_sections(
+        existing,
+        section_names,
+        migrate_empty_legacy="" in section_names,
+    )
     existing = trim_trailing_blanks(existing)
 
     # Read content to inject
@@ -125,12 +204,11 @@ def inject_section(
         parts.append(existing)
         parts.append("")
 
-    parts.append(f"<!-- TOOLKIT:{section} START -->")
-    parts.append("<!-- Auto-injected by ai-toolkit. Re-run to update. -->")
+    parts.append(markers_start(section).rstrip("\n"))
     parts.append("")
     parts.append(new_content.rstrip("\n"))
     parts.append("")
-    parts.append(f"<!-- TOOLKIT:{section} END -->")
+    parts.append(markers_end(section).lstrip("\n"))
 
     output = "\n".join(parts) + "\n"
     output = collapse_blank_runs(output)
@@ -151,7 +229,7 @@ def inject_rule(rule_file: str | Path, target_dir: str | Path) -> str:
     if not rule_file.is_file():
         raise FileNotFoundError(f"Rule file not found: {rule_file}")
 
-    rule_name = re.sub(r"[^a-zA-Z0-9_-]", "", rule_file.stem)
+    rule_name = _validate_section_name(rule_file.stem)
     claude_md = target_dir / ".claude" / "CLAUDE.md"
     claude_md.parent.mkdir(parents=True, exist_ok=True)
 
@@ -170,7 +248,8 @@ def remove_rule_section(rule_name: str, target_dir: str | Path) -> bool:
         return False
 
     content = claude_md.read_text(encoding="utf-8")
-    start_marker = f"<!-- TOOLKIT:{rule_name} START -->"
+    rule_name = _validate_section_name(rule_name)
+    start_marker = markers_start(rule_name).splitlines()[0]
 
     if start_marker not in content:
         return False

package/scripts/install_steps/ai_tools.py

@@ -1,19 +1,22 @@
 """Install global and project-local AI tool configs."""
 from __future__ import annotations
 
+import os
 import shutil
 import subprocess
 from pathlib import Path
 
-from _common import app_dir, inject_section, should_install, toolkit_dir
+from _common import app_dir, inject_section, toolkit_dir
 from codex_skill_adapter import (
     cleanup_codex_skills,
+    prepare_codex_skills_dir,
     sync_codex_skill,
+    unmanaged_codex_skill_names,
 )
 from mcp_editors import sync_project_mcp_to_editors
 from injection import (
     collapse_blank_runs as _collapse_blank_runs,
-    strip_section as _strip_section,
+    strip_all_sections as _strip_all_sections,
     trim_trailing_blanks as _trim_trailing_blanks,
 )
 
@@ -141,7 +144,9 @@ def install_ai_tools(target_dir: Path, rules_dir: Path,
 
     if "codex" in eds:
         if dry_run:
-            print("  Would inject: ~/.codex/AGENTS.md, ~/.agents/skills/, ~/.codex/hooks.json")
+            print("  Would inject: $CODEX_HOME/AGENTS.md, $CODEX_HOME/agents/, "
+                  "$CODEX_HOME/hooks.json")
+            print("  Would generate: ~/.agents/skills/ (shared Codex skill discovery)")
         else:
             _install_codex_global(target_dir, rules_dir)
         installed.append("codex")
@@ -166,12 +171,20 @@ def install_ai_tools(target_dir: Path, rules_dir: Path,
         installed.append("cursor")
 
     if "copilot" in eds:
-        # Copilot CLI reads user-level instructions from ~/.copilot/. RULES have
-        # a documented global surface here even though .github/ stays repo-only.
-        copilot_root = target_dir / ".copilot"
+        # Copilot CLI reads every personal customization from its active config
+        # root. COPILOT_HOME replaces ~/.copilot rather than extending it.
+        from generate_copilot_hooks import copilot_home
+
+        copilot_root = copilot_home(target_dir)
+        if copilot_root.is_symlink():
+            raise RuntimeError(
+                f"Refusing symlinked Copilot configuration root: {copilot_root}"
+            )
         if dry_run:
-            print("  Would inject: ~/.copilot/copilot-instructions.md")
-            print("  Would generate: ~/.copilot/instructions/ai-toolkit-*.instructions.md")
+            print("  Would inject: $COPILOT_HOME/copilot-instructions.md")
+            print("  Would generate: $COPILOT_HOME/{instructions,agents,skills}/")
+            if add_hooks:
+                print("  Would generate: $COPILOT_HOME/hooks/ai-toolkit.json")
         else:
             inject_with_rules(
                 "generate_copilot.py",
@@ -181,6 +194,12 @@ def install_ai_tools(target_dir: Path, rules_dir: Path,
             _try_generator("generate_copilot", target_dir,
                            rules_dir=rules_dir, config_root=copilot_root,
                            emit_prompts=False)
+            if add_hooks:
+                _try_generator(
+                    "generate_copilot_hooks",
+                    target_dir,
+                    config_root=copilot_root,
+                )
         installed.append("copilot")
 
     if "antigravity" in eds:
@@ -203,20 +222,34 @@ def install_ai_tools(target_dir: Path, rules_dir: Path,
     return installed
 
 
+def _resolve_global_codex_home(target_dir: Path) -> Path:
+    """Resolve the active Codex user root without changing project paths."""
+    configured = os.environ.get("CODEX_HOME")
+    if not configured:
+        return target_dir / ".codex"
+
+    codex_home = Path(configured).expanduser()
+    if not codex_home.is_absolute():
+        raise RuntimeError("CODEX_HOME must be an absolute path")
+    if not codex_home.is_dir():
+        raise RuntimeError("Configured CODEX_HOME must already exist")
+    if codex_home.is_symlink():
+        raise RuntimeError(f"Refusing symlinked CODEX_HOME: {codex_home}")
+    return codex_home
+
+
 def _install_codex_global(target_dir: Path, rules_dir: Path) -> None:
-    """Install Codex at the global level (~/.codex layer).
+    """Install Codex at the active user-level ``CODEX_HOME`` layer.
 
     Creates:
-      - ~/.codex/AGENTS.md (marker injection; universal coding rules inlined
-        here). Codex reads GLOBAL instructions from ``$CODEX_HOME/AGENTS.md``
-        (default ~/.codex/AGENTS.md), NOT ~/AGENTS.md — a home-root AGENTS.md
-        is only loaded in the degenerate case where a session's cwd is $HOME.
-      - ~/.agents/skills/* (skill symlinks; a documented Codex skill dir)
-      - ~/.codex/hooks.json (lifecycle hooks)
+      - ``$CODEX_HOME/AGENTS.md`` (defaults to ``~/.codex/AGENTS.md``)
+      - ``$CODEX_HOME/agents/*`` and ``$CODEX_HOME/hooks.json``
+      - ``~/.agents/skills/*`` (the documented shared user-skill path)
     """
+    codex_home = _resolve_global_codex_home(target_dir)
     inject_with_rules(
         "generate_codex.py",
-        target_dir / ".codex" / "AGENTS.md",
+        codex_home / "AGENTS.md",
         rules_dir,
     )
 
@@ -226,17 +259,22 @@ def _install_codex_global(target_dir: Path, rules_dir: Path) -> None:
     if _strip_toolkit_sections(target_dir / "AGENTS.md"):
         print("  Migrated: removed stale ai-toolkit section from ~/AGENTS.md")
 
-    override = target_dir / ".codex" / "AGENTS.override.md"
+    override = codex_home / "AGENTS.override.md"
     if override.is_file() and override.read_text(encoding="utf-8").strip():
         print(
-            "  Warning: ~/.codex/AGENTS.override.md exists and takes precedence "
-            "over ~/.codex/AGENTS.md — toolkit rules will be masked."
+            f"  Warning: {override} exists and takes precedence over "
+            f"{codex_home / 'AGENTS.md'} — toolkit rules will be masked."
         )
 
     from generate_codex_hooks import generate as gen_codex_hooks
-    gen_codex_hooks(target_dir)
-    print("  Created: ~/.codex/hooks.json")
+    gen_codex_hooks(
+        target_dir,
+        global_install=True,
+        codex_home=codex_home,
+    )
+    print(f"  Created: {codex_home / 'hooks.json'}")
 
+    _install_codex_agents(target_dir, config_root=codex_home)
     _install_codex_skills(target_dir)
 
 
@@ -506,14 +544,9 @@ def inject_with_rules(
 
     existing = target_file.read_text(encoding="utf-8")
     # Strip ALL toolkit sections from existing — generated output is the
-    # complete source of truth (includes ai-toolkit block + custom rules)
-    import re
-    existing = re.sub(
-        r"<!-- TOOLKIT:[^ ]+ START -->.*?<!-- TOOLKIT:[^ ]+ END -->\n?",
-        "",
-        existing,
-        flags=re.DOTALL,
-    )
+    # complete source of truth (includes ai-toolkit block + custom rules).
+    # The shared parser also repairs nested legacy sections and orphan markers.
+    existing = _strip_all_sections(existing)
     existing = _trim_trailing_blanks(existing)
     existing = existing.lstrip("\n")
 
@@ -540,15 +573,8 @@ def _strip_toolkit_sections(target_file: Path) -> bool:
     """
     if not target_file.is_file():
         return False
-    import re
-
     original = target_file.read_text(encoding="utf-8")
-    stripped = re.sub(
-        r"<!-- TOOLKIT:[^ ]+ START -->.*?<!-- TOOLKIT:[^ ]+ END -->\n?",
-        "",
-        original,
-        flags=re.DOTALL,
-    )
+    stripped = _strip_all_sections(original)
     if stripped == original:
         return False
     stripped = stripped.lstrip("\n")
@@ -559,37 +585,14 @@ def _strip_toolkit_sections(target_file: Path) -> bool:
     return True
 
 
-def _inject_text_section(target_file: Path, section: str, text: str) -> None:
-    """Inject generated text into one marker section without touching others."""
-    target_file.parent.mkdir(parents=True, exist_ok=True)
-    existing = target_file.read_text(encoding="utf-8") if target_file.is_file() else ""
-    existing = _trim_trailing_blanks(_strip_section(existing, section))
-
-    parts: list[str] = []
-    if existing.strip():
-        parts.append(existing)
-        parts.append("")
-    parts.extend([
-        f"<!-- TOOLKIT:{section} START -->",
-        "<!-- Auto-injected by ai-toolkit. Re-run to update. -->",
-        "",
-        text.rstrip("\n"),
-        "",
-        f"<!-- TOOLKIT:{section} END -->",
-    ])
-
-    output = _collapse_blank_runs("\n".join(parts) + "\n").lstrip("\n")
-    target_file.write_text(output, encoding="utf-8")
-
-
-def _install_copilot_agents_md(cwd: Path) -> None:
-    """Emit root AGENTS.md for GitHub Copilot without clobbering other tools."""
-    generated = run_script("generate_agents_md.py", capture=True)
-    if not generated.strip():
-        print("  ERROR: generate_agents_md.py produced no output")
-        return
-    _inject_text_section(cwd / "AGENTS.md", "copilot-agents", generated)
-    print("  Updated: AGENTS.md (Copilot agent instructions)")
+def _install_copilot_agents_md(cwd: Path, rules_dir: Path) -> None:
+    """Emit the same effective AGENTS.md used by Codex, including rules."""
+    inject_with_rules(
+        "generate_codex.py",
+        cwd / "AGENTS.md",
+        rules_dir,
+    )
+    print("  Updated: AGENTS.md (shared Codex/Copilot instructions)")
 
 
 def run_script(script_name: str, *args: str, capture: bool = False) -> str:
@@ -617,6 +620,12 @@ ALL_EDITORS = [
 # Map of project files/dirs → editor names for auto-detection
 _EDITOR_MARKERS: dict[str, str] = {
     ".github/copilot-instructions.md": "copilot",
+    ".github/instructions": "copilot",
+    ".github/prompts": "copilot",
+    ".github/agents": "copilot",
+    ".github/skills": "copilot",
+    ".github/hooks": "copilot",
+    ".github/mcp.json": "copilot",
     ".cursorrules": "cursor",
     ".cursor/rules": "cursor",
     ".windsurfrules": "windsurf",
@@ -740,7 +749,7 @@ def install_local_project(rules_dir: Path, dry_run: bool, reset: bool,
         if language_modules:
             print(f"  Would inject language rules: {', '.join(language_modules)}")
         if merged_config:
-            print(f"  Would apply merged config from extends")
+            print("  Would apply merged config from extends")
         return
 
     (cwd / ".claude").mkdir(parents=True, exist_ok=True)
@@ -864,7 +873,7 @@ def _apply_extends_config(cwd: Path, merged: dict) -> None:
     if meta:
         state_file = cwd / ".softspark-toolkit-extends.json"
         state_file.write_text(_json.dumps(meta, indent=2) + "\n", encoding="utf-8")
-        print(f"  Saved: .softspark-toolkit-extends.json (resolution metadata)")
+        print("  Saved: .softspark-toolkit-extends.json (resolution metadata)")
 
 
 def _inject_language_rules(cwd: Path, language_modules: list[str] | None) -> None:
@@ -914,7 +923,7 @@ def _inject_language_rules(cwd: Path, language_modules: list[str] | None) -> Non
         "when their triggers match -- you do not need to Read them manually."
     )
     if langs:
-        skill_names = ", ".join(f"`{l}-rules`" for l in langs)
+        skill_names = ", ".join(f"`{language}-rules`" for language in langs)
         lines.append("")
         lines.append(f"Detected languages: {skill_names}.")
 
@@ -1031,8 +1040,11 @@ def _install_local_dry_run(reset: bool, editors: list[str] | None = None,
             print("  Would migrate: remove undocumented .devin/skills toolkit pointer")
 
     # Profile-driven extras (matrix in kb/reference/global-install-model.md)
-    if "copilot" in eds and add_copilot_dir:
-        print("  Would generate: .github/instructions/ + .github/prompts/ (profile >= standard)")
+    if "copilot" in eds:
+        print("  Would generate: .github/agents/ + .github/skills/")
+        if add_copilot_dir:
+            print("  Would generate: .github/instructions/ + .github/prompts/ + "
+                  ".github/hooks/ (profile >= standard)")
     if "gemini" in eds and add_gemini_hooks:
         print("  Would generate: .gemini/settings.json hooks (profile >= standard)")
     if add_native_surfaces:
@@ -1048,6 +1060,7 @@ def _install_local_dry_run(reset: bool, editors: list[str] | None = None,
         if "gemini" in eds:
             print("  Would generate: .gemini/commands/ + .gemini/skills/ (profile=full)")
     if "codex" in eds:
+        print("  Would generate: .codex/agents/ native agents")
         print("  Would generate: .agents/skills/ Codex skills")
         if codex_skills:
             print("  Would refresh: .agents/skills/ via --codex-skills")
@@ -1158,8 +1171,8 @@ def _install_codex_skills(cwd: Path) -> None:
     if not skills_src.is_dir():
         return
 
-    skills_dst = cwd / ".agents" / "skills"
-    skills_dst.mkdir(parents=True, exist_ok=True)
+    skills_dst = prepare_codex_skills_dir(cwd)
+    user_names = unmanaged_codex_skill_names(skills_dst, skills_src)
 
     linked = 0
     adapted = 0
@@ -1170,6 +1183,9 @@ def _install_codex_skills(cwd: Path) -> None:
         skill_md = skill_dir / "SKILL.md"
         if not skill_md.is_file():
             continue
+        if skill_dir.name in user_names:
+            skipped += 1
+            continue
 
         mode = sync_codex_skill(skill_dir, skills_dst)
         if mode == "linked":
@@ -1179,7 +1195,7 @@ def _install_codex_skills(cwd: Path) -> None:
         else:
             skipped += 1
 
-    cleanup_codex_skills(skills_dst, skills_src)
+    cleanup_codex_skills(skills_dst, skills_src, user_names)
 
     print(
         f"  Installed: {linked + adapted} skills to .agents/skills/"
@@ -1187,6 +1203,22 @@ def _install_codex_skills(cwd: Path) -> None:
     )
 
 
+def _install_codex_agents(cwd: Path, *, config_root: Path | None = None) -> None:
+    """Generate native Codex custom-agent TOML files."""
+    from generate_codex_agents import generate as gen_codex_agents
+
+    written, removed = gen_codex_agents(cwd, config_root=config_root)
+    agents_dir = (
+        config_root / "agents"
+        if config_root is not None
+        else Path(".codex/agents")
+    )
+    message = f"  Created: {agents_dir}/ ({written} agents"
+    if removed:
+        message += f", {removed} stale removed"
+    print(message + ")")
+
+
 def _try_generator(module_name: str, *args, **kwargs) -> bool:
     """Import and invoke ``<module>.generate(...)``.
 
@@ -1235,18 +1267,37 @@ def _create_local_ai_tool_configs(cwd: Path, rules_dir: Path,
     emit_pointer = not _claude_skills_discoverable(cwd)
 
     if "copilot" in eds:
+        from generate_copilot import (
+            generate as gen_copilot_dir,
+            preflight_cleanup as preflight_copilot_cleanup,
+        )
+        if not add_copilot_dir:
+            from generate_copilot_hooks import (
+                preflight_cleanup as preflight_copilot_hook_cleanup,
+            )
+            preflight_copilot_cleanup(cwd)
+            preflight_copilot_hook_cleanup(cwd)
         inject_with_rules(
             "generate-copilot.sh",
             cwd / ".github" / "copilot-instructions.md",
             rules_dir,
         )
-        _install_copilot_agents_md(cwd)
-        # `standard` and above: emit path-specific instructions + prompt files
-        # (directory mode). `minimal` stays backwards-compatible with v2.
+        _install_copilot_agents_md(cwd, rules_dir)
+        # Agents and skills are the minimal Copilot surface. Standard and above
+        # add path instructions, prompts, and native lifecycle hooks.
+        gen_copilot_dir(
+            cwd,
+            language_modules=language_modules,
+            rules_dir=rules_dir,
+            emit_prompts=add_copilot_dir,
+            emit_instructions=add_copilot_dir,
+            cleanup_disabled=not add_copilot_dir,
+        )
         if add_copilot_dir:
-            from generate_copilot import generate as gen_copilot_dir
-            gen_copilot_dir(cwd, language_modules=language_modules,
-                            rules_dir=rules_dir)
+            _try_generator("generate_copilot_hooks", cwd)
+        else:
+            from generate_copilot_hooks import cleanup as cleanup_copilot_hooks
+            cleanup_copilot_hooks(cwd)
 
     if "cursor" in eds:
         inject_with_rules(
@@ -1338,8 +1389,10 @@ def _create_local_ai_tool_configs(cwd: Path, rules_dir: Path,
         )
         # .codex/hooks.json — Codex lifecycle hooks
         from generate_codex_hooks import generate as gen_codex_hooks
-        gen_codex_hooks(cwd)
+        gen_codex_hooks(cwd, global_install=False)
         print("  Created: .codex/hooks.json")
+        # .codex/agents/ -- native Codex custom-agent definitions
+        _install_codex_agents(cwd)
         # .agents/skills/ — Codex discovery path for repo-local skills
         _install_codex_skills(cwd)
         # --codex-skills explicitly re-runs the same Codex skill sync path.

package/scripts/instruction_core.py

@@ -0,0 +1,95 @@
+"""Render shared editor instructions from canonical ai-toolkit sources."""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+
+CONSTITUTION_PATH = (
+    Path(__file__).resolve().parent.parent / "app" / "constitution.md"
+)
+
+
+def _strip_frontmatter(text: str) -> str:
+    """Return Markdown after an optional leading YAML frontmatter block."""
+    lines = text.splitlines()
+    if not lines or lines[0] != "---":
+        return text.strip()
+    try:
+        closing = lines.index("---", 1)
+    except ValueError:
+        return text.strip()
+    return "\n".join(lines[closing + 1:]).strip()
+
+
+def read_constitution(path: Path = CONSTITUTION_PATH) -> str:
+    """Read the canonical constitution body without YAML frontmatter."""
+    return _strip_frontmatter(path.read_text(encoding="utf-8"))
+
+
+def render_constitution_policy(
+    heading_level: int = 2,
+    path: Path = CONSTITUTION_PATH,
+) -> str:
+    """Render the canonical constitution below a caller-selected heading."""
+    if not 1 <= heading_level <= 5:
+        raise ValueError("heading_level must be between 1 and 5")
+
+    body_lines = read_constitution(path).splitlines()
+    if body_lines and body_lines[0].startswith("# "):
+        body_lines = body_lines[1:]
+        while body_lines and not body_lines[0].strip():
+            body_lines.pop(0)
+
+    heading_shift = heading_level - 1
+    rebased: list[str] = []
+    for line in body_lines:
+        match = re.match(r"^(#{1,6})(\s+.*)$", line)
+        if not match:
+            rebased.append(line)
+            continue
+        level = min(6, len(match.group(1)) + heading_shift)
+        rebased.append("#" * level + match.group(2))
+
+    title = "#" * heading_level + " Constitution"
+    source = "Generated from `app/constitution.md`, the single policy source."
+    return f"{title}\n\n{source}\n\n" + "\n".join(rebased).rstrip()
+
+
+def _demote_rule_heading(body: str) -> str:
+    if body.startswith("# "):
+        return "### " + body[2:]
+    return body
+
+
+def render_instruction_core() -> str:
+    """Render the compact root AGENTS.md body shared by Codex and Copilot."""
+    from dir_rules_shared import (
+        rule_code_style,
+        rule_output_mode,
+        rule_security,
+        rule_testing,
+    )
+    from emission import generate_workflow_guidelines
+
+    coding_rules = "\n\n".join(
+        _demote_rule_heading(rule_fn().rstrip())
+        for rule_fn in (
+            rule_code_style,
+            rule_testing,
+            rule_security,
+            rule_output_mode,
+        )
+    )
+    sections = [
+        "# AI Toolkit Instructions",
+        (
+            "Shared, always-on policy for ai-toolkit projects. Agent and skill"
+            " catalogs are discovered from their native directories instead of"
+            " being duplicated here."
+        ),
+        render_constitution_policy(heading_level=2),
+        generate_workflow_guidelines(),
+        "## Coding Rules\n\n" + coding_rules,
+    ]
+    return "\n\n".join(sections).rstrip() + "\n"