opkg 0.11.2 → 0.11.3

package/specs/cli-options.md

@@ -1,134 +0,0 @@
-# CLI Global Options
-
-This document specifies behavior for global CLI flags available across all `opkg` / `openpackage` commands.
-
-## `--cwd <dir>`
-
-### Overview
-The `--cwd` global option overrides the effective working directory for the entire command execution. It simulates running the CLI from `<dir>` instead of the shell's current directory, affecting:
-- Path resolutions (relative files, globs).
-- Package/workspace detection (e.g., `openpackage.yml` lookup at effective cwd).
-- File operations (install/add/uninstall/status target the specified dir's context).
-- Any code using `process.cwd()` (captured post-`--cwd` processing).
-
-This enables monorepo workflows without `cd` (e.g., `opkg install --cwd ./packages/web some-dep` installs into `./packages/web` from root).
-
-**Note**: The `--global` / `-g` flag (install and uninstall commands) **trumps** `--cwd`. If both are specified, `--cwd` is ignored and operations proceed in the home directory (`~/`).
-
-### Behavior
-1. **Parsing & Timing**: Commander parses it as global (usable before/after subcommand). Processed in `preAction` hook *before* subcommand action runs (after arg validation).
-2. **Resolution**: Resolved to absolute via `path.resolve(originalProcessCwd, <dir>)` (relatives vs shell cwd, not target).
-3. **Validation** (sync/async checks before chdir):
-   - Exists (fs.stat throws ENOENT if not).
-   - Is directory (fs.stat.isDirectory()).
-   - Readable/writable (fs.access R_OK | W_OK; errors if perms insufficient for cmd).
-   - Errors: Custom msg via console.error + log, `process.exit(1)` (e.g., "Invalid --cwd: must exist, be accessible, and writable").
-4. **chdir**: Calls `process.chdir(resolved)` if valid; logs "Changed working directory to: <abs>".
-5. **Effects**:
-   - All relative paths (e.g., getPackageYmlPath, file discovery) resolve vs new cwd.
-   - Package root = effective cwd (or --cwd dir).
-   - Global state unaffected (e.g., `~/.openpackage/registry` via os.homedir()).
-6. **Edge Cases**:
-   - Relative: `--cwd ../sibling` → resolves vs original.
-   - Invalid: Early exit, no action run.
-   - No-op: Omitted → uses shell cwd.
-   - Globals: Applies (harmless for login/logout; may affect utils like prompts for rel paths).
-   - Subprocesses: Inherit new cwd (if spawned).
-7. **Limitations**: Doesn't re-parse other args vs new cwd (resolved early). User scripts via exec may need own handling.
-
-### Usage Patterns
-- Monorepos: Target sub-packages without cd.
-- Scripts: `opkg install --cwd $PROJ_DIR`.
-- Validation fails prevent ops (safety).
-
-Cross-refs: [install-behavior.md] (installs to effective cwd), [package-root-layout.md] (root = effective cwd).
-
----
-
-## `-g, --global`
-
-### Overview
-The `--global` (or `-g`) flag changes the target directory for install and uninstall operations to the user's home directory (`~/`). This enables system-wide package installations that apply across all projects rather than being scoped to a single workspace.
-
-**Available on:** `install`, `uninstall`
-
-### Behavior
-1. **Directory Change**: When `--global` is present, the CLI changes the working directory to `os.homedir()` before executing the command.
-2. **Priority**: `--global` **trumps** `--cwd`. If both are provided, `--cwd` is ignored and operations proceed in `~/`.
-3. **Manifest**: Creates/updates `~/openpackage.yml` for dependency tracking.
-4. **Platform Files**: Installs to `~/.cursor/`, `~/.claude/`, `~/.opencode/`, etc.
-5. **Root Files**: Copies to `~/` (with `root/` prefix stripped).
-
-### Use Cases
-- **System-wide configurations**: AI coding rules/commands that apply to all projects
-- **Personal dotfiles**: Manage home directory configurations as packages
-- **Shared settings**: Common preferences across multiple workspaces
-
-### Examples
-
-#### Install
-```bash
-# Install package globally
-opkg install -g shared-rules
-opkg install --global shared-rules
-
-# With platforms specified
-opkg install -g cursor-config --platforms cursor claude
-
-# Global overrides --cwd
-opkg install -g my-package --cwd ./some-dir  # Installs to ~/, not ./some-dir
-```
-
-#### Uninstall
-```bash
-# Uninstall global package
-opkg uninstall -g shared-rules
-opkg uninstall --global shared-rules
-```
-
-### Validation
-- No special validation beyond standard directory checks (home directory should always exist and be writable)
-- If home directory is inaccessible, command fails early with appropriate error
-
-### Edge Cases
-- Works with any source type (registry, git, path, tarball)
-- Compatible with all other install/uninstall flags (`--platforms`, `--dry-run`, etc.)
-- `--cwd` is explicitly ignored when `--global` is present
-
-### Conditional Flows
-The `--global` flag enables conditional installation behavior through the `$$targetRoot` context variable in platform flows:
-
-**Platform Flow Example:**
-```jsonc
-{
-  "from": ["mcp.jsonc", "mcp.json"],
-  "to": ".mcp.json",
-  "when": { "$ne": ["$$targetRoot", "~/"] }  // Install to .mcp.json when NOT global
-},
-{
-  "from": ["mcp.jsonc", "mcp.json"],
-  "to": ".claude.json",
-  "when": { "$eq": ["$$targetRoot", "~/"] }  // Install to .claude.json when global
-}
-```
-
-**How it works:**
-- Normal install: `$$targetRoot` = workspace directory (e.g., `/Users/john/project`)
-- Global install: `$$targetRoot` = home directory (e.g., `/Users/john`)
-- Conditions use path-aware comparison with tilde expansion and glob support
-
-**Result:**
-- `opkg install plugin` → Files go to `.mcp.json` (workspace)
-- `opkg install -g plugin` → Files go to `.claude.json` (global)
-
-See [Flow Reference](./platforms/flow-reference.md) for details on `$$targetRoot` and conditional flows.
-
----
-
-## Command Notes (selected)
-
-This document primarily defines global flags, but some global-option-sensitive behavior is worth calling out:
-
-- **`opkg install`**: installs packages to the effective working directory (or home directory when using `--global`).
-- **`opkg add`**: adds files to mutable package sources. To sync changes to workspace, use `opkg install`.
-- **`opkg remove`**: removes files from mutable package sources. To sync deletions to workspace, use `opkg install`.

package/specs/codex-mcp.md

@@ -1,114 +0,0 @@
-# Model Context Protocol
-
-Model Context Protocol (MCP) connects models to tools and context. Use it to give Codex access to third-party documentation, or to let it interact with developer tools like your browser or Figma.
-
-Codex supports MCP servers in both the CLI and the IDE extension.
-
-## Supported MCP features
-
-- **STDIO servers**: Servers that run as a local process (started by a command).
-  - Environment variables
-- **Streamable HTTP servers**: Servers that you access at an address.
-  - Bearer token authentication
-  - OAuth authentication (run `codex mcp login <server-name>` for servers that support OAuth)
-
-## Connect Codex to an MCP server
-
-Codex stores MCP configuration in `~/.codex/config.toml` alongside other Codex configuration settings.
-
-The CLI and the IDE extension share this configuration. Once you configure your MCP servers, you can switch between the two Codex clients without redoing setup.
-
-To configure MCP servers, choose one option:
-
-1. **Use the CLI**: Run `codex mcp` to add and manage servers.
-2. **Edit `config.toml`**: Update `~/.codex/config.toml` directly.
-
-### Configure with the CLI
-
-#### Add an MCP server
-
-```bash
-codex mcp add <server-name> --env VAR1=VALUE1 --env VAR2=VALUE2 -- <stdio server-command>
-```
-
-For example, to add Context7 (a free MCP server for developer documentation), you can run the following command:
-
-```bash
-codex mcp add context7 -- npx -y @upstash/context7-mcp
-```
-
-#### Other CLI commands
-
-To see all available MCP commands, you can run `codex mcp --help`.
-
-#### Terminal UI (TUI)
-
-In the `codex` TUI, use `/mcp` to see your active MCP servers.
-
-### Configure with config.toml
-
-For more fine-grained control over MCP server options, edit `~/.codex/config.toml`. In the IDE extension, select **MCP settings** > **Open config.toml** from the gear menu.
-
-Configure each MCP server with a `[mcp_servers.<server-name>]` table in the configuration file.
-
-#### STDIO servers
-
-- `command` (required): The command that starts the server.
-- `args` (optional): Arguments to pass to the server.
-- `env` (optional): Environment variables to set for the server.
-- `env_vars` (optional): Environment variables to allow and forward.
-- `cwd` (optional): Working directory to start the server from.
-
-#### Streamable HTTP servers
-
-- `url` (required): The server address.
-- `bearer_token_env_var` (optional): Environment variable name for a bearer token to send in `Authorization`.
-- `http_headers` (optional): Map of header names to static values.
-- `env_http_headers` (optional): Map of header names to environment variable names (values pulled from the environment).
-
-#### Other configuration options
-
-- `startup_timeout_sec` (optional): Timeout (seconds) for the server to start. Default: `10`.
-- `tool_timeout_sec` (optional): Timeout (seconds) for the server to run a tool. Default: `60`.
-- `enabled` (optional): Set `false` to disable a server without deleting it.
-- `enabled_tools` (optional): Tool allow list.
-- `disabled_tools` (optional): Tool deny list (applied after `enabled_tools`).
-
-#### config.toml examples
-
-```toml
-[mcp_servers.context7]
-command = "npx"
-args = ["-y", "@upstash/context7-mcp"]
-
-[mcp_servers.context7.env]
-MY_ENV_VAR = "MY_ENV_VALUE"
-```
-
-```toml
-[mcp_servers.figma]
-url = "https://mcp.figma.com/mcp"
-bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
-http_headers = { "X-Figma-Region" = "us-east-1" }
-```
-
-```toml
-[mcp_servers.chrome_devtools]
-url = "http://localhost:3000/mcp"
-enabled_tools = ["open", "screenshot"]
-disabled_tools = ["screenshot"] # applied after enabled_tools
-startup_timeout_sec = 20
-tool_timeout_sec = 45
-enabled = true
-```
-
-## Examples of useful MCP servers
-
-The list of MCP servers keeps growing. Here are a few common ones:
-
-- [Context7](https://github.com/upstash/context7): Connect to up-to-date developer documentation.
-- Figma [Local](https://developers.figma.com/docs/figma-mcp-server/local-server-installation/) and [Remote](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/): Access your Figma designs.
-- [Playwright](https://www.npmjs.com/package/@playwright/mcp): Control and inspect a browser using Playwright.
-- [Chrome Developer Tools](https://github.com/ChromeDevTools/chrome-devtools-mcp/): Control and inspect Chrome.
-- [Sentry](https://docs.sentry.io/product/sentry-mcp/#codex): Access Sentry logs.
-- [GitHub](https://github.com/github/github-mcp-server): Manage GitHub beyond what `git` supports (for example, pull requests and issues).

package/specs/commands-overview.md

@@ -1,184 +0,0 @@
-# Commands Overview
-
-This file provides high-level semantics for core commands in the path-based model. Detailed behaviors in subdirs (e.g., [Install](install/)). Commands enforce mutability (e.g., add/remove require mutable sources).
-
-## Command Summary
-
-| Command | Direction | Purpose | Mutable Source | Immutable Source |
-|---------|-----------|---------|----------------|------------------|
-| `new` | N/A | Create package manifest | N/A | N/A |
-| `add` | Filesystem → Source | Add new files (source-only, path-only for workspace root) | ✅ | ❌ Error |
-| `remove` | Source → Deletion | Remove files from source (source-only, path-only for workspace root) | ✅ | ❌ Error |
-| `save` | Workspace → Source | Save workspace edits back to source (hash-based sync) | ✅ | ❌ Error |
-| `set` | N/A | Update manifest metadata | ✅ | ❌ Error |
-| `install` | Registry → Workspace | Install version (git/path too) + update index | N/A | ✅ |
-| `list` | N/A | Report sync state | ✅ | ✅ |
-| `uninstall` | Workspace | Remove package files/mappings | ✅ | ✅ |
-| `publish` | Source → Registry | Publish to local or remote registry | ✅ | N/A |
-| `configure` | N/A | Configure settings | N/A | N/A |
-
-Other: `login`/`logout` in subdocs or future.
-
-## Detailed Semantics
-
-### `add`
-
-Add new files from anywhere to mutable source (workspace or global packages).
-
-- Preconditions: Mutable package source (workspace or global); **does not require installation**.
-- Flow: Resolve mutable source → Collect input → Map (platform→universal, root→root, other→root/<rel>) → Copy to source.
-- **No index updates**: `add` only modifies package source. To sync to workspace, use `install`.
-- Example: 
-  - `opkg add ./new-files/ --to my-pkg` (source-only)
-  - `opkg add ./file.md --to my-pkg` (adds to source)
-  - `opkg install my-pkg` (to sync to workspace)
-- Works from any directory with any mutable package.
-- See [Add](add/).
-
-### `remove`
-
-Remove files from mutable source or workspace root.
-
-- Preconditions: Mutable source or workspace root; fails on registry.
-- Flow: Resolve arguments → Resolve source → Collect files → Confirm → Delete → Clean up empty dirs.
-- **Argument modes**: 
-  - With option: `opkg remove <path> --from <pkg>` (named package)
-  - Path only: `opkg remove <path>` (workspace root)
-- **No index updates**: `remove` only modifies package source. To sync deletions to workspace, use `install`.
-- Options: `--force` (skip confirmation), `--dry-run` (preview).
-- Example:
-  - `opkg remove commands/deprecated.md` (workspace root, path-only)
-  - `opkg remove commands/deprecated.md --from my-pkg` (named package, source-only)
-  - `opkg remove rules/old/ --from my-pkg` (removes from source)
-  - `opkg remove commands/ --dry-run` (preview workspace root)
-  - `opkg install my-pkg` (to sync deletions to workspace)
-- Works from any directory with any mutable package.
-- Opposite of `add` command.
-- See [Remove](remove/).
-
-### `save`
-
-Save workspace edits back to mutable package source.
-
-- Preconditions: Package installed in workspace; mutable source; has file mappings.
-- Flow: Read index → Compare hashes → Copy changed files → Report.
-- **Hash-based detection**: Only copies files where workspace content differs from source.
-- **Simple overwrite**: No conflict resolution - workspace wins.
-- **Minimal MVP**: ~230 LOC total (vs 5,000+ in previous implementation).
-- Example:
-  - `opkg save my-pkg` (save all changed files)
-  - Skips files with matching hashes
-  - Creates new files in source if needed
-  - Suggests running `opkg install my-pkg` to re-sync workspace
-- Bidirectional workflow: `install` goes forward, `save` goes backward.
-- See [Save](save/).
-
-### `set`
-
-Update manifest metadata fields in openpackage.yml for mutable packages.
-
-- Preconditions: Mutable source; fails on registry.
-- Flow: Resolve package → Load manifest → Collect updates (interactive or flags) → Validate → Apply → Write.
-- Modes: Interactive (prompts for fields), Batch (via CLI flags), Non-interactive (CI/CD).
-- Fields: `--ver` (version), `--name`, `--description`, `--keywords`, `--author`, `--license`, `--homepage`, `--private`.
-- Options: `--force` (skip confirmation), `--non-interactive` (require flags).
-- Example: 
-  - `opkg set my-pkg --ver 1.2.0` (update version)
-  - `opkg set my-pkg` (interactive mode)
-  - `opkg set --ver 2.0.0 --description "Updated"` (CWD package)
-- See [Set](set/).
-
-### `install`
-
-Resolve/install from registry/git/path to workspace.
-
-- Flow: Resolve ver/source → Apply files → Update yml (constraint) / index (path/ver/mappings).
-- Partial via `files:` supported.
-- **Claude Code plugin support**: Automatically detects and transforms plugins from git sources (individual plugins or marketplaces with interactive selection).
-- Subdirectory support: `git:url#ref&subdirectory=path` for monorepos and plugin marketplaces.
-- **Global mode**: `-g, --global` installs to home directory (`~/`) instead of current workspace.
-- Example: 
-  - `opkg install community-pkg@^1.0.0` (registry)
-  - `opkg install -g shared-rules` (global install)
-  - `opkg install github:anthropics/claude-code#subdirectory=plugins/commit-commands` (plugin)
-  - `opkg install github:anthropics/claude-code` (marketplace with interactive selection)
-- See [Install](install/).
-
-### `list`
-
-Check package states.
-
-- Flow: Read index → Validate paths → Hash compare source vs. workspace → Report (synced/modified/missing).
-- Example: `opkg list` (✅/⚠️/❌ output).
-- See [List](list/).
-
-### `uninstall`
-
-Remove package from workspace.
-
-- Flow: Read index → Delete mapped files (not source) → Remove sections from root files → Update index/yml.
-- **Global mode**: `-g, --global` uninstalls from home directory (`~/`) instead of current workspace.
-- Example: 
-  - `opkg uninstall my-pkg` (workspace)
-  - `opkg uninstall -g shared-rules` (global)
-- See [Uninstall](uninstall/).
-
-### `publish`
-
-Publish package to local registry (default) or remote registry (with `--remote` flag).
-
-- Flow: 
-  - **Local**: Resolve package source → Validate version → Copy to local registry or custom output → Update workspace index.
-  - **Remote**: Resolve package source → Validate version → Authenticate → Collect files → Create tarball → Upload to remote.
-- **Package Input**: 
-  - No argument: Uses CWD
-  - Package name: Resolves from CWD → Workspace → Global
-  - Directory path: Uses specified path
-- **Local publishing** (default):
-  - Destination: `~/.openpackage/registry/<name>/<version>/` or custom path via `--output`
-  - No authentication required
-  - Allows prerelease versions (with warning)
-- **Remote publishing** (`--remote`):
-  - Destination: Remote OpenPackage backend
-  - Authentication: Required via `--profile` or `--api-key`
-  - Scoping: Auto-adds username scope to unscoped packages
-  - Version: Must be stable semver (no prereleases)
-- Options: `--force`, `--output <path>` (local only), `--remote`, `--profile`, `--api-key`.
-- Example:
-  - `opkg publish` (publish CWD to local registry)
-  - `opkg publish my-pkg` (publish by name)
-  - `opkg publish ./path/to/package` (publish by path)
-  - `opkg publish --output ./dist` (custom output)
-  - `opkg publish --remote` (publish to remote)
-  - `opkg publish my-pkg --remote --profile prod` (remote with profile)
-- **Replaces**: `pack` command (deprecated and removed)
-- See [Publish](publish/).
-
-### `new`
-
-Create a new package with manifest.
-
-- Flow: Prompt for scope (if interactive) → Validate scope/name → Resolve target path → Create directory → Write openpackage.yml → Optional workspace integration.
-- Scopes: `root` (cwd), `local` (workspace), `global` (cross-workspace).
-- Scope Selection: Interactive prompt when `--scope` not provided; required in non-interactive mode.
-- Options: `--scope`, `--force`, `--non-interactive`.
-- Example: `opkg new my-pkg` (prompts for scope), `opkg new utils --scope global` (explicit global).
-- See [New](new/).
-
-## Mutability Matrix (Expanded)
-
-| Command | Mutable Source | Immutable Source | Creates Files In |
-|---------|----------------|------------------|------------------|
-| `new` | N/A | N/A | Package location (scope-dependent) |
-| `add` | ✅ Adds to source | ❌ Error | Source path |
-| `remove` | ✅ Removes from source | ❌ Error | N/A (deletes) |
-| `set` | ✅ Updates manifest | ❌ Error | Source path |
-| `install` | N/A | ✅ Syncs to workspace | Workspace |
-| `list` | ✅ Shows status | ✅ Shows status | N/A |
-| `uninstall` | ✅ Removes | ✅ Removes | N/A (deletes) |
-| `publish` | ✅ Creates snapshot (local) or uploads (remote) | N/A | Local/remote registry |
-| `configure` | ✅ Updates config | ✅ Updates config | Config files |
-
-See table above for summary; full ops rules in [Package Sources](package-sources.md).
-
-For CLI options common to commands, see [CLI Options](cli-options.md). Future commands (e.g., elevate) in [Scope Management](scope-management.md).

package/specs/directory-layout.md

@@ -1,95 +0,0 @@
-# Directory Layout
-
-This document describes the global (`~/.openpackage/`) and workspace directory structures central to the path-based model.
-
-## Global Directory (`~/.openpackage/`)
-
-The global dir holds shared mutable sources and local registry snapshots.
-
-```
-~/.openpackage/
-├── packages/                          # Mutable development codebases
-│   ├── <name>/                       # e.g., shared-rules/
-│   │   ├── openpackage.yml           # Manifest
-│   │   ├── commands/                 # Universal content
-│   │   ├── rules/
-│   │   └── root/                     # Copy-to-root files
-│   └── @scope/                       # Scoped (e.g., @org/tools/)
-│       └── <name>/
-│
-├── registry/                          # Immutable versioned snapshots
-│   ├── <name>/                       # Directory-based (no tarballs)
-│   │   ├── <version>/                # e.g., 1.0.0/
-│   │   │   ├── openpackage.yml
-│   │   │   ├── commands/
-│   │   │   ├── rules/
-│   │   │   └── AGENTS.md             # Root files
-│   │   └── <version>/
-│   └── @scope/
-│       └── <name>/
-│           └── <version>/
-│
-└── config.yml                         # Global config (future?)
-```
-
-## Workspace Directory
-
-Workspace-local metadata and packages; platforms are sync targets.
-
-```
-<workspace>/
-├── .openpackage/                      # Local metadata & packages
-│   ├── openpackage.yml               # Root manifest (deps)
-│   ├── openpackage.index.yml         # Unified index (all packages/sources/mappings)
-│   └── packages/                     # Workspace-local mutable sources
-│       └── <name>/                   # e.g., project-tools/
-│           ├── openpackage.yml
-│           ├── commands/
-│           └── root/
-│
-├── .cursor/                           # Platform dir (sync target)
-│   ├── rules/                        # From package universal subdirs
-│   └── commands/
-├── .opencode/                         # Other platforms
-│   └── ...
-└── docs/                              # Root-level (e.g., from package root/ or AGENTS.md processing)
-    └── ...
-```
-
-## Directory Purposes
-
-| Directory | Purpose | Mutability | Notes |
-|-----------|---------|------------|-------|
-| `~/.openpackage/packages/` | Global shared dev codebases | ✅ Mutable | Cross-workspace sharing |
-| `~/.openpackage/registry/` | Versioned immutable snapshots | ❌ Immutable | From pack; git clones cached here |
-| `./.openpackage/packages/` | Workspace-local dev codebases | ✅ Mutable | Project-specific; inside .openpackage/ for cleanliness |
-| `./.openpackage/openpackage.index.yml` | Tracks installs/sources/mappings | Metadata | Unified; never in payload |
-
-## Key Principles
-
-- **Unified Index**: Single file at `.openpackage/openpackage.index.yml` for all package tracking—replaces prior per-package indices.
-- **Directory Registry**: Expanded dirs for easy inspection/debugging; same code for all sources (no extraction).
-- **Workspace Packages in `.openpackage/`**: Keeps root clean; signals opkg management.
-- **No Workspace Metadata in Payload**: `.openpackage/` excluded from registry copies.
-
-See [Package Root Layout](package/package-root-layout.md) for inside package dirs; [Registry](registry.md) for version details.
-
-## Path Conventions
-
-| Type | Example | Use | Portability |
-|------|---------|-----|-------------|
-| Workspace Rel | `./.openpackage/packages/my-pkg/` | Local packages | ✅ (project-committed) |
-| Global Tilde | `~/.openpackage/packages/shared/` | Shared | ✅ (tilde expands) |
-| Registry | `~/.openpackage/registry/my-pkg/1.0.0/` | Immutable | Inferred post-install |
-| Absolute | `/custom/path/` | Custom | ❌ Machine-specific |
-
-Tilde `~` expands at runtime; relatives from openpackage.yml location.
-
-## Key Changes from Prior Versions
-
-- **Unified Index**: Single file vs. per-package.
-- **No Per-Package Metadata Dirs**: Embedded in index.
-- **Directory Registry**: No tarballs.
-- **Workspace Packages Location**: `./.openpackage/packages/` (was `./packages/?`).
-
-For source resolution, see [Package Sources](package-sources.md).

package/specs/install/README.md

@@ -1,35 +0,0 @@
-### Install Command Specs
-
-This directory contains specifications for the `install` command, with a focus on:
-
-- **Latest-in-range resolution from local + remote registries**
-- **Workspace context**: Installs target effective cwd (shell, global --cwd, or home directory with --global; see [../../cli-options.md])
-- **Global installation mode**: Install to home directory (`~/`) with `-g, --global` flag
-- **`openpackage.yml` as the canonical source of dependency intent**
-- **Consistent, minimal, npm-inspired UX**
-- **Git sources with subdirectory support** for monorepos and Claude Code plugins
-- **Cross-platform conversion** via Universal Platform Converter (automatic format detection and conversion)
-
-The documents are intended to be implementation-guiding but not tied to specific modules.
-
-### Files
-
-#### Core Installation
-
-- **`install-behavior.md`**: Top-level `opkg install` UX and scenarios (CLI shapes, fresh vs existing deps, dev vs prod). Includes Claude Code plugin support (§9) with Universal Converter integration.
-- **`git-sources.md`**: Installing packages from git repositories (`git:` and `github:` inputs), including subdirectory support for monorepos and Claude Code plugins. Covers scoped naming for GitHub plugins.
-- **`git-cache.md`**: Structured Git cache architecture at `~/.openpackage/cache/git/` with deterministic paths, automatic reuse, and metadata tracking.
-- **`version-resolution.md`**: Formal rules for "latest in range from local+remote", including pre-release vs stable semantics.
-- **`package-yml-canonical.md`**: Rules for treating `openpackage.yml` as the canonical declaration for install.
-
-#### Claude Code Plugin Installation
-
-- **`plugin-installation.md`**: Complete specification for Claude Code plugin installation including detection, transformation, and source handling. Covers individual plugins and marketplace plugins with all supported source types.
-- **`marketplace-installation.md`**: Detailed marketplace installation workflow including manifest parsing, plugin selection, and multi-plugin installation. Covers relative path, GitHub, and Git URL sources.
-- **`plugin-source-normalization.md`**: Normalization and validation logic for plugin sources. Specifies conversion rules, validation constraints, and security measures for all source types.
-
-### Related
-
-- **[Universal Platform Converter](../platforms/universal-converter.md)**: Cross-platform package conversion system that enables installing platform-specific packages to any platform
-
-