@brainfish-ai/devdoc 0.1.33 → 0.1.35

package/ai-agents/.claude/skills/blame-doc/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: blame-doc
+description: Analyze documentation for duplicates, outdated content, and discrepancies with codebase
+---
+
+## Instructions
+
+Perform a deep analysis of documentation quality, finding issues that need attention.
+
+### Step 0: Read Context
+
+**Read `.devdoc/context.json` if it exists** for product info and terminology.
+
+**Read `docs.json`** to understand documentation structure.
+
+### Step 1: Scan Codebase
+
+Analyze the source code to understand:
+- Exported functions, classes, types
+- API endpoints and routes
+- Configuration options
+- Feature flags and capabilities
+
+### Step 2: Analyze Documentation
+
+Scan all MDX files for:
+- Topics covered
+- Code examples used
+- Features documented
+- API references
+
+### Step 3: Generate Blame Report
+
+```
+Documentation Blame Report
+==========================
+
+Generated: [date]
+Files analyzed: X docs, Y source files
+
+## 🔴 Critical Issues
+
+### Duplicate Content (count)
+
+Content that appears in multiple places, causing maintenance burden:
+
+| Topic | Files | Recommendation |
+|-------|-------|----------------|
+| Authentication setup | auth.mdx, quickstart.mdx, api/overview.mdx | Consolidate to auth.mdx, link from others |
+| Error handling | errors.mdx, troubleshooting.mdx | Merge into single page |
+
+**Details:**
+- `auth.mdx:15-45` and `quickstart.mdx:80-110` contain nearly identical OAuth setup instructions
+- `errors.mdx` and `troubleshooting.mdx` both list the same error codes
+
+### Outdated Documentation (count)
+
+Docs that don't match current codebase:
+
+| File | Issue | Current State |
+|------|-------|---------------|
+| api/users.mdx | Wrong signature | `getUser(id)` is now `getUser(id, options)` |
+| config.mdx | Missing options | `timeout` and `retries` not documented |
+| quickstart.mdx | Old version | References v1.x, current is v2.x |
+
+**Details:**
+- `api/users.mdx:23` shows `getUser(id: string)` but code has `getUser(id: string, options?: UserOptions)`
+- `config.mdx` missing 3 new configuration options added in v2.0
+
+### Code-Doc Discrepancies (count)
+
+Mismatches between documented and actual behavior:
+
+| File | Documented | Actual |
+|------|------------|--------|
+| api/auth.mdx | Returns `{ token }` | Returns `{ token, expiresAt }` |
+| guides/setup.mdx | Requires Node 14+ | package.json requires Node 18+ |
+| api/errors.mdx | Error code 401 | Code throws 403 for this case |
+
+## 🟡 Warnings
+
+### Undocumented Features (count)
+
+Code exists but no documentation:
+
+- `src/utils/retry.ts` - Retry utility with backoff (exported, no docs)
+- `src/api/webhooks.ts` - Webhook handlers (3 endpoints, no docs)
+- `src/config/advanced.ts` - Advanced options (12 options, not in config.mdx)
+
+### Stale Examples (count)
+
+Code examples that may not work:
+
+| File | Line | Issue |
+|------|------|-------|
+| quickstart.mdx | 45 | Uses deprecated `init()`, should be `initialize()` |
+| api/fetch.mdx | 23 | Import path changed from `pkg` to `pkg/client` |
+
+### Inconsistent Terminology
+
+Terms used differently across docs:
+
+| Term | Variations Found | Recommended |
+|------|------------------|-------------|
+| API key | "api key", "API Key", "apiKey", "api-key" | "API key" |
+| endpoint | "endpoint", "route", "URL", "path" | "endpoint" |
+
+## 🟢 Good Practices Found
+
+✓ All public exports have corresponding docs
+✓ Code examples have language tags
+✓ Consistent use of components (Note, Warning, etc.)
+
+## Recommendations
+
+### High Priority
+1. **Consolidate auth docs** - Merge duplicate OAuth content into single source
+2. **Update API signatures** - 5 files have outdated function signatures
+3. **Document webhooks** - Major feature with zero documentation
+
+### Medium Priority
+4. **Version bump** - Update all version references to v2.x
+5. **Standardize terminology** - Create glossary in context.json
+
+### Low Priority
+6. **Add missing options** - Document 12 config options
+7. **Fix stale examples** - Update deprecated imports
+```
+
+## Analysis Techniques
+
+### Finding Duplicates
+
+Look for:
+1. **Exact matches** - Same paragraphs in multiple files
+2. **Similar code blocks** - Nearly identical examples
+3. **Repeated explanations** - Same concept explained multiple times
+4. **Copy-paste patterns** - Setup instructions repeated
+
+### Finding Outdated Content
+
+Compare:
+1. **Function signatures** - Params, return types
+2. **Import paths** - Package structure changes
+3. **Version numbers** - In code vs docs
+4. **Default values** - Changed defaults
+5. **Error messages** - Updated error text
+
+### Finding Discrepancies
+
+Check:
+1. **Return types** - What docs say vs code returns
+2. **Required fields** - Optional vs required mismatches
+3. **Behavior descriptions** - Edge cases documented incorrectly
+4. **Prerequisites** - Wrong versions, missing dependencies
+
+## Output Actions
+
+After generating report, suggest:
+
+"Found X issues. Would you like me to:
+1. **Fix outdated docs** - Update signatures and versions
+2. **Consolidate duplicates** - Merge redundant content
+3. **Create missing docs** - Stub pages for undocumented features
+4. **Update terminology** - Standardize across all files"
+
+## Integration with Other Skills
+
+- After blame analysis → `/update-doc` to fix issues
+- For new undocumented features → `/create-doc`
+- When ready to save → `/commit-doc`

package/ai-agents/.claude/skills/bootstrap-docs/SKILL.md

@@ -1,15 +1,27 @@
 ---
 name: bootstrap-docs
-description: Analyze repository and generate documentation. Reads docType from docs.json config, or asks if not set.
+description: Analyze repository and generate documentation. Creates context memory for consistent AI assistance.
 ---
 
 ## Instructions
 
 When bootstrapping documentation from a repository:
 
-### Step 1: Detect Project Structure
+### Step 1: Check Context Memory
 
-Determine where you are:
+**First, check if `.devdoc/context.json` exists:**
+
+**If context.json exists and is populated:**
+- Read the context file
+- Tell user: "Found existing product context. Using saved configuration."
+- Skip to Step 5 (Generate Documentation)
+
+**If context.json is empty or doesn't exist:**
+- Proceed to Step 2 (Discovery Flow)
+
+### Step 2: Discovery Flow (Context Creation)
+
+#### 2a. Detect Project Structure
 
 **If `docs.json` exists in current directory:**
 - You're in a DevDoc docs folder
@@ -22,55 +34,296 @@ Determine where you are:
 **If neither matches:**
 - Ask user for the source code path
 
-### Step 2: Check for docType Configuration
+#### 2b. Scan for Existing API Specs
+
+**Search for OpenAPI specs:**
+```
+openapi.json, openapi.yaml, openapi.yml
+swagger.json, swagger.yaml, swagger.yml
+api-spec.json, api-spec.yaml
+**/openapi.*, **/swagger.*
+```
+
+**Search for GraphQL schemas:**
+```
+schema.graphql, schema.gql
+*.graphql, *.gql
+**/schema.graphql
+```
+
+**If found, store the paths for later use.**
+
+#### 2c. Auto-Discover Information
+
+Scan the repository and extract:
+
+```
+From README.md:
+- Product name
+- Description
+- Key features
+
+From package.json / pyproject.toml / Cargo.toml:
+- Primary language
+- Framework (from dependencies)
+- Project type (library, cli, api, etc.)
+
+From OpenAPI spec (if exists):
+- API style: REST
+- Base URL
+- Authentication type
+- Endpoints count
+- Common patterns
+
+From GraphQL schema (if exists):
+- API style: GraphQL
+- Types count
+- Queries/Mutations
+
+From source code structure:
+- Key directories
+- Naming conventions
+```
+
+#### 2d. Ask Key Questions
+
+After auto-discovery, ask the user to confirm/provide:
+
+**Question 1: Documentation Type**
+"What type of documentation are you creating?
+1. **internal** - For your team: setup guides, architecture, contribution guidelines
+2. **api** - For developers using your product: API reference, SDKs, integration guides  
+3. **product** - For end users: feature guides, tutorials, FAQs"
+
+---
+
+**Question 2: Import Existing API Spec (if detected)**
+
+**If OpenAPI spec found:**
+"I found an OpenAPI specification at `{path}`:
+- {endpoint_count} endpoints
+- Base URL: {base_url}
+- Auth: {auth_type}
+
+Would you like me to:
+1. **Import it** - Copy to `api-reference/openapi.json` and generate API Reference tab
+2. **Reference it** - Point docs.json to existing location: `{path}`
+3. **Skip** - Don't include API reference (I'll create manual docs instead)"
+
+**If GraphQL schema found:**
+"I found a GraphQL schema at `{path}`:
+- {types_count} types
+- {queries_count} queries
+- {mutations_count} mutations
+
+Would you like me to:
+1. **Import it** - Copy to `api-reference/schema.graphql` and generate GraphQL tab
+2. **Reference it** - Point docs.json to existing location: `{path}`
+3. **Skip** - Don't include GraphQL playground"
+
+**If multiple specs found:**
+"I found multiple API specifications:
+- OpenAPI: `{openapi_path}`
+- GraphQL: `{graphql_path}`
+
+Which would you like to use for the API Reference?
+1. **OpenAPI (REST)** - Interactive REST API playground
+2. **GraphQL** - GraphQL playground with schema explorer
+3. **Both** - Create separate tabs for each
+4. **Skip** - Manual documentation only"
+
+---
+
+**Question 3: Target Audience**
+"Who is your primary audience?
+(e.g., 'Backend developers integrating our payment API', 'Internal engineering team', 'Non-technical business users')"
+
+**Question 4: Terminology (optional)**
+"Any specific terminology I should know? For example:
+- Brand names with specific capitalization
+- Terms to avoid or prefer
+- Domain-specific vocabulary
+
+(Press Enter to skip)"
 
-**Read `docs.json` and check for `docType` field:**
+**Question 5: Code Examples**
+"What language should I use for code examples?
+(e.g., TypeScript, Python, curl)"
+
+#### 2e. Create Context Memory
+
+Create `.devdoc/` folder and `context.json` with discovered + user info:
 
 ```json
 {
-  "name": "Project Name",
-  "docType": "api",  // "internal" | "api" | "product"
-  ...
+  "$schema": "https://devdoc.sh/schemas/context.json",
+  "version": "1.0",
+  "lastUpdated": "2026-01-24T10:30:00Z",
+  "product": {
+    "name": "[from README/package.json]",
+    "description": "[from README]",
+    "type": "[api/sdk/platform/cli/library]",
+    "domain": "[inferred or asked]",
+    "targetAudience": "[from Question 3]",
+    "keyFeatures": ["[from README]"]
+  },
+  "terminology": {
+    "glossary": {},
+    "avoidTerms": [],
+    "brandNames": {}
+  },
+  "api": {
+    "style": "[REST/GraphQL/etc if detected]",
+    "specPath": "[path to imported/referenced spec]",
+    "baseUrl": "[from OpenAPI if found]",
+    "authentication": {
+      "type": "[from OpenAPI if found]",
+      "headerName": "",
+      "description": ""
+    },
+    "conventions": {},
+    "commonPatterns": []
+  },
+  "codebase": {
+    "language": "[from package.json]",
+    "framework": "[from dependencies]",
+    "sourceLocation": "../"
+  },
+  "documentation": {
+    "voice": "[based on docType]",
+    "perspective": "second_person",
+    "codeExamples": {
+      "primaryLanguage": "[from Question 5]",
+      "additionalLanguages": []
+    },
+    "templates": {
+      "guide": ".devdoc/templates/guide.md",
+      "apiReference": ".devdoc/templates/api-reference.md",
+      "tutorial": ".devdoc/templates/tutorial.md",
+      "quickstart": ".devdoc/templates/quickstart.md",
+      "troubleshooting": ".devdoc/templates/troubleshooting.md"
+    }
+  },
+  "learned": {
+    "insights": [],
+    "corrections": []
+  }
 }
 ```
 
-**If `docType` is set:**
-- Use that value automatically
-- Tell user: "Using docType: {type} from docs.json"
+Also copy template files to `.devdoc/templates/` if they don't exist.
 
-**If `docType` is NOT set, ask the user:**
+Tell user: 
+"Created product context in `.devdoc/context.json`
+- Product: {name}
+- Type: {docType}
+- API: {REST/GraphQL} (imported from {spec_path})
+- Audience: {targetAudience}
+- Code examples: {primaryLanguage}
 
-"What type of documentation are you creating?
+This context will be used for consistent documentation generation."
 
-1. **internal** - For your team: setup guides, architecture, contribution guidelines
-2. **api** - For developers using your product: API reference, SDKs, integration guides
-3. **product** - For end users: feature guides, tutorials, FAQs"
+### Step 3: Import API Spec (if selected)
+
+**For OpenAPI (Import option):**
+1. Copy spec to `api-reference/openapi.json` (or `.yaml`)
+2. Validate the spec is valid OpenAPI 3.x
+3. Extract key info for context.json
+
+**For OpenAPI (Reference option):**
+1. Note the relative path for docs.json
+2. Extract key info for context.json
 
-**IMPORTANT: After user answers, immediately update docs.json:**
+**For GraphQL (Import option):**
+1. Copy schema to `api-reference/schema.graphql`
+2. Validate the schema
+3. Extract types/queries/mutations for context
 
-Add the `docType` field to docs.json so it's saved for future use:
+**For GraphQL (Reference option):**
+1. Note the relative path for docs.json
+2. Extract schema info for context
+
+### Step 4: Update docs.json with API Reference
+
+**Read existing `docs.json` or create new one.**
+
+Add the `docType` field and API reference tab:
+
+**For OpenAPI:**
+```json
+{
+  "name": "Project Name",
+  "docType": "api",
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "Guides",
+        "groups": [...]
+      },
+      {
+        "tab": "API Reference",
+        "type": "openapi",
+        "spec": "api-reference/openapi.json"
+      }
+    ]
+  }
+}
+```
 
+**For GraphQL:**
 ```json
 {
   "name": "Project Name",
-  "docType": "api",  // Save their choice here
-  "navigation": { ... }
+  "docType": "api",
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "Guides",
+        "groups": [...]
+      },
+      {
+        "tab": "GraphQL API",
+        "type": "graphql",
+        "schema": "api-reference/schema.graphql",
+        "endpoint": "https://api.example.com/graphql"
+      }
+    ]
+  }
+}
+```
+
+**For Both:**
+```json
+{
+  "navigation": {
+    "tabs": [
+      { "tab": "Guides", "groups": [...] },
+      { "tab": "REST API", "type": "openapi", "spec": "api-reference/openapi.json" },
+      { "tab": "GraphQL API", "type": "graphql", "schema": "api-reference/schema.graphql" }
+    ]
+  }
 }
 ```
 
-Tell user: "Saved docType: {type} to docs.json - you won't be asked again."
+Tell user: "Configured API Reference with {spec_type} from {path}"
 
-### Step 3: Analyze Repository
+### Step 5: Generate Documentation
 
-Scan the source code for:
-- `README.md` - Project overview
-- `package.json` / `Cargo.toml` / `pyproject.toml` - Dependencies, metadata
-- `src/` or `lib/` - Source code structure
-- `api/` or `routes/` - API endpoints
-- `openapi.json` / `swagger.yaml` - API specs
-- `schema.graphql` - GraphQL schemas
+**Read context from `.devdoc/context.json` before generating.**
 
-### Step 4: Generate Based on docType
+**Read the appropriate template** from `.devdoc/templates/` for each page type:
+- For guides: read `.devdoc/templates/guide.md`
+- For API reference: read `.devdoc/templates/api-reference.md`
+- For quickstart: read `.devdoc/templates/quickstart.md`
+- For tutorials: read `.devdoc/templates/tutorial.md`
+
+**Apply context throughout:**
+- Use correct product name from `product.name`
+- Use terminology from `terminology.glossary`
+- Avoid terms from `terminology.avoidTerms`
+- Use code language from `documentation.codeExamples.primaryLanguage`
+- Match voice from `documentation.voice`
+- Reference API spec path from `api.specPath`
 
 ---
 
@@ -80,6 +333,9 @@ For internal team documentation, create:
 
 ```
 docs/
+├── .devdoc/
+│   ├── context.json
+│   └── templates/
 ├── docs.json
 ├── index.mdx              # Project overview
 ├── getting-started/
@@ -107,6 +363,8 @@ docs/
 - Debugging and troubleshooting
 - Team conventions and standards
 
+**Voice:** Technical, direct, assumes familiarity with codebase
+
 ---
 
 ## docType: "api"
@@ -115,6 +373,9 @@ For external developers using your API/SDK, create:
 
 ```
 docs/
+├── .devdoc/
+│   ├── context.json
+│   └── templates/
 ├── docs.json
 ├── index.mdx              # Product intro, value prop
 ├── quickstart.mdx         # 5-minute getting started
@@ -126,7 +387,8 @@ docs/
 │   ├── introduction.mdx   # API overview, base URL, versioning
 │   ├── authentication.mdx # Auth details
 │   ├── errors.mdx         # Error codes and handling
-│   └── openapi.json       # Full API spec
+│   ├── openapi.json       # Full API spec (if imported)
+│   └── schema.graphql     # GraphQL schema (if imported)
 ├── sdks/                  # If SDKs exist
 │   ├── javascript.mdx
 │   ├── python.mdx
@@ -143,6 +405,8 @@ docs/
 - Error handling and troubleshooting
 - Rate limits and best practices
 
+**Voice:** Professional, helpful, code-focused
+
 ---
 
 ## docType: "product"
@@ -151,6 +415,9 @@ For end users of your product, create:
 
 ```
 docs/
+├── .devdoc/
+│   ├── context.json
+│   └── templates/
 ├── docs.json
 ├── index.mdx              # Product overview
 ├── getting-started/
@@ -180,6 +447,8 @@ docs/
 - FAQs and troubleshooting
 - Feature explanations
 
+**Voice:** Friendly, supportive, non-technical
+
 ---
 
 ## docs.json Templates (with docType)
@@ -205,7 +474,7 @@ docs/
 }
 ```
 
-### Customer API Docs
+### Customer API Docs (with OpenAPI)
 ```json
 {
   "name": "{Product Name}",
@@ -229,6 +498,31 @@ docs/
 }
 ```
 
+### Customer API Docs (with GraphQL)
+```json
+{
+  "name": "{Product Name}",
+  "docType": "api",
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "Guides",
+        "groups": [
+          { "group": "Getting Started", "pages": ["index", "quickstart", "authentication"] },
+          { "group": "Guides", "pages": ["guides/overview"] }
+        ]
+      },
+      {
+        "tab": "GraphQL API",
+        "type": "graphql",
+        "schema": "api-reference/schema.graphql",
+        "endpoint": "https://api.example.com/graphql"
+      }
+    ]
+  }
+}
+```
+
 ### Product Docs
 ```json
 {
@@ -252,8 +546,12 @@ docs/
 
 ## Quality Guidelines
 
-- Extract real code examples, don't fabricate
-- Match tone to audience (technical vs non-technical)
+- Extract real code examples from source, don't fabricate
+- Match tone to audience based on docType
 - Add TODO markers for sections needing human review
 - Include relevant screenshots for product docs
 - Test all code examples work
+- Always use terminology from context.json
+- Update context.json if you learn new information
+- **Import existing API specs** rather than creating manual docs
+- **Validate specs** before importing