blueprint-os 1.0.2 → 1.2.0

package/.agent/skills/brainstorming/SKILL.md

@@ -154,4 +154,4 @@ The `shaping-specs` skill will use the design document as its starting context,
 - Design document output: `specs/`
 - Next step: `.agent/skills/shaping-specs/SKILL.md`
 - Existing standards (Mode 2): `standards/README.md`
-- Superpowers brainstorming reference: `npx skills add obra/superpowers`
+- Superpowers brainstorming reference: `npx skills add obra/superpowers -a antigravity -y --copy`

package/.agent/skills/creating-skills/SKILL.md

@@ -16,7 +16,7 @@ description: Acquires or creates Blueprint OS skills. Searches skills.sh registr
 
 - [ ] Clarify the skill's purpose — what task does it solve, and what are its triggers?
 - [ ] Search skills.sh for an existing community skill (see Instructions > Discovering on skills.sh)
-- [ ] If found: install with `npx skills add <owner/repo>` and evaluate fit
+- [ ] If found: install with `npx skills add <owner/repo> -a antigravity -y --copy` and evaluate fit
 - [ ] If it covers the need as-is: done — update the Skills Index in `README.md`
 - [ ] If it partially fits: customize it (see Instructions > Customizing an installed skill)
 - [ ] If nothing suitable found: create from scratch (see Instructions > Creating from scratch)
@@ -32,7 +32,7 @@ Before building anything, search the [skills.sh registry](https://skills.sh) —
 **Search via agent:**
 
 ```bash
-npx skills add https://github.com/vercel-labs/skills --skill find-skills
+npx skills add https://github.com/vercel-labs/skills --skill find-skills -a antigravity -y --copy
 ```
 
 Then ask the `find-skills` skill to search for what you need.
@@ -42,18 +42,18 @@ Then ask the `find-skills` skill to search for what you need.
 **Install a skill:**
 
 ```bash
-npx skills add <owner/repo>
+npx skills add <owner/repo> -a antigravity -y --copy
 ```
 
 Example:
 
 ```bash
-npx skills add supabase/agent-skills
-npx skills add vercel-labs/agent-skills
-npx skills add anthropics/skills
+npx skills add supabase/agent-skills -a antigravity -y --copy
+npx skills add vercel-labs/agent-skills -a antigravity -y --copy
+npx skills add anthropics/skills -a antigravity -y --copy
 ```
 
-Installed skills land in `.agent/skills/` automatically — compatible with Blueprint OS out of the box.
+The `-a antigravity` flag installs to `.agent/skills/`, matching Blueprint OS. The `--copy` flag creates real files (not symlinks) so deleting `.agents` won't break the skill when Cursor is detected.
 
 ### Customizing an installed skill
 

package/.agent/skills/find-skills/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: find-skills
+description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
+---
+
+# Find Skills
+
+This skill helps you discover and install skills from the open agent skills ecosystem.
+
+## When to Use This Skill
+
+Use this skill when the user:
+
+- Asks "how do I do X" where X might be a common task with an existing skill
+- Says "find a skill for X" or "is there a skill for X"
+- Asks "can you do X" where X is a specialized capability
+- Expresses interest in extending agent capabilities
+- Wants to search for tools, templates, or workflows
+- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
+
+## What is the Skills CLI?
+
+The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
+
+**Key commands:**
+
+- `npx skills find [query]` - Search for skills interactively or by keyword
+- `npx skills add <package>` - Install a skill from GitHub or other sources
+- `npx skills check` - Check for skill updates
+- `npx skills update` - Update all installed skills
+
+**Browse skills at:** https://skills.sh/
+
+## How to Help Users Find Skills
+
+### Step 1: Understand What They Need
+
+When a user asks for help with something, identify:
+
+1. The domain (e.g., React, testing, design, deployment)
+2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
+3. Whether this is a common enough task that a skill likely exists
+
+### Step 2: Search for Skills
+
+Run the find command with a relevant query:
+
+```bash
+npx skills find [query]
+```
+
+For example:
+
+- User asks "how do I make my React app faster?" → `npx skills find react performance`
+- User asks "can you help me with PR reviews?" → `npx skills find pr review`
+- User asks "I need to create a changelog" → `npx skills find changelog`
+
+The command will return results like:
+
+```
+Install with npx skills add <owner/repo@skill>
+
+vercel-labs/agent-skills@vercel-react-best-practices
+└ https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+### Step 3: Present Options to the User
+
+When you find relevant skills, present them to the user with:
+
+1. The skill name and what it does
+2. The install command they can run
+3. A link to learn more at skills.sh
+
+Example response:
+
+```
+I found a skill that might help! The "vercel-react-best-practices" skill provides
+React and Next.js performance optimization guidelines from Vercel Engineering.
+
+To install it:
+npx skills add vercel-labs/agent-skills@vercel-react-best-practices
+
+Learn more: https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+### Step 4: Offer to Install
+
+If the user wants to proceed, you can install the skill for them:
+
+```bash
+npx skills add <owner/repo@skill> -g -y
+```
+
+The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
+
+## Common Skill Categories
+
+When searching, consider these common categories:
+
+| Category        | Example Queries                          |
+| --------------- | ---------------------------------------- |
+| Web Development | react, nextjs, typescript, css, tailwind |
+| Testing         | testing, jest, playwright, e2e           |
+| DevOps          | deploy, docker, kubernetes, ci-cd        |
+| Documentation   | docs, readme, changelog, api-docs        |
+| Code Quality    | review, lint, refactor, best-practices   |
+| Design          | ui, ux, design-system, accessibility     |
+| Productivity    | workflow, automation, git                |
+
+## Tips for Effective Searches
+
+1. **Use specific keywords**: "react testing" is better than just "testing"
+2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
+3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
+
+## When No Skills Are Found
+
+If no relevant skills exist:
+
+1. Acknowledge that no existing skill was found
+2. Offer to help with the task directly using your general capabilities
+3. Suggest the user could create their own skill with `npx skills init`
+
+Example:
+
+```
+I searched for skills related to "xyz" but didn't find any matches.
+I can still help you with this task directly! Would you like me to proceed?
+
+If this is something you do often, you could create your own skill:
+npx skills init my-xyz-skill
+```

package/README.md

@@ -79,7 +79,9 @@ From your project directory:
 npx blueprint-os init
 ```
 
-This copies `.agent/`, `standards/`, `references/`, and `adapters/` into your project. No dependency is added to `package.json`.
+This copies `.agent/`, `standards/`, `references/`, and `adapters/` into your project. No dependency is added to `package.json`. The `find-skills` skill is included so you can search the skills.sh registry without installing it separately.
+
+**Conditional copy:** If `standards/` or `references/` already contain project content (files beyond the template), they are preserved and not overwritten.
 
 **Or copy manually:** Place the `.agent/` folder, `standards/` folder, and `references/` folder at the root of your project:
 
@@ -87,6 +89,9 @@ This copies `.agent/`, `standards/`, `references/`, and `adapters/` into your pr
 your-project/
 ├── .agent/
 │   └── skills/
+│       ├── find-skills/      ← pre-installed
+│       ├── brainstorming/
+│       └── ...
 ├── standards/
 ├── references/
 └── ... your code
@@ -124,11 +129,33 @@ your-project/
 **Adding a new skill:**
 
 ```
-1. Browse https://skills.sh or run: npx skills add https://github.com/vercel-labs/skills --skill find-skills
-2. If found: npx skills add <owner/repo>
+1. Use the pre-installed find-skills: "Read .agent/skills/find-skills/SKILL.md and find a skill for [task]" — or browse https://skills.sh
+2. If found: npx skills add <owner/repo> -a antigravity -y --copy
 3. If not found: ask your agent "Read .agent/skills/creating-skills/SKILL.md and create a skill for [task]"
 ```
 
+### Updating Blueprint OS
+
+To refresh core skills and adapters without touching your content:
+
+```bash
+npx blueprint-os@latest update
+```
+
+**What `update` does:**
+- Updates core skills in `.agent/skills/` (brainstorming, shaping-specs, discovering-standards, etc.)
+- Updates `adapters/`
+- Refreshes `references/agent-workflow/` and `references/README.md`
+- Refreshes `standards/README.md`
+
+**What `update` preserves:**
+- `specs/` — never touched
+- Your standards files (e.g. `api-design.md`, `error-handling.md`)
+- Your reference files (anything beyond `agent-workflow/`)
+- Community skills you installed from skills.sh
+
+**Conditional copy on `init`:** If you run `init` again, `standards/` and `references/` are preserved when they already contain project content (files beyond the shipped template).
+
 ---
 
 ## Skills Index
@@ -137,6 +164,7 @@ Skills live in `.agent/skills/`. Each skill is a `SKILL.md` file the agent reads
 
 | Skill | Path | Purpose |
 |---|---|---|
+| Find Skills | `.agent/skills/find-skills/` | Search the skills.sh registry for community skills (pre-installed) |
 | Brainstorming | `.agent/skills/brainstorming/` | Explore problems, compare approaches, produce a design document |
 | Creating Skills | `.agent/skills/creating-skills/` | Find on skills.sh first, author from scratch as fallback |
 | Shaping Specs | `.agent/skills/shaping-specs/` | Formalize a chosen direction into an implementation spec |
@@ -146,7 +174,7 @@ Skills live in `.agent/skills/`. Each skill is a `SKILL.md` file the agent reads
 | Security Audit | `.agent/skills/security-audit/` | Audit auth, API, and sensitive data changes before merge |
 | Code Review | `.agent/skills/code-review/` | Final validation against spec and standards before merge |
 
-**Community skills** from [skills.sh](https://skills.sh) install directly into `.agent/skills/` and work with Blueprint OS out of the box. Run `npx skills add <owner/repo>` to install any skill from the registry.
+**Community skills** from [skills.sh](https://skills.sh) install into `.agent/skills/` when you use `-a antigravity -y --copy`. The `--copy` flag creates real files so deleting `.agents` (created when Cursor is detected) won't break the skill.
 
 ---
 
@@ -258,17 +286,16 @@ Agent loads `component-patterns.md`, `error-handling.md`, and any relevant refer
 
 You want the agent to follow a strict TDD workflow but Blueprint OS has no skill for it.
 
-**Step 1: Check skills.sh first**
+**Step 1: Use the pre-installed find-skills**
 ```
-npx skills add https://github.com/vercel-labs/skills --skill find-skills
+Read .agent/skills/find-skills/SKILL.md and find a skill for test-driven development
 ```
-Then: `Use the find-skills skill to search for a test-driven development skill`
 
 Found: `obra/superpowers` has `test-driven-development`.
 
 **Step 2: Install it**
 ```
-npx skills add obra/superpowers test-driven-development
+npx skills add obra/superpowers --skill test-driven-development -a antigravity -y --copy
 ```
 Lands in `.agent/skills/test-driven-development/SKILL.md` — immediately available.
 

package/adapters/antigravity.md

@@ -1,6 +1,6 @@
 # Using Blueprint OS in Antigravity
 
-Blueprint OS uses the `.agent/skills/` structure natively — the same format Antigravity expects. No extra setup required.
+Blueprint OS uses the `.agent/skills/` structure natively — the same format Antigravity expects. When installing from skills.sh, use `-a antigravity` so skills land here. No extra setup required.
 
 ---
 
@@ -133,7 +133,7 @@ Use the `creating-skills` skill — it searches skills.sh first, then creates fr
 Find or create a skill for [task]
 ```
 
-The agent will check [skills.sh](https://skills.sh) first (`npx skills add https://github.com/vercel-labs/skills --skill find-skills`), install a community skill if available, or create a new one following `.agent/skills/creating-skills/SKILL.md`.
+The agent will check [skills.sh](https://skills.sh) first (`npx skills add https://github.com/vercel-labs/skills --skill find-skills -a antigravity -y --copy`), install a community skill if available, or create a new one following `.agent/skills/creating-skills/SKILL.md`.
 
 ---
 

package/adapters/cursor.md

@@ -1,6 +1,6 @@
 # Using Blueprint OS in Cursor
 
-Cursor reads rules from `.cursor/rules/` and skills from a skills directory. Blueprint OS skills live in `.agent/skills/` as portable markdown files. This guide shows how to connect them.
+Cursor reads rules from `.cursor/rules/` and skills from a skills directory. Blueprint OS skills live in `.agent/skills/` (singular) as portable markdown files. Cursor's native skills path is `.agents/skills/` (plural) — Blueprint OS uses `.agent/` and connects via rules and `@` references. Do not rename `.agent` to `.agents`; keep the Blueprint OS layout. This guide shows how to connect them.
 
 ---
 
@@ -23,6 +23,7 @@ Blueprint OS skills are located in `.agent/skills/`. When the user invokes a ski
 
 ## Available skills
 
+- **Find skills** → `.agent/skills/find-skills/SKILL.md` (pre-installed)
 - **Brainstorming** → `.agent/skills/brainstorming/SKILL.md`
 - **Creating skills** → `.agent/skills/creating-skills/SKILL.md`
 - **Shaping specs** → `.agent/skills/shaping-specs/SKILL.md`
@@ -128,4 +129,4 @@ Run QA after implementation. Run SEC when changes touch auth, API, or sensitive
 - Reference designs and diagrams in `references/` with `@references/checkout-flow.mmd` or `@references/agent-workflow/superpowers-link.md`
 - Brainstorm documents and spec files saved to `specs/` are readable the same way
 - The `.agent/` folder is invisible to most file trees by default — open it explicitly if needed
-- For skills.sh integration, see [skills-sh.md](skills-sh.md)
+- For skills.sh integration, see [skills-sh.md](skills-sh.md). Use `-a antigravity -y --copy` when installing so skills land in `.agent/skills/` as real files. Without `--copy`, the CLI may symlink from `.agents/`, and deleting `.agents` breaks the skill.

package/adapters/skills-sh.md

@@ -1,16 +1,28 @@
 # Using skills.sh with Blueprint OS
 
-[skills.sh](https://skills.sh) is an open registry of reusable agent skills. Skills install directly into `.agent/skills/` — the same directory Blueprint OS uses — so they work together with no extra configuration.
+[skills.sh](https://skills.sh) is an open registry of reusable agent skills. Blueprint OS uses `.agent/skills/` (singular). The skills CLI installs to different paths per agent — use the Antigravity target so skills land in `.agent/skills/` and work with Blueprint OS.
+
+---
+
+## Paths: `.agent` vs `.agents`
+
+The skills CLI uses agent-specific paths. Cursor, Codex, and other "Universal" agents use `.agents/skills/` (plural). Antigravity uses `.agent/skills/` (singular). Blueprint OS uses `.agent/skills/` for all adapters — Cursor reads from there via rules and `@` references, not from `.agents`. Always target Antigravity when installing so skills land in the correct folder.
+
+---
+
+## Symlinks: use `--copy` for Cursor
+
+The CLI defaults to symlinks. One location holds the canonical copy; others point to it. If Cursor is detected, the canonical copy may live in `.agents/`. Deleting `.agents` then breaks the skill in `.agent/`. Use `--copy` so `.agent/skills/` gets real files. You can safely remove `.agents` if the CLI creates it.
 
 ---
 
 ## How it works
 
-```
-npx skills add <owner/repo>
+```bash
+npx skills add <owner/repo> -a antigravity -y --copy
 ```
 
-This command installs one or more skills from a GitHub repo into your project's `.agent/skills/` folder. Installed skills are immediately available to your agent as Blueprint OS skills.
+The `-a antigravity` flag installs to `.agent/skills/`, matching Blueprint OS. The `--copy` flag creates real files (not symlinks) so deleting `.agents` won't break the skill. The `-y` flag skips prompts. Installed skills are immediately available via `@.agent/skills/<skill-name>/SKILL.md`.
 
 Skills.sh supports Cursor, Antigravity, Claude Code, Codex, Cline, Windsurf, and more — the same tools Blueprint OS targets.
 
@@ -21,7 +33,7 @@ Skills.sh supports Cursor, Antigravity, Claude Code, Codex, Cline, Windsurf, and
 **Option 1 — Use the find-skills skill:**
 
 ```bash
-npx skills add https://github.com/vercel-labs/skills --skill find-skills
+npx skills add https://github.com/vercel-labs/skills --skill find-skills -a antigravity -y --copy
 ```
 
 This installs a meta-skill that can search the registry for you. Then ask your agent:
@@ -36,7 +48,7 @@ Visit [skills.sh](https://skills.sh) and search by keyword or browse by category
 
 **Option 3 — Search by GitHub org:**
 
-Many popular tool maintainers publish official skills:
+Many popular tool maintainers publish official skills. Append `-a antigravity -y` for Blueprint OS:
 
 | Publisher | Install command | What's inside |
 |---|---|---|
@@ -53,10 +65,10 @@ Many popular tool maintainers publish official skills:
 
 ```bash
 # Single repo (may contain multiple skills)
-npx skills add supabase/agent-skills
+npx skills add supabase/agent-skills -a antigravity -y --copy
 
 # Install a specific skill by name
-npx skills add obra/superpowers systematic-debugging
+npx skills add obra/superpowers --skill systematic-debugging -a antigravity -y --copy
 ```
 
 Skills land in `.agent/skills/<skill-name>/SKILL.md`. Open them to inspect what was installed.
@@ -105,7 +117,7 @@ If you've built a Blueprint OS skill that others would benefit from, you can pub
 
 1. Push your `.agent/skills/<skill-name>/` folder to a public GitHub repo
 2. Submit your skill at [skills.sh](https://skills.sh) (follow the site's submission process)
-3. Others can then install it with `npx skills add <your-github-username>/<repo>`
+3. Others can then install it with `npx skills add <your-github-username>/<repo> -a antigravity -y --copy`
 
 **Tip:** Structure your repo so each skill is its own folder at the root — that's the convention the `npx skills add` command expects.
 
@@ -117,18 +129,19 @@ These community skills complement Blueprint OS directly:
 
 | Skill | Install | Pairs with |
 |---|---|---|
-| `systematic-debugging` | `npx skills add obra/superpowers` | Any execution phase |
-| `writing-plans` | `npx skills add obra/superpowers` | `shaping-specs` |
-| `executing-plans` | `npx skills add obra/superpowers` | After `deploying-standards` |
-| `requesting-code-review` | `npx skills add obra/superpowers` | After execution |
-| `api-design-principles` | `npx skills add wshobson/agents` | `discovering-standards` for API projects |
-| `test-driven-development` | `npx skills add obra/superpowers` | Before writing new features |
+| `systematic-debugging` | `npx skills add obra/superpowers -a antigravity -y --copy` | Any execution phase |
+| `writing-plans` | `npx skills add obra/superpowers -a antigravity -y --copy` | `shaping-specs` |
+| `executing-plans` | `npx skills add obra/superpowers -a antigravity -y --copy` | After `deploying-standards` |
+| `requesting-code-review` | `npx skills add obra/superpowers -a antigravity -y --copy` | After execution |
+| `api-design-principles` | `npx skills add wshobson/agents -a antigravity -y --copy` | `discovering-standards` for API projects |
+| `test-driven-development` | `npx skills add obra/superpowers -a antigravity -y --copy` | Before writing new features |
 
 ---
 
 ## Notes
 
 - skills.sh skills use the same `SKILL.md` format as Blueprint OS — no conversion needed
+- Always use `-a antigravity -y --copy` when installing. `-a antigravity` puts skills in `.agent/skills/`. `--copy` creates real files (not symlinks) so deleting `.agents` won't break the skill. Without it, the CLI may symlink from `.agents/`, and removing `.agents` breaks `.agent/`
 - If `npx skills add` is not available, clone the repo and copy the skill folder manually into `.agent/skills/`
 - Community skills may not follow all Blueprint OS conventions — review before use
 - Pin to a specific commit if you need a stable, reproducible skill version

package/bin/blueprint-os.js

@@ -1,14 +1,18 @@
 #!/usr/bin/env node
 
-const { init } = require('../lib/init');
+const { init, update } = require('../lib/init');
 
 const [cmd] = process.argv.slice(2);
 
 if (cmd === 'init') {
   init(process.cwd());
+} else if (cmd === 'update') {
+  update(process.cwd());
 } else {
   console.log('Blueprint OS - AI agent workflow system\n');
-  console.log('Usage: npx blueprint-os init');
-  console.log('\nCopies .agent/, standards/, and references/ into your project.');
+  console.log('Usage:');
+  console.log('  npx blueprint-os init    Install or reinstall (preserves standards/references if they have content)');
+  console.log('  npx blueprint-os update   Safe update: refreshes core skills and adapters, preserves your content');
+  console.log('\nUse "npx blueprint-os@latest init" or "npx blueprint-os@latest update" to get the latest version.');
   process.exit(1);
 }

package/lib/init.js

@@ -4,6 +4,40 @@ const path = require('path');
 const PACKAGE_ROOT = path.join(__dirname, '..');
 const FOLDERS = ['.agent', 'standards', 'references', 'adapters'];
 
+const CORE_SKILLS = [
+  'brainstorming',
+  'creating-skills',
+  'shaping-specs',
+  'discovering-standards',
+  'deploying-standards',
+  'quality-assurance',
+  'security-audit',
+  'code-review',
+  'find-skills',
+];
+
+function hasUserContent(dir, packageOnly) {
+  if (!fs.existsSync(dir)) return false;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const e of entries) {
+    const name = e.name;
+    if (e.isDirectory()) {
+      if (!packageOnly.dirs.includes(name)) return true;
+    } else {
+      if (!packageOnly.files.includes(name)) return true;
+    }
+  }
+  return false;
+}
+
+function shouldPreserveStandards(dest) {
+  return hasUserContent(dest, { files: ['README.md'], dirs: [] });
+}
+
+function shouldPreserveReferences(dest) {
+  return hasUserContent(dest, { files: ['README.md'], dirs: ['agent-workflow'] });
+}
+
 function init(cwd) {
   const resolvedCwd = path.resolve(cwd);
   const resolvedRoot = path.resolve(PACKAGE_ROOT);
@@ -25,6 +59,16 @@ function init(cwd) {
       continue;
     }
 
+    if (folder === 'standards' && shouldPreserveStandards(dest)) {
+      console.log(`  ⊘ standards/ (preserved - has project content)`);
+      continue;
+    }
+
+    if (folder === 'references' && shouldPreserveReferences(dest)) {
+      console.log(`  ⊘ references/ (preserved - has project content)`);
+      continue;
+    }
+
     fs.cpSync(src, dest, { recursive: true });
     console.log(`  ✓ ${folder}/`);
   }
@@ -40,4 +84,67 @@ function init(cwd) {
   console.log('  npx blueprint-os --help');
 }
 
-module.exports = { init };
+function update(cwd) {
+  const resolvedCwd = path.resolve(cwd);
+  const resolvedRoot = path.resolve(PACKAGE_ROOT);
+  if (resolvedCwd === resolvedRoot || resolvedCwd.startsWith(resolvedRoot + path.sep)) {
+    console.log('You are inside the Blueprint OS package. Run from your project directory instead:\n');
+    console.log('  cd /path/to/your-project');
+    console.log('  npx blueprint-os update\n');
+    return;
+  }
+
+  const agentDest = path.join(cwd, '.agent', 'skills');
+  if (!fs.existsSync(agentDest)) {
+    console.log('Blueprint OS not found. Run "npx blueprint-os init" first.\n');
+    return;
+  }
+
+  console.log('Updating Blueprint OS...\n');
+
+  const skillsSrc = path.join(PACKAGE_ROOT, '.agent', 'skills');
+  for (const skill of CORE_SKILLS) {
+    const src = path.join(skillsSrc, skill);
+    const dest = path.join(agentDest, skill);
+    if (fs.existsSync(src)) {
+      fs.cpSync(src, dest, { recursive: true });
+      console.log(`  ✓ .agent/skills/${skill}/`);
+    }
+  }
+
+  const adaptersSrc = path.join(PACKAGE_ROOT, 'adapters');
+  const adaptersDest = path.join(cwd, 'adapters');
+  if (fs.existsSync(adaptersSrc)) {
+    fs.cpSync(adaptersSrc, adaptersDest, { recursive: true });
+    console.log('  ✓ adapters/');
+  }
+
+  const refsSrc = path.join(PACKAGE_ROOT, 'references');
+  const refsDest = path.join(cwd, 'references');
+  if (fs.existsSync(refsSrc) && fs.existsSync(refsDest)) {
+    const agentWorkflowSrc = path.join(refsSrc, 'agent-workflow');
+    const agentWorkflowDest = path.join(refsDest, 'agent-workflow');
+    if (fs.existsSync(agentWorkflowSrc)) {
+      fs.cpSync(agentWorkflowSrc, agentWorkflowDest, { recursive: true });
+      console.log('  ✓ references/agent-workflow/');
+    }
+    const refsReadmeSrc = path.join(refsSrc, 'README.md');
+    const refsReadmeDest = path.join(refsDest, 'README.md');
+    if (fs.existsSync(refsReadmeSrc)) {
+      fs.copyFileSync(refsReadmeSrc, refsReadmeDest);
+      console.log('  ✓ references/README.md');
+    }
+  }
+
+  const standardsReadmeSrc = path.join(PACKAGE_ROOT, 'standards', 'README.md');
+  const standardsReadmeDest = path.join(cwd, 'standards', 'README.md');
+  if (fs.existsSync(standardsReadmeSrc) && fs.existsSync(path.dirname(standardsReadmeDest))) {
+    fs.copyFileSync(standardsReadmeSrc, standardsReadmeDest);
+    console.log('  ✓ standards/README.md');
+  }
+
+  console.log('\nDone. Core skills, adapters, and framework references updated.');
+  console.log('Preserved: specs/, your standards files, your references, community skills.');
+}
+
+module.exports = { init, update, CORE_SKILLS };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blueprint-os",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "description": "A portable, tool-agnostic AI agent workflow system built on skills and standards",
   "bin": {
     "blueprint-os": "./bin/blueprint-os.js"