synap 0.1.1 → 0.4.0

package/.claude/skills/synap-assistant/SKILL.md

@@ -51,7 +51,7 @@ Detect user intent and respond appropriately:
 | **Capture** | "Add this...", "Remind me...", "I had an idea..." | Fast capture, minimal questions, default to idea type |
 | **Review** | "What's on my plate?", "Daily review", "Show me..." | Stats + prioritized summary, grouped by type |
 | **Triage** | "Process my synap", "Process my brain dump", "What needs attention?" | Surface raw entries, help classify and prioritize |
-| **Focus** | "What should I work on?", "Priority items" | P1 todos + active projects, clear next actions |
+| **Focus** | "What should I work on?", "Priority items" | WIP items + P1 todos + active projects, clear next actions |
 | **Cleanup** | "Archive completed", "Clean up old stuff" | Bulk operations with preview and confirmation |
 
 ### Volume Modes (Quick vs Deep)
@@ -67,12 +67,15 @@ Detect user intent and respond appropriately:
 |------|---------|
 | Capture idea | `synap add "your thought here"` |
 | Add todo | `synap todo "task description"` |
+| Add todo with due date | `synap todo "Review PR #42" --due tomorrow` |
 | Add question | `synap question "what you're wondering"` |
 | List active | `synap list` |
 | See all | `synap list --all` |
 | Search | `synap search "keyword"` |
 | Show details | `synap show <id>` |
 | Mark done | `synap done <id>` |
+| Start working | `synap start <id>` |
+| Stop working | `synap stop <id>` |
 | Get stats | `synap stats` |
 | Setup wizard | `synap setup` |
 | Edit preferences | `synap preferences --edit` |
@@ -98,6 +101,7 @@ Quick capture of a thought.
 ```bash
 synap add "What if we used a graph database?"
 synap add "Need to review the API design" --type todo --priority 1
+synap add "Prep for demo" --type todo --due 2025-02-15
 synap add "Meeting notes from standup" --type note --tags "meetings,weekly"
 synap add --type project --title "Website Redesign" "Complete overhaul of the marketing site..."
 ```
@@ -108,6 +112,7 @@ synap add --type project --title "Website Redesign" "Complete overhaul of the ma
 - `--priority <1|2|3>`: 1=high, 2=medium, 3=low
 - `--tags <tags>`: Comma-separated tags
 - `--parent <id>`: Parent entry ID
+- `--due <date>`: Due date (YYYY-MM-DD, 3d/1w, weekday names: monday/friday, or keywords: today, tomorrow, next monday)
 - `--json`: JSON output
 
 #### `synap todo <content>`
@@ -118,6 +123,8 @@ synap todo "Review PR #42"
 # Equivalent to: synap add "Review PR #42" --type todo
 ```
 
+Options: `--priority`, `--tags`, `--parent`, `--due`, `--json`
+
 #### `synap question <content>`
 Shorthand for adding a question.
 
@@ -126,6 +133,20 @@ synap question "Should we migrate to TypeScript?"
 # Equivalent to: synap add "..." --type question
 ```
 
+Options: `--priority`, `--tags`, `--parent`, `--due`, `--json`
+
+#### `synap log <id> <message>`
+Add a timestamped log entry under a parent entry.
+
+```bash
+synap log a1b2c3d4 "Started implementation"
+synap log a1b2c3d4 "Completed first draft" --inherit-tags
+```
+
+**Options**:
+- `--inherit-tags`: Copy tags from parent entry
+- `--json`: JSON output
+
 ### Query Commands
 
 #### `synap list`
@@ -139,22 +160,30 @@ synap list --status raw                 # Needs triage
 synap list --priority 1                 # High priority only
 synap list --tags work,urgent           # Has ALL specified tags
 synap list --since 7d                   # Created in last 7 days
+synap list --overdue                    # Overdue entries
+synap list --due-before 7d              # Due in next 7 days
+synap list --has-due                    # Entries with due dates
 synap list --json                       # JSON output for parsing
 ```
 
 **Options**:
 - `--type <type>`: Filter by entry type
-- `--status <status>`: raw, active, someday, done, archived (default: raw,active)
+- `--status <status>`: raw, active, wip, someday, done, archived (default: raw,active)
 - `--tags <tags>`: Comma-separated, AND logic
 - `--priority <1|2|3>`: Filter by priority
 - `--parent <id>`: Children of specific entry
 - `--orphans`: Only entries without parent
 - `--since <duration>`: e.g., 7d, 24h, 2w
+- `--due-before <date>`: Due before date (YYYY-MM-DD or 3d/1w)
+- `--due-after <date>`: Due after date (YYYY-MM-DD or 3d/1w)
+- `--overdue`: Only overdue entries
+- `--has-due`: Only entries with due dates
+- `--no-due`: Only entries without due dates
 - `--all`: All statuses except archived
 - `--done`: Include done entries
 - `--archived`: Show only archived
 - `--limit <n>`: Max entries (default: 50)
-- `--sort <field>`: created, updated, priority
+- `--sort <field>`: created, updated, priority, due
 - `--reverse`: Reverse sort order
 - `--json`: JSON output
 
@@ -224,6 +253,36 @@ synap done --type todo --tags "sprint-1"     # By filter
 synap done --dry-run --type todo             # Preview first
 ```
 
+#### `synap start <ids...>`
+Start working on entries (mark as WIP).
+
+```bash
+synap start a1b2c3d4                         # Single entry
+synap start a1b2c3d4 b2c3d4e5                # Multiple
+synap start --type todo --tags urgent        # By filter
+synap start --dry-run --type todo            # Preview first
+```
+
+**Options**:
+- `-t, --type <type>`: Filter by type
+- `--tags <tags>`: Filter by tags
+- `--dry-run`: Show what would be started
+- `--json`: JSON output
+
+#### `synap stop <ids...>`
+Stop working on entries (remove WIP status).
+
+```bash
+synap stop a1b2c3d4                          # Single entry
+synap stop --all                             # Stop all WIP entries
+synap stop --dry-run                         # Preview first
+```
+
+**Options**:
+- `--all`: Stop all WIP entries
+- `--dry-run`: Show what would be stopped
+- `--json`: JSON output
+
 #### `synap archive <ids...>`
 Archive entries (hides from default view).
 
@@ -432,11 +491,13 @@ Critical for preventing accidental mass changes:
   "content": "The full text of the entry",
   "title": "Short title (optional)",
   "type": "idea|project|feature|todo|question|reference|note",
-  "status": "raw|active|someday|done|archived",
+  "status": "raw|active|wip|someday|done|archived",
   "priority": 1|2|3|null,
   "tags": ["tag1", "tag2"],
   "parent": "parent-id|null",
   "related": ["id1", "id2"],
+  "due": "2026-01-10T23:59:59.000Z",
+  "startedAt": "2026-01-10T08:30:00.000Z",
   "createdAt": "2026-01-05T08:30:00.000Z",
   "updatedAt": "2026-01-05T08:30:00.000Z",
   "source": "cli|agent|import"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synap",
-  "version": "0.1.1",
+  "version": "0.4.0",
   "description": "A CLI for externalizing your working memory",
   "main": "src/cli.js",
   "bin": {

package/src/cli.js

@@ -63,6 +63,35 @@ async function main() {
     return date.toLocaleString();
   };
 
+  // Helper: Format due date for display
+  const formatDueDate = (dateStr) => {
+    const date = new Date(dateStr);
+    if (isNaN(date.getTime())) return 'invalid date';
+
+    const now = new Date();
+    const startOfToday = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+    const startOfDue = new Date(date.getFullYear(), date.getMonth(), date.getDate());
+    const diffDays = Math.round((startOfDue - startOfToday) / (24 * 60 * 60 * 1000));
+
+    if (diffDays === 0) return 'today';
+    if (diffDays === 1) return 'tomorrow';
+    if (diffDays === -1) return 'yesterday';
+    if (diffDays > 1 && diffDays <= 7) return `in ${diffDays} days`;
+    if (diffDays < -1 && diffDays >= -7) return `${Math.abs(diffDays)} days ago`;
+    return date.toLocaleDateString();
+  };
+
+  const formatDuration = (ms) => {
+    const minutes = Math.floor(ms / (1000 * 60));
+    const hours = Math.floor(minutes / 60);
+    const days = Math.floor(hours / 24);
+
+    if (days > 0) return `(${days}d ${hours % 24}h)`;
+    if (hours > 0) return `(${hours}h ${minutes % 60}m)`;
+    if (minutes > 0) return `(${minutes}m)`;
+    return '(<1m)';
+  };
+
   // ============================================
   // CAPTURE COMMANDS
   // ============================================
@@ -75,27 +104,39 @@ async function main() {
     .option('-p, --priority <priority>', 'Priority level (1=high, 2=medium, 3=low)')
     .option('--tags <tags>', 'Comma-separated tags')
     .option('--parent <id>', 'Parent entry ID')
+    .option('--due <date>', 'Due date (YYYY-MM-DD, 3d/1w, or keywords: today, tomorrow, next monday)')
     .option('--json', 'Output as JSON')
     .action(async (contentParts, options) => {
       const content = contentParts.join(' ');
       const tags = mergeTags(options.tags);
 
-      const entry = await storage.addEntry({
-        content,
-        title: options.title,
-        type: options.type,
-        priority: options.priority ? parseInt(options.priority, 10) : undefined,
-        tags,
-        parent: options.parent,
-        source: 'cli'
-      });
+      try {
+        const entry = await storage.addEntry({
+          content,
+          title: options.title,
+          type: options.type,
+          priority: options.priority ? parseInt(options.priority, 10) : undefined,
+          tags,
+          parent: options.parent,
+          due: options.due,
+          source: 'cli'
+        });
 
-      if (options.json) {
-        console.log(JSON.stringify({ success: true, entry }, null, 2));
-      } else {
-        const shortId = entry.id.slice(0, 8);
-        const priorityBadge = entry.priority ? chalk.yellow(`[P${entry.priority}] `) : '';
-        console.log(chalk.green(`Added ${entry.type} ${shortId}: `) + priorityBadge + `"${content.slice(0, 50)}${content.length > 50 ? '...' : ''}"`);
+        if (options.json) {
+          console.log(JSON.stringify({ success: true, entry }, null, 2));
+        } else {
+          const shortId = entry.id.slice(0, 8);
+          const priorityBadge = entry.priority ? chalk.yellow(`[P${entry.priority}] `) : '';
+          const dueBadge = entry.due ? chalk.magenta(` [due: ${formatDueDate(entry.due)}]`) : '';
+          console.log(chalk.green(`Added ${entry.type} ${shortId}: `) + priorityBadge + `"${content.slice(0, 50)}${content.length > 50 ? '...' : ''}"` + dueBadge);
+        }
+      } catch (err) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: err.message, code: 'INVALID_DUE_DATE' }));
+        } else {
+          console.error(chalk.red(err.message));
+        }
+        process.exit(1);
       }
     });
 
@@ -105,26 +146,38 @@ async function main() {
     .option('-p, --priority <priority>', 'Priority level (1=high, 2=medium, 3=low)')
     .option('--tags <tags>', 'Comma-separated tags')
     .option('--parent <id>', 'Parent entry ID')
+    .option('--due <date>', 'Due date (YYYY-MM-DD, 3d/1w, or keywords: today, tomorrow, next monday)')
     .option('--json', 'Output as JSON')
     .action(async (contentParts, options) => {
       const content = contentParts.join(' ');
       const tags = mergeTags(options.tags);
 
-      const entry = await storage.addEntry({
-        content,
-        type: 'todo',
-        priority: options.priority ? parseInt(options.priority, 10) : undefined,
-        tags,
-        parent: options.parent,
-        source: 'cli'
-      });
+      try {
+        const entry = await storage.addEntry({
+          content,
+          type: 'todo',
+          priority: options.priority ? parseInt(options.priority, 10) : undefined,
+          tags,
+          parent: options.parent,
+          due: options.due,
+          source: 'cli'
+        });
 
-      if (options.json) {
-        console.log(JSON.stringify({ success: true, entry }, null, 2));
-      } else {
-        const shortId = entry.id.slice(0, 8);
-        const priorityBadge = entry.priority ? chalk.yellow(`[P${entry.priority}] `) : '';
-        console.log(chalk.green(`Added todo ${shortId}: `) + priorityBadge + `"${content.slice(0, 50)}${content.length > 50 ? '...' : ''}"`);
+        if (options.json) {
+          console.log(JSON.stringify({ success: true, entry }, null, 2));
+        } else {
+          const shortId = entry.id.slice(0, 8);
+          const priorityBadge = entry.priority ? chalk.yellow(`[P${entry.priority}] `) : '';
+          const dueBadge = entry.due ? chalk.magenta(` [due: ${formatDueDate(entry.due)}]`) : '';
+          console.log(chalk.green(`Added todo ${shortId}: `) + priorityBadge + `"${content.slice(0, 50)}${content.length > 50 ? '...' : ''}"` + dueBadge);
+        }
+      } catch (err) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: err.message, code: 'INVALID_DUE_DATE' }));
+        } else {
+          console.error(chalk.red(err.message));
+        }
+        process.exit(1);
       }
     });
 
@@ -134,26 +187,38 @@ async function main() {
     .option('-p, --priority <priority>', 'Priority level (1=high, 2=medium, 3=low)')
     .option('--tags <tags>', 'Comma-separated tags')
     .option('--parent <id>', 'Parent entry ID')
+    .option('--due <date>', 'Due date (YYYY-MM-DD, 3d/1w, or keywords: today, tomorrow, next monday)')
     .option('--json', 'Output as JSON')
     .action(async (contentParts, options) => {
       const content = contentParts.join(' ');
       const tags = mergeTags(options.tags);
 
-      const entry = await storage.addEntry({
-        content,
-        type: 'question',
-        priority: options.priority ? parseInt(options.priority, 10) : undefined,
-        tags,
-        parent: options.parent,
-        source: 'cli'
-      });
+      try {
+        const entry = await storage.addEntry({
+          content,
+          type: 'question',
+          priority: options.priority ? parseInt(options.priority, 10) : undefined,
+          tags,
+          parent: options.parent,
+          due: options.due,
+          source: 'cli'
+        });
 
-      if (options.json) {
-        console.log(JSON.stringify({ success: true, entry }, null, 2));
-      } else {
-        const shortId = entry.id.slice(0, 8);
-        const priorityBadge = entry.priority ? chalk.yellow(`[P${entry.priority}] `) : '';
-        console.log(chalk.green(`Added question ${shortId}: `) + priorityBadge + `"${content.slice(0, 50)}${content.length > 50 ? '...' : ''}"`);
+        if (options.json) {
+          console.log(JSON.stringify({ success: true, entry }, null, 2));
+        } else {
+          const shortId = entry.id.slice(0, 8);
+          const priorityBadge = entry.priority ? chalk.yellow(`[P${entry.priority}] `) : '';
+          const dueBadge = entry.due ? chalk.magenta(` [due: ${formatDueDate(entry.due)}]`) : '';
+          console.log(chalk.green(`Added question ${shortId}: `) + priorityBadge + `"${content.slice(0, 50)}${content.length > 50 ? '...' : ''}"` + dueBadge);
+        }
+      } catch (err) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: err.message, code: 'INVALID_DUE_DATE' }));
+        } else {
+          console.error(chalk.red(err.message));
+        }
+        process.exit(1);
       }
     });
 
@@ -163,21 +228,32 @@ async function main() {
       const content = contentParts.join(' ');
       const tags = mergeTags(options.tags);
 
-      const entry = await storage.addEntry({
-        content,
-        type: typeName,
-        priority: options.priority ? parseInt(options.priority, 10) : undefined,
-        tags,
-        parent: options.parent,
-        source: 'cli'
-      });
+      try {
+        const entry = await storage.addEntry({
+          content,
+          type: typeName,
+          priority: options.priority ? parseInt(options.priority, 10) : undefined,
+          tags,
+          parent: options.parent,
+          due: options.due,
+          source: 'cli'
+        });
 
-      if (options.json) {
-        console.log(JSON.stringify({ success: true, entry }, null, 2));
-      } else {
-        const shortId = entry.id.slice(0, 8);
-        const priorityBadge = entry.priority ? chalk.yellow(`[P${entry.priority}] `) : '';
-        console.log(chalk.green(`Added ${displayName} ${shortId}: `) + priorityBadge + `"${content.slice(0, 50)}${content.length > 50 ? '...' : ''}"`);
+        if (options.json) {
+          console.log(JSON.stringify({ success: true, entry }, null, 2));
+        } else {
+          const shortId = entry.id.slice(0, 8);
+          const priorityBadge = entry.priority ? chalk.yellow(`[P${entry.priority}] `) : '';
+          const dueBadge = entry.due ? chalk.magenta(` [due: ${formatDueDate(entry.due)}]`) : '';
+          console.log(chalk.green(`Added ${displayName} ${shortId}: `) + priorityBadge + `"${content.slice(0, 50)}${content.length > 50 ? '...' : ''}"` + dueBadge);
+        }
+      } catch (err) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: err.message, code: 'INVALID_DUE_DATE' }));
+        } else {
+          console.error(chalk.red(err.message));
+        }
+        process.exit(1);
       }
     };
   };
@@ -188,6 +264,7 @@ async function main() {
     .option('-p, --priority <priority>', 'Priority level (1=high, 2=medium, 3=low)')
     .option('--tags <tags>', 'Comma-separated tags')
     .option('--parent <id>', 'Parent entry ID')
+    .option('--due <date>', 'Due date (YYYY-MM-DD, 3d/1w, or keywords: today, tomorrow, next monday)')
     .option('--json', 'Output as JSON')
     .action(createTypeShorthand('idea'));
 
@@ -197,6 +274,7 @@ async function main() {
     .option('-p, --priority <priority>', 'Priority level (1=high, 2=medium, 3=low)')
     .option('--tags <tags>', 'Comma-separated tags')
     .option('--parent <id>', 'Parent entry ID')
+    .option('--due <date>', 'Due date (YYYY-MM-DD, 3d/1w, or keywords: today, tomorrow, next monday)')
     .option('--json', 'Output as JSON')
     .action(createTypeShorthand('project'));
 
@@ -206,6 +284,7 @@ async function main() {
     .option('-p, --priority <priority>', 'Priority level (1=high, 2=medium, 3=low)')
     .option('--tags <tags>', 'Comma-separated tags')
     .option('--parent <id>', 'Parent entry ID')
+    .option('--due <date>', 'Due date (YYYY-MM-DD, 3d/1w, or keywords: today, tomorrow, next monday)')
     .option('--json', 'Output as JSON')
     .action(createTypeShorthand('feature'));
 
@@ -215,6 +294,7 @@ async function main() {
     .option('-p, --priority <priority>', 'Priority level (1=high, 2=medium, 3=low)')
     .option('--tags <tags>', 'Comma-separated tags')
     .option('--parent <id>', 'Parent entry ID')
+    .option('--due <date>', 'Due date (YYYY-MM-DD, 3d/1w, or keywords: today, tomorrow, next monday)')
     .option('--json', 'Output as JSON')
     .action(createTypeShorthand('note'));
 
@@ -224,9 +304,71 @@ async function main() {
     .option('-p, --priority <priority>', 'Priority level (1=high, 2=medium, 3=low)')
     .option('--tags <tags>', 'Comma-separated tags')
     .option('--parent <id>', 'Parent entry ID')
+    .option('--due <date>', 'Due date (YYYY-MM-DD, 3d/1w, or keywords: today, tomorrow, next monday)')
     .option('--json', 'Output as JSON')
     .action(createTypeShorthand('reference', 'reference'));
 
+  program
+    .command('log <id> <message...>')
+    .description('Add a timestamped log entry under a parent')
+    .option('--inherit-tags', 'Copy tags from parent entry')
+    .option('--json', 'Output as JSON')
+    .action(async (id, messageParts, options) => {
+      const message = messageParts.join(' ');
+
+      const parent = await storage.getEntry(id);
+      if (!parent) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: `Parent entry not found: ${id}`, code: 'ENTRY_NOT_FOUND' }));
+        } else {
+          console.error(chalk.red(`Parent entry not found: ${id}`));
+        }
+        process.exit(1);
+      }
+
+      const now = new Date();
+      const timestamp = now.toISOString().slice(0, 16).replace('T', ' ');
+      const content = `[${timestamp}] ${message}`;
+      const title = message.length <= 40 ? message : message.slice(0, 37) + '...';
+
+      let tags = [];
+      if (options.inheritTags && parent.tags && parent.tags.length > 0) {
+        tags = [...parent.tags];
+      }
+
+      try {
+        const entry = await storage.addEntry({
+          content,
+          title,
+          type: 'note',
+          tags,
+          parent: parent.id,
+          source: 'cli'
+        });
+
+        if (options.json) {
+          console.log(JSON.stringify({
+            success: true,
+            entry,
+            parent: { id: parent.id, title: parent.title || parent.content.slice(0, 40) }
+          }, null, 2));
+        } else {
+          const shortId = entry.id.slice(0, 8);
+          const parentShortId = parent.id.slice(0, 8);
+          console.log(chalk.green(`Logged ${shortId} under ${parentShortId}:`));
+          console.log(`  Parent: ${chalk.cyan(parent.title || parent.content.slice(0, 30))}`);
+          console.log(`  Log: ${message.slice(0, 60)}${message.length > 60 ? '...' : ''}`);
+        }
+      } catch (err) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: err.message }));
+        } else {
+          console.error(chalk.red(err.message));
+        }
+        process.exit(1);
+      }
+    });
+
   // ============================================
   // QUERY COMMANDS
   // ============================================
@@ -246,11 +388,16 @@ async function main() {
     .option('--since <duration>', 'Created after (e.g., 7d, 24h)')
     .option('--before <duration>', 'Created before (e.g., 7d, 24h)')
     .option('--between <range>', 'Date range: start,end (e.g., 2025-01-01,2025-01-31)')
+    .option('--due-before <date>', 'Due before date (YYYY-MM-DD or 3d/1w)')
+    .option('--due-after <date>', 'Due after date (YYYY-MM-DD or 3d/1w)')
+    .option('--overdue', 'Only overdue entries')
+    .option('--has-due', 'Only entries with due dates')
+    .option('--no-due', 'Only entries without due dates')
     .option('-a, --all', 'Include all statuses except archived')
     .option('--done', 'Include done entries')
     .option('--archived', 'Show only archived entries')
     .option('-n, --limit <n>', 'Max entries to return', '50')
-    .option('--sort <field>', 'Sort by: created, updated, priority', 'created')
+    .option('--sort <field>', 'Sort by: created, updated, priority, due', 'created')
     .option('--reverse', 'Reverse sort order')
     .option('--json', 'Output as JSON')
     .action(async (options) => {
@@ -271,6 +418,10 @@ async function main() {
           const [start, end] = options.between.split(',');
           return { start: start.trim(), end: end.trim() };
         })() : undefined,
+        dueBefore: options.dueBefore,
+        dueAfter: options.dueAfter,
+        overdue: options.overdue,
+        hasDue: options.hasDue ? true : (options.due === false ? false : undefined),
         includeDone: options.done || options.all,
         limit: parseInt(options.limit, 10),
         sort: options.sort,
@@ -314,7 +465,13 @@ async function main() {
             const title = entry.title || entry.content.slice(0, 40);
             const truncated = title.length > 40 ? '...' : '';
             const timeStr = chalk.gray(formatTime(entry.createdAt));
-            console.log(`  ${chalk.blue(shortId)}  ${priorityBadge} ${title}${truncated}${tags} ${timeStr}`);
+            let dueStr = '';
+            if (entry.due) {
+              const isOverdue = new Date(entry.due) < new Date() && entry.status !== 'done';
+              const dueText = formatDueDate(entry.due);
+              dueStr = isOverdue ? chalk.red(` [OVERDUE: ${dueText}]`) : chalk.magenta(` [due: ${dueText}]`);
+            }
+            console.log(`  ${chalk.blue(shortId)}  ${priorityBadge} ${title}${truncated}${tags}${dueStr} ${timeStr}`);
           }
           console.log('');
         }
@@ -374,6 +531,12 @@ async function main() {
 
         console.log(`  ${chalk.gray('Created:')}  ${formatTime(entry.createdAt)}`);
         console.log(`  ${chalk.gray('Updated:')}  ${formatTime(entry.updatedAt)}`);
+        if (entry.due) {
+          const isOverdue = new Date(entry.due) < new Date() && entry.status !== 'done';
+          const dueColor = isOverdue ? chalk.red : chalk.magenta;
+          const overdueLabel = isOverdue ? ' (OVERDUE)' : '';
+          console.log(`  ${chalk.gray('Due:')}      ${dueColor(formatDueDate(entry.due))}${overdueLabel}`);
+        }
         if (entry.source) {
           console.log(`  ${chalk.gray('Source:')}   ${entry.source}`);
         }
@@ -517,6 +680,8 @@ async function main() {
     .option('--remove-tags <tags>', 'Remove tags')
     .option('--parent <id>', 'Set parent')
     .option('--clear-parent', 'Remove parent')
+    .option('--due <date>', 'Set due date')
+    .option('--clear-due', 'Remove due date')
     .option('--json', 'Output as JSON')
     .action(async (id, options) => {
       const entry = await storage.getEntry(id);
@@ -546,6 +711,19 @@ async function main() {
       }
       if (options.parent) updates.parent = options.parent;
       if (options.clearParent) updates.parent = null;
+      if (options.due) {
+        const dueDate = storage.parseDate(options.due);
+        if (!dueDate) {
+          if (options.json) {
+            console.log(JSON.stringify({ success: false, error: `Invalid due date: ${options.due}`, code: 'INVALID_DUE_DATE' }));
+          } else {
+            console.error(chalk.red(`Invalid due date: ${options.due}`));
+          }
+          process.exit(1);
+        }
+        updates.due = dueDate;
+      }
+      if (options.clearDue) updates.due = null;
 
       const updated = await storage.updateEntry(entry.id, updates);
 
@@ -669,6 +847,126 @@ async function main() {
       }
     });
 
+  program
+    .command('start [ids...]')
+    .description('Start working on entries (mark as WIP)')
+    .option('-t, --type <type>', 'Filter by type')
+    .option('--tags <tags>', 'Filter by tags')
+    .option('--dry-run', 'Show what would be started')
+    .option('--json', 'Output as JSON')
+    .action(async (ids, options) => {
+      let entries;
+
+      if (ids.length > 0) {
+        entries = await storage.getEntriesByIds(ids);
+      } else if (options.type || options.tags) {
+        const result = await storage.listEntries({
+          type: options.type,
+          tags: options.tags ? options.tags.split(',').map(t => t.trim()) : undefined,
+          status: 'raw,active',
+          limit: 1000
+        });
+        entries = result.entries;
+      } else {
+        console.error(chalk.red('Please provide entry IDs or filter options (--type, --tags)'));
+        process.exit(1);
+      }
+
+      entries = entries.filter(e => e.status !== 'wip');
+
+      if (entries.length === 0) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: true, count: 0, entries: [] }));
+        } else {
+          console.log(chalk.gray('No entries to start (already WIP or not found)'));
+        }
+        return;
+      }
+
+      if (options.dryRun) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: true, dryRun: true, count: entries.length, entries }));
+        } else {
+          console.log(chalk.yellow(`Would start ${entries.length} entries:`));
+          for (const entry of entries) {
+            console.log(`  ${entry.id.slice(0, 8)} (${entry.type}): ${entry.title || entry.content.slice(0, 40)}...`);
+          }
+        }
+        return;
+      }
+
+      const startedAt = new Date().toISOString();
+      const updatedEntries = [];
+      for (const entry of entries) {
+        const updated = await storage.updateEntry(entry.id, { status: 'wip', startedAt });
+        updatedEntries.push(updated);
+      }
+
+      if (options.json) {
+        console.log(JSON.stringify({ success: true, count: updatedEntries.length, entries: updatedEntries }));
+      } else {
+        console.log(chalk.green(`Started ${updatedEntries.length} entries (marked as WIP)`));
+        for (const entry of updatedEntries) {
+          console.log(`  ${chalk.blue(entry.id.slice(0, 8))} ${entry.title || entry.content.slice(0, 40)}`);
+        }
+      }
+    });
+
+  program
+    .command('stop [ids...]')
+    .description('Stop working on entries (remove WIP status)')
+    .option('--all', 'Stop all WIP entries')
+    .option('--dry-run', 'Show what would be stopped')
+    .option('--json', 'Output as JSON')
+    .action(async (ids, options) => {
+      let entries;
+
+      if (ids.length > 0) {
+        entries = await storage.getEntriesByIds(ids);
+        entries = entries.filter(e => e.status === 'wip');
+      } else if (options.all) {
+        const result = await storage.listEntries({ status: 'wip', limit: 1000 });
+        entries = result.entries;
+      } else {
+        console.error(chalk.red('Please provide entry IDs or use --all to stop all WIP entries'));
+        process.exit(1);
+      }
+
+      if (entries.length === 0) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: true, count: 0, entries: [] }));
+        } else {
+          console.log(chalk.gray('No WIP entries to stop'));
+        }
+        return;
+      }
+
+      if (options.dryRun) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: true, dryRun: true, count: entries.length, entries }));
+        } else {
+          console.log(chalk.yellow(`Would stop ${entries.length} WIP entries:`));
+          for (const entry of entries) {
+            const duration = entry.startedAt ? formatDuration(Date.now() - new Date(entry.startedAt).getTime()) : '';
+            console.log(`  ${entry.id.slice(0, 8)}: ${entry.title || entry.content.slice(0, 40)}... ${duration}`);
+          }
+        }
+        return;
+      }
+
+      const updatedEntries = [];
+      for (const entry of entries) {
+        const updated = await storage.updateEntry(entry.id, { status: 'active', startedAt: null });
+        updatedEntries.push(updated);
+      }
+
+      if (options.json) {
+        console.log(JSON.stringify({ success: true, count: updatedEntries.length, entries: updatedEntries }));
+      } else {
+        console.log(chalk.green(`Stopped ${updatedEntries.length} entries (marked as active)`));
+      }
+    });
+
   program
     .command('archive [ids...]')
     .description('Archive entries')
@@ -1043,7 +1341,7 @@ async function main() {
 
   program
     .command('focus')
-    .description('Show what to work on now: P1 todos + active projects')
+    .description('Show what to work on now: P1 todos + overdue + active projects')
     .option('--json', 'Output as JSON')
     .action(async (options) => {
       // Get P1 todos
@@ -1054,6 +1352,17 @@ async function main() {
         limit: 100
       });
 
+      // Get overdue entries
+      const overdueEntries = await storage.listEntries({
+        overdue: true,
+        status: 'raw,active',
+        limit: 100
+      });
+
+      // Deduplicate (some P1 todos may also be overdue)
+      const p1TodoIds = new Set(p1Todos.entries.map(e => e.id));
+      const overdueNotP1 = overdueEntries.entries.filter(e => !p1TodoIds.has(e.id));
+
       // Get active projects with progress
       const projects = await storage.listEntries({
         type: 'project',
@@ -1075,18 +1384,32 @@ async function main() {
         console.log(JSON.stringify({
           success: true,
           p1Todos: p1Todos.entries,
+          overdueItems: overdueNotP1,
           activeProjects: projectsWithProgress
         }, null, 2));
       } else {
         console.log(chalk.bold('Focus: What to work on now\n'));
 
+        // Overdue section (show first - most urgent)
+        if (overdueNotP1.length > 0) {
+          console.log(chalk.red.bold('Overdue:'));
+          for (const item of overdueNotP1) {
+            const shortId = item.id.slice(0, 8);
+            const title = item.title || item.content.slice(0, 50);
+            const dueStr = formatDueDate(item.due);
+            console.log(`  ${chalk.blue(shortId)} ${title} ${chalk.red(`[${dueStr}]`)}`);
+          }
+          console.log();
+        }
+
         // P1 Todos
         if (p1Todos.entries.length > 0) {
           console.log(chalk.yellow.bold('P1 Todos:'));
           for (const todo of p1Todos.entries) {
             const shortId = todo.id.slice(0, 8);
             const title = todo.title || todo.content.slice(0, 50);
-            console.log(`  ${chalk.blue(shortId)} ${title}`);
+            const dueStr = todo.due ? chalk.magenta(` [due: ${formatDueDate(todo.due)}]`) : '';
+            console.log(`  ${chalk.blue(shortId)} ${title}${dueStr}`);
           }
           console.log();
         } else {

package/src/storage.js

@@ -15,7 +15,7 @@ const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
 
 // Valid types, statuses, and date formats
 const VALID_TYPES = ['idea', 'project', 'feature', 'todo', 'question', 'reference', 'note'];
-const VALID_STATUSES = ['raw', 'active', 'someday', 'done', 'archived'];
+const VALID_STATUSES = ['raw', 'active', 'wip', 'someday', 'done', 'archived'];
 const VALID_DATE_FORMATS = ['relative', 'absolute', 'locale'];
 
 /**
@@ -201,6 +201,109 @@ function parseDuration(duration) {
   return value * multipliers[unit];
 }
 
+/**
+ * Parse date input to ISO string
+ * Supports: ISO dates ("2025-01-15"), relative ("3d", "1w"), natural language ("tomorrow", "next Monday")
+ * @param {string} input - Date input string
+ * @returns {string|null} - ISO date string or null if invalid
+ */
+function parseDate(input) {
+  if (typeof input !== 'string') return null;
+  const trimmed = input.trim();
+  if (!trimmed) return null;
+
+  const lowered = trimmed.toLowerCase();
+  const dayMs = 24 * 60 * 60 * 1000;
+
+  const endOfDay = (date) => {
+    const next = new Date(date);
+    next.setHours(23, 59, 59, 999);
+    return next;
+  };
+
+  if (lowered === 'today') {
+    return endOfDay(new Date()).toISOString();
+  }
+  if (lowered === 'tomorrow') {
+    return endOfDay(new Date(Date.now() + dayMs)).toISOString();
+  }
+  if (lowered === 'yesterday') {
+    return endOfDay(new Date(Date.now() - dayMs)).toISOString();
+  }
+
+  const nextWeekdayMatch = lowered.match(/^next\s+(monday|tuesday|wednesday|thursday|friday|saturday|sunday)$/);
+  if (nextWeekdayMatch) {
+    const weekdays = {
+      sunday: 0,
+      monday: 1,
+      tuesday: 2,
+      wednesday: 3,
+      thursday: 4,
+      friday: 5,
+      saturday: 6
+    };
+    const target = weekdays[nextWeekdayMatch[1]];
+    const now = new Date();
+    const current = now.getDay();
+    let diff = (target + 7 - current) % 7;
+    if (diff === 0) diff = 7;
+    return endOfDay(new Date(now.getTime() + diff * dayMs)).toISOString();
+  }
+
+  // Bare weekday names (e.g., "monday", "friday")
+  const bareWeekdayMatch = lowered.match(/^(monday|tuesday|wednesday|thursday|friday|saturday|sunday)$/);
+  if (bareWeekdayMatch) {
+    const weekdays = {
+      sunday: 0,
+      monday: 1,
+      tuesday: 2,
+      wednesday: 3,
+      thursday: 4,
+      friday: 5,
+      saturday: 6
+    };
+    const target = weekdays[bareWeekdayMatch[1]];
+    const now = new Date();
+    const current = now.getDay();
+    let diff = (target - current + 7) % 7;
+    if (diff === 0) diff = 7;
+    return endOfDay(new Date(now.getTime() + diff * dayMs)).toISOString();
+  }
+
+  const inMatch = lowered.match(/^in\s+(\d+)\s*(hour|hours|day|days|week|weeks|month|months)$/);
+  if (inMatch) {
+    const value = parseInt(inMatch[1], 10);
+    const unit = inMatch[2];
+    const multipliers = {
+      hour: 60 * 60 * 1000,
+      hours: 60 * 60 * 1000,
+      day: dayMs,
+      days: dayMs,
+      week: 7 * dayMs,
+      weeks: 7 * dayMs,
+      month: 30 * dayMs,
+      months: 30 * dayMs
+    };
+    return new Date(Date.now() + value * multipliers[unit]).toISOString();
+  }
+
+  // Try relative duration first (3d, 1w, etc.) - for FUTURE dates
+  const durationMs = parseDuration(trimmed);
+  if (durationMs !== null) {
+    return new Date(Date.now() + durationMs).toISOString();
+  }
+
+  // Try ISO date (YYYY-MM-DD)
+  if (/^\d{4}-\d{2}-\d{2}$/.test(trimmed)) {
+    const date = new Date(trimmed + 'T23:59:59');
+    if (!isNaN(date.getTime())) {
+      return date.toISOString();
+    }
+  }
+
+  return null;
+}
+
 /**
  * Add a new entry
  */
@@ -216,6 +319,16 @@ async function addEntry(options) {
     }
   }
 
+  // Parse due date if provided
+  let dueDate = undefined;
+  const dueInput = typeof options.due === 'string' ? options.due.trim() : options.due;
+  if (dueInput) {
+    dueDate = parseDate(dueInput);
+    if (!dueDate) {
+      throw new Error(`Invalid due date: ${options.due}`);
+    }
+  }
+
   const now = new Date().toISOString();
   const entry = {
     id: uuidv4(),
@@ -227,6 +340,7 @@ async function addEntry(options) {
     tags: options.tags || [],
     parent: parentId || undefined,
     related: [],
+    due: dueDate,
     createdAt: now,
     updatedAt: now,
     source: options.source || 'cli'
@@ -392,6 +506,40 @@ async function listEntries(query = {}) {
     });
   }
 
+  // Filter by due before
+  if (query.dueBefore) {
+    const cutoffDate = parseDate(query.dueBefore);
+    if (cutoffDate) {
+      entries = entries.filter(e => e.due && new Date(e.due) <= new Date(cutoffDate));
+    }
+  }
+
+  // Filter by due after
+  if (query.dueAfter) {
+    const cutoffDate = parseDate(query.dueAfter);
+    if (cutoffDate) {
+      entries = entries.filter(e => e.due && new Date(e.due) >= new Date(cutoffDate));
+    }
+  }
+
+  // Filter overdue (due before now, not done/archived)
+  if (query.overdue) {
+    const now = new Date();
+    entries = entries.filter(e =>
+      e.due &&
+      new Date(e.due) < now &&
+      e.status !== 'done' &&
+      e.status !== 'archived'
+    );
+  }
+
+  // Filter entries with/without due date
+  if (query.hasDue === true) {
+    entries = entries.filter(e => e.due);
+  } else if (query.hasDue === false) {
+    entries = entries.filter(e => !e.due);
+  }
+
   // Include done if requested
   if (!query.includeDone && query.status !== 'done') {
     entries = entries.filter(e => e.status !== 'done');
@@ -400,6 +548,13 @@ async function listEntries(query = {}) {
   // Sort
   const sortField = query.sort || 'created';
   entries.sort((a, b) => {
+    if (sortField === 'due') {
+      // Entries without due dates go to the end
+      if (!a.due && !b.due) return 0;
+      if (!a.due) return 1;
+      if (!b.due) return -1;
+      return new Date(a.due) - new Date(b.due);
+    }
     if (sortField === 'priority') {
       const pA = a.priority || 99;
       const pB = b.priority || 99;
@@ -518,6 +673,8 @@ async function updateEntry(id, updates) {
   // Handle null values (clear fields)
   if (updates.priority === null) delete entry.priority;
   if (updates.parent === null) delete entry.parent;
+  if (updates.due === null) delete entry.due;
+  if (updates.startedAt === null) delete entry.startedAt;
 
   saveEntries(data);
 
@@ -794,6 +951,7 @@ module.exports = {
   getDefaultConfig,
   validateConfigValue,
   saveConfig,
+  parseDate,
   CONFIG_DIR,
   ENTRIES_FILE,
   ARCHIVE_FILE,