feat(FR-2084): extract docs-toolkit as reusable package

[yomybaby]

Resolves #5395 (FR-2084)

Summary

Extract the Backend.AI WebUI docs markdown → PDF/HTML engine as a standalone, reusable backend.ai-docs-toolkit package.

New Package: backend.ai-docs-toolkit

• 18 source files: Config-driven engine with all hardcoded Backend.AI references replaced by DocConfig injection
• CLI commands: pdf, preview, preview:html, init, agents
• 6 Handlebars templates: Agent file generation system for Claude Code
• Public API: Programmatic access to all engine functions

Migrated: backend.ai-webui-docs

• Consumes toolkit as workspace:* dependency
• docs-toolkit.config.yaml with Backend.AI-specific settings
• Scripts replaced with toolkit CLI calls
• Engine files removed (now in toolkit package)

Documentation

• Added README.md for both packages
• Added .gitignore for both packages
• Updated webui-docs README to reflect toolkit architecture

Test plan

• Toolkit builds cleanly (pnpm run build)
• docs-toolkit help shows usage
• docs-toolkit agents generates agent files from templates
• docs-toolkit pdf --lang en generates PDF successfully

[yomybaby]

• docs(FR-2075): standardize admonition types and fix formatting across documentation #5404 : 2 dependent PRs (#5423 , #5450 )
• docs(FR-2074): improve PDF documentation layout and structure #5403
• feat(FR-2084): extract docs-toolkit as reusable package #5397 👈 (View in Graphite)
• main

---

How to use the Graphite Merge Queue

Add either label to this PR to merge it via the merge queue:

• flow:merge-queue - adds this PR to the back of the merge queue
• flow:hotfix - for urgent hot fixes, skip the queue and merge this PR next

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has required the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[Copilot]

Pull request overview

This PR extracts the Backend.AI WebUI documentation engine into a standalone, reusable backend.ai-docs-toolkit npm package. The toolkit provides CLI commands, a config-driven architecture, and Handlebars-based agent templates for Claude Code integration.

Changes:

• Created new backend.ai-docs-toolkit package with 18 source files, CLI interface, config system, and public API
• Migrated backend.ai-webui-docs to consume the toolkit as a workspace dependency with Backend.AI-specific configuration
• Extracted all hardcoded references into configurable docs-toolkit.config.yaml settings

Reviewed changes

Copilot reviewed 33 out of 41 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
pnpm-workspace.yaml	Added backend.ai-docs-toolkit to workspace packages
pnpm-lock.yaml	Updated dependencies for both packages, toolkit now has core dependencies
packages/backend.ai-docs-toolkit/package.json	New package with CLI bin, exports, dependencies, and peer dependencies
packages/backend.ai-docs-toolkit/tsconfig.json	TypeScript config with rootDir changed to src/, declaration enabled
packages/backend.ai-docs-toolkit/src/cli.ts	New CLI with pdf, preview, preview:html, init, agents commands
packages/backend.ai-docs-toolkit/src/config.ts	Config system with DocConfig interface, defaults, and YAML loader
packages/backend.ai-docs-toolkit/src/index.ts	Public API exports for programmatic usage
packages/backend.ai-docs-toolkit/src/*.ts	Core engine files migrated from scripts/ with config injection
packages/backend.ai-docs-toolkit/templates/*.hbs	Handlebars templates for agent generation and config scaffolding
packages/backend.ai-docs-toolkit/README.md	Comprehensive toolkit documentation
packages/backend.ai-webui-docs/package.json	Scripts replaced with toolkit CLI calls, engine dependencies removed
packages/backend.ai-webui-docs/docs-toolkit.config.yaml	Backend.AI-specific configuration for the toolkit
packages/backend.ai-webui-docs/.claude/agents/*.md	Generated Claude Code agent files from toolkit templates
packages/backend.ai-webui-docs/README.md	Updated to reflect toolkit architecture and usage
packages/backend.ai-webui-docs/scripts/version.ts	Removed (moved to toolkit)

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

Comments suppressed due to low confidence (4)

packages/backend.ai-docs-toolkit/tsconfig.json:10

• The rootDir configuration changed from "./scripts" to "./src", but there's no verification that all files previously in scripts/ have been properly moved to src/. While the diff shows many new files in src/, this is a critical change that could break the build if any file was missed.

Consider adding a comment or build validation to ensure no orphaned TypeScript files remain in the old scripts directory.
packages/backend.ai-docs-toolkit/src/preview-server.ts:320

• Similar cross-platform path issue: new URL(import.meta.url).pathname won't work correctly on Windows. The pathname will have an incorrect format like /C:/path/to/file instead of C:\path\to\file.

Replace with fileURLToPath from the 'url' module to ensure cross-platform compatibility.
packages/backend.ai-docs-toolkit/src/preview-server-web.ts:113

• Cross-platform path issue: new URL(import.meta.url).pathname won't work on Windows systems. This will break file watching functionality on Windows.

Use fileURLToPath(import.meta.url) from the 'url' module for proper cross-platform path conversion.
packages/backend.ai-docs-toolkit/src/generate-pdf.ts:50

• The template filename formatting replaces spaces with underscores but doesn't handle other potentially problematic characters in filenames. For example, if the title contains characters like /, \, :, *, ?, ", <, >, |, these could cause filesystem errors or security issues.

Consider using a more robust sanitization approach that removes or replaces all invalid filename characters, not just spaces.

[ironAiken2]

LGTM

[ironAiken2]

LGTM