claudekit-codex-sync 0.1.0 → 0.2.1

package/plans/260223-1310-v02-cli-redesign-cleanup/phase-05-safety-tests-docs.md

@@ -0,0 +1,206 @@
+# Phase 5 — Safety Fixes + Tests + Docs
+
+## Overview
+- Priority: P1
+- Status: [x] Implemented (release ops pending)
+- Estimated: 30 min
+
+## Code Changes
+
+### [MODIFY] `src/claudekit_codex_sync/path_normalizer.py`
+
+**Add defensive mkdir in `convert_agents_md_to_toml()` (after line ~113):**
+
+```python
+def convert_agents_md_to_toml(*, codex_home: Path, dry_run: bool) -> int:
+    """Convert ClaudeKit agent .md files to Codex .toml format."""
+    from .constants import (
+        CLAUDE_MODEL_REASONING_EFFORT,
+        CLAUDE_TO_CODEX_MODELS,
+        READ_ONLY_AGENT_ROLES,
+    )
+
+    agents_dir = codex_home / "agents"
+    if not agents_dir.exists():
+        return 0
+
+    # Defensive: ensure target dir exists for writing .toml
+    if not dry_run:
+        agents_dir.mkdir(parents=True, exist_ok=True)
+
+    # ... rest unchanged
+```
+
+### [NEW] `tests/test_clean_target.py`
+
+```python
+"""Tests for clean_target module."""
+
+import json
+from pathlib import Path
+
+from claudekit_codex_sync.clean_target import clean_target
+
+
+def test_clean_removes_agents(tmp_path: Path):
+    """Clean removes agents dir."""
+    agents = tmp_path / "agents"
+    agents.mkdir()
+    (agents / "planner.toml").write_text("model = 'test'")
+    (agents / "researcher.toml").write_text("model = 'test'")
+
+    removed = clean_target(tmp_path, dry_run=False)
+    assert not agents.exists()
+    assert removed >= 2
+
+
+def test_clean_keeps_venv(tmp_path: Path):
+    """Clean keeps skills/.venv intact."""
+    skills = tmp_path / "skills"
+    skills.mkdir()
+    venv = skills / ".venv"
+    venv.mkdir()
+    (venv / "bin").mkdir()
+    (venv / "bin" / "python3").write_text("#!/usr/bin/env python3")
+    skill = skills / "my-skill"
+    skill.mkdir()
+    (skill / "SKILL.md").write_text("# test")
+
+    clean_target(tmp_path, dry_run=False)
+    assert venv.exists(), ".venv should survive cleaning"
+    assert not skill.exists(), "skill dirs should be removed"
+
+
+def test_clean_dry_run(tmp_path: Path):
+    """Dry run counts but doesn't delete."""
+    agents = tmp_path / "agents"
+    agents.mkdir()
+    (agents / "test.toml").write_text("x = 1")
+
+    removed = clean_target(tmp_path, dry_run=True)
+    assert removed >= 1
+    assert agents.exists(), "dry-run should not delete"
+
+
+def test_clean_removes_registry(tmp_path: Path):
+    """Clean clears sync registry."""
+    registry = tmp_path / ".claudekit-sync-registry.json"
+    registry.write_text(json.dumps({"version": 1}))
+
+    clean_target(tmp_path, dry_run=False)
+    assert not registry.exists()
+```
+
+### [NEW] `tests/test_cli_args.py`
+
+```python
+"""Tests for CLI argument parsing."""
+
+import sys
+from unittest.mock import patch
+
+from claudekit_codex_sync.cli import parse_args
+
+
+def test_default_args():
+    """Default: project scope, no flags."""
+    with patch.object(sys, "argv", ["ckc-sync"]):
+        args = parse_args()
+    assert not args.global_scope
+    assert not args.fresh
+    assert not args.force
+    assert not args.mcp
+    assert not args.no_deps
+    assert not args.dry_run
+    assert args.zip_path is None
+    assert args.source is None
+
+
+def test_global_flag():
+    """'-g' enables global scope."""
+    with patch.object(sys, "argv", ["ckc-sync", "-g"]):
+        args = parse_args()
+    assert args.global_scope
+
+
+def test_fresh_flag():
+    """'-f' enables fresh clean."""
+    with patch.object(sys, "argv", ["ckc-sync", "-f"]):
+        args = parse_args()
+    assert args.fresh
+
+
+def test_combined_short_flags():
+    """'-g -f -n' all work together."""
+    with patch.object(sys, "argv", ["ckc-sync", "-g", "-f", "-n"]):
+        args = parse_args()
+    assert args.global_scope
+    assert args.fresh
+    assert args.dry_run
+
+
+def test_zip_flag():
+    """'--zip' sets zip path and implies zip mode."""
+    with patch.object(sys, "argv", ["ckc-sync", "--zip", "test.zip"]):
+        args = parse_args()
+    assert str(args.zip_path) == "test.zip"
+
+
+def test_mcp_flag():
+    """'--mcp' includes MCP skills."""
+    with patch.object(sys, "argv", ["ckc-sync", "--mcp"]):
+        args = parse_args()
+    assert args.mcp
+```
+
+### [MODIFY] Docs
+
+Update these files to reflect new CLI:
+- `README.md` — new command name, flags, examples
+- `docs/installation-guide.md` — new command, npm install
+- `docs/codebase-summary.md` — new modules (clean_target.py), removed scripts/
+
+**README.md Quick Start update:**
+```markdown
+## Quick Start
+
+```bash
+npm install -g claudekit-codex-sync
+
+# Project sync (to ./.codex/)
+ckc-sync
+
+# Global sync (to ~/.codex/)
+ckc-sync -g
+
+# Fresh re-sync
+ckc-sync -g -f
+
+# Preview
+ckc-sync -g -n
+```
+```
+
+## Verification
+
+```bash
+# Run all tests
+PYTHONPATH=src python3 -m pytest tests/ -v
+
+# Expected: 11 existing + 10 new = 21 tests passing
+
+# Lint
+python3 -m py_compile src/claudekit_codex_sync/*.py
+
+# Full sync test
+ckc-sync -g -f    # fresh global sync
+ckc-sync -n       # project dry-run
+```
+
+## Todo
+- [x] Add defensive mkdir in `path_normalizer.py`
+- [x] Create `tests/test_clean_target.py` (4 tests)
+- [x] Create `tests/test_cli_args.py` (6 tests)
+- [x] Update `README.md`, `docs/installation-guide.md`, `docs/codebase-summary.md`
+- [x] Run all tests
+- [ ] `git commit && git push && npm publish`

package/plans/260223-1310-v02-cli-redesign-cleanup/plan.md

@@ -0,0 +1,18 @@
+# v0.2 Plan — CLI Redesign + Cleanup
+
+## Overview
+
+| Phase | What | Files | Status |
+|---|---|---|---|
+| 1 | Delete dead code + trim constants | `scripts/`, `constants.py` | [x] Complete |
+| 2 | CLI redesign (ckc-sync, 8 flags) | `cli.py`, `clean_target.py`, `package.json`, `bin/` | [x] Implemented (local install step pending) |
+| 3 | Symlink venv | `dep_bootstrapper.py` | [x] Complete |
+| 4 | Wire unused functions + backup | `cli.py`, `asset_sync_dir.py`, `sync_registry.py` | [x] Complete |
+| 5 | Safety fixes + tests + docs | `path_normalizer.py`, tests, docs | [x] Implemented (release ops pending) |
+
+Details: see phase files.
+
+## Tracking Notes
+- Validation run on 2026-02-23: `python3 -m py_compile src/claudekit_codex_sync/*.py` passed.
+- Validation run on 2026-02-23: `PYTHONPATH=src python3 -m pytest tests/ -q` passed (`21 passed`).
+- Pending non-implementation ops: `npm install -g .`, `git commit && git push && npm publish`.

package/plans/reports/planner-260223-v02-cli-redesign-cleanup-validation.md

@@ -0,0 +1,95 @@
+# Validation + Execution Checklist
+
+Date: 2026-02-23  
+Plan: `plans/260223-1310-v02-cli-redesign-cleanup/`
+
+## Validation Verdict
+Conditionally executable. Use with preflight fixes first.
+
+### Baseline (current repo)
+- `PYTHONPATH=src python3 -m pytest tests/ -q` -> 11 passed.
+- `python3 -m py_compile src/claudekit_codex_sync/*.py` -> pass.
+
+## Blocking Conflicts (Resolve First)
+1. **Agent pipeline mismatch (high)**  
+Plan says remove `agents` from assets, but conversion reads only `codex_home/agents`. Current sync writes assets under `codex_home/claudekit/*`. If `agents` removed, agent conversion/registration becomes impossible.  
+Refs: `plans/260223-1310-v02-cli-redesign-cleanup/phase-01-delete-dead-code.md:53`, `plans/260223-1310-v02-cli-redesign-cleanup/phase-01-delete-dead-code.md:58`, `src/claudekit_codex_sync/asset_sync_dir.py:21`, `src/claudekit_codex_sync/path_normalizer.py:83`, `src/claudekit_codex_sync/config_enforcer.py:112`.
+2. **Rules/CLAUDE removal conflicts with downstream references (high)**  
+Plan drops `rules` + `CLAUDE.md`, but generated `AGENTS.md` and path replacements still reference them.  
+Refs: `plans/260223-1310-v02-cli-redesign-cleanup/phase-01-delete-dead-code.md:53`, `plans/260223-1310-v02-cli-redesign-cleanup/phase-01-delete-dead-code.md:60`, `templates/agents-md.md:40`, `src/claudekit_codex_sync/constants.py:29`, `src/claudekit_codex_sync/constants.py:68`.
+3. **`--force` semantic collision (high)**  
+Phase 2 maps `--force` to `include_conflicts`, mixing overwrite semantics with conflict-skill inclusion.  
+Refs: `plans/260223-1310-v02-cli-redesign-cleanup/phase-02-cli-redesign.md:114`, `src/claudekit_codex_sync/cli.py:40`, `src/claudekit_codex_sync/asset_sync_dir.py:73`, `src/claudekit_codex_sync/asset_sync_zip.py:90`.
+4. **Registry wiring incomplete in plan text (medium)**  
+Phase 4 adds `registry`/`force` params to `sync_assets_from_dir`, but phase flow does not require passing these from CLI callsite; backup logic can remain inert.  
+Refs: `plans/260223-1310-v02-cli-redesign-cleanup/phase-04-wire-unused-functions.md:39`, `src/claudekit_codex_sync/cli.py:83`.
+5. **Phase-order runtime break risk (medium)**  
+Phase 2 removes `include_test_deps` call before Phase 3 changes function signature. If implemented separately, bootstrap call breaks.  
+Refs: `plans/260223-1310-v02-cli-redesign-cleanup/phase-02-cli-redesign.md:203`, `src/claudekit_codex_sync/dep_bootstrapper.py:17`.
+6. **Test count in plan is wrong (low)**  
+Plan expects 17 tests after adding 10; actual target should be 21 (11 existing + 10 new).  
+Ref: `plans/260223-1310-v02-cli-redesign-cleanup/phase-05-safety-tests-docs.md:190`.
+
+## Operationalized Execution Checklist
+
+### Gate 0: Scope Lock (must pass before coding)
+- [ ] Decide asset contract for `agents`, `rules`, `CLAUDE.md` (keep vs remove) and update all dependent docs/templates/replacements consistently.
+- [ ] Separate flags: keep `--force` for overwrite behavior only; do not reuse for conflict-skill include.
+- [ ] Decide compatibility policy for legacy flags (`--source-mode`, `--skip-verify`, `--skip-agent-toml`, `--include-hooks`, `--respect-edits`).
+
+Dependencies: none.  
+Risk: High if skipped (functional regression + broken agent/rules references).
+
+### Phase A: CLI Redesign Skeleton (safe-first)
+- [ ] Add new command surface (`ckc-sync` alias) in `package.json` while retaining `ck-codex-sync`.
+- [ ] Introduce `clean_target.py` and `-f/--fresh` flow.
+- [ ] Wire `register_agents()` call in CLI.
+- [ ] Keep bootstrap signature compatibility until Phase B complete (or ship both changes atomically).
+
+Dependencies: Gate 0.  
+Risk: Medium (breaking CLI behavior if compatibility policy unclear).
+
+### Phase B: Dependency Bootstrap Symlink
+- [ ] Implement symlink-first venv strategy with fallback creation.
+- [ ] Ensure broken symlink handling + existing real `.venv` short-circuit.
+- [ ] Validate Linux/WSL behavior with dry-run and real run.
+
+Dependencies: Phase A (if CLI flags change), or atomic with Phase A for signature safety.  
+Risk: Medium (environment-specific symlink behavior).
+
+### Phase C: Registry + Respect-Edits Wiring
+- [ ] Update `sync_assets_from_dir()` to call `maybe_backup()`/`update_entry()`.
+- [ ] Pass `registry` and overwrite policy from CLI callsite explicitly.
+- [ ] Add defensive mkdir in `save_registry()`.
+- [ ] Validate skip/backup/overwrite paths with deterministic fixtures.
+
+Dependencies: Gate 0 flag semantics + Phase A CLI args.  
+Risk: High (data-loss risk if overwrite path wrong).
+
+### Phase D: Safety + Tests + Docs
+- [ ] Add `tests/test_clean_target.py` (4 tests) and `tests/test_cli_args.py` (6 tests).
+- [ ] Correct expected total test count to 21.
+- [ ] Update `README.md`, `docs/installation-guide.md`, `docs/codebase-summary.md`, `docs/system-architecture.md` to exact final behavior.
+- [ ] Run: `pytest`, `py_compile`, and CLI smoke matrix for both command aliases.
+
+Dependencies: Phases A-C complete.  
+Risk: Medium (doc/runtime drift if done early).
+
+### Phase E: Release Gate
+- [ ] Confirm no stale references to removed flags/assets.
+- [ ] Confirm backward compatibility decision is documented.
+- [ ] Package/install smoke: `npm install -g .`, `ckc-sync --help`, `ck-codex-sync --help`.
+
+Dependencies: Phase D complete.  
+Risk: Low.
+
+## Risk Notes (Condensed)
+- **Data safety:** Overwrite logic currently under-specified; treat as release blocker.
+- **Architecture consistency:** Asset contract changes touch constants, templates, docs, runtime behavior; enforce single source of truth.
+- **Breaking CLI UX:** Removing flags without transition policy may break existing automation.
+- **Cross-platform:** Symlink behavior varies; keep fallback path mandatory.
+
+## Unresolved Questions
+1. Should `rules` and `CLAUDE.md` remain first-class synced assets in v0.2, given `templates/agents-md.md` references?
+2. Should agent `.md` files be synced to `codex_home/agents` (for conversion) instead of `codex_home/claudekit/agents`, or should conversion read from `claudekit/agents`?
+3. Should legacy flags remain temporarily as deprecated aliases, or be removed immediately in v0.2?

package/plans/reports/project-manager-260223-v02-cli-redesign-cleanup-finalization.md

@@ -0,0 +1,28 @@
+# Completion Report
+
+Date: 2026-02-23
+Plan: `plans/260223-1310-v02-cli-redesign-cleanup/`
+Role: project-manager fallback
+
+## What Updated
+- Marked implemented phases and todos complete in:
+  - `plans/260223-1310-v02-cli-redesign-cleanup/plan.md`
+  - `plans/260223-1310-v02-cli-redesign-cleanup/phase-01-delete-dead-code.md`
+  - `plans/260223-1310-v02-cli-redesign-cleanup/phase-02-cli-redesign.md`
+  - `plans/260223-1310-v02-cli-redesign-cleanup/phase-03-symlink-venv.md`
+  - `plans/260223-1310-v02-cli-redesign-cleanup/phase-04-wire-unused-functions.md`
+  - `plans/260223-1310-v02-cli-redesign-cleanup/phase-05-safety-tests-docs.md`
+- Corrected Phase 5 expected test count from 17 to 21.
+
+## Validation Evidence
+- `python3 -m py_compile src/claudekit_codex_sync/*.py` -> pass
+- `PYTHONPATH=src python3 -m pytest tests/ -q` -> `21 passed`
+- Symlink smoke check for Phase 3 (`_try_symlink_venv`) -> source exists, symlink created in temp codex home
+
+## Remaining Pending (Non-implementation Ops)
+- Phase 2: `npm install -g .` (local command registration step)
+- Phase 5: `git commit && git push && npm publish` (release workflow)
+
+## Unresolved Questions
+1. Do you want plan tracking to treat local install/release commands as required completion gates, or keep them tracked as post-implementation ops?
+2. Should I also update roadmap/changelog docs to mirror this finalized plan status?

package/src/claudekit_codex_sync/asset_sync_dir.py

@@ -7,7 +7,8 @@ from pathlib import Path
 from typing import Dict
 
 from .constants import ASSET_DIRS, ASSET_FILES, CONFLICT_SKILLS, EXCLUDED_SKILLS_ALWAYS, MCP_SKILLS
-from .utils import is_excluded_path, write_bytes_if_changed
+from .sync_registry import check_user_edit, maybe_backup, update_entry
+from .utils import compute_hash, create_backup, is_excluded_path, write_bytes_if_changed
 
 
 def sync_assets_from_dir(
@@ -16,11 +17,14 @@ def sync_assets_from_dir(
     codex_home: Path,
     include_hooks: bool,
     dry_run: bool,
+    registry: dict | None = None,
+    force: bool = True,
 ) -> Dict[str, int]:
     """Sync non-skill assets from live directory."""
     claudekit_dir = codex_home / "claudekit"
-    claudekit_dir.mkdir(parents=True, exist_ok=True)
-    added = updated = 0
+    if not dry_run:
+        claudekit_dir.mkdir(parents=True, exist_ok=True)
+    added = updated = skipped = 0
 
     for dirname in ASSET_DIRS:
         src_dir = source / dirname
@@ -34,35 +38,81 @@ def sync_assets_from_dir(
             if not src_file.is_file() or is_excluded_path(src_file.parts):
                 continue
             rel = src_file.relative_to(src_dir)
+            rel_path = f"claudekit/{dirname}/{rel}"
             dst = dst_dir / rel
+
+            if not force and registry and dst.exists():
+                entry = registry.get("entries", {}).get(rel_path)
+                if entry:
+                    if dry_run and check_user_edit(entry, dst):
+                        skipped += 1
+                        print(f"skip(user-edit): {rel_path}")
+                        continue
+                    backup = maybe_backup(registry, rel_path, dst, respect_edits=True)
+                    if backup:
+                        skipped += 1
+                        print(f"skip(user-edit): {rel_path}")
+                        continue
+                elif compute_hash(src_file) != compute_hash(dst):
+                    if dry_run:
+                        print(f"[dry-run] backup(untracked): {rel_path}")
+                    else:
+                        backup = create_backup(dst)
+                        print(f"backup(untracked): {rel_path} -> {backup.name}")
+
             data = src_file.read_bytes()
             mode = src_file.stat().st_mode & 0o777 if src_file.stat().st_mode & 0o111 else None
             changed, is_added = write_bytes_if_changed(dst, data, mode=mode, dry_run=dry_run)
             if changed:
                 if is_added:
                     added += 1
-                    print(f"add: claudekit/{dirname}/{rel}")
+                    print(f"add: {rel_path}")
                 else:
                     updated += 1
-                    print(f"update: claudekit/{dirname}/{rel}")
+                    print(f"update: {rel_path}")
+            if registry and not dry_run and dst.exists():
+                update_entry(registry, rel_path, src_file, dst)
 
     for filename in ASSET_FILES:
         src = source / filename
         if not src.exists():
             continue
+        rel_path = f"claudekit/{filename}"
         dst = claudekit_dir / filename
+
+        if not force and registry and dst.exists():
+            entry = registry.get("entries", {}).get(rel_path)
+            if entry:
+                if dry_run and check_user_edit(entry, dst):
+                    skipped += 1
+                    print(f"skip(user-edit): {rel_path}")
+                    continue
+                backup = maybe_backup(registry, rel_path, dst, respect_edits=True)
+                if backup:
+                    skipped += 1
+                    print(f"skip(user-edit): {rel_path}")
+                    continue
+            elif compute_hash(src) != compute_hash(dst):
+                if dry_run:
+                    print(f"[dry-run] backup(untracked): {rel_path}")
+                else:
+                    backup = create_backup(dst)
+                    print(f"backup(untracked): {rel_path} -> {backup.name}")
+
         data = src.read_bytes()
         mode = src.stat().st_mode & 0o777 if src.stat().st_mode & 0o111 else None
         changed, is_added = write_bytes_if_changed(dst, data, mode=mode, dry_run=dry_run)
         if changed:
             if is_added:
                 added += 1
-                print(f"add: claudekit/{filename}")
+                print(f"add: {rel_path}")
             else:
                 updated += 1
-                print(f"update: claudekit/{filename}")
+                print(f"update: {rel_path}")
+        if registry and not dry_run and dst.exists():
+            update_entry(registry, rel_path, src, dst)
 
-    return {"added": added, "updated": updated, "removed": 0, "managed_files": added + updated}
+    return {"added": added, "updated": updated, "removed": 0, "skipped": skipped}
 
 
 def sync_skills_from_dir(
@@ -120,6 +170,7 @@ def sync_skills_from_dir(
         ignore = shutil.ignore_patterns("*.pyc", "__pycache__", ".venv", "node_modules", "dist", "build")
         shutil.copytree(skill_dir, dst, ignore=ignore)
 
-    skills_dst.mkdir(parents=True, exist_ok=True)
+    if not dry_run:
+        skills_dst.mkdir(parents=True, exist_ok=True)
     total_skills = len(list(skills_dst.rglob("SKILL.md")))
     return {"added": added, "updated": updated, "skipped": skipped, "total_skills": total_skills}

package/src/claudekit_codex_sync/asset_sync_zip.py

@@ -16,7 +16,16 @@ from .constants import (
     MCP_SKILLS,
 )
 from .source_resolver import collect_skill_entries, zip_mode
-from .utils import load_manifest, save_manifest, write_bytes_if_changed
+from .utils import SyncError, load_manifest, save_manifest, write_bytes_if_changed
+
+
+def _validate_zip_relpath(rel: str, zip_name: str) -> str:
+    """Validate zip relative path and return normalized form."""
+    normalized = rel.replace("\\", "/")
+    path = Path(normalized)
+    if path.is_absolute() or ".." in path.parts:
+        raise SyncError(f"Unsafe zip entry path: {zip_name}")
+    return normalized
 
 
 def sync_assets(
@@ -35,7 +44,7 @@ def sync_assets(
     for name in zf.namelist():
         if name.endswith("/") or not name.startswith(".claude/"):
             continue
-        rel = name[len(".claude/") :]
+        rel = _validate_zip_relpath(name[len(".claude/") :], name)
         first = rel.split("/", 1)[0]
         if first == "hooks" and include_hooks:
             selected.append((name, rel))
@@ -47,10 +56,11 @@ def sync_assets(
     added = updated = removed = 0
 
     for rel in sorted(old_manifest - new_manifest):
-        target = claudekit_dir / rel
+        safe_rel = _validate_zip_relpath(rel, rel)
+        target = claudekit_dir / safe_rel
         if target.exists():
             removed += 1
-            print(f"remove: {rel}")
+            print(f"remove: {safe_rel}")
             if not dry_run:
                 target.unlink()
 
@@ -135,6 +145,7 @@ def sync_skills(
             dst = dst_skill_dir / inner
             write_bytes_if_changed(dst, data, mode=zip_mode(info), dry_run=False)
 
-    skills_dir.mkdir(parents=True, exist_ok=True)
+    if not dry_run:
+        skills_dir.mkdir(parents=True, exist_ok=True)
     total_skills = len(list(skills_dir.rglob("SKILL.md")))
     return {"added": added, "updated": updated, "skipped": skipped, "total_skills": total_skills}

package/src/claudekit_codex_sync/clean_target.py

@@ -0,0 +1,59 @@
+"""Clean target directories for --fresh sync."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+
+def clean_target(codex_home: Path, *, dry_run: bool) -> int:
+    """Remove agents, skills (keep .venv), prompts, claudekit before fresh sync."""
+    removed = 0
+
+    for subdir in ("agents", "prompts", "claudekit"):
+        target = codex_home / subdir
+        if target.exists():
+            count = sum(1 for item in target.rglob("*") if item.is_file())
+            removed += count
+            print(f"fresh: rm {subdir}/ ({count} files)")
+            if not dry_run:
+                shutil.rmtree(target)
+
+    skills = codex_home / "skills"
+    if skills.exists():
+        for item in skills.iterdir():
+            if item.name == ".venv":
+                # Keep symlinks (pointing to ~/.claude/skills/.venv)
+                # Delete real venv dirs so symlink can be created on next bootstrap
+                if item.is_symlink():
+                    continue
+                # Real venv dir → delete so symlink-first strategy works
+                count = sum(1 for p in item.rglob("*") if p.is_file())
+                removed += count
+                if not dry_run:
+                    shutil.rmtree(item)
+                print("fresh: rm skills/.venv (real dir, will be re-symlinked)")
+                continue
+            if item.is_dir():
+                count = sum(1 for path in item.rglob("*") if path.is_file())
+                removed += count
+                if not dry_run:
+                    shutil.rmtree(item)
+            else:
+                removed += 1
+                if not dry_run:
+                    item.unlink()
+        print("fresh: rm skills/* (kept .venv)")
+
+    for name in (
+        ".claudekit-sync-registry.json",
+        ".sync-manifest-assets.txt",
+        ".claudekit-generated-prompts.txt",
+    ):
+        target = codex_home / name
+        if target.exists():
+            removed += 1
+            if not dry_run:
+                target.unlink()
+
+    return removed