feat: make Access Grants the front door for granting access

Access Grants are GA and are now the default, recommended way to grant
access to any physical space, irrespective of locking hardware. The docs
previously framed Access Grants as ACS-only (entrances/spaces), which
led developers and AI assistants (including the Seam MCP) to wrongly
steer standalone-smart-lock users to the legacy Access Codes API.

- Add new top-level "Use Cases" nav section with a "Granting Access"
  decision page (which API to use, with the recommended ladder:
  one device -> multiple devices/spaces -> ACS entrances)
- Move Access Grants guides under use-cases/granting-access/ with
  .gitbook.yaml redirects for all old URLs
- Rewrite Access Grants overview: universal framing, device_ids first
  in the "Where" table, devices-first teaching order
- Add "Creating an Access Grant Using Devices" guide (device_ids +
  code access method, capability checks)
- Rewrite Quick Start step 3 around access_grants.create with a code
  access method instead of lock/unlock
- Lead the access_grants/create API reference with a devices-only
  code sample (new sample in code-sample-definitions)
- Add "Grant Access" card first on the docs landing page
- Teach validate-links to accept URLs covered by .gitbook.yaml
  redirects (upstream @seamapi/types still links old URLs; resolved
  via redirects until the upstream descriptions are updated)

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

Author: sybohy

.gitbook.yaml

@@ -23,3 +23,13 @@ redirects:
   core-concepts/connect-webviews: core-concepts/connect-webviews/README.md
   capability-guides/access-systems/understanding-acs-differences: capability-guides/access-systems/README.md
   capability-guides/thermostats/creating-and-managing-climate-schedules: capability-guides/thermostats/creating-and-managing-thermostat-schedules.md
+  capability-guides/access-grants: use-cases/granting-access/access-grants/README.md
+  capability-guides/access-grants/access-grant-quick-start: use-cases/granting-access/access-grants/access-grant-quick-start.md
+  capability-guides/access-grants/creating-an-access-grant-using-entrances: use-cases/granting-access/access-grants/creating-an-access-grant-using-entrances.md
+  capability-guides/access-grants/creating-an-access-grant-using-spaces: use-cases/granting-access/access-grants/creating-an-access-grant-using-spaces.md
+  capability-guides/access-grants/delivering-access-methods: use-cases/granting-access/access-grants/delivering-access-methods.md
+  capability-guides/access-grants/reservation-access-grants: use-cases/granting-access/access-grants/reservation-access-grants.md
+  capability-guides/access-grants/retrieving-access-grants-and-access-methods: use-cases/granting-access/access-grants/retrieving-access-grants-and-access-methods.md
+  capability-guides/access-grants/updating-an-access-grant: use-cases/granting-access/access-grants/updating-an-access-grant.md
+  capability-guides/access-grants/revoking-an-access-method: use-cases/granting-access/access-grants/revoking-an-access-method.md
+  capability-guides/access-grants/deleting-an-access-grant: use-cases/granting-access/access-grants/deleting-an-access-grant.md

codegen/data/code-sample-definitions/access_grants.yaml

@@ -1,4 +1,36 @@
 ---
+- title: Create an Access Grant for devices
+  description:
+    Creates a new Access Grant that gives a user identity a PIN code on one
+    or more devices, such as standalone smart locks.
+  request:
+    path: /access_grants/create
+    parameters:
+      user_identity_id: e3d736c1-540d-4d10-83e5-9a4e135453b4
+      device_ids:
+        - 6ba7b811-9dad-11d1-80b4-00c04fd430c8
+      requested_access_methods:
+        - mode: code
+      starts_at: '2025-06-16T16:54:17.946606Z'
+      ends_at: '2025-06-18T16:54:17.946606Z'
+  response:
+    body:
+      access_grant:
+        access_grant_id: ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b
+        access_method_ids:
+          - a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d
+        created_at: '2025-06-16T16:54:17.946606Z'
+        display_name: My Access Grant
+        ends_at: '2025-06-18T16:54:17.946606Z'
+        requested_access_methods:
+          - display_name: PIN Code Credential
+            mode: code
+            created_at: '2025-06-16T16:54:17.946606Z'
+            created_access_method_ids:
+              - a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d
+        starts_at: '2025-06-16T16:54:17.946606Z'
+        user_identity_id: e3d736c1-540d-4d10-83e5-9a4e135453b4
+        workspace_id: 750fc0bc-4450-4356-8d9f-18c6a3a6b2c7
 - title: Create an Access Grant using spaces
   description: Creates a new Access Grant using space IDs and an existing user identity.
   request:

codegen/validate-links.ts

@@ -1,6 +1,8 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 
+import YAML from 'yaml'
+
 import {
   baseUrl,
   type SiteSection,
@@ -12,6 +14,36 @@ function findSiteSection(filePath: string): SiteSection | undefined {
   return siteSections.find(({ root }) => filePath.startsWith(root + '/'))
 }
 
+// Each site section has its own .gitbook.yaml with a redirects map.
+// A URL covered by a redirect is not broken: GitBook resolves it.
+// (validate-redirects separately ensures every redirect target exists.)
+const sectionConfigPaths: Record<string, string> = {
+  Guides: '.gitbook.yaml',
+  'API Reference': join('docs', 'api-reference', '.gitbook.yaml'),
+  'Brand Guides': join('docs', 'brand-guides', '.gitbook.yaml'),
+}
+
+const sectionRedirects = new Map<string, Set<string>>()
+
+function getSectionRedirects(sectionName: string): Set<string> {
+  const cached = sectionRedirects.get(sectionName)
+  if (cached != null) return cached
+
+  const redirectPaths = new Set<string>()
+  const configPath = sectionConfigPaths[sectionName]
+  if (configPath != null && existsSync(configPath)) {
+    const config = YAML.parse(readFileSync(configPath, 'utf-8')) as {
+      redirects?: Record<string, string>
+    }
+    for (const key of Object.keys(config.redirects ?? {})) {
+      redirectPaths.add(key.replace(/^\//, ''))
+    }
+  }
+
+  sectionRedirects.set(sectionName, redirectPaths)
+  return redirectPaths
+}
+
 const absoluteUrlPattern = new RegExp(
   `${baseUrl.replaceAll('.', '\\.')}[^)"<>\\s]+`,
   'g',
@@ -83,6 +115,11 @@ function checkAbsoluteUrl(file: string, line: number, rawUrl: string): void {
   const targetMd = `${targetRoot}.md`
   const targetReadme = join(targetRoot, 'README.md')
 
+  // A URL covered by a .gitbook.yaml redirect resolves on the published site.
+  if (getSectionRedirects(section.name).has(pagePath.replace(/^\//, ''))) {
+    return
+  }
+
   if (!existsSync(targetMd) && !existsSync(targetReadme)) {
     brokenLinks.push({
       file,