@jhytabest/plashboard 0.1.7 → 0.1.9

package/README.md

@@ -9,6 +9,7 @@ This plugin manages dashboard templates, scheduled fill runs, validation, and at
 ```bash
 openclaw plugins install @jhytabest/plashboard
 openclaw plugins enable plashboard
+sudo systemctl restart openclaw-gateway
 openclaw plugins doctor
 ```
 
@@ -18,7 +19,21 @@ openclaw plugins doctor
 openclaw plugins update plashboard
 ```
 
-## Minimal Config
+## Zero-Config First Run
+
+No manual config is required for first use. Defaults are safe:
+- `fill_provider=openclaw`
+- `openclaw_fill_agent_id=main`
+- automatic init on service start
+- automatic starter template seed when template store is empty
+
+In chat, run:
+
+```text
+/plashboard quickstart <what this dashboard should focus on>
+```
+
+## Optional Config
 
 Add to `openclaw.json`:
 
@@ -35,6 +50,7 @@ Add to `openclaw.json`:
           "default_retry_count": 1,
           "retry_backoff_seconds": 20,
           "session_timeout_seconds": 90,
+          "auto_seed_template": true,
           "fill_provider": "openclaw",
           "openclaw_fill_agent_id": "main",
           "display_profile": {
@@ -59,6 +75,9 @@ Use `fill_provider: "command"` only if you need a custom external runner.
 
 ```text
 /plashboard setup [openclaw [agent_id]|mock|command <fill_command>]
+/plashboard quickstart <description>
+/plashboard doctor [local_url] [https_port] [repo_dir]
+/plashboard web-guide [local_url] [repo_dir]
 /plashboard expose-guide [local_url] [https_port]
 /plashboard expose-check [local_url] [https_port]
 /plashboard init
@@ -74,8 +93,15 @@ Use `fill_provider: "command"` only if you need a custom external runner.
 Recommended first run:
 
 ```text
-/plashboard setup openclaw
-/plashboard init
+/plashboard quickstart "Focus on service health, priorities, blockers, and next actions."
+```
+
+If `quickstart` returns web/exposure warnings:
+
+```text
+/plashboard web-guide
+/plashboard expose-guide
+/plashboard doctor
 ```
 
 Tailscale helper flow:

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "plashboard",
   "name": "Plashboard",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Template-driven dashboard runtime with scheduled OpenClaw fills and safe publish.",
   "entry": "./src/index.ts",
   "skills": ["./skills/plashboard-admin"],
@@ -15,6 +15,7 @@
       "default_retry_count": { "type": "integer", "minimum": 0, "maximum": 5, "default": 1 },
       "retry_backoff_seconds": { "type": "integer", "minimum": 1, "maximum": 300, "default": 20 },
       "session_timeout_seconds": { "type": "integer", "minimum": 10, "maximum": 600, "default": 90 },
+      "auto_seed_template": { "type": "boolean", "default": true },
       "fill_provider": { "type": "string", "enum": ["command", "mock", "openclaw"], "default": "openclaw" },
       "fill_command": { "type": "string" },
       "openclaw_fill_agent_id": { "type": "string", "default": "main" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhytabest/plashboard",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "private": false,
   "description": "Plashboard OpenClaw plugin runtime",
   "license": "MIT",

package/skills/plashboard-admin/SKILL.md

@@ -20,7 +20,10 @@ Always use plugin tools:
 - `plashboard_setup`
 - `plashboard_exposure_guide`
 - `plashboard_exposure_check`
+- `plashboard_web_guide`
+- `plashboard_doctor`
 - `plashboard_init`
+- `plashboard_quickstart`
 - `plashboard_template_create`
 - `plashboard_template_update`
 - `plashboard_template_list`
@@ -39,7 +42,10 @@ Always use plugin tools:
 - Never ask the model to generate full dashboard structure when filling values.
 
 ## Command Shortcuts
+- `/plashboard quickstart <description>`
 - `/plashboard setup [openclaw [agent_id]|mock|command <fill_command>]`
+- `/plashboard doctor [local_url] [https_port] [repo_dir]`
+- `/plashboard web-guide [local_url] [repo_dir]`
 - `/plashboard expose-guide [local_url] [https_port]`
 - `/plashboard expose-check [local_url] [https_port]`
 - `/plashboard init`

package/src/config.ts

@@ -22,6 +22,16 @@ function asString(value: unknown, fallback: string): string {
   return typeof value === 'string' && value.trim() ? value : fallback;
 }
 
+function asBoolean(value: unknown, fallback: boolean): boolean {
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'string') {
+    const normalized = value.trim().toLowerCase();
+    if (normalized === 'true' || normalized === '1' || normalized === 'yes' || normalized === 'on') return true;
+    if (normalized === 'false' || normalized === '0' || normalized === 'no' || normalized === 'off') return false;
+  }
+  return fallback;
+}
+
 function asObject(value: unknown): Record<string, unknown> {
   return value && typeof value === 'object' && !Array.isArray(value)
     ? (value as Record<string, unknown>)
@@ -65,6 +75,7 @@ export function resolveConfig(api: unknown): PlashboardConfig {
     default_retry_count: Math.max(0, Math.floor(asNumber(raw.default_retry_count, 1))),
     retry_backoff_seconds: Math.max(1, Math.floor(asNumber(raw.retry_backoff_seconds, 20))),
     session_timeout_seconds: Math.max(10, Math.floor(asNumber(raw.session_timeout_seconds, 90))),
+    auto_seed_template: asBoolean(raw.auto_seed_template, true),
     fill_provider: fillProvider,
     fill_command: typeof raw.fill_command === 'string' ? raw.fill_command : undefined,
     openclaw_fill_agent_id: asString(raw.openclaw_fill_agent_id, 'main'),

package/src/fill-runner.test.ts

@@ -37,6 +37,7 @@ function config(overrides: Partial<PlashboardConfig>): PlashboardConfig {
     default_retry_count: 0,
     retry_backoff_seconds: 1,
     session_timeout_seconds: 30,
+    auto_seed_template: false,
     fill_provider: 'mock',
     fill_command: undefined,
     openclaw_fill_agent_id: 'main',

package/src/plugin.ts

@@ -90,6 +90,7 @@ type SetupParams = {
   fill_provider?: 'mock' | 'command' | 'openclaw';
   fill_command?: string;
   openclaw_fill_agent_id?: string;
+  auto_seed_template?: boolean;
   data_dir?: string;
   scheduler_tick_seconds?: number;
   session_timeout_seconds?: number;
@@ -101,12 +102,30 @@ type SetupParams = {
   layout_safety_margin_px?: number;
 };
 
+type QuickstartParams = {
+  description?: string;
+  template_id?: string;
+  template_name?: string;
+  every_minutes?: number;
+  activate?: boolean;
+  run_now?: boolean;
+};
+
 type ExposureParams = {
   local_url?: string;
   tailscale_https_port?: number;
   dashboard_output_path?: string;
 };
 
+type WebGuideParams = {
+  local_url?: string;
+  repo_dir?: string;
+};
+
+type DoctorParams = ExposureParams & {
+  repo_dir?: string;
+};
+
 type CommandExecResult = {
   ok: boolean;
   stdout: string;
@@ -220,6 +239,40 @@ async function buildExposureGuide(resolvedConfig: ReturnType<typeof resolveConfi
   } satisfies ToolResponse<Record<string, unknown>>;
 }
 
+function deriveRepoDir(raw?: string): string {
+  const value = (raw || '').trim();
+  return value || '/opt/plashboard';
+}
+
+async function buildWebGuide(resolvedConfig: ReturnType<typeof resolveConfig>, params: WebGuideParams = {}) {
+  const localUrl = normalizeLocalUrl(params.local_url);
+  const repoDir = deriveRepoDir(params.repo_dir);
+  const dashboardPath = resolvedConfig.dashboard_output_path;
+
+  return {
+    ok: true,
+    errors: [],
+    data: {
+      local_url: localUrl,
+      repo_dir: repoDir,
+      dashboard_output_path: dashboardPath,
+      commands: [
+        `git clone https://github.com/jhytabest/plashboard.git ${repoDir} || true`,
+        `git -C ${repoDir} pull --ff-only`,
+        `docker compose -f ${repoDir}/docker-compose.yml up -d`,
+        `docker ps --format "{{.Names}} {{.Ports}}" | grep -E "plash-web|18888"`,
+        `curl -I ${localUrl}`,
+        `curl -I ${localUrl}/healthz`
+      ],
+      notes: [
+        'Plashboard writes dashboard JSON; a local web server must serve the UI and /data/dashboard.json.',
+        'The bundled docker-compose stack exposes nginx at 127.0.0.1:18888 by default.',
+        'If you host UI differently, update local_url in expose-check/expose-guide.'
+      ]
+    }
+  } satisfies ToolResponse<Record<string, unknown>>;
+}
+
 async function runExposureCheck(resolvedConfig: ReturnType<typeof resolveConfig>, params: ExposureParams = {}) {
   const localUrl = normalizeLocalUrl(params.local_url);
   const httpsPort = normalizePort(asNumber(params.tailscale_https_port), 8444);
@@ -357,6 +410,13 @@ async function runSetup(api: UnknownApi, resolvedConfig: ReturnType<typeof resol
     || asString(currentPluginConfig.fill_command)
     || asString(resolvedConfig.fill_command)
   ).trim();
+  const selectedAutoSeed = (
+    typeof params.auto_seed_template === 'boolean'
+      ? params.auto_seed_template
+      : typeof currentPluginConfig.auto_seed_template === 'boolean'
+        ? currentPluginConfig.auto_seed_template
+        : resolvedConfig.auto_seed_template
+  );
   const selectedAgentId = (
     params.openclaw_fill_agent_id
     || asString(currentPluginConfig.openclaw_fill_agent_id)
@@ -397,6 +457,7 @@ async function runSetup(api: UnknownApi, resolvedConfig: ReturnType<typeof resol
       )
     ),
     fill_provider: selectedProvider,
+    auto_seed_template: selectedAutoSeed,
     display_profile: displayProfile
   };
 
@@ -438,6 +499,7 @@ async function runSetup(api: UnknownApi, resolvedConfig: ReturnType<typeof resol
       fill_provider: selectedProvider,
       fill_command: selectedProvider === 'command' ? selectedCommand : undefined,
       openclaw_fill_agent_id: selectedProvider === 'openclaw' ? selectedAgentId : undefined,
+      auto_seed_template: selectedAutoSeed,
       data_dir: nextPluginConfig.data_dir,
       scheduler_tick_seconds: nextPluginConfig.scheduler_tick_seconds,
       session_timeout_seconds: nextPluginConfig.session_timeout_seconds,
@@ -450,6 +512,101 @@ async function runSetup(api: UnknownApi, resolvedConfig: ReturnType<typeof resol
   } satisfies ToolResponse<Record<string, unknown>>;
 }
 
+async function runQuickstart(
+  runtime: PlashboardRuntime,
+  resolvedConfig: ReturnType<typeof resolveConfig>,
+  params: QuickstartParams = {}
+): Promise<ToolResponse<Record<string, unknown>>> {
+  const quickstart = await runtime.quickstart(params);
+  const exposure = await runExposureCheck(resolvedConfig, {});
+  const guide = await buildExposureGuide(resolvedConfig, {});
+  const webGuide = await buildWebGuide(resolvedConfig, {});
+
+  const warnings: string[] = [];
+  if (!exposure.ok) {
+    warnings.push(...exposure.errors);
+  }
+
+  return {
+    ok: quickstart.ok,
+    errors: quickstart.errors,
+    data: {
+      ...(quickstart.data || {}),
+      postcheck: {
+        local_url: exposure.data?.local_url,
+        local_url_ok: exposure.data?.local_url_ok,
+        tailscale_port_configured: exposure.data?.tailscale_port_configured,
+        dashboard_exists: exposure.data?.dashboard_exists
+      },
+      warnings,
+      next_steps: warnings.length
+        ? [
+          'run /plashboard web-guide and execute its commands',
+          'run /plashboard expose-guide and apply tailscale mapping',
+          'run /plashboard doctor'
+        ]
+        : [
+          'dashboard generation is working',
+          'run /plashboard doctor for full readiness check'
+        ],
+      exposure_guide: guide.data,
+      web_guide: webGuide.data
+    }
+  };
+}
+
+async function runDoctor(
+  runtime: PlashboardRuntime,
+  resolvedConfig: ReturnType<typeof resolveConfig>,
+  params: DoctorParams = {}
+): Promise<ToolResponse<Record<string, unknown>>> {
+  const status = await runtime.status();
+  const exposure = await runExposureCheck(resolvedConfig, params);
+  const exposureGuide = await buildExposureGuide(resolvedConfig, params);
+  const webGuide = await buildWebGuide(resolvedConfig, params);
+
+  const issues: string[] = [];
+  const statusData = status.data;
+  const templateCount = Number(statusData?.template_count ?? 0);
+  const activeTemplateId = statusData?.active_template_id || null;
+
+  if (!status.ok) issues.push(...status.errors);
+  if (templateCount === 0) issues.push('no templates exist; run /plashboard quickstart "<description>"');
+  if (!activeTemplateId) issues.push('no active template; activate one with /plashboard activate <template-id>');
+  if (exposure.data?.dashboard_exists !== true) {
+    issues.push(`dashboard output missing at ${resolvedConfig.dashboard_output_path}`);
+  }
+  if (exposure.data?.local_url_ok !== true) {
+    issues.push(`local dashboard server is not reachable at ${String(exposure.data?.local_url || 'http://127.0.0.1:18888')}`);
+  }
+  if (exposure.data?.tailscale_status_ok !== true) {
+    issues.push('tailscale serve status failed');
+  } else if (exposure.data?.tailscale_port_configured !== true) {
+    issues.push(`tailscale serve mapping missing for port ${String(exposure.data?.tailscale_https_port || 8444)}`);
+  }
+
+  const ready = issues.length === 0;
+  return {
+    ok: ready,
+    errors: issues,
+    data: {
+      ready,
+      status: statusData,
+      exposure: exposure.data,
+      exposure_guide: exposureGuide.data,
+      web_guide: webGuide.data,
+      next_steps: ready
+        ? ['dashboard runtime + web exposure look healthy']
+        : [
+          'run /plashboard quickstart "<description>" if no templates exist',
+          'run /plashboard web-guide and start local UI server',
+          'run /plashboard expose-guide and apply tailscale mapping',
+          're-run /plashboard doctor'
+        ]
+    }
+  };
+}
+
 export function registerPlashboardPlugin(api: UnknownApi): void {
   const config = resolveConfig(api);
   const runtimeCommand = api.runtime?.system?.runCommandWithTimeout;
@@ -528,6 +685,40 @@ export function registerPlashboardPlugin(api: UnknownApi): void {
       toToolResult(await runExposureCheck(config, params))
   });
 
+  api.registerTool?.({
+    name: 'plashboard_web_guide',
+    description: 'Return exact commands to start the local plashboard web UI server.',
+    optional: true,
+    parameters: {
+      type: 'object',
+      properties: {
+        local_url: { type: 'string' },
+        repo_dir: { type: 'string' }
+      },
+      additionalProperties: false
+    },
+    execute: async (_toolCallId: unknown, params: WebGuideParams = {}) =>
+      toToolResult(await buildWebGuide(config, params))
+  });
+
+  api.registerTool?.({
+    name: 'plashboard_doctor',
+    description: 'Run full plashboard readiness checks (templates, local UI, and tailscale mapping).',
+    optional: true,
+    parameters: {
+      type: 'object',
+      properties: {
+        local_url: { type: 'string' },
+        tailscale_https_port: { type: 'number' },
+        dashboard_output_path: { type: 'string' },
+        repo_dir: { type: 'string' }
+      },
+      additionalProperties: false
+    },
+    execute: async (_toolCallId: unknown, params: DoctorParams = {}) =>
+      toToolResult(await runDoctor(runtime, config, params))
+  });
+
   api.registerTool?.({
     name: 'plashboard_setup',
     description: 'Bootstrap or update plashboard plugin configuration in openclaw.json.',
@@ -538,6 +729,7 @@ export function registerPlashboardPlugin(api: UnknownApi): void {
         fill_provider: { type: 'string', enum: ['mock', 'command', 'openclaw'] },
         fill_command: { type: 'string' },
         openclaw_fill_agent_id: { type: 'string' },
+        auto_seed_template: { type: 'boolean' },
         data_dir: { type: 'string' },
         scheduler_tick_seconds: { type: 'number' },
         session_timeout_seconds: { type: 'number' },
@@ -566,6 +758,26 @@ export function registerPlashboardPlugin(api: UnknownApi): void {
     execute: async () => toToolResult(await runtime.init())
   });
 
+  api.registerTool?.({
+    name: 'plashboard_quickstart',
+    description: 'Create a first dashboard template from a short description, activate it, and run it once.',
+    optional: true,
+    parameters: {
+      type: 'object',
+      properties: {
+        description: { type: 'string' },
+        template_id: { type: 'string' },
+        template_name: { type: 'string' },
+        every_minutes: { type: 'number' },
+        activate: { type: 'boolean' },
+        run_now: { type: 'boolean' }
+      },
+      additionalProperties: false
+    },
+    execute: async (_toolCallId: unknown, params: QuickstartParams = {}) =>
+      toToolResult(await runQuickstart(runtime, config, params))
+  });
+
   api.registerTool?.({
     name: 'plashboard_template_create',
     description: 'Create a new dashboard template.',
@@ -769,6 +981,28 @@ export function registerPlashboardPlugin(api: UnknownApi): void {
           })
         );
       }
+      if (cmd === 'web-guide') {
+        const localUrl = rest.find((token) => token.startsWith('http://') || token.startsWith('https://'));
+        const repoDir = rest.find((token) => token.startsWith('/'));
+        return toCommandResult(
+          await buildWebGuide(config, {
+            local_url: localUrl,
+            repo_dir: repoDir
+          })
+        );
+      }
+      if (cmd === 'doctor') {
+        const localUrl = rest.find((token) => token.startsWith('http://') || token.startsWith('https://'));
+        const portToken = rest.find((token) => /^[0-9]+$/.test(token));
+        const repoDir = rest.find((token) => token.startsWith('/'));
+        return toCommandResult(
+          await runDoctor(runtime, config, {
+            local_url: localUrl,
+            tailscale_https_port: portToken ? Number(portToken) : undefined,
+            repo_dir: repoDir
+          })
+        );
+      }
       if (cmd === 'setup') {
         const mode = asString(rest[0]).toLowerCase();
         const fillProvider = mode === 'command' || mode === 'mock' || mode === 'openclaw' ? mode : undefined;
@@ -782,6 +1016,10 @@ export function registerPlashboardPlugin(api: UnknownApi): void {
           })
         );
       }
+      if (cmd === 'quickstart') {
+        const description = rest.join(' ').trim() || undefined;
+        return toCommandResult(await runQuickstart(runtime, config, { description }));
+      }
       if (cmd === 'init') return toCommandResult(await runtime.init());
       if (cmd === 'status') return toCommandResult(await runtime.status());
       if (cmd === 'list') return toCommandResult(await runtime.templateList());
@@ -806,7 +1044,7 @@ export function registerPlashboardPlugin(api: UnknownApi): void {
       return toCommandResult({
         ok: false,
         errors: [
-          'unknown command. supported: setup [openclaw [agent_id]|mock|command <fill_command>], expose-guide [local_url] [https_port], expose-check [local_url] [https_port], init, status, list, activate <id>, delete <id>, copy <src> <new-id> [new-name] [activate], run <id>, set-display <width> <height> <top> <bottom>'
+          'unknown command. supported: setup [openclaw [agent_id]|mock|command <fill_command>], quickstart <description>, doctor [local_url] [https_port] [repo_dir], web-guide [local_url] [repo_dir], expose-guide [local_url] [https_port], expose-check [local_url] [https_port], init, status, list, activate <id>, delete <id>, copy <src> <new-id> [new-name] [activate], run <id>, set-display <width> <height> <top> <bottom>'
         ]
       });
     }

package/src/runtime.test.ts

@@ -51,7 +51,7 @@ function template(id: string): DashboardTemplate {
   };
 }
 
-async function setupRuntime() {
+async function setupRuntime(overrides: Partial<PlashboardConfig> = {}) {
   const root = await mkdtemp(join(tmpdir(), 'plashboard-test-'));
   const config: PlashboardConfig = {
     data_dir: root,
@@ -61,6 +61,7 @@ async function setupRuntime() {
     default_retry_count: 0,
     retry_backoff_seconds: 1,
     session_timeout_seconds: 30,
+    auto_seed_template: false,
     fill_provider: 'mock',
     fill_command: undefined,
     python_bin: 'python3',
@@ -75,7 +76,8 @@ async function setupRuntime() {
       safe_side_px: 28,
       layout_safety_margin_px: 24
     },
-    model_defaults: {}
+    model_defaults: {},
+    ...overrides
   };
 
   const runtime = new PlashboardRuntime(config);
@@ -160,4 +162,41 @@ describe('PlashboardRuntime', () => {
       await rm(root, { recursive: true, force: true });
     }
   });
+
+  it('auto-seeds a starter template when enabled', async () => {
+    const { runtime, root } = await setupRuntime({ auto_seed_template: true });
+    try {
+      const list = await runtime.templateList();
+      expect(list.ok).toBe(true);
+      const templates = list.data?.templates ?? [];
+      expect(templates.length).toBe(1);
+      expect(String(templates[0]?.id)).toBe('starter');
+
+      const status = await runtime.status();
+      expect(status.ok).toBe(true);
+      expect(status.data?.active_template_id).toBe('starter');
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it('quickstart creates, activates, and runs once', async () => {
+    const { runtime, root, config } = await setupRuntime({ auto_seed_template: false });
+    try {
+      const quickstart = await runtime.quickstart({
+        description: 'Focus on homelab health, priorities, blockers, and next actions.'
+      });
+      expect(quickstart.ok).toBe(true);
+      const templateId = String(quickstart.data?.template_id || '');
+      expect(templateId).toBeTruthy();
+      expect(quickstart.data?.active_template_id).toBe(templateId);
+      expect(quickstart.data?.run_status).toBe('success');
+
+      const published = JSON.parse(await readFile(config.dashboard_output_path, 'utf8')) as Record<string, unknown>;
+      expect(published.version).toBe('3.0');
+      expect(typeof published.generated_at).toBe('string');
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
 });

package/src/runtime.ts

@@ -31,6 +31,25 @@ const NOOP_LOGGER: Logger = {
   error: () => {}
 };
 
+function clampInt(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, Math.floor(value)));
+}
+
+function normalizeTemplateId(input: string): string {
+  const cleaned = input
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, '-')
+    .replace(/^-+/, '')
+    .replace(/-+$/, '')
+    .replace(/--+/g, '-');
+
+  if (!cleaned) return '';
+  const limited = cleaned.slice(0, 64);
+  if (!/^[a-z0-9]/.test(limited)) return '';
+  return limited;
+}
+
 function resolveLastAttemptMs(state: PlashboardState, templateId: string): number | null {
   const runState = state.template_runs[templateId];
   if (!runState) return null;
@@ -100,32 +119,48 @@ export class PlashboardRuntime {
     await this.paths.ensure();
     await this.loadState();
 
-    const templates = await this.templateStore.list();
     const state = await this.loadState();
+    let templates = await this.templateStore.list();
+    let autoSeededTemplateId: string | null = null;
+    let autoSeededSource: 'live_dashboard' | 'starter' | null = null;
 
     if (!state.display_profile) {
       state.display_profile = this.config.display_profile;
       await this.saveState(state);
     }
 
-    if (!templates.length) {
-      const seeded = await this.seedDefaultTemplate();
-      if (seeded) {
-        const next = await this.templateStore.list();
-        if (!state.active_template_id && next.length) {
-          state.active_template_id = next[0].id;
-          await this.saveState(state);
-        }
+    if (!templates.length && this.config.auto_seed_template) {
+      autoSeededTemplateId = await this.seedTemplateFromLiveDashboard();
+      autoSeededSource = autoSeededTemplateId ? 'live_dashboard' : null;
+
+      if (!autoSeededTemplateId) {
+        autoSeededTemplateId = await this.seedStarterTemplate({
+          preferredId: 'starter',
+          name: 'Starter Dashboard',
+          description: 'A first-run dashboard that summarizes priorities, risks, and next actions.',
+          everyMinutes: 15
+        });
+        autoSeededSource = 'starter';
       }
     }
 
+    templates = await this.templateStore.list();
+    if (!state.active_template_id && templates.length) {
+      state.active_template_id = autoSeededTemplateId || templates[0].id;
+      await this.saveState(state);
+    }
+
     return {
       ok: true,
       errors: [],
       data: {
         data_dir: this.paths.dataDir,
         dashboard_output_path: this.paths.liveDashboardPath,
-        scheduler_tick_seconds: this.config.scheduler_tick_seconds
+        scheduler_tick_seconds: this.config.scheduler_tick_seconds,
+        template_count: templates.length,
+        active_template_id: state.active_template_id,
+        auto_seeded_template_id: autoSeededTemplateId,
+        auto_seeded_source: autoSeededSource
       }
     };
   }
@@ -333,6 +368,88 @@ export class PlashboardRuntime {
     };
   }
 
+  async quickstart(params: {
+    description?: string;
+    template_id?: string;
+    template_name?: string;
+    every_minutes?: number;
+    activate?: boolean;
+    run_now?: boolean;
+  } = {}): Promise<ToolResponse<Record<string, unknown>>> {
+    const description = (params.description || '').trim()
+      || 'Create a high-signal operational dashboard with concise summaries and actionable updates.';
+    const everyMinutes = clampInt(
+      Number.isFinite(params.every_minutes) ? Number(params.every_minutes) : 15,
+      1,
+      24 * 60
+    );
+
+    const requestedId = (params.template_id || '').trim();
+    if (requestedId && !/^[a-z0-9][a-z0-9_-]{0,63}$/.test(requestedId)) {
+      return { ok: false, errors: ['template_id is invalid'] };
+    }
+
+    const resolvedTemplateId = requestedId
+      ? await this.allocateTemplateId(requestedId)
+      : await this.allocateTemplateId('quickstart');
+
+    const templateName = (params.template_name || '').trim() || 'Quickstart Dashboard';
+    const template = this.buildStarterTemplate({
+      id: resolvedTemplateId,
+      name: templateName,
+      description,
+      everyMinutes
+    });
+
+    const createResult = await this.templateCreate(template);
+    if (!createResult.ok) return createResult;
+
+    const errors: string[] = [];
+    let activeTemplateId: string | null = null;
+
+    const shouldActivate = params.activate !== false;
+    if (shouldActivate) {
+      const activateResult = await this.templateActivate(resolvedTemplateId);
+      if (!activateResult.ok) {
+        errors.push(...activateResult.errors.map((entry) => `activate: ${entry}`));
+      } else {
+        activeTemplateId = activateResult.data?.active_template_id || null;
+      }
+    } else {
+      const state = await this.loadState();
+      activeTemplateId = state.active_template_id;
+    }
+
+    let runStatus: string | null = null;
+    let published = false;
+    let runErrors: string[] = [];
+    const shouldRunNow = params.run_now !== false;
+    if (shouldRunNow) {
+      const runResult = await this.runNow(resolvedTemplateId);
+      runStatus = String(runResult.data?.status || '');
+      published = Boolean(runResult.data?.published);
+      runErrors = runResult.errors;
+      if (!runResult.ok) {
+        errors.push(...runResult.errors.map((entry) => `run: ${entry}`));
+      }
+    }
+
+    return {
+      ok: errors.length === 0,
+      errors,
+      data: {
+        template_id: resolvedTemplateId,
+        template_name: templateName,
+        schedule_every_minutes: everyMinutes,
+        active_template_id: activeTemplateId,
+        run_now: shouldRunNow,
+        run_status: runStatus,
+        run_published: published,
+        run_errors: runErrors
+      }
+    };
+  }
+
   async status(): Promise<ToolResponse<RuntimeStatus>> {
     const state = await this.loadState();
     const templates = await this.templateStore.list();
@@ -571,18 +688,19 @@ export class PlashboardRuntime {
     return state.display_profile || this.config.display_profile;
   }
 
-  private async seedDefaultTemplate(): Promise<boolean> {
+  private async seedTemplateFromLiveDashboard(): Promise<string | null> {
     try {
       await access(this.paths.liveDashboardPath, fsConstants.R_OK);
     } catch {
-      return false;
+      return null;
     }
 
     const text = await readFile(this.paths.liveDashboardPath, 'utf8');
     const dashboard = JSON.parse(text) as Record<string, unknown>;
+    const templateId = await this.allocateTemplateId('default');
 
     const template: DashboardTemplate = {
-      id: 'default',
+      id: templateId,
       name: 'Default Dashboard Template',
       enabled: true,
       schedule: {
@@ -602,7 +720,217 @@ export class PlashboardRuntime {
     };
 
     await this.templateStore.upsert(template);
-    return true;
+    return templateId;
+  }
+
+  private async seedStarterTemplate(params: {
+    preferredId: string;
+    name: string;
+    description: string;
+    everyMinutes: number;
+  }): Promise<string> {
+    const id = await this.allocateTemplateId(params.preferredId);
+    const template = this.buildStarterTemplate({
+      id,
+      name: params.name,
+      description: params.description,
+      everyMinutes: clampInt(params.everyMinutes, 1, 24 * 60)
+    });
+
+    const validationErrors = await this.validateTemplate(template);
+    if (validationErrors.length) {
+      throw new Error(`starter template validation failed: ${validationErrors.join('; ')}`);
+    }
+
+    await this.templateStore.upsert(template);
+    return id;
+  }
+
+  private async allocateTemplateId(preferredId: string): Promise<string> {
+    const normalized = normalizeTemplateId(preferredId) || 'starter';
+    const existing = await this.templateStore.get(normalized);
+    if (!existing) return normalized;
+
+    const base = normalized.slice(0, 58);
+    for (let i = 2; i <= 99; i += 1) {
+      const candidate = `${base}-${i}`;
+      const found = await this.templateStore.get(candidate);
+      if (!found) return candidate;
+    }
+    return `${base}-${Date.now()}`.slice(0, 64);
+  }
+
+  private buildStarterTemplate(params: {
+    id: string;
+    name: string;
+    description: string;
+    everyMinutes: number;
+  }): DashboardTemplate {
+    const description = params.description.trim();
+    return {
+      id: params.id,
+      name: params.name,
+      enabled: true,
+      schedule: {
+        mode: 'interval',
+        every_minutes: params.everyMinutes,
+        timezone: this.config.timezone
+      },
+      base_dashboard: {
+        title: params.name,
+        summary: 'Preparing summary…',
+        ui: {
+          timezone: this.config.timezone
+        },
+        sections: [
+          {
+            id: 'overview',
+            label: 'Overview',
+            cards: [
+              {
+                id: 'pulse',
+                title: 'System Pulse',
+                description: 'Waiting for first run…',
+                long_description: 'This card is filled by OpenClaw on each run.'
+              },
+              {
+                id: 'priorities',
+                title: 'Top Priorities',
+                description: 'Waiting for first run…',
+                long_description: 'This card highlights what matters most right now.'
+              }
+            ]
+          },
+          {
+            id: 'operations',
+            label: 'Operations',
+            cards: [
+              {
+                id: 'risks',
+                title: 'Risks to Watch',
+                description: 'Waiting for first run…'
+              },
+              {
+                id: 'blockers',
+                title: 'Potential Blockers',
+                description: 'Waiting for first run…'
+              }
+            ]
+          },
+          {
+            id: 'actions',
+            label: 'Actions',
+            cards: [
+              {
+                id: 'next_steps',
+                title: 'Next Actions',
+                description: 'Waiting for first run…'
+              },
+              {
+                id: 'questions',
+                title: 'Open Questions',
+                description: 'Waiting for first run…'
+              }
+            ]
+          }
+        ],
+        alerts: []
+      },
+      fields: [
+        {
+          id: 'summary',
+          pointer: '/summary',
+          type: 'string',
+          prompt: 'Write one concise dashboard summary (max 260 chars).',
+          required: true,
+          constraints: { max_len: 260 }
+        },
+        {
+          id: 'pulse',
+          pointer: '/sections/0/cards/0/description',
+          type: 'string',
+          prompt: 'Describe current pulse/status in one short paragraph.',
+          required: true,
+          constraints: { max_len: 280 }
+        },
+        {
+          id: 'pulse_details',
+          pointer: '/sections/0/cards/0/long_description',
+          type: 'string',
+          prompt: 'Provide richer context behind the pulse status with concrete facts.',
+          required: true,
+          constraints: { max_len: 900 }
+        },
+        {
+          id: 'priorities',
+          pointer: '/sections/0/cards/1/description',
+          type: 'string',
+          prompt: 'State the top priorities right now as a compact sentence.',
+          required: true,
+          constraints: { max_len: 280 }
+        },
+        {
+          id: 'priorities_details',
+          pointer: '/sections/0/cards/1/long_description',
+          type: 'string',
+          prompt: 'Explain why these priorities matter and what outcome is expected.',
+          required: true,
+          constraints: { max_len: 900 }
+        },
+        {
+          id: 'risks',
+          pointer: '/sections/1/cards/0/description',
+          type: 'string',
+          prompt: 'Describe the most relevant risks and their likely impact.',
+          required: true,
+          constraints: { max_len: 320 }
+        },
+        {
+          id: 'blockers',
+          pointer: '/sections/1/cards/1/description',
+          type: 'string',
+          prompt: 'List active blockers and the dependency needed to unblock.',
+          required: true,
+          constraints: { max_len: 320 }
+        },
+        {
+          id: 'next_steps',
+          pointer: '/sections/2/cards/0/description',
+          type: 'string',
+          prompt: 'Provide immediate next steps with owners/time hints if possible.',
+          required: true,
+          constraints: { max_len: 320 }
+        },
+        {
+          id: 'questions',
+          pointer: '/sections/2/cards/1/description',
+          type: 'string',
+          prompt: 'List open questions that need decisions soon.',
+          required: true,
+          constraints: { max_len: 320 }
+        }
+      ],
+      context: {
+        dashboard_prompt: `Dashboard objective: ${description}`,
+        section_prompts: {
+          overview: 'Summarize high-level status and priorities for quick scanning.',
+          operations: 'Highlight operational risks and blockers with practical impact.',
+          actions: 'Focus on actionable next steps and unresolved decision points.'
+        },
+        card_prompts: {
+          pulse: `Context: ${description}. Keep it factual and concise.`,
+          priorities: 'Surface the top priorities and expected outcomes.',
+          risks: 'Call out risks that deserve active monitoring.',
+          blockers: 'Describe blockers and what would resolve them.',
+          next_steps: 'Give concrete next actions.',
+          questions: 'Capture open questions requiring a decision.'
+        }
+      },
+      run: {
+        retry_count: this.config.default_retry_count,
+        repair_attempts: 1
+      }
+    };
   }
 
   private async writeRenderedSnapshot(templateId: string, payload: Record<string, unknown>): Promise<void> {

package/src/types.ts

@@ -23,6 +23,7 @@ export interface PlashboardConfig {
   default_retry_count: number;
   retry_backoff_seconds: number;
   session_timeout_seconds: number;
+  auto_seed_template: boolean;
   fill_provider: 'command' | 'mock' | 'openclaw';
   fill_command?: string;
   openclaw_fill_agent_id?: string;