Repository navigation
docs: fix 404 example package, policy debugging output and producer pages - #3850
Closed
Daniel Meppiel (danielmeppiel) wants to merge 1 commit into
Closed
Daniel Meppiel (danielmeppiel) wants to merge 1 commit into
Daniel Meppiel (danielmeppiel) wants to merge 1 commit into
Conversation
…ages Phase 3 of the docs corpus re-sweep: per the amended scope on #3800, fix the remaining findings instead of deferring or holding them. Every claim was re-verified on current main with real CLI runs; confirmed code defects are filed as bugs (#3835-#3847) and linked where users are affected today. Refs #3800 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Daniel Meppiel (danielmeppiel)
requested a review
from Sergio Sisternes (sergio-sisternes-epam)
as a code owner
November 18, 2026 08:07
9 of 16 tasks
Contributor
There was a problem hiding this comment.
🟢 Approval recommended
No active review issues block this documentation-only update.
No open issues 🎉
What changed in this PR
This documentation-only PR addresses part of #3800’s post-release audit, aligning reader-facing guidance with current APM behavior without changing runtime code.
Changes:
- Replaces the broken migration example and updates the README and quickstart guide pins to
v0.36.1. - Corrects policy diagnostics, bundle integrity caveats, compilation guidance, and target-specific deployment details.
- Refreshes authentication, lifecycle, cache, CI, and contributor instructions.
| File | Description |
|---|---|
README.md |
Updates the approved apm-guide pin to v0.36.1. |
docs/src/content/docs/troubleshooting/policy-debugging.md |
Shows current policy output and explains the misleading remediation hint. |
docs/src/content/docs/troubleshooting/compile-zero-output-warning.md |
Replaces unsupported includes guidance with compilation.exclude. |
docs/src/content/docs/quickstart.mdx |
Updates the guide package pin to v0.36.1. |
docs/src/content/docs/producer/package-relative-links.md |
Corrects skill deployment and relative-link paths. |
docs/src/content/docs/producer/pack-a-bundle.md |
Explains the lockfile prerequisite for bundle integrity checks. |
docs/src/content/docs/producer/compile.md |
Clarifies which targets receive native rules during install. |
docs/src/content/docs/producer/author-primitives/skills.md |
Adds target destinations and corrects alias guidance. |
docs/src/content/docs/producer/author-primitives/prompts.md |
Documents Kiro prompts and install-time transformation. |
docs/src/content/docs/producer/author-primitives/instructions-and-agents.md |
Removes the incorrect agent-name collision warning. |
docs/src/content/docs/producer/author-primitives/hooks-and-commands.md |
Adds target support details and clarifies silent skips. |
docs/src/content/docs/integrations/ci-cd.md |
Specifies Python 3.11+ and includes .agents/ in commit guidance. |
docs/src/content/docs/getting-started/migration.md |
Fixes .cursorrules spelling and replaces the broken package example. |
docs/src/content/docs/getting-started/authentication.md |
Adds apm auth guidance and per-org credential precedence. |
docs/src/content/docs/contributing/integration-testing.md |
Corrects when smoke and end-to-end tests run. |
docs/src/content/docs/contributing/development-guide.md |
Corrects pre-commit setup and the requirements manifest path. |
docs/src/content/docs/consumer/installing-from-marketplaces.md |
Distinguishes fetched-reference and marketplace catalog caches. |
docs/src/content/docs/concepts/the-three-promises.md |
Corrects the lockfile model name to LockedDependency. |
docs/src/content/docs/concepts/lifecycle.md |
Separates install and compile responsibilities and clarifies init prompts. |
Review effort: Balanced
Daniel Meppiel (danielmeppiel)
added a commit
that referenced
this pull request
Nov 18, 2026
Brings the apm-usage skill fixes (formerly #3849) and the guides, producer and troubleshooting fixes (formerly #3850) into this PR, and scopes the apm-usage inheritance note: on allow lists a child [] narrows to nothing, and unmanaged_files.exclude widens by union. Refs #3800 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
3 of 8 tasks
Collaborator
Author
|
Folded into #3848 to keep this to one PR (same commits, same review fixes). |
This was referenced Nov 18, 2026
Daniel Meppiel (danielmeppiel)
added a commit
that referenced
this pull request
Nov 18, 2026
… README pin) (#3848) * docs(reference): fix policy inheritance, lockfile, manifest and CLI reference drift Phase 3 of the docs corpus re-sweep: per the amended scope on #3800, fix the remaining findings instead of deferring or holding them. Every claim was re-verified on current main with real CLI runs; confirmed code defects are filed as bugs (#3835-#3847) and linked where users are affected today. Refs #3800 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * docs(reference): show the real block hint and the exclude exception Refs #3800 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * docs: fold apm-usage and guide fixes into the reference batch Brings the apm-usage skill fixes (formerly #3849) and the guides, producer and troubleshooting fixes (formerly #3850) into this PR, and scopes the apm-usage inheritance note: on allow lists a child [] narrows to nothing, and unmanaged_files.exclude widens by union. Refs #3800 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: danielmeppiel <danielmeppiel@users.noreply.github.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Fixes the highest-impact remaining reader-facing drift, plus the approved README pin.
getting-started/migration.md: the exampleapm install microsoft/copilot-best-practicesreturns 404, so it now usesmicrosoft/apm-sample-package. Also fixes the.cursorrulesspelling.troubleshooting/policy-debugging.md: section 1 showed rule-id/severity/evidence fields that APM never prints. It is rewritten from realapm installandapm audit --cipolicy failures (install first), with a short note linking the current hint shortcoming to [BUG] Install policy block names the check, not the dependency, and tells users to remove the check from apm.yml #3835.troubleshooting/compile-zero-output-warning.md: replaces a per-dependencyincludes:filter that doesn't exist withcompilation.exclude, verified to produce zero output.apm runagent-collision pitfall that can't happen. The hook/command skip is now consistently described as silent, and the Kiro, Antigravity and Hermes rows are added.pack-a-bundle: runapm installfirst; without a lockfile the bundle has no integrity manifest ([BUG]apm pack(default Claude plugin format) ships a bundle with no integrity manifest when there is no lockfile, but says it embeds one #3846). Also fixespackage-relative-linkspaths.getting-started/authentication.md: points toapm auth <host>; per-org env vars resolve first.LockedDependency, cache layout, the requirements manifest path,uvx pre-commit install(the documenteduv runfails), CI schedule, Python 3.11+, and committing.agents/.apm-guidepin moves to#v0.36.1. This is the README change already proposed to and approved by the maintainer, and the only README change.Edits on pages that open PRs also edit (#2657, #3290, #3332, #3582, #3615, #3713, #3737, #3748, #3801) stay outside those PRs' hunks. The two overlapping edits are being coordinated with #2657 and #3582.
Issue and approved scope
Issue: Refs #3800
Human scope-approval comment: #3800 (comment) (amended scope: fix remaining findings, do not defer or hold)
Does this PR complete the issue, or what remains? Partial: one of three phase-3 batches. The remaining items need edits that overlap open PRs; I am coordinating those with the PR owners and track them on #3800.
Type of change
Testing
--help, source reads, or real CLI runs (scratch dirs,HOMEisolated).cd docs && npm run buildexits 0 ("All internal links are valid"; "Checked 1221 relative link(s) ... No broken relative links found"). Added lines are ASCII.Spec conformance (OpenAPM v0.1)
fetch_failuremerging is filed as [BUG] OpenAPM v0.1 policy merge table saysfetch_failurechild overrides; implementation escalates (stricter wins) #3847.