Document the 2026-06 platform layer on the website#142
Merged
Conversation
The website auto-imports docs/design/ and shows the 2026-06 design docs under Internals → Design notes — but the user-facing guides sidebar didn't mention any of the new platform features. Fixing that: 8 new hand-authored Starlight guide pages + sidebar group + landing-page section + intro doc cross-link. docs/cli.md — top-level shape now lists every platform subcommand; seven new sections describe vx mcp, vx coordinator, vx run --worker, vx insights serve, vx serve (with /version /events /stream), vx dev. apps/docs/src/content/docs/guides/ (NEW pages, hand-authored Starlight content): - mcp.md — Model Context Protocol server for AI agents (Claude Code, Cursor, Continue.dev). Tool catalog, config snippets, what the agent can actually do today. - distributed-ci.md — vx coordinator + vx run --worker e2e. Two- terminal quick start, GHA matrix pattern, dispatch diagram, honest list of Phase A-B limits. - plugins.md — Plugin contract + 3 worked examples (Sentry, Slack summary, timeseries metrics). Crash-isolation rules. What plugins can NOT do today. - predictive-scheduling.md — opt-in via predictive: true. How the topo-DP works, two example graphs showing where it differs from the default, observability via vx info --history and vx mcp getRunHistory. - insights.md — vx insights serve. SPA + static cache.db server diagram, DuckDB-WASM sqlite_scanner explanation, env vars, known limits. - vx-cloud.md — Cloudflare deploy walk-through. Bindings table, HMAC signing setup, event ingest pipeline, what's deferred, cost notes (free tier sufficient for small teams). - otel-bridge.md — OpenTelemetry CI/CD spans. Backend config snippets for Grafana / Honeycomb / Datadog / Jaeger. Sample event shape with cicd.pipeline.* attributes. - wire-protocol.md — JSON-RPC 2.0 envelope. SSE curl + WS TS client examples in both legacy and envelope forms. Channels table, error codes, sample subscribers. apps/docs/astro.config.mjs — new 'Platform & extensions' sidebar group listing all 8 guides between 'Build your monorepo' and 'Migrate to vx'. apps/docs/src/pages/index.astro — new 'The open platform layer' section after 'What sets vx apart.' Six cards link to the guides: MCP, Distributed CI, Plugin API, Wire protocol, vx Cloud, Predictive scheduling. Card icons added to featIcons; CSS for .platform-card hover state in landing.css. apps/docs/src/content/docs/introduction.md — new 'The open platform layer' section after the differentiators. One-line each for the eight surfaces with cross-links to the guides. Verification: bun src/bin.ts run @vzn/vx-docs#build produces 111 HTML pages including /guides/mcp/, /guides/distributed-ci/, /guides/plugins/, /guides/predictive-scheduling/, /guides/insights/, /guides/vx-cloud/, /guides/otel-bridge/, /guides/wire-protocol/. Full CI gate: 3 success / 3 success / 3 success.
DuckDB-WASM's sqlite_scanner can't read SQLite over HTTP. ATTACH
against an http URL hits the 'unable to open database file' error
the user reported.
Fix: fetch the bytes via standard fetch(), register them as a
virtual file via db.registerFileBuffer('cache.db', bytes), then
ATTACH 'cache.db' AS cachedb (TYPE SQLITE). Same query API on top.
The default URL is unchanged ('/cache.db' from the static server
'vx insights serve' boots; or VITE_CACHE_DB_URL when overridden).
A clear UserError surfaces if the fetch fails (server not running
yet, or cache.db missing because no vx run has populated it).
Verified: SPA builds cleanly (171 modules, 200KB DuckDB chunk);
the local static server smoke-test returns 200 with real SQLite
bytes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The website's user-facing sidebar didn't mention any of the 2026-06 platform features — only the auto-imported design docs under Internals showed them. This PR adds eight hand-authored Starlight guide pages, wires them into the sidebar, surfaces them on the landing page, and updates the CLI reference.
What ships
8 new guide pages under
apps/docs/src/content/docs/guides/:mcp.mdvx mcp— MCP server for AI agents (Claude Code, Cursor, Continue.dev). Tool catalog + config snippetsdistributed-ci.mdvx coordinator+vx run --worker. Two-terminal quick start, GHA matrix pattern, dispatch diagram, honest Phase A-B limitsplugins.mdpredictive-scheduling.mdpredictive: true. How topo-DP works, two example graphs, observability viavx info --historyand MCPinsights.mdvx insights serve. SPA + static cache.db server diagram, DuckDB-WASM, known limitsvx-cloud.mdotel-bridge.mdwire-protocol.mdSidebar: new "Platform & extensions" group in
apps/docs/astro.config.mjsbetween "Build your monorepo" and "Migrate to vx".Landing page: new "The open platform layer" section after "What sets vx apart" with six clickable cards linking to the guides. Six new SVG icons. CSS for
.platform-cardhover state.Intro doc (
introduction.md): new "The open platform layer" section after the differentiators with one-line each for the eight surfaces cross-linked to the guides.docs/cli.md(the source the docs-importer pulls in): the top-level shape now lists every platform subcommand; seven new sections describevx mcp,vx coordinator,vx run --worker,vx insights serve,vx serve(with/version/events/stream),vx dev.Verification
bun src/bin.ts run @vzn/vx-docs#buildproduces 111 HTML pages including all 8 new guide URLs:/guides/mcp//guides/distributed-ci//guides/plugins//guides/predictive-scheduling//guides/insights//guides/vx-cloud//guides/otel-bridge//guides/wire-protocol/bun src/bin.ts run ci: 3 success / 3 success / 3 success.Test plan
🤖 Generated with Claude Code
https://claude.ai/code/session_01RW7aso5j5CrBo7cjyET23D
Generated by Claude Code