docs: the documentation site — vitepress + typedoc, on the entity template

[btravers]

What

The project documentation site, mirroring @btravstack/entity's arrangement: a private docs/ workspace package whose build runs TypeDoc (markdown into docs/api/di, git-ignored) and then vitepress build, published to btravstack.github.io/di/ by a deploy-docs.yml that chains off a green CI run on main.

Structure

The guide follows the four Diátaxis modes, one shared sidebar across all of them:

• Tutorial — getting-started: ports → ServiceOf → providers/modules → Module.build → a real resource → the compiler forcing Module.scoped.
• How-to — swap an adapter for tests, manage a resource's lifetime, open a per-request scope, build a plugin registry, keep a port private.
• Reference — ports, providers (the five-arm table), modules (the three channels), entry points (the arity gate, ScopedOptions, Context), wiring defects (the five checks with their exact messages), plus the TypeDoc-generated API with a hand-written overview.
• Explanation — why di?, compile errors not surprises, modules and privacy, scopes and resource safety, failures vs defects, peer dependencies.
• Examples — one page per runnable examples/* package, describing what each spec actually asserts (verified against the spec files, not paraphrased from memory).

Infrastructure ported from entity

• docs/ added to the workspace; catalog entries for vitepress/typedoc/@btravstack/theme/@btravstack/typedoc, the named typedoc catalog (TypeDoc needs the JS compiler API that the native 7.0.2 port does not ship), the vite@<6.4.3 security override, and the search-insights peer exception.
• turbo.json docs-build task with packages/di/src as an input; knip entries for the two configs it cannot trace; .gitignore entries for the VitePress cache and generated API pages.
• Theme: shared @btravstack/theme with di's accent set to the logo's blue (#2a62b8).
• typedoc.json suppresses warnings only for the 17 deliberately-internal type names.
• OG social card: docs/public/og-di.png, 1280×640 on the family template (dark canvas, name in the package accent, tagline, URL, the syringe artwork), wired into the OG/Twitter meta tags with summary_large_image.

Verification

• pnpm --filter ./docs exec turbo build — TypeDoc zero warnings, VitePress build + sitemap clean.
• Full gate green: format, lint, typecheck, test, knip, build.
• No changeset: docs and tooling only, no API or behaviour impact.

[Copilot]

Pull request overview

This PR adds a full documentation website for @btravstack/di, implemented as a private docs/ workspace package that generates API markdown via TypeDoc and publishes a VitePress site to GitHub Pages.

Changes:

• Introduces a new docs/ workspace package (@btravstack/di-docs) with TypeDoc → VitePress build scripts and a VitePress site config/theme.
• Adds a structured Diátaxis-style documentation set (tutorial/how-to/reference/explanation) plus curated pages for the runnable examples and an API overview.
• Wires docs build caching into Turbo and adds a GitHub Actions workflow to deploy the site after CI succeeds on main.

Reviewed changes

Copilot reviewed 32 out of 34 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
turbo.json	Adds a cached Turbo build task for the docs package, including packages/di/src/** as an input and VitePress/TypeDoc outputs.
pnpm-workspace.yaml	Adds the docs workspace and catalogs/overrides needed for VitePress + TypeDoc.
knip.jsonc	Ignores docs-related config dependencies knip can’t trace.
docs/package.json	Introduces the private docs package and its typedoc && vitepress scripts.
docs/typedoc.json	Configures TypeDoc generation of markdown API docs into docs/api/di.
docs/index.md	Adds the VitePress homepage content and “at a glance” example.
docs/tutorial/getting-started.md	Adds the end-to-end tutorial showing ports → providers/modules → build vs scoped.
docs/how-to/swap-an-adapter.md	Adds a how-to guide for composing an app module against different adapters.
docs/how-to/request-scope.md	Adds a how-to guide for per-request scope via Module.forkScope.
docs/how-to/private-ports.md	Adds a how-to guide explaining export-based privacy boundaries.
docs/how-to/plugin-registry.md	Adds a how-to guide for set ports and Provider.member registries.
docs/how-to/manage-a-resource.md	Adds a how-to guide for acquire/release and lifecycle hooks.
docs/reference/ports.md	Adds reference documentation for ports, set ports, ServiceOf, and type-only Scope.
docs/reference/providers.md	Adds reference documentation for provider arms, hooks, and channels.
docs/reference/modules.md	Adds reference documentation for module composition and phantom channels/variance.
docs/reference/entry-points.md	Adds reference documentation for build/scoped/forkScope, gating, and Context.
docs/reference/wiring-defects.md	Adds reference documentation for pre-construction defect checks and messages.
docs/explanation/why-di.md	Adds explanation of the overall design goals and what the library refuses to do.
docs/explanation/compile-time-wiring.md	Adds explanation of Needs propagation and the UNSATISFIED DEPENDENCIES gate.
docs/explanation/modules-and-privacy.md	Adds explanation of the runtime flat map and type-level privacy.
docs/explanation/scopes-and-resources.md	Adds explanation of phantom Scope and scope guarantees.
docs/explanation/failures-vs-defects.md	Adds explanation of unthrown failure vs defect channel separation.
docs/explanation/peer-dependencies.md	Adds explanation of why unthrown must be a peer dependency.
docs/examples/index.md	Adds an examples overview page tying examples to guide concepts.
docs/examples/hexagonal-order-api.md	Adds example write-up for the hexagonal slice package.
docs/examples/request-scope.md	Adds example write-up for the request-scope package.
docs/examples/plugin-registry.md	Adds example write-up for the plugin-registry package.
docs/api/index.md	Adds a hand-written API overview entry page for the generated TypeDoc section.
docs/.vitepress/config.ts	Adds VitePress site configuration (base path, sidebar/nav, canonical/OG meta, SSR bundling for theme).
docs/.vitepress/theme/index.ts	Wires the shared @btravstack/theme into the docs site.
docs/.vitepress/theme/custom.css	Sets the site accent and hero styling tokens for the package.
.gitignore	Ignores VitePress cache, generated TypeDoc pages, and local design scratch directory.
.github/workflows/deploy-docs.yml	Adds a Pages deployment workflow chained off successful CI on main.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.