@cleocode/cleo 2026.3.2 → 2026.3.6

package/packages/ct-skills/skills/ct-gitbook/references/api-sdk.md

@@ -1,318 +0,0 @@
-# @gitbook/api TypeScript SDK Reference
-
-The official TypeScript SDK for the GitBook API. Works in Node.js and browsers.
-
-## Installation
-
-```bash
-npm install @gitbook/api
-```
-
-## Client Initialization
-
-```typescript
-import { GitBookAPI } from '@gitbook/api';
-
-// With explicit token
-const client = new GitBookAPI({
-  authToken: 'gb_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
-});
-
-// From environment
-const client = new GitBookAPI({
-  authToken: process.env.GITBOOK_API_TOKEN,
-});
-```
-
-## Authentication
-
-Generate an API token at `https://app.gitbook.com/account/developer`.
-
-```typescript
-// Verify authentication
-const user = await client.user.getCurrentUser();
-console.log(user.data.displayName);
-// Returns: { data: { id, displayName, email, photoURL } }
-```
-
-Token scopes control access. Create tokens with the minimum required permissions.
-
-## Organizations
-
-```typescript
-// List all organizations for the authenticated user
-const orgs = await client.orgs.listOrganizationsForAuthenticatedUser();
-for (const org of orgs.data.items) {
-  console.log(`${org.title} (${org.id})`);
-}
-
-// Get organization by ID
-const org = await client.orgs.getOrganizationById(orgId);
-
-// List members
-const members = await client.orgs.listMembersInOrganization(orgId);
-
-// Invite members
-await client.orgs.inviteMembersToOrganization(orgId, {
-  emails: ['user@example.com'],
-  role: 'editor', // admin | creator | editor | reviewer | reader
-});
-
-// Update member role
-await client.orgs.updateMemberInOrganization(orgId, memberId, {
-  role: 'admin',
-});
-
-// Remove member
-await client.orgs.removeMemberFromOrganization(orgId, memberId);
-```
-
-## Spaces
-
-```typescript
-// List spaces in an organization
-const spaces = await client.orgs.listSpacesInOrganization(orgId);
-
-// Get space by ID
-const space = await client.spaces.getSpaceById(spaceId);
-
-// Create space
-const newSpace = await client.orgs.createSpace(orgId, {
-  title: 'API Documentation',
-  visibility: 'public', // public | private | unlisted
-});
-
-// Update space
-await client.spaces.updateSpace(spaceId, {
-  title: 'Updated Title',
-  visibility: 'private',
-});
-
-// Delete space
-await client.spaces.deleteSpace(spaceId);
-```
-
-## Content & Pages
-
-```typescript
-// List pages in a space (returns tree structure)
-const pages = await client.spaces.listPagesInSpace(spaceId);
-for (const page of pages.data.pages) {
-  console.log(`${page.title} — ${page.path}`);
-}
-
-// Get a specific page
-const page = await client.spaces.getPageInSpace(spaceId, pageId);
-
-// Search content
-const results = await client.spaces.searchSpaceContent(spaceId, {
-  query: 'authentication',
-});
-
-// Import content from external source
-await client.spaces.importContentInSpace(spaceId, {
-  source: {
-    type: 'github',
-    url: 'https://github.com/org/docs-repo',
-    ref: 'main',
-  },
-});
-```
-
-## Content Variants
-
-```typescript
-// List variants for a space
-const variants = await client.spaces.listVariantsInSpace(spaceId);
-
-// Create a variant
-const variant = await client.spaces.createVariant(spaceId, {
-  title: 'v2.0',
-  slug: 'v2',
-});
-
-// Set default variant
-await client.spaces.setDefaultVariant(spaceId, variantId);
-
-// Get variant content
-const content = await client.spaces.listPagesInVariant(spaceId, variantId);
-
-// Delete variant
-await client.spaces.deleteVariant(spaceId, variantId);
-```
-
-## Collections
-
-```typescript
-// List collections
-const collections = await client.orgs.listCollectionsInOrganization(orgId);
-
-// Create collection
-const collection = await client.orgs.createCollection(orgId, {
-  title: 'Product Docs',
-  description: 'All product documentation',
-});
-
-// Add space to collection
-await client.collections.addSpaceToCollection(collectionId, spaceId);
-
-// List spaces in collection
-const spaces = await client.collections.listSpacesInCollection(collectionId);
-
-// Remove space from collection
-await client.collections.removeSpaceFromCollection(collectionId, spaceId);
-```
-
-## Docs Sites
-
-```typescript
-// Create a docs site
-const site = await client.orgs.createSite(orgId, {
-  title: 'Developer Documentation',
-});
-
-// List sites
-const sites = await client.orgs.listSitesInOrganization(orgId);
-
-// Get site
-const site = await client.sites.getSiteById(siteId);
-
-// Update site customization
-await client.sites.updateSiteCustomization(siteId, {
-  hostname: 'docs.example.com',
-  styling: {
-    primaryColor: '#0066FF',
-    font: 'Inter',
-  },
-  themes: {
-    default: 'light',
-    toggleable: true,
-  },
-  favicon: 'https://example.com/favicon.ico',
-  logo: {
-    light: 'https://example.com/logo-light.png',
-    dark: 'https://example.com/logo-dark.png',
-  },
-});
-
-// Delete site
-await client.sites.deleteSite(siteId);
-```
-
-## Site Sections
-
-```typescript
-// Add a section to a site
-await client.sites.addSiteSection(siteId, {
-  spaceId: spaceId,
-  title: 'API Reference',
-});
-
-// List sections
-const sections = await client.sites.listSiteSections(siteId);
-
-// Update section
-await client.sites.updateSiteSection(siteId, sectionId, {
-  title: 'Updated Section Title',
-});
-
-// Remove section
-await client.sites.removeSiteSection(siteId, sectionId);
-
-// Create section group (nested navigation)
-await client.sites.addSiteSectionGroup(siteId, {
-  title: 'Products',
-  sections: [sectionId1, sectionId2],
-});
-```
-
-## Change Requests
-
-```typescript
-// Create a change request
-const cr = await client.spaces.createChangeRequest(spaceId, {
-  subject: 'Update authentication guide',
-});
-
-// List change requests
-const changeRequests = await client.spaces.listChangeRequests(spaceId);
-
-// Get change request details
-const detail = await client.spaces.getChangeRequest(spaceId, crId);
-
-// Merge change request
-await client.spaces.mergeChangeRequest(spaceId, crId);
-```
-
-## Error Handling
-
-The SDK throws typed errors for API failures:
-
-```typescript
-import { GitBookAPI, GitBookAPIError } from '@gitbook/api';
-
-try {
-  await client.spaces.getSpaceById('invalid-id');
-} catch (error) {
-  if (error instanceof GitBookAPIError) {
-    console.error(`API Error ${error.statusCode}: ${error.message}`);
-    // error.statusCode — HTTP status (401, 403, 404, etc.)
-    // error.message — Human-readable error description
-  }
-}
-```
-
-### Common Error Codes
-
-| Status | Meaning | Action |
-|--------|---------|--------|
-| 401 | Unauthorized | Check/regenerate API token |
-| 403 | Forbidden | Token lacks required scope |
-| 404 | Not Found | Verify resource ID |
-| 429 | Rate Limited | Back off and retry |
-| 500 | Server Error | Retry with exponential backoff |
-
-## Rate Limiting
-
-The API enforces rate limits. Handle 429 responses with exponential backoff:
-
-```typescript
-async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
-  for (let attempt = 0; attempt <= maxRetries; attempt++) {
-    try {
-      return await fn();
-    } catch (error) {
-      if (error instanceof GitBookAPIError && error.statusCode === 429 && attempt < maxRetries) {
-        const delay = Math.pow(2, attempt) * 1000;
-        await new Promise((resolve) => setTimeout(resolve, delay));
-        continue;
-      }
-      throw error;
-    }
-  }
-  throw new Error('Max retries exceeded');
-}
-```
-
-## Pagination
-
-List endpoints return paginated results:
-
-```typescript
-// Manual pagination
-let page = await client.orgs.listSpacesInOrganization(orgId);
-const allSpaces = [...page.data.items];
-
-while (page.data.next) {
-  page = await client.orgs.listSpacesInOrganization(orgId, {
-    page: page.data.next,
-  });
-  allSpaces.push(...page.data.items);
-}
-```
-
-## Resources
-
-- **npm**: https://www.npmjs.com/package/@gitbook/api
-- **API Docs**: https://developer.gitbook.com/
-- **API Reference**: https://gitbook.com/docs/developers/gitbook-api/api-reference

package/packages/ct-skills/skills/ct-gitbook/references/auth-sso.md

@@ -1,208 +0,0 @@
-# Authentication & SSO Reference
-
-Visitor authentication, SSO/SAML, and identity provider setup for GitBook.
-
-## Overview
-
-GitBook provides two layers of authentication:
-
-1. **Organization SSO** — Controls who can edit documentation (team members)
-2. **Visitor Authentication** — Controls who can view published documentation (end users)
-
-## Visitor Authentication
-
-Protect published docs behind a login screen. When enabled, visitors must authenticate through your identity provider before viewing content.
-
-### Supported Providers
-
-| Provider | Type | GitBook Integration |
-|----------|------|-------------------|
-| Auth0 | Native | Install from integrations |
-| Okta | Native | Install from integrations |
-| Azure AD | Native | Install from integrations |
-| AWS Cognito | Native | Install from integrations |
-| Custom OIDC | Manual | Build your own backend |
-
-### Enabling Authenticated Access
-
-1. Open your site's settings
-2. Navigate to **Audience**
-3. Select **Authenticated access**
-4. Choose your identity provider
-5. Configure the provider settings
-
-## Auth0 Setup
-
-### 1. Create Auth0 Application
-
-In Auth0 dashboard:
-- Create a new **Regular Web Application**
-- Note the Domain, Client ID, and Client Secret
-
-### 2. Configure Callback URLs
-
-Add your GitBook docs URL as an allowed callback:
-```
-https://docs.example.com/~gitbook/auth/callback
-```
-
-### 3. Install GitBook Integration
-
-In GitBook:
-1. Go to site settings > Integrations
-2. Install the **Auth0** integration
-3. Enter your Auth0 Domain, Client ID, and Client Secret
-
-### 4. Configure Claims for Adaptive Content
-
-To use Auth0 with adaptive content, add an Auth0 Action or Rule that includes custom claims in the ID token:
-
-```javascript
-// Auth0 Action — Add custom claims
-exports.onExecutePostLogin = async (event, api) => {
-  const namespace = 'https://docs.example.com/';
-  api.idToken.setCustomClaim(`${namespace}plan`, event.user.app_metadata?.plan || 'free');
-  api.idToken.setCustomClaim(`${namespace}role`, event.user.app_metadata?.role || 'user');
-};
-```
-
-These claims become available for adaptive content conditions in GitBook.
-
-## Okta Setup
-
-### 1. Create Okta Application
-
-In Okta admin console:
-- Create a new **Web Application**
-- Set the sign-in redirect URI to your GitBook callback URL
-- Note the Client ID and Client Secret
-
-### 2. Configure in GitBook
-
-Install the Okta integration and provide:
-- Okta domain (e.g., `dev-12345.okta.com`)
-- Client ID
-- Client Secret
-
-### 3. Claims for Adaptive Content
-
-Configure Okta to include custom claims in the authentication token:
-
-1. Go to **Security > API > Authorization Servers**
-2. Select your authorization server
-3. Add custom claims (e.g., `plan`, `role`) with values from user profile attributes
-
-## Azure AD Setup
-
-### 1. Register Application
-
-In Azure portal:
-- Navigate to **Azure Active Directory > App registrations**
-- Register a new application
-- Add redirect URI: `https://docs.example.com/~gitbook/auth/callback`
-- Create a client secret
-
-### 2. Configure in GitBook
-
-Install the Azure AD integration and provide:
-- Tenant ID
-- Client ID
-- Client Secret
-
-### Known Limitation
-
-The Azure integration removes heading URL fragments upon authentication. Deep links to specific headings may not work as expected after the auth redirect.
-
-## Custom OIDC Backend
-
-For providers not natively supported, implement a custom authentication backend:
-
-### Requirements
-
-Your backend must:
-1. Handle the OIDC authorization flow
-2. Redirect to GitBook with a signed JWT
-3. Include required claims in the JWT payload
-
-### JWT Payload
-
-```json
-{
-  "sub": "user-id",
-  "email": "user@example.com",
-  "name": "User Name",
-  "iat": 1706000000,
-  "exp": 1706003600,
-  "custom_claims": {
-    "plan": "enterprise",
-    "role": "admin"
-  }
-}
-```
-
-### Flow
-
-1. Visitor accesses protected docs
-2. GitBook redirects to your auth endpoint
-3. Your backend authenticates the user
-4. Your backend redirects back to GitBook with a signed JWT
-5. GitBook validates the JWT and grants access
-
-## Organization SSO
-
-Separate from visitor auth — this controls team member access to the GitBook organization.
-
-### Email Domain SSO
-
-Allow anyone with an email from your domain to join your organization:
-
-1. Go to **Organization settings > SSO**
-2. Add your verified email domain
-3. Team members can sign in with their work email
-
-### SAML 2.0
-
-For enterprise identity providers:
-
-1. Go to **Organization settings > SSO > SAML**
-2. Provide your IdP's metadata URL or upload metadata XML
-3. Configure attribute mapping:
-   - `email` → User email
-   - `firstName` → First name
-   - `lastName` → Last name
-4. Enable SAML SSO
-
-### Supported SAML IdPs
-
-Any SAML 2.0 compliant provider works, including:
-- Okta
-- Azure AD
-- OneLogin
-- Google Workspace
-- PingFederate
-- JumpCloud
-
-## Security Certifications
-
-GitBook holds:
-- **SOC 2 Type II** — Security, availability, and confidentiality
-- **ISO 27001** — Information security management
-
-## Access Control Roles
-
-| Role | Permissions |
-|------|------------|
-| Admin | Full organization management |
-| Creator | Create spaces and content |
-| Editor | Edit existing content |
-| Reviewer | Review change requests, add comments |
-| Reader | View private content only |
-
-## Resources
-
-- **Visitor Authentication**: https://docs.gitbook.com/publishing-documentation/visitor-authentication
-- **SSO & SAML**: https://gitbook.com/docs/account-management/sso-and-saml
-- **Auth0 Setup**: https://gitbook.com/docs/publishing-documentation/authenticated-access/setting-up-auth0
-- **Okta Setup**: https://gitbook.com/docs/publishing-documentation/authenticated-access/setting-up-okta
-- **Azure AD Setup**: https://gitbook.com/docs/publishing-documentation/authenticated-access/setting-up-azure-ad
-- **Authenticated Access**: https://gitbook.com/docs/publishing-documentation/authenticated-access/enabling-authenticated-access

package/packages/ct-skills/skills/ct-gitbook/references/change-requests.md

@@ -1,169 +0,0 @@
-# Change Requests Reference
-
-Branch-and-merge editing workflow with review, plus adaptive content personalization.
-
-## Overview
-
-A Change Request (CR) is an isolated copy of your space's content — similar to a Git branch or pull request. You can edit freely in a CR without affecting live documentation, then merge when ready.
-
-## Workflow
-
-### 1. Create a Change Request
-
-**In the UI**: Click **New change request** in the space sidebar.
-
-**Via API**:
-```typescript
-const cr = await client.spaces.createChangeRequest(spaceId, {
-  subject: 'Update authentication guide',
-});
-console.log(`Created CR: ${cr.data.id}`);
-```
-
-### 2. Make Edits
-
-- Edit pages in the GitBook editor within the CR context
-- Add, remove, or reorder pages
-- Upload new assets
-- Use the Docs Agent (AI) to generate or refine content within the CR
-
-All changes are isolated from the live site.
-
-### 3. Request Review
-
-- Tag reviewers in the CR's **Overview** tab
-- Reviewers are notified and can approve, request changes, or comment
-- Docs Agent can also be assigned as a reviewer for AI-assisted feedback
-
-### 4. Review
-
-Reviewers can:
-- View a diff of all changes
-- Add inline comments on specific content
-- Approve or request changes
-- Previous reviews are marked as **outdated** when the CR is updated
-
-### 5. Merge
-
-```typescript
-await client.spaces.mergeChangeRequest(spaceId, crId);
-```
-
-Merging applies all changes to the main content and publishes them to the live site immediately.
-
-## API Operations
-
-```typescript
-// Create change request
-const cr = await client.spaces.createChangeRequest(spaceId, {
-  subject: 'Add new API endpoints documentation',
-});
-
-// List change requests for a space
-const list = await client.spaces.listChangeRequests(spaceId);
-for (const item of list.data.items) {
-  console.log(`${item.subject} — ${item.status}`);
-}
-
-// Get change request details
-const detail = await client.spaces.getChangeRequest(spaceId, crId);
-
-// Get content diff
-const diff = await client.spaces.getChangeRequestDiff(spaceId, crId);
-
-// Merge
-await client.spaces.mergeChangeRequest(spaceId, crId);
-
-// Close without merging
-await client.spaces.closeChangeRequest(spaceId, crId);
-```
-
-## Review Features (October 2025 Updates)
-
-- **Improved sidebar**: Filter CRs by creator, participant, or review status
-- **Shortcut filters**: Quick access to "awaiting my review" and "created by me"
-- **Outdated reviews**: Automatically marked when new changes are pushed
-- **Re-request review**: Single-action button to request a fresh review
-- **Review badges**: Visual indicators for review status on each CR
-
-## Docs Agent Integration
-
-The Docs Agent is GitBook's AI assistant that can:
-- Generate content within a change request
-- Review changes and suggest improvements
-- Be assigned as a reviewer alongside human reviewers
-- Provide automated quality feedback
-
-## Change Request Statuses
-
-| Status | Description |
-|--------|-------------|
-| `open` | Active, editable |
-| `merged` | Changes applied to main content |
-| `closed` | Discarded without merging |
-
-## Best Practices
-
-1. **One topic per CR** — Keep changes focused for easier review
-2. **Descriptive subjects** — Use clear subjects like "Add OAuth2 guide" not "Update docs"
-3. **Tag reviewers early** — Don't wait until the CR is complete to request feedback
-4. **Use Docs Agent** — Let AI catch formatting issues and suggest improvements
-5. **Merge promptly** — Long-lived CRs increase conflict risk
-
----
-
-## Adaptive Content
-
-Adaptive content personalizes published documentation based on visitor attributes (claims).
-
-### How It Works
-
-1. Visitors arrive with **claims** — data about who they are (role, plan, region, etc.)
-2. Claims are passed via cookies, URL parameters, feature flags, or authentication providers
-3. GitBook dynamically shows/hides content based on claim values
-
-### Methods for Passing Claims
-
-| Method | Use Case |
-|--------|----------|
-| Cookies | Public or signed cookies set by your app |
-| URL parameters | `?plan=enterprise&role=admin` |
-| Feature flag provider | LaunchDarkly, Split, etc. |
-| Authentication provider | Auth0, Okta, Azure AD claims |
-
-### What You Can Adapt
-
-- **Pages**: Show/hide entire pages based on claims
-- **Sections**: Show/hide page sections
-- **Header links**: Dynamic navigation based on user type
-- **Content blocks**: Conditional content within a page
-
-### Example Use Cases
-
-- Show "Getting Started" to new users, "Advanced API" to experienced users
-- Display pre-filled API keys for authenticated developers
-- Show enterprise features only to enterprise plan users
-- Present region-specific compliance information
-- Hide internal-only documentation from external visitors
-
-### Configuration
-
-Enable adaptive content in site settings. Requires an Ultimate plan and a custom domain.
-
-```typescript
-// Site must have authenticated access enabled
-// Claims are then available for content conditions
-await client.sites.updateSiteCustomization(siteId, {
-  audience: 'authenticated',
-});
-```
-
-### AI Assistant Integration
-
-GitBook Assistant uses adaptive content context to provide personalized answers. When connected to MCP servers, the assistant can pull information from third-party sources and trigger actions based on visitor claims.
-
-## Resources
-
-- **Change Requests**: https://gitbook.com/docs/collaboration/change-requests
-- **Adaptive Content**: https://gitbook.com/docs/publishing-documentation/adaptive-content
-- **Personalization Guide**: https://gitbook.com/docs/guides/docs-personalization-and-authentication/setting-up-adaptive-content