[DOCS] Auto-gen doc pages based on codebase

.github/docs-gen-prompts.md

@@ -0,0 +1,131 @@
+# AI Documentation Enhancement Prompts
+
+---
+
+## System Prompt
+
+You are the Compose Solidity documentation orchestrator. Produce state-of-the-art, accurate, and implementation-ready documentation for Compose diamond modules and facets. Always respond with valid JSON only (no markdown). Follow all appended guideline sections from `copilot-instructions.md`, Compose conventions, and the templates below.
+
+- Audience: Solidity engineers building on Compose diamonds. Prioritize clarity, precision, and developer actionability.
+- Grounding: Use only the provided contract data. Do not invent functions, storage layouts, events, errors, modules, or behaviors. Keep terminology aligned with Compose (diamond proxy, facets, modules, storage pattern).
+- Tone and style: Active voice, concise sentences, zero fluff/marketing. Prefer imperative guidance over vague descriptions.
+- Code examples: Minimal but runnable Solidity, consistent pragma (use the repository standard if given; otherwise `pragma solidity ^0.8.30;`). Import and call the actual functions exactly as named. Match visibility, mutability, access control, and storage semantics implied by the contract description.
+- Output contract details only through the specified JSON fields. Do not add extra keys or reorder fields. Escape newlines as `\\n` inside JSON strings.
+
+### Quality Guardrails (must stay in the system prompt)
+
+- Hallucinations: no invented APIs, behaviors, dependencies, or storage details beyond the supplied context.
+- Vagueness and filler: avoid generic statements like “this is very useful”; be specific to the module/facet and diamond pattern.
+- Repetition and redundancy: do not restate inputs verbatim or repeat the same idea in multiple sections.
+- Passive, wordy, or hedging language: prefer direct, active phrasing without needless qualifiers.
+- Inaccurate code: wrong function names/params/visibility, missing imports, or examples that can’t compile.
+- Inconsistency: maintain a steady tense, voice, and terminology; keep examples consistent with the described functions.
+- Overclaiming: no security, performance, or compatibility claims that are not explicitly supported by the context.
+
+---
+
+## Relevant Guideline Sections
+
+These section headers from `copilot-instructions.md` are appended to the system prompt to enforce Compose-wide standards. One section per line; must match exactly.
+
+```
+## 3. Core Philosophy
+## 4. Facet Design Principles
+## 5. Banned Solidity Features
+## 6. Composability Guidelines
+## 11. Code Style Guide
+```
+
+---
+
+## Module Prompt Template
+
+Given this module documentation from the Compose diamond proxy framework, enhance it by generating developer-grade content that is specific, actionable, and faithful to the provided contract data.
+
+1. **description**: A concise one-line description (max 100 chars) for the page subtitle. Derive from the module's purpose based on its functions and NatSpec. Do NOT include "module" or "for Compose diamonds" - just describe what it does.
+2. **overview**: 2-3 sentence overview of what the module does and why it matters for diamonds (storage reuse, composition, safety).
+3. **usageExample**: 10-20 lines of Solidity demonstrating how a facet would import and call this module. Use the real function names and signatures; include pragma and any required imports. Keep it minimal but compilable.
+4. **bestPractices**: 2-3 bullets focused on safe and idiomatic use (access control, storage hygiene, upgrade awareness, error handling).
+5. **integrationNotes**: Explain how the module interacts with diamond storage and how changes are visible to facets; note any invariants or ordering requirements.
+6. **keyFeatures**: 2-4 bullets highlighting unique capabilities, constraints, or guarantees.
+
+Contract Information:
+- Name: {{title}}
+- Current Description: {{description}}
+- Functions: {{functionNames}}
+- Events: {{eventNames}}
+- Errors: {{errorNames}}
+- Function Details:
+{{functionDescriptions}}
+
+Respond ONLY with valid JSON in this exact format (no markdown code blocks, no extra text):
+{
+  "description": "concise one-line description here",
+  "overview": "enhanced overview text here",
+  "usageExample": "solidity code here (use \\n for newlines)",
+  "bestPractices": "- Point 1\\n- Point 2\\n- Point 3",
+  "keyFeatures": "- Feature 1\\n- Feature 2",
+  "integrationNotes": "integration notes here"
+}
+
+---
+
+## Facet Prompt Template
+
+Given this facet documentation from the Compose diamond proxy framework, enhance it by generating precise, implementation-ready guidance.
+
+1. **description**: A concise one-line description (max 100 chars) for the page subtitle. Derive from the facet's purpose based on its functions and NatSpec. Do NOT include "facet" or "for Compose diamonds" - just describe what it does.
+2. **overview**: 2-3 sentence summary of the facet's purpose and value inside a diamond (routing, orchestration, surface area).
+3. **usageExample**: 10-20 lines showing how this facet is deployed or invoked within a diamond. Include pragma, imports, selector usage, and sample calls that reflect the real function names and signatures.
+4. **bestPractices**: 2-3 bullets on correct integration patterns (initialization, access control, storage handling, upgrade safety).
+5. **securityConsiderations**: Concise notes on access control, reentrancy, input validation, and any state-coupling risks specific to this facet.
+6. **keyFeatures**: 2-4 bullets calling out unique abilities, constraints, or guarantees.
+
+Contract Information:
+- Name: {{title}}
+- Current Description: {{description}}
+- Functions: {{functionNames}}
+- Events: {{eventNames}}
+- Errors: {{errorNames}}
+- Function Details:
+{{functionDescriptions}}
+
+Respond ONLY with valid JSON in this exact format (no markdown code blocks, no extra text):
+{
+  "description": "concise one-line description here",
+  "overview": "enhanced overview text here",
+  "usageExample": "solidity code here (use \\n for newlines)",
+  "bestPractices": "- Point 1\\n- Point 2\\n- Point 3",
+  "keyFeatures": "- Feature 1\\n- Feature 2",
+  "securityConsiderations": "security notes here"
+}
+
+---
+
+## Module Fallback Content
+
+Used when AI enhancement is unavailable for modules.
+
+### integrationNotes
+
+This module accesses shared diamond storage, so changes made through this module are immediately visible to facets using the same storage pattern. All functions are internal as per Compose conventions.
+
+### keyFeatures
+
+- All functions are `internal` for use in custom facets
+- Follows diamond storage pattern (EIP-8042)
+- Compatible with ERC-2535 diamonds
+- No external dependencies or `using` directives
+
+---
+
+## Facet Fallback Content
+
+Used when AI enhancement is unavailable for facets.
+
+### keyFeatures
+
+- Self-contained facet with no imports or inheritance
+- Only `external` and `internal` function visibility
+- Follows Compose readability-first conventions
+- Ready for diamond integration

.github/scripts/ai-provider/README.md

@@ -0,0 +1,179 @@
+# AI Provider Service
+
+Simple, configurable AI service for CI workflows supporting multiple providers.
+
+## Features
+
+- **Simple API**: One function to call any AI model
+- **Multiple Providers**: GitHub Models (GPT-4o) and Google Gemini
+- **Auto-detection**: Automatically uses available provider
+- **Rate Limiting**: Built-in request and token-based rate limiting
+- **Configurable**: Override provider and model via environment variables
+
+## Supported Providers
+
+| Provider | Models | Rate Limits | API Key |
+|----------|--------|-------------|---------|
+| **GitHub Models** | gpt-4o, gpt-4o-mini | 10 req/min, 40k tokens/min | `GITHUB_TOKEN` |
+| **Google Gemini** | gemini-1.5-flash, gemini-1.5-pro | 15 req/min, 1M tokens/min | `GOOGLE_AI_API_KEY` |
+
+## Usage
+
+### Basic Usage
+
+```javascript
+const ai = require('./ai-provider');
+
+const response = await ai.call(
+  'You are a helpful assistant',  // system prompt
+  'Explain quantum computing'      // user prompt
+);
+
+console.log(response);
+```
+
+### With Options
+
+```javascript
+const response = await ai.call(
+  systemPrompt,
+  userPrompt,
+  {
+    maxTokens: 1000,
+    onSuccess: (text, tokens) => {
+      console.log(`Success! Used ${tokens} tokens`);
+    },
+    onError: (error) => {
+      console.error('Failed:', error);
+    }
+  }
+);
+```
+
+## Environment Variables
+
+### Provider Selection
+
+```bash
+# Auto-detect (default) - Try other provider with fallback to Github
+AI_PROVIDER=auto
+
+# Use specific provider
+AI_PROVIDER=github    # Use GitHub Models
+AI_PROVIDER=gemini    # Use Google Gemini
+```
+
+### Model Override
+
+```bash
+# Override default model for the provider
+AI_MODEL=gpt-4o              # For GitHub Models
+AI_MODEL=gemini-1.5-pro      # For Gemini
+```
+
+### API Keys
+
+```bash
+# Google Gemini
+GOOGLE_AI_API_KEY=
+```
+
+## Examples
+
+## GitHub Actions Integration
+
+```yaml
+- name: Run AI-powered task
+  env:
+    # Option 1: Auto-detect (recommended)
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    GOOGLE_AI_API_KEY: ${{ secrets.GOOGLE_AI_API_KEY }}
+
+    # Option 2: Force specific provider
+    # AI_PROVIDER: 'gemini'
+    # AI_MODEL: 'gemini-1.5-pro'
+  run: node .github/scripts/your-script.js
+```
+
+## Architecture
+
+```
+ai-provider/
+├── index.js                 # Main service (singleton)
+├── base-provider.js         # Base provider class
+├── provider-factory.js      # Provider creation logic
+├── rate-limiter.js          # Rate limiting logic
+└── providers/
+    ├── github-models.js     # GitHub Models implementation
+    └── gemini.js            # Gemini implementation
+```
+
+## Adding a New Provider
+
+1. Create a new provider class in `providers/`:
+
+```javascript
+const BaseAIProvider = require('../base-provider');
+
+class MyProvider extends BaseAIProvider {
+  constructor(config, apiKey) {
+    super('My Provider', config, apiKey);
+  }
+
+  buildRequestOptions() {
+    // Return HTTP request options
+  }
+
+  buildRequestBody(systemPrompt, userPrompt, maxTokens) {
+    // Return JSON.stringify(...) of request body
+  }
+
+  extractContent(response) {
+    // Return { content: string, tokens: number|null }
+  }
+}
+
+module.exports = MyProvider;
+```
+
+2. Register in `provider-factory.js`:
+
+```javascript
+const MyProvider = require('./providers/my-provider');
+
+function createMyProvider(customModel) {
+  const apiKey = process.env.MY_PROVIDER_API_KEY;
+  if (!apiKey) return null;
+
+  return new MyProvider({ model: customModel || 'default-model' }, apiKey);
+}
+```
+
+3. Add to auto-detection or switch statement.
+
+## Rate Limiting
+
+The service automatically handles rate limiting:
+
+- **Request-based**: Ensures minimum delay between requests
+- **Token-based**: Tracks token consumption in a 60-second rolling window
+- **Smart waiting**: Calculates exact wait time needed
+
+Rate limits are provider-specific and configured automatically.
+
+## Error Handling
+
+```javascript
+try {
+  const response = await ai.call(systemPrompt, userPrompt);
+  // Use response
+} catch (error) {
+  if (error.message.includes('429')) {
+    console.log('Rate limited - try again later');
+  } else if (error.message.includes('401')) {
+    console.log('Invalid API key');
+  } else {
+    console.log('Other error:', error.message);
+  }
+}
+```