From bf346778c253c02bb6176885720c7b551517617f Mon Sep 17 00:00:00 2001 From: "Anthony Fu (via agent)" Date: Tue, 15 Sep 2026 05:57:46 +0000 Subject: [PATCH] docs: add devframe references and guard docs build in CI Surface Devframe/hub-origin features (rpc, shared state, json-render, diagnostics, when clauses, commands, docks) with kit-first pointers to devfra.me, keeping the Vite DevTools docs focused on the Vite path. Add a docs-build step to CI so a broken docs site fails PRs instead of letting Netlify keep serving the last good (stale) deploy. fixes #562 --- .github/workflows/ci.yml | 3 +++ .github/workflows/src/ci.yml | 5 +++++ docs/kit/commands.md | 2 +- docs/kit/diagnostics.md | 2 +- docs/kit/dock-system.md | 2 +- docs/kit/json-render.md | 2 +- docs/kit/rpc.md | 2 +- docs/kit/shared-state.md | 2 +- docs/kit/when-clauses.md | 2 +- 9 files changed, 15 insertions(+), 7 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b26e7ab1f..e420cf59c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -44,6 +44,9 @@ jobs: - name: Typecheck run: nr typecheck + - name: Docs build + run: pnpm -C docs run docs:build + - name: Knip run: nr knip continue-on-error: true diff --git a/.github/workflows/src/ci.yml b/.github/workflows/src/ci.yml index 6da4fb39a..96117f0f6 100644 --- a/.github/workflows/src/ci.yml +++ b/.github/workflows/src/ci.yml @@ -43,6 +43,11 @@ jobs: - name: Typecheck run: nr typecheck + # Fail the build when the docs site breaks, so the deployed site never + # silently goes stale (a broken build keeps the last good Netlify deploy). + - name: Docs build + run: pnpm -C docs run docs:build + # Non-blocking until the existing findings are triaged; see knip.jsonc. - name: Knip run: nr knip diff --git a/docs/kit/commands.md b/docs/kit/commands.md index 484566aec..169be7c02 100644 --- a/docs/kit/commands.md +++ b/docs/kit/commands.md @@ -4,7 +4,7 @@ outline: deep # Commands & Command Palette -DevTools Kit's commands system lets plugins register executable commands on the server and client. Users discover and run them through the built-in command palette, and rebind keyboard shortcuts to taste. +DevTools Kit's commands system lets plugins register executable commands on the server and client. Users discover and run them through the built-in command palette, and rebind keyboard shortcuts to taste. The palette is a [`@devframes/hub`](https://devfra.me/guide/hub) feature surfaced through the kit context. ## Overview diff --git a/docs/kit/diagnostics.md b/docs/kit/diagnostics.md index 5d1d66572..bec168565 100644 --- a/docs/kit/diagnostics.md +++ b/docs/kit/diagnostics.md @@ -1,6 +1,6 @@ # Structured Diagnostics -`ctx.diagnostics` is a thin layer over [`nostics`](https://github.com/vercel-labs/nostics) that lets DevTools plugins register coded errors and warnings into a shared registry without depending on `nostics` directly. Use it for author-defined coded diagnostics — errors, warnings, deprecations — that carry a stable code, a documentation URL, and a structured payload. For free-form runtime output that should appear in the DevTools UI, use [`ctx.messages`](./messages). +`ctx.diagnostics` is a thin layer over [`nostics`](https://github.com/vercel-labs/nostics) that lets DevTools plugins register coded errors and warnings into a shared registry without depending on `nostics` directly. It surfaces [Devframe's diagnostics](https://devfra.me/guide/diagnostics) through the kit context. Use it for author-defined coded diagnostics — errors, warnings, deprecations — that carry a stable code, a documentation URL, and a structured payload. For free-form runtime output that should appear in the DevTools UI, use [`ctx.messages`](./messages). | Surface | Purpose | Example | |---------|---------|---------| diff --git a/docs/kit/dock-system.md b/docs/kit/dock-system.md index e742c5d5c..6150b0c29 100644 --- a/docs/kit/dock-system.md +++ b/docs/kit/dock-system.md @@ -4,7 +4,7 @@ outline: deep # Dock System -Dock entries are how users open your DevTools integration — clickable items in the dock, similar to the macOS Dock. +Dock entries are how users open your DevTools integration — clickable items in the dock, similar to the macOS Dock. The dock is a [`@devframes/hub`](https://devfra.me/guide/hub) feature surfaced through the kit context. ## Entry types diff --git a/docs/kit/json-render.md b/docs/kit/json-render.md index 7ed863db5..289e97416 100644 --- a/docs/kit/json-render.md +++ b/docs/kit/json-render.md @@ -4,7 +4,7 @@ outline: deep # JSON Render -JSON render panels build DevTools UIs from server-side TypeScript alone. You describe the UI as a JSON spec; the DevTools client renders it with the built-in component library. +JSON render panels build DevTools UIs from server-side TypeScript alone. You describe the UI as a JSON spec; the DevTools client renders it with the built-in component library. It builds on [Devframe's JSON-Render](https://devfra.me/guide/json-render). ## Getting started diff --git a/docs/kit/rpc.md b/docs/kit/rpc.md index 3b2c6c538..c24f74520 100644 --- a/docs/kit/rpc.md +++ b/docs/kit/rpc.md @@ -4,7 +4,7 @@ outline: deep # Remote Procedure Calls (RPC) -DevTools Kit's RPC layer is type-safe, bidirectional, and works between your Node.js server and any connected browser client. +DevTools Kit's RPC layer is type-safe, bidirectional, and works between your Node.js server and any connected browser client. It surfaces [Devframe's RPC](https://devfra.me/guide/rpc) through the kit-augmented context, so these patterns carry over to any Devframe host. ## Overview diff --git a/docs/kit/shared-state.md b/docs/kit/shared-state.md index 5630ce3a3..c2c8210d7 100644 --- a/docs/kit/shared-state.md +++ b/docs/kit/shared-state.md @@ -4,7 +4,7 @@ outline: deep # Shared State -DevTools Kit's shared-state system synchronizes data between server and clients. Changes on either side propagate to every connected party. +DevTools Kit's shared-state system synchronizes data between server and clients. Changes on either side propagate to every connected party. It surfaces [Devframe's shared state](https://devfra.me/guide/shared-state) through the kit context. ## Overview diff --git a/docs/kit/when-clauses.md b/docs/kit/when-clauses.md index 94ae5f996..7a6d17dc4 100644 --- a/docs/kit/when-clauses.md +++ b/docs/kit/when-clauses.md @@ -6,7 +6,7 @@ outline: deep When clauses are conditional expressions that control visibility and activation of commands and dock entries. The expression language matches [VS Code's when-clause contexts](https://code.visualstudio.com/api/references/when-clause-contexts), evaluated against a reactive context object. -The evaluator is [`whenexpr`](https://github.com/antfu/whenexpr), which also provides the `WhenExpression` type helper used by `defineCommand` / `defineDockEntry` for compile-time validation — see [Type-safe `when` clauses](#type-safe-when-clauses). +The evaluator is [`whenexpr`](https://github.com/antfu/whenexpr), which also provides the `WhenExpression` type helper used by `defineCommand` / `defineDockEntry` for compile-time validation — see [Type-safe `when` clauses](#type-safe-when-clauses). For the framework-neutral reference, see [Devframe's when clauses](https://devfra.me/references/when-clauses). ## Usage