Custom Slash Command Handlers

When the user starts a message with a slash command, you must immediately execute the corresponding Python script in the workspace using your run_command tool, capture the output, and present the findings to the user.

Command Mappings

• /getContextSize
  • Purpose: Show current conversation context window size, character count, and estimated token count.
  • Execution: uv run python scripts/knowledge_commands.py --tokens
• /okc-book <input> / /okc-bookSummary <input>
  • Purpose: Ingest a non-fiction book or long document (PDF, EPUB, DOCX, TXT, MD) using the okc-bookSummary skill and the HDAS (High-Density Actionable Synthesis) standard. It extracts structure, sanitizes text, segments chapters, synthesizes rich actionable chapter notes (with front-loaded insights, mental models, pitfalls, 15-min challenges, cross-domain commentary, Mermaid mindmaps, key questions, and critical analysis), writes directly to the Obsidian Vault (VAULT_ROOT), compiles concepts in wiki/, purges temporary staging folders/files, and syncs the vault.
  • Execution: Run uv run python scripts/fetch_book_data.py --input "<input>". Read temp/fetched_book_data.json and temp/fetched_book_data.txt, generate book notes and chapter files directly in VAULT_ROOT/dataScienceKnowledgeBase/<Category>/raw/books/, compile concepts in wiki/, run uv run python scripts/fetch_book_data.py --clean, and run uv run python scripts/sync_vault.py.
• /okc-bookFlashcards <input> [flags] / /okc-bookDeck <input> [flags]
  • Purpose: Transform an entire EPUB or PDF non-fiction book into an exhaustive active-recall flashcard deck using the HDAR (High-Density Active Recall) standard. Decomposes into semantic sections, extracts core mechanisms and trade-offs, formulates atomic Basic (optional reversed card) notes, avoids duplicates, embeds diagrams, and syncs directly to Anki and Obsidian.
  • Execution: Run uv run python scripts/book_flashcards_engine.py --input "<input>" --deck "<DeckName>" [--sync-anki] [--replace-deck].
• /okc-diagnosticsAndSynchronization [flags] / /okc-doctor [flags]
  • Purpose: Comprehensive health check, integrity audit, and full synchronization across the entire Obsidian vault. Scans SQLite DB, Master Plans, dead wikilinks, contradictions, ZWSP unicode hygiene, unreferenced visual assets, protected zones, and rebuilds Graphify + KNOWLEDGE.md index. Supports --fix for auto-repair.
  • Execution: uv run python scripts/okc_doctor.py (or uv run python scripts/okc_doctor.py --fix / --clean-assets)
• /okc-doc <input>
  • Purpose: Ingest an office document, presentation, spreadsheet, EPUB or PDF (.docx, .pptx, .xlsx, .epub, .pdf, .odt, .csv) using AnyDoc (firecrawl-anydoc). Converts to clean Markdown, extracts embedded images to <VAULT_ROOT>/assets/images/, curates note in raw/, compiles concepts in wiki/, and syncs the vault.
  • Execution: Run native FastMCP tool fetch_doc_data(file_path="<input>") (which returns inline text and SQLite graphify_context in 1 turn; only read temp/fetched_data.txt if is_truncated is True). Generate curated note in raw/, compile concepts in wiki/, and commit atomically via FastMCP commit_curated_note(..., fast_sync=True, async_sync=True).
• /okc-drift
  • Purpose: Compare intentions vs actual behaviors in notes.
  • Execution: uv run python scripts/knowledge_commands.py --drift
• /okc-emerge
  • Purpose: Find implied ideas in recent notes.
  • Execution: uv run python scripts/knowledge_commands.py --emerge
• /okc-explore <concept>
  • Purpose: Explore a concept in the local graph index and view its direct relationships.
  • Execution: uv run python scripts/knowledge_commands.py --explore "<concept>"
• /okc-find <query>
  • Purpose: Case-insensitive substring search for note titles.
  • Execution: uv run python scripts/knowledge_commands.py --find "<query>"
• /okc-instagram
  • Purpose: Batch ingest and curate an Instagram Saved Collection of reels. Uses the Chrome DOM bridge to harvest saved URLs, downloads audio via yt-dlp, transcribes offline with Whisper (base), generates atomic notes in Leadership and Coach/raw/Instagram/, compiles a collection Master Plan, and syncs the vault.
  • Execution: uv run python scripts/process_instagram_saved_batch.py
• /okc-linter
  • Purpose: Run vault linter separately.
  • Execution: uv run python scripts/vault_linter.py
• /okc-normalize [flags]
  • Purpose: Audit, deduplicate, remove stubs, and inject canonical Obsidian headers into notes in a category or folder. Supports --fix and --sync.
  • Execution: uv run python scripts/normalize_notes.py --target "<folder>" [--fix] [--sync]
• /okc-notion [flags]
  • Purpose: Curate, format, compile wiki concepts, and update Master Plans for imported Notion folders.
  • Execution: Run uv run python scripts/curate_notion_import.py --notion-dir "<dir>" --target-kb "<category>" --course-name "<course>" --execute.
• /okc-setup
  • Purpose: Configure project environment variables, Obsidian Vault path, LLM providers, and system dependencies from .env.template.
  • Execution: Run uv run python scripts/setup_project.py --non-interactive --sync (or pass --vault-path <path>).
• /okc-study <action> [flags]
  • Purpose: Managed study deck and flashcard engine. Parses notes via AST, extracts atomic Knowledge Units, generates SuperMemo-aligned cards (Basic/Cloze), creates managed Markdown decks in <RootFolder>/study/<Deck Name>.md, and syncs directly to Anki via MCP / AnkiConnect.
  • Execution: Run uv run python scripts/study_deck.py create --source "<folder_or_note>" --deck "<DeckName>" [--anki-deck "<AnkiName>"] (or status / sync-anki).
• /okc-study-multichoice <action> [flags]
  • Purpose: Reusable and parameterized Multiple-Choice flashcard engine. Supports syntax validation, status inspections, and direct Anki synchronization.
  • Execution: uv run python scripts/study_multi_choice.py <action> --file "<path>" [--deck-prefix "<prefix>"]
• /okc-sync [flags]
  • Purpose: Rebuild master plans and run vault linter. Supports --fast for incremental synchronization without full 27k-node graph rebuilds.
  • Execution: uv run python scripts/sync_vault.py [--fast]
• /okc-validate-cards [flags]
  • Purpose: Audit syntax, delimiter hygiene (?), 4-alternative structure, answer key alignment, and comprehensive distractor breakdowns across multiple-choice flashcard decks.
  • Execution: uv run python scripts/validate_flashcards.py --file "<path>" [--fix] [--strict] [--json]
• /okc-trace <topic>
  • Purpose: Chronological trace of an idea.
  • Execution: uv run python scripts/knowledge_commands.py --trace "<topic>"
• /okc-urlArticle <url>
  • Purpose: Fetch full DOM content from an article or web page (without 5,000-char limits), download infographics concurrently to <VAULT_ROOT>/assets/images/, filter avatars (<100px), curate note in raw/, compile concepts in wiki/, and sync the vault incrementally.
  • Execution: Run FastMCP tool fetch_article_data(url="<url>", download_all_images=True) (returns inline text, already_exists, and SQLite graphify_context in 1 turn; skip read_file on temp/ unless is_truncated == True). Generate curated note content and wiki concepts, and commit atomically via FastMCP tool commit_curated_note(raw_note_path="...", raw_content="...", wiki_notes={...}, fast_sync=True, async_sync=True).
• /okc-urlPlaylist <url>
  • Purpose: Ingest an entire YouTube playlist with concurrent transcript extraction, per-video SQLite pre-flight checks, dynamic $N$-subagent parallel curation (1 Video = 1 Subagent), and atomic batch commit.
  • Execution: Run FastMCP tool fetch_playlist_data(url="<url>", skip_existing=True). Inspect pending_count ($N$): if $N == 1$, draft directly in the main agent; if $2 \le N \le 8$, spawn $N$ parallel subagents (invoke_subagent, 1 per pending video) passing each video's metadata and transcript / transcript_path_abs; if $N > 8$, dispatch subagents in parallel waves of $6\text{–}8$. Consolidate all $N$ drafted raw/ notes, Master Plan — <Series>.md, and wiki/ concepts, and commit atomically in 1 turn via FastMCP tool commit_curated_batch(raw_notes={...}, master_plan_path="...", master_plan_content="...", wiki_notes={...}, fast_sync=True, async_sync=True).
• /okc-urlPodcast <url>
  • Purpose: Ingest a podcast episode or audio link, transcribe audio using Buzz CLI (Whisper), map Graphify context, curate note in raw/, compile concepts in wiki/, and sync the vault. Automatically delegates Spotify URLs to the Chrome DOM bridge.
  • Execution: Run FastMCP tool fetch_podcast_data(url="<url>") (returns inline text, already_exists, and SQLite graphify_context in 1 turn). Generate the curated note in raw/, compile concepts in wiki/, and commit atomically via FastMCP tool commit_curated_note(..., fast_sync=True, async_sync=True).
• /okc-urlSpotify <url>
  • Purpose: Ingest a Spotify podcast episode using the Google Chrome DOM hydration bridge. Overcomes Widevine DRM (MP4_128_CBCS) by connecting to the active session in Chrome, activating the Transcript tab, hydrating virtualized rows, curating note in raw/, compiling concepts in wiki/, and syncing the vault.
  • Execution: Run FastMCP tool fetch_spotify_data(url="<url>") (returns inline text, already_exists, and SQLite graphify_context in 1 turn). Generate the curated note in raw/, compile concepts in wiki/, and commit atomically via FastMCP tool commit_curated_note(..., fast_sync=True, async_sync=True).
• /okc-urlTwitter <url>
  • Purpose: Ingest a Twitter/X post or video. It extracts post text and metadata, and if a video is present without subtitles, it automatically downloads the audio and transcribes it using Buzz CLI / Whisper. It curates the note in raw/ (including Processed date), compiles concepts in wiki/, and syncs the vault.
  • Execution: Run FastMCP tool fetch_twitter_data(url="<url>") (returns inline text, already_exists, and SQLite graphify_context in 1 turn). Generate the curated note in raw/, compile concepts in wiki/, and commit atomically via FastMCP tool commit_curated_note(..., fast_sync=True, async_sync=True).
• /okc-urlYoutube <url>
  • Purpose: Ingest a YouTube video. Uses concurrent oEmbed/HTML metadata + youtube-transcript-api (or local Buzz CLI Whisper fallback), returns full inline transcript and SQLite context in 1 turn, curates the note in raw/ (including Processed date), compiles concepts in wiki/, and commits with surgical SQLite upsert + detached async background sync.
  • Execution: Run FastMCP tool fetch_youtube_data(url_or_id="<url>") (do not read temp/fetched_data.txt unless is_truncated == True). Generate the curated note in raw/, compile concepts in wiki/, and commit atomically via FastMCP tool commit_curated_note(..., fast_sync=True, async_sync=True).

Formatting Guidelines

• Always run the commands from the workspace root directory.
• Execute workflows end-to-end autonomously without requesting intermediate confirmations or stopping mid-pipeline.
• Universal Source-Agnostic Multi-Source Parallel Protocol (1 Source Unit = 1 Subagent): Whenever a prompt contains multiple sources ($N \ge 2$) of any type or heterogeneous mix (YouTube videos, YouTube playlists, Web articles, Twitter/X posts, Podcasts, Spotify episodes, or local Documents .pdf/.docx/.epub/.pptx):
  1. Turn 1 (Parallel Discovery & Extraction): Emit any Rule Zero web searches concurrently, and extract all sources in parallel using either fetch_multi_source_data(sources=[...], skip_existing=True) or concurrent calls to the corresponding FastMCP tools (fetch_youtube_data, fetch_playlist_data, fetch_article_data, fetch_twitter_data, fetch_podcast_data, fetch_spotify_data, fetch_doc_data).
  2. Turn 2 (Dynamic Subagent Fan-Out — 1 Source Unit = 1 Subagent): Count total pending source units $N$ (already_exists == False) across all extractors:
     • If $N == 0$: Report existing [[wikilinks]] immediately.
     • If $N == 1$: Draft directly in the main agent and call commit_curated_note(..., async_sync=True).
     • If $2 \le N \le 8$: Spawn $N$ parallel subagents (invoke_subagent) in a single turn (1 subagent per source unit, regardless of source type) passing each subagent its inline text/transcript (or isolated source_txt_abs path in temp/sources/) and graphify_context.
     • If $N > 8$: Spawn subagents in parallel waves of $6\text{–}8$ (1 subagent per source unit).
  3. Turn 3 (Atomic Batch Commit): Merge all $N$ drafted raw/ notes, series Master Plan (if a playlist was included), and shared wiki/ concepts into a single call to FastMCP commit_curated_batch(..., fast_sync=True, async_sync=True).
• Format output inside a clean code block and append a list of any notes modified or referenced as clickable links (using the Obsidian URI scheme when relevant).

Agent skills

Issue tracker

Issues live as local markdown files under .scratch/<feature>/. See docs/agents/issue-tracker.md.

Domain docs

Single-context layout with GEMINI.md at repo root and ADRs in docs/adr/. See docs/agents/domain.md.