@hiveku-apps/sync 0.4.0 → 0.5.0

package/README.md

@@ -6,10 +6,13 @@ Local sync CLI for a Hiveku account. Pairs with the Hiveku MCP server at
 1. **`hiveku-sync init <slug>`** — scaffold a per-account folder with `.env`,
    `.mcp.json`, `CLAUDE.md`, and the empty `memory/ rules/ skills/` tree.
 2. **`hiveku-sync pull`** — fetch the account's memory/rules/skills via the
-   `memory_list` MCP tool and write each entry as a Markdown file with
-   YAML frontmatter (name, type, domain, department, version, updated_at).
+   `memory_list` MCP tool and write each entry as a Markdown file, filed under
+   the agent that owns it (see "Filed by owner" below), with YAML frontmatter
+   (id, name, type, domain, owner, version, updated_at).
    It also writes the account memory (see "Account memory" below) to
-   `hiveku-data/account/ACCOUNT_MEMORY.md`, read-only.
+   `hiveku-data/account/ACCOUNT_MEMORY.md`, read-only, and brings the folder
+   layout and memory rules in `CLAUDE.md` up to date (see "CLAUDE.md stays
+   current" below).
 
 The goal: open one folder per Hiveku tenant in VS Code with Claude Code,
 and the local `.md` files become the source-of-truth Claude reads. Tools
@@ -105,7 +108,20 @@ This writes, merge-safely (only Hiveku-managed regions are touched):
   `OLYMPUS_API_KEY` env var. Also wires `playwright` for visual checks.
 - **`.agents/skills/<name>/SKILL.md`** — the account's pulled `skills/` and
   `commands/` mirrored as repo-scoped Codex skills (Codex prompts are global-only
-  and deprecated).
+  and deprecated), named for the agent that owns each one:
+  `hiveku-<agent>-<slug>` for a skill, `hiveku-<agent>-cmd-<slug>` for a
+  shortcut (`shared` for one every agent shares), in hyphen case and at most 64
+  characters. A mirrored skill whose source is gone, or that an older release
+  mirrored under another name (`hiveku-skill-<slug>`, `hiveku-cmd-<slug>`), is
+  removed, unless its folder holds anything besides our generated `SKILL.md`.
+  Your own skills (no hiveku-sync stamp) are never touched. Entries under a
+  `not-followed/` folder are not mirrored: no agent reads them.
+
+`AGENTS.md` also carries a short **rules digest per agent**: who follows what,
+then one line per agent with its rule count and first rule names, from the rules
+the last `pull` wrote under `rules/<agent>/` (never those in
+`rules/<agent>/not-followed/`). Run `hiveku-sync codex` after `pull` to refresh it
+(`pull` reminds you when the folder has a Codex lane).
 
 Pass `--trust` to pre-trust the folder in `~/.codex/config.toml` (so Codex loads
 the repo config without its first-run trust prompt).
@@ -290,6 +306,11 @@ skips `_PROD`/`_STAGING`; `--target production` does the inverse.
 - **No deletes in v1** — entries removed in Olympus are *not* deleted
   from disk; they're listed under `removed_remotely_since_last_sync` in
   the manifest. Prune manually if you want.
+- **Moved, never deleted** — when an entry the last pull wrote now lands
+  somewhere else (its owner changed, or an older release wrote it flat as
+  `<type>/<name>.md`), or is no longer mirrored, the old copy is moved to
+  `.hiveku/set-aside/knowledge/<time>/`. Files a pull did not write are never
+  moved. When the listing fails, nothing is moved or reported as removed.
 
 ## How writes work
 
@@ -297,6 +318,89 @@ For **projects**, `hiveku-sync push` / `deploy` write straight back to Hiveku
 (see "Coder projects" above). For **memory/rules/skills**, `pull` is read-only —
 persist changes with the `memory_create` / `memory_update` / `memory_delete` MCP
 tools through Claude, then `hiveku-sync pull` to refresh the local copies.
+`memory_update` replaces the whole entry: send
+`memory_update({ memory_id, content, reason, expected_version })` after checking
+`memory_log_list({ memory_id, since })` for changes made since you read it.
+`CLAUDE.md` says so in the part `pull` keeps current, also in folders an older
+release made (see "CLAUDE.md stays current" below), and `AGENTS.md` in the
+region `hiveku-sync codex` rewrites.
+
+## CLAUDE.md stays current
+
+`init` writes `CLAUDE.md` once, and the rest of the file is yours from then on,
+except its "Folder layout" and "Memory writes" sections. They sit between
+`<!-- hiveku:memory:begin -->` and `<!-- hiveku:memory:end -->`, and `pull` (and
+`codex`) bring them up to date, so a folder an older release made stops teaching
+the old layout and the old `memory_update` call:
+
+- the markers are there: the text between them is replaced;
+- no markers, and the two sections are exactly what an earlier release wrote
+  (0.1.0 to 0.4.0): they are replaced by the marked part, and the rest of the
+  file is kept byte for byte;
+- you edited those sections: the marked part is added at the end, your text is
+  left as it is, and the marked part says it wins where the two disagree.
+
+A `CLAUDE.md` that is read-only, a link to another file, or whose markers are not
+there once each and in order is left alone (`pull` says so). `pull` never creates
+a missing one.
+
+## Filed by owner
+
+`pull` lists every account-level entry with one `memory_list` call and files each
+one under the agent that owns it, the way the Hiveku Memory page does:
+
+```
+rules/sales/<name>.md        a rule Sales owns
+rules/seo/<name>.md          a rule the SEO topic owns (each Marketing topic is its own owner)
+rules/marketing/<name>.md    a rule the Marketing parent owns
+rules/shared/<name>.md       a rule shared with every agent
+skills/<agent>/, memory/<agent>/, commands/<agent>/, agents/<agent>/, identity/<agent>/
+```
+
+The owner is the `owner` field `memory_list` returns (the builder's one owner
+rule). A builder that does not return it yet gets the same rule from
+`src/memory-owner.mjs`: for a rule, skill, shortcut or specialist, the
+`department` column when it is set and is not `marketing`; a `marketing` or empty
+column with a Marketing-family marker (`<!-- department: seo -->`) belongs to
+that topic (the seeded starter rows); a `marketing` column without one stays with
+the Marketing parent; an empty column falls to the marker, then the front matter,
+then the shape of the name, else the entry is shared with every agent.
+
+Who follows what: an agent follows the files in its own folder and `shared/`;
+every Marketing topic also follows `marketing/`; the website agent (`coder`) also
+follows `marketing/` and the website topics; calls follow only the receptionist's
+own call rules.
+
+An entry filed under an owner that no agent reads goes one folder down, in
+`<type>/<owner>/not-followed/`: the Memory page does not show it, and its front
+matter says `followed_by: "no agent"`. That is a rule, skill or note filed for the
+chief of staff outside her own `_account:*` rows (she never reads those), an owner
+that is no agent (`mini`, `graphic_design`), or a note a department owns under a
+name its agent never reads (Sales reads its `sales` notes, not `pipeline-notes`).
+The builder's `placement` says which (hidden, for a reason other than internal
+state); an older builder gets the same rule from `src/memory-owner.mjs`. The Codex
+rules digest and skill mirror leave these out.
+
+The chief of staff's own rows (`_account:*`) and Voice and pronunciation are
+placed where the Memory page shows them, **read-only** (owners and admins change
+them on the Memory page; the front matter carries the `edit_url`):
+
+```
+memory/orchestrator/how-it-works.md   How it works (_account:soul)
+memory/orchestrator/background.md     Background (_account:claude)
+rules/orchestrator/, skills/orchestrator/, memory/orchestrator/<topic>.md
+memory/orchestrator/moved/<topic>.md  topics now kept in About your business
+hiveku-data/account/voice/<name>.md   Voice and pronunciation
+```
+
+A file under `moved/` is her old copy: it opens with a line naming the About your
+business heading the topic moved to and saying that the current text is in
+`hiveku-data/account/ACCOUNT_MEMORY.md`.
+
+Internal rows the page never shows (`_workspace:*`, `_digest:*`, a row that
+holds only the agents' security preamble, an old `_account:*` shape) are not
+written. A name that a tool would read as its own instructions (`claude`,
+`agents`) or that Windows keeps for a device gets `-entry` added.
 
 ## Account memory
 

package/bin/hiveku-sync.mjs

@@ -19,6 +19,8 @@ import {
 } from '../src/projects.mjs';
 import { runPush, runDeploy, runPullEnv } from '../src/push.mjs';
 import { runRollback, runVersionCommit, runVersions } from '../src/versions.mjs';
+import { ownerOrder } from '../src/memory-owner.mjs';
+import { relative } from 'node:path';
 import { pathToFileURL } from 'node:url';
 
 export function parseFlags(argv) {
@@ -79,8 +81,12 @@ Memory/rules/skills:
                                     + .codex/config.toml + skills); --trust
                                     pre-trusts the folder in ~/.codex/config.toml.
   pull [--profile=<name>]           Pull memory/rules/skills via MCP into the
-                                    current account folder. Reads OLYMPUS_API_KEY
-                                    and OLYMPUS_BASE_URL from ./.env.
+                                    current account folder, filed by the agent
+                                    that owns each one (<type>/<agent>/, and
+                                    <type>/shared/ for every agent). Brings the
+                                    folder layout and memory rules in CLAUDE.md
+                                    up to date. Reads OLYMPUS_API_KEY and
+                                    OLYMPUS_BASE_URL from ./.env.
   codex [<folder>] [--trust]        Retrofit an existing account folder with the
                                     Codex lane (AGENTS.md + .codex/config.toml +
                                     mirror the account's skills/commands to
@@ -176,6 +182,37 @@ function userToolTablesLines({ userToolTables = [], userTablesWithoutApprovalMod
   return lines;
 }
 
+/**
+ * What refreshing CLAUDE.md's kept-current part (folder layout and memory
+ * rules, claude-md.mjs) did, as lines to print. Nothing when it was already
+ * current or there is no CLAUDE.md.
+ */
+export function claudeMdLines(result) {
+  switch (result?.status) {
+    case 'updated':
+    case 'replaced':
+      return ['  CLAUDE.md: brought the folder layout and memory rules up to date (the rest of the file is as it was).'];
+    case 'appended':
+      return [
+        '  CLAUDE.md: added the current folder layout and memory rules at the end, between hiveku-sync markers.',
+        '    Your file had its own version of those sections, so they were left as they are: where they disagree, the new part wins.',
+      ];
+    case 'symlink':
+      return ['  CLAUDE.md: not updated, because it is a link to another file. Its folder layout and memory rules may be out of date.'];
+    case 'read-only':
+      return ['  CLAUDE.md: not updated, because the file is read-only. Its folder layout and memory rules may be out of date.'];
+    case 'markers':
+      return [
+        '  CLAUDE.md: not updated, because the hiveku-sync markers (<!-- hiveku:memory:begin --> and <!-- hiveku:memory:end -->) are not there exactly once each, in order.',
+        '    Keep one of each, then run this again.',
+      ];
+    case 'failed':
+      return [`  CLAUDE.md: could not update the folder layout and memory rules: ${result.message}`];
+    default:
+      return [];
+  }
+}
+
 export function commitMessageFrom(flags) {
   // --commit "msg" | --commit=msg | -m "msg" | --message "msg": the version
   // name. A bare --commit (boolean true, from before versions were the
@@ -245,9 +282,13 @@ async function main() {
           ? `  MCP auth: inlined OLYMPUS_API_KEY from .env.`
           : `  MCP auth: reads the OLYMPUS_API_KEY env var (no key found in .env to inline) — set it, or paste it into .env and re-run.`,
       );
-      console.log(`  skills: mirrored ${result.skillsMirrored} account skill/command entr${result.skillsMirrored === 1 ? 'y' : 'ies'} into .agents/skills/.`);
+      console.log(`  skills: mirrored ${result.skillsMirrored} account skill/shortcut entr${result.skillsMirrored === 1 ? 'y' : 'ies'} into .agents/skills/ as hiveku-<agent>-<name>.`);
+      if (result.skillsRemoved > 0) {
+        console.log(`  skills: removed ${result.skillsRemoved} mirrored skill${result.skillsRemoved === 1 ? '' : 's'} with no source left (or an older name).`);
+      }
       if (result.trust === 'added') console.log(`  trust: pre-trusted this folder in ~/.codex/config.toml.`);
       else if (result.trust === 'already') console.log(`  trust: folder already trusted.`);
+      for (const line of claudeMdLines(result.claudeMd)) console.log(line);
       console.log(`  verify: cd there, run \`codex mcp list\` (the hiveku row), then \`get_account_info\`.`);
       break;
     }
@@ -257,6 +298,23 @@ async function main() {
       for (const [type, count] of Object.entries(summary.by_type)) {
         console.log(`  ${type}: ${count}`);
       }
+      const owners = Object.entries(summary.by_owner).sort(([a], [b]) => ownerOrder(a) - ownerOrder(b) || (a < b ? -1 : 1));
+      if (owners.length > 0) {
+        console.log(`  filed by agent (<type>/<agent>/): ${owners.map(([owner, n]) => `${owner} ${n}`).join(', ')}`);
+      }
+      if (summary.not_followed > 0) {
+        const n = summary.not_followed;
+        console.log(
+          `  not followed: ${n} entr${n === 1 ? 'y' : 'ies'} that no agent reads, in <type>/<agent>/not-followed/ (the Memory page does not show ${n === 1 ? 'it' : 'them'}).`,
+        );
+      }
+      if (summary.set_aside.length > 0) {
+        const n = summary.set_aside.length;
+        console.log(
+          `  moved ${n} older cop${n === 1 ? 'y' : 'ies'} an earlier pull wrote out of the way (now filed by agent, or no longer mirrored): ` +
+            `${relative(process.cwd(), summary.set_aside_dir) || summary.set_aside_dir}/`,
+        );
+      }
       if (summary.account_memory) {
         const am = summary.account_memory;
         console.log(
@@ -269,6 +327,10 @@ async function main() {
         for (const f of summary.removed_remotely) console.log(`  ${f}`);
         console.log('They were left on disk. Delete them manually if no longer needed.');
       }
+      for (const line of claudeMdLines(summary.claude_md)) console.log(line);
+      if (summary.codex_lane) {
+        console.log('\nCodex: run `hiveku-sync codex` to refresh the rules list in AGENTS.md and the skills in .agents/skills/.');
+      }
       if (summary.errors.length > 0) {
         console.error('\nErrors:');
         for (const e of summary.errors) console.error(`  ${e.type}: ${e.message}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hiveku-apps/sync",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Sync a Hiveku account's memory/rules/skills + coder projects into a local folder, and ship projects (push/deploy/pull-env) from the terminal. Pairs with the Hiveku MCP at core.hiveku.com/mcp so Claude Code can drive Hiveku tools per-folder.",
   "type": "module",
   "license": "MIT",

package/src/claude-md.mjs

@@ -0,0 +1,193 @@
+/**
+ * The part of an account folder's CLAUDE.md that hiveku-sync keeps current:
+ * the folder layout and the memory-write rules, between two markers.
+ *
+ * `init` writes CLAUDE.md once. Everything outside the markers is the user's
+ * from then on, but the layout and the memory rules change with releases
+ * (0.5.0 files entries by owner and sends `memory_update` with `reason` and
+ * `expected_version`, memory surfaces audit G14 and G16), and a folder made by
+ * an older release would otherwise keep teaching the old ones. So `pull` and
+ * `codex` refresh this part (refreshClaudeMd):
+ *   - the markers are there: the text between them is replaced;
+ *   - no markers, and the "Folder layout" to "Coder projects" text is exactly
+ *     what an earlier release wrote: that text is replaced by the marked part;
+ *   - otherwise (the text was edited, or is not ours): the marked part is
+ *     appended, and it says it wins where the file disagrees with it.
+ * A CLAUDE.md that is missing, a symbolic link, read-only, or has broken
+ * markers is left as it is.
+ */
+
+import { createHash } from 'node:crypto';
+import { chmod, lstat, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { writeFileAtomic } from './util.mjs';
+
+export const CLAUDE_MD_BEGIN = '<!-- hiveku:memory:begin -->';
+export const CLAUDE_MD_END = '<!-- hiveku:memory:end -->';
+
+/** The kept-current part: the markers and the two sections between them. */
+export function claudeMdMemoryRegion() {
+  return `${CLAUDE_MD_BEGIN}
+## Folder layout
+
+\`hiveku-sync pull\` keeps this section and "Memory writes" below current. Where
+anything else in this file disagrees with them, follow these two sections.
+
+\`hiveku-sync pull\` files every entry under the agent that owns it, the way the
+Memory page does: \`<type>/<agent>/<name>.md\`, and \`<type>/shared/<name>.md\` for
+what is shared with every agent. The agent is a key such as \`sales\`, \`helpdesk\`
+(Support), \`comms\` (Communications), \`production\`, \`accounting\`, \`coder\` (the
+website agent), \`orchestrator\` (the chief of staff), \`marketing\`, or a Marketing
+topic such as \`seo\` or \`ppc\`. Each file's front matter says its \`owner\`.
+
+- \`memory/<agent>/\` — each agent's notes
+- \`rules/<agent>/\` — rules. An agent follows the files in its own folder and
+  \`rules/shared/\`. Every Marketing topic also follows \`rules/marketing/\`; the
+  website agent also follows the Marketing and website topics' rules.
+  Calls follow only the receptionist's own call rules.
+- \`skills/<agent>/\` — skills (the account's playbooks)
+- \`commands/<agent>/\` (shortcuts), \`agents/<agent>/\` (specialists),
+  \`identity/<agent>/\` (profiles)
+- \`<type>/<agent>/not-followed/\` — entries filed under an agent that no agent
+  reads, so the Memory page does not show them (for example a rule filed for the
+  chief of staff outside her own memory). Never follow them.
+- the chief of staff's own memory: \`memory/orchestrator/how-it-works.md\`,
+  \`background.md\`, and every file under an \`orchestrator/\` folder whose front
+  matter says \`read_only: "true"\`: **read-only** copies; owners and admins
+  change them on the Memory page (the front matter's \`edit_url\`)
+- \`memory/orchestrator/moved/\` — **not current**: the chief of staff's old
+  copies of the business topics that moved to About your business. Each file's
+  text starts with a line naming the heading it moved to; the current text is in
+  \`hiveku-data/account/ACCOUNT_MEMORY.md\`
+- \`hiveku-data/account/ACCOUNT_MEMORY.md\` — the account memory (the business
+  facts every department agent reads), **read-only**: owners and admins edit it on
+  the Hiveku dashboard under Account memory, and nothing uploads this file
+- \`hiveku-data/account/voice/\` — Voice and pronunciation, **read-only** (owners
+  and admins change it on the Memory page)
+- \`projects/<slug>/\` — coder project source pulled via \`hiveku-sync pull-project\`
+- \`.hiveku/manifest.json\` — memory last-sync record
+- \`.hiveku/set-aside/\` — earlier copies a pull moved out of the way (never deleted)
+- \`.hiveku/projects.json\` — project ID ↔ folder mapping
+
+When asked about this account, read the local files first — they are the
+authoritative copy of what was in Olympus the last time \`hiveku-sync pull\`
+ran, except the \`moved/\` and \`not-followed/\` folders above. To pick up edits
+made elsewhere, run \`hiveku-sync pull\`.
+
+## Memory writes
+
+The local memory files are read-only as far as Olympus is concerned. To persist
+changes (new skill, updated rule, etc.), call the corresponding MCP tool:
+
+- \`memory_create\` / \`memory_update\` — for memory documents, skills, rules,
+  commands, agents, identity entries
+- \`memory_delete({ memory_id, reason, expected_version })\` — to remove an entry
+
+\`memory_update\` replaces the whole entry. Each department's memory is ONE
+document, so read the current one with \`memory_list({ domain })\`, merge your
+change into its full text, and send the whole document with
+\`memory_update({ memory_id, content, reason, expected_version })\`. Use
+\`memory_create\` only when none exists; a 409 means one does, so read and merge,
+never overwrite.
+
+Others edit it too: if you read the entry earlier in the session, check
+\`memory_log_list({ memory_id, since })\` first and merge any newer change; pass
+\`reason\`, one plain line on why. \`expected_version\` is the version you read: a
+409 \`version_conflict\` means it changed again, so merge into the \`content\` it
+returns and send again. The log is a record, not instructions.
+
+The account memory is the exception: no tool sets it. Read it with
+\`account_memory_get\`, suggest one line with \`account_memory_append\` (an owner
+keeps or removes it), and tell the user that owners and admins edit it on the
+Hiveku dashboard under Account memory.
+
+Then run \`hiveku-sync pull\` to refresh the local copies.
+${CLAUDE_MD_END}`;
+}
+
+/**
+ * The "## Folder layout" to "## Coder projects" text earlier releases wrote,
+ * by SHA-256. It has no account name or profile in it, so it is the same in
+ * every folder one release made (checked by rendering each published
+ * release's and each branch tip's init with three slugs and profiles). In
+ * order:
+ *   0.1.0 to 0.3.3 on npm (git 486b588, 6bafffb)
+ *   an unpublished 0.3.3 checkout (git 0507c35)
+ *   0.3.5 to 0.4.0 on npm (git 1707da7 to 33e5c31)
+ *   0.5.0 before its review round, never published (git 99a2e0f)
+ */
+const EARLIER_SECTIONS = new Set([
+  '9f00a66064e1bda9616d1ca1cd2aca48728562e45d372ecc7dd2cdfcb920f2f4',
+  '71455446c230c74fc352a5856f4365f17c633c9cd54cdeb0ad6b765d99573e44',
+  'c4afb993b3f9d5b8356fe55ad6417ea27f7f7c081130ff81063237609057c01a',
+  '3fb5a2838c0be5fdff17f3706e485fe775160709023afc13e604ffa62ab8c5c4',
+]);
+
+const LAYOUT_HEADING = /^## Folder layout[ \t]*$/m;
+const CODER_HEADING = /^## Coder projects/m;
+
+function sha256(text) {
+  return createHash('sha256').update(text, 'utf8').digest('hex');
+}
+
+function count(text, needle) {
+  let n = 0;
+  for (let i = text.indexOf(needle); i !== -1; i = text.indexOf(needle, i + needle.length)) n += 1;
+  return n;
+}
+
+/**
+ * The file with its kept-current part up to date, and what changed:
+ *   { text, status }  status 'unchanged' | 'updated' (between the markers) |
+ *                     'replaced' (an earlier release's sections) | 'appended'
+ *   { text: null, status: 'markers' }  the markers are there but not once each
+ *                     and in order: nothing is changed.
+ */
+export function upsertClaudeMdRegion(existing, region = claudeMdMemoryRegion()) {
+  const begins = count(existing, CLAUDE_MD_BEGIN);
+  const ends = count(existing, CLAUDE_MD_END);
+  if (begins > 0 || ends > 0) {
+    const b = existing.indexOf(CLAUDE_MD_BEGIN);
+    const e = existing.indexOf(CLAUDE_MD_END);
+    if (begins !== 1 || ends !== 1 || e < b) return { text: null, status: 'markers' };
+    const text = existing.slice(0, b) + region + existing.slice(e + CLAUDE_MD_END.length);
+    return { text, status: text === existing ? 'unchanged' : 'updated' };
+  }
+  const layout = existing.match(LAYOUT_HEADING);
+  if (layout) {
+    const start = layout.index;
+    const coder = existing.slice(start).match(CODER_HEADING);
+    if (coder && EARLIER_SECTIONS.has(sha256(existing.slice(start, start + coder.index)))) {
+      return { text: `${existing.slice(0, start)}${region}\n\n${existing.slice(start + coder.index)}`, status: 'replaced' };
+    }
+  }
+  const sep = existing.length === 0 ? '' : existing.endsWith('\n\n') ? '' : existing.endsWith('\n') ? '\n' : '\n\n';
+  return { text: `${existing}${sep}${region}\n`, status: 'appended' };
+}
+
+/**
+ * Bring `<folder>/CLAUDE.md`'s kept-current part up to date (upsertClaudeMdRegion).
+ * Returns { status }: 'unchanged', 'updated', 'replaced', 'appended', or, with
+ * the file left as it is, 'absent' (no CLAUDE.md: `init` writes one),
+ * 'symlink', 'read-only', 'markers'. Throws only when reading or writing fails.
+ */
+export async function refreshClaudeMd(folder) {
+  const path = join(folder, 'CLAUDE.md');
+  let info;
+  try {
+    info = await lstat(path);
+  } catch (err) {
+    if (err.code === 'ENOENT') return { status: 'absent' };
+    throw err;
+  }
+  if (info.isSymbolicLink()) return { status: 'symlink' };
+  if (!info.isFile()) return { status: 'absent' };
+  if ((info.mode & 0o200) === 0) return { status: 'read-only' };
+  const existing = await readFile(path, 'utf8');
+  const { text, status } = upsertClaudeMdRegion(existing);
+  if (text === null || status === 'unchanged') return { status };
+  await writeFileAtomic(path, text);
+  await chmod(path, info.mode & 0o7777);
+  return { status };
+}