total-recall-brain 3.18.3 → 3.19.0

package/src/server/routes/dashboard.mjs

@@ -1,52 +1,73 @@
 import { Router } from 'express';
 import fs from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { requireAuth, requireScope } from '../auth.mjs';
 import { getNodes } from '../../core/vault-cache.mjs';
-import { VAULT_DIR, INSTRUCTIONS } from './_shared.mjs';
+import {
+  VAULT_DIR,
+  INSTRUCTIONS,
+  ROOT as SHARED_ROOT,
+  resolveVaultFromQuery,
+  pathsForVault,
+} from './_shared.mjs';
 
 const router = Router();
-const ROOT = process.env.TR_ROOT || path.join(path.dirname(new URL(import.meta.url).pathname), '..', '..', '..');
+// Prefer shared ROOT (fileURLToPath-safe). Fall back with fileURLToPath — never URL.pathname
+// (breaks on Windows and on paths with encoded characters).
+const ROOT = process.env.TR_ROOT || SHARED_ROOT || path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
 
 router.get('/api/dashboard/instructions', requireAuth, requireScope('instructions:read'), (req, res) => {
+  const vaultDir = resolveVaultFromQuery(req);
+  const paths = pathsForVault(vaultDir);
+  // skillsDir = …/.agent/skills → agentDir = …/.agent; surfaces often at repo root (parent of .agent)
+  const agentDir = path.dirname(paths.skillsDir);
+  const surfaceBase =
+    path.basename(agentDir) === '.agent' ? path.dirname(agentDir) : agentDir;
+
   const surfaces = [];
   const surfaceFiles = ['AGENTS.md', 'GEMINI.md', 'CLAUDE.md', 'INSTRUCTIONS.md'];
-  
+
   for (const name of surfaceFiles) {
-    let filePath;
-    if (name === 'INSTRUCTIONS.md') {
-      filePath = path.join(ROOT, name);
-    } else {
-      filePath = path.join(ROOT, name);
-    }
-    
+    // Prefer agent-adjacent surfaces; fall back to package ROOT for monorepo dashboard
+    const candidates = [
+      path.join(surfaceBase, name),
+      path.join(agentDir, name),
+      path.join(ROOT, name),
+    ];
+    let filePath = candidates.find((p) => fs.existsSync(p)) || candidates[0];
+
     let size = 0;
     let lastCompiled = '';
     let active = false;
-    
+
     if (fs.existsSync(filePath)) {
       const stat = fs.statSync(filePath);
       size = stat.size;
       lastCompiled = stat.mtime.toISOString();
       active = true;
     }
-    
+
     surfaces.push({
       name,
       filename: name,
       size,
       lastCompiled,
-      active
+      active,
     });
   }
-  
-  const lastCompileTimestamp = fs.existsSync(INSTRUCTIONS) ? fs.statSync(INSTRUCTIONS).mtime.toISOString() : '';
-  const totalNodes = fs.existsSync(VAULT_DIR) ? getNodes(VAULT_DIR).length : 0;
-  
+
+  const instructionsFile = paths.instructionsFile || INSTRUCTIONS;
+  const lastCompileTimestamp = fs.existsSync(instructionsFile)
+    ? fs.statSync(instructionsFile).mtime.toISOString()
+    : '';
+  const totalNodes = fs.existsSync(vaultDir) ? getNodes(vaultDir).length : 0;
+
   res.json({
     surfaces,
     lastCompileTimestamp,
-    totalNodes
+    totalNodes,
+    vault_dir: vaultDir,
   });
 });
 

package/src/server/routes/docs.mjs

@@ -27,10 +27,26 @@ function getRegistryTypes(brainDir) {
   return {};
 }
 
-// Ensure the path is safe
+// Ensure the path is safe (relative, no traversal)
 function isSafePath(p) {
-  const normalized = path.normalize(p).replace(/^(\.\.(\/|\\|$))+/, '');
-  return normalized === p && !p.startsWith('/') && !p.includes('..');
+  if (!p || typeof p !== 'string' || p.includes('\0')) return false;
+  if (path.isAbsolute(p)) return false;
+  const normalized = path.normalize(p);
+  // Reject any path that still escapes after normalize
+  if (normalized.startsWith('..') || normalized.includes(`${path.sep}..${path.sep}`) || normalized.endsWith(`${path.sep}..`)) {
+    return false;
+  }
+  if (normalized.includes('..')) return false;
+  return true;
+}
+
+/** Resolve relPath under vaultDir; returns null if it escapes the vault. */
+function resolveSafeVaultPath(vaultDir, relPath) {
+  if (!isSafePath(relPath)) return null;
+  const root = path.resolve(vaultDir);
+  const abs = path.resolve(vaultDir, relPath);
+  if (abs !== root && !abs.startsWith(root + path.sep)) return null;
+  return abs;
 }
 
 /**
@@ -108,9 +124,8 @@ router.get('/api/docs/read', requireAuth, requireScope('ssss:read'), (req, res)
   try {
     const vaultDir = resolveVaultFromQuery(req);
     const relPath = req.query.path;
-    if (!relPath || !isSafePath(relPath)) return badRequest(res, 'Invalid path');
-
-    const absPath = path.join(vaultDir, relPath);
+    const absPath = resolveSafeVaultPath(vaultDir, relPath);
+    if (!absPath) return badRequest(res, 'Invalid path');
     if (!fs.existsSync(absPath)) return notFound(res, 'Document not found');
 
     const raw = fs.readFileSync(absPath, 'utf8');
@@ -134,8 +149,8 @@ router.post('/api/docs', requireAuth, requireScope('ssss:write'), async (req, re
     const vaultDir = resolveVaultFromQuery(req);
     const { path: relPath, content } = req.body;
     
-    if (!relPath || !isSafePath(relPath)) return badRequest(res, 'Invalid path');
-    const absPath = path.join(vaultDir, relPath);
+    const absPath = resolveSafeVaultPath(vaultDir, relPath);
+    if (!absPath) return badRequest(res, 'Invalid path');
     if (fs.existsSync(absPath)) return res.status(409).json({ error: 'Document already exists' });
 
     const envelope = {
@@ -164,8 +179,8 @@ router.put('/api/docs', requireAuth, requireScope('ssss:write'), async (req, res
     const vaultDir = resolveVaultFromQuery(req);
     const { path: relPath, content } = req.body;
     
-    if (!relPath || !isSafePath(relPath)) return badRequest(res, 'Invalid path');
-    const absPath = path.join(vaultDir, relPath);
+    const absPath = resolveSafeVaultPath(vaultDir, relPath);
+    if (!absPath) return badRequest(res, 'Invalid path');
     if (!fs.existsSync(absPath)) return notFound(res, 'Document not found');
 
     const envelope = {
@@ -193,9 +208,8 @@ router.delete('/api/docs', requireAuth, requireScope('ssss:write'), async (req,
   try {
     const vaultDir = resolveVaultFromQuery(req);
     const relPath = req.query.path;
-    
-    if (!relPath || !isSafePath(relPath)) return badRequest(res, 'Invalid path');
-    const absPath = path.join(vaultDir, relPath);
+    const absPath = resolveSafeVaultPath(vaultDir, relPath);
+    if (!absPath) return badRequest(res, 'Invalid path');
     if (!fs.existsSync(absPath)) return notFound(res, 'Document not found');
 
     const envelope = {

package/src/server/routes/dream.mjs

@@ -1,27 +1,26 @@
 import { Router } from 'express';
-import fs from 'node:fs';
 import path from 'node:path';
-import crypto from 'node:crypto';
 import { requireAuth, requireScope } from '../auth.mjs';
-import { serverError, ROOT, BRAIN_DIR, VAULT_DIR, SKILLS_DIR, INSTRUCTIONS, DERIVED_DIR } from './_shared.mjs';
-import { logger } from '../../core/logger.mjs';
+import { serverError, resolveVaultFromQuery, pathsForVault } from './_shared.mjs';
 
 const router = Router();
 
 router.post('/api/dream', requireAuth, requireScope('memory:recompile'), async (req, res) => {
   try {
     const { runDreamCycle } = await import('../../core/dream.mjs');
-    const conflictsDir = path.join(BRAIN_DIR, 'memory-inbox', 'conflicts');
-    
+    const vaultDir = resolveVaultFromQuery(req);
+    const paths = pathsForVault(vaultDir);
+    const conflictsDir = path.join(paths.brainDir, 'memory-inbox', 'conflicts');
+
     const result = await runDreamCycle({
-      vaultDir: VAULT_DIR,
-      skillsDir: SKILLS_DIR,
-      derivedDir: DERIVED_DIR,
+      vaultDir,
+      skillsDir: paths.skillsDir,
+      derivedDir: paths.derivedDir,
       conflictsDir,
-      instructionsFile: INSTRUCTIONS,
+      instructionsFile: paths.instructionsFile,
     });
 
-    res.json({ success: true, status: result.status });
+    res.json({ success: true, status: result.status, vault_dir: vaultDir });
   } catch (err) {
     serverError(res, err);
   }

package/src/server/routes/export.mjs

@@ -1,22 +1,28 @@
 import { Router } from 'express';
 import fs from 'node:fs';
 import path from 'node:path';
-import crypto from 'node:crypto';
 import { spawn } from 'node:child_process';
 import { requireAuth, requireScope } from '../auth.mjs';
-import { serverError, ROOT, BRAIN_DIR, VAULT_DIR, SKILLS_DIR, INSTRUCTIONS, DERIVED_DIR, SESSIONS_DIR } from './_shared.mjs';
-import { logger } from '../../core/logger.mjs';
+import {
+  serverError,
+  resolveVaultFromQuery,
+  pathsForVault,
+} from './_shared.mjs';
 
 const router = Router();
 
 router.get('/api/brain/export', requireAuth, requireScope('brain:export'), async (req, res) => {
   try {
+    const vaultDir = resolveVaultFromQuery(req);
+    const paths = pathsForVault(vaultDir);
+    const brainDir = paths.brainDir;
+
     const ALL_PARTS = {
-      vault:    VAULT_DIR,
-      derived:  DERIVED_DIR,
-      sessions: SESSIONS_DIR,
-      config:   path.join(BRAIN_DIR, 'config'),
-      skills:   SKILLS_DIR,
+      vault:    vaultDir,
+      derived:  paths.derivedDir,
+      sessions: paths.sessionsDir,
+      config:   path.join(brainDir, 'config'),
+      skills:   paths.skillsDir,
     };
     const requested = req.query.include
       ? String(req.query.include).split(',').map(s => s.trim())
@@ -27,14 +33,39 @@ router.get('/api/brain/export', requireAuth, requireScope('brain:export'), async
     const date = new Date().toISOString().slice(0, 10);
     res.setHeader('Content-Type', 'application/gzip');
     res.setHeader('Content-Disposition', `attachment; filename="total-recall-brain-${date}.tar.gz"`);
+    res.setHeader('X-Total-Recall-Vault', vaultDir);
+
+    // Only pack paths under brainDir (avoid `..` parent escapes for skills)
+    const relativeDirs = [];
+    for (const k of dirs) {
+      const abs = ALL_PARTS[k];
+      const rel = path.relative(brainDir, abs);
+      if (rel.startsWith('..') || path.isAbsolute(rel)) {
+        // skills lives as sibling of total-recall under .agent/skills — skip unsafe parent
+        if (k === 'skills') continue;
+        continue;
+      }
+      relativeDirs.push(rel || '.');
+    }
+    if (relativeDirs.length === 0) {
+      // Always can pack vault at least
+      relativeDirs.push(path.relative(brainDir, vaultDir) || 'memory-vault');
+    }
 
-    const relativeDirs = dirs.map(k => path.relative(BRAIN_DIR, ALL_PARTS[k]));
-    const tar = spawn('tar', ['czf', '-', '-C', BRAIN_DIR, '--exclude=security.yml', '--exclude=keys.jsonl', '--exclude=session-secret', ...relativeDirs], { stdio: ['ignore', 'pipe', 'ignore'] });
+    const tar = spawn('tar', [
+      'czf', '-',
+      '-C', brainDir,
+      '--exclude=security.yml',
+      '--exclude=keys.jsonl',
+      '--exclude=session-secret',
+      ...relativeDirs,
+    ], { stdio: ['ignore', 'pipe', 'ignore'] });
     tar.stdout.pipe(res);
     tar.on('error', err => { if (!res.headersSent) serverError(res, err); });
     tar.on('close', code => { if (code !== 0 && !res.writableEnded) res.end(); });
-    
-  } catch (err) { serverError(res, err); }
+  } catch (err) {
+    serverError(res, err);
+  }
 });
 
 export default router;

package/src/server/routes/field.mjs

@@ -1,18 +1,16 @@
 import { Router } from 'express';
-import fs from 'node:fs';
-import path from 'node:path';
-import crypto from 'node:crypto';
 import { requireAuth, requireScope } from '../auth.mjs';
-import { serverError, ROOT, BRAIN_DIR, VAULT_DIR, SKILLS_DIR, INSTRUCTIONS, DERIVED_DIR, badRequest } from './_shared.mjs';
-import { logger } from '../../core/logger.mjs';
+import { serverError, badRequest, resolveVaultFromQuery, pathsForVault } from './_shared.mjs';
 
 const router = Router();
 
 router.post('/api/field/compile', requireAuth, requireScope('memory:recompile'), async (req, res) => {
   try {
     const { compileField } = await import('../../core/vector-field.mjs');
-    const result = await compileField({ vaultDir: VAULT_DIR, derivedDir: DERIVED_DIR });
-    res.json({ compiled: true, ...result.meta });
+    const vaultDir = resolveVaultFromQuery(req);
+    const { derivedDir } = pathsForVault(vaultDir);
+    const result = await compileField({ vaultDir, derivedDir });
+    res.json({ compiled: true, vault_dir: vaultDir, ...result.meta });
   } catch (err) {
     serverError(res, err);
   }
@@ -23,12 +21,14 @@ router.post('/api/field/sample', requireAuth, requireScope('memory:read'), async
     const { sampleField } = await import('../../core/vector-field.mjs');
     const { query, top_k, entanglement_boost, velocity_weight } = req.body || {};
     if (!query) return badRequest(res, 'query is required');
+    const vaultDir = resolveVaultFromQuery(req);
+    const { derivedDir } = pathsForVault(vaultDir);
     const result = await sampleField({
       query,
       topK: top_k,
       entanglementBoost: entanglement_boost,
       velocityWeight: velocity_weight,
-      derivedDir: DERIVED_DIR,
+      derivedDir,
     });
     res.json(result);
   } catch (err) {
@@ -39,7 +39,9 @@ router.post('/api/field/sample', requireAuth, requireScope('memory:read'), async
 router.get('/api/field/stats', requireAuth, requireScope('memory:read'), async (req, res) => {
   try {
     const { fieldStats } = await import('../../core/vector-field.mjs');
-    res.json(fieldStats(DERIVED_DIR));
+    const vaultDir = resolveVaultFromQuery(req);
+    const { derivedDir } = pathsForVault(vaultDir);
+    res.json({ vault_dir: vaultDir, ...fieldStats(derivedDir) });
   } catch (err) {
     serverError(res, err);
   }

package/src/server/routes/graph.mjs

@@ -30,14 +30,24 @@ import {
   ROOT,
   badRequest,
   serverError,
+  resolveVaultFromQuery,
+  pathsForVault,
 } from './_shared.mjs';
 
 const router = Router();
 
 // ─── Helpers ───────────────────────────────────────────────────────────────────
 
-function isDashboardEnhanced() {
-  return fs.existsSync(path.join(VAULT_DIR, '..', 'preferences', 'dashboard-enhanced.md'));
+/**
+ * Feature flag file locations:
+ * - Production SSSS layout: <vault>/preferences/dashboard-enhanced.md
+ * - Legacy/test layout: <vault>/../preferences/dashboard-enhanced.md
+ */
+function isDashboardEnhanced(vaultDir = VAULT_DIR) {
+  return (
+    fs.existsSync(path.join(vaultDir, 'preferences', 'dashboard-enhanced.md')) ||
+    fs.existsSync(path.join(vaultDir, '..', 'preferences', 'dashboard-enhanced.md'))
+  );
 }
 
 function sha256(content) {
@@ -124,19 +134,23 @@ function safeReferencePath(name) {
  * Requires dashboard-enhanced feature flag.
  */
 router.get('/api/graph', requireAuth, requireScope('ssss:read'), (req, res) => {
-  if (!isDashboardEnhanced()) {
+  const vaultDir = resolveVaultFromQuery(req);
+  if (!isDashboardEnhanced(vaultDir)) {
     return res.status(404).json({ error: 'dashboard-enhanced feature flag not enabled' });
   }
   try {
-    const graphFile = path.join(DERIVED_DIR, 'graph-index.jsonl');
-    const routesFile = path.join(DERIVED_DIR, 'skill-routes.jsonl');
+    const { derivedDir } = pathsForVault(vaultDir);
+    // Prefer brain-local derived; fall back to shared DERIVED_DIR (tests/mocks)
+    const derived = fs.existsSync(derivedDir) ? derivedDir : DERIVED_DIR;
+    const graphFile = path.join(derived, 'graph-index.jsonl');
+    const routesFile = path.join(derived, 'skill-routes.jsonl');
     const nodes = fs.existsSync(graphFile)
       ? fs.readFileSync(graphFile, 'utf8').split('\n').filter(Boolean).map(l => JSON.parse(l))
       : [];
     const routes = fs.existsSync(routesFile)
       ? fs.readFileSync(routesFile, 'utf8').split('\n').filter(Boolean).map(l => JSON.parse(l))
       : [];
-    res.json({ nodes, routes });
+    res.json({ nodes, routes, vault_dir: vaultDir });
   } catch (err) { serverError(res, err); }
 });
 
@@ -146,11 +160,13 @@ router.get('/api/graph', requireAuth, requireScope('ssss:read'), (req, res) => {
  * Requires dashboard-enhanced feature flag.
  */
 router.get('/api/conflicts', requireAuth, requireScope('ssss:read'), async (req, res) => {
-  if (!isDashboardEnhanced()) {
+  const vaultDir = resolveVaultFromQuery(req);
+  if (!isDashboardEnhanced(vaultDir)) {
     return res.status(404).json({ error: 'dashboard-enhanced feature flag not enabled' });
   }
   try {
-    const conflictsDir = path.join(BRAIN_DIR, 'memory-inbox', 'conflicts');
+    const paths = pathsForVault(vaultDir);
+    const conflictsDir = path.join(paths.brainDir, 'memory-inbox', 'conflicts');
     const conflicts = [];
 
     if (fs.existsSync(conflictsDir)) {
@@ -166,9 +182,9 @@ router.get('/api/conflicts', requireAuth, requireScope('ssss:read'), async (req,
       }
     }
 
-    // Dynamic scan
+    // Dynamic scan for the requested brain (not always global)
     const { detectSemanticConflicts } = await import('../../core/conflict-detector.mjs');
-    const list = getNodes(VAULT_DIR);
+    const list = getNodes(vaultDir);
     const dynamicConflicts = [];
     for (let i = 0; i < list.length; i++) {
       const found = detectSemanticConflicts(list[i], list.slice(0, i));
@@ -207,15 +223,17 @@ router.post('/api/conflicts/resolve', requireAuth, requireScope('memory:write'),
       return badRequest(res, "action must be either 'keep' or 'supersede'");
     }
 
-    const inboxDir = path.join(BRAIN_DIR, 'memory-inbox');
+    const vaultDir = resolveVaultFromQuery(req);
+    const paths = pathsForVault(vaultDir);
+    const inboxDir = path.join(paths.brainDir, 'memory-inbox');
     const { resolveConflict } = await import('../../core/conflict-detector.mjs');
     const result = resolveConflict(conflict_id, inboxDir, action, winner_slug);
     if (!result.resolved) {
       return badRequest(res, result.error || 'Failed to resolve conflict');
     }
 
-    invalidate(); // clear cache
-    res.json({ success: true, conflict_id });
+    invalidate(vaultDir);
+    res.json({ success: true, conflict_id, vault_dir: vaultDir });
   } catch (err) {
     serverError(res, err);
   }

package/src/server/routes/import.mjs

@@ -1,39 +1,58 @@
 import { Router } from 'express';
-import fs from 'node:fs';
 import path from 'node:path';
-import crypto from 'node:crypto';
 import { requireAuth, requireScope } from '../auth.mjs';
-import { serverError, ROOT, BRAIN_DIR, VAULT_DIR, SKILLS_DIR, INSTRUCTIONS, badRequest } from './_shared.mjs';
-import { logger } from '../../core/logger.mjs';
+import {
+  serverError,
+  ROOT,
+  VAULT_DIR,
+  badRequest,
+  resolveVaultFromQuery,
+} from './_shared.mjs';
 import { detectRuleFiles, importRuleFiles } from '../../core/import-rules.mjs';
 
 const router = Router();
 
 router.get('/api/import/rules', requireAuth, requireScope('memory:read'), (req, res) => {
   try {
-    const allowedRoots = [ROOT, VAULT_DIR];
-    const rawDirs = req.query.dir ? (Array.isArray(req.query.dir) ? req.query.dir : [req.query.dir]) : allowedRoots;
-    const dirs = rawDirs.filter(d => allowedRoots.some(root => path.resolve(d).startsWith(path.resolve(root))));
+    const vaultDir = resolveVaultFromQuery(req);
+    const allowedRoots = [ROOT, VAULT_DIR, vaultDir, path.dirname(ROOT)];
+    const rawDirs = req.query.dir ? (Array.isArray(req.query.dir) ? req.query.dir : [req.query.dir]) : [ROOT];
+    const dirs = rawDirs.filter(d =>
+      allowedRoots.some(root => path.resolve(d).startsWith(path.resolve(root))),
+    );
     if (dirs.length === 0) return badRequest(res, 'No permitted directories specified');
     const detected = detectRuleFiles(dirs);
-    res.json({ dirs, detected });
-    
-  } catch (err) { serverError(res, err); }
+    res.json({ dirs, detected, vault_dir: vaultDir });
+  } catch (err) {
+    serverError(res, err);
+  }
 });
 
 router.post('/api/import/rules', requireAuth, requireScope('memory:write'), async (req, res) => {
   try {
     const { dirs, force = false, dryRun = false } = req.body || {};
-    const searchDirs = dirs?.length ? dirs : [ROOT, VAULT_DIR];
+    const vaultDir = resolveVaultFromQuery(req);
+    const searchDirs = dirs?.length ? dirs : [ROOT];
     const detected = detectRuleFiles(searchDirs);
     const toImport = req.body?.files?.length
       ? detected.filter(f => req.body.files.includes(f.absolutePath))
       : detected.filter(f => !f.alreadyImported || force);
-    if (dryRun) return res.json({ dryRun: true, detected, toImport, imported: [], skipped: [], failed: [] });
-    const result = await importRuleFiles(toImport, { force, vaultDir: VAULT_DIR });
-    res.json({ detected, ...result });
-    
-  } catch (err) { serverError(res, err); }
+    if (dryRun) {
+      return res.json({
+        dryRun: true,
+        detected,
+        toImport,
+        imported: [],
+        skipped: [],
+        failed: [],
+        vault_dir: vaultDir,
+      });
+    }
+    const result = await importRuleFiles(toImport, { force, vaultDir });
+    res.json({ detected, vault_dir: vaultDir, ...result });
+  } catch (err) {
+    serverError(res, err);
+  }
 });
 
 export default router;

package/src/server/routes/instructions.mjs

@@ -1,15 +1,49 @@
 import { Router } from 'express';
 import fs from 'node:fs';
 import path from 'node:path';
-import crypto from 'node:crypto';
 import { requireAuth, requireScope } from '../auth.mjs';
-import { serverError, ROOT, BRAIN_DIR, VAULT_DIR, SKILLS_DIR, INSTRUCTIONS } from './_shared.mjs';
+import {
+  serverError,
+  INSTRUCTIONS,
+  ROOT,
+  resolveVaultFromQuery,
+  pathsForVault,
+} from './_shared.mjs';
 import { logger } from '../../core/logger.mjs';
 
 const router = Router();
 
+function resolveInstructionsPath(req) {
+  const vaultDir = resolveVaultFromQuery(req);
+  const paths = pathsForVault(vaultDir);
+  // Prefer brain-local INSTRUCTIONS, then shared constant, then package ROOT
+  const candidates = [
+    paths.instructionsFile,
+    // surface compile often writes to parent of .agent (repo root)
+    path.join(path.dirname(path.dirname(paths.skillsDir)), 'INSTRUCTIONS.md'),
+    INSTRUCTIONS,
+    path.join(ROOT, 'INSTRUCTIONS.md'),
+  ];
+  for (const p of candidates) {
+    if (p && fs.existsSync(p)) return p;
+  }
+  return paths.instructionsFile || INSTRUCTIONS;
+}
+
+function sendTextResource(res, filePath, label) {
+  try {
+    if (!fs.existsSync(filePath)) {
+      return res.status(404).json({ error: `${label} not found`, path: filePath });
+    }
+    const content = fs.readFileSync(filePath, 'utf8');
+    res.type('text/markdown').send(content);
+  } catch (err) {
+    serverError(res, err);
+  }
+}
+
 router.get('/api/instructions', requireAuth, requireScope('instructions:read'), (req, res) => {
-  return sendTextResource(res, path.join(ROOT, 'INSTRUCTIONS.md'), 'instructions');
+  return sendTextResource(res, resolveInstructionsPath(req), 'instructions');
 });
 
 router.put('/api/instructions', requireAuth, requireScope('instructions:write'), (req, res) => {
@@ -18,8 +52,10 @@ router.put('/api/instructions', requireAuth, requireScope('instructions:write'),
     return res.status(400).json({ error: 'Missing or invalid `content` field.' });
   }
   try {
-    fs.writeFileSync(INSTRUCTIONS, content, 'utf8');
-    return res.json({ success: true, message: 'Instructions updated successfully' });
+    const target = resolveInstructionsPath(req);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, content, 'utf8');
+    return res.json({ success: true, message: 'Instructions updated successfully', path: target });
   } catch (err) {
     logger.error('api', `Failed to write instructions: ${err.message}`);
     return res.status(500).json({ error: err.message });