@jayjiang/byoao 1.1.2 → 2.0.0

package/src/skills/connect.md

@@ -1,11 +1,14 @@
 ---
 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.
+description: >
+  Bridges two topics using the link graph, shared people, tags, domains, and conceptual
+  overlap. Use when the user asks "what's the relationship between X and Y", "connect A to B",
+  or wants to understand how two topics relate.
 ---
 
-# /connect — Bridge Two Domains
+# /connect — Bridge Two Topics
 
-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.
+You are a connector. Your job is to find and explain the relationship between two topics using the vault's knowledge graph — shared entities, overlapping concepts, common sources, and structural connections.
 
 ## Prerequisites Check
 
@@ -13,201 +16,110 @@ You are a knowledge connector. Your job is to find the hidden relationship betwe
 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.
+If this fails, STOP and display the Obsidian CLI availability message (see /prep).
 
 ## 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.
+- **from** (required): First topic or page name.
+- **to** (required): Second topic or page name.
+- **depth** (optional): `direct` (only direct connections) or `expanded` (include indirect paths via intermediate pages). Default: `expanded`.
 
 ## 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?
+### Step 1: Locate Both Topics
 
 ```bash
-obsidian search "<topic>"
+obsidian search "<from>"
+obsidian search "<to>"
 ```
 
-2. **Gather the neighborhood** — all notes that mention or link to this topic:
-
-```bash
-obsidian backlinks "<topic>"
-```
+If `INDEX.base` exists, read it to spot compiled pages for either topic.
 
-3. **Extract properties** — what domains, tags, and references are associated?
+Read any existing agent pages in `entities/`, `concepts/`, `comparisons/`, and `queries/`:
 
 ```bash
-obsidian read "<topic note>"
+obsidian read file="entities/<from>.md"  # if exists
+obsidian read file="concepts/<from>.md"  # if exists
+obsidian read file="comparisons/<from>.md"  # if exists
+obsidian read file="queries/<from>.md"  # if exists
+obsidian read file="entities/<to>.md"    # if exists
+obsidian read file="concepts/<to>.md"    # if exists
+obsidian read file="comparisons/<to>.md"  # if exists
+obsidian read file="queries/<to>.md"    # if exists
 ```
 
-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:
+### Step 2: Map Each Topic's Connections
 
-```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
+For each topic:
 
-- **[[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]]
+```bash
+obsidian backlinks "<from>"
+obsidian backlinks "<to>"
 ```
 
-{Explain what this path reveals}
+Read the pages that link to each topic. Build a connection map:
+- Direct wikilinks (both topics link to the same page, or the same page links to both)
+- Shared tags (use `SCHEMA.md` for taxonomy context when classifying)
+- Shared domain
+- Shared source notes (both topics were extracted from the same user note)
+- Shared people/entities mentioned in both topics' pages
 
-## Strength Assessment
+### Step 3: Find Direct Connections
 
-- **Overall**: {Strong / Moderate / Weak}
-- **Evidence**: {N} shared notes, {N} shared people, {N} graph paths
-- **Confidence**: {High — solid thematic overlap / Medium — circumstantial / Low — tenuous}
+Check if there's already a direct relationship:
+- Does the `from` page wikilink to `to` (or vice versa)?
+- Is there a `comparisons/` page that covers both?
+- Do they share a `sources` entry in frontmatter?
 
-## Potential Insights
+### Step 4: Find Indirect Paths (Expanded Mode)
 
-1. {What the user might learn from this connection}
-2. {How this could inform decisions in either domain}
-3. {A question this connection raises}
+If no direct connection exists, search for intermediate pages:
 
-## Suggested Actions
+1. Find all pages that link to `from`
+2. For each of those, check if they link to `to`
+3. If yes: `from` → `intermediate` → `to` is a connection path
+4. Report the shortest path(s) and explain the relationship
 
-- 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
+Also check:
+- Shared tag clusters (both topics use tags that co-occur frequently)
+- Shared domain context (both are about the same domain but different aspects)
+- Temporal overlap (both topics emerged around the same time)
 
-If no meaningful connection is found after searching:
+### Step 5: Present the Connection
 
 ```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
+# Connection: [[{from}]] ↔ [[{to}]]
 
-- 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
+## Direct Relationship
+{Yes/No} — {explain the direct connection if it exists}
 
-## Want to Create a Connection?
+## Connection Paths
+{If indirect paths exist, show them:}
 
-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:
+1. [[{from}]] → [[{intermediate}]] → [[{to}]]
+   - Path explanation: {how they connect through this intermediate}
 
-> "Would you like me to save this as a note?"
+## Shared Context
+- **Shared tags**: {tag1}, {tag2}
+- **Shared domain**: {domain}
+- **Shared sources**: [[source-note-1]], [[source-note-2]]
+- **Shared entities**: [[entity-1]], [[entity-2]]
 
-If the user confirms, save with frontmatter:
+## Relationship Type
+{Classify the relationship:}
+- **Dependency**: {from} depends on {to} (or vice versa)
+- **Sibling**: Both are aspects of a larger concept
+- **Contrast**: They represent opposing approaches
+- **Evolution**: {to} evolved from {from} over time
+- **Parallel**: Independent topics that happen to share context
 
-```yaml
----
-title: "Connect: {From} ↔ {To}"
-note_type: literature
-type: analysis
-date: <today>
-references:
-  - "[[from-anchor]]"
-  - "[[to-anchor]]"
-tags: [connect, bridge]
----
+## Why This Connection Matters
+{2-3 sentences on what this relationship reveals and why it's worth knowing}
 ```
 
-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.
+- **Graph over guesswork.** Base connections on actual wikilinks, shared tags, and shared sources — not inferred relationships.
+- **Multiple paths.** There may be several ways two topics connect — show the most meaningful ones, not just the shortest.
+- **Explain, don't just list.** The value is in the *explanation* of why the connection matters, not just the path itself.
+- **Obsidian is first workbench.** All note operations go through Obsidian CLI.

package/src/skills/cook.md

@@ -0,0 +1,167 @@
+---
+name: cook
+description: >
+  The core knowledge compilation skill. Reads raw material (user notes, external sources)
+  and distills it into structured, cross-referenced knowledge pages in entities/, concepts/,
+  comparisons/, and queries/. Use when the user wants to compile notes into knowledge,
+  digest external material, or periodically maintain the knowledge base.
+---
+
+# /cook — Knowledge Compilation
+
+You are a knowledge compiler. Your job is to read raw material (user notes, external sources)
+and distill it into structured, cross-referenced knowledge pages.
+
+## Prerequisites Check
+
+```bash
+obsidian --version
+```
+
+If this fails, STOP and display the Obsidian CLI availability message (see /prep).
+
+## Parameters
+
+- **target** (optional): What to cook. Default: incremental (new/modified notes since last cook).
+  - `--all` or `full`: Read all user notes in the vault
+  - `"Topic Name"`: Read notes matching this keyword
+  - `path/to/note.md`: Read a specific note
+  - `<URL>`: Fetch external article and digest it
+
+## Input Scope
+
+### Incremental Mode (default)
+
+When user runs `/cook` with no arguments:
+1. Read `log.md` for last cook timestamp
+2. Scan for `.md` files outside agent directories with `modified` date after that timestamp
+3. Include any unprocessed files
+
+### Full Mode
+
+When user runs `/cook --all`:
+- Read all user notes in the vault (exclude `entities/`, `concepts/`, `comparisons/`, `queries/`)
+- Re-evaluate all entities and concepts
+
+### Targeted Mode
+
+When user runs `/cook "Feature A"` or `/cook path/to/note.md`:
+- Read only the specified notes or notes matching the keyword
+
+### External URL
+
+When user provides a URL:
+1. Fetch content using WebFetch or Obsidian Web Clipper
+2. Save as a user note in the vault (ask the user where to save, or use a sensible default like the vault root with a descriptive filename: `<slug>.md`)
+3. Add frontmatter: `title`, `source_url`, `fetched` date
+4. Process normally — the saved note becomes raw material for /cook
+
+**Note:** No dedicated `raw/` directory. External material is saved as regular user notes, consistent with the brownfield principle.
+
+## Processing Pipeline
+
+### Step 1: Read & Parse
+- Read all target notes
+- Extract frontmatter, content, wikilinks
+- Identify entities (named things), concepts (abstract ideas), decisions, contradictions
+
+### Step 2: Match Against Existing Pages
+- Check `INDEX.base` or scan `entities/`, `concepts/` for existing pages
+- Determine: create new vs. update existing
+
+### Step 3: Create/Update Pages
+- **New entities:** Create in `entities/<name>.md`
+- **New concepts:** Create in `concepts/<name>.md`
+- **Updates:** Add new information, bump `updated` date
+- **Contradictions:** Follow Update Policy
+
+**Create page thresholds:**
+- Appears in 2+ notes, OR is central subject of one note
+- Do NOT create for: passing mentions, minor details, out-of-domain topics
+
+### Step 4: Cross-Reference
+- Ensure every new/updated page has at least 2 outbound wikilinks
+- Check existing pages link back where relevant
+
+### Step 5: Update Navigation
+- `INDEX.base` auto-updates via Obsidian Base query
+- Append entry to `log.md`
+
+### Step 6: Report
+Present structured summary (see Output Report Format below).
+
+## Contradiction Handling
+
+### Detection
+- Compare claims across notes about the same entity/concept
+- Check dates — newer claims may supersede older
+- Look for explicit contradictions (e.g., "we changed from X to Y")
+
+### Resolution Workflow
+1. Note both positions with dates and source references
+2. Mark in frontmatter: `contradictions: [page-name]`
+3. Report to user with specific sources
+4. Offer to create a comparison page
+5. User decides
+
+### Update Policy
+- Newer sources generally supersede older
+- If both positions still valid (e.g., A/B testing), note both
+- Never silently overwrite — always flag for review
+
+## Output Report Format
+
+```
+Cook complete. Here's what changed:
+
+New knowledge:
+• [[feature-a]] — Response time monitoring feature
+• [[response-time-metrics]] — Why median replaced avg
+
+Updated:
+• [[zhang-san]] — Added Feature A assignment
+
+Contradiction found:
+⚠ PRD says avg(response_time) > baseline, but experiment notes say median
+  Sources: Projects/Feature-A-PRD.md vs Daily/2026-04-05.md
+  Want me to create a comparison page?
+
+Log: 1 entry added to log.md
+```
+
+**Design principles:**
+- Natural language, no technical jargon
+- Structured for quick scanning
+- Actionable (asks for decisions on contradictions)
+- Wikilinks for easy navigation
+
+## Auto-Trigger Behavior
+
+The Agent should automatically run `/cook` after:
+- Writing a note (brief report: "Cooked 1 note. Updated [[x]], created [[y]].")
+- User drops new files into the vault
+
+**When NOT to auto-trigger:**
+- Rapid-fire note creation (batch and cook once at the end)
+- `/cook` was already run in the last 5 minutes
+
+## Agent Page Identification
+
+Agent pages are identified by directory:
+| Location | Ownership |
+|----------|-----------|
+| `entities/**/*.md` | Agent |
+| `concepts/**/*.md` | Agent |
+| `comparisons/**/*.md` | Agent |
+| `queries/**/*.md` | Agent |
+| All other `.md` | User (read-only during /cook) |
+
+No `owner` frontmatter field needed.
+
+## Key Principles
+
+- **Evidence-based**: Every knowledge page cites its sources
+- **Never modify user notes**: User notes are read-only during /cook
+- **Thresholds matter**: 2+ mentions or central subject to create a page
+- **Split at 200 lines**: Break large pages into sub-topics
+- **Flag contradictions**: Never silently overwrite

package/src/skills/diagnose.md

@@ -1,72 +1,131 @@
 ---
 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.
+description: >
+  Vault health check at the structural level. Checks frontmatter coverage, orphan notes,
+  broken links, AGENTS.md and SCHEMA.md drift, v2 agent directories, and overall vault configuration.
+  Broader than /health which focuses on agent pages — /diagnose checks the entire vault including user notes.
 ---
 
-# /diagnose — Knowledge Graph Health Check
+# /diagnose — Vault Diagnosis
 
-You are a vault health assistant. Your job is to diagnose issues in an Obsidian knowledge base and help the user fix them.
+You are a vault doctor. Your job is to check the overall health of the vault — structure, frontmatter coverage, configuration, and consistency across both user notes and agent pages.
 
-## Execution Flow
+## Prerequisites Check
 
-### Step 1: Locate Vault
+```bash
+obsidian --version
+```
+
+If this fails, STOP and display the Obsidian CLI availability message (see /prep).
 
-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).
+## Parameters
 
-### Step 2: Run Diagnosis
+- **focus** (optional): Specific area to check — `frontmatter`, `links`, `structure`, `config`, or `all`. Default: `all`.
 
-Call `byoao_vault_doctor` with the vault path. This runs 5 checks:
+## Process
 
-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
+### Step 1: Frontmatter Coverage
 
-Additionally, if `INDEX.base` exists:
-6. **INDEX.base accuracy** — verify note counts match actual vault state
+```bash
+obsidian properties sort=count counts
+```
 
-### Step 3: Present Results
+Report:
+- Total notes with frontmatter vs. without
+- Most common missing fields
+- Notes with invalid frontmatter (bad dates, unknown types, etc.)
+- Tag usage: how many unique tags, how many notes per tag
 
-Format the report by severity:
+### Step 2: Broken Wikilinks
 
+Scan for wikilinks that point to non-existent files:
+
+```bash
+obsidian search "\[\[.*\]\]"
 ```
-! 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
+For each wikilink found, check if the target file exists. Report broken links with:
+- Source file where the broken link appears
+- Target link that doesn't resolve
+- Suggested fix (create the missing file or remove the link)
+
+### Step 3: Orphan Detection
 
-i 2 orphan notes (no incoming or outgoing wikilinks)
-  - Archive/old-draft.md
-  - Inbox/random.md
+Find notes with no inbound wikilinks:
 
-ok 0 broken wikilinks
+```bash
+obsidian backlinks "note-name"
 ```
 
-### Step 4: Suggest Fixes
+For both user notes and agent pages, identify orphans. Note that newly created notes are expected to be orphans temporarily.
+
+### Step 4: AGENTS.md, SCHEMA.md, and v2 layout
+
+Check if `AGENTS.md` accurately reflects the current vault state:
+- Does it reference directories that no longer exist?
+- Does it miss directories that were added?
+- Are the skill references still valid?
+- Is the navigation advice still accurate?
+
+Check `SCHEMA.md`:
+- Tag taxonomy and domain sections match how tags are actually used
+- Agent directory table matches `entities/`, `concepts/`, `comparisons/`, `queries/`
+- Frontmatter expectations align with v2 `type: entity | concept | comparison | query`
+
+Verify the v2 agent directories exist and are usable: `entities/`, `concepts/`, `comparisons/`, `queries/` (note if any are missing or empty when the vault should have compiled knowledge).
+
+### Step 5: Configuration Check
 
-For each issue category, suggest a concrete next action:
+Verify vault configuration:
+- `.obsidian/` directory exists and is valid
+- `.opencode/` directory has current skill definitions
+- `SCHEMA.md` exists and has a defined tag taxonomy
+- `log.md` exists and has recent entries
+- `INDEX.base` exists for compiled knowledge discovery
 
-| 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" |
+### Step 6: Present Diagnosis
 
-**Always ask for user confirmation before making changes.** Do not auto-fix.
+```markdown
+# Vault Diagnosis
 
-### Step 5: Update INDEX.base Timestamp
+Scanned {N} notes, {M} agent pages, {K} user notes.
 
-If `INDEX.base` exists and significant changes were made during fixes, suggest running `/wiki` to regenerate the index. If the user confirms, run `/wiki`.
+---
+
+## Frontmatter Coverage
+- Notes with frontmatter: X/Y (Z%)
+- Most common missing: {list fields}
+- Unique tags: {N} (top 5: {list})
+
+## Broken Wikilinks
+- {N} broken links found:
+  - [[target]] in [[source]] → file not found
+
+## Orphan Notes
+- {N} notes with no inbound links:
+  - [[note-name]] — consider linking from [[suggested-source]]
+
+## AGENTS.md / SCHEMA.md / layout
+- AGENTS.md: {Up to date / Needs update} — {details if outdated}
+- SCHEMA.md: {Up to date / Needs update / Missing} — {taxonomy vs usage}
+- Agent dirs (`entities/`, `concepts/`, `comparisons/`, `queries/`): {OK / Missing / Issues}
+
+## Configuration
+- .obsidian/: {OK / Missing / Issues}
+- .opencode/: {OK / Missing / Issues}
+- log.md: {OK / Missing / {N} entries, last: {date}}
+- INDEX.base: {OK / Missing / Needs update}
+
+## Overall Health
+**Score**: {Good / Fair / Needs attention}
+
+{2-3 sentence summary of the vault's overall health and the top 2-3 issues to address}
+```
 
 ## 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
+- **Comprehensive but prioritized.** Check everything, but surface the most important issues first.
+- **Actionable findings.** Every issue should come with a suggested fix.
+- **Non-destructive by default.** Report issues, don't fix them automatically.
+- **Whole vault, not just agent pages.** Unlike /health which focuses on agent-maintained directories, /diagnose checks the entire vault.
+- **Obsidian is first workbench.** All note operations go through Obsidian CLI.