wicked-brain 0.4.13 → 0.4.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-brain",
-  "version": "0.4.13",
+  "version": "0.4.15",
   "type": "module",
   "description": "Digital brain as skills for AI coding CLIs — no vector DB, no embeddings, no infrastructure",
   "keywords": [

package/server/lib/file-watcher.mjs

@@ -36,26 +36,33 @@ export class FileWatcher {
   }
 
   start() {
+    const brainDirs = ["chunks", "wiki", "memory"];
+
     // Build initial hash map
-    this.#scanAndHash("chunks");
-    this.#scanAndHash("wiki");
-    this.#scanAndHash("memory");
+    for (const dir of brainDirs) this.#scanAndHash(dir);
 
     // Watch directories
-    for (const dir of ["chunks", "wiki", "memory"]) {
-      const absDir = join(this.#brainPath, dir);
-      if (!existsSync(absDir)) continue;
+    const unwatched = [];
+    for (const dir of brainDirs) {
+      if (!this.#tryWatch(dir)) unwatched.push(dir);
+    }
 
-      try {
-        const watcher = watch(absDir, { recursive: true }, (eventType, filename) => {
-          if (!filename || !filename.endsWith(".md")) return;
-          const relPath = normalizePath(`${dir}/${filename}`);
-          this.#debounce(relPath, () => this.#handleChange(relPath));
-        });
-        this.#watchers.push(watcher);
-      } catch {
-        // recursive watch not supported on this platform (Linux) — fall back to polling
-      }
+    // Retry directories that were missing at startup (check every 3s, stop after 30s)
+    if (unwatched.length > 0) {
+      const pending = new Set(unwatched);
+      let elapsed = 0;
+      const retryInterval = setInterval(() => {
+        elapsed += 3000;
+        for (const dir of pending) {
+          if (this.#tryWatch(dir)) {
+            this.#scanAndHash(dir);
+            pending.delete(dir);
+          }
+        }
+        if (pending.size === 0 || elapsed >= 30000) clearInterval(retryInterval);
+      }, 3000);
+      // Don't keep the process alive just for retries
+      retryInterval.unref();
     }
 
     // Watch registered project directories
@@ -84,6 +91,24 @@ export class FileWatcher {
     }
   }
 
+  /** Try to set up fs.watch for a brain subdirectory. Returns true on success. */
+  #tryWatch(dir) {
+    const absDir = join(this.#brainPath, dir);
+    if (!existsSync(absDir)) return false;
+    try {
+      const watcher = watch(absDir, { recursive: true }, (eventType, filename) => {
+        if (!filename || !filename.endsWith(".md")) return;
+        const relPath = normalizePath(`${dir}/${filename}`);
+        this.#debounce(relPath, () => this.#handleChange(relPath));
+      });
+      this.#watchers.push(watcher);
+      return true;
+    } catch {
+      // recursive watch not supported (Linux) — polling fallback handles it
+      return false;
+    }
+  }
+
   stop() {
     for (const w of this.#watchers) w.close();
     this.#watchers = [];

package/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-brain-server",
-  "version": "0.4.13",
+  "version": "0.4.15",
   "type": "module",
   "description": "SQLite FTS5 search server for wicked-brain digital knowledge bases",
   "keywords": [

package/skills/wicked-brain-init/SKILL.md

@@ -120,24 +120,59 @@ directory, not a project subdirectory), push back: explain the per-project
 convention and suggest `~/.wicked-brain/projects/{project_name}` instead.
 Only accept the flat path if the user explicitly insists.
 
-### Step 2: Check for existing brains
+### The `projects/` infix is mandatory — do not invent alternate layouts
 
-#### 2a: Detect a flat brain at the parent path
+The ONLY valid brain path under the default container is
+`~/.wicked-brain/projects/{name}/`. Common misreadings to avoid:
+
+- ❌ `~/.wicked-brain/{name}/` — missing the `projects/` segment. Not valid.
+- ❌ `~/.{name}-brain/` — sibling directory. Not the convention.
+- ❌ `~/.wicked-brain/projects/{name}/projects/{subname}/` — nested brains. Not supported.
 
-If `~/.wicked-brain/brain.json` exists (note: `brain.json` at the flat parent
-path, NOT inside a `projects/` subdirectory), this is a legacy flat brain from
-before v0.4.7. Stop and tell the user:
+If the user asks "why not `~/.wicked-brain/{name}`?" the answer is: the `projects/`
+segment is a deliberate namespace. The parent `~/.wicked-brain/` is a container
+that may hold other metadata (linked brain indexes, federation config, etc.),
+and every brain lives under `projects/` to keep that clean.
 
-"I found an existing flat brain at `~/.wicked-brain/`. The current layout puts
-each project under `~/.wicked-brain/projects/{name}/`. I can migrate the flat
-brain with `wicked-brain:migrate` before creating the new one. Migrate now?"
+Do not improvise alternate layouts when you hit an obstacle. If the documented
+path is occupied, invoke the migration flow (Step 2a) — do not pick a sibling
+directory or a nested path.
 
-If yes, invoke `wicked-brain:migrate` with `flat_path=~/.wicked-brain` and
-wait for it to complete before continuing.
+### Step 2: Check for existing brains
+
+#### 2a: Detect a flat brain at the parent path
 
-If no, confirm the user wants to keep the flat brain and proceed (accept the
-tradeoff: the new project brain will live under `projects/` but the old one
-stays at the flat path).
+**Check first, before anything else:** does `~/.wicked-brain/brain.json` exist?
+(That is `brain.json` at the flat parent path, NOT inside `projects/`.) If yes,
+this is a legacy flat brain from before v0.4.7 and you **MUST STOP** the init
+flow and resolve it before continuing.
+
+Read `~/.wicked-brain/brain.json` to find the existing brain's name, then tell
+the user exactly this (substituting the real name):
+
+> "Heads up — there's already a legacy flat brain at `~/.wicked-brain/` named
+> `{existing_name}`. The current layout puts each project under
+> `~/.wicked-brain/projects/{name}/`, so I can't just create a new brain at the
+> parent path without clobbering it. You have two options:
+>
+> 1. **Migrate** the existing `{existing_name}` brain to
+>    `~/.wicked-brain/projects/{existing_name}/` first, then create the new
+>    `{project_name}` brain alongside it. Recommended.
+> 2. **Keep** the flat `{existing_name}` brain where it is and create the new
+>    brain at `~/.wicked-brain/projects/{project_name}/`. This works but leaves
+>    the old brain in a legacy layout.
+>
+> Which do you want?"
+
+Do NOT propose any other options. Do NOT suggest a sibling directory like
+`~/.wicked-bus-brain`. Do NOT suggest nesting inside the existing brain. Do NOT
+proceed with overwriting `~/.wicked-brain/brain.json` under any circumstances.
+
+If the user picks option 1, invoke `wicked-brain:migrate` with
+`flat_path=~/.wicked-brain` and wait for it to complete before continuing.
+
+If the user picks option 2, proceed with the new brain at
+`~/.wicked-brain/projects/{project_name}/` — the flat brain stays untouched.
 
 #### 2b: Check target path
 
@@ -154,17 +189,18 @@ Use your native Write tool to create these directories (write a `.gitkeep` place
 - `{brain_path}/chunks/inferred`
 - `{brain_path}/wiki/concepts`
 - `{brain_path}/wiki/topics`
+- `{brain_path}/memory`
 - `{brain_path}/_meta`
 
 Shell equivalents if needed:
 ```bash
 # macOS/Linux
 mkdir -p {brain_path}/raw {brain_path}/chunks/extracted {brain_path}/chunks/inferred \
-  {brain_path}/wiki/concepts {brain_path}/wiki/topics {brain_path}/_meta
+  {brain_path}/wiki/concepts {brain_path}/wiki/topics {brain_path}/memory {brain_path}/_meta
 ```
 ```powershell
 # Windows PowerShell
-New-Item -ItemType Directory -Force -Path "{brain_path}\raw","{brain_path}\chunks\extracted","{brain_path}\chunks\inferred","{brain_path}\wiki\concepts","{brain_path}\wiki\topics","{brain_path}\_meta"
+New-Item -ItemType Directory -Force -Path "{brain_path}\raw","{brain_path}\chunks\extracted","{brain_path}\chunks\inferred","{brain_path}\wiki\concepts","{brain_path}\wiki\topics","{brain_path}\memory","{brain_path}\_meta"
 ```
 
 ### Step 4: Write brain.json

package/skills/wicked-brain-memory/SKILL.md

@@ -17,7 +17,7 @@ Store and recall experiential learnings in the brain's memory system.
 - Uses `curl` for server API calls (available on Windows 10+, macOS, Linux)
 - File writes use agent-native tools (Write/Edit), not shell commands
 - Path separator: always use forward slashes in `contains:` and `path` fields
-- Brain path default: `~/.wicked-brain` (macOS/Linux), `%USERPROFILE%\.wicked-brain` (Windows)
+- Brain path default: `~/.wicked-brain/projects/{project-name}` (macOS/Linux), `%USERPROFILE%\.wicked-brain\projects\{project-name}` (Windows)
 
 ## Config