@flydocs/cli 0.5.0-beta.1 → 0.5.0-beta.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flydocs/cli",
-  "version": "0.5.0-beta.1",
+  "version": "0.5.0-beta.11",
   "type": "module",
   "description": "FlyDocs AI CLI — install, setup, and manage FlyDocs projects",
   "bin": {
@@ -22,6 +22,7 @@
   "dependencies": {
     "@clack/prompts": "^0.9.1",
     "citty": "^0.1.6",
+    "clipboardy": "^5.3.0",
     "picocolors": "^1.1.1"
   },
   "devDependencies": {

package/template/.claude/CLAUDE.md

@@ -21,29 +21,29 @@ These are non-negotiable and enforced by hooks:
 
 The FlyDocs development lifecycle. Read the workflow skill before taking any workflow action.
 
-| Action | Skill | Entry Point |
-|--------|-------|-------------|
-| Capture issue | `flydocs-workflow` | `stages/capture.md` |
-| Refine / triage | `flydocs-workflow` | `stages/refine.md` |
-| Activate work | `flydocs-workflow` | `stages/activate.md` |
-| Implement | `flydocs-workflow` | `stages/implement.md` |
-| Code review | `flydocs-workflow` | `stages/review.md` |
-| QE validation | `flydocs-workflow` | `stages/validate.md` |
-| Close issue | `flydocs-workflow` | `stages/close.md` |
-| Start / wrap session | `flydocs-workflow` | `session.md` |
-| Comment templates | `flydocs-workflow` | `reference/comment-templates.md` |
-| Status transitions | `flydocs-workflow` | `reference/status-workflow.md` |
+| Action               | Skill              | Entry Point                       |
+| -------------------- | ------------------ | --------------------------------- |
+| Capture issue        | `flydocs-workflow` | `stages/capture.md`               |
+| Refine / triage      | `flydocs-workflow` | `stages/refine.md`                |
+| Activate work        | `flydocs-workflow` | `stages/activate.md`              |
+| Implement            | `flydocs-workflow` | `stages/implement.md`             |
+| Code review          | `flydocs-workflow` | `stages/review.md`                |
+| QE validation        | `flydocs-workflow` | `stages/validate.md`              |
+| Close issue          | `flydocs-workflow` | `stages/close.md`                 |
+| Start / wrap session | `flydocs-workflow` | `session.md`                      |
+| Comment templates    | `flydocs-workflow` | `reference/comment-templates.md`  |
+| Status transitions   | `flydocs-workflow` | `reference/status-workflow.md`    |
 | Priority & estimates | `flydocs-workflow` | `reference/priority-estimates.md` |
-| Issue templates | `flydocs-workflow` | `templates/` |
+| Issue templates      | `flydocs-workflow` | `templates/`                      |
 
 ## Mechanism Scripts
 
 Issue operations are handled by the installed mechanism skill. Only one is active at a time.
 
-| Tier | Skill | Backend |
-|------|-------|---------|
-| Local (free) | `flydocs-local` | File-based (`flydocs/issues/`) |
-| Cloud (connected) | `flydocs-cloud` | Linear GraphQL API |
+| Tier              | Skill           | Backend                        |
+| ----------------- | --------------- | ------------------------------ |
+| Local (free)      | `flydocs-local` | File-based (`flydocs/issues/`) |
+| Cloud (connected) | `flydocs-cloud` | Linear GraphQL API             |
 
 Read the active mechanism skill's `SKILL.md` for script catalog and calling conventions.
 
@@ -54,37 +54,72 @@ Read the active mechanism skill's `SKILL.md` for script catalog and calling conv
 
 FlyDocs platform skills with premium functionality.
 
-| Skill | When to Read |
-|-------|--------------|
-| `flydocs-figma` | Building UI from Figma designs — extraction, token mapping |
-| `flydocs-estimates` | Estimating AI token usage and costs (opt-in via config) |
+| Skill               | When to Read                                               |
+| ------------------- | ---------------------------------------------------------- |
+| `flydocs-figma`     | Building UI from Figma designs — extraction, token mapping |
+| `flydocs-estimates` | Estimating AI token usage and costs (opt-in via config)    |
 
 ## Project Context
 
-| File | Purpose |
-|------|---------|
+| File                         | Purpose                                      |
+| ---------------------------- | -------------------------------------------- |
 | `flydocs/context/project.md` | Product scope, tech stack, active priorities |
-| `.flydocs/config.json` | Tier, provider, labels, active projects |
+| `.flydocs/config.json`       | Tier, provider, labels, active projects      |
 
 ## Hooks
 
-| Hook | Trigger | Purpose |
-|------|---------|---------|
-| `PostToolUse` (Edit/Write) | After code changes | Auto-format |
-| `UserPromptSubmit` | Before prompt | Inject git/issue context |
-| `PreToolUse` | Before script execution | Auto-approve mechanism scripts |
+| Hook                       | Trigger                 | Purpose                        |
+| -------------------------- | ----------------------- | ------------------------------ |
+| `PostToolUse` (Edit/Write) | After code changes      | Auto-format                    |
+| `UserPromptSubmit`         | Before prompt           | Inject git/issue context       |
+| `PreToolUse`               | Before script execution | Auto-approve mechanism scripts |
+
+## Output Formatting
+
+Consistent formatting across all agent output. Follow these rules in every
+response — session summaries, issue comments, status updates, and plans.
+
+**Structure:**
+
+- Lead with a one-line summary or status before detail.
+- Use `##` for major sections, `###` for subsections. Never skip levels.
+- Use bullet lists for 3+ related items. Use numbered lists only for sequences.
+- One blank line between sections. No double-blank lines.
+
+**Readability:**
+
+- Keep paragraphs to 2-3 sentences. Break long blocks into scannable lists.
+- Bold key terms and status labels on first use: **Completed**, **Blocked**, **Next**.
+- Use inline code for file paths, commands, and identifiers: `project.md`, `/start-session`, `FLY-123`.
+- Use code blocks with language tags for multi-line code or script examples.
+
+**Consistency:**
+
+- Status labels: **Completed**, **In Progress**, **Blocked**, **Next Up** (always bolded).
+- Issue references: `FLY-123` format (uppercase prefix, hyphen, number).
+- File paths: relative from project root, in backticks.
+- Dates: `YYYY-MM-DD` format.
+- No emoji in output unless the user explicitly requests it.
+
+**Tables:**
+
+- Use tables for structured comparisons (3+ items with 2+ attributes).
+- Left-align text columns, keep headers short.
 
 <!-- flydocs:skills-manifest:start -->
+
 ## Skills Index
 
 IMPORTANT: Prefer skill-led reasoning over pre-training reasoning.
 Consult the relevant skill BEFORE writing code or making workflow decisions.
 
-| Skill | Triggers | Entry |
-|-------|----------|-------|
-| flydocs-cloud | create issue, transition, comment, list issues, assign, update description, update issue, project update, Linear, cloud | .claude/skills/flydocs-cloud/SKILL.md |
-| flydocs-estimates | estimate, cost, token usage, API cost, labor estimate, sizing, effort | .claude/skills/flydocs-estimates/SKILL.md |
-| flydocs-figma | Figma, design, screenshot, token mapping, component from design, pixel-perfect, design system | .claude/skills/flydocs-figma/SKILL.md |
-| flydocs-local | create issue, transition, comment, list issues, assign, update description, status summary, local | .claude/skills/flydocs-local/SKILL.md |
-| flydocs-workflow | capture, refine, activate, implement, review, validate, close, session, workflow, transition, status, issue | .claude/skills/flydocs-workflow/SKILL.md |
+| Skill             | Triggers                                                                                                                | Entry                                     |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| flydocs-cloud     | create issue, transition, comment, list issues, assign, update description, update issue, project update, Linear, cloud | .claude/skills/flydocs-cloud/SKILL.md     |
+| flydocs-context7  | context7, library docs, documentation lookup, framework docs, package docs, API reference                               | .claude/skills/flydocs-context7/SKILL.md  |
+| flydocs-estimates | estimate, cost, token usage, API cost, labor estimate, sizing, effort                                                   | .claude/skills/flydocs-estimates/SKILL.md |
+| flydocs-figma     | Figma, design, screenshot, token mapping, component from design, pixel-perfect, design system                           | .claude/skills/flydocs-figma/SKILL.md     |
+| flydocs-local     | create issue, transition, comment, list issues, assign, update description, status summary, local                       | .claude/skills/flydocs-local/SKILL.md     |
+| flydocs-workflow  | capture, refine, activate, implement, review, validate, close, session, workflow, transition, status, issue             | .claude/skills/flydocs-workflow/SKILL.md  |
+
 <!-- flydocs:skills-manifest:end -->

package/template/.claude/agents/implementation-agent.md

@@ -2,7 +2,7 @@
 name: implementation-agent
 description: "Builds features, fixes bugs, writes code. Invoke for implementation, coding, or technical work."
 model: opus
-tools: [Read, Glob, Grep, Bash, Write, Edit, WebFetch, WebSearch, mcp__context7]
+tools: [Read, Glob, Grep, Bash, Write, Edit, WebFetch, WebSearch]
 skills:
   - flydocs-workflow
 ---

package/template/.claude/agents/research-agent.md

@@ -2,7 +2,7 @@
 name: research-agent
 description: "Codebase exploration and research. Invoke for understanding code structure, finding patterns, or gathering technical context."
 model: sonnet
-tools: [Read, Glob, Grep, WebFetch, WebSearch, mcp__context7]
+tools: [Read, Glob, Grep, WebFetch, WebSearch]
 disallowedTools: [Bash, Write, Edit]
 skills:
   - flydocs-workflow

package/template/.claude/commands/flydocs-setup.md

@@ -11,6 +11,22 @@ Triggers: "setup flydocs", "onboard project", "flydocs init"
 
 ---
 
+## IMPORTANT: Use Plan Mode
+
+**Before executing any setup steps, enter plan mode.** This setup involves
+multiple phases with user decisions at each stage. Planning first ensures a
+better experience:
+
+1. Run scenario detection (Phase 0) to understand the project state
+2. Scan for existing documentation and the tech stack
+3. Present a structured setup plan showing all phases and what each will do
+4. Get user approval before making any changes
+
+This lets the user see the full picture before committing. Only exit plan
+mode and begin execution after the user approves the plan.
+
+---
+
 ## Phase 0: Scenario Detection
 
 Before starting, detect the project state by checking the filesystem:
@@ -161,7 +177,7 @@ offer updates.
 **Step 0: Check for legacy context files.**
 
 Before reading project.md, check if `flydocs/context/legacy/` exists. This
-directory is created by `install.sh` when it finds pre-v1.0 separate context
+directory is created by the installer when it finds pre-v1.0 separate context
 files (`overview.md`, `stack.md`, `standards.md`) and moves them there for
 safe migration.
 
@@ -175,7 +191,7 @@ Consolidate into project.md using the same mapping as Phase 1M Step 2.
 Show the user the merged result and confirm before writing.
 
 After successful migration, delete the files from `legacy/` so the next
-`install.sh` run will clean up the empty directory.
+`flydocs update` run will clean up the empty directory.
 
 **Step 1: Show what's new in this version.**
 
@@ -187,7 +203,7 @@ update:
 ```
 Updated to FlyDocs v0.2.0. Here's what changed:
 - Scenario-aware setup command with proactive doc scanning
-- Deprecated file cleanup in install.sh
+- Deprecated file cleanup in the installer
 - Legacy context migration for pre-v1.0 projects
 - Changelog and version tracking
 ```
@@ -541,7 +557,26 @@ Wrapping up:
 - No account or API key needed — everything is local and offline
 - Run `/status` anytime to see your backlog at a glance
 
-### Step 4: Beta CTA
+### Step 4: Commit setup
+
+FlyDocs setup creates and modifies many files. Prompt the user to commit
+everything as a clean baseline:
+
+```
+Ready to commit the FlyDocs setup? This creates a clean baseline with all
+configuration, context, and initial backlog in one commit.
+```
+
+If the user agrees, create a single commit with a message like:
+`Add FlyDocs project setup (local tier)` or `Add FlyDocs project setup (cloud tier)`
+
+Stage all new and modified FlyDocs files (`.flydocs/`, `.claude/`, `.cursor/`,
+`flydocs/`, `AGENTS.md`, `.gitignore`). Do not stage unrelated changes.
+
+If the user declines, remind them to commit before starting work:
+"No problem — just remember to commit these files before your first session."
+
+### Step 5: Beta CTA
 
 Always end with the beta call-to-action:
 

package/template/.claude/commands/flydocs-update.md

@@ -7,10 +7,9 @@ Check for and apply FlyDocs updates to this project.
 1. **Check current version** — read `.flydocs/version` and report it.
 2. **Show changelog** — read `.flydocs/CHANGELOG.md` and summarize recent changes
    since the installed version.
-3. **Run update** — execute `flydocs update` (or `install.sh --update` if using
-   the bash CLI) to update skills, commands, hooks, and config to the latest
-   version. Preserves project-specific content in `flydocs/context/project.md`
-   and user config in `.flydocs/config.json`.
+3. **Run update** — execute `flydocs update` to update skills, commands, hooks,
+   and config to the latest version. Preserves project-specific content in
+   `flydocs/context/project.md` and user config in `.flydocs/config.json`.
 4. **Post-update** — if version changed, suggest running `/flydocs-setup` to review
    any new config options or migrate legacy content.
 5. **Beta reminder** — always end with:

package/template/.claude/settings.json

@@ -10,16 +10,6 @@
             "timeout": 5
           }
         ]
-      },
-      {
-        "matcher": "mcp__linear.*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.flydocs/hooks/prefer-scripts.py",
-            "timeout": 5
-          }
-        ]
       }
     ],
     "PostToolUse": [

package/template/.claude/skills/README.md

@@ -11,24 +11,17 @@
 Owned and maintained by FlyDocs. May include executable scripts and premium
 functionality gated via API relay.
 
-| Skill | Category | Purpose |
-|-------|----------|---------|
-| `flydocs-workflow` | Core | Lifecycle stages, session management, comment templates |
-| `flydocs-local` | Mechanism (free) | File-based issue management |
-| `flydocs-cloud` | Mechanism (paid) | Linear/provider issue management via API |
-| `flydocs-figma` | Premium | Design extraction from Figma |
-| `flydocs-estimates` | Premium | AI token/labor cost estimation |
+| Skill               | Category         | Purpose                                                 |
+| ------------------- | ---------------- | ------------------------------------------------------- |
+| `flydocs-workflow`  | Core             | Lifecycle stages, session management, comment templates |
+| `flydocs-local`     | Mechanism (free) | File-based issue management                             |
+| `flydocs-cloud`     | Mechanism (paid) | Linear/provider issue management via API                |
+| `flydocs-context7`  | Core             | Library documentation lookup via Context7 API           |
+| `flydocs-figma`     | Premium          | Design extraction from Figma                            |
+| `flydocs-estimates` | Premium          | AI token/labor cost estimation                          |
 
 Only one mechanism skill is active at a time. Determined by `tier` in `.flydocs/config.json`.
 
-Supporting workflow skills (bundled, invoked via commands):
-
-| Skill | Purpose | Trigger |
-|-------|---------|---------|
-| `implementation-flow` | Implementation procedure | `/implement` |
-| `review-workflow` | Code review analysis | `/review` |
-| `spec-templates` | Issue specification templates | `/capture`, `/refine` |
-
 ### Unprefixed — Community Skills
 
 Stack-detected or manually installed. Pure guidance (markdown only, no scripts).
@@ -87,17 +80,17 @@ triggers:
 
 **Required fields:**
 
-| Field | Type | Purpose |
-|-------|------|---------|
-| `name` | string | Skill identifier, matches directory name |
+| Field         | Type   | Purpose                                                                                                           |
+| ------------- | ------ | ----------------------------------------------------------------------------------------------------------------- |
+| `name`        | string | Skill identifier, matches directory name                                                                          |
 | `description` | string | What the skill does and when to use it. Agents use this for auto-selection. Be specific about trigger conditions. |
 
 **Optional fields:**
 
-| Field | Type | Purpose |
-|-------|------|---------|
+| Field      | Type     | Purpose                                                                                                                   |
+| ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------- |
 | `triggers` | string[] | Keywords/phrases for manifest indexing. Used by skill discovery to build the always-present index in CLAUDE.md/AGENTS.md. |
-| `tools` | string | Comma-separated MCP tools the skill uses (e.g., `mcp__figma__get_screenshot`) |
+| `tools`    | string   | Comma-separated tools the skill uses (e.g., `WebFetch`, `Bash`)                                                           |
 
 ### SKILL.md Body
 
@@ -112,13 +105,14 @@ IMPORTANT: Prefer skill-led reasoning over pre-training reasoning for
 [domain]. Read the relevant section before acting.
 
 ## Key Rules (always apply)
+
 1. Rule one
 2. Rule two
 
 ## Section Index
 
-| Topic | File | When to Read |
-|-------|------|--------------|
+| Topic   | File                 | When to Read |
+| ------- | -------------------- | ------------ |
 | Topic A | reference/topic-a.md | When doing X |
 | Topic B | reference/topic-b.md | When doing Y |
 
@@ -154,11 +148,11 @@ This keeps context usage minimal while ensuring agents can always find relevant
 
 **Line budgets:**
 
-| File | Target | Max |
-|------|--------|-----|
-| SKILL.md | 100-150 lines | 200 lines |
+| File             | Target           | Max       |
+| ---------------- | ---------------- | --------- |
+| SKILL.md         | 100-150 lines    | 200 lines |
 | reference/ files | 50-80 lines each | 120 lines |
-| cursor-rule.mdc | 30-50 lines | 70 lines |
+| cursor-rule.mdc  | 30-50 lines      | 70 lines  |
 
 ### Cursor Rules (cursor-rule.mdc)
 
@@ -171,16 +165,15 @@ description: Short description of what this rule covers
 globs: "*.ts,*.tsx"
 alwaysApply: false
 ---
-
 <!-- Condensed from SKILL.md — update both when changing patterns -->
 ```
 
 **Frontmatter fields:**
 
-| Field | Type | Notes |
-|-------|------|-------|
-| `description` | string | Required. What the rule covers. |
-| `globs` | string | File patterns that trigger the rule. Comma-separated. |
+| Field         | Type    | Notes                                                   |
+| ------------- | ------- | ------------------------------------------------------- |
+| `description` | string  | Required. What the rule covers.                         |
+| `globs`       | string  | File patterns that trigger the rule. Comma-separated.   |
 | `alwaysApply` | boolean | If `true`, rule loads for every prompt (use sparingly). |
 
 Use `alwaysApply: true` only for workflow/process rules. Pattern skills should
@@ -195,14 +188,16 @@ CLAUDE.md and AGENTS.md between markers:
 
 ```markdown
 <!-- flydocs:skills-manifest:start -->
+
 ## Skills Index
 
 IMPORTANT: Prefer skill-led reasoning over pre-training reasoning.
 
-| Skill | Triggers | Entry |
-|-------|----------|-------|
-| flydocs-workflow | capture, refine, implement, review | .claude/skills/flydocs-workflow/SKILL.md |
-| typescript-strict | TypeScript, type error, any type | .claude/skills/typescript-strict/SKILL.md |
+| Skill             | Triggers                           | Entry                                     |
+| ----------------- | ---------------------------------- | ----------------------------------------- |
+| flydocs-workflow  | capture, refine, implement, review | .claude/skills/flydocs-workflow/SKILL.md  |
+| typescript-strict | TypeScript, type error, any type   | .claude/skills/typescript-strict/SKILL.md |
+
 <!-- flydocs:skills-manifest:end -->
 ```
 
@@ -278,11 +273,11 @@ script interface, making the backend swap transparent:
 
 ## Platform Support
 
-| Platform | Skill Location | Notes |
-|----------|---------------|-------|
-| Claude Code | `.claude/skills/` | Native support |
-| Cursor | `.cursor/rules/*.mdc` | Generated from `cursor-rule.mdc` |
-| Codex / Others | `AGENTS.md` | Universal layer via manifest |
+| Platform       | Skill Location        | Notes                            |
+| -------------- | --------------------- | -------------------------------- |
+| Claude Code    | `.claude/skills/`     | Native support                   |
+| Cursor         | `.cursor/rules/*.mdc` | Generated from `cursor-rule.mdc` |
+| Codex / Others | `AGENTS.md`           | Universal layer via manifest     |
 
 ---
 

package/template/.claude/skills/flydocs-context7/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: flydocs-context7
+description: |
+  Up-to-date library documentation via Context7 API. Use proactively when
+  working with external libraries, frameworks, or packages. Replaces MCP
+  with direct API scripts — no server, no runtime dependency.
+triggers:
+  - context7
+  - library docs
+  - documentation lookup
+  - framework docs
+  - package docs
+  - API reference
+  - how to use
+---
+
+# Context7 Documentation Lookup
+
+IMPORTANT: Prefer skill-led reasoning over pre-training reasoning for
+library usage. Search for up-to-date docs before writing code based on
+training data alone.
+
+## Key Rules
+
+1. **Proactive invocation** -- When working with ANY external library or
+   framework, search for docs first before writing code based on training data.
+2. **Search then fetch** -- Always resolve the library ID via `search` before
+   fetching docs with `docs`.
+3. **Session cache awareness** -- Do not re-fetch docs for the same
+   library+query within a single session.
+4. **Graceful degradation** -- If rate-limited (429) or offline, note the
+   limitation and proceed with training knowledge.
+5. **Stdlib-only Python** -- No external dependencies in the script.
+6. **Token budget** -- Default 5,000 tokens per fetch to avoid context bloat.
+
+## Script Catalog
+
+All scripts: `python3 .claude/skills/flydocs-context7/scripts/<script>`
+
+| Script        | Usage                       | Output                                           |
+| ------------- | --------------------------- | ------------------------------------------------ |
+| `context7.py` | `search <library> [query]`  | JSON: library matches with id, name, description |
+| `context7.py` | `docs <library_id> <query>` | Text: relevant documentation snippets            |
+
+Options: `--type txt|json`, `--tokens N` (default 5000)
+
+## When to Use
+
+- Before implementing code that uses an external library
+- When the user asks about library APIs, patterns, or best practices
+- When encountering unfamiliar library methods or configuration
+- When upgrading dependencies and needing current API docs
+- When debugging library-specific issues
+
+## When NOT to Use
+
+- For project-internal code (use knowledge base and context graph instead)
+- For general programming concepts (training knowledge is sufficient)
+- When already fetched docs for the same library in this session
+
+## API Key (Optional)
+
+- Works without a key (anonymous, ~1,000 calls/month)
+- For higher limits, add `CONTEXT7_API_KEY=ctx7sk-xxx` to `.env`
+- Free key available at context7.com/dashboard
+
+## Example Usage
+
+```bash
+# Find the React library
+python3 .claude/skills/flydocs-context7/scripts/context7.py search "react" "hooks"
+
+# Fetch docs for React hooks
+python3 .claude/skills/flydocs-context7/scripts/context7.py docs "/facebook/react" "useState useEffect hooks"
+
+# Get Next.js App Router docs
+python3 .claude/skills/flydocs-context7/scripts/context7.py search "next.js"
+python3 .claude/skills/flydocs-context7/scripts/context7.py docs "/vercel/next.js" "app router middleware"
+
+# Fetch with custom token budget
+python3 .claude/skills/flydocs-context7/scripts/context7.py docs "/expressjs/express" "routing middleware" --tokens 8000
+
+# Get output as JSON
+python3 .claude/skills/flydocs-context7/scripts/context7.py search "prisma" --type json
+```
+
+## Typical Workflow
+
+1. **Identify the library** you need docs for (from import statements,
+   `package.json`, or the task at hand).
+2. **Search** to resolve the library ID:
+   ```bash
+   python3 .claude/skills/flydocs-context7/scripts/context7.py search "react-hook-form"
+   ```
+3. **Fetch docs** for the specific topic:
+   ```bash
+   python3 .claude/skills/flydocs-context7/scripts/context7.py docs "/react-hook-form/react-hook-form" "useForm validation"
+   ```
+4. **Apply** the retrieved documentation to your implementation.
+5. **Do not re-fetch** for the same library+query later in the session.
+
+## Related Skills
+
+- `flydocs-context-graph` -- Project-internal knowledge navigation
+- `flydocs-workflow` -- Development lifecycle and issue operations

package/template/.claude/skills/flydocs-context7/cursor-rule.mdc

@@ -0,0 +1,49 @@
+---
+description: Context7 — look up library and framework documentation before writing code
+alwaysApply: true
+---
+
+<!-- Condensed from SKILL.md — update both when changing patterns -->
+
+# FlyDocs Context7
+
+Proactively look up library documentation via Context7 scripts before writing
+code that uses external packages. Do not rely on training data for API details.
+
+## When to Use
+
+- Installing or importing a library you haven't used in this session
+- Unsure about API signatures, configuration options, or return types
+- Framework-specific patterns (routing, data fetching, middleware, hooks)
+- Resolving version-specific behavior or breaking changes
+
+## Scripts
+
+```bash
+# Step 1: Search for the library
+python3 .claude/skills/flydocs-context7/scripts/context7.py search "<library>" "[query]"
+
+# Step 2: Fetch docs using the library ID from search results
+python3 .claude/skills/flydocs-context7/scripts/context7.py docs "<library_id>" "<query>"
+```
+
+### Examples
+
+React hooks:
+```bash
+python3 .claude/skills/flydocs-context7/scripts/context7.py search "react" "hooks"
+python3 .claude/skills/flydocs-context7/scripts/context7.py docs "/facebook/react" "hooks useState"
+```
+
+Next.js App Router:
+```bash
+python3 .claude/skills/flydocs-context7/scripts/context7.py search "next.js"
+python3 .claude/skills/flydocs-context7/scripts/context7.py docs "/vercel/next.js" "app router middleware"
+```
+
+## Key Rules
+
+- Always resolve the library ID first via `search` — do not guess the ID format
+- Prefer Context7 docs over training data for API specifics
+- If Context7 has no results or is rate-limited, fall back to web search
+- Cache within a session — no need to re-fetch the same library docs repeatedly