symbio 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,41 @@ versions follow [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.5.0]
+
+- Docs tab: a folder tree instead of a flat list; search across all docs (any case or accent) that
+  opens the doc at the matching line; links and paths in backticks that point to another doc open
+  it, with Back; an "On this page" outline for long docs; .txt sources shown with line numbers.
+- Rules register (optional, per project; on by default for new projects): agents record rules with
+  their sources, literal excerpts, who imposes them, confirmation and status through new tools, and
+  the Docs tab shows them as a filterable index grouped by area and stage. A citation opens its
+  source: a text doc at the cited line, a PDF in a new tab at the cited page.
+- Links in docs to PDFs and images open them in a new tab.
+- `view_image`: agents look at images through a scaled-down copy (or a full-resolution crop);
+  reading image files directly is refused with a message pointing to it, so images can't bloat a
+  conversation.
+- An agent whose conversation becomes too large to send ("Timed out reading request body", often
+  after reading full-size images) continues in a fresh session with a handoff note, instead of
+  Symbio trying every other model.
+- A helper's folder that was deleted outside Symbio is recreated from its branch (committed work
+  kept), and the human and the helper are told.
+- A project reopened from its folder takes the rules register choice made in the New project dialog.
+
+## [0.4.0]
+
+- Helpers can work in the project folder itself instead of their own copy on a branch: what one
+  writes, the next sees at once, with nothing to merge (for pipelines and step-by-step work).
+  Settings → Team sets the default for new helpers; core can choose per helper; existing helpers
+  can be moved into the project folder from their chat (or by core) once their work is merged.
+- Background processes belong to the agent that started them: in a shared folder, agents only
+  see and stop their own, and stopping a helper stops only its processes.
+- Agents are told that OpenCode's "tool catalog changed" notices don't list Symbio's tools, so they
+  keep using them instead of reporting them missing.
+- update_task accepts summary as well as note, so review notes aren't lost.
+- Symbio no longer crashes when OpenCode is restarted (to free memory) while it was reading usage;
+  errors in background work are logged instead of stopping the app.
+- Long chats: asking for a 200-message page no longer fails.
+
 ## [0.3.0]
 
 - Remote access: `sym remote` (or Settings → Remote access) opens a temporary Cloudflare link with an

package/README.md

@@ -55,14 +55,23 @@ place. Here Symbio was restarted mid-task, and it told the helper to pick up whe
 - **One conversation, a whole team.** You chat with core. It asks what you want, studies an
   existing folder before touching it, and proposes a plan of tasks for you to approve.
 - **Helpers that work in parallel without collisions.** Each helper gets its own git worktree and
-  branch. core reviews and merges their work. Helpers are only created when work can really run in
-  parallel; one helper is the default.
+  branch, and core reviews and merges their work. For step-by-step work (each step using the
+  previous one's files), helpers can share the project folder instead, with nothing to merge.
+  Helpers are only created when work can really run in parallel; one helper is the default.
 - **Agents talk to each other.** Messages go straight from agent to agent through Symbio, and
   delivering a message wakes the recipient. No copy-pasting between terminals.
 - **Shared assets with a gatekeeper.** Anything several agents could change (a file pattern, a
   database, a spreadsheet) can be declared a *shared asset*. Agents request it from core, wait for
   the grant and release it when done. Changes to an asset an agent wasn't granted are flagged at
   merge.
+- **Documentation you can find your way in.** core keeps the project's docs up to date, and the
+  Docs tab shows them as a folder tree with search across every doc, links between docs that open
+  in place, an outline of long docs, and plain-text sources (e-mails, transcripts) with line
+  numbers.
+- **A rules register (optional).** Agents record the project's rules (requirements, decisions,
+  constraints) with where each came from, a literal excerpt, who imposes it, how confirmed it is
+  and whether it's met. The Docs tab shows them as an index you can filter and search, with each
+  citation opening its source at the cited line.
 - **A live plan.** The Plan tab is an animated kanban that moves by itself as helpers pick up
   tasks, ask for review and get merged.
 - **You stay in control.** Questions, plan approvals, permission requests (like installing
@@ -75,7 +84,8 @@ place. Here Symbio was restarted mid-task, and it told the helper to pick up whe
   when a model fails (quota, outage) the agent switches to the next allowed model and carries on.
 - **Safety rails.** Agents can't kill processes by name (which would take down your terminals and
   editors), can't read your SSH keys or Symbio's secret store, and must ask before installing
-  software.
+  software. They look at images through scaled-down copies, so a few large pictures can't make a
+  conversation too big to send.
 
 ## Requirements
 
@@ -147,7 +157,7 @@ itself. Whoever gets in controls your agents, so keep the link and code to yours
 | Term | Meaning |
 |---|---|
 | **core** | The project's lead agent. It plans, delegates, reviews and merges; it coordinates rather than doing the work itself. |
-| **Helper** | An agent core creates for a piece of work. It works in its own git worktree (branch `symbio/<name>`). |
+| **Helper** | An agent core creates for a piece of work. It works in its own git worktree (branch `symbio/<name>`) or, if the project is set to, in the project folder itself. |
 | **Shared asset** | Something more than one agent could change. Access goes through core: request, grant, release. |
 | **Connection** | A GitHub account or SSH server agents can use through Symbio, without ever seeing its credentials. |
 | **Allowed models** | The models a project's agents may run on. If one fails, agents fall back to the next. |

package/dist/server/api.js

@@ -9,7 +9,8 @@ import { describeInspection, inspectFolder } from "./inspect.js";
 import { gitAvailable, initRepository } from "./git.js";
 import { pickFolder } from "./folder-picker.js";
 import { beginOauth, cancelOauth, completeOauth, connectWithKey, listProviders, oauthStatus, removeLogin } from "./providers.js";
-import { docsRoot, listDocs, readDoc, writeDoc } from "./docs.js";
+import { docsRoot, listDocs, rawDoc, readDoc, searchDocs, writeDoc } from "./docs.js";
+import { readRegister } from "./rules.js";
 import { PriceBook, projectUsage, resolvePrices } from "./costs.js";
 import { globalDir } from "./store.js";
 // Debug routes pass OpenCode responses through, which can contain provider keys.
@@ -269,6 +270,7 @@ export function createApi(store, runtime, team, connections) {
             allowedModels: allowed,
             coordinatorModel: body.coordinatorModel,
             docsLocation: body.docsLocation === "private" ? "private" : "project",
+            rulesRegister: body.rulesRegister === true,
             origin: inspection.empty ? "new" : "existing",
             inspectionSummary: describeInspection(inspection),
             connections: cleanLinks(body.connections),
@@ -291,6 +293,10 @@ export function createApi(store, runtime, team, connections) {
     api.patch("/projects/:id", async (c) => {
         const project = withProject(c.req.param("id"));
         const body = await c.req.json();
+        if (typeof body.rulesRegister === "boolean")
+            await team.setRulesRegister(project, body.rulesRegister);
+        if (body.helperWorkspace === "own" || body.helperWorkspace === "shared")
+            await team.setHelperWorkspace(project, body.helperWorkspace);
         if (body.name?.trim())
             project.name = body.name.trim();
         if (body.renewSessions === "manual" || body.renewSessions === "after-task")
@@ -358,6 +364,34 @@ export function createApi(store, runtime, team, connections) {
         const project = withProject(c.req.param("id"));
         return c.json({ location: project.docsLocation, root: docsRoot(project), files: await listDocs(project) });
     });
+    api.get("/projects/:id/rules", async (c) => {
+        const project = withProject(c.req.param("id"));
+        return c.json({ enabled: !!project.rulesRegister, ...(await readRegister(project)) });
+    });
+    // Any file in the docs (a PDF cited by a rule, an image), read-only.
+    api.get("/projects/:id/docs/raw", async (c) => {
+        const project = withProject(c.req.param("id"));
+        try {
+            const file = await rawDoc(project, c.req.query("path") ?? "");
+            return new Response(new Uint8Array(file.data), {
+                headers: {
+                    "content-type": file.type,
+                    "content-disposition": `${file.inline ? "inline" : "attachment"}; filename*=UTF-8''${encodeURIComponent(file.name)}`,
+                    "x-content-type-options": "nosniff",
+                    "content-security-policy": "default-src 'none'; img-src 'self' blob: data:; style-src 'unsafe-inline'",
+                },
+            });
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                throw new HttpError(404, "file not found");
+            throw new HttpError(400, err.message);
+        }
+    });
+    api.get("/projects/:id/docs/search", async (c) => {
+        const project = withProject(c.req.param("id"));
+        return c.json(await searchDocs(project, (c.req.query("q") ?? "").slice(0, 200)));
+    });
     api.get("/projects/:id/docs/file", async (c) => {
         const project = withProject(c.req.param("id"));
         const rel = c.req.query("path") ?? "";
@@ -501,6 +535,18 @@ export function createApi(store, runtime, team, connections) {
             return c.json({ error: err.message }, 400);
         }
     });
+    // Moves a helper from its own copy (branch) into the project folder.
+    api.post("/projects/:id/agents/:agentId/move-to-project-folder", async (c) => {
+        const project = withProject(c.req.param("id"));
+        const agent = withAgent(project, c.req.param("agentId"));
+        try {
+            await team.moveToProjectFolder(project, agent, "moved by the human");
+            return c.json(project);
+        }
+        catch (err) {
+            return c.json({ error: err.message }, 400);
+        }
+    });
     // A fresh session for a long-running agent (keeps its identity; the old session stays readable).
     api.post("/projects/:id/agents/:agentId/renew", async (c) => {
         const project = withProject(c.req.param("id"));

package/dist/server/docs.js

@@ -44,13 +44,60 @@ export async function listDocs(project) {
 export async function readDoc(project, rel) {
     return fs.readFile(resolveDoc(project, rel), "utf8");
 }
+const MAX_MATCHES = 300;
+const MAX_SEARCH_BYTES = 2_000_000; // per file; larger files are skipped
+/** Case- and accent-insensitive, so "regra" also finds "Regra" and "regrá". */
+const fold = (s) => s.normalize("NFD").replace(/\p{Diacritic}/gu, "").toLowerCase();
+/** Lines containing every word of the query, across all docs. */
+export async function searchDocs(project, query) {
+    const words = fold(query).split(/\s+/).filter(Boolean);
+    if (!words.length)
+        return { matches: [], truncated: false };
+    const matches = [];
+    for (const file of await listDocs(project)) {
+        if (file.size > MAX_SEARCH_BYTES)
+            continue;
+        const lines = (await readDoc(project, file.path).catch(() => "")).split(/\r?\n/);
+        for (let i = 0; i < lines.length; i++) {
+            const hay = fold(lines[i]);
+            if (!words.every((w) => hay.includes(w)))
+                continue;
+            matches.push({ path: file.path, line: i + 1, text: lines[i].trim().slice(0, 300) });
+            if (matches.length >= MAX_MATCHES)
+                return { matches, truncated: true };
+        }
+    }
+    return { matches, truncated: false };
+}
 export async function writeDoc(project, rel, content) {
     const abs = resolveDoc(project, rel);
     await fs.mkdir(path.dirname(abs), { recursive: true });
     await fs.writeFile(abs, content);
 }
+/**
+ * Any file in the docs locations, read-only, with how to send it: sources cited by the rules
+ * register are often PDFs or images. Shown inline only for types a browser displays safely
+ * (no HTML or SVG, which could run scripts); everything else is a download.
+ */
+export async function rawDoc(project, rel) {
+    const abs = resolveDoc(project, rel, true);
+    const ext = path.extname(abs).toLowerCase();
+    const inline = RAW_INLINE[ext];
+    return { data: await fs.readFile(abs), type: inline ?? "application/octet-stream", inline: !!inline, name: path.basename(abs) };
+}
+const RAW_INLINE = {
+    ".pdf": "application/pdf",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".txt": "text/plain; charset=utf-8",
+    ".md": "text/plain; charset=utf-8",
+    ".csv": "text/plain; charset=utf-8",
+};
 /** Validates a doc path against the allowed locations. Throws on anything else. */
-function resolveDoc(project, rel) {
+function resolveDoc(project, rel, anyType = false) {
     const root = docsRoot(project);
     const normalized = rel.replace(/\\/g, "/").replace(/^\/+/, "");
     const abs = path.resolve(root, normalized);
@@ -59,7 +106,7 @@ function resolveDoc(project, rel) {
     const allowed = project.docsLocation === "private"
         ? insideRoot
         : insideRoot && (relBack === "AGENTS.md" || relBack.startsWith("docs/"));
-    if (!allowed || !TEXT_EXT.has(path.extname(abs).toLowerCase())) {
+    if (!allowed || (!anyType && !TEXT_EXT.has(path.extname(abs).toLowerCase()))) {
         throw new Error(`Not a docs file: ${rel}`);
     }
     // A symlink inside the docs could point at any file (an SSH key, say); compare real

package/dist/server/guard.js

@@ -99,16 +99,37 @@ const SECRET_SHELL = [
     "*.symbio*backups*",
     "*opencode*auth.json*",
 ];
+// Images read with the read tool go into the conversation at full size and are re-sent every
+// turn; a few large ones made a conversation too big to send at all. Agents look at images
+// through Symbio's view_image tool instead, which scales them down. These reads are "ask", not
+// "deny", only so the refusal can carry a message: Symbio rejects them itself, at once, telling
+// the agent to use view_image (a bare deny just says "Permission denied", and a model gave up).
+// Patterns are case-sensitive, hence both spellings.
+export const IMAGE_EXTENSIONS = ["png", "jpg", "jpeg", "gif", "webp", "bmp"];
+const IMAGE_PATHS = IMAGE_EXTENSIONS.flatMap((ext) => [`*.${ext}`, `*.${ext.toUpperCase()}`]);
+/** A read Symbio refuses on the agent's behalf (an image file), with what to do instead. */
+export function imageReadRefusal(action, resources) {
+    if (action !== "read" || !resources.length || !resources.every((r) => IMAGE_PATHS.some((p) => wildcardMatch(p, r))))
+        return null;
+    return ("Symbio blocks reading image files directly: a full-size image stays in your conversation and is sent again on every " +
+        `turn. Use Symbio's view_image tool instead (in code mode: tools.symbio.view_image({ path: ${JSON.stringify(resources[0])} })); ` +
+        "it returns a scaled-down copy, and a crop shows details at full resolution.");
+}
 const rules = (action, effect, patterns) => patterns.map((resource) => ({ action, resource, effect }));
 // Any matching deny blocks a call; otherwise any ask prompts. Deny rules come last
 // so they also win under "last match wins".
 export const AGENT_PERMISSIONS = [
     ...rules("shell", "ask", INSTALL_PATTERNS),
+    ...rules("read", "ask", IMAGE_PATHS), // refused by Symbio with a message (imageReadRefusal)
     ...rules("shell", "deny", KILL_PATTERNS),
     ...rules("shell", "deny", SECRET_SHELL),
     ...rules("read", "deny", SECRET_PATHS),
     ...rules("edit", "deny", SECRET_PATHS),
 ];
+/** Whether a path is one agents may never read (keys, Symbio's secrets…), for Symbio's own file tools. */
+export function isSecretPath(file) {
+    return SECRET_PATHS.some((p) => wildcardMatch(p, file));
+}
 /** Text for agent briefs explaining the rule and the alternative. */
 export const PROCESS_RULES = `- Never kill processes by name or PID (taskkill, Stop-Process, kill, pkill…):
   other programs on this machine — the human's terminals and editors, other

package/dist/server/images.js

@@ -0,0 +1,54 @@
+// view_image: agents look at images through scaled-down copies. A full-size image read into a
+// conversation stays there and is re-sent every turn; a few large ones made a conversation too
+// big to send at all. A crop shows one region at full resolution when details matter.
+import { existsSync, promises as fs } from "node:fs";
+import path from "node:path";
+import sharp from "sharp";
+import { IMAGE_EXTENSIONS, isSecretPath } from "./guard.js";
+export const DEFAULT_IMAGE_SIZE = 1024;
+const MAX_IMAGE_SIZE = 2048;
+const MAX_BYTES = 1_500_000; // what we send back, after scaling
+export async function viewImage(folder, input) {
+    const given = String(input.path ?? "").trim();
+    if (!given)
+        throw new Error("Give the image's path.");
+    const file = path.resolve(folder, given);
+    const ext = path.extname(file).slice(1).toLowerCase();
+    if (!IMAGE_EXTENSIONS.includes(ext))
+        throw new Error(`Not an image (${IMAGE_EXTENSIONS.join(", ")}): ${given}`);
+    if (isSecretPath(file))
+        throw new Error(`Not allowed: ${given}`);
+    if (!existsSync(file))
+        throw new Error(`No such file: ${file}`);
+    const size = Math.min(MAX_IMAGE_SIZE, Math.max(64, Math.round(Number(input.max_size) || DEFAULT_IMAGE_SIZE)));
+    let image = sharp(await fs.readFile(file), { animated: false }).rotate(); // apply EXIF orientation
+    const meta = await image.metadata();
+    const width = meta.autoOrient?.width ?? meta.width ?? 0;
+    const height = meta.autoOrient?.height ?? meta.height ?? 0;
+    if (!width || !height)
+        throw new Error(`Couldn't read the image: ${given}`);
+    let note = `${given}: ${width}×${height} px`;
+    const crop = input.crop;
+    if (crop && typeof crop === "object") {
+        const left = Math.max(0, Math.floor(Number(crop.left) || 0));
+        const top = Math.max(0, Math.floor(Number(crop.top) || 0));
+        const w = Math.min(width - left, Math.floor(Number(crop.width) || 0));
+        const h = Math.min(height - top, Math.floor(Number(crop.height) || 0));
+        if (w <= 0 || h <= 0)
+            throw new Error(`The crop must lie inside the ${width}×${height} image (left, top, width, height in pixels).`);
+        image = image.extract({ left, top, width: w, height: h });
+        note += `, region ${w}×${h} at (${left}, ${top})`;
+    }
+    image = image.resize({ width: size, height: size, fit: "inside", withoutEnlargement: true });
+    // JPEG keeps it small; flatten transparency onto white so it stays readable.
+    let quality = 82;
+    let out = await image.clone().flatten({ background: "#ffffff" }).jpeg({ quality }).toBuffer({ resolveWithObject: true });
+    while (out.data.length > MAX_BYTES && quality > 40) {
+        quality -= 15;
+        out = await image.clone().flatten({ background: "#ffffff" }).jpeg({ quality }).toBuffer({ resolveWithObject: true });
+    }
+    note += `, shown at ${out.info.width}×${out.info.height}.`;
+    if (!crop && (out.info.width < width || out.info.height < height))
+        note += " For details, ask for a crop (a region in the original's pixels), shown at full resolution.";
+    return { content: [{ type: "text", text: note }, { type: "image", data: out.data.toString("base64"), mimeType: "image/jpeg" }] };
+}

package/dist/server/index.js

@@ -16,6 +16,9 @@ import { OpencodeRuntime } from "./opencode/runtime.js";
 import { Store, globalDir } from "./store.js";
 import { Team } from "./team.js";
 import { removeOrphanWorkspaces } from "./workspaces.js";
+// Background work (timers, event handlers) must never take the whole app down: an error there
+// (e.g. OpenCode restarting mid-call) is logged and the next tick tries again.
+process.on("unhandledRejection", (err) => console.error("[unhandled]", err instanceof Error ? err.stack ?? err.message : err));
 const PORT = Number(process.env.SYMBIO_PORT ?? 4310);
 const here = path.dirname(fileURLToPath(import.meta.url));
 // dist/server/index.js → dist/web ; src/server/index.ts → dist/web (after a build)

package/dist/server/mcp.js

@@ -58,8 +58,8 @@ async function handleOne(req, token, resolve) {
             if (caller.ctx == null)
                 return fail(-32001, "could not identify the calling agent");
             try {
-                const text = await tool.run(req.params?.arguments ?? {}, caller.ctx);
-                return reply({ content: [{ type: "text", text }] });
+                const result = await tool.run(req.params?.arguments ?? {}, caller.ctx);
+                return reply({ content: typeof result === "string" ? [{ type: "text", text: result }] : result.content });
             }
             catch (err) {
                 // Tool errors go back to the model as a result, so it can react.

package/dist/server/opencode/client.js

@@ -101,6 +101,7 @@ export class OpencodeClient {
      * "older than id" (verified against 2.1.4, see docs/opencode-api.md).
      */
     async messagePage(sessionId, limit, before) {
+        limit = Math.min(limit, 199); // OpenCode refuses more than 200, and we ask for one extra
         const params = new URLSearchParams({ limit: String(limit + 1) }); // one extra tells whether more exist
         if (before)
             params.set("cursor", Buffer.from(JSON.stringify({ id: before, order: "desc", direction: "next" })).toString("base64url"));

package/dist/server/prompts.js

@@ -1,7 +1,25 @@
 // Briefings injected into agent sessions as instruction entries.
 // Keep these domain-neutral: projects can be software, writing, research, design, anything.
+import { existsSync } from "node:fs";
+import path from "node:path";
 import { docsPaths } from "./docs.js";
 import { PROCESS_RULES } from "./guard.js";
+// Seen live: a coordinator read eight 2–4 MB images, its conversation reached 25 MB and the
+// provider gave up receiving it ("Timed out reading request body"), whatever the model.
+const KEEP_CONVERSATION_SMALL = `- Keep your conversation small: whatever you read stays in it and is sent to
+  the model again on every turn, until it becomes too large to send. Look at
+  images with Symbio's \`view_image\` tool (a scaled-down copy; ask for a crop to
+  see details) — reading image files directly is blocked. For a big file, read
+  the part you need. Reviewing many images is work for a helper.`;
+// OpenCode's code mode posts "tool catalog changed" notices that list only its own tools and
+// say the catalog is complete; Symbio's tools still work (seen live: a coordinator kept using
+// them after such a notice, another gave up without trying).
+const FINDING_TOOLS = `These tools come from the "symbio" tool server. In OpenCode's code mode you call
+them inside \`execute\` as \`tools.symbio.<name>(…)\`, and \`search({ namespace: "symbio" })\`
+finds them. OpenCode's tool catalog notices may list only its own tools, even
+when they say the catalog is complete: Symbio's tools are still there. Never
+conclude they are gone without calling one; if a call really fails, tell the
+human what the error said.`;
 export function coordinatorBrief(project, connections = "") {
     return `# You are "core", the coordinator of a Symbio project
 
@@ -58,6 +76,8 @@ ${onboarding(project)}
 
 ${docsSection(project)}
 
+${rulesSection(project, "coordinator")}
+
 ## Your team tools (from the "symbio" tool server)
 
 - \`submit_plan\`, \`add_task\`, \`list_tasks\` — the plan. Tasks are for helpers;
@@ -71,17 +91,20 @@ ${docsSection(project)}
   marks its tasks in review as done.
 - \`spawn_agent\` — create a helper agent with a name, a purpose, its first task
   (\`task_id\` from the plan, or a description) and optionally a model. ${project.allowedModels.length > 1 ? "Pick cheaper models for simpler work. " : ""}Allowed models: ${project.allowedModels.join(", ")}.
-  In a git project each helper works in its own isolated copy (its own branch);
-  it only sees **committed** files, so commit before spawning if it needs recent
-  changes.
+${helperFolders(project)}
 - \`send_message\` — message an agent. Delivering a message wakes the recipient.
 - \`list_team\` — who exists, what they do, whether they are working.
-- \`merge_work\` — bring a helper's committed work into the project. Merges are
-  checked against shared-asset grants; ungranted changes are reported to you.
+- \`merge_work\` — bring a helper's committed work into the project (helpers with
+  their own copy). Merges are checked against shared-asset grants; ungranted
+  changes are reported to you.
+- \`move_to_project_folder\` — move an idle helper from its own copy into the
+  project folder (after its work is merged); it continues in a fresh session.
 - \`stop_agent\` — stop a helper when its area of the project is finished for good.
 - \`declare_asset\`, \`grant_asset\`, \`deny_asset\`, \`list_assets\` — the shared-asset register.
 - \`ask_human\` — reach the human when you are not in a direct conversation.
 
+${FINDING_TOOLS}
+
 Team members are created with \`spawn_agent\` only. OpenCode's built-in subagent
 tool is fine for quick, read-only lookups, but never use it to do project work:
 Symbio can't see, coordinate or merge what built-in subagents do.
@@ -119,8 +142,25 @@ ${connectionsSection(connections)}
 - Never start long-running processes (servers, watchers, anything that doesn't
   exit on its own) in the foreground.
 ${PROCESS_RULES}
+${KEEP_CONVERSATION_SMALL}
 `;
 }
+/** Where helpers work, for the coordinator's tool list. */
+function helperFolders(project) {
+    if (!existsSync(path.join(project.directory, ".git"))) {
+        return "  Helpers work directly in the project folder, alongside you.";
+    }
+    const def = project.helperWorkspace === "shared" ? "shared" : "own";
+    return `  Where a helper works (\`workspace\`; this project's default is **${def}**, set by
+  the human):
+  - **own**: its own isolated copy on its own branch. It only sees **committed**
+    files (commit before spawning if it needs recent changes), and its work
+    reaches the project when you merge it. For parallel work on the same files.
+  - **shared**: the project folder itself. What it writes is there at once for
+    you and the next helper; nothing to merge, and it doesn't commit. For steps
+    that produce or check files others use next (pipelines, reviews of outputs).
+    Helpers in the project folder claim the files they write as shared assets.`;
+}
 function onboarding(project) {
     if (project.origin === "new") {
         return `## Starting point
@@ -146,6 +186,43 @@ The folder already has content. Before planning anything:
 
 Respect what is there: follow existing conventions and guidance files.`;
 }
+/** The rules register, when the project keeps one. */
+function rulesSection(project, role) {
+    if (!project.rulesRegister)
+        return "";
+    const common = `## The rules register
+
+This project keeps a register of its rules: anything the work must respect (a
+requirement, a decision, a constraint, a style rule), each with where it came
+from and whether it's met. The human reads it in Symbio's Docs tab. Use the
+tools \`list_rules\`, \`save_rule\`, \`save_rule_area\` and \`save_rule_source\`; never
+edit the register file directly.
+
+- **Only what the sources say.** A rule's text states what its source says.
+  Cite the source with its location and a literal excerpt. If nothing backs a
+  rule yet, record it without citations (it shows as unsourced) — never invent a
+  source, date or person.
+- **Confirmation:** \`found\` (extracted, nobody checked), \`checked-by-agent\`
+  (you compared text, location and excerpt against the source), \`checked-by-human\`
+  (only when the human says so), \`contested\` (a source contradicts it; ask).
+- **Status:** whether the work meets it today: \`done\`, \`partial\`, \`missing\`,
+  \`not-applicable\`. When the work differs from the rule, say so in \`current\`
+  (start with "Diverges:").
+- **Stable ids.** A rule keeps its id forever; a rule that changes is superseded
+  by a new one (\`superseded_by\`), and the old one stays for the record.
+- **Rules first.** A change of behavior that comes from a new decision is recorded
+  as a rule (with that decision as its source) before the work changes.`;
+    return role === "coordinator"
+        ? `${common}
+- **Keep it current without stopping the work.** Record rules as they come up:
+  in the human's answers, documents and meetings, and in what helpers find.
+  Ask helpers to update the rules their task touches (status, current state).
+  Areas group rules by part of the project, with stages in order; sources get
+  short codes and their file, so the human can open the cited place.`
+        : `${common}
+- When your task touches a rule, update its \`status\` and \`current\` once you're
+  done. A rule you discover goes in as \`found\`; tell the coordinator.`;
+}
 function docsSection(project) {
     const { entry, folder } = docsPaths(project);
     if (project.docsLocation === "private") {
@@ -194,7 +271,11 @@ assets. Your tasks come from the coordinator.
         ? `You work in your own isolated copy of the project, on branch \`${agent.branch}\`.
   Commit your work there with clear messages; never merge or push — the
   coordinator merges your work into the project.`
-        : "You work directly in the shared project folder, alongside other agents."}
+        : `You work directly in the project folder, alongside the coordinator and other
+  agents: what you write is there for them at once, and theirs for you. Before
+  writing files others may also write, claim them as a shared asset (below).
+  Don't commit, merge or push unless the coordinator asks; don't touch files or
+  processes that aren't yours.`}
 - When you finish a task, or are blocked, report it once: with \`update_task\`
   for plan tasks (see below), otherwise with \`send_message\` to the coordinator
   (what you did, where, anything they should know). Then end your turn; new
@@ -214,12 +295,16 @@ documents, data, configuration, external systems). Before changing one:
 
 If you are unsure whether something is shared, ask the coordinator.
 
+${rulesSection(project, "worker")}
+
 ## Tools (from the "symbio" tool server)
 
 \`send_message\`, \`ask_human\`, \`list_team\`, \`list_assets\`, \`request_asset\`,
 \`release_asset\`, \`check_messages\`, \`list_tasks\`, \`update_task\`.
 
-Tasks from the plan arrive as "Task T3: …". When you finish one, commit and call
+${FINDING_TOOLS}
+
+Tasks from the plan arrive as "Task T3: …". When you finish one, ${isolated ? "commit and " : ""}call
 \`update_task("T3", "review", <summary of what you did>)\` — that **is** your
 report to the coordinator; don't also send a message. If you are stuck, use
 \`update_task("T3", "blocked", <why>)\`.
@@ -242,6 +327,7 @@ ${connectionsSection(connections)}
 - Never start long-running processes (servers, watchers, anything that doesn't
   exit on its own) in the foreground.
 ${PROCESS_RULES}
+${KEEP_CONVERSATION_SMALL}
 `;
 }
 /** First turn, sent by Symbio right after the coordinator is created, so it speaks first. */