opencodekit 0.18.0 → 0.18.2

package/dist/template/.opencode/skill/memory-system/SKILL.md

@@ -1,11 +1,45 @@
 ---
 name: memory-system
 description: Use when persisting learnings, loading previous context, or searching past decisions - covers memory file structure, tools, and when to update each file
+version: 1.0.0
+tags: [context, workflow]
+dependencies: []
 ---
 
 # Memory System Best Practices
 
-Persistent context that survives across sessions. Uses **SQLite + FTS5** for searchable observations.
+## When to Use
+
+- Starting work and needing to recall prior decisions, bugs, or patterns
+- Recording non-obvious learnings or decisions for future sessions
+
+## When NOT to Use
+
+- For ephemeral notes that won't matter beyond the current session
+- When you need to change actual markdown files (use read/write), not SQLite memory entries
+
+
+## Architecture
+
+```
+message.part.updated → capture.ts → temporal_messages
+                                        ↓ (session.idle, 10+ messages)
+                                     distill.ts → distillations (TF-IDF + key sentences)
+                                        ↓ (session.idle)
+                                     curator.ts → observations (pattern-matched)
+                                        ↓
+system.transform ← inject.ts ← FTS5 search → scored + packed → system prompt
+messages.transform ← context.ts → token budget enforcement
+```
+
+### 4 Tiers
+
+| Tier              | Storage       | Populated By        | Purpose                         |
+| ----------------- | ------------- | ------------------- | ------------------------------- |
+| temporal_messages | SQLite        | Automatic (capture) | Raw message text, 180-day TTL   |
+| distillations     | SQLite + FTS5 | Automatic (idle)    | TF-IDF compressed sessions      |
+| observations      | SQLite + FTS5 | Manual + curator    | Decisions, bugs, patterns, etc. |
+| memory_files      | SQLite        | Manual              | Static docs, handoffs, research |
 
 ## Core Principle
 
@@ -23,11 +57,11 @@ Always search memory first.
 
 ```typescript
 // Search for relevant past work
-memory_search({ query: "<task keywords>", limit: 5 });
-memory_search({ query: "bugfix <component>", type: "observations" });
+memory - search({ query: "<task keywords>", limit: 5 });
+memory - search({ query: "bugfix <component>", type: "observations" });
 
 // Check recent handoffs
-memory_search({ query: "handoff", type: "handoffs", limit: 3 });
+memory - search({ query: "handoff", type: "handoffs", limit: 3 });
 ```
 
 **Why:** Past you already solved this. Don't rediscover.
@@ -38,14 +72,14 @@ Don't fetch full content until you know you need it.
 
 ```typescript
 // 1. Search returns compact index (50-100 tokens per result)
-const results = memory_search({ query: "auth patterns" });
+const results = memory - search({ query: "auth patterns" });
 // Returns: [{id: 42, title: "Auth bug fixed", ...}]
 
 // 2. Fetch full details ONLY for relevant IDs
-memory_get({ ids: "42,45" });
+memory - get({ ids: "42,45" });
 
 // 3. See what led to this decision
-memory_timeline({ anchor_id: 42, depth_before: 3 });
+memory - timeline({ anchor_id: 42, depth_before: 3 });
 ```
 
 **Why:** Prevents context bloat. High signal, low noise.
@@ -56,12 +90,13 @@ Create observations for anything non-obvious. Don't wait until the end.
 
 ```typescript
 observation({
-  type: "pattern", // decision | bugfix | pattern | discovery | warning
+  type: "pattern", // decision | bugfix | pattern | discovery | warning | learning
   title: "Brief description",
   narrative: "Context and reasoning...",
   facts: "key, facts, here",
   concepts: "searchable, keywords",
   files_modified: "src/file.ts",
+  source: "manual", // manual (default) | curator | imported
 });
 ```
 
@@ -79,9 +114,10 @@ observation({
 Document completion state for future you.
 
 ```typescript
-memory_update({
-  file: "handoffs/YYYY-MM-DD-task",
-  content: `## Completed
+memory -
+  update({
+    file: "handoffs/YYYY-MM-DD-task",
+    content: `## Completed
 - X
 
 ## Blockers
@@ -89,8 +125,8 @@ memory_update({
 
 ## Next
 - Z`,
-  mode: "append",
-});
+    mode: "append",
+  });
 ```
 
 ---
@@ -99,18 +135,18 @@ memory_update({
 
 ### memory-search (Start Here)
 
-Fast FTS5 full-text search. Returns **compact index** for progressive disclosure.
+Fast FTS5 full-text search with porter stemming. Returns **compact index** for progressive disclosure.
 
 ```typescript
-memory_search({ query: "authentication" });
-memory_search({ query: "bugfix", type: "observations", limit: 5 });
-memory_search({ query: "session", type: "handoffs" });
-memory_search({ query: "patterns", type: "all" }); // Search everything
+memory - search({ query: "authentication" });
+memory - search({ query: "bugfix", type: "observations", limit: 5 });
+memory - search({ query: "session", type: "handoffs" });
+memory - search({ query: "patterns", type: "all" }); // Search everything
 ```
 
 **Search modes:**
 
-- `observations` (default): Search SQLite with FTS5 ranking
+- `observations` (default): Search SQLite with FTS5 BM25 ranking
 - `handoffs`, `research`, `templates`: Search specific directories
 - `beads`: Search .beads/artifacts
 - `all`: Search everything
@@ -120,8 +156,8 @@ memory_search({ query: "patterns", type: "all" }); // Search everything
 Fetch full observation details after identifying relevant IDs:
 
 ```typescript
-memory_get({ ids: "42" }); // Single observation
-memory_get({ ids: "1,5,10" }); // Multiple observations
+memory - get({ ids: "42" }); // Single observation
+memory - get({ ids: "1,5,10" }); // Multiple observations
 ```
 
 ### memory-timeline (Chronological Context)
@@ -129,7 +165,7 @@ memory_get({ ids: "1,5,10" }); // Multiple observations
 See what happened before/after a specific observation:
 
 ```typescript
-memory_timeline({ anchor_id: 42, depth_before: 5, depth_after: 5 });
+memory - timeline({ anchor_id: 42, depth_before: 5, depth_after: 5 });
 ```
 
 ### memory-read (Files)
@@ -137,9 +173,9 @@ memory_timeline({ anchor_id: 42, depth_before: 5, depth_after: 5 });
 Load project files, handoffs, or templates:
 
 ```typescript
-memory_read({ file: "project/gotchas" });
-memory_read({ file: "handoffs/2024-01-20-phase-1" });
-memory_read({ file: "research/auth-patterns" });
+memory - read({ file: "project/gotchas" });
+memory - read({ file: "handoffs/2024-01-20-phase-1" });
+memory - read({ file: "research/auth-patterns" });
 ```
 
 ### memory-update (Files)
@@ -147,13 +183,40 @@ memory_read({ file: "research/auth-patterns" });
 Save to project files or handoffs:
 
 ```typescript
-memory_update({
-  file: "project/gotchas",
-  content: "### New Gotcha\n\nDescription...",
-  mode: "append", // or "replace"
-});
+memory -
+  update({
+    file: "project/gotchas",
+    content: "### New Gotcha\n\nDescription...",
+    mode: "append", // or "replace"
+  });
+```
+
+### memory-admin (Maintenance)
+
+```typescript
+// Check current status (schema, FTS5, counts, DB size)
+memory - admin({ operation: "status" });
+
+// Full maintenance (archive >90 days, checkpoint WAL, vacuum)
+memory - admin({ operation: "full" });
+
+// Preview what would be archived
+memory - admin({ operation: "archive", older_than_days: 60, dry_run: true });
+
+// Capture pipeline stats (temporal messages, distillations, compression)
+memory - admin({ operation: "capture-stats" });
+
+// Force distillation for current session
+memory - admin({ operation: "distill-now" });
+
+// Force curator run (extract observations from distillations)
+memory - admin({ operation: "curate-now" });
 ```
 
+**Automatic:** On session idle — distillation, curation, FTS5 optimize, WAL checkpoint.
+
+**Manual:** Run `memory-admin({ operation: "status" })` to check health.
+
 ---
 
 ## What Goes Where
@@ -161,24 +224,34 @@ memory_update({
 ### SQLite (observations)
 
 - Events: decisions, bugfixes, patterns discovered
-- Searchable via FTS5
+- Searchable via FTS5 with porter stemming
+- Created manually via `observation()` or automatically by curator
 - Use `observation()` to create
 
+### SQLite (distillations — automatic)
+
+- Compressed session summaries with TF-IDF terms
+- Created automatically when 10+ messages accumulate
+- Searchable via FTS5
+- Used for relevance-scored LTM injection
+
 ### Markdown Files
 
 - Static knowledge: user preferences, tech stack
 - Handoffs: session summaries
 - Research: deep-dive documents
-- Use `memory_read()` / `memory_update()`
-
-| Location                   | Content                    | Tool                              |
-| -------------------------- | -------------------------- | --------------------------------- |
-| `project/user.md`          | User identity, preferences | `memory_read()`                   |
-| `project/tech-stack.md`    | Frameworks, constraints    | `memory_read()`                   |
-| `project/gotchas.md`       | Footguns, warnings         | `memory_update({mode: "append"})` |
-| `handoffs/YYYY-MM-DD-*.md` | Session summaries          | `memory_update()`                 |
-| `research/*.md`            | Deep-dive analysis         | `memory_update()`                 |
-| SQLite                     | Observations, events       | `observation()`                   |
+- Use `memory-read()` / `memory-update()`
+
+| Location                   | Content                    | Tool                                |
+| -------------------------- | -------------------------- | ----------------------------------- |
+| `project/user.md`          | User identity, preferences | `memory-read()`                     |
+| `project/tech-stack.md`    | Frameworks, constraints    | `memory-read()`                     |
+| `project/gotchas.md`       | Footguns, warnings         | `memory-update({ mode: "append" })` |
+| `handoffs/YYYY-MM-DD-*.md` | Session summaries          | `memory-update()`                   |
+| `research/*.md`            | Deep-dive analysis         | `memory-update()`                   |
+| SQLite observations        | Events, decisions          | `observation()`                     |
+| SQLite distillations       | Session summaries          | Automatic (idle) or `distill-now`   |
+| SQLite temporal_messages   | Raw captured text          | Automatic (message events)          |
 
 ---
 
@@ -195,6 +268,7 @@ observation({
   files_read: "src/auth.ts, src/middleware.ts",
   files_modified: "src/auth.ts",
   bead_id: "br-abc123", // Link to task (optional)
+  source: "manual", // manual (default), curator, imported
 });
 ```
 
@@ -213,25 +287,6 @@ observation({
 
 ---
 
-## Maintenance
-
-```typescript
-// Check current status
-memory_admin({ operation: "status" });
-
-// Full maintenance (archive >90 days, checkpoint WAL, vacuum)
-memory_admin({ operation: "full" });
-
-// Preview what would be archived
-memory_admin({ operation: "archive", older_than_days: 60, dry_run: true });
-```
-
-**Automatic:** Runs at session end (FTS5 optimize, WAL checkpoint if >1MB)
-
-**Manual:** Run monthly or when storage grows
-
----
-
 ## Philosophy
 
 **Memory is not a dumping ground. It's curated signal.**

package/dist/template/.opencode/skill/mockup-to-code/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: mockup-to-code
 description: Use when converting UI mockups, screenshots, Figma/Sketch designs, wireframes, or building component libraries from design systems into production-ready code
+version: 1.0.0
+tags: [ui, workflow]
+dependencies: []
 ---
 
 # Mockup to Code Skill
 
-Convert UI mockups, screenshots, and designs into production-ready code.
-
 ## When to Use
 
 - Converting Figma/Sketch mockups to React/Vue/HTML
@@ -14,6 +15,11 @@ Convert UI mockups, screenshots, and designs into production-ready code.
 - Building component libraries from design systems
 - Rapid prototyping from wireframes
 
+## When NOT to Use
+
+- No visual reference or mockup to implement.
+
+
 ## Core Workflow
 
 ### Phase 1: Design Analysis
@@ -158,6 +164,6 @@ Save implementations to `.opencode/memory/design/implementations/`
 
 | Need              | Skill                 |
 | ----------------- | --------------------- |
-| Aesthetic quality | `frontend-design` |
+| Aesthetic quality | `frontend-design`     |
 | Accessibility     | `accessibility-audit` |
 | Design tokens     | `design-system-audit` |

package/dist/template/.opencode/skill/mqdh/SKILL.md

@@ -5,11 +5,21 @@ mcp:
   mqdh:
     command: "${MQDH_MCP_PATH}"
     args: []
+version: 1.0.0
+tags: [integration, mcp]
+dependencies: []
 ---
 
 # Meta Quest Developer Hub MCP
 
-Access Meta Horizon OS development tools via the MQDH MCP server. This MCP is **bundled with the Meta Quest Developer Hub application** (v6.2.1+).
+## When to Use
+
+- When you need Meta Quest docs, ADB tooling, or device management via MQDH MCP.
+
+## When NOT to Use
+
+- When you are not working on Meta Quest/VR development or MQDH is unavailable.
+
 
 ## Prerequisites
 

package/dist/template/.opencode/skill/obsidian/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: obsidian
 description: Use when working with Obsidian vault via MCP - read/write notes, search, tag management, and vault operations
+version: 1.0.0
+tags: [integration, documentation]
+dependencies: []
 mcp:
   server: @mauricio.wolff/mcp-obsidian
   args: ["{env:OBSIDIAN_VAULT_PATH}"]
@@ -8,7 +11,14 @@ mcp:
 
 # Obsidian Vault (MCP)
 
-MCP server for safe Obsidian vault access. Read/write notes, search, manage tags.
+## When to Use
+
+- When you need MCP-based read/write/search operations in an Obsidian vault.
+
+## When NOT to Use
+
+- When the task does not involve an Obsidian vault or MCP access.
+
 
 ## Available Tools
 

package/dist/template/.opencode/skill/opensrc/SKILL.md

@@ -1,11 +1,21 @@
 ---
 name: opensrc
 description: Fetch source code for npm, PyPI, or crates.io packages and GitHub/GitLab repos to provide AI agents with implementation context beyond types and docs. Use when needing to understand how a library works internally, debug dependency issues, or explore package implementations.
+version: 1.0.0
+tags: [research, integration]
+dependencies: []
 ---
 
 # opensrc
 
-CLI tool to fetch source code for packages/repos, giving AI coding agents deeper implementation context.
+## When to Use
+
+- When you need actual dependency source code to understand behavior or debug issues.
+
+## When NOT to Use
+
+- When API docs or local type definitions are sufficient for the task.
+
 
 ## When to Use
 
@@ -39,12 +49,12 @@ npx opensrc owner/repo@v1.0.0
 
 ## Commands
 
-| Command | Description |
-|---------|-------------|
+| Command                 | Description                     |
+| ----------------------- | ------------------------------- |
 | `opensrc <packages...>` | Fetch source for packages/repos |
-| `opensrc list` | List all fetched sources |
-| `opensrc remove <name>` | Remove specific source |
-| `opensrc clean` | Remove all sources |
+| `opensrc list`          | List all fetched sources        |
+| `opensrc remove <name>` | Remove specific source          |
+| `opensrc clean`         | Remove all sources              |
 
 ## Output Structure
 
@@ -63,6 +73,7 @@ opensrc/
 ## File Modifications
 
 On first run, opensrc prompts to modify:
+
 - `.gitignore` - adds `opensrc/` to ignore list
 - `tsconfig.json` - excludes `opensrc/` from compilation
 - `AGENTS.md` - adds section pointing agents to source code
@@ -110,6 +121,7 @@ npx opensrc zod pypi:pydantic vercel/ai
 ## References
 
 For detailed information:
+
 - [CLI Usage & Options](references/cli-usage.md) - Full command reference
 - [Architecture](references/architecture.md) - Code structure and extension
 - [Registry Support](references/registry-support.md) - npm, PyPI, crates.io details

package/dist/template/.opencode/skill/pdf-extract/SKILL.md

@@ -1,11 +1,21 @@
 ---
 name: pdf-extract
 description: Extract text, images, tables, and metadata from PDF files. Choose the right library based on extraction needs - text only, structured data, or complex layouts.
+version: 1.0.0
+tags: [research, integration]
+dependencies: []
 ---
 
 # PDF Content Extraction
 
-Extract content from PDF files using the best library for your specific use case.
+## When to Use
+
+- When you need to extract text, images, tables, or metadata from PDF files.
+
+## When NOT to Use
+
+- When the source data is already available in a non-PDF, structured format.
+
 
 ## Quick Decision Guide
 

package/dist/template/.opencode/skill/playwright/SKILL.md

@@ -1,11 +1,21 @@
 ---
 name: playwright
 description: Browser automation for testing, screenshots, form validation, and UX verification. Uses Playwright CLI for token-efficient automation, with MCP fallback for complex exploratory workflows.
+version: 1.0.0
+tags: [automation, mcp, testing]
+dependencies: []
 ---
 
 # Playwright Browser Automation
 
-Browser automation via **Playwright CLI** (primary) and **Playwright MCP** (fallback for complex workflows).
+## When to Use
+
+- When you need automated browser testing, screenshots, or form workflows via Playwright CLI/MCP.
+
+## When NOT to Use
+
+- When you specifically need to control your existing Chrome session (use playwriter instead).
+
 
 ## Quick Decision
 

package/dist/template/.opencode/skill/playwriter/SKILL.md

@@ -5,11 +5,21 @@ mcp:
   playwriter:
     command: npx
     args: ["playwriter@latest"]
+version: 1.0.0
+tags: [automation, mcp]
+dependencies: []
 ---
 
 # Playwriter Browser Automation (MCP)
 
-Control your actual Chrome browser via extension. Unlike traditional browser MCP tools that spawn isolated instances, Playwriter:
+## When to Use
+
+- When you need to automate your existing Chrome browser session via the Playwriter extension.
+
+## When NOT to Use
+
+- When you need a fresh, isolated browser instance without your local extensions/cookies.
+
 
 - **Uses your existing browser** - extensions, sessions, cookies all work
 - **Single `execute` tool** - send Playwright code snippets directly

package/dist/template/.opencode/skill/polar/SKILL.md

@@ -1,11 +1,21 @@
 ---
 name: polar
 description: Polar payment platform integration for monetization, subscriptions, and license keys. Use when implementing checkout, managing products, or building customer portals.
+version: 1.0.0
+tags: [integration, mcp]
+dependencies: []
 ---
 
 # Polar Integration
 
-Polar is a merchant-of-record platform for digital products, subscriptions, and license keys.
+## When to Use
+
+- When implementing Polar checkout, subscriptions, or license key flows.
+
+## When NOT to Use
+
+- When payments are handled by a different platform.
+
 
 ## What I Do
 

package/dist/template/.opencode/skill/prd/SKILL.md

@@ -1,17 +1,26 @@
 ---
 name: prd
 description: Create Product Requirements Documents (PRDs) that define the end state of a feature. Use when planning new features, migrations, or refactors. Generates structured PRDs with acceptance criteria.
+version: 1.0.0
+tags: [planning, documentation]
+dependencies: []
 ---
 
 # PRD Creation Skill
 
-Create Product Requirements Documents suitable for RFC review by Principal Engineers, Designers, and Product Owners.
+## When to Use
+
+- After a design is validated and you need formal requirements and acceptance criteria
+- Before breaking work into tasks or plans for features, migrations, or refactors
+
+## When NOT to Use
+
+- When you already have an approved PRD and only need task conversion
+- For small, mechanical changes where a PRD would be overhead
+
 
-The PRD describes WHAT to build and WHY, not HOW or in WHAT ORDER.
 
-**Part of:** `development-lifecycle` skill (Phase 2: Specification)
 
-**Template:** `.opencode/memory/_templates/prd.md`
 
 ## Beads-Native Output (Recommended)
 

package/dist/template/.opencode/skill/prd-task/SKILL.md

@@ -3,15 +3,25 @@ name: prd-task
 description: Convert a Beads PRD markdown file to executable JSON tasks for autonomous execution. Use after writing `.beads/artifacts/<bead-id>/prd.md`.
 references:
   - references/prd-schema.json
+version: 1.0.0
+tags: [planning, workflow]
+dependencies: [prd]
 ---
 
 # PRD Task Skill (Beads-Native)
 
-Convert a markdown PRD into executable JSON format for autonomous task completion.
+## When to Use
+
+- After a PRD is complete at `.beads/artifacts/<bead-id>/prd.md` and you need executable tasks
+- When you need to generate `prd.json` and initialize `progress.txt` for a bead
+
+## When NOT to Use
+
+- Before a PRD exists or when requirements are still being gathered
+- If you only need a human-readable plan (use writing-plans instead)
+
 
-The PRD defines the **end state** via tasks with verification steps. The agent decides HOW to get there.
 
-**Part of:** `development-lifecycle` skill (Phase 3: Task Conversion)
 
 ## Beads-Native File Locations (Recommended)
 

package/dist/template/.opencode/skill/ralph/SKILL.md

@@ -1,18 +1,13 @@
 ---
 name: ralph
 description: Use when running autonomous agent loops for extended task completion without human intervention - handles PRD-driven development, migration tasks, or batch operations
-license: MIT
-compatibility: opencode
-metadata:
-  source: https://ghuntley.com/ralph/
-  category: automation
-  updated: 2026-01-10
+version: 1.0.0
+tags: [workflow, automation]
+dependencies: []
 ---
 
 # Ralph Wiggum - Autonomous Agent Loop
 
-A workflow pattern for extended autonomous work sessions where the agent iterates through tasks until completion.
-
 ## When to Use
 
 - **PRD-driven development**: Work through a product requirements document task by task
@@ -27,6 +22,7 @@ A workflow pattern for extended autonomous work sessions where the agent iterate
 - Exploratory work where the goal isn't clear
 - Critical production changes (requires human oversight)
 
+
 ## Quick Start
 
 Invoke the workflow with: