RFC: Reorganize docs into 3 site sections

docs-reorganization-plan.md

@@ -0,0 +1,85 @@
+# Docs Reorganization Plan
+
+## Problem
+
+Today, all 633 pages live in a single sidebar (`SUMMARY.md`). This creates several issues:
+
+- **Overwhelming navigation** — the sidebar is a single scroll through 600+ entries
+- **API Reference dominates** — ~240 endpoint pages push everything else down
+- **Device guides are buried** — 100+ manufacturer pages sit at the bottom
+- **Deep nesting** — some paths go 7 levels deep (ASSA ABLOY Visionline)
+- **Inconsistent file structure** — content for the same section lives across `products/`, `capability-guides/`, `device-guides/`, and `device-and-system-integration-guides/`
+- **Sandbox data bloat** — 40 sandbox entries inflate the Developer Tools section
+
+## Proposed Solution: 3 Site Sections
+
+Split the documentation into **3 GitBook site sections**, each backed by its own space with its own sidebar and navigation. All sections are published under one site with global search.
+
+> **Requirement:** GitBook Ultimate plan ($249/site/mo) is needed for site sections.
+
+See: [`plan/`](plan/) for the full proposed sidebar trees (step 1: sectioning, step 2: reorganization).
+
+### Section 1: Guides (main landing space)
+
+The default entry point. Conceptual docs and how-to guides for developers building with Seam.
+
+**Audience:** Developers learning Seam or implementing specific features.
+
+**Organized by product type.** The Guides sidebar groups content by product vertical:
+
+| Product           | What it covers                                                                                                    |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------- |
+| **Access**        | Access Grants & Identity (high-level), Smart Locks & Access Codes (low-level), Access Control Systems (low-level) |
+| **Thermostats**   | HVAC modes, climate presets, schedules, programs                                                                  |
+| **Noise Sensors** | Noise threshold configuration                                                                                     |
+
+Cross-product features (Connectors & Automations, Customer Portals, Reservation Automations) have their own section. Developer workflow tools (Webhooks, CLI, MCP, Mobile SDKs) live in Developer Tools. UI Components (Seam Components, Seam Mobile Components) are in their own section for now.
+
+### Section 2: API Reference
+
+Endpoint documentation, SDK installation, authentication, and API behavior reference. Endpoints mirror the Guides product structure (Access, Thermostats, Noise Sensors, Connectors & Automations).
+
+**Audience:** Developers looking up specific endpoints, parameters, and response schemas during implementation.
+**Approx. pages:** ~240
+
+### Section 3: Integrations
+
+Per-manufacturer setup, configuration, getting started guides, and sandbox data — all consolidated by brand and organized by device category (Smart Locks, Access Control Systems, Thermostats, Other).
+
+**Audience:** Developers integrating a specific device brand or system.
+**Approx. pages:** ~160
+
+---
+
+## What Changes
+
+| Before                                                                      | After                                                                    |
+| --------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| 1 sidebar, ~633 pages                                                       | 3 sidebars, focused by audience                                          |
+| API Reference buried mid-sidebar                                            | API Reference is its own top-level section                               |
+| `device-guides/` + `device-and-system-integration-guides/` as separate dirs | Consolidated into one Integrations section, organized by device category |
+| Sandbox data under Developer Tools (40 entries)                             | Sandbox data lives alongside each manufacturer in Integrations           |
+| Guides organized by abstraction layer                                       | Guides organized by product type (Access, Thermostats, Noise Sensors)    |
+| UI Components mixed into main sidebar                                       | UI Components in its own section within Guides (TBD)                     |
+| Deep nesting (up to 7 levels)                                               | Max 4 levels of nesting                                                  |
+
+## What Doesn't Change
+
+- All existing page content stays the same (no rewrites needed)
+- API Reference pages remain auto-generated
+- Writing conventions, code example patterns, and GitBook syntax are unchanged
+
+## Migration Steps
+
+1. **Decide on plan** — confirm Ultimate plan for site sections
+2. **Create 3 GitBook spaces** — one per section, each with its own SUMMARY.md
+3. **Move/reorganize files** — consolidate `device-guides/` and `device-and-system-integration-guides/`; move sandbox data alongside manufacturers
+4. **Update internal links** — cross-section links become absolute URLs
+5. **Publish as site sections** — link all 3 spaces under one site
+
+## Open Questions
+
+- [ ] Are we on GitBook Ultimate, or willing to upgrade?
+- [ ] Should Device Manufacturer Guidance (building Seam-compatible APIs) live in Integrations or in its own section?
+- [ ] SDKs and UI component libraries should have content in both Guides (setup, usage, tutorials) and API Reference (API surface, parameters, methods). Need to define the split for each.
+- [ ] How do we maintain backward compatibility for existing page URLs during the migration? (redirects strategy TBD)

plan/step_1/README.md

@@ -0,0 +1,116 @@
+# Step 1: Split into 3 Site Sections
+
+Split the single SUMMARY.md into 3 GitBook site sections without reorganizing content within each section. The sidebar within each section preserves the current structure.
+
+## Sections
+
+### Guides
+
+Current SUMMARY.md sections that stay in Guides:
+
+- Top-level pages (Seam Documentation, Quick Start, Go Live)
+- Core Concepts
+- Capability Guides
+- UI Components
+- Developer Tools
+- Industry Guides
+
+### API Reference
+
+Current SUMMARY.md section that moves to API Reference:
+
+- API Reference (auto-generated endpoint docs, installation, authentication, pagination)
+
+### Brand Guides
+
+Current SUMMARY.md sections that move to Brand Guides:
+
+- Device and System Integration Guides
+- Device Manufacturer Guidance
+- Sandbox data (currently scattered across device-guides/ and developer-tools/)
+
+---
+
+## Technical concerns
+
+### 1. Each GitBook section needs its own root directory
+
+GitBook site sections map to separate spaces, and each space requires its own root directory with its own SUMMARY.md. Files cannot be referenced outside a space's root. The repo would need to look like:
+
+```
+repo-root/
+├── guides/
+│   ├── .gitbook.yaml
+│   ├── SUMMARY.md
+│   └── (all guide content)
+├── api-reference/
+│   ├── .gitbook.yaml
+│   ├── SUMMARY.md
+│   └── (all API endpoint docs)
+└── brand-guides/
+    ├── .gitbook.yaml
+    ├── SUMMARY.md
+    └── (all integration/device docs)
+```
+
+This means files must physically move into separate directories — even for step 1.
+
+### 2. Cross-section links become absolute URLs
+
+Within a GitBook space, links use relative markdown paths. Between spaces, links must use absolute URLs (e.g., `https://docs.seam.co/api-reference/access_codes/create`). GitBook's broken link detection does not work across spaces.
+
+Pages that will need link updates:
+
+- Guides link heavily to API Reference endpoints (e.g., "see the `access_codes.create` endpoint")
+- Brand Guides link back to Capability Guides (e.g., "see the Access Codes guide")
+- API Reference links to Guides for conceptual context
+
+**Mitigating URL sprawl:** GitBook has no variable/macro support for URLs. However, ~638 of the existing `docs.seam.co` references are in auto-generated API pages — the codegen's `postprocess.ts` already rewrites URLs and can read the base URL from a config value (e.g., in `paths.yaml` or an env var). Hand-written guide pages rarely link to other sections, so the volume of hardcoded absolute URLs in manually maintained files is small.
+
+### 3. Codegen pipeline needs updating
+
+The current codegen (`npm run generate` → `codegen/smith.ts`) assumes a single `docs/` root:
+
+- `summary.ts` splices generated API content into the single SUMMARY.md between anchors (`[Pagination]` and `## Developer Tools`)
+- `postprocess.ts` converts absolute URLs to relative paths (assumes single-space structure)
+- Generated files are written to `docs/api/`
+
+For step 1, the codegen needs to:
+
+- Write API files to `api-reference/` instead of `docs/api/`
+- Generate a standalone SUMMARY.md for the API Reference space
+- Update `postprocess.ts` to handle cross-space links (keep absolute URLs for links to Guides/Brand Guides)
+
+### 4. Shared assets must be duplicated
+
+GitBook spaces cannot share assets. Currently all images live in `docs/.gitbook/assets/` and reusable snippets in `docs/.gitbook/includes/`. Each space would need its own copy of any shared assets.
+
+Options:
+
+- Duplicate assets into each space that uses them
+- Use a build step to copy shared assets into each space directory
+- Audit which assets are used by which section and split accordingly
+
+### 5. Sandbox data lives in the wrong directories
+
+Sandbox pages are currently scattered across `device-guides/sandbox-and-sample-data/` and `developer-tools/sandbox-and-sample-data/`. In step 1, these need to move to the Brand Guides space. Some are referenced from the Developer Tools section in Guides — those references would become cross-section absolute links.
+
+### 6. Files referenced across sections
+
+Some files currently live in one directory but are listed in a different sidebar section:
+
+- `device-guides/reconnecting-an-account.md` is listed under Core Concepts > Connected Accounts
+- `device-guides/rate-limits-and-guardrails.md` is listed under Developer Tools
+- Various `products/` files appear in Capability Guides
+
+These files need to either move to the correct space or be replaced with cross-section links.
+
+### 7. Git Sync is per-space
+
+Each GitBook space has its own independent Git Sync configuration. With 3 spaces, you configure sync 3 times — each pointing at a different project directory in the same repo and branch. A commit touching files in `api-reference/` only triggers sync for that space.
+
+### 8. Redirects
+
+Every page that changes URL needs a redirect for backward compatibility. The current site publishes under `docs.seam.co/latest/`. If the new sections publish under different URL prefixes (e.g., `/api-reference/`, `/brand-guides/`), all existing URLs need redirects.
+
+Each space's `.gitbook.yaml` can define redirects, but only for pages within that space. Cross-space redirects (old URL in one space, new URL in another) may need to be handled at the DNS/proxy level or via GitBook's site-level redirect settings.

plan/step_2/README.md

@@ -0,0 +1,19 @@
+# Step 2: Reorganize Content Within Each Section
+
+After step 1 splits the docs into 3 GitBook site sections, step 2 reorganizes the sidebar structure within each section.
+
+See the before/after trees for each section:
+
+- [Guides](guides.md)
+- [API Reference](api-reference.md)
+- [Brand Guides](brand-guides.md)
+
+## TODOs
+
+- [ ] **Get Started section** — How should Quick Start and Go Live be organized? Should they remain top-level, be grouped under a "Get Started" section, or be split per product (e.g., "Get started with Access", "Get started with Thermostats")?
+- [ ] **Core Concepts section** — Review which concepts are still relevant as top-level items. Some may fold into product sections (e.g., Devices into Access, Connect Webviews into a setup/onboarding flow). Others may be too granular for their current placement (e.g., custom metadata filtering pages).
+- [ ] **Connectors & Automations placement** — Cross-product section, but location TBD.
+- [ ] **Seam Bridge placement** — Currently under ACS, may move closer to Connected Accounts.
+- [ ] **SDKs and UI component libraries** — Define the content split between Guides (setup, usage, tutorials) and API Reference (API surface, parameters, methods).
+- [ ] **API Reference product grouping** — Requires codegen changes to `summary.ts` to produce the new grouping instead of flat namespace list.
+- [ ] **Platform section in API Reference** — Review which resources belong here vs under a product group.

plan/step_2/api-reference.md

@@ -0,0 +1,99 @@
+# Step 2: API Reference Reorganization
+
+## Before (current structure after step 1)
+
+```
+API Reference
+├── Overview
+├── Installation
+├── Authentication
+├── Pagination
+├── Access Codes
+│   ├── (CRUD + generate, report constraints)
+│   ├── Simulations
+│   └── Unmanaged Access Codes
+├── Access Control Systems (ACS)
+│   ├── Access Groups
+│   ├── ACS Users
+│   ├── Credentials
+│   ├── Encoders (+ simulations)
+│   ├── Entrances
+│   └── Systems
+├── Access Grants
+│   └── Unmanaged
+├── Access Methods
+│   └── Unmanaged
+├── Action Attempts
+├── Client Sessions
+├── Connect Webviews
+├── Connected Accounts (+ simulate)
+├── Customers
+├── Devices (+ simulations, unmanaged)
+├── Events
+├── Instant Keys
+├── Locks (+ simulations)
+├── Noise Sensors
+│   ├── Simulations
+│   └── Noise Thresholds
+├── Phones (+ simulations)
+├── Spaces
+├── Thermostats
+│   ├── Daily Programs
+│   ├── Schedules
+│   └── Simulations
+├── User Identities (+ unmanaged)
+├── Webhooks
+└── Workspaces
+```
+
+## After (proposed)
+
+```
+API Reference
+├── Overview
+├── Installation
+├── Authentication
+├── Pagination
+├── Rate Limits
+├── Access
+│   ├── Access Grants & Identity
+│   │   ├── Access Grants (+ unmanaged)
+│   │   ├── Access Methods (+ unmanaged)
+│   │   ├── User Identities (+ unmanaged)
+│   │   └── Instant Keys
+│   ├── Smart Locks
+│   │   ├── Access Codes (+ simulations, unmanaged)
+│   │   └── Locks (+ simulations)
+│   └── Access Control Systems
+│       ├── Systems
+│       ├── Access Groups
+│       ├── Users
+│       ├── Credentials
+│       ├── Encoders (+ simulations)
+│       └── Entrances
+├── Thermostats
+│   └── Thermostats (+ daily programs, schedules, simulations)
+├── Noise Sensors
+│   └── Noise Sensors (+ noise thresholds, simulations)
+├── Connectors & Automations
+│   ├── Customers
+│   └── Spaces
+└── Platform (TBD)
+    ├── Action Attempts
+    ├── Client Sessions
+    ├── Connect Webviews
+    ├── Connected Accounts (+ simulate)
+    ├── Devices (+ simulations, unmanaged)
+    ├── Events
+    ├── Phones (+ simulations)
+    ├── Webhooks
+    └── Workspaces
+```
+
+## Key changes
+
+- Flat namespace list reorganized into **product-type groups** mirroring Guides (Access, Thermostats, Noise Sensors, Connectors & Automations)
+- Access endpoints grouped into the same two-tier split: **Access Grants & Identity** and **Smart Locks / ACS**
+- Cross-cutting platform resources (Devices, Events, Webhooks, etc.) grouped under **Platform**
+- **Rate Limits** added (moved from Guides → Developer Tools)
+- Requires codegen changes to `summary.ts` to produce the new grouping