Update CLAUDE.md with dev commands, architecture, and guidelines

claude.md → CLAUDE.md

@@ -1,22 +1,57 @@
-# Seam API Documentation - Repository Guide
+# CLAUDE.md
 
-This document provides a comprehensive overview of the Seam API documentation repository structure, organization, and writing conventions. Use this as a reference when working with the documentation.
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-**Repository:** Seam API Documentation (hosted on GitBook at https://docs.seam.co/latest/)
-**Total Files:** 627 markdown files
-**Last Updated:** 2026-01-28
+## Repository Overview
 
----
+Seam API documentation hosted on GitBook at https://docs.seam.co/latest/. Contains hand-written guides, auto-generated API reference pages, a codegen pipeline, and a GitBook plugin.
+
+## Commands
+
+```bash
+nvm install && npm install        # Setup (requires Node >=22.11.0)
+npm run generate                  # Regenerate API reference docs (Metalsmith + Handlebars)
+npm run format                    # Prettier (also runs eslint --fix via preformat hook)
+npm run lint                      # ESLint + Prettier check
+npm run typecheck                 # TypeScript type checking
+npm run validate-paths            # Validate doc file paths
+npm run validate-links            # Validate internal links
+npm run validate-orphan-pages     # Find pages not in SUMMARY.md
+npm run validate-redirects        # Validate .gitbook.yaml redirects
+```
+
+**Always run `npm run format` before committing.** CI auto-commits formatting fixes on non-main branches, but formatting locally avoids noise.
+
+Optional external tools used during `npm run generate` for code sample formatting: `ruff` (Python), `shfmt` (shell), `gofmt` (Go), `stree` from `syntax_tree` gem (Ruby).
+
+## Architecture
+
+### Three GitBook Sites
+
+The repo serves three separate GitBook sites, each with its own config, `SUMMARY.md`, and redirect rules:
+
+| Site          | Root                  | Config                             | Content                                  |
+| ------------- | --------------------- | ---------------------------------- | ---------------------------------------- |
+| Main docs     | `docs/guides/`        | `.gitbook.yaml`                    | Guides, core concepts, capability guides |
+| API reference | `docs/api-reference/` | `docs/api-reference/.gitbook.yaml` | Auto-generated API endpoint docs         |
+| Brand guides  | `docs/brand-guides/`  | `docs/brand-guides/.gitbook.yaml`  | Device/system integration guides         |
+
+### Auto-Generated vs. Hand-Written Content
+
+**`docs/api-reference/`** is auto-generated by `npm run generate`. Do not manually edit these files -- changes will be overwritten. The codegen pipeline:
 
-## Table of Contents
+- Entry point: `codegen/smith.ts` (Metalsmith static site generator)
+- Templates: `codegen/layouts/*.hbs` (Handlebars)
+- Code samples: `codegen/data/code-sample-definitions/*.yaml`
+- Types come from `@seamapi/types` and `@seamapi/blueprint` packages
 
-1. [Documentation Organization](#documentation-organization)
-2. [File Structure](#file-structure)
-3. [Writing Style & Tone](#writing-style--tone)
-4. [Content Types](#content-types)
-5. [GitBook Configuration](#gitbook-configuration)
-6. [Common Patterns & Conventions](#common-patterns--conventions)
-7. [Key Guidelines](#key-guidelines)
+**Everything else under `docs/`** is hand-written and edited directly.
+
+### Other Directories
+
+- `gitbook-plugin/` -- Custom GitBook integration plugin (separate npm package)
+- `seam-sdk-playground/` -- Dev environment for testing SDK code samples across languages
+- `codegen/` -- API reference generation pipeline + validation scripts
 
 ---
 
@@ -63,7 +98,7 @@ The documentation is organized into **7 main sections**, each serving a distinct
 
 ### 3. API Reference (Technical Specifications)
 
-**Purpose:** Complete API endpoint documentation (appears to be auto-generated from OpenAPI specs)
+**Purpose:** Complete API endpoint documentation, auto-generated by `npm run generate`
 
 **Topics:**
 
@@ -79,7 +114,7 @@ The documentation is organized into **7 main sections**, each serving a distinct
   - Connected Accounts
   - And 20+ other resources
 
-**Location:** `/docs/api/`
+**Location:** `docs/api-reference/` (do not manually edit -- see [Auto-Generated vs. Hand-Written Content](#auto-generated-vs-hand-written-content))
 
 ### 4. UI Components
 
@@ -147,7 +182,7 @@ The documentation is organized into **7 main sections**, each serving a distinct
 /docs/
 ├── core-concepts/                           (9 subdirectories)
 ├── capability-guides/                       (11 subdirectories)
-├── api/                                     (29 subdirectories - auto-generated)
+├── api-reference/                           (auto-generated - do not edit)
 ├── device-and-system-integration-guides/    (26 subdirectories)
 ├── device-guides/                           (41 subdirectories)
 ├── products/                                (4 subdirectories)
@@ -326,33 +361,11 @@ The documentation is organized into **7 main sections**, each serving a distinct
 
 ## GitBook Configuration
 
-### Key Settings (from `.gitbook.yaml`)
-
-**Root directory:** `./docs/`
-
-**Structure files:**
-
-- `README.md` - Landing page
-- `SUMMARY.md` - Table of contents
+See the [Architecture](#architecture) section above for the three GitBook site configs and the codegen pipeline.
 
 ### Redirect Management
 
-The configuration includes **198+ redirects** maintaining backward compatibility:
-
-**Common redirect patterns:**
-
-```yaml
-# API client paths → Unified API paths
-api-clients/access-codes/create: api/access_codes/create
-
-# Device guides → Integration guides
-device-guides/august-locks: device-and-system-integration-guides/august-locks
-
-# URL normalization
-old/path/with-dashes: new-path/with-underscores
-```
-
-**Purpose:** Ensures old documentation links continue working as structure evolves
+Each `.gitbook.yaml` contains redirects maintaining backward compatibility. When restructuring, always add redirects in the appropriate site's config.
 
 ---
 
@@ -698,7 +711,7 @@ To follow this guide, you need:
 
 ### For Working with This Repository
 
-1. **Auto-generated content:** The `/docs/api/` directory appears to be auto-generated. Avoid manual edits here - changes should be made to the source spec.
+1. **Auto-generated content:** The `docs/api-reference/` directory is auto-generated by `npm run generate`. Do not manually edit these files -- changes should be made to the codegen pipeline or upstream packages (`@seamapi/types`, `@seamapi/blueprint`).
 
 2. **Consistency is critical:** With 627 files, maintaining consistent formatting, tone, and structure is essential. Follow existing patterns exactly.
 
@@ -714,9 +727,11 @@ To follow this guide, you need:
 
 8. **Link maintenance:** When restructuring, always add redirects in `.gitbook.yaml` to maintain backward compatibility.
 
-9. **Visual aids:** Use screenshots, diagrams, and videos generously. IoT integrations benefit from visual guidance.
+9. **Do not modify file URLs in SUMMARY.md.** Renaming or moving page URLs via SUMMARY.md can break GitBook sync. Use the GitBook UI to rename or move pages instead.
+
+10. **Visual aids:** Use screenshots, diagrams, and videos generously. IoT integrations benefit from visual guidance.
 
-10. **Accessibility:** Provide alt text for images, use semantic HTML, and ensure code examples are properly formatted.
+11. **Accessibility:** Provide alt text for images, use semantic HTML, and ensure code examples are properly formatted.
 
 ### Writing Checklist