Move 12 files to match SUMMARY.md nesting and fix path validator

GitBook derives published URLs from SUMMARY.md tree nesting, not file
paths. Files nested under a parent in SUMMARY.md must live in the
parent's directory. Moved 10 brand-guide get-started pages into their
parent directories (e.g., get-started-with-ecobee-thermostats.md into
ecobee-thermostats/) and 2 guides files.

Also extended validate-paths to check that nested SUMMARY.md entries
have file paths under their parent's directory, catching URL/path
mismatches.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: louis-pre

codegen/validate-links.ts

@@ -93,12 +93,7 @@ function checkAbsoluteUrl(file: string, line: number, rawUrl: string): void {
   }
 }
 
-function checkRelativeLink(
-  file: string,
-  line: number,
-  rawLink: string,
-  { allowCrossSection = false } = {},
-): void {
+function checkRelativeLink(file: string, line: number, rawLink: string): void {
   // Strip GitBook "mention" hint and anchor
   const linkPath = rawLink.replace(/ "mention"$/, '').split('#')[0]
   if (linkPath == null || linkPath === '') return
@@ -136,9 +131,6 @@ function checkRelativeLink(
   }
 
   // Check that relative links don't cross site section boundaries
-  // (HTML href links are allowed to cross sections in GitBook)
-  if (allowCrossSection) return
-
   const sourceSection = findSiteSection(file)
   const targetSection = findSiteSection(resolved)
   if (
@@ -178,11 +170,11 @@ for (const file of files) {
       checkRelativeLink(file, i + 1, rawLink)
     }
 
-    // Check HTML href links (relative, cross-section allowed)
+    // Check HTML href links (relative)
     for (const match of lineText.matchAll(htmlRelativeLinkPattern)) {
       const rawLink = match[1]
       if (rawLink == null) continue
-      checkRelativeLink(file, i + 1, rawLink, { allowCrossSection: true })
+      checkRelativeLink(file, i + 1, rawLink)
     }
 
     // Check HTML href links (absolute docs.seam.co URLs)

codegen/validate-paths.ts

@@ -18,6 +18,16 @@ function slugify(heading: string): string {
     .trim()
 }
 
+function slugFromPath(linkPath: string): string {
+  return linkPath
+    .replace(/README\.md$/, '')
+    .replace(/\.md$/, '')
+    .replace(/\/$/, '')
+    .split('/')
+    .filter(Boolean)
+    .pop() ?? ''
+}
+
 interface PathMismatch {
   section: string
   line: number
@@ -37,6 +47,11 @@ for (const section of siteSections) {
 
   let currentGroup: string | null = null
 
+  // Track nesting: each entry is { level, slug, path }
+  // GitBook builds URLs by joining ancestor slugs, so child file paths
+  // should be under their parent's directory.
+  const parentStack: Array<{ level: number; slug: string; path: string }> = []
+
   for (let i = 0; i < lines.length; i++) {
     const lineText = lines[i]
     if (lineText == null) continue
@@ -48,7 +63,14 @@ for (const section of siteSections) {
       continue
     }
 
-    for (const match of lineText.matchAll(summaryLinkPattern)) {
+    // Only process list items
+    const stripped = lineText.trimStart()
+    if (!stripped.startsWith('* [')) continue
+
+    const indent = lineText.length - stripped.length
+    const level = Math.floor(indent / 2)
+
+    for (const match of stripped.matchAll(summaryLinkPattern)) {
       const title = match[1] ?? ''
       const linkPath = match[2] ?? ''
 
@@ -79,6 +101,49 @@ for (const section of siteSections) {
           reason: `Path should start with "${currentGroup}/" (listed under "## ${currentGroup}")`,
         })
       }
+
+      // Check 3: nested items should have paths under their parent's directory.
+      // GitBook builds published URLs from the SUMMARY.md tree, so a child
+      // nested under a parent gets a URL like /parent-slug/child-slug.
+      // The file path must match this structure.
+      // Trim stack to current level
+      while (parentStack.length > 0) {
+        const top = parentStack[parentStack.length - 1]
+        if (top != null && top.level >= level) parentStack.pop()
+        else break
+      }
+
+      const slug = slugFromPath(linkPath)
+      const parent =
+        parentStack.length > 0
+          ? parentStack[parentStack.length - 1]
+          : undefined
+
+      if (parent != null) {
+        // The parent's path determines the expected directory prefix.
+        // e.g., parent path "access_codes/simulate/README.md" means
+        // children should start with "access_codes/simulate/".
+        const parentDir = parent.path
+          .replace(/README\.md$/, '')
+          .replace(/\.md$/, '/')
+        if (!linkPath.startsWith(parentDir)) {
+          const publishedUrl =
+            section.urlPrefix +
+            '/' +
+            [...parentStack.map((p) => p.slug), slug].join('/')
+          mismatches.push({
+            section: section.name,
+            line: i + 1,
+            title,
+            path: linkPath,
+            reason: `Path should start with "${parentDir}" to match published URL ${publishedUrl}`,
+          })
+        }
+      }
+
+      if (slug !== '') {
+        parentStack.push({ level, slug, path: linkPath })
+      }
     }
   }
 }

docs/brand-guides/2n-intercom-systems/get-started-with-2n-intercoms.md

@@ -575,11 +575,11 @@ Now that you've completed this guide, you can try to connect a real 2N device. T
 
 In addition, if you'd like to explore other aspects of Seam, here is a list of helpful resources:
 
-* [Yale Getting Started Guide](../get-started-with-yale-locks.md)
-* [August Getting Started Guide](../get-started-with-august-locks.md)
+* [Yale Getting Started Guide](../yale-locks/get-started-with-yale-locks.md)
+* [August Getting Started Guide](../august-locks/get-started-with-august-locks.md)
 * [Schlage Getting Started Guide](../schlage-locks/get-started-with-schlage-locks.md)
 * [SmartThings Getting Started Guide](../smartthings-hubs-+-devices/get-started-with-smartthings-hubs-+-smart-locks.md)
-* [Minut Getting Started Guide](../get-started-with-minut-sensors.md)
+* [Minut Getting Started Guide](../minut-sensors/get-started-with-minut-sensors.md)
 * [Receiving webhook](https://docs.seam.co/latest/developer-tools/webhooks) for [device events](https://docs.seam.co/latest/api/events/list)
 * [Core Concepts](https://docs.seam.co/latest/core-concepts/overview)
 

docs/brand-guides/33-lock-devices/README.md

@@ -60,7 +60,7 @@ To control 33 Lock devices using Seam, you must prompt owners of these devices t
 
 ## Troubleshooting
 
-For errors and warnings that are relevant to 33 Lock devices, see [Troubleshooting](../ttlock-locks.md#troubleshooting) in the TTLock device integration guide.
+For errors and warnings that are relevant to 33 Lock devices, see [Troubleshooting](../ttlock-locks/#troubleshooting) in the TTLock device integration guide.
 
 ***
 

docs/brand-guides/README.md

@@ -20,7 +20,7 @@ To find the integration guide for each of your devices or systems, see the follo
 
 ## Smart Locks
 
-<table data-view="cards"><thead><tr><th align="center"></th><th data-hidden></th><th data-hidden></th><th data-hidden data-card-cover data-type="files"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td align="center"><strong>2N Intercom Systems</strong></td><td></td><td></td><td><a href=".gitbook/assets/2n-logo.png">2n-logo.png</a></td><td><a href="2n-intercom-systems/">2n-intercom-systems</a></td></tr><tr><td align="center"><strong>33 Lock Devices</strong></td><td></td><td></td><td><a href=".gitbook/assets/33-lock-logo.png">33-lock-logo.png</a></td><td><a href="33-lock-devices/">33-lock-devices</a></td></tr><tr><td align="center"><strong>4SUITES Locks</strong></td><td></td><td></td><td><a href=".gitbook/assets/4suites-logo.png">4suites-logo.png</a></td><td><a href="4suites-locks/">4suites-locks</a></td></tr><tr><td align="center"><strong>Akiles Locks</strong></td><td></td><td></td><td><a href=".gitbook/assets/akiles-logo.png">akiles-logo.png</a></td><td><a href="akiles-locks/">akiles-locks</a></td></tr><tr><td align="center"><strong>August Locks</strong></td><td></td><td></td><td><a href="../guides/.gitbook/assets/august-logo.png">august-logo.png</a></td><td><a href="august-locks.md">august-locks.md</a></td></tr><tr><td align="center"><strong>dormakaba Oracode Locks</strong></td><td></td><td></td><td><a href=".gitbook/assets/dormakaba-logo.png">dormakaba-logo.png</a></td><td><a href="dormakaba-oracode-locks/">dormakaba-oracode-locks</a></td></tr><tr><td align="center"><strong>iglooHome Locks</strong></td><td></td><td></td><td><a href=".gitbook/assets/igloohome-logo.png">igloohome-logo.png</a></td><td><a href="igloohome-locks/">igloohome-locks.md</a></td></tr><tr><td align="center"><strong>Kwikset Locks</strong></td><td></td><td></td><td><a href=".gitbook/assets/kwikset-logo.png">kwikset-logo.png</a></td><td><a href="kwikset-locks.md">kwikset-locks.md</a></td></tr><tr><td align="center"><strong>Lockly Locks</strong></td><td></td><td></td><td><a href=".gitbook/assets/lockly-logo.png">lockly-logo.png</a></td><td><a href="lockly-locks/">lockly-locks</a></td></tr><tr><td align="center"><strong>Nuki Locks</strong></td><td></td><td></td><td><a href=".gitbook/assets/nuki-logo.png">nuki-logo.png</a></td><td><a href="nuki-locks.md">nuki-locks.md</a></td></tr><tr><td align="center"><strong>Salto KS Locks</strong></td><td></td><td></td><td><a href=".gitbook/assets/salto-logo.png">salto-logo.png</a></td><td><a href="salto-locks.md">salto-locks.md</a></td></tr><tr><td align="center"><strong>Schlage Locks</strong></td><td></td><td></td><td><a href=".gitbook/assets/schlage-logo.png">schlage-logo.png</a></td><td><a href="schlage-locks/">get-started-with-schlage-locks.md</a></td></tr><tr><td align="center"><strong>SmartThings Hubs + Smart Locks</strong></td><td></td><td></td><td><a href=".gitbook/assets/smartthings-logo.png">smartthings-logo.png</a></td><td><a href="smartthings-hubs-+-devices/">smartthings-hubs-+-devices</a></td></tr><tr><td align="center"><strong>Tedee Locks</strong></td><td></td><td></td><td><a href=".gitbook/assets/tedee-logo.png">tedee-logo.png</a></td><td><a href="tedee-locks/">tedee-locks</a></td></tr><tr><td align="center"><strong>TTLock Locks</strong></td><td></td><td></td><td><a href=".gitbook/assets/ttlock-logo.png">ttlock-logo.png</a></td><td><a href="ttlock-locks.md">ttlock-locks.md</a></td></tr><tr><td align="center"><strong>Wyze Locks</strong></td><td></td><td></td><td><a href=".gitbook/assets/wyze-logo.png">wyze-logo.png</a></td><td><a href="wyze-locks.md">wyze-locks.md</a></td></tr><tr><td align="center"><strong>Yale Locks</strong></td><td></td><td></td><td><a href=".gitbook/assets/yale-logo.png">yale-logo.png</a></td><td><a href="yale-locks.md">yale-locks.md</a></td></tr></tbody></table>
+<table data-view="cards"><thead><tr><th align="center"></th><th data-hidden></th><th data-hidden></th><th data-hidden data-card-cover data-type="files"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td align="center"><strong>2N Intercom Systems</strong></td><td></td><td></td><td><a href=".gitbook/assets/2n-logo.png">2n-logo.png</a></td><td><a href="2n-intercom-systems/">2n-intercom-systems</a></td></tr><tr><td align="center"><strong>33 Lock Devices</strong></td><td></td><td></td><td><a href=".gitbook/assets/33-lock-logo.png">33-lock-logo.png</a></td><td><a href="33-lock-devices/">33-lock-devices</a></td></tr><tr><td align="center"><strong>4SUITES Locks</strong></td><td></td><td></td><td><a href=".gitbook/assets/4suites-logo.png">4suites-logo.png</a></td><td><a href="4suites-locks/">4suites-locks</a></td></tr><tr><td align="center"><strong>Akiles Locks</strong></td><td></td><td></td><td><a href=".gitbook/assets/akiles-logo.png">akiles-logo.png</a></td><td><a href="akiles-locks/">akiles-locks</a></td></tr><tr><td align="center"><strong>August Locks</strong></td><td></td><td></td><td><a href="../guides/.gitbook/assets/august-logo.png">august-logo.png</a></td><td><a href="august-locks/">august-locks.md</a></td></tr><tr><td align="center"><strong>dormakaba Oracode Locks</strong></td><td></td><td></td><td><a href=".gitbook/assets/dormakaba-logo.png">dormakaba-logo.png</a></td><td><a href="dormakaba-oracode-locks/">dormakaba-oracode-locks</a></td></tr><tr><td align="center"><strong>iglooHome Locks</strong></td><td></td><td></td><td><a href=".gitbook/assets/igloohome-logo.png">igloohome-logo.png</a></td><td><a href="igloohome-locks/">igloohome-locks.md</a></td></tr><tr><td align="center"><strong>Kwikset Locks</strong></td><td></td><td></td><td><a href=".gitbook/assets/kwikset-logo.png">kwikset-logo.png</a></td><td><a href="kwikset-locks/">kwikset-locks.md</a></td></tr><tr><td align="center"><strong>Lockly Locks</strong></td><td></td><td></td><td><a href=".gitbook/assets/lockly-logo.png">lockly-logo.png</a></td><td><a href="lockly-locks/">lockly-locks</a></td></tr><tr><td align="center"><strong>Nuki Locks</strong></td><td></td><td></td><td><a href=".gitbook/assets/nuki-logo.png">nuki-logo.png</a></td><td><a href="nuki-locks/">nuki-locks.md</a></td></tr><tr><td align="center"><strong>Salto KS Locks</strong></td><td></td><td></td><td><a href=".gitbook/assets/salto-logo.png">salto-logo.png</a></td><td><a href="salto-locks/">salto-locks.md</a></td></tr><tr><td align="center"><strong>Schlage Locks</strong></td><td></td><td></td><td><a href=".gitbook/assets/schlage-logo.png">schlage-logo.png</a></td><td><a href="schlage-locks/">get-started-with-schlage-locks.md</a></td></tr><tr><td align="center"><strong>SmartThings Hubs + Smart Locks</strong></td><td></td><td></td><td><a href=".gitbook/assets/smartthings-logo.png">smartthings-logo.png</a></td><td><a href="smartthings-hubs-+-devices/">smartthings-hubs-+-devices</a></td></tr><tr><td align="center"><strong>Tedee Locks</strong></td><td></td><td></td><td><a href=".gitbook/assets/tedee-logo.png">tedee-logo.png</a></td><td><a href="tedee-locks/">tedee-locks</a></td></tr><tr><td align="center"><strong>TTLock Locks</strong></td><td></td><td></td><td><a href=".gitbook/assets/ttlock-logo.png">ttlock-logo.png</a></td><td><a href="ttlock-locks/">ttlock-locks.md</a></td></tr><tr><td align="center"><strong>Wyze Locks</strong></td><td></td><td></td><td><a href=".gitbook/assets/wyze-logo.png">wyze-logo.png</a></td><td><a href="wyze-locks/">wyze-locks.md</a></td></tr><tr><td align="center"><strong>Yale Locks</strong></td><td></td><td></td><td><a href=".gitbook/assets/yale-logo.png">yale-logo.png</a></td><td><a href="yale-locks/">yale-locks.md</a></td></tr></tbody></table>
 
 ***
 
@@ -32,13 +32,13 @@ To find the integration guide for each of your devices or systems, see the follo
 
 ## Thermostats
 
-<table data-view="cards"><thead><tr><th align="center"></th><th data-hidden></th><th data-hidden></th><th data-hidden data-card-cover data-type="files"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td align="center"><strong>ecobee Thermostats</strong></td><td></td><td></td><td><a href="../guides/.gitbook/assets/ecobee-logo.png">ecobee-logo.png</a></td><td><a href="ecobee-thermostats.md">ecobee-thermostats.md</a></td></tr><tr><td align="center"><strong>Google Nest Thermostats</strong></td><td></td><td></td><td><a href="../guides/.gitbook/assets/nest-logo.png">nest-logo.png</a></td><td><a href="google-nest-thermostats/">google-nest-thermostats</a></td></tr><tr><td align="center"><strong>Honeywell Resideo Thermostats</strong></td><td></td><td></td><td><a href=".gitbook/assets/honeywell-logo.png">honeywell-logo.png</a></td><td><a href="honeywell-thermostats/">honeywell-thermostats</a></td></tr><tr><td align="center"><strong>Sensi Thermostats</strong></td><td></td><td></td><td><a href="../guides/.gitbook/assets/sensi-logo.png">sensi-logo.png</a></td><td><a href="sensi-thermostats/">sensi-thermostats</a></td></tr><tr><td align="center"><strong>SmartThings Hubs + Thermostats</strong></td><td></td><td></td><td><a href=".gitbook/assets/smartthings-logo.png">smartthings-logo.png</a></td><td><a href="smartthings-hubs-+-devices/">smartthings-hubs-+-devices</a></td></tr></tbody></table>
+<table data-view="cards"><thead><tr><th align="center"></th><th data-hidden></th><th data-hidden></th><th data-hidden data-card-cover data-type="files"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td align="center"><strong>ecobee Thermostats</strong></td><td></td><td></td><td><a href="../guides/.gitbook/assets/ecobee-logo.png">ecobee-logo.png</a></td><td><a href="ecobee-thermostats/">ecobee-thermostats.md</a></td></tr><tr><td align="center"><strong>Google Nest Thermostats</strong></td><td></td><td></td><td><a href="../guides/.gitbook/assets/nest-logo.png">nest-logo.png</a></td><td><a href="google-nest-thermostats/">google-nest-thermostats</a></td></tr><tr><td align="center"><strong>Honeywell Resideo Thermostats</strong></td><td></td><td></td><td><a href=".gitbook/assets/honeywell-logo.png">honeywell-logo.png</a></td><td><a href="honeywell-thermostats/">honeywell-thermostats</a></td></tr><tr><td align="center"><strong>Sensi Thermostats</strong></td><td></td><td></td><td><a href="../guides/.gitbook/assets/sensi-logo.png">sensi-logo.png</a></td><td><a href="sensi-thermostats/">sensi-thermostats</a></td></tr><tr><td align="center"><strong>SmartThings Hubs + Thermostats</strong></td><td></td><td></td><td><a href=".gitbook/assets/smartthings-logo.png">smartthings-logo.png</a></td><td><a href="smartthings-hubs-+-devices/">smartthings-hubs-+-devices</a></td></tr></tbody></table>
 
 ***
 
 ## Noise sensors
 
-<table data-view="cards"><thead><tr><th align="center"></th><th data-hidden></th><th data-hidden></th><th data-hidden data-card-cover data-type="files"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td align="center"><strong>Minut Sensors</strong></td><td></td><td></td><td><a href=".gitbook/assets/minut-logo.png">minut-logo.png</a></td><td><a href="minut-sensors.md">minut-sensors.md</a></td></tr><tr><td align="center"><strong>NoiseAware Sensors</strong></td><td></td><td></td><td><a href=".gitbook/assets/noiseaware-logo.png">noiseaware-logo.png</a></td><td><a href="noiseaware-sensors.md">noiseaware-sensors.md</a></td></tr></tbody></table>
+<table data-view="cards"><thead><tr><th align="center"></th><th data-hidden></th><th data-hidden></th><th data-hidden data-card-cover data-type="files"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td align="center"><strong>Minut Sensors</strong></td><td></td><td></td><td><a href=".gitbook/assets/minut-logo.png">minut-logo.png</a></td><td><a href="minut-sensors/">minut-sensors.md</a></td></tr><tr><td align="center"><strong>NoiseAware Sensors</strong></td><td></td><td></td><td><a href=".gitbook/assets/noiseaware-logo.png">noiseaware-logo.png</a></td><td><a href="noiseaware-sensors/">noiseaware-sensors.md</a></td></tr></tbody></table>
 
 ***