opkg 0.5.0 → 0.6.0

package/dist/utils/root-file-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"root-file-registry.js","sourceRoot":"","sources":["../../src/utils/root-file-registry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAiB,MAAM,uBAAuB,CAAC;AACrE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE9E;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,WAAmB,EACnB,OAAe;IAEf,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC5C,MAAM,WAAW,GAAG,qBAAqB,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IAEhE,IAAI,CAAC,CAAC,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC;QACjC,MAAM,CAAC,KAAK,CAAC,wCAAwC,WAAW,EAAE,CAAC,CAAC;QACpE,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,sEAAsE;IACtE,MAAM,iBAAiB,GAAG,CAAC,GAAG,EAAE;QAC9B,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;QAC9B,KAAK,MAAM,QAAQ,IAAI,eAAe,EAAE,EAAE,CAAC;YACzC,MAAM,GAAG,GAAG,qBAAqB,CAAC,QAAQ,CAAC,CAAC;YAC5C,IAAI,GAAG,CAAC,QAAQ;gBAAE,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC1C,CAAC;QACD,wEAAwE;QACxE,GAAG,CAAC,GAAG,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;QACjC,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IAClC,CAAC,CAAC,EAAE,CAAC;IAEL,gCAAgC;IAChC,KAAK,MAAM,YAAY,IAAI,iBAAiB,EAAE,CAAC;QAC7C,MAAM,YAAY,GAAG,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;QAErD,IAAI,MAAM,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC;YAC/B,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,YAAY,CAAC,CAAC;gBACjD,IAAI,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC;oBACnB,SAAS,CAAC,GAAG,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;oBACrC,MAAM,CAAC,KAAK,CAAC,gCAAgC,YAAY,QAAQ,WAAW,IAAI,OAAO,EAAE,CAAC,CAAC;gBAC7F,CAAC;YACH,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,CAAC,IAAI,CAAC,4BAA4B,YAAY,mBAAmB,KAAK,EAAE,CAAC,CAAC;YAClF,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,QAAgB;IACrD,6DAA6D;IAC7D,IAAI,QAAQ,KAAK,aAAa,CAAC,SAAS,EAAE,CAAC;QACzC,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,qCAAqC;IACrC,KAAK,MAAM,QAAQ,IAAI,eAAe,EAAE,EAAE,CAAC;QACzC,MAAM,GAAG,GAAG,qBAAqB,CAAC,QAAQ,CAAC,CAAC;QAC5C,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YAC9B,OAAO,QAAQ,CAAC;QAClB,CAAC;IACH,CAAC;IAED,oBAAoB;IACpB,OAAO,WAAW,CAAC;AACrB,CAAC"}
+{"version":3,"file":"root-file-registry.js","sourceRoot":"","sources":["../../src/utils/root-file-registry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAiB,MAAM,sBAAsB,CAAC;AAE7F;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,WAAmB,EACnB,OAAe;IAEf,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC5C,MAAM,WAAW,GAAG,qBAAqB,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IAEhE,IAAI,CAAC,CAAC,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC;QACjC,MAAM,CAAC,KAAK,CAAC,wCAAwC,WAAW,EAAE,CAAC,CAAC;QACpE,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,sEAAsE;IACtE,MAAM,iBAAiB,GAAG,CAAC,GAAG,EAAE;QAC9B,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;QAC9B,KAAK,MAAM,QAAQ,IAAI,eAAe,EAAE,EAAE,CAAC;YACzC,MAAM,GAAG,GAAG,qBAAqB,CAAC,QAAQ,CAAC,CAAC;YAC5C,IAAI,GAAG,CAAC,QAAQ;gBAAE,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC1C,CAAC;QACD,wEAAwE;QACxE,GAAG,CAAC,GAAG,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;QACjC,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IAClC,CAAC,CAAC,EAAE,CAAC;IAEL,gCAAgC;IAChC,KAAK,MAAM,YAAY,IAAI,iBAAiB,EAAE,CAAC;QAC7C,MAAM,YAAY,GAAG,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;QAErD,IAAI,MAAM,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC;YAC/B,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,YAAY,CAAC,CAAC;gBACjD,IAAI,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC;oBACnB,SAAS,CAAC,GAAG,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;oBACrC,MAAM,CAAC,KAAK,CAAC,gCAAgC,YAAY,QAAQ,WAAW,IAAI,OAAO,EAAE,CAAC,CAAC;gBAC7F,CAAC;YACH,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,CAAC,IAAI,CAAC,4BAA4B,YAAY,mBAAmB,KAAK,EAAE,CAAC,CAAC;YAClF,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,QAAgB;IACrD,6DAA6D;IAC7D,IAAI,QAAQ,KAAK,aAAa,CAAC,SAAS,EAAE,CAAC;QACzC,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,qCAAqC;IACrC,KAAK,MAAM,QAAQ,IAAI,eAAe,EAAE,EAAE,CAAC;QACzC,MAAM,GAAG,GAAG,qBAAqB,CAAC,QAAQ,CAAC,CAAC;QAC5C,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YAC9B,OAAO,QAAQ,CAAC;QAClB,CAAC;IACH,CAAC;IAED,oBAAoB;IACpB,OAAO,WAAW,CAAC;AACrB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opkg",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "publishConfig": {
     "access": "public"
   },
@@ -40,13 +40,14 @@
     "dev:watch": "nodemon --exec ts-node src/index.ts",
     "clean": "rm -rf dist",
     "prepublishOnly": "npm run build",
-    "test": "node --loader ts-node/esm tests/save-pack-versioning.test.ts && node --loader ts-node/esm tests/install-cli-modes.test.ts && node --loader ts-node/esm tests/install-selection.test.js && node --loader ts-node/esm tests/version-selection.test.ts && node --loader ts-node/esm tests/push-stable-selection.test.ts"
+    "test": "TS_NODE_TRANSPILE_ONLY=1 node --loader ts-node/esm tests/save-pack-versioning.test.ts && TS_NODE_TRANSPILE_ONLY=1 node --loader ts-node/esm tests/install-cli-modes.test.ts && TS_NODE_TRANSPILE_ONLY=1 node --loader ts-node/esm tests/install-selection.test.ts && TS_NODE_TRANSPILE_ONLY=1 node --loader ts-node/esm tests/version-selection.test.ts && TS_NODE_TRANSPILE_ONLY=1 node --loader ts-node/esm tests/push-stable-selection.test.ts && TS_NODE_TRANSPILE_ONLY=1 node --loader ts-node/esm tests/workspace-paths.test.ts && TS_NODE_TRANSPILE_ONLY=1 node --loader ts-node/esm tests/platform-extension-filter.test.ts && TS_NODE_TRANSPILE_ONLY=1 node --loader ts-node/esm tests/package-filters.test.ts"
   },
   "dependencies": {
     "commander": "^14.0.0",
     "gray-matter": "^4.0.3",
     "hash-wasm": "^4.12.0",
     "js-yaml": "^4.1.0",
+    "jsonc-parser": "^3.3.1",
     "junk": "^4.0.1",
     "nanoid": "^5.0.7",
     "prompts": "^2.4.2",

package/platforms.jsonc

@@ -0,0 +1,178 @@
+{
+  // Platform definitions for all supported AI coding platforms
+  // Each platform defines its directory structure, root files, and subdirectories
+
+  "augment": {
+    "name": "Augment Code",
+    "rootDir": ".augment",
+    "subdirs": {
+      "rules": {
+        "path": "rules",
+        "exts": [".md"]
+      },
+      "commands": {
+        "path": "commands",
+        "exts": [".md"]
+      }
+    }
+  },
+
+  "claude": {
+    "name": "Claude Code",
+    "rootDir": ".claude",
+    "rootFile": "CLAUDE.md",
+    "aliases": ["claudecode"],
+    "subdirs": {
+      "commands": {
+        "path": "commands",
+        "exts": [".md"]
+      },
+      "agents": {
+        "path": "agents",
+        "exts": [".md"]
+      },
+      "skills": {
+        "path": "skills"
+      }
+    }
+  },
+
+  "codex": {
+    "name": "Codex CLI",
+    "rootDir": ".codex",
+    "rootFile": "AGENTS.md",
+    "aliases": ["codexcli"],
+    "subdirs": {
+      "commands": {
+        "path": "prompts",
+        "exts": [".md"]
+      }
+    }
+  },
+
+  "cursor": {
+    "name": "Cursor",
+    "rootDir": ".cursor",
+    "rootFile": "AGENTS.md",
+    "subdirs": {
+      "rules": {
+        "path": "rules",
+        "exts": [".mdc", ".md"],
+        "transformations": [
+          {
+            "packageExt": ".md",
+            "workspaceExt": ".mdc"
+          }
+        ]
+      },
+      "commands": {
+        "path": "commands",
+        "exts": [".md"]
+      }
+    }
+  },
+
+  "factory": {
+    "name": "Factory AI",
+    "rootDir": ".factory",
+    "rootFile": "AGENTS.md",
+    "subdirs": {
+      "commands": {
+        "path": "commands",
+        "exts": [".md"]
+      },
+      "agents": {
+        "path": "droids",
+        "exts": [".md"]
+      }
+    }
+  },
+
+  "kilo": {
+    "name": "Kilo Code",
+    "rootDir": ".kilocode",
+    "rootFile": "AGENTS.md",
+    "aliases": ["kilocode"],
+    "subdirs": {
+      "rules": {
+        "path": "rules",
+        "exts": [".md"]
+      },
+      "commands": {
+        "path": "workflows",
+        "exts": [".md"]
+      }
+    }
+  },
+
+  "kiro": {
+    "name": "Kiro",
+    "rootDir": ".kiro",
+    "subdirs": {
+      "rules": {
+        "path": "steering",
+        "exts": [".md"]
+      }
+    }
+  },
+
+  "opencode": {
+    "name": "OpenCode",
+    "rootDir": ".opencode",
+    "rootFile": "AGENTS.md",
+    "subdirs": {
+      "commands": {
+        "path": "command",
+        "exts": [".md"]
+      },
+      "agents": {
+        "path": "agent",
+        "exts": [".md"]
+      }
+    }
+  },
+
+  "qwen": {
+    "name": "Qwen Code",
+    "rootDir": ".qwen",
+    "rootFile": "QWEN.md",
+    "aliases": ["qwencode"],
+    "subdirs": {
+      "agents": {
+        "path": "agents",
+        "exts": [".md"]
+      }
+    }
+  },
+
+  "roo": {
+    "name": "Roo Code",
+    "rootDir": ".roo",
+    "rootFile": "AGENTS.md",
+    "subdirs": {
+      "commands": {
+        "path": "commands",
+        "exts": [".md"]
+      }
+    }
+  },
+
+  "warp": {
+    "name": "Warp",
+    "rootDir": ".warp",
+    "rootFile": "WARP.md",
+    "subdirs": {}
+  },
+
+  "windsurf": {
+    "name": "Windsurf",
+    "rootDir": ".windsurf",
+    "subdirs": {
+      "rules": {
+        "path": "rules",
+        "exts": [".md"]
+      }
+    }
+  }
+}
+

package/specs/package/README.md

@@ -0,0 +1,60 @@
+### Canonical Universal Package Structure
+
+This directory contains the canonical on-disk structure spec for OpenPackage packages, split into focused documents:
+
+- **Root layout**: `package-root-layout.md` – Package directory structure and content types
+- **Universal content**: `universal-content.md` – Platform-normalized content under `.openpackage/`
+- **Package index**: `package-index-yml.md` – File mapping and `package.index.yml` structure
+- **Registry payload and 1:1 copy rules**: `registry-payload-and-copy.md` – What gets included in packages
+- **Nested packages and parent packages**: `nested-packages-and-parent-packages.md` – Multi-package workspaces
+
+---
+
+#### Core Concept: Package Root
+
+A **package root** is any directory containing `.openpackage/package.yml`. This applies to:
+
+- **Workspace root package**: `cwd/` is the package root
+- **Nested packages**: `cwd/.openpackage/packages/<name>/` is the package root
+- **Registry copies**: `~/.openpackage/registry/<name>/<version>/` is the package root
+
+All package roots have **identical internal structure**:
+
+```text
+<package-root>/
+  .openpackage/
+    package.yml              # marks this as a package
+    package.index.yml        # install index (not in registry)
+    commands/                # universal content
+    rules/
+    agents/
+    skills/
+  <root-dir>/                # root-level content (outside .openpackage/)
+  AGENTS.md                  # root files
+  README.md
+```
+
+---
+
+#### Two Types of Content
+
+| Type | Location | Example |
+|------|----------|---------|
+| **Universal content** | `.openpackage/<subdir>/` | `.openpackage/commands/test.md` |
+| **Root-level content** | At package root (outside `.openpackage/`) | `<dir>/helper.md`, `AGENTS.md` |
+
+**Universal content** is mapped to platform-specific paths during install.  
+**Root-level content** is copied 1:1 without transformation.
+
+---
+
+#### Design Goal
+
+A package directory can be **moved or copied 1:1** between:
+
+- Workspace root packages (`cwd/`)
+- Nested workspace packages (`cwd/.openpackage/packages/<name>/`)
+- Local registry copies (`~/.openpackage/registry/<name>/<version>/`)
+
+…while preserving the same internal layout and invariants.
+

package/specs/package/nested-packages-and-parent-packages.md

@@ -0,0 +1,79 @@
+### Nested Packages and Parent Packages
+
+#### Workspace Structure with Nested Packages
+
+```text
+<workspace-root>/                              # root package (package root = cwd/)
+  .openpackage/
+    package.yml                                # root package manifest
+    package.index.yml                          # root package index
+    commands/                                  # root package universal content
+      shared-command.md
+    rules/
+      shared-rule.md
+  <root-dir>/                                  # root package root-level content (any directory)
+    workspace-helper.md
+  AGENTS.md                                    # root package root file
+  packages/                                    # nested packages directory (workspace root only)
+    alpha/                                     # nested package (package root = .openpackage/packages/alpha/)
+      .openpackage/
+        package.yml
+        package.index.yml
+        commands/
+          alpha-command.md
+      <root-dir>/                              # nested package root-level content
+        alpha-helper.md
+    beta/                                      # nested package (package root = .openpackage/packages/beta/)
+      .openpackage/
+        package.yml
+        package.index.yml
+        rules/
+          beta-rule.md
+```
+
+---
+
+#### Key Rules
+
+- Each `packages/<name>/` directory is its **own canonical package root**, with:
+  - Its own `.openpackage/package.yml` (marks it as a package)
+  - Its own `.openpackage/` content directory
+  - Its own root-level content (outside `.openpackage/`)
+
+- The **parent root package never inlines** `packages/<name>/` into its own payload.
+
+- Registry entries for `alpha` and `beta` are created **independently** from their respective package roots.
+
+- **Only the workspace root package** can have a `packages/` directory. Nested packages cannot have further nested packages.
+
+---
+
+#### Package Root Locations
+
+| Package Type | Package Root Path |
+|--------------|-------------------|
+| Workspace root | `cwd/` |
+| Nested `alpha` | `cwd/.openpackage/packages/alpha/` |
+| Nested `beta` | `cwd/.openpackage/packages/beta/` |
+
+---
+
+#### Identical Internal Structure
+
+Both root and nested packages have **identical internal structure**:
+
+```text
+<package-root>/
+  .openpackage/
+    package.yml
+    package.index.yml
+    <universal-subdirs>/
+  <root-level-content>/
+  <root-files>
+```
+
+This uniformity ensures packages can be:
+- Moved between workspace root and nested locations
+- Copied to/from registry without structural changes
+- Processed by the same code paths regardless of location
+

package/specs/package/package-index-yml.md

@@ -0,0 +1,171 @@
+### Package Index File (`package.index.yml`)
+
+The `package.index.yml` file tracks the mapping between package files and their **actually installed** workspace locations.
+
+---
+
+#### Location
+
+- **Root package**: `cwd/.openpackage/package.index.yml`
+- **Nested package**: `cwd/.openpackage/packages/<name>/.openpackage/package.index.yml`
+
+> **Note**: `package.index.yml` is **never** included in the registry payload. It's workspace-local metadata.
+
+---
+
+#### Excluded Content
+
+The following files are **never** included in the index, even though they may exist in the package:
+
+| File | Reason |
+|------|--------|
+| `package.yml` | Package manifest; not synced to workspace |
+| `.openpackage/package.yml` | Same as above (path variant) |
+| `package.index.yml` | Index file itself; workspace-local metadata |
+
+The index only contains entries for content that is **actually synced** to workspace locations.
+
+---
+
+#### Structure
+
+```yaml
+# This file is managed by OpenPackage. Do not edit manually.
+
+workspace:
+  hash: <workspace-hash>
+  version: <installed-version>
+files:
+  <registry-key>:
+    - <installed-path>
+    - <installed-path>
+  <registry-key>:
+    - <installed-path>
+```
+
+---
+
+#### Registry Keys
+
+Registry keys are **relative to the package root**:
+
+| Content Type | Key Format | Example |
+|--------------|------------|---------|
+| Universal content | `.openpackage/<subdir>/<file>` | `.openpackage/commands/test.md` |
+| Root-level content | `<path>` | `<dir>/helper.md` |
+| Root files | `<filename>` | `AGENTS.md` |
+
+---
+
+#### Values (Installed Paths)
+
+Values are **relative to the workspace root (`cwd`)** and represent **paths that actually exist**:
+
+| Content Type | Value Format | Example |
+|--------------|--------------|---------|
+| Universal content | Platform-specific paths | `.cursor/commands/test.md`, `.opencode/commands/test.md` |
+| Root-level content | Same as key | `ai/helper.md` |
+
+> **Important**: The index only records paths where files **actually exist**. If a file is only installed to one platform (e.g., `.cursor/`), only that path appears in the index—not hypothetical paths for other platforms.
+
+---
+
+#### Index Update Behavior
+
+The index is updated differently depending on the operation:
+
+| Operation | Behavior |
+|-----------|----------|
+| **Add** | Records only the source path that was used to add the file. If you add `.cursor/commands/test.md`, only that path is recorded. |
+| **Save/Sync** | Expands the index to include all platform paths where files were actually created during sync. |
+| **Install** | Populates the index with all platform paths where files were installed. |
+
+This ensures the index reflects the **current state** of the workspace, not hypothetical future states.
+
+---
+
+#### Root Package Skip Logic
+
+For **root packages only**, when a registry key maps to the exact same value, the mapping is **skipped** because:
+- The file is already at the correct location
+- No installation/syncing needed
+- Avoids redundant mappings
+
+**Example**: For a root package, `<dir>/helper.md` → `<dir>/helper.md` is skipped.
+
+---
+
+#### Nested Package Full Mapping
+
+For **nested packages**, all mappings are included because:
+- Files live inside the nested package directory
+- Need to be mapped OUT to workspace root during install
+
+**Example**: For nested package `foo`:
+- File at `.openpackage/packages/foo/<dir>/helper.md`
+- Key: `<dir>/helper.md`
+- Value: `<dir>/helper.md` (installed at workspace root)
+
+---
+
+#### Complete Examples
+
+**After `opkg add .cursor/commands/test.md`** (only source path recorded):
+
+```yaml
+workspace:
+  hash: abc123
+  version: 1.0.0-abc123.xyz
+files:
+  .openpackage/commands/test.md:
+    - .cursor/commands/test.md    # Only the source path that exists
+```
+
+**After `opkg save`** (all synced paths recorded):
+
+```yaml
+workspace:
+  hash: abc123
+  version: 1.0.0-abc123.xyz
+files:
+  .openpackage/commands/test.md:
+    - .cursor/commands/test.md    # Original source
+    - .opencode/command/test.md   # Synced by save
+  .openpackage/rules/auth.md:
+    - .cursor/rules/auth.mdc
+  # Note: package.yml is NOT included (it's the manifest, not synced content)
+  # Note: <dir>/helper.md is SKIPPED for root packages (maps to itself)
+```
+
+**Nested package** (`cwd/.openpackage/packages/foo/.openpackage/package.index.yml`):
+
+```yaml
+workspace:
+  hash: abc123
+  version: 1.0.0
+files:
+  .openpackage/commands/test.md:
+    - .cursor/commands/test.md
+    - .opencode/command/test.md
+  <dir>/helper.md:
+    - <dir>/helper.md
+  AGENTS.md:
+    - AGENTS.md
+```
+
+---
+
+#### Add Command Examples
+
+When adding files, the index only records the **source path that exists**:
+
+| Command | Package | Stored At | Registry Key | Values (in index) |
+|---------|---------|-----------|--------------|-------------------|
+| `opkg add foo <dir>/foo.md` | Nested `foo` | `.openpackage/packages/foo/<dir>/foo.md` | `<dir>/foo.md` | `<dir>/foo.md` |
+| `opkg add foo .cursor/test/foo.md` | Nested `foo` | `.openpackage/packages/foo/.openpackage/test/foo.md` | `.openpackage/test/foo.md` | `.cursor/test/foo.md` (only source) |
+| `opkg add <dir>/foo.md` | Root | `.openpackage/<dir>/foo.md` | `<dir>/foo.md` | SKIPPED |
+| `opkg add .cursor/test/foo.md` | Root | `.openpackage/test/foo.md` | `.openpackage/test/foo.md` | `.cursor/test/foo.md` (only source) |
+
+> **Note**: After `opkg save`, the index will expand to include other platform paths (e.g., `.opencode/test/foo.md`) once those files are actually synced.
+
+

package/specs/package/package-root-layout.md

@@ -0,0 +1,78 @@
+### Package Root Layout
+
+Every package root directory (workspace root, nested, or registry) uses this structure:
+
+```text
+<package-root>/
+  .openpackage/                # REQUIRED – package content directory
+    package.yml                # REQUIRED – package manifest (marks this as a package)
+    package.index.yml          # OPTIONAL – install/index metadata (never in registry payload)
+    agents/                    # universal content subdirs
+    rules/
+    commands/
+    skills/
+    <custom-subdirs>/          # any additional universal content
+  <root-dirs>/                 # OPTIONAL – root-level content (outside .openpackage/)
+  AGENTS.md                    # OPTIONAL – universal root file
+  <other-root-files>           # OPTIONAL – platform-specific root files (e.g. CLAUDE.md)
+  README.md                    # OPTIONAL – documentation
+  packages/                    # OPTIONAL – nested packages (workspace root only)
+```
+
+---
+
+#### Two Types of Package Content
+
+1. **Root-level content** (outside `.openpackage/`):
+   - Any files/directories at the package root (e.g., `<dir>/foo.md`, `AGENTS.md`, `CLAUDE.md`)
+   - Live directly at the package root level, outside `.openpackage/`
+   - Stored and mapped without transformation
+
+2. **Universal content** (inside `.openpackage/`):
+   - Platform-normalized files stored under `.openpackage/<subdir>/`
+   - Source files like `.cursor/commands/test.md` are normalized to `.openpackage/commands/test.md`
+   - Mapped to platform-specific locations during install (e.g., `.cursor/commands/`, `.opencode/commands/`)
+
+---
+
+#### Key Invariants
+
+- **`.openpackage/package.yml`** marks a directory as a package root.
+- **Universal content** (rules, agents, commands, skills, custom subdirs) lives **under `.openpackage/`**.
+- **Root-level content** (any directories/files outside `.openpackage/`) lives **at the package root** (sibling of `.openpackage/`).
+- **Nested packages** live under `packages/` and are treated as **independent packages**.
+- The **same structure** applies to workspace root packages, nested packages, and registry copies.
+
+---
+
+#### Concrete Examples
+
+**Workspace root package** (package root = `cwd/`):
+
+```text
+cwd/
+  .openpackage/
+    package.yml
+    package.index.yml
+    commands/
+      test.md
+    rules/
+      auth.md
+  <root-dir>/                  # any root-level directory
+    helper.md
+  AGENTS.md
+```
+
+**Nested package** (package root = `cwd/.openpackage/packages/foo/`):
+
+```text
+cwd/.openpackage/packages/foo/
+  .openpackage/
+    package.yml
+    package.index.yml
+    commands/
+      test.md
+  <root-dir>/                  # any root-level directory
+    helper.md
+```
+

package/specs/package/registry-payload-and-copy.md

@@ -0,0 +1,77 @@
+### Registry Payload and 1:1 Copy
+
+The **registry payload** for a given version is defined by two layers of rules.
+
+---
+
+#### 1. Static Rules
+
+**Always exclude:**
+- `package.index.yml` (workspace-local metadata)
+- Anything under `packages/` (nested packages are separate units)
+
+**Always include (cannot be excluded):**
+- `.openpackage/package.yml` (package manifest)
+
+**Included by default (removable via manifest `exclude`):**
+- Every platform root file declared in `platforms.jsonc` (e.g., `CLAUDE.md`, `WARP.md`, `AGENTS.md`) when it exists
+- Any `.openpackage/<universal-subdir>/…` directory (agents, rules, commands, skills, etc.)
+- Any root-level content (directories/files at package root, outside `.openpackage/`)
+
+**Everything else starts excluded by default.**
+
+---
+
+#### 2. Manifest Filters
+
+In `package.yml`:
+
+- **`include`** (array): Expands the payload by listing additional glob-like patterns relative to the package root
+- **`exclude`** (array): Removes matches after include rules are applied (but never overrides hard includes/excludes)
+
+> **Note**: Newly created nested packages default their `package.yml` to `include: ["**"]`, so they start including all files until the author narrows the list.
+
+---
+
+#### Save and Install Operations
+
+**When saving:**
+
+1. The save pipeline reads files from the package root using the rules above
+2. Files are written **unchanged** to: `~/.openpackage/registry/<name>/<version>/...`
+
+**When installing:**
+
+1. The install pipeline loads `pkg.files` from the registry
+2. Files are written 1:1 to: `cwd/.openpackage/packages/<name>/...` for local cache
+3. Universal content is mapped to platform-specific locations in the workspace
+
+---
+
+#### Package Structure in Registry
+
+Registry copies maintain the same structure as workspace packages:
+
+```text
+~/.openpackage/registry/<name>/<version>/
+  .openpackage/
+    package.yml                # package manifest
+    commands/                  # universal content
+      test.md
+    rules/
+      auth.md
+  <root-dir>/                  # root-level content (any directory)
+    helper.md
+  AGENTS.md                    # root files
+```
+
+---
+
+#### Guarantees
+
+This system guarantees that:
+
+- The **workspace package**, **local cache**, and **registry version directory** all share the **same tree shape**
+- Save and install operations are **pure copies** at the package boundary, without structural rewrites
+- Packages can be moved between locations (workspace root ↔ nested ↔ registry) without modification
+