gru-ai 0.3.0 → 0.3.1

package/README.md

@@ -11,18 +11,16 @@
 
 <p align="center">
   <a href="#what-is-gruai">What Is gruAI?</a> •
+  <a href="#quickstart">Quickstart</a> •
   <a href="#the-pipeline">The Pipeline</a> •
-  <a href="#the-context-tree">Context Tree</a> •
-  <a href="#why-is-the-output-better">Why It Works</a> •
   <a href="#your-team">Your Team</a> •
-  <a href="#quickstart">Quickstart</a>
+  <a href="#why-is-the-output-better">Why It Works</a> •
+  <a href="#the-context-tree">Context Tree</a>
 </p>
 
-<p align="center">
-  <video src="docs/assets/demo.mp4" width="720" autoplay loop muted playsinline>
-    <img src="docs/assets/game-office.png" alt="gruAI pixel-art office with agents working" width="720" />
-  </video>
-</p>
+<div align="center">
+  <video src="https://github.com/user-attachments/assets/8859bc1f-8a04-47ac-9f94-35b9c71741eb" width="720" controls></video>
+</div>
 
 ---
 
@@ -36,131 +34,87 @@ The system is designed for **depth, not speed.** Agents accumulate institutional
 
 **You make decisions. Agents make software.** Every directive flows through a 15-step pipeline — triage, audit, brainstorm, plan, build, review, and ship — grounded in published research from Anthropic and OpenAI on what actually makes AI output reliable.
 
-**gruAI is right for you if:**
+---
+
+## Is gruAI Right for You?
 
-✅ You want to give direction, not write prompts — and have agents that brainstorm, challenge your thinking, and get it right without a reprompt loop
-✅ You want mandatory code review and mechanical verification, not optional "looks good to me"
-✅ You want institutional memory — agents that learn from mistakes and carry lessons across every task
-✅ You want a structured pipeline backed by context engineering research, not ad-hoc agent orchestration
-✅ You coordinate specialized roles (CTO, COO, CPO, CMO, engineers) not generic "AI assistants"
+- ✅ You're running 10+ terminals, juggling context, reprompting the same mistakes — and you want to hand down a directive and walk away
+- ✅ You've been burned by agents that "review" their own code — you want reviews that are mandatory, mechanical, and impossible to skip
+- ✅ Your agents forget everything between sessions — you want a team that remembers what broke last time
+- ✅ You're the bottleneck for every decision, every prompt, every context refresh — you want to be the CEO, not the project manager
+- ✅ You like running a one-person company with a full AI team, and you want it to actually feel that way — not like managing a chatbot farm
+- ✅ You want agents that push back on your ideas before building, not agents that say yes and ship the wrong thing
 
 ---
 
 ## The Pipeline
 
-You say *"add a payment system."* The pipeline takes it from here — 15 steps across 5 phases.
+You type: `/directive Create a landing page for gruAI`. Here's what happens next.
 
-| Icon | Meaning |
-|:----:|---------|
-| :gear: | **System step** — automated, no agent or human involved |
-| :busts_in_silhouette: | **Agent step** — one or more AI agents do the work |
-| :diamond_shape_with_a_dot_inside: | **CEO gate** — pipeline pauses for your decision |
+**1. Triage** — *Automated*
 
-### Phase 1: Intake
+Classified **heavyweight** — touches copy, layout, SEO, and design across multiple files. Each agent gets [role-scoped context](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents): the CTO gets your tech stack and component patterns, the CMO gets your positioning docs, engineers get your existing layout system. Not a 200K-token dump. [Start simple, add complexity only when needed.](https://www.anthropic.com/research/building-effective-agents)
 
-| # | Step | Who | What Happens |
-|:-:|------|:---:|-------------|
-| 1 | :gear: **Triage** | System | Classifies your directive by weight: lightweight, medium, heavyweight, or strategic. *"Add a payment system"* spans API, database, and UI — classified **heavyweight**. [Start simple, add complexity only when needed.](https://www.anthropic.com/research/building-effective-agents) |
-| 2 | :gear: **Checkpoint** | System | Checks for prior progress. If a session died mid-execution, it reads `directive.json` and [resumes from the last completed step](https://www.anthropic.com/engineering/building-c-compiler) — no work is lost. |
-| 3 | :gear: **Read** | System | Parses your directive brief, creates structured metadata, and extracts your Definition of Done. |
+**2. Audit** — *QA Engineer → CTO*
 
-### Phase 2: Analysis
+QA scans the codebase: finds the existing `/app` route structure, the Tailwind config, that there's no `og:image` setup, and that the current root page is a placeholder. CTO recommends: reuse the existing layout components, add Open Graph meta from the start, keep it server-rendered for SEO — no need for a SPA or a CMS.
 
-| # | Step | Who | What Happens |
-|:-:|------|:---:|-------------|
-| 4 | :gear: **Context** | System | Loads lessons, design docs, and intel — [scoped to what this directive needs](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents), not a 200K-token dump. |
-| 5 | :busts_in_silhouette: **Audit** | QA Engineer, then CTO | Two-agent sequential audit. QA scans the codebase (pure facts: which files, what state, what breaks). Then the CTO recommends approaches. Identifies existing API patterns, database schema, and security considerations. |
-| 6 | :busts_in_silhouette: **Brainstorm** | CTO + CPO + CMO | C-suite agents independently propose approaches, then [deliberate and argue](https://www.anthropic.com/engineering/multi-agent-research-system). CTO pushes for Stripe, CPO argues for simpler in-house billing, CMO flags pricing page implications. They surface 3 questions for you. |
+**3. Debate** — *CTO + CPO + CMO*
 
-### Phase 3: Planning
+**You're not in the room.** The C-suite agents independently propose approaches, then [argue](https://www.anthropic.com/engineering/multi-agent-research-system):
 
-| # | Step | Who | What Happens |
-|:-:|------|:---:|-------------|
-| 7 | :diamond_shape_with_a_dot_inside: **Clarification** | System → **CEO confirms** | Synthesizes intent from your brief, audit findings, and brainstorm. Surfaces conflicts and gaps. **You answer the 3 questions** — catching misalignment here costs one interaction instead of a full reopen. |
-| 8 | :busts_in_silhouette: **Plan** | COO | Decomposes the directive into projects, assigns agents and reviewers. Payment system → 2 projects: backend engineer builds API + database, frontend engineer builds UI. CTO reviews both. |
-| 9 | :diamond_shape_with_a_dot_inside: **Approve** | **CEO reviews plan** | **You review the plan** before any code is written. [Human review at trust boundaries only](https://www.anthropic.com/engineering/building-c-compiler) — you gate the plan and the result, not every step in between. |
+> **CTO:** *"Static HTML page. One task, no framework overhead. We don't need React for a landing page — it's marketing content, not an app."*
+>
+> **CPO:** *"A static page won't convert. Developers want to see the product work before they install anything. We need an interactive demo or at minimum an embedded video walkthrough."*
+>
+> **CMO:** *"Neither matters if nobody finds it. An SPA landing page is invisible to Google. Server-rendered with proper meta tags, structured data, and a clear CTA — or we're building for an audience of zero."*
 
-### Phase 4: Execution
+They find common ground: server-rendered page with an embedded demo video. Then they surface 3 questions for you.
 
-| # | Step | Who | What Happens |
-|:-:|------|:---:|-------------|
-| 10 | :busts_in_silhouette: **Project Brainstorm** | CTO + assigned builder | Break each project into concrete tasks with Definition of Done criteria. API project gets 3 tasks: Stripe integration, webhook handling, subscription management. |
-| 11 | :gear: **Setup** | System | Creates a git branch to isolate changes. |
-| 12 | :busts_in_silhouette: **Execute** | Assigned builders + reviewers | Builders work through tasks. After each task, a [separate reviewer evaluates with fresh context](https://www.anthropic.com/research/building-effective-agents) — no builder reasoning, no confirmation bias. Failed review triggers a fix cycle. |
+**4. Clarify** — 👤 **You**
 
-### Phase 5: Verification
+You answer 3 questions: *"Should the demo be live or a video?"* → video for now. *"Target audience — developers or technical founders?"* → developers first. *"Ship under /landing or replace the root?"* → replace root, the current placeholder adds no value.
 
-| # | Step | Who | What Happens |
-|:-:|------|:---:|-------------|
-| 13 | :gear: **Review Gate** | System | Bash scripts — not LLMs — [mechanically verify](https://openai.com/index/harness-engineering/) that every task was reviewed by a different agent, every DOD criterion was evaluated, and review artifacts exist. |
-| 14 | :gear: **Wrapup** | System | Updates lessons and design docs. Generates a CEO digest with files changed, review results, and revert commands. [Knowledge persists](https://arxiv.org/abs/2602.20478) for future directives. |
-| 15 | :diamond_shape_with_a_dot_inside: **Completion** | **CEO** | **Mandatory for all weights.** You review the digest and decide: approve (ship it), amend (fix specific issues), or reopen (start over). The pipeline never ships without your sign-off. |
+**5. Plan** — *COO* → 👤 **You**
 
-### Weight Adaptation
+COO breaks it into 2 projects with 6 tasks:
+- **Project 1:** Full-stack engineer builds page structure — hero with tagline and demo video, feature grid with pipeline highlights, agent team section, and Open Graph meta. 4 tasks.
+- **Project 2:** Frontend engineer builds responsive layout — mobile breakpoints, CTA positioning, and dark mode support. 2 tasks.
 
-| Weight | Example | Skips | CEO Gates |
-|--------|---------|-------|-----------|
-| **Lightweight** | Fix a typo | Brainstorm | Completion only |
-| **Medium** | Add dark mode toggle | Brainstorm | Completion only |
-| **Heavyweight** | New payment system | Nothing | Clarification + Approve + Completion |
-| **Strategic** | Platform migration | Nothing | Clarification + Approve + Completion |
+CTO reviews both projects. Each task has a Definition of Done: *"Hero section renders demo video with fallback image, loads in under 2s on 3G."* **You approve the plan** before any code is written.
 
----
+**6. Build** — *Engineers*
 
-## The Context Tree
+Full-stack engineer builds the hero section, feature grid, and OG meta on an isolated git branch. Each task runs in a [clean context window](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) — the agent building the hero section doesn't carry leftover context from the meta tags task. After each task, a [separate reviewer evaluates with fresh context](https://www.anthropic.com/research/building-effective-agents) — no builder reasoning, no confirmation bias.
 
-All state lives in `.context/` at your repo root — plain markdown and JSON, version-controlled alongside your code.
+**7. Review** — *Reviewers + Automated*
 
-```
-.context/
-├── directives/              # All work lives here
-│   └── dark-mode/
-│       ├── directive.json   # Pipeline state, weight, progress
-│       ├── directive.md     # CEO brief
-│       ├── audit.md         # CTO's technical audit
-│       ├── brainstorm.md    # C-suite deliberation
-│       └── projects/
-│           └── dark-mode/
-│               └── project.json  # Tasks, DOD, agents, reviews
-├── lessons/                 # What went wrong (reactive)
-├── design/                  # Why the system works this way (proactive)
-├── intel/                   # External research from /scout
-└── reports/                 # CEO digests
-```
+> **Round 1:** CTO reviews the hero section. Finds 3 issues: missing `<meta description>` tag (SEO blind spot), layout breaks below 375px on the feature grid (iPhone SE), and no `loading="lazy"` on the demo video (kills page speed score). Sends findings back to builder with specific file locations and expected fixes.
+>
+> **Round 2:** Builder fixes all three. CTO reviews again with fresh context — doesn't remember giving the feedback, evaluates the code on its own merit. Finds one remaining issue: `#aaa` text on `#fff` background in the feature section fails WCAG AA contrast (4.5:1 required, got 2.7:1). Builder bumps to `#595959`. **Passes.**
 
-**Directive → Projects → Tasks.** A directive is a unit of work ("add dark mode"). The COO decomposes it into projects, each with tasks, agents, reviewers, and a Definition of Done. `directive.json` tracks pipeline progress — any session can read it and resume where it left off. `project.json` is the source of truth for what needs building and whether it passed review.
+Bash scripts [verify](https://openai.com/index/harness-engineering/) every task was reviewed by a different agent than the one that built it. No review can be skipped, faked, or self-certified. This [evaluator-optimizer loop](https://www.anthropic.com/research/building-effective-agents) runs up to 3 rounds per task.
 
-**Knowledge compounds.** Lessons, design rationale, and standing corrections persist across directives. Agents load relevant context just-in-time — not everything, just what they need for their role and task. No database, no external service — just files.
+**8. Ship** — *Automated*
 
----
-
-## Why Is the Output Better?
-
-Every point below traces to published research from Anthropic and OpenAI. This isn't a workflow we invented — it's assembled from what the research says actually works.
-
-- **Agents brainstorm and argue before anyone writes code.** For strategic directives, your C-suite agents independently propose approaches, then deliberate — challenging assumptions, resolving disagreements, and surfacing questions for you. Anthropic's research found [multi-agent outperformed single-agent by 90.2%](https://www.anthropic.com/engineering/multi-agent-research-system). The pipeline implements their [orchestrator-workers pattern](https://www.anthropic.com/research/building-effective-agents) where specialized agents collaborate, producing better results than any single agent.
+Lessons captured: *"Always add OG meta tags when creating new pages"* and *"Check WCAG contrast on all text colors."* Design docs updated with the new route structure. CEO digest generated with all 8 files changed, both review rounds summarized, and `git revert` commands ready if needed. [Knowledge persists](https://arxiv.org/abs/2602.20478) — next time someone creates a page, agents already know about the OG tags.
 
-- **Reviewers evaluate intent, not just code.** Each reviewer gets [fresh context](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) scoped to the task — they never see the builder's reasoning, preventing confirmation bias. They verify against your Definition of Done (what you asked for), not just whether the code compiles. This is Anthropic's [evaluator-optimizer pattern](https://www.anthropic.com/research/building-effective-agents): one agent generates, another evaluates, issues get fixed in-loop — not after the fact.
-
-- **Context is isolated, not accumulated.** Each agent spawns with a [clean context window](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) scoped to exactly what it needs. No 200K-token sessions where the model forgets what it read at the start. Anthropic's context engineering research shows accuracy degrades as token count increases — gruAI treats context as a finite resource under active degradation.
+**9. Your Call** — 👤 **You**
 
-- **Verification is mechanical.** Bash scripts — not LLMs — enforce pipeline integrity: schema validation, self-review prevention, step dependency checks, role assignment verification. This follows Anthropic's [poka-yoke principle](https://www.anthropic.com/research/building-effective-agents) (error-proof design) and OpenAI's finding that [invariants should be enforced through structural tests](https://openai.com/index/harness-engineering/), not judgment.
+You see the digest: 8 files changed, 2 review rounds, all 6 DOD criteria met, zero open issues. You open the page in your browser, check mobile, and decide: **approve** it as-is, **amend** with specific fixes (*"bump the CTA font size"*), **extend** the directive with new scope (*"now add a pricing section"*), or **redirect** if the approach was wrong. The pipeline never ships without your sign-off — and never limits you to just "accept" or "reject."
 
-- **The harness determines output quality, not model intelligence.** Anthropic found that ["the task verifier must be nearly perfect, otherwise the agent solves the wrong problem"](https://www.anthropic.com/engineering/building-c-compiler). OpenAI's team reached the same conclusion: [3 engineers produced 1M lines of code](https://openai.com/index/harness-engineering/) not by writing better prompts, but by designing better environments and feedback loops. gruAI's 15-step pipeline IS that harness.
-
-- **Memory compounds across directives.** Lessons, design rationale, and standing corrections persist in `.context/` and get loaded into every future agent. This implements the [codified context pattern](https://arxiv.org/abs/2602.20478) — hot-memory + specialized agents + cold-memory knowledge base.
+> *The pipeline runs 15 internal steps. Context loading, crash recovery, git isolation, and lesson extraction run automatically between the steps above.*
 
----
-
-## Why Not Just Use Claude Code Directly?
-
-Claude Code is the execution engine. gruAI is the management layer on top.
-
-Without gruAI, you prompt an agent, review the output, re-prompt to fix issues, manage context yourself, and hope nothing falls through the cracks. There is no review gate, no institutional memory, and no structure beyond what you hold in your head.
+### Weight Adaptation
 
-With gruAI, you hand down a directive and agents self-organize through a 15-step pipeline. Reviews are mandatory and mechanical — a different agent reviews each task, and bash scripts verify the reviews actually happened. Lessons persist across directives so your 10th task runs better than your 1st. You approve the result, not every step along the way.
+Not every directive needs the full process.
 
-gruAI doesn't replace Claude Code. It makes Claude Code work like a team instead of a solo assistant.
+| Weight | Example | Skips | You Decide At |
+|--------|---------|-------|---------------|
+| **Lightweight** | Fix a typo | Debate | Accept only |
+| **Medium** | Add dark mode | Debate | Accept only |
+| **Heavyweight** | New landing page | Nothing | Clarify + Plan + Accept |
+| **Strategic** | Platform migration | Nothing | Clarify + Plan + Accept |
 
 ---
 
@@ -248,6 +202,63 @@ The pipeline and dashboard are engine-agnostic by design — platform adapters h
 
 ---
 
+## Why Is the Output Better?
+
+Every point below traces to published research from Anthropic and OpenAI. This isn't a workflow we invented — it's assembled from what the research says actually works.
+
+- **Agents brainstorm and argue before anyone writes code.** For strategic directives, your C-suite agents independently propose approaches, then deliberate — challenging assumptions, resolving disagreements, and surfacing questions for you. Anthropic's research found [multi-agent outperformed single-agent by 90.2%](https://www.anthropic.com/engineering/multi-agent-research-system). The pipeline implements their [orchestrator-workers pattern](https://www.anthropic.com/research/building-effective-agents) where specialized agents collaborate, producing better results than any single agent.
+
+- **Reviewers evaluate intent, not just code.** Each reviewer gets [fresh context](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) scoped to the task — they never see the builder's reasoning, preventing confirmation bias. They verify against your Definition of Done (what you asked for), not just whether the code compiles. This is Anthropic's [evaluator-optimizer pattern](https://www.anthropic.com/research/building-effective-agents): one agent generates, another evaluates, issues get fixed in-loop — not after the fact.
+
+- **Context is isolated, not accumulated.** Each agent spawns with a [clean context window](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) scoped to exactly what it needs. No 200K-token sessions where the model forgets what it read at the start. Anthropic's context engineering research shows accuracy degrades as token count increases — gruAI treats context as a finite resource under active degradation.
+
+- **Verification is mechanical.** Bash scripts — not LLMs — enforce pipeline integrity: schema validation, self-review prevention, step dependency checks, role assignment verification. This follows Anthropic's [poka-yoke principle](https://www.anthropic.com/research/building-effective-agents) (error-proof design) and OpenAI's finding that [invariants should be enforced through structural tests](https://openai.com/index/harness-engineering/), not judgment.
+
+- **The harness determines output quality, not model intelligence.** Anthropic found that ["the task verifier must be nearly perfect, otherwise the agent solves the wrong problem"](https://www.anthropic.com/engineering/building-c-compiler). OpenAI's team reached the same conclusion: [3 engineers produced 1M lines of code](https://openai.com/index/harness-engineering/) not by writing better prompts, but by designing better environments and feedback loops. gruAI's 15-step pipeline IS that harness.
+
+- **Memory compounds across directives.** Lessons, design rationale, and standing corrections persist in `.context/` and get loaded into every future agent. This implements the [codified context pattern](https://arxiv.org/abs/2602.20478) — hot-memory + specialized agents + cold-memory knowledge base.
+
+---
+
+## Why Not Just Use Claude Code Directly?
+
+Claude Code is the execution engine. gruAI is the management layer on top.
+
+Without gruAI, you prompt an agent, review the output, re-prompt to fix issues, manage context yourself, and hope nothing falls through the cracks. There is no review gate, no institutional memory, and no structure beyond what you hold in your head.
+
+With gruAI, you hand down a directive and agents self-organize through a 15-step pipeline. Reviews are mandatory and mechanical — a different agent reviews each task, and bash scripts verify the reviews actually happened. Lessons persist across directives so your 10th task runs better than your 1st. You approve the result, not every step along the way.
+
+gruAI doesn't replace Claude Code. It makes Claude Code work like a team instead of a solo assistant.
+
+---
+
+## The Context Tree
+
+All state lives in `.context/` at your repo root — plain markdown and JSON, version-controlled alongside your code.
+
+```
+.context/
+├── directives/              # All work lives here
+│   └── dark-mode/
+│       ├── directive.json   # Pipeline state, weight, progress
+│       ├── directive.md     # CEO brief
+│       ├── audit.md         # CTO's technical audit
+│       ├── brainstorm.md    # C-suite deliberation
+│       └── projects/
+│           └── dark-mode/
+│               └── project.json  # Tasks, DOD, agents, reviews
+├── lessons/                 # What went wrong (reactive)
+├── design/                  # Why the system works this way (proactive)
+├── intel/                   # External research from /scout
+└── reports/                 # CEO digests
+```
+
+**Directive → Projects → Tasks.** A directive is a unit of work ("add dark mode"). The COO decomposes it into projects, each with tasks, agents, reviewers, and a Definition of Done. `directive.json` tracks pipeline progress — any session can read it and resume where it left off. `project.json` is the source of truth for what needs building and whether it passed review.
+
+**Knowledge compounds.** Lessons, design rationale, and standing corrections persist across directives. Agents load relevant context just-in-time — not everything, just what they need for their role and task. No database, no external service — just files.
+
+---
+
 <details>
 <summary><strong>Terminal Support</strong></summary>
 

package/dist-cli/commands/scaffold.d.ts

@@ -1,6 +1,9 @@
 /**
  * Scaffolding engine — creates all project files from templates.
  *
+ * SAFE BY DEFAULT: Never overwrites existing user files. Only writes new files.
+ * gruai-owned files (agents, skills, registry) are always updated.
+ *
  * Takes an InitConfig and produces:
  *  - .gruai/ canonical home directory
  *  - Platform symlink (.claude/, .aider/, etc.)

package/dist-cli/commands/scaffold.js

@@ -1,6 +1,9 @@
 /**
  * Scaffolding engine — creates all project files from templates.
  *
+ * SAFE BY DEFAULT: Never overwrites existing user files. Only writes new files.
+ * gruai-owned files (agents, skills, registry) are always updated.
+ *
  * Takes an InitConfig and produces:
  *  - .gruai/ canonical home directory
  *  - Platform symlink (.claude/, .aider/, etc.)
@@ -25,6 +28,13 @@ function writeFile(filePath, content) {
     ensureDir(path.dirname(filePath));
     fs.writeFileSync(filePath, content, 'utf-8');
 }
+/** Write only if file does not exist. Returns true if written, false if skipped. */
+function writeFileIfNew(filePath, content) {
+    if (fs.existsSync(filePath))
+        return false;
+    writeFile(filePath, content);
+    return true;
+}
 function copyFile(src, dest) {
     ensureDir(path.dirname(dest));
     fs.copyFileSync(src, dest);
@@ -64,24 +74,39 @@ function platformDir(platform) {
 function scaffoldGruaiHome(projectPath, platform) {
     const gruaiDir = path.join(projectPath, '.gruai');
     ensureDir(gruaiDir);
-    // Create platform symlink if applicable
+    const merged = [];
     const platDir = platformDir(platform);
     if (platDir) {
         const platPath = path.join(projectPath, platDir);
-        // If platform dir already exists as a real directory, skip symlink
         if (fs.existsSync(platPath)) {
             const stat = fs.lstatSync(platPath);
             if (stat.isSymbolicLink()) {
+                // Already a symlink — check if it points to .gruai
+                const target = fs.readlinkSync(platPath);
+                if (target === '.gruai' || target === path.join(projectPath, '.gruai')) {
+                    // Already correct, nothing to do
+                    return { merged };
+                }
                 fs.unlinkSync(platPath);
             }
             else {
-                // Real directory exists -- copy contents into .gruai and replace with symlink
-                const entries = fs.readdirSync(platPath);
+                // Real directory — merge contents into .gruai preserving existing files
+                const entries = fs.readdirSync(platPath, { withFileTypes: true });
                 for (const entry of entries) {
-                    const src = path.join(platPath, entry);
-                    const dest = path.join(gruaiDir, entry);
-                    if (!fs.existsSync(dest)) {
+                    const src = path.join(platPath, entry.name);
+                    const dest = path.join(gruaiDir, entry.name);
+                    if (fs.existsSync(dest)) {
+                        // Destination exists — merge directories, skip files
+                        if (entry.isDirectory() && fs.statSync(dest).isDirectory()) {
+                            // Merge directory contents (existing files in .gruai win)
+                            mergeDir(src, dest);
+                            merged.push(entry.name + '/');
+                        }
+                        // Skip files that already exist in .gruai
+                    }
+                    else {
                         fs.renameSync(src, dest);
+                        merged.push(entry.name);
                     }
                 }
                 fs.rmSync(platPath, { recursive: true, force: true });
@@ -90,13 +115,33 @@ function scaffoldGruaiHome(projectPath, platform) {
         // Create symlink: .claude -> .gruai
         fs.symlinkSync('.gruai', platPath);
     }
+    return { merged };
+}
+/** Recursively merge src into dest, never overwriting existing files in dest. */
+function mergeDir(src, dest) {
+    ensureDir(dest);
+    const entries = fs.readdirSync(src, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            mergeDir(srcPath, destPath);
+        }
+        else if (!fs.existsSync(destPath)) {
+            fs.renameSync(srcPath, destPath);
+        }
+        // If destPath exists, user's file wins — do nothing
+    }
 }
 function scaffoldAgents(projectPath, agents) {
     const destDir = path.join(projectPath, '.gruai', 'agents');
-    let count = 0;
+    let written = 0;
+    const skipped = [];
     for (const agent of agents) {
         const roleId = ROLE_DEFINITIONS.find(r => r.title === agent.title)?.id;
         const templatePath = path.join(ROLE_TEMPLATES_DIR, `${roleId}.md`);
+        const destPath = path.join(destDir, agent.agentFile);
+        // Agent personality files are gruai-owned — always write
         let content;
         if (fs.existsSync(templatePath)) {
             content = fs.readFileSync(templatePath, 'utf-8');
@@ -107,10 +152,10 @@ function scaffoldAgents(projectPath, agents) {
         else {
             content = `# ${agent.name} -- ${agent.role}\n\nRole template not found.\n`;
         }
-        writeFile(path.join(destDir, agent.agentFile), content);
-        count++;
+        writeFile(destPath, content);
+        written++;
     }
-    return count;
+    return { written, skipped };
 }
 function scaffoldRegistry(projectPath, agents, preset) {
     const ceoEntry = {
@@ -148,6 +193,7 @@ function scaffoldRegistry(projectPath, agents, preset) {
     }));
     const teams = buildTeams(agents);
     const registry = { teamSize: preset, agents: [ceoEntry, ...agentEntries], teams };
+    // Registry is gruai-owned — always overwrite
     writeFile(path.join(projectPath, '.gruai', 'agent-registry.json'), JSON.stringify(registry, null, 2));
 }
 function buildTeams(agents) {
@@ -201,7 +247,8 @@ function buildTeams(agents) {
 }
 function scaffoldSkills(projectPath) {
     const destDir = path.join(projectPath, '.gruai', 'skills');
-    let count = 0;
+    let written = 0;
+    let updated = 0;
     for (const skill of ALL_SKILLS) {
         const skillDir = path.join(SKILLS_SRC_DIR, skill);
         const skillMd = path.join(skillDir, 'SKILL.md');
@@ -209,28 +256,52 @@ function scaffoldSkills(projectPath) {
             console.warn(c.yellow(`  Warning: Skill file not found: ${skill}/SKILL.md (skipped)`));
             continue;
         }
-        copyFile(skillMd, path.join(destDir, skill, 'SKILL.md'));
+        const destSkillMd = path.join(destDir, skill, 'SKILL.md');
+        const existed = fs.existsSync(destSkillMd);
+        // Skills are gruai-owned — always update to latest version
+        copyFile(skillMd, destSkillMd);
         const docsDir = path.join(skillDir, 'docs');
         if (fs.existsSync(docsDir) && fs.statSync(docsDir).isDirectory()) {
             copyDirRecursive(docsDir, path.join(destDir, skill, 'docs'));
         }
-        count++;
+        if (existed)
+            updated++;
+        else
+            written++;
     }
-    return count;
+    return { written, updated };
 }
 function scaffoldContext(projectPath, config) {
     const contextDir = path.join(projectPath, '.context');
-    // vision.md
+    const created = [];
+    const preserved = [];
+    // vision.md — user-owned, skip if exists
+    const visionPath = path.join(contextDir, 'vision.md');
     const vision = readTemplate('vision.md').replace(/\{\{PROJECT_NAME\}\}/g, config.projectName);
-    writeFile(path.join(contextDir, 'vision.md'), vision);
-    // lessons/index.md
+    if (writeFileIfNew(visionPath, vision))
+        created.push('vision.md');
+    else
+        preserved.push('vision.md');
+    // lessons/index.md — user-owned, skip if exists
+    const lessonsPath = path.join(contextDir, 'lessons', 'index.md');
     const lessons = readTemplate('lessons.md').replace(/\{\{PROJECT_NAME\}\}/g, config.projectName);
-    writeFile(path.join(contextDir, 'lessons', 'index.md'), lessons);
-    // preferences.md
-    writeFile(path.join(contextDir, 'preferences.md'), `# CEO Preferences\n\n> Standing orders for the team. Agents read this before every task.\n\n## Standing Orders\n\n- (Add your preferences here)\n`);
-    // backlog.json
+    if (writeFileIfNew(lessonsPath, lessons))
+        created.push('lessons/index.md');
+    else
+        preserved.push('lessons/index.md');
+    // preferences.md — user-owned, skip if exists
+    const prefsPath = path.join(contextDir, 'preferences.md');
+    if (writeFileIfNew(prefsPath, `# CEO Preferences\n\n> Standing orders for the team. Agents read this before every task.\n\n## Standing Orders\n\n- (Add your preferences here)\n`))
+        created.push('preferences.md');
+    else
+        preserved.push('preferences.md');
+    // backlog.json — user-owned, skip if exists
+    const backlogPath = path.join(contextDir, 'backlog.json');
     const backlog = readTemplate('backlog.json.template');
-    writeFile(path.join(contextDir, 'backlog.json'), backlog);
+    if (writeFileIfNew(backlogPath, backlog))
+        created.push('backlog.json');
+    else
+        preserved.push('backlog.json');
     // Empty directories with .gitkeep
     for (const dir of ['directives', 'reports']) {
         const dirPath = path.join(contextDir, dir);
@@ -240,8 +311,14 @@ function scaffoldContext(projectPath, config) {
             fs.writeFileSync(gitkeep, '', 'utf-8');
         }
     }
+    return { created, preserved };
 }
 function scaffoldClaudeMd(projectPath, config) {
+    const claudeMdPath = path.join(projectPath, 'CLAUDE.md');
+    // User-owned file — never overwrite
+    if (fs.existsSync(claudeMdPath)) {
+        return 'preserved';
+    }
     const template = readTemplate('CLAUDE.md.template');
     const rosterLines = ['| Name | Title | Role |', '|------|-------|------|'];
     rosterLines.push('| (You) | CEO | Chief Executive Officer |');
@@ -251,9 +328,12 @@ function scaffoldClaudeMd(projectPath, config) {
     const content = template
         .replace(/\{\{PROJECT_NAME\}\}/g, config.projectName)
         .replace(/\{\{AGENT_ROSTER\}\}/g, rosterLines.join('\n'));
-    writeFile(path.join(projectPath, 'CLAUDE.md'), content);
+    writeFile(claudeMdPath, content);
+    return 'created';
 }
 function scaffoldGruaiConfig(projectPath, config) {
+    const configPath = path.join(projectPath, 'gruai.config.json');
+    const existed = fs.existsSync(configPath);
     const template = readTemplate('gruai.config.json.template');
     const agentsJson = JSON.stringify(config.agents.map(a => ({ id: a.id, name: a.name, role: a.title })), null, 4);
     const indentedAgentsJson = agentsJson
@@ -265,19 +345,25 @@ function scaffoldGruaiConfig(projectPath, config) {
         .replace(/\{\{PRESET\}\}/g, config.preset)
         .replace(/\{\{PLATFORM\}\}/g, config.platform)
         .replace(/\{\{AGENTS_JSON\}\}/g, indentedAgentsJson);
-    writeFile(path.join(projectPath, 'gruai.config.json'), content);
+    // gruai config is gruai-owned — always update
+    writeFile(configPath, content);
+    return existed ? 'updated' : 'created';
 }
 function scaffoldWelcomeDirective(projectPath) {
     const srcDir = path.join(TEMPLATES_DIR, 'welcome-directive');
     if (!fs.existsSync(srcDir))
-        return;
+        return false;
     const destDir = path.join(projectPath, '.context', 'directives', 'welcome');
+    // User-owned content — skip if directive already exists
+    if (fs.existsSync(path.join(destDir, 'directive.json')))
+        return false;
     ensureDir(destDir);
     // directive.json
     const djson = fs.readFileSync(path.join(srcDir, 'directive.json'), 'utf-8');
     writeFile(path.join(destDir, 'directive.json'), djson.replace(/\{\{CREATED_AT\}\}/g, new Date().toISOString()));
     // directive.md
     copyFile(path.join(srcDir, 'directive.md'), path.join(destDir, 'directive.md'));
+    return true;
 }
 // ─── Main scaffold function ─────────────────────────────────────────────────
 export async function runScaffold(config) {
@@ -287,35 +373,55 @@ export async function runScaffold(config) {
     }
     console.log(`\n  ${c.bold('Scaffolding gruai...')}\n`);
     // 1. .gruai/ home + platform symlink
-    scaffoldGruaiHome(config.projectPath, config.platform);
+    const { merged } = scaffoldGruaiHome(config.projectPath, config.platform);
     const platDir = platformDir(config.platform);
     if (platDir) {
         console.log(c.green(`  [+] Home:        .gruai/ with ${platDir}/ -> .gruai/ symlink`));
+        if (merged.length > 0) {
+            console.log(c.dim(`                   merged ${merged.length} existing entries from ${platDir}/`));
+        }
     }
     else {
         console.log(c.green(`  [+] Home:        .gruai/`));
     }
-    // 2. Agent registry
+    // 2. Agent registry (gruai-owned — always update)
     scaffoldRegistry(config.projectPath, config.agents, config.preset);
-    console.log(c.green(`  [+] Registry:    .gruai/agent-registry.json (${config.agents.length} agents + CEO, ${config.preset} preset)`));
-    // 3. Agent personality files
-    const agentCount = scaffoldAgents(config.projectPath, config.agents);
-    console.log(c.green(`  [+] Agents:      ${agentCount} personality files`));
-    // 4. Skills
-    const skillCount = scaffoldSkills(config.projectPath);
-    console.log(c.green(`  [+] Skills:      ${skillCount} skill definitions`));
-    // 5. Context tree
-    scaffoldContext(config.projectPath, config);
-    console.log(c.green(`  [+] Context:     vision.md, lessons/, directives/, backlog.json`));
-    // 6. CLAUDE.md
-    scaffoldClaudeMd(config.projectPath, config);
-    console.log(c.green(`  [+] CLAUDE.md:   project rules with agent roster`));
-    // 7. gruai.config.json
-    scaffoldGruaiConfig(config.projectPath, config);
-    console.log(c.green(`  [+] Config:      gruai.config.json`));
-    // 8. Welcome directive
-    scaffoldWelcomeDirective(config.projectPath);
-    console.log(c.green(`  [+] Directive:   welcome directive scaffolded`));
+    console.log(c.green(`  [+] Registry:    agent-registry.json (${config.agents.length} agents + CEO, ${config.preset} preset)`));
+    // 3. Agent personality files (gruai-owned — always update)
+    const agentResult = scaffoldAgents(config.projectPath, config.agents);
+    console.log(c.green(`  [+] Agents:      ${agentResult.written} personality files`));
+    // 4. Skills (gruai-owned — always update to latest)
+    const skillResult = scaffoldSkills(config.projectPath);
+    const skillParts = [];
+    if (skillResult.written > 0)
+        skillParts.push(`${skillResult.written} new`);
+    if (skillResult.updated > 0)
+        skillParts.push(`${skillResult.updated} updated`);
+    console.log(c.green(`  [+] Skills:      ${skillParts.join(', ') || 'up to date'}`));
+    // 5. Context tree (user-owned — never overwrite)
+    const ctxResult = scaffoldContext(config.projectPath, config);
+    if (ctxResult.created.length > 0) {
+        console.log(c.green(`  [+] Context:     ${ctxResult.created.join(', ')}`));
+    }
+    if (ctxResult.preserved.length > 0) {
+        console.log(c.dim(`  [=] Context:     ${ctxResult.preserved.join(', ')} (preserved)`));
+    }
+    // 6. CLAUDE.md (user-owned — never overwrite)
+    const claudeResult = scaffoldClaudeMd(config.projectPath, config);
+    if (claudeResult === 'created') {
+        console.log(c.green(`  [+] CLAUDE.md:   project rules with agent roster`));
+    }
+    else {
+        console.log(c.dim(`  [=] CLAUDE.md:   preserved (existing file kept)`));
+    }
+    // 7. gruai.config.json (gruai-owned — always update)
+    const configResult = scaffoldGruaiConfig(config.projectPath, config);
+    console.log(c.green(`  [+] Config:      gruai.config.json (${configResult})`));
+    // 8. Welcome directive (user-owned — skip if exists)
+    const welcomeCreated = scaffoldWelcomeDirective(config.projectPath);
+    if (welcomeCreated) {
+        console.log(c.green(`  [+] Directive:   welcome directive scaffolded`));
+    }
     // Output team summary
     console.log(`\n  ${c.bold('Done!')} gruai scaffolded into: ${c.cyan(config.projectPath)}\n`);
     console.log(`  ${c.bold('Your team:')}\n`);
@@ -333,10 +439,10 @@ export async function runScaffold(config) {
      ${c.dim(path.join(config.projectPath, '.context', 'preferences.md'))}
 
   3. Start the dashboard:
-     ${c.cyan('gru-ai start')}
+     ${c.cyan('npx gru-ai start')}
 
-  4. Create your first directive:
-     ${c.cyan('claude -p "/directive welcome"')}
+  4. Give your first directive:
+     ${c.cyan('claude -p "/directive add dark mode to the dashboard"')}
 
   ${c.dim('Happy orchestrating!')}
 `);

package/dist-cli/commands/start.js

@@ -14,15 +14,15 @@ function printStartHelp() {
 ${c.bold('gruai start')} — Launch the dashboard server
 
 ${c.bold('Usage:')}
-  gru-ai start [options]
+  npx gru-ai start [options]
 
 ${c.bold('Options:')}
   --port <port>  Server port (default: 4444)
   --help         Show this help message
 
 ${c.bold('Examples:')}
-  gru-ai start
-  gru-ai start --port 8080
+  npx gru-ai start
+  npx gru-ai start --port 8080
 `);
 }
 function isInitialized(projectPath) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gru-ai",
   "private": false,
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "bin": {
     "gru-ai": "dist-cli/index.js"