@brainfish-ai/devdoc 0.1.32 → 0.1.34

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

@@ -1,102 +1,557 @@
 ---
 name: bootstrap-docs
-description: Analyze repository and generate complete initial documentation structure
+description: Analyze repository and generate documentation. Creates context memory for consistent AI assistance.
 ---
 
 ## Instructions
 
 When bootstrapping documentation from a repository:
 
-### Step 1: Analyze Repository Structure
+### Step 1: Check Context Memory
 
-Scan and identify:
-- `README.md` - Project overview, installation, usage
-- `package.json` / `Cargo.toml` / `pyproject.toml` - Dependencies, scripts, metadata
-- `src/` or `lib/` - Main source code structure
-- `api/` or `routes/` - API endpoints (REST, GraphQL)
-- `components/` - UI components (React, Vue, etc.)
-- `docs/` - Existing documentation
-- `.env.example` - Environment variables
-- `docker-compose.yml` / `Dockerfile` - Deployment info
-- `openapi.json` / `swagger.yaml` - API specifications
-- `schema.graphql` - GraphQL schemas
+**First, check if `.devdoc/context.json` exists:**
 
-### Step 2: Generate Documentation Structure
+**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)
 
-Create the following based on what's found:
+**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
+- Source code is likely in `../` (parent directory)
+
+**If `package.json` and `src/` exist:**
+- You're at repo root
+- Create docs in `./docs/` subfolder
+
+**If neither matches:**
+- Ask user for the source code path
+
+#### 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)"
+
+**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
+{
+  "$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": []
+  }
+}
+```
+
+Also copy template files to `.devdoc/templates/` if they don't exist.
+
+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}
+
+This context will be used for consistent documentation generation."
+
+### 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
+
+**For GraphQL (Import option):**
+1. Copy schema to `api-reference/schema.graphql`
+2. Validate the schema
+3. Extract types/queries/mutations for context
+
+**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",
+  "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: "Configured API Reference with {spec_type} from {path}"
+
+### Step 5: Generate Documentation
+
+**Read context from `.devdoc/context.json` before generating.**
+
+**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`
+
+---
+
+## docType: "internal"
+
+For internal team documentation, create:
 
 ```
 docs/
-├── docs.json              # Navigation config
-├── index.mdx              # Homepage (from README)
-├── quickstart.mdx         # Getting started guide
-├── installation.mdx       # Installation instructions
-├── configuration.mdx      # Environment/config setup
+├── .devdoc/
+│   ├── context.json
+│   └── templates/
+├── docs.json
+├── index.mdx              # Project overview
+├── getting-started/
+│   ├── setup.mdx          # Dev environment setup
+│   ├── prerequisites.mdx  # Required tools/versions
+│   └── first-contribution.mdx
+├── architecture/
+│   ├── overview.mdx       # System architecture
+│   ├── folder-structure.mdx
+│   └── decisions.mdx      # ADRs, design decisions
+├── development/
+│   ├── workflow.mdx       # Git workflow, PR process
+│   ├── testing.mdx        # How to run/write tests
+│   ├── debugging.mdx      # Common issues, debugging tips
+│   └── deployment.mdx     # How to deploy
+├── api/                   # Internal API docs (if applicable)
+│   └── ...
+└── contributing.mdx       # Contribution guidelines
+```
+
+**Content focus:**
+- How to set up local development
+- Codebase architecture and patterns
+- Internal APIs and services
+- Debugging and troubleshooting
+- Team conventions and standards
+
+**Voice:** Technical, direct, assumes familiarity with codebase
+
+---
+
+## docType: "api"
+
+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
+├── authentication.mdx     # Auth setup (API keys, OAuth)
 ├── guides/
-│   ├── overview.mdx       # Architecture overview
-│   └── {feature}.mdx      # Feature-specific guides
+│   ├── overview.mdx       # Concepts overview
+│   └── {use-case}.mdx     # Common use case tutorials
 ├── api-reference/
-│   ├── introduction.mdx   # API overview
-│   ├── authentication.mdx # Auth guide
-│   └── openapi.json       # (if found/generated)
-├── components/            # (if UI library)
-│   └── {component}.mdx
-└── deployment.mdx         # Deployment guide
+│   ├── introduction.mdx   # API overview, base URL, versioning
+│   ├── authentication.mdx # Auth details
+│   ├── errors.mdx         # Error codes and handling
+│   ├── openapi.json       # Full API spec (if imported)
+│   └── schema.graphql     # GraphQL schema (if imported)
+├── sdks/                  # If SDKs exist
+│   ├── javascript.mdx
+│   ├── python.mdx
+│   └── ...
+├── webhooks.mdx           # If webhooks exist
+└── changelog.mdx          # API changelog
+```
+
+**Content focus:**
+- Quick time-to-first-API-call
+- Authentication and authorization
+- API reference with examples
+- SDKs and client libraries
+- Error handling and troubleshooting
+- Rate limits and best practices
+
+**Voice:** Professional, helpful, code-focused
+
+---
+
+## docType: "product"
+
+For end users of your product, create:
+
 ```
+docs/
+├── .devdoc/
+│   ├── context.json
+│   └── templates/
+├── docs.json
+├── index.mdx              # Product overview
+├── getting-started/
+│   ├── quickstart.mdx     # First steps
+│   ├── account-setup.mdx  # Account creation, onboarding
+│   └── key-concepts.mdx   # Core concepts explained
+├── features/
+│   ├── {feature-1}.mdx    # Feature guides
+│   ├── {feature-2}.mdx
+│   └── ...
+├── tutorials/
+│   ├── {workflow-1}.mdx   # Step-by-step tutorials
+│   └── ...
+├── integrations/          # If integrations exist
+│   └── ...
+├── troubleshooting/
+│   ├── common-issues.mdx
+│   └── faq.mdx
+└── release-notes.mdx      # What's new
+```
+
+**Content focus:**
+- Non-technical language (minimal code)
+- Screenshots and visual guides
+- Step-by-step tutorials
+- Use case focused
+- FAQs and troubleshooting
+- Feature explanations
 
-### Step 3: Content Generation
+**Voice:** Friendly, supportive, non-technical
 
-For each page, generate:
-1. Frontmatter with title and description
-2. Clear introduction explaining the topic
-3. Code examples extracted from source
-4. Links to related documentation
+---
 
-### Step 4: Generate docs.json
+## docs.json Templates (with docType)
 
-Create navigation structure:
+### Internal Docs
 ```json
 {
-  "name": "{Project Name from package.json}",
+  "name": "{Project Name}",
+  "docType": "internal",
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "Documentation",
+        "groups": [
+          { "group": "Getting Started", "pages": ["index", "getting-started/setup", "getting-started/prerequisites"] },
+          { "group": "Architecture", "pages": ["architecture/overview", "architecture/folder-structure"] },
+          { "group": "Development", "pages": ["development/workflow", "development/testing", "development/deployment"] },
+          { "group": "Contributing", "pages": ["contributing"] }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Customer API Docs (with OpenAPI)
+```json
+{
+  "name": "{Product Name}",
+  "docType": "api",
   "navigation": {
     "tabs": [
       {
         "tab": "Guides",
-        "type": "docs",
         "groups": [
-          {
-            "group": "Getting Started",
-            "pages": ["index", "quickstart", "installation"]
-          },
-          {
-            "group": "Guides",
-            "pages": ["guides/overview"]
-          }
+          { "group": "Getting Started", "pages": ["index", "quickstart", "authentication"] },
+          { "group": "Guides", "pages": ["guides/overview"] }
         ]
+      },
+      {
+        "tab": "API Reference",
+        "type": "openapi",
+        "spec": "api-reference/openapi.json"
       }
     ]
   }
 }
 ```
 
-## What to Extract from Source Code
+### 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"
+      }
+    ]
+  }
+}
+```
 
-| Source | Documentation Generated |
-|--------|------------------------|
-| README.md | Homepage content, project overview |
-| package.json scripts | CLI commands, development workflow |
-| Exported functions | API reference pages |
-| React components | Component documentation with props |
-| API routes | Endpoint reference |
-| OpenAPI spec | Full API documentation |
-| GraphQL schema | GraphQL type documentation |
-| Config files | Configuration reference |
-| Tests | Usage examples |
+### Product Docs
+```json
+{
+  "name": "{Product Name}",
+  "docType": "product",
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "Documentation",
+        "groups": [
+          { "group": "Getting Started", "pages": ["index", "getting-started/quickstart", "getting-started/key-concepts"] },
+          { "group": "Features", "pages": ["features/..."] },
+          { "group": "Tutorials", "pages": ["tutorials/..."] },
+          { "group": "Help", "pages": ["troubleshooting/common-issues", "troubleshooting/faq"] }
+        ]
+      }
+    ]
+  }
+}
+```
 
-## Output Quality Guidelines
+## Quality Guidelines
 
-- Extract real code examples, don't fabricate
-- Preserve existing documentation where found
-- Note areas that need human review with TODOs
-- Generate SEO-friendly descriptions
-- Include installation commands from package manager
+- 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