chore(docs): pin npx package versions in skill docs (Fixes #381)

Pin copy-pasteable npx invocations to explicit versions so agents
executing them verbatim get reproducible behavior:

- playwright docs: npx playwright@1.62.1 (SKILL.md, README.md,
  references 02-selectors / 05-ci-integration / 07-accessibility)
- mermaid-diagrams: @mermaid-js/mermaid-cli@11.16.0 (SKILL.md,
  references/pdf-rendering-pipeline.md)
- hugo-theme seo-outputs-testing: @axe-core/cli@4.13.0
- agent-skills using-scripts.md: strengthen version-pinning bullet
  into a normative rule for copy-pasteable commands

Reword the anydoc cli-reference "Version pinning" prose so the
anti-pattern is explained didactically without presenting an unpinned
command as a recipe; the @0.1.6 house pin is unchanged.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

agent-skills/references/using-scripts.md

@@ -47,7 +47,7 @@ When an existing package already does what you need, you can reference it direct
 
     * Bundled with Node.js — no extra install needed.
     * Downloads the package, runs it, and caches it for future use.
-    * Pin versions with `npx package@version` for reproducibility.
+    * **Pin versions for any command an agent will copy-paste** (`npx package@version`, e.g. `npx eslint@9.0.0`) so the command behaves the same over time — never leave a copy-pasteable `npx` invocation unpinned.
   </Tab>
 
   <Tab title="bunx">

anydoc/references/cli-reference.md

@@ -112,11 +112,11 @@ curl -s https://example.com/paper.pdf | npx -y @firecrawl/anydoc@0.1.6 -   # URL
 ### Version pinning
 
 Always pin the version: `npx -y @firecrawl/anydoc@0.1.6`. An unpinned
-`npx -y @firecrawl/anydoc` floats to the latest published tag, so conversions
+invocation (`npx -y @firecrawl/anydoc` with no `@version` suffix) floats to the
-are not reproducible across time. All behavior in this skill is documented
+latest published tag, so conversions are not reproducible across time. All
-against **0.1.6**. The `-y` flag answers npx's "Ok to proceed?" install prompt
+behavior in this skill is documented against **0.1.6**. The `-y` flag answers
-non-interactively; without it, bare `npx @firecrawl/anydoc` will prompt on a
+npx's "Ok to proceed?" install prompt non-interactively — omitting it means npx
-cold cache.
+asks for confirmation before installing a cold-cache package.
 
 ### First run and offline behavior
 

hugo-theme/references/seo-outputs-testing.md

@@ -305,7 +305,7 @@ jobs:
 
     - name: Accessibility audit
       run: |
-        npx @axe-core/cli http://localhost:1313/ --exit --stdout || true
+        npx @axe-core/cli@4.13.0 http://localhost:1313/ --exit --stdout || true
 
 ```
 
@@ -315,7 +315,7 @@ jobs:
 |------|---------|-------------|
 | `html5validator` | HTML spec compliance | `pip install html5validator` |
 | `broken-link-checker` | Dead links | `npm install broken-link-checker` |
-| `@axe-core/cli` | Accessibility | `npx @axe-core/cli` |
+| `@axe-core/cli` | Accessibility | `npx @axe-core/cli@4.13.0` |
 | `hugo --templateMetrics` | Template performance | Built-in CLI flag |
 | `hugo --renderToMemory` | Build without writing to disk | `hugo --renderToMemory --gc` |
 | `hugo mod verify` | Module integrity | Built-in |

mermaid-diagrams/SKILL.md

@@ -33,7 +33,7 @@ Mermaid code blocks (```mermaid```) do NOT render in the Pandoc → HTML → Pup
 
 **For any diagram destined for PDF output:**
 1. Create the diagram as a standalone .mmd file
-2. Pre-render to SVG: `npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.svg --width 800`
+2. Pre-render to SVG: `npx @mermaid-js/mermaid-cli@11.16.0 -i diagram.mmd -o diagram.svg --width 800`
 3. Choose one embedding method: use raw inline SVG by default, or base64 data URIs when the renderer corrupts raw SVG.
 4. Strip hardcoded `max-width` pixel values from the SVG tags
 5. Use `flowchart TD` (portrait) not `flowchart LR` (landscape) — see `references/portrait-layout.md`
@@ -116,9 +116,9 @@ See `references/c4-to-flowchart.md` for worked examples of all three C4 levels.
 ### CLI (mmdc) — for PDF/SVG/PNG output
 
 ```bash
-npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.svg
+npx @mermaid-js/mermaid-cli@11.16.0 -i diagram.mmd -o diagram.svg
-npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.png
+npx @mermaid-js/mermaid-cli@11.16.0 -i diagram.mmd -o diagram.png
-npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.pdf
+npx @mermaid-js/mermaid-cli@11.16.0 -i diagram.mmd -o diagram.pdf
 ```
 
 Requires Puppeteer + Chromium (~1.7GB). Use the Docker image for isolated rendering:

mermaid-diagrams/references/pdf-rendering-pipeline.md

@@ -8,7 +8,7 @@ This reference captures the lessons from a session where six PDF iterations were
 
 ```bash
 # Step 1: Pre-render all Mermaid diagrams to SVG
-npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.svg --width 800
+npx @mermaid-js/mermaid-cli@11.16.0 -i diagram.mmd -o diagram.svg --width 800
 
 # Step 2: Embed SVGs in markdown (NOT as data URI img tags)
 # Use raw <svg> tags inline in the markdown file

playwright/README.md

@@ -30,11 +30,11 @@ bash scripts/pwrun report --report test-results/test-results.json --json
 # Scaffold a new suite (copy the templates into your project)
 cp templates/playwright.config.ts templates/example.spec.ts templates/accessibility.spec.ts .
 npm i -D @playwright/test
-npx playwright install
+npx playwright@1.62.1 install
-npx playwright test
+npx playwright@1.62.1 test
 ```
 
-The `--help` output documents every flag and works without Node. Set `BASE_URL` to override the smoke target; `scripts/pwrun smoke --url http://localhost:3000 --json` runs a delegated pass through `npx playwright test`.
+The `--help` output documents every flag and works without Node. Set `BASE_URL` to override the smoke target; `scripts/pwrun smoke --url http://localhost:3000 --json` runs a delegated pass through `npx playwright@1.62.1 test`.
 
 ## Triggers
 

playwright/SKILL.md

@@ -75,7 +75,7 @@ Exit codes: 0 ok, 1 analysis error, 2 usage error, 127 dependency (node/playwrig
 
 ## CI integration
 
-- Install browsers and OS deps on the runner (`npx playwright install --with-deps`), pin the Playwright version, and cache `~/.cache/ms-playwright`.
+- Install browsers and OS deps on the runner (`npx playwright@1.62.1 install --with-deps`), pin the Playwright version, and cache `~/.cache/ms-playwright`.
 - Configure `webServer`, `retries` (retry flaky tests on CI only), and `trace: 'on-first-retry'` so failures are debuggable. Report with `html`/`json`/`github` and upload artifacts on failure.
 - Triage CI failures from the JSON report with `scripts/pwrun report --json` — it summarizes stats, failing specs, and error messages without opening a browser. Full CI recipes: `references/05-ci-integration.md`.
 
@@ -94,7 +94,7 @@ Exit codes: 0 ok, 1 analysis error, 2 usage error, 127 dependency (node/playwrig
 ## Headed debugging
 
 - Run headed (`--headed`), slow the action with `--slow-mo`, or drop into the inspector with `--debug` / `PWDEBUG=1` and the `page.pause()` breakpoint.
-- Generate starter tests with `npx playwright codegen <url>`, then harden the generated selectors into user-facing locators.
+- Generate starter tests with `npx playwright@1.62.1 codegen <url>`, then harden the generated selectors into user-facing locators.
 - When a test fails: read the trace (`--trace on`), which records network, DOM snapshots, and console for the failed action. Use `scripts/pwrun report --report <json> --json` first to see the failure summary.
 - Debugging workflows live in `references/07-accessibility-and-debugging.md`.
 
@@ -124,7 +124,7 @@ Exit codes: 0 ok, 1 analysis error, 2 usage error, 127 dependency (node/playwrig
 |---|---|
 | Toolchain is present | `scripts/pwrun doctor --json` reports node, @playwright/test, and browsers available |
 | Suite is understood | `scripts/pwrun inventory --json` lists config and spec files |
-| A test passes | `npx playwright test` exit 0 on the targeted spec (or `smoke` delegation) |
+| A test passes | `npx playwright@1.62.1 test` exit 0 on the targeted spec (or `smoke` delegation) |
 | A CI failure is explained | `scripts/pwrun report --report test-results.json --json` names the failing specs and errors |
 | Accessibility is covered | An axe scan runs with zero violations of the declared severity, and aria snapshots match |
 | No regressions in the covered flows | The suite ran under the configured workers/sharding with expected/flaky/unexpected counts recorded |

playwright/references/02-selectors.md

@@ -43,7 +43,7 @@ await card.getByRole('button', { name: 'Add to cart' }).click();
 A flaky test is a bug report about your selectors, not a request for more
 `waitForTimeout`. When a test passes sometimes:
 
-1. Run the spec alone (`npx playwright test <spec> --workers=1 --repeat-each=5`)
+1. Run the spec alone (`npx playwright@1.62.1 test <spec> --workers=1 --repeat-each=5`)
    to measure flakiness deterministically.
 2. Use `--debug` or the trace to see what the failing action actually resolved.
    Common causes:

playwright/references/05-ci-integration.md

@@ -19,8 +19,8 @@ jobs:
       - uses: actions/setup-node@v4
         with: { node-version: 20, cache: npm }
       - run: npm ci
-      - run: npx playwright install --with-deps chromium
+      - run: npx playwright@1.62.1 install --with-deps chromium
-      - run: npx playwright test
+      - run: npx playwright@1.62.1 test
       - if: failure()
         uses: actions/upload-artifact@v4
         with:
@@ -31,7 +31,7 @@ jobs:
 
 ## Non-negotiables
 
-1. **Install browsers with OS deps**: `npx playwright install --with-deps` (not
+1. **Install browsers with OS deps**: `npx playwright@1.62.1 install --with-deps` (not
    bare `install`) on Linux runners; `--with-deps` installs the system
    libraries Chromium/Firefox/WebKit need.
 2. **Pin and cache**:
@@ -77,7 +77,7 @@ strategy:
   matrix:
     shard: [1/4, 2/4, 3/4, 4/4]
 steps:
-  - run: npx playwright test --shard=${{ matrix.shard }}
+  - run: npx playwright@1.62.1 test --shard=${{ matrix.shard }}
 ```
 
 Merge reports from all shards with `playwright merge-reports` (see

playwright/references/07-accessibility-and-debugging.md

@@ -42,7 +42,7 @@ await expect(page).toMatchAriaSnapshot(`
 - These read like spec assertions ("the heading is X, the button is Y") and
   catch regressions in structure, labels, and semantics — not just contrast.
 - They are stable: inline text changes show up as a reviewable diff.
-- **Update deliberately.** Run `npx playwright test --update-snapshots` only
+- **Update deliberately.** Run `npx playwright@1.62.1 test --update-snapshots` only
   after inspecting what changed; never blind-update to make CI green (hard
   boundary in `SKILL.md`).
 - Requires Playwright 1.49+ (see `00-source-index.md` for version notes).
@@ -56,14 +56,14 @@ When a test fails or a locator matches nothing:
 2. **Run headed with slow-mo** to watch the actual page:
 
    ```bash
-   npx playwright test <spec> --headed --slow-mo 300
+   npx playwright@1.62.1 test <spec> --headed --slow-mo 300
    ```
 3. **The inspector** (`--debug` or `PWDEBUG=1`) pauses before each action and
    shows the current locator; `page.pause()` drops a breakpoint mid-test.
 4. **Codegen** to prototype a flow quickly:
 
    ```bash
-   npx playwright codegen https://example.com
+   npx playwright@1.62.1 codegen https://example.com
    ```
    Generate starter tests, then harden the emitted selectors into user-facing
    locators (`02-selectors.md`).