Skip to content

docs(troubleshooting): quote real error messages and fix wrong remediations - #3812

Merged
Daniel Meppiel (danielmeppiel) merged 1 commit into
mainfrom
docs-sweep/troubleshooting
Nov 18, 2026
Merged

Daniel Meppiel (danielmeppiel) merged 1 commit into
mainfrom
docs-sweep/troubleshooting

Conversation

@danielmeppiel

@danielmeppiel Daniel Meppiel (danielmeppiel) commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

Description

Surgical fixes to troubleshooting/*. Every quoted message was grepped in src/apm_cli/, and every remediation was checked against --help, the code, or a scratch run.

  • policy-debugging.md: five quoted symptom strings do not exist in the code, so they now quote the real messages. apm install mcp:<name> is now apm install --mcp <name>. Discovery no longer lists a project apm.yml step and instead names the .github-private/.github/.apm/_apm cascade. To test against upstream, pass --policy-source <owner>/.github (org resolves to your fork). Use --no-cache to refetch the policy, since --refresh does not touch it. Also fixes a dead #merge-rules-tighten-only anchor.
  • migration.md: apm prune does not remove a dropped target's files (apm install does) and does not switch compile strategies (compilation.strategy plus apm compile --clean, then remove leftover nested files by hand when moving to single-file). Also corrects the unsupported-lockfile-version message, notes that MCP servers belong under dependencies.mcp, and lists compile's real outputs.
  • compile-zero-output-warning.md: the worked examples confused compile and install output. Command files and skills come from apm install. The *_files_written stats keys are not printed.
  • common-errors.md: corrects the "No primitives matched", unapproved-host and authentication-failure messages and their fixes. The ref-mismatch hint depends on the case (apm install --update for a missing lock entry, apm install for a changed ref). apm list lists scripts, not prompts. The policy pin is policy.hash in apm.yml. Timeouts are no longer quoted as fixed numbers.

Deferred to the sweep report (they need a rewrite or a decision): the section 1 failure sample in policy-debugging and the nonexistent per-dependency includes: filter in compile-zero-output-warning step 3.
Pages that a still-open PR also edits are left out of this PR, as the approved scope requires. Their fixes are held for after those PRs land, and the sweep report lists them.

Issue and approved scope

Issue: Refs #3800

Human scope-approval comment: #3800 (comment)

Does this PR complete the issue, or what remains? Partial: one area batch of the corpus re-sweep. Pages edited by still-open PRs are not touched here; their findings are recorded in the final sweep report and re-checked after v0.36.1.

Type of change

  • Bug fix
  • New feature
  • Documentation
  • Maintenance / refactor

Testing

  • Tested locally: every changed claim was verified against .venv/bin/apm <cmd> --help, the source under src/apm_cli/, or a scratch-directory run. cd docs && npm run build exits 0 ("All internal links are valid"; "Checked 1197 relative link(s) ... No broken relative links found").
  • All existing tests pass (docs-only change)
  • Added tests for new functionality (if applicable)

Spec conformance (OpenAPM v0.1)

  • N/A -- this PR does not change OpenAPM-observable behaviour.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The documentation incorrectly promises automatic cleanup of stale generated files and recommends apm install --update for a ref mismatch that only requires apm install.

2 open issues
What changed in this PR

This docs-only PR updates APM troubleshooting guidance as part of the documentation re-sweep in #3800, aligning quoted errors and recovery steps with current CLI behavior.

Changes:

  • Updates policy discovery, cache refresh, and policy-violation examples.
  • Clarifies migration steps and separates compile outputs from install-deployed files.
  • Corrects common error messages, command hints, and configuration references.
File Description
docs/​src/​content/​docs/​troubleshooting/​policy-debugging.md Updates policy discovery, symptoms, remediation commands, and a broken anchor.
docs/​src/​content/​docs/​troubleshooting/​migration.md Revises lockfile, compile-strategy, target-removal, and MCP migration guidance.
docs/​src/​content/​docs/​troubleshooting/​compile-zero-output-warning.md Distinguishes compile output from prompt and skill deployment.
docs/​src/​content/​docs/​troubleshooting/​common-errors.md Updates error examples and troubleshooting commands.

Review effort: Balanced

…ations

Surgical fixes from the post-0.36 docs corpus re-sweep. Every changed
claim was checked against current main (CLI --help, source, or a
scratch-dir run). Pages that a still-open PR edits are left out, per
the approved scope.

Refs #3800

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@danielmeppiel
Daniel Meppiel (danielmeppiel) merged commit 90f93c9 into main Nov 18, 2026
26 checks passed
@danielmeppiel
Daniel Meppiel (danielmeppiel) deleted the docs-sweep/troubleshooting branch November 18, 2026 02:57
This was referenced Nov 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants