pointfree-docs 0.1.0 → 0.2.0

package/README.md

@@ -2,6 +2,12 @@
 
 A CLI tool for searching Point-Free library documentation locally. Uses sparse git checkout and SQLite FTS5 for fast, offline full-text search. Built for use with AI coding assistants like Claude Code.
 
+## Demo
+
+See pf-docs in action: install, search, and real-world usage with Claude Code.
+
+https://github.com/user-attachments/assets/ed6c6340-2d29-4515-89ca-62f65cfa4755
+
 ## Quick Start
 
 ```bash
@@ -31,7 +37,7 @@ pf-docs list tca
 
 ### `pf-docs list --available`
 
-Show all libraries available to download.
+Show all libraries available to download, plus additional sources (examples, episodes).
 
 ### `pf-docs init`
 
@@ -40,6 +46,9 @@ Download and index documentation. Only fetches `Documentation.docc` folders via
 ```bash
 pf-docs init --libs tca dependencies navigation
 pf-docs init --all
+pf-docs init --examples           # TCA CaseStudies, SyncUps, etc.
+pf-docs init --episodes           # 350+ Point-Free episode code samples
+pf-docs init --all --examples --episodes  # Everything
 ```
 
 ### `pf-docs update`
@@ -47,8 +56,10 @@ pf-docs init --all
 Pull latest changes and re-index.
 
 ```bash
-pf-docs update              # All initialized libraries
-pf-docs update --libs tca   # Specific libraries
+pf-docs update                    # All initialized libraries
+pf-docs update --libs tca         # Specific libraries
+pf-docs update --examples         # Update examples
+pf-docs update --episodes         # Update episodes
 ```
 
 ### `pf-docs search <query>`
@@ -59,6 +70,12 @@ Full-text search across all indexed docs.
 pf-docs search "testing effects"
 pf-docs search "navigation" --lib tca
 pf-docs search "Store" --limit 5
+
+# Search by source type
+pf-docs search "TestStore" --source=docs      # Default: docs only
+pf-docs search "TestStore" --source=examples  # TCA examples only
+pf-docs search "TestStore" --source=episodes  # Episode code only
+pf-docs search "TestStore" --source=all       # Everything, labeled
 ```
 
 ### `pf-docs get <path>`
@@ -68,6 +85,11 @@ Fetch a specific article as clean markdown.
 ```bash
 pf-docs get tca/Articles/TestingTCA
 pf-docs get dependencies/Articles/QuickStart --raw
+
+# Code files show preview by default (50 lines)
+pf-docs get examples/CaseStudies/03-Effects-Basics.swift
+pf-docs get examples/CaseStudies/03-Effects-Basics.swift --raw      # Full content
+pf-docs get episodes/0156-testable-state/Main.swift --lines=100     # More lines
 ```
 
 ### `pf-docs list [lib]`
@@ -75,13 +97,15 @@ pf-docs get dependencies/Articles/QuickStart --raw
 List indexed documentation.
 
 ```bash
-pf-docs list                # All indexed docs
-pf-docs list tca --tree     # Tree view for one library
+pf-docs list                      # All indexed docs
+pf-docs list tca --tree           # Tree view for one library
+pf-docs list --source=examples    # Only examples
+pf-docs list --source=all         # All sources
 ```
 
 ### `pf-docs stats`
 
-Show indexing statistics.
+Show indexing statistics by source and library.
 
 All commands support `--json` for programmatic output.
 
@@ -104,12 +128,48 @@ All commands support `--json` for programmatic output.
 
 Run `pf-docs list --available` to see this list in your terminal.
 
+## Additional Sources
+
+| Source | Description | Flag |
+|--------|-------------|------|
+| `examples` | TCA CaseStudies, SyncUps, Todos, VoiceMemos, etc. | `--examples` |
+| `episodes` | 350+ Point-Free episode code samples | `--episodes` |
+
+### Source Types for Search
+
+When searching, you can filter by source type:
+
+- `docs` (default) — Library documentation (DocC articles)
+- `examples` — TCA example apps and case studies
+- `episodes` — Point-Free episode code samples
+- `all` — Everything, with labels showing the source
+
+```bash
+# Search docs for concepts
+pf-docs search "testing effects"
+
+# Search examples for real implementations
+pf-docs search "TestStore" --source=examples
+
+# Search everything
+pf-docs search "dependency injection" --source=all
+```
+
+Results with `--source=all` are labeled:
+```
+[DOC]     tca/Articles/Testing           (0.94)
+[EXAMPLE] CaseStudies/03-Effects-Basics  (0.82)
+[EPISODE] Ep156: Testable State          (0.71)
+```
+
 ## Usage with Claude Code
 
 Add the key commands to your project's `CLAUDE.md`:
 
 ```markdown
-Use `pf-docs search "<query>"` to search Point-Free docs, `pf-docs get <path>` to read an article.
+Use `pf-docs search "<query>"` to search Point-Free docs.
+Use `pf-docs search "<query>" --source=examples` to find real code examples.
+Use `pf-docs get <path>` to read an article or code file.
 ```
 
 ## Adding Libraries

package/dist/cli.js

@@ -15,23 +15,28 @@ const program = new Command();
 program
     .name("pf-docs")
     .description("CLI tool for searching Point-Free library documentation")
-    .version("0.1.0");
+    .version("0.2.0");
 program
     .command("init")
     .description("Initialize and download documentation for specified libraries")
     .option("-l, --libs <libs...>", "Libraries to download (e.g., tca dependencies)")
     .option("-a, --all", "Download all available libraries")
+    .option("-e, --examples", "Download TCA examples (CaseStudies, SyncUps, etc.)")
+    .option("-p, --episodes", "Download Point-Free episode code samples (350+)")
     .action(initCommand);
 program
     .command("update")
     .description("Update documentation from remote repositories")
     .option("-l, --libs <libs...>", "Specific libraries to update")
+    .option("-e, --examples", "Update examples")
+    .option("-p, --episodes", "Update episodes")
     .action(updateCommand);
 program
     .command("search <query>")
     .description("Search across all indexed documentation")
     .option("-l, --lib <lib>", "Limit search to specific library")
     .option("-n, --limit <n>", "Max results to return", "10")
+    .option("-s, --source <source>", "Source type: docs, examples, episodes, all (default: docs)")
     .option("-j, --json", "Output results as JSON")
     .action(searchCommand);
 program
@@ -39,6 +44,8 @@ program
     .description("Get a specific documentation article (e.g., tca/Testing)")
     .option("-j, --json", "Output as JSON")
     .option("-r, --raw", "Output raw content without header")
+    .option("-p, --preview", "Preview mode (first 50 lines for code files)")
+    .option("--lines <n>", "Number of lines to show in preview mode", "50")
     .action(getCommand);
 program
     .command("list [lib]")
@@ -46,6 +53,7 @@ program
     .option("-t, --tree", "Show as tree structure")
     .option("-j, --json", "Output as JSON")
     .option("-a, --available", "Show all libraries available to download")
+    .option("-s, --source <source>", "Filter by source: docs, examples, episodes, all")
     .action(listCommand);
 program
     .command("stats")

package/dist/commands/get.d.ts

@@ -4,6 +4,8 @@
 interface GetOptions {
     json?: boolean;
     raw?: boolean;
+    preview?: boolean;
+    lines?: string;
 }
 export declare function getCommand(path: string, options?: GetOptions): void;
 export {};

package/dist/commands/get.js

@@ -4,6 +4,29 @@
 import chalk from "chalk";
 import { getDoc, withIndex } from "../lib/index.js";
 import { formatDocForOutput } from "../lib/markdown.js";
+import { getSourceLabel } from "../lib/format.js";
+const DEFAULT_PREVIEW_LINES = 50;
+/**
+ * Truncate content to a specified number of lines
+ */
+function truncateContent(content, maxLines) {
+    const lines = content.split("\n");
+    const totalLines = lines.length;
+    if (lines.length <= maxLines) {
+        return { content, truncated: false, totalLines };
+    }
+    return {
+        content: lines.slice(0, maxLines).join("\n"),
+        truncated: true,
+        totalLines,
+    };
+}
+/**
+ * Check if a document is code (not documentation) based on its source
+ */
+function isCodeFile(doc) {
+    return doc.source === "examples" || doc.source === "episodes";
+}
 export function getCommand(path, options = {}) {
     const doc = withIndex(() => getDoc(path));
     if (!doc) {
@@ -16,8 +39,28 @@ export function getCommand(path, options = {}) {
         console.log(chalk.gray(`Or search: pf-docs search "<query>"`));
         return;
     }
+    // Determine preview lines
+    const previewLines = options.lines
+        ? parseInt(options.lines, 10)
+        : DEFAULT_PREVIEW_LINES;
+    // Apply preview mode for code files (examples/episodes)
+    const shouldPreview = options.preview || (isCodeFile(doc) && !options.raw);
+    let outputContent = doc.content;
+    let truncationInfo = "";
+    if (shouldPreview && !options.raw) {
+        const { content, truncated, totalLines } = truncateContent(doc.content, previewLines);
+        outputContent = content;
+        if (truncated) {
+            truncationInfo = `\n${chalk.gray(`... truncated (showing ${previewLines} of ${totalLines} lines)`)}\n${chalk.gray(`Use --raw for full content, or --lines=<n> for more`)}`;
+        }
+    }
     if (options.json) {
-        console.log(JSON.stringify(doc, null, 2));
+        const result = { ...doc, content: outputContent };
+        if (truncationInfo) {
+            result.truncated = true;
+            result.previewLines = previewLines;
+        }
+        console.log(JSON.stringify(result, null, 2));
         return;
     }
     // Raw output (just content, no header)
@@ -25,6 +68,20 @@ export function getCommand(path, options = {}) {
         console.log(doc.content);
         return;
     }
+    // For code files, show with syntax hint
+    if (isCodeFile(doc)) {
+        console.log(`\n${getSourceLabel(doc.source)} ${chalk.bold(doc.title)}`);
+        console.log(chalk.gray(`Path: ${doc.path}`));
+        console.log(chalk.gray("─".repeat(60)));
+        console.log(outputContent);
+        if (truncationInfo) {
+            console.log(truncationInfo);
+        }
+        return;
+    }
     // Output the formatted document (clean markdown)
-    console.log(formatDocForOutput(doc));
+    console.log(formatDocForOutput({ ...doc, content: outputContent }));
+    if (truncationInfo) {
+        console.log(truncationInfo);
+    }
 }

package/dist/commands/init.d.ts

@@ -4,6 +4,8 @@
 interface InitOptions {
     libs?: string[];
     all?: boolean;
+    examples?: boolean;
+    episodes?: boolean;
 }
 export declare function initCommand(options: InitOptions): Promise<void>;
 export {};

package/dist/commands/init.js

@@ -3,10 +3,12 @@
  */
 import chalk from "chalk";
 import { LIBRARIES, getLibrary, LIBRARY_NAMES } from "../config.js";
-import { cloneLibrary } from "../lib/repos.js";
-import { indexLibrary, openIndex, closeIndex } from "../lib/index.js";
+import { cloneLibrary, cloneExamples, cloneEpisodes } from "../lib/repos.js";
+import { indexLibrary, indexExamples, indexEpisodes, openIndex, closeIndex } from "../lib/index.js";
 export async function initCommand(options) {
     console.log(chalk.bold("\n📚 Initializing Point-Free Documentation\n"));
+    const includeExamples = options.examples || false;
+    const includeEpisodes = options.episodes || false;
     // Determine which libraries to download
     let librariesToInit = LIBRARIES;
     if (options.libs && !options.all) {
@@ -22,28 +24,67 @@ export async function initCommand(options) {
             }
         }
     }
-    if (librariesToInit.length === 0) {
-        console.log(chalk.red("No valid libraries specified."));
-        console.log(`\nUsage: pf-docs init --libs tca dependencies navigation`);
-        console.log(`       pf-docs init --all`);
+    // If no libs specified and not --all, and no examples/episodes, show usage
+    if (librariesToInit.length === 0 && !includeExamples && !includeEpisodes) {
+        console.log(chalk.red("No valid libraries or sources specified."));
+        console.log(`\nUsage:`);
+        console.log(`  pf-docs init --libs tca dependencies navigation`);
+        console.log(`  pf-docs init --all`);
+        console.log(`  pf-docs init --examples`);
+        console.log(`  pf-docs init --episodes`);
+        console.log(`  pf-docs init --all --examples --episodes`);
         console.log(`\nAvailable libraries: ${LIBRARY_NAMES.join(", ")}`);
         return;
     }
-    console.log(chalk.blue(`Libraries to initialize: ${librariesToInit.map((l) => l.shortName).join(", ")}\n`));
-    // Clone repositories
-    console.log(chalk.bold("Cloning repositories..."));
-    for (const lib of librariesToInit) {
+    // Show what we're going to initialize
+    const sources = [];
+    if (librariesToInit.length > 0) {
+        sources.push(`Docs: ${librariesToInit.map((l) => l.shortName).join(", ")}`);
+    }
+    if (includeExamples) {
+        sources.push("Examples (TCA CaseStudies, SyncUps, etc.)");
+    }
+    if (includeEpisodes) {
+        sources.push("Episodes (350+ Point-Free episode code samples)");
+    }
+    console.log(chalk.blue(`Initializing: \n  ${sources.join("\n  ")}\n`));
+    // Clone library documentation repositories
+    if (librariesToInit.length > 0) {
+        console.log(chalk.bold("Cloning documentation repositories..."));
+        for (const lib of librariesToInit) {
+            try {
+                await cloneLibrary(lib);
+            }
+            catch (error) {
+                console.error(chalk.red(`  ✗ Failed to clone ${lib.shortName}:`), error);
+            }
+        }
+    }
+    // Clone examples if requested
+    if (includeExamples) {
+        console.log(chalk.bold("\nCloning TCA examples..."));
+        try {
+            await cloneExamples();
+        }
+        catch (error) {
+            console.error(chalk.red(`  ✗ Failed to clone examples:`), error);
+        }
+    }
+    // Clone episodes if requested
+    if (includeEpisodes) {
+        console.log(chalk.bold("\nCloning episode code samples..."));
         try {
-            await cloneLibrary(lib);
+            await cloneEpisodes();
         }
         catch (error) {
-            console.error(chalk.red(`  ✗ Failed to clone ${lib.shortName}:`), error);
+            console.error(chalk.red(`  ✗ Failed to clone episodes:`), error);
         }
     }
     // Build search index
     console.log(chalk.bold("\nBuilding search index..."));
     openIndex();
     let totalIndexed = 0;
+    // Index library docs
     for (const lib of librariesToInit) {
         try {
             const count = indexLibrary(lib);
@@ -54,10 +95,34 @@ export async function initCommand(options) {
             console.error(chalk.red(`  ✗ Failed to index ${lib.shortName}:`), error);
         }
     }
+    // Index examples
+    if (includeExamples) {
+        try {
+            const count = indexExamples();
+            console.log(`  ✓ Indexed examples: ${count} files`);
+            totalIndexed += count;
+        }
+        catch (error) {
+            console.error(chalk.red(`  ✗ Failed to index examples:`), error);
+        }
+    }
+    // Index episodes
+    if (includeEpisodes) {
+        try {
+            const count = indexEpisodes();
+            console.log(`  ✓ Indexed episodes: ${count} files`);
+            totalIndexed += count;
+        }
+        catch (error) {
+            console.error(chalk.red(`  ✗ Failed to index episodes:`), error);
+        }
+    }
     closeIndex();
-    console.log(chalk.green(`\n✅ Done! Indexed ${totalIndexed} documents.\n`));
+    console.log(chalk.green(`\n✅ Done! Indexed ${totalIndexed} items.\n`));
     console.log(`Try it out:`);
     console.log(chalk.gray(`  pf-docs search "testing async effects"`));
+    console.log(chalk.gray(`  pf-docs search "Store" --source=examples`));
+    console.log(chalk.gray(`  pf-docs search "dependency" --source=all`));
     console.log(chalk.gray(`  pf-docs list tca`));
     console.log(chalk.gray(`  pf-docs get tca/Testing`));
 }

package/dist/commands/list.d.ts

@@ -5,6 +5,7 @@ interface ListOptions {
     tree?: boolean;
     json?: boolean;
     available?: boolean;
+    source?: string;
 }
 export declare function listCommand(lib: string | undefined, options: ListOptions): void;
 export {};

package/dist/commands/list.js

@@ -3,14 +3,19 @@
  */
 import chalk from "chalk";
 import { listDocs, getStats, withIndex } from "../lib/index.js";
-import { getLibrary, LIBRARIES, LIBRARY_NAMES } from "../config.js";
+import { getLibrary, LIBRARIES, LIBRARY_NAMES, SOURCE_TYPES, EXAMPLES_CONFIG, EPISODES_CONFIG } from "../config.js";
+import { getSourceLabel } from "../lib/format.js";
 export function listCommand(lib, options) {
     if (options.available) {
         if (options.json) {
             const libs = LIBRARIES.map(({ shortName, name, repo, description }) => ({
                 shortName, name, repo, description,
             }));
-            console.log(JSON.stringify(libs, null, 2));
+            const extras = [
+                { shortName: "examples", name: EXAMPLES_CONFIG.name, repo: EXAMPLES_CONFIG.repo, description: EXAMPLES_CONFIG.description },
+                { shortName: "episodes", name: EPISODES_CONFIG.name, repo: EPISODES_CONFIG.repo, description: EPISODES_CONFIG.description },
+            ];
+            console.log(JSON.stringify({ libraries: libs, extras }, null, 2));
             return;
         }
         console.log(chalk.bold(`\n📦 Available Libraries\n`));
@@ -20,10 +25,27 @@ export function listCommand(lib, options) {
         }
         console.log(chalk.gray(`Total: ${LIBRARIES.length} libraries`));
         console.log(chalk.gray(`\nTo download: pf-docs init --libs <name> [<name>...]`));
+        console.log(chalk.bold(`\n📦 Additional Sources\n`));
+        console.log(`  ${chalk.magenta("examples".padEnd(24))} ${EXAMPLES_CONFIG.description}`);
+        console.log(chalk.gray(`  ${"".padEnd(24)} --examples flag\n`));
+        console.log(`  ${chalk.yellow("episodes".padEnd(24))} ${EPISODES_CONFIG.description}`);
+        console.log(chalk.gray(`  ${"".padEnd(24)} --episodes flag\n`));
         return;
     }
+    // Validate source option
+    let source;
+    if (options.source) {
+        if (options.source === "all" || SOURCE_TYPES.includes(options.source)) {
+            source = options.source;
+        }
+        else {
+            console.log(chalk.red(`Invalid source: ${options.source}`));
+            console.log(chalk.gray(`Valid sources: ${SOURCE_TYPES.join(", ")}, all`));
+            return;
+        }
+    }
     const { docs, stats } = withIndex(() => ({
-        docs: listDocs(lib),
+        docs: listDocs(lib, source),
         stats: getStats(),
     }));
     // JSON output for programmatic use
@@ -45,6 +67,11 @@ export function listCommand(lib, options) {
     console.log(chalk.bold(`\n📄 Available Documentation\n`));
     // Show stats summary
     if (!lib) {
+        console.log(chalk.gray(`Indexed by source:`));
+        for (const [sourceName, count] of Object.entries(stats.bySource)) {
+            console.log(chalk.gray(`  ${getSourceLabel(sourceName)}: ${count} items`));
+        }
+        console.log();
         console.log(chalk.gray(`Indexed libraries:`));
         for (const [libName, count] of Object.entries(stats.byLibrary)) {
             const libConfig = getLibrary(libName);
@@ -54,33 +81,46 @@ export function listCommand(lib, options) {
         console.log();
     }
     if (options.tree) {
-        // Group by library and show as tree
-        const byLibrary = new Map();
+        // Group by source and library, show as tree
+        const bySource = new Map();
         for (const doc of docs) {
-            if (!byLibrary.has(doc.library)) {
-                byLibrary.set(doc.library, []);
+            if (!bySource.has(doc.source)) {
+                bySource.set(doc.source, new Map());
+            }
+            const sourceMap = bySource.get(doc.source);
+            if (!sourceMap.has(doc.library)) {
+                sourceMap.set(doc.library, []);
             }
-            byLibrary.get(doc.library).push(doc);
+            sourceMap.get(doc.library).push(doc);
         }
-        for (const [library, libraryDocs] of byLibrary) {
-            console.log(chalk.blue(`${library}/`));
-            for (let i = 0; i < libraryDocs.length; i++) {
-                const doc = libraryDocs[i];
-                const relativePath = doc.path.replace(`${library}/`, "");
-                const isLast = i === libraryDocs.length - 1;
-                const prefix = isLast ? "└── " : "├── ";
-                console.log(chalk.gray(`  ${prefix}${relativePath}`));
+        for (const [sourceName, byLibrary] of bySource) {
+            console.log(getSourceLabel(sourceName));
+            for (const [library, libraryDocs] of byLibrary) {
+                console.log(chalk.blue(`  ${library}/`));
+                const maxToShow = 10;
+                for (let i = 0; i < Math.min(libraryDocs.length, maxToShow); i++) {
+                    const doc = libraryDocs[i];
+                    const relativePath = doc.path.replace(`${library}/`, "").replace(`${sourceName}/`, "");
+                    const isLast = i === Math.min(libraryDocs.length, maxToShow) - 1;
+                    const prefix = isLast ? "└── " : "├── ";
+                    console.log(chalk.gray(`    ${prefix}${relativePath}`));
+                }
+                if (libraryDocs.length > maxToShow) {
+                    console.log(chalk.gray(`    ... and ${libraryDocs.length - maxToShow} more`));
+                }
             }
             console.log();
         }
     }
     else {
-        // Simple list
+        // Simple list with source labels
+        const showSourceLabel = !source || source === "all";
         for (const doc of docs) {
-            console.log(chalk.blue(doc.path));
+            const label = showSourceLabel ? `${getSourceLabel(doc.source)} ` : "";
+            console.log(`${label}${chalk.blue(doc.path)}`);
             console.log(chalk.gray(`  ${doc.title}`));
         }
     }
-    console.log(chalk.gray(`\nTotal: ${docs.length} documents`));
+    console.log(chalk.gray(`\nTotal: ${docs.length} items`));
     console.log(chalk.gray(`\nTo view a document: pf-docs get <path>`));
 }

package/dist/commands/search.d.ts

@@ -5,6 +5,7 @@ interface SearchOptions {
     lib?: string;
     limit?: string;
     json?: boolean;
+    source?: string;
 }
 export declare function searchCommand(query: string, options: SearchOptions): void;
 export {};

package/dist/commands/search.js

@@ -3,11 +3,25 @@
  */
 import chalk from "chalk";
 import { search as searchIndex, withIndex } from "../lib/index.js";
+import { SOURCE_TYPES } from "../config.js";
+import { getSourceLabel } from "../lib/format.js";
 export function searchCommand(query, options) {
     const limit = options.limit ? parseInt(options.limit, 10) : 10;
-    const results = withIndex(() => searchIndex(query, { lib: options.lib, limit }));
+    // Validate source option
+    let source = "docs"; // Default to docs only
+    if (options.source) {
+        if (options.source === "all" || SOURCE_TYPES.includes(options.source)) {
+            source = options.source;
+        }
+        else {
+            console.log(chalk.red(`Invalid source: ${options.source}`));
+            console.log(chalk.gray(`Valid sources: ${SOURCE_TYPES.join(", ")}, all`));
+            return;
+        }
+    }
+    const results = withIndex(() => searchIndex(query, { lib: options.lib, limit, source }));
     if (options.json) {
-        console.log(JSON.stringify({ query, results }, null, 2));
+        console.log(JSON.stringify({ query, source, results }, null, 2));
         return;
     }
     if (results.length === 0) {
@@ -15,17 +29,26 @@ export function searchCommand(query, options) {
         if (options.lib) {
             console.log(chalk.gray(`  (searched in library: ${options.lib})`));
         }
+        if (source !== "all") {
+            console.log(chalk.gray(`  (searched in source: ${source})`));
+            console.log(chalk.gray(`  Try --source=all to search everything`));
+        }
         console.log(chalk.gray(`\nTry a different query or run 'pf-docs list' to see available docs.`));
         return;
     }
-    console.log(chalk.bold(`\n🔍 Search results for: "${query}"\n`));
+    const sourceLabel = source === "all" ? "all sources" : source;
+    console.log(chalk.bold(`\n🔍 Search results for: "${query}" (${sourceLabel})\n`));
     for (let i = 0; i < results.length; i++) {
         const result = results[i];
-        console.log(chalk.blue(`${i + 1}. ${result.title}`));
+        const label = source === "all" ? `${getSourceLabel(result.source)} ` : "";
+        console.log(`${label}${chalk.blue(`${i + 1}. ${result.title}`)}`);
         console.log(chalk.gray(`   Path: ${result.path}`));
         console.log(chalk.gray(`   ${result.snippet}`));
         console.log();
     }
     console.log(chalk.gray(`\nTo view a document: pf-docs get <path>`));
     console.log(chalk.gray(`Example: pf-docs get ${results[0].path}`));
+    if (source !== "all") {
+        console.log(chalk.gray(`\nTip: Use --source=all to search docs, examples, and episodes together`));
+    }
 }

package/dist/commands/stats.js

@@ -3,8 +3,9 @@
  */
 import chalk from "chalk";
 import { getStats, withIndex } from "../lib/index.js";
-import { LIBRARIES, getLibrary } from "../config.js";
-import { isLibraryCloned } from "../lib/repos.js";
+import { LIBRARIES, getLibrary, EXAMPLES_CONFIG, EPISODES_CONFIG } from "../config.js";
+import { isLibraryCloned, areExamplesCloned, areEpisodesCloned } from "../lib/repos.js";
+import { getSourceName } from "../lib/format.js";
 export function statsCommand(options) {
     const stats = withIndex(() => getStats());
     if (options.json) {
@@ -12,12 +13,19 @@ export function statsCommand(options) {
         return;
     }
     console.log(chalk.bold("\n📊 pf-docs Statistics\n"));
-    console.log(chalk.blue(`Total indexed documents: ${stats.totalDocs}`));
+    console.log(chalk.blue(`Total indexed items: ${stats.totalDocs}`));
     console.log();
-    console.log(chalk.bold("Indexed libraries:"));
+    // Show breakdown by source
+    console.log(chalk.bold("By source:"));
+    for (const [sourceName, count] of Object.entries(stats.bySource)) {
+        console.log(`  ${getSourceName(sourceName)}: ${count} items`);
+    }
+    console.log();
+    // Show breakdown by library
+    console.log(chalk.bold("By library:"));
     for (const [libName, count] of Object.entries(stats.byLibrary)) {
         const libConfig = getLibrary(libName);
-        console.log(`  ${chalk.green("●")} ${libName}: ${count} docs`);
+        console.log(`  ${chalk.green("●")} ${libName}: ${count} items`);
         if (libConfig) {
             console.log(chalk.gray(`      ${libConfig.description}`));
         }
@@ -34,4 +42,23 @@ export function statsCommand(options) {
         console.log();
         console.log(chalk.gray(`To add: pf-docs init --libs ${notIndexed[0].shortName}`));
     }
+    // Show examples/episodes status
+    const extrasNotIndexed = [];
+    if (!areExamplesCloned()) {
+        extrasNotIndexed.push("examples");
+    }
+    if (!areEpisodesCloned()) {
+        extrasNotIndexed.push("episodes");
+    }
+    if (extrasNotIndexed.length > 0) {
+        console.log(chalk.bold("Additional sources (not indexed):"));
+        if (extrasNotIndexed.includes("examples")) {
+            console.log(`  ${chalk.gray("○")} examples — ${EXAMPLES_CONFIG.description}`);
+        }
+        if (extrasNotIndexed.includes("episodes")) {
+            console.log(`  ${chalk.gray("○")} episodes — ${EPISODES_CONFIG.description}`);
+        }
+        console.log();
+        console.log(chalk.gray(`To add: pf-docs init --examples --episodes`));
+    }
 }