@jayjiang/byoao 0.5.0 → 0.6.0

package/src/skills/{vault-doctor.md → diagnose.md}

@@ -1,11 +1,11 @@
 ---
-name: vault-doctor
-description: Diagnose vault health — find missing frontmatter, orphan notes, broken wikilinks, and AGENT.md drift. Suggests fixes and asks for confirmation before making changes.
+name: diagnose
+description: Diagnose knowledge graph health — find missing frontmatter, orphan notes, broken wikilinks, and AGENT.md drift. Suggests fixes and asks for confirmation before making changes.
 ---
 
-# Vault Doctor
+# /diagnose — Knowledge Graph Health Check
 
-You are a vault health assistant. Your job is to diagnose issues in an Obsidian vault and help the user fix them.
+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
 
@@ -28,18 +28,18 @@ Call `byoao_vault_doctor` with the vault path. This runs 5 checks:
 Format the report by severity:
 
 ```
-⚠ 3 notes without frontmatter
+! 3 notes without frontmatter
   - Inbox/quick-thought.md
   - Projects/demo-notes.md
   - Knowledge/api-overview.md
 
-⚠ AGENT.md lists [[Kent]] but no People/Kent.md found
+! AGENT.md lists [[Kent]] but no People/Kent.md found
 
-ℹ 2 orphan notes (no incoming or outgoing wikilinks)
+i 2 orphan notes (no incoming or outgoing wikilinks)
   - Archive/old-draft.md
   - Inbox/random.md
 
-✓ 0 broken wikilinks
+ok 0 broken wikilinks
 ```
 
 ### Step 4: Suggest Fixes
@@ -48,9 +48,9 @@ For each issue category, suggest a concrete next action:
 
 | Issue | Suggested Fix |
 |-------|--------------|
-| Missing frontmatter | "Run `/enrich-document` on these files to add structure" |
-| Missing type/tags | "Run `/enrich-document` to fill in metadata" |
-| AGENT.md drift | "Create the missing note? I can run `byoao_add_member` or `byoao_add_project`" |
+| Missing frontmatter | "Run `/weave` on these files to add structure" |
+| Missing type/tags | "Run `/weave` to fill in metadata" |
+| AGENT.md drift | "Create the missing note? I can run `byoao_add_person` or `byoao_add_project`" |
 | Orphan notes | "Consider adding `[[wikilinks]]` to connect them, or archive if unused" |
 | Broken wikilinks | "Create the target note, or fix the link name" |
 
@@ -62,7 +62,7 @@ After fixes are applied (with user consent), append or update a `Last Scanned` l
 
 ```markdown
 ---
-_Last scanned by vault-doctor: 2026-03-13_
+_Last scanned by /diagnose: 2026-03-27_
 ```
 
 ## Key Principles

package/src/skills/{system-explainer.md → explain.md}

@@ -1,9 +1,9 @@
 ---
-name: system-explainer
+name: explain
 description: Explain codebase systems and workflows in clear, non-jargon language. Uses engineer-generated overviews as baseline, reads local repo clones for details, caches knowledge in Obsidian vault.
 ---
 
-# System Explainer
+# /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.
 
@@ -12,21 +12,21 @@ You are a codebase knowledge assistant for knowledge workers. Your job is to exp
 System knowledge comes from three sources, in priority order:
 
 ```
-Layer 1: Baseline Overview    — Engineer-generated CLAUDE.md per repo (high-level architecture)
+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 using Claude Code `/init`, which produces a CLAUDE.md containing architecture, key paths, conventions, and dependencies. These overviews are stored at:
+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     # CLAUDE.md content from payment-service repo
-├── auth-service.md        # CLAUDE.md content from auth-service repo
-└── api-gateway.md         # CLAUDE.md content from api-gateway repo
+  _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.

package/src/skills/weave.md

@@ -0,0 +1,240 @@
+---
+name: weave
+description: Scan vault notes, enrich with frontmatter + wikilinks, maintain the Glossary, create hub notes — building a connected knowledge graph.
+---
+
+# /weave — Connect Your Notes
+
+You are a knowledge graph builder. Your job is to scan vault notes, enrich them with frontmatter and wikilinks, maintain the Glossary as an entity dictionary, and create hub notes for frequently referenced topics — turning scattered files into an interconnected knowledge graph.
+
+## Prerequisites Check
+
+**Before doing anything else**, verify Obsidian CLI is available:
+
+```bash
+obsidian --version
+```
+
+If this fails, STOP and display:
+
+```
+Obsidian CLI is not available. Please ensure:
+1. Obsidian is running
+2. This vault is open in Obsidian
+3. CLI is enabled: Settings → General → Advanced → Command-line interface
+```
+
+Do NOT proceed with degraded results — graph queries are essential.
+
+## Parameters
+
+- **file** (optional): Path to a single file to weave. If omitted, scan the entire vault.
+- **folder** (optional): Path to a folder to scan. If omitted, scan the entire vault.
+- **dry-run** (optional): If set, show proposed changes without applying them.
+
+## File Exclusion Rules
+
+When scanning files, skip:
+
+| Pattern | Reason |
+|---------|--------|
+| `.obsidian/` | Obsidian internal config |
+| `.git/` | Git internals |
+| `.byoao/` | BYOAO internal data |
+| `node_modules/` | Dependencies |
+| `.env`, `credentials.*`, `*.key` | Sensitive files |
+| Binary files (images, PDFs, etc.) | Cannot add frontmatter/wikilinks |
+| `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
+
+Execute these steps in order. Be explicit about each tool call — different LLM providers must execute this consistently.
+
+### Step 1: Load Glossary
+
+```bash
+obsidian read "Knowledge/Glossary.md"
+```
+
+Parse the Glossary table. Extract all existing terms — these are automatic wikilink candidates for every file you scan.
+
+### Step 2: Build Vault Map
+
+```bash
+obsidian list
+```
+
+This gives you the full list of notes. Also run:
+
+```bash
+obsidian properties sort=count counts
+```
+
+This reveals the vault's structure — which properties are used, how many notes have frontmatter.
+
+### Step 3: Scan Target Files
+
+For each markdown file in scope (respecting exclusion rules):
+
+#### 3a. Read the file
+
+```bash
+obsidian read "<note name>"
+```
+
+#### 3b. Identify entities
+
+Scan the content for:
+- **People names** — proper nouns that appear to be people
+- **Project/product names** — capitalized multi-word phrases that recur
+- **Domain concepts** — technical terms, acronyms, recurring themes
+- **Tool/system names** — software, services, platforms mentioned
+- **Dates and events** — meetings, deadlines, milestones
+
+#### 3c. Cross-reference against Glossary + existing notes
+
+For each entity found:
+1. Is it already a Glossary term? → Mark as wikilink candidate
+2. Does a vault note with this name exist? → Mark as wikilink candidate
+3. Is it a new, unrecognized entity? → Track for Glossary suggestion (Step 5)
+
+#### 3d. Propose frontmatter
+
+If the file has no frontmatter, or has incomplete frontmatter, propose additions:
+
+```yaml
+---
+title: "<inferred from content or filename>"
+type: "<inferred: meeting, idea, reference, daily, project, person, etc>"
+date: <if identifiable from content>
+domain: "<knowledge area: analytics, infrastructure, design, etc>"
+references:
+  - "[[Related Note]]"
+  - "[[Glossary]]"
+tags: [<relevant tags>]
+status: <draft | active | completed | archived>
+---
+```
+
+**Frontmatter preservation rules:**
+- **Never overwrite** existing fields
+- **Only add** missing fields
+- **Merge arrays** — if file has `tags: [meeting]` and you suggest `tags: [meeting, migration]`, result is `[meeting, migration]`
+- **Warn on conflicts** — if existing value seems wrong, note it but don't change it
+
+#### 3e. Propose wikilinks
+
+Convert plain text mentions to `[[wikilinks]]`:
+- Glossary terms → `[[Term]]`
+- Existing note names → `[[Note Name]]`
+- People → `[[Person Name]]`
+
+Rules:
+- Only link the **first occurrence** of each term in a file
+- Don't link inside code blocks, frontmatter, or existing wikilinks
+- Don't link common English words even if they happen to match a note name
+- Preserve the original text when the casing differs: `rate limiting` → `[[Rate Limiting|rate limiting]]`
+
+### Step 4: Backup Before Modification
+
+Before modifying any file, create a backup:
+
+```bash
+mkdir -p .byoao/backups/<timestamp>
+cp "<file path>" ".byoao/backups/<timestamp>/<filename>"
+```
+
+Use the current date-time as the timestamp (e.g., `2026-03-27T20-45`).
+
+This is critical for existing folder adoption (Mode B) where files are user-created and irreplaceable.
+
+### Step 5: Apply Changes
+
+For each file with proposed changes:
+1. Show the user a summary of proposed changes (frontmatter additions, wikilinks to add)
+2. Wait for confirmation before applying
+3. Apply changes using file edit tools
+
+### Step 6: Glossary Maintenance
+
+After scanning all files, analyze entity frequency:
+
+**New term suggestions:**
+- An entity appears in 3+ files but is not in the Glossary
+- Present each suggestion: "'Kafka' mentioned in 8 notes. Add to Glossary? (Y/n)"
+- For confirmed terms, use `byoao_add_glossary_term` to add them
+
+**Auto-graduation suggestions:**
+- A Glossary term is referenced by 5+ notes
+- Suggest creating a standalone concept note in `Knowledge/`
+- The concept note gets auto-generated frontmatter:
+  ```yaml
+  domain: <from Glossary>
+  references:
+    - "[[note1]]"
+    - "[[note2]]"
+  ```
+- Update the Glossary entry to link to the concept note
+
+### Step 7: Hub Note Creation
+
+Identify entities that are frequently mentioned but have no corresponding note:
+- "12 files mention 'Payment Migration' but no note exists — create it?"
+- Hub notes aggregate references and provide a landing page for the topic
+- Hub note template:
+
+```markdown
+---
+title: "<Topic>"
+type: reference
+domain: "<inferred domain>"
+references:
+  - "[[note1]]"
+  - "[[note2]]"
+tags: [hub]
+status: active
+---
+
+# <Topic>
+
+(Auto-created by /weave — this topic is mentioned across multiple notes)
+
+## Referenced In
+
+- [[note1]] — <brief context>
+- [[note2]] — <brief context>
+```
+
+### Step 8: Report
+
+After all changes are applied, provide a summary:
+
+```
+Weave complete:
+- Scanned: N files
+- Enriched: N files (frontmatter + wikilinks)
+- Wikilinks added: N
+- Glossary terms added: N
+- Hub notes created: N
+- Concept notes graduated: N
+- Orphaned files (no links): N
+- Skipped: N non-markdown files
+- Backups: .byoao/backups/<timestamp>/
+```
+
+## Single File Mode
+
+When `file=` is provided, run the same process but only for that one file. Still read the Glossary and check for cross-references, but skip Steps 6-7 (Glossary maintenance and hub note creation are batch operations).
+
+## Important Guidelines
+
+- **Be conservative**: When in doubt about a wikilink or frontmatter value, skip it. False positives degrade trust.
+- **Ask, don't assume**: Always present changes for user confirmation before applying.
+- **Preserve user content**: Never delete, rewrite, or reorganize existing text. Only add metadata and convert mentions to links.
+- **Domain inference**: Use Glossary domains and existing note domains to infer the domain for new notes. Consistency matters.
+- **Idempotent**: Running /weave twice on the same file should not add duplicate wikilinks or frontmatter fields.

package/src/assets/web-clipper/confluence-page.json

@@ -1,63 +0,0 @@
-{
-  "schemaVersion": "0.1.0",
-  "name": "BYOAO — Confluence Page",
-  "behavior": "create",
-  "noteContentFormat": "text",
-  "properties": [
-    {
-      "name": "title",
-      "value": "{{title|safe_name}}",
-      "type": "text"
-    },
-    {
-      "name": "type",
-      "value": "confluence-clip",
-      "type": "text"
-    },
-    {
-      "name": "source",
-      "value": "{{url}}",
-      "type": "text"
-    },
-    {
-      "name": "author",
-      "value": "{{selector:.contributor-list a|wikilink}}",
-      "type": "text"
-    },
-    {
-      "name": "space",
-      "value": "{{selector:#breadcrumb-nav a:first-child}}",
-      "type": "text"
-    },
-    {
-      "name": "labels",
-      "value": "{{selector:.label-list a}}",
-      "type": "multitext"
-    },
-    {
-      "name": "last-modified",
-      "value": "{{selector:.last-modified time}}",
-      "type": "text"
-    },
-    {
-      "name": "clipped-date",
-      "value": "{{date}}",
-      "type": "date"
-    },
-    {
-      "name": "status",
-      "value": "inbox",
-      "type": "text"
-    },
-    {
-      "name": "tags",
-      "value": "[confluence-clip, {{\"Based on this Confluence page content, suggest 3 relevant topic tags as comma-separated values (no # prefix, lowercase, hyphenated). Output ONLY the tags, nothing else.\"|prompt}}]",
-      "type": "multitext"
-    }
-  ],
-  "noteNameFormat": "{{date}} — {{title|safe_name|truncate:80}}",
-  "path": "Inbox",
-  "triggers": ["atlassian.net/wiki", "confluence"],
-  "context": "{{content}}",
-  "body": "## Summary\n\n{{\"Summarize the key points of this Confluence page in 3-5 bullet points. Focus on decisions, action items, and important context. Be concise.\"|prompt}}\n\n---\n\n## Original Content\n\n{{content}}"
-}

package/src/assets/web-clipper/general-article.json

@@ -1,53 +0,0 @@
-{
-  "schemaVersion": "0.1.0",
-  "name": "BYOAO — General Article",
-  "behavior": "create",
-  "noteContentFormat": "text",
-  "properties": [
-    {
-      "name": "title",
-      "value": "{{title|safe_name}}",
-      "type": "text"
-    },
-    {
-      "name": "type",
-      "value": "web-clip",
-      "type": "text"
-    },
-    {
-      "name": "source",
-      "value": "{{url}}",
-      "type": "text"
-    },
-    {
-      "name": "author",
-      "value": "{% if author %}{{author|wikilink}}{% elseif meta:property:article:author %}{{meta:property:article:author|wikilink}}{% else %}unknown{% endif %}",
-      "type": "text"
-    },
-    {
-      "name": "published",
-      "value": "{% if meta:property:article:published_time %}{{meta:property:article:published_time|date:'YYYY-MM-DD'}}{% else %}{{date}}{% endif %}",
-      "type": "date"
-    },
-    {
-      "name": "clipped-date",
-      "value": "{{date}}",
-      "type": "date"
-    },
-    {
-      "name": "status",
-      "value": "inbox",
-      "type": "text"
-    },
-    {
-      "name": "tags",
-      "value": "[web-clip, {{\"Based on this article, suggest 3 relevant topic tags as comma-separated values (no # prefix, lowercase, hyphenated). Output ONLY the tags, nothing else.\"|prompt}}]",
-      "type": "multitext"
-    }
-  ],
-  "noteNameFormat": "{{date}} — {{title|safe_name|truncate:80}}",
-  "path": "Inbox",
-  "triggers": [],
-  "context": "{{content|truncate:3000}}",
-  "body": "## Summary\n\n{{\"Summarize this article in 3-5 bullet points. Focus on key insights, conclusions, and actionable takeaways. Be concise.\"|prompt}}\n\n## Key Quotes\n\n{% if highlights %}{% for highlight in highlights %}\n> {{highlight}}\n{% endfor %}{% else %}\n*No highlights selected. Use the Web Clipper highlighter to capture key passages.*\n{% endif %}\n\n---\n\n## Original Content\n\n{{content}}\n\n---\n\n*Clipped from [{{domain}}]({{url}}) on {{date}}*"
-}

package/src/assets/web-clipper/jira-issue.json

@@ -1,68 +0,0 @@
-{
-  "schemaVersion": "0.1.0",
-  "name": "BYOAO — Jira Issue",
-  "behavior": "create",
-  "noteContentFormat": "text",
-  "properties": [
-    {
-      "name": "title",
-      "value": "{{selector:#summary-val|default:title}}",
-      "type": "text"
-    },
-    {
-      "name": "type",
-      "value": "jira-clip",
-      "type": "text"
-    },
-    {
-      "name": "jira-key",
-      "value": "{{selector:#key-val}}",
-      "type": "text"
-    },
-    {
-      "name": "source",
-      "value": "{{url}}",
-      "type": "text"
-    },
-    {
-      "name": "status",
-      "value": "{{selector:#status-val span}}",
-      "type": "text"
-    },
-    {
-      "name": "priority",
-      "value": "{{selector:#priority-val img|attr:alt}}",
-      "type": "text"
-    },
-    {
-      "name": "assignee",
-      "value": "{{selector:#assignee-val span|wikilink}}",
-      "type": "text"
-    },
-    {
-      "name": "reporter",
-      "value": "{{selector:#reporter-val span|wikilink}}",
-      "type": "text"
-    },
-    {
-      "name": "issue-type",
-      "value": "{{selector:#type-val}}",
-      "type": "text"
-    },
-    {
-      "name": "clipped-date",
-      "value": "{{date}}",
-      "type": "date"
-    },
-    {
-      "name": "tags",
-      "value": "[jira-clip]",
-      "type": "multitext"
-    }
-  ],
-  "noteNameFormat": "{{selector:#key-val|default:title|safe_name}} — {{selector:#summary-val|default:title|safe_name|truncate:60}}",
-  "path": "Inbox",
-  "triggers": ["atlassian.net/browse", "atlassian.net/jira"],
-  "context": "{{content}}",
-  "body": "## Summary\n\n**Status**: {{selector:#status-val span}} | **Priority**: {{selector:#priority-val img|attr:alt}} | **Assignee**: {{selector:#assignee-val span}}\n\n## Description\n\n{{selector:#description-val|markdown}}\n\n{% if selector:.acceptance-criteria %}## Acceptance Criteria\n\n{{selector:.acceptance-criteria|markdown}}\n{% endif %}\n\n---\n\n*Clipped from [Jira]({{url}}) on {{date}}*"
-}

package/src/assets/web-clipper/meeting-notes.json

@@ -1,53 +0,0 @@
-{
-  "schemaVersion": "0.1.0",
-  "name": "BYOAO — Meeting Notes",
-  "behavior": "create",
-  "noteContentFormat": "text",
-  "properties": [
-    {
-      "name": "title",
-      "value": "{{title|safe_name}}",
-      "type": "text"
-    },
-    {
-      "name": "type",
-      "value": "meeting-notes",
-      "type": "text"
-    },
-    {
-      "name": "source",
-      "value": "{{url}}",
-      "type": "text"
-    },
-    {
-      "name": "date",
-      "value": "{{date}}",
-      "type": "date"
-    },
-    {
-      "name": "participants",
-      "value": "",
-      "type": "multitext"
-    },
-    {
-      "name": "project",
-      "value": "",
-      "type": "text"
-    },
-    {
-      "name": "status",
-      "value": "inbox",
-      "type": "text"
-    },
-    {
-      "name": "tags",
-      "value": "[meeting-notes]",
-      "type": "multitext"
-    }
-  ],
-  "noteNameFormat": "{{date}} — Meeting — {{title|safe_name|truncate:60}}",
-  "path": "Inbox",
-  "triggers": ["meet.google.com", "calendar.google.com", "outlook.office.com"],
-  "context": "{% if selection %}{{selection}}{% else %}{{content|truncate:3000}}{% endif %}",
-  "body": "## Meeting Info\n\n- **Date**: {{date}}\n- **Participants**: *fill in after meeting*\n- **Project**: *link to project*\n\n## Agenda / Context\n\n{% if selection %}{{selection|markdown}}{% else %}{{content|markdown}}{% endif %}\n\n## Notes\n\n- \n\n## Action Items\n\n- [ ] \n\n## Decisions\n\n- \n\n---\n\n*Clipped from [{{domain}}]({{url}}) on {{date}}*"
-}

package/src/skills/enrich-document.md

@@ -1,52 +0,0 @@
----
-name: enrich-document
-description: Auto-enrich an Obsidian note with frontmatter properties and wikilinks. Reads existing vault context to suggest connections.
----
-
-# Enrich Document
-
-You are a document enrichment assistant. Your job is to improve Obsidian notes by adding proper frontmatter and wikilinks based on the vault's existing content.
-
-## Process
-
-1. **Read the target note** that needs enrichment.
-
-2. **Scan the vault** for context:
-   - Use `byoao_vault_status` to understand what's in the vault
-   - Read `AGENT.md` for project/people index
-   - Read `Knowledge/Glossary.md` for domain terms
-
-3. **Add/fix frontmatter**:
-   - Ensure `title`, `type`, `status`, `date`, `tags` are present
-   - Infer `type` from content: meeting → "meeting", feature spec → "feature", etc.
-   - Add `team`, `project`, `stakeholders` if identifiable from content
-
-4. **Add wikilinks**:
-   - Link mentions of people names to `[[Person Name]]`
-   - Link mentions of projects to `[[Project Name]]`
-   - Link domain terms to `[[Glossary]]` or concept notes
-   - Link related system references to `Systems/` docs
-
-5. **Preserve content**: Never delete or rewrite user content. Only add frontmatter and convert plain text mentions to wikilinks.
-
-## Example
-
-Before:
-```markdown
-Met with Alice and Bob about the payment migration. Need to check with the platform team about API rate limits.
-```
-
-After:
-```markdown
----
-title: "Payment Migration Discussion"
-type: meeting
-date: 2026-03-12
-team: HDR Operations
-project: Payment Migration
-stakeholders: [Alice, Bob]
-tags: [meeting, payment, migration]
----
-
-Met with [[Alice]] and [[Bob]] about the [[Payment Migration]]. Need to check with the [[Platform Team]] about API rate limits.
-```