docs: fix packaged docs against source, ship snippets, check anchors

Merged
OK
10d ago
+448-246

Every docs/**/*.mdx page ships in the e2e package so coding agents can read the docs offline. An audit of those 57 pages against packages/*/src turned up about 45 wrong or stale claims. This PR fixes them, ships the snippets the pages import, and adds a check for #anchor links, which mint broken-links does not cover.

Packaging

  • packages/e2e/scripts/prepare-build.ts now copies docs/snippets/*.jsx. quickstart and models keep the provider list (packages, env vars, model setup) only in model-provider.jsx, so offline those sections were empty. Every page-level import now resolves inside the package.
  • New scripts/check-docs-anchors.ts, run by docs:check. It slugs headings, tabs, and accordions the way Mintlify does (@sindresorhus/slugify 2.2.0, the version @mintlify/common pins). It found /reference/config#tests in reference/cli.mdx, which matches no heading.

Wrong claims fixed

  • security.mdx said there is no update check, but e2e feedback fetches registry.npmjs.org/e2e/latest.
  • reference/security.mdx:
    • A tool without execute fails with CONFIG_LOAD_FAILED, not INVALID_CONFIG.
    • The saved-session envelope keeps the secret-filled flag unencrypted (authenticated only).
    • Redaction covers only .txt/.csv/.json/.html/.htm downloads.
    • Limrun is now listed under outbound connections.
  • reference/engine.mdx: a failing startVideo fails the launch only when the video mode was set explicitly. Also adds the missing EnginePrepareInfo.headed, and maps select_at/type_at/press_at to their action kinds.
  • reference/mobile.mdx: mobile({ app }) gets the generic unknown-key error. Also covers the prepare failures that end the run, press('Space'), and the FoldPose export.
  • migrate/playwright.mdx: web({ connect }) is CDP-only, so use.connectOptions is now a "missing" row. There is no -g.
  • migrate/maestro.mdx, migrate/detox.mdx, skills/migrate-to-e2e: use init --engine mobile instead of initializing for web and swapping the engine by hand.
  • ci/bitrise, ci/codemagic, ci/eas-workflows: Node 24. A preinstalled 22.x can be older than 22.22.3, which fails with NODE_UNSUPPORTED.
  • reference/errors.mdx:
    • AgentError now shows category/retryable/details.
    • The two conflicting POLICY_DENIED rows are merged into one that links the security rules.
    • Adds how e2e login/logout/models print failures.
  • Smaller fixes:
    • environment.mdx: 4 CI markers, LIMRUN_*, E2E_WEB_BROWSERS_*, and inheritEnv.
    • agent.mdx: vision with a custom executor, StepCacheInfo.entry/detail, and mobile's missing selectOption.
    • config.mdx: undefined handling.
    • mcp.mdx: exit codes.
    • debugging.mdx: a jq recipe for serial groups, and unbox-ai runs/--run 0.
    • telemetry.mdx: --watch and run().
    • expect.mdx: two sample messages the code shown could not produce.
    • screen.mdx: null guard on boundingBox() and the swipe duration range.
    • web.mdx: WebBasicAuth and WebInitScript.
    • authentication.mdx: missing imports.
  • Source, with an e2e patch changeset:
    • engine/manifest.ts: the version error no longer says the version keys the replay cache (it keys sessions and reports).
    • types.ts: the E2EConfig.output JSDoc names results/ instead of artifacts/.

Pages are not shortened here, to keep the diff reviewable. Per-page shortening PRs stack on this one.

Verified

Ran it locally: yes

  • pnpm run check, including the new anchor check: docs anchors: 320 anchor links across 57 pages resolve. On origin/main it reports docs/reference/cli.mdx:565: no #tests in docs/reference/config.mdx.
  • The anchor check was run on a scratch page with a 4-backtick fence around a 3-backtick one, duplicate accordion titles, <span id>, <Card id>, an explicit tab id, and a {#custom} heading. Each case resolves or fails the way Mintlify renders it.
  • node scripts/prepare-build.ts && npm pack --dry-run: 57 pages plus 5 docs/snippets/*.jsx ship, and every page import resolves inside the package.
  • Every changed claim was checked against packages/*/src by a separate fresh-context verification pass.
  • mint dev renders the changed pages:
errors.mdx POLICY_DENIEDdebugging.mdx serial groupsweb.mdx WebBasicAuth