selftune 0.2.23 → 0.2.24

package/cli/selftune/workflows/workflows.ts

@@ -8,13 +8,14 @@
  *  - cliMain()          (reads logs, discovers workflows, prints output or saves)
  */
 
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { parseArgs } from "node:util";
 
 import { getDb } from "../localdb/db.js";
 import { querySessionTelemetry, querySkillUsageRecords } from "../localdb/queries.js";
 import type {
   CodifiedWorkflow,
+  DiscoveredWorkflow,
   SessionTelemetryRecord,
   SkillUsageRecord,
   WorkflowDiscoveryReport,
@@ -22,6 +23,38 @@ import type {
 import { CLIError } from "../utils/cli-error.js";
 import { discoverWorkflows } from "./discover.js";
 import { appendWorkflow } from "./skill-md-writer.js";
+import { buildWorkflowSkillDraft, formatWorkflowSkillDraft } from "./skill-scaffold.js";
+
+function resolveWorkflowSelection(
+  report: WorkflowDiscoveryReport,
+  selection: string | undefined,
+): DiscoveredWorkflow {
+  if (!selection) {
+    throw new CLIError(
+      "Usage: selftune workflows <save|scaffold> <name-or-index>",
+      "MISSING_FLAG",
+      "Provide a workflow name or index (e.g., selftune workflows scaffold 1).",
+    );
+  }
+
+  let workflow = report.workflows.find((w) => w.workflow_id === selection);
+  if (!workflow) {
+    const idx = Number.parseInt(selection, 10);
+    if (!Number.isNaN(idx) && idx >= 1 && idx <= report.workflows.length) {
+      workflow = report.workflows[idx - 1];
+    }
+  }
+
+  if (!workflow) {
+    throw new CLIError(
+      `No workflow found matching "${selection}".`,
+      "INVALID_FLAG",
+      "Run 'selftune workflows' to see discovered workflows and their indices.",
+    );
+  }
+
+  return workflow;
+}
 
 // ---------------------------------------------------------------------------
 // formatWorkflows — pure formatter
@@ -69,12 +102,41 @@ export async function cliMain(): Promise<void> {
       window: { type: "string" },
       skill: { type: "string" },
       "skill-path": { type: "string" },
+      "output-dir": { type: "string" },
+      "skill-name": { type: "string" },
+      description: { type: "string" },
+      write: { type: "boolean" },
+      force: { type: "boolean" },
       json: { type: "boolean" },
+      help: { type: "boolean", short: "h" },
     },
     strict: true,
     allowPositionals: true,
   });
 
+  if (values.help) {
+    console.log(`selftune workflows — Discover repeated multi-skill patterns
+
+Usage:
+  selftune workflows [options]
+  selftune workflows save <name-or-index> [--skill-path <path>]
+  selftune workflows scaffold <name-or-index> [--output-dir <path>] [--skill-name <name>] [--description <text>] [--write] [--force] [--json]
+
+Options:
+  --min-occurrences <n>  Minimum workflow frequency to show (default: 3)
+  --window <n>           Only analyze the most recent N sessions
+  --skill <name>         Only show workflows containing the named skill
+  --skill-path <path>    Target SKILL.md for the save subcommand
+  --output-dir <path>    Target skill registry dir for scaffold previews/writes
+  --skill-name <name>    Override the generated draft skill name
+  --description <text>   Override the generated draft skill description
+  --write                Persist the scaffolded draft skill to disk
+  --force                Overwrite an existing scaffold path when combined with --write
+  --json                 Emit machine-readable JSON
+  -h, --help             Show this help message`);
+    process.exit(0);
+  }
+
   const subcommand = positionals[0];
   const minOccurrences = values["min-occurrences"]
     ? Number.parseInt(values["min-occurrences"], 10)
@@ -101,31 +163,7 @@ export async function cliMain(): Promise<void> {
 
   if (subcommand === "save") {
     // Save subcommand: find workflow, append to SKILL.md
-    const nameArg = positionals[1];
-    if (!nameArg) {
-      throw new CLIError(
-        "Usage: selftune workflows save <name-or-index>",
-        "MISSING_FLAG",
-        "Provide a workflow name or index (e.g., selftune workflows save 1).",
-      );
-    }
-
-    // Match by numeric index (1-based) or workflow_id
-    let workflow = report.workflows.find((w) => w.workflow_id === nameArg);
-    if (!workflow) {
-      const idx = Number.parseInt(nameArg, 10);
-      if (!Number.isNaN(idx) && idx >= 1 && idx <= report.workflows.length) {
-        workflow = report.workflows[idx - 1];
-      }
-    }
-
-    if (!workflow) {
-      throw new CLIError(
-        `No workflow found matching "${nameArg}".`,
-        "INVALID_FLAG",
-        "Run 'selftune workflows' to see discovered workflows and their indices.",
-      );
-    }
+    const workflow = resolveWorkflowSelection(report, positionals[1]);
 
     // Determine SKILL.md path
     let skillPath = values["skill-path"];
@@ -187,6 +225,42 @@ export async function cliMain(): Promise<void> {
     return;
   }
 
+  if (subcommand === "scaffold") {
+    const workflow = resolveWorkflowSelection(report, positionals[1]);
+    const draft = buildWorkflowSkillDraft(workflow, {
+      outputDir: values["output-dir"],
+      skillName: values["skill-name"],
+      description: values.description,
+    });
+
+    if (values.write) {
+      if (existsSync(draft.skill_path) && !values.force) {
+        throw new CLIError(
+          `Refusing to overwrite existing draft at ${draft.skill_path}.`,
+          "FILE_EXISTS",
+          "Re-run with --force to overwrite the existing draft skill.",
+        );
+      }
+
+      mkdirSync(draft.skill_dir, { recursive: true });
+      writeFileSync(draft.skill_path, draft.content, "utf-8");
+
+      if (values.json || !process.stdout.isTTY) {
+        console.log(JSON.stringify({ ...draft, written: true }, null, 2));
+      } else {
+        console.log(`Scaffolded skill "${draft.skill_name}" to ${draft.skill_path}`);
+      }
+      return;
+    }
+
+    if (values.json || !process.stdout.isTTY) {
+      console.log(JSON.stringify({ ...draft, written: false }, null, 2));
+    } else {
+      console.log(formatWorkflowSkillDraft(draft));
+    }
+    return;
+  }
+
   // Default: discover and display
   if (values.json || !process.stdout.isTTY) {
     console.log(JSON.stringify(report, null, 2));

package/node_modules/@selftune/telemetry-contract/fixtures/complete-push.ts

@@ -1,4 +1,4 @@
-import type { PushPayloadV2 } from "../src/schemas.js";
+import type { PushPayloadV2 } from "../src/types.js";
 
 /**
  * A valid PushPayloadV2 with at least one of every record type.

package/node_modules/@selftune/telemetry-contract/fixtures/evidence-only-push.ts

@@ -1,4 +1,4 @@
-import type { PushPayloadV2 } from "../src/schemas.js";
+import type { PushPayloadV2 } from "../src/types.js";
 
 /**
  * A valid PushPayloadV2 with only evolution_evidence entries and

package/node_modules/@selftune/telemetry-contract/fixtures/partial-push-no-sessions.ts

@@ -1,4 +1,4 @@
-import type { PushPayloadV2 } from "../src/schemas.js";
+import type { PushPayloadV2 } from "../src/types.js";
 
 /**
  * A valid PushPayloadV2 with zero sessions but non-empty evolution_evidence.

package/node_modules/@selftune/telemetry-contract/fixtures/partial-push-unresolved-parents.ts

@@ -1,4 +1,4 @@
-import type { PushPayloadV2 } from "../src/schemas.js";
+import type { PushPayloadV2 } from "../src/types.js";
 
 /**
  * A valid PushPayloadV2 with invocations and prompts that reference a

package/node_modules/@selftune/telemetry-contract/src/schemas.ts

@@ -140,10 +140,13 @@ export const CanonicalEvolutionEvidenceRecordSchema = z.object({
   evidence_id: z.string().min(1),
   skill_name: z.string().min(1),
   proposal_id: z.string().optional(),
+  timestamp: z.string().datetime().optional(),
+  skill_path: z.string().optional(),
   target: z.string().min(1),
   stage: z.string().min(1),
   rationale: z.string().optional(),
   confidence: z.number().min(0).max(1).optional(),
+  details: z.string().optional(),
   original_text: z.string().optional(),
   proposed_text: z.string().optional(),
   eval_set_json: z.unknown().optional(),
@@ -151,6 +154,37 @@ export const CanonicalEvolutionEvidenceRecordSchema = z.object({
   raw_source_ref: rawSourceRefSchema.optional(),
 });
 
+export const CanonicalGradingResultRecordSchema = z.object({
+  grading_id: z.string().min(1),
+  session_id: z.string().min(1),
+  skill_name: z.string().min(1),
+  transcript_path: z.string().nullable().optional(),
+  graded_at: z.string().min(1),
+  pass_rate: z.number().min(0).max(1).nullable().optional(),
+  mean_score: z.number().min(0).max(1).nullable().optional(),
+  score_std_dev: z.number().nullable().optional(),
+  passed_count: z.number().int().nonnegative().nullable().optional(),
+  failed_count: z.number().int().nonnegative().nullable().optional(),
+  total_count: z.number().int().nonnegative().nullable().optional(),
+  expectations_json: z.string().nullable().optional(),
+  claims_json: z.string().nullable().optional(),
+  eval_feedback_json: z.string().nullable().optional(),
+  failure_feedback_json: z.string().nullable().optional(),
+  execution_metrics_json: z.string().nullable().optional(),
+});
+
+export const CanonicalImprovementSignalRecordSchema = z.object({
+  signal_id: z.string().min(1),
+  timestamp: z.string().min(1),
+  session_id: z.string().min(1),
+  query: z.string().min(1),
+  signal_type: z.string().min(1),
+  mentioned_skill: z.string().nullable().optional(),
+  consumed: z.boolean(),
+  consumed_at: z.string().nullable().optional(),
+  consumed_by_run: z.string().nullable().optional(),
+});
+
 // ---------- Orchestrate run schemas ----------
 
 export const OrchestrateRunSkillActionSchema = z.object({
@@ -194,12 +228,14 @@ export const PushPayloadV2Schema = z.object({
     normalization_runs: z.array(CanonicalNormalizationRunRecordSchema).min(0),
     evolution_evidence: z.array(CanonicalEvolutionEvidenceRecordSchema).optional(),
     orchestrate_runs: z.array(PushOrchestrateRunRecordSchema).optional(),
+    grading_results: z.array(CanonicalGradingResultRecordSchema).optional(),
+    improvement_signals: z.array(CanonicalImprovementSignalRecordSchema).optional(),
   }),
 });
 
 // ---------- Inferred types from Zod schemas ----------
 
-export type PushPayloadV2 = z.infer<typeof PushPayloadV2Schema>;
+export type ZodPushPayloadV2 = z.infer<typeof PushPayloadV2Schema>;
 export type ZodCanonicalSessionRecord = z.infer<typeof CanonicalSessionRecordSchema>;
 export type ZodCanonicalPromptRecord = z.infer<typeof CanonicalPromptRecordSchema>;
 export type ZodCanonicalSkillInvocationRecord = z.infer<
@@ -212,4 +248,8 @@ export type ZodCanonicalNormalizationRunRecord = z.infer<
 export type ZodCanonicalEvolutionEvidenceRecord = z.infer<
   typeof CanonicalEvolutionEvidenceRecordSchema
 >;
+export type ZodCanonicalGradingResultRecord = z.infer<typeof CanonicalGradingResultRecordSchema>;
+export type ZodCanonicalImprovementSignalRecord = z.infer<
+  typeof CanonicalImprovementSignalRecordSchema
+>;
 export type ZodPushOrchestrateRunRecord = z.infer<typeof PushOrchestrateRunRecordSchema>;

package/node_modules/@selftune/telemetry-contract/src/types.ts

@@ -54,7 +54,7 @@ export const CANONICAL_RECORD_KINDS = [
 ] as const;
 export type CanonicalRecordKind = (typeof CANONICAL_RECORD_KINDS)[number];
 
-export interface CanonicalRawSourceRef {
+export interface CanonicalRawSourceRef extends Record<string, unknown> {
   path?: string;
   line?: number;
   event_type?: string;
@@ -62,7 +62,7 @@ export interface CanonicalRawSourceRef {
   metadata?: Record<string, unknown>;
 }
 
-export interface CanonicalRecordBase {
+export interface CanonicalRecordBase extends Record<string, unknown> {
   record_kind: CanonicalRecordKind;
   schema_version: CanonicalSchemaVersion;
   normalizer_version: string;
@@ -143,6 +143,16 @@ export interface CanonicalExecutionFactRecord extends CanonicalSessionRecordBase
   errors_encountered: number;
   input_tokens?: number;
   output_tokens?: number;
+  cached_input_tokens?: number;
+  reasoning_output_tokens?: number;
+  cost_usd?: number;
+  files_changed?: number;
+  lines_added?: number;
+  lines_removed?: number;
+  lines_modified?: number;
+  artifact_count?: number;
+  session_type?: string;
+  agent_summary?: string;
   duration_ms?: number;
   completion_status?: CanonicalCompletionStatus;
   end_reason?: string;
@@ -157,9 +167,100 @@ export interface CanonicalNormalizationRunRecord extends CanonicalRecordBase {
   repair_applied: boolean;
 }
 
+export interface CanonicalEvolutionEvidenceRecord {
+  evidence_id?: string;
+  timestamp?: string;
+  proposal_id?: string;
+  skill_name: string;
+  skill_path?: string;
+  target: string;
+  stage: string;
+  rationale?: string;
+  confidence?: number;
+  details?: string;
+  original_text?: string;
+  proposed_text?: string;
+  eval_set_json?: unknown;
+  validation_json?: unknown;
+  raw_source_ref?: CanonicalRawSourceRef;
+}
+
+export interface CanonicalGradingResultRecord {
+  grading_id: string;
+  session_id: string;
+  skill_name: string;
+  transcript_path?: string | null;
+  graded_at: string;
+  pass_rate?: number | null;
+  mean_score?: number | null;
+  score_std_dev?: number | null;
+  passed_count?: number | null;
+  failed_count?: number | null;
+  total_count?: number | null;
+  expectations_json?: string | null;
+  claims_json?: string | null;
+  eval_feedback_json?: string | null;
+  failure_feedback_json?: string | null;
+  execution_metrics_json?: string | null;
+}
+
+export interface CanonicalImprovementSignalRecord {
+  signal_id: string;
+  timestamp: string;
+  session_id: string;
+  query: string;
+  signal_type: string;
+  mentioned_skill?: string | null;
+  consumed: boolean;
+  consumed_at?: string | null;
+  consumed_by_run?: string | null;
+}
+
 export type CanonicalRecord =
   | CanonicalSessionRecord
   | CanonicalPromptRecord
   | CanonicalSkillInvocationRecord
   | CanonicalExecutionFactRecord
   | CanonicalNormalizationRunRecord;
+
+export interface PushOrchestrateRunRecord {
+  run_id: string;
+  timestamp: string;
+  elapsed_ms: number;
+  dry_run: boolean;
+  approval_mode: "auto" | "review";
+  total_skills: number;
+  evaluated: number;
+  evolved: number;
+  deployed: number;
+  watched: number;
+  skipped: number;
+  skill_actions: Array<{
+    skill: string;
+    action: "evolve" | "watch" | "skip";
+    reason: string;
+    deployed?: boolean;
+    rolledBack?: boolean;
+    alert?: string | null;
+    elapsed_ms?: number;
+    llm_calls?: number;
+  }>;
+}
+
+export interface PushPayloadV2 {
+  schema_version: CanonicalSchemaVersion;
+  client_version: string;
+  push_id: string;
+  normalizer_version: string;
+  canonical: {
+    sessions: CanonicalSessionRecord[];
+    prompts: CanonicalPromptRecord[];
+    skill_invocations: CanonicalSkillInvocationRecord[];
+    execution_facts: CanonicalExecutionFactRecord[];
+    normalization_runs: CanonicalNormalizationRunRecord[];
+    evolution_evidence?: CanonicalEvolutionEvidenceRecord[];
+    orchestrate_runs?: PushOrchestrateRunRecord[];
+    grading_results?: CanonicalGradingResultRecord[];
+    improvement_signals?: CanonicalImprovementSignalRecord[];
+  };
+}

package/package.json

@@ -1,24 +1,35 @@
 {
   "name": "selftune",
-  "version": "0.2.23",
-  "description": "Self-improving skills CLI for AI agents",
+  "version": "0.2.24",
+  "description": "Skill-level observability and self-improvement for AI agents — monitors skill routing, detects missed triggers, and evolves descriptions automatically",
   "keywords": [
     "agent",
+    "agent-skills",
+    "ai-agent",
+    "ai-observability",
     "bun",
     "claude-code",
     "cli",
+    "cline",
     "codex",
     "eval",
+    "evals",
     "evolution",
     "grading",
+    "llm",
+    "observability",
     "opencode",
     "self-improving",
     "selftune",
     "skill",
+    "skill-evals",
+    "skill-observability",
+    "skill-routing",
+    "skill-testing",
     "telemetry",
     "typescript"
   ],
-  "homepage": "https://github.com/selftune-dev/selftune#readme",
+  "homepage": "https://selftune.dev",
   "bugs": {
     "url": "https://github.com/selftune-dev/selftune/issues"
   },
@@ -44,6 +55,7 @@
     "bin/",
     "cli/selftune/",
     "apps/local-dashboard/dist/",
+    "packages/dashboard-core/",
     "packages/telemetry-contract/",
     "packages/ui/",
     "templates/",
@@ -53,9 +65,9 @@
   ],
   "type": "module",
   "scripts": {
-    "dev": "trap 'kill 0' EXIT; bun --watch run cli/selftune/dashboard-server.ts --port 7888 --runtime-mode dev-server & sleep 1 && cd apps/local-dashboard && bunx vite --strictPort",
-    "dev:server": "bun --watch run cli/selftune/dashboard-server.ts --port 7888 --runtime-mode dev-server",
-    "dev:dashboard": "bun run cli/selftune/index.ts dashboard --port 7888 --no-open",
+    "dev": "cd apps/local-dashboard && bun run dev",
+    "dev:server": "sh -c 'dashboard_port=${DASHBOARD_PORT:-7888}; bun --watch run cli/selftune/dashboard-server.ts --port $dashboard_port --runtime-mode dev-server'",
+    "dev:dashboard": "sh -c 'dashboard_port=${DASHBOARD_PORT:-7888}; bun run cli/selftune/index.ts dashboard --port $dashboard_port --no-open'",
     "lint": "bunx oxlint",
     "lint:fix": "bunx oxlint --fix",
     "format": "bunx oxfmt",
@@ -71,17 +83,21 @@
     "sync-version": "bun run scripts/sync-skill-version.ts",
     "validate:subagents": "bun run scripts/validate-subagent-docs.ts",
     "prepublishOnly": "bun run sync-version && bun run build:dashboard",
+    "typecheck:runtime": "bunx tsc --noEmit -p tsconfig.runtime.json",
     "typecheck:dashboard": "cd apps/local-dashboard && bunx tsc --noEmit",
-    "check": "bun run lint && bun run format:check && bun run lint:arch && bun run typecheck:dashboard && bun run test",
+    "check": "bun run lint && bun run format:check && bun run lint:arch && bun run typecheck:runtime && bun run typecheck:dashboard && bun run test",
     "prepare": "bunx lefthook install || true",
     "start": "bun run cli/selftune/index.ts --help"
   },
   "dependencies": {
-    "@selftune/telemetry-contract": "file:packages/telemetry-contract"
+    "@selftune/telemetry-contract": "file:packages/telemetry-contract",
+    "react-markdown": "^10.1.0",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@evilmartians/lefthook": "^1.13.6",
-    "@types/bun": "^1.1.0",
+    "@types/bun": "^1.3.11",
+    "bun-types": "^1.3.11",
     "oxfmt": "^0.41.0",
     "oxlint": "^1.56.0"
   },

package/packages/dashboard-core/AGENTS.md

@@ -0,0 +1,18 @@
+# @selftune/dashboard-core
+
+Shared dashboard application layer used by both the cloud dashboard and the local OSS dashboard. Canonical copy lives here; synced to `oss/selftune/packages/dashboard-core` via `scripts/sync-embedded-shared.sh`.
+
+| Directory | Contents |
+|-----------|----------|
+| `src/host/` | Capability model, host adapter contracts, provider/context hooks |
+| `src/models/` | Normalized view models shared across hosts |
+| `src/routes/` | Route definition and route access helpers |
+| `src/chrome/` | Shared shell, sidebar, header, runtime badge, and chrome types |
+| `src/gates/` | Shared feature gates, locked-route surfaces, and upgrade CTAs |
+| `src/screens/` | Shared screen implementations; analytics, the overview autonomy/comparison/support surfaces, skills library, and the skill report scaffold/trust chrome are extracted |
+
+**Exports:** `.`, `./host`, `./models`, `./routes`, `./chrome`, `./gates`, `./screens`
+
+**Dependencies:** `@selftune/ui`, `lucide-react`, `react` (peer), `react-dom` (peer)
+
+**Important:** Do NOT edit `oss/selftune/packages/dashboard-core/` directly. Edit here and run `scripts/sync-embedded-shared.sh`.

package/packages/dashboard-core/README.md

@@ -0,0 +1,30 @@
+# @selftune/dashboard-core
+
+Shared dashboard application layer for SelfTune cloud and local hosts.
+
+This package owns:
+
+- capability and entitlement contracts
+- host adapter interfaces
+- normalized dashboard view models
+- shared route definition helpers
+- shared dashboard chrome primitives used by cloud and local hosts
+- shared feature gates and locked-route upgrade surfaces
+- shared screen implementations, including analytics, the overview autonomy/comparison/support surfaces, skills library, and the shared skill report scaffold/trust chrome
+
+## Usage
+
+```ts
+import {
+  DashboardChrome,
+  DashboardHostProvider,
+  canUseFeature,
+  type Capabilities,
+  type DashboardHostAdapter,
+} from "@selftune/dashboard-core";
+```
+
+## OSS Mirror
+
+This package is canonical in the root `packages/` directory and mirrored into
+`oss/selftune/packages/dashboard-core` via `scripts/sync-embedded-shared.sh`.

package/packages/dashboard-core/index.ts

@@ -0,0 +1,3 @@
+export * from "./src/host/index";
+export * from "./src/models/index";
+export * from "./src/routes/index";

package/packages/dashboard-core/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@selftune/dashboard-core",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Shared dashboard application layer for selftune cloud and local hosts",
+  "license": "MIT",
+  "author": "Daniel Petro",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/selftune-dev/selftune.git",
+    "directory": "packages/dashboard-core"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./host": "./src/host/index.ts",
+    "./models": "./src/models/index.ts",
+    "./routes": "./src/routes/index.ts",
+    "./chrome": "./src/chrome/index.ts",
+    "./gates": "./src/gates/index.ts",
+    "./screens": "./src/screens/index.ts",
+    "./screens/analytics": "./src/screens/analytics/index.ts",
+    "./screens/overview": "./src/screens/overview/index.ts",
+    "./screens/skill-report": "./src/screens/skill-report/index.ts",
+    "./screens/skills": "./src/screens/skills/index.ts"
+  },
+  "dependencies": {
+    "@selftune/ui": "workspace:*",
+    "lucide-react": "^0.576.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  }
+}

package/packages/dashboard-core/src/chrome/DashboardChrome.tsx

@@ -0,0 +1,74 @@
+"use client";
+
+import { PlayIcon } from "lucide-react";
+import { useState } from "react";
+
+import { TooltipProvider } from "@selftune/ui/primitives";
+
+import { DashboardHeader } from "./DashboardHeader";
+import { DashboardSidebar } from "./DashboardSidebar";
+import { cn } from "./utils";
+import type { DashboardChromeProps } from "./types";
+
+const DEFAULT_CONTENT_CLASS_NAME = "@container/main mx-auto max-w-7xl px-4 py-8 sm:px-6 lg:px-8";
+
+export function DashboardChrome({
+  brand,
+  navItems,
+  renderLink,
+  headerMeta,
+  searchItems = [],
+  headerUser,
+  sidebarUser,
+  sidebarAction,
+  onSignOut,
+  overlay,
+  contentClassName,
+  children,
+}: DashboardChromeProps) {
+  const [mobileOpen, setMobileOpen] = useState(false);
+
+  const content =
+    contentClassName === null ? (
+      children
+    ) : (
+      <div className={cn(contentClassName ?? DEFAULT_CONTENT_CLASS_NAME)}>{children}</div>
+    );
+
+  return (
+    <TooltipProvider>
+      <div className="min-h-screen bg-background">
+        <DashboardSidebar
+          brand={brand}
+          navItems={navItems}
+          renderLink={renderLink}
+          sidebarAction={
+            sidebarAction ?? {
+              label: "Run Evolution",
+              tooltip: "Dashboard-triggered evolution is not available yet.",
+              icon: <PlayIcon className="size-4" />,
+              disabled: true,
+            }
+          }
+          sidebarUser={sidebarUser}
+          onSignOut={onSignOut}
+          mobileOpen={mobileOpen}
+          onMobileOpenChange={setMobileOpen}
+        />
+
+        <div className="min-h-screen lg:pl-64">
+          <DashboardHeader
+            renderLink={renderLink}
+            headerMeta={headerMeta}
+            searchItems={searchItems}
+            headerUser={headerUser}
+            onToggleSidebar={() => setMobileOpen((open) => !open)}
+          />
+          <main className="min-h-[calc(100vh-4rem)]">{content}</main>
+        </div>
+
+        {overlay}
+      </div>
+    </TooltipProvider>
+  );
+}