@jayjiang/byoao 1.1.2 → 2.0.1

package/dist/assets/skills/organize.md

@@ -1,206 +1,107 @@
 ---
 name: organize
-description: Reorganize vault directory structure using Obsidian CLI's move command, which safely updates all backlinks. Analyzes enriched frontmatter (type, domain) to propose a logical folder layout. Use when the user says "organize my vault", "reorganize files", "clean up folders", "restructure", or after running /weave on a messy vault.
+description: >
+  Directory organization based on frontmatter metadata. Suggests and applies file moves to
+  keep the vault structured. Use when the user wants to reorganize notes, fix directory
+  placement, or clean up the vault structure.
 ---
 
-# /organize — Vault Directory Reorganization
+# /organize — Directory Organization
 
-You are a vault organizer. Your job is to analyze the current directory structure, propose a logical reorganization based on enriched frontmatter metadata, and execute moves safely using Obsidian CLI — which automatically updates all backlinks and wikilinks.
+You are a librarian. Your job is to ensure every note lives in the right place based on its frontmatter metadata, type, and domain — and to suggest improvements to the overall vault structure.
 
 ## Prerequisites Check
 
-**Before doing anything else:**
-
-1. 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
-```
-
-2. Check that files have frontmatter (specifically `type`). Run:
-
-```bash
-obsidian properties sort=count counts
-```
-
-If `type` property has very low coverage (< 30% of notes), STOP and suggest:
-
-```
-Most files lack a `type` property — /organize needs frontmatter to
-decide where files belong. Run /weave first to enrich your notes,
-then come back to /organize.
-```
+If this fails, STOP and display the Obsidian CLI availability message (see /prep).
 
 ## Parameters
 
-- **scope** (optional): `all` (default) or a specific directory path to reorganize
-- **dry-run** (optional): If set, show proposed changes without executing
-- **aggressive** (optional): Also suggest consolidating existing directory structures (e.g., merge year-based sprint folders into `Sprints/`)
-
-## File Exclusion Rules
-
-Never move or suggest moving:
-
-| Pattern | Reason |
-|---------|--------|
-| `AGENTS.md` | BYOAO-managed root file |
-| `INDEX.base` | Knowledge graph index — do not move |
-| `Start Here.md` | BYOAO onboarding file |
-| `.obsidian/`, `.git/`, `.byoao/` | System directories |
-| `.opencode/`, `.cursor/`, `.claude/` | Tool config directories |
-| `.env`, `credentials.*`, `*.key` | Sensitive files |
+- **scope** (optional): `all` (full vault), `agents` (agent pages only), `sources` (user notes), or a specific directory. Default: `all`.
+- **dry_run** (optional): `true` to only suggest, `false` to apply changes. Default: `true`.
 
 ## Process
 
-### Step 1: Analyze Current Structure
-
-Build a complete picture of the vault:
+### Step 1: Scan Current Structure
 
 ```bash
 obsidian list
 ```
 
-Then read frontmatter for every file to build a map of `path → {type, domain, project, tags}`. Use batch reading:
+Build a picture of:
+- Current directory structure
+- Notes in each directory
+- Notes that seem misplaced based on their frontmatter
 
-```bash
-obsidian read "<note name>"
-```
-
-Categorize every file into one of:
-- **Has type** — can be auto-organized based on the mapping table
-- **No type but in coherent directory** — already organized, leave in place
-- **No type and in root/flat dir** — suggest running `/weave` first
-
-### Step 2: Build Reorganization Map
+### Step 2: Check Agent Pages
 
-For each file with a `type` property, determine if it should move based on this mapping:
+Agent pages should live in their designated directories:
 
-| `type` | Target Directory | Notes |
-|--------|-----------------|-------|
-| `daily` | `Daily/` | |
-| `meeting` | Project folder if `project` field exists, else `Meetings/` | Group by project when possible |
-| `feature` | `Projects/<project>/` | Use `project` frontmatter field |
-| `project` | `Projects/` | Top-level project notes |
-| `sprint-handoff` | `Sprints/` | |
-| `reference` | `Knowledge/` or user's preferred reference location | General reference material |
-| `person` | `People/` | |
-| `investigation` | Project folder if `project` field exists, else `Knowledge/` | |
-| `idea` | `Knowledge/` | |
-| `decision` | Project folder if `project` field exists, else `Knowledge/` | |
+| `type` frontmatter | Expected directory |
+|-------------------|-------------------|
+| `entity` | `entities/` |
+| `concept` | `concepts/` |
+| `comparison` | `comparisons/` |
+| `query` | `queries/` |
 
-**Smart rules — when NOT to move:**
+For each agent page, check:
+- Does its current directory match its `type`?
+- If not, suggest a move
 
-1. **Already in the right place** — if a `type: meeting` file is already in `Meetings/` or inside a project folder, skip it
-2. **Part of a coherent group** — if a file sits in `2025 Sprint/Sprint22/JIRA ticket/` alongside related files, the entire group is already organized even if the parent folder name doesn't match BYOAO conventions. Do NOT break up coherent groups
-3. **Deep nesting** — if a file is 3+ levels deep in a project-specific directory, it's likely intentionally placed. Leave it unless the user explicitly asks to flatten
-4. **Name collisions** — if moving a file would create a name collision in the target directory, flag it and skip
+### Step 3: Check User Notes
 
-**When `aggressive` mode is enabled**, also suggest structural consolidation:
-- Multiple year/sprint directories (e.g., `2025 Sprint/`, `2026 Sprint/`) → merge under `Sprints/2025/`, `Sprints/2026/`
-- Scattered documentation directories → consolidate under `Knowledge/`
-- This is a larger operation — always present as a separate approval step
+User notes should **remain** in their existing directories (`Projects/`, `Daily/`, personal folders, etc.). Do not suggest moving them into agent directories. Suggest organization only if:
 
-### Step 3: Present Plan
+- A user note has been placed in an agent directory (`entities/`, `concepts/`, `comparisons/`, `queries/`) — this is likely a mistake; propose moving it back to an appropriate user area
+- Multiple user notes about the same topic are scattered across **user** directories when they could be grouped there (never into agent dirs unless they are true agent pages with correct `type` frontmatter)
 
-Group proposed moves by category and show a clear summary:
-
-```
-/organize analysis complete.
+### Step 4: Check Naming Conventions
 
-## Files to move (23 of 504)
+Per SCHEMA.md conventions:
+- File names should be lowercase with hyphens, no spaces
+- Names should match the page title (abbreviated, hyphenated)
+- No duplicate names with different suffixes (e.g., `feature-a.md` and `feature-a-1.md`)
 
-### Root files → proper directories
-  HANDOVER-2026-03-04.md → Knowledge/Handovers/HANDOVER-2026-03-04.md
-  HANDOVER-2026-03-02.md → Knowledge/Handovers/HANDOVER-2026-03-02.md
-  BigQuery_Syntax_Guide.md → Knowledge/BigQuery_Syntax_Guide.md
+Flag any naming violations.
 
-### Meeting notes → Meetings/
-  standup-2026-03-15.md → Meetings/standup-2026-03-15.md
+### Step 5: Suggest Moves
 
-### Reference docs → Knowledge/
-  API_Overview.md → Knowledge/API_Overview.md
+For each misplaced file:
 
-## New directories to create
-  Knowledge/Handovers/
-  Meetings/
-
-## Files staying in place: 481
-  (Already in coherent directory structures)
-
-## Files without `type` (cannot auto-organize): 12
-  Run /weave on these first, then re-run /organize.
-
-Options:
-  1. Approve all moves
-  2. Review one-by-one
-  3. Skip — make no changes
 ```
+Move: entities/wrong-place.md → concepts/wrong-place.md
+  Reason: type=concept but currently in entities/
 
-Wait for user response before proceeding.
+Move: Projects/random-notes.md → Projects/feature-a/
+  Reason: Content is about Feature A, should be grouped with other Feature A notes
+```
 
-### Step 4: Execute Moves
+### Step 6: Apply Moves (If Confirmed)
 
-For each approved move, use `obsidian move`:
+Use Obsidian CLI to rename/move files:
 
 ```bash
-obsidian move file="HANDOVER-2026-03-04" to="Knowledge/Handovers/"
+obsidian rename file="old-path.md" new_name="new-path.md"
 ```
 
-**Execution rules:**
+Always show the full plan before applying. Never move files silently.
 
-- Create target directories first if they don't exist:
-  ```bash
-  mkdir -p "<vault path>/<target directory>"
-  ```
-- Execute moves one at a time and verify each succeeds
-- If a move fails (name collision, file locked, etc.), log the error and continue with remaining moves
-- Report progress every 10 moves: "Moved 10/23 files..."
+### Step 7: Update Wikilinks
 
-**Why `obsidian move` instead of `mv`:**
+After moving files, check that all wikilinks to the moved files are still valid:
 
-`obsidian move` tells Obsidian to perform the move internally. Obsidian automatically updates **all wikilinks and backlinks** across the entire vault that reference the moved file. Using file system `mv` would leave broken links.
-
-### Step 5: Verify
-
-After all moves complete:
-
-1. Get the updated file list:
-   ```bash
-   obsidian list
-   ```
-
-2. Check for broken links:
-   ```bash
-   byoao_graph_health
-   ```
-
-3. Report results:
-
-```
-/organize complete:
-  - Moved: 23 files
-  - Skipped: 0 (errors)
-  - New directories created: 2
-  - Broken links after moves: 0
-  - Files still without `type`: 12 (run /weave to fix)
+```bash
+obsidian backlinks "moved-file"
 ```
 
-If any broken links are found, report them and suggest fixes.
+Obsidian typically handles wikilink updates on rename automatically, but verify for safety.
 
-## Important Guidelines
+## Key Principles
 
-- **Conservative by default**: Only suggest moves where the benefit is clear. A file that's "good enough" where it is should stay
-- **Never break coherent groups**: If files are organized together in a project directory, don't scatter them even if their `type` would suggest different target directories
-- **User approval is mandatory**: Never move files without explicit confirmation
-- **`obsidian move` only**: Never use file system `mv`, `cp`, or rename commands for vault files — only `obsidian move` and `obsidian rename` preserve link integrity
-- **Idempotent**: Running /organize twice should not propose moves for files that were already correctly placed in the first run
-- **Reversible**: If the user wants to undo, they can run `/organize` again with manual adjustments, or restore from git history
+- **Suggest first, act second.** Default to dry_run mode. Show the full plan before making any changes.
+- **Agent directories are sacred.** Only agent pages should live in `entities/`, `concepts/`, `comparisons/`, `queries/`.
+- **User notes are user territory.** Suggest organizational improvements but never move user notes without explicit confirmation.
+- **Obsidian is first workbench.** All note operations go through Obsidian CLI.

package/dist/assets/skills/prep/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: prep
+description: >
+  Shared prerequisites check and graph enrichment. Verifies Obsidian CLI is available and
+  scans frontmatter for cross-reference suggestions. Referenced by all skills via "(see /prep)".
+  Use when the user says "check prerequisites", "prep my vault", "enrich the graph", or
+  before running other skills that depend on Obsidian CLI.
+---
+
+# /prep — Prerequisites Check
+
+## Obsidian CLI Availability
+
+Before using any BYOAO skill, verify the Obsidian CLI is available:
+
+```bash
+obsidian --version
+```
+
+If this fails, STOP and display:
+
+```
+Obsidian CLI is not available. The Obsidian CLI is bundled with the Obsidian
+app (v1.12+) and cannot be installed separately.
+
+1. Install or update Obsidian from: https://obsidian.md/download
+2. Open Obsidian and enable the CLI:
+   Settings → General → Advanced → Command-line interface
+3. Make sure Obsidian is running, then try again.
+```
+
+## Graph Enrichment
+
+Scan all user notes and enrich frontmatter, suggest cross-references.
+
+### Step 1: Scan Notes
+- Read all `.md` files outside agent directories
+- Extract entities, key terms, and potential wikilink targets
+
+### Step 2: Enrich Frontmatter
+For each note missing frontmatter:
+- Add `title` (from filename or first heading)
+- Add `date` (from file creation time or content)
+- Suggest `tags` based on content
+
+For notes with partial frontmatter:
+- Fill in missing required fields
+- Never overwrite existing values
+
+### Step 3: Suggest Cross-References
+- Identify recurring terms mentioned across notes
+- Suggest converting mentions to `[[wikilinks]]`
+- Propose new entries for `SCHEMA.md` tag taxonomy
+
+### Step 4: Report
+Present a summary:
+- Notes enriched: X
+- Wikilinks suggested: Y
+- New schema terms proposed: Z
+Ask for approval before applying any changes.
+
+### Key Behaviors
+- Idempotent — running twice won't duplicate changes
+- Never overwrites existing frontmatter values
+- Asks before applying wikilink suggestions

package/dist/assets/skills/prep.md

@@ -0,0 +1,63 @@
+---
+name: prep
+description: >
+  Shared prerequisites check — verifies Obsidian CLI is available and displays a correct
+  error message with installation guidance. Referenced by all skills via "(see /prep)".
+---
+
+# /prep — Prerequisites Check
+
+## Obsidian CLI Availability
+
+Before using any BYOAO skill, verify the Obsidian CLI is available:
+
+```bash
+obsidian --version
+```
+
+If this fails, STOP and display:
+
+```
+Obsidian CLI is not available. The Obsidian CLI is bundled with the Obsidian
+app (v1.12+) and cannot be installed separately.
+
+1. Install or update Obsidian from: https://obsidian.md/download
+2. Open Obsidian and enable the CLI:
+   Settings → General → Advanced → Command-line interface
+3. Make sure Obsidian is running, then try again.
+```
+
+## Graph Enrichment
+
+Scan all user notes and enrich frontmatter, suggest cross-references.
+
+### Step 1: Scan Notes
+- Read all `.md` files outside agent directories
+- Extract entities, key terms, and potential wikilink targets
+
+### Step 2: Enrich Frontmatter
+For each note missing frontmatter:
+- Add `title` (from filename or first heading)
+- Add `date` (from file creation time or content)
+- Suggest `tags` based on content
+
+For notes with partial frontmatter:
+- Fill in missing required fields
+- Never overwrite existing values
+
+### Step 3: Suggest Cross-References
+- Identify recurring terms mentioned across notes
+- Suggest converting mentions to `[[wikilinks]]`
+- Propose new entries for `SCHEMA.md` tag taxonomy
+
+### Step 4: Report
+Present a summary:
+- Notes enriched: X
+- Wikilinks suggested: Y
+- New schema terms proposed: Z
+Ask for approval before applying any changes.
+
+### Key Behaviors
+- Idempotent — running twice won't duplicate changes
+- Never overwrites existing frontmatter values
+- Asks before applying wikilink suggestions

package/dist/assets/skills/trace/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: trace
+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", "when did we start thinking about",
+  "show how this idea changed", or wants to understand the chronological evolution of
+  any topic, decision, or concept in their notes.
+---
+
+# /trace — Chronological Timeline
+
+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
+
+```bash
+obsidian --version
+```
+
+If this fails, STOP and display the Obsidian CLI availability message (see /prep).
+
+## Parameters
+
+- **topic** (required): The idea, decision, or concept to trace.
+- **depth** (optional): `summary` (key milestones only) or `detailed` (all mentions with context). Default: `summary`.
+
+## Process
+
+### Step 1: Locate All Mentions
+
+Search for the topic across all notes:
+
+```bash
+obsidian search "<topic>"
+obsidian tags "<topic>"
+```
+
+Also search agent-maintained pages under `entities/`, `concepts/`, `comparisons/`, and `queries/`:
+
+```bash
+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 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
+
+### Step 3: Detect Phases
+
+Group the timeline into phases:
+
+- **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)
+
+A topic may skip phases, cycle back, or have multiple parallel tracks.
+
+### Step 4: Identify Turning Points
+
+Highlight moments where the trajectory changed:
+
+- "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
+
+### Step 5: Find Contradictions
+
+Compare statements across time:
+
+- "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?
+
+Flag genuine contradictions. Note the dates, sources, and nature of the conflict.
+
+### Step 6: Present Timeline
+
+```markdown
+# Timeline: {topic}
+
+Traced across {N} notes spanning {start date} to {end date}.
+
+---
+
+## Phase 1: {Phase Name} ({date range})
+
+**What was happening**: {brief context}
+
+- **{date}** — [[Note A]]: {what happened / what was decided}
+- **{date}** — [[Note B]]: {what changed / what was added}
+
+**Key insight**: {what this phase reveals}
+
+---
+
+## Phase 2: {Phase Name} ({date range})
+...
+
+---
+
+## Turning Points
+
+1. **{date}**: {what changed and why it mattered} — [[source note]]
+
+## Contradictions Found
+
+- ⚠ [[Note A]] says X, but [[Note B]] says Y — {resolution if known}
+
+## Current State
+
+{Where things stand now — the most recent position on this topic}
+
+## Unanswered Questions
+
+{What the vault doesn't tell us about this topic's evolution}
+```
+
+## Key Principles
+
+- **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.