code-context-control 2.36.0__py3-none-any.whl → 2.37.0__py3-none-any.whl

cli/c3.py

@@ -85,7 +85,7 @@ console = Console() if HAS_RICH else None
 # Config
 CONFIG_DIR = ".c3"
 CONFIG_FILE = ".c3/config.json"
-__version__ = "2.36.0"
+__version__ = "2.37.0"
 
 
 def _command_deps() -> CommandDeps:
@@ -379,6 +379,44 @@ def _build_permission_tier(tier: str, include_mcp_wildcard: bool = False) -> dic
     }}
 
 
+def _c3_managed_permission_entries() -> tuple[set, set]:
+    """Return (allow, deny) sets of every entry any C3 tier can emit.
+
+    Used to tell C3-managed permission rules apart from user-added ones so a
+    tier change replaces only the former and preserves the latter.
+    """
+    managed_allow: set = set()
+    managed_deny: set = set()
+    for _tier in PERMISSION_TIERS:
+        perms = _build_permission_tier(_tier, include_mcp_wildcard=True)["permissions"]
+        managed_allow.update(perms.get("allow", []))
+        managed_deny.update(perms.get("deny", []))
+    return managed_allow, managed_deny
+
+
+def _merge_permission_tier(existing: dict, tier_perms: dict) -> dict:
+    """Merge a tier's permissions into existing ones, preserving user rules.
+
+    C3 owns every entry a tier can emit: those are replaced by the chosen tier.
+    Any other allow/deny entry the user added is kept, and non-list permission
+    keys (e.g. ``ask``, ``defaultMode``, ``additionalDirectories``) are left
+    untouched. Mirrors how hooks and .mcp.json preserve non-C3 content.
+    """
+    existing = existing if isinstance(existing, dict) else {}
+    managed = dict(zip(("allow", "deny"), _c3_managed_permission_entries()))
+    merged = dict(existing)  # preserve unknown sub-keys (ask, defaultMode, ...)
+    for key in ("allow", "deny"):
+        user_custom = [e for e in (existing.get(key) or []) if e not in managed[key]]
+        out: list = []
+        seen: set = set()
+        for entry in user_custom + list(tier_perms.get(key) or []):
+            if entry not in seen:
+                seen.add(entry)
+                out.append(entry)
+        merged[key] = out
+    return merged
+
+
 def _detect_current_tier(settings_path) -> str | None:
     """Detect which permission tier is active in settings_path, or None.
 
@@ -456,9 +494,12 @@ def _apply_permission_tier(project_path: str, tier: str,
     settings_path = Path(project_path) / ".claude" / "settings.local.json"
     settings_path.parent.mkdir(parents=True, exist_ok=True)
     settings = _safe_read_json(settings_path, str(settings_path))
-    settings["permissions"] = _build_permission_tier(
+    tier_perms = _build_permission_tier(
         tier, include_mcp_wildcard=include_mcp_wildcard
     )["permissions"]
+    settings["permissions"] = _merge_permission_tier(
+        settings.get("permissions") or {}, tier_perms
+    )
     # Persist chosen tier in .c3/config.json
     c3_config_path = Path(project_path) / ".c3" / "config.json"
     c3_config = _safe_read_json(c3_config_path, str(c3_config_path))
@@ -5139,10 +5180,23 @@ def cmd_install_mcp(args):
             },
         ]
         stop_event = "Stop"
-        # Replace any existing C3 stop hooks (matcher=""), keep user-added ones
+        # Replace only C3's own stop hooks (identified by our hook scripts) and
+        # keep every user-added stop hook — including matcher-less ones, which
+        # are the normal shape for Stop hooks.
+        _c3_stop_scripts = (
+            "hook_session_stats.py", "hook_auto_snapshot.py", "hook_terse_advisor.py",
+        )
+
+        def _is_c3_stop_hook(entry: dict) -> bool:
+            return any(
+                script in (hk.get("command") or "")
+                for hk in entry.get("hooks", [])
+                for script in _c3_stop_scripts
+            )
+
         existing_stop = [
             h for h in settings.get("hooks", {}).get(stop_event, [])
-            if h.get("matcher")  # keep entries with a non-empty matcher
+            if not _is_c3_stop_hook(h)
         ]
         existing_stop.extend(desired_stop_hooks)
         settings.setdefault("hooks", {})[stop_event] = existing_stop
@@ -5160,9 +5214,12 @@ def cmd_install_mcp(args):
         include_wildcard = bool(getattr(args, "include_mcp_wildcard", False))
         if perm_tier and profile.name == "claude-code":
             if perm_tier in PERMISSION_TIERS:
-                settings["permissions"] = _build_permission_tier(
-                    perm_tier, include_mcp_wildcard=include_wildcard
-                )["permissions"]
+                settings["permissions"] = _merge_permission_tier(
+                    settings.get("permissions") or {},
+                    _build_permission_tier(
+                        perm_tier, include_mcp_wildcard=include_wildcard
+                    )["permissions"],
+                )
                 # Persist tier choice in .c3/config.json
                 _c3cfg = _safe_read_json(c3_config_path, str(c3_config_path))
                 _c3cfg["permission_tier"] = perm_tier

cli/commands/common.py

@@ -200,13 +200,9 @@ def cmd_claudemd(args, deps: CommandDeps):
             print(content)
         else:
             output_path = Path(project_path) / instructions_file
-            output_path.parent.mkdir(parents=True, exist_ok=True)
-            if output_path.exists():
-                existing = output_path.read_text(encoding="utf-8", errors="replace")
-                if "# User Notes" in existing:
-                    user_section = existing[existing.index("# User Notes"):]
-                    content += f"\n\n{user_section}"
-            output_path.write_text(content, encoding="utf-8")
+            # Wrap in the C3 managed block; preserve user content outside it.
+            from services.claude_md import write_c3_instruction_doc
+            write_c3_instruction_doc(output_path, content)
             print(f"{instructions_file} saved to {output_path} ({tokens} tokens)")
 
     elif args.claudemd_cmd == "check":

cli/guide/getting-started.html

@@ -188,6 +188,14 @@ c3 init</code></pre>
 
       <h3>Re-init / upgrade</h3>
       <p>Running <code>c3 init</code> on an existing project is safe — it merges new config without overwriting your customizations.</p>
+
+      <div class="callout callout-info">
+        <span class="callout-icon">🛡️</span>
+        <div class="callout-body">
+          <strong>Your hand-written content is preserved</strong>
+          Generated instruction files (<code>CLAUDE.md</code>, <code>AGENTS.md</code>, <code>GEMINI.md</code>) wrap C3 content in a <code>&lt;!-- C3:BEGIN … --&gt;</code> / <code>&lt;!-- C3:END --&gt;</code> block. Re-running init (or <code>c3 claudemd save</code> / the <strong>Compact</strong> action) rewrites only that block — anything you add outside it stays put. An existing hand-written file with no block is kept and the C3 block is appended below it.
+        </div>
+      </div>
     </section>
 
     <hr class="divider">
@@ -200,7 +208,7 @@ c3 init</code></pre>
 
       <h3>Claude Code (primary)</h3>
       <pre><code>c3 install-mcp claude</code></pre>
-      <p>This writes to <code>.mcp.json</code> (project scope) and optionally configures PreToolUse / PostToolUse hooks in <code>.claude/settings.local.json</code>.</p>
+      <p>This writes to <code>.mcp.json</code> (project scope) and optionally configures PreToolUse / PostToolUse hooks in <code>.claude/settings.local.json</code>. Both are merged, not overwritten: C3 only touches its own <code>c3</code> server entry and its own hooks, leaving any other MCP servers, hooks, and top-level keys you've added in place.</p>
 
       <h3>VS Code Copilot</h3>
       <pre><code>c3 install-mcp vscode</code></pre>
@@ -358,6 +366,14 @@ c3_session(action='snapshot')   <span class="com"># before /clear</span></code><
           The <code>standard</code> tier blocks destructive shell commands (rm -rf, git reset --hard, etc.) while allowing safe operations. Upgrade to <code>unrestricted</code> only when needed.
         </div>
       </div>
+
+      <div class="callout callout-info">
+        <span class="callout-icon">🛡️</span>
+        <div class="callout-body">
+          <strong>Your custom rules survive a tier change</strong>
+          Applying or switching a tier preserves <code>allow</code>/<code>deny</code> entries you added yourself, plus keys like <code>ask</code> and <code>defaultMode</code>. C3 only replaces the entries it manages, so you can mix a tier with project-specific permissions.
+        </div>
+      </div>
     </section>
 
     <hr class="divider">

cli/hub_server.py

@@ -1206,7 +1206,7 @@ def api_projects_permissions_get():
 @app.route("/api/projects/permissions/apply", methods=["POST"])
 def api_projects_permissions_put():
     """Apply permission tier to a project. Body: {path, tier}"""
-    from cli.c3 import PERMISSION_TIERS, _build_permission_tier
+    from cli.c3 import PERMISSION_TIERS, _build_permission_tier, _merge_permission_tier
     data = request.get_json(force=True) or {}
     path = (data.get("path") or "").strip()
     tier = (data.get("tier") or "").strip()
@@ -1228,7 +1228,9 @@ def api_projects_permissions_put():
                 settings = json.load(f)
         except Exception:
             pass
-    settings["permissions"] = tier_perms["permissions"]
+    settings["permissions"] = _merge_permission_tier(
+        settings.get("permissions") or {}, tier_perms["permissions"]
+    )
     with open(settings_path, "w", encoding="utf-8") as f:
         json.dump(settings, f, indent=2)
 

cli/server.py

@@ -1121,16 +1121,11 @@ def api_claudemd_save():
         return jsonify({"error": "Generation produced empty content"}), 500
 
     output_path = PROJECT_PATH / claude_md_mgr.instructions_file
-    output_path.parent.mkdir(parents=True, exist_ok=True)
 
-    # Preserve user-written sections
-    if output_path.exists():
-        existing = output_path.read_text(encoding="utf-8", errors="replace")
-        if "# User Notes" in existing:
-            user_section = existing[existing.index("# User Notes"):]
-            content += f"\n\n{user_section}"
+    # Wrap in the C3 managed block; never clobber user content outside it.
+    from services.claude_md import write_c3_instruction_doc
+    write_c3_instruction_doc(output_path, content)
 
-    output_path.write_text(content, encoding="utf-8")
     return jsonify({
         "path": str(output_path),
         "tokens": gen.get("tokens", 0),
@@ -2021,7 +2016,12 @@ def api_permissions_get():
 @app.route('/api/permissions', methods=['PUT'])
 def api_permissions_put():
     """Apply a permission tier. Body: {tier: "read-only"|"standard"|"permissive"}"""
-    from cli.c3 import PERMISSION_TIERS, _build_permission_tier, _safe_read_json
+    from cli.c3 import (
+        PERMISSION_TIERS,
+        _build_permission_tier,
+        _merge_permission_tier,
+        _safe_read_json,
+    )
     data = request.get_json() or {}
     tier = data.get("tier", "").strip()
     if tier not in PERMISSION_TIERS:
@@ -2031,7 +2031,9 @@ def api_permissions_put():
     settings_path = PROJECT_PATH / ".claude" / "settings.local.json"
     settings_path.parent.mkdir(parents=True, exist_ok=True)
     settings = _safe_read_json(settings_path, str(settings_path))
-    settings["permissions"] = tier_perms["permissions"]
+    settings["permissions"] = _merge_permission_tier(
+        settings.get("permissions") or {}, tier_perms["permissions"]
+    )
     with open(settings_path, "w", encoding="utf-8") as f:
         json.dump(settings, f, indent=2)
 

{code_context_control-2.36.0.dist-info → code_context_control-2.37.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-control
-Version: 2.36.0
+Version: 2.37.0
 Summary: Local code-intelligence layer for AI coding tools (Claude Code, Codex, Gemini, Copilot). Retrieve less, read less, edit safer.
 Author-email: Dimitri Tselenchuk <dtselenc@gmail.com>
 License-Expression: Apache-2.0
@@ -231,6 +231,8 @@ Every session you've ever run, with duration, decision count, file count, tool c
 
 Manage `CLAUDE.md`, `AGENTS.md` (Codex), `GEMINI.md`, and `.github/copilot-instructions.md` from one editor. Generate from project state, run a Health Check (drift detection vs the actual codebase), Compact stale sections, or Promote insights captured during sessions. **One source of truth** instead of four out-of-sync files.
 
+C3-generated content is wrapped in a `<!-- C3:BEGIN … -->` / `<!-- C3:END -->` block. Regenerating (or `Compact`) only rewrites that block — **anything you write outside it is preserved**, so it's safe to keep your own notes in the same file.
+
 ### 7. Chat — browse prior AI conversations
 
 <p align="center">
@@ -370,6 +372,8 @@ c3 permissions show
 c3 permissions standard
 ```
 
+Applying or switching a tier **preserves your own `allow`/`deny` rules** (and keys like `ask`/`defaultMode`) — only C3-managed entries are replaced. Likewise, C3 never clobbers your other entries in `.mcp.json` (only its own `c3` server) or the hooks you've added to `settings.local.json` (only its own hooks).
+
 ---
 
 ## Benchmarks

{code_context_control-2.36.0.dist-info → code_context_control-2.37.0.dist-info}/RECORD

@@ -1,6 +1,6 @@
 cli/__init__.py,sha256=ec66drCZGNMRU4V6ov0zVhYZph1us12Vn8OvG_LJyRY,22
 cli/_hook_utils.py,sha256=1_hTA-Wz62xB8jnSAH4C5TfCkrwEP0g2kq_-oRfQLm4,3724
-cli/c3.py,sha256=wNzXp_GKTIenTJqgxmEL9kFRG8ukoyE0BHPVK1YPH2w,295249
+cli/c3.py,sha256=X9HResiGmUELIVlz6uosit35OSCCKeJwuwr02gzuGBM,297611
 cli/docs.html,sha256=JgtBFUuUkvmYowPREYiGhhcRbB5e2UjkRc00MIF0hsU,143653
 cli/edits.html,sha256=UjAhoCmBmQ89cklGvJqzC6eyNP2tc8H6T-e01DVkLvE,43418
 cli/hook_auto_snapshot.py,sha256=amtliVDzKUQr6KBR0pdBA8vXghAV-gKr19jBaJVnP_w,5006
@@ -15,18 +15,18 @@ cli/hook_read.py,sha256=M5l_SU899O72tZe3j4YQJJKNb1-xulvKOj8XZjJzwYU,8021
 cli/hook_session_stats.py,sha256=a1OKi9kmiXRI2qieY_Uq14xRxdXQTQu9WVzDTUlI0GQ,1897
 cli/hook_terse_advisor.py,sha256=pD7Bap7OYOKqtYz7cX8nWSRLH7ook-tSD2Ov2MNp_sA,5907
 cli/hub.html,sha256=Hl-XPZGT1mMiKrbX9c5OsEw6mXEumwIB3vp1WlWaplM,183966
-cli/hub_server.py,sha256=b1O3hTDd051cBG15xU3wKWGiyNC1SWIFlndpVeKIBw4,60110
+cli/hub_server.py,sha256=Zo---712ynP83XWB_aZb45b9XcQmzs9EGp8wwyRIGLU,60207
 cli/mcp_proxy.py,sha256=92htuT-p0j-cDTbyqlIJpGoQ85_Aw7UuB8L_Toi_u20,17511
 cli/mcp_server.py,sha256=iYUB6rfGjNuiNQP-GecuXyMVa1CEihtu4dV7PhRHWqg,32549
-cli/server.py,sha256=PkaUwLXPUOAjAmnYQuazMquqQ-qmnDuF1WO-1aHNgg4,120376
+cli/server.py,sha256=tOgLZvB_i7RluK3qwORqhrhTz1DVL3VVAIWu9f55ysg,120292
 cli/ui.html,sha256=xcdt74nlFEXx-0Bx6-Okw-WSVZPAXL0iukxU0ytI6CA,5694
 cli/ui_legacy.html,sha256=cI8tC6RKmE2NIJOcsu7CY-zT4VznjcbD6NTjxb_fvUY,378460
 cli/ui_nano.html,sha256=UAwQ6bbTOXAoGq191AZ7slhngR9edJSa3IhqpynveDg,27740
 cli/commands/__init__.py,sha256=0Z8MABNzwSFJGT4Xv9R5AJVR8XxraTsuVTz5b0bShmo,38
-cli/commands/common.py,sha256=3fXTjFCIo7q-Tr6KtxfjuLPu-Apl7PeS5mN9B5-bqkc,11494
+cli/commands/common.py,sha256=8_uYFWcJBXMscPmvQEMYOwYXZidwD7Of9j9fiD00g6Q,11272
 cli/commands/parser.py,sha256=unu8jkTocf3AoOSiEAlw_qta_2K7sQqg9BmluTzOKO4,22968
 cli/guide/bitbucket.html,sha256=5HrLDm6Ue-AJZ81bqWaSp2nSfxaRdEjHFY29P7plLXA,33350
-cli/guide/getting-started.html,sha256=t1CNa1nVcuUrinuTYJAVLmKhJFlDtO1-DjimWnABTgE,17461
+cli/guide/getting-started.html,sha256=F3AaF2HVfeg6eKO25p_vPogr_i1hvkjIZVggIJFWTl0,18829
 cli/guide/index.html,sha256=sAk4Z7Xrlw7_F_Gbxn3lhZeT7hydrp1aENhMQ_9msgU,19861
 cli/guide/oracle.html,sha256=-5RtRTLV0JUVerjIayEftQdcqg8j_-X0ail8lVVJfOE,21897
 cli/guide/shared.css,sha256=Mmm7W6aYxrkDq2RPOcyXiQFYGR-yB3auwX1uIWi6C74,15967
@@ -64,7 +64,7 @@ cli/ui/components/memory.js,sha256=v5IsHTxLHpXX4xCsUaZ_UPprZEabdgP4jiWc298iV2U,2
 cli/ui/components/sessions.js,sha256=FIKtil76B8tCkAmcFV7hlj6GQ_DCJK2jCzvEmdK7NBE,30837
 cli/ui/components/settings.js,sha256=8LVTV2TQl9tcRXhXbtBEJOCBdiyk-x2QASoVYZUAuEA,71442
 cli/ui/components/sidebar.js,sha256=cAY_jwYB-o1X_wWn__VXlG4IegVObuE3NmVsuFWqxtg,7417
-code_context_control-2.36.0.dist-info/licenses/LICENSE,sha256=l8Kh5QCNWNvR6kIt8L0BUZvc2LAFiHv2c-FnsGnUZf4,11301
+code_context_control-2.37.0.dist-info/licenses/LICENSE,sha256=l8Kh5QCNWNvR6kIt8L0BUZvc2LAFiHv2c-FnsGnUZf4,11301
 core/__init__.py,sha256=TSDCEcM4V7gcZVM3w2ykJaqEUch4Dkon-rivV17T73s,2501
 core/config.py,sha256=knSre16IF_6FZ-pctHWbA5mZdjCEJUF5rsdzZxWg4zU,13002
 core/ide.py,sha256=9LzsDVK2LL8RVpL40l6oNGiasZ3D8OCU_9i9A0gJKBo,6876
@@ -99,7 +99,7 @@ services/auto_memory.py,sha256=v__ZS1e68533_Yv491mZtvuZnheC63q6_uTvWhBw3Lw,14290
 services/benchmark_dashboard.py,sha256=iR-DnqnoKbqHMJ4d-ZkIvJBYfzwTa7r-jzO6j2BYDfQ,27711
 services/bitbucket_client.py,sha256=v8xGEcnIEmURvcg38XwmiCGh7-_QnjhAJEb0te_yZzQ,16107
 services/bitbucket_credentials.py,sha256=2qLA9pQMol4y95y4DJMNBsBBPUsJQCKbLFo2iiCnfvI,7364
-services/claude_md.py,sha256=iL0vUQw-5lxSQehNPvhlkUmcGPeMSCcZqP4OYG_qoYk,35092
+services/claude_md.py,sha256=FiFDyeAQ10baRCYH74QAn-UixVi_rgn-_6yP70wCRS8,40278
 services/compressor.py,sha256=uSVyTYfvxFrRYupzyKj-HzkBP0RwARrGYFz_DnMSEaM,25169
 services/context_snapshot.py,sha256=s_klEr1SJYM9u-anMmnoemsYuIF_KUWBjz1zUo0wPgU,15662
 services/conversation_store.py,sha256=vPiMiKAE22RCBSSphgGH9Vx-lPV45SmttOwgVVWahL4,33398
@@ -132,7 +132,7 @@ services/retrieval_broker.py,sha256=9X67VZ_6AkbAzopHuuMFKmP4CGZLnW576kjSKMenBnw,
 services/router.py,sha256=Cz10nx2fKTbaGn14mSBePWIDrw5rdcs_1JFYXeik084,15626
 services/runtime.py,sha256=SOUizCDW1FFTDCoaZ1Njozjp25Bhah7lR1f0WYscaw0,11361
 services/session_benchmark.py,sha256=qw_vtDim1hvFdM8Me5EsgU9pTuJhzRjQmh6m7DDnXWY,98989
-services/session_manager.py,sha256=Px7RpTS6zDSuxj2O87o-7tkR8l-faMZxBX1gd5RLHfo,43837
+services/session_manager.py,sha256=vWgvYGForO7W2wZzBC8QNaBQyUR2VIlVuC2wpmUqIOc,43735
 services/session_preloader.py,sha256=DsTAXMKVtrX9yu1sEFojYDi9-jkSAj1Ylt9JTy57Dow,9883
 services/text_index.py,sha256=r3o4CobTG9jAO9PWazgbWYLY9oi_FgEJ3xwEXrF4KM0,2783
 services/tool_classifier.py,sha256=Fgvq0ZcpnCskwtO8a3YI1MiecPNnw6UbPyJQIUwgfiQ,6512
@@ -163,8 +163,8 @@ tui/screens/search_view.py,sha256=MMHjVdlk3HZSuDBSvq8IGrqv_Mh5Us6YqXQ80bcWSMk,19
 tui/screens/session_view.py,sha256=eZ1eDwHTvPOck1wCCviixtOaCxIkBT_95ytNNNriGNA,5991
 tui/screens/stats.py,sha256=p81PjzdaIv7hllb8f45-rlVe4lJZwSdIMqu7e86_u5s,6223
 tui/screens/ui_view.py,sha256=1QJCgLh2YfgWIpvzRG1KOGXYEaOYX6ojN61Azjf2oX0,2125
-code_context_control-2.36.0.dist-info/METADATA,sha256=UlOzUNxejptWMtekvU7AguyY779ubiQabBrlJ5OKCnI,20668
-code_context_control-2.36.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-code_context_control-2.36.0.dist-info/entry_points.txt,sha256=7kX_WUsDCF2hbXzvbNyscyaBb9AeA-DJY5v_5hN0DlU,93
-code_context_control-2.36.0.dist-info/top_level.txt,sha256=wRt41zBybVF3qAiNXHz9BURbkKvUvfhmWWtKMhaw6eE,29
-code_context_control-2.36.0.dist-info/RECORD,,
+code_context_control-2.37.0.dist-info/METADATA,sha256=ztn-S1aTmKvYltI1Rw0hhPXNGl9t34fgqbVkd8tZmm0,21230
+code_context_control-2.37.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+code_context_control-2.37.0.dist-info/entry_points.txt,sha256=7kX_WUsDCF2hbXzvbNyscyaBb9AeA-DJY5v_5hN0DlU,93
+code_context_control-2.37.0.dist-info/top_level.txt,sha256=wRt41zBybVF3qAiNXHz9BURbkKvUvfhmWWtKMhaw6eE,29
+code_context_control-2.37.0.dist-info/RECORD,,

services/claude_md.py

@@ -66,6 +66,87 @@ Plan mode: all c3_* read tools work normally — skip edit/delegate steps.
 DO NOT: start with native Read/Grep/Glob/Edit, skip c3_validate, read full files without c3_compress."""
 
 
+# --- C3-managed instruction block ---------------------------------------------
+# C3-generated content for project instruction docs (CLAUDE.md / AGENTS.md /
+# GEMINI.md / copilot-instructions.md) is wrapped in these sentinels so that
+# regenerating the docs never clobbers user-written content. Mirrors the
+# non-destructive merge used for the global ~/.claude/CLAUDE.md.
+C3_BLOCK_BEGIN = (
+    "<!-- C3:BEGIN — auto-generated by C3. Do NOT edit inside this block; it is "
+    "regenerated on every `c3 install-mcp` / `c3 init`. Your content OUTSIDE the "
+    "block is preserved. -->"
+)
+C3_BLOCK_END = "<!-- C3:END -->"
+C3_BLOCK_HEADING = "# C3 — Managed Instructions"
+
+# First line of every legacy (marker-less) C3 instruction doc. Used to detect
+# and replace pre-marker C3 content instead of leaving it duplicated above the
+# new block. Both the compact and nano workflows start with this heading.
+C3_LEGACY_FIRST_LINE = "## C3 Tools"
+
+
+def wrap_c3_block(content: str) -> str:
+    """Wrap C3-generated instruction ``content`` in the managed-section markers."""
+    body = content.strip()
+    return f"{C3_BLOCK_BEGIN}\n{C3_BLOCK_HEADING}\n\n{body}\n{C3_BLOCK_END}"
+
+
+def merge_c3_block(existing: str, new_block: str) -> str:
+    """Merge a freshly wrapped C3 block into ``existing`` file content.
+
+    Non-destructive, mirroring the global ~/.claude/CLAUDE.md behaviour:
+
+    1. If the C3 markers are already present, replace only the marked region and
+       preserve everything the user wrote before and after it.
+    2. Legacy (marker-less) C3 docs are recognised by their leading
+       ``## C3 Tools`` heading and replaced wholesale, while any trailing
+       ``# User Notes`` section (the pre-marker convention) is preserved.
+    3. A genuine, user-authored file with neither markers nor the legacy
+       signature is never overwritten — the C3 block is appended below it.
+    """
+    new_block = new_block.strip()
+
+    # 1. Markers present → surgical in-place replacement.
+    if C3_BLOCK_BEGIN in existing and C3_BLOCK_END in existing:
+        start = existing.index(C3_BLOCK_BEGIN)
+        end = existing.index(C3_BLOCK_END) + len(C3_BLOCK_END)
+        before = existing[:start].rstrip()
+        after = existing[end:].lstrip()
+        parts = [p for p in (before, new_block, after) if p]
+        return "\n\n".join(parts) + "\n"
+
+    # 2. Legacy marker-less C3 doc → replace head, keep trailing user notes.
+    if existing.lstrip().startswith(C3_LEGACY_FIRST_LINE):
+        tail = ""
+        if "# User Notes" in existing:
+            tail = existing[existing.index("# User Notes"):].strip()
+        parts = [new_block] + ([tail] if tail else [])
+        return "\n\n".join(parts) + "\n"
+
+    # 3. Genuine user-authored file → preserve fully, append the C3 block.
+    head = existing.rstrip()
+    parts = [head, new_block] if head else [new_block]
+    return "\n\n".join(parts) + "\n"
+
+
+def write_c3_instruction_doc(path, content: str) -> str:
+    """Write a C3-generated instruction doc without clobbering user content.
+
+    Wraps ``content`` in the C3 managed block and merges it into any existing
+    file via :func:`merge_c3_block`. Returns the exact text written to disk.
+    """
+    p = Path(path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    block = wrap_c3_block(content)
+    if p.exists():
+        existing = p.read_text(encoding="utf-8", errors="replace")
+        final = merge_c3_block(existing, block)
+    else:
+        final = block.rstrip() + "\n"
+    p.write_text(final, encoding="utf-8")
+    return final
+
+
 class ClaudeMdManager:
     """Manages instructions file generation, analysis, compaction, and insight promotion.
 
@@ -285,14 +366,17 @@ class ClaudeMdManager:
         }
 
     def compact(self, target_lines: int = 150) -> dict:
-        """Compact existing CLAUDE.md to fit within target line count."""
+        """Compact existing CLAUDE.md to fit within target line count.
+
+        When the file uses the C3 managed-block markers, only the inner C3
+        body is compacted and the block is re-wrapped, so the markers, the
+        ``# C3`` heading, and any user content outside the block survive.
+        """
         current = self._read_current()
         if current is None:
             return {"error": f"No {self.instructions_file} found on disk. Use CLI `c3 claudemd generate` to preview, then `c3 claudemd save` to persist before compacting."}
 
         original_metrics = self._count_metrics(current)
-        sections = self._parse_sections(current)
-        lines = current.split('\n')
 
         # If already under target, no compaction needed
         if original_metrics["lines"] <= target_lines:
@@ -305,6 +389,54 @@ class ClaudeMdManager:
                 "actions": ["Already under target — no compaction needed."],
             }
 
+        # Isolate the C3 managed block so its markers, the # C3 heading, and
+        # any surrounding user content are preserved verbatim across compaction.
+        before = after = ""
+        inner = current
+        has_block = C3_BLOCK_BEGIN in current and C3_BLOCK_END in current
+        if has_block:
+            start = current.index(C3_BLOCK_BEGIN)
+            end = current.index(C3_BLOCK_END) + len(C3_BLOCK_END)
+            before = current[:start]
+            after = current[end:]
+            inner = current[start + len(C3_BLOCK_BEGIN):end - len(C3_BLOCK_END)].strip()
+            if inner.startswith(C3_BLOCK_HEADING):
+                inner = inner[len(C3_BLOCK_HEADING):].lstrip("\n")
+
+        compacted_inner, actions = self._compact_sections(inner, target_lines)
+
+        if has_block:
+            pieces = []
+            if before.strip():
+                pieces.append(before.strip())
+            pieces.append(wrap_c3_block(compacted_inner))
+            if after.strip():
+                pieces.append(after.strip())
+            content = "\n\n".join(pieces) + "\n"
+        else:
+            content = compacted_inner
+
+        compacted_metrics = self._count_metrics(content)
+
+        if not actions:
+            actions.append("No compaction opportunities found.")
+
+        return {
+            "content": content,
+            "original_lines": original_metrics["lines"],
+            "compacted_lines": compacted_metrics["lines"],
+            "original_tokens": original_metrics["tokens"],
+            "compacted_tokens": compacted_metrics["tokens"],
+            "actions": actions,
+        }
+
+    def _compact_sections(self, text: str, target_lines: int) -> tuple:
+        """Section-based compaction of an instruction-doc body.
+
+        Returns ``(content, actions)``. Operates purely on ``text``; callers
+        handle any C3 managed-block wrapping.
+        """
+        sections = self._parse_sections(text)
         actions = []
 
         # Step 1: Compress session history — keep last 3, one-line summaries
@@ -318,12 +450,12 @@ class ClaudeMdManager:
         # Step 2: Deduplicate — remove exact duplicate lines (excluding blank lines and headers)
         seen_lines = set()
         deduped_sections = {}
-        for name, text in sections.items():
+        for name, sect_text in sections.items():
             if name in ("User Notes", "C3 — Token-Saving Workflow (MUST FOLLOW)"):
-                deduped_sections[name] = text
+                deduped_sections[name] = sect_text
                 continue
             new_lines = []
-            for line in text.split('\n'):
+            for line in sect_text.split('\n'):
                 stripped = line.strip()
                 if not stripped or stripped.startswith('#'):
                     new_lines.append(line)
@@ -350,20 +482,7 @@ class ClaudeMdManager:
                 actions.append("Reduced project structure tree depth")
 
         # Reassemble
-        content = self._reassemble_sections(sections)
-        compacted_metrics = self._count_metrics(content)
-
-        if not actions:
-            actions.append("No compaction opportunities found.")
-
-        return {
-            "content": content,
-            "original_lines": original_metrics["lines"],
-            "compacted_lines": compacted_metrics["lines"],
-            "original_tokens": original_metrics["tokens"],
-            "compacted_tokens": compacted_metrics["tokens"],
-            "actions": actions,
-        }
+        return self._reassemble_sections(sections), actions
 
     def get_promotion_candidates(self, min_relevance: int = 2) -> dict:
         """Find facts and patterns worth promoting into CLAUDE.md."""

services/session_manager.py

@@ -465,19 +465,14 @@ class SessionManager:
         else:
             content = auto_content
 
+        # Wrap C3-generated content in the managed block so regenerating the
+        # doc never clobbers user-written content outside it (mirrors global
+        # ~/.claude/CLAUDE.md). Legacy files and bare user files are preserved.
+        from services.claude_md import write_c3_instruction_doc
+
         output_path = self.project_path / instructions_file
-        output_path.parent.mkdir(parents=True, exist_ok=True)
-
-        # Check for existing file
-        if output_path.exists():
-            existing = output_path.read_text(encoding="utf-8")
-            # Preserve user-written sections
-            if "# User Notes" in existing:
-                user_section = existing[existing.index("# User Notes"):]
-                content += f"\n\n{user_section}"
-
-        output_path.write_text(content, encoding="utf-8")
-        tokens = count_tokens(content)
+        final = write_c3_instruction_doc(output_path, content)
+        tokens = count_tokens(final)
 
         return {
             "path": str(output_path),