kdcokenny · kdcokenny · Jan 31, 2026 · Jan 31, 2026 · Jan 31, 2026 · Feb 1, 2026
diff --git a/.opencode/profiles/work/AGENTS.md b/.opencode/profiles/work/AGENTS.md
@@ -0,0 +1,4 @@
+# Profile Instructions
+
+<!-- Add your custom instructions for this profile here -->
+<!-- These will be included when running `ocx opencode -p work` -->
diff --git a/.opencode/profiles/work/ocx.jsonc b/.opencode/profiles/work/ocx.jsonc
@@ -0,0 +1,14 @@
+{
+  "$schema": "https://ocx.kdco.dev/schemas/ocx.json",
+  "registries": {},
+  "renameWindow": true,
+  "exclude": [
+    // "**/AGENTS.md",
+    "**/CLAUDE.md",
+    "**/CONTEXT.md",
+    "**/.opencode/**",
+    "**/opencode.jsonc",
+    "**/opencode.json"
+  ],
+  "include": []
+}
diff --git a/.opencode/profiles/work/opencode.jsonc b/.opencode/profiles/work/opencode.jsonc
@@ -0,0 +1 @@
+{}
diff --git a/.opencode/worktree.jsonc b/.opencode/worktree.jsonc
@@ -1,29 +1,29 @@
 {
-  "$schema": "https://registry.kdco.dev/schemas/worktree.json",
+	"$schema": "https://registry.kdco.dev/schemas/worktree.json",
 
-  // Worktree plugin configuration
-  // Documentation: https://github.com/kdcokenny/ocx
+	// Worktree plugin configuration
+	// Documentation: https://github.com/kdcokenny/ocx
 
-  "sync": {
-    // Files to copy from main worktree to new worktrees
-    // Example: [".env", ".env.local", "dev.sqlite"]
-    "copyFiles": [],
+	"sync": {
+		// Files to copy from main worktree to new worktrees
+		// Example: [".env", ".env.local", "dev.sqlite"]
+		"copyFiles": [],
 
-    // Directories to symlink (saves disk space)
-    // Example: ["node_modules"]
-    "symlinkDirs": [],
+		// Directories to symlink (saves disk space)
+		// Example: ["node_modules"]
+		"symlinkDirs": [],
 
-    // Patterns to exclude from copying
-    "exclude": []
-  },
+		// Patterns to exclude from copying
+		"exclude": []
+	},
 
-  "hooks": {
-    // Commands to run after worktree creation
-    // Example: ["pnpm install", "docker compose up -d"]
-    "postCreate": [],
+	"hooks": {
+		// Commands to run after worktree creation
+		// Example: ["pnpm install", "docker compose up -d"]
+		"postCreate": [],
 
-    // Commands to run before worktree deletion
-    // Example: ["docker compose down"]
-    "preDelete": []
-  }
+		// Commands to run before worktree deletion
+		// Example: ["docker compose down"]
+		"preDelete": []
+	}
 }
diff --git a/AGENTS.md b/AGENTS.md
@@ -226,7 +226,6 @@ packages/cli/          # Main CLI tool (@ocx/cli)
       update.ts        # Update components
       build.ts         # Build components
       diff.ts          # Component diff
-      ghost/           # [TEMPORARY] Ghost mode migration
     config/            # Config providers and resolution
     profile/           # Profile management (manager, paths)
     registry/          # Registry fetching/resolution
@@ -257,7 +256,6 @@ OCX provides a global profile system for managing multiple OpenCode configuratio
 | Config commands | `src/commands/config/` | show, edit |
 | OpenCode commands | `src/commands/opencode/` | Launch OpenCode with profile config |
 | Init commands | `src/commands/init/` | Initialize global/local configs |
-| Ghost commands | `src/commands/ghost/` | [TEMPORARY] Migration utilities |
 
 ### Directory Structure
 
@@ -288,20 +286,19 @@ Profiles are resolved in this order:
 3. `default` profile (if it exists)
 4. No profile (base configs only)
 
-### Configuration Isolation
+### Configuration Merging
 
-OCX configs (`ocx.jsonc`) are **ISOLATED per scope** - they do NOT merge.
+OCX configs (`ocx.jsonc`) **merge when using profiles**:
 
-**Registry Isolation (Security Model):**
-- **Global registries** (in `~/.config/opencode/ocx.jsonc`) - ONLY used for downloading global settings like profiles
-- **Profile registries** (in profile's `ocx.jsonc`) - ONLY available when using that profile
-- **Local registries** (in `.opencode/ocx.jsonc`) - ONLY for that project
+**Profile Layering:**
+- Global profile + local profile (if both exist with same name) = merged config
+- Deep merge with local winning on conflicts
+- Registries merge (local adds to global)
+- Arrays replace (local wins)
 
-This prevents global registries from injecting components into all projects.
-
-**What DOES merge:**
-- OpenCode config files (`opencode.jsonc`) merge: profile → local (if not excluded by patterns)
-- Profile's exclude/include patterns control which project files OpenCode can see
+**Registry Isolation:**
+Global base config registries are ONLY used for downloading profiles, not components.
+When using a profile, registries come from merged profile config.
 
 ### How `ocx opencode` Works
 
@@ -318,26 +315,38 @@ This prevents global registries from injecting components into all projects.
 
 ### Instruction File Discovery
 
-By default, all project instruction files are excluded so only your profile's files are used.
+OCX doesn't exclude anything by default. A clean ocx.jsonc includes all project instruction files. The default profile template ships an exclude list for security.
 
-**Default exclude patterns:**
-- `**/AGENTS.md`
-- `**/CLAUDE.md`
-- `**/CONTEXT.md`
-- `**/.opencode/**`
-- `**/opencode.jsonc`
-- `**/opencode.json`
+**The default profile template uses this exclude list:**
+
+```jsonc
+{
+  "exclude": [
+    "**/AGENTS.md",
+    "**/CLAUDE.md",
+    "**/CONTEXT.md",
+    "**/.opencode/**",
+    "**/opencode.jsonc",
+    "**/opencode.json"
+  ]
+}
+```
 
 **To include project files**, modify your profile's `ocx.jsonc`:
 
 ```jsonc
 {
-  // Include all project AGENTS.md files
-  "exclude": ["**/CLAUDE.md", "**/CONTEXT.md", "**/.opencode/**", "**/opencode.jsonc", "**/opencode.json"],
-
-  // Or exclude all but include specific ones (TypeScript/Vite style)
-  "exclude": ["**/AGENTS.md"],
-  "include": ["./docs/AGENTS.md"]
+  // Include all project AGENTS.md files by removing from exclude
+  "exclude": ["**/CLAUDE.md", "**/CONTEXT.md", "**/.opencode/**", "**/opencode.jsonc", "**/opencode.json"]
+}
+```
+
+Or use include patterns to override excludes (TypeScript/Vite style):
+
+```jsonc
+{
+  "exclude": ["**/AGENTS.md", "**/CLAUDE.md", "**/CONTEXT.md", "**/.opencode/**", "**/opencode.jsonc", "**/opencode.json"],
+  "include": ["./docs/AGENTS.md"]  // Include only specific file
 }
 ```
 
@@ -395,15 +404,6 @@ Use profile commands to manage multiple configurations:
 | `ocx init` | - | Initialize local .opencode/ |
 | `ocx init --global` | - | Initialize global profiles |
 
-#### Ghost Commands (TEMPORARY)
-
-| Command | Alias | Description |
-|---------|-------|-------------|
-| `ocx ghost migrate` | - | Migrate ghost.jsonc to ocx.jsonc in profiles |
-| `ocx ghost migrate --dry-run` | - | Preview migration without making changes |
-
-**Note:** The ghost command group is temporary and will be removed in the next minor version. It helps users migrate from the legacy "ghost mode" configuration format (`ghost.jsonc`) to the unified profile system (`ocx.jsonc`).
-
 #### Self Commands
 
 | Command | Description |
@@ -435,13 +435,13 @@ Use profile commands to manage multiple configurations:
 # Initialize global profiles
 ocx init --global
 
-# Create and use a work profile
-ocx profile add work
+# Create and use a global work profile
+ocx profile add work --global
 ocx config edit -p work  # Edit profile settings
 
 # Install profile from registry (requires global registry config)
 ocx registry add https://ocx-kit.kdco.dev --name kit --global
-ocx profile add ws --from kit/ws
+ocx profile add ws --from kit/ws --global
 
 # Force overwrite existing profile
 ocx profile add ws --from kit/ws --force
@@ -453,7 +453,7 @@ ocx opencode -p work
 OCX_PROFILE=work ocx opencode
 
 # Clone settings from existing profile
-ocx profile add client-x --from work
+ocx profile add client-x --from work --global
 
 # View configuration from current scope
 ocx config show

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -32,12 +32,12 @@ Your `registry.jsonc` defines a namespace for all components:
   "components": [
     {
       "name": "component",
-      "type": "ocx:plugin",
+      "type": "plugin",
       "description": "What it does",
       "files": [
         {
           "path": "plugin/my-plugin.ts",
-          "target": ".opencode/plugin/component.ts"
+          "target": "plugin/component.ts"
         }
       ],
       "dependencies": []
@@ -94,10 +94,8 @@ Use the `ocx-dev` profile to keep testing completely separate.
 #### Setup ocx-dev Profile (One-time)
 
 ```bash
-# Create the ocx-dev profile
+# Create a LOCAL profile for isolated testing (not --global, intentionally project-scoped)
 ./packages/cli/dist/index.js profile add ocx-dev
-
-# Profile is automatically available for use
 ```
 
 #### Quick Feature Testing
@@ -198,7 +196,6 @@ Key test scenarios:
 - `--all` flag updates all components
 - `--registry` flag scopes to registry
 - `--dry-run` previews without changes
-- `@version` syntax pins to specific version
 - Error cases (conflicts, missing components)
 
 > **Note:** For quick manual testing or AI-driven testing, prefer Profile Mode Testing above.

diff --git a/README.md b/README.md
@@ -9,9 +9,9 @@ Your OpenCode config, anywhere.
 
 ## Why OCX?
 
-- 👻 **Profiles** — Work in any repo with YOUR config. Control exactly what OpenCode sees.
+- 📁 **Profiles** — Work in any repo with YOUR config. Control exactly what OpenCode sees.
 - 📦 **Registries** — npm plugins, MCP servers, components from curated registries.
-- 🔒 **Auditable** — SHA-256 verified, version-pinned, code you own.
+- 🔒 **Auditable** — SHA-verified, code you own.
 
 ![OCX Profiles Demo](./assets/profiles-demo.gif)
 
@@ -38,11 +38,11 @@ Work in any repo without modifying it. Your config, their code.
 ```bash
 # One-time setup
 ocx init --global           # Initialize global profiles
-ocx profile add work        # Create a work profile
+ocx profile add work --global  # Create a global work profile
 
 # Install pre-configured profile (optional)
 ocx registry add https://ocx-kit.kdco.dev --name kit --global
-ocx profile add work --from kit/omo
+ocx profile add work --from kit/omo --global
 
 # Use in any repo
 cd ~/oss/some-project
@@ -55,7 +55,7 @@ ocx oc                      # Uses work profile automatically
 
 Profile settings control what OpenCode sees through `exclude`/`include` patterns. Registries are isolated per profile for security. OpenCode config merges safely between profile and local settings.
 
-> **Security Note:** By default, profiles include project `AGENTS.md` files. For untrusted repos, uncomment `**/AGENTS.md` in your profile's exclude list. See [Lock Down Recipe](./docs/PROFILES.md#lock-down-recipe).
+> **Security Note:** An empty exclude list includes all project instruction files; the default profile template ships a secure exclude list. For trusted repos, edit your profile to loosen the template's exclude list. See [Lock Down Recipe](./docs/PROFILES.md#lock-down-recipe).
 
 **[Full Profile Guide →](./docs/PROFILES.md)**
 
@@ -66,26 +66,30 @@ Add components to local projects with automatic dependency resolution.
 ![OCX Components Demo](./assets/components-demo.gif)
 
 ```bash
-# Initialize local config
+# Initialize local config if not present
 ocx init
 
-# Add a registry
-ocx registry add https://registry.kdco.dev --name kdco
-
-# Install components
-ocx add kdco/workspace
+# One-command install with ephemeral registry (not saved)
+ocx add kdco/workspace --from https://registry.kdco.dev
 
 # Or install npm plugins directly
 ocx add npm:@franlol/opencode-md-table-formatter
 ```
 
 After installation, components live in `.opencode/` where you can customize freely. OCX handles npm dependencies, MCP servers, and config merging automatically.
 
+To add a registry permanently for your project:
+
+```bash
+ocx registry add https://registry.kdco.dev --name kdco
+ocx add kdco/workspace
+```
+
 ## Philosophy
 
 OCX follows the **ShadCN model**: components are copied into your project (`.opencode/`), not hidden in `node_modules`. You own the code—customize freely.
 
-Like **Cargo**, OCX resolves dependencies, pins versions, and verifies integrity. Every component is SHA-256 verified and version-pinned. See changes before updating:
+Like **Cargo**, OCX resolves dependencies and verifies integrity. Every component is SHA-256 verified. See changes before updating:
 
 ```bash
 ocx diff kdco/workspace
@@ -98,13 +102,14 @@ ocx diff kdco/workspace
 | Command | Description |
 |---------|-------------|
 | `ocx add <component>` | Add components or npm plugins (`npm:package`) |
+| `ocx add <component> --from <url>` | One-command install with ephemeral registry (not saved) |
 | `ocx update [component]` | Update to latest version |
 | `ocx diff [component]` | Show upstream changes before updating |
 | `ocx profile <cmd>` | Manage global profiles (`add`, `list`, `remove`, `show`) |
 | `ocx opencode` / `ocx oc` | Launch OpenCode with profile |
-| `ocx registry add <url>` | Add a component registry (`--global` for global, `-p` for profile) |
+| `ocx registry add <url>` | Add a component registry (local-first; use `--global` for global) |
 | `ocx config show` | View config from current scope |
-| `ocx config edit` | Edit local or global config (`--global`) |
+| `ocx config edit` | Edit local config (use `--global` for global) |
 | `ocx self update` | Update OCX to latest version |
 | `ocx self uninstall` | Remove OCX config and binary |
 

diff --git a/SECURITY.md b/SECURITY.md
@@ -6,9 +6,9 @@ OCX uses SHA-256 cryptographic hashes to ensure installed components haven't bee
 
 ### How it works
 
-1. **Locking**: When a component is first installed, its content is hashed and stored in `ocx.lock`.
+1. **Receipt**: When a component is first installed, its content is hashed and stored in `.ocx/receipt.jsonc`.
 2. **Verification**: On subsequent installs or updates, OCX re-hashes the incoming content.
-3. **Protection**: If the new hash doesn't match the one in `ocx.lock`, the installation is aborted with an `INTEGRITY_ERROR`.
+3. **Protection**: If the new hash doesn't match the one in `.ocx/receipt.jsonc`, the installation is aborted with an `INTEGRITY_ERROR`.
 
 This ensures that once a version is approved and locked by your team, it cannot be silently swapped for different content, even if the registry itself is compromised.