microsoft / microsoft/apm

[BUG] docs(install): local .apm/ deployment is documented as skipped at --global, but ~/.apm/ primitives do deploy

Open
#3,014 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

area/cli area/docs-site status/accepted triage/recommended type/docs
Dominant language
Python
Stars
3.8k
Forks
362
Avg merge
1d 17h
Merged PRs (30d)
132

Description

Describe the bug

The apm install reference documents local .apm/ deployment as "Skipped at --global and with --only mcp" (docs/src/content/docs/reference/cli/install.md). The --only mcp half is correct; the --global half is not. At user scope the source root is $HOME (get_source_root() in src/apm_cli/core/scope.py), so apm install -g runs the phase against ~/.apm/ and deploys those primitives to user-scope targets.

The wording traces to #830, where apm install -g was walking all of $HOME looking for local primitives. That was resolved by scoping the walk to ~/.apm/, not by skipping the phase, so the docs describe a skip that was never shipped. Readers who keep primitives in ~/.apm/ are told the supported path does not work and go hunting for a workaround.

To Reproduce

Verified on 0.31.0 (8fd10ac) against an isolated HOME containing:

~/.apm/apm.yml                             # targets: [claude]
~/.apm/instructions/demo.instructions.md
~/.apm/skills/demo-skill/SKILL.md
$ apm install -g
[>] Installing dependencies from apm.yml...
  [+] <project root> (local)
  |-- 1 rule(s) integrated -> .claude/rules/
  |-- 1 skill(s) integrated -> .claude/skills/
[*] Installed 1 APM dependency in 0.1s.

$ ls ~/.claude/rules/
demo.md

The same setup with apm install -g --only mcp deploys nothing, matching the documented --only mcp skip.

Expected behavior

The bullet lists --only mcp as the only skip condition and states the user-scope source root, so readers know ~/.apm/ primitives deploy to user-scope targets.

PR #2769 is open with the one-line correction.

Environment

  • OS: macOS (Darwin 25.6.0)
  • APM Version: 0.31.0 (8fd10ac)
  • Documented claim still present at HEAD 707e8fa0

Disclosure: this report was drafted with AI assistance; every command above was executed on the environment described.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Open docs/src/content/docs/reference/cli/install.md and inspect the install-scope wording alongside get_source_root() in src/apm_cli/core/scope.py. Compare the documented skip conditions with the reproduced --global and --only mcp behavior, then check PR #2769. Done means the reference accurately states that ~/.apm/ primitives deploy at user scope while --only mcp skips them.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
Under an hour
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.