2ndbrain 2026.1.32 → 2026.1.34

package/.claude/settings.local.json

@@ -11,7 +11,11 @@
       "WebFetch(domain:latenode.com)",
       "Bash(claude:*)",
       "Bash(printf:*)",
-      "Bash(ls -la \"c:\\\\dev\\\\fingerskier\\\\agent\\\\2ndbrain\\\\db\\\\migrations\"\" 2>/dev/null || echo \"No migrations directory \")"
+      "Bash(ls -la \"c:\\\\dev\\\\fingerskier\\\\agent\\\\2ndbrain\\\\db\\\\migrations\"\" 2>/dev/null || echo \"No migrations directory \")",
+      "Bash(node:*)",
+      "Bash(ls -la \"c:\\\\dev\\\\fingerskier\\\\agent\\\\2ndbrain\\\\src\\\\web\"\" 2>/dev/null || echo \"web directory not found \")",
+      "Bash(ls -la \"c:\\\\dev\\\\fingerskier\\\\agent\\\\2ndbrain\\\\db\"\" 2>/dev/null || echo \"Directory not accessible \")",
+      "Bash(npm install:*)"
     ]
   }
 }

package/db/migrations/002_scheduled_tasks.sql

@@ -0,0 +1,25 @@
+-- 002_scheduled_tasks.sql
+-- Scheduled tasks table for the /schedule feature (cron-based task execution)
+
+CREATE TABLE scheduled_tasks (
+  id              SERIAL PRIMARY KEY,
+  created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  chat_id         TEXT NOT NULL,                -- Telegram chat ID for delivering results
+  cron_expression TEXT NOT NULL,                -- Standard 5-field cron: min hour dom month dow
+  task_prompt     TEXT NOT NULL,                -- Prompt sent to Claude when the task fires
+  description     TEXT NOT NULL DEFAULT '',     -- Human-readable description
+  timezone        TEXT NOT NULL DEFAULT 'UTC',  -- IANA timezone (e.g. 'America/New_York')
+  enabled         BOOLEAN NOT NULL DEFAULT TRUE,
+  last_run_at     TIMESTAMPTZ,
+  next_run_at     TIMESTAMPTZ,
+  error_count     INTEGER NOT NULL DEFAULT 0,   -- Consecutive error count for backoff
+  last_error      TEXT                          -- Last error message, if any
+);
+
+CREATE INDEX idx_scheduled_tasks_next_run
+  ON scheduled_tasks (next_run_at)
+  WHERE enabled = TRUE;
+
+CREATE INDEX idx_scheduled_tasks_chat_id
+  ON scheduled_tasks (chat_id);

package/doc/SPEC.md

@@ -103,6 +103,7 @@ See also: §4 (Command Router), §8 (Attachment Store), §14 (Security Model),
 
 Parses incoming messages and routes them:
 - Messages prefixed with `/` are dispatched to slash command handlers
+- Pass-through commands are forwarded to the Claude Bridge where the corresponding skill handles them (§12)
 - All other messages are forwarded to the Claude Bridge (§5)
 
 ### Slash Commands
@@ -115,11 +116,17 @@ Parses incoming messages and routes them:
 | `/restart` | none | Process restart | Confirmation prompt; on confirm, restart process |
 | `/reboot` | none | OS reboot | Confirmation prompt; on confirm, `sudo reboot` |
 | `/new` | none | Start new conversation session | Confirmation; old session preserved in logs |
+| `/project` | optional description | Manage projects, specs, issues | Pass-through to Claude (§12, `project-manage` skill) |
+| `/journal` | optional text | Record or search journal entries | Pass-through to Claude (§12, `journal` skill) |
+| `/knowledge` | optional text | Manage knowledge graph | Pass-through to Claude (§12, `knowledge` skill) |
+| `/schedule` | optional description | Create, list, or manage scheduled tasks | Pass-through to Claude (§12, `scheduler` skill) |
 | `/help` | none | List available commands | Command list with descriptions |
 
 `/restart` and `/reboot` require explicit confirmation reply before execution (see §14.4). `/new` starts a fresh Claude session; the previous session remains accessible in logs and search.
 
-See also: §5 (Claude Bridge), §14.4 (Dangerous Operations)
+**Pass-through commands** (`/project`, `/journal`, `/knowledge`, `/schedule`) are recognized by the command router but not handled locally. Instead, the full message text is forwarded to the Claude Bridge as a conversational message. The corresponding Claude skill (§12) activates on the `/command` prefix and performs the database operations. Pass-through commands go through the normal message flow including rate limiting, conversation persistence, and lifecycle hooks.
+
+See also: §5 (Claude Bridge), §12 (Claude Skills), §14.4 (Dangerous Operations)
 
 
 ## 5. Claude Bridge
@@ -315,6 +322,31 @@ Structured operational logs are written to the `system_logs` table with level (`
 
 See also: §9 (Web Admin Server), §15 (Error Handling), §17.1 (`system_logs` table), §18 (rate limit and log variables)
 
+### 10.2 Scheduler Worker
+
+Background service that executes scheduled tasks defined in the `scheduled_tasks` table (§17.7).
+
+| Property | Value |
+|----------|-------|
+| Poll interval | 60 seconds |
+| Max tasks per tick | 3 |
+| Auto-disable threshold | 5 consecutive errors |
+| Pattern | `EmbeddingWorker` (setTimeout-based polling loop) |
+
+**Execution flow:**
+1. Poll `scheduled_tasks` for rows where `enabled = TRUE AND next_run_at <= NOW()`
+2. Check `ClaudeBridge.isActive()` -- skip if a user message is being processed
+3. Acquire Claude rate limiter slot
+4. Invoke `claude-cli` with the task's `task_prompt` (fresh session per execution)
+5. Deliver the response to the user's Telegram chat, prefixed with `[Scheduled: <description>]`
+6. Compute `next_run_at` using `node-cron` and update the row
+
+**Startup recovery:** On service start, recomputes `next_run_at` for all enabled tasks with NULL or past values. Tasks missed during downtime skip ahead to the next scheduled time (no retroactive execution).
+
+**Error handling:** Consecutive failures increment `error_count`. After 5 failures, the task is auto-disabled and the user is notified via Telegram. Re-enabling via `/schedule` resets the error count.
+
+See also: §12.2 (`scheduler` skill), §17.7 (`scheduled_tasks` table)
+
 
 ## 11. Knowledge Platform
 
@@ -403,6 +435,7 @@ $DATA_DIR/claude-runtime/.claude/skills/
   knowledge/SKILL.md
   project-manage/SKILL.md
   recall/SKILL.md
+  scheduler/SKILL.md
   system-ops/SKILL.md
 ```
 
@@ -507,6 +540,26 @@ Each skill is defined as a `SKILL.md` file containing natural-language instructi
 
 **Restrictions:** This skill provides read-only system access only. It does NOT support restart, reboot, shutdown, or any mutating operations. Those remain exclusive to slash commands with confirmation prompts (§4).
 
+#### `scheduler` -- Scheduled Task Management
+
+| Property | Value |
+|----------|-------|
+| Name | `scheduler` |
+| Description | Create, list, update, and delete scheduled tasks. Parse natural language schedules into cron expressions and persist them for automatic execution. |
+| Invocation | User sends message with `/schedule` preamble, or automatic (Claude detects scheduling intent: "every morning remind me to...", "schedule a daily check on...") |
+| Allowed tools | PostgreSQL MCP (`mcp__pg__query`) |
+| Tables | `scheduled_tasks` |
+
+**Behaviors:**
+- **Create task:** Parse natural language into a 5-field cron expression and task prompt. `INSERT INTO scheduled_tasks (chat_id, cron_expression, task_prompt, description, timezone) VALUES ($1, $2, $3, $4, $5)`. The `chat_id` is obtained from the system prompt context.
+- **List tasks:** `SELECT * FROM scheduled_tasks WHERE chat_id = $1 ORDER BY created_at DESC`
+- **Update task:** `UPDATE scheduled_tasks SET cron_expression = $1, task_prompt = $2, description = $3, next_run_at = NULL, updated_at = NOW() WHERE id = $4 AND chat_id = $5`. Setting `next_run_at = NULL` forces the scheduler worker to recompute it.
+- **Enable/disable:** `UPDATE scheduled_tasks SET enabled = $1, error_count = 0, updated_at = NOW() WHERE id = $2 AND chat_id = $3`
+- **Delete task:** `DELETE FROM scheduled_tasks WHERE id = $1 AND chat_id = $2`
+- **Search tasks:** `SELECT * FROM scheduled_tasks WHERE chat_id = $1 AND (description ILIKE $2 OR task_prompt ILIKE $2)`
+
+**Execution model:** The skill only manages task definitions in the database. Actual execution is performed by the `SchedulerWorker` background service (§10.2), which polls the `scheduled_tasks` table every 60 seconds and invokes `claude-cli` for tasks whose `next_run_at` has passed. After 5 consecutive execution failures, a task is auto-disabled and the user is notified.
+
 
 ## 13. Claude Hooks
 
@@ -864,6 +917,31 @@ CREATE INDEX idx_embeddings_vector
   ON embeddings USING hnsw (vector vector_cosine_ops);
 ```
 
+### 17.7 Scheduled Tasks
+
+```sql
+CREATE TABLE scheduled_tasks (
+  id              SERIAL PRIMARY KEY,
+  created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  chat_id         TEXT NOT NULL,                -- Telegram chat ID for delivering results
+  cron_expression TEXT NOT NULL,                -- Standard 5-field cron: min hour dom month dow
+  task_prompt     TEXT NOT NULL,                -- Prompt sent to Claude when the task fires
+  description     TEXT NOT NULL DEFAULT '',     -- Human-readable description
+  timezone        TEXT NOT NULL DEFAULT 'UTC',  -- IANA timezone (e.g. 'America/New_York')
+  enabled         BOOLEAN NOT NULL DEFAULT TRUE,
+  last_run_at     TIMESTAMPTZ,
+  next_run_at     TIMESTAMPTZ,                 -- Pre-computed by SchedulerWorker
+  error_count     INTEGER NOT NULL DEFAULT 0,   -- Consecutive error count for backoff
+  last_error      TEXT                          -- Last error message, if any
+);
+
+CREATE INDEX idx_scheduled_tasks_next_run
+  ON scheduled_tasks (next_run_at) WHERE enabled = TRUE;
+CREATE INDEX idx_scheduled_tasks_chat_id
+  ON scheduled_tasks (chat_id);
+```
+
 
 ## 18. Configuration Reference
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "2ndbrain",
-  "version": "2026.1.32",
+  "version": "2026.1.34",
   "description": "Always-on Node.js service bridging Telegram messaging to Claude AI with knowledge graph, journal, project management, and semantic search.",
   "main": "src/index.js",
   "bin": {
@@ -15,7 +15,13 @@
     "type": "git",
     "url": "git+https://github.com/fingerskier/2ndbrain.git"
   },
-  "keywords": ["telegram", "claude", "ai", "assistant", "knowledge-graph"],
+  "keywords": [
+    "telegram",
+    "claude",
+    "ai",
+    "assistant",
+    "knowledge-graph"
+  ],
   "author": "",
   "license": "MIT",
   "bugs": {
@@ -25,6 +31,7 @@
   "dependencies": {
     "dotenv": "^16.4.7",
     "express": "^4.21.2",
+    "node-cron": "^4.2.1",
     "open": "^10.1.0",
     "pg": "^8.13.1"
   },

package/skills/project-manage/SKILL.md

@@ -57,6 +57,86 @@ No other tools are permitted for this skill.
 
 ## Operations
 
+### List All Projects (No Arguments)
+
+When the user sends `/project` with no additional text, list all projects with status:
+
+```sql
+SELECT
+  p.id,
+  p.name,
+  p.created_at,
+  COUNT(i.id) FILTER (WHERE NOT i.completed) AS open_issues,
+  COUNT(i.id) FILTER (WHERE i.completed) AS closed_issues,
+  COUNT(DISTINCT s.id) AS spec_count
+FROM projects p
+LEFT JOIN issues i ON i.project_id = p.id
+LEFT JOIN specifications s ON s.project_id = p.id
+GROUP BY p.id, p.name, p.created_at
+ORDER BY p.updated_at DESC;
+```
+
+Present as a concise listing. If no projects exist, respond: "No projects found. Send `/project <description>` to create one."
+
+### Parse and Scaffold from Description
+
+When the user sends `/project` followed by a natural language description, parse it and create the appropriate database records:
+
+1. **Extract the project name** from the description. Use the most prominent noun phrase or explicit project name.
+
+2. **Check for existing project** (case-insensitive):
+
+```sql
+SELECT id, name FROM projects WHERE name ILIKE '%project name%';
+```
+
+   - If a match exists, use the existing project ID (do not create a duplicate).
+   - If multiple matches, list them and ask the user to clarify.
+   - If no match, create a new project.
+
+3. **Extract specifications** -- any requirements, constraints, architecture decisions, API contracts, or design notes from the description. Insert each:
+
+```sql
+INSERT INTO specifications (project_id, note)
+VALUES (<project_id>, 'extracted specification')
+RETURNING id, note;
+```
+
+   Use `parent_id` when specifications have a natural parent-child hierarchy.
+
+4. **Extract issues/tasks** -- any action items, features to build, bugs to fix, or work items. Insert each:
+
+```sql
+INSERT INTO issues (project_id, note)
+VALUES (<project_id>, 'extracted task or issue')
+RETURNING id, note;
+```
+
+   Use `parent_id` when tasks have a natural hierarchy.
+
+5. **Upsert behavior:** Before inserting a specification or issue, check if one with very similar text already exists for this project:
+
+```sql
+SELECT id, note FROM specifications WHERE project_id = <project_id> AND note ILIKE '%key phrase%';
+SELECT id, note FROM issues WHERE project_id = <project_id> AND note ILIKE '%key phrase%';
+```
+
+   If a match exists, skip it (note as "already exists" in the summary). Do not delete existing records.
+
+6. **Respond with a summary** of everything created or found:
+
+```
+Project: <name> (id: <id>) [created | existing]
+
+Specifications:
+- <spec note> (id: <id>)
+- <spec note> (id: <id>) [already exists]
+
+Issues:
+- <issue note> (id: <id>)
+- <issue note> (id: <id>) [already exists]
+```
+
 ### Create a Project
 
 When the user wants to start tracking a new project.

package/skills/scheduler/SKILL.md

@@ -0,0 +1,207 @@
+# Skill: scheduler
+
+## Description
+
+Create, list, update, and delete scheduled tasks. Use this skill when the user wants to set up recurring actions that run on a cron schedule. The user describes the task and schedule in natural language; you parse it into a cron expression and a task prompt, then persist it to the database. A background worker executes each task at its scheduled time by sending the prompt to Claude and delivering the response to the user's Telegram chat.
+
+## When to Activate
+
+Activate this skill when any of the following conditions are met:
+
+- The user's message begins with `/schedule`
+- The user wants to set up a recurring task (e.g., "every morning remind me to...", "schedule a daily check on...", "run this every Monday")
+- The user asks about their scheduled tasks (e.g., "what's scheduled", "list my schedules", "show my cron jobs")
+- The user wants to modify or cancel a scheduled task (e.g., "stop the daily reminder", "change the schedule to weekly", "disable schedule #3")
+
+## Available Tools
+
+- `mcp__pg__query` -- Execute SQL queries against the PostgreSQL database.
+
+No other tools are permitted for this skill.
+
+## Context
+
+The current Telegram `chat_id` is provided in the system prompt as `Current Telegram chat_id: <value>`. You MUST use this value when inserting or querying scheduled tasks to scope operations to the current user's chat.
+
+## Database Tables
+
+### `scheduled_tasks`
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `id` | SERIAL PRIMARY KEY | Auto-incrementing identifier |
+| `created_at` | TIMESTAMPTZ | Timestamp of creation |
+| `updated_at` | TIMESTAMPTZ | Timestamp of last update |
+| `chat_id` | TEXT NOT NULL | Telegram chat ID (from system prompt) |
+| `cron_expression` | TEXT NOT NULL | Standard 5-field cron: minute hour day-of-month month day-of-week |
+| `task_prompt` | TEXT NOT NULL | The prompt sent to Claude when the task fires |
+| `description` | TEXT NOT NULL DEFAULT '' | Human-readable description of the task |
+| `timezone` | TEXT NOT NULL DEFAULT 'UTC' | IANA timezone for cron evaluation |
+| `enabled` | BOOLEAN NOT NULL DEFAULT TRUE | Whether the task is active |
+| `last_run_at` | TIMESTAMPTZ | When the task last executed |
+| `next_run_at` | TIMESTAMPTZ | Pre-computed next execution time |
+| `error_count` | INTEGER NOT NULL DEFAULT 0 | Consecutive error count |
+| `last_error` | TEXT | Most recent error message |
+
+## Cron Expression Reference
+
+Standard 5-field cron format: `minute hour day-of-month month day-of-week`
+
+| Field | Values | Special Characters |
+|-------|--------|--------------------|
+| Minute | 0-59 | `*` `,` `-` `/` |
+| Hour | 0-23 | `*` `,` `-` `/` |
+| Day of Month | 1-31 | `*` `,` `-` `/` |
+| Month | 1-12 | `*` `,` `-` `/` |
+| Day of Week | 0-6 (0=Sunday) | `*` `,` `-` `/` |
+
+### Common Patterns
+
+| Natural Language | Cron Expression |
+|-----------------|-----------------|
+| every day at 8am | `0 8 * * *` |
+| every weekday at 9am | `0 9 * * 1-5` |
+| every Monday at 10am | `0 10 * * 1` |
+| every hour | `0 * * * *` |
+| every 30 minutes | `*/30 * * * *` |
+| every 15 minutes | `*/15 * * * *` |
+| first of every month at noon | `0 12 1 * *` |
+| every Sunday at 6pm | `0 18 * * 0` |
+| twice a day (8am and 8pm) | `0 8,20 * * *` |
+| every weekday at 5pm | `0 17 * * 1-5` |
+| every 6 hours | `0 */6 * * *` |
+
+## Operations
+
+### List All Scheduled Tasks (No Arguments)
+
+When the user sends `/schedule` with no additional text, list all their tasks:
+
+```sql
+SELECT id, description, cron_expression, timezone, enabled,
+       last_run_at, next_run_at, error_count, last_error
+FROM scheduled_tasks
+WHERE chat_id = '<chat_id>'
+ORDER BY created_at DESC;
+```
+
+Present as a concise listing showing: ID, description, schedule (human-readable interpretation of the cron), enabled status, and next run time. If no tasks exist, respond: "No scheduled tasks found. Send `/schedule <description>` to create one."
+
+Example format:
+```
+Your Scheduled Tasks:
+
+#1 - Check project status
+  Schedule: Every day at 8:00 AM (UTC)
+  Status: Enabled
+  Next run: 2026-02-01 08:00 UTC
+
+#2 - Weekly team summary
+  Schedule: Every Monday at 9:00 AM (America/New_York)
+  Status: Disabled (5 errors)
+  Last error: Claude subprocess timed out
+```
+
+### Create a Scheduled Task
+
+When the user sends `/schedule` followed by a natural language description, parse it:
+
+1. **Extract the schedule** from the natural language and convert to a 5-field cron expression.
+2. **Extract the task prompt** -- this is what Claude will be asked to do when the task fires. Formulate it as a clear, actionable prompt. For example, if the user says "remind me to check my project status", the task prompt should be something like: "Check my project status and give me a summary of open issues across all projects."
+3. **Extract or infer the timezone** -- if the user mentions a timezone, use it. Otherwise default to UTC. If unclear, ask.
+4. **Write a human-readable description** summarizing the task.
+
+```sql
+INSERT INTO scheduled_tasks (chat_id, cron_expression, task_prompt, description, timezone)
+VALUES ('<chat_id>', '<cron>', '<task_prompt>', '<description>', '<timezone>')
+RETURNING id, cron_expression, task_prompt, description, timezone;
+```
+
+After creating, confirm with the user:
+```
+Scheduled task created:
+  #<id> - <description>
+  Schedule: <human-readable cron interpretation> (<timezone>)
+  Prompt: "<task_prompt>"
+
+The task will first run at <next computed time>. The background scheduler picks up new tasks within 60 seconds.
+```
+
+**Important:** Do NOT set `next_run_at` yourself. The background scheduler worker computes and sets `next_run_at` automatically when it detects new tasks with a NULL `next_run_at`.
+
+### Update a Scheduled Task
+
+When the user wants to change the schedule, prompt, or description of an existing task.
+
+First, verify the task belongs to this chat:
+
+```sql
+SELECT id, description, cron_expression, task_prompt, timezone
+FROM scheduled_tasks
+WHERE id = <task_id> AND chat_id = '<chat_id>';
+```
+
+Then update the requested fields:
+
+```sql
+UPDATE scheduled_tasks
+SET cron_expression = '<new_cron>',
+    task_prompt = '<new_prompt>',
+    description = '<new_description>',
+    timezone = '<new_timezone>',
+    next_run_at = NULL,
+    updated_at = NOW()
+WHERE id = <task_id> AND chat_id = '<chat_id>';
+```
+
+Setting `next_run_at = NULL` forces the scheduler worker to recompute it on the next poll.
+
+### Enable / Disable a Task
+
+```sql
+UPDATE scheduled_tasks
+SET enabled = TRUE, error_count = 0, last_error = NULL,
+    next_run_at = NULL, updated_at = NOW()
+WHERE id = <task_id> AND chat_id = '<chat_id>';
+```
+
+```sql
+UPDATE scheduled_tasks
+SET enabled = FALSE, updated_at = NOW()
+WHERE id = <task_id> AND chat_id = '<chat_id>';
+```
+
+When re-enabling, reset `error_count` and `last_error`, and set `next_run_at = NULL` so the scheduler recomputes it.
+
+### Delete a Scheduled Task
+
+When the user wants to permanently remove a task.
+
+```sql
+DELETE FROM scheduled_tasks
+WHERE id = <task_id> AND chat_id = '<chat_id>';
+```
+
+Confirm deletion to the user. If the task ID does not exist or does not belong to this chat, say so.
+
+### Search Scheduled Tasks
+
+```sql
+SELECT id, description, cron_expression, timezone, enabled
+FROM scheduled_tasks
+WHERE chat_id = '<chat_id>'
+  AND (description ILIKE '%' || '<search_term>' || '%'
+       OR task_prompt ILIKE '%' || '<search_term>' || '%')
+ORDER BY created_at DESC;
+```
+
+## Restrictions and Notes
+
+- Always use `mcp__pg__query` for database operations. Do not use any other tool.
+- Always scope queries with `chat_id = '<chat_id>'` using the chat ID from the system prompt. Never access another chat's tasks.
+- When the user refers to a task by number (e.g., "disable #3" or "delete task 3"), use that as the `id`.
+- If the user's schedule description is ambiguous (e.g., "every morning" -- what time exactly?), ask for clarification rather than guessing.
+- The cron expression must be valid 5-field format. Do not use 6-field (with seconds) or non-standard extensions.
+- When listing tasks, always translate the cron expression into human-readable language (e.g., `0 8 * * 1-5` = "Every weekday at 8:00 AM").
+- Task prompts should be self-contained and actionable -- the Claude instance executing them will not have the original conversation context. Write prompts that make sense in isolation.
+- Do not set or modify `next_run_at`, `last_run_at`, `error_count`, or `last_error` when creating or updating tasks. These are managed by the scheduler worker.

package/src/config.js

@@ -60,6 +60,19 @@ const config = {
   EMBEDDING_BASE_URL: env.EMBEDDING_BASE_URL || '',
 };
 
+// Ensure DATABASE_URL includes a database name (default: 2ndbrain)
+if (config.DATABASE_URL) {
+  try {
+    const url = new URL(config.DATABASE_URL);
+    if (!url.pathname || url.pathname === '/') {
+      url.pathname = '/2ndbrain';
+      config.DATABASE_URL = url.toString();
+    }
+  } catch {
+    // leave as-is if URL parsing fails
+  }
+}
+
 const REQUIRED_VARS = ['TELEGRAM_BOT_TOKEN', 'TELEGRAM_ALLOWED_USERS', 'DATABASE_URL'];
 
 /**

package/src/db/pool.js

@@ -12,6 +12,40 @@ pool.on('error', (err) => {
   console.error(`[${new Date().toISOString()}] [error] [db/pool] Unexpected idle client error:`, err.message);
 });
 
+/**
+ * Ensure the target database exists, creating it if necessary.
+ * Connects to the 'postgres' maintenance database to check/create.
+ */
+async function ensureDatabase() {
+  try {
+    const url = new URL(config.DATABASE_URL);
+    const dbName = url.pathname.slice(1); // strip leading '/'
+    if (!dbName) return;
+
+    // Build a maintenance URL pointing at the 'postgres' system database
+    const maintenanceUrl = new URL(config.DATABASE_URL);
+    maintenanceUrl.pathname = '/postgres';
+
+    const client = new pg.Client({ connectionString: maintenanceUrl.toString() });
+    await client.connect();
+
+    const result = await client.query(
+      'SELECT 1 FROM pg_database WHERE datname = $1',
+      [dbName],
+    );
+
+    if (result.rows.length === 0) {
+      // Use double-quoted identifier to handle special characters in name
+      await client.query(`CREATE DATABASE "${dbName}"`);
+      console.log(`[${new Date().toISOString()}] [info] [db/pool] Created database "${dbName}".`);
+    }
+
+    await client.end();
+  } catch (err) {
+    console.error(`[${new Date().toISOString()}] [error] [db/pool] ensureDatabase failed: ${err.message}`);
+  }
+}
+
 /**
  * Execute a parameterized SQL query against the pool.
  * @param {string} text - SQL query string
@@ -29,5 +63,5 @@ async function close() {
   await pool.end();
 }
 
-export { pool, query, close };
+export { pool, query, close, ensureDatabase };
 export default pool;

package/src/hooks/lifecycle.js

@@ -239,6 +239,11 @@ class LifecycleHooks extends EventEmitter {
         ctx.systemPrompt = dateContext;
       }
 
+      // Inject chat_id for skills that need it (e.g., scheduler)
+      if (ctx.chatId) {
+        ctx.systemPrompt += `\nCurrent Telegram chat_id: ${ctx.chatId}`;
+      }
+
       // Assemble conversation context from recent history if db is available
       if (db && ctx.includeHistory !== false) {
         try {

package/src/index.js

@@ -20,7 +20,7 @@ import path from 'node:path';
 import fs from 'node:fs';
 
 import { config, validateConfig, isFirstRun, PROJECT_ROOT } from './config.js';
-import { pool, query, close as closeDb } from './db/pool.js';
+import { pool, query, close as closeDb, ensureDatabase } from './db/pool.js';
 import { migrate } from './db/migrate.js';
 import logger from './logging.js';
 import { createRateLimiters } from './rate-limiter.js';
@@ -34,6 +34,7 @@ import { createEmbedTool } from './mcp/embed-server.js';
 import { AttachmentStore } from './attachments/store.js';
 import { EmbeddingsEngine } from './embeddings/engine.js';
 import { EmbeddingWorker } from './embeddings/worker.js';
+import { SchedulerWorker } from './scheduler/worker.js';
 import { WebServer } from './web/server.js';
 
 // ---------------------------------------------------------------------------
@@ -44,6 +45,7 @@ const startTime = Date.now();
 let bot = null;
 let webServer = null;
 let embeddingWorker = null;
+let schedulerWorker = null;
 let embedTool = null;
 let shuttingDown = false;
 
@@ -178,6 +180,7 @@ async function handleMessage(message, deps) {
       message: text,
       systemPrompt: '',
       sessionId: conversationManager.currentSessionId,
+      chatId,
     });
 
     if (preResult.aborted) {
@@ -296,6 +299,10 @@ async function shutdown(signal) {
     try { embeddingWorker.stop(); } catch { /* ignore */ }
   }
 
+  if (schedulerWorker) {
+    try { schedulerWorker.stop(); } catch { /* ignore */ }
+  }
+
   if (embedTool?.server) {
     try { embedTool.server.close(); } catch { /* ignore */ }
   }
@@ -329,6 +336,7 @@ async function main() {
   let dbReady = false;
   if (config.DATABASE_URL) {
     try {
+      await ensureDatabase();
       await pool.query('SELECT 1');
       logger.info('startup', 'Database connection established.');
       dbReady = true;
@@ -515,6 +523,19 @@ async function main() {
     embeddingWorker.start();
   }
 
+  // Start background scheduler worker
+  if (dbReady && bot) {
+    schedulerWorker = new SchedulerWorker({
+      db: { query },
+      config,
+      logger,
+      claudeBridge,
+      bot,
+      rateLimiters,
+    });
+    schedulerWorker.start();
+  }
+
   // Step 8: Set signal handlers
   process.on('SIGTERM', () => shutdown('SIGTERM'));
   process.on('SIGINT', () => shutdown('SIGINT'));

package/src/scheduler/worker.js

@@ -0,0 +1,320 @@
+import cron from 'node-cron';
+
+/** Milliseconds between processing iterations (1 minute). */
+const POLL_INTERVAL_MS = 60_000;
+
+/** Maximum tasks to execute per poll cycle. */
+const MAX_TASKS_PER_TICK = 3;
+
+/** Consecutive errors before auto-disabling a task. */
+const MAX_CONSECUTIVE_ERRORS = 5;
+
+/** Maximum minutes to scan forward when computing next run (366 days). */
+const MAX_SCAN_MINUTES = 366 * 24 * 60;
+
+/**
+ * Compute the next Date after `from` that matches the cron expression.
+ *
+ * Uses node-cron's internal timeMatcher to check each minute. Scans up
+ * to ~366 days forward before giving up.
+ *
+ * @param {string} cronExpression - 5-field cron expression
+ * @param {Date} from - Start searching from this date (exclusive)
+ * @param {string} [timezone='UTC'] - IANA timezone for evaluation
+ * @returns {Date|null} Next matching date, or null if none found
+ */
+function nextCronDate(cronExpression, from, timezone = 'UTC') {
+  // Create a temporary task just to access the timeMatcher
+  const task = cron.schedule(cronExpression, () => {}, {
+    scheduled: false,
+    timezone,
+  });
+
+  const matcher = task.timeMatcher;
+
+  // Start from the next whole minute after `from`
+  const candidate = new Date(from.getTime());
+  candidate.setSeconds(0, 0);
+  candidate.setMinutes(candidate.getMinutes() + 1);
+
+  for (let i = 0; i < MAX_SCAN_MINUTES; i++) {
+    if (matcher.match(candidate)) {
+      return new Date(candidate.getTime());
+    }
+    candidate.setMinutes(candidate.getMinutes() + 1);
+  }
+
+  return null;
+}
+
+/**
+ * Background scheduler worker -- periodically checks for scheduled tasks
+ * whose next_run_at has passed, executes them via the Claude bridge,
+ * and delivers results to the user's Telegram chat.
+ *
+ * Follows the EmbeddingWorker pattern (§11.4): setTimeout-based polling
+ * loop with overlap guard.
+ */
+class SchedulerWorker {
+  /**
+   * @param {object} deps
+   * @param {object} deps.db            - Database query interface ({ query(sql, params) })
+   * @param {object} deps.config        - Application configuration
+   * @param {object} deps.logger        - Logger instance
+   * @param {import('../claude/bridge.js').ClaudeBridge} deps.claudeBridge - Claude CLI bridge
+   * @param {import('../telegram/bot.js').TelegramBot} deps.bot - Telegram bot instance
+   * @param {object} deps.rateLimiters  - { claude: RateLimiter, ... }
+   */
+  constructor({ db, config, logger, claudeBridge, bot, rateLimiters }) {
+    this.db = db;
+    this.config = config;
+    this.logger = logger;
+    this.claudeBridge = claudeBridge;
+    this.bot = bot;
+    this.rateLimiters = rateLimiters;
+
+    /** @type {ReturnType<typeof setTimeout>|null} */
+    this._timer = null;
+
+    /** Whether the worker loop is active. */
+    this._running = false;
+
+    /** Guard to prevent overlapping iterations. */
+    this._processing = false;
+  }
+
+  /**
+   * Start the periodic scheduler worker loop.
+   * Initializes next_run_at for any tasks that need it, then begins polling.
+   */
+  async start() {
+    if (this._running) {
+      return;
+    }
+
+    this._running = true;
+    this.logger.info('scheduler', 'Starting background scheduler worker.');
+
+    try {
+      await this._initializeNextRuns();
+    } catch (err) {
+      this.logger.error('scheduler', `Failed to initialize next runs: ${err.message}`);
+    }
+
+    this._scheduleNext();
+  }
+
+  /**
+   * Stop the worker loop gracefully. Any in-flight iteration will finish
+   * before the loop fully halts.
+   */
+  stop() {
+    this._running = false;
+
+    if (this._timer !== null) {
+      clearTimeout(this._timer);
+      this._timer = null;
+    }
+
+    this.logger.info('scheduler', 'Scheduler worker stopped.');
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
+
+  /**
+   * On startup, compute next_run_at for tasks that have NULL or past values.
+   * Tasks missed during downtime skip ahead to the next valid time (no
+   * retroactive execution).
+   */
+  async _initializeNextRuns() {
+    const result = await this.db.query(
+      `SELECT id, cron_expression, timezone
+       FROM scheduled_tasks
+       WHERE enabled = TRUE
+         AND (next_run_at IS NULL OR next_run_at < NOW())`,
+    );
+
+    if (result.rows.length === 0) {
+      return;
+    }
+
+    this.logger.info('scheduler', `Recomputing next_run_at for ${result.rows.length} task(s).`);
+
+    for (const row of result.rows) {
+      try {
+        if (!cron.validate(row.cron_expression)) {
+          this.logger.warn('scheduler', `Invalid cron expression for task ${row.id}: "${row.cron_expression}"; skipping.`);
+          continue;
+        }
+
+        const nextRun = nextCronDate(row.cron_expression, new Date(), row.timezone);
+        if (nextRun) {
+          await this.db.query(
+            'UPDATE scheduled_tasks SET next_run_at = $1, updated_at = NOW() WHERE id = $2',
+            [nextRun.toISOString(), row.id],
+          );
+        }
+      } catch (err) {
+        this.logger.warn('scheduler', `Failed to compute next_run_at for task ${row.id}: ${err.message}`);
+      }
+    }
+  }
+
+  /**
+   * Schedule the next processing iteration after POLL_INTERVAL_MS.
+   */
+  _scheduleNext() {
+    if (!this._running) {
+      return;
+    }
+
+    this._timer = setTimeout(async () => {
+      this._timer = null;
+
+      // Skip if the previous iteration is still running
+      if (this._processing) {
+        this._scheduleNext();
+        return;
+      }
+
+      // Skip if Claude is busy with a user message
+      if (this.claudeBridge.isActive()) {
+        this.logger.debug('scheduler', 'Skipping tick: Claude subprocess is active.');
+        this._scheduleNext();
+        return;
+      }
+
+      try {
+        this._processing = true;
+        await this._processQueue();
+      } catch (err) {
+        this.logger.error('scheduler', `Unexpected error in worker loop: ${err.message}`);
+      } finally {
+        this._processing = false;
+        this._scheduleNext();
+      }
+    }, POLL_INTERVAL_MS);
+  }
+
+  /**
+   * Fetch and execute tasks whose next_run_at has passed.
+   */
+  async _processQueue() {
+    const result = await this.db.query(
+      `SELECT id, chat_id, cron_expression, task_prompt, description, timezone, error_count
+       FROM scheduled_tasks
+       WHERE enabled = TRUE
+         AND next_run_at IS NOT NULL
+         AND next_run_at <= NOW()
+       ORDER BY next_run_at ASC
+       LIMIT $1`,
+      [MAX_TASKS_PER_TICK],
+    );
+
+    if (result.rows.length === 0) {
+      return;
+    }
+
+    this.logger.info('scheduler', `Processing ${result.rows.length} scheduled task(s).`);
+
+    for (const row of result.rows) {
+      // Re-check if Claude became active between tasks
+      if (this.claudeBridge.isActive()) {
+        this.logger.debug('scheduler', 'Pausing task execution: Claude became active.');
+        break;
+      }
+
+      try {
+        await this._executeTask(row);
+      } catch (err) {
+        this.logger.error('scheduler', `Failed to execute task ${row.id}: ${err.message}`);
+      }
+    }
+  }
+
+  /**
+   * Execute a single scheduled task: invoke Claude, send the response,
+   * and update next_run_at.
+   *
+   * @param {object} row - Database row from scheduled_tasks
+   */
+  async _executeTask(row) {
+    const { id, chat_id, cron_expression, task_prompt, description, timezone, error_count } = row;
+
+    try {
+      // Respect the Claude rate limiter
+      await this.rateLimiters.claude.acquire();
+
+      // Show typing indicator
+      await this.bot.sendTyping(chat_id);
+
+      // Invoke Claude with a fresh session
+      const systemPrompt = `You are executing a scheduled task. Task description: ${description}. Provide a helpful, concise response.`;
+      const result = await this.claudeBridge.invoke(task_prompt, null, systemPrompt);
+
+      // Deliver the response
+      const responseText = result.text || 'Scheduled task completed (no output).';
+      const header = `[Scheduled: ${description}]\n\n`;
+      await this.bot.sendMessage(chat_id, header + responseText, {
+        parse_mode: undefined,
+      });
+
+      // Compute the next run time
+      const nextRun = nextCronDate(cron_expression, new Date(), timezone);
+
+      await this.db.query(
+        `UPDATE scheduled_tasks
+         SET last_run_at = NOW(),
+             next_run_at = $1,
+             error_count = 0,
+             last_error = NULL,
+             updated_at = NOW()
+         WHERE id = $2`,
+        [nextRun ? nextRun.toISOString() : null, id],
+      );
+
+      this.logger.info('scheduler', `Task ${id} ("${description}") executed. Next run: ${nextRun?.toISOString() || 'none'}`);
+    } catch (err) {
+      // Record the error and possibly auto-disable
+      const newErrorCount = error_count + 1;
+      const shouldDisable = newErrorCount >= MAX_CONSECUTIVE_ERRORS;
+
+      // Still compute next_run_at so a re-enabled task doesn't fire immediately
+      let nextRun = null;
+      try {
+        nextRun = nextCronDate(cron_expression, new Date(), timezone);
+      } catch { /* ignore parse errors during error handling */ }
+
+      await this.db.query(
+        `UPDATE scheduled_tasks
+         SET error_count = $1,
+             last_error = $2,
+             enabled = $3,
+             next_run_at = $4,
+             updated_at = NOW()
+         WHERE id = $5`,
+        [newErrorCount, err.message, !shouldDisable, nextRun ? nextRun.toISOString() : null, id],
+      );
+
+      if (shouldDisable) {
+        this.logger.warn('scheduler', `Task ${id} auto-disabled after ${MAX_CONSECUTIVE_ERRORS} consecutive errors.`);
+
+        // Notify the user
+        try {
+          await this.bot.sendMessage(
+            chat_id,
+            `Your scheduled task "${description}" has been disabled after ${MAX_CONSECUTIVE_ERRORS} consecutive failures.\n\nLast error: ${err.message}\n\nUse /schedule to re-enable it.`,
+            { parse_mode: undefined },
+          );
+        } catch { /* best-effort notification */ }
+      }
+
+      throw err;
+    }
+  }
+}
+
+export { SchedulerWorker, nextCronDate };
+export default SchedulerWorker;

package/src/telegram/commands.js

@@ -4,6 +4,13 @@ import { escapeMarkdownV2 } from './bot.js';
 /** How long a confirmation remains valid (ms). */
 const CONFIRMATION_TTL_MS = 60_000;
 
+/**
+ * Commands that are forwarded to Claude instead of handled by the router.
+ * The corresponding Claude skill activates on the `/command` prefix.
+ * @type {Set<string>}
+ */
+const PASSTHROUGH_COMMANDS = new Set(['/project', '/journal', '/knowledge', '/schedule']);
+
 /**
  * Descriptions shown by the /help command.
  * @type {Record<string, string>}
@@ -15,6 +22,10 @@ const COMMAND_DESCRIPTIONS = {
   '/restart': 'Restart the service process',
   '/reboot': 'Reboot the host operating system',
   '/new': 'Start a new conversation session',
+  '/project': 'Manage projects, specs, and issues (handled by Claude)',
+  '/journal': 'Record and search journal entries (handled by Claude)',
+  '/knowledge': 'Manage knowledge graph (handled by Claude)',
+  '/schedule': 'Create, list, or manage scheduled tasks (handled by Claude)',
   '/help': 'List available commands',
 };
 
@@ -91,6 +102,11 @@ class CommandRouter {
     // Extract the command name (everything up to the first space or @)
     const command = trimmed.split(/[\s@]/)[0].toLowerCase();
 
+    // Skill-managed commands pass through to Claude
+    if (PASSTHROUGH_COMMANDS.has(command)) {
+      return false;
+    }
+
     const replyOpts = { reply_to_message_id: messageId, parse_mode: undefined };
 
     try {
@@ -436,5 +452,5 @@ class CommandRouter {
   }
 }
 
-export { CommandRouter, COMMAND_DESCRIPTIONS };
+export { CommandRouter, COMMAND_DESCRIPTIONS, PASSTHROUGH_COMMANDS };
 export default CommandRouter;

package/src/web/server.js

@@ -187,8 +187,10 @@ class WebServer {
         'SELECT COUNT(*)::int AS count FROM conversation_messages',
       );
       data.messageCount = countRes.rows[0]?.count ?? 0;
-    } catch {
+    } catch (err) {
       data.dbAvailable = false;
+      data.dbError = diagnosePgError(err);
+      this._logger.error('web', `Dashboard DB error: ${err.message} (code=${err.code || 'none'})`);
     }
 
     if (data.dbAvailable) {
@@ -299,14 +301,19 @@ class WebServer {
 
     try {
       await this._db.query('SELECT 1');
-    } catch {
-      health.components.database = 'error';
+    } catch (err) {
+      health.components.database = {
+        status: 'error',
+        error: err.message || 'Unknown error',
+        code: err.code || undefined,
+      };
     }
 
     // Derive overall status from component states
     const states = Object.values(health.components);
-    if (states.includes('error')) {
-      health.status = states.every((s) => s === 'error') ? 'error' : 'degraded';
+    const isErr = (s) => s === 'error' || (typeof s === 'object' && s.status === 'error');
+    if (states.some(isErr)) {
+      health.status = states.every(isErr) ? 'error' : 'degraded';
     }
 
     const httpStatus = health.status === 'error' ? 503 : 200;
@@ -351,7 +358,7 @@ class WebServer {
 
       const tablesResult = await this._db.query(`
         SELECT
-          relname AS name,
+          c.relname AS name,
           n_live_tup AS row_count,
           pg_size_pretty(pg_total_relation_size(c.oid)) AS size
         FROM pg_class c
@@ -372,7 +379,9 @@ class WebServer {
       data.dbSize = sizeResult.rows[0]?.size || '';
     } catch (err) {
       data.dbAvailable = false;
-      this._logger.error('web', `Database page error: ${err.message}`);
+      data.dbError = diagnosePgError(err);
+      data.dbUrl = maskDatabaseUrl(this._config.DATABASE_URL);
+      this._logger.error('web', `Database page error: ${err.message} (code=${err.code || 'none'})`);
     }
 
     res.send(databaseHTML(data));
@@ -499,6 +508,83 @@ function maskValue(value) {
   return s.slice(0, 4) + '*'.repeat(Math.min(s.length - 8, 20)) + s.slice(-4);
 }
 
+/** Mask the password in a PostgreSQL connection URL for safe display. */
+function maskDatabaseUrl(url) {
+  if (!url) return '(not set)';
+  const schemeEnd = url.indexOf('://');
+  const lastAt = url.lastIndexOf('@');
+  if (schemeEnd >= 0 && lastAt > schemeEnd) {
+    const userInfo = url.slice(schemeEnd + 3, lastAt);
+    const colonPos = userInfo.indexOf(':');
+    if (colonPos >= 0) {
+      return url.slice(0, schemeEnd + 3 + colonPos + 1) + '****' + url.slice(lastAt);
+    }
+  }
+  return maskValue(url);
+}
+
+/**
+ * Extract diagnostic information from a pg / Node.js connection error.
+ * Returns { message, code, detail, hint, diagnosis }.
+ */
+function diagnosePgError(err) {
+  const info = {
+    message: err.message || 'Unknown error',
+    code: err.code || '',
+    detail: err.detail || '',
+    hint: err.hint || '',
+    diagnosis: '',
+  };
+
+  switch (err.code) {
+    case 'ECONNREFUSED':
+      info.diagnosis = 'Cannot connect to the database server. Verify the host and port are correct and that PostgreSQL is running.';
+      break;
+    case 'ENOTFOUND':
+      info.diagnosis = 'DNS lookup failed. The database hostname could not be resolved. Check the host in your DATABASE_URL.';
+      break;
+    case 'ETIMEDOUT':
+      info.diagnosis = 'Connection timed out. The database server may be unreachable or behind a firewall.';
+      break;
+    case 'ECONNRESET':
+      info.diagnosis = 'Connection was reset by the server. This may indicate a network issue or server restart.';
+      break;
+    default:
+      break;
+  }
+
+  if (!info.diagnosis && typeof err.code === 'string' && err.code.length === 5) {
+    const cls = err.code.substring(0, 2);
+    switch (cls) {
+      case '08':
+        info.diagnosis = 'Connection exception. The database server rejected or dropped the connection.';
+        break;
+      case '28':
+        info.diagnosis = 'Authentication failed. Check the username and password in your DATABASE_URL.';
+        break;
+      case '3D':
+        info.diagnosis = 'The specified database does not exist. Verify the database name in your DATABASE_URL.';
+        break;
+      case '53':
+        info.diagnosis = 'The database server has insufficient resources (too many connections, out of memory, or disk full).';
+        break;
+      case '57':
+        info.diagnosis = 'The database server is shutting down or not accepting connections.';
+        break;
+      default:
+        break;
+    }
+  }
+
+  if (!info.diagnosis && err.message) {
+    if (/ssl/i.test(err.message) || /certificate/i.test(err.message)) {
+      info.diagnosis = 'SSL/TLS error. Check your SSL configuration or try adding ?sslmode=require or ?sslmode=no-verify to your DATABASE_URL.';
+    }
+  }
+
+  return info;
+}
+
 // ---------------------------------------------------------------------------
 // HTML template functions
 // ---------------------------------------------------------------------------
@@ -670,6 +756,28 @@ function layoutHTML(title, content) {
     font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
     margin-bottom: 0.25rem;
   }
+  .secret-input-wrapper {
+    position: relative;
+  }
+  .secret-input-wrapper input {
+    padding-right: 2.5rem;
+  }
+  .secret-toggle {
+    position: absolute;
+    right: 0.4rem;
+    top: 50%;
+    transform: translateY(-50%);
+    background: none;
+    border: none;
+    color: #8b949e;
+    cursor: pointer;
+    padding: 0.2rem;
+    font-size: 0.85rem;
+    line-height: 1;
+  }
+  .secret-toggle:hover {
+    color: #c9d1d9;
+  }
   .checkbox-group {
     display: flex;
     align-items: center;
@@ -828,9 +936,17 @@ function dashboardHTML(data) {
   </div>`;
 
   // -- DB warning ----------------------------------------------------------
-  const dbWarn = data.dbAvailable
-    ? ''
-    : '<div class="db-warn">Database is unavailable. Dashboard data may be incomplete.</div>';
+  let dbWarn = '';
+  if (!data.dbAvailable) {
+    const e = data.dbError || {};
+    dbWarn = '<div class="db-warn">Database is unavailable. Dashboard data may be incomplete.';
+    if (e.diagnosis) {
+      dbWarn += `<br><span style="font-size:0.82rem;">${esc(e.diagnosis)}</span>`;
+    } else if (e.message) {
+      dbWarn += `<br><span style="font-size:0.82rem;">${esc(e.message)}</span>`;
+    }
+    dbWarn += '</div>';
+  }
 
   // -- Recent messages -----------------------------------------------------
   let messagesSection;
@@ -900,15 +1016,23 @@ function settingsHTML(config, message) {
       let inputArea;
 
       if (field.secret) {
+        const maskedDisplay = field.key === 'DATABASE_URL'
+          ? maskDatabaseUrl(String(value))
+          : maskValue(String(value));
         const status = value
-          ? `Current: ${esc(maskValue(String(value)))}`
+          ? `Current: ${esc(maskedDisplay)}`
           : '(not set)';
         inputArea = `
           <div>
             <div class="secret-current">${status}</div>
-            <input type="password" name="${esc(field.key)}"
-                   value="" placeholder="Enter new value to change"
-                   autocomplete="off" />
+            <div class="secret-input-wrapper">
+              <input type="password" id="input-${esc(field.key)}" name="${esc(field.key)}"
+                     value="" placeholder="Enter new value to change"
+                     autocomplete="off" />
+              <button type="button" class="secret-toggle"
+                      onclick="const inp=document.getElementById('input-${esc(field.key)}');const show=inp.type==='password';inp.type=show?'text':'password';this.textContent=show?'&#x25C9;':'&#x25CE;';"
+                      title="Toggle visibility">&#x25CE;</button>
+            </div>
           </div>`;
       } else if (field.type === 'boolean') {
         const checked = String(value).toLowerCase() === 'true' ? ' checked' : '';
@@ -991,9 +1115,29 @@ function databaseHTML(data) {
     ? `<div class="alert alert-${esc(data.message.type)}">${esc(data.message.text)}</div>`
     : '';
 
-  const dbWarn = data.dbAvailable
-    ? ''
-    : '<div class="db-warn">Database is unavailable. Cannot retrieve database information.</div>';
+  let dbWarn = '';
+  if (!data.dbAvailable) {
+    const e = data.dbError || {};
+    dbWarn = '<div class="db-warn">';
+    dbWarn += '<strong>Database is unavailable.</strong> Cannot retrieve database information.';
+    if (e.diagnosis) {
+      dbWarn += `<br><br><strong>Diagnosis:</strong> ${esc(e.diagnosis)}`;
+    }
+    dbWarn += `<br><br><strong>Error:</strong> ${esc(e.message || 'Unknown')}`;
+    if (e.code) {
+      dbWarn += ` <span class="muted">(code: ${esc(e.code)})</span>`;
+    }
+    if (e.detail) {
+      dbWarn += `<br><strong>Detail:</strong> ${esc(e.detail)}`;
+    }
+    if (e.hint) {
+      dbWarn += `<br><strong>Hint:</strong> ${esc(e.hint)}`;
+    }
+    if (data.dbUrl) {
+      dbWarn += `<br><br><strong>Connection URL:</strong> <code style="font-size:0.82rem;">${esc(data.dbUrl)}</code>`;
+    }
+    dbWarn += '</div>';
+  }
 
   const stats = data.dbAvailable
     ? `