feat(install): -g should compile instructions into user-scope root context file

[vlsi]

Summary

apm install -g <pkg> deploys per-target primitives into user-scope directories (~/.claude/skills/, ...) and writes metadata under ~/.apm/. For instructions this is not enough: the harness loads them only through a root context file (CLAUDE.md, AGENTS.md, GEMINI.md) that apm compile generates, and apm compile has no user-scope mode.

Net effect: apm install -g silently installs instructions that no harness ever picks up.

Repro

Real-world example: Netcracker/qubership-ai-packages/agent-packages/apm-authoring ships both .apm/skills/ and .apm/instructions/.

apm install -g Netcracker/qubership-ai-packages --target claude
# skills land under ~/.claude/skills/                         -> picked up by Claude Code
# instructions land under ~/.apm/apm_modules/.../instructions/ -> never reach ~/.claude/CLAUDE.md
ls ~/.claude/CLAUDE.md   # missing

apm compile has no --global / -g flag (see src/apm_cli/commands/compile/cli.py). The obvious workaround cd ~/.apm && apm compile --target claude writes to ~/.apm/CLAUDE.md, which Claude Code does not read.

Proposal

1. When apm install -g finishes and at least one installed package carries instructions, run the compile pipeline with scope=USER so it reads ~/.apm/apm_modules/ and writes into each active target's user-scope root context path (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, ~/.gemini/GEMINI.md, ...).
2. Add a symmetric --global / -g flag to apm compile.
3. Honour CLAUDE_CONFIG_DIR and the equivalent env vars that TargetProfile.for_scope(user_scope=True) already handles.
4. Reuse the <!-- Generated by APM CLI from .apm/ primitives --> marker rule so a hand-authored root context file is never overwritten without consent.

Packages that contain only skills, agents, commands, hooks, or MCP already work correctly under -g -- compile is not on the path for those primitives.

[github-actions]

Triage decision

accept

Proposed labels

theme/portability
area/cli
area/distribution
type/bug
status/accepted
priority/high

Milestone

0.14.0

Suggested next action

Implement scope=USER in the compile pipeline and add -g/--global to apm compile, then wire apm install -g to invoke the user-scope compile step after deploying instruction primitives.

Suggested issue comment

Thanks for the precise repro and root-cause analysis -- the gap is confirmed: `apm install -g` deploys instructions that no harness ever loads because `apm compile` has no user-scope mode.

This is a broken promise in the -g install path, not a missing feature, so it lands as type/bug with priority/high on the 0.14.0 milestone.

The fix involves two linked changes:
1. Add `scope=USER` to the compile pipeline so it reads `~/.apm/apm_modules/` and writes to each active target's user-scope root context path.
2. Add `-g/--global` to `apm compile` (symmetric with `apm install -g`).
3. Wire `apm install -g` to trigger the user-scope compile step when at least one installed package carries `instructions`.

The `<!-- Generated by APM CLI -->` marker guard already handles the "don't overwrite hand-authored context files" case, and `TargetProfile.for_scope(user_scope=True)` already exists -- so the integration surface is smaller than it might look.

Would you like to take this as a PR? If so, start with step 1 (the compile scope) and open a draft PR early for architecture review.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The repro is clear and reproducible. The user expectation is correct: -g should deploy end-to-end for all primitive types. The fact that skills/agents/commands already work under -g (compile is not on their path) while instructions silently fail is an inconsistency that will confuse every user who installs a mixed-primitive package globally. High priority because the broken behavior is silent -- no error, no warning.

Supply Chain Security Expert -- Risk-Surface Reviewer

The user-scope compile writes to ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, etc. The existing marker-guard prevents overwriting hand-authored files. The CLAUDE_CONFIG_DIR env var is already handled. No new supply-chain risk -- this is closing a hole in an existing flow, not opening a new one. area/cli and area/distribution apply.

OSS Growth Hacker -- Contributor-Tone Reviewer

vlsi is NONE association, technically sophisticated, with a working repro and specific code file references. The reply should validate the diagnosis immediately, not hedge. A direct invitation to open a draft PR is appropriate for someone at this technical level.

Python Architect -- Architecture Reviewer

The fix is well-scoped: add USER scope to compile, add -g flag, wire post-install trigger. TargetProfile.for_scope(user_scope=True) already exists, which is the main extension point. The main cross-cutting risk is install->compile sequencing (compile must run after all packages are deployed, not interleaved). That is an implementation detail, not a design-doc blocker. Status: accept.

Doc Writer -- Documentation Reviewer

The new --global flag on apm compile needs a reference entry. The apm install -g behavior change (now also compiles instructions) needs a note in the install docs. area/docs-site is a secondary area pruned from the label set to stay within the 6-label limit -- the implementing PR scope checklist will capture it.

APM CEO -- Triage Arbiter

This is a broken promise in a documented feature. Priority/high, accept, milestone 0.14.0. theme/portability because the gap breaks the cross-tool user-scope install story. The fix is well-specified enough that needs-design is not warranted.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": "theme/portability",
  "areas": ["area/cli", "area/distribution"],
  "type": "type/bug",
  "status": "status/accepted",
  "priority": "priority/high",
  "preserved_labels": [],
  "milestone": "0.14.0",
  "next_action": "Implement scope=USER in the compile pipeline and add -g/--global to apm compile, then wire apm install -g to invoke the user-scope compile step after deploying instruction primitives.",
  "comment_markdown": "Confirmed: apm install -g deploys instructions that no harness ever loads. Accepted as type/bug priority/high on 0.14.0. Fix: add scope=USER to compile, add -g to apm compile, wire post-install compile trigger for instructions primitives."
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · sonnet46 7.4M · ◷

[danielmeppiel]

Triaged under a batch bug sweep. This reads as a feature/design request rather than a regression: apm compile has no global-mode behavior at HEAD to regress against, so the described change is new design work, not a bug. Surfacing for human triage to reprioritize as an enhancement; leaving the issue open.