@booklib/core 2.0.0

package/lib/wizard/prompt.js

@@ -0,0 +1,156 @@
+// lib/wizard/prompt.js
+import * as clack from '@clack/prompts';
+import { createInterface } from 'node:readline';
+
+// ── Clack-based wizard session ───────────────────────────────────────────────
+
+export function createWizardUI() {
+  return {
+    intro(text) { clack.intro(text); },
+    outro(text) { clack.outro(text); },
+
+    async confirm(message, initial = true) {
+      const result = await clack.confirm({ message, initialValue: initial });
+      if (clack.isCancel(result)) { clack.outro('Setup cancelled.'); process.exit(0); }
+      return result;
+    },
+
+    async text(message, placeholder) {
+      const result = await clack.text({ message, placeholder });
+      if (clack.isCancel(result)) { clack.outro('Setup cancelled.'); process.exit(0); }
+      return result;
+    },
+
+    async select(message, options) {
+      const result = await clack.select({ message, options });
+      if (clack.isCancel(result)) { clack.outro('Setup cancelled.'); process.exit(0); }
+      return result;
+    },
+
+    async multiselect(message, options, opts = {}) {
+      const result = await clack.multiselect({
+        message: `${message} (space to toggle, enter to confirm)`,
+        options,
+        required: false,
+        ...opts,
+      });
+      if (clack.isCancel(result)) { clack.outro('Setup cancelled.'); process.exit(0); }
+      return result;
+    },
+
+    spinner() { return clack.spinner(); },
+    log: clack.log,
+    isCancel: clack.isCancel,
+  };
+}
+
+// ── Legacy standalone functions (used outside wizard) ────────────────────────
+
+function readLine() {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const onSigint = () => { rl.close(); process.exit(130); };
+    process.once('SIGINT', onSigint);
+    rl.once('line', line => {
+      process.removeListener('SIGINT', onSigint);
+      rl.close();
+      resolve(line.trim());
+    });
+    rl.once('close', () => {
+      process.removeListener('SIGINT', onSigint);
+      resolve('');
+    });
+  });
+}
+
+export async function confirm(question, defaultY = true) {
+  process.stdout.write(`${question} [${defaultY ? 'Y/n' : 'y/N'}] `);
+  const answer = await readLine();
+  if (!answer) return defaultY;
+  return answer.toLowerCase().startsWith('y');
+}
+
+export async function multiSelect(question, choices) {
+  process.stdout.write(`\n${question}\n\n`);
+  choices.forEach((c, i) => {
+    const desc = c.description ? `  — ${c.description}` : '';
+    process.stdout.write(`  ${i + 1}. ${c.label}${desc}\n`);
+  });
+  process.stdout.write(`\n  [A] All (recommended)  [1,2,3...] pick  [S] Skip\n\n  > `);
+  const answer = await readLine();
+  if (!answer) return process.stdin.isTTY ? choices.map((_, i) => i) : [];
+  if (answer.toLowerCase() === 'a') return choices.map((_, i) => i);
+  if (answer.toLowerCase() === 's') return [];
+  return answer.split(',')
+    .map(n => parseInt(n.trim(), 10) - 1)
+    .filter(n => !isNaN(n) && n >= 0 && n < choices.length);
+}
+
+export function formatProgress(current, total, width = 30) {
+  const clamped = Math.min(current, total);
+  const filled = total > 0 ? Math.round((clamped / total) * width) : 0;
+  const bar = '\u2588'.repeat(filled) + '\u2591'.repeat(Math.max(0, width - filled));
+  return `[${bar}] ${clamped}/${total}`;
+}
+
+export function progressBar(total) {
+  let current = 0;
+  function render() { process.stdout.write(`\r  ${formatProgress(current, total)}`); }
+  render();
+  return {
+    tick(n = 1) { current = Math.min(current + n, total); render(); },
+    done() { process.stdout.write('\n'); },
+  };
+}
+
+export async function readText(promptText) {
+  process.stdout.write(promptText);
+  return readLine();
+}
+
+export function sep(char = '\u2500', width = 45) {
+  return char.repeat(width);
+}
+
+export function createSession(opts = {}) {
+  const rl = createInterface({
+    input: opts.input ?? process.stdin,
+    output: opts.output ?? process.stdout,
+  });
+  function question(prompt) {
+    return new Promise(resolve => {
+      rl.question(prompt, answer => resolve(answer.trim()));
+    });
+  }
+  return {
+    async confirm(text, defaultY = true) {
+      const answer = await question(`${text} [${defaultY ? 'Y/n' : 'y/N'}] `);
+      if (!answer) return defaultY;
+      return answer.toLowerCase().startsWith('y');
+    },
+    async readText(prompt) { return question(prompt); },
+    async multiSelect(title, choices) {
+      process.stdout.write(`\n${title}\n\n`);
+      choices.forEach((c, i) => {
+        const desc = c.description ? `  — ${c.description}` : '';
+        process.stdout.write(`  ${i + 1}. ${c.label}${desc}\n`);
+      });
+      process.stdout.write(`\n  [A] All  [1,2,3...] pick  [S] Skip\n\n`);
+      const answer = await question('  > ');
+      if (!answer) return choices.map((_, i) => i);
+      if (answer.toLowerCase() === 'a') return choices.map((_, i) => i);
+      if (answer.toLowerCase() === 's') return [];
+      return answer.split(',')
+        .map(n => parseInt(n.trim(), 10) - 1)
+        .filter(n => !isNaN(n) && n >= 0 && n < choices.length);
+    },
+    async numberedInput(prompt, maxN) {
+      const answer = await question(prompt);
+      if (!answer) return [];
+      return answer.split(',')
+        .map(n => parseInt(n.trim(), 10) - 1)
+        .filter(n => !isNaN(n) && n >= 0 && n < maxN);
+    },
+    close() { rl.close(); },
+  };
+}

package/lib/wizard/registry-embeddings.js

@@ -0,0 +1,107 @@
+// lib/wizard/registry-embeddings.js
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { fileURLToPath } from 'url';
+import { BookLibSearcher } from '../engine/searcher.js';
+
+const PACKAGE_ROOT = path.resolve(fileURLToPath(import.meta.url), '..', '..', '..');
+const CACHE_PATH   = path.join(os.homedir(), '.booklib', 'registry-embeddings.json');
+
+/**
+ * Extracts description from SKILL.md frontmatter.
+ * Exported for testing.
+ */
+export function extractDescription(content) {
+  // Try inline: description: some text on one line
+  const inline = content.match(/^description:\s+(?!>)(.+)$/m);
+  if (inline?.[1]?.trim()) return inline[1].trim();
+
+  // Try YAML folded scalar: description: >\n  line one\n  line two
+  const folded = content.match(/^description:\s*>\s*\n((?:[ \t]+[^\n]*\n?)+)/m);
+  if (folded) {
+    return folded[1]
+      .split('\n')
+      .map(l => l.trim())
+      .filter(Boolean)
+      .join(' ')
+      .slice(0, 200);
+  }
+
+  return null;
+}
+
+/**
+ * Returns unified skill catalog: bundled skills + community registry.
+ * Each entry: { name, description, source: 'bundled'|'registry', entry? }
+ */
+export function loadSkillCatalog() {
+  const skills = [];
+  const seen = new Set();
+
+  // 1. Bundled skills from package's skills/ directory
+  const skillsDir = path.join(PACKAGE_ROOT, 'skills');
+  try {
+    for (const name of fs.readdirSync(skillsDir)) {
+      const skillFile = path.join(skillsDir, name, 'SKILL.md');
+      if (!fs.existsSync(skillFile)) continue;
+      const content = fs.readFileSync(skillFile, 'utf8');
+      const description = extractDescription(content);
+      if (description && !seen.has(name)) {
+        skills.push({ name, description, source: 'bundled' });
+        seen.add(name);
+      }
+    }
+  } catch { /* skip if skills dir missing */ }
+
+  // 2. Community registry
+  const registryPath = path.join(PACKAGE_ROOT, 'community', 'registry.json');
+  try {
+    const raw = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+    const entries = Array.isArray(raw) ? raw : raw.skills ?? [];
+    for (const entry of entries) {
+      if (entry.name && entry.description && !seen.has(entry.name)) {
+        skills.push({ name: entry.name, description: entry.description, source: 'registry', entry });
+        seen.add(entry.name);
+      }
+    }
+  } catch { /* skip */ }
+
+  return skills;
+}
+
+/**
+ * Loads (or computes) embeddings for every skill in the catalog.
+ * Caches result to ~/.booklib/registry-embeddings.json.
+ *
+ * @param {Function} [onProgress] - (done: number, total: number) => void
+ * @returns {Promise<Map<string, number[]>>}
+ */
+export async function getEmbeddings(onProgress) {
+  const catalog = loadSkillCatalog();
+  const cached  = _loadCache();
+  const result  = new Map(Object.entries(cached));
+  const missing = catalog.filter(s => !result.has(s.name));
+
+  if (missing.length > 0) {
+    const searcher = new BookLibSearcher();
+    for (let i = 0; i < missing.length; i++) {
+      result.set(missing[i].name, await searcher.getEmbedding(missing[i].description));
+      onProgress?.(i + 1, missing.length);
+    }
+    _saveCache(Object.fromEntries(result));
+  }
+
+  return result;
+}
+
+function _loadCache() {
+  try { return JSON.parse(fs.readFileSync(CACHE_PATH, 'utf8')); } catch { return {}; }
+}
+
+function _saveCache(data) {
+  try {
+    fs.mkdirSync(path.dirname(CACHE_PATH), { recursive: true });
+    fs.writeFileSync(CACHE_PATH, JSON.stringify(data));
+  } catch { /* best-effort */ }
+}

package/lib/wizard/skill-recommender.js

@@ -0,0 +1,69 @@
+// lib/wizard/skill-recommender.js
+import { BookLibSearcher } from '../engine/searcher.js';
+import { loadSkillCatalog, getEmbeddings } from './registry-embeddings.js';
+
+export const SKILL_LIMIT = 32;
+
+/**
+ * Cosine similarity between two vectors. Exported for testing.
+ */
+export function cosine(a, b) {
+  let dot = 0, na = 0, nb = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    na  += a[i] * a[i];
+    nb  += b[i] * b[i];
+  }
+  return dot / (Math.sqrt(na) * Math.sqrt(nb) || 1);
+}
+
+/**
+ * Filters and ranks pre-scored catalog by installed exclusion and slot limit.
+ * Exported for testing.
+ *
+ * @param {Array<{name, score}>} catalog - already scored entries
+ * @param {{ installedNames: string[], available: number }} opts
+ */
+export function filterAndRank(catalog, { installedNames = [], available = SKILL_LIMIT } = {}) {
+  const installed = new Set(installedNames.map(n => n.toLowerCase()));
+  return catalog
+    .filter(s => !installed.has(s.name.toLowerCase()))
+    .sort((a, b) => (b.score ?? 0) - (a.score ?? 0))
+    .slice(0, available);
+}
+
+/**
+ * Returns ranked skill recommendations.
+ *
+ * @param {string} query - Free-text user goal (may be empty)
+ * @param {object} opts
+ * @param {string[]} opts.languages - Detected project languages
+ * @param {string[]} opts.installedNames - Already-installed skill names to exclude
+ * @param {number}   opts.slotsUsed - Current installed slot count
+ * @param {Function} [opts.onEmbeddingProgress] - (done, total) => void
+ * @returns {Promise<Array<{name, description, source, score, entry?}>>}
+ */
+export async function recommend(query, {
+  languages = [],
+  installedNames = [],
+  slotsUsed = 0,
+  onEmbeddingProgress,
+} = {}) {
+  const catalog    = loadSkillCatalog();
+  const embeddings = await getEmbeddings(onEmbeddingProgress);
+  const available  = Math.max(0, SKILL_LIMIT - slotsUsed);
+
+  // Build query: user text + language hints
+  const queryText = [query, ...languages.map(l => `${l} programming`)].filter(Boolean).join('. ')
+    || 'software engineering best practices';
+
+  const searcher = new BookLibSearcher();
+  const queryVec = await searcher.getEmbedding(queryText);
+
+  const scored = catalog.map(s => ({
+    ...s,
+    score: embeddings.has(s.name) ? cosine(queryVec, embeddings.get(s.name)) : 0,
+  }));
+
+  return filterAndRank(scored, { installedNames, available });
+}

package/llms-full.txt

@@ -0,0 +1,254 @@
+# BookLib Full Skill Catalog
+
+An open knowledge ecosystem for AI coding agents. Packages expert knowledge from canonical books as skills, with a discovery engine for community sources, semantic search, and orchestrator compatibility (obra/superpowers, ruflo).
+
+This file contains detailed descriptions and triggers for every bundled skill, plus documentation of the discovery system and CLI commands, optimized for RAG retrieval.
+
+## Skill: animation-at-work
+**Description**: Apply web animation principles from Animation at Work by Rachel Nabors. Covers human perception of motion, 12 principles of animation, animation patterns (transitions, supplements, feedback, demonstrations, decorations), CSS transitions, CSS animations, Web Animations API, SVG/Canvas/WebGL, communicating animation with storyboards and motion comps, performance (composite-only properties, will-change, RAIL), accessibility (prefers- reduced-motion, vestibular disorders), and team workflow. Trigger on "animation", "transition", "CSS animation", "keyframe", "easing", "motion design", "web animation", "prefers-reduced-motion", "storyboard", "parallax", "loading animation", "hover effect", "micro-interaction".
+
+**Directory**: `skills/animation-at-work/`
+
+---
+
+## Skill: clean-code-reviewer
+**Description**: Reviews code against Robert C. Martin's Clean Code principles. Use when users share code for review, ask for refactoring suggestions, or want to improve code quality. Produces actionable feedback organized by Clean Code principles with concrete before/after examples.
+**Directory**: `skills/clean-code-reviewer/`
+
+---
+
+## Skill: data-intensive-patterns
+**Description**: Generate and review data-intensive application code using patterns from Martin Kleppmann's "Designing Data-Intensive Applications." Use this skill whenever the user asks about data storage engines, replication, partitioning, transactions, distributed systems, batch or stream processing, encoding/serialization, consistency models, consensus, event sourcing, CQRS, change data capture, or anything related to building reliable, scalable, and maintainable data systems. Trigger on phrases like "data-intensive", "replication", "partitioning", "sharding", "LSM-tree", "B-tree", "transaction isolation", "distributed consensus", "stream processing", "batch processing", "event sourcing", "CQRS", "CDC", "change data capture", "serialization format", "schema evolution", "consensus algorithm", "leader election", "total order broadcast", or "data pipeline."
+
+**Directory**: `skills/data-intensive-patterns/`
+
+---
+
+## Skill: data-pipelines
+**Description**: Apply Data Pipelines Pocket Reference practices (James Densmore). Covers Infrastructure (Ch 1-2: warehouses, lakes, cloud), Patterns (Ch 3: ETL, ELT, CDC), DB Ingestion (Ch 4: MySQL, PostgreSQL, MongoDB, full/incremental), File Ingestion (Ch 5: CSV, JSON, cloud storage), API Ingestion (Ch 6: REST, pagination, rate limiting), Streaming (Ch 7: Kafka, Kinesis, event-driven), Storage (Ch 8: Redshift, BigQuery, Snowflake), Transforms (Ch 9: SQL, Python, dbt), Validation (Ch 10: Great Expectations, schema checks), Orchestration (Ch 11: Airflow, DAGs, scheduling), Monitoring (Ch 12: SLAs, alerting), Best Practices (Ch 13: idempotency, backfilling, error handling). Trigger on "data pipeline", "ETL", "ELT", "data ingestion", "Airflow", "dbt", "data warehouse", "Kafka streaming", "CDC", "data orchestration".
+
+**Directory**: `skills/data-pipelines/`
+
+---
+
+## Skill: design-patterns
+**Description**: Apply and review GoF design patterns from Head First Design Patterns. Use for Creational patterns (Factory Method, Abstract Factory, Singleton, Builder, Prototype), Structural patterns (Adapter, Bridge, Composite, Decorator, Facade, Flyweight, Proxy), Behavioral patterns (Chain of Responsibility, Command, Interpreter, Iterator, Mediator, Memento, Observer, State, Strategy, Template Method, Visitor), compound patterns (MVC), and OO design principles. Trigger on "design pattern", "GoF", "Gang of Four", "factory", "singleton", "observer", "strategy", "decorator", "adapter", "facade", "proxy", "composite", "command", "iterator", "state", "template method", "builder", "prototype", "bridge", "flyweight", "mediator", "memento", "visitor", "chain of responsibility", "interpreter", "MVC", "refactor to pattern", or "code smells."
+
+**Directory**: `skills/design-patterns/`
+
+---
+
+## Skill: domain-driven-design
+**Description**: Design and review software using patterns from Eric Evans' "Domain-Driven Design." Use for DDD tactical patterns (Entities, Value Objects, Aggregates, Repositories, Factories, Domain Services), strategic patterns (Bounded Context, Context Map, Anticorruption Layer, Shared Kernel, Open Host Service), supple design (Intention-Revealing Interfaces, Side-Effect-Free Functions, Closure of Operations), distillation (Core Domain, Segregated Core), large-scale structure (Responsibility Layers, Knowledge Level), and Ubiquitous Language. Trigger on "DDD", "domain-driven design", "bounded context", "aggregate root", "value object", "entity", "repository pattern", "domain service", "anticorruption layer", "context map", "ubiquitous language", "core domain", "specification pattern", "supple design", "layered architecture", or "strategic design."
+
+**Directory**: `skills/domain-driven-design/`
+
+---
+
+## Skill: effective-java
+**Description**: Generate and review Java code using patterns and best practices from Joshua Bloch's "Effective Java" (3rd Edition). Use this skill whenever the user asks about Java best practices, API design, object creation patterns, generics, enums, lambdas, streams, concurrency, serialization, method design, exception handling, or writing clean, maintainable Java code. Trigger on phrases like "Effective Java", "Java best practices", "builder pattern", "static factory", "defensive copy", "immutable class", "enum type", "generics", "bounded wildcard", "PECS", "stream pipeline", "optional", "thread safety", "serialization proxy", "checked exception", "try-with-resources", "composition over inheritance", "method reference", "functional interface", or "Java API design."
+
+**Directory**: `skills/effective-java/`
+
+---
+
+## Skill: effective-kotlin
+**Description**: Apply Effective Kotlin best practices (Marcin Moskała, 2nd Ed). Covers Safety (Items 1-10: mutability, scope, nulls, types, expectations, errors, resources, tests), Readability (Items 11-18: operators, receivers, properties, naming), Reusability (Items 19-25: DRY, generics, delegation, variance), Abstraction (Items 26-32: levels, stability, visibility, contracts), Object Creation (Items 33-35: factories, constructors, DSLs), Class Design (Items 36-44: composition, data classes, sealed hierarchies, equals/hashCode/compareTo, extensions), Efficiency (Items 45-52: object creation, inline, sequences, collections). Trigger on "Effective Kotlin", "Kotlin best practice", "Kotlin idiom", "Kotlin style", "Kotlin review", "Kotlin safety", "Kotlin performance", "Kotlin readability", or "Kotlin design".
+
+**Directory**: `skills/effective-kotlin/`
+
+---
+
+## Skill: effective-python
+**Description**: Review existing Python code and write new Python code following the 90 best practices from "Effective Python" by Brett Slatkin (2nd Edition). Use when writing Python, reviewing Python code, or wanting idiomatic, Pythonic solutions.
+**Directory**: `skills/effective-python/`
+
+---
+
+## Skill: effective-typescript
+**Description**: Review existing TypeScript code and write new TypeScript following the 62 items from "Effective TypeScript" by Dan Vanderkam. Use when writing TypeScript, reviewing TypeScript code, working with type design, avoiding any, managing type declarations, or migrating JavaScript to TypeScript. Trigger on: "TypeScript best practices", "type safety", "any", "type assertions", "type design", "strict mode", "TypeScript review", "migrate to TypeScript".
+
+**Directory**: `skills/effective-typescript/`
+
+---
+
+## Skill: kotlin-in-action
+**Description**: Apply Kotlin In Action practices (Elizarov, Isakova, Aigner, Jemerov, 2nd Ed). Covers Basics (Ch 1-3: functions, extensions, default args), Classes (Ch 4: sealed, data, delegation, companion objects), Lambdas (Ch 5-6: functional APIs, sequences, scope functions), Nullability (Ch 7-8: safe calls, Elvis, platform types, primitives), Conventions (Ch 9: operators, delegated properties), Higher-Order (Ch 10: inline, noinline, crossinline), Generics (Ch 11: variance, reified), Reflection (Ch 12: KClass, KProperty), DSLs (Ch 13: receivers, @DslMarker), Coroutines (Ch 14: structured concurrency, dispatchers, cancellation), Flows (Ch 15: operators, StateFlow, SharedFlow). Trigger on "Kotlin In Action", "Kotlin idiom", "Kotlin coroutine", "Kotlin flow", "Kotlin DSL", "Kotlin generics", "Kotlin null safety", "Kotlin delegation", "Kotlin inline", or "Kotlin extension".
+
+**Directory**: `skills/kotlin-in-action/`
+
+---
+
+## Skill: lean-startup
+**Description**: Apply The Lean Startup practices (Eric Ries). Covers Vision (Ch 1-4: Start, Define, Learn, Experiment — validated learning, Build-Measure-Learn loop), Steer (Ch 5-8: Leap of faith assumptions, MVP testing, innovation accounting, pivot or persevere decisions), Accelerate (Ch 9-14: small batches, engines of growth — sticky/viral/paid, adaptive organization, Five Whys, innovation sandbox, startup within enterprise). Trigger on "lean startup", "MVP", "minimum viable product", "validated learning", "pivot", "Build-Measure-Learn", "innovation accounting", "product-market fit", "startup strategy", "lean methodology", "growth engine", "Five Whys".
+
+**Directory**: `skills/lean-startup/`
+
+---
+
+## Skill: microservices-patterns
+**Description**: Generate and review microservices code using patterns from Chris Richardson's "Microservices Patterns." Use this skill whenever the user asks about microservices architecture, wants to generate service code, design distributed systems, review microservices code, implement sagas, set up CQRS, configure API gateways, handle inter-service communication, or anything related to breaking apart monoliths. Trigger on phrases like "microservice", "saga pattern", "event sourcing", "CQRS", "API gateway", "service mesh", "domain-driven design for services", "distributed transactions", "decompose my monolith", or "review my microservice."
+
+**Directory**: `skills/microservices-patterns/`
+
+---
+
+## Skill: programming-with-rust
+**Description**: Write and review Rust code using practices from "Programming with Rust" by Donis Marshall. Covers ownership, borrowing, lifetimes, error handling with Result/Option, traits, generics, pattern matching, closures, fearless concurrency, and macros. Use when writing Rust, reviewing Rust code, or learning Rust idioms. Trigger on: "Rust", "ownership", "borrow checker", "lifetimes", "Result", "Option", "traits", "fearless concurrency", ".rs files", "cargo".
+
+**Directory**: `skills/programming-with-rust/`
+
+---
+
+## Skill: refactoring-ui
+**Description**: Apply UI design principles from Refactoring UI by Adam Wathan & Steve Schoger. Covers visual hierarchy (size, weight, color, spacing), layout systems (spacing scales, grids), typography (type scales, line-height, alignment), color (HSL palettes, shade systems, accessible contrast), depth (shadow elevation, overlap), images (text on images, user content, icons), and finishing touches (accent borders, empty states, fewer borders). Trigger on "UI design", "visual hierarchy", "spacing system", "type scale", "color palette", "shadow", "layout", "design system", "component design", "card design", "form design", "button design", "refactoring UI", "design tokens", "dark mode", "responsive design".
+
+**Directory**: `skills/refactoring-ui/`
+
+---
+
+## Skill: rust-in-action
+**Description**: Write and review Rust code using systems programming concepts from "Rust in Action" by Tim McNamara. Covers language foundations, ownership and borrowing, smart pointers, data representation (bits, endianness, floats), memory (stack/heap/virtual), file I/O, networking (TCP/HTTP), concurrency (threads/closures), and OS-level programming. Use when writing systems-level Rust, working with binary data, raw pointers, file formats, network protocols, or low-level memory. Trigger on: "Rust", "systems programming", "smart pointers", "endianness", "bit manipulation", "TCP", "raw pointers", "serde", "borrow checker", "ownership", "concurrency", "kernel", ".rs files", "cargo".
+
+**Directory**: `skills/rust-in-action/`
+
+---
+
+## Skill: skill-router
+**Description**: Select the 1-2 most relevant booklib for a given file, PR, or task. Use before applying any skill when unsure which book's lens applies, or when multiple skills could apply. Trigger on "which skill", "which book", "route this", "what skill should I use", or whenever a user describes a task without specifying a skill. Returns a ranked recommendation with rationale and anti-triggers.
+
+**Directory**: `skills/skill-router/`
+
+---
+
+## Skill: spring-boot-in-action
+**Description**: Write and review Spring Boot applications using practices from "Spring Boot in Action" by Craig Walls. Covers auto-configuration, starter dependencies, externalizing configuration with properties and profiles, Spring Security, testing with MockMvc and @SpringBootTest, Spring Actuator for production observability, and deployment strategies (JAR, WAR, Cloud Foundry). Use when building Spring Boot apps, configuring beans, writing integration tests, setting up health checks, or deploying to production. Trigger on: "Spring Boot", "Spring", "@SpringBootApplication", "auto-configuration", "application.properties", "application.yml", "@RestController", "@Service", "@Repository", "SpringBootTest", "Actuator", "starter", ".java files", "Maven", "Gradle".
+
+**Directory**: `skills/spring-boot-in-action/`
+
+---
+
+## Skill: storytelling-with-data
+**Description**: Apply data visualization and storytelling principles from Storytelling with Data by Cole Nussbaumer Knaflic. Covers choosing effective visuals (line, bar, table, scatterplot), eliminating clutter (Gestalt principles, data-ink ratio), focusing attention (preattentive attributes, strategic color), thinking like a designer (affordances, alignment, white space), and narrative structure (three-act story, horizontal/vertical logic, Big Idea). Trigger on "data visualization", "chart design", "dashboard design", "data storytelling", "presentation chart", "declutter chart", "bar chart", "line chart", "data narrative", "slide deck data", "chart review", "viz critique", "storytelling with data".
+
+**Directory**: `skills/storytelling-with-data/`
+
+---
+
+## Skill: system-design-interview
+**Description**: Apply system design principles from System Design Interview by Alex Xu. Covers scaling (load balancing, DB replication, sharding, caching, CDN), estimation (QPS, storage, bandwidth), the 4-step framework, and 12 real designs: rate limiter, consistent hashing, key-value store, unique ID generator, URL shortener, web crawler, notification system, news feed, chat system, search autocomplete, YouTube, Google Drive. Trigger on "system design", "scale", "high-level design", "distributed system", "rate limiter", "consistent hashing", "back-of-envelope", "QPS", "sharding", "load balancer", "CDN", "cache", "message queue", "web crawler", "news feed", "chat system", "autocomplete", "URL shortener".
+
+**Directory**: `skills/system-design-interview/`
+
+---
+
+## Skill: using-asyncio-python
+**Description**: Apply Using Asyncio in Python practices (Caleb Hattingh). Covers Introducing Asyncio (Ch 1: what it is, I/O-bound concurrency), Threads (Ch 2: drawbacks, race conditions, GIL, ThreadPoolExecutor), Asyncio Walk-Through (Ch 3: event loop, coroutines, async def/await, tasks, futures, gather, wait, async with, async for, async comprehensions, startup/shutdown, signal handling, executors), Libraries (Ch 4: aiohttp, aiofiles, Sanic, aioredis, asyncpg), Concluding Thoughts (Ch 5), History (App A: generators to async/await), Supplementary (App B). Trigger on "asyncio", "async/await", "event loop", "coroutine", "aiohttp", "async Python", "concurrent I/O", "non-blocking".
+
+**Directory**: `skills/using-asyncio-python/`
+
+---
+
+## Skill: web-scraping-python
+**Description**: Apply Web Scraping with Python practices (Ryan Mitchell). Covers First Scrapers (Ch 1: urllib, BeautifulSoup), HTML Parsing (Ch 2: find, findAll, CSS selectors, regex, lambda), Crawling (Ch 3-4: single-domain, cross-site, crawl models), Scrapy (Ch 5: spiders, items, pipelines, rules), Storing Data (Ch 6: CSV, MySQL, files, email), Reading Documents (Ch 7: PDF, Word, encoding), Cleaning Data (Ch 8: normalization, OpenRefine), NLP (Ch 9: n-grams, Markov, NLTK), Forms & Logins (Ch 10: POST, sessions, cookies), JavaScript (Ch 11: Selenium, headless, Ajax), APIs (Ch 12: REST, undocumented), Image/OCR (Ch 13: Pillow, Tesseract), Avoiding Traps (Ch 14: headers, honeypots), Testing (Ch 15: unittest, Selenium), Parallel (Ch 16: threads, processes), Remote (Ch 17: Tor, proxies), Legalities (Ch 18: robots.txt, CFAA, ethics). Trigger on "web scraping", "BeautifulSoup", "Scrapy", "crawler", "spider", "scraper", "parse HTML", "Selenium scraping", "data extraction".
+
+**Directory**: `skills/web-scraping-python/`
+
+---
+---
+
+## Discovery & Community Skills
+
+BookLib can discover and fetch skills beyond the 22 bundled ones. As of the current registry, 258 community skills are discoverable.
+
+### Configuration (booklib.config.json)
+
+Source types:
+- `registry` — bundled skills (this package)
+- `manifest` — JSON list at a URL or local path; `community/registry.json` ships 258 skills with star counts and role tags
+- `github-skills-dir` — scans a subdirectory of a GitHub repo for SKILL.md files (e.g. obra/superpowers `skills/`, ruvnet/ruflo `.claude/skills/`)
+- `github-org` — scans all public repos in a GitHub org for SKILL.md at root
+- `npm-scope` — searches an npm scope for packages containing SKILL.md
+
+Set `GITHUB_TOKEN` env var to raise the GitHub API limit from 60 to 5000 req/hr.
+
+### Discovery Commands
+
+- `booklib discover` — list available skills from all configured sources (cached 24h)
+- `booklib discover --refresh` — force re-scan
+- `booklib fetch <name>` — download, index, and sync a specific skill
+- `booklib setup` — fetch all trusted skills at once
+
+---
+
+## Orchestrator Compatibility
+
+After `booklib sync`, every fetched skill is written to `~/.claude/skills/<name>/SKILL.md` with clean frontmatter (no internal XML wrappers). A `.booklib` marker file identifies BookLib-managed directories so user-placed skills are never overwritten.
+
+Compatible with:
+- **obra/superpowers** — install with `/plugin install superpowers`; skills surface via Claude Code's native Skill tool
+- **ruflo** — install with `npm install -g ruflo`; same Skill tool path
+
+---
+
+## Swarm & Role-Based Profiles
+
+### booklib profile <role>
+
+Returns skills most relevant to an agent role. Available roles:
+`architect` · `coder` · `reviewer` · `tester` · `security` · `frontend` · `optimizer` · `devops` · `ai-engineer` · `manager`
+
+### booklib swarm-config [trigger]
+
+Maps a swarm trigger to agent roles and their recommended skills. Built-in triggers:
+- `audit` → security-scan · coverage · vulnerability-check
+- `feature` → architect · coder · reviewer · tester
+- `refactor` → reviewer · coder · optimizer
+- `deploy` → devops · security
+
+### booklib init [--orchestrator=obra|ruflo]
+
+Generates context files for all AI tools in the project:
+- `CLAUDE.md` — Claude Code
+- `.cursor/rules/booklib-standards.mdc` — Cursor
+- `.github/copilot-instructions.md` — GitHub Copilot
+- `.gemini/context.md` — Gemini CLI
+
+With `--orchestrator`, appends install instructions for the chosen framework.
+
+---
+
+## Skill Activation Mechanisms
+
+| Mechanism | How it works |
+|-----------|-------------|
+| PreToolUse hook | Fires on every Read/Edit/Write/Bash call; matches file path against skill `filePattern` metadata; injects relevant chunks as `additionalContext`. Fine-grained, automatic, silent. |
+| Skill tool | `Skill("<name>")` returns the full SKILL.md content. Coarse, on-demand, used by orchestrator subagents. Reads from `~/.claude/skills/` after `booklib sync`. |
+| Search | `booklib search "<concept>"` runs vector search over indexed chunks; returns the most relevant passages. |
+| Audit | `booklib audit <skill> <file>` applies a skill's principles to a specific file and reports violations. |
+
+---
+
+## Session Handoff
+
+- `booklib save-state --goal="..." --next="..." --progress="..."` — save context snapshot
+- `booklib resume` — restore last session
+- `booklib recover-auto` — auto-recover from session files or git history
+- `booklib sessions-list` — all sessions across agents
+- `booklib sessions-merge <a>,<b> <output>` — merge two session contexts
+- `booklib sessions-lineage <parent> <child> "<note>"` — track session inheritance
+- `booklib sessions-compare <a>,<b> <file> <output>` — compare multi-agent audit findings
+
+All session data stored in `.booklib/sessions/` (gitignored).
+
+---
+
+## MCP Server
+
+Start: `node bin/booklib-mcp.js`
+
+Tools exposed:
+- `search_skills` — semantic search over skill content
+- `audit_content` — apply a skill to arbitrary code content
+- `save_session_state` — persist a handoff snapshot
+- `scan_project` — generate wisdom heatmap for a project directory