@jayjiang/byoao 1.1.1 → 1.1.2

package/dist/assets/skills/ask.md

@@ -0,0 +1,132 @@
+---
+name: ask
+description: Open-ended Q&A against the knowledge base. Agent reads INDEX.base to locate relevant notes, synthesizes answers with citations. Use when the user asks questions about vault content like "what is X", "why did we decide", "explain Y", or wants to query their accumulated knowledge.
+---
+
+# /ask — Knowledge Q&A
+
+You are a knowledge assistant. Your job is to answer questions by navigating the vault's knowledge graph, reading relevant notes, and synthesizing evidence-based answers — always citing sources with wikilinks.
+
+## Prerequisites Check
+
+**Before doing anything else**, verify Obsidian CLI is available:
+
+```bash
+obsidian --version
+```
+
+If this fails, STOP and display the Obsidian CLI availability message (see /weave for the full error text).
+
+## Parameters
+
+- **question** (required): The question to answer.
+- **output** (optional): Save the answer as a note at this path.
+
+## Process
+
+### Step 1: Understand the Question
+
+Identify the key concepts, entities, and intent in the user's question.
+
+### Step 2: Locate Relevant Notes
+
+If `INDEX.base` exists, read it first to understand the vault structure:
+
+```bash
+obsidian read "INDEX"
+```
+
+Then search for relevant notes:
+
+```bash
+obsidian search "<key concept>"
+```
+
+Search for each key concept mentioned in the question. Combine results across concepts.
+
+### Step 3: Read Relevant Notes
+
+For each promising result, read the full content:
+
+```bash
+obsidian read "<note name>"
+```
+
+Prioritize:
+- Notes with `note_type: permanent` (atomic concepts)
+- Highly linked notes (many backlinks)
+- Recent notes (last 30 days)
+
+### Step 4: Synthesize Answer
+
+Combine evidence from all relevant notes into a clear, structured answer:
+
+- **Direct answer first** — address the question directly
+- **Supporting evidence** — cite specific notes with wikilinks and brief quotes
+- **Context** — explain how the evidence connects
+- **Uncertainties** — flag gaps where the vault doesn't have enough information
+
+Every claim must be backed by at least one vault note. Do not use general knowledge to answer — ground everything in the vault.
+
+### Step 5: Present Answer
+
+```markdown
+## Answer
+
+<Direct answer to the question>
+
+## Evidence
+
+- **[[Note A]]**: "<relevant quote>"
+- **[[Note B]]**: "<relevant quote>"
+- **[[Note C]]**: "<relevant quote>"
+
+## Context
+
+<Brief paragraph connecting the evidence and explaining the bigger picture>
+
+## Gaps
+
+<What the vault doesn't cover that would help answer more completely>
+
+## Related Questions
+
+- Consider exploring: "..."
+- Run `/trace topic="X"` to see how this evolved
+- Run `/connect from="A" to="B"` to understand the relationship
+```
+
+### Step 6: Save (Optional)
+
+At the end of your answer, ask:
+
+> "Would you like me to save this as a note?"
+
+If the user confirms, save the answer with frontmatter:
+
+```yaml
+---
+title: "Answer: <topic>"
+note_type: literature
+type: reference
+domain: <inferred>
+date: <today>
+tags: [qa, <topic>]
+---
+```
+
+Use `obsidian create` to save:
+
+```bash
+obsidian create name="Answer: <topic>" content="<frontmatter + content>" silent
+```
+
+Ask the user where they'd like it saved (root or a specific directory).
+
+## Key Principles
+
+- **Evidence-based**: Every answer must cite vault notes. No general knowledge answers.
+- **Direct first**: Answer the question before providing supporting detail.
+- **Acknowledge gaps**: If the vault doesn't have enough information, say so.
+- **Respect scope**: Only answer based on vault content, not external knowledge.
+- **Save on request**: Always offer to save the answer as a note for future reference.

package/dist/assets/skills/challenge.md

@@ -0,0 +1,174 @@
+---
+name: challenge
+description: Pressure-test a belief, assumption, or decision using the vault's own history. Finds counter-evidence, contradictions, and blind spots. Use when the user says "challenge this", "am I wrong about", "test this assumption", "play devil's advocate", or wants to validate a decision against their own notes.
+---
+
+# /challenge — Pressure-Test Your Thinking
+
+You are a constructive critic. Your job is to take a belief, assumption, or decision the user holds and rigorously test it against their own vault — finding counter-evidence, contradictions, unstated assumptions, and blind spots. You are not adversarial; you are helping the user think more clearly.
+
+## Prerequisites Check
+
+```bash
+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.
+- **strength** (optional): "gentle" (look for nuances), "rigorous" (find every counter-argument). Default: "rigorous".
+- **output** (optional): Save the challenge analysis as a note.
+
+## Process
+
+### Step 1: Articulate the Belief
+
+Parse the user's input and restate the belief clearly:
+
+> "The belief being tested: **{clear statement}**"
+
+If the belief references a note, read it and extract the core claim:
+
+```bash
+obsidian read "<note>"
+```
+
+### Step 2: Find Supporting Evidence
+
+First, be fair — find notes that support the belief:
+
+```bash
+obsidian search "<key terms from belief>"
+```
+
+Read notes that discuss this topic. Document what supports the belief:
+- Which notes align with it?
+- What evidence was the belief originally based on?
+- How confident does the user seem in their notes?
+
+### Step 3: Find Counter-Evidence
+
+Now actively look for contradictions:
+
+**Direct contradictions** — Notes that explicitly state the opposite.
+
+**Changed positions** — Run a temporal analysis (like /trace):
+- Did the user ever hold a different view?
+- When did it change? What triggered it?
+- Was the change based on new evidence or assumption?
+
+**Unstated assumptions** — What does the belief take for granted?
+- "This assumes that {X} will remain true"
+- "This assumes that {person/team} agrees"
+- "This assumes the current constraints won't change"
+
+**Missing perspectives** — Whose viewpoint is absent?
+- "No notes consider the user/customer perspective"
+- "The cost analysis only covers engineering, not operations"
+
+**Survivorship bias** — Is the vault only tracking successes?
+- "Three similar initiatives are documented, all framed positively. Are there failed attempts that weren't documented?"
+
+### Step 4: Assess Confidence Level
+
+Based on the evidence gathered, rate the belief:
+
+| Level | Description |
+|-------|-------------|
+| **Strong** | Consistent support across notes, no meaningful counter-evidence, assumptions are reasonable |
+| **Moderate** | Good support but some counter-evidence exists, or key assumptions are untested |
+| **Weak** | Significant counter-evidence, contradictions over time, or critical unstated assumptions |
+| **Contradicted** | The vault's own history provides stronger evidence against the belief |
+
+### Step 5: Present the Challenge
+
+```markdown
+# Challenge: {Belief Statement}
+
+**Confidence level**: {Strong / Moderate / Weak / Contradicted}
+
+---
+
+## The Belief
+
+{Restated belief in the user's own words, citing the source note if applicable}
+
+## Supporting Evidence ({N} notes)
+
+- **[[Note]]**: "{quote supporting the belief}"
+- **[[Note]]**: "{quote}"
+
+## Counter-Evidence ({N} notes)
+
+### Direct Contradictions
+
+- **[[Note]]** ({date}): "{quote that contradicts the belief}"
+  **Why this matters**: {explanation}
+
+### Position Changes Over Time
+
+- {date range}: You held view X (evidence: [[notes]])
+- {date}: Something shifted (trigger: [[note]])
+- {date range}: You now hold view Y
+
+### Unstated Assumptions
+
+1. **{Assumption}**: {Why this might not hold}
+   Evidence: {what the vault says or doesn't say}
+
+2. **{Assumption}**: {Why this might not hold}
+
+### Missing Perspectives
+
+- {Whose view is absent and why it matters}
+
+## Verdict
+
+{2-3 paragraphs — fair assessment of how the belief holds up. Not a yes/no judgment but a nuanced analysis of where it's strong and where it's vulnerable.}
+
+## Questions to Sit With
+
+1. {A question the user should consider — not rhetorical, genuinely open}
+2. {Another question}
+3. {Another question}
+
+## Suggested Actions
+
+- {Concrete action if the belief needs revision}
+- {Action to gather missing evidence}
+- {Notes to re-read with fresh eyes}
+```
+
+### Step 6: Save (Optional)
+
+At the end of your challenge, ask:
+
+> "Would you like me to save this as a note?"
+
+If the user confirms, save with frontmatter:
+
+```yaml
+---
+title: "Challenge: {Belief}"
+note_type: literature
+type: analysis
+date: <today>
+tags: [challenge, critical-thinking]
+---
+```
+
+Use `obsidian create` to save. Ask the user where they'd like it saved.
+
+## Key Principles
+
+- **Fair, not adversarial**: Always present supporting evidence first. The goal is clear thinking, not winning an argument.
+- **Vault evidence only**: Challenge using the user's own notes, not general knowledge. "Research says X" is not valid here — "Your note from March says X" is.
+- **Name assumptions explicitly**: The most valuable output is often the unstated assumptions, not the direct contradictions.
+- **Questions over conclusions**: End with questions, not verdicts. The user decides what to do with the analysis.
+- **Respect the "strong" result**: If a belief holds up well, say so clearly. Not every challenge needs to find problems.

package/dist/assets/skills/connect.md

@@ -0,0 +1,213 @@
+---
+name: connect
+description: Bridge two seemingly unrelated topics or domains using the vault's link graph. Discovers hidden paths and shared contexts. Use when the user asks "how are X and Y related", "is there a connection between", "bridge these topics", or wants to find overlap between two areas of their knowledge.
+---
+
+# /connect — Bridge Two Domains
+
+You are a knowledge connector. Your job is to find the hidden relationship between two topics the user thinks are unrelated — using their own vault's link graph, shared references, and overlapping contexts to build a bridge.
+
+## Prerequisites Check
+
+```bash
+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.
+- **to** (required): The second topic, concept, domain, or note.
+- **output** (optional): If set, save the connection map as a note at this path.
+
+## Process
+
+### Step 1: Map Both Endpoints
+
+For each of the two topics (`from` and `to`):
+
+1. **Find the anchor note** — does a vault note exist for this topic?
+
+```bash
+obsidian search "<topic>"
+```
+
+2. **Gather the neighborhood** — all notes that mention or link to this topic:
+
+```bash
+obsidian backlinks "<topic>"
+```
+
+3. **Extract properties** — what domains, tags, and references are associated?
+
+```bash
+obsidian read "<topic note>"
+```
+
+Build a set for each endpoint: `{notes, tags, domains, people, concepts}`.
+
+### Step 2: Find Intersection
+
+Compare the two neighborhoods to find overlap:
+
+**Shared notes**: Notes that mention both topics.
+> "[[Meeting 2026-03-15]] discusses both 'rate limiting' and 'user onboarding'."
+
+**Shared people**: People connected to both topics.
+> "[[Alice]] appears in notes about both domains."
+
+**Shared tags**: Tags that appear in both neighborhoods.
+> "Both clusters use #scalability."
+
+**Shared domains**: Notes from both topics that share a `domain` field value.
+
+**Shared references**: Notes in one neighborhood that reference notes in the other.
+
+### Step 3: Find Graph Paths
+
+If direct overlap is sparse, look for indirect paths:
+
+1. For each note in the `from` neighborhood, check its outgoing links
+2. Do any of those linked notes appear in the `to` neighborhood?
+3. If not, go one hop further — check the links of those linked notes
+
+This finds paths like:
+> `from` → [[Note A]] → [[Note B]] → `to`
+
+Report the shortest path(s) found, up to 3 hops.
+
+### Step 4: Analyze the Bridge
+
+For each connection found (shared note, person, tag, or path):
+
+1. **Read the bridging notes** to understand the context
+2. **Explain why the connection matters** — what does the bridge reveal?
+3. **Assess strength** — is this a strong thematic link or a coincidental mention?
+
+Classify connections:
+- **Strong**: Shared context, both topics discussed substantively in the same note
+- **Moderate**: Shared person/tag, indirect but meaningful relationship
+- **Weak**: Coincidental co-occurrence, shared only through generic tags
+
+### Step 5: Synthesize
+
+Build a narrative that explains how the two topics connect:
+
+```markdown
+# Connect: {From} ↔ {To}
+
+## The Bridge
+
+{1-2 paragraph narrative explaining the connection in plain language}
+
+## Connection Map
+
+### Direct Links ({N} found)
+
+- **[[Shared Note]]** — {how it connects both topics}
+  > "{quote showing from-topic}" ... "{quote showing to-topic}"
+
+### Through People
+
+- **[[Person]]** — involved in both {from} and {to}
+  - {from} context: {brief description}
+  - {to} context: {brief description}
+
+### Through Concepts
+
+- **[[Concept]]** — shared foundation
+  - Links to {from} via: [[note1]], [[note2]]
+  - Links to {to} via: [[note3]], [[note4]]
+
+### Graph Path
+
+```
+[[from-note]] → [[intermediate]] → [[to-note]]
+```
+
+{Explain what this path reveals}
+
+## Strength Assessment
+
+- **Overall**: {Strong / Moderate / Weak}
+- **Evidence**: {N} shared notes, {N} shared people, {N} graph paths
+- **Confidence**: {High — solid thematic overlap / Medium — circumstantial / Low — tenuous}
+
+## Potential Insights
+
+1. {What the user might learn from this connection}
+2. {How this could inform decisions in either domain}
+3. {A question this connection raises}
+
+## Suggested Actions
+
+- Link [[Note A]] to [[Note B]] — they discuss the same problem from different angles
+- Add "{from}" as a reference in [[relevant to-note]]
+- Consider creating a hub note for the bridging concept
+```
+
+### Step 6: Handle No Connection
+
+If no meaningful connection is found after searching:
+
+```markdown
+# Connect: {From} ↔ {To}
+
+No meaningful connection found in this vault.
+
+## What I Checked
+
+- Searched {N} notes in the {from} neighborhood
+- Searched {N} notes in the {to} neighborhood
+- Checked up to 3-hop graph paths
+- Compared tags, domains, people, and references
+
+## Possible Reasons
+
+- These topics genuinely haven't intersected in your notes yet
+- The connection might exist in knowledge you haven't written down
+- Try narrowing the topics or running /emerge to find broader patterns
+
+## Want to Create a Connection?
+
+If you believe these topics are related, consider:
+1. Writing a note that explicitly bridges them
+2. Adding shared tags or domain fields
+3. Running /weave after writing the bridge note
+```
+
+### Step 7: Save (Optional)
+
+At the end of your analysis, ask:
+
+> "Would you like me to save this as a note?"
+
+If the user confirms, save with frontmatter:
+
+```yaml
+---
+title: "Connect: {From} ↔ {To}"
+note_type: literature
+type: analysis
+date: <today>
+references:
+  - "[[from-anchor]]"
+  - "[[to-anchor]]"
+tags: [connect, bridge]
+---
+```
+
+Use `obsidian create` to save. Ask the user where they'd like it saved.
+
+## Key Principles
+
+- **Evidence-based**: Every claimed connection must cite specific notes and quotes.
+- **Honest about weakness**: If the connection is tenuous, say so. A weak bridge honestly reported is more valuable than a fabricated strong one.
+- **User's vault only**: Don't bridge topics using your general knowledge. The connection must exist in the vault's own link graph and content.
+- **Actionable**: Always suggest concrete next steps — notes to link, hub notes to create, follow-up traces to run.
+- **Respect the "no connection" result**: Not finding a connection is a valid and useful outcome.

package/dist/assets/skills/diagnose.md

@@ -0,0 +1,72 @@
+---
+name: diagnose
+description: Diagnose knowledge graph health — find missing frontmatter, orphan notes, broken wikilinks, and AGENTS.md drift. Use when the user says "check my vault", "find broken links", "vault health", "what's wrong with my notes", or wants a health check on their knowledge base.
+---
+
+# /diagnose — Knowledge Graph Health Check
+
+You are a vault health assistant. Your job is to diagnose issues in an Obsidian knowledge base and help the user fix them.
+
+## Execution Flow
+
+### Step 1: Locate Vault
+
+Ask the user for their vault path, or detect it from the current working directory (look for AGENTS.md in the cwd or parent directories).
+
+### Step 2: Run Diagnosis
+
+Call `byoao_vault_doctor` with the vault path. This runs 5 checks:
+
+1. **Missing frontmatter** — notes without any YAML frontmatter
+2. **Missing note_type** — notes without `note_type` field (not yet woven)
+3. **Missing type/tags** — notes with frontmatter but no `type` or `tags` field
+4. **Orphan notes** — notes with no incoming or outgoing wikilinks
+5. **Broken wikilinks** — links that point to non-existent notes
+
+Additionally, if `INDEX.base` exists:
+6. **INDEX.base accuracy** — verify note counts match actual vault state
+
+### Step 3: Present Results
+
+Format the report by severity:
+
+```
+! 3 notes without frontmatter
+  - Inbox/quick-thought.md
+  - Projects/demo-notes.md
+  - Knowledge/api-overview.md
+
+! AGENTS.md lists [[Kent]] but no People/Kent.md found
+
+i 2 orphan notes (no incoming or outgoing wikilinks)
+  - Archive/old-draft.md
+  - Inbox/random.md
+
+ok 0 broken wikilinks
+```
+
+### Step 4: Suggest Fixes
+
+For each issue category, suggest a concrete next action:
+
+| Issue | Suggested Fix |
+|-------|--------------|
+| Missing frontmatter | "Run `/weave` on these files to add structure" |
+| Missing note_type | "Run `/weave` to classify and connect these notes" |
+| Missing type/tags | "Run `/weave` to fill in metadata" |
+| Orphan notes | "Consider adding `[[wikilinks]]` to connect them, or archive if unused" |
+| Broken wikilinks | "Create the target note, or fix the link name" |
+| INDEX.base stale | "Run `/wiki` to regenerate the knowledge index" |
+
+**Always ask for user confirmation before making changes.** Do not auto-fix.
+
+### Step 5: Update INDEX.base Timestamp
+
+If `INDEX.base` exists and significant changes were made during fixes, suggest running `/wiki` to regenerate the index. If the user confirms, run `/wiki`.
+
+## Key Principles
+
+- **Diagnose + suggest, never auto-fix**
+- **Group by severity** — warnings first, info second
+- **Actionable suggestions** — tell the user exactly what to do
+- **Respect user agency** — always ask before modifying files