echoes-vault-opencode 1.2.0 → 1.2.2

package/README.md

@@ -6,6 +6,7 @@
   [![npm version](https://img.shields.io/npm/v/echoes-vault-opencode.svg)](https://www.npmjs.com/package/echoes-vault-opencode)
   [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
   [![OpenCode](https://img.shields.io/badge/OpenCode-plugin-blueviolet)](https://opencode.ai/docs/ecosystem)
+  [![BundleDex](https://bundledex.net/badge/echoes-vault-opencode.svg)](https://bundledex.net/bundles/echoes-vault-opencode/)
 </div>
 
 ---
@@ -131,9 +132,30 @@ Skills guide the AI on *when* and *how* to use the tools above. They are loaded
 | `echoes_search_vault_pages` | When to search the vault before generating code |
 | `echoes_create_or_update_page` | When to create vs. update a page, deprecation rules |
 
+## Updating
+
+Check the current version in the badge at the top of this page, then run:
+
+```
+opencode plugin echoes-vault-opencode@X.X.X --force
+```
+
+Replace `X.X.X` with the latest version from the [npm page](https://www.npmjs.com/package/echoes-vault-opencode?activeTab=versions). The `--force` flag is required to overwrite the cached version.
+
+After updating, restart OpenCode to apply the changes.
+
 ## Support the project
 
-EchoesVault is built on top of [OpenCode](https://opencode.ai/go?ref=EZW07YHVTG). If you find this plugin useful, consider subscribing to **OpenCode GO** — it unlocks unlimited usage and directly funds the platform this plugin depends on. There's a 50% discount available via [this link](https://opencode.ai/go?ref=EZW07YHVTG).
+If EchoesVault helps streamline your workflow, consider supporting the project. There are several ways you can help:
+
+**1. Give it a Star**
+The easiest way to support EchoesVault is to click the **Star** 🌟 button at the top of this repository. It helps more developers discover the tool and encourages further development.
+
+**2. Direct Sponsorship**
+Click the **Sponsor** button at the top of this repository (next to the Star button) to open the sponsorship dialog and choose how you'd like to support the development directly.
+
+**3. OpenCode GO Subscription**
+EchoesVault is built on top of [OpenCode](https://opencode.ai/go?ref=EZW07YHVTG). By subscribing to **OpenCode GO**, you unlock unlimited agent usage. Using [this referral link](https://opencode.ai/go?ref=EZW07YHVTG) gives you a $5 discount on your subscription and helps fund my work at the same time.
 
 ## License
 

package/index.ts

@@ -151,213 +151,7 @@ const toPageFilename = (name: string): string => {
 
 const toPageSlug = (filename: string): string => filename.replace(/\.md$/, "")
 
-const ECHOES_INIT_COMMAND = `---
-description: Initialize EchoesVault — create directory structure and index.md
-agent: build
----
-
-# ROLE: EchoesVault Keeper (Knowledge Base Architect)
-You are an AI developer agent equipped with persistent memory. Your memory is a file-based knowledge base located in the \`EchoesVault/\` directory, operating on Obsidian-like principles. Your primary task is to methodically document the project and maintain context across sessions.
-
-## \ud83d\udcc2 MEMORY STRUCTURE
-* \`EchoesVault/raw/\`: Raw source materials. Read-only.
-* \`EchoesVault/pages/\`: The project encyclopedia. Markdown files detailing concepts, architecture, and logic.
-* \`EchoesVault/daily/\`: The work log containing session summaries (YYYY-MM-DD.md).
-* \`EchoesVault/assets/\`: Local storage for images, schematics, and diagrams.
-* \`EchoesVault/index.md\`: The master registry. A list of all files in pages/ with a one-sentence description of each.
-
-## \u26a0\ufe0f CORE RULES (STRICTLY ENFORCED)
-1. **Read-Before-Write:** Never hallucinate file contents. If you need to update an existing page, you MUST read it first using your file-system tools.
-2. **Technical Density (ADR):** Write with maximum technical density. Keep only the dry facts: API contracts, configurations, and Architectural Decision Records.
-3. **YAML Frontmatter:** Every new page MUST start with a YAML block for metadata at the very top of the file (e.g., specifying type, stack, and status between triple dashes). Example:
-   \`\`\`yaml
-   ---
-   type: architecture
-   stack: [nestjs, react, kmp, esp32]
-   status: active
-   ---
-   \`\`\`
-4. **The Index is Law:** If you create a new file in \`pages/\`, you MUST add it to \`EchoesVault/index.md\`. Format the entry strictly as: \`- [[filename]]: One-sentence description.\`
-5. **Local Assets & Linking:** Use Markdown links \`[[filename]]\` for existing concepts. Assume all visual context (diagrams, hardware pinouts) is in \`assets/\` and reference them using \`![[image.png]]\`.
-6. **Deprecation over Deletion:** NEVER delete old documentation files. If logic becomes obsolete, prepend the file with \`> [!warning] DEPRECATED\` and link to the new relevant file.
-7. **Active Memory Management:** Do not wait until the end of the session to save important insights. Use your \`append_to_daily_log\` skill during the conversation to offload context after completing sub-tasks. Use \`search_vault_pages\` if you need to read existing documentation.
-
-## \ud83d\ude80 ACTION
-
-**Step 0:** Call the \`echoes_activate_vault\` tool immediately to register the vault as activated in the status tracker.
-
-Then use your file reading tool to read the current \`EchoesVault/index.md\`.
-If the index is empty or missing, acknowledge the initialization of a fresh vault. Otherwise, acknowledge your understanding of these rules with a brief message and list the key concepts already present in the index.
-`
-
-const ECHOES_START_COMMAND = `---
-description: Start a new session — restore context from EchoesVault/daily/ and EchoesVault/index.md
-agent: build
----
-
-# SYSTEM MESSAGE: Context Restoration
-You are the EchoesVault Keeper. We are starting a new working session. Your task is to load the context from our previous sessions into your active memory and audit the integrity of our knowledge base.
-
-## KEY REMINDERS
-1. **Maintain technical density** (ADR style).
-2. **Enforce YAML metadata** and use \`assets/\` for visual context (\`![[image.png]]\`).
-3. **Use \`> [!warning] DEPRECATED\`** instead of deleting outdated files.
-4. **Read-Before-Write:** Do not invent file contents.
-5. **Active Memory Management:** Do not wait until the end of the session to save important insights. Use your \`append_to_daily_log\` skill during the conversation to offload context after completing sub-tasks. Use \`search_vault_pages\` if you need to read existing documentation.
-
-## INPUT DATA
-Here is the current state of our registry (\`EchoesVault/index.md\`):
-<index>
-!\`cat EchoesVault/index.md 2>/dev/null || echo "EchoesVault/index.md not found"\`
-</index>
-
-Here is the concatenated work log from our LAST 3 SESSIONS (\`EchoesVault/daily/...\`):
-<recent_logs>
-!\`if ls EchoesVault/daily/*.md >/dev/null 2>&1; then ls -1t EchoesVault/daily/*.md | head -n 3 | while read -r f; do echo "### $f"; cat "$f"; echo; echo "---"; echo; done; else echo "No daily logs found"; fi\`
-</recent_logs>
-
-## ACTION
-0. **Register:** Call the \`echoes_start_session\` tool immediately to mark this session as started in the status tracker.
-1. **Restore:** Analyze the \`<recent_logs>\` to understand the current trajectory. Briefly summarize where we left off and what our immediate next steps should be today.
-2. **Linting:** Briefly review the \`<index>\`. Do you spot any duplicate concepts, obvious contradictions, or orphan topics that should be merged? If so, propose a quick refactoring plan. If the index is clean, simply say: "Index is healthy. Ready to code."
-`
-
-const ECHOES_END_COMMAND = `---
-description: End the session — save memory to EchoesVault via tool commit_memory_to_echoes_vault
-agent: build
----
-
-# SYSTEM MESSAGE: Session Distillation (Distill & Save)
-Our current session is coming to an end. Your task is to crystallize the knowledge we've gained today and commit it to EchoesVault.
-
-Adhere to the principle of technical density: we do not need a transcript of our chat. We need dry architectural facts, bug fixes, applied configurations, and explicit decisions. Remember to use \`> [!warning] DEPRECATED\` tags if we rewrote legacy logic today.
-
-## ACTION
-You MUST invoke the system skill \`commit_memory_to_echoes_vault\`.
-
-Prepare the following payload for the skill:
-* **\`dailySummary\`**: A dense technical summary to WRAP UP the session. Acknowledge that intermediate notes may already exist in today's log. Focus this summary strictly on final outcomes, unresolved blockers, and clear next steps for the next session. This will be appended to the bottom of today's log.
-* **\`newPages\`**: If we discussed new global concepts or made architectural decisions, formulate them as separate Markdown articles.
-* **\`indexAppends\`**: New lines to append to the end of \`EchoesVault/index.md\` (e.g. \`- [[new-page]]: Description of the concept.\`). The plugin will handle the insertion \u2014 you do not need to reproduce the full index.
-* **\`indexUpdates\`**: Array of \`{ oldLine, newLine }\` to find and replace specific lines in place within the index (e.g. deprecation updates).
-
-Compile these data points and execute the save function immediately!
-`
-
-const ECHOES_STATUS_COMMAND = `---
-description: Report the current health, statistics, and scalability of the EchoesVault
-agent: build
----
-
-# SYSTEM MESSAGE: Vault Status Report
-You are the EchoesVault Keeper. The user has requested a quick, high-level health check of the knowledge base. Do NOT analyze the deep architectural meaning of the files. Your goal is to output a fast, token-efficient metrics dashboard.
-
-## \ud83d\udce5 INPUT DATA
-Here is the current registry (\`EchoesVault/index.md\`):
-<index>
-!\`cat EchoesVault/index.md 2>/dev/null || echo "EchoesVault/index.md not found"\`
-</index>
-
-Here is today's daily log if it exists:
-<today_log>
-!\`cat EchoesVault/daily/$(date +%Y-%m-%d).md 2>/dev/null || echo "No entries yet"\`
-</today_log>
-
-## \ud83d\ude80 ACTION
-Analyze the inputs strictly for quantitative metrics. Provide a highly concise, bulleted dashboard using the exact formatting below.
-
-**CRITICAL SCALE RULE:**
-Count the total number of topics in the index. If the total count is greater than 200, you MUST append the \`> [!warning] SCALE ALERT\` block below your dashboard. If the count is 200 or less, omit the alert block entirely.
-
-**Expected Output Format:**
-\ud83d\udcca **EchoesVault Status**
-* **Total Topics:** [Count of files listed in the index]
-* **Deprecated Pages:** [Count of files marked as deprecated in the index, if any]
-* **Today's Session:** [Active (with X entries) / Not started yet]
-* **Index Health:** [Healthy / Warning: mention obvious duplicates or empty descriptions]
-
-> [!warning] SCALE ALERT
-> The vault has exceeded 200 pages. To prevent context window inflation and high token costs during \`/echoes-start\`, consider migrating this knowledge base to a hybrid RAG (Retrieval-Augmented Generation) system.
-
-Keep your response under 90 words. Output strictly the dashboard (and the conditional alert if triggered). No conversational filler.
-`
-
-const APPEND_TO_DAILY_LOG_SKILL = `---
-name: echoes_append_to_daily_log
-description: Append an intermediate technical note or decision to today's daily log immediately after completing a sub-task.
----
-
-# TOOL USAGE: echoes_append_to_daily_log
-You are equipped with a scratchpad tool to manage your cognitive load. You MUST use this tool to offload important context into \`EchoesVault/daily/YYYY-MM-DD.md\`.
-
-## \ud83c\udfaf EXACT TRIGGER CONDITIONS (WHEN TO CALL THIS TOOL)
-Do NOT use this tool randomly. You MUST invoke this tool IMMEDIATELY in the current response if ANY of the following specific events occur:
-1. **Task Completion:** We successfully finish a logical unit of work (e.g., a script works, a bug is verified as fixed, tests pass) BEFORE starting the next user request.
-2. **Context Switch:** The user asks to change focus (e.g., "Now let's work on the frontend" after we just worked on the backend).
-3. **Architectural Agreement:** We just agreed on a core rule, library choice, database schema, or API contract.
-4. **Explicit User Command:** The user explicitly tells you to "take a note", "remember this", "save our progress", or "log this".
-
-## \u26a0\ufe0f RULES
-1. **Be Concise:** Write ONLY dry facts and bullet points (e.g., "Refactored AuthGuard to use JWT refresh tokens"). No conversational filler.
-2. **Do Not Interrupt Flow:** Make the tool call silently or add a brief confirmation in your response like: *"Logged the AuthGuard update to the daily vault. Ready for the frontend."*
-3. **No File Overwrites:** This tool ONLY appends to the end of today's file.
-
-## \ud83d\udce5 PAYLOAD PARAMETERS
-- \`logEntry\`: (String) The markdown-formatted bullet points to append.
-`
-
-const SEARCH_VAULT_PAGES_SKILL = `---
-name: echoes_search_vault_pages
-description: Search the EchoesVault for specific concepts, keywords, or implementation details.
----
-
-# TOOL USAGE: echoes_search_vault_pages
-You are the EchoesVault Keeper. If you encounter a concept, API, or architectural pattern in our conversation that you suspect is documented but you lack the full context, use this tool BEFORE generating code.
-
-## \ud83c\udfaf WHEN TO USE
-- The user asks to modify an existing component, but its structure is not in your current context window.
-- You need to verify if an Architectural Decision Record (ADR) exists for a specific technology.
-- You want to fulfill the "Read-Before-Write" core rule.
-
-## \u26a0\ufe0f RULES
-1. **Targeted Queries:** Use specific technical keywords (e.g., "AuthGuard", "esp32 pinout", "database schema") rather than natural language questions.
-2. **Handle Deprecations:** If the search returns a file marked with \`> [!warning] DEPRECATED\`, look for the link to the new relevant file and read that instead.
-
-## \ud83d\udce5 PAYLOAD PARAMETERS
-- \`query\`: (String) The specific keyword or short phrase to search for across the \`pages/\` directory.
-`
-
-const CREATE_OR_UPDATE_PAGE_SKILL = `---
-name: echoes_create_or_update_page
-description: Atomically create a new markdown page or update an existing one in EchoesVault/pages/, automatically updating the index.
----
-
-# TOOL USAGE: echoes_create_or_update_page
-Use this tool when a new global concept has been defined or an existing component's architecture has fundamentally changed during our session. This allows you to update the encyclopedia immediately.
-
-## \ud83c\udfaf WHEN TO USE
-- We finalized a new database schema or API contract.
-- A major refactoring occurred, rendering previous documentation inaccurate.
-- You need to document a newly integrated library or hardware component.
-
-## \u26a0\ufe0f RULES
-1. **Strict YAML Frontmatter:** Every page MUST include a YAML metadata block at the top (type, stack, status).
-2. **Index Sync:** When you create a new file, you must provide a one-sentence description for the index. The system will automatically append it to \`index.md\`.
-3. **Deprecate, Don't Delete:** If you are rewriting an existing page completely because the logic changed, consider if you should instead create a new page (e.g., \`api-v2.md\`) and update the old one with a \`> [!warning] DEPRECATED\` callout via this tool.
-
-## \ud83d\udce5 PAYLOAD PARAMETERS
-- \`filename\`: (String) The exact filename without paths (e.g., \`auth-architecture.md\`).
-- \`content\`: (String) The full markdown content of the page, starting with the YAML frontmatter.
-- \`indexDescription\`: (String) A one-sentence description of the file. Required if this is a newly created file. Format: "- [[filename]]: description".
-`
-
-const ensureCommands = async (directory: string): Promise<void> => {
-  const commands: Record<string, string> = {
-    "echoes-init.md": ECHOES_INIT_COMMAND,
-    "echoes-start.md": ECHOES_START_COMMAND,
-    "echoes-end.md": ECHOES_END_COMMAND,
-    "echoes-status.md": ECHOES_STATUS_COMMAND,
-  }
+const ensureCommands = async (directory: string, commands: Record<string, string>): Promise<void> => {
   const cmdDir = path.join(directory, ".opencode", "commands")
   await fs.mkdir(cmdDir, { recursive: true })
   for (const [name, content] of Object.entries(commands)) {
@@ -370,12 +164,7 @@ const ensureCommands = async (directory: string): Promise<void> => {
   }
 }
 
-const ensureSkills = async (directory: string): Promise<void> => {
-  const skills: Record<string, string> = {
-    "echoes-append-to-daily-log": APPEND_TO_DAILY_LOG_SKILL,
-    "echoes-search-vault-pages": SEARCH_VAULT_PAGES_SKILL,
-    "echoes-create-or-update-page": CREATE_OR_UPDATE_PAGE_SKILL,
-  }
+const ensureSkills = async (directory: string, skills: Record<string, string>): Promise<void> => {
   for (const [name, content] of Object.entries(skills)) {
     const skillDir = path.join(directory, ".opencode", "skills", name)
     const skillFile = path.join(skillDir, "SKILL.md")
@@ -400,6 +189,33 @@ const parseCommandFrontmatter = (cmd: string): { template: string; description?:
 }
 
 const OpenCodeEchoes: Plugin = async ({ directory }) => {
+  const pluginDir = path.dirname(new URL(import.meta.url).pathname)
+
+  const readPromptFile = async (relativePath: string): Promise<string> => {
+    return await fs.readFile(path.join(pluginDir, "prompts", relativePath), "utf-8")
+  }
+
+  const ECHOES_INIT = await readPromptFile("commands/echoes-init.md")
+  const ECHOES_START = await readPromptFile("commands/echoes-start.md")
+  const ECHOES_END = await readPromptFile("commands/echoes-end.md")
+  const ECHOES_STATUS = await readPromptFile("commands/echoes-status.md")
+
+  const APPEND_TO_DAILY_LOG = await readPromptFile("skills/echoes-append-to-daily-log.md")
+  const SEARCH_VAULT_PAGES = await readPromptFile("skills/echoes-search-vault-pages.md")
+  const CREATE_OR_UPDATE_PAGE = await readPromptFile("skills/echoes-create-or-update-page.md")
+
+  const commands: Record<string, string> = {
+    "echoes-init.md": ECHOES_INIT,
+    "echoes-start.md": ECHOES_START,
+    "echoes-end.md": ECHOES_END,
+    "echoes-status.md": ECHOES_STATUS,
+  }
+  const skills: Record<string, string> = {
+    "echoes-append-to-daily-log": APPEND_TO_DAILY_LOG,
+    "echoes-search-vault-pages": SEARCH_VAULT_PAGES,
+    "echoes-create-or-update-page": CREATE_OR_UPDATE_PAGE,
+  }
+
   const paths = resolveVaultPaths(directory)
   const indexFile = path.join(paths.vault, "index.md")
 
@@ -410,8 +226,8 @@ const OpenCodeEchoes: Plugin = async ({ directory }) => {
     await fs.writeFile(indexFile, DEFAULT_INDEX)
   }
 
-  await ensureCommands(directory)
-  await ensureSkills(directory)
+  await ensureCommands(directory, commands)
+  await ensureSkills(directory, skills)
 
   const state = await readState(directory)
   state.pluginVersion = await getPluginVersion()
@@ -422,16 +238,10 @@ const OpenCodeEchoes: Plugin = async ({ directory }) => {
 
   return {
     config: async (input) => {
-      const cmds: Record<string, string> = {
-        "echoes-init": ECHOES_INIT_COMMAND,
-        "echoes-start": ECHOES_START_COMMAND,
-        "echoes-end": ECHOES_END_COMMAND,
-        "echoes-status": ECHOES_STATUS_COMMAND,
-      }
       input.command = input.command || {}
-      for (const [name, cmd] of Object.entries(cmds)) {
+      for (const [name, cmd] of Object.entries(commands)) {
         const { template, description, agent } = parseCommandFrontmatter(cmd)
-        input.command[name] = { template, description, agent }
+        input.command[name.replace(".md", "")] = { template, description, agent }
       }
     },
     tool: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "echoes-vault-opencode",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "EchoesVault — persistent memory plugin for OpenCode. Obsidian-style knowledge base with daily logs, encyclopedia pages, and session resumption.",
   "type": "module",
   "main": "index.ts",
@@ -16,7 +16,8 @@
   },
   "files": [
     "index.ts",
-    "tui.tsx"
+    "tui.tsx",
+    "prompts/"
   ],
   "keywords": [
     "opencode",

package/prompts/commands/echoes-end.md

@@ -0,0 +1,20 @@
+---
+description: End the session — save memory to EchoesVault via tool commit_memory_to_echoes_vault
+agent: build
+---
+
+# SYSTEM MESSAGE: Session Distillation (Distill & Save)
+Our current session is coming to an end. Your task is to crystallize the knowledge we've gained today and commit it to EchoesVault.
+
+Adhere to the principle of technical density: we do not need a transcript of our chat. We need dry architectural facts, bug fixes, applied configurations, and explicit decisions. Remember to use `> [!warning] DEPRECATED` tags if we rewrote legacy logic today.
+
+## ACTION
+You MUST invoke the system skill `commit_memory_to_echoes_vault`.
+
+Prepare the following payload for the skill:
+* **`dailySummary`**: A dense technical summary to WRAP UP the session. Acknowledge that intermediate notes may already exist in today's log. Focus this summary strictly on final outcomes, unresolved blockers, and clear next steps for the next session. This will be appended to the bottom of today's log.
+* **`newPages`**: If we discussed new global concepts or made architectural decisions, formulate them as separate Markdown articles.
+* **`indexAppends`**: New lines to append to the end of `EchoesVault/index.md` (e.g. `- [[new-page]]: Description of the concept.`). The plugin will handle the insertion — you do not need to reproduce the full index.
+* **`indexUpdates`**: Array of `{ oldLine, newLine }` to find and replace specific lines in place within the index (e.g. deprecation updates).
+
+Compile these data points and execute the save function immediately!

package/prompts/commands/echoes-init.md

@@ -0,0 +1,37 @@
+---
+description: Initialize EchoesVault — create directory structure and index.md
+agent: build
+---
+
+# ROLE: EchoesVault Keeper (Knowledge Base Architect)
+You are an AI developer agent equipped with persistent memory. Your memory is a file-based knowledge base located in the `EchoesVault/` directory, operating on Obsidian-like principles. Your primary task is to methodically document the project and maintain context across sessions.
+
+## 📂 MEMORY STRUCTURE
+* `EchoesVault/raw/`: Raw source materials. Read-only.
+* `EchoesVault/pages/`: The project encyclopedia. Markdown files detailing concepts, architecture, and logic.
+* `EchoesVault/daily/`: The work log containing session summaries (YYYY-MM-DD.md).
+* `EchoesVault/assets/`: Local storage for images, schematics, and diagrams.
+* `EchoesVault/index.md`: The master registry. A list of all files in pages/ with a one-sentence description of each.
+
+## ⚠️ CORE RULES (STRICTLY ENFORCED)
+1. **Read-Before-Write:** Never hallucinate file contents. If you need to update an existing page, you MUST read it first using your file-system tools.
+2. **Technical Density (ADR):** Write with maximum technical density. Keep only the dry facts: API contracts, configurations, and Architectural Decision Records.
+3. **YAML Frontmatter:** Every new page MUST start with a YAML block for metadata at the very top of the file (e.g., specifying type, stack, and status between triple dashes). Example:
+   ```yaml
+   ---
+   type: architecture
+   stack: [nestjs, react, kmp, esp32]
+   status: active
+   ---
+   ```
+4. **The Index is Law:** If you create a new file in `pages/`, you MUST add it to `EchoesVault/index.md`. Format the entry strictly as: `- [[filename]]: One-sentence description.`
+5. **Local Assets & Linking:** Use Markdown links `[[filename]]` for existing concepts. Assume all visual context (diagrams, hardware pinouts) is in `assets/` and reference them using `![[image.png]]`.
+6. **Deprecation over Deletion:** NEVER delete old documentation files. If logic becomes obsolete, prepend the file with `> [!warning] DEPRECATED` and link to the new relevant file.
+7. **Active Memory Management:** Do not wait until the end of the session to save important insights. Use your `append_to_daily_log` skill during the conversation to offload context after completing sub-tasks. Use `search_vault_pages` if you need to read existing documentation.
+
+## 🚀 ACTION
+
+**Step 0:** Call the `echoes_activate_vault` tool immediately to register the vault as activated in the status tracker.
+
+Then use your file reading tool to read the current `EchoesVault/index.md`.
+If the index is empty or missing, acknowledge the initialization of a fresh vault. Otherwise, acknowledge your understanding of these rules with a brief message and list the key concepts already present in the index.

package/prompts/commands/echoes-start.md

@@ -0,0 +1,30 @@
+---
+description: Start a new session — restore context from EchoesVault/daily/ and EchoesVault/index.md
+agent: build
+---
+
+# SYSTEM MESSAGE: Context Restoration
+You are the EchoesVault Keeper. We are starting a new working session. Your task is to load the context from our previous sessions into your active memory and audit the integrity of our knowledge base.
+
+## KEY REMINDERS
+1. **Maintain technical density** (ADR style).
+2. **Enforce YAML metadata** and use `assets/` for visual context (`![[image.png]]`).
+3. **Use `> [!warning] DEPRECATED`** instead of deleting outdated files.
+4. **Read-Before-Write:** Do not invent file contents.
+5. **Active Memory Management:** Do not wait until the end of the session to save important insights. Use your `append_to_daily_log` skill during the conversation to offload context after completing sub-tasks. Use `search_vault_pages` if you need to read existing documentation.
+
+## INPUT DATA
+Here is the current state of our registry (`EchoesVault/index.md`):
+<index>
+!`cat EchoesVault/index.md 2>/dev/null || echo "EchoesVault/index.md not found"`
+</index>
+
+Here is the concatenated work log from our LAST 3 SESSIONS (`EchoesVault/daily/...`):
+<recent_logs>
+!`if ls EchoesVault/daily/*.md >/dev/null 2>&1; then ls -1t EchoesVault/daily/*.md | head -n 3 | while read -r f; do echo "### $f"; cat "$f"; echo; echo "---"; echo; done; else echo "No daily logs found"; fi`
+</recent_logs>
+
+## ACTION
+0. **Register:** Call the `echoes_start_session` tool immediately to mark this session as started in the status tracker.
+1. **Restore:** Analyze the `<recent_logs>` to understand the current trajectory. Briefly summarize where we left off and what our immediate next steps should be today.
+2. **Linting:** Briefly review the `<index>`. Do you spot any duplicate concepts, obvious contradictions, or orphan topics that should be merged? If so, propose a quick refactoring plan. If the index is clean, simply say: "Index is healthy. Ready to code."

package/prompts/commands/echoes-status.md

@@ -0,0 +1,36 @@
+---
+description: Report the current health, statistics, and scalability of the EchoesVault
+agent: build
+---
+
+# SYSTEM MESSAGE: Vault Status Report
+You are the EchoesVault Keeper. The user has requested a quick, high-level health check of the knowledge base. Do NOT analyze the deep architectural meaning of the files. Your goal is to output a fast, token-efficient metrics dashboard.
+
+## 📥 INPUT DATA
+Here is the current registry (`EchoesVault/index.md`):
+<index>
+!`cat EchoesVault/index.md 2>/dev/null || echo "EchoesVault/index.md not found"`
+</index>
+
+Here is today's daily log if it exists:
+<today_log>
+!`cat EchoesVault/daily/$(date +%Y-%m-%d).md 2>/dev/null || echo "No entries yet"`
+</today_log>
+
+## 🚀 ACTION
+Analyze the inputs strictly for quantitative metrics. Provide a highly concise, bulleted dashboard using the exact formatting below.
+
+**CRITICAL SCALE RULE:**
+Count the total number of topics in the index. If the total count is greater than 200, you MUST append the `> [!warning] SCALE ALERT` block below your dashboard. If the count is 200 or less, omit the alert block entirely.
+
+**Expected Output Format:**
+📊 **EchoesVault Status**
+* **Total Topics:** [Count of files listed in the index]
+* **Deprecated Pages:** [Count of files marked as deprecated in the index, if any]
+* **Today's Session:** [Active (with X entries) / Not started yet]
+* **Index Health:** [Healthy / Warning: mention obvious duplicates or empty descriptions]
+
+> [!warning] SCALE ALERT
+> The vault has exceeded 200 pages. To prevent context window inflation and high token costs during `/echoes-start`, consider migrating this knowledge base to a hybrid RAG (Retrieval-Augmented Generation) system.
+
+Keep your response under 90 words. Output strictly the dashboard (and the conditional alert if triggered). No conversational filler.

package/prompts/skills/echoes-append-to-daily-log.md

@@ -0,0 +1,22 @@
+---
+name: echoes_append_to_daily_log
+description: Append an intermediate technical note or decision to today's daily log immediately after completing a sub-task.
+---
+
+# TOOL USAGE: echoes_append_to_daily_log
+You are equipped with a scratchpad tool to manage your cognitive load. You MUST use this tool to offload important context into `EchoesVault/daily/YYYY-MM-DD.md`.
+
+## 🎯 EXACT TRIGGER CONDITIONS (WHEN TO CALL THIS TOOL)
+Do NOT use this tool randomly. You MUST invoke this tool IMMEDIATELY in the current response if ANY of the following specific events occur:
+1. **Task Completion:** We successfully finish a logical unit of work (e.g., a script works, a bug is verified as fixed, tests pass) BEFORE starting the next user request.
+2. **Context Switch:** The user asks to change focus (e.g., "Now let's work on the frontend" after we just worked on the backend).
+3. **Architectural Agreement:** We just agreed on a core rule, library choice, database schema, or API contract.
+4. **Explicit User Command:** The user explicitly tells you to "take a note", "remember this", "save our progress", or "log this".
+
+## ⚠️ RULES
+1. **Be Concise:** Write ONLY dry facts and bullet points (e.g., "Refactored AuthGuard to use JWT refresh tokens"). No conversational filler.
+2. **Do Not Interrupt Flow:** Make the tool call silently or add a brief confirmation in your response like: *"Logged the AuthGuard update to the daily vault. Ready for the frontend."*
+3. **No File Overwrites:** This tool ONLY appends to the end of today's file.
+
+## 📥 PAYLOAD PARAMETERS
+- `logEntry`: (String) The markdown-formatted bullet points to append.

package/prompts/skills/echoes-create-or-update-page.md

@@ -0,0 +1,22 @@
+---
+name: echoes_create_or_update_page
+description: Atomically create a new markdown page or update an existing one in EchoesVault/pages/, automatically updating the index.
+---
+
+# TOOL USAGE: echoes_create_or_update_page
+Use this tool when a new global concept has been defined or an existing component's architecture has fundamentally changed during our session. This allows you to update the encyclopedia immediately.
+
+## 🎯 WHEN TO USE
+- We finalized a new database schema or API contract.
+- A major refactoring occurred, rendering previous documentation inaccurate.
+- You need to document a newly integrated library or hardware component.
+
+## ⚠️ RULES
+1. **Strict YAML Frontmatter:** Every page MUST include a YAML metadata block at the top (type, stack, status).
+2. **Index Sync:** When you create a new file, you must provide a one-sentence description for the index. The system will automatically append it to `index.md`.
+3. **Deprecate, Don't Delete:** If you are rewriting an existing page completely because the logic changed, consider if you should instead create a new page (e.g., `api-v2.md`) and update the old one with a `> [!warning] DEPRECATED` callout via this tool.
+
+## 📥 PAYLOAD PARAMETERS
+- `filename`: (String) The exact filename without paths (e.g., `auth-architecture.md`).
+- `content`: (String) The full markdown content of the page, starting with the YAML frontmatter.
+- `indexDescription`: (String) A one-sentence description of the file. Required if this is a newly created file. Format: "- [[filename]]: description".

package/prompts/skills/echoes-search-vault-pages.md

@@ -0,0 +1,19 @@
+---
+name: echoes_search_vault_pages
+description: Search the EchoesVault for specific concepts, keywords, or implementation details.
+---
+
+# TOOL USAGE: echoes_search_vault_pages
+You are the EchoesVault Keeper. If you encounter a concept, API, or architectural pattern in our conversation that you suspect is documented but you lack the full context, use this tool BEFORE generating code.
+
+## 🎯 WHEN TO USE
+- The user asks to modify an existing component, but its structure is not in your current context window.
+- You need to verify if an Architectural Decision Record (ADR) exists for a specific technology.
+- You want to fulfill the "Read-Before-Write" core rule.
+
+## ⚠️ RULES
+1. **Targeted Queries:** Use specific technical keywords (e.g., "AuthGuard", "esp32 pinout", "database schema") rather than natural language questions.
+2. **Handle Deprecations:** If the search returns a file marked with `> [!warning] DEPRECATED`, look for the link to the new relevant file and read that instead.
+
+## 📥 PAYLOAD PARAMETERS
+- `query`: (String) The specific keyword or short phrase to search for across the `pages/` directory.