feat: add --global / -g flag for scoped package installation

CHANGELOG.md

@@ -11,6 +11,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Marketplace integration for plugin discovery and governance: `apm marketplace add/list/browse/update/remove` commands, `apm search QUERY@MARKETPLACE` scoped search, `apm install NAME@MARKETPLACE` syntax for installing plugins from marketplace registries; lockfile provenance fields `discovered_via` and `marketplace_plugin_name` to track marketplace origin; support for Copilot CLI and Claude Code `marketplace.json` formats with 4 source types (github, url, git-subdir, relative path) (#503)
+
+### Fixed
+
+- `apm install -g ./local-pkg` now rejects local path dependencies at user scope with a clear error instead of silently failing (relative paths resolve against `cwd` during validation but against `$HOME` during copy) (#452)
 ### Changed
 
 - `apm deps update` now skips download and integration for packages whose resolved SHA matches the lockfile SHA, making the common "nothing changed" case near-instant (#495)
@@ -42,6 +46,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - `apm install --target` flag to force deployment to a specific target (copilot, claude, cursor, opencode, all) (#456)
+- Global `apm install --global` / `-g` and `apm uninstall --global` flags for user-scope package installation, backed by `InstallScope`-based scope resolution in `core/scope.py`; deploys primitives to `~/.copilot/`, `~/.claude/`, `~/.cursor/`, `~/.config/opencode/` and tracks metadata under `~/.apm/` (#452)
 
 ### Fixed
 

docs/src/content/docs/guides/dependencies.md

@@ -279,6 +279,61 @@ dependencies:
 
 **Pack guard:** `apm pack` rejects packages with local path dependencies — replace them with remote references before distributing.
 
+**User-scope guard:** Local path dependencies are **not supported** with `--global` (`-g`). Relative paths resolve against `cwd`, which is meaningless at user scope where packages deploy to `~/.apm/`. Use remote references (`owner/repo`) for global installs.
+
+## Global (User-Scope) Installation
+
+By default, `apm install` targets the **current project** -- manifest, modules, and lockfile live in
+the working directory and deployed primitives go to `.github/`, `.claude/`, `.cursor/`, `.opencode/`.
+
+Pass `--global` (or `-g`) to install to your **home directory** instead, making packages available
+across every project on the machine:
+
+```bash
+apm install -g microsoft/apm-sample-package
+apm uninstall -g microsoft/apm-sample-package
+apm deps list -g       # user-scope packages only
+apm deps list --all    # project + user-scope packages
+```
+
+| Item | Project scope (default) | User scope (`-g`) |
+|------|------------------------|-------------------|
+| Manifest | `./apm.yml` | `~/.apm/apm.yml` |
+| Modules | `./apm_modules/` | `~/.apm/apm_modules/` |
+| Lockfile | `./apm.lock.yaml` | `~/.apm/apm.lock.yaml` |
+| Deployed primitives | `./.github/`, `./.claude/`, ... | `~/.copilot/`, `~/.claude/`, `~/.cursor/`, `~/.config/opencode/` |
+
+### Per-target support
+
+Coverage varies by target and primitive type:
+
+| Target | Status | User-level dir | Primitives | Not supported |
+|--------|--------|---------------|------------|---------------|
+| Claude Code | Supported | `~/.claude/` | Skills, agents, commands, hooks, instructions | -- |
+| Copilot CLI | Partial | `~/.copilot/` | Skills, agents, instructions, hooks | Prompts (not supported by Copilot CLI) |
+| Cursor | Partial | `~/.cursor/` | Skills, agents, hooks | Rules |
+| OpenCode | Partial | `~/.config/opencode/` | Skills, agents, commands | Hooks |
+
+Target detection mirrors project scope: APM auto-detects by `~/.<target>/` directory presence,
+falling back to Copilot. Security scanning runs for global installs.
+
+### When to use each scope
+
+| Use case | Scope |
+|----------|-------|
+| Team-shared instructions and prompts | Project (`apm install`) |
+| Personal commands, agents, or skills | User (`apm install -g`) |
+| CI/CD reproducible setup | Project |
+| Cross-project coding standards | User |
+
+:::note
+MCP servers are not supported at user scope. Each target uses a different MCP configuration format; user-scope MCP support is planned for a future release.
+:::
+
+:::caution
+Local path dependencies (`./path`, `../path`, `/abs/path`) are rejected at user scope. Relative paths resolve against `cwd`, which differs from the user-scope deploy root (`~/.apm/`). Use remote references for `apm install -g`.
+:::
+
 ## MCP Dependency Formats
 
 MCP dependencies support three forms: string references, overlay objects, and self-defined servers.

docs/src/content/docs/integrations/ide-tool-integration.md

@@ -51,6 +51,8 @@ apm compile
 
 For running agentic workflows locally, see the [Agent Workflows guide](../../guides/agent-workflows/).
 
+> **User-scope deployment**: `apm install -g` deploys primitives to user-level directories (`~/.copilot/`, `~/.claude/`, etc.), making packages available across all projects. See [Global Installation](../../guides/dependencies/#global-user-scope-installation) for per-target coverage.
+
 ## VS Code Integration
 
 APM works natively with VS Code's GitHub Copilot implementation.

docs/src/content/docs/reference/cli-commands.md

@@ -95,6 +95,7 @@ apm install [PACKAGES...] [OPTIONS]
 - `--verbose` - Show individual file paths and full error details in the diagnostic summary
 - `--trust-transitive-mcp` - Trust self-defined MCP servers from transitive packages (skip re-declaration requirement)
 - `--dev` - Add packages to [`devDependencies`](../manifest-schema/#5-devdependencies) instead of `dependencies`. Dev deps are installed locally but excluded from `apm pack --format plugin` bundles
+- `-g, --global` - Install to user scope (`~/.apm/`) instead of the current project. Primitives deploy to `~/.copilot/`, `~/.claude/`, etc.
 
 **Behavior:**
 - `apm install` (no args): Installs **all** packages from `apm.yml`
@@ -152,6 +153,9 @@ apm install --dev owner/test-helpers
 apm install ./packages/my-shared-skills
 apm install /home/user/repos/my-ai-package
 
+# Install to user scope (available across all projects)
+apm install -g microsoft/apm-sample-package
+
 # Install a plugin from a registered marketplace
 apm install code-review@acme-plugins
 ```
@@ -274,6 +278,7 @@ apm uninstall [OPTIONS] PACKAGES...
 
 **Options:**
 - `--dry-run` - Show what would be removed without removing
+- `-g, --global` - Remove from user scope (`~/.apm/`) instead of the current project
 
 **Examples:**
 ```bash
@@ -285,6 +290,9 @@ apm uninstall https://github.com/microsoft/apm-sample-package.git
 
 # Preview what would be removed
 apm uninstall microsoft/apm-sample-package --dry-run
+
+# Uninstall from user scope
+apm uninstall -g microsoft/apm-sample-package
 ```
 
 **What Gets Removed:**
@@ -605,13 +613,23 @@ apm deps COMMAND [OPTIONS]
 Show all installed APM dependencies in a Rich table format with per-primitive counts.
 
 ```bash
-apm deps list
+apm deps list [OPTIONS]
 ```
 
+**Options:**
+- `-g, --global` - List user-scope packages from `~/.apm/` instead of the current project
+- `--all` - List packages from both project and user scope
+
 **Examples:**
 ```bash
-# Show all installed APM packages
+# Show project-scope packages
 apm deps list
+
+# Show user-scope packages
+apm deps list -g
+
+# Show both scopes
+apm deps list --all
 ```
 
 **Sample Output:**

src/apm_cli/commands/_helpers.py

@@ -432,12 +432,13 @@ def _create_plugin_json(config):
         f.write(json.dumps(plugin_data, indent=2) + "\n")
 
 
-def _create_minimal_apm_yml(config, plugin=False):
+def _create_minimal_apm_yml(config, plugin=False, target_path=None):
     """Create minimal apm.yml file with auto-detected metadata.
 
     Args:
         config: dict with name, version, description, author keys.
         plugin: if True, include a devDependencies section.
+        target_path: explicit file path to write (defaults to cwd/apm.yml).
     """
     # Create minimal apm.yml structure
     apm_yml_data = {
@@ -455,4 +456,5 @@ def _create_minimal_apm_yml(config, plugin=False):
 
     # Write apm.yml
     from ..utils.yaml_io import dump_yaml
-    dump_yaml(apm_yml_data, APM_YML_FILENAME)
+    out_path = target_path or APM_YML_FILENAME
+    dump_yaml(apm_yml_data, out_path)