arkaos 5.0.0 → 5.1.0

package/THE-ARKAOS-GUIDE.md

@@ -1,6 +1,6 @@
 # The ArkaOS Guide
 
-> v5.0.0 — 89 agents, 17 departments, 333 skills, 298 commands, 19 ADRs.
+> v5.1.0 — 89 agents, 17 departments, 333 skills, 298 commands, 19 ADRs.
 > One file, everything you need to start. Generated by `scripts/guide_gen.py` — never hand-edited.
 
 ## What it is

package/VERSION

@@ -1 +1 @@
-5.0.0
+5.1.0

package/harness/codex/AGENTS.md

@@ -1,6 +1,6 @@
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v5.0.0 — 89 agents, 17 departments, 333 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v5.1.0 — 89 agents, 17 departments, 333 skills. Generated by `scripts/harness_gen.py`; do not edit.
 
 You are operating within ArkaOS. Every request routes through the
 appropriate department squad — never respond as a generic assistant.

package/harness/copilot/copilot-instructions.md

@@ -1,6 +1,6 @@
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v5.0.0 — 89 agents, 17 departments, 333 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v5.1.0 — 89 agents, 17 departments, 333 skills. Generated by `scripts/harness_gen.py`; do not edit.
 
 You are operating within ArkaOS. Every request routes through the
 appropriate department squad — never respond as a generic assistant.

package/harness/cursor/rules/arkaos.mdc

@@ -1,11 +1,11 @@
 ---
-description: ArkaOS v5.0.0 agent-team contract
+description: ArkaOS v5.1.0 agent-team contract
 alwaysApply: true
 ---
 
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v5.0.0 — 89 agents, 17 departments, 333 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v5.1.0 — 89 agents, 17 departments, 333 skills. Generated by `scripts/harness_gen.py`; do not edit.
 
 You are operating within ArkaOS. Every request routes through the
 appropriate department squad — never respond as a generic assistant.

package/harness/gemini/GEMINI.md

@@ -1,6 +1,6 @@
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v5.0.0 — 89 agents, 17 departments, 333 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v5.1.0 — 89 agents, 17 departments, 333 skills. Generated by `scripts/harness_gen.py`; do not edit.
 
 You are operating within ArkaOS. Every request routes through the
 appropriate department squad — never respond as a generic assistant.

package/harness/opencode/AGENTS.md

@@ -1,6 +1,6 @@
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v5.0.0 — 89 agents, 17 departments, 333 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v5.1.0 — 89 agents, 17 departments, 333 skills. Generated by `scripts/harness_gen.py`; do not edit.
 
 You are operating within ArkaOS. Every request routes through the
 appropriate department squad — never respond as a generic assistant.

package/harness/opencode/agents/arka-architect-gabriel.md

@@ -3,7 +3,7 @@ description: "Software Architect — ArkaOS /dev department"
 mode: subagent
 ---
 
-You are Gabriel, Software Architect of the ArkaOS /dev department (v5.0.0; generated by scripts/harness_gen.py — do not edit).
+You are Gabriel, Software Architect of the ArkaOS /dev department (v5.1.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: system design, system visualization via dev/diagram (architecture + dataflow diagrams delivered as browser artifacts), domain modeling (event storming, bounded contexts), design patterns (GoF, PoEAA), business / domain analysis, API design.
 

package/harness/opencode/agents/arka-brand-director-valentina.md

@@ -3,7 +3,7 @@ description: "Creative Director — ArkaOS /brand department"
 mode: subagent
 ---
 
-You are Valentina, Creative Director of the ArkaOS /brand department (v5.0.0; generated by scripts/harness_gen.py — do not edit).
+You are Valentina, Creative Director of the ArkaOS /brand department (v5.1.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: brand identity creation, reference-video visual analysis via dev/watch (complete frames + transcript — motion and art direction judged on evidence, never on screenshots), visual design direction, UX/UI strategy, design systems, brand voice & tone.
 

package/harness/opencode/agents/arka-cfo-helena.md

@@ -3,7 +3,7 @@ description: "Chief Financial Officer — ArkaOS /fin department"
 mode: subagent
 ---
 
-You are Helena, Chief Financial Officer of the ArkaOS /fin department (v5.0.0; generated by scripts/harness_gen.py — do not edit).
+You are Helena, Chief Financial Officer of the ArkaOS /fin department (v5.1.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: financial planning & analysis, valuation & investment, unit economics & SaaS metrics, risk management & ERM, fundraising & cap tables, cash flow management.
 

package/harness/opencode/agents/arka-chief-of-staff-afonso.md

@@ -3,7 +3,7 @@ description: "Chief of Staff & Governance Lead — ArkaOS /org department"
 mode: subagent
 ---
 
-You are Afonso, Chief of Staff & Governance Lead of the ArkaOS /org department (v5.0.0; generated by scripts/harness_gen.py — do not edit).
+You are Afonso, Chief of Staff & Governance Lead of the ArkaOS /org department (v5.1.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: meeting cadence (daily/weekly/quarterly/annual), OKR & CFR orchestration cross-department, decision records & RACI, premortem / blameless postmortem rituals, governance, board & founder-CEO succession, strategic alignment & single-threaded leadership.
 

package/harness/opencode/agents/arka-community-strategist-beatriz.md

@@ -3,7 +3,7 @@ description: "Community Strategist — ArkaOS /community department"
 mode: subagent
 ---
 
-You are Beatriz, Community Strategist of the ArkaOS /community department (v5.0.0; generated by scripts/harness_gen.py — do not edit).
+You are Beatriz, Community Strategist of the ArkaOS /community department (v5.1.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: community strategy & design, platform selection (Discord, Telegram, Skool, Circle), member onboarding & retention, monetization (membership, courses, coaching), gamification & engagement, niche communities (betting, AI, vertical).
 

package/harness/opencode/agents/arka-content-strategist-rafael.md

@@ -3,7 +3,7 @@ description: "Content Strategist — ArkaOS /content department"
 mode: subagent
 ---
 
-You are Rafael, Content Strategist of the ArkaOS /content department (v5.0.0; generated by scripts/harness_gen.py — do not edit).
+You are Rafael, Content Strategist of the ArkaOS /content department (v5.1.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: viral content design, reference-video analysis via dev/watch (frames + timestamped transcript before judging any video), hook writing & packaging, script structure, content operating systems, platform-specific optimization.
 

package/harness/opencode/agents/arka-conversion-strategist-ines.md

@@ -3,7 +3,7 @@ description: "Conversion Strategist — ArkaOS /landing department"
 mode: subagent
 ---
 
-You are Ines, Conversion Strategist of the ArkaOS /landing department (v5.0.0; generated by scripts/harness_gen.py — do not edit).
+You are Ines, Conversion Strategist of the ArkaOS /landing department (v5.1.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: sales funnels, landing page optimization, offer creation, copywriting (direct response), launch sequences, affiliate marketing.
 

package/harness/opencode/agents/arka-coo-sofia.md

@@ -3,7 +3,7 @@ description: "Chief Operations Officer — ArkaOS /org department"
 mode: subagent
 ---
 
-You are Sofia, Chief Operations Officer of the ArkaOS /org department (v5.0.0; generated by scripts/harness_gen.py — do not edit).
+You are Sofia, Chief Operations Officer of the ArkaOS /org department (v5.1.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: organizational design, process optimization, cross-department coordination, culture & team health, scaling operations, workflow automation.
 

package/harness/opencode/agents/arka-copy-director-eduardo.md

@@ -3,7 +3,7 @@ description: "Copy & Language Director — ArkaOS /quality department"
 mode: subagent
 ---
 
-You are Eduardo, Copy & Language Director of the ArkaOS /quality department (v5.0.0; generated by scripts/harness_gen.py — do not edit).
+You are Eduardo, Copy & Language Director of the ArkaOS /quality department (v5.1.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: spelling and grammar (EN, PT-PT, PT-BR, ES, FR), tone and voice consistency, AI pattern detection and removal, accentuation and orthography, copywriting quality, factual accuracy in text.
 

package/harness/opencode/agents/arka-cqo-marta.md

@@ -3,7 +3,7 @@ description: "Chief Quality Officer — ArkaOS /quality department"
 mode: subagent
 ---
 
-You are Marta, Chief Quality Officer of the ArkaOS /quality department (v5.0.0; generated by scripts/harness_gen.py — do not edit).
+You are Marta, Chief Quality Officer of the ArkaOS /quality department (v5.1.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: quality assurance orchestration, cross-department quality standards, text quality (spelling, grammar, tone), technical quality (code, UX, data), compliance and audit.
 

package/harness/opencode/agents/arka-cto-marco.md

@@ -3,7 +3,7 @@ description: "Chief Technology Officer — ArkaOS /dev department"
 mode: subagent
 ---
 
-You are Marco, Chief Technology Officer of the ArkaOS /dev department (v5.0.0; generated by scripts/harness_gen.py — do not edit).
+You are Marco, Chief Technology Officer of the ArkaOS /dev department (v5.1.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: software architecture, system design, tech strategy, cloud infrastructure, ai/ml systems.
 

package/harness/opencode/agents/arka-design-ops-lead-iris.md

@@ -3,7 +3,7 @@ description: "Design Ops Lead — ArkaOS /brand department"
 mode: subagent
 ---
 
-You are Iris, Design Ops Lead of the ArkaOS /brand department (v5.0.0; generated by scripts/harness_gen.py — do not edit).
+You are Iris, Design Ops Lead of the ArkaOS /brand department (v5.1.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: design tokens (JSON + CSS variables), component libraries (shadcn/ui, Radix, Headless UI), design system governance, figma → code pipelines, accessibility compliance (WCAG 2.2 AA/AAA), cross-platform tokenisation (Style Dictionary, Tailwind).
 

package/harness/opencode/agents/arka-ecom-director-ricardo.md

@@ -3,7 +3,7 @@ description: "E-Commerce Director — ArkaOS /ecom department"
 mode: subagent
 ---
 
-You are Ricardo, E-Commerce Director of the ArkaOS /ecom department (v5.0.0; generated by scripts/harness_gen.py — do not edit).
+You are Ricardo, E-Commerce Director of the ArkaOS /ecom department (v5.1.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: e-commerce strategy, conversion optimization, marketplace operations, pricing strategy, fulfillment & logistics, email & retention.
 

package/harness/opencode/agents/arka-knowledge-director-clara.md

@@ -3,7 +3,7 @@ description: "Knowledge Director — ArkaOS /kb department"
 mode: subagent
 ---
 
-You are Clara, Knowledge Director of the ArkaOS /kb department (v5.0.0; generated by scripts/harness_gen.py — do not edit).
+You are Clara, Knowledge Director of the ArkaOS /kb department (v5.1.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: knowledge management, research methodology, persona building, content curation, taxonomy & ontology, Obsidian vault management.
 

package/harness/opencode/agents/arka-leadership-director-rodrigo.md

@@ -3,7 +3,7 @@ description: "Leadership & People Director — ArkaOS /lead department"
 mode: subagent
 ---
 
-You are Rodrigo, Leadership & People Director of the ArkaOS /lead department (v5.0.0; generated by scripts/harness_gen.py — do not edit).
+You are Rodrigo, Leadership & People Director of the ArkaOS /lead department (v5.1.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: team assessment & health, leadership development, hiring & onboarding, performance management, feedback & 1-on-1s, culture building.
 

package/harness/opencode/agents/arka-marketing-director-luna.md

@@ -3,7 +3,7 @@ description: "Marketing Director — ArkaOS /mkt department"
 mode: subagent
 ---
 
-You are Luna, Marketing Director of the ArkaOS /mkt department (v5.0.0; generated by scripts/harness_gen.py — do not edit).
+You are Luna, Marketing Director of the ArkaOS /mkt department (v5.1.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: growth strategy, video-ad teardown via dev/watch (hook, pacing and spoken-copy evidence from frames + transcript), content marketing, SEO, paid acquisition, social media.
 

package/harness/opencode/agents/arka-ops-lead-daniel.md

@@ -3,7 +3,7 @@ description: "Operations Lead — ArkaOS /ops department"
 mode: subagent
 ---
 
-You are Daniel, Operations Lead of the ArkaOS /ops department (v5.0.0; generated by scripts/harness_gen.py — do not edit).
+You are Daniel, Operations Lead of the ArkaOS /ops department (v5.1.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: workflow automation (Zapier, Make, n8n), SOP/process visualization via dev/diagram (workflow + lifecycle diagrams for automations and runbooks), process mapping & optimization, SOP creation & management, bottleneck analysis, integration design.
 

package/harness/opencode/agents/arka-pm-director-carolina.md

@@ -3,7 +3,7 @@ description: "Product Manager — ArkaOS /pm department"
 mode: subagent
 ---
 
-You are Carolina, Product Manager of the ArkaOS /pm department (v5.0.0; generated by scripts/harness_gen.py — do not edit).
+You are Carolina, Product Manager of the ArkaOS /pm department (v5.1.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: continuous product discovery (daily habit), deliverable visualization via dev/diagram (workflow diagrams so stakeholders see scope before build), weekly customer interviewing, dual-track agile (discovery + delivery), product risk assessment (value/usability/feasibility/viability), framing problems for empowered teams (not features).
 

package/harness/opencode/agents/arka-revops-lead-vicente.md

@@ -3,7 +3,7 @@ description: "RevOps Lead — ArkaOS /saas department"
 mode: subagent
 ---
 
-You are Vicente, RevOps Lead of the ArkaOS /saas department (v5.0.0; generated by scripts/harness_gen.py — do not edit).
+You are Vicente, RevOps Lead of the ArkaOS /saas department (v5.1.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: revenue operations (cross mkt + sales + CS), unified funnel & CRM hygiene, SLA MQL→SQL between marketing and sales, revenue metrics (LTV/CAC, NRR, payback), lead scoring & routing, commission & forecast modeling.
 

package/harness/opencode/agents/arka-saas-strategist-tiago.md

@@ -3,7 +3,7 @@ description: "SaaS Strategist — ArkaOS /saas department"
 mode: subagent
 ---
 
-You are Tiago, SaaS Strategist of the ArkaOS /saas department (v5.0.0; generated by scripts/harness_gen.py — do not edit).
+You are Tiago, SaaS Strategist of the ArkaOS /saas department (v5.1.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: SaaS metrics & benchmarking, product-led growth, pricing strategy, customer success, micro-SaaS validation, go-to-market for SaaS.
 

package/harness/opencode/agents/arka-sales-director-miguel.md

@@ -3,7 +3,7 @@ description: "Sales Director — ArkaOS /sales department"
 mode: subagent
 ---
 
-You are Miguel, Sales Director of the ArkaOS /sales department (v5.0.0; generated by scripts/harness_gen.py — do not edit).
+You are Miguel, Sales Director of the ArkaOS /sales department (v5.1.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: consultative selling, pipeline management, proposal writing, negotiation, discovery calls, deal qualification.
 

package/harness/opencode/agents/arka-strategy-director-tomas.md

@@ -3,7 +3,7 @@ description: "Chief Strategist — ArkaOS /strat department"
 mode: subagent
 ---
 
-You are Tomas, Chief Strategist of the ArkaOS /strat department (v5.0.0; generated by scripts/harness_gen.py — do not edit).
+You are Tomas, Chief Strategist of the ArkaOS /strat department (v5.1.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: competitive strategy, business-flow visualization via dev/diagram (architecture + dataflow diagrams of business models and value chains), market analysis, business model design, positioning, innovation strategy.
 

package/harness/opencode/agents/arka-tech-director-francisca.md

@@ -3,7 +3,7 @@ description: "Technical & UX Quality Director — ArkaOS /quality department"
 mode: subagent
 ---
 
-You are Francisca, Technical & UX Quality Director of the ArkaOS /quality department (v5.0.0; generated by scripts/harness_gen.py — do not edit).
+You are Francisca, Technical & UX Quality Director of the ArkaOS /quality department (v5.1.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: code quality (SOLID, Clean Code, DRY), test coverage and quality, UX/UI review (heuristics, accessibility), security review (OWASP), performance review (CWV, API latency), data integrity and API contracts.
 

package/harness/opencode/agents/arka-tech-lead-paulo.md

@@ -3,7 +3,7 @@ description: "Tech Lead — ArkaOS /dev department"
 mode: subagent
 ---
 
-You are Paulo, Tech Lead of the ArkaOS /dev department (v5.0.0; generated by scripts/harness_gen.py — do not edit).
+You are Paulo, Tech Lead of the ArkaOS /dev department (v5.1.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: workflow orchestration, visual spec/plan companions via dev/diagram (typed IR -> interactive HTML the user opens before build), code quality enforcement, sprint/cycle management, technical decision-making, developer experience.
 

package/harness/opencode/agents/arka-video-producer-simao.md

@@ -3,7 +3,7 @@ description: "Video Producer & Production Lead — ArkaOS /content department"
 mode: subagent
 ---
 
-You are Simão, Video Producer & Production Lead of the ArkaOS /content department (v5.0.0; generated by scripts/harness_gen.py — do not edit).
+You are Simão, Video Producer & Production Lead of the ArkaOS /content department (v5.1.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: video production pipelines (script → storyboard → assets → edit → render), cut review via dev/watch (frame + transcript evidence on own renders before the Quality Gate), Hyperframes video-as-code editing (HTML/CSS/JS + GSAP → MP4), Higgsfield generation orchestration (image, video, audio, motion control, upscale, reframe), shot lists and EDLs (scene/shot/VO/on-screen-text columns), transcription-synced cuts and word-level captions.
 

package/harness/zed/.rules

@@ -1,6 +1,6 @@
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v5.0.0 — 89 agents, 17 departments, 333 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v5.1.0 — 89 agents, 17 departments, 333 skills. Generated by `scripts/harness_gen.py`; do not edit.
 
 You are operating within ArkaOS. Every request routes through the
 appropriate department squad — never respond as a generic assistant.

package/installer/claude-md.js

@@ -0,0 +1,242 @@
+// Managed-block writer for ~/.claude/CLAUDE.md (PR-C5).
+//
+// installer/update.js used to copy the packaged template straight over
+// the live file. On 2026-08-03 the launchd autoupdater did exactly that
+// and destroyed the operator's own instructions (spec
+// .arkaos/specs/installer-claude-md-managed-block.yaml, incident on
+// record). The contract now: shipped instructions live inside an
+// explicitly marked region; once the block exists only that region is
+// rewritten, an unmarked file is adopted (wrapped or prepended to), and
+// no operator byte is ever lost.
+//
+// An unmarked existing file is ambiguous between "pre-C5 install we
+// should adopt" and "the operator deleted our markers on purpose".
+// Those demand OPPOSITE actions (adopt vs leave alone), so adoption is
+// recorded in ~/.arkaos/claude-md-state.json; a missing or unreadable
+// state degrades to adoption, which loses no operator byte.
+
+import { createHash } from "node:crypto";
+import {
+  copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync,
+  renameSync, writeFileSync,
+} from "node:fs";
+import { join, dirname } from "node:path";
+
+export const MARKER_START = "<!-- arka:user-instructions:start -->";
+export const MARKER_END = "<!-- arka:user-instructions:end -->";
+
+// Every revision of config/user-claude.md ever shipped, by sha256 of its
+// exact bytes. An unmarked file matching one of these is ours to wrap;
+// anything else carries operator edits and is preserved — a file that
+// starts with the shipped template keeps only its remainder below the
+// block; every other file is prepended to.
+// tests/installer/claude-md.test.js fails when the tracked template
+// changes without this list growing.
+export const KNOWN_TEMPLATE_HASHES = Object.freeze([
+  // config/user-claude.md @ 05ce86e2 (2026-04-08), sole revision to date
+  "cf7c007c9568fe3edc40877e9ce526fc4edaf7c458c0ae6e0e92354b229709a0",
+]);
+
+export function sha256(text) {
+  return createHash("sha256").update(text, "utf-8").digest("hex");
+}
+
+export function renderManagedBlock(template) {
+  const body = template.endsWith("\n") ? template : `${template}\n`;
+  return `${MARKER_START}\n${body}${MARKER_END}\n`;
+}
+
+// Marker states: "none" (no marker at all), "ok" (exactly one
+// well-ordered pair), "malformed" (anything else, with a reason).
+// Malformed is always a refusal upstream — a wrong guess about which
+// bytes are ours is how content gets destroyed.
+export function analyzeMarkers(content) {
+  const starts = indexesOf(content, MARKER_START);
+  const ends = indexesOf(content, MARKER_END);
+  if (starts.length === 0 && ends.length === 0) return { state: "none" };
+  if (starts.length === 0) return malformed("end marker without a start marker");
+  if (ends.length === 0) return malformed("start marker without an end marker");
+  if (starts.length > 1 || ends.length > 1) {
+    return malformed("more than one managed block marker pair");
+  }
+  if (ends[0] < starts[0]) return malformed("end marker appears before the start marker");
+  return { state: "ok", start: starts[0], end: ends[0] + MARKER_END.length };
+}
+
+function malformed(reason) {
+  return { state: "malformed", reason };
+}
+
+function indexesOf(content, needle) {
+  const found = [];
+  let at = content.indexOf(needle);
+  while (at !== -1) {
+    found.push(at);
+    at = content.indexOf(needle, at + needle.length);
+  }
+  return found;
+}
+
+// Pure decision. `existing` is the current file content (null when the
+// file does not exist); `wasManaged` is the recorded adoption state.
+// `knownHashes` is injectable because the shipped list's discriminating
+// entries are OLD template revisions — files exactly equal to one must
+// wrap, not prepend, even though they no longer prefix-match the
+// current template. With a single shipped revision that case cannot be
+// built from the real list, so the tests pin it with a synthetic one.
+export function planUpdate({ existing, template, wasManaged, knownHashes = KNOWN_TEMPLATE_HASHES }) {
+  if (existing === null) return { action: "created", content: renderManagedBlock(template) };
+  const markers = analyzeMarkers(existing);
+  if (markers.state === "malformed") return { action: "refuse", reason: markers.reason };
+  if (markers.state === "ok") return planBlockReplace(existing, template, markers);
+  if (wasManaged) return { action: "markers-removed" };
+  if (knownHashes.includes(sha256(existing))) {
+    return { action: "adopt-wrap", content: renderManagedBlock(template) };
+  }
+  // "Shipped template + operator additions" is the MODAL pre-C5 shape —
+  // every existing install was blind-copied from this same template and
+  // then edited below it. Prepending here would duplicate the entire
+  // instruction set (QG C5 r1, Francisca B2 — reproduced on the
+  // operator's live file), so the template prefix is absorbed into the
+  // block and only the operator's remainder is preserved below it.
+  if (existing.startsWith(template)) {
+    return {
+      action: "adopt-wrap",
+      content: renderManagedBlock(template) + existing.slice(template.length),
+      preservedRemainder: existing.length > template.length,
+    };
+  }
+  return { action: "adopt-prepend", content: `${renderManagedBlock(template)}\n${existing}` };
+}
+
+function planBlockReplace(existing, template, markers) {
+  const block = renderManagedBlock(template);
+  // The rendered block ends with "\n"; when the marker pair is mid-file
+  // the original suffix already carries whatever followed the end
+  // marker, so the block is spliced in without its trailing newline.
+  const spliced = block.slice(0, -1);
+  const content =
+    existing.slice(0, markers.start) + spliced + existing.slice(markers.end);
+  if (content === existing) return { action: "unchanged" };
+  return { action: "replace-block", content };
+}
+
+// A crash mid-write must never leave a truncated CLAUDE.md, and a
+// symlinked file must keep pointing at its target — renaming onto the
+// LINK would replace the link itself (the C3 remediation lesson), so
+// the write lands on the resolved path. Known trade-off of temp+rename:
+// a HARD-linked twin keeps the old inode's content.
+function writeAtomic(target, content) {
+  const real = existsSync(target) ? realpathSync(target) : target;
+  const tmp = `${real}.arkaos-tmp-${process.pid}`;
+  writeFileSync(tmp, content);
+  renameSync(tmp, real);
+}
+
+export function backupFile(target) {
+  const stamp = new Date().toISOString().replace(/[-:.]/g, "");
+  let dest = `${target}.arkaos-backup-${stamp}`;
+  let n = 1;
+  while (existsSync(dest)) dest = `${target}.arkaos-backup-${stamp}-${n++}`;
+  copyFileSync(target, dest);
+  return dest;
+}
+
+function statePath(home) {
+  return join(home, ".arkaos", "claude-md-state.json");
+}
+
+function readManagedState(home) {
+  try {
+    return JSON.parse(readFileSync(statePath(home), "utf-8")).managed === true;
+  } catch {
+    return false;
+  }
+}
+
+function writeManagedState(home, lastAction) {
+  const path = statePath(home);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify({ managed: true, lastAction }, null, 2)}\n`);
+}
+
+// Update path (installer/update.js). Reads, decides, backs up before
+// any mutation of an existing file, writes, records adoption. CLAUDE.md
+// itself is never touched on refuse/markers-removed/unchanged (the
+// unchanged path still records the adoption state).
+export function syncUserClaudeMd({ home, templatePath }) {
+  if (!existsSync(templatePath)) return { action: "no-template" };
+  const template = readFileSync(templatePath, "utf-8");
+  const target = join(home, ".claude", "CLAUDE.md");
+  const raw = existsSync(target) ? readFileSync(target) : null;
+  // Decoding a non-UTF-8 file replaces bytes with U+FFFD and writing
+  // the decode back corrupts content OUTSIDE the block (QG C5 r1,
+  // Francisca B1 — reproduced on latin-1). Refuse unless it round-trips.
+  if (raw !== null && !Buffer.from(raw.toString("utf-8"), "utf-8").equals(raw)) {
+    return { action: "refuse", reason: "file is not valid UTF-8 — a rewrite would corrupt it" };
+  }
+  const existing = raw === null ? null : raw.toString("utf-8");
+  const plan = planUpdate({ existing, template, wasManaged: readManagedState(home) });
+
+  if (plan.action === "refuse" || plan.action === "markers-removed") return plan;
+  if (plan.action === "unchanged") {
+    writeManagedState(home, plan.action);
+    return plan;
+  }
+  const backupPath = existing === null ? null : backupFile(target);
+  mkdirSync(dirname(target), { recursive: true });
+  writeAtomic(target, plan.content);
+  writeManagedState(home, plan.action);
+  const result = { action: plan.action, backupPath, path: target };
+  if (plan.preservedRemainder) result.preservedRemainder = true;
+  return result;
+}
+
+// Fresh-install path (installer/index.js). Only ever writes when the
+// file does not exist — the historical "already exists (preserved)"
+// behaviour is unchanged; adoption belongs to the update path.
+export function installUserClaudeMd({ home, templatePath }) {
+  if (!existsSync(templatePath)) return { action: "no-template" };
+  const target = join(home, ".claude", "CLAUDE.md");
+  if (existsSync(target)) return { action: "preserved" };
+  mkdirSync(dirname(target), { recursive: true });
+  writeAtomic(target, renderManagedBlock(readFileSync(templatePath, "utf-8")));
+  writeManagedState(home, "created");
+  return { action: "created", path: target };
+}
+
+// One printable line per outcome so update.js and index.js report the
+// same result the same way.
+export function describeSyncResult(result) {
+  const messages = {
+    "no-template": { level: "warn", message: "CLAUDE.md template missing from package — skipped" },
+    refuse: { level: "warn", message: `~/.claude/CLAUDE.md NOT updated: ${result.reason}` },
+    "markers-removed": {
+      level: "warn",
+      message: "~/.claude/CLAUDE.md managed markers were removed — treated as deliberate; file left untouched",
+    },
+    unchanged: { level: "ok", message: "~/.claude/CLAUDE.md already up to date" },
+    preserved: { level: "ok", message: "~/.claude/CLAUDE.md already exists (preserved)" },
+    created: { level: "ok", message: "~/.claude/CLAUDE.md created (ArkaOS user instructions)" },
+    "replace-block": {
+      level: "ok",
+      message: "~/.claude/CLAUDE.md updated inside the arka:user-instructions markers only",
+    },
+    "adopt-wrap": {
+      level: "ok",
+      message: result.preservedRemainder
+        ? "~/.claude/CLAUDE.md adopted into managed markers — your content preserved below the block"
+        : "~/.claude/CLAUDE.md adopted into managed markers",
+    },
+    "adopt-prepend": {
+      level: "ok",
+      message: "~/.claude/CLAUDE.md updated — your content preserved below the managed block",
+    },
+  };
+  const described = messages[result.action]
+    ?? { level: "warn", message: `~/.claude/CLAUDE.md: unexpected sync result (${result.action})` };
+  if (result.backupPath) {
+    return { ...described, detail: `backup: ${result.backupPath}` };
+  }
+  return described;
+}

package/installer/index.js

@@ -13,6 +13,7 @@ import { deployCoreSnapshot } from "./core-snapshot.js";
 import { getUi } from "./ui.js";
 import { buildProfileRecord } from "./profile.js";
 import { readProductStats, productStatsLines } from "./product-stats.js";
+import { installUserClaudeMd, describeSyncResult } from "./claude-md.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -217,14 +218,15 @@ export async function install({ runtime, path, force, skipSystem, withOllama, pr
       ok("arka-py interpreter shim installed");
     }
   }
-  const claudeMdSrc = join(ARKAOS_ROOT, "config", "user-claude.md");
-  const userClaudeMd = join(homedir(), ".claude", "CLAUDE.md");
-  if (existsSync(claudeMdSrc) && !existsSync(userClaudeMd)) {
-    copyFileSync(claudeMdSrc, userClaudeMd);
-    ok("~/.claude/CLAUDE.md created (ArkaOS user instructions)");
-  } else if (existsSync(userClaudeMd)) {
-    ok("~/.claude/CLAUDE.md already exists (preserved)");
-  }
+  // Fresh install writes the template inside managed markers (PR-C5) so
+  // later updates can manage the file via its markers, no hash path
+  // needed; an existing file keeps the historical preserve semantics.
+  const claudeMdResult = installUserClaudeMd({
+    home: homedir(),
+    templatePath: join(ARKAOS_ROOT, "config", "user-claude.md"),
+  });
+  const claudeMdReport = describeSyncResult(claudeMdResult);
+  (claudeMdReport.level === "warn" ? warn : ok)(claudeMdReport.message);
 
   // ═══ Step 10: Deploy Cognitive Scheduler ═══
   step(10, 14, "Deploying cognitive scheduler...");

package/installer/update.js

@@ -10,6 +10,7 @@ import { deployCoreSnapshot } from "./core-snapshot.js";
 import { getRuntimeConfig } from "./detect-runtime.js";
 import { loadAdapter } from "./index.js";
 import { migrateUserData, printMigrationReport } from "./migrate-user-data.js";
+import { syncUserClaudeMd, describeSyncResult } from "./claude-md.js";
 import { resolveFile } from "./path-resolver.js";
 import { IS_WINDOWS, HOOK_EXT } from "./platform.js";
 import { getUi } from "./ui.js";
@@ -368,13 +369,17 @@ export async function update({ skillsFlag = "" } = {}) {
       ok("arka-py interpreter shim updated");
     }
   }
-  const userClaudeMd = join(homedir(), ".claude", "CLAUDE.md");
-  const claudeMdSrc = join(ARKAOS_ROOT, "config", "user-claude.md");
-  if (existsSync(claudeMdSrc)) {
-    mkdirSync(join(homedir(), ".claude"), { recursive: true });
-    copyFileSync(claudeMdSrc, userClaudeMd);
-    ok("~/.claude/CLAUDE.md updated");
-  }
+  // Managed-block sync: once the block exists only the marked region is
+  // rewritten; an unmarked file is adopted (wrapped or prepended to) and
+  // no operator byte is lost (PR-C5 — the blind copy here destroyed the
+  // operator's CLAUDE.md via the autoupdater on 2026-08-03).
+  const claudeMdResult = syncUserClaudeMd({
+    home: homedir(),
+    templatePath: join(ARKAOS_ROOT, "config", "user-claude.md"),
+  });
+  const claudeMdReport = describeSyncResult(claudeMdResult);
+  (claudeMdReport.level === "warn" ? warn : ok)(claudeMdReport.message);
+  if (claudeMdReport.detail) detail(`         ${claudeMdReport.detail}`);
 
   // ── 5. Update Cognitive Scheduler ──
   section(5, 9, "Updating cognitive scheduler...");

package/knowledge/skills-manifest.json

@@ -1,7 +1,7 @@
 {
   "_meta": {
     "generator": "scripts/marketplace_gen.py",
-    "version": "5.0.0",
+    "version": "5.1.0",
     "marketplace": "arkaos"
   },
   "structural": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "description": "The Operating System for AI Agent Teams",
   "type": "module",
   "bin": {

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arkaos-core"
-version = "5.0.0"
+version = "5.1.0"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}