docs: restructure documentation with API migration and auto-generated provider docs

[Kamilbenkirane]

Overview

This PR restructures the Celeste documentation to align with the new API pattern and introduces auto-generated provider documentation.

Key Changes

Documentation Restructure

• Migrated from capability-based to modality-based structure
• Added new modalities/ and domains/ sections
• Removed deprecated capabilities/ section

API Migration

• Updated all examples from create_client(Capability, Provider) to celeste.{modality}.{operation}() pattern
• Updated provider documentation with new API examples
• Added auto-generated model tables to provider pages

New Features

• Auto-generated provider documentation from Celeste registry
• Mermaid diagram support for documentation
• Provider logos in page headers
• Page actions (copy, view options)
• New provider pages: bfl, byteplus, deepseek, gradium, groq, moonshot, xai

Infrastructure

• Added build scripts for auto-generating provider docs
• Updated dependencies (mermaid, radix-ui components)
• Added prebuild/predev hooks for doc generation

Breaking Changes

• Removed capability-based documentation structure
• All API examples now use new pattern

Testing

• Documentation builds successfully
• All provider pages render correctly
• Auto-generated model tables display properly
• Mermaid diagrams render correctly
• Provider logos display correctly
• Page actions work as expected

Related

• Related to Celeste Python API changes
• Part of documentation modernization effort

[claude]

Pull Request Review

This PR represents a significant restructure of the Celeste documentation with auto-generated provider docs. Overall, this is a well-executed refactor with good code quality.

---

✅ Strengths

Architecture & Design

• Excellent separation of concerns: The auto-generation script cleanly separates manual prose from generated content using marker-based replacement
• Smart backward compatibility: Migration from HTML comments to JSX-safe comments is well-handled
• Type safety: Good use of TypeScript with proper interfaces and type annotations
• Clear documentation: The Python script has excellent docstrings explaining design goals

Code Quality

• Python script: Clean, well-structured code with clear function names, good use of dataclasses and type hints, proper error handling
• React components: Clean functional components with proper TypeScript types and good use of React hooks
• Build Process: Smart use of prebuild/predev hooks to auto-generate docs

---

⚠️ Critical Security Issues

1. XSS Vulnerability in Mermaid.tsx (Line 50)

The Mermaid component uses dangerouslySetInnerHTML to render SVG output. While mermaid.js provides some sanitization, this is a potential XSS vector if untrusted chart content is ever rendered.

Recommendations:

• Add explicit sanitization using a library like DOMPurify
• Or document that chart content must be from trusted sources only
• Consider using securityLevel: 'strict' instead of 'loose' (line 9)

2. Mermaid ID Collision Potential (Line 26)

Using Date.now() for IDs could theoretically collide if two renders happen in the same millisecond.

Recommendation: Use crypto.randomUUID() for more robust ID generation

3. Missing Error Handling in page-actions.tsx

The LLMCopyButton component (lines 28-37) has a try-finally but doesn't catch or display fetch errors.

Recommendation: Add error state and user feedback for failed fetches

---

🟡 Medium Priority Issues

4. Accessibility: Missing proper button labels

   • InstallSelector.tsx: Copy button should have aria-label for screen readers
   • MethodSelector.tsx: Tab buttons could benefit from ARIA attributes

5. Python script: Potential encoding issues - no handling for files with different encodings or BOM markers

6. MethodSelector.tsx: Array index used as key (lines 37-38) - could cause issues with dynamic content

---

🧪 Test Coverage

Missing Tests:

• No test files included for new components
• Python script lacks unit tests for regex replacements and edge cases

Recommendations:

• Add tests for marker replacement logic
• Add tests for malformed MDX files
• Add tests for React component rendering
• Add tests for edge cases (empty provider lists, missing logos, etc.)

---

📊 Performance Considerations

• ✅ Good: Caching in LLMCopyButton reduces redundant fetches
• ✅ Good: Mermaid renders on client side, avoiding SSR overhead
• ⚠️ Consider: The prebuild hook runs doc generation on every build - for CI/CD, this adds time

---

🔒 Security Summary

Severity	Issue	Location
🔴 High	XSS via dangerouslySetInnerHTML	src/components/Mermaid.tsx:50
🟡 Medium	Weak ID generation	src/components/Mermaid.tsx:26
🟡 Medium	Missing fetch error handling	src/components/page-actions.tsx:28-37

---

📋 Recommendations Before Merge

Must Fix:

1. ⚠️ Address XSS vulnerability in Mermaid.tsx
2. Change Mermaid securityLevel to 'strict' unless 'loose' is required

Should Fix:

3. Improve Mermaid ID generation to use crypto.randomUUID()
4. Add error handling for fetch failures in LLMCopyButton
5. Add accessibility labels to interactive components

Nice to Have:

6. Add unit tests for Python generation script
7. Add component tests for new React components

---

🎯 Overall Assessment

Code Quality: ⭐⭐⭐⭐ (4/5)
Security: ⚠️ ⭐⭐⭐ (3/5 - due to XSS risk)
Architecture: ⭐⭐⭐⭐⭐ (5/5)
Documentation: ⭐⭐⭐⭐⭐ (5/5)
Test Coverage: ⭐⭐ (2/5 - tests missing)

This is a solid refactor with excellent architectural decisions. The auto-generation approach is well-implemented. However, the XSS vulnerability in the Mermaid component should be addressed before merge.

Recommendation: Address the critical security issue, then this is ready to merge. 👍