[BUG] docs(install): local .apm/ deployment is documented as skipped at --global, but ~/.apm/ primitives do deploy
Nobody has claimed this yet.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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