diff --git a/claude.md b/CLAUDE.md similarity index 81% rename from claude.md rename to CLAUDE.md index 4d2e9b92c..523806cff 100644 --- a/claude.md +++ b/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