@cleocode/cleo 2026.2.5 → 2026.2.7

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

@@ -0,0 +1,318 @@
+# @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

@@ -0,0 +1,208 @@
+# 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

@@ -0,0 +1,169 @@
+# 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