@jayjiang/byoao 1.1.0 → 1.1.2

package/src/skills/weave.md

@@ -1,11 +1,11 @@
 ---
 name: weave
-description: Scan vault notes, enrich with frontmatter + wikilinks, maintain the Glossary, create hub notes — building a connected knowledge graph. Use when the user says "connect my notes", "add links", "enrich", "run weave", or after importing new files into the vault.
+description: Scan vault notes, enrich with frontmatter + wikilinks, suggest permanent concept notes, and create a connected knowledge graph. Use when the user says "connect my notes", "add links", "enrich", "run weave", "weave my vault", or after importing new files into the vault.
 ---
 
 # /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.
+You are a knowledge graph builder. Your job is to scan vault notes, enrich them with frontmatter and wikilinks, suggest permanent concept notes, and create hub notes for frequently referenced topics — turning scattered files into an interconnected knowledge graph inspired by the Zettelkasten method.
 
 ## Prerequisites Check
 
@@ -44,8 +44,8 @@ When scanning files, skip:
 | `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 |
+| `AGENTS.md` | BYOAO-managed file |
+| `*.base` | Obsidian Base files — not user content notes |
 
 Report skipped non-markdown files at the end: "Skipped N non-markdown files".
 
@@ -53,15 +53,7 @@ Report skipped non-markdown files at the end: "Skipped N non-markdown files".
 
 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
+### Step 1: Build Vault Map
 
 ```bash
 obsidian list
@@ -75,51 +67,63 @@ 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
+### Step 2: Scan Target Files
 
 For each markdown file in scope (respecting exclusion rules):
 
-#### 3a. Read the file
+#### 2a. Read the file
 
 ```bash
 obsidian read "<note name>"
 ```
 
-#### 3b. Identify entities
+#### 2b. Identify entities
+
+Scan the content for concepts using semantic understanding (not a predefined list):
 
-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
+- **Methodologies/frameworks** — named approaches like "Zettelkasten", "Agile", etc.
 
-#### 3c. Cross-reference against Glossary + existing notes
+#### 2c. Cross-reference against 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
+1. Does a vault note with this name exist? → Mark as wikilink candidate
+2. Is it a new, unrecognized concept? → Track for permanent note suggestion (Step 4)
+
+#### 2d. Propose frontmatter
 
 If the file has no frontmatter, or has incomplete frontmatter, propose additions:
 
 ```yaml
 ---
 title: "<inferred from content or filename>"
+note_type: <fleeting | literature | permanent>
 type: "<inferred: meeting, idea, reference, daily, project, person, etc>"
 date: YYYY-MM-DD
 domain: "<knowledge area: analytics, infrastructure, design, etc>"
 references:
   - "[[Related Note]]"
-  - "[[Glossary]]"
 tags: [<relevant tags>]
 status: <draft | active | completed | archived>
 source: "<URL if this note originates from a cloud document>"
 ---
 ```
 
+**note_type classification (Zettelkasten):**
+
+| `note_type` | When to use |
+|-------------|-------------|
+| `fleeting` | Raw inputs: quick notes, meeting minutes, clipped articles, thoughts not yet processed |
+| `literature` | Processed references: summaries of papers, books, articles, or external sources |
+| `permanent` | Atomic concepts: single-idea notes that synthesize understanding from multiple sources |
+
+If unsure, default to `fleeting` — the user can reclassify later.
+
 **Date resolution (mandatory — never leave empty):**
 
 1. Extract from content — explicit dates in the text, meeting dates, file name patterns (e.g. `2026-03-27-meeting.md`)
@@ -146,12 +150,13 @@ source: "<URL if this note originates from a cloud document>"
 - **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
+#### 2e. Propose wikilinks
 
 Convert plain text mentions to `[[wikilinks]]`:
-- Glossary terms → `[[Term]]`
+
 - Existing note names → `[[Note Name]]`
 - People → `[[Person Name]]`
+- Domain concepts → `[[Concept Name]]`
 
 Rules:
 - Only link the **first occurrence** of each term in a file
@@ -159,7 +164,7 @@ Rules:
 - 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
+### Step 3: Backup Before Modification
 
 Before modifying any file, create a backup:
 
@@ -170,77 +175,77 @@ 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.
+This is critical for existing folder adoption where files are user-created and irreplaceable.
 
-### Step 5: Apply Changes
+### Step 4: 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 and classify candidates:
+### Step 5: Suggest Permanent Notes
 
-**High confidence (auto-suggest):** Entity appears in 5+ files AND has a clear,
-unambiguous definition (proper nouns, product names, acronyms, technical terms
-with standard meanings). Present as a batch for user review:
-- "'Kafka' mentioned in 8 notes — message streaming platform. Add to Glossary?"
+After scanning all files, analyze concept frequency across the vault:
 
-**Medium confidence (verify with user):** Entity appears in 3+ files but meaning
-is ambiguous or domain-specific. Ask the user to confirm the definition:
-- "'Migration' mentioned in 5 notes — what does this term mean in your context?"
+**When to suggest a permanent note:**
+- A concept appears in 3+ notes
+- No dedicated note exists for that concept
+- The concept has a clear, non-ambiguous definition
 
-**Skip:** Common words, generic phrases, or terms that appear fewer than 3 times.
-Do not suggest these.
+For each candidate, present to the user:
 
-- Always present Glossary additions as a batch for user review, not one-by-one
-- 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
+```markdown
+### Permanent Note Candidate: [[Concept Name]]
 
-### Step 7: Hub Note Creation
+**Appears in:** [[Note A]], [[Note B]], [[Note C]]
 
-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:
+**Proposed content:**
 
-```markdown
 ---
-title: "<Topic>"
+title: "Concept Name"
+note_type: permanent
 type: reference
-date: <today's date YYYY-MM-DD>
-domain: "<inferred domain>"
+domain: <inferred from source notes>
+date: <today>
+tags: [<inferred>]
 references:
-  - "[[note1]]"
-  - "[[note2]]"
-tags: [hub]
-status: active
+  - "[[Note A]]"
+  - "[[Note B]]"
 ---
 
-# <Topic>
+# Concept Name
+
+*Auto-generated by /weave — this concept appears across multiple notes. Review and refine.*
+
+## Summary
+<1-2 sentence summary synthesized from source notes>
+
+## References
+- [[Note A]] — <context>
+- [[Note B]] — <context>
+```
+
+Ask the user: "Create this permanent note?" Only create if confirmed.
+
+### Step 6: Suggest Note Splitting (Zettelkasten Atomicity)
 
-(Auto-created by /weave — this topic is mentioned across multiple notes)
+Check for notes that contain multiple independent concepts. For each candidate:
 
-## Referenced In
+```markdown
+### Split Suggestion: [[Multi-Concept Note]]
+
+This note appears to cover multiple distinct concepts:
+1. **Concept A** — <brief description>
+2. **Concept B** — <brief description>
+3. **Concept C** — <brief description>
 
-- [[note1]] — <brief context>
-- [[note2]] — <brief context>
+Consider splitting these into separate atomic notes for better knowledge graph connectivity.
 ```
 
-### Step 8: Directory Organization (optional)
+**Do NOT split automatically.** Only suggest; the user decides.
+
+### Step 7: Directory Organization (optional)
 
 If the vault has many files in flat or disorganized directories, suggest:
 
@@ -252,7 +257,7 @@ to safely relocate files while automatically updating all links."
 Do NOT move files during /weave — directory reorganization is
 a separate step handled by `/organize`.
 
-### Step 9: Report
+### Step 8: Report
 
 After all changes are applied, provide a summary:
 
@@ -261,9 +266,8 @@ 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
+- Permanent notes created: N
+- Split suggestions: N (pending user review)
 - Orphaned files (no links): N
 - Skipped: N non-markdown files
 - Backups: .byoao/backups/<timestamp>/
@@ -271,12 +275,13 @@ Weave complete:
 
 ## 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).
+When `file=` is provided, run the same process but only for that one file. Still read the vault map and check for cross-references, but skip Steps 5-6 (permanent note generation and split suggestions 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.
+- **Domain inference**: Use 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.
+- **Zettelkasten principle**: Favor atomicity. One idea per note. Suggest splits for multi-concept notes.

package/src/skills/wiki.md

@@ -0,0 +1,227 @@
+---
+name: wiki
+description: Generate INDEX.base knowledge graph at vault root and update AGENTS.md with current stats. Use when the user says "generate index", "build wiki", "update INDEX", "create knowledge map", or wants a visual overview of their vault.
+---
+
+# /wiki — Generate Knowledge Index
+
+You are a knowledge cartographer. Your job is to generate an `INDEX.base` file at the vault root that serves as the knowledge graph entry point, and update `AGENTS.md` with current vault statistics.
+
+## 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
+```
+
+## Process
+
+### Step 1: Build Vault Map
+
+```bash
+obsidian list
+```
+
+```bash
+obsidian properties sort=count counts
+```
+
+This gives you the full list of notes and their frontmatter distribution.
+
+### Step 2: Read Existing INDEX.base (if any)
+
+If `INDEX.base` already exists, read it to understand the current structure:
+
+```bash
+obsidian read "INDEX"
+```
+
+### Step 3: Analyze Knowledge Structure
+
+Group notes by their `domain` frontmatter field. For notes without `domain`, infer it from content. Count:
+- Total notes
+- Notes by `domain` (topics)
+- Notes by `note_type` (fleeting, literature, permanent)
+- Most frequently referenced concepts
+
+### Step 4: Generate INDEX.base
+
+Create or overwrite `INDEX.base` at the vault root. Use Obsidian CLI to create the file:
+
+```bash
+obsidian create name="INDEX" content="<YAML content>" silent overwrite
+```
+
+The content should be valid YAML for an Obsidian Base:
+
+```yaml
+filters:
+  not:
+    - 'note_type == ""'
+formulas: {}
+properties:
+  note_type:
+    displayName: Type
+  domain:
+    displayName: Domain
+views:
+  - type: table
+    name: "All Notes"
+    groupBy:
+      property: domain
+      direction: ASC
+    order:
+      - file.name
+      - note_type
+      - domain
+      - tags
+      - date
+  - type: cards
+    name: "Gallery"
+    groupBy:
+      property: note_type
+      direction: ASC
+    order:
+      - file.name
+      - note_type
+      - domain
+      - date
+```
+
+**IMPORTANT:** The YAML must be properly formatted. Use single quotes for formulas containing special characters. Ensure proper indentation (2 spaces).
+
+### Step 5: Generate AGENTS.md
+
+Read the current `AGENTS.md` (if it exists):
+
+```bash
+obsidian read "AGENTS"
+```
+
+Generate a complete `AGENTS.md` that serves as the agent's entry point for the vault. Use `obsidian create` with `overwrite`:
+
+```bash
+obsidian create path="AGENTS.md" content="<content>" overwrite silent
+```
+
+The AGENTS.md must contain these sections:
+
+**Header**
+```markdown
+# BYOAO — Build Your Own AI OS
+
+This knowledge base contains **M topics** and **N indexed notes**.
+```
+
+**Usage**
+```markdown
+## Usage
+
+- `/weave` — Scan notes, enrich with frontmatter and wikilinks, build the knowledge graph
+- `/wiki` — Regenerate the INDEX.base knowledge map
+- `/organize` — Suggest a directory structure based on frontmatter metadata
+```
+
+**Current Stats**
+```markdown
+## Current Stats
+
+- Total notes: {total}
+- Indexed notes (have note_type): {indexed}
+- Topics (domain): {domain1}, {domain2}, ...
+- Pending notes (need weave): {pending}
+```
+
+**Interacting with the Vault** — This is critical. The agent must always prefer Obsidian CLI:
+```markdown
+## Working with this Vault
+
+When you need to interact with notes, always use Obsidian CLI first:
+
+| Task | Command |
+|------|---------|
+| Search notes | `obsidian search query="keyword"` |
+| Read a note | `obsidian read file="Note Name"` |
+| Create a new note | `obsidian create name="Note Title" content="# Content"` |
+| Create note in folder | `obsidian create path="Folder/Note.md" content="# Content"` |
+| Append to a note | `obsidian append file="Note" content="New content"` |
+| Add frontmatter | `obsidian prepend file="Note" content='---
+title: "Title"
+note_type: fleeting
+domain: Topic
+date: YYYY-MM-DD
+tags: [tag1]
+---
+
+'` |
+| Rename/move a note | `obsidian move path="Old.md" to="NewFolder/New.md"` |
+| List backlinks | `obsidian backlinks file="Note"` |
+| Check links | `obsidian links file="Note"` |
+| List all files | `obsidian files ext=md` |
+| Check unresolved links | `obsidian unresolved total` |
+| Open random note | `obsidian random` |
+
+For multi-line content, use `\\n` for newlines in the `content=` parameter.
+```
+
+**Creating New Notes** — explicit guidance:
+```markdown
+## Creating New Notes
+
+When asked to write, research, or document something:
+
+1. **Search first** — `obsidian search query="topic"` to check if a relevant note already exists
+2. **Read existing notes** — `obsidian read file="Note"` to understand what's already captured
+3. **Create with frontmatter** — always include proper YAML frontmatter when creating:
+   ```
+   obsidian create name="New Note" content='---
+   title: "New Note"
+   note_type: fleeting
+   domain: YourDomain
+   date: YYYY-MM-DD
+   tags: [relevant-tags]
+   ---
+
+   # New Note
+
+   Content here...
+   '
+   ```
+4. **Link to existing notes** — use `[[wikilink]]` syntax to connect new notes to existing ones
+5. **Use `/weave` after bulk creation** — to enrich and connect the new notes to the graph
+```
+
+**Footer**
+```markdown
+---
+*Generated by /wiki skill*
+```
+
+### Step 6: Report
+
+```
+Wiki index generated:
+- INDEX.base: created/updated at vault root
+- Notes indexed: N
+- Topics: M (by domain)
+- AGENTS.md: updated with new counts
+```
+
+Suggest the user open `INDEX.base` in Obsidian to view the knowledge graph in table or card view.
+
+## Important Guidelines
+
+- **INDEX.base is a query, not static content** — it dynamically displays notes based on frontmatter. The file itself only contains the query configuration.
+- **Only index notes with `note_type`** — notes without this field are not yet processed by `/weave` and should not appear in the index.
+- **Preserve custom views** — if the user has added custom views to `INDEX.base`, merge new views rather than overwriting.
+- **Idempotent** — running `/wiki` multiple times should produce the same result without duplication.