feat(server): migrate control plane to Nitro v3 with ViteHub

.agents/skills/vitehub

@@ -0,0 +1 @@
+../../.skills/vitehub

.gitignore

@@ -3,6 +3,7 @@ node_modules/
 dist/
 .output/
 .nuxt/
+.vitehub/
 *.tsbuildinfo
 coverage/
 playwright-report/

.skills/orpc-server/SKILL.md

@@ -11,16 +11,20 @@ description: Use when changing apps/server procedures, oRPC contracts, handlers,
 
 - Keep procedure contracts and router composition in `apps/server/src/rpc.ts`, and the runtime
  operations they delegate to in `apps/server/src/router.ts`.
-- Keep Node HTTP startup in `apps/server/src/index.ts` and request routing in
- `apps/server/src/http.ts`.
+- The HTTP host is Nitro v3 registered as a Vite plugin next to ViteHub (`vite.config.ts`,
+ `nitro.config.ts`). HTTP routes live in `apps/server/server/` (`routes/rpc/[...].ts` mounts the
+ oRPC fetch handler; `api/dashboard.get.ts` serves the aggregate view); `src/` stays
+ transport-neutral.
 - Infer client types from the router; do not duplicate request or response interfaces.
 - Validate inputs at the procedure boundary and return stable domain-shaped results.
 - Procedures call the agent runtime through typed APIs. They do not execute shell commands or
  mutate checkouts directly.
-- Persist through the `KeyValueStorage` contract so Redis, KV, and Nitro drivers stay
- interchangeable; never store review input or checkout paths.
+- Persist through the `KeyValueStorage` contract, adapted over the ViteHub KV Runtime Helper in
+ `apps/server/server/utils/store.ts`, so KV drivers stay interchangeable; never store review
+ input or checkout paths.
 - Keep transport-specific headers, status mapping, and request objects out of runtime packages.
-- Do not introduce Hono, Nitro, or a second HTTP framework.
+- Nitro v3 plus ViteHub is the only HTTP host; do not introduce Hono, Express, or a second HTTP
+ framework.
 
 ## Workflow
 

.skills/vitehub/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: vitehub
+description: Build and debug complete ViteHub apps from live docs and installed contracts. Use for server primitives and Runtime Helpers; Agent Definitions, Drivers, Capabilities, Workspaces, Sources, Channels, Triggers, or orchestration; Vite/Nuxt integration, Provider Output, previews, hosts, and deployment.
+---
+
+# ViteHub
+
+Use one proof loop: orient, route, inspect the contract, build, and prove. Exact package exports, installed types, and current raw docs outrank remembered or project-example syntax.
+
+## 1. Orient
+
+- Inspect the package manifest, lockfile, Vite or Nuxt config, server entry, and nearby project instructions.
+- Identify installed ViteHub packages and versions, package manager, framework, host target, and requested outcome.
+- Open `https://vitehub.dev/llms.txt`, then select the smallest raw Markdown page covering the primary behavior. Links inside references are selection menus; do not open every linked page.
+
+Orientation is complete when the current setup, target outcome, host boundary, and first docs URL are named.
+
+## 2. Route before code
+
+Choose one primary lane. Server Primitives serve application behavior through Vite Integrations and Runtime Helpers. Agents serve model-backed, harness-backed, or custom-run behavior through Agent Definitions; they may compose Server Primitives without changing the primary lane.
+
+Read only the references whose conditions match, but read them before writing code:
+
+| Task condition | Required reference |
+| ------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
+| New project, uncertain file layout, or cross-feature composition | [Project shapes](references/project-shapes.md) |
+| Released or `pkg.pr.new` installation, upgrade, or package mismatch | [Installed and preview contracts](references/preview-contract.md) |
+| KV, Blob, Database, Env, Email, Queue, Rate Limit, Sandbox, Shell, or another Server Primitive | [Server Primitives](references/server-primitives.md) |
+| Modify an existing framework integration; add Nitro or Nuxt; use generated types; configure a provider; or diagnose a framework-specific failure | [Framework composition](references/framework-composition.md) |
+| Agent Definition, Agent Driver, Agent Invocation, instructions, output, hooks, or Evals | [Agent Definitions and Drivers](references/agent-definitions.md) |
+| Workspace, Source, access scope, mounted files, or write-back | [Workspaces, Sources, and access](references/workspaces-sources-access.md) |
+| Channel, Trigger, webhook, messages, admission, concurrency, or delivery | [Channels and Triggers](references/channels-triggers.md) |
+| Capability, tool, secret, rate limit, telemetry, or other granted authority | [Capabilities and authority](references/capabilities-authority.md) |
+| Schedule, Workflow, orchestration retry, idempotency, or terminal state | [Schedules, Workflows, and Invocations](references/schedules-workflows-invocations.md) |
+| Box, trusted host, isolation, required command, or deployment target | [Boxes and hosts](references/boxes-hosts.md) |
+| A proof has failed, generated state disagrees, or a runtime/host failure needs diagnosis | [Proof and recovery](references/proof-recovery.md) |
+| Looking for a complete public application pattern | [Project patterns](references/project-patterns.md) |
+| Existing `@vitehub/*`, `@vite-hub/vite`, or individual `hubX()` composition | [Migration quarantine](references/migration.md) |
+
+Routing is complete when every requested behavior has one primary lane and every matching reference has been read. Do not load the whole library.
+
+## 3. Inspect the installed contract
+
+- Read each installed package's `package.json`, exports, relevant types, and generated declarations before writing imports or options.
+- For a fresh application, install `vite-hub` and use its root integration plus feature subpaths. Use direct owner packages only for a focused library, an unexported advanced subpath, or an installed older contract.
+- When docs, examples, and installed artifacts disagree, implement the installed artifacts and record the mismatch. Treat project examples as patterns whose imports must be revalidated.
+
+Contract inspection is complete when every planned package, import, option, generated path, and runtime entry exists in the installed graph; no syntax is inferred only from memory.
+
+## 4. Build the coherent file set
+
+Before editing, map every requested behavior to:
+
+| Behavior | Package owner | Source file | Runtime path | Authority or persistence | Proof |
+| -------- | ------------- | ----------- | ------------ | ------------------------ | ----- |
+
+Then implement the smallest coherent set: manifest and lockfile, framework integration, discovered Definition where needed, application or orchestration entrypoint, and proof surface. Keep application authority in application code; grant an Agent access only through visible Capabilities, Workspace rules, Sources, Channels, or Box configuration.
+
+Building is complete when every requested behavior has an implemented row and no placeholder, unused integration, implicit authority, or unowned persistence remains.
+
+## 5. Prove and repair
+
+- Run the narrow typecheck or package test nearest the change, then the relevant build.
+- Prove the actual lane: execute the Runtime Helper, perform an Agent Invocation, exercise the webhook or schedule, or inspect generated Provider Output.
+- On failure, return to installed exports/types, `.vitehub` generated state, the selected raw docs page, and [Proof and recovery](references/proof-recovery.md). Repair the cause and rerun the same proof.
+
+The task is complete when every behavior row has an observed result, or a precise source-backed unsupported boundary. Report commands and observations, docs URLs, installed ViteHub versions or preview commit, contract mismatches, and host limitations.

.skills/vitehub/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+ display_name: 'ViteHub'
+ short_description: 'Build complete ViteHub projects'
+ default_prompt: 'Use $vitehub to route the smallest relevant reference set, follow live docs and the installed contract, and prove every requested behavior.'

.skills/vitehub/references/agent-definitions.md

@@ -0,0 +1,33 @@
+# Agent Definitions and Drivers
+
+Use this for Agent Definitions, model or harness Drivers, deterministic custom Drivers, instructions, structured output, hooks, or Evals.
+
+## Select current pages
+
+For a first deterministic custom Driver and direct invocation, open only [First Agent](https://vitehub.dev/raw/docs/getting-started/first-agent.md). Use [Agent Definitions](https://vitehub.dev/raw/docs/agents/agent-definitions.md) for advanced composition or discovery, [Agent Drivers](https://vitehub.dev/raw/docs/agents/agent-drivers.md) for model/harness details, and [Agent Invocations](https://vitehub.dev/raw/docs/agents/invocations.md) for advanced runtime context. Open [Instructions](https://vitehub.dev/raw/docs/agents/instructions.md) or [Evals](https://vitehub.dev/raw/docs/agents/evals.md) only when that behavior is requested. Do not read the whole set.
+
+## Definition shape
+
+Default-export one `defineAgent()` boundary from `server/agents/<name>.ts` or `server/agents/<name>/agent.ts`. Compose only the facets the outcome needs:
+
+```text
+driver how the Agent runs
+instructions model-facing behavior
+workspace files and Sources available to the invocation
+capabilities granted tools and authority
+channels external conversation adapters
+box execution environment and requirements
+hooks/output lifecycle and delivery behavior
+```
+
+Use a deterministic custom `driver.run` for the first offline proof. Add model or harness packages, credentials, executable prerequisites, and sandbox requirements only when the requested outcome needs them.
+
+Keep repository-wide guidance in repository files, Agent behavior in Driver Instructions, and reusable runtime Skills in the documented Agent skill surface.
+
+## Invocation boundary
+
+Pass invocation input separately from trusted runtime context. Keep run identity, memoization, wait-until behavior, actor/admission context, and runtime selection explicit where the chosen invocation helper requires them.
+
+## Proof
+
+Prove Driver prerequisites, run one real Agent Invocation, inspect granted authority, and assert the expected output. A typecheck without an invocation is incomplete.

.skills/vitehub/references/boxes-hosts.md

@@ -0,0 +1,17 @@
+# Boxes and hosts
+
+Use this for trusted-host commands, isolated execution, credentials projected into Home, required binaries, deployment targets, or Provider Output.
+
+## Select current pages
+
+Open [Boxes](https://vitehub.dev/raw/docs/agents/boxes.md) for execution environments, the selected page under [Frameworks and hosts](https://vitehub.dev/raw/docs/frameworks-hosts.md) for a deployment target, or [Provider Output](https://vitehub.dev/raw/docs/reference/provider-output.md) for artifact ownership. Open only the pages matching the task.
+
+## State the runtime boundary
+
+Name the Box provider or trusted host, isolation guarantee, persistence lifetime, network policy, required commands, projected credentials, cost, and production-readiness. A local tempdir or host process is convenience, not isolation.
+
+Keep host-specific setup behind the Box or provider boundary. Agent Instructions may explain available commands, but configuration must make the commands and credentials actually available.
+
+## Proof
+
+Inspect the resolved Box requirements, execute one required command, prove credential access without exposing the credential, and confirm cleanup or persistence. For deployment, build and inspect the documented Provider Output before a live target check.

.skills/vitehub/references/capabilities-authority.md

@@ -0,0 +1,27 @@
+# Capabilities and authority
+
+Use this whenever an Agent receives a tool, secret-backed operation, browser, storage, shell, repository, rate-limit, telemetry, or custom action.
+
+## Select current pages
+
+Open [Official Capabilities](https://vitehub.dev/raw/docs/capabilities/official-capabilities.md) plus the chosen Capability page. Use [Capabilities API](https://vitehub.dev/raw/docs/concepts/capabilities-api.md) for lifecycle or authority questions, and [Custom Capabilities](https://vitehub.dev/raw/docs/capabilities/custom-capabilities.md) only when no official Capability fits.
+
+## Authority pass
+
+Every Capability changes what an Agent may observe or do. For each one, name:
+
+- operations exposed to the model;
+- data and secret sources;
+- actor, scope, rate, and policy checks;
+- persistence or external side effects;
+- artifacts or traces available for inspection.
+
+Use official factories before writing a custom Capability. Use `defineCapability()` when the application needs a stable domain-specific boundary, not as a wrapper around an already suitable official tool.
+
+Keep secrets server-side and unseal them only at the documented execution boundary. A Workspace Source does not grant an operation; a Capability should not silently mount unrelated data.
+
+For `rateLimit()`, pass a direct `RateLimiter` with `limiter`. Keep Agent Invoker, Run, or trusted-IP identity in the Capability; keep atomic consumption and provider guarantees in `@vite-hub/rate-limit`. Do not recreate the removed inline `limit`, `window`, `store`, or generic KV model.
+
+## Proof
+
+Run one allowed operation and one relevant denied or out-of-scope case. Inspect the tool surface, result, trace/artifact, and external effect.

.skills/vitehub/references/channels-triggers.md

@@ -0,0 +1,23 @@
+# Channels and Triggers
+
+Use this for GitHub, Teams, Telegram, Discord, web chat, custom webhooks, message history, admission, concurrency, or delivery effects.
+
+## Select one current page
+
+Open [Channels](https://vitehub.dev/raw/docs/agents/channels.md) for conversation adapters, [Triggers](https://vitehub.dev/raw/docs/agents/triggers.md) for other inbound events, or [Chat history and sessions](https://vitehub.dev/raw/docs/agents/chat-history-sessions.md) for identity and persistence. Open another page only when the first explicitly crosses that boundary.
+
+## Composition
+
+A Channel adapts an external conversation surface; a Trigger admits an external event into an Agent Invocation. Keep webhook verification, actor/admission rules, history/session identity, concurrency, input commands, and delivery behavior explicit.
+
+Use official Channel helpers when the installed contract provides them. Create a custom Trigger only when the external event is not a conversation adapter or the official boundary cannot represent the source.
+
+Treat webhook secrets and installation tokens as server-only Env. Keep generated routes inspectable and document the exact local or deployed URL used for proof.
+
+For initial setup of a built-in Telegram Channel, discover the installed contract with `pnpm vitehub channels sync --help` after the application stage is deployed. Run `pnpm vitehub channels sync --stage <stage> --url <https-origin> --json` first; it is read-only, loads the stage-specific Vite environment, and verifies the deployed webhook route before inspecting Telegram.
+
+Apply a reviewed registration only when the task explicitly authorizes provider mutation, using `--apply --confirm-origin <the-same-https-origin>`. Never infer the stage or origin, pass provider credentials as arguments, or expose Env values in output. A planned deletion also needs explicit intent and `--allow-delete`; switching Telegram to polling or `webhooks: false` can produce that plan. Keep custom adapter registration and product policy application-owned.
+
+## Proof
+
+Exercise the generated or custom webhook with a verified event, observe the Agent Invocation, and confirm the expected external delivery or persisted message. A route existing in Provider Output is not proof that admission and delivery work.

.skills/vitehub/references/framework-composition.md

@@ -0,0 +1,29 @@
+# Framework composition
+
+Use this for Vite, Nitro, Nuxt, integration ordering, generated types, or deployment configuration.
+
+## Select one current page
+
+Start with [Vite Integrations and Provider Output](https://vitehub.dev/raw/docs/concepts/vite-integrations-and-provider-output.md). Open [Config options](https://vitehub.dev/raw/docs/reference/config-options.md) only for an option mismatch, or the selected page under [Frameworks and hosts](https://vitehub.dev/raw/docs/frameworks-hosts.md) only for a named framework or deployment target.
+
+## Current application contract
+
+Fresh apps install `vite-hub`, register `vitehub()` from the root, and use feature subpaths for runtime APIs. Direct `hubX()` integrations belong to an installed owner-package contract or deliberate advanced composition.
+
+For Vite plus Nitro, keep ordering explicit:
+
+```text
+client/framework plugins
+vitehub(...)
+nitro(...)
+```
+
+For Nuxt, use documented modules or the Vite extension point supported by the installed packages. Do not reproduce app-local aliases or output rewrites from project examples without a source-backed need.
+
+## Generated state
+
+Include `.vitehub/types/**/*.d.ts` when generated names or `#vitehub/*` imports require it. Inspect `.vitehub` during development, but author source Definitions and stable imports rather than generated files.
+
+## Proof
+
+Run prepare/typecheck, build the selected framework, inspect `.vitehub`, and inspect the target's Provider Output. Ordering is proven by generated bindings and a live Runtime Helper or Agent Invocation, not by config shape alone.