Skip to content

docs: fix 404 example package, policy debugging output and producer pages - #3850

Closed
Daniel Meppiel (danielmeppiel) wants to merge 1 commit into
mainfrom
docs-sweep/p3-guides
Closed

Daniel Meppiel (danielmeppiel) wants to merge 1 commit into
mainfrom
docs-sweep/p3-guides

Conversation

@danielmeppiel

Copy link
Copy Markdown
Collaborator

Description

Fixes the highest-impact remaining reader-facing drift, plus the approved README pin.

  • getting-started/migration.md: the example apm install microsoft/copilot-best-practices returns 404, so it now uses microsoft/apm-sample-package. Also fixes the .cursorrules spelling.
  • troubleshooting/policy-debugging.md: section 1 showed rule-id/severity/evidence fields that APM never prints. It is rewritten from real apm install and apm audit --ci policy 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-dependency includes: filter that doesn't exist with compilation.exclude, verified to produce zero output.
  • Producer pages: compile-required column (install deploys native rules for claude, grok-build and antigravity). Removes an apm run agent-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: run apm install first; 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 fixes package-relative-links paths.
  • getting-started/authentication.md: points to apm auth <host>; per-org env vars resolve first.
  • concepts, consumer, contributing, integrations: compile vs install roles, init re-run prompts, LockedDependency, cache layout, the requirements manifest path, uvx pre-commit install (the documented uv run fails), CI schedule, Python 3.11+, and committing .agents/.
  • README.md:179 and quickstart.mdx: the apm-guide pin 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

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

Testing

  • Tested locally: every changed claim was re-verified on current main with --help, source reads, or real CLI runs (scratch dirs, HOME isolated). cd docs && npm run build exits 0 ("All internal links are valid"; "Checked 1221 relative link(s) ... No broken relative links found"). Added lines are ASCII.
  • All existing tests pass (docs-only change)
  • Added tests for new functionality (if applicable)

Spec conformance (OpenAPM v0.1)

…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>

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.

🟢 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>
@danielmeppiel

Copy link
Copy Markdown
Collaborator Author

Folded into #3848 to keep this to one PR (same commits, same review fixes).

@danielmeppiel
Daniel Meppiel (danielmeppiel) deleted the docs-sweep/p3-guides branch November 18, 2026 08:19
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>
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