@agentprojectcontext/apx 1.57.0 → 1.58.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentprojectcontext/apx",
-  "version": "1.57.0",
+  "version": "1.58.0",
   "description": "APX — unified CLI + daemon for the Agent Project Context (APC) standard.",
   "publishConfig": {
     "access": "public"

package/src/core/apc/paths.js

@@ -18,6 +18,7 @@ export const APC_SKILLS_DIR = "skills";
 export const APC_COMMANDS_DIR = "commands";
 export const APC_NOTES_DIR = "notes";
 export const APC_MCPS_FILE = "mcps.json";
+export const APC_ORGANIZATION_FILE = "organization.json";
 export const APC_REMOVED_FILE = ".removed.json";
 export const AGENTS_MD = "AGENTS.md";
 
@@ -77,6 +78,12 @@ export function apcMcpsFile(root) {
   return path.join(root, APC_DIR, APC_MCPS_FILE);
 }
 
+// Org structure (areas + roles) for company/enterprise projects. Committed,
+// no secrets — travels with the project like agents do.
+export function apcOrganizationFile(root) {
+  return path.join(root, APC_DIR, APC_ORGANIZATION_FILE);
+}
+
 export function agentsMdFile(root) {
   return path.join(root, AGENTS_MD);
 }

package/src/core/stores/organization.js

@@ -0,0 +1,152 @@
+// Organization structure (areas + roles) for a project.
+//
+// Only meaningful for "company"/enterprise-shaped projects, but the store is
+// generic: any project can carry an org chart. Persisted as committed JSON at
+//   <root>/.apc/organization.json
+// so it travels with the project and is diffable (same model as agents). No
+// secrets ever live here.
+//
+// Shape on disk:
+//   {
+//     "areas": [{ slug, name, goal }],
+//     "roles": [{ slug, name, area, description }]
+//   }
+//
+// `role.area` references an area slug (or null for a general/unassigned role).
+// Deleting an area detaches its roles (sets their `area` to null) rather than
+// cascading a delete — losing a role definition because its grouping changed
+// would be surprising.
+import fs from "node:fs";
+import path from "node:path";
+import { apcOrganizationFile } from "../apc/paths.js";
+
+export const ORG_SLUG_RE = /^[a-z][a-z0-9_-]*$/;
+
+// Derive a slug from a free-text name (kebab-case). Mirrors the front-end's
+// auto-slug behavior so a name typed in either surface yields the same slug.
+export function slugifyName(name) {
+  return String(name || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .replace(/-{2,}/g, "-");
+}
+
+function emptyOrg() {
+  return { areas: [], roles: [] };
+}
+
+export function readOrganization(root) {
+  const file = apcOrganizationFile(root);
+  if (!fs.existsSync(file)) return emptyOrg();
+  try {
+    const raw = JSON.parse(fs.readFileSync(file, "utf8"));
+    return {
+      areas: Array.isArray(raw.areas) ? raw.areas : [],
+      roles: Array.isArray(raw.roles) ? raw.roles : [],
+    };
+  } catch {
+    // A corrupt file shouldn't take down the whole project view.
+    return emptyOrg();
+  }
+}
+
+function writeOrganization(root, org) {
+  const file = apcOrganizationFile(root);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(org, null, 2) + "\n");
+  return org;
+}
+
+function normSlug(input, fallbackName) {
+  const raw = input && String(input).trim() ? input : slugifyName(fallbackName);
+  const slug = slugifyName(raw);
+  if (!slug || !ORG_SLUG_RE.test(slug)) {
+    throw new Error(`invalid slug: ${slug || "(empty)"}`);
+  }
+  return slug;
+}
+
+// ─────────────────────────────── Areas ─────────────────────────────────────
+
+export function createArea(root, { name, slug, goal } = {}) {
+  if (!name || !String(name).trim()) throw new Error("area name required");
+  const org = readOrganization(root);
+  const areaSlug = normSlug(slug, name);
+  if (org.areas.some((a) => a.slug === areaSlug))
+    throw new Error(`area ${areaSlug} already exists`);
+  const area = { slug: areaSlug, name: String(name).trim(), goal: goal ? String(goal) : null };
+  org.areas.push(area);
+  writeOrganization(root, org);
+  return area;
+}
+
+export function updateArea(root, slug, patch = {}) {
+  const org = readOrganization(root);
+  const area = org.areas.find((a) => a.slug === slug);
+  if (!area) return null;
+  if (patch.name !== undefined) area.name = String(patch.name).trim();
+  if (patch.goal !== undefined) area.goal = patch.goal ? String(patch.goal) : null;
+  writeOrganization(root, org);
+  return area;
+}
+
+export function removeArea(root, slug) {
+  const org = readOrganization(root);
+  const idx = org.areas.findIndex((a) => a.slug === slug);
+  if (idx === -1) return false;
+  org.areas.splice(idx, 1);
+  // Detach roles that pointed at this area (see header note).
+  for (const r of org.roles) if (r.area === slug) r.area = null;
+  writeOrganization(root, org);
+  return true;
+}
+
+// ─────────────────────────────── Roles ─────────────────────────────────────
+
+export function createRole(root, { name, slug, area, description } = {}) {
+  if (!name || !String(name).trim()) throw new Error("role name required");
+  const org = readOrganization(root);
+  const roleSlug = normSlug(slug, name);
+  if (org.roles.some((r) => r.slug === roleSlug))
+    throw new Error(`role ${roleSlug} already exists`);
+  const areaSlug = area ? String(area) : null;
+  if (areaSlug && !org.areas.some((a) => a.slug === areaSlug))
+    throw new Error(`area ${areaSlug} not found`);
+  const role = {
+    slug: roleSlug,
+    name: String(name).trim(),
+    area: areaSlug,
+    description: description ? String(description) : null,
+  };
+  org.roles.push(role);
+  writeOrganization(root, org);
+  return role;
+}
+
+export function updateRole(root, slug, patch = {}) {
+  const org = readOrganization(root);
+  const role = org.roles.find((r) => r.slug === slug);
+  if (!role) return null;
+  if (patch.name !== undefined) role.name = String(patch.name).trim();
+  if (patch.description !== undefined)
+    role.description = patch.description ? String(patch.description) : null;
+  if (patch.area !== undefined) {
+    const areaSlug = patch.area ? String(patch.area) : null;
+    if (areaSlug && !org.areas.some((a) => a.slug === areaSlug))
+      throw new Error(`area ${areaSlug} not found`);
+    role.area = areaSlug;
+  }
+  writeOrganization(root, org);
+  return role;
+}
+
+export function removeRole(root, slug) {
+  const org = readOrganization(root);
+  const idx = org.roles.findIndex((r) => r.slug === slug);
+  if (idx === -1) return false;
+  org.roles.splice(idx, 1);
+  writeOrganization(root, org);
+  return true;
+}

package/src/core/stores/project-files.js

@@ -0,0 +1,199 @@
+// Project file browser — a safe, sandboxed view of a project's own files.
+//
+// Powers the web /files browser and the /docs editor (same store, different
+// root). Everything is resolved *inside* the project root; any path that would
+// escape it throws. This is intentionally NOT a general filesystem API — it
+// only ever touches files under one project.
+//
+// Two roots matter:
+//   - project root  — the repo directory (whole-project /files browser)
+//   - docs root      — a subfolder (config `docs.root`, default "docs") used by
+//                      the /docs editor, so specs/casework live in one place
+//                      (like Appsi's work/ folder of case folders).
+//
+// Reads classify by extension: text is returned inline (utf8); images under a
+// size cap are returned base64 so the authenticated JSON API can render them
+// without a separate unauthenticated asset route; anything else is reported as
+// binary with no body (the UI shows metadata + a download affordance).
+import fs from "node:fs";
+import path from "node:path";
+
+// Directories that are never useful to browse and would blow the node budget.
+const SKIP_DIRS = new Set([
+  "node_modules", ".git", "dist", "build", ".next", ".turbo", ".nuxt",
+  "coverage", ".cache", ".venv", "venv", "__pycache__", ".pytest_cache",
+  ".idea", ".vscode", ".DS_Store",
+]);
+
+const TEXT_EXTS = new Set([
+  "md", "markdown", "mdx", "txt", "text", "rst", "adoc",
+  "js", "jsx", "ts", "tsx", "mjs", "cjs", "json", "jsonc", "json5",
+  "css", "scss", "sass", "less", "html", "htm", "xml", "svg", "vue", "svelte",
+  "py", "rb", "go", "rs", "java", "kt", "c", "h", "cpp", "hpp", "cc",
+  "cs", "php", "swift", "sh", "bash", "zsh", "fish", "sql", "graphql", "gql",
+  "yml", "yaml", "toml", "ini", "cfg", "conf", "env", "properties",
+  "csv", "tsv", "log", "gitignore", "dockerignore", "dockerfile", "makefile",
+]);
+
+const IMAGE_EXTS = new Set(["png", "jpg", "jpeg", "gif", "webp", "svg", "bmp", "ico", "avif"]);
+
+const IMAGE_MIME = {
+  png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif",
+  webp: "image/webp", svg: "image/svg+xml", bmp: "image/bmp", ico: "image/x-icon",
+  avif: "image/avif",
+};
+
+// Guardrails.
+const MAX_NODES = 4000;         // total tree entries returned
+const MAX_TEXT_BYTES = 2_000_000;  // 2 MB inline text ceiling
+const MAX_IMAGE_BYTES = 5_000_000; // 5 MB base64 image ceiling
+
+function extOf(name) {
+  const base = name.toLowerCase();
+  if (base === "dockerfile" || base === "makefile") return base;
+  const dot = base.lastIndexOf(".");
+  return dot === -1 ? "" : base.slice(dot + 1);
+}
+
+export function classifyKind(name) {
+  const ext = extOf(name);
+  if (IMAGE_EXTS.has(ext)) return "image";
+  if (ext === "md" || ext === "markdown" || ext === "mdx") return "markdown";
+  if (TEXT_EXTS.has(ext)) return "text";
+  return "binary";
+}
+
+// Resolve `rel` inside `base`, refusing anything that escapes the sandbox.
+function resolveWithin(base, rel = "") {
+  const root = path.resolve(base);
+  const clean = String(rel || "").replace(/^[/\\]+/, "");
+  const abs = path.resolve(root, clean);
+  if (abs !== root && !abs.startsWith(root + path.sep)) {
+    throw new Error("path escapes the project root");
+  }
+  return { root, abs };
+}
+
+// The docs root for a project (config.docs.root, default "docs"), as a subpath
+// relative to the project root. Sanitized so it can't escape.
+export function docsSubdir(config) {
+  const raw = config?.docs?.root;
+  const sub = raw && typeof raw === "string" ? raw : "docs";
+  return sub.replace(/^[/\\]+/, "").replace(/\.\.(?:[/\\]|$)/g, "");
+}
+
+// Recursively build a nested tree under `absDir`. Dirs first, then files, each
+// alphabetical. `relPrefix` is the path relative to the sandbox root, which is
+// what callers pass back to read/write.
+function walk(absDir, relPrefix, budget) {
+  let entries;
+  try {
+    entries = fs.readdirSync(absDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const dirs = [];
+  const files = [];
+  for (const ent of entries) {
+    const name = ent.name;
+    if (name.startsWith(".")) continue;      // hide dotfiles/dirs
+    if (ent.isDirectory() && SKIP_DIRS.has(name)) continue;
+    (ent.isDirectory() ? dirs : files).push(ent);
+  }
+  dirs.sort((a, b) => a.name.localeCompare(b.name));
+  files.sort((a, b) => a.name.localeCompare(b.name));
+
+  const out = [];
+  for (const ent of [...dirs, ...files]) {
+    if (budget.count >= MAX_NODES) {
+      budget.truncated = true;
+      break;
+    }
+    budget.count += 1;
+    const rel = relPrefix ? `${relPrefix}/${ent.name}` : ent.name;
+    if (ent.isDirectory()) {
+      out.push({ name: ent.name, path: rel, type: "dir", children: walk(path.join(absDir, ent.name), rel, budget) });
+    } else {
+      out.push({ name: ent.name, path: rel, type: "file", kind: classifyKind(ent.name) });
+    }
+  }
+  return out;
+}
+
+// List a tree. `opts.subdir` scopes the sandbox to a subfolder (used for docs).
+// Returns { root, subdir, tree, truncated }. A missing dir yields an empty tree
+// rather than an error — the UI treats that as "nothing here yet".
+export function listTree(projectRoot, opts = {}) {
+  const subdir = opts.subdir ? String(opts.subdir) : "";
+  const { abs } = resolveWithin(projectRoot, subdir);
+  const budget = { count: 0, truncated: false };
+  const tree = fs.existsSync(abs) && fs.statSync(abs).isDirectory()
+    ? walk(abs, "", budget)
+    : [];
+  return { root: projectRoot, subdir, tree, truncated: budget.truncated };
+}
+
+// Read a single file. `opts.subdir` scopes the sandbox (docs). Returns metadata
+// plus the body when it's text/image; binary bodies are omitted.
+export function readFile(projectRoot, relPath, opts = {}) {
+  const base = opts.subdir ? path.join(projectRoot, opts.subdir) : projectRoot;
+  const { abs } = resolveWithin(base, relPath);
+  if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) return null;
+  const stat = fs.statSync(abs);
+  const name = path.basename(abs);
+  const kind = classifyKind(name);
+  const common = {
+    path: relPath.replace(/^[/\\]+/, ""),
+    name,
+    kind,
+    size: stat.size,
+    modified: stat.mtime.toISOString(),
+  };
+  if (kind === "image") {
+    if (stat.size > MAX_IMAGE_BYTES) return { ...common, encoding: "binary", content: null, too_large: true };
+    const ext = extOf(name);
+    return {
+      ...common,
+      encoding: "base64",
+      mime: IMAGE_MIME[ext] || "application/octet-stream",
+      content: fs.readFileSync(abs).toString("base64"),
+    };
+  }
+  if (kind === "binary") {
+    return { ...common, encoding: "binary", content: null };
+  }
+  if (stat.size > MAX_TEXT_BYTES) {
+    return { ...common, encoding: "binary", content: null, too_large: true };
+  }
+  return { ...common, encoding: "utf8", content: fs.readFileSync(abs, "utf8") };
+}
+
+// Write (create or overwrite) a text file, creating parent dirs as needed.
+export function writeFile(projectRoot, relPath, content, opts = {}) {
+  const base = opts.subdir ? path.join(projectRoot, opts.subdir) : projectRoot;
+  const { abs } = resolveWithin(base, relPath);
+  if (typeof content !== "string") throw new Error("content must be a string");
+  if (fs.existsSync(abs) && fs.statSync(abs).isDirectory())
+    throw new Error("path is a directory");
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, content);
+  return { ok: true, path: relPath.replace(/^[/\\]+/, ""), bytes: Buffer.byteLength(content, "utf8") };
+}
+
+// Create a directory (mkdir -p).
+export function makeDir(projectRoot, relPath, opts = {}) {
+  const base = opts.subdir ? path.join(projectRoot, opts.subdir) : projectRoot;
+  const { abs } = resolveWithin(base, relPath);
+  fs.mkdirSync(abs, { recursive: true });
+  return { ok: true, path: relPath.replace(/^[/\\]+/, "") };
+}
+
+// Delete a file or directory (recursive). Refuses to delete the sandbox root.
+export function removeEntry(projectRoot, relPath, opts = {}) {
+  const base = opts.subdir ? path.join(projectRoot, opts.subdir) : projectRoot;
+  const { root, abs } = resolveWithin(base, relPath);
+  if (abs === root) throw new Error("refusing to delete the root");
+  if (!fs.existsSync(abs)) return false;
+  fs.rmSync(abs, { recursive: true, force: true });
+  return true;
+}

package/src/core/stores/tasks.js

@@ -19,6 +19,16 @@ import path from "node:path";
 import { nowIso } from "../util/time.js";
 import { shortId as makeShortId } from "../util/ids.js";
 
+// Workflow sub-status for an *open* task. Orthogonal to `state`
+// (open/done/dropped): `state` is the storage lifecycle, `status` is how an
+// open task is progressing. `blocked` means it's waiting on a human/agent.
+export const TASK_STATUSES = Object.freeze(["pending", "running", "in_review", "blocked"]);
+export const DEFAULT_TASK_STATUS = "pending";
+
+function normalizeStatus(v) {
+  return TASK_STATUSES.includes(v) ? v : DEFAULT_TASK_STATUS;
+}
+
 function tasksDir(storagePath) {
   return path.join(storagePath, "tasks");
 }
@@ -72,12 +82,15 @@ function projectState(events) {
           created_at: ev.ts,
           updated_at: ev.ts,
           state: "open",
+          status: normalizeStatus(ev.status),
           title: ev.title || "",
           body: ev.body || null,
           tags: Array.isArray(ev.tags) ? [...ev.tags] : [],
           due: ev.due || null,
           agent: ev.agent || null,
           source: ev.source || null,
+          created_by: ev.created_by || null,
+          thread: ev.thread || null,
           meta: ev.meta && typeof ev.meta === "object" ? { ...ev.meta } : {},
         });
         break;
@@ -87,7 +100,7 @@ function projectState(events) {
         const patch = ev.patch && typeof ev.patch === "object" ? ev.patch : {};
         for (const k of Object.keys(patch)) {
           if (k === "id" || k === "state" || k === "created_at") continue;
-          existing[k] = patch[k];
+          existing[k] = k === "status" ? normalizeStatus(patch[k]) : patch[k];
         }
         existing.updated_at = ev.ts;
         break;
@@ -141,10 +154,13 @@ export function createTask(storagePath, fields) {
     op: "create",
     title: fields.title.trim(),
     body: fields.body || null,
+    status: normalizeStatus(fields.status),
     tags: Array.isArray(fields.tags) ? fields.tags.filter((t) => typeof t === "string") : [],
     due: fields.due || null,
     agent: fields.agent || null,
     source: fields.source || null,
+    created_by: fields.created_by || null,
+    thread: fields.thread || null,
     meta: fields.meta && typeof fields.meta === "object" ? fields.meta : {},
   };
   appendEvent(storagePath, ev);
@@ -207,6 +223,19 @@ export function patchTask(storagePath, idOrPrefix, patch) {
   return getTask(storagePath, existing.id);
 }
 
+/** Set the workflow status (pending/running/in_review/blocked) of an open task. */
+export function setTaskStatus(storagePath, idOrPrefix, status) {
+  const existing = getTask(storagePath, idOrPrefix);
+  if (!existing) return null;
+  appendEvent(storagePath, {
+    id: existing.id,
+    ts: nowIso(),
+    op: "update",
+    patch: { status: normalizeStatus(status) },
+  });
+  return getTask(storagePath, existing.id);
+}
+
 /** Mark done. */
 export function doneTask(storagePath, idOrPrefix, by = null) {
   const existing = getTask(storagePath, idOrPrefix);
@@ -249,11 +278,15 @@ export function reopenTask(storagePath, idOrPrefix) {
 export function countTasks(storagePath) {
   const tasks = [...projectState(readAllEvents(storagePath)).values()];
   const today = new Date().toISOString().slice(0, 10);
+  const open = tasks.filter((t) => t.state === "open");
+  const byStatus = {};
+  for (const s of TASK_STATUSES) byStatus[s] = open.filter((t) => t.status === s).length;
   return {
-    open: tasks.filter((t) => t.state === "open").length,
+    open: open.length,
     done: tasks.filter((t) => t.state === "done").length,
     dropped: tasks.filter((t) => t.state === "dropped").length,
-    overdue: tasks.filter((t) => t.state === "open" && t.due && t.due < today).length,
+    overdue: open.filter((t) => t.due && t.due < today).length,
     total: tasks.length,
+    status: byStatus,
   };
 }

package/src/host/daemon/api/agents.js

@@ -24,6 +24,17 @@ import {
 } from "#core/agent/memory.js";
 import { agentToResponse } from "./shared.js";
 import { normalizeVaultPatch } from "#core/apc/agents-vault.js";
+import { PERMISSION_MODES } from "#core/constants/permissions.js";
+
+// Autonomy mirrors the super-agent permission modes (total/automatico/permiso).
+// An invalid value is dropped rather than persisted so a typo can't silently
+// widen an agent's autonomy.
+const AUTONOMY_VALUES = new Set(Object.values(PERMISSION_MODES));
+function normalizeAutonomy(v) {
+  if (v === undefined) return undefined;
+  if (v === null || v === "") return null;
+  return AUTONOMY_VALUES.has(v) ? v : undefined;
+}
 
 export function register(app, { projects, project }) {
   // Vault = global agent templates. Two-layer: bundled defaults shipped with
@@ -128,14 +139,17 @@ export function register(app, { projects, project }) {
   app.post("/projects/:pid/agents", (req, res) => {
     const p = project(req, res);
     if (!p) return;
-    const { slug, role, model, skills, language, description, tools, is_master, parent } =
-      req.body || {};
+    const {
+      slug, role, model, skills, language, description, tools, is_master,
+      parent, type, area, emoji, autonomy,
+    } = req.body || {};
     if (!slug) return res.status(400).json({ error: "slug required" });
     if (!/^[a-z][a-z0-9_-]*$/.test(slug))
       return res.status(400).json({ error: "invalid slug" });
     const existing = readAgents(p.path).find((a) => a.slug === slug);
     if (existing)
       return res.status(400).json({ error: `agent ${slug} already exists` });
+    const autonomyVal = normalizeAutonomy(autonomy);
     try {
       writeAgentFile(p.path, slug, {
         Role: role || null,
@@ -146,6 +160,10 @@ export function register(app, { projects, project }) {
         Tools: tools || [],
         Master: is_master ? true : null,
         Parent: parent || null,
+        Type: type || null,
+        Area: area || null,
+        Emoji: emoji || null,
+        Autonomy: autonomyVal || null,
       });
       ensureAgentDir(p.path, slug);
       ensureAgentRuntimeDir(p, slug);
@@ -179,6 +197,8 @@ export function register(app, { projects, project }) {
     setStr("Parent", b.parent);
     setStr("Type", b.type);
     setStr("Area", b.area);
+    setStr("Emoji", b.emoji);
+    setStr("Autonomy", normalizeAutonomy(b.autonomy));
     if (b.skills !== undefined) fields.Skills = Array.isArray(b.skills) ? b.skills : [];
     if (b.tools !== undefined) fields.Tools = Array.isArray(b.tools) ? b.tools : [];
     if (b.is_master !== undefined) {

package/src/host/daemon/api/files-project.js

@@ -0,0 +1,99 @@
+// Project file browser + docs editor API.
+//
+// A sandboxed view of one project's own files. `scope` selects the sandbox:
+//   project — the whole repo (the /files browser)
+//   docs     — the docs subfolder (config docs.root, default "docs"); powers
+//              the /docs spec editor
+//
+//   GET    /projects/:pid/fs/tree?scope=project|docs
+//   GET    /projects/:pid/fs/file?scope=…&path=<rel>
+//   PUT    /projects/:pid/fs/file        body { scope?, path, content }
+//   POST   /projects/:pid/fs/dir         body { scope?, path }
+//   DELETE /projects/:pid/fs/entry?scope=…&path=<rel>
+//
+// Thin adapter over core/stores/project-files.
+import {
+  listTree,
+  readFile,
+  writeFile,
+  makeDir,
+  removeEntry,
+  docsSubdir,
+} from "#core/stores/project-files.js";
+
+// Resolve the sandbox subdir for a scope. Unknown scope → project root.
+function scopeOpts(p, scope) {
+  if (scope === "docs") return { subdir: docsSubdir(p.config), scope: "docs" };
+  return { subdir: "", scope: "project" };
+}
+
+export function register(app, { project }) {
+  app.get("/projects/:pid/fs/tree", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const { subdir, scope } = scopeOpts(p, req.query?.scope);
+    try {
+      res.json({ scope, ...listTree(p.path, { subdir }) });
+    } catch (e) {
+      res.status(400).json({ error: e.message });
+    }
+  });
+
+  app.get("/projects/:pid/fs/file", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const rel = req.query?.path;
+    if (!rel) return res.status(400).json({ error: "path required" });
+    const { subdir } = scopeOpts(p, req.query?.scope);
+    try {
+      const file = readFile(p.path, String(rel), { subdir });
+      if (!file) return res.status(404).json({ error: "file not found" });
+      res.json(file);
+    } catch (e) {
+      res.status(400).json({ error: e.message });
+    }
+  });
+
+  app.put("/projects/:pid/fs/file", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const { path: rel, content, scope } = req.body || {};
+    if (!rel) return res.status(400).json({ error: "path required" });
+    if (typeof content !== "string")
+      return res.status(400).json({ error: "content must be a string" });
+    const { subdir } = scopeOpts(p, scope);
+    try {
+      res.json(writeFile(p.path, String(rel), content, { subdir }));
+    } catch (e) {
+      res.status(400).json({ error: e.message });
+    }
+  });
+
+  app.post("/projects/:pid/fs/dir", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const { path: rel, scope } = req.body || {};
+    if (!rel) return res.status(400).json({ error: "path required" });
+    const { subdir } = scopeOpts(p, scope);
+    try {
+      res.status(201).json(makeDir(p.path, String(rel), { subdir }));
+    } catch (e) {
+      res.status(400).json({ error: e.message });
+    }
+  });
+
+  app.delete("/projects/:pid/fs/entry", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const rel = req.query?.path;
+    if (!rel) return res.status(400).json({ error: "path required" });
+    const { subdir } = scopeOpts(p, req.query?.scope);
+    try {
+      if (!removeEntry(p.path, String(rel), { subdir }))
+        return res.status(404).json({ error: "entry not found" });
+      res.json({ ok: true });
+    } catch (e) {
+      res.status(400).json({ error: e.message });
+    }
+  });
+}