claudekit-codex-sync 0.1.0 → 0.2.0

package/README.md

@@ -1,70 +1,92 @@
 # claudekit-codex-sync
 
-Sync [ClaudeKit](https://github.com/anthropics/claudekit) skills, agents, prompts, and configuration to [Codex CLI](https://developers.openai.com/codex).
+Sync [ClaudeKit](https://github.com/anthropics/claudekit) skills, config assets, prompts, and runtime setup to [Codex CLI](https://developers.openai.com/codex).
 
 ## Problem
 
-ClaudeKit stores agent definitions (`.md` with YAML frontmatter), skills, prompts, and config under `~/.claude/`. Codex CLI uses a different layout under `~/.codex/` with `.toml` agents, GPT model names, and TOML-based config. Manually migrating is tedious and error-prone.
+ClaudeKit uses `~/.claude/` conventions and agent markdown frontmatter. Codex uses `~/.codex/`, TOML config, and different runtime defaults. Manual migration is slow and error-prone.
 
 ## What It Does
 
 | Step | Action |
 |---|---|
-| **Source resolve** | Detects `~/.claude/` (live) or ClaudeKit export zip |
-| **Asset sync** | Copies agents, commands, rules, scripts → `~/.codex/claudekit/` |
-| **Skill sync** | Copies 54+ skills → `~/.codex/skills/` |
-| **Path normalize** | Rewrites `.claude` → `.codex` in all synced files |
-| **Agent convert** | `.md` (YAML frontmatter) → `.toml` with model mapping |
-| **Model mapping** | `opus → gpt-5.3-codex`, `haiku → gpt-5.3-codex-spark` |
-| **Config enforce** | Sets `multi_agent`, `child_agents_md`, registers `[agents.*]` |
+| **Scope select** | Sync to project `./.codex/` (default) or global `~/.codex/` (`-g`) |
+| **Fresh clean** | Optional `-f` cleanup of target dirs before sync |
+| **Source resolve** | Uses live `~/.claude/` or `--zip` export |
+| **Asset sync** | Copies commands/output-styles/scripts and `.env.example` to `codex_home/claudekit/` |
+| **Skill sync** | Copies skills into `codex_home/skills/` |
+| **Path normalize** | Rewrites `.claude` references to `.codex` |
+| **Config enforce** | Ensures `config.toml`, feature flags, and agent registration |
 | **Prompt export** | Generates Codex-compatible prompt files |
-| **Dep bootstrap** | Installs Python/Node deps for skills requiring them |
-| **Runtime verify** | Health-checks the synced environment |
+| **Dep bootstrap** | Symlink-first venv strategy, fallback install |
+| **Runtime verify** | Health-checks synced environment |
 
 ## Installation
 
 ```bash
-# Clone and install globally
+# Install from npm registry
+npm install -g claudekit-codex-sync
+
+# Or install from source
 git clone https://github.com/vinhawk-66/claudekit-codex-sync.git
 cd claudekit-codex-sync
 npm install -g .
 ```
 
+## Quick Start
+
+```bash
+# Project sync (to ./.codex/)
+ckc-sync
+
+# Global sync (to ~/.codex/)
+ckc-sync -g
+
+# Fresh global re-sync
+ckc-sync -g -f
+
+# Preview only
+ckc-sync -g -n
+```
+
 ## Usage
 
 ```bash
-# Sync from live ~/.claude/ directory
-ck-codex-sync --source-mode live
+# Custom live source (instead of ~/.claude)
+ckc-sync --source /path/to/.claude
 
 # Sync from exported zip
-ck-codex-sync --zip claudekit-export.zip
-
-# Preview without changes
-ck-codex-sync --source-mode live --dry-run
+ckc-sync --zip claudekit-export.zip --force
 
 # Include MCP skills
-ck-codex-sync --source-mode live --include-mcp
+ckc-sync --mcp
+
+# Skip dependency bootstrap
+ckc-sync --no-deps
+
+# Overwrite user-edited managed assets
+ckc-sync --force
+
+# Backward-compatible command name
+ck-codex-sync -g -n
 ```
 
 ## CLI Options
 
 ```
---source-mode live|zip|auto   Source selection (default: auto)
---source-dir PATH             Custom source directory
---zip PATH                    Specific zip file
---codex-home PATH             Codex home (default: ~/.codex)
---include-mcp                 Include MCP skills
---include-hooks               Include hooks
---skip-bootstrap              Skip dependency installation
---skip-verify                 Skip runtime verification
---skip-agent-toml             Skip agent TOML normalization
---respect-edits               Backup user-edited files
---dry-run                     Preview mode
+-g, --global      Sync to ~/.codex/ (default: ./.codex/)
+-f, --fresh       Clean target dirs before sync
+--force           Overwrite user-edited files without backup (required for zip write mode)
+--zip PATH        Sync from zip instead of live ~/.claude/
+--source PATH     Custom source dir (default: ~/.claude/)
+--mcp             Include MCP skills
+--no-deps         Skip dependency bootstrap (venv)
+-n, --dry-run     Preview only
 ```
 
 ## Agent Model Mapping
 
-Per [official Codex docs](https://developers.openai.com/codex/multi-agent), each agent role can override `model`, `model_reasoning_effort`, and `sandbox_mode`:
+Per [official Codex docs](https://developers.openai.com/codex/multi-agent):
 
 | Claude Model | Codex Model | Reasoning | Used By |
 |---|---|---|---|
@@ -72,35 +94,30 @@ Per [official Codex docs](https://developers.openai.com/codex/multi-agent), each
 | `sonnet` | `gpt-5.3-codex` | high | debugger, fullstack_developer |
 | `haiku` | `gpt-5.3-codex-spark` | medium | researcher, tester, docs_manager |
 
-Read-only agents (brainstormer, code_reviewer, researcher, project_manager, journal_writer) get `sandbox_mode = "read-only"`.
-
-## Related Tools
-
-- **[ccs](https://www.npmjs.com/package/@kaitranntt/ccs)** (`@kaitranntt/ccs`) — Claude Code Profile & Model Switcher. Allows running Claude Code with different model backends including Codex models via CLIProxy. Example: `ccs codex` launches Claude Code using Codex as the backend model.
-- **[Codex CLI](https://github.com/openai/codex)** (`@openai/codex`) — OpenAI's coding agent CLI.
+Read-only roles remain: brainstormer, code_reviewer, researcher, project_manager, journal_writer.
 
 ## Project Structure
 
 ```
-├── bin/ck-codex-sync.js           # npm CLI entry point
-├── src/claudekit_codex_sync/      # Python modules (13 files, ~1500 LOC)
-│   ├── cli.py                     # Main orchestrator
-│   ├── source_resolver.py         # Source detection (live/zip/auto)
-│   ├── asset_sync_dir.py          # Directory-based sync
-│   ├── asset_sync_zip.py          # Zip-based sync
-│   ├── path_normalizer.py         # Path rewriting + agent .md→.toml
-│   ├── config_enforcer.py         # Config, multi-agent, agent registration
-│   ├── prompt_exporter.py         # Prompt file generation
-│   ├── bridge_generator.py        # Bridge skill for Codex
-│   ├── dep_bootstrapper.py        # Dependency installation
-│   ├── runtime_verifier.py        # Health checks
-│   ├── sync_registry.py           # Backup/registry (SHA-256)
-│   ├── constants.py               # Replacements, model maps
-│   └── utils.py                   # Shared utilities
-├── templates/                     # Template files for generated content
-├── tests/                         # pytest suite
-├── scripts/                       # Legacy standalone scripts
-└── docs/                          # Documentation
+├── bin/ck-codex-sync.js
+├── src/claudekit_codex_sync/
+│   ├── cli.py
+│   ├── clean_target.py
+│   ├── source_resolver.py
+│   ├── asset_sync_dir.py
+│   ├── asset_sync_zip.py
+│   ├── path_normalizer.py
+│   ├── config_enforcer.py
+│   ├── prompt_exporter.py
+│   ├── bridge_generator.py
+│   ├── dep_bootstrapper.py
+│   ├── runtime_verifier.py
+│   ├── sync_registry.py
+│   ├── constants.py
+│   └── utils.py
+├── templates/
+├── tests/
+└── docs/
 ```
 
 ## Development
@@ -109,11 +126,11 @@ Read-only agents (brainstormer, code_reviewer, researcher, project_manager, jour
 # Run tests
 PYTHONPATH=src python3 -m pytest tests/ -v
 
-# Lint
+# Compile check
 python3 -m py_compile src/claudekit_codex_sync/*.py
 
-# Run sync locally
-PYTHONPATH=src python3 -m claudekit_codex_sync.cli --source-mode live --dry-run
+# Local dry-run sync
+PYTHONPATH=src python3 -m claudekit_codex_sync.cli -n
 ```
 
 ## Documentation

package/docs/codebase-summary.md

@@ -2,82 +2,79 @@
 
 ## Overview
 
-**claudekit-codex-sync** bridges ClaudeKit (`~/.claude/`) to Codex CLI (`~/.codex/`) by syncing skills, agents, prompts, and configuration. Written primarily in Python with a Node.js CLI wrapper.
+**claudekit-codex-sync** bridges ClaudeKit (`~/.claude/`) to Codex CLI (`.codex/` project scope by default, optional global `~/.codex/`) by syncing skills, assets, prompts, and runtime defaults.
 
 ## Stats
 
-| Component | Files | LOC | Purpose |
-|---|---|---|---|
-| `src/claudekit_codex_sync/` | 13 | ~1500 | Core Python modules |
-| `templates/` | 5 | ~280 | Generated file templates |
-| `tests/` | 2 | ~106 | pytest-based test suite |
-| `scripts/` | 4 | ~1780 | Legacy standalone scripts |
-| `bin/` | 2 | ~20 | npm CLI entry point |
+| Component | Files | Purpose |
+|---|---|---|
+| `src/claudekit_codex_sync/` | 14 | Core Python sync modules |
+| `templates/` | 6 | Generated content templates |
+| `tests/` | 4 | pytest suite |
+| `bin/` | 2 | npm CLI entry points |
 
 ## Module Map
 
 ### Core Orchestration
 
-- **`cli.py`** (199 LOC) — Main entry point. Parses args, coordinates all sync phases, outputs JSON summary. Supports `live` (directory) and `zip` source modes.
+- **`cli.py`** — Main entry point with 8-flag interface (`-g`, `-f`, `--force`, `--zip`, `--source`, `--mcp`, `--no-deps`, `-n`).
+- **`clean_target.py`** — Fresh-sync cleaner for `--fresh` (preserves `skills/.venv`).
 
 ### Source Resolution
 
-- **`source_resolver.py`** (78 LOC) — Detects ClaudeKit source: `~/.claude/` for live mode, finds latest zip for zip mode. Validates source has required structure.
-
-### Asset Sync
-
-- **`asset_sync_dir.py`** (125 LOC) — Copies assets and skills from a live `~/.claude/` directory to `~/.codex/`. Handles `ASSET_DIRS` (agents, commands, rules, scripts) and `ASSET_FILES`.
-- **`asset_sync_zip.py`** (140 LOC) — Same as above but from a ClaudeKit export zip file.
+- **`source_resolver.py`** — Live source discovery and zip source lookup.
 
-### Path Normalization
+### Asset & Skill Sync
 
-- **`path_normalizer.py`** (248 LOC) — Rewrites `.claude` → `.codex` paths in all synced files. Also converts ClaudeKit agent `.md` files (with YAML frontmatter) to Codex `.toml` format with correct model mapping.
-- **`constants.py`** (104 LOC) — All replacement patterns (`SKILL_MD_REPLACEMENTS`, `AGENT_TOML_REPLACEMENTS`, `CLAUDE_SYNTAX_ADAPTATIONS`), model mapping tables, and read-only role sets.
+- **`asset_sync_dir.py`** — Live sync for assets and skills with registry-aware overwrite/backup behavior for managed assets.
+- **`asset_sync_zip.py`** — Zip-based sync path.
 
-### Configuration
+### Normalization & Conversion
 
-- **`config_enforcer.py`** (140 LOC) — Ensures `config.toml` has correct structure, enforces `multi_agent` + `child_agents_md` feature flags, auto-registers `[agents.*]` sections from TOML files.
+- **`path_normalizer.py`** — `.claude` path rewrites, copywriting script patch, agent markdown-to-TOML conversion.
+- **`constants.py`** — Replacement patterns, model mapping, asset allowlists.
 
-### Prompt & Bridge
+### Config & Prompting
 
-- **`prompt_exporter.py`** (89 LOC) — Exports ClaudeKit prompts to Codex-compatible format.
-- **`bridge_generator.py`** (33 LOC) — Creates a bridge skill in `~/.codex/skills/claudekit-command-bridge/`.
+- **`config_enforcer.py`** — `config.toml` enforcement + agent registration.
+- **`prompt_exporter.py`** — Prompt generation.
+- **`bridge_generator.py`** — Bridge skill generation.
 
-### Support
+### Runtime Support
 
-- **`dep_bootstrapper.py`** (73 LOC) — Installs Python/Node dependencies for skills that require them.
-- **`runtime_verifier.py`** (32 LOC) — Verifies synced environment health (codex help, copywriting, prompt count, skill count).
-- **`sync_registry.py`** (77 LOC) — SHA-256 checksum registry for tracking synced files and detecting user edits.
-- **`utils.py`** (130 LOC) — Shared utilities: `apply_replacements()`, `load_template()`, `write_text_if_changed()`, `SyncError`.
+- **`dep_bootstrapper.py`** — Symlink-first dependency bootstrap (`~/.claude/skills/.venv` -> `codex_home/skills/.venv` fallback to create/install).
+- **`runtime_verifier.py`** — Runtime health checks.
+- **`sync_registry.py`** — Sync registry and user-edit detection helpers.
+- **`utils.py`** — Shared helpers and `SyncError`.
 
 ## Data Flow
 
 ```
 Source (~/.claude/ or zip)
     ↓
-source_resolver.py → detect source type
+source_resolver.py
     ↓
-asset_sync_dir/zip.py → copy agents, skills, commands
+asset_sync_dir.py / asset_sync_zip.py
     ↓
-path_normalizer.py → rewrite paths + convert .md→.toml agents
+path_normalizer.py
     ↓
-config_enforcer.py → update config.toml + register agents
+config_enforcer.py
     ↓
-prompt_exporter.py → generate prompt files
+prompt_exporter.py
     ↓
-dep_bootstrapper.py → install skill dependencies
+dep_bootstrapper.py
     ↓
-runtime_verifier.py → health check
+runtime_verifier.py
     ↓
-Output: ~/.codex/ fully configured for Codex CLI
+Configured Codex home (.codex project scope or ~/.codex global)
 ```
 
 ## Test Coverage
 
-| File | Tests | Coverage |
-|---|---|---|
-| `config_enforcer.py` | 4 | Feature flag enforcement |
-| `path_normalizer.py` | 7 | Path replacement patterns |
-| **Total** | **11** | Core functionality |
-
-Untested modules (need coverage): `cli.py`, `asset_sync_dir.py`, `asset_sync_zip.py`, `source_resolver.py`, `prompt_exporter.py`, `dep_bootstrapper.py`, `runtime_verifier.py`, `sync_registry.py`, `bridge_generator.py`, `utils.py`.
+| File | Tests |
+|---|---|
+| `tests/test_config_enforcer.py` | 4 |
+| `tests/test_path_normalizer.py` | 7 |
+| `tests/test_clean_target.py` | 4 |
+| `tests/test_cli_args.py` | 6 |
+| **Total** | **21** |

package/docs/codex-vs-claude-agents.md

@@ -1,49 +1,60 @@
 # Codex vs Claude Agents
 
-This document outlines the differences between Claude Code agents and Codex agents, and what is lost or preserved during sync.
+Differences between Claude Code (ClaudeKit) agents and Codex CLI agents, and how this sync tool handles the translation.
 
-## Key Differences
+## Agent Definition Format
 
-| Feature | Claude Code | Codex CLI |
-|---------|-------------|-----------|
-| **Agent Definition** | TOML files with `[[agents]]` sections | TOML files with `[[agents]]` sections |
-| **Model Selection** | `model` frontmatter field | No per-agent model selection |
-| **Tool Restrictions** | `tools` frontmatter field | No tool restrictions (all tools available) |
-| **Memory** | `memory` frontmatter field | `developer_instructions` text only |
-| **Delegation** | `Task()` tool for explicit delegation | Auto-spawn via `multi_agent = true` |
+| Aspect | Claude Code (ClaudeKit) | Codex CLI |
+|---|---|---|
+| **File format** | `.md` with YAML frontmatter | `.toml` |
+| **Instructions** | Markdown body below `---` | `developer_instructions = """..."""` |
+| **Model** | `model: opus/sonnet/haiku` | `model = "gpt-5.3-codex"` (per-agent override) |
+| **Reasoning** | Not configurable | `model_reasoning_effort = "xhigh/high/medium"` |
+| **Sandbox** | Not configurable | `sandbox_mode = "read-only/workspace-write"` |
+| **Tools** | `tools: [Glob, Grep, Read, ...]` | All tools available (no restriction) |
+| **Delegation** | `Task(planner)` explicit call | Auto-spawn by model + `/agent` to switch threads |
+| **Memory** | `memory: project` field | Instructions text + AGENTS.md |
 
-## What Transfers
+## What the Sync Preserves
 
-The following are preserved during ClaudeKit -> Codex sync:
+- ✅ Agent name and slug
+- ✅ Developer instructions (full markdown body)
+- ✅ Description (from YAML frontmatter)
+- ✅ Model selection → mapped to Codex equivalents
+- ✅ Sandbox mode settings
+- ✅ File structure (`~/.codex/agents/`)
+- ✅ Config registration (`[agents.*]` in config.toml)
 
-- **Agent name and description** - Basic identity
-- **Developer instructions** - Core behavior guidance
-- **Sandbox mode settings** - Security constraints
-- **Agent file structure** - Organized in `~/.codex/agents/`
+## What Changes
 
-## What's Lost
+### Model Mapping
 
-The following Claude-specific features are stripped or adapted:
+The sync automatically maps Claude model names to Codex equivalents:
 
-1. **Explicit Task() delegation syntax**
-   - Claude: `Task(subagent_type="researcher", ...)`
-   - Codex: Auto-spawn based on context
+```
+opus   → gpt-5.3-codex       + model_reasoning_effort = "xhigh"
+sonnet → gpt-5.3-codex       + model_reasoning_effort = "high"
+haiku  → gpt-5.3-codex-spark + model_reasoning_effort = "medium"
+```
+
+### Sandbox Assignment
 
-2. **Tool restrictions**
-   - Claude: `tools = ["Read", "Grep", "Edit"]` limits available tools
-   - Codex: All tools available to all agents
+Agents that only read/analyze get `sandbox_mode = "read-only"`:
+- brainstormer, code_reviewer, researcher, project_manager, journal_writer
 
-3. **Model selection**
-   - Claude: `model = "haiku"` for cost/performance tuning
-   - Codex: Single model for all operations
+Agents that write code get `sandbox_mode = "workspace-write"`:
+- planner, debugger, fullstack_developer, tester, code_simplifier, etc.
 
-4. **Memory configuration**
-   - Claude: `memory` section with context management
-   - Codex: Instructions embedded in developer text
+### Delegation Syntax
+
+```diff
+- Task(subagent_type="researcher", ...)
++ delegate to the researcher agent
+```
 
-## Path Normalization
+`Task()` calls are rewritten to natural language since Codex uses model-driven auto-spawning.
 
-Agent TOMLs are automatically normalized during sync:
+### Path Normalization
 
 ```diff
 - $HOME/.claude/skills/
@@ -53,22 +64,22 @@ Agent TOMLs are automatically normalized during sync:
 + ~/.codex/
 ```
 
-## Multi-Agent Configuration
+## What's Not Supported
+
+- **Tool restrictions**: Claude's `tools = [...]` field is dropped — Codex gives all tools to all agents
+- **Memory config**: Claude's `memory: project` is dropped — use `developer_instructions` text instead
+- **Explicit model names**: Claude-specific model names are replaced, not preserved
+
+## Multi-Agent in Codex
 
-After sync, enable multi-agent mode:
+After sync, Codex supports multi-agent workflows via:
 
 ```toml
 [features]
 multi_agent = true
+child_agents_md = true
 ```
 
-This allows Codex to auto-spawn sub-agents based on task context, similar to Claude's `Task()` delegation but without explicit syntax.
-
-## Recommendation
-
-For maximum compatibility:
+Built-in roles: `default`, `worker`, `explorer`. Custom roles (from your synced agents) are spawned by the model based on `description` in `[agents.*]` config sections.
 
-1. Write agent instructions assuming all tools are available
-2. Use natural language for delegation intent (e.g., "use the researcher agent")
-3. Keep agent instructions under 2000 tokens
-4. Test agents after sync to verify behavior
+Use `/agent` in interactive Codex CLI to switch between active sub-agent threads.

package/docs/installation-guide.md

@@ -2,63 +2,107 @@
 
 ## Prerequisites
 
-- Python 3.9+
-- Node.js 18+ (for npm installation)
-- Codex CLI installed
+- Python 3.12+
+- Node.js 18+
+- [Codex CLI](https://developers.openai.com/codex/cli) installed (`npm install -g @openai/codex`)
+- ClaudeKit installed (`~/.claude/` exists) or exported ClaudeKit zip
+
+## Install via npm
+
+```bash
+npm install -g claudekit-codex-sync
+```
 
 ## Install from Source
 
 ```bash
-cd /home/vinhawk/claudekit-codex-sync
+git clone https://github.com/vinhawk-66/claudekit-codex-sync.git
+cd claudekit-codex-sync
 npm install -g .
 ```
 
 ## Verify Installation
 
 ```bash
+ckc-sync --help
 ck-codex-sync --help
 ```
 
 ## Usage
 
-### Basic Sync (from zip)
+### Project sync (default target: `./.codex/`)
 
 ```bash
-ck-codex-sync
+ckc-sync
 ```
 
-### Live Source Mode (from ~/.claude/)
+### Global sync (`~/.codex/`)
 
 ```bash
-ck-codex-sync --source-mode live
+ckc-sync -g
 ```
 
-### Include MCP Skills
+### Fresh re-sync
 
 ```bash
-ck-codex-sync --include-mcp
+ckc-sync -g -f
 ```
 
-### Dry Run
+### Preview only
 
 ```bash
-ck-codex-sync --dry-run
+ckc-sync -g -n
 ```
 
-## Configuration
-
-The tool automatically configures:
+### Zip source
 
-- `~/.codex/config.toml` - Codex configuration
-- `~/.codex/agents/` - Agent definitions
-- `~/.codex/skills/` - Skill definitions
-- `~/.codex/prompts/` - Custom prompts
+```bash
+ckc-sync --zip path/to/claudekit-export.zip --force
+```
 
-## Post-Install Verification
+### Custom live source
 
 ```bash
-# Check multi-agent is enabled
-codex features list | grep multi_agent
+ckc-sync --source /path/to/.claude
+```
 
-# Should show: multi_agent    experimental    true
+## Full Options
+
+```
+-g, --global      Sync to ~/.codex/ (default: ./.codex/)
+-f, --fresh       Clean target dirs before sync
+--force           Overwrite user-edited files without backup (required for zip write mode)
+--zip PATH        Sync from zip instead of live ~/.claude/
+--source PATH     Custom source dir (default: ~/.claude/)
+--mcp             Include MCP skills
+--no-deps         Skip dependency bootstrap (venv)
+-n, --dry-run     Preview only
 ```
+
+## What Gets Synced
+
+| Source/Input | Destination |
+|---|---|
+| `skills/*/` | `codex_home/skills/*/` |
+| `commands/` | `codex_home/claudekit/commands/` |
+| `output-styles/` | `codex_home/claudekit/output-styles/` |
+| `scripts/` | `codex_home/claudekit/scripts/` |
+| `.env.example` | `codex_home/claudekit/.env.example` |
+| Generated from `codex_home/claudekit/commands/*.md` | `codex_home/prompts/*.md` |
+
+Notes:
+- In zip mode, `hooks/` entries are also synced to `codex_home/claudekit/hooks/`.
+
+## Post-Install
+
+After sync:
+
+```bash
+codex --help
+```
+
+The sync process enforces:
+- `[features] multi_agent = true`
+- `[features] child_agents_md = true`
+- Bridge skill setup
+- Agent registration for available `codex_home/agents/*.toml`

package/docs/project-overview-pdr.md

@@ -1,44 +1,38 @@
-# Project Overview — PDR
+# Project Overview - PDR
 
 ## Product
 
-**claudekit-codex-sync** — CLI tool that syncs ClaudeKit configuration to OpenAI Codex CLI.
+**claudekit-codex-sync** — CLI tool that syncs ClaudeKit configuration into Codex CLI-compatible layout.
 
 ## Problem Statement
 
-ClaudeKit users who also use Codex CLI face duplicate setup: re-configuring agents, skills, prompts, and paths. The two platforms use incompatible formats (ClaudeKit: Markdown agents with YAML frontmatter, Claude model names; Codex: TOML agents, GPT model names).
+ClaudeKit and Codex CLI use different file layouts, model naming, and config conventions. Users migrating between tools spend time on repetitive manual setup.
 
 ## Solution
 
-A single-command sync tool that:
-1. Copies all assets from `~/.claude/` → `~/.codex/`
-2. Rewrites paths (`.claude` → `.codex`)
-3. Converts agent definitions (`.md` → `.toml`)
-4. Maps model names (`opus` → `gpt-5.3-codex`, `haiku` → `gpt-5.3-codex-spark`)
-5. Configures multi-agent features and registers agent roles
+Single-command sync that:
+1. Copies skills and managed assets from ClaudeKit source
+2. Normalizes path references (`.claude` -> `.codex`)
+3. Enforces Codex config defaults and feature flags
+4. Registers available agents
+5. Exports prompts and verifies runtime readiness
 
 ## Target Users
 
-ClaudeKit power-users who also use or are migrating to Codex CLI.
+ClaudeKit users moving to or co-using Codex CLI.
 
 ## Key Metrics
 
-- Zero manual configuration needed after sync
-- All synced agents load correctly in Codex
-- No `.claude` path references remain in synced files
-- 14+ agent roles with correct model assignments
+- Project-scope default sync (`./.codex`) with optional global scope (`-g`)
+- 21 automated tests covering core path normalization/config plus CLI parsing and fresh-clean behavior
+- Backward-compatible command alias (`ck-codex-sync`) retained during v0.2
+- Faster bootstrap for existing ClaudeKit users via symlink-first venv reuse
 
 ## Status
 
-**v0.1.0** — Functional. All core features implemented:
-- [x] Live directory sync
-- [x] Zip archive sync
-- [x] Path normalization (37+ files per sync)
-- [x] Agent .md → .toml conversion with model mapping
-- [x] Multi-agent config (multi_agent + child_agents_md)
-- [x] Agent registration (14 roles)
-- [x] Prompt export (20+ prompts)
-- [x] Dependency bootstrap
-- [x] Runtime verification
-- [ ] Full test coverage (11/~40 target tests)
-- [ ] Idempotent re-sync (partial — registry exists but not fully wired)
+**v0.2.0** — CLI redesign and cleanup complete:
+- [x] New `ckc-sync` command surface
+- [x] `--fresh` clean target workflow
+- [x] `--force` overwrite handling for managed assets
+- [x] Symlink-first dependency bootstrap
+- [x] Expanded tests and docs refresh