feat: port the Unity bridge to Codex

.TestProject/.gitignore

@@ -19,5 +19,6 @@ ProjectSettings/*.meta
 !Packages/
 !Packages/manifest.json
 
-# .unity-bridge/ is created at runtime by Unity Bridge - always ignore
+# Bridge runtime directories are created at runtime - always ignore
 .unity-bridge/
+.codex-unity-bridge/

.TestProject/Packages/manifest.json

@@ -1,6 +1,6 @@
 {
   "dependencies": {
-    "com.mxr.claude-bridge": "file:../../package",
+    "com.prodfact.codex-bridge": "file:../../package",
     "com.unity.ai.navigation": "2.0.9",
     "com.unity.collab-proxy": "2.9.3",
     "com.unity.ide.rider": "3.0.38",
@@ -53,6 +53,6 @@
     }
   ],
   "testables": [
-    "com.mxr.claude-bridge"
+    "com.prodfact.codex-bridge"
   ]
 }

.TestProject/README.md

@@ -1,226 +1,127 @@
-# Unity Bridge - Integration Test Project
+# Unity Bridge Integration Project
 
-This is a minimal Unity 2021.3+ project used for end-to-end integration testing of the Claude Unity Bridge package.
-
-**Note**: This directory is named `.TestProject` (hidden) to prevent it from appearing in the Package Manager when users install this package. It's excluded via `.npmignore` and only used for local development and testing.
+`.TestProject/` is the local Unity project used to validate the package in a real editor session. It stays hidden so it does not show up in normal package browsing and is excluded from the published package.
 
 ## Purpose
 
-The `.TestProject/` directory enables:
-
-1. **Package Development** - Test Unity Bridge changes in a real Unity project
-2. **End-to-End Validation** - Verify the bridge protocol works correctly
-3. **Agent Testing** - Allow AI agents to validate their Unity code changes
-4. **Integration Testing** - Test Python skill script against actual Unity Editor
+- Validate the Unity package against a real project, not only isolated tests
+- Exercise the file-based bridge end to end
+- Give contributors a repeatable place to run manual Unity checks
+- Provide a local target for the package test assembly
 
 ## Structure
 
-```
+```text
 .TestProject/
-├── Assets/               # Unity assets (gitignored, created by Unity)
-├── Packages/             # Package dependencies
-│   └── manifest.json    # References parent directory as local package
-├── ProjectSettings/      # Unity project settings (committed to git)
-├── .unity-bridge/       # Bridge protocol directory (gitignored, created at runtime)
-├── .gitignore           # Ignores everything except ProjectSettings & README
-└── README.md            # This file
+├── Assets/                  # Unity assets (mostly gitignored)
+├── Packages/
+│   └── manifest.json        # Local package reference + testables
+├── ProjectSettings/         # Committed Unity project settings
+├── .codex-unity-bridge/     # Runtime bridge directory (gitignored)
+├── .gitignore
+├── README.md
+└── VALIDATION.md
 ```
 
-## Package Reference
+## Local Package Reference
 
-The project references the Claude Unity Bridge package via a **local package reference**:
+The project loads the package from this repository through a local file reference:
 
 ```json
 {
   "dependencies": {
-    "com.mxr.claude-bridge": "file:.."
+    "com.prodfact.codex-bridge": "file:../../package"
   }
 }
 ```
 
-This means:
-- Changes to the package in `../Editor/` are immediately reflected in this project
-- No need to reinstall or update the package
-- Perfect for development and testing
+That means changes under `../package/` are picked up by this Unity project without republishing anything.
 
-## Usage
+## Basic Workflow
 
-### 1. Open in Unity Editor
+1. Open `.TestProject/` in Unity 2021.3 or later.
+2. Wait for Unity to finish importing and for the package to initialize.
+3. Run bridge commands from the Unity project directory, not the repo root.
+4. Check the Unity Console for `[CodexBridge]` logs.
+
+Example:
 
 ```bash
-# From repository root
 open -a "Unity" .TestProject/
+cd .TestProject
+python3 ../skill/src/codex_unity_bridge/cli.py get-status
+python3 ../skill/src/codex_unity_bridge/cli.py compile
+python3 ../skill/src/codex_unity_bridge/cli.py get-console-logs --limit 10 --filter Error
 ```
 
-Or open via Unity Hub by adding `.TestProject/` as a project.
-
-**Important**: You must have Unity 2021.3 or later installed.
-
-### 2. Verify Package Loaded
+## Important Working Directory Rule
 
-Once Unity Editor opens:
+The CLI writes into the current Unity project's `.codex-unity-bridge/` directory. If you run the command from the wrong directory, the CLI and Unity will look at different runtime folders and the command will time out.
 
-1. Check Window > Package Manager
-2. Find "Claude Unity Bridge" in the package list
-3. Verify it shows as a "Local" package
-4. Check for any console errors related to package loading
-
-### 3. Test the Bridge Protocol
-
-With Unity Editor open and the .TestProject loaded, test the Python skill script:
+Correct:
 
 ```bash
-# From repository root
-cd skill
-python3 scripts/cli.py get-status
-```
-
-**Expected output:**
-```
-✓ Unity Editor is running
-  Version: 2021.3.x
-  Project: .TestProject
-  Play Mode: Inactive
-  Compiling: No
-  Platform: StandaloneOSX
+cd /path/to/codex-unity-bridge/.TestProject
+python3 ../skill/src/codex_unity_bridge/cli.py get-status
 ```
 
-### 4. Run More Commands
-
-Try other commands to validate full functionality:
+Incorrect:
 
 ```bash
-# Compile scripts
-python3 scripts/cli.py compile
-
-# Refresh asset database
-python3 scripts/cli.py refresh
-
-# Get console logs
-python3 scripts/cli.py get-console-logs --limit 10
-
-# Run tests (if any test assemblies exist)
-python3 scripts/cli.py run-tests --mode EditMode
+cd /path/to/codex-unity-bridge
+python3 skill/src/codex_unity_bridge/cli.py get-status
 ```
 
-## Troubleshooting
-
-### "Unity Editor not detected"
-
-**Cause**: The `.unity-bridge/` directory doesn't exist yet.
-
-**Fix**:
-1. Ensure Unity Editor is open with .TestProject loaded
-2. The package should create `.unity-bridge/` automatically on startup
-3. Check Unity Console for any `[ClaudeBridge]` errors
-4. Try reopening the project if the directory isn't created
-
-### Package Not Showing in Package Manager
-
-**Cause**: The local package reference may not be resolving correctly.
-
-**Fix**:
-1. Check `Packages/manifest.json` contains `"com.mxr.claude-bridge": "file:.."`
-2. Verify the parent directory contains a valid `package.json`
-3. Try Window > Package Manager > Refresh
-4. Check Unity Console for package resolution errors
+## Verifying the Package Loaded
 
-### "Command timed out after 30s"
+Once Unity opens:
 
-**Cause**: Unity Bridge isn't polling for commands.
+1. Open `Window > Package Manager`
+2. Confirm `ProdFact Codex Unity Bridge` appears as a local package
+3. Confirm `.TestProject/.codex-unity-bridge/` is created
+4. Confirm the Unity Console shows `[CodexBridge]` initialization logs
 
-**Fix**:
-1. Check Unity Console for `[ClaudeBridge]` initialization messages
-2. Verify no errors during package initialization
-3. Try restarting Unity Editor
-4. Check if `.unity-bridge/` directory exists and is writable
-
-## For AI Agents
-
-When working on the Claude Unity Bridge package:
-
-1. **Before Testing Changes**: Open .TestProject in Unity Editor
-2. **Make Changes**: Edit files in `../Editor/` (changes reflect immediately)
-3. **Validate**: Run Python commands from `skill/` directory
-4. **Check Logs**: Monitor Unity Console for `[ClaudeBridge]` messages
-5. **Clean Up**: Unity will clean up old response files automatically
-
-### Typical Workflow
-
-```bash
-# 1. Open Unity with .TestProject (in separate terminal or GUI)
-open -a "Unity" .TestProject/
-
-# 2. Make changes to package C# code
-# Edit files in Editor/Commands/, Editor/ClaudeBridge.cs, etc.
-
-# 3. Test changes via Python skill script
-cd skill
-python3 scripts/cli.py get-status
-python3 scripts/cli.py compile
-
-# 4. Run pytest tests for Python script
-pytest tests/test_cli.py -v
-
-# 5. Commit when all tests pass
-```
-
-## What Gets Committed
-
-Only these files are tracked in git (see `.gitignore`):
-
-- `ProjectSettings/` - Unity project settings (except ProjectSettings.asset)
-- `Packages/manifest.json` - Package dependencies including local reference
-- `.gitignore` - Git ignore rules
-- `README.md` - This file
-
-Everything else (Assets/, Library/, Temp/, Logs/, .unity-bridge/) is gitignored.
-
-## Adding Test Assets (Optional)
+## Troubleshooting
 
-If you need to add test scenes, scripts, or assets for testing:
+### Unity Editor not detected
 
-1. Create them in Unity Editor as normal
-2. Update `.gitignore` to include the specific test assets
-3. Commit only the assets needed for automated testing
+- Ensure `.TestProject` is the project currently open in Unity
+- Confirm `.TestProject/.codex-unity-bridge/` exists
+- Check the Unity Console for package initialization errors
 
-For example, to add a test scene:
+### Package does not resolve
 
-```gitignore
-# In .TestProject/.gitignore, add:
-!Assets/
-!Assets/Scenes/
-!Assets/Scenes/TestScene.unity
-!Assets/Scenes/TestScene.unity.meta
-```
+- Confirm `Packages/manifest.json` contains `"com.prodfact.codex-bridge": "file:../../package"`
+- Confirm `../package/package.json` exists
+- Refresh the Package Manager window
 
-## Unity Version
+### Command timed out
 
-This project targets **Unity 2021.3** (the minimum version supported by the package).
+- Run the CLI from `.TestProject/`
+- Confirm Unity is not blocked by compile/import errors
+- Check for `[CodexBridge]` errors in the Unity Console
 
-To use a different Unity version:
-1. Open the project in your Unity version
-2. Unity will automatically upgrade `ProjectSettings/ProjectVersion.txt`
-3. Commit the updated version file if intentional
+## What Is Tracked
 
-## Related Documentation
+The test project commits only the minimum useful files:
 
-- **[../AGENTS.md](../AGENTS.md)** - Complete agent guidelines for development
-- **[../README.md](../README.md)** - Main package documentation
-- **[../skill/SKILL.md](../skill/SKILL.md)** - Python skill documentation
-- **[../skill/references/COMMANDS.md](../skill/references/COMMANDS.md)** - Command reference
+- `ProjectSettings/`
+- `Packages/manifest.json`
+- `.gitignore`
+- `README.md`
+- `VALIDATION.md`
 
-## Quick Reference
+Unity-generated folders such as `Library/`, `Temp/`, `Logs/`, and `.codex-unity-bridge/` remain ignored.
 
-```bash
-# Open project
-open -a "Unity" .TestProject/
+## Related Docs
 
-# Test bridge
-cd skill && python3 scripts/cli.py get-status
+- [AGENTS.md](../AGENTS.md)
+- [README.md](../README.md)
+- [skill/SKILL.md](../skill/SKILL.md)
+- [skill/references/COMMANDS.md](../skill/references/COMMANDS.md)
 
 # Run all commands
-python3 scripts/cli.py --help
+python3 src/codex_unity_bridge/cli.py --help
 
 # Close Unity
 # Use Cmd+Q or Unity > Quit