@jayjiang/byoao 1.1.2 → 2.0.0

package/dist/assets/skills/trace.md

@@ -1,11 +1,14 @@
 ---
 name: trace
-description: Track how an idea, concept, or topic evolved across the vault over time. Builds a chronological timeline from scattered mentions. Use when the user asks "how did X evolve", "what's the history of", "when did we start thinking about", "trace this idea", or wants to understand the arc of a concept.
+description: >
+  Chronological timeline of an idea across notes. Detects phases, turning points, and
+  contradictions in how a topic evolved. Use when the user asks "how did X evolve",
+  "trace the history of Y", "timeline of Z", or wants to understand how an idea changed over time.
 ---
 
-# /trace — Track Idea Evolution
+# /trace — Chronological Timeline
 
-You are a knowledge archaeologist. Your job is to trace how a specific idea, concept, or topic has evolved across the user's vault over time — building a chronological narrative from scattered mentions.
+You are a historical detective. Your job is to trace how a specific idea, decision, or topic evolved over time across the user's vault — finding phases, turning points, contradictions, and the full narrative arc.
 
 ## Prerequisites Check
 
@@ -13,144 +16,126 @@ You are a knowledge archaeologist. Your job is to trace how a specific idea, con
 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
 
-- **topic** (required): The idea, concept, person, project, or term to trace.
-- **since** (optional): Start date for the trace (e.g. "2025-01-01"). Default: trace all history.
-- **output** (optional): If set, save the trace as a new note at this path.
+- **topic** (required): The idea, decision, or concept to trace.
+- **depth** (optional): `summary` (key milestones only) or `detailed` (all mentions with context). Default: `summary`.
 
 ## 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
+### Step 1: Locate All Mentions
 
-Search for the topic across the vault using multiple strategies:
+Search for the topic across all notes:
 
 ```bash
 obsidian search "<topic>"
+obsidian tags "<topic>"
 ```
 
-Also check:
-- `INDEX.base` if it exists, for domain and note_type classification
-- Backlinks to `[[<topic>]]` if a note exists for it
-- Tag variations: `#<topic>`, `#<topic-kebab-case>`
+Also search agent-maintained pages under `entities/`, `concepts/`, `comparisons/`, and `queries/`:
 
 ```bash
-obsidian backlinks "<topic>"
+obsidian read file="entities/<topic>.md"
+obsidian read file="concepts/<topic>.md"
+obsidian read file="comparisons/<topic>.md"
+obsidian read file="queries/<topic>.md"
 ```
 
+Read `INDEX.base` to check if there's already a compiled page for this topic.
+
 ### Step 2: Build Timeline
 
 For each note that mentions the topic:
 
-1. **Read the note** to understand the context of the mention
-2. **Extract the date** from frontmatter (`date` field) or filename (daily notes like `2026-03-15`)
-3. **Summarize** what the note says about the topic in 1-2 sentences
-4. **Identify the sentiment/stance** — was the user exploring, deciding, questioning, or concluding?
+1. Read the full content using `obsidian read`
+2. Extract the date (from frontmatter or filename for daily notes)
+3. Identify what the note says about the topic:
+   - **New idea proposed** — first mention of the concept
+   - **Decision made** — commitment to a specific approach
+   - **Change/evolution** — modification of previous understanding
+   - **Contradiction** — statement that conflicts with an earlier note
+   - **Confirmation** — validation of a previous position
+   - **Abandoned** — idea dropped or superseded
 
-Sort all mentions chronologically.
+### Step 3: Detect Phases
 
-### Step 3: Identify Phases
+Group the timeline into phases:
 
-Look for natural phases in how the topic evolved:
+- **Inception** — topic first appears, initial framing
+- **Exploration** — multiple approaches considered, debate
+- **Decision** — specific approach chosen
+- **Implementation** — execution details, adjustments
+- **Resolution** — outcome, lessons learned (or abandonment)
 
-- **Discovery** — first mentions, exploratory, lots of questions
-- **Investigation** — deeper dives, multiple notes, gathering evidence
-- **Decision** — a conclusion was reached, direction was set
-- **Implementation** — action taken, results documented
-- **Reflection** — looking back, lessons learned, re-evaluation
+A topic may skip phases, cycle back, or have multiple parallel tracks.
 
-Not every topic will have all phases. Some may cycle through phases multiple times.
+### Step 4: Identify Turning Points
 
-### Step 4: Detect Turning Points
+Highlight moments where the trajectory changed:
 
-Flag moments where the user's understanding or stance shifted:
+- "We switched from X to Y" — explicit change
+- Data or evidence that contradicted previous assumptions
+- New stakeholder or constraint that shifted direction
+- External event (tech release, policy change) that affected the topic
 
-- Contradictions: "In March you wrote X, but by June you concluded Y"
-- New information: "After reading [[Source]], your approach changed"
-- Decisions: "The meeting on 2026-04-10 resolved the debate"
-- Abandoned threads: "You explored X but never followed up after May"
+### Step 5: Find Contradictions
 
-### Step 5: Present the Trace
+Compare statements across time:
 
-Format the output as a structured timeline:
+- "In Note A (March 1): we decided X"
+- "In Note B (April 15): actually Y is better because..."
+- Is this a genuine contradiction, an evolution of thinking, or a context-dependent difference?
 
-```markdown
-# Trace: {Topic}
+Flag genuine contradictions. Note the dates, sources, and nature of the conflict.
 
-Traced across {N} notes, spanning {date range}.
+### Step 6: Present Timeline
 
-## Timeline
+```markdown
+# Timeline: {topic}
 
-### Phase 1: Discovery ({date range})
+Traced across {N} notes spanning {start date} to {end date}.
 
-- **{date}** — [[Note Name]]: {1-2 sentence summary}
-  > "{key quote from the note}"
-- **{date}** — [[Note Name]]: {summary}
+---
 
-### Phase 2: Investigation ({date range})
+## Phase 1: {Phase Name} ({date range})
 
-- **{date}** — [[Note Name]]: {summary}
+**What was happening**: {brief context}
 
-### Turning Point: {description}
+- **{date}** — [[Note A]]: {what happened / what was decided}
+- **{date}** — [[Note B]]: {what changed / what was added}
 
-- **{date}** — [[Note Name]]: {what changed and why}
+**Key insight**: {what this phase reveals}
 
-### Phase 3: Decision ({date range})
+---
 
-- **{date}** — [[Note Name]]: {summary}
+## Phase 2: {Phase Name} ({date range})
+...
 
-## Insights
+---
 
-- **Evolution**: {how the idea changed from start to now}
-- **Key influences**: {notes/people/events that shaped the direction}
-- **Open threads**: {aspects mentioned but never resolved}
-- **Current state**: {where the topic stands now}
+## Turning Points
 
-## Related Traces
+1. **{date}**: {what changed and why it mattered} — [[source note]]
 
-Consider tracing these connected topics:
-- [[Related Topic 1]] — mentioned in {N} of the same notes
-- [[Related Topic 2]] — appears to be a dependency
-```
+## Contradictions Found
 
-### Step 6: Save (Optional)
+- ⚠ [[Note A]] says X, but [[Note B]] says Y — {resolution if known}
 
-At the end of your trace, ask:
+## Current State
 
-> "Would you like me to save this as a note?"
+{Where things stand now — the most recent position on this topic}
 
-If the user confirms, save the trace with frontmatter:
+## Unanswered Questions
 
-```yaml
----
-title: "Trace: {Topic}"
-note_type: literature
-type: reference
-domain: <inferred from topic>
-date: <today>
-references:
-  - "[[note1]]"
-  - "[[note2]]"
-tags: [trace, <topic-tag>]
----
+{What the vault doesn't tell us about this topic's evolution}
 ```
 
-Use `obsidian create` to save. Ask the user where they'd like it saved.
-
 ## Key Principles
 
-- **Chronological accuracy**: Always verify dates. Don't guess — if a note has no date, say "undated."
-- **Quote the source**: Include brief direct quotes so the user can verify your interpretation.
-- **Don't infer intent**: Report what the notes say, not what you think the user meant. Flag contradictions but don't resolve them.
-- **Respect scope**: Only trace what's in the vault. Don't fill gaps with general knowledge.
-- **Highlight gaps**: If there's a 3-month silence on a topic, note it. Gaps are informative.
+- **Chronology is authority.** The timeline must follow actual note dates, not inferred order.
+- **Evidence-based.** Every claim in the timeline must cite a specific note.
+- **Show the messiness.** Ideas rarely evolve linearly. Show the false starts, reversals, and parallel tracks.
+- **Flag contradictions.** Don't resolve them — present both sides and let the user decide.
+- **Obsidian is first workbench.** All note operations go through Obsidian CLI.

package/dist/assets/skills/wiki.md

@@ -1,227 +1,126 @@
 ---
 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.
+description: >
+  Generate and maintain INDEX.base — the dynamic knowledge map for v2 agent pages (`type`:
+  entity | concept | comparison | query). Uses Obsidian Base queries to list agent-maintained
+  pages; SCHEMA.md defines tag taxonomy. Use when the user runs /wiki or wants to see the current
+  state of the knowledge base.
 ---
 
-# /wiki — Generate Knowledge Index
+# /wiki — Knowledge Map
 
-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.
+**Metaphor:** The menu board — shows what's been prepared and what's on offer.
 
-## Prerequisites Check
+## Purpose
 
-**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
-```
+Generate and maintain `INDEX.base`, the dynamic knowledge map that lists all agent-maintained pages grouped by v2 `type` (`entity`, `concept`, `comparison`, `query`). Unlike static index files, INDEX.base uses Obsidian Base queries to stay current automatically. Use `SCHEMA.md` for tag taxonomy when summarizing or grouping entries.
 
 ## Process
 
-### Step 1: Build Vault Map
-
-```bash
-obsidian list
-```
+### Step 1: Prerequisites Check
 
 ```bash
-obsidian properties sort=count counts
+obsidian --version
 ```
 
-This gives you the full list of notes and their frontmatter distribution.
+If this fails, STOP and display the Obsidian CLI availability message (see /prep).
 
-### Step 2: Read Existing INDEX.base (if any)
-
-If `INDEX.base` already exists, read it to understand the current structure:
+### Step 2: Read SCHEMA.md
 
 ```bash
-obsidian read "INDEX"
+obsidian read file="SCHEMA.md"
 ```
 
-### 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
+Understand the current tag taxonomy, domain definitions, and page conventions.
 
-### Step 4: Generate INDEX.base
+### Step 3: Generate INDEX.base Content
 
-Create or overwrite `INDEX.base` at the vault root. Use Obsidian CLI to create the file:
+Query all agent-maintained pages by v2 frontmatter `type` (`entity`, `concept`, `comparison`, `query`) so each page is listed under the correct section:
 
 ```bash
-obsidian create name="INDEX" content="<YAML content>" silent overwrite
+obsidian properties type=entity
+obsidian properties type=concept
+obsidian properties type=comparison
+obsidian properties type=query
 ```
 
-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
-```
+For each type, compile entries with:
+- Page name (as wikilink)
+- Title from frontmatter
+- Brief summary (from content's first paragraph or definition section)
+- Tags and domain
 
-**IMPORTANT:** The YAML must be properly formatted. Use single quotes for formulas containing special characters. Ensure proper indentation (2 spaces).
+Format by section:
 
-### Step 5: Generate AGENTS.md
+```markdown
+# Knowledge Index
 
-Read the current `AGENTS.md` (if it exists):
+## Entities
+- [[feature-a]] — Response time monitoring feature (tags: monitoring, backend)
+- [[zhang-san]] — Senior engineer on Feature A team (tags: team, engineering)
 
-```bash
-obsidian read "AGENTS"
-```
+## Concepts
+- [[response-time-metrics]] — Why median replaced avg for trigger calculation (tags: metrics, decisions)
+- [[search-trigger-rules]] — Search trigger rule design principles (tags: search, configuration)
 
-Generate a complete `AGENTS.md` that serves as the agent's entry point for the vault. Use `obsidian create` with `overwrite`:
+## Comparisons
+- [[avg-vs-median-for-trigger]] — Side-by-side analysis of avg vs median as trigger metrics (tags: metrics, decisions)
 
-```bash
-obsidian create path="AGENTS.md" content="<content>" overwrite silent
+## Queries
+- [[why-did-we-choose-median]] — "Why did we choose median over avg?" — detailed answer (tags: metrics, history)
 ```
 
-The AGENTS.md must contain these sections:
+### Step 4: Check Obsidian Base Configuration
 
-**Header**
-```markdown
-# BYOAO — Build Your Own AI OS
+INDEX.base relies on Obsidian Base (saved search) configuration. Verify:
 
-This knowledge base contains **M topics** and **N indexed notes**.
-```
+1. The Base query covers all four agent directories
+2. The query filters by `type` frontmatter field
+3. Results are grouped by type
 
-**Usage**
-```markdown
-## Usage
+If the Base doesn't exist or is misconfigured, guide the user to set it up:
+- Open Obsidian → Bases → Create new base
+- Name it "Knowledge Index"
+- Query: `path:entities/ OR path:concepts/ OR path:comparisons/ OR path:queries/`
+- Group by: `type`
 
-- `/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
-```
+### Step 5: Present the Index
 
-**Current Stats**
-```markdown
-## Current Stats
-
-- Total notes: {total}
-- Indexed notes (have note_type): {indexed}
-- Topics (domain): {domain1}, {domain2}, ...
-- Pending notes (need weave): {pending}
-```
+Show the current INDEX.base content to the user:
 
-**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]
----
+# Knowledge Index
 
-'` |
-| 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` |
+Generated on YYYY-MM-DD
 
-For multi-line content, use `\\n` for newlines in the `content=` parameter.
-```
+Total pages: N (X entities, Y concepts, Z comparisons, W queries)
 
-**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
-```
+## By Domain
+- backend: N pages
+- frontend: M pages
+- infrastructure: K pages
 
-**Footer**
-```markdown
----
-*Generated by /wiki skill*
-```
-
-### Step 6: Report
+## Most Connected
+- [[page-name]] — N inbound links
+- [[page-name]] — M inbound links
 
+## Recently Updated
+- [[page-name]] — updated YYYY-MM-DD
+- [[page-name]] — updated YYYY-MM-DD
 ```
-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.
+### Step 6: Suggest Gaps
+
+Based on the index, identify knowledge gaps:
+- Entity mentioned in multiple concepts but no entity page exists
+- Concept referenced in entity pages but no concept page exists
+- Domains with very few pages (under-represented areas)
+- Tags used frequently but no corresponding concept page
 
-## Important Guidelines
+## Key Principles
 
-- **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.
+- **INDEX.base is dynamic.** The Obsidian Base query keeps it current — no manual regeneration needed on every cook cycle.
+- **Summary quality.** Each entry's one-line summary should be genuinely informative, not just the page title repeated.
+- **Navigation first.** INDEX.base exists to help humans find knowledge quickly. Structure it for scanning, not completeness.
+- **Obsidian is first workbench.** All note operations go through Obsidian CLI.
+- **Agent pages only.** INDEX.base covers only `entities/`, `concepts/`, `comparisons/`, `queries/` — not user notes.

package/dist/cli/cli-program.js

@@ -130,8 +130,8 @@ program
 // ── byoao init ───────────────────────────────────────────────────
 program
     .command("init")
-    .description("Create a personal knowledge base — sets up folders, templates, " +
-    "glossary, and an AI routing index (AGENTS.md). Works with empty " +
+    .description("Create an LLM Wiki knowledge base — sets up agent directories, " +
+    "SCHEMA.md, log.md, and AI routing (AGENTS.md). Works with empty " +
     "directories or adopts existing folders.")
     .option("--kb <name>", "Knowledge base name (skips interactive prompt)")
     .option("--name <name>", "Your name (default: OS username in non-interactive mode)")
@@ -153,7 +153,7 @@ program
     let ownerName = opts.name || "";
     let vaultPath = opts.path || opts.from;
     let presetName = opts.preset || "minimal";
-    let members = [];
+    let wikiDomain = "";
     let mcpSkip = opts.mcpSkip || [];
     let gcpProjectId = opts.gcpProject || "";
     // Interactive TUI when --kb is not provided and stdout is TTY
@@ -235,15 +235,15 @@ program
                     vaultPath = customPath;
                 }
             }
-            // 4. Optional work preset
+            // 4. Work profile (preset)
             const presets = listPresets().filter(p => p.name !== "minimal");
             if (presets.length > 0) {
                 const { selectedPreset } = await inquirer.prompt([{
                         type: "list",
                         name: "selectedPreset",
-                        message: "Add a work preset? (optional)",
+                        message: "Choose your work profile:",
                         choices: [
-                            { name: "No — start with a minimal personal KB", value: "minimal" },
+                            { name: "Minimal — core LLM Wiki only", value: "minimal" },
                             ...presets.map(p => ({
                                 name: `${p.displayName} — ${p.description}`,
                                 value: p.name,
@@ -252,7 +252,15 @@ program
                     }]);
                 presetName = selectedPreset;
             }
-            // 5. MCP service selection (only if preset has MCP servers)
+            // 5. Wiki domain (optional)
+            const { domain } = await inquirer.prompt([{
+                    type: "input",
+                    name: "domain",
+                    message: "What domain does this knowledge base cover? (optional, press Enter to skip)",
+                    default: "",
+                }]);
+            wikiDomain = domain.trim();
+            // 6. MCP service selection (only if preset has MCP servers)
             if (presetName !== "minimal") {
                 const { config: presetCfg } = loadPreset(presetName);
                 const mcpEntries = Object.entries(presetCfg.mcpServers);
@@ -289,10 +297,6 @@ program
                     }
                 }
             }
-            // Create owner as a member if a preset with People/ is selected
-            if (ownerName && presetName !== "minimal") {
-                members.push({ name: ownerName, role: presetName === "pm-tpm" ? "PM/TPM" : "Team Member" });
-            }
         }
         catch {
             // inquirer not available — fall through to require --kb
@@ -316,12 +320,11 @@ program
         kbName,
         ownerName,
         vaultPath,
-        members,
-        projects: [],
         preset: presetName,
         provider: providerOpt,
         gcpProjectId,
         mcpSkip,
+        wikiDomain,
     });
     const spinner = startSpinner(`Creating knowledge base "${kbName}"`);
     const result = await createVault(config);
@@ -429,7 +432,7 @@ program
     printEventDetail(`     ${result.vaultPath}`);
     printEventDetail("  2. Enable Obsidian CLI: Settings → General → Advanced → Command-line interface");
     printEventDetail('  3. Read "Start Here.md" for a quick orientation');
-    printEventDetail("  4. Open the Agent Client panel and run /weave to connect your notes");
+    printEventDetail("  4. Open the Agent Client panel and run /cook to compile your notes into knowledge pages");
 });
 // ── byoao status ─────────────────────────────────────────────────
 program