@orderful/droid 0.28.1 → 0.29.0

package/.claude-plugin/marketplace.json

@@ -8,8 +8,8 @@
   "plugins": [
     {
       "name": "droid",
-      "description": "Core droid meta-skill for update awareness and tool discovery. Checks for updates and helps users find the right tools.",
-      "version": "0.4.0",
+      "description": "Core droid meta-skill for update awareness, tool discovery, and usage help. Checks for updates, helps users find tools, and answers 'how do I...' questions about droid workflows.",
+      "version": "0.5.0",
       "source": {
         "source": "github",
         "repo": "orderful/droid",

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @orderful/droid
 
+## 0.29.0
+
+### Minor Changes
+
+- [#170](https://github.com/Orderful/droid/pull/170) [`8e2b62f`](https://github.com/Orderful/droid/commit/8e2b62f773aeca43dc1dac511dfff1587b2b29c8) Thanks [@frytyler](https://github.com/frytyler)! - Add usage guides and automatic update notifications to droid
+
+  **Usage guides:** The droid skill now answers common workflow questions like:
+  - "How do I add context to my thread?"
+  - "Remind me the tools you have"
+  - "How do I find something in the codex?"
+  - "What's the best way to start a session?"
+
+  Includes guides for: starting sessions right, loading project context, searching codex, planning before implementing, using comments for async work, coach mode, and code review.
+
+  **Update notifications:** New `droid-bootstrap` skill with `alwaysApply: true` checks for droid updates once per session and shows a notification if a newer version is available. Lightweight (~20 lines) to minimize context overhead.
+
 ## 0.28.1
 
 ### Patch Changes

package/dist/bin/droid.js

@@ -1024,6 +1024,36 @@ function updateSkill(skillName) {
   }
   return result;
 }
+function updateAllSkills() {
+  const config = loadConfig();
+  const tools = getPlatformTools(config);
+  const result = {
+    updated: [],
+    failed: [],
+    upToDate: 0
+  };
+  for (const skillName of Object.keys(tools)) {
+    const status = getSkillUpdateStatus(skillName);
+    if (!status.hasUpdate) {
+      result.upToDate++;
+      continue;
+    }
+    const updateResult = updateSkill(skillName);
+    if (updateResult.success) {
+      result.updated.push({
+        name: skillName,
+        from: status.installedVersion,
+        to: status.bundledVersion
+      });
+    } else {
+      result.failed.push({
+        name: skillName,
+        error: updateResult.message
+      });
+    }
+  }
+  return result;
+}
 function installSkill(skillName) {
   const config = loadConfig();
   const skillPath = findSkillPath(skillName);
@@ -1833,12 +1863,23 @@ async function updateCommand(tool, options) {
     return;
   }
   if (options?.tools) {
-    console.log(chalk8.yellow("\n\u26A0 Tool-only updates not implemented yet"));
-    console.log(
-      chalk8.gray(
-        "Tools are bundled with the CLI - run `droid update` to update all."
-      )
-    );
+    console.log(chalk8.bold("\n\u{1F916} Syncing tools...\n"));
+    const result = updateAllSkills();
+    if (result.updated.length > 0) {
+      console.log(chalk8.green("\u2713 Updated:"));
+      for (const skill of result.updated) {
+        console.log(chalk8.gray(`  ${skill.name}: ${skill.from} \u2192 ${skill.to}`));
+      }
+    }
+    if (result.failed.length > 0) {
+      console.log(chalk8.red("\n\u2717 Failed:"));
+      for (const skill of result.failed) {
+        console.log(chalk8.gray(`  ${skill.name}: ${skill.error}`));
+      }
+    }
+    if (result.updated.length === 0 && result.failed.length === 0) {
+      console.log(chalk8.green("\u2713 All tools up to date"));
+    }
     return;
   }
   console.log(chalk8.bold("\n\u{1F916} Updating Droid...\n"));

package/dist/commands/update.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../src/commands/update.ts"],"names":[],"mappings":"AAIA,UAAU,aAAa;IACrB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,wBAAsB,aAAa,CACjC,IAAI,CAAC,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,IAAI,CAAC,CA6Df"}
+{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../src/commands/update.ts"],"names":[],"mappings":"AAKA,UAAU,aAAa;IACrB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,wBAAsB,aAAa,CACjC,IAAI,CAAC,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,IAAI,CAAC,CA6Ef"}

package/dist/tools/droid/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "droid",
-  "version": "0.4.0",
-  "description": "Core droid meta-skill for update awareness and tool discovery. Checks for updates and helps users find the right tools.",
+  "version": "0.5.0",
+  "description": "Core droid meta-skill for update awareness, tool discovery, and usage help. Checks for updates, helps users find tools, and answers 'how do I...' questions about droid workflows.",
   "author": {
     "name": "Orderful",
     "url": "https://github.com/orderful"

package/dist/tools/droid/TOOL.yaml

@@ -1,6 +1,6 @@
 name: droid
-description: "Core droid meta-skill for update awareness and tool discovery. Checks for updates and helps users find the right tools."
-version: 0.4.0
+description: "Core droid meta-skill for update awareness, tool discovery, and usage help. Checks for updates, helps users find tools, and answers 'how do I...' questions about droid workflows."
+version: 0.5.0
 status: beta
 
 # System tool - always stays current regardless of auto-update settings
@@ -10,6 +10,8 @@ includes:
   skills:
     - name: droid
       required: true
+    - name: droid-bootstrap
+      required: true
   commands: []
   agents: []
 

package/dist/tools/droid/skills/droid/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: droid
-description: "Core droid meta-skill for updates and tool discovery. Use when checking for droid updates or discovering available tools. User prompts like 'any droid updates?', 'what tools do I have?', 'is droid up to date?'."
+description: "Core droid meta-skill for updates, tool discovery, and usage help. Use when checking for droid updates, discovering available tools, or answering 'how do I...' questions about droid workflows. User prompts like 'any droid updates?', 'what tools do I have?', 'how do I add context?', 'remind me how to use codex', 'what's the best way to start a session?'."
 globs:
   - "**/*"
 alwaysApply: false
@@ -9,7 +9,7 @@ allowed-tools: [Bash]
 
 # Droid
 
-Core meta-skill for droid update awareness and tool discovery.
+Core meta-skill for droid update awareness, tool discovery, and usage guidance.
 
 ## Purpose
 
@@ -240,3 +240,214 @@ Run `droid install <tool>` or just `droid` to browse and install.
 
 They work well together: research in brain docs, capture decisions in project files.
 ```
+
+---
+
+## Usage Guides
+
+When users ask "how do I..." questions about droid workflows, use these guides.
+
+### Starting a Session Right
+
+**User asks:** "How do I add context?", "How do I start a session?", "Remind me how to set up context"
+
+**Answer:**
+
+```
+[● ●] Great question! Starting with context makes everything better.
+
+**Option 1: Load project context**
+`/project {name}` - Loads your project file with goals, decisions, and current work.
+
+**Option 2: Load shared knowledge**
+`/codex search {topic}` - Find relevant PRDs, tech designs, or patterns from the codex.
+
+**Option 3: Both**
+Start with `/project` for your working context, then `/codex search` if you need org knowledge.
+
+**Pro tip:** Context at the start of a thread beats adding it mid-conversation.
+```
+
+### Finding Things in the Codex
+
+**User asks:** "How do I find something in the codex?", "How do I search codex?"
+
+**Answer:**
+
+```
+[● ●] Use `/codex search {keywords}` to find content across the codex.
+
+Examples:
+- `/codex search webhooks` - Find docs mentioning webhooks
+- `/codex search partnership automation` - Find the partnership automation PRD
+- `/codex search error handling patterns` - Find relevant patterns
+
+The search looks across PRDs, tech designs, patterns, and explored topics.
+```
+
+### Loading Project Context
+
+**User asks:** "How do I load my project?", "How does project work?"
+
+**Answer:**
+
+```
+[● ●] Use `/project {name}` to load a project file.
+
+Examples:
+- `/project transaction-templates` - Load the transaction templates project
+- `/project droid` - Load the droid project context
+
+**What it gives me:**
+- Project goals and background
+- Key technical decisions and rationale
+- Current work in progress
+- Relevant code locations
+
+**Pro tip:** Load your project at the start of each session. I'll have full context immediately.
+```
+
+### Planning Before Implementing
+
+**User asks:** "How do I plan something?", "Should I plan first?"
+
+**Answer:**
+
+```
+[● ●] Yes! Planning before implementing helps me help you better.
+
+**Option 1: Brain doc (async, iterative)**
+`/brain plan {topic}` - Creates a planning doc you can iterate on with @mentions.
+
+**Option 2: Tech design (larger features)**
+`/tech-design {feature}` - For features that need research, alternatives, and rollout plans.
+
+**Why plan?**
+- I understand the full scope before writing code
+- We catch issues early, not mid-implementation
+- The plan becomes documentation
+```
+
+### Using Comments for Async Work
+
+**User asks:** "How do comments work?", "How do I leave notes for the AI?"
+
+**Answer:**
+
+```
+[● ●] Use @mentions to have async conversations in any file.
+
+**Leave a question:**
+Add `> @droid why is this pattern used here?` in a comment
+
+**Check for questions:**
+`/comments check` - I'll find and respond to all @droid mentions
+
+**Clean up:**
+`/comments cleanup` - Remove resolved comment threads
+
+Works great for code review notes and async collaboration.
+```
+
+### Learning vs Velocity Mode
+
+**User asks:** "What's coach mode?", "How do I learn instead of just getting answers?"
+
+**Answer:**
+
+```
+[● ●] Use `/coach` when you want to learn, not just ship.
+
+**Normal mode:** I implement for you (fast, but you don't learn)
+**Coach mode:** I guide you to implement yourself (slower, but you grow)
+
+Examples:
+- `/coach plan auth-refactor` - I'll ask questions to help YOU design it
+- `/coach review my-code.ts` - I'll ask Socratic questions, not give answers
+
+Good for: learning new codebases, building skills, understanding deeply.
+```
+
+### Code Review
+
+**User asks:** "How do I get a code review?", "Can you review my changes?"
+
+**Answer:**
+
+```
+[● ●] Use `/code-review` to review code with specialized agents.
+
+Examples:
+- `/code-review` - Review staged changes
+- `/code-review --pr 123` - Review a specific PR
+- `/code-review src/auth/` - Review specific files
+
+**What I check:**
+- Error handling and edge cases
+- Test coverage gaps
+- Type safety issues
+- EDI/partnership patterns (if applicable)
+
+Each finding has a confidence score so you can prioritize.
+```
+
+### Quick Reference
+
+| Question | Answer |
+|----------|--------|
+| "Add context to my thread" | `/project {name}` or `/codex search {topic}` |
+| "Find something in the codex" | `/codex search {keywords}` |
+| "Start planning" | `/brain plan {topic}` or `/tech-design {feature}` |
+| "Leave a note for AI" | Add `> @droid {question}` then `/comments check` |
+| "Learn instead of copy-paste" | `/coach {command}` |
+| "Review my code" | `/code-review` |
+| "Capture a decision" | `/codex decision {summary}` |
+| "Update project context" | `/project update` |
+
+### Example Dialogue
+
+**User:** "Hey droid, remind me the tools you have"
+
+```
+[● ●] Here's what you have installed:
+
+**Context loading:**
+- `/project {name}` - Load your project's working context
+- `/codex search {topic}` - Find shared knowledge (PRDs, tech designs, patterns)
+
+**Planning & thinking:**
+- `/brain plan {topic}` - Create a planning scratchpad
+- `/tech-design {feature}` - Design larger features
+
+**Collaboration:**
+- `/comments check` - Respond to @droid mentions
+- `/code-review` - Get AI code review with specialized agents
+
+**Learning:**
+- `/coach` - AI as guide, not implementer
+
+**Pro tip:** Start threads with `/project` or `/codex search` for best results.
+```
+
+**User:** "How should I approach this new feature?"
+
+```
+[● ●] Here's my suggested workflow:
+
+1. **Load context first**
+   `/project {your-project}` - So I know the codebase
+   `/codex search {related-topic}` - For any relevant patterns
+
+2. **Plan before coding**
+   `/brain plan {feature}` - Sketch out the approach
+   Iterate with @droid/@{you} comments until it feels right
+
+3. **Implement with context**
+   Now I have full context - ask me to implement
+
+4. **Review before shipping**
+   `/code-review` - Catch issues before PR
+
+5. **Capture learnings**
+   `/project update` - Save decisions for next session
+```

package/dist/tools/droid/skills/droid-bootstrap/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: droid-bootstrap
+description: "Lightweight droid bootstrap for update awareness. Checks for droid updates once per session."
+globs: []
+alwaysApply: true
+allowed-tools: [Bash]
+---
+
+# Droid Bootstrap
+
+**Once per session**, check if a droid update is available.
+
+## Update Check
+
+Get latest version from npm (timeout 3s, fail silently):
+
+```bash
+timeout 3 npm view @orderful/droid version 2>/dev/null
+```
+
+Get installed version:
+
+```bash
+droid --version
+```
+
+If a newer version exists, ask the user:
+
+```
+[● ●] Droid v{latest} is available (you have v{current}).
+Would you like me to update now?
+```
+
+If user says yes, run these commands:
+
+```bash
+droid update && droid update --tools
+```
+
+The first command updates the npm package, the second syncs skill files to the install location. After updating, tell the user to restart their AI tool (Claude Code/OpenCode) to load the new skills.
+
+If user declines, continue with their request. Don't ask again this session.
+
+If the check fails (network issues, timeout), skip silently.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orderful/droid",
-  "version": "0.28.1",
+  "version": "0.29.0",
   "description": "AI workflow toolkit for sharing skills, commands, and agents across the team",
   "type": "module",
   "bin": {

package/src/commands/update.ts

@@ -1,6 +1,7 @@
 import chalk from 'chalk';
 import { execSync } from 'child_process';
 import { getVersion } from '../lib/version';
+import { updateAllSkills } from '../lib/skills';
 
 interface UpdateOptions {
   tools?: boolean;
@@ -22,14 +23,30 @@ export async function updateCommand(
     return;
   }
 
-  // If --tools flag, update tools only
+  // If --tools flag, sync skills from bundled package to install location
   if (options?.tools) {
-    console.log(chalk.yellow('\n⚠ Tool-only updates not implemented yet'));
-    console.log(
-      chalk.gray(
-        'Tools are bundled with the CLI - run `droid update` to update all.',
-      ),
-    );
+    console.log(chalk.bold('\n🤖 Syncing tools...\n'));
+
+    const result = updateAllSkills();
+
+    if (result.updated.length > 0) {
+      console.log(chalk.green('✓ Updated:'));
+      for (const skill of result.updated) {
+        console.log(chalk.gray(`  ${skill.name}: ${skill.from} → ${skill.to}`));
+      }
+    }
+
+    if (result.failed.length > 0) {
+      console.log(chalk.red('\n✗ Failed:'));
+      for (const skill of result.failed) {
+        console.log(chalk.gray(`  ${skill.name}: ${skill.error}`));
+      }
+    }
+
+    if (result.updated.length === 0 && result.failed.length === 0) {
+      console.log(chalk.green('✓ All tools up to date'));
+    }
+
     return;
   }
 

package/src/tools/droid/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "droid",
-  "version": "0.4.0",
-  "description": "Core droid meta-skill for update awareness and tool discovery. Checks for updates and helps users find the right tools.",
+  "version": "0.5.0",
+  "description": "Core droid meta-skill for update awareness, tool discovery, and usage help. Checks for updates, helps users find tools, and answers 'how do I...' questions about droid workflows.",
   "author": {
     "name": "Orderful",
     "url": "https://github.com/orderful"

package/src/tools/droid/TOOL.yaml

@@ -1,6 +1,6 @@
 name: droid
-description: "Core droid meta-skill for update awareness and tool discovery. Checks for updates and helps users find the right tools."
-version: 0.4.0
+description: "Core droid meta-skill for update awareness, tool discovery, and usage help. Checks for updates, helps users find tools, and answers 'how do I...' questions about droid workflows."
+version: 0.5.0
 status: beta
 
 # System tool - always stays current regardless of auto-update settings
@@ -10,6 +10,8 @@ includes:
   skills:
     - name: droid
       required: true
+    - name: droid-bootstrap
+      required: true
   commands: []
   agents: []
 

package/src/tools/droid/skills/droid/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: droid
-description: "Core droid meta-skill for updates and tool discovery. Use when checking for droid updates or discovering available tools. User prompts like 'any droid updates?', 'what tools do I have?', 'is droid up to date?'."
+description: "Core droid meta-skill for updates, tool discovery, and usage help. Use when checking for droid updates, discovering available tools, or answering 'how do I...' questions about droid workflows. User prompts like 'any droid updates?', 'what tools do I have?', 'how do I add context?', 'remind me how to use codex', 'what's the best way to start a session?'."
 globs:
   - "**/*"
 alwaysApply: false
@@ -9,7 +9,7 @@ allowed-tools: [Bash]
 
 # Droid
 
-Core meta-skill for droid update awareness and tool discovery.
+Core meta-skill for droid update awareness, tool discovery, and usage guidance.
 
 ## Purpose
 
@@ -240,3 +240,214 @@ Run `droid install <tool>` or just `droid` to browse and install.
 
 They work well together: research in brain docs, capture decisions in project files.
 ```
+
+---
+
+## Usage Guides
+
+When users ask "how do I..." questions about droid workflows, use these guides.
+
+### Starting a Session Right
+
+**User asks:** "How do I add context?", "How do I start a session?", "Remind me how to set up context"
+
+**Answer:**
+
+```
+[● ●] Great question! Starting with context makes everything better.
+
+**Option 1: Load project context**
+`/project {name}` - Loads your project file with goals, decisions, and current work.
+
+**Option 2: Load shared knowledge**
+`/codex search {topic}` - Find relevant PRDs, tech designs, or patterns from the codex.
+
+**Option 3: Both**
+Start with `/project` for your working context, then `/codex search` if you need org knowledge.
+
+**Pro tip:** Context at the start of a thread beats adding it mid-conversation.
+```
+
+### Finding Things in the Codex
+
+**User asks:** "How do I find something in the codex?", "How do I search codex?"
+
+**Answer:**
+
+```
+[● ●] Use `/codex search {keywords}` to find content across the codex.
+
+Examples:
+- `/codex search webhooks` - Find docs mentioning webhooks
+- `/codex search partnership automation` - Find the partnership automation PRD
+- `/codex search error handling patterns` - Find relevant patterns
+
+The search looks across PRDs, tech designs, patterns, and explored topics.
+```
+
+### Loading Project Context
+
+**User asks:** "How do I load my project?", "How does project work?"
+
+**Answer:**
+
+```
+[● ●] Use `/project {name}` to load a project file.
+
+Examples:
+- `/project transaction-templates` - Load the transaction templates project
+- `/project droid` - Load the droid project context
+
+**What it gives me:**
+- Project goals and background
+- Key technical decisions and rationale
+- Current work in progress
+- Relevant code locations
+
+**Pro tip:** Load your project at the start of each session. I'll have full context immediately.
+```
+
+### Planning Before Implementing
+
+**User asks:** "How do I plan something?", "Should I plan first?"
+
+**Answer:**
+
+```
+[● ●] Yes! Planning before implementing helps me help you better.
+
+**Option 1: Brain doc (async, iterative)**
+`/brain plan {topic}` - Creates a planning doc you can iterate on with @mentions.
+
+**Option 2: Tech design (larger features)**
+`/tech-design {feature}` - For features that need research, alternatives, and rollout plans.
+
+**Why plan?**
+- I understand the full scope before writing code
+- We catch issues early, not mid-implementation
+- The plan becomes documentation
+```
+
+### Using Comments for Async Work
+
+**User asks:** "How do comments work?", "How do I leave notes for the AI?"
+
+**Answer:**
+
+```
+[● ●] Use @mentions to have async conversations in any file.
+
+**Leave a question:**
+Add `> @droid why is this pattern used here?` in a comment
+
+**Check for questions:**
+`/comments check` - I'll find and respond to all @droid mentions
+
+**Clean up:**
+`/comments cleanup` - Remove resolved comment threads
+
+Works great for code review notes and async collaboration.
+```
+
+### Learning vs Velocity Mode
+
+**User asks:** "What's coach mode?", "How do I learn instead of just getting answers?"
+
+**Answer:**
+
+```
+[● ●] Use `/coach` when you want to learn, not just ship.
+
+**Normal mode:** I implement for you (fast, but you don't learn)
+**Coach mode:** I guide you to implement yourself (slower, but you grow)
+
+Examples:
+- `/coach plan auth-refactor` - I'll ask questions to help YOU design it
+- `/coach review my-code.ts` - I'll ask Socratic questions, not give answers
+
+Good for: learning new codebases, building skills, understanding deeply.
+```
+
+### Code Review
+
+**User asks:** "How do I get a code review?", "Can you review my changes?"
+
+**Answer:**
+
+```
+[● ●] Use `/code-review` to review code with specialized agents.
+
+Examples:
+- `/code-review` - Review staged changes
+- `/code-review --pr 123` - Review a specific PR
+- `/code-review src/auth/` - Review specific files
+
+**What I check:**
+- Error handling and edge cases
+- Test coverage gaps
+- Type safety issues
+- EDI/partnership patterns (if applicable)
+
+Each finding has a confidence score so you can prioritize.
+```
+
+### Quick Reference
+
+| Question | Answer |
+|----------|--------|
+| "Add context to my thread" | `/project {name}` or `/codex search {topic}` |
+| "Find something in the codex" | `/codex search {keywords}` |
+| "Start planning" | `/brain plan {topic}` or `/tech-design {feature}` |
+| "Leave a note for AI" | Add `> @droid {question}` then `/comments check` |
+| "Learn instead of copy-paste" | `/coach {command}` |
+| "Review my code" | `/code-review` |
+| "Capture a decision" | `/codex decision {summary}` |
+| "Update project context" | `/project update` |
+
+### Example Dialogue
+
+**User:** "Hey droid, remind me the tools you have"
+
+```
+[● ●] Here's what you have installed:
+
+**Context loading:**
+- `/project {name}` - Load your project's working context
+- `/codex search {topic}` - Find shared knowledge (PRDs, tech designs, patterns)
+
+**Planning & thinking:**
+- `/brain plan {topic}` - Create a planning scratchpad
+- `/tech-design {feature}` - Design larger features
+
+**Collaboration:**
+- `/comments check` - Respond to @droid mentions
+- `/code-review` - Get AI code review with specialized agents
+
+**Learning:**
+- `/coach` - AI as guide, not implementer
+
+**Pro tip:** Start threads with `/project` or `/codex search` for best results.
+```
+
+**User:** "How should I approach this new feature?"
+
+```
+[● ●] Here's my suggested workflow:
+
+1. **Load context first**
+   `/project {your-project}` - So I know the codebase
+   `/codex search {related-topic}` - For any relevant patterns
+
+2. **Plan before coding**
+   `/brain plan {feature}` - Sketch out the approach
+   Iterate with @droid/@{you} comments until it feels right
+
+3. **Implement with context**
+   Now I have full context - ask me to implement
+
+4. **Review before shipping**
+   `/code-review` - Catch issues before PR
+
+5. **Capture learnings**
+   `/project update` - Save decisions for next session
+```

package/src/tools/droid/skills/droid-bootstrap/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: droid-bootstrap
+description: "Lightweight droid bootstrap for update awareness. Checks for droid updates once per session."
+globs: []
+alwaysApply: true
+allowed-tools: [Bash]
+---
+
+# Droid Bootstrap
+
+**Once per session**, check if a droid update is available.
+
+## Update Check
+
+Get latest version from npm (timeout 3s, fail silently):
+
+```bash
+timeout 3 npm view @orderful/droid version 2>/dev/null
+```
+
+Get installed version:
+
+```bash
+droid --version
+```
+
+If a newer version exists, ask the user:
+
+```
+[● ●] Droid v{latest} is available (you have v{current}).
+Would you like me to update now?
+```
+
+If user says yes, run these commands:
+
+```bash
+droid update && droid update --tools
+```
+
+The first command updates the npm package, the second syncs skill files to the install location. After updating, tell the user to restart their AI tool (Claude Code/OpenCode) to load the new skills.
+
+If user declines, continue with their request. Don't ask again this session.
+
+If the check fails (network issues, timeout), skip silently.