@soleri/core 9.8.0 → 9.10.0

package/dist/workflows/workflow-loader.js

@@ -0,0 +1,207 @@
+/**
+ * Workflow loader — reads agent workflow overrides from the file tree.
+ *
+ * Each workflow is a folder under `workflows/` containing:
+ *   - `prompt.md`  — system prompt for the workflow (optional)
+ *   - `gates.yaml` — gate definitions (optional)
+ *   - `tools.yaml` — tool allowlist (optional)
+ *
+ * These overrides are merged into the OrchestrationPlan when
+ * the detected intent matches a workflow via WORKFLOW_TO_INTENT.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+// ---------------------------------------------------------------------------
+// Schemas
+// ---------------------------------------------------------------------------
+export const WorkflowGateSchema = z.object({
+    phase: z.string(),
+    requirement: z.string(),
+    check: z.string(),
+});
+export const WorkflowOverrideSchema = z.object({
+    name: z.string(),
+    prompt: z.string().optional(),
+    gates: z.array(WorkflowGateSchema).default([]),
+    tools: z.array(z.string()).default([]),
+});
+// ---------------------------------------------------------------------------
+// Workflow → Intent mapping
+// ---------------------------------------------------------------------------
+/**
+ * Maps workflow folder names to intent strings.
+ * Used by `getWorkflowForIntent()` to find a matching workflow.
+ */
+export const WORKFLOW_TO_INTENT = {
+    'feature-dev': 'BUILD',
+    'bug-fix': 'FIX',
+    'code-review': 'REVIEW',
+    'component-build': 'BUILD',
+    'token-migration': 'ENHANCE',
+    'a11y-remediation': 'FIX',
+};
+// ---------------------------------------------------------------------------
+// Loader
+// ---------------------------------------------------------------------------
+/**
+ * Load all workflow overrides from an agent's `workflows/` directory.
+ *
+ * Returns an empty Map if the directory doesn't exist or can't be read
+ * (graceful degradation — no throw).
+ */
+export function loadAgentWorkflows(workflowsDir) {
+    const workflows = new Map();
+    let entries;
+    try {
+        entries = fs.readdirSync(workflowsDir);
+    }
+    catch {
+        // Directory doesn't exist or can't be read — that's fine
+        return workflows;
+    }
+    for (const entry of entries) {
+        const fullPath = path.join(workflowsDir, entry);
+        let stat;
+        try {
+            stat = fs.statSync(fullPath);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isDirectory())
+            continue;
+        const override = { name: entry, gates: [], tools: [] };
+        // Read prompt.md
+        const promptPath = path.join(fullPath, 'prompt.md');
+        try {
+            override.prompt = fs.readFileSync(promptPath, 'utf-8').trim();
+        }
+        catch {
+            // No prompt — that's fine
+        }
+        // Read gates.yaml
+        const gatesPath = path.join(fullPath, 'gates.yaml');
+        try {
+            const raw = fs.readFileSync(gatesPath, 'utf-8');
+            // Simple YAML parsing for the gates structure
+            const gates = parseGatesYaml(raw);
+            override.gates = gates;
+        }
+        catch {
+            // No gates — that's fine
+        }
+        // Read tools.yaml
+        const toolsPath = path.join(fullPath, 'tools.yaml');
+        try {
+            const raw = fs.readFileSync(toolsPath, 'utf-8');
+            const tools = parseToolsYaml(raw);
+            override.tools = tools;
+        }
+        catch {
+            // No tools — that's fine
+        }
+        // Only store if we got something useful
+        if (override.prompt || override.gates.length > 0 || override.tools.length > 0) {
+            workflows.set(entry, override);
+        }
+    }
+    return workflows;
+}
+// ---------------------------------------------------------------------------
+// Intent matching
+// ---------------------------------------------------------------------------
+/**
+ * Find a workflow override that matches the given intent.
+ *
+ * Uses WORKFLOW_TO_INTENT mapping, optionally overridden by customMapping.
+ * Returns null if no matching workflow is found.
+ */
+export function getWorkflowForIntent(workflows, intent, customMapping) {
+    const mapping = customMapping ?? WORKFLOW_TO_INTENT;
+    const normalizedIntent = intent.toUpperCase();
+    for (const [workflowName, mappedIntent] of Object.entries(mapping)) {
+        if (mappedIntent.toUpperCase() === normalizedIntent && workflows.has(workflowName)) {
+            return workflows.get(workflowName);
+        }
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Minimal YAML parsers (no external dependency)
+// ---------------------------------------------------------------------------
+/**
+ * Parse a simple gates.yaml file. Expected format:
+ *
+ * ```yaml
+ * gates:
+ *   - phase: brainstorming
+ *     requirement: Requirements are clear
+ *     check: user-approval
+ * ```
+ */
+function parseGatesYaml(raw) {
+    const gates = [];
+    const lines = raw.split('\n');
+    let current = null;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Skip empty lines and the root "gates:" key
+        if (!trimmed || trimmed === 'gates:')
+            continue;
+        // New list item
+        if (trimmed.startsWith('- ')) {
+            if (current && current.phase && current.requirement && current.check) {
+                gates.push(current);
+            }
+            current = {};
+            // Parse inline key from "- phase: value"
+            const inlineMatch = trimmed.match(/^-\s+(\w+):\s*(.+)$/);
+            if (inlineMatch) {
+                const [, key, value] = inlineMatch;
+                if (key === 'phase' || key === 'requirement' || key === 'check') {
+                    current[key] = value.trim();
+                }
+            }
+            continue;
+        }
+        // Continuation key: "    requirement: value"
+        if (current) {
+            const kvMatch = trimmed.match(/^(\w+):\s*(.+)$/);
+            if (kvMatch) {
+                const [, key, value] = kvMatch;
+                if (key === 'phase' || key === 'requirement' || key === 'check') {
+                    current[key] = value.trim();
+                }
+            }
+        }
+    }
+    // Flush last entry
+    if (current && current.phase && current.requirement && current.check) {
+        gates.push(current);
+    }
+    return gates;
+}
+/**
+ * Parse a simple tools.yaml file. Expected format:
+ *
+ * ```yaml
+ * tools:
+ *   - soleri_vault op:search_intelligent
+ *   - soleri_plan op:create_plan
+ * ```
+ */
+function parseToolsYaml(raw) {
+    const tools = [];
+    const lines = raw.split('\n');
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed === 'tools:')
+            continue;
+        if (trimmed.startsWith('- ')) {
+            tools.push(trimmed.slice(2).trim());
+        }
+    }
+    return tools;
+}
+//# sourceMappingURL=workflow-loader.js.map

package/dist/workflows/workflow-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-loader.js","sourceRoot":"","sources":["../../src/workflows/workflow-loader.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soleri/core",
-  "version": "9.8.0",
+  "version": "9.10.0",
   "description": "Shared engine for Soleri agents — vault, brain, planner, LLM utilities, and facade infrastructure.",
   "keywords": [
     "agent",

package/src/__tests__/paths.test.ts

@@ -0,0 +1,31 @@
+import { describe, it, expect } from 'vitest';
+import { join, resolve } from 'node:path';
+import { findProjectRoot } from '../paths.js';
+
+// Resolve the monorepo root from __dirname (packages/core/src/__tests__)
+const MONOREPO_ROOT = resolve(__dirname, '..', '..', '..', '..');
+
+describe('findProjectRoot', () => {
+  it('finds monorepo root from package subdirectory', () => {
+    const packageDir = join(MONOREPO_ROOT, 'packages', 'core');
+    const root = findProjectRoot(packageDir);
+    expect(root).toBe(MONOREPO_ROOT);
+  });
+
+  it('finds root from deeply nested directory', () => {
+    const deepDir = join(MONOREPO_ROOT, 'packages', 'core', 'src', 'runtime');
+    const root = findProjectRoot(deepDir);
+    expect(root).toBe(MONOREPO_ROOT);
+  });
+
+  it('returns root when already at root', () => {
+    const root = findProjectRoot(MONOREPO_ROOT);
+    expect(root).toBe(MONOREPO_ROOT);
+  });
+
+  it('returns startDir as fallback for non-project directory', () => {
+    const tmpDir = '/tmp';
+    const result = findProjectRoot(tmpDir);
+    expect(result).toBe(tmpDir);
+  });
+});

package/src/brain/intelligence.ts

@@ -36,6 +36,8 @@ import type {
 const USAGE_MAX = 10;
 const SPREAD_MAX = 5;
 const RECENCY_DECAY_DAYS = 30;
+const STRENGTH_HALFLIFE_DAYS = 90;
+const STRENGTH_DECAY_FLOOR = 0.3;
 const EXTRACTION_TOOL_THRESHOLD = 3;
 const EXTRACTION_FILE_THRESHOLD = 3;
 const EXTRACTION_HIGH_FEEDBACK_RATIO = 0.8;
@@ -554,11 +556,21 @@ export class BrainIntelligence {
       const successScore = 25 * successRate;
 
       // Recency score: max(0, 25 * (1 - daysSince / RECENCY_DECAY_DAYS))
-      const lastUsedMs = new Date(row.last_used).getTime();
+      // last_used is MAX(created_at) which is unixepoch() (seconds) — convert to ms
+      const lastUsedRaw = Number(row.last_used);
+      const lastUsedMs = lastUsedRaw < 1e12 ? lastUsedRaw * 1000 : lastUsedRaw;
       const daysSince = (now - lastUsedMs) / (1000 * 60 * 60 * 24);
       const recencyScore = Math.max(0, 25 * (1 - daysSince / RECENCY_DECAY_DAYS));
 
-      const strength = usageScore + spreadScore + successScore + recencyScore;
+      const rawStrength = usageScore + spreadScore + successScore + recencyScore;
+
+      // Temporal decay multiplier: exponential halflife with floor
+      // Patterns fade over time but never vanish completely
+      const temporalMultiplier = Math.max(
+        STRENGTH_DECAY_FLOOR,
+        Math.exp((-Math.LN2 * daysSince) / STRENGTH_HALFLIFE_DAYS),
+      );
+      const strength = rawStrength * temporalMultiplier;
 
       const ps: PatternStrength = {
         pattern,
@@ -568,6 +580,7 @@ export class BrainIntelligence {
         spreadScore,
         successScore,
         recencyScore,
+        temporalMultiplier,
         usageCount: row.total,
         uniqueContexts,
         successRate,

package/src/brain/types.ts

@@ -118,6 +118,7 @@ export interface PatternStrength {
   spreadScore: number;
   successScore: number;
   recencyScore: number;
+  temporalMultiplier?: number;
   usageCount: number;
   uniqueContexts: number;
   successRate: number;

package/src/enforcement/adapters/opencode.test.ts

@@ -353,7 +353,8 @@ describe('detectHost', () => {
 
   it('detects opencode via filesystem config when env vars absent', () => {
     mockedExistsSync.mockImplementation((p: unknown) => {
-      const path = String(p);
+      // Normalize to forward slashes so the check works on Windows too
+      const path = String(p).replace(/\\/g, '/');
       if (path.includes('opencode/opencode.json')) return true;
       if (path.includes('.claude')) return false;
       return false;
@@ -364,7 +365,8 @@ describe('detectHost', () => {
 
   it('detects claude-code via filesystem when .claude dir exists', () => {
     mockedExistsSync.mockImplementation((p: unknown) => {
-      const path = String(p);
+      // Normalize to forward slashes so the check works on Windows too
+      const path = String(p).replace(/\\/g, '/');
       if (path.includes('.claude')) return true;
       return false;
     });

package/src/index.ts

@@ -40,9 +40,19 @@ export {
   agentKeysPath,
   agentTemplatesDir,
   agentFlagsPath,
+  agentKnowledgeDir,
+  projectKnowledgeDir,
+  findProjectRoot,
   sharedVaultPath,
 } from './paths.js';
 
+// ─── Vault Markdown Sync ───────────────────────────────────────────
+export {
+  syncAllToMarkdown,
+  syncEntryToMarkdown,
+  entryToMarkdown,
+} from './vault/vault-markdown-sync.js';
+
 // ─── Intelligence ────────────────────────────────────────────────────
 export type {
   IntelligenceEntry,
@@ -901,6 +911,16 @@ export type {
   DeclinedCategory,
 } from './operator/operator-context-types.js';
 
+// ─── Workflows ─────────────────────────────────────────────────────────
+export {
+  WorkflowGateSchema,
+  WorkflowOverrideSchema,
+  WORKFLOW_TO_INTENT,
+  loadAgentWorkflows,
+  getWorkflowForIntent,
+} from './workflows/index.js';
+export type { WorkflowGate, WorkflowOverride } from './workflows/index.js';
+
 // ─── Update Check ────────────────────────────────────────────────────
 export { checkForUpdate, buildChangelogUrl, detectBreakingChanges } from './update-check.js';
 export type { UpdateInfo } from './update-check.js';

package/src/paths.ts

@@ -13,9 +13,9 @@
  * Override with SOLERI_HOME env var or explicit paths in agent.yaml → engine.vault.
  */
 
-import { join } from 'node:path';
+import { join, parse as parsePath } from 'node:path';
 import { homedir } from 'node:os';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 
 /** Root directory for all Soleri data. Default: ~/.soleri/ */
 export const SOLERI_HOME = process.env.SOLERI_HOME ?? join(homedir(), '.soleri');
@@ -109,6 +109,51 @@ export function agentKnowledgeDir(agentId: string): string {
   return join(agentHome(agentId), 'knowledge');
 }
 
+/** Project-local knowledge directory for browsable markdown sync. */
+export function projectKnowledgeDir(projectPath: string): string {
+  return join(projectPath, 'knowledge');
+}
+
+/**
+ * Walk up from startDir to find the actual project/monorepo root.
+ *
+ * Checks for (in order): .git directory, package.json with "workspaces",
+ * or agent.yaml. Returns the first match, or startDir as fallback.
+ *
+ * This prevents vault exports from landing in package subdirectories
+ * when the engine CWD is packages/cli/ instead of the monorepo root.
+ */
+export function findProjectRoot(startDir: string): string {
+  let dir = startDir;
+  const root = parsePath(dir).root;
+
+  while (dir !== root) {
+    // .git is the strongest signal — always marks the project root
+    if (existsSync(join(dir, '.git'))) return dir;
+
+    // package.json with workspaces = monorepo root
+    const pkgPath = join(dir, 'package.json');
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        if (pkg.workspaces) return dir;
+      } catch {
+        /* malformed package.json — skip */
+      }
+    }
+
+    // agent.yaml = file-tree agent root
+    if (existsSync(join(dir, 'agent.yaml'))) return dir;
+
+    // Walk up
+    const parent = join(dir, '..');
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return startDir;
+}
+
 /** Shared vault path: ~/.soleri/vault.db (cross-agent intelligence) */
 export function sharedVaultPath(): string {
   return join(SOLERI_HOME, 'vault.db');

package/src/planning/gap-patterns.ts

@@ -172,12 +172,16 @@ export function analyzeStructure(plan: Plan): PlanGap[] {
   }
 
   if (plan.tasks.length === 0) {
+    const hasApproachSteps =
+      plan.approach && /(?:step\s+\d|task\s+\d|\d\.\s|\d\)\s)/i.test(plan.approach);
     gaps.push(
       gap(
-        'critical',
+        hasApproachSteps ? 'major' : 'critical',
         'structure',
-        'Plan has no tasks.',
-        'Add at least one task to make the plan actionable.',
+        hasApproachSteps
+          ? 'Plan has no tasks but approach contains steps. Use `addTasks` in `plan_iterate` or pass `tasks` in `create_plan` to promote them.'
+          : 'Plan has no tasks.',
+        'Add tasks via `create_plan` (tasks param) or `plan_iterate` (addTasks param).',
         'tasks',
         'no_tasks',
       ),

package/src/runtime/admin-setup-ops.ts

@@ -33,6 +33,7 @@ import {
   injectAtPosition,
   buildInjectionContent,
   injectEngineRulesBlock,
+  removeEngineRulesFromGlobal,
 } from './claude-md-helpers.js';
 import { discoverSkills, syncSkillsToClaudeCode } from '../skills/sync-skills.js';
 
@@ -295,9 +296,9 @@ export function createAdminSetupOps(runtime: AgentRuntime): OpDefinition[] {
         const filePath = targetPath ?? join(projectPath, 'CLAUDE.md');
         const existingContent = existsSync(filePath) ? readFileSync(filePath, 'utf-8') : '';
 
-        // Inject engine rules if this is a global injection and agentDir is available
+        // Inject engine rules only for project-level injection (NOT global)
         let contentWithEngineRules = existingContent;
-        if (isGlobal && config.agentDir) {
+        if (!isGlobal && config.agentDir) {
           const enginePath = join(config.agentDir, 'instructions', '_engine.md');
           if (existsSync(enginePath)) {
             const engineRulesContent = readFileSync(enginePath, 'utf-8');
@@ -460,14 +461,41 @@ export function createAdminSetupOps(runtime: AgentRuntime): OpDefinition[] {
           }
         }
 
+        // 4. Self-healing: strip engine rules from global files if present
+        const selfHealing = { engineRulesRemoved: false, agentsMdEngineRulesRemoved: false };
+        if (install) {
+          const globalClaudeMdPath = join(globalClaudeDir, 'CLAUDE.md');
+          if (existsSync(globalClaudeMdPath)) {
+            const result = removeEngineRulesFromGlobal(readFileSync(globalClaudeMdPath, 'utf-8'));
+            if (result.removed) {
+              writeFileSync(globalClaudeMdPath, result.cleaned, 'utf-8');
+              selfHealing.engineRulesRemoved = true;
+            }
+          }
+
+          const globalAgentsMdPath = join(homedir(), '.config', 'opencode', 'AGENTS.md');
+          if (existsSync(globalAgentsMdPath)) {
+            const result = removeEngineRulesFromGlobal(readFileSync(globalAgentsMdPath, 'utf-8'));
+            if (result.removed) {
+              writeFileSync(globalAgentsMdPath, result.cleaned, 'utf-8');
+              selfHealing.agentsMdEngineRulesRemoved = true;
+            }
+          }
+        }
+
         return {
           dryRun: !install,
           agentId: config.agentId,
           hookifyRules: hookifyResults,
           skills: skillsResults,
           settingsJson: settingsResults,
+          selfHealing,
           ...(install
-            ? { message: 'Global setup complete' }
+            ? {
+                message: selfHealing.engineRulesRemoved
+                  ? 'Global setup complete (engine rules removed from global CLAUDE.md)'
+                  : 'Global setup complete',
+              }
             : { message: 'Dry run — pass install: true to apply' }),
         };
       },

package/src/runtime/capture-ops.test.ts

@@ -14,12 +14,14 @@ vi.mock('../vault/scope-detector.js', () => ({
   })),
 }));
 
+const mockSyncEntryToMarkdown = vi.fn(() => Promise.resolve({ written: true }));
 vi.mock('../vault/vault-markdown-sync.js', () => ({
-  syncEntryToMarkdown: vi.fn(() => Promise.resolve()),
+  syncEntryToMarkdown: (...args: unknown[]) => mockSyncEntryToMarkdown(...args),
 }));
 
 vi.mock('../paths.js', () => ({
   agentKnowledgeDir: vi.fn(() => '/mock/knowledge'),
+  projectKnowledgeDir: vi.fn((p: string) => `/mock/project/${p}/knowledge`),
 }));
 
 // ─── Mock Runtime Factory ──────────────────────────────────────────────
@@ -213,6 +215,32 @@ describe('createCaptureOps', () => {
       const results = result.results as Array<Record<string, unknown>>;
       expect((results[0].scope as Record<string, unknown>).tier).toBe('agent');
     });
+
+    it('triggers markdown file write on successful capture', async () => {
+      mockSyncEntryToMarkdown.mockClear();
+      await findOp(ops, 'capture_knowledge').handler({
+        entries: [
+          { type: 'pattern', domain: 'testing', title: 'Sync Test', description: 'test', tags: [] },
+        ],
+      });
+      // fire-and-forget: allow microtask to flush
+      await new Promise((r) => setTimeout(r, 10));
+      expect(mockSyncEntryToMarkdown).toHaveBeenCalledWith(
+        expect.objectContaining({ domain: 'testing', title: 'Sync Test' }),
+        '/mock/knowledge',
+      );
+    });
+
+    it('does not block capture response when sync fails', async () => {
+      mockSyncEntryToMarkdown.mockClear();
+      mockSyncEntryToMarkdown.mockRejectedValueOnce(new Error('disk full'));
+      const result = (await findOp(ops, 'capture_knowledge').handler({
+        entries: [{ type: 'pattern', domain: 'a', title: 'A', description: 'a', tags: [] }],
+      })) as Record<string, unknown>;
+      // Capture should still succeed despite sync error
+      expect(result.captured).toBe(1);
+      expect(result.rejected).toBe(0);
+    });
   });
 
   describe('capture_quick', () => {
@@ -323,6 +351,35 @@ describe('createCaptureOps', () => {
       expect(result.captured).toBe(false);
       expect((result.governance as Record<string, unknown>).action).toBe('error');
     });
+
+    it('triggers markdown file write on successful capture', async () => {
+      mockSyncEntryToMarkdown.mockClear();
+      await findOp(ops, 'capture_quick').handler({
+        type: 'pattern',
+        domain: 'testing',
+        title: 'Quick Sync Test',
+        description: 'quick test',
+      });
+      // fire-and-forget: allow microtask to flush
+      await new Promise((r) => setTimeout(r, 10));
+      expect(mockSyncEntryToMarkdown).toHaveBeenCalledWith(
+        expect.objectContaining({ domain: 'testing', title: 'Quick Sync Test' }),
+        '/mock/knowledge',
+      );
+    });
+
+    it('does not block capture response when sync fails', async () => {
+      mockSyncEntryToMarkdown.mockClear();
+      mockSyncEntryToMarkdown.mockRejectedValueOnce(new Error('disk full'));
+      const result = (await findOp(ops, 'capture_quick').handler({
+        type: 'pattern',
+        domain: 'testing',
+        title: 'Quick Fail',
+        description: 'test',
+      })) as Record<string, unknown>;
+      // Capture should still succeed despite sync error
+      expect(result.captured).toBe(true);
+    });
   });
 
   describe('search_intelligent', () => {

package/src/runtime/capture-ops.ts

@@ -11,7 +11,7 @@ import type { AgentRuntime } from './types.js';
 import { detectScope } from '../vault/scope-detector.js';
 import type { ScopeTier, ScopeDetectionResult } from '../vault/scope-detector.js';
 import { syncEntryToMarkdown } from '../vault/vault-markdown-sync.js';
-import { agentKnowledgeDir } from '../paths.js';
+import { agentKnowledgeDir, projectKnowledgeDir, findProjectRoot } from '../paths.js';
 import type { IntelligenceEntry } from '../intelligence/types.js';
 
 /**
@@ -189,6 +189,7 @@ export function createCaptureOps(runtime: AgentRuntime): OpDefinition[] {
                         origin: 'user',
                       },
                       config.agentId,
+                      projectPath,
                     );
                   }
                 } catch (err) {
@@ -417,6 +418,7 @@ export function createCaptureOps(runtime: AgentRuntime): OpDefinition[] {
                     origin: 'user',
                   },
                   config.agentId,
+                  projectPath,
                 );
                 return result;
               } catch (err) {
@@ -629,9 +631,18 @@ function mapType(type: string): 'pattern' | 'anti-pattern' | 'rule' | 'playbook'
 }
 
 /** Fire-and-forget markdown sync — never blocks capture, logs errors silently. */
-function fireAndForgetSync(entry: IntelligenceEntry, agentId: string): void {
-  const knowledgeDir = agentKnowledgeDir(agentId);
-  syncEntryToMarkdown(entry, knowledgeDir).catch(() => {
+function fireAndForgetSync(entry: IntelligenceEntry, agentId: string, projectPath?: string): void {
+  // Always sync to agent home dir
+  const agentDir = agentKnowledgeDir(agentId);
+  syncEntryToMarkdown(entry, agentDir).catch(() => {
     /* non-blocking — markdown sync is best-effort */
   });
+
+  // Also sync to project-local knowledge dir if a real project path is provided
+  if (projectPath && projectPath !== '.') {
+    const projDir = projectKnowledgeDir(findProjectRoot(projectPath));
+    syncEntryToMarkdown(entry, projDir).catch(() => {
+      /* non-blocking — markdown sync is best-effort */
+    });
+  }
 }