opencodekit 0.13.2 → 0.14.1

package/dist/index.js

@@ -750,7 +750,7 @@ var cac = (name = "") => new CAC(name);
 // package.json
 var package_default = {
   name: "opencodekit",
-  version: "0.13.2",
+  version: "0.14.1",
   description: "CLI tool for bootstrapping and managing OpenCodeKit projects",
   type: "module",
   repository: {
@@ -3765,6 +3765,7 @@ import {
   readdirSync as readdirSync3,
   writeFileSync as writeFileSync4
 } from "node:fs";
+import { homedir, platform } from "node:os";
 import { basename as basename2, dirname, join as join4 } from "node:path";
 import { fileURLToPath } from "node:url";
 var import_picocolors8 = __toESM(require_picocolors(), 1);
@@ -3783,6 +3784,15 @@ var EXCLUDED_FILES = [
   "yarn.lock",
   "pnpm-lock.yaml"
 ];
+function getGlobalConfigDir() {
+  const os = platform();
+  if (os === "win32") {
+    const appData = process.env.APPDATA || process.env.LOCALAPPDATA || join4(homedir(), "AppData", "Roaming");
+    return join4(appData, "opencode");
+  }
+  const xdgConfig = process.env.XDG_CONFIG_HOME || join4(homedir(), ".config");
+  return join4(xdgConfig, "opencode");
+}
 function detectMode(targetDir) {
   const opencodeDir = join4(targetDir, ".opencode");
   if (existsSync4(opencodeDir)) {
@@ -3842,9 +3852,46 @@ async function copyOpenCodeOnly(templateRoot, targetDir) {
 async function initCommand(options = {}) {
   if (process.argv.includes("--quiet"))
     return;
+  oe(import_picocolors8.default.bgCyan(import_picocolors8.default.black(" OpenCodeKit ")));
+  if (options.global) {
+    const globalDir = getGlobalConfigDir();
+    const os = platform();
+    const osName = os === "win32" ? "Windows" : os === "darwin" ? "macOS" : "Linux";
+    f2.info(`Installing to global config (${osName})`);
+    f2.info(`Target: ${import_picocolors8.default.cyan(globalDir)}`);
+    const templateRoot2 = getTemplateRoot();
+    if (!templateRoot2) {
+      f2.error("Template not found. Please reinstall opencodekit.");
+      $e(import_picocolors8.default.red("Failed"));
+      process.exit(1);
+    }
+    if (existsSync4(globalDir) && !options.force) {
+      f2.warn(`Global config already exists at ${globalDir}`);
+      f2.info(`Use ${import_picocolors8.default.cyan("--force")} to overwrite`);
+      $e("Nothing to do");
+      return;
+    }
+    const s2 = de();
+    s2.start("Copying to global config");
+    const opencodeSrc = join4(templateRoot2, ".opencode");
+    if (!existsSync4(opencodeSrc)) {
+      s2.stop("Failed");
+      f2.error("Template .opencode/ not found");
+      $e(import_picocolors8.default.red("Failed"));
+      process.exit(1);
+    }
+    await copyDir(opencodeSrc, globalDir);
+    s2.stop("Done");
+    le(`Global config installed at:
+${globalDir}
+
+This provides default agents, skills, and tools
+for all OpenCode projects on this machine.`, "Global Installation Complete");
+    $e(import_picocolors8.default.green("Ready!"));
+    return;
+  }
   const targetDir = process.cwd();
   const mode = detectMode(targetDir);
-  oe(import_picocolors8.default.bgCyan(import_picocolors8.default.black(" OpenCodeKit ")));
   if (mode === "already-initialized" && !options.force) {
     f2.warn("Already initialized (.opencode/ exists)");
     f2.info(`Use ${import_picocolors8.default.cyan("--force")} to reinitialize`);
@@ -5998,7 +6045,7 @@ var cli = cac("ock");
 cli.option("--verbose", "Enable verbose logging");
 cli.option("--quiet", "Suppress all output");
 cli.version(`${packageVersion}`);
-cli.command("init", "Initialize OpenCodeKit in current directory").option("--force", "Reinitialize even if already exists").option("--beads", "Also initialize .beads/ for multi-agent coordination").action(initCommand);
+cli.command("init", "Initialize OpenCodeKit in current directory").option("--force", "Reinitialize even if already exists").option("--beads", "Also initialize .beads/ for multi-agent coordination").option("--global", "Install to global OpenCode config (~/.config/opencode/)").action(initCommand);
 cli.command("agent [action]", "Manage agents (list, add, view)").action(async (action) => {
   if (!action) {
     console.log(`

package/dist/template/.opencode/AGENTS.md

@@ -20,6 +20,41 @@ Everything else is guidelines, not laws.
 
 If yes → Delegate. If no → Execute directly.
 
+## Question Tool
+
+**Rule**: Use `question` tool to gather user input when interpretation matters.
+
+### When to Use
+
+Use the question tool when ambiguous requests could lead to significantly different implementations—if "add auth" could mean OAuth, JWT, or session-based, ask before building the wrong thing. Use it when multiple valid approaches exist and user preference matters, like choosing between frameworks or patterns. Always ask before destructive operations like deleting branches, resetting hard, or force pushing. When user preferences affect the outcome—naming conventions, file structure, coding style—let them choose. For gathering multiple selections at once, use `multiple: true` to let users pick several options.
+
+### When NOT to Use
+
+Skip the question tool for trivial decisions where any reasonable choice works. If you already have enough context from the conversation, just proceed. When you can make a sensible default, mention what you're doing and continue—don't stop for permission on every small choice. Subagents like explore, scout, and review should never ask questions; they report findings back to the leader agent who decides what to do.
+
+### Question Design
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Auth Type", // Max 12 chars
+      question: "Which authentication approach?",
+      multiple: false, // true for multi-select
+      options: [
+        { label: "JWT (Recommended)", description: "Stateless, scalable" },
+        { label: "Session-based", description: "Traditional, server-side" },
+        { label: "OAuth 2.0", description: "Third-party providers" },
+      ],
+    },
+  ],
+});
+```
+
+** Design Rule**: Use `question` tool to gather user input when interpretation matters.
+
+Put your recommended option first with "(Recommended)" in the label. Keep options to 3-5 choices—more than that overwhelms users. Write short, clear descriptions that explain the tradeoff. Users can always select "Other" to provide custom input, so you don't need to cover every edge case.
+
 ## Anti-Hallucination (The Truth)
 
 - **Check First**: Run `bd show <id>` before starting major work.
@@ -39,18 +74,27 @@ If yes → Delegate. If no → Execute directly.
 
 **Rule**: Always `read` before `edit`.
 
-1.  **LSP (Best)**: `lsp_lsp_document_symbols` (outline), `lsp_lsp_hover` (types), `lsp_lsp_goto_definition`.
-2.  **Structure**: `ast-grep` (Find functions/classes patterns)
-3.  **Search**: `grep` (Find text/TODOs)
-4.  **Files**: `glob` (Find files)
+1.  **LSP (Best)**: `lsp_lsp_document_symbols`, `lsp_lsp_goto_definition`. **Follow [LSP NAVIGATION AVAILABLE] nudges immediately.**
+2.  **Memory**: `memory-search` (Check past learnings), `repo-map` (Understand structure).
+3.  **Structure**: `ast-grep` (Find functions/classes patterns)
+4.  **Search**: `grep` (Find text/TODOs)
+5.  **Files**: `glob` (Find files)
+
+## Active Memory (The Brain)
+
+**Rule**: Use memory proactively, not just when asked.
+
+- **Start**: `memory-search` to find relevant context and code.
+- **Learn**: `observation` to save decisions, patterns, and gotchas.
+- **Act**: If you see an LSP Nudge, execute it. Don't wait.
 
 ## Beads (Task Tracking)
 
 **Leader Only**: `build` and `rush` agents own the DB. Subagents read-only.
 
-- **Start**: `bd_init()` → `bd_claim()`
-- **Work**: `bd_reserve()` (Lock files!) → Edit
-- **Finish**: `bd_done()` → **RESTART SESSION**
+- **Start**: `bd ready` → `bd update <id> --status in_progress`
+- **Work**: `bd-reserve({ paths: [...] })` (Lock files!) → Edit
+- **Finish**: `bd close <id> --reason "..."` → `bd sync` → **RESTART SESSION**
 
 ## Core Constraints
 

package/dist/template/.opencode/README.md

@@ -161,10 +161,106 @@ Plugins run automatically in every session:
 
 - **memory-read** - Load previous context, templates
 - **memory-update** - Save learnings, handoffs
-- **memory-search** - Search across all memory files
-- **observation** - Create structured observations
+- **memory-search** - Search across all memory files (keyword, semantic, hybrid)
+- **memory-index** - Rebuild vector store for semantic search
+- **memory-embed** - Generate embeddings using Ollama
+- **observation** - Create structured observations (auto-embedded)
 - **ast-grep** - Semantic code search/replace (AST-based)
 
+---
+
+## Semantic Memory Setup (Ollama)
+
+Semantic search requires Ollama running locally. Zero API keys needed.
+
+**Model:** `qwen3-embedding:0.6b` (639MB)
+
+- State-of-the-art quality (MTEB #1 for 8B version)
+- Code-aware (optimized for code retrieval)
+- Multilingual (100+ languages including Vietnamese)
+- 32K context, 1024 dimensions
+
+### Installation
+
+**macOS:**
+
+```bash
+brew install ollama
+```
+
+**Linux:**
+
+```bash
+curl -fsSL https://ollama.com/install.sh | sh
+```
+
+**Windows:**
+
+1. Download from https://ollama.com/download/windows
+2. Run the installer
+3. Ollama runs as a background service automatically
+
+### Setup
+
+```bash
+# Start Ollama (macOS/Linux - if not running as service)
+ollama serve
+
+# Pull embedding model (one-time, ~639MB)
+ollama pull qwen3-embedding:0.6b
+
+# Verify
+ollama list  # Should show qwen3-embedding:0.6b
+```
+
+**Linux:**
+
+```bash
+curl -fsSL https://ollama.com/install.sh | sh
+```
+
+**Windows:**
+
+1. Download from https://ollama.com/download/windows
+2. Run the installer
+3. Ollama runs as a background service automatically
+
+### Setup
+
+```bash
+# Start Ollama (macOS/Linux - if not running as service)
+ollama serve
+
+# Pull embedding model (one-time, ~274MB)
+ollama pull nomic-embed-text
+
+# Verify
+ollama list  # Should show nomic-embed-text
+```
+
+### Custom Host (Optional)
+
+If Ollama runs on a different machine:
+
+```bash
+export OLLAMA_HOST=http://192.168.1.100:11434
+```
+
+### Usage
+
+```bash
+# Rebuild vector index (after adding new observations)
+memory-index action=rebuild
+
+# Search with semantic similarity
+memory-search query="authentication patterns" mode=semantic
+
+# Hybrid search (keyword + semantic)
+memory-search query="auth" mode=hybrid
+```
+
+---
+
 ### AST-Grep Usage
 
 Semantic code operations - smarter than regex:

package/dist/template/.opencode/agent/build.md

@@ -62,7 +62,50 @@ Before ANY action on a new request, do two things.
 
 **First, check skills.** If the request matches a skill trigger phrase, invoke that skill immediately. Skills are specialized workflows that handle specific tasks better than manual orchestration. Don't proceed until you've checked.
 
-**Second, classify the request.** Trivial requests (single file, known location) get direct tool use. Explicit requests (specific file and line, clear command) get immediate execution. Exploratory requests ("how does X work?") get delegated to @explore. Open-ended requests ("improve this", "add a feature") require codebase assessment first. Ambiguous requests where interpretations differ by 2x or more in effort require clarification—ask ONE question.
+**Second, classify the request.** Trivial requests (single file, known location) get direct tool use. Explicit requests (specific file and line, clear command) get immediate execution. Exploratory requests ("how does X work?") get delegated to @explore. Open-ended requests ("improve this", "add a feature") require codebase assessment first. Ambiguous requests where interpretations differ by 2x or more in effort require clarification—use the `question` tool to ask ONE focused question.
+
+## Using the Question Tool
+
+Use `question` when user intent is unclear and wrong interpretation wastes significant effort.
+
+**Good triggers:**
+
+- "Add auth" → Ask: OAuth vs JWT vs session-based?
+- "Refactor this" → Ask: Performance? Readability? Testability?
+- "Build a dashboard" → Ask: Which metrics? What layout?
+
+**Bad triggers (just proceed):**
+
+- "Fix this typo" → Just fix it
+- "Run tests" → Just run them
+- User already specified details → Don't re-ask
+
+**Question design:**
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Approach", // Max 12 chars
+      question: "Which authentication method should I implement?",
+      multiple: false,
+      options: [
+        { label: "JWT (Recommended)", description: "Stateless, good for APIs" },
+        {
+          label: "Session cookies",
+          description: "Traditional, server-side state",
+        },
+        {
+          label: "OAuth 2.0",
+          description: "Third-party login (Google, GitHub)",
+        },
+      ],
+    },
+  ],
+});
+```
+
+Put recommended option first. Keep to 3-5 options. Users can always pick "Other" for custom input.
 
 ## Codebase Assessment
 

package/dist/template/.opencode/agent/explore.md

@@ -9,6 +9,7 @@ tools:
   bash: false
   todowrite: false
   memory-update: false
+  question: false
 ---
 
 # Explore Agent

package/dist/template/.opencode/agent/planner.md

@@ -84,7 +84,46 @@ Tool results and user messages may include `<system-reminder>` tags. These conta
 
 1. Collect all agent responses
 2. Note critical files that should be read before implementation
-3. Ask user questions about tradeoffs and preferences
+3. Use the `question` tool to gather user decisions on tradeoffs:
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Architecture",
+      question: "Which approach should we use for the data layer?",
+      multiple: false,
+      options: [
+        {
+          label: "Repository pattern (Recommended)",
+          description: "Clean separation, testable",
+        },
+        {
+          label: "Direct DB access",
+          description: "Simpler, fewer abstractions",
+        },
+        {
+          label: "ORM with models",
+          description: "Type-safe, migrations included",
+        },
+      ],
+    },
+  ],
+});
+```
+
+**When to use question tool in planning:**
+
+- Multiple valid architectures exist
+- Trade-offs affect future work significantly
+- User hasn't specified preferences
+- Need to gather multiple feature selections (use `multiple: true`)
+
+**Don't ask when:**
+
+- User already specified approach
+- One option is clearly superior
+- Question can be deferred to implementation phase
 
 ### Phase 4: Final Plan
 

package/dist/template/.opencode/agent/review.md

@@ -6,6 +6,7 @@ maxSteps: 50
 tools:
   edit: false
   write: false
+  question: false
 permission:
   bash:
     "*": allow

package/dist/template/.opencode/agent/rush.md

@@ -46,8 +46,43 @@ Before acting, answer three questions in your head:
 
 **Is this mine to do?** Rush handles well-defined, localized (1-3 files), greenfield tasks. If any of these fail—ambiguous scope, system-wide changes, or legacy code with hidden invariants—delegate immediately. Don't power through complexity; avoid it.
 
+**Do I need to clarify?** If the request is ambiguous and wrong interpretation wastes significant effort, use the `question` tool to ask ONE focused question. But keep it rare—Rush moves fast. If you're unsure, delegate to @build who handles complexity better.
+
 **Do I need to read first?** If you're about to edit a file you haven't seen, stop. Read it. Never speculate about uninspected code.
 
+## Using the Question Tool (Sparingly)
+
+Rush uses questions rarely—only when wrong interpretation would waste significant effort AND the task is still small enough for Rush.
+
+**Good triggers (still ask fast):**
+
+- "Delete this" → Ask: Which files/branches specifically?
+- "Rename X" → Ask: New name preference?
+- Binary choice that user must decide
+
+**Bad triggers (delegate instead):**
+
+- "Add auth" → Too complex for Rush, delegate to @build
+- Multiple design decisions → Delegate to @planner
+- Research needed → Delegate to @scout
+
+**If you need to ask more than ONE question, the task is too complex for Rush. Delegate.**
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Confirm",
+      question: "Delete feature/old-auth branch?",
+      options: [
+        { label: "Yes, delete it", description: "Removes remote and local" },
+        { label: "No, keep it", description: "Abort operation" },
+      ],
+    },
+  ],
+});
+```
+
 ## Bail Triggers
 
 Delegate immediately when you hit any of these:

package/dist/template/.opencode/agent/scout.md

@@ -8,6 +8,7 @@ tools:
   write: false
   bash: false
   memory-update: false
+  question: false
 ---
 
 # Scout Agent

package/dist/template/.opencode/command/brainstorm.md

@@ -33,12 +33,35 @@ If `$ARGUMENTS` is a bead ID:
 
 Load constraints from `.beads/artifacts/<bead-id>/spec.md` if it exists.
 
-**Check for prior thinking:**
+**Check for prior thinking (Semantic Search):**
 
 ```typescript
-memory - search({ query: "[topic keywords]" });
+// Search for related ideas and past brainstorms
+memory -
+  search({
+    query: "[topic keywords]",
+    mode: "semantic",
+    limit: 5,
+  });
+
+// Find related observations
+memory -
+  search({
+    query: "[topic]",
+    mode: "semantic",
+    type: "observation",
+    limit: 3,
+  });
 ```
 
+Review findings for:
+
+- Previous brainstorms on similar topics
+- Related decisions and patterns
+- Ideas that were considered before
+
+If memory search fails (Ollama not running), continue without it.
+
 ## Phase 2: Set Boundaries
 
 Before brainstorming, establish:
@@ -252,7 +275,56 @@ bd create "[Idea name]" -t task -p 2
 
 ## Output
 
+```markdown
+Brainstorm Complete: $ARGUMENTS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Duration: [N] minutes
+Ideas generated: [N]
+Ideas evaluated: [N]
+
+Top 3:
+
+1. [Idea 1] - Score: [N]
+2. [Idea 2] - Score: [N]
+3. [Idea 3] - Score: [N]
+
+Recommendation: [Chosen approach]
+Confidence: [High/Medium/Low]
+
+Artifacts:
+
+- .beads/artifacts/<bead-id>/brainstorm.md (if bead)
+- Observation created ✓
+
+Follow-up beads: [N] created
+```
+
+**Use question tool for next steps:**
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Next Step",
+      question: "What should we do next with $ARGUMENTS?",
+      options: [
+        {
+          label: "Research approach (Recommended)",
+          description: "Validate with /research",
+        },
+        { label: "Create implementation plan", description: "Plan with /plan" },
+        {
+          label: "Explore more",
+          description: "Continue brainstorming other aspects",
+        },
+        { label: "Done for now", description: "Save findings, revisit later" },
+      ],
+    },
+  ],
+});
 ```
+
 Brainstorm Complete: $ARGUMENTS
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
@@ -261,6 +333,7 @@ Ideas generated: [N]
 Ideas evaluated: [N]
 
 Top 3:
+
 1. [Idea 1] - Score: [N]
 2. [Idea 2] - Score: [N]
 3. [Idea 3] - Score: [N]
@@ -269,21 +342,25 @@ Recommendation: [Chosen approach]
 Confidence: [High/Medium/Low]
 
 Artifacts:
+
 - .beads/artifacts/<bead-id>/brainstorm.md (if bead)
 - Observation created ✓
 
 Follow-up beads: [N] created
+
 ```
 
 **Next steps:**
 
 ```
+
 If ready to proceed:
-  /research <bead-id>   # Validate approach
-  /plan <bead-id>       # Create implementation plan
+/research <bead-id> # Validate approach
+/plan <bead-id> # Create implementation plan
 
 If need more exploration:
-  /brainstorm <new-aspect>   # Continue ideation
+/brainstorm <new-aspect> # Continue ideation
+
 ```
 
 ## Anti-Patterns
@@ -293,3 +370,4 @@ If need more exploration:
 - ❌ **Infinite brainstorming** - Time box and decide
 - ❌ **No decision** - Brainstorming must produce a recommendation
 - ❌ **No capture** - Undocumented ideas are lost ideas
+```

package/dist/template/.opencode/command/finish.md

@@ -116,17 +116,27 @@ git commit -m "$ARGUMENTS: [what was done]
 Closes: $ARGUMENTS"
 ```
 
-## Close The Task (Ask First)
+## Close The Task (Use Question Tool)
 
-**Ask the user:**
-
-```
-Close bead $ARGUMENTS?
-- Yes, close it
-- No, keep it open for now
+```typescript
+question({
+  questions: [
+    {
+      header: "Close",
+      question: "Should I close bead $ARGUMENTS?",
+      options: [
+        {
+          label: "Yes, close it (Recommended)",
+          description: "All gates passed, task complete",
+        },
+        { label: "No, keep open", description: "Need more work or review" },
+      ],
+    },
+  ],
+});
 ```
 
-If user confirms:
+If user confirms close:
 
 ```bash
 bd close $ARGUMENTS --reason "Completed: [1-line summary]"
@@ -166,17 +176,34 @@ Write `.beads/artifacts/$ARGUMENTS/review.md`:
 
 ## Record Learnings
 
-If you discovered patterns or gotchas worth remembering:
+If you discovered patterns, gotchas, or decisions worth remembering:
 
 ```typescript
 observation({
-  type: "learning",
-  title: "[concise title]",
-  content: "[what you learned]",
+  type: "learning", // or "pattern", "bugfix", "decision", "warning"
+  title: "[concise, searchable title]",
+  content: "[what you learned - be specific and actionable]",
   bead_id: "$ARGUMENTS",
+  files: "[affected files, comma-separated]",
+  concepts: "[keywords for semantic search]",
 });
 ```
 
+**This auto-embeds into the vector store** for future semantic search. Future `/start` and `/implement` commands will find this learning.
+
+**When to create observations:**
+
+- Discovered a non-obvious gotcha
+- Made a significant architectural decision
+- Found a pattern worth reusing
+- Hit a bug that others might hit
+
+**Skip observations for:**
+
+- Routine implementations
+- Well-documented patterns
+- Trivial fixes
+
 ## Output
 
 ```