bopodev-api 0.1.35 → 0.1.37

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bopodev-api",
-  "version": "0.1.35",
+  "version": "0.1.37",
   "license": "MIT",
   "type": "module",
   "files": [
@@ -21,9 +21,9 @@
     "ws": "^8.19.0",
     "yaml": "^2.8.3",
     "zod": "^4.1.5",
-    "bopodev-agent-sdk": "0.1.35",
-    "bopodev-db": "0.1.35",
-    "bopodev-contracts": "0.1.35"
+    "bopodev-agent-sdk": "0.1.37",
+    "bopodev-contracts": "0.1.37",
+    "bopodev-db": "0.1.37"
   },
   "devDependencies": {
     "@types/archiver": "^7.0.0",

package/src/lib/instance-paths.ts

@@ -66,6 +66,11 @@ export function resolveCompanySkillsPath(companyId: string) {
   return join(resolveCompanyProjectsWorkspacePath(companyId), "skills");
 }
 
+/** Company knowledge base (`knowledge/**`), markdown and text files on disk; exportable with company zip. */
+export function resolveCompanyKnowledgePath(companyId: string) {
+  return join(resolveCompanyProjectsWorkspacePath(companyId), "knowledge");
+}
+
 export function resolveAgentFallbackWorkspacePath(companyId: string, agentId: string) {
   const safeCompanyId = assertPathSegment(companyId, "companyId");
   const safeAgentId = assertPathSegment(agentId, "agentId");

package/src/routes/companies.ts

@@ -118,7 +118,7 @@ export function createCompaniesRouter(ctx: AppContext) {
       return sendOk(res, {
         ok: false,
         companyName: "",
-        counts: { projects: 0, agents: 0, goals: 0, routines: 0, skillFiles: 0 },
+        counts: { projects: 0, agents: 0, goals: 0, routines: 0, skillFiles: 0, knowledgeFiles: 0 },
         hasCeo: false,
         errors: [message],
         warnings: [] as string[]

package/src/routes/issues.ts

@@ -50,6 +50,7 @@ import { isInsidePath, normalizeCompanyWorkspacePath, resolveProjectWorkspacePat
 import { requireCompanyScope } from "../middleware/company-scope";
 import { enforcePermission } from "../middleware/request-actor";
 import { triggerIssueCommentDispatchWorker } from "../services/comment-recipient-dispatch-service";
+import { knowledgeFileExists } from "../services/company-knowledge-file-service";
 import { publishAttentionSnapshot } from "../realtime/attention";
 import {
   createIssueCommentLegacySchema,
@@ -108,10 +109,26 @@ function normalizeOptionalExternalLink(value: string | null | undefined) {
   return trimmed.length > 0 ? trimmed : null;
 }
 
+async function validateIssueKnowledgePaths(companyId: string, paths: string[]): Promise<string | null> {
+  for (const p of paths) {
+    if (!(await knowledgeFileExists({ companyId, relativePath: p }))) {
+      return `Knowledge file not found: ${p}`;
+    }
+  }
+  return null;
+}
+
 function toIssueResponse(issue: Record<string, unknown>, goalIds: string[] = []) {
   const labels = parseStringArray(issue.labelsJson);
   const tags = parseStringArray(issue.tagsJson);
-  const { labelsJson: _labelsJson, tagsJson: _tagsJson, goalId: _legacyGoalId, ...rest } = issue as Record<string, unknown> & {
+  const knowledgePaths = parseStringArray(issue.knowledgePathsJson);
+  const {
+    labelsJson: _labelsJson,
+    tagsJson: _tagsJson,
+    knowledgePathsJson: _knowledgePathsJson,
+    goalId: _legacyGoalId,
+    ...rest
+  } = issue as Record<string, unknown> & {
     goalId?: unknown;
   };
   const externalRaw = rest.externalLink;
@@ -122,7 +139,8 @@ function toIssueResponse(issue: Record<string, unknown>, goalIds: string[] = [])
     externalLink,
     labels,
     tags,
-    goalIds
+    goalIds,
+    knowledgePaths
   };
 }
 
@@ -209,6 +227,12 @@ export function createIssuesRouter(ctx: AppContext) {
         return sendError(res, assignmentValidation, 422);
       }
     }
+    if (parsed.data.knowledgePaths.length > 0) {
+      const kpErr = await validateIssueKnowledgePaths(req.companyId!, parsed.data.knowledgePaths);
+      if (kpErr) {
+        return sendError(res, kpErr, 422);
+      }
+    }
     const issue = await createIssue(ctx.db, {
       companyId: req.companyId!,
       projectId: parsed.data.projectId,
@@ -221,7 +245,8 @@ export function createIssuesRouter(ctx: AppContext) {
       priority: parsed.data.priority,
       assigneeAgentId: parsed.data.assigneeAgentId,
       labels: parsed.data.labels,
-      tags: parsed.data.tags
+      tags: parsed.data.tags,
+      knowledgePaths: parsed.data.knowledgePaths
     });
     await appendActivity(ctx.db, {
       companyId: req.companyId!,
@@ -606,6 +631,12 @@ export function createIssuesRouter(ctx: AppContext) {
     if (updateBody.externalLink !== undefined) {
       updateBody.externalLink = normalizeOptionalExternalLink(updateBody.externalLink) ?? null;
     }
+    if (updateBody.knowledgePaths !== undefined && updateBody.knowledgePaths.length > 0) {
+      const kpErr = await validateIssueKnowledgePaths(req.companyId!, updateBody.knowledgePaths);
+      if (kpErr) {
+        return sendError(res, kpErr, 422);
+      }
+    }
     const issue = await updateIssue(ctx.db, { companyId: req.companyId!, id: req.params.issueId, ...updateBody });
     if (!issue) {
       return sendError(res, "Issue not found.", 404);

package/src/routes/observability.ts

@@ -25,14 +25,27 @@ import {
   writeAgentOperatingFile
 } from "../services/agent-operating-file-service";
 import { BUILTIN_BOPO_SKILLS } from "../lib/builtin-bopo-skills";
+import {
+  buildKnowledgeTreeFromPaths,
+  createKnowledgeFile,
+  deleteKnowledgeFile,
+  listKnowledgeFiles,
+  readKnowledgeFile,
+  renameKnowledgeFile,
+  renameKnowledgeFolderPrefix,
+  writeKnowledgeFile
+} from "../services/company-knowledge-file-service";
 import {
   createCompanySkillPackage,
+  deleteCompanySkillFile,
   deleteCompanySkillPackage,
   linkCompanySkillFromUrl,
   listCompanySkillFiles,
   listCompanySkillPackages,
   refreshCompanySkillFromUrl,
   readCompanySkillFile,
+  renameCompanySkillFile,
+  setCompanySkillSidebarTitle,
   writeCompanySkillFile
 } from "../services/company-skill-file-service";
 import {
@@ -550,6 +563,7 @@ export function createObservabilityRouter(ctx: AppContext) {
             linkedUrl: pack.linkedUrl,
             linkLastFetchedAt: pack.linkLastFetchedAt,
             hasLocalSkillMd,
+            sidebarTitle: pack.sidebarTitle,
             files: relativePaths.map((relativePath) => ({ relativePath }))
           };
         })
@@ -602,6 +616,77 @@ export function createObservabilityRouter(ctx: AppContext) {
     }
   });
 
+  router.patch("/company-skills/file", async (req, res) => {
+    if (!enforcePermission(req, res, "agents:write")) {
+      return;
+    }
+    const companyId = req.companyId!;
+    const skillId = typeof req.query.skillId === "string" ? req.query.skillId.trim() : "";
+    if (!skillId) {
+      return sendError(res, "Query parameter 'skillId' is required.", 422);
+    }
+    const body = req.body as { from?: unknown; to?: unknown };
+    if (typeof body?.from !== "string" || !body.from.trim()) {
+      return sendError(res, "Expected JSON body with string 'from' (current path).", 422);
+    }
+    if (typeof body?.to !== "string" || !body.to.trim()) {
+      return sendError(res, "Expected JSON body with string 'to' (new path).", 422);
+    }
+    try {
+      const result = await renameCompanySkillFile({
+        companyId,
+        skillId,
+        fromRelativePath: body.from.trim(),
+        toRelativePath: body.to.trim()
+      });
+      return sendOk(res, result);
+    } catch (error) {
+      return sendError(res, String(error), 422);
+    }
+  });
+
+  router.patch("/company-skills/sidebar-title", async (req, res) => {
+    if (!enforcePermission(req, res, "agents:write")) {
+      return;
+    }
+    const companyId = req.companyId!;
+    const body = req.body as { skillId?: unknown; title?: unknown };
+    if (typeof body?.skillId !== "string" || !body.skillId.trim()) {
+      return sendError(res, "Expected JSON body with string 'skillId'.", 422);
+    }
+    if (typeof body?.title !== "string") {
+      return sendError(res, "Expected JSON body with string 'title' (empty string resets to skill id).", 422);
+    }
+    try {
+      const result = await setCompanySkillSidebarTitle({
+        companyId,
+        skillId: body.skillId.trim(),
+        title: body.title
+      });
+      return sendOk(res, result);
+    } catch (error) {
+      return sendError(res, String(error), 422);
+    }
+  });
+
+  router.delete("/company-skills/file", async (req, res) => {
+    if (!enforcePermission(req, res, "agents:write")) {
+      return;
+    }
+    const companyId = req.companyId!;
+    const skillId = typeof req.query.skillId === "string" ? req.query.skillId.trim() : "";
+    const relativePath = typeof req.query.path === "string" ? req.query.path.trim() : "";
+    if (!skillId || !relativePath) {
+      return sendError(res, "Query parameters 'skillId' and 'path' are required.", 422);
+    }
+    try {
+      const result = await deleteCompanySkillFile({ companyId, skillId, relativePath });
+      return sendOk(res, result);
+    } catch (error) {
+      return sendError(res, String(error), 422);
+    }
+  });
+
   router.post("/company-skills/create", async (req, res) => {
     if (!enforcePermission(req, res, "agents:write")) {
       return;
@@ -679,6 +764,143 @@ export function createObservabilityRouter(ctx: AppContext) {
     }
   });
 
+  router.get("/company-knowledge", async (req, res) => {
+    const companyId = req.companyId!;
+    try {
+      const { files } = await listKnowledgeFiles({ companyId });
+      const tree = buildKnowledgeTreeFromPaths(files);
+      return sendOk(res, { items: files, tree });
+    } catch (error) {
+      return sendError(res, String(error), 422);
+    }
+  });
+
+  router.get("/company-knowledge/file", async (req, res) => {
+    const companyId = req.companyId!;
+    const relativePath = typeof req.query.path === "string" ? req.query.path.trim() : "";
+    if (!relativePath) {
+      return sendError(res, "Query parameter 'path' is required.", 422);
+    }
+    try {
+      const file = await readKnowledgeFile({ companyId, relativePath });
+      return sendOk(res, { content: file.content });
+    } catch (error) {
+      return sendError(res, String(error), 422);
+    }
+  });
+
+  router.put("/company-knowledge/file", async (req, res) => {
+    if (!enforcePermission(req, res, "agents:write")) {
+      return;
+    }
+    const companyId = req.companyId!;
+    const relativePath = typeof req.query.path === "string" ? req.query.path.trim() : "";
+    if (!relativePath) {
+      return sendError(res, "Query parameter 'path' is required.", 422);
+    }
+    const body = req.body as { content?: unknown };
+    if (typeof body?.content !== "string") {
+      return sendError(res, "Expected JSON body with string 'content'.", 422);
+    }
+    try {
+      const result = await writeKnowledgeFile({
+        companyId,
+        relativePath,
+        content: body.content
+      });
+      return sendOk(res, result);
+    } catch (error) {
+      return sendError(res, String(error), 422);
+    }
+  });
+
+  router.post("/company-knowledge/file", async (req, res) => {
+    if (!enforcePermission(req, res, "agents:write")) {
+      return;
+    }
+    const companyId = req.companyId!;
+    const body = req.body as { path?: unknown; content?: unknown };
+    if (typeof body?.path !== "string" || !body.path.trim()) {
+      return sendError(res, "Expected JSON body with string 'path'.", 422);
+    }
+    const content = typeof body.content === "string" ? body.content : undefined;
+    try {
+      const result = await createKnowledgeFile({
+        companyId,
+        relativePath: body.path.trim(),
+        ...(content !== undefined ? { content } : {})
+      });
+      return sendOk(res, result);
+    } catch (error) {
+      return sendError(res, String(error), 422);
+    }
+  });
+
+  router.patch("/company-knowledge/file", async (req, res) => {
+    if (!enforcePermission(req, res, "agents:write")) {
+      return;
+    }
+    const companyId = req.companyId!;
+    const body = req.body as { from?: unknown; to?: unknown };
+    if (typeof body?.from !== "string" || !body.from.trim()) {
+      return sendError(res, "Expected JSON body with string 'from' (current path).", 422);
+    }
+    if (typeof body?.to !== "string" || !body.to.trim()) {
+      return sendError(res, "Expected JSON body with string 'to' (new path).", 422);
+    }
+    try {
+      const result = await renameKnowledgeFile({
+        companyId,
+        fromRelativePath: body.from.trim(),
+        toRelativePath: body.to.trim()
+      });
+      return sendOk(res, result);
+    } catch (error) {
+      return sendError(res, String(error), 422);
+    }
+  });
+
+  router.patch("/company-knowledge/folder", async (req, res) => {
+    if (!enforcePermission(req, res, "agents:write")) {
+      return;
+    }
+    const companyId = req.companyId!;
+    const body = req.body as { from?: unknown; to?: unknown };
+    if (typeof body?.from !== "string" || !body.from.trim()) {
+      return sendError(res, "Expected JSON body with string 'from' (current folder prefix).", 422);
+    }
+    if (typeof body?.to !== "string" || !body.to.trim()) {
+      return sendError(res, "Expected JSON body with string 'to' (new folder prefix).", 422);
+    }
+    try {
+      const result = await renameKnowledgeFolderPrefix({
+        companyId,
+        fromPrefix: body.from.trim(),
+        toPrefix: body.to.trim()
+      });
+      return sendOk(res, result);
+    } catch (error) {
+      return sendError(res, String(error), 422);
+    }
+  });
+
+  router.delete("/company-knowledge/file", async (req, res) => {
+    if (!enforcePermission(req, res, "agents:write")) {
+      return;
+    }
+    const companyId = req.companyId!;
+    const relativePath = typeof req.query.path === "string" ? req.query.path.trim() : "";
+    if (!relativePath) {
+      return sendError(res, "Query parameter 'path' is required.", 422);
+    }
+    try {
+      const result = await deleteKnowledgeFile({ companyId, relativePath });
+      return sendOk(res, result);
+    } catch (error) {
+      return sendError(res, String(error), 422);
+    }
+  });
+
   router.get("/memory/:agentId/context-preview", async (req, res) => {
     const companyId = req.companyId!;
     const agentId = req.params.agentId;

package/src/services/company-file-archive-service.ts

@@ -8,9 +8,10 @@ import { getCompany, listAgents, listGoals, listProjects } from "bopodev-db";
 import {
   resolveAgentMemoryRootPath,
   resolveAgentOperatingPath,
+  resolveCompanyKnowledgePath,
   resolveCompanyProjectsWorkspacePath
 } from "../lib/instance-paths";
-import { SKILL_LINK_BASENAME } from "./company-skill-file-service";
+import { SKILL_LINK_BASENAME, SKILL_SIDEBAR_TITLE_BASENAME } from "./company-skill-file-service";
 import { listWorkLoopTriggers, listWorkLoops } from "./work-loop-service/work-loop-service";
 
 const EXPORT_SCHEMA = "bopo/company-export/v1";
@@ -69,7 +70,7 @@ async function walkTextFilesUnder(rootAbs: string, budget: { n: number }): Promi
         return;
       }
       const name = ent.name;
-      if (name.startsWith(".") && name !== SKILL_LINK_BASENAME) {
+      if (name.startsWith(".") && name !== SKILL_LINK_BASENAME && name !== SKILL_SIDEBAR_TITLE_BASENAME) {
         continue;
       }
       const full = join(dir, name);
@@ -110,12 +111,23 @@ async function walkSkillsDir(companyId: string, budget: { n: number }): Promise<
   return out;
 }
 
+async function walkKnowledgeDir(companyId: string, budget: { n: number }): Promise<Record<string, string>> {
+  const root = resolveCompanyKnowledgePath(companyId);
+  const files = await walkTextFilesUnder(root, budget);
+  const out: Record<string, string> = {};
+  for (const [rel, content] of Object.entries(files)) {
+    out[`knowledge/${rel}`] = content;
+  }
+  return out;
+}
+
 function buildReadmeMarkdown(input: {
   companyName: string;
   slug: string;
   agentRows: { slug: string; name: string; role: string; managerSlug: string | null }[];
   projectRows: { slug: string; name: string; description: string | null }[];
   skillFileCount: number;
+  knowledgeFileCount: number;
   taskCount: number;
   goalCount: number;
   exportedAt: string;
@@ -131,6 +143,7 @@ function buildReadmeMarkdown(input: {
     `| Projects | ${input.projectRows.length} |`,
     `| Goals | ${input.goalCount} |`,
     `| Skills (files under skills/) | ${input.skillFileCount} |`,
+    `| Knowledge (files under knowledge/) | ${input.knowledgeFileCount} |`,
     `| Scheduled tasks | ${input.taskCount} |`,
     "",
     "### Agents",
@@ -350,6 +363,12 @@ export async function buildCompanyExportFileMap(
     files[p] = c;
   }
 
+  const knowledgeFiles = await walkKnowledgeDir(companyId, skillBudget);
+  const knowledgeFileCount = Object.keys(knowledgeFiles).length;
+  for (const [p, c] of Object.entries(knowledgeFiles)) {
+    files[p] = c;
+  }
+
   const taskCount = Object.keys(routineManifest).length;
 
   files["README.md"] = buildReadmeMarkdown({
@@ -358,6 +377,7 @@ export async function buildCompanyExportFileMap(
     agentRows: agentRowsForReadme,
     projectRows: projectEntries.map((p) => ({ slug: p.slug, name: p.name, description: p.description })),
     skillFileCount,
+    knowledgeFileCount,
     taskCount,
     goalCount: sortedGoals.length,
     exportedAt: yamlDoc.exportedAt
@@ -420,7 +440,9 @@ export async function listCompanyExportManifest(
   return Object.entries(files)
     .map(([path, content]): CompanyExportFileEntry => {
       const source: "generated" | "workspace" =
-        path.startsWith("agents/") || path.startsWith("skills/") ? "workspace" : "generated";
+        path.startsWith("agents/") || path.startsWith("skills/") || path.startsWith("knowledge/")
+          ? "workspace"
+          : "generated";
       return {
         path,
         bytes: Buffer.byteLength(content, "utf8"),

package/src/services/company-file-import-service.ts

@@ -328,6 +328,12 @@ export async function seedOperationalDataFromPackage(db: BopoDb, companyId: stri
       const dest = join(companyRoot, path);
       await mkdir(dirname(dest), { recursive: true });
       await writeFile(dest, text, "utf8");
+      continue;
+    }
+    if (path.startsWith("knowledge/")) {
+      const dest = join(companyRoot, path);
+      await mkdir(dirname(dest), { recursive: true });
+      await writeFile(dest, text, "utf8");
     }
   }
 
@@ -424,11 +430,15 @@ export function summarizeCompanyPackageForPreview(parsed: ParsedCompanyPackage):
     goals: number;
     routines: number;
     skillFiles: number;
+    knowledgeFiles: number;
   };
   hasCeo: boolean;
 } {
   const doc = parsed.doc;
   const skillFiles = Object.keys(parsed.entries).filter((k) => k.startsWith("skills/") && !k.endsWith("/")).length;
+  const knowledgeFiles = Object.keys(parsed.entries).filter(
+    (k) => k.startsWith("knowledge/") && !k.endsWith("/")
+  ).length;
   const hasCeo = Object.values(doc.agents).some((a) => (a.roleKey ?? "").trim().toLowerCase() === "ceo");
   return {
     companyName: doc.company.name,
@@ -437,7 +447,8 @@ export function summarizeCompanyPackageForPreview(parsed: ParsedCompanyPackage):
       agents: Object.keys(doc.agents).length,
       goals: Object.keys(doc.goals ?? {}).length,
       routines: Object.keys(doc.routines ?? {}).length,
-      skillFiles
+      skillFiles,
+      knowledgeFiles
     },
     hasCeo
   };

package/src/services/company-knowledge-file-service.ts

@@ -0,0 +1,361 @@
+import { mkdir, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import { isInsidePath, resolveCompanyKnowledgePath, resolveCompanyProjectsWorkspacePath } from "../lib/instance-paths";
+
+const MAX_OBSERVABILITY_FILES = 200;
+const MAX_OBSERVABILITY_FILE_BYTES = 512 * 1024;
+const MAX_PATH_SEGMENTS = 32;
+const TEXT_EXT = new Set([".md", ".yaml", ".yml", ".txt", ".json"]);
+
+/** Default file body when POST create omits `content`. Markdown/text start empty (no frontmatter boilerplate). */
+function defaultContentForNewKnowledgeFile(relativePath: string): string {
+  const lower = relativePath.toLowerCase();
+  if (lower.endsWith(".json")) {
+    return "{}\n";
+  }
+  return "";
+}
+
+export function assertKnowledgeRelativePath(relativePath: string): string {
+  const normalized = relativePath.trim().replace(/\\/g, "/");
+  if (!normalized || normalized.startsWith("/") || normalized.includes("..")) {
+    throw new Error("Invalid relative path.");
+  }
+  const parts = normalized.split("/").filter(Boolean);
+  if (parts.length === 0 || parts.length > MAX_PATH_SEGMENTS) {
+    throw new Error("Invalid relative path.");
+  }
+  for (const p of parts) {
+    if (p === "." || p === ".." || p.startsWith(".")) {
+      throw new Error("Invalid relative path.");
+    }
+  }
+  const base = parts[parts.length - 1]!;
+  const lower = base.toLowerCase();
+  const ext = lower.includes(".") ? lower.slice(lower.lastIndexOf(".")) : "";
+  if (!TEXT_EXT.has(ext)) {
+    throw new Error("Only text knowledge files (.md, .yaml, .yml, .txt, .json) are allowed.");
+  }
+  return normalized;
+}
+
+async function knowledgeRoot(companyId: string) {
+  const root = resolveCompanyKnowledgePath(companyId);
+  const companyWorkspace = resolveCompanyProjectsWorkspacePath(companyId);
+  if (!isInsidePath(companyWorkspace, root)) {
+    throw new Error("Invalid knowledge root.");
+  }
+  return { root };
+}
+
+export async function listKnowledgeFiles(input: { companyId: string; maxFiles?: number }) {
+  const { root } = await knowledgeRoot(input.companyId);
+  await mkdir(root, { recursive: true });
+  const maxFiles = Math.max(1, Math.min(MAX_OBSERVABILITY_FILES, input.maxFiles ?? MAX_OBSERVABILITY_FILES));
+  const relativePaths = await walkKnowledgeTextFiles(root, maxFiles);
+  return { root, files: relativePaths.map((relativePath) => ({ relativePath })) };
+}
+
+export type KnowledgeTreeNode =
+  | { type: "file"; name: string; relativePath: string }
+  | { type: "dir"; name: string; children: KnowledgeTreeNode[] };
+
+/** Nested tree from flat relative paths (trie). */
+export function buildKnowledgeTreeFromPaths(files: { relativePath: string }[]): KnowledgeTreeNode[] {
+  type Trie = { dirs: Map<string, Trie>; files: KnowledgeTreeNode[] };
+  const root: Trie = { dirs: new Map(), files: [] };
+
+  for (const { relativePath } of [...files].sort((a, b) => a.relativePath.localeCompare(b.relativePath))) {
+    const parts = relativePath.split("/").filter(Boolean);
+    if (parts.length === 0) {
+      continue;
+    }
+    const fileName = parts.pop()!;
+    let node = root;
+    for (const segment of parts) {
+      if (!node.dirs.has(segment)) {
+        node.dirs.set(segment, { dirs: new Map(), files: [] });
+      }
+      node = node.dirs.get(segment)!;
+    }
+    node.files.push({ type: "file", name: fileName, relativePath });
+  }
+
+  function trieToNodes(trie: Trie): KnowledgeTreeNode[] {
+    const dirNodes: KnowledgeTreeNode[] = [];
+    for (const [name, child] of [...trie.dirs.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+      const children = trieToNodes(child);
+      dirNodes.push({ type: "dir", name, children });
+    }
+    const sortedFiles = [...trie.files].sort((a, b) => a.name.localeCompare(b.name));
+    return [...dirNodes, ...sortedFiles];
+  }
+
+  return trieToNodes(root);
+}
+
+async function walkKnowledgeTextFiles(knowledgeDir: string, maxFiles: number): Promise<string[]> {
+  const collected: string[] = [];
+  const queue = [knowledgeDir];
+  while (queue.length > 0 && collected.length < maxFiles) {
+    const current = queue.shift();
+    if (!current) {
+      continue;
+    }
+    let entries: import("node:fs").Dirent[];
+    try {
+      entries = await readdir(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (collected.length >= maxFiles) {
+        break;
+      }
+      const absolutePath = join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (!entry.name.startsWith(".")) {
+          queue.push(absolutePath);
+        }
+        continue;
+      }
+      if (entry.name.startsWith(".")) {
+        continue;
+      }
+      const lower = entry.name.toLowerCase();
+      const ext = lower.includes(".") ? lower.slice(lower.lastIndexOf(".")) : "";
+      if (TEXT_EXT.has(ext)) {
+        collected.push(relative(knowledgeDir, absolutePath).replace(/\\/g, "/"));
+      }
+    }
+  }
+  return collected.sort((a, b) => a.localeCompare(b));
+}
+
+export async function readKnowledgeFile(input: { companyId: string; relativePath: string }) {
+  const { root } = await knowledgeRoot(input.companyId);
+  const rel = assertKnowledgeRelativePath(input.relativePath);
+  const candidate = resolve(root, rel);
+  if (!isInsidePath(root, candidate)) {
+    throw new Error("Requested path is outside of knowledge directory.");
+  }
+  const info = await stat(candidate);
+  if (!info.isFile()) {
+    throw new Error("Requested path is not a file.");
+  }
+  if (info.size > MAX_OBSERVABILITY_FILE_BYTES) {
+    throw new Error("File exceeds size limit.");
+  }
+  const content = await readFile(candidate, "utf8");
+  return {
+    relativePath: rel,
+    content,
+    sizeBytes: info.size
+  };
+}
+
+export async function writeKnowledgeFile(input: {
+  companyId: string;
+  relativePath: string;
+  content: string;
+}) {
+  const { root } = await knowledgeRoot(input.companyId);
+  const rel = assertKnowledgeRelativePath(input.relativePath);
+  const candidate = resolve(root, rel);
+  if (!isInsidePath(root, candidate)) {
+    throw new Error("Requested path is outside of knowledge directory.");
+  }
+  const bytes = Buffer.byteLength(input.content, "utf8");
+  if (bytes > MAX_OBSERVABILITY_FILE_BYTES) {
+    throw new Error("Content exceeds size limit.");
+  }
+  const parent = dirname(candidate);
+  if (!isInsidePath(root, parent)) {
+    throw new Error("Invalid parent directory.");
+  }
+  await mkdir(parent, { recursive: true });
+  await writeFile(candidate, input.content, { encoding: "utf8" });
+  const info = await stat(candidate);
+  return {
+    relativePath: rel,
+    sizeBytes: info.size
+  };
+}
+
+/** Create a new file; fails if it already exists. */
+export async function createKnowledgeFile(input: {
+  companyId: string;
+  relativePath: string;
+  content?: string;
+}) {
+  const { root } = await knowledgeRoot(input.companyId);
+  const rel = assertKnowledgeRelativePath(input.relativePath);
+  const candidate = resolve(root, rel);
+  if (!isInsidePath(root, candidate)) {
+    throw new Error("Requested path is outside of knowledge directory.");
+  }
+  try {
+    await stat(candidate);
+    throw new Error("A file already exists at this path.");
+  } catch (error) {
+    if (error instanceof Error && error.message === "A file already exists at this path.") {
+      throw error;
+    }
+    const code = error && typeof error === "object" && "code" in error ? (error as NodeJS.ErrnoException).code : undefined;
+    if (code !== "ENOENT") {
+      throw error;
+    }
+  }
+  const body = input.content ?? defaultContentForNewKnowledgeFile(rel);
+  const bytes = Buffer.byteLength(body, "utf8");
+  if (bytes > MAX_OBSERVABILITY_FILE_BYTES) {
+    throw new Error("Content exceeds size limit.");
+  }
+  const parent = dirname(candidate);
+  if (!isInsidePath(root, parent)) {
+    throw new Error("Invalid parent directory.");
+  }
+  await mkdir(parent, { recursive: true });
+  await writeFile(candidate, body, { encoding: "utf8" });
+  const info = await stat(candidate);
+  return {
+    relativePath: rel,
+    sizeBytes: info.size
+  };
+}
+
+/** Rename/move a knowledge file within the knowledge root. */
+export async function renameKnowledgeFile(input: {
+  companyId: string;
+  fromRelativePath: string;
+  toRelativePath: string;
+}) {
+  const fromRel = assertKnowledgeRelativePath(input.fromRelativePath.trim());
+  const toRel = assertKnowledgeRelativePath(input.toRelativePath.trim());
+  if (fromRel === toRel) {
+    return { relativePath: toRel };
+  }
+  const { root } = await knowledgeRoot(input.companyId);
+  const fromAbs = resolve(root, fromRel);
+  const toAbs = resolve(root, toRel);
+  if (!isInsidePath(root, fromAbs) || !isInsidePath(root, toAbs)) {
+    throw new Error("Requested path is outside of knowledge directory.");
+  }
+  const fromInfo = await stat(fromAbs);
+  if (!fromInfo.isFile()) {
+    throw new Error("Source path is not a file.");
+  }
+  try {
+    await stat(toAbs);
+    throw new Error("A file already exists at the destination path.");
+  } catch (error) {
+    if (error instanceof Error && error.message === "A file already exists at the destination path.") {
+      throw error;
+    }
+    const code = error && typeof error === "object" && "code" in error ? (error as NodeJS.ErrnoException).code : undefined;
+    if (code !== "ENOENT") {
+      throw error;
+    }
+  }
+  const parent = dirname(toAbs);
+  if (!isInsidePath(root, parent)) {
+    throw new Error("Invalid parent directory.");
+  }
+  await mkdir(parent, { recursive: true });
+  await rename(fromAbs, toAbs);
+  return { relativePath: toRel };
+}
+
+/** Folder path prefix (no trailing slash), e.g. `guides/onboarding`. */
+export function assertKnowledgeFolderPrefix(prefix: string): string {
+  const normalized = prefix.trim().replace(/\\/g, "/").replace(/\/+$/g, "");
+  if (!normalized) {
+    throw new Error("Invalid folder path.");
+  }
+  if (normalized.startsWith("/") || normalized.includes("..")) {
+    throw new Error("Invalid folder path.");
+  }
+  const parts = normalized.split("/").filter(Boolean);
+  if (parts.length === 0 || parts.length > MAX_PATH_SEGMENTS - 1) {
+    throw new Error("Invalid folder path.");
+  }
+  for (const p of parts) {
+    if (p === "." || p === ".." || p.startsWith(".")) {
+      throw new Error("Invalid folder path.");
+    }
+  }
+  return parts.join("/");
+}
+
+/**
+ * Rename a knowledge folder by moving every file under `fromPrefix/` to the same relative paths under `toPrefix`.
+ */
+export async function renameKnowledgeFolderPrefix(input: {
+  companyId: string;
+  fromPrefix: string;
+  toPrefix: string;
+}) {
+  const fromP = assertKnowledgeFolderPrefix(input.fromPrefix);
+  const toP = assertKnowledgeFolderPrefix(input.toPrefix);
+  if (fromP === toP) {
+    return { moved: 0, fromPrefix: fromP, toPrefix: toP };
+  }
+  if (toP.startsWith(`${fromP}/`) || fromP.startsWith(`${toP}/`)) {
+    throw new Error("Invalid folder rename: one folder sits inside the other.");
+  }
+  const { files } = await listKnowledgeFiles({ companyId: input.companyId, maxFiles: MAX_OBSERVABILITY_FILES });
+  const paths = files.map((f) => f.relativePath);
+  const filePathsToMove = paths.filter((p) => p.startsWith(`${fromP}/`));
+  if (filePathsToMove.length === 0) {
+    throw new Error("No files found under that folder.");
+  }
+  const existing = new Set(paths);
+  for (const p of filePathsToMove) {
+    const np = `${toP}${p.slice(fromP.length)}`;
+    if (existing.has(np) && !filePathsToMove.includes(np)) {
+      throw new Error(`A file already exists at ${np}.`);
+    }
+  }
+  const sorted = [...filePathsToMove].sort((a, b) => b.length - a.length);
+  for (const p of sorted) {
+    const np = `${toP}${p.slice(fromP.length)}`;
+    await renameKnowledgeFile({
+      companyId: input.companyId,
+      fromRelativePath: p,
+      toRelativePath: np
+    });
+    existing.delete(p);
+    existing.add(np);
+  }
+  return { moved: sorted.length, fromPrefix: fromP, toPrefix: toP };
+}
+
+export async function deleteKnowledgeFile(input: { companyId: string; relativePath: string }) {
+  const { root } = await knowledgeRoot(input.companyId);
+  const rel = assertKnowledgeRelativePath(input.relativePath);
+  const candidate = resolve(root, rel);
+  if (!isInsidePath(root, candidate)) {
+    throw new Error("Requested path is outside of knowledge directory.");
+  }
+  const info = await stat(candidate);
+  if (!info.isFile()) {
+    throw new Error("Requested path is not a file.");
+  }
+  await rm(candidate, { force: true });
+  return { relativePath: rel };
+}
+
+export async function knowledgeFileExists(input: { companyId: string; relativePath: string }): Promise<boolean> {
+  try {
+    const rel = assertKnowledgeRelativePath(input.relativePath);
+    const { root } = await knowledgeRoot(input.companyId);
+    const candidate = resolve(root, rel);
+    if (!isInsidePath(root, candidate)) {
+      return false;
+    }
+    const info = await stat(candidate);
+    return info.isFile();
+  } catch {
+    return false;
+  }
+}

package/src/services/company-skill-file-service.ts

@@ -1,4 +1,4 @@
-import { mkdir, mkdtemp, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join, relative, resolve } from "node:path";
 import TurndownService from "turndown";
@@ -8,6 +8,9 @@ const MAX_OBSERVABILITY_FILES = 200;
 const MAX_OBSERVABILITY_FILE_BYTES = 512 * 1024;
 const SKILL_MD = "SKILL.md";
 export const SKILL_LINK_BASENAME = ".bopo-skill-link.json";
+/** Optional UI-only label for the skill in Settings (does not rename files or the skill id). */
+export const SKILL_SIDEBAR_TITLE_BASENAME = ".bopo-skill-sidebar-title.json";
+const MAX_SKILL_SIDEBAR_TITLE_CHARS = 200;
 const SKILL_ID_RE = /^[a-zA-Z0-9_-]+$/;
 const TEXT_EXT = new Set([".md", ".yaml", ".yml", ".txt", ".json"]);
 
@@ -27,6 +30,8 @@ export type CompanySkillPackageListItem = {
   skillId: string;
   linkedUrl: string | null;
   linkLastFetchedAt: string | null;
+  /** When set, shown in Settings sidebar instead of `skillId`. */
+  sidebarTitle: string | null;
 };
 
 export function assertCompanySkillId(skillId: string): string {
@@ -101,6 +106,24 @@ export async function readOptionalSkillLinkUrl(root: string): Promise<string | n
   return rec?.url ?? null;
 }
 
+export async function readOptionalSkillSidebarTitle(root: string): Promise<string | null> {
+  try {
+    const raw = await readFile(join(root, SKILL_SIDEBAR_TITLE_BASENAME), "utf8");
+    const parsed: unknown = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object") {
+      return null;
+    }
+    const t = (parsed as { sidebarTitle?: unknown }).sidebarTitle;
+    if (typeof t !== "string") {
+      return null;
+    }
+    const s = t.trim();
+    return s.length > 0 ? s : null;
+  } catch {
+    return null;
+  }
+}
+
 async function writeSkillLinkMetadata(root: string, url: string): Promise<{ lastFetchedAt: string }> {
   const lastFetchedAt = new Date().toISOString();
   await writeFile(
@@ -131,10 +154,12 @@ export async function listCompanySkillPackages(input: { companyId: string; maxSk
     if (!hasMd && !linkedUrl) {
       continue;
     }
+    const sidebarTitle = await readOptionalSkillSidebarTitle(skillDir);
     items.push({
       skillId: ent.name,
       linkedUrl,
-      linkLastFetchedAt: linkRec?.lastFetchedAt ?? null
+      linkLastFetchedAt: linkRec?.lastFetchedAt ?? null,
+      sidebarTitle
     });
     if (items.length >= maxSkills) {
       break;
@@ -227,6 +252,47 @@ export async function readCompanySkillFile(input: {
   };
 }
 
+function assertSkillSidebarTitle(trimmed: string): string {
+  if (!trimmed) {
+    throw new Error("Title is empty.");
+  }
+  if (trimmed.length > MAX_SKILL_SIDEBAR_TITLE_CHARS) {
+    throw new Error(`Title must be at most ${MAX_SKILL_SIDEBAR_TITLE_CHARS} characters.`);
+  }
+  if (/[\r\n]/.test(trimmed)) {
+    throw new Error("Title cannot contain line breaks.");
+  }
+  return trimmed;
+}
+
+/** Set or clear the Settings-only sidebar label for a company skill package. */
+export async function setCompanySkillSidebarTitle(input: {
+  companyId: string;
+  skillId: string;
+  /** Empty / whitespace removes the custom title (sidebar falls back to skill id). */
+  title: string;
+}) {
+  const { root, id } = await skillRoot(input.companyId, input.skillId);
+  const hasMd = await skillDirHasSkillMd(root);
+  const linkedUrl = await readOptionalSkillLinkUrl(root);
+  if (!hasMd && !linkedUrl) {
+    throw new Error("Skill not found.");
+  }
+  const metaPath = join(root, SKILL_SIDEBAR_TITLE_BASENAME);
+  const trimmedAll = input.title.trim();
+  if (!trimmedAll || trimmedAll === id) {
+    try {
+      await rm(metaPath, { force: true });
+    } catch {
+      /* noop */
+    }
+    return { skillId: id, sidebarTitle: null as string | null };
+  }
+  const t = assertSkillSidebarTitle(trimmedAll);
+  await writeFile(metaPath, JSON.stringify({ sidebarTitle: t }, null, 2), "utf8");
+  return { skillId: id, sidebarTitle: t };
+}
+
 export async function writeCompanySkillFile(input: {
   companyId: string;
   skillId: string;
@@ -263,6 +329,89 @@ export async function writeCompanySkillFile(input: {
   };
 }
 
+/** Rename/move a text file within one skill package directory. */
+export async function renameCompanySkillFile(input: {
+  companyId: string;
+  skillId: string;
+  fromRelativePath: string;
+  toRelativePath: string;
+}) {
+  const { root } = await skillRoot(input.companyId, input.skillId);
+  const fromRel = assertSkillRelativePath(input.fromRelativePath.trim());
+  const toRel = assertSkillRelativePath(input.toRelativePath.trim());
+  if (fromRel === toRel) {
+    return { skillId: input.skillId, relativePath: toRel };
+  }
+  const fromAbs = resolve(root, fromRel);
+  const toAbs = resolve(root, toRel);
+  if (!isInsidePath(root, fromAbs) || !isInsidePath(root, toAbs)) {
+    throw new Error("Requested path is outside of skill directory.");
+  }
+  const hasMd = await skillDirHasSkillMd(root);
+  const linkedUrl = await readOptionalSkillLinkUrl(root);
+  if (linkedUrl && !hasMd && fromRel === SKILL_MD) {
+    throw new Error("This skill is loaded from a URL only; save a local copy before renaming.");
+  }
+  const fromInfo = await stat(fromAbs);
+  if (!fromInfo.isFile()) {
+    throw new Error("Source path is not a file.");
+  }
+  try {
+    await stat(toAbs);
+    throw new Error("A file already exists at the destination path.");
+  } catch (error) {
+    if (error instanceof Error && error.message === "A file already exists at the destination path.") {
+      throw error;
+    }
+    const code = error && typeof error === "object" && "code" in error ? (error as NodeJS.ErrnoException).code : undefined;
+    if (code !== "ENOENT") {
+      throw error;
+    }
+  }
+  const parent = dirname(toAbs);
+  if (!isInsidePath(root, parent)) {
+    throw new Error("Invalid parent directory.");
+  }
+  await mkdir(parent, { recursive: true });
+  await rename(fromAbs, toAbs);
+  return { skillId: input.skillId, relativePath: toRel };
+}
+
+/** Delete one text file from a skill package. Removing sole local SKILL.md with no URL link deletes the package folder. */
+export async function deleteCompanySkillFile(input: {
+  companyId: string;
+  skillId: string;
+  relativePath: string;
+}) {
+  const { root } = await skillRoot(input.companyId, input.skillId);
+  const rel = assertSkillRelativePath(input.relativePath.trim());
+  const candidate = resolve(root, rel);
+  if (!isInsidePath(root, candidate)) {
+    throw new Error("Requested path is outside of skill directory.");
+  }
+  const hasMd = await skillDirHasSkillMd(root);
+  const linkedUrl = await readOptionalSkillLinkUrl(root);
+  if (rel === SKILL_MD && linkedUrl && !hasMd) {
+    throw new Error("This skill is loaded from a URL only; delete the whole skill or refresh from URL.");
+  }
+  const allFiles = await walkSkillTextFiles(root, MAX_OBSERVABILITY_FILES);
+  if (rel === SKILL_MD && allFiles.length > 1) {
+    throw new Error("Remove other files in this skill before deleting SKILL.md.");
+  }
+  const info = await stat(candidate);
+  if (!info.isFile()) {
+    throw new Error("Requested path is not a file.");
+  }
+  await rm(candidate, { force: true });
+  if (rel === SKILL_MD && allFiles.length === 1) {
+    const stillLinked = await readOptionalSkillLinkUrl(root);
+    if (!stillLinked) {
+      await rm(root, { recursive: true, force: true });
+    }
+  }
+  return { skillId: input.skillId, relativePath: rel };
+}
+
 /** Remove `skills/<id>/` entirely (local files and linked-skill pointer). */
 export async function deleteCompanySkillPackage(input: { companyId: string; skillId: string }) {
   const { root, id } = await skillRoot(input.companyId, input.skillId);

package/src/validation/issue-routes.ts

@@ -1,4 +1,19 @@
 import { z } from "zod";
+import { assertKnowledgeRelativePath } from "../services/company-knowledge-file-service";
+
+const KnowledgePathSchema = z.string().min(1).max(1024).superRefine((val, ctx) => {
+  try {
+    assertKnowledgeRelativePath(val);
+  } catch (err) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: err instanceof Error ? err.message : "Invalid knowledge path"
+    });
+  }
+});
+
+const knowledgePathsCreate = z.array(KnowledgePathSchema).max(20).default([]);
+const knowledgePathsUpdate = z.array(KnowledgePathSchema).max(20);
 
 export const createIssueSchema = z.object({
   projectId: z.string().min(1),
@@ -28,7 +43,8 @@ export const createIssueSchema = z.object({
   goalIds: z.array(z.string().min(1)).default([]),
   externalLink: z.string().max(2048).nullable().optional(),
   labels: z.array(z.string()).default([]),
-  tags: z.array(z.string()).default([])
+  tags: z.array(z.string()).default([]),
+  knowledgePaths: knowledgePathsCreate
 });
 
 export const createIssueCommentSchema = z.object({
@@ -75,6 +91,7 @@ export const updateIssueSchema = z
     goalIds: z.array(z.string().min(1)).optional(),
     externalLink: z.string().max(2048).nullable().optional(),
     labels: z.array(z.string()).optional(),
-    tags: z.array(z.string()).optional()
+    tags: z.array(z.string()).optional(),
+    knowledgePaths: knowledgePathsUpdate.optional()
   })
   .refine((payload) => Object.keys(payload).length > 0, "At least one field must be provided.");