Symptom

The build_docs job in .github/workflows/package.yml fails during release builds with:

$ pnpm run build:toolkit && docs-toolkit pdf --lang all
$ pnpm --filter backend.ai-docs-toolkit build
$ tsc
sh: 1: docs-toolkit: not found

Example failing run: https://github.com/lablup/backend.ai-webui/actions/runs/25917622880/job/76178117083 (v26.4.8-rc.4)

Root Cause

backend.ai-docs-toolkit exposes its CLI via bin: { "docs-toolkit": "./dist/cli.js" }, but dist/cli.js only exists after tsc runs. On a fresh checkout:

1. pnpm install --frozen-lockfile tries to symlink node_modules/.bin/docs-toolkit → …/dist/cli.js. Under pnpm v11 this fails with ENOENT (older pnpm created dangling symlinks; v11 refuses).
2. The workflow then runs pnpm --filter backend.ai-docs-toolkit run build to produce dist/cli.js.
3. The workflow re-runs pnpm install --frozen-lockfile hoping the bin link gets retried — but pnpm v11 sees node_modules as up-to-date (Already up to date) and does not retry bin linking. Even pnpm install --force is a no-op here.

The bin symlink is therefore permanently missing for the rest of the job, and docs-toolkit pdf --lang all (and every other pdf:* / preview* / build:web* / serve:web* / agents* script in backend.ai-webui-docs and backend.ai-docs-toolkit-example) fails with spawn ENOENT.

This was masked before the pnpm v11 migration (#7307, #7345) because pnpm v10 created the dangling symlink at install time and silently let it resolve once dist/cli.js appeared.

Fix

Invoke the toolkit by direct file path instead of relying on the bin symlink. After pnpm run build:toolkit (which always runs first in these scripts), packages/backend.ai-docs-toolkit/dist/cli.js is guaranteed to exist, so node ../backend.ai-docs-toolkit/dist/cli.js works regardless of the bin link state.

Updates needed in:

• packages/backend.ai-webui-docs/package.json
• packages/backend.ai-docs-toolkit-example/package.json
• .github/workflows/package.yml — drop the now-redundant "Build docs-toolkit and link CLI" step (the inaccurate comment about "link CLI" should also go).

Reproduction

rm -rf node_modules packages/*/node_modules packages/backend.ai-docs-toolkit/dist
pnpm install --frozen-lockfile        # WARN: Failed to create bin at .../docs-toolkit. ENOENT
pnpm --filter backend.ai-docs-toolkit run build
pnpm install --frozen-lockfile        # "Already up to date" — bin still missing
pnpm --filter backend.ai-webui-docs run pdf:en
# → sh: 1: docs-toolkit: not found

Verification

After the fix, the same reproducer succeeds and produces a PDF in packages/backend.ai-webui-docs/dist/.

JIRA Issue: FR-2906