opkg 0.7.0 → 0.7.1

package/specs/install/git-cache.md

@@ -0,0 +1,403 @@
+# Git Cache Architecture
+
+This document specifies the structured Git cache system used for cloning and caching Git repositories.
+
+---
+
+## 1. Overview
+
+The Git cache provides:
+- **Deterministic paths**: Same repository/commit always uses same location
+- **Automatic reuse**: Detects and reuses existing cached commits
+- **Persistent storage**: Cache survives reboots (unlike temp directories)
+- **Space efficiency**: Uses shallow clones (`--depth 1`)
+- **Metadata tracking**: Stores repository and commit information for debugging
+
+---
+
+## 2. Cache structure
+
+### 2.1 Base directory
+
+All Git clones are cached at:
+```
+~/.openpackage/cache/git/
+```
+
+### 2.2 Directory hierarchy
+
+```
+~/.openpackage/cache/git/
+├── <url-hash-12>/              # Repository (by URL hash)
+│   ├── .opkg-repo.json         # Repository metadata
+│   ├── <commit-sha-7>/         # Commit checkout
+│   │   ├── .git/               # Git repository data
+│   │   ├── .opkg-commit.json   # Commit metadata
+│   │   └── <repository files>
+│   └── <commit-sha-7>/         # Another commit
+│       └── ...
+└── <url-hash-12>/              # Another repository
+    └── ...
+```
+
+**Path components**:
+- `<url-hash-12>`: 12 hex characters (48 bits) - hash of normalized Git URL
+- `<commit-sha-7>`: 7 hex characters - first 7 chars of resolved commit SHA
+
+---
+
+## 3. URL hash generation
+
+### 3.1 Normalization
+
+URLs are normalized before hashing to ensure consistency:
+
+**Transformations**:
+1. Convert to lowercase
+2. Remove `.git` suffix
+3. Normalize GitHub SSH to HTTPS format:
+   - `git@github.com:owner/repo.git` → `https://github.com/owner/repo`
+4. Normalize other SSH formats:
+   - `git@host:owner/repo.git` → `https://host/owner/repo`
+5. Remove trailing slashes
+
+**Examples**:
+| Original URL | Normalized URL |
+|--------------|----------------|
+| `https://github.com/User/Repo.git` | `https://github.com/user/repo` |
+| `git@github.com:anthropics/claude-code.git` | `https://github.com/anthropics/claude-code` |
+| `https://gitlab.com/group/project.git` | `https://gitlab.com/group/project` |
+
+### 3.2 Hash computation
+
+- Algorithm: SHA-256
+- Length: First 12 hex characters (48 bits)
+- Collision probability: ~10^-10 with 1000 repos
+- Deterministic: Same normalized URL always produces same hash
+
+**Implementation**:
+```typescript
+function computeGitUrlHash(url: string): string {
+  const normalized = normalizeGitUrl(url);
+  const hash = createHash('sha256').update(normalized).digest('hex');
+  return hash.substring(0, 12);
+}
+```
+
+---
+
+## 4. Commit SHA resolution
+
+### 4.1 Resolution process
+
+When cloning a repository:
+1. Clone repository to temporary location within cache
+2. Resolve current HEAD to full commit SHA (40 chars)
+3. Truncate to 7 characters for directory name
+4. Move to final location: `<url-hash>/<commit-sha-7>/`
+
+### 4.2 Ref handling
+
+**Branch or tag specified**:
+- Clone with `--branch <ref>`
+- Resolve to commit SHA after clone
+- Directory named by commit SHA (not branch name)
+
+**Commit SHA specified**:
+- Clone default branch
+- Fetch and checkout specific commit
+- Directory named by commit SHA
+
+**No ref specified**:
+- Clone default branch
+- Resolve HEAD to commit SHA
+- Directory named by commit SHA
+
+**Result**: Different branches/tags pointing to same commit → same cache location
+
+---
+
+## 5. Metadata files
+
+### 5.1 Repository metadata
+
+**Location**: `~/.openpackage/cache/git/<url-hash>/.opkg-repo.json`
+
+**Schema**:
+```json
+{
+  "url": "https://github.com/anthropics/claude-code.git",
+  "normalized": "https://github.com/anthropics/claude-code",
+  "lastFetched": "2025-01-13T10:30:00Z"
+}
+```
+
+**Fields**:
+- `url`: Original Git URL (as provided by user)
+- `normalized`: Normalized URL used for hashing
+- `lastFetched`: Timestamp of most recent fetch operation
+
+### 5.2 Commit metadata
+
+**Location**: `~/.openpackage/cache/git/<url-hash>/<commit-sha-7>/.opkg-commit.json`
+
+**Schema**:
+```json
+{
+  "url": "https://github.com/anthropics/claude-code.git",
+  "commit": "abc1234567890abcdef",
+  "ref": "main",
+  "subdirectory": "plugins/commit-commands",
+  "clonedAt": "2025-01-13T10:30:00Z",
+  "lastAccessed": "2025-01-13T12:00:00Z"
+}
+```
+
+**Fields**:
+- `url`: Git URL for this commit
+- `commit`: Full commit SHA (40 chars)
+- `ref`: Branch/tag name if specified (optional)
+- `subdirectory`: Subdirectory path if specified (optional)
+- `clonedAt`: Timestamp when commit was first cloned
+- `lastAccessed`: Timestamp of most recent access
+
+---
+
+## 6. Clone operations
+
+### 6.1 Initial clone
+
+When cloning a new commit:
+1. Generate cache paths:
+   - `repoDir = ~/.openpackage/cache/git/<url-hash>/`
+   - `tempPath = <repoDir>/.temp-clone`
+2. Create repo directory if needed
+3. Write `.opkg-repo.json` metadata
+4. Clone to temporary path:
+   - `git clone --depth 1 [--branch <ref>] <url> <tempPath>`
+5. Resolve commit SHA from HEAD
+6. Check if commit already cached (rare race condition)
+7. Move temp path to final location: `<repoDir>/<commit-sha-7>/`
+8. Write `.opkg-commit.json` metadata
+
+### 6.2 Cache hit
+
+When requested commit is already cached:
+1. Check if directory exists: `~/.openpackage/cache/git/<url-hash>/<commit-sha-7>/`
+2. Read and validate `.opkg-commit.json`
+3. Update `lastAccessed` timestamp
+4. Return path to cached commit
+5. Skip clone entirely
+
+### 6.3 Subdirectory handling
+
+Subdirectories are accessed within the cloned repository:
+- Clone full repository to cache
+- Return path to subdirectory: `<commit-dir>/<subdirectory>/`
+- Validate subdirectory exists before returning
+
+**Example**:
+```
+Cache: ~/.openpackage/cache/git/a1b2c3d4e5f6/abc1234/
+Subdirectory: plugins/commit-commands
+Return: ~/.openpackage/cache/git/a1b2c3d4e5f6/abc1234/plugins/commit-commands/
+```
+
+---
+
+## 7. Shallow clone details
+
+### 7.1 Clone depth
+
+All clones use `--depth 1` (shallow clone):
+- Fetches only the latest commit
+- Significantly smaller repository size
+- Faster clone times
+- Sufficient for package installation
+
+**Comparison**:
+| Clone Type | Size | Time |
+|------------|------|------|
+| Full clone | ~100MB | 10s |
+| Shallow clone (`--depth 1`) | ~10MB | 2s |
+
+### 7.2 Limitations
+
+Shallow clones have limited Git history:
+- Cannot `git log` beyond fetched commit
+- Cannot easily determine branch history
+- May need additional fetch for some operations
+
+**Acceptable for OpenPackage** because:
+- Only need files at specific commit
+- Not performing Git operations after clone
+- Can re-clone if full history needed
+
+---
+
+## 8. Cache management
+
+### 8.1 Current behavior
+
+- Cache grows indefinitely (no automatic cleanup)
+- Multiple commits of same repository stored separately
+- No size limits enforced
+
+### 8.2 Future enhancements
+
+**Cache cleanup**:
+- Remove commits not accessed in N days
+- Remove commits not referenced in any workspace
+- Size-based cleanup (when cache exceeds threshold)
+
+**Cache commands** (not yet implemented):
+```bash
+opkg cache list              # List all cached repositories
+opkg cache show <url>        # Show commits for specific repository
+opkg cache clean             # Clean old/unused cache entries
+opkg cache clean --all       # Remove entire cache
+opkg cache clean <url>       # Remove specific repository
+```
+
+**Cache statistics**:
+- Total cache size
+- Number of repositories
+- Number of commits
+- Last accessed timestamps
+
+---
+
+## 9. Error handling
+
+### 9.1 Clone failures
+
+If clone operation fails:
+1. Clean up temporary clone directory
+2. Preserve existing cache entries
+3. Return error to caller
+4. Do not write metadata files
+
+### 9.2 Corrupted cache
+
+If cache directory is corrupted:
+- Next clone attempt will detect missing/invalid metadata
+- Re-clone automatically
+- Corrupted entries can be manually deleted
+
+### 9.3 Disk space
+
+If disk is full:
+- Clone fails with disk space error
+- User must free space or clean cache
+- No automatic cleanup on low disk space
+
+---
+
+## 10. Benefits and trade-offs
+
+### 10.1 Benefits
+
+✅ **Deterministic**: Same repo/commit → same path  
+✅ **Fast reinstalls**: Reuses existing cache  
+✅ **Debuggable**: Metadata files show what's cached  
+✅ **Persistent**: Survives reboots  
+✅ **Space efficient**: Shallow clones  
+✅ **Collision resistant**: 48-bit hash
+
+### 10.2 Trade-offs
+
+⚠️ **Disk usage**: Cache grows over time  
+⚠️ **No automatic cleanup**: User must manage cache  
+⚠️ **Shallow history**: Limited Git operations  
+⚠️ **Branch updates**: No automatic update detection
+
+---
+
+## 11. Implementation notes
+
+### 11.1 URL parsing
+
+Supports multiple Git URL formats:
+- HTTPS: `https://github.com/owner/repo.git`
+- SSH: `git@github.com:owner/repo.git`
+- SSH with protocol: `ssh://git@github.com:owner/repo.git`
+- Git protocol: `git://github.com/owner/repo.git`
+
+All formats are normalized to HTTPS for hashing.
+
+### 11.2 Path safety
+
+- All paths use filesystem-safe characters
+- Commit SHAs are hex (safe for all filesystems)
+- URL hashes are hex (safe for all filesystems)
+- No special character handling needed
+
+### 11.3 Concurrency
+
+**Current implementation**:
+- No file locking or coordination
+- Rare race condition possible (same commit cloned simultaneously)
+- Race is detected and handled (one clone succeeds, others reuse)
+
+**Future consideration**:
+- File locking for clone operations
+- Atomic directory moves
+- Retry logic for transient failures
+
+---
+
+## 12. Related specifications
+
+- [Git Sources](./git-sources.md): Git install behavior
+- [Install Behavior](./install-behavior.md): Overall install flow
+- [Claude Code Plugin Support](./install-behavior.md#9-claude-code-plugin-support): Plugin installation
+
+---
+
+## 13. Examples
+
+### 13.1 GitHub plugin marketplace
+
+**Command**:
+```bash
+opkg install github:anthropics/claude-code#subdirectory=plugins/commit-commands
+```
+
+**Process**:
+1. Normalize URL: `https://github.com/anthropics/claude-code`
+2. Compute hash: `a1b2c3d4e5f6`
+3. Clone to: `~/.openpackage/cache/git/a1b2c3d4e5f6/.temp-clone`
+4. Resolve commit: `abc1234567890abcdef`
+5. Move to: `~/.openpackage/cache/git/a1b2c3d4e5f6/abc1234/`
+6. Return path: `~/.openpackage/cache/git/a1b2c3d4e5f6/abc1234/plugins/commit-commands/`
+
+### 13.2 GitLab project
+
+**Command**:
+```bash
+opkg install git:https://gitlab.com/company/project.git#v1.0.0
+```
+
+**Process**:
+1. Normalize URL: `https://gitlab.com/company/project`
+2. Compute hash: `x9y8z7w6v5u4`
+3. Clone with tag: `git clone --depth 1 --branch v1.0.0 <url>`
+4. Resolve commit: `def5678901234abcdef`
+5. Move to: `~/.openpackage/cache/git/x9y8z7w6v5u4/def5678/`
+6. Return path: `~/.openpackage/cache/git/x9y8z7w6v5u4/def5678/`
+
+### 13.3 Cache reuse
+
+**First install**:
+```bash
+opkg install github:user/plugin
+# Clones to: ~/.openpackage/cache/git/k4l5m6n7o8p9/ghi9012/
+```
+
+**Second install** (same commit):
+```bash
+opkg install github:user/plugin
+# Detects existing cache
+# Reuses: ~/.openpackage/cache/git/k4l5m6n7o8p9/ghi9012/
+# No clone needed
+```

package/specs/install/git-sources.md

@@ -70,9 +70,16 @@ Rules:
 
 ### 3.1 Basic git install
 
-- `install` clones the repository to a temporary directory using the system `git` executable.
+- `install` clones the repository to a **structured cache** at `~/.openpackage/cache/git/` using the system `git` executable.
+- **Cache structure**: `~/.openpackage/cache/git/<url-hash-12>/<commit-sha-7>/`
+  - `<url-hash-12>`: 12-character hash of normalized Git URL
+  - `<commit-sha-7>`: First 7 characters of resolved commit SHA
+- **Clone behavior**:
+  - Uses shallow clones (`--depth 1`) for space efficiency.
+  - Reuses existing cache if same commit is already cached.
+  - Writes metadata files (`.opkg-repo.json`, `.opkg-commit.json`) for tracking.
 - If `ref` is provided:
-  - For branch/tag: clone the specified ref.
+  - For branch/tag: clone the specified ref and resolve to commit SHA.
   - For commit SHA: clone and checkout that SHA (best-effort shallow fetch).
 - Without subdirectory: The cloned repository root MUST contain `openpackage.yml`.
 - The installed package version is read from the repo's `openpackage.yml`.
@@ -83,14 +90,35 @@ Rules:
 ### 3.2 Subdirectory installs
 
 When `subdirectory` is specified:
-- Repository is cloned to a temporary directory.
+- Repository is cloned to the structured cache (same as §3.1).
 - The specified subdirectory path is resolved relative to the repository root.
 - The subdirectory MUST contain either:
   - `openpackage.yml` (standard OpenPackage package), OR
   - `.claude-plugin/plugin.json` (Claude Code plugin), OR
   - `.claude-plugin/marketplace.json` (Claude Code plugin marketplace)
 - For OpenPackage packages: `openpackage.yml` is read from the subdirectory.
-- For Claude Code plugins: See §4 for special handling.
+- For Claude Code plugins: See §4 for special handling including scoped naming.
+
+### 3.3 Cache persistence and management
+
+The Git cache persists across sessions:
+- **Location**: `~/.openpackage/cache/git/`
+- **Benefits**: Faster reinstalls, survives reboots, debuggable with metadata
+- **Structure**:
+  ```
+  ~/.openpackage/cache/git/
+  ├── a1b2c3d4e5f6/              # URL hash
+  │   ├── .opkg-repo.json        # Repo metadata (URL, last fetched)
+  │   ├── abc1234/               # Commit SHA
+  │   │   ├── .git/              # Shallow clone
+  │   │   ├── .opkg-commit.json  # Commit metadata (ref, timestamp)
+  │   │   └── <repo contents>
+  │   └── def5678/               # Different commit
+  └── x9y8z7w6v5u4/              # Different repo
+  ```
+- **Metadata tracking**:
+  - `.opkg-repo.json`: Stores URL, normalized URL, last fetch timestamp
+  - `.opkg-commit.json`: Stores full commit SHA, ref name, clone/access timestamps
 
 ---
 
@@ -116,20 +144,29 @@ Detection happens automatically after cloning, before attempting to load as an O
 
 When an individual plugin is detected:
 1. Plugin manifest (`.claude-plugin/plugin.json`) is read and validated.
-2. Plugin metadata is transformed to OpenPackage format in-memory:
-   - `name` and `version` from `plugin.json` become package metadata
+2. **Plugin name is generated with scoping**:
+   - **GitHub plugins**: Use scoped format `@<username>/<plugin-name>`
+   - **GitHub plugins from subdirectory**: Use `@<username>/<repo>/<plugin-name>`
+   - **Non-GitHub sources**: Use original plugin name (no scoping)
+   - **Fallback behavior**: If `plugin.json` has no `name` field:
+     - Use subdirectory basename if installing from subdirectory
+     - Use repository name if installing full repo
+     - Use "unnamed-plugin" as last resort
+3. Plugin metadata is transformed to OpenPackage format in-memory:
+   - Scoped `name` becomes package metadata
+   - `version` from `plugin.json` becomes package version
    - `description`, `author`, `repository`, etc. are preserved
-3. All plugin files are collected (commands/, agents/, skills/, hooks/, .mcp.json, .lsp.json, etc.)
-4. **Package format is detected** and appropriate installation strategy selected:
+4. All plugin files are collected (commands/, agents/, skills/, hooks/, .mcp.json, .lsp.json, etc.)
+5. **Package format is detected** and appropriate installation strategy selected:
    - **Direct AS-IS**: Source platform = target platform (fastest)
    - **Cross-platform conversion**: Source ≠ target (via Universal Converter)
    - **Standard flows**: Universal format packages
-5. Files are installed to platform-specific directories:
+6. Files are installed to platform-specific directories:
    - `commands/` → `.claude/commands/`, `.cursor/commands/`, etc.
    - `agents/` → `.claude/agents/`, `.cursor/agents/`, etc.
    - Root files (`.mcp.json`, `.lsp.json`) → platform roots
-6. The dependency is tracked in `openpackage.yml` with its git source (not as a registry version).
-7. No registry copy is created (git repository remains source of truth).
+7. The dependency is tracked in `openpackage.yml` with its **scoped name** and git source (not as a registry version).
+8. No registry copy is created (git repository remains source of truth).
 
 **See:** [Universal Platform Converter](../platforms/universal-converter.md) for cross-platform conversion details.
 
@@ -141,22 +178,29 @@ opkg install github:anthropics/claude-code#subdirectory=plugins/commit-commands
 Result in `openpackage.yml`:
 ```yaml
 packages:
-  - name: commit-commands
+  - name: "@anthropics/claude-code/commit-commands"  # Scoped name
     git: https://github.com/anthropics/claude-code.git
     subdirectory: plugins/commit-commands
 ```
 
+Installed to cache:
+```
+~/.openpackage/cache/git/a1b2c3d4e5f6/abc1234/plugins/commit-commands/
+```
+
 ### 4.3 Marketplace install
 
 When a plugin marketplace is detected:
 1. Marketplace manifest (`.claude-plugin/marketplace.json`) is parsed.
+   - **Fallback behavior**: If `marketplace.json` has no `name` field, uses repository name
 2. An interactive multiselect prompt is displayed listing all available plugins.
 3. User selects which plugin(s) to install (space to select, enter to confirm).
 4. Each selected plugin is installed individually:
+   - **Scoped name is generated**: `@<username>/<marketplace-name>/<plugin-name>`
    - Plugin subdirectory is resolved within the cloned repository.
    - Plugin is validated (must have `.claude-plugin/plugin.json`).
    - Plugin is installed following the individual plugin flow (§4.2).
-5. Each plugin gets its own entry in `openpackage.yml` with its specific subdirectory.
+5. Each plugin gets its own entry in `openpackage.yml` with its **scoped name** and specific subdirectory.
 
 **Example:**
 ```bash
@@ -177,15 +221,48 @@ Select plugins to install (space to select, enter to confirm):
 Result in `openpackage.yml` (if user selected commit-commands and pr-review-toolkit):
 ```yaml
 packages:
-  - name: commit-commands
+  - name: "@anthropics/claude-code/commit-commands"  # Scoped name
     git: https://github.com/anthropics/claude-code.git
     subdirectory: plugins/commit-commands
-  - name: pr-review-toolkit
+  - name: "@anthropics/claude-code/pr-review-toolkit"  # Scoped name
     git: https://github.com/anthropics/claude-code.git
     subdirectory: plugins/pr-review-toolkit
 ```
 
-### 4.4 Plugin transformation details
+Installed to cache:
+```
+~/.openpackage/cache/git/a1b2c3d4e5f6/abc1234/plugins/commit-commands/
+~/.openpackage/cache/git/a1b2c3d4e5f6/abc1234/plugins/pr-review-toolkit/
+```
+
+### 4.4 Plugin naming convention
+
+**Scoped naming for GitHub plugins**: Plugins installed from GitHub repositories use scoped names to provide clear provenance and prevent naming conflicts.
+
+**Naming formats**:
+- **Marketplace plugin**: `@<username>/<marketplace-name>/<plugin-name>`
+- **Standalone plugin**: `@<username>/<plugin-name>`
+- **Non-GitHub source**: `<plugin-name>` (no scoping)
+
+**Examples**:
+| Source | Plugin Name | Scoped Name |
+|--------|-------------|-------------|
+| `github:anthropics/claude-code#subdirectory=plugins/commit-commands` | `commit-commands` | `@anthropics/claude-code/commit-commands` |
+| `github:anthropics/my-plugin` | `my-plugin` | `@anthropics/my-plugin` |
+| `git:https://gitlab.com/user/plugin.git` | `cool-plugin` | `cool-plugin` (no scoping) |
+| `./local-plugin/` | `local-plugin` | `local-plugin` (no scoping) |
+
+**Fallback behavior**:
+1. **Plugin name missing**: Uses subdirectory basename → repo name → "unnamed-plugin"
+2. **Marketplace name missing**: Uses repo name → "unnamed-marketplace"
+
+**Benefits**:
+- Clear GitHub provenance at a glance
+- No name conflicts between authors
+- Easy to identify plugin source
+- Consistent with npm/yarn scoping patterns
+
+### 4.5 Plugin transformation details
 
 **In-memory transformation** (no registry copy):
 - Plugin manifest fields map to OpenPackage metadata:
@@ -213,8 +290,8 @@ packages:
 
 ### 5.1 Current limitations
 
-- No lockfile or commit pinning is persisted (no `resolvedSha` field).
-- No clone caching (each install may re-clone).
+- **No lockfile pinning**: Commit SHAs are resolved but not persisted to `openpackage.yml` (no `resolvedSha` field).
+- **Branch tracking**: Installing from a branch will use the latest commit at install time, not track updates.
 - Authentication behavior is delegated to `git` (credentials configured in the user's environment).
 
 ### 5.2 Subdirectory support notes
@@ -223,8 +300,19 @@ packages:
 - Subdirectory must contain a valid package or plugin manifest.
 - For OpenPackage packages in subdirectories, their dependencies are resolved relative to the subdirectory location.
 
-### 5.3 Future considerations
-
-- Commit SHA resolution and pinning for reproducible installs.
-- Clone caching to speed up repeated installs.
-- Plugin registry support (converting plugins to first-class OpenPackage packages).
+### 5.3 Cache features
+
+**Implemented**:
+- ✅ Structured cache at `~/.openpackage/cache/git/`
+- ✅ Deterministic paths based on URL hash + commit SHA
+- ✅ Automatic cache reuse when same commit exists
+- ✅ Metadata tracking (`.opkg-repo.json`, `.opkg-commit.json`)
+- ✅ Shallow clones for space efficiency
+- ✅ Persistent across reboots
+
+**Future considerations**:
+- Cache management commands (`opkg cache list`, `opkg cache clean`)
+- Cache update detection (detect when branch has new commits)
+- Git worktrees for further space optimization
+- Automatic cache cleanup based on age/size
+- Commit SHA lockfile support for reproducible installs

package/specs/new/README.md

@@ -20,7 +20,9 @@ Creates a new package with an `openpackage.yml` manifest in one of three predefi
 - `[package-name]` (optional for root scope, required for local/global)
   - Package name following OpenPackage naming conventions
   - Supports scoped packages (`@org/package-name`)
-  - Validated against naming rules (lowercase, alphanumeric, hyphens, slashes for scopes)
+  - Supports hierarchical packages (`@org/package-name/subpackage`)
+  - Validated against naming rules (lowercase, alphanumeric, dots, underscores, hyphens, slashes)
+  - No consecutive or trailing slashes allowed
 
 ### Options
 - `--scope <scope>` - Package scope: `root`, `local`, or `global` (prompts if not specified in interactive mode)

package/specs/set/README.md

@@ -126,16 +126,19 @@ opkg set --ver 0.1.0
 **Format:** Package name string
 
 **Validation:**
-- Must contain only: `a-z`, `0-9`, `.`, `_`, `-`
+- Must contain only: `a-z`, `0-9`, `.`, `_`, `-`, `/`
 - Automatically normalized to lowercase
 - No spaces allowed
 - Supports scoped names: `@scope/package-name`
+- Supports hierarchical names: `@scope/package-name/subpackage`
+- No consecutive or trailing slashes
 
 **Examples:**
 ```bash
 opkg set --name my-package
 opkg set --name @myorg/my-package
 opkg set --name package.name
+opkg set --name @anthropics/claude-code/commit-commands
 ```
 
 ### Description Field (`--description`)
@@ -305,7 +308,7 @@ Version must be valid semver (e.g., 1.0.0, 2.1.3-beta.1)
 **Error:** Name contains invalid characters
 
 ```
-Error: Package name 'invalid name' contains invalid characters (use only: a-z, 0-9, ., _, -)
+Error: Package name 'invalid name' segment 'invalid name' contains invalid characters (use only: a-z, 0-9, ., _, -)
 ```
 
 ### Invalid URL