docs: clarify dev-only primitives and the .apm/ scanner boundary

[danielmeppiel]

Why

Maintainers hit a recurring surprise: declare a local-path devDependency pointing at a skill under .apm/skills/, expect apm pack --format plugin to strip it, and the pack scanner picks it up anyway. The docs do not explain that the local-content scanner operates on .apm/ only and does NOT consult the devDependency marker. Three behaviors compound the confusion:

1. The scanner does not honor the devDep marker -- it bundles everything under .apm/ at pack time.
2. includes: is allow-list only -- there is no exclude: form, so users cannot fence off subdirectories of .apm/.
3. Plain apm install (no flag) deploys both dependencies and devDependencies; there is no --omit=dev flag today.

A real-world example of the cure: dadff60 in danielmeppiel/genesis moves a maintainer-only skill out of .apm/ and references it via a local-path devDependency.

What

• New guide: docs/src/content/docs/guides/dev-only-primitives.md -- the canonical pattern (author outside .apm/, reference via local-path devDependency), with worked example, the three behaviors it works around, when to use / when not, and a verification recipe.
• 5 cross-reference patches to existing pages, each surgical:
  • introduction/anatomy-of-an-apm-package.md -- new FAQ entry pointing to the guide.
  • reference/manifest-schema.md 3.9 -- explicit note that includes: has no exclude form.
  • reference/manifest-schema.md 5 -- caveat on plain apm install deploying devDeps + scanner caveat + local-path devDep example.
  • guides/dependencies.md -- caveat in Development Dependencies section.
  • guides/pack-distribute.md -- caveat in devDependencies exclusion section.
  • guides/skills.md -- new Option 5 for maintainer-only skills.

How

Audit followed the PROSE methodology: single source of truth lives in the new guide; every other page gets a 1-2 sentence summary and a relative cross-reference. Total addition is one new ~580-word guide plus ~125 lines of inserts -- all surgical, no rewrites of surrounding prose.

ASCII-only throughout my changes (box-drawing in the new guide and the Option 5 tree use +-- / |, matching the audit's convention).

Verification

• npm run build in docs/ succeeds; starlight-links-validator reports all internal links valid (47 pages built).
• grep -rln dev-only-primitives docs/src/content/docs/ resolves to all 5 patched files plus the new guide.
• apm pack --format plugin --dry-run recipe in the new guide is the empirical check users can run today.

Out of scope

• Pre-existing dependencies.md line 267 schema bug (- source: owner/test-helpers does not match the manifest schema). Will file separately.
• Feature gaps from Step 5 of the audit (--omit=dev flag, includes: exclude: form, scanner honoring devDep marker). Docs-only PR.

---

Co-authored-by: Copilot copilot@github.com

[Copilot]

Pull request overview

Adds documentation clarifying how dev-only primitives should be authored to avoid being bundled by the .apm/ local-content scanner during apm pack --format plugin, and updates the PR Review Panel workflow to cost-gate execution on the panel-review label.

Changes:

• Add a new guide documenting the canonical "dev-only primitives" pattern (author outside .apm/, reference via local-path devDependencies).
• Add cross-references and caveats across existing docs to explain scanner behavior, includes: limitations, and install/pack devDep semantics.
• Update PR Review Panel workflow to enforce a deterministic pre-activation label gate.

Show a summary per file

File	Description
docs/src/content/docs/reference/manifest-schema.md	Adds explicit notes about includes: being allow-list-only and clarifies devDeps behavior vs .apm/ scanning.
docs/src/content/docs/introduction/anatomy-of-an-apm-package.md	Adds FAQ guidance pointing to the new dev-only primitives guide.
docs/src/content/docs/guides/skills.md	Adds a new "Maintainer-only Skill (Dev-only)" option referencing the canonical pattern.
docs/src/content/docs/guides/pack-distribute.md	Clarifies devDependencies exclusion and adds caveat about .apm/ local-content scanning.
docs/src/content/docs/guides/dev-only-primitives.md	New canonical guide describing the pattern, rationale, and verification steps.
docs/src/content/docs/guides/dependencies.md	Adds an explicit caveat about apm install deploying devDeps and .apm/ scanning behavior.
.github/workflows/pr-review-panel.md	Adds a workflow-level label filter step intended to skip non-panel-review label events early.
.github/workflows/pr-review-panel.lock.yml	Regenerates the compiled lockfile to reflect the workflow changes.

Copilot's findings

• Files reviewed: 6/6 changed files
• Comments generated: 2

[Copilot]

Intra-guides links elsewhere in the docs use the ../<page>/ form (e.g. guides/dependencies.md -> ../pack-distribute/). Using ./dev-only-primitives/ here will resolve under the current page path in the built site (e.g. /guides/pack-distribute/dev-only-primitives/), which breaks navigation. Recommend switching this to ../dev-only-primitives/ for consistency and correct routing.

Suggested change

**Caveat for primitives you author yourself:** the dev/prod split is enforced via the lockfile's `is_dev` marker for resolved dependencies. The local-content scanner that ships your own `.apm/` content does NOT consult that marker -- it bundles everything under `.apm/`. To keep maintainer-only primitives (release-checklist skills, internal debugging agents) out of plugin bundles, author them OUTSIDE `.apm/` (e.g. under `dev/`) and reference them via a local-path devDependency. See [Dev-only Primitives](./dev-only-primitives/).

**Caveat for primitives you author yourself:** the dev/prod split is enforced via the lockfile's `is_dev` marker for resolved dependencies. The local-content scanner that ships your own `.apm/` content does NOT consult that marker -- it bundles everything under `.apm/`. To keep maintainer-only primitives (release-checklist skills, internal debugging agents) out of plugin bundles, author them OUTSIDE `.apm/` (e.g. under `dev/`) and reference them via a local-path devDependency. See [Dev-only Primitives](../dev-only-primitives/).

[Copilot]

This link uses ./pack-distribute/#plugin-format, but other pages in guides consistently link to sibling pages with ../<page>/... (because routes are /guides/<page>/). As written, it will resolve under /guides/dev-only-primitives/pack-distribute/ in the built site. Suggest changing it to ../pack-distribute/#plugin-format.

Suggested change

	- [Pack & Distribute -- Plugin format](./pack-distribute/#plugin-format) -- what the scanner emits.
	- [Pack & Distribute -- Plugin format](../pack-distribute/#plugin-format) -- what the scanner emits.