@jayjiang/byoao 0.9.0 → 0.9.1

package/dist/hooks/system-transform.js

@@ -62,6 +62,11 @@ function buildNavigationStrategy(vaultPath) {
         "| `references`| Related notes — follow for deeper context        |",
         "| `type`      | Note kind (meeting, idea, reference, daily, etc) |",
         "| `tags`      | Flexible categorization                          |",
+        "",
+        "### Vault Health",
+        "",
+        "If you notice broken wikilinks, orphan notes, or missing frontmatter while working,",
+        "suggest that the user run `/diagnose` to get a full vault health report.",
     ].join("\n");
 }
 /**

package/dist/hooks/system-transform.js.map

@@ -1 +1 @@
-{"version":3,"file":"system-transform.js","sourceRoot":"","sources":["../../src/hooks/system-transform.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"system-transform.js","sourceRoot":"","sources":["../../src/hooks/system-transform.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jayjiang/byoao",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Build Your Own AI OS — Obsidian + AI Agent",
   "type": "module",
   "engines": {

package/src/assets/obsidian-skills/vault-thinking.md

@@ -0,0 +1,40 @@
+---
+name: vault-thinking
+description: Guide for recommending BYOAO vault analysis commands to users. Use when the user is reflecting, brainstorming, stuck on an idea, asking about patterns, or could benefit from a vault-powered thinking workflow.
+---
+
+# Vault Thinking Guide
+
+This vault has BYOAO thinking commands available. Suggest them when they match the user's intent — don't wait for an exact keyword match.
+
+## Available Commands
+
+| Command | What it does | Suggest when |
+|---------|-------------|--------------|
+| `/weave` | Enrich notes with frontmatter, wikilinks, Glossary entries, hub notes | User imports new files, asks to organize, or vault has many unlinked notes |
+| `/trace topic` | Chronological timeline of how an idea evolved | User asks how something developed, wants history, or says "when did I start..." |
+| `/emerge` | Surface hidden patterns, clusters, contradictions across the vault | User asks "what am I missing", wants a big-picture review, or seems stuck |
+| `/connect A B` | Bridge two topics via the vault's link graph | User wonders if two areas are related, or wants cross-domain insight |
+| `/ideas` | Deep scan to generate actionable ideas from vault content | User asks "what should I work on", wants brainstorming, or needs next steps |
+| `/challenge topic` | Pressure-test a belief against the vault's own history | User is making a decision, says "am I wrong", or wants to validate an assumption |
+| `/drift` | Compare stated intentions vs actual behavior over 30-90 days | User asks about follow-through, wonders where time went, or reviews goals |
+| `/diagnose` | Vault health check — orphans, broken links, frontmatter gaps | User notices broken links, asks "what's wrong with my vault", or after heavy editing |
+## When to Proactively Suggest
+
+- User is **reflecting on a topic** → suggest `/trace` to see how their thinking evolved
+- User is **brainstorming or feels stuck** → suggest `/emerge` or `/ideas`
+- User is **making a decision** → suggest `/challenge` to pressure-test it
+- User is **reviewing goals or progress** → suggest `/drift`
+- User **imported new notes** or mentions disorganization → suggest `/weave`
+- User asks about **connections between topics** → suggest `/connect`
+- User mentions **broken links or vault messiness** → suggest `/diagnose`
+
+## How to Suggest
+
+Mention the command naturally in conversation. For example:
+
+- "You could run `/trace data-mesh` to see how that idea has evolved across your notes."
+- "If you want to pressure-test that assumption, `/challenge` can find counter-evidence in your vault."
+- "After importing those files, `/weave` can add frontmatter and link them to your existing notes."
+
+Do not run these commands automatically — they read many vault files and can take several minutes. Always let the user decide when to invoke them.

package/src/skills/challenge.md

@@ -15,6 +15,10 @@ obsidian --version
 
 If this fails, STOP and display the Obsidian CLI availability message (see /weave for the full error text).
 
+## Tool Selection
+
+Use `obsidian` CLI for content operations (read, search, backlinks, properties, tags). Use BYOAO tools (`byoao_search_vault`, `byoao_graph_health`) when Obsidian CLI is unavailable or for graph-level structural queries.
+
 ## Parameters
 
 - **belief** (required): The belief, assumption, or decision to challenge. Can be a direct statement or a reference to a note.

package/src/skills/connect.md

@@ -15,6 +15,10 @@ obsidian --version
 
 If this fails, STOP and display the Obsidian CLI availability message (see /weave for the full error text).
 
+## Tool Selection
+
+Use `obsidian` CLI for content operations (read, search, backlinks, properties, tags). Use BYOAO tools (`byoao_search_vault`, `byoao_graph_health`) when Obsidian CLI is unavailable or for graph-level structural queries.
+
 ## Parameters
 
 - **from** (required): The first topic, concept, domain, or note.

package/src/skills/diagnose.md

@@ -58,7 +58,7 @@ For each issue category, suggest a concrete next action:
 
 ### Step 5: Update AGENT.md Timestamp
 
-After fixes are applied (with user consent), append or update a `Last Scanned` line at the bottom of AGENT.md:
+After fixes are applied, **ask the user** before updating AGENT.md. If confirmed, append or update a `Last Scanned` line at the bottom of AGENT.md:
 
 ```markdown
 ---

package/src/skills/drift.md

@@ -15,6 +15,10 @@ obsidian --version
 
 If this fails, STOP and display the Obsidian CLI availability message (see /weave for the full error text).
 
+## Tool Selection
+
+Use `obsidian` CLI for content operations (read, search, backlinks, properties, tags). Use BYOAO tools (`byoao_search_vault`, `byoao_graph_health`) when Obsidian CLI is unavailable or for graph-level structural queries.
+
 ## Parameters
 
 - **period** (optional): Time window to analyze. Default: "30d" (last 30 days). Accepts: "7d", "30d", "60d", "90d".
@@ -23,24 +27,39 @@ If this fails, STOP and display the Obsidian CLI availability message (see /weav
 
 ## Process
 
+### Date Range Resolution
+
+Calculate the cutoff date from the `period` parameter (e.g., "30d" = today minus 30 days). Use this to filter all notes:
+- **Daily notes**: filter by filename pattern (`Daily/YYYY-MM-DD.md`)
+- **Other notes**: filter by frontmatter `date` field
+- Notes without a date: include only if they are in an active project folder or have `status: active`
+
 ### Step 1: Collect Intentions
 
-Search for stated intentions, goals, and plans:
+Use a structured, layered approach to find stated intentions:
+
+**Layer 1 — Structured notes (most reliable):**
+```bash
+obsidian search "type: decision"
+obsidian search "type: plan"
+```
+Read sprint handoffs, project docs, and decision records within the period.
+
+**Layer 2 — Daily notes (chronological):**
+Read daily notes for the period by filename pattern (e.g., `Daily/2026-03-*.md`). Extract stated priorities, action items, and commitments.
 
+**Layer 3 — Keyword fallback (for vaults without structured frontmatter):**
+Only if Layers 1-2 produce fewer than 5 intentions:
 ```bash
 obsidian search "goal"
-obsidian search "plan"
-obsidian search "will do"
 obsidian search "next steps"
 obsidian search "TODO"
 obsidian search "priority"
 ```
 
 Also read:
-- Decision records — what was decided
-- Sprint/project plans — what was committed
-- Daily notes from the start of the period — stated priorities
-- Meeting notes — action items assigned
+- Meeting notes with action items assigned
+- Notes with tags like `#plan`, `#goal`, `#commitment`
 
 Extract a list of **stated intentions** with dates:
 - "{date}: Planned to {X}" (source: [[Note]])
@@ -88,6 +107,7 @@ Look for systemic patterns, not just individual misses:
 
 **Energy leaks** — Time going to undocumented work.
 > "Daily notes from weeks 3-5 rarely mention the stated priority. The gap suggests time is going somewhere not reflected in the vault."
+**Caveat:** This pattern is only meaningful if the user writes daily notes consistently. If daily notes are sparse or irregular, the absence of mentions is a documentation gap, not evidence of time spent elsewhere. Note this distinction in the report.
 
 **Goal abandonment** — Goals that silently disappeared.
 > "The Q1 goal of 'improve test coverage' was mentioned 3 times in January and never again."

package/src/skills/emerge.md

@@ -15,6 +15,10 @@ obsidian --version
 
 If this fails, STOP and display the Obsidian CLI availability message (see /weave for the full error text).
 
+## Tool Selection
+
+Use `obsidian` CLI for content operations (read, search, backlinks, properties, tags). Use BYOAO tools (`byoao_search_vault`, `byoao_graph_health`) when Obsidian CLI is unavailable or for graph-level structural queries.
+
 ## Parameters
 
 - **scope** (optional): Limit analysis to a folder, domain, or tag. Default: entire vault.
@@ -23,6 +27,10 @@ If this fails, STOP and display the Obsidian CLI availability message (see /weav
 
 ## Process
 
+### Sampling Strategy
+
+If a domain or search returns more than 30 notes, prioritize: (1) most recent 10, (2) most-linked 10 (highest backlink count), (3) notes with `status: active`. Read these first, then scan remaining titles and frontmatter to check for outliers before synthesizing.
+
 ### Step 1: Map the Vault
 
 Build a structural picture:

package/src/skills/ideas.md

@@ -15,6 +15,10 @@ obsidian --version
 
 If this fails, STOP and display the Obsidian CLI availability message (see /weave for the full error text).
 
+## Tool Selection
+
+Use `obsidian` CLI for content operations (read, search, backlinks, properties, tags). Use BYOAO tools (`byoao_search_vault`, `byoao_graph_health`) when Obsidian CLI is unavailable or for graph-level structural queries.
+
 ## Parameters
 
 - **focus** (optional): Narrow ideas to a specific domain, project, or theme. Default: scan all domains.
@@ -23,6 +27,10 @@ If this fails, STOP and display the Obsidian CLI availability message (see /weav
 
 ## Process
 
+### Sampling Strategy
+
+If a domain or search returns more than 30 notes, prioritize: (1) most recent 10, (2) most-linked 10 (highest backlink count), (3) notes with `status: active`. Read these first, then scan remaining titles and frontmatter to check for outliers before synthesizing.
+
 ### Step 1: Map the Vault
 
 ```bash
@@ -70,6 +78,12 @@ Generate ideas across these categories:
 **Challenge ideas** — Question an assumption the vault takes for granted.
 > "Every note about the data pipeline assumes batch processing, but your meeting notes from February suggest the team wants real-time. Is batch still the right choice?"
 
+**People ideas** — People the user should meet, reconnect with, or introduce to each other.
+> "[[Alice]] keeps coming up in your infrastructure notes but you haven't had a 1:1 since February. Worth reconnecting."
+
+**Content ideas** — Things worth writing or publishing, based on depth of vault coverage.
+> "You have 8 notes about 'event-driven architecture' spanning 4 months — enough material for an article or internal tech talk."
+
 ### Step 5: Validate Each Idea
 
 For each idea, verify:
@@ -114,6 +128,14 @@ Generated from {N} notes across {M} domains.
 
 {Brief paragraph on themes across the ideas — are they pointing in the same direction?}
 
+## Top 3 Do Now
+
+Rank the three highest-impact, most immediately actionable ideas:
+
+1. **{Idea title}** — {one-sentence reason this is high-priority}
+2. **{Idea title}** — {reason}
+3. **{Idea title}** — {reason}
+
 ## Suggested Follow-ups
 
 - Run `/trace topic="X"` to explore Idea 1 further

package/src/skills/trace.md

@@ -15,6 +15,10 @@ obsidian --version
 
 If this fails, STOP and display the Obsidian CLI availability message (see /weave for the full error text).
 
+## Tool Selection
+
+Use `obsidian` CLI for content operations (read, search, backlinks, properties, tags). Use BYOAO tools (`byoao_search_vault`, `byoao_graph_health`) when Obsidian CLI is unavailable or for graph-level structural queries.
+
 ## Parameters
 
 - **topic** (required): The idea, concept, person, project, or term to trace.
@@ -23,6 +27,10 @@ If this fails, STOP and display the Obsidian CLI availability message (see /weav
 
 ## Process
 
+### Sampling Strategy
+
+If a search returns more than 30 notes, prioritize: (1) most recent 10, (2) most-linked 10 (highest backlink count), (3) notes with `status: active`. Read these first, then scan remaining titles and frontmatter to check for outliers before synthesizing.
+
 ### Step 1: Find All Mentions
 
 Search for the topic across the vault using multiple strategies:

package/src/skills/weave.md

@@ -47,8 +47,6 @@ When scanning files, skip:
 | `AGENT.md` | BYOAO-managed file |
 | `Knowledge/templates/` | Template files — not user content |
 
-Also respect `.byoaoignore` if present (same format as `.gitignore`).
-
 Report skipped non-markdown files at the end: "Skipped N non-markdown files".
 
 ## Process

package/src/skills/explain.md

@@ -1,58 +0,0 @@
----
-name: explain
-description: Explain codebase systems and workflows in clear, non-jargon language, cached in the Obsidian vault. Use when the user asks "how does this system work", "explain the architecture", "what does this service do", or needs a plain-language explanation of any codebase or technical system.
----
-
-# /explain — System Explainer
-
-You are a codebase knowledge assistant for knowledge workers. Your job is to explain system behavior, workflows, and architecture in plain language — no code blocks unless explicitly requested.
-
-## Three-Layer Knowledge Strategy
-
-System knowledge comes from three sources, in priority order:
-
-```
-Layer 1: Baseline Overview    — Codebase overview per repo (high-level architecture)
-Layer 2: Live Code Access     — Local repo clone + file read/grep (detailed tracing)
-Layer 3: Knowledge Cache      — Obsidian Vault Systems/ (accumulated explanations)
-```
-
-### Layer 1: Baseline Overviews
-
-Engineers generate a codebase overview for each repo (e.g. via `opencode /init` or similar), containing architecture, key paths, conventions, and dependencies. These overviews are stored at:
-
-```
-.opencode/context/repos/
-  _index.md              # Repo registry: name, one-line description, last-updated date
-  payment-service.md     # Overview of payment-service repo
-  auth-service.md        # Overview of auth-service repo
-  api-gateway.md         # Overview of api-gateway repo
-```
-
-**Always load the relevant baseline overview first** before reading raw code.
-
-### Layer 2: Local Repo Clones
-
-For detailed questions, read the actual code from local clones at `~/repos/`. Use file read + grep + git log to trace specific workflows.
-
-### Layer 3: Obsidian Knowledge Cache
-
-Previously generated explanations are cached in `Systems/`. Reuse them when the question matches and the doc is still current.
-
-## Behavior
-
-1. **Parse the question** — identify the target system, service, or feature.
-2. **Load baseline overview** — read `.opencode/context/repos/{service}.md`.
-3. **Check Obsidian vault** — search `Systems/` for existing knowledge docs.
-4. **If more detail needed** — read the local repo clone using baseline as guide.
-5. **Staleness detection** — flag discrepancies between baseline and actual code.
-6. **Synthesize a clear explanation** with Mermaid diagrams where helpful.
-7. **Save to Obsidian vault** — create or update a doc in `Systems/`.
-
-## Output Style
-
-- Lead with **what the system does** (behavior), not how it's coded
-- Use workflow descriptions: "When X happens, the system does Y, then Z"
-- Include Mermaid diagrams for multi-step flows
-- No code blocks unless explicitly requested
-- Use `[[wikilinks]]` to connect related vault docs