synap 0.6.1 → 0.8.0

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

@@ -36,11 +36,40 @@ When assisting users with their synap entries:
 
 ## User Preferences (Memory)
 
-synap stores long-term user preferences at `~/.config/synap/user-preferences.md`.
+synap stores user data in a configurable data directory (default: `~/.config/synap/`).
+
+**Data files (syncable):**
+- `entries.json` - Active entries
+- `archive.json` - Archived entries  
+- `user-preferences.md` - Agent memory / user preferences
+
+**Config files (local only):**
+- `config.json` - Settings (including `dataDir` for custom data location)
+- `deletion-log.json` - Audit trail for restore
+
+### Custom Data Directory (for sync)
+
+Users can point synap to a custom folder (e.g., a git repo for multi-device sync):
+
+```bash
+synap config dataDir ~/synap-data
+# Or during setup:
+synap setup
+```
+
+When custom `dataDir` is set:
+- Data files go to the custom location
+- Config stays in `~/.config/synap/`
+- User can sync data folder via git, Dropbox, iCloud, etc.
+
+### Preferences Operations
 
 - Read preferences at the start of a session when present.
-- Append stable, reusable preferences with `synap preferences --append "## Section" "..."`.
-- Avoid overwriting user-written content; prefer section-based appends.
+- Prefer idempotent updates with `synap preferences set --section "Tag Meanings" --entry "#urgent = must do today"`.
+- Remove entries with `synap preferences remove --section tags --match "urgent"`.
+- List entries with `synap preferences list --section tags --json`.
+- `synap preferences --append "## Section" "..."` is still supported for raw appends.
+- Avoid overwriting user-written content; prefer section-based updates.
 
 ## Operating Modes
 
@@ -79,6 +108,7 @@ Detect user intent and respond appropriately:
 | Get stats | `synap stats` |
 | Setup wizard | `synap setup` |
 | Edit preferences | `synap preferences --edit` |
+| Set preference | `synap preferences set --section tags --entry "#urgent = must do today"` |
 
 ## Pre-flight Check
 
@@ -373,8 +403,47 @@ synap import backup.json --merge             # Update existing + add new
 synap import backup.json --skip-existing     # Only add new
 ```
 
+#### `synap config`
+View or update configuration.
+
+```bash
+synap config                                 # Show all settings + paths
+synap config dataDir                         # Show data directory
+synap config dataDir ~/synap-data            # Set custom data directory
+synap config --reset                         # Reset to defaults
+```
+
 ## Workflow Patterns
 
+### Multi-Device Sync Setup
+
+For users who want to sync their synap across devices:
+
+1. **Set custom data directory:**
+   ```bash
+   synap config dataDir ~/synap-data
+   ```
+
+2. **Initialize git (optional):**
+   ```bash
+   cd ~/synap-data
+   git init
+   git remote add origin git@github.com:user/synap-data.git
+   ```
+
+3. **Daily sync workflow:**
+   ```bash
+   cd ~/synap-data && git pull    # Start of day
+   # ... use synap normally ...
+   cd ~/synap-data && git add . && git commit -m "sync" && git push  # End of day
+   ```
+
+4. **On a new device:**
+   ```bash
+   git clone git@github.com:user/synap-data.git ~/synap-data
+   synap config dataDir ~/synap-data
+   ```
+
 ### Daily Review
 
 Run this each morning to get oriented:

package/package.json

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

package/src/cli.js

@@ -1749,7 +1749,16 @@ async function main() {
   // PREFERENCES COMMANDS
   // ============================================
 
-  program
+  const respondPreferencesError = (options, message, code = 'INVALID_ARGS') => {
+    if (options.json) {
+      console.log(JSON.stringify({ success: false, error: message, code }));
+    } else {
+      console.error(chalk.red(message));
+    }
+    process.exit(1);
+  };
+
+  const preferencesCommand = program
     .command('preferences')
     .description('View or update user preferences')
     .option('--edit', 'Open preferences in $EDITOR')
@@ -1761,22 +1770,13 @@ async function main() {
       const hasAppend = Array.isArray(options.append);
       const activeFlags = [options.edit, options.reset, hasAppend].filter(Boolean).length;
 
-      const respondError = (message, code = 'INVALID_ARGS') => {
-        if (options.json) {
-          console.log(JSON.stringify({ success: false, error: message, code }));
-        } else {
-          console.error(chalk.red(message));
-        }
-        process.exit(1);
-      };
-
       if (activeFlags > 1) {
-        respondError('Use only one of --edit, --reset, or --append');
+        respondPreferencesError(options, 'Use only one of --edit, --reset, or --append');
       }
       try {
         if (options.edit) {
           if (options.json) {
-            respondError('Cannot use --json with --edit', 'INVALID_MODE');
+            respondPreferencesError(options, 'Cannot use --json with --edit', 'INVALID_MODE');
           }
 
           preferences.loadPreferences();
@@ -1832,7 +1832,7 @@ async function main() {
         if (hasAppend) {
           const values = options.append || [];
           if (values.length < 2) {
-            respondError('Usage: synap preferences --append "## Section" "Text to append"');
+            respondPreferencesError(options, 'Usage: synap preferences --append "## Section" "Text to append"');
           }
 
           const [section, ...textParts] = values;
@@ -1865,7 +1865,160 @@ async function main() {
           console.log(content);
         }
       } catch (err) {
-        respondError(err.message || 'Failed to update preferences', 'PREFERENCES_ERROR');
+        respondPreferencesError(options, err.message || 'Failed to update preferences', 'PREFERENCES_ERROR');
+      }
+    });
+
+  preferencesCommand
+    .command('set')
+    .description('Add a preference entry to a section')
+    .option('--section <section>', 'Section name or alias')
+    .option('--entry <entry>', 'Entry text')
+    .option('--json', 'Output as JSON')
+    .action((options) => {
+      if (!options.section || !options.entry) {
+        respondPreferencesError(
+          options,
+          'Usage: synap preferences set --section "tags" --entry "text to add"'
+        );
+      }
+
+      try {
+        const result = preferences.setEntry(options.section, options.entry);
+        const payload = { ...result, path: preferences.getPreferencesPath() };
+
+        if (options.json) {
+          console.log(JSON.stringify(payload, null, 2));
+        } else if (result.added) {
+          console.log(chalk.green(`Added entry to ${result.section}`));
+        } else {
+          console.log(chalk.yellow(`Entry already exists in ${result.section}`));
+        }
+      } catch (err) {
+        respondPreferencesError(options, err.message || 'Failed to set preferences', 'PREFERENCES_ERROR');
+      }
+    });
+
+  preferencesCommand
+    .command('remove')
+    .description('Remove preference entries from a section')
+    .option('--section <section>', 'Section name or alias')
+    .option('--match <pattern>', 'Match text (case-insensitive substring)')
+    .option('--entry <entry>', 'Exact entry text')
+    .option('--json', 'Output as JSON')
+    .action((options) => {
+      if (!options.section) {
+        respondPreferencesError(
+          options,
+          'Usage: synap preferences remove --section "tags" --match "urgent"'
+        );
+      }
+      if (options.match && options.entry) {
+        respondPreferencesError(options, 'Use only one of --match or --entry');
+      }
+      if (!options.match && !options.entry) {
+        respondPreferencesError(
+          options,
+          'Usage: synap preferences remove --section "tags" --match "urgent"'
+        );
+      }
+
+      try {
+        const result = preferences.removeFromSection(options.section, {
+          match: options.match,
+          entry: options.entry
+        });
+        const payload = { ...result, path: preferences.getPreferencesPath() };
+
+        if (options.json) {
+          console.log(JSON.stringify(payload, null, 2));
+        } else if (result.removed) {
+          console.log(chalk.green(`Removed ${result.count} entr${result.count === 1 ? 'y' : 'ies'} from ${result.section}`));
+        } else {
+          console.log(chalk.yellow(`No entries matched in ${result.section}`));
+        }
+      } catch (err) {
+        respondPreferencesError(options, err.message || 'Failed to remove preferences', 'PREFERENCES_ERROR');
+      }
+    });
+
+  preferencesCommand
+    .command('list')
+    .description('List preference entries')
+    .option('--section <section>', 'Section name or alias')
+    .option('--json', 'Output as JSON')
+    .action((options) => {
+      try {
+        if (options.section) {
+          const section = preferences.resolveSection(options.section);
+          const entries = preferences.getEntriesInSection(section);
+          const payload = { section, entries, count: entries.length };
+
+          if (options.json) {
+            console.log(JSON.stringify(payload, null, 2));
+          } else if (entries.length === 0) {
+            console.log(chalk.gray(`No entries found in ${section}`));
+          } else {
+            console.log(chalk.bold(section));
+            entries.forEach((entry) => {
+              console.log(`- ${entry}`);
+            });
+          }
+          return;
+        }
+
+        const content = preferences.loadPreferences();
+        const lines = content.split(/\r?\n/);
+        const sections = [];
+        let current = null;
+
+        for (const line of lines) {
+          const headingMatch = line.match(/^(#{1,6})\s*(.+?)\s*$/);
+          if (headingMatch) {
+            const level = headingMatch[1].length;
+            const name = headingMatch[2].trim();
+
+            if (level === 2) {
+              current = { section: name, entries: [] };
+              sections.push(current);
+            } else if (level === 1) {
+              current = null;
+            }
+            continue;
+          }
+
+          if (!current) {
+            continue;
+          }
+
+          const trimmed = line.trim();
+          if (!trimmed || trimmed.startsWith('<!--') || /^(#{1,6})\s+/.test(trimmed)) {
+            continue;
+          }
+
+          current.entries.push(trimmed);
+        }
+
+        const populatedSections = sections.filter(section => section.entries.length > 0);
+        const totalEntries = populatedSections.reduce((sum, section) => sum + section.entries.length, 0);
+
+        if (options.json) {
+          console.log(JSON.stringify({ sections: populatedSections, count: totalEntries }, null, 2));
+        } else if (populatedSections.length === 0) {
+          console.log(chalk.gray('No preference entries found'));
+        } else {
+          populatedSections.forEach((section, index) => {
+            if (index > 0) {
+              console.log('');
+            }
+            console.log(chalk.bold(section.section));
+            section.entries.forEach((entry) => {
+              console.log(`- ${entry}`);
+            });
+          });
+        }
+      } catch (err) {
+        respondPreferencesError(options, err.message || 'Failed to list preferences', 'PREFERENCES_ERROR');
       }
     });
 
@@ -1879,6 +2032,8 @@ async function main() {
     .option('--json', 'Output as JSON')
     .action(async (options) => {
       const fs = require('fs');
+      const os = require('os');
+      const path = require('path');
 
       let hasEntries = false;
       if (fs.existsSync(storage.ENTRIES_FILE)) {
@@ -1890,16 +2045,9 @@ async function main() {
         }
       }
 
-      let createdEntry = null;
-      if (!hasEntries) {
-        createdEntry = await storage.addEntry({
-          content: 'My first thought',
-          type: config.defaultType || 'idea',
-          source: 'setup'
-        });
-      }
-
       let skillResult = { prompted: false };
+      let dataLocationResult = { configured: false };
+      
       if (!options.json) {
         console.log('');
         console.log(chalk.bold('Welcome to synap!\n'));
@@ -1908,19 +2056,93 @@ async function main() {
 
         console.log('Let\'s get you set up:\n');
 
-        console.log('[1/3] Quick capture test...');
-        if (createdEntry) {
+        // Step 1: Data location (only ask if not already configured)
+        const currentConfig = storage.loadConfig();
+        console.log('[1/4] Data location...');
+        
+        if (currentConfig.dataDir) {
+          console.log(`      ${chalk.gray('Already configured:')} ${storage.DATA_DIR}`);
+          dataLocationResult.configured = true;
+          dataLocationResult.path = storage.DATA_DIR;
+        } else {
+          const { select, input } = await import('@inquirer/prompts');
+          const dataChoice = await select({
+            message: 'Where should synap store your data?',
+            choices: [
+              { 
+                name: `Default (${path.join(os.homedir(), '.config', 'synap')})`, 
+                value: 'default',
+                description: 'Recommended for most users'
+              },
+              { 
+                name: 'Custom path (for git sync, Dropbox, iCloud)', 
+                value: 'custom',
+                description: 'Choose a custom folder for syncing across devices'
+              }
+            ]
+          });
+
+          if (dataChoice === 'custom') {
+            const defaultSuggestion = path.join(os.homedir(), 'synap-data');
+            const customPath = await input({
+              message: 'Enter path for synap data:',
+              default: defaultSuggestion,
+              validate: (val) => {
+                if (!val.trim()) return 'Path is required';
+                const expanded = val.replace(/^~/, os.homedir());
+                const parentDir = path.dirname(expanded);
+                if (!fs.existsSync(parentDir)) {
+                  return `Parent directory does not exist: ${parentDir}`;
+                }
+                return true;
+              }
+            });
+
+            const expanded = customPath.replace(/^~/, os.homedir());
+            
+            // Create directory if needed
+            if (!fs.existsSync(expanded)) {
+              fs.mkdirSync(expanded, { recursive: true });
+            }
+
+            // Save to config
+            currentConfig.dataDir = customPath;
+            storage.saveConfig(currentConfig);
+            storage.refreshDataDir();
+            
+            console.log(`      ${chalk.green('✓')} Data directory set to: ${expanded}`);
+            dataLocationResult.configured = true;
+            dataLocationResult.path = expanded;
+            dataLocationResult.custom = true;
+          } else {
+            console.log(`      ${chalk.green('✓')} Using default location: ${storage.DATA_DIR}`);
+            dataLocationResult.configured = true;
+            dataLocationResult.path = storage.DATA_DIR;
+          }
+        }
+
+        // Step 2: Quick capture test
+        console.log('\n[2/4] Quick capture test...');
+        let createdEntry = null;
+        if (!hasEntries) {
+          createdEntry = await storage.addEntry({
+            content: 'My first thought',
+            type: config.defaultType || 'idea',
+            source: 'setup'
+          });
           console.log(`      synap add "My first thought"`);
           console.log(`      ${chalk.green('✓')} Created entry ${createdEntry.id.slice(0, 8)}`);
         } else {
           console.log(`      ${chalk.gray('Existing entries detected, skipping.')}`);
         }
 
-        console.log('\n[2/3] Configuration...');
+        // Step 3: Configuration
+        console.log('\n[3/4] Configuration...');
         console.log(`      Default type: ${chalk.cyan(config.defaultType || 'idea')}`);
         console.log(`      Change with: ${chalk.cyan('synap config defaultType todo')}`);
 
-        console.log('\n[3/3] Claude Code Integration');
+        // Step 4: Claude Code Integration
+        console.log('\n[4/4] Claude Code Integration');
         const { confirm } = await import('@inquirer/prompts');
         const shouldInstall = await confirm({
           message: 'Install Claude skill for AI assistance?',
@@ -1952,10 +2174,26 @@ async function main() {
         console.log(`  ${chalk.cyan('synap todo "Something to do"')}`);
         console.log(`  ${chalk.cyan('synap focus')}`);
         console.log(`  ${chalk.cyan('synap review daily')}`);
+        
+        if (dataLocationResult.custom) {
+          console.log(chalk.bold('\n📁 Sync tip:'));
+          console.log(`  Your data is stored in: ${chalk.cyan(dataLocationResult.path)}`);
+          console.log(`  To sync with git: ${chalk.gray('cd ' + dataLocationResult.path + ' && git init')}`);
+        }
         console.log('');
         return;
       }
 
+      // JSON mode - minimal interaction
+      let createdEntry = null;
+      if (!hasEntries) {
+        createdEntry = await storage.addEntry({
+          content: 'My first thought',
+          type: config.defaultType || 'idea',
+          source: 'setup'
+        });
+      }
+
       console.log(JSON.stringify({
         success: true,
         mode: hasEntries ? 'existing' : 'first-run',
@@ -1996,7 +2234,15 @@ async function main() {
       // No key: show all config
       if (!key) {
         if (options.json) {
-          console.log(JSON.stringify({ success: true, config: currentConfig, defaults }, null, 2));
+          console.log(JSON.stringify({ 
+            success: true, 
+            config: currentConfig, 
+            defaults,
+            paths: {
+              configDir: storage.CONFIG_DIR,
+              dataDir: storage.DATA_DIR
+            }
+          }, null, 2));
         } else {
           console.log(chalk.bold('Configuration:\n'));
           for (const [k, v] of Object.entries(currentConfig)) {
@@ -2005,6 +2251,9 @@ async function main() {
             const displayValue = Array.isArray(v) ? v.join(', ') || '(none)' : (v === null ? '(null)' : v);
             console.log(`  ${chalk.cyan(k)}: ${displayValue}${defaultNote}`);
           }
+          console.log(chalk.bold('\nPaths:'));
+          console.log(`  ${chalk.cyan('configDir')}: ${storage.CONFIG_DIR}`);
+          console.log(`  ${chalk.cyan('dataDir')}: ${storage.DATA_DIR}`);
           console.log(chalk.gray('\nUse: synap config <key> <value> to set a value'));
         }
         return;
@@ -2048,16 +2297,42 @@ async function main() {
         parsedValue = value.split(',').map(t => t.trim()).filter(Boolean);
       } else if (key === 'editor' && (value === 'null' || value === '')) {
         parsedValue = null;
+      } else if (key === 'dataDir') {
+        // Handle dataDir specially
+        if (value === 'null' || value === '') {
+          parsedValue = null;
+        } else {
+          // Expand ~ but keep the ~ in storage for portability
+          const expanded = value.replace(/^~/, require('os').homedir());
+          // Create directory if it doesn't exist
+          if (!fs.existsSync(expanded)) {
+            fs.mkdirSync(expanded, { recursive: true });
+            if (!options.json) {
+              console.log(chalk.gray(`Created directory: ${expanded}`));
+            }
+          }
+          // Store the original value (with ~ if used)
+          parsedValue = value;
+        }
       }
 
       currentConfig[key] = parsedValue;
       storage.saveConfig(currentConfig);
 
+      // If dataDir changed, refresh the storage paths
+      if (key === 'dataDir') {
+        storage.refreshDataDir();
+      }
+
       if (options.json) {
         console.log(JSON.stringify({ success: true, key, value: parsedValue }));
       } else {
         const displayValue = Array.isArray(parsedValue) ? parsedValue.join(', ') : parsedValue;
         console.log(chalk.green(`Set ${key} = ${displayValue}`));
+        if (key === 'dataDir') {
+          console.log(chalk.gray(`Data will be stored in: ${storage.DATA_DIR}`));
+          console.log(chalk.yellow('\nNote: Restart synap for changes to take full effect.'));
+        }
       }
     });
 

package/src/deletion-log.js

@@ -1,21 +1,27 @@
 /**
  * deletion-log.js - Audit logging for deleted entries, enables restore
+ * 
+ * The deletion log is stored in DATA_DIR (syncable across devices)
  */
 
 const fs = require('fs');
 const path = require('path');
-const os = require('os');
+const storage = require('./storage');
 
-// Storage directory
-const CONFIG_DIR = process.env.SYNAP_DIR || path.join(os.homedir(), '.config', 'synap');
-const DELETION_LOG_FILE = path.join(CONFIG_DIR, 'deletion-log.json');
+/**
+ * Get deletion log file path (dynamic, based on DATA_DIR)
+ */
+function getDeletionLogPath() {
+  return path.join(storage.DATA_DIR, 'deletion-log.json');
+}
 
 /**
- * Ensure config directory exists
+ * Ensure data directory exists
  */
-function ensureConfigDir() {
-  if (!fs.existsSync(CONFIG_DIR)) {
-    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+function ensureDataDir() {
+  const dataDir = storage.DATA_DIR;
+  if (!fs.existsSync(dataDir)) {
+    fs.mkdirSync(dataDir, { recursive: true });
   }
 }
 
@@ -32,12 +38,13 @@ function atomicWriteSync(filePath, data) {
  * Load deletion log
  */
 function loadLog() {
-  ensureConfigDir();
-  if (!fs.existsSync(DELETION_LOG_FILE)) {
+  ensureDataDir();
+  const logFile = getDeletionLogPath();
+  if (!fs.existsSync(logFile)) {
     return [];
   }
   try {
-    return JSON.parse(fs.readFileSync(DELETION_LOG_FILE, 'utf8'));
+    return JSON.parse(fs.readFileSync(logFile, 'utf8'));
   } catch {
     return [];
   }
@@ -47,8 +54,8 @@ function loadLog() {
  * Save deletion log
  */
 function saveLog(log) {
-  ensureConfigDir();
-  atomicWriteSync(DELETION_LOG_FILE, log);
+  ensureDataDir();
+  atomicWriteSync(getDeletionLogPath(), log);
 }
 
 /**

package/src/preferences.js

@@ -1,5 +1,7 @@
 /**
  * preferences.js - User preferences storage and helpers
+ * 
+ * User preferences are stored in DATA_DIR (syncable) not CONFIG_DIR
  */
 
 const fs = require('fs');
@@ -7,17 +9,35 @@ const path = require('path');
 const storage = require('./storage');
 
 const TEMPLATE_PATH = path.join(__dirname, 'templates', 'user-preferences-template.md');
-const PREFERENCES_FILE = path.join(storage.CONFIG_DIR, 'user-preferences.md');
 const MAX_LINES = 500;
+const SECTION_ALIASES = new Map([
+  ['about', 'About Me'],
+  ['me', 'About Me'],
+  ['projects', 'Important Projects'],
+  ['important', 'Important Projects'],
+  ['tags', 'Tag Meanings'],
+  ['tag', 'Tag Meanings'],
+  ['review', 'Review Preferences'],
+  ['behavior', 'Behavioral Preferences'],
+  ['behavioral', 'Behavioral Preferences']
+]);
 
-function ensureConfigDir() {
-  if (!fs.existsSync(storage.CONFIG_DIR)) {
-    fs.mkdirSync(storage.CONFIG_DIR, { recursive: true });
+/**
+ * Get current preferences file path (dynamic, based on DATA_DIR)
+ */
+function getPreferencesFilePath() {
+  return path.join(storage.DATA_DIR, 'user-preferences.md');
+}
+
+function ensureDataDir() {
+  const dataDir = storage.DATA_DIR;
+  if (!fs.existsSync(dataDir)) {
+    fs.mkdirSync(dataDir, { recursive: true });
   }
 }
 
 function getPreferencesPath() {
-  return PREFERENCES_FILE;
+  return getPreferencesFilePath();
 }
 
 function readTemplate() {
@@ -51,22 +71,24 @@ function savePreferences(content) {
     throw new Error(validation.error);
   }
 
-  ensureConfigDir();
-  const tmpPath = `${PREFERENCES_FILE}.tmp`;
+  ensureDataDir();
+  const preferencesFile = getPreferencesFilePath();
+  const tmpPath = `${preferencesFile}.tmp`;
   fs.writeFileSync(tmpPath, content, 'utf8');
-  fs.renameSync(tmpPath, PREFERENCES_FILE);
+  fs.renameSync(tmpPath, preferencesFile);
   return content;
 }
 
 function loadPreferences() {
-  ensureConfigDir();
-  if (!fs.existsSync(PREFERENCES_FILE)) {
+  ensureDataDir();
+  const preferencesFile = getPreferencesFilePath();
+  if (!fs.existsSync(preferencesFile)) {
     const template = readTemplate();
     savePreferences(template);
     return template;
   }
 
-  const content = fs.readFileSync(PREFERENCES_FILE, 'utf8');
+  const content = fs.readFileSync(preferencesFile, 'utf8');
   const validation = validatePreferences(content);
   if (!validation.valid) {
     throw new Error(validation.error);
@@ -79,7 +101,16 @@ function resetPreferences() {
   return savePreferences(template);
 }
 
+function resolveSection(input) {
+  const target = parseSectionTarget(input);
+  const key = target.name.toLowerCase();
+  return SECTION_ALIASES.get(key) || target.name;
+}
+
 function parseSectionTarget(section) {
+  if (typeof section !== 'string') {
+    throw new Error('Section name is required');
+  }
   const trimmed = section.trim();
   if (!trimmed) {
     throw new Error('Section name is required');
@@ -93,9 +124,22 @@ function parseSectionTarget(section) {
   return { level: null, name: trimmed };
 }
 
+function normalizeEntry(entry) {
+  return entry.trim();
+}
+
+function isCommentLine(line) {
+  const trimmed = line.trim();
+  return trimmed.startsWith('<!--');
+}
+
+function isHeadingLine(line) {
+  return /^(#{1,6})\s+/.test(line.trim());
+}
+
 function findSection(lines, target) {
   for (let i = 0; i < lines.length; i += 1) {
-    const match = lines[i].match(/^(#{1,6})\s*(.+?)\s*$/);
+    const match = lines[i].match(/^(#{1,6})\s+(.+?)\s*$/);
     if (!match) {
       continue;
     }
@@ -113,6 +157,148 @@ function findSection(lines, target) {
   return null;
 }
 
+function getSectionRange(lines, match) {
+  if (!match) {
+    return null;
+  }
+
+  let endIndex = lines.length;
+  for (let i = match.index + 1; i < lines.length; i += 1) {
+    const headingMatch = lines[i].match(/^(#{1,6})\s+(.+?)\s*$/);
+    if (!headingMatch) {
+      continue;
+    }
+    const level = headingMatch[1].length;
+    if (level <= match.level) {
+      endIndex = i;
+      break;
+    }
+  }
+
+  return { start: match.index, end: endIndex };
+}
+
+function getEntriesInSection(section) {
+  const resolved = resolveSection(section);
+  const content = loadPreferences();
+  const lines = content.split(/\r?\n/);
+  const target = parseSectionTarget(resolved);
+  const match = findSection(lines, target);
+
+  if (!match) {
+    return [];
+  }
+
+  const range = getSectionRange(lines, match);
+  const entries = [];
+
+  for (let i = match.index + 1; i < range.end; i += 1) {
+    const line = lines[i];
+    const trimmed = line.trim();
+
+    if (!trimmed || isCommentLine(trimmed) || isHeadingLine(trimmed)) {
+      continue;
+    }
+
+    entries.push(trimmed);
+  }
+
+  return entries;
+}
+
+function setEntry(section, entry) {
+  if (typeof entry !== 'string' || !entry.trim()) {
+    throw new Error('Entry text is required');
+  }
+
+  const resolved = resolveSection(section);
+  const normalized = normalizeEntry(entry);
+  const entries = getEntriesInSection(resolved);
+  const existed = entries.some((existing) => existing === normalized);
+
+  if (existed) {
+    return {
+      added: false,
+      existed: true,
+      section: resolved,
+      entry: normalized
+    };
+  }
+
+  appendToSection(resolved, normalized);
+  return {
+    added: true,
+    existed: false,
+    section: resolved,
+    entry: normalized
+  };
+}
+
+function removeFromSection(section, { match, entry } = {}) {
+  const hasMatch = typeof match === 'string' && match.trim();
+  const hasEntry = typeof entry === 'string' && entry.trim();
+
+  if (!hasMatch && !hasEntry) {
+    throw new Error('Match or entry is required');
+  }
+  if (hasMatch && hasEntry) {
+    throw new Error('Use either match or entry, not both');
+  }
+
+  const resolved = resolveSection(section);
+  const content = loadPreferences();
+  const lines = content.split(/\r?\n/);
+  const target = parseSectionTarget(resolved);
+  const sectionMatch = findSection(lines, target);
+
+  if (!sectionMatch) {
+    return { removed: false, count: 0, entries: [], section: resolved };
+  }
+
+  const range = getSectionRange(lines, sectionMatch);
+  const sectionLines = lines.slice(sectionMatch.index + 1, range.end);
+  const removedEntries = [];
+  const normalizedEntry = hasEntry ? normalizeEntry(entry) : null;
+  const matchNeedle = hasMatch ? match.trim().toLowerCase() : null;
+
+  const updatedSectionLines = sectionLines.filter((line) => {
+    const trimmed = line.trim();
+
+    if (!trimmed || isCommentLine(trimmed) || isHeadingLine(trimmed)) {
+      return true;
+    }
+
+    const matches = normalizedEntry
+      ? trimmed === normalizedEntry
+      : trimmed.toLowerCase().includes(matchNeedle);
+
+    if (matches) {
+      removedEntries.push(trimmed);
+      return false;
+    }
+
+    return true;
+  });
+
+  if (removedEntries.length === 0) {
+    return { removed: false, count: 0, entries: [], section: resolved };
+  }
+
+  const updatedLines = [
+    ...lines.slice(0, sectionMatch.index + 1),
+    ...updatedSectionLines,
+    ...lines.slice(range.end)
+  ];
+
+  savePreferences(updatedLines.join('\n'));
+  return {
+    removed: true,
+    count: removedEntries.length,
+    entries: removedEntries,
+    section: resolved
+  };
+}
+
 function appendToSection(section, text) {
   if (typeof text !== 'string' || !text.trim()) {
     throw new Error('Append text is required');
@@ -140,7 +326,7 @@ function appendToSection(section, text) {
 
   let insertIndex = lines.length;
   for (let i = match.index + 1; i < lines.length; i += 1) {
-    const headingMatch = lines[i].match(/^(#{1,6})\s*(.+?)\s*$/);
+    const headingMatch = lines[i].match(/^(#{1,6})\s+(.+?)\s*$/);
     if (!headingMatch) {
       continue;
     }
@@ -167,9 +353,13 @@ module.exports = {
   getPreferencesPath,
   loadPreferences,
   savePreferences,
+  resolveSection,
+  setEntry,
+  removeFromSection,
+  getEntriesInSection,
   appendToSection,
   resetPreferences,
   validatePreferences,
-  PREFERENCES_FILE,
+  get PREFERENCES_FILE() { return getPreferencesFilePath(); },
   TEMPLATE_PATH
 };

package/src/storage.js

@@ -7,16 +7,30 @@ const path = require('path');
 const os = require('os');
 const { v4: uuidv4 } = require('uuid');
 
-// Storage directory
-const CONFIG_DIR = process.env.SYNAP_DIR || path.join(os.homedir(), '.config', 'synap');
-const ENTRIES_FILE = path.join(CONFIG_DIR, 'entries.json');
-const ARCHIVE_FILE = path.join(CONFIG_DIR, 'archive.json');
-const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+// =============================================================================
+// Directory Resolution (XDG-compliant with backward compatibility)
+// =============================================================================
 
-// Valid types, statuses, and date formats
-const VALID_TYPES = ['idea', 'project', 'feature', 'todo', 'question', 'reference', 'note'];
-const VALID_STATUSES = ['raw', 'active', 'wip', 'someday', 'done', 'archived'];
-const VALID_DATE_FORMATS = ['relative', 'absolute', 'locale'];
+/**
+ * Resolve the config directory path
+ * Priority:
+ *   1. SYNAP_CONFIG_DIR env var (explicit override for config only)
+ *   2. SYNAP_DIR env var (legacy - affects both config and data)
+ *   3. Default: ~/.config/synap
+ */
+function resolveConfigDir() {
+  if (process.env.SYNAP_CONFIG_DIR) {
+    return process.env.SYNAP_CONFIG_DIR;
+  }
+  if (process.env.SYNAP_DIR) {
+    return process.env.SYNAP_DIR;
+  }
+  return path.join(os.homedir(), '.config', 'synap');
+}
+
+// Config directory - always local, not synced
+const CONFIG_DIR = resolveConfigDir();
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
 
 /**
  * Ensure config directory exists
@@ -27,6 +41,90 @@ function ensureConfigDir() {
   }
 }
 
+/**
+ * Load configuration (needed before resolving DATA_DIR)
+ */
+function loadConfigRaw() {
+  ensureConfigDir();
+  if (!fs.existsSync(CONFIG_FILE)) {
+    return {};
+  }
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Resolve the data directory path
+ * Priority:
+ *   1. SYNAP_DATA_DIR env var (explicit override for data only)
+ *   2. config.json -> dataDir setting
+ *   3. SYNAP_DIR env var (legacy - affects both config and data)
+ *   4. Default: ~/.local/share/synap (XDG compliant)
+ */
+function resolveDataDir() {
+  // 1. Explicit env var override for data
+  if (process.env.SYNAP_DATA_DIR) {
+    return process.env.SYNAP_DATA_DIR;
+  }
+
+  // 2. Config file setting
+  const rawConfig = loadConfigRaw();
+  if (rawConfig.dataDir) {
+    // Expand ~ to home directory
+    const expanded = rawConfig.dataDir.replace(/^~/, os.homedir());
+    return expanded;
+  }
+
+  // 3. Legacy env var (affects both config and data)
+  if (process.env.SYNAP_DIR) {
+    return process.env.SYNAP_DIR;
+  }
+
+  // 4. Default: XDG-compliant data directory
+  return path.join(os.homedir(), '.local', 'share', 'synap');
+}
+
+// Resolve DATA_DIR at module load time
+// This will be re-evaluated if config changes require restart
+let DATA_DIR = resolveDataDir();
+
+// Data files (syncable)
+let ENTRIES_FILE = path.join(DATA_DIR, 'entries.json');
+let ARCHIVE_FILE = path.join(DATA_DIR, 'archive.json');
+
+/**
+ * Refresh data directory paths (call after config change)
+ */
+function refreshDataDir() {
+  DATA_DIR = resolveDataDir();
+  ENTRIES_FILE = path.join(DATA_DIR, 'entries.json');
+  ARCHIVE_FILE = path.join(DATA_DIR, 'archive.json');
+}
+
+/**
+ * Get current data directory path
+ */
+function getDataDir() {
+  return DATA_DIR;
+}
+
+/**
+ * Ensure data directory exists
+ */
+function ensureDataDir() {
+  if (!fs.existsSync(DATA_DIR)) {
+    fs.mkdirSync(DATA_DIR, { recursive: true });
+  }
+}
+
+// Valid types, statuses, and date formats
+const VALID_TYPES = ['idea', 'project', 'feature', 'todo', 'question', 'reference', 'note'];
+const VALID_STATUSES = ['raw', 'active', 'wip', 'someday', 'done', 'archived'];
+const VALID_DATE_FORMATS = ['relative', 'absolute', 'locale'];
+
 /**
  * Atomic file write - write to temp file then rename
  */
@@ -40,7 +138,7 @@ function atomicWriteSync(filePath, data) {
  * Load entries from file
  */
 function loadEntries() {
-  ensureConfigDir();
+  ensureDataDir();
   if (!fs.existsSync(ENTRIES_FILE)) {
     return { version: 1, entries: [] };
   }
@@ -55,7 +153,7 @@ function loadEntries() {
  * Save entries to file
  */
 function saveEntries(data) {
-  ensureConfigDir();
+  ensureDataDir();
   atomicWriteSync(ENTRIES_FILE, data);
 }
 
@@ -63,7 +161,7 @@ function saveEntries(data) {
  * Load archived entries
  */
 function loadArchive() {
-  ensureConfigDir();
+  ensureDataDir();
   if (!fs.existsSync(ARCHIVE_FILE)) {
     return { version: 1, entries: [] };
   }
@@ -78,7 +176,7 @@ function loadArchive() {
  * Save archived entries
  */
 function saveArchive(data) {
-  ensureConfigDir();
+  ensureDataDir();
   atomicWriteSync(ARCHIVE_FILE, data);
 }
 
@@ -91,7 +189,8 @@ function loadConfig() {
     defaultType: 'idea',
     defaultTags: [],
     editor: null, // Falls back to EDITOR env var in CLI
-    dateFormat: 'relative'
+    dateFormat: 'relative',
+    dataDir: null // Custom data directory (null = use default)
   };
 
   if (!fs.existsSync(CONFIG_FILE)) {
@@ -123,6 +222,12 @@ function loadConfig() {
         .map(t => t.trim());
     }
 
+    // Validate dataDir if set
+    if (config.dataDir !== null && typeof config.dataDir !== 'string') {
+      console.warn(`Warning: Invalid dataDir in config. Ignoring.`);
+      config.dataDir = null;
+    }
+
     return config;
   } catch (err) {
     console.warn(`Warning: Could not parse config.json: ${err.message}`);
@@ -138,7 +243,8 @@ function getDefaultConfig() {
     defaultType: 'idea',
     defaultTags: [],
     editor: null,
-    dateFormat: 'relative'
+    dateFormat: 'relative',
+    dataDir: null
   };
 }
 
@@ -170,6 +276,17 @@ function validateConfigValue(key, value) {
     case 'editor':
       // Any string or null is valid
       break;
+    case 'dataDir':
+      // Path validation - must be a valid path string or null
+      if (value !== null && value !== 'null' && typeof value === 'string') {
+        const expanded = value.replace(/^~/, os.homedir());
+        // Check if parent directory exists (we'll create the target if needed)
+        const parentDir = path.dirname(expanded);
+        if (!fs.existsSync(parentDir)) {
+          return { valid: false, error: `Parent directory does not exist: ${parentDir}` };
+        }
+      }
+      break;
   }
   return { valid: true };
 }
@@ -1018,9 +1135,12 @@ module.exports = {
   validateConfigValue,
   saveConfig,
   parseDate,
+  refreshDataDir,
+  getDataDir,
   CONFIG_DIR,
-  ENTRIES_FILE,
-  ARCHIVE_FILE,
+  get DATA_DIR() { return DATA_DIR; },
+  get ENTRIES_FILE() { return ENTRIES_FILE; },
+  get ARCHIVE_FILE() { return ARCHIVE_FILE; },
   VALID_TYPES,
   VALID_STATUSES,
   VALID_DATE_FORMATS