2ndbrain 2026.1.33 → 2026.1.35

package/.claude/settings.local.json

@@ -14,7 +14,12 @@
       "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(ls -la \"c:\\\\dev\\\\fingerskier\\\\agent\\\\2ndbrain\\\\db\"\" 2>/dev/null || echo \"Directory not accessible \")",
+      "Bash(npm install:*)",
+      "mcp__dude__get_project_context",
+      "mcp__dude__create_project",
+      "mcp__dude__create_issue",
+      "mcp__dude__update_issue"
     ]
   }
 }

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.33",
+  "version": "2026.1.35",
   "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

@@ -7,9 +7,22 @@ import { fileURLToPath } from 'node:url';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const PROJECT_ROOT = path.resolve(__dirname, '..');
-const ENV_PATH = path.join(PROJECT_ROOT, '.env');
+const SETTINGS_DIR = path.join(os.homedir(), '.2ndbrain');
+const ENV_PATH = path.join(SETTINGS_DIR, '.env');
+const LEGACY_ENV_PATH = path.join(PROJECT_ROOT, '.env');
 
-// Load .env from project root
+// Migrate legacy .env from package root to stable user directory
+if (!fs.existsSync(ENV_PATH) && fs.existsSync(LEGACY_ENV_PATH)) {
+  try {
+    fs.mkdirSync(SETTINGS_DIR, { recursive: true });
+    fs.copyFileSync(LEGACY_ENV_PATH, ENV_PATH);
+  } catch { /* fall through to first-run */ }
+}
+
+// Ensure settings directory exists
+try { fs.mkdirSync(SETTINGS_DIR, { recursive: true }); } catch { /* ignore */ }
+
+// Load .env from stable user directory
 dotenvConfig({ path: ENV_PATH });
 
 const env = process.env;
@@ -99,5 +112,5 @@ function isFirstRun() {
   return !valid;
 }
 
-export { config, validateConfig, isFirstRun, PROJECT_ROOT, ENV_PATH };
+export { config, validateConfig, isFirstRun, PROJECT_ROOT, ENV_PATH, SETTINGS_DIR };
 export default config;

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

@@ -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 */ }
   }
@@ -516,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

@@ -4,11 +4,10 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { migrate, getMigrationFiles, ensureMigrationsTable } from '../db/migrate.js';
+import { ENV_PATH } from '../config.js';
 
-// Resolve project root (two directories up from src/web/)
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
-const DEFAULT_ENV_PATH = path.resolve(__dirname, '..', '..', '.env');
 
 // ---------------------------------------------------------------------------
 // Settings field definitions -- drives both the form UI and save logic
@@ -107,7 +106,7 @@ class WebServer {
     this._logger = logger;
     this._server = null;
     this._app = null;
-    this._envPath = config.ENV_PATH || DEFAULT_ENV_PATH;
+    this._envPath = ENV_PATH;
   }
 
   /**