@surething/cockpit 1.0.275 → 1.0.276

package/dist/{chunk-6R4AHIIV.mjs → chunk-QY2K7YIF.mjs}

@@ -14,7 +14,7 @@ import {
   getTerminalOutputPath,
   readJsonFile,
   writeJsonFile
-} from "./chunk-JJWVBF6H.mjs";
+} from "./chunk-BCWVTDEZ.mjs";
 
 // packages/feature/console/src/server/plugins/browser/BrowserBridge.ts
 import { WebSocket } from "ws";

package/dist/httpApi.mjs

@@ -27,10 +27,10 @@ import {
   unregisterBrowser,
   unregisterTerminal,
   writeStdinToCommand
-} from "./chunk-6R4AHIIV.mjs";
+} from "./chunk-QY2K7YIF.mjs";
 import {
   getTerminalHistoryPath
-} from "./chunk-JJWVBF6H.mjs";
+} from "./chunk-BCWVTDEZ.mjs";
 import "./chunk-7P6ASYW6.mjs";
 
 // src/lib/httpApi.ts

package/dist/scheduledTasks.mjs

@@ -17,11 +17,12 @@ import {
   isRunActive,
   mutateJsonFile,
   readJsonFile,
+  readJsonFileForUpdate,
   requestStop,
   updateGlobalState,
   withFileLock,
   writeJsonFile
-} from "./chunk-JJWVBF6H.mjs";
+} from "./chunk-BCWVTDEZ.mjs";
 import "./chunk-7P6ASYW6.mjs";
 
 // packages/feature/agent/src/server/scheduledTasks.ts
@@ -254,7 +255,8 @@ var en_default = {
     reloadNow: "Reload",
     upgradeCommandCopied: "Copied `cockpit update`",
     projectNotes: "Project Notes",
-    closeProject: "Close project"
+    closeProject: "Close project",
+    bots: "Bots"
   },
   mobile: {
     useDesktop: "Desktop",
@@ -601,7 +603,7 @@ var en_default = {
     codexResumeFailed: "Previous session is in use by another Codex client \u2014 started a new session; history was not carried over",
     codexResumeFailedPrevious: "Previous session",
     codexResumeFailedNew: "New session",
-    placeholder: "Type a message, Enter to send (Shift+Enter for new line, paste images; start a line with / (main session) or @ (subagent) for commands, multiple allowed)",
+    placeholder: "Type a message, Enter to send (Shift+Enter for new line, paste images; start a line with / (skill), /@ (skill in a subagent) or @ (bot in a subagent), multiple allowed)",
     placeholderDisabled: "Generating... you can keep typing (ESC to cancel; if stuck, cancel and resend 'continue')",
     imageSizeLimit: "Image size exceeds limit (max 5MB), current: {{size}}MB",
     viewGitChanges: "View Git changes",
@@ -1342,6 +1344,29 @@ var en_default = {
   reviewUtils: {
     adjectives: ["Happy", "Brave", "Quiet", "Bright", "Gentle", "Agile", "Free", "Clear", "Flying", "Relaxed", "Lively", "Wise", "Calm", "Alert", "Composed", "Steady", "Cheerful", "Warm", "Bold", "Poised"],
     nouns: ["Panda", "Dolphin", "Crane", "Snow Leopard", "Skylark", "Squirrel", "Flying Fish", "Deer", "Bluebird", "Silver Fox", "Owl", "Dragonfly", "Firefly", "Sea Turtle", "Butterfly", "Monkey", "Red-crowned Crane", "Antelope", "Swallow", "Penguin"]
+  },
+  bots: {
+    title: "Bots",
+    search: "Search bots",
+    addExisting: "Add bot",
+    addTooltip: "Add as Bot",
+    emptyNoMatch: "No bots match your search.",
+    emptyNoBots: "No bots of your own yet.",
+    emptyCreatePrefix: "Use",
+    emptyCreateSuffix: "in chat to create one.",
+    emptyAddExisting: "add an existing Bot directory",
+    invalid: "Invalid",
+    builtin: "Built-in",
+    remove: "Remove registration",
+    open: "Open as project",
+    pathPlaceholder: "Absolute path to a Bot directory or its BOT.md",
+    addHint: "The directory must contain a BOT.md. Its files are not changed.",
+    added: "Bot added",
+    alreadyAdded: "Already added",
+    removed: "Bot removed; its files were kept.",
+    loadFailed: "Failed to load bots",
+    saveFailed: "Failed to add bot",
+    removeFailed: "Failed to remove bot"
   }
 };
 
@@ -1569,7 +1594,8 @@ var zh_default = {
     reloadNow: "\u5237\u65B0",
     upgradeCommandCopied: "\u5DF2\u590D\u5236 `cockpit update`",
     projectNotes: "\u9879\u76EE\u7B14\u8BB0",
-    closeProject: "\u5173\u95ED\u9879\u76EE"
+    closeProject: "\u5173\u95ED\u9879\u76EE",
+    bots: "\u673A\u5668\u4EBA"
   },
   mobile: {
     useDesktop: "\u684C\u9762\u7248",
@@ -1916,7 +1942,7 @@ var zh_default = {
     codexResumeFailed: "\u539F\u4F1A\u8BDD\u88AB\u5176\u4ED6 Codex \u5BA2\u6237\u7AEF\u5360\u7528\uFF0C\u5DF2\u65B0\u5EFA\u4F1A\u8BDD\uFF0C\u5386\u53F2\u672A\u7EE7\u627F",
     codexResumeFailedPrevious: "\u539F\u4F1A\u8BDD",
     codexResumeFailedNew: "\u65B0\u4F1A\u8BDD",
-    placeholder: "\u8F93\u5165\u6D88\u606F\uFF0CEnter \u53D1\u9001\uFF08Shift+Enter \u6362\u884C\uFF0C\u53EF\u7C98\u8D34\u56FE\u7247\uFF1B\u884C\u9996 /\uFF08\u4E3B\u4F1A\u8BDD\uFF09\u6216 @\uFF08\u5B50\u4EE3\u7406\uFF09\u5524\u8D77\u547D\u4EE4\uFF0C\u652F\u6301\u591A\u884C\u591A\u547D\u4EE4\uFF09",
+    placeholder: "\u8F93\u5165\u6D88\u606F\uFF0CEnter \u53D1\u9001\uFF08Shift+Enter \u6362\u884C\uFF0C\u53EF\u7C98\u8D34\u56FE\u7247\uFF1B\u884C\u9996 /\uFF08skill\uFF09\u3001/@\uFF08\u5B50\u4EE3\u7406\u6267\u884C skill\uFF09\u6216 @\uFF08\u5B50\u4EE3\u7406\u6267\u884C\u673A\u5668\u4EBA\uFF09\uFF0C\u652F\u6301\u591A\u884C\u591A\u547D\u4EE4\uFF09",
     placeholderDisabled: "\u751F\u6210\u4E2D... \u53EF\u7EE7\u7EED\u8F93\u5165 (ESC \u53D6\u6D88;\u5361\u4F4F\u592A\u4E45\u53EF\u53D6\u6D88\u540E\u91CD\u53D1\u300C\u7EE7\u7EED\u300D)",
     imageSizeLimit: "\u56FE\u7247\u5927\u5C0F\u8D85\u8FC7\u9650\u5236\uFF08\u6700\u5927 5MB\uFF09\uFF0C\u5F53\u524D\u5927\u5C0F: {{size}}MB",
     viewGitChanges: "\u67E5\u770B Git \u53D8\u66F4",
@@ -2657,6 +2683,29 @@ var zh_default = {
   reviewUtils: {
     adjectives: ["\u5FEB\u4E50", "\u52C7\u6562", "\u5B89\u9759", "\u660E\u4EAE", "\u6E29\u67D4", "\u7075\u5DE7", "\u81EA\u7531", "\u6E05\u6F88", "\u98DE\u7FD4", "\u60A0\u95F2", "\u6D3B\u6CFC", "\u806A\u6167", "\u6DE1\u5B9A", "\u673A\u654F", "\u4ECE\u5BB9", "\u575A\u5B9A", "\u723D\u6717", "\u548C\u7166", "\u5954\u653E", "\u6C89\u7A33"],
     nouns: ["\u718A\u732B", "\u6D77\u8C5A", "\u767D\u9E64", "\u96EA\u8C79", "\u4E91\u96C0", "\u677E\u9F20", "\u98DE\u9C7C", "\u6885\u82B1\u9E7F", "\u9752\u9E1F", "\u94F6\u72D0", "\u732B\u5934\u9E70", "\u873B\u8713", "\u8424\u706B\u866B", "\u6D77\u9F9F", "\u8774\u8776", "\u91D1\u4E1D\u7334", "\u4E39\u9876\u9E64", "\u7F9A\u7F8A", "\u71D5\u5B50", "\u4F01\u9E45"]
+  },
+  bots: {
+    title: "\u673A\u5668\u4EBA",
+    search: "\u641C\u7D22\u673A\u5668\u4EBA",
+    addExisting: "\u6DFB\u52A0\u673A\u5668\u4EBA",
+    addTooltip: "\u6DFB\u52A0\u4E3A\u673A\u5668\u4EBA",
+    emptyNoMatch: "\u6CA1\u6709\u5339\u914D\u7684\u673A\u5668\u4EBA\u3002",
+    emptyNoBots: "\u8FD8\u6CA1\u6709\u4F60\u81EA\u5DF1\u7684\u673A\u5668\u4EBA\u3002",
+    emptyCreatePrefix: "\u5728\u804A\u5929\u91CC\u4F7F\u7528",
+    emptyCreateSuffix: "\u521B\u5EFA\u4E00\u4E2A\u3002",
+    emptyAddExisting: "\u6DFB\u52A0\u5DF2\u6709\u7684\u673A\u5668\u4EBA\u76EE\u5F55",
+    invalid: "\u65E0\u6548",
+    builtin: "\u5185\u7F6E",
+    remove: "\u79FB\u9664\u6CE8\u518C",
+    open: "\u4F5C\u4E3A\u9879\u76EE\u6253\u5F00",
+    pathPlaceholder: "\u673A\u5668\u4EBA\u76EE\u5F55\u6216\u5176 BOT.md \u7684\u7EDD\u5BF9\u8DEF\u5F84",
+    addHint: "\u76EE\u5F55\u4E2D\u5FC5\u987B\u5305\u542B BOT.md\uFF0C\u4E0D\u4F1A\u6539\u52A8\u5176\u4E2D\u7684\u6587\u4EF6\u3002",
+    added: "\u673A\u5668\u4EBA\u5DF2\u6DFB\u52A0",
+    alreadyAdded: "\u5DF2\u6DFB\u52A0\u8FC7",
+    removed: "\u5DF2\u79FB\u9664\u673A\u5668\u4EBA\u6CE8\u518C\uFF0C\u76EE\u5F55\u6587\u4EF6\u4ECD\u4FDD\u7559\u3002",
+    loadFailed: "\u52A0\u8F7D\u673A\u5668\u4EBA\u5931\u8D25",
+    saveFailed: "\u6DFB\u52A0\u673A\u5668\u4EBA\u5931\u8D25",
+    removeFailed: "\u79FB\u9664\u673A\u5668\u4EBA\u5931\u8D25"
   }
 };
 
@@ -2852,6 +2901,8 @@ var ScheduledTaskManager = class {
     this.firing = /* @__PURE__ */ new Set();
     this.initialized = false;
     this.initPromise = null;
+    /** Set when the task file exists but does not parse; see init(). */
+    this.loadFailed = false;
     this.onTaskFired = null;
   }
   /**
@@ -2871,7 +2922,17 @@ var ScheduledTaskManager = class {
   async init() {
     if (this.initialized) return;
     this.initialized = true;
-    this.tasks = await readJsonFile(SCHEDULED_TASKS_FILE, []);
+    try {
+      this.tasks = await readJsonFileForUpdate(SCHEDULED_TASKS_FILE, []);
+    } catch (error) {
+      this.loadFailed = true;
+      this.tasks = [];
+      console.error(
+        `[ScheduledTaskManager] ${SCHEDULED_TASKS_FILE} could not be read \u2014 NO scheduled task will fire until it is fixed. The file has been left untouched:`,
+        error
+      );
+      return;
+    }
     console.log(`[ScheduledTaskManager] Loaded ${this.tasks.length} scheduled tasks`);
     for (const task of this.tasks) {
       if (!task.paused && !task.completed) {
@@ -2880,6 +2941,10 @@ var ScheduledTaskManager = class {
     }
     await this.saveToDisk();
   }
+  /** True when init() could not parse the task file: no timers, and no writes. */
+  isLoadFailed() {
+    return this.loadFailed;
+  }
   /**
    * Register a task-fired callback (used for WS broadcast).
    */
@@ -2890,7 +2955,7 @@ var ScheduledTaskManager = class {
    * Read tasks from disk (avoids in-memory inconsistency between dual module instances).
    */
   async readTasksFromDisk() {
-    return readJsonFile(SCHEDULED_TASKS_FILE, []);
+    return readJsonFileForUpdate(SCHEDULED_TASKS_FILE, []);
   }
   /**
    * Return all tasks for the current instance (reads from disk each time to ensure cross-instance consistency).
@@ -2928,7 +2993,7 @@ var ScheduledTaskManager = class {
   async updateTask(id, fields) {
     await this.ensureInit();
     const task = await withFileLock(SCHEDULED_TASKS_FILE, async () => {
-      const allTasks = await readJsonFile(SCHEDULED_TASKS_FILE, []);
+      const allTasks = await readJsonFileForUpdate(SCHEDULED_TASKS_FILE, []);
       const idx = allTasks.findIndex((t) => t.id === id);
       if (idx === -1) return null;
       const updated = { ...allTasks[idx], ...fields };
@@ -2953,7 +3018,7 @@ var ScheduledTaskManager = class {
   async deleteTask(id) {
     await this.ensureInit();
     const removed = await withFileLock(SCHEDULED_TASKS_FILE, async () => {
-      const allTasks = await readJsonFile(SCHEDULED_TASKS_FILE, []);
+      const allTasks = await readJsonFileForUpdate(SCHEDULED_TASKS_FILE, []);
       const idx = allTasks.findIndex((t) => t.id === id);
       if (idx === -1) return false;
       allTasks.splice(idx, 1);
@@ -2978,7 +3043,7 @@ var ScheduledTaskManager = class {
    * Resume a task.
    */
   async resumeTask(id) {
-    const allTasks = await readJsonFile(SCHEDULED_TASKS_FILE, []);
+    const allTasks = await readJsonFileForUpdate(SCHEDULED_TASKS_FILE, []);
     const task = allTasks.find((t) => t.id === id);
     if (!task) return null;
     const now = Date.now();
@@ -3005,7 +3070,7 @@ var ScheduledTaskManager = class {
    */
   async triggerTask(id) {
     await this.ensureInit();
-    const allTasks = await readJsonFile(SCHEDULED_TASKS_FILE, []);
+    const allTasks = await readJsonFileForUpdate(SCHEDULED_TASKS_FILE, []);
     const task = allTasks.find((t) => t.id === id);
     if (!task) return false;
     const memIdx = this.tasks.findIndex((t) => t.id === id);
@@ -3059,7 +3124,7 @@ var ScheduledTaskManager = class {
   async markReadBySessionId(sessionId) {
     await this.ensureInit();
     await withFileLock(SCHEDULED_TASKS_FILE, async () => {
-      const allTasks = await readJsonFile(SCHEDULED_TASKS_FILE, []);
+      const allTasks = await readJsonFileForUpdate(SCHEDULED_TASKS_FILE, []);
       let changed = false;
       for (const task of allTasks) {
         if (task.sessionId === sessionId && task.unread) {
@@ -3076,7 +3141,7 @@ var ScheduledTaskManager = class {
   async markAllRead() {
     await this.ensureInit();
     await withFileLock(SCHEDULED_TASKS_FILE, async () => {
-      const allTasks = await readJsonFile(SCHEDULED_TASKS_FILE, []);
+      const allTasks = await readJsonFileForUpdate(SCHEDULED_TASKS_FILE, []);
       let changed = false;
       for (const task of allTasks) {
         if (task.unread) {
@@ -3093,7 +3158,7 @@ var ScheduledTaskManager = class {
   async reorderTasks(orderedIds) {
     await this.ensureInit();
     await withFileLock(SCHEDULED_TASKS_FILE, async () => {
-      const allTasks = await readJsonFile(SCHEDULED_TASKS_FILE, []);
+      const allTasks = await readJsonFileForUpdate(SCHEDULED_TASKS_FILE, []);
       for (let i = 0; i < orderedIds.length; i++) {
         const task = allTasks.find((t) => t.id === orderedIds[i]);
         if (task) task.sortIndex = i;
@@ -3209,6 +3274,7 @@ var ScheduledTaskManager = class {
     }
   }
   async saveToDisk() {
+    if (this.loadFailed) return;
     try {
       await mutateJsonFile(SCHEDULED_TASKS_FILE, [], () => [...this.tasks]);
     } catch (error) {

package/dist/wsServer.mjs

@@ -13,7 +13,7 @@ import {
   resolvePendingRequest,
   unregisterBrowser,
   writeStdinToCommand
-} from "./chunk-6R4AHIIV.mjs";
+} from "./chunk-QY2K7YIF.mjs";
 import {
   Effect_exports,
   FSError,
@@ -33,7 +33,7 @@ import {
   recoverStashedCodexRollouts,
   recoverStashedTranscripts,
   sanitizedSpawnEnv
-} from "./chunk-JJWVBF6H.mjs";
+} from "./chunk-BCWVTDEZ.mjs";
 import {
   registerWatcherSubscriber,
   subscribeBuildProgress

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@surething/cockpit",
-  "version": "1.0.275",
+  "version": "1.0.276",
   "description": "OpenCockpit is the open-source Claude Code GUI — an IDE-like workbench for parallel AI coding. Drive Claude (default), Codex, DeepSeek, Kimi, or local Ollama in tabs. Terminal, browser & DB bubbles, code review. Self-host on a shared dev box — a seat for every teammate. Local-first, MIT.",
   "author": "Robert",
   "license": "MIT",
@@ -68,6 +68,7 @@
     "bin",
     "chrome-extension",
     "apps",
+    "bots",
     "!**/*.test.*",
     "!**/*.spec.*",
     "public",

package/skills/README.md

@@ -21,10 +21,17 @@ sets `COCKPIT_ROOT` to the package root), then:
    *is* the registry, for both dispatch and the `/api/commands` autocomplete
    dropdown (whose description text comes from each file's frontmatter).
 2. On dispatch the file is read, `{{BASE_URL}}` is substituted with
-   `http://localhost:<port>`, and the result is written to
+   `http://localhost:<port>` and `{{COCKPIT_DIR}}` with the resolved data
+   directory (`$COCKPIT_HOME`, default `~/.cockpit`), and the result is written to
    `~/.cockpit/skills/<cmd>/SKILL.md` — the copy the agent is pointed at, so
    builtins travel the same "read this skill file" path as user skills.
-3. A user-registered skill with the same `name` shadows the builtin.
+3. Any **other** `*.md` in `skills/<cmd>/` is copied next to it with the same
+   substitution. These are reference files, not commands — step 1 keys on
+   directories holding a `SKILL.md`, so adding one never registers a verb.
+   A SKILL.md points at `{{COCKPIT_DIR}}/skills/<cmd>/<file>.md` to defer the
+   part most invocations do not need (`bot-turn` keeps its write lock and its
+   review checklist out of every ordinary Bot turn this way).
+4. A user-registered skill with the same `name` shadows the builtin.
 
 Edits take effect on the next dispatch — no rebuild, no restart.
 
@@ -35,6 +42,9 @@ Edits take effect on the next dispatch — no rebuild, no restart.
    ```yaml
    ---
    name: <cmd>            # MUST equal the directory name
+   hidden: true           # optional — machinery, not a command to type: still
+                          # dispatchable and still read by whoever references it,
+                          # just left out of the `/` autocomplete (see bot-run)
    description: <one line — this is verbatim what the autocomplete dropdown
                  shows; it is NOT translated, and must not be given an
                  i18n commands.<cmd> key, which would silently override it>
@@ -44,6 +54,12 @@ Edits take effect on the next dispatch — no rebuild, no restart.
 
 2. Body is English prose. Use `{{BASE_URL}}` for any URL the agent must curl
    on the server host.
+
+   Split it when one part is long and rarely needed: put that part in
+   `skills/<cmd>/<file>.md` and have SKILL.md name the absolute path plus the
+   condition for opening it. Keep the *consequence* of not opening it in
+   SKILL.md — a deferred rule the model never learns it should fetch is the
+   same as a deleted one.
 3. That's it — no TypeScript to touch. Both the dropdown and the dispatcher
    pick it up from the directory.
 

package/skills/bot/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: bot
+description: "Create a Bot: a plain directory with BOT.md and long-term context, addressed as @name."
+argument-hint: "[what the Bot is for]"
+---
+
+# Creating a Bot
+
+A **Bot** is a plain directory with a `BOT.md` at its root. Once registered, a line starting with
+`@name` in any chat is handed to a session of its own, which reads `BOT.md` and uses the Bot's
+files as its long-term context. Its files change only when the user explicitly asks (remember /
+update / correct / forget), under a short write lock, so parallel sessions keep reading freely.
+
+**This skill does one thing: create a new Bot.** Everything you can do *to* an existing Bot is
+addressed to the Bot itself, not to this command — `@name review` to sweep it, `@name attach <path
+to SKILL.md>` to give it a tool, `@name export to <path>` to make a shareable copy with no memory
+in it, `@name <task>` for ordinary work. That is where those instructions live too, so they
+improve for every existing Bot at once. If the request is about a Bot that already exists, say
+which `@name` line does it and stop.
+
+**Cloning one is not an exception.** "Copy this Bot", "make me another one like it", "turn it into
+a template" all operate on a Bot that exists, so they are `@name export to <path>` — and they need
+a session that has read the whole source directory to tell a general procedure from this user's
+private memory. Say that line and stop; do not scaffold a copy from here.
+
+`curl -s {{BASE_URL}}/api/bots` lists registered Bots with their `name`, `description` and
+absolute `path` — use it to check a new name for clashes.
+
+## 1. Create: align first, write only after confirmation
+
+1. **Align on the Bot** — restate in a few lines what this Bot is for: its role, what it
+   should remember, and what it is responsible for keeping up to date. Ask back only when the
+   request is genuinely ambiguous.
+2. **Tell the name and directory** — resolve both and state them exactly:
+   - **You pick `<name>`** from the request: lowercase letters, digits and `-`, starting with a
+     letter or digit (it becomes the `@name` mention). Check it against the registry above.
+   - The user gave a directory → `<that directory>/<name>/`; none given →
+     `{{COCKPIT_DIR}}/bots/<name>/`.
+   - The target must not already exist, or must be empty. Never overwrite an existing directory.
+3. **Write only after confirmation** — once the user agrees, create the files below with
+   `Write`.
+4. **Hand over registration** — do NOT register it yourself. Tell the user the directory
+   path and the two ways to add it: open the **Bots** panel → **Add bot** and paste the path,
+   or open `BOT.md` in the file explorer and click its **Add as Bot** button.
+5. **Say what it can now be asked**, in four lines — this is the only place the user learns the
+   verbs, since `@` autocomplete shows only the description:
+   - `@<name> <task>` — ordinary work, in its own session, with its files as context
+   - `@<name> review` — a sweep for stale entries, contradictions and dangling commitments
+   - `@<name> attach <path to SKILL.md>` — teach it a tool it may use
+   - `@<name> export to <path>` — a new Bot at that path with the manual and skills but none of
+     the memory, to hand to someone else
+
+   Say them in the user's own language if they wrote in another one — each mode answers to the
+   phrasings listed at the top of its `bot-turn` file, English and Chinese alike.
+
+## 2. Layout
+
+```text
+<name>/
+├── BOT.md                  # manifest + operating manual (the subagent reads this first)
+├── identity/
+│   ├── persona.md          # stable role, voice, scope
+│   └── principles.md       # operating principles and boundaries
+├── relationships/
+│   └── user.md             # confirmed preferences of the people it works with
+├── memory/
+│   ├── facts.md            # durable, verified facts
+│   └── procedures.md       # procedures proven by successful execution
+├── projects/               # created on demand: projects/<project-name>/CONTEXT.md
+├── skills/                 # created on demand: this Bot's own SKILL.md files
+├── commitments/
+│   └── active.md           # open promises and follow-ups
+├── evidence/
+│   └── refs.md             # sources backing the entries above
+└── secrets/                # only if this Bot has credentials of its own — never read, never printed
+```
+
+Two more directories appear on their own and are never scaffolded: `.locks/` (the write lock) and
+`.reviews/` (one uniquely timestamped file per review sweep). Both are work products, never memory — nothing
+reads them as fact.
+
+Credentials belong to the tool, not to the Bot: a skill's `.env` files stay next to that skill, so
+several Bots share one copy and no key is duplicated. `<bot>/secrets/` is for the rare case where
+the credential really is this Bot's own (its own account). Either way it is gitignored when the
+directory is a repository.
+
+Seed `identity/persona.md` and `identity/principles.md` from what the user told you. Every
+other file starts as a heading plus a one-line HTML comment describing its purpose — never
+invent facts, preferences, or history.
+
+## 3. BOT.md
+
+Frontmatter is only `name` and `description` (the description is what the `@` autocomplete shows).
+
+The body says **who this Bot is** — its role, which of its files to read, which skills it has, and
+where new entries belong. It does NOT restate how a Bot turn works: reading rules, entry format,
+the write lock, the non-recording list and the reporting rules all live in the hidden `bot-turn`
+skill, which is handed to the session alongside this file. Keep it that way. Anything written here
+is copied into every Bot and frozen on the user's disk; anything in `bot-turn` is fixed once and
+every existing Bot gets the fix. Put in `BOT.md` only what would be wrong in another Bot's.
+
+````markdown
+---
+name: <name>
+description: "<one line: what this Bot knows and maintains>"
+---
+
+# <name>
+
+<one paragraph: role and scope>
+
+## Before working
+
+Read, relative to this file's directory:
+
+- identity/persona.md and identity/principles.md — always
+- relationships/user.md and commitments/active.md — always
+- memory/facts.md and memory/procedures.md — when relevant to the task
+- projects/<project-name>/CONTEXT.md — when the task concerns that project
+- the Skills table below — always; resolve and open a row's SKILL.md only when the task matches it
+
+Reading rules, entry format, when writing is allowed, the write lock and the reporting rules are
+the same for every Bot: they are in the `bot-turn` skill you were handed with this file. If you do
+not have it, say so rather than inventing a protocol — especially the write lock.
+
+## Skills
+
+| Skill | When to use | Where |
+|---|---|---|
+| <name> | <the kind of task it applies to> | <the registered skill's name, or a path relative to this directory for one of this Bot's own> |
+
+## Updating
+
+Only when the task explicitly asks to remember, update, correct or forget something (`bot-turn`
+§3–§4 covers the rest: metadata, what never gets recorded, the write lock). Where things go in
+this Bot:
+
+- a confirmed fact or a correction → memory/facts.md (mark the old entry `status: superseded` or replace it; never leave a contradiction)
+- a decision and its reason → memory/facts.md under `## Decisions`, dated
+- a user preference → relationships/user.md
+- a promise made or completed → commitments/active.md, with `done-when`, `waiting-on` and
+  `next-check` (`status: done` or `cancelled` when it ends)
+- a procedure that just worked → memory/procedures.md
+- project status changes → projects/<project-name>/CONTEXT.md, where `<project-name>` is the
+  project's name in lowercase kebab-case (by default its root directory name); reuse an existing
+  directory for the same project instead of creating a second one
+- where the information came from → evidence/refs.md
+
+<Anything that is true of THIS Bot only: a file it must never touch, a project whose CONTEXT.md
+is authoritative, a person whose word settles a question.>
+````
+
+Adapt the lists to the Bot's purpose, but keep the sections: together with `bot-turn` they are the
+only contract between the Bot and whoever runs it. Resist copying any of `bot-turn` back in here —
+a frozen copy is exactly what this split exists to prevent.