---
name: suaveplan-library-navigator
description: Navigate the 473+ @suaveplan/* packages. Load sp-<package> skills for deep API context, or search the docs tree for detailed module documentation.
---

# Suaveplan Library Navigator

This plugin provides natural-language discovery across all `@suaveplan/*` packages in the genesis monorepo. It consists of:

- **473 package skills** (`sp-<package>`) — distilled architecture, patterns, constraints, and checklists for every library
- **Docs tree** — 5,979 `.md` files mirrored from `packages/`, searchable for deep API detail
- **`/sp` slash command** — natural-language library finder

## 4-Tier Doc Hierarchy

```
packages/
  <category>/README.md                    → category overview
    <subcategory>/README.md               → subcategory package table
      <pkg>/README.md                     → package description + quick-start
        src/<module>/<module>.md          → module-level API docs
```

The docs tree at `.claude/plugins/suaveplan-skills/docs/` replicates this structure with only `.md` files.

## How to Navigate

1. **For a specific package** — load its skill: `sp-<package-name>`
   - Example: `sp-crypto` for `@suaveplan/crypto`
   - Example: `sp-api` for `@suaveplan/api`
   - Skills contain: description, architecture, file structure, patterns (code examples), constraints, checklist

2. **For cross-cutting concerns** — use the `/sp` slash command with a natural-language query
   - Example: `/sp I need to send SMS messages with retry and rate limiting`
   - The command searches the docs tree, ranks packages, and extracts code examples

3. **For deep API detail** — read the module `.md` files in the docs tree
   - Path: `.claude/plugins/suaveplan-skills/docs/<category>/<subcategory>/<pkg>/src/<module>.md`

## Skill Quality Tiers

| Tier | Count | Description |
|------|-------|-------------|
| **Distilled** | 10 | Manually curated with rich architecture tables, detailed patterns, and constraints (bitpacker family) |
| **Baseline** | 463 | Auto-generated from READMEs: accurate descriptions, sibling packages, extracted code examples |

Baseline skills are regenerated by `scripts/generate-sp-skills.ts` whenever READMEs change. Distilled skills are preserved across regeneration.

## Syncing Docs

Run `bun run scripts/sync-sp-docs.ts` to refresh the docs tree from `packages/`.

## Regenerating Skills

Run `bun run scripts/generate-sp-skills.ts` to regenerate baseline skills. Existing distilled skills are skipped.