@flydocs/cli 0.5.0-beta.6 → 0.5.0-beta.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flydocs/cli",
-  "version": "0.5.0-beta.6",
+  "version": "0.5.0-beta.8",
   "type": "module",
   "description": "FlyDocs AI CLI — install, setup, and manage FlyDocs projects",
   "bin": {

package/template/.claude/CLAUDE.md

@@ -116,6 +116,7 @@ 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-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     |

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

@@ -177,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.
 
@@ -191,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.**
 
@@ -203,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
 ```

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