feat(compile): explicit apm compile -g + install-time hint for global root context (#1632)

* feat(compile): add explicit global compile hint

Rebuilds PR #1632 on current main after the original branch could not be rebased due to historical add/add conflicts, preserving the user-visible apm compile -g behavior and the install-time read-only hint for issue #1485.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix(compile): fold global compile review follow-ups

Tightens the explicit global compile surface after panel review: dry-run output now uses info styling, --global rejects every explicitly supplied project-output flag via an allowlist, user root context writes scan generated content before writing, and marker ownership is anchored to the file header so quoted markers cannot clobber hand-authored files.

Also updates security/install docs and adds regression traps for hand-authored root context preservation. Addresses panel follow-ups from cli-logging, DevX UX, supply-chain security, doc-writer, and test coverage.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix(compile): align global flag diagnostics

Allows --verbose with the explicit global compile path, routes the handler through CommandLogger when called from the CLI, and keeps the security documentation precise about compile -g scan reporting.

Addresses final panel follow-ups from CLI logging, DevX UX, and doc-writer.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: tighten global compile safeguards

Block critical hidden-character output in the new global compile path before writing root context files, reduce default output noise, and keep install hints scoped to verified root-context targets. Adds regression coverage for the security, dry-run, missing apm_modules, and logger-routing contracts raised by the shepherd panel.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: fold compile global review follow-ups

Route global compile output through CommandLogger, clarify the install hint and help text, and enumerate user-scope root context outputs in docs. Addresses shepherd-driver panel follow-ups for PR #1632.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* docs: clarify global compile target matrix

Document user-scope root context outputs in the target matrix so the global compile guide does not drift from reference docs. Addresses final panel doc-writer follow-up.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: danielmeppiel <danielmeppiel@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: danielmeppiel

CHANGELOG.md

@@ -154,6 +154,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `apm lock export --format cyclonedx|spdx` emits a standard SBOM inventory of installed packages, and a new declared-license recorder stores each package's manifest-declared license (`apm.yml` `license:` / `plugin.json`) in the lockfile after offline SPDX-id validation. APM records what a package declares -- it does not scan LICENSE text or gate installs on a license. (closes #1777) (#1820)
 - `apm install` / `apm pack` can now deploy an experimental Copilot-only `canvas` primitive: a package declaring `.apm/extensions/<name>/` ships verbatim to `.github/extensions/<name>/` (or `~/.copilot/extensions/<name>/` with `--global`), where Copilot CLI discovers it in-session. The surface is gated twice -- `apm experimental enable canvas` plus `--trust-canvas-extensions` for dependency-provided canvases -- and is fail-closed when the flag is off. (#1689)
 - `apm install` now blocks dependency-provided executables (hooks and `bin/`) by default, mirroring npm v12's default-deny model. A dependency's hooks or binaries deploy only after explicit approval in an `allowExecutables` block of `apm.yml`, managed via `apm approve` / `apm deny`; root-authored content and text-only primitives are unaffected. (#1723)
+- `apm compile --global` / `-g` compiles user-scope root context files such as
+  `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, and `~/.gemini/GEMINI.md` from
+  globally installed instructions. Compilation stays explicit; `apm install -g`
+  prints a one-line hint pointing at `apm compile -g` when global instructions
+  land on a root-context-only target, but writes no root context file. (#1632)
 
 ### Changed
 

docs/src/content/docs/consumer/install-packages.md

@@ -178,6 +178,12 @@ apm install -g <package>               # install to user scope (~/.apm/)
 apm install -v                         # verbose: show resolution and integration
 ```
 
+Targets with native user-scope instruction files pick up global instructions
+during install. Targets whose user-scope instruction surface is a root context
+file require explicit
+[`apm compile --global`](../../reference/cli/compile/#global-compilation);
+`apm install -g` prints a hint and writes no root context file.
+
 For the full flag reference, run `apm install --help` or see
 [CLI commands](../../reference/cli/install/).
 

docs/src/content/docs/enterprise/security.md

@@ -136,6 +136,12 @@ download → scan source → block or deploy → report
 Content scanning extends beyond install:
 
 - **`apm compile`** scans compiled output (AGENTS.md, CLAUDE.md, `.github/copilot-instructions.md`, commands) before writing to disk. Critical findings cause `apm compile` to exit with code 1 after writing — defense-in-depth since source files were already scanned at install, but compilation assembles content from multiple sources. `.github/copilot-instructions.md` is assembled from global instructions in `.apm/instructions/`, including those installed under `apm_modules/`.
+- **`apm compile --global`** scans user-scope root context files assembled from
+  globally installed instructions before writing them. Critical findings stop
+  the write and exit with code 1. Existing hand-authored root context files are
+  skipped unless they carry APM's generated marker, so opting into global
+  compilation does not clobber user-managed `CLAUDE.md`, `AGENTS.md`, or
+  `GEMINI.md` files.
 - **`apm pack`** scans files before bundling. This catches hidden characters before a package is published, preventing authors from accidentally distributing tainted content.
 - **`apm unpack`** scans bundle contents before deployment. This is a pre-deployment gate matching `apm install` — critical findings block deployment unless `--force` is used. (Note: `apm unpack` is DEPRECATED; prefer `apm install <bundle-path>` for new pipelines -- it applies the same scan plus lockfile integration. See [Pack and distribute](../producer/pack-a-bundle/).)
 

docs/src/content/docs/producer/compile.md

@@ -244,6 +244,46 @@ you can omit `start_marker` and `end_marker` if you use those verbatim.
 - In distributed compile mode, subdirectory `AGENTS.md` files remain fully
   APM-owned and are overwritten on each run.
 
+## Global compilation (-g)
+
+Install a package once globally and root-context tools on your machine can pick
+up its instructions without per-project setup. For user-scope instructions, use
+the `--global` or `-g` flag:
+
+```bash
+apm compile --global
+apm compile -g --dry-run
+```
+
+This reads **global instructions** from `~/.apm/apm_modules/` (instructions
+without `applyTo:` frontmatter) and writes user-scope root context files for
+root-context targets:
+
+- `~/.claude/CLAUDE.md` (or `$CLAUDE_CONFIG_DIR/CLAUDE.md`)
+- `~/.codex/AGENTS.md`
+- `~/.config/opencode/AGENTS.md`
+- `~/.copilot/AGENTS.md`
+- `~/.cursor/AGENTS.md`
+- `~/.gemini/GEMINI.md`
+
+### Overwrite protection
+
+When a root file exists but contains no APM marker, it is treated as
+hand-authored and never overwritten. Use `--dry-run` to preview what would
+be written without modifying files.
+
+### Constraints
+
+- Compilation is explicit. `apm install -g` (see
+  [Install packages](../consumer/install-packages/)) does not write root context
+  files; it prints a one-line hint pointing at `apm compile -g` when global
+  instructions land on a root-context-only target.
+- `--global` cannot be combined with project-output flags such as `--target`,
+  `--all`, `--watch`, `--root`, or `--output`.
+- Compiled output is security-scanned before it is written. Critical findings
+  stop the write and make `apm compile -g` exit non-zero.
+- Skills-only packages (no global instructions) do not write root files.
+
 ## Pitfalls
 
 - **Confusing compile's scope.** Compile only handles **instructions**

docs/src/content/docs/reference/cli/compile.md

@@ -109,6 +109,25 @@ The dry-run output shows `[dry-run] would remove stale CLAUDE.md -- instructions
 | `--dry-run` | Show placement decisions without writing files. |
 | `-v, --verbose` | Show source attribution and optimizer analysis. |
 
+### Global compilation
+
+Global compilation keeps supported user-scope root-context targets in sync with
+globally installed instruction packages -- one command, no per-tool setup.
+
+| Flag | Description |
+|------|-------------|
+| `-g, --global` | Compile user-scope root context files from `~/.apm/apm_modules`. Reads globally installed packages and writes one root context file per supported user-scope target (e.g. `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`). Not valid with project-output flags such as `--target`, `--all`, `--watch`, `--root`, or `--output`. Exits non-zero if `~/.apm/apm_modules` does not exist. |
+
+`apm compile --global` is explicit. `apm install -g` does not run it; instead,
+when global instructions land on a root-context-only target, install prints a
+one-line hint pointing at `apm compile -g`. Run it manually after adding or
+removing global packages. Hand-authored files (files that do not carry the
+APM-generated marker) are never overwritten.
+
+```bash
+apm compile -g
+```
+
 ## Examples
 
 Compile for whatever the project is set up for:

docs/src/content/docs/reference/cli/install.md

@@ -103,6 +103,7 @@ Transport env vars: `APM_GIT_PROTOCOL` (`ssh` or `https`) sets the default initi
 - **No-op nudge.** When the lockfile is already satisfied and nothing needs deploying, install prints `[i] Run 'apm update' to check for newer versions.` so you know the silent success was not a missed refresh.
 - **Frozen mode.** With `--frozen`, install resolves only what is in `apm.lock.yaml`. A direct dependency missing from the lockfile, or a missing lockfile entirely, exits `1`. Orphan lockfile entries (locked but no longer in `apm.yml`) are tolerated; local-path deps are skipped. This is a structural check, not a content check -- run `apm audit --ci` for hash verification.
 - **Local `.apm/` deployment.** After dependencies are integrated, primitives in the project's own `.apm/` directory are deployed to the same targets. Local files win on collision. Skipped at `--global` and with `--only mcp`.
+- **User-scope root context hint.** Compilation stays explicit. After `apm install -g`, targets with native user-scope instruction files pick up global instructions during install. Targets whose user-scope instruction surface is a root context file require [`apm compile --global`](../compile/#global-compilation); install prints a one-line `[i]` hint and writes no root context file.
 - **Stale-file cleanup.** Files a still-present package previously deployed but no longer produces are removed from the workspace, gated by per-file content hashes recorded in the lockfile (user-edited files are kept with a warning).
 - **Enterprise marketplace gate.** When installing from a `*.ghe.com` marketplace, bare cross-repo `repo:` fields (e.g. `repo: owner/repo`) are refused before any network request runs, preventing dependency-confusion attacks. Host-qualify the field to proceed: `repo: corp.ghe.com/owner/repo` for an enterprise dep, or `repo: github.com/owner/repo` for a declared cross-host dep.
 - **Security scan.** Source files are scanned for hidden Unicode and other tag-character / bidi-override patterns before deployment. Critical findings block the package; the install exits `1`. Use `--force` to deploy anyway, or run `apm audit --strip` first to remediate.

docs/src/content/docs/reference/targets-matrix.md

@@ -90,6 +90,8 @@ GitHub Copilot (CLI and IDE).
   - hooks: `.github/hooks/<name>.json`
   - generated: `.github/copilot-instructions.md` (compile output)
 - **User scope.** Partial. `prompts` deploy under `~/.copilot/prompts/`; `instructions` from all packages are concatenated into `~/.copilot/copilot-instructions.md` (Copilot CLI reads only that single file at user scope). User-scope deploys land under `~/.copilot/`, not `~/.github/`.
+- **Global compile.** `apm compile -g` can also render global instructions to
+  `~/.copilot/AGENTS.md` for root-context readers that honor `AGENTS.md`.
 
 ## claude
 
@@ -120,6 +122,9 @@ Cursor.
   - skills: `.agents/skills/<name>/SKILL.md`
   - hooks: `.cursor/hooks.json`
 - **User scope.** Partial. `instructions` is excluded at user scope; Cursor reads global rules from its Settings UI rather than from disk.
+- **Global compile.** `apm compile -g` can render global instructions to
+  `~/.cursor/AGENTS.md` for root-context readers that honor `AGENTS.md`; Cursor
+  global rules still use the Settings UI.
 - **Caveat.** Command files use the shared `claude_command` transformer today; Cursor-specific frontmatter keys (`author`, `mcp`, `parameters`, ...) are dropped at install time and surfaced via diagnostics.
 
 ## codex
@@ -174,6 +179,8 @@ OpenCode.
   - commands: `.opencode/commands/<name>.md`
   - skills: `.agents/skills/<name>/SKILL.md`
 - **Caveat.** OpenCode has no hooks concept; the `hooks` primitive is silently skipped for this target.
+- **Global compile.** `apm compile -g` writes
+  `~/.config/opencode/AGENTS.md` from global instructions.
 
 ## windsurf
 

packages/apm-guide/.apm/skills/apm-usage/commands.md

@@ -55,7 +55,7 @@ If no `--target`, no `targets:` in `apm.yml`, and no harness signal is present,
 
 | Command | Purpose | Key flags |
 |---------|---------|-----------|
-| `apm compile` | Compile agent context | `-o` output, `-t` target (comma-separated; resolution chain `--target` > apm.yml `targets:` > auto-detect), `--all` compile for every canonical target (preferred over deprecated `--target all`), `--chatmode`, `--dry-run`, `--no-links`, `--watch`, `--validate`, `--single-agents`, `-v` verbose, `--local-only`, `--clean`, `--with-constitution/--no-constitution`, `--no-dedup` / `--force-instructions` (opt out of Claude/Copilot deduplication), `--root DIR` redirect generated artifacts under DIR while sources resolve from `$PWD` (mirrors `pip install --target`; not valid with `--watch`) |
+| `apm compile` | Compile agent context | `-o` output, `-t` target (comma-separated; resolution chain `--target` > apm.yml `targets:` > auto-detect), `--all` compile for every canonical target (preferred over deprecated `--target all`), `-g`/`--global` (read global instructions from `~/.apm/apm_modules/`, write user-scope root files; cannot combine with project-output flags such as `--target`, `--all`, `--watch`, `--root`, or `--output`; critical hidden-character findings stop the write and exit 1), `--chatmode`, `--dry-run`, `--no-links`, `--watch`, `--validate`, `--single-agents`, `-v` verbose, `--local-only`, `--clean`, `--with-constitution/--no-constitution`, `--no-dedup` / `--force-instructions` (opt out of Claude/Copilot deduplication), `--root DIR` redirect generated artifacts under DIR while sources resolve from `$PWD` (mirrors `pip install --target`; not valid with `--watch`) |
 
 `apm compile --watch` live-reloads `apm.yml`: editing `target:` / `targets:` mid-session takes effect on the next file event without restarting the watcher. The CLI `--target` flag, when passed to `apm compile --watch`, still outranks `apm.yml`. Re-resolution is gated on the changed file's basename being `apm.yml`, so `.instructions.md` edits do not pay an extra resolver round-trip and a stray `backup_apm.yml` cannot trigger a reload. `--clean` is ignored in watch mode and the watcher prints an explicit `[!]` warning at startup (`--clean is ignored in watch mode; run 'apm compile --clean' separately to remove orphaned outputs.`); run `apm compile --clean` separately between watch sessions to remove orphans.
 

src/apm_cli/commands/compile/cli.py

@@ -335,6 +335,97 @@ def _resolve_effective_target(
     return detected_target, detection_reason, config_target
 
 
+def _handle_global_flag(dry_run: bool, logger: CommandLogger) -> int:
+    """Handle --global compilation of user-scope root context files.
+
+    Returns 0 on success, 1 on error (for sys.exit).
+    """
+
+    from ...compilation import compile_user_root_contexts
+    from ...core.scope import InstallScope, get_apm_dir
+    from ...integration.targets import KNOWN_TARGETS
+
+    source_root = get_apm_dir(InstallScope.USER)
+    apm_modules = source_root / "apm_modules"
+    if not apm_modules.is_dir():
+        display_path = _display_user_path(apm_modules)
+        logger.error(
+            f"User-scope apm_modules not found: {display_path}. "
+            "Run 'apm install -g <package>' to install packages globally.",
+            symbol="error",
+        )
+        return 1
+
+    results = compile_user_root_contexts(
+        list(KNOWN_TARGETS.values()),
+        source_root,
+        dry_run=dry_run,
+        logger=None,
+    )
+
+    if not results:
+        logger.info(
+            "No user-scope targets produced output -- run 'apm install -g <package>' "
+            "to add global instructions.",
+            symbol="info",
+        )
+        return 0
+
+    has_error = False
+    written_count = 0
+    would_write_count = 0
+    unchanged_count = 0
+    for entry in results:
+        status = entry.status
+        tname = entry.target
+        path = entry.path
+        display_path = _display_user_path(path) if path is not None else None
+        if status == "written":
+            logger.success(f"{tname}: wrote {display_path}", symbol="check")
+            written_count += 1
+        elif status == "would-write":
+            logger.info(f"{tname}: would write {display_path} (dry-run)", symbol="preview")
+            would_write_count += 1
+        elif status == "unchanged":
+            logger.verbose_detail(f"{tname}: unchanged {display_path}")
+            unchanged_count += 1
+        elif status == "skipped-hand-authored":
+            logger.info(f"{tname}: skipped (hand-authored) {display_path}", symbol="info")
+        elif status == "skipped-no-instructions":
+            logger.verbose_detail(f"{tname}: skipped (no global instructions)")
+        elif status.startswith("error:"):
+            logger.error(f"{tname}: {status[6:]}", symbol="error")
+            has_error = True
+        if entry.has_critical_security:
+            has_error = True
+
+    if not has_error:
+        changed_count = written_count + would_write_count
+        if changed_count:
+            verb = "Would compile" if dry_run else "Compiled"
+            message = f"{verb} {changed_count} user-scope root context file(s)"
+            if unchanged_count:
+                message += f"; {unchanged_count} unchanged"
+            message += "."
+            if dry_run:
+                logger.info(message, symbol="preview")
+            else:
+                logger.success(message, symbol="check")
+        else:
+            logger.info("No user-scope root context files changed.", symbol="info")
+
+    return 1 if has_error else 0
+
+
+def _display_user_path(path: Path) -> str:
+    """Render paths under HOME with a stable tilde prefix for CLI output."""
+    try:
+        rel = path.resolve().relative_to(Path.home().resolve())
+    except ValueError:
+        return str(path)
+    return f"~/{rel.as_posix()}"
+
+
 def _validate_project(logger: CommandLogger, dry_run: bool, source_root: Path) -> None:
     """Check APM project exists and has content.
 
@@ -892,6 +983,19 @@ def _coerce_provenance_targets(value):
         "for scratch-dir verification. Cannot be combined with --watch."
     ),
 )
+@click.option(
+    "--global",
+    "-g",
+    "global_",
+    is_flag=True,
+    default=False,
+    help=(
+        "Compile user-scope root context files (~/.claude/CLAUDE.md, etc.) "
+        "from ~/.apm/apm_modules. Cannot be combined with project-scoped output "
+        "flags such as --target, --all, --watch, --root, or --output; use with "
+        "--dry-run to preview changes."
+    ),
+)
 @click.pass_context
 def compile(  # noqa: PLR0913 -- Click handler
     ctx,
@@ -911,12 +1015,16 @@ def compile(  # noqa: PLR0913 -- Click handler
     compile_all,
     no_dedup,
     root,
+    global_,
 ):
     """Compile APM context into distributed AGENTS.md files.
 
     By default, uses distributed compilation to generate multiple focused AGENTS.md
     files across your directory structure following the Minimal Context Principle.
 
+    Use --global / -g to compile user-scope root context files from globally
+    installed packages.
+
     Use --single-agents for traditional single-file compilation when needed.
 
     Target platforms:
@@ -953,6 +1061,39 @@ def compile(  # noqa: PLR0913 -- Click handler
         # consumers running with -W default, which we have none of.
         logger.warning("'--target all' is deprecated; use '--all' instead.")
 
+    # --global: compile user-scope root context files from ~/.apm/apm_modules.
+    # Must be checked before --watch / --root guards so we return early.
+    if global_:
+        from click.core import ParameterSource
+
+        allowed_with_global = {"global_", "dry_run", "verbose"}
+        flag_names = {
+            "chatmode": "--chatmode",
+            "clean": "--clean",
+            "compile_all": "--all",
+            "legacy_skill_paths": "--legacy-skill-paths",
+            "local_only": "--local-only",
+            "no_dedup": "--no-dedup/--force-instructions",
+            "no_links": "--no-links",
+            "output": "--output",
+            "root": "--root",
+            "single_agents": "--single-agents",
+            "target": "--target",
+            "validate": "--validate",
+            "verbose": "--verbose",
+            "watch": "--watch",
+            "with_constitution": "--with-constitution/--no-constitution",
+        }
+        for name in sorted(set(ctx.params) - allowed_with_global):
+            if ctx.get_parameter_source(name) is ParameterSource.DEFAULT:
+                continue
+            flag = flag_names.get(name, f"--{name.replace('_', '-')}")
+            raise click.UsageError(f"--global is not valid with {flag}")
+        rc = _handle_global_flag(dry_run=dry_run, logger=logger)
+        if rc != 0:
+            ctx.exit(rc)
+        return
+
     # --root + --watch is rejected: ``_watch_mode`` uses bare-relative
     # paths (``Path(APM_DIR)``, ``AgentsCompiler(".")``) and the watch
     # loop would scan the deploy root rather than the source tree. The