Add link snapshot contract + CI enforcement

.github/workflows/check-docs.yaml

@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
       - name: Check markdown links
         uses: gaurav-nelson/github-action-markdown-link-check@v1
         # use <!-- markdown-link-check-disable-next-line --> to skip next line

.github/workflows/check-link-snapshot.yaml

@@ -0,0 +1,23 @@
+name: Check link snapshot
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "22"
+          cache: "npm"
+      - run: npm ci
+      - name: Verify snapshot contract
+        run: npm run snapshot:check

.github/workflows/check-notebooks.yaml

@@ -27,10 +27,10 @@ jobs:
         working-directory: notebooks
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: '3.12'
 

.github/workflows/run-notebooks.yaml

@@ -22,7 +22,7 @@ jobs:
       notebooks: ${{ steps.list.outputs.notebooks }}
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: List notebooks
         id: list
@@ -35,10 +35,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: '3.12'
 
@@ -63,10 +63,10 @@ jobs:
         notebook: ${{ fromJSON(needs.discover-notebooks.outputs.notebooks) }}
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: '3.12'
 

.husky/pre-commit

@@ -0,0 +1,6 @@
+#!/usr/bin/env sh
+# Regenerate link-snapshot.yaml when docs structure may have changed.
+if git diff --cached --name-only | grep -qE '^(docs\.json|.*\.mdx?$)'; then
+  npm run snapshot:update --silent || exit 1
+  git add link-snapshot.yaml
+fi

CLAUDE.md

@@ -182,6 +182,23 @@ grep -r '/>' --include="*.mdx" --include="*.md" .
 3. Check if you need to target light/dark mode specifically
 4. For icons using mask-image, set `background-color` instead of `color`
 
+## Link Snapshot Contract
+
+`link-snapshot.yaml` is an append-only ledger of every URL the docs site has promised to keep resolving. The pre-commit hook keeps it in sync; [`check-link-snapshot.yaml`](.github/workflows/check-link-snapshot.yaml) fails any PR that would make a recorded URL stop resolving. Run `npm install` once to install the hook.
+
+A URL in `active` resolves if any of these are true:
+1. It is in the `docs.json` navigation tree.
+2. A matching `.mdx`/`.md` file exists under `lfm/`, `leap/`, `examples/`, or `deployment/`.
+3. It matches a `redirects[*].source` (literal or `:slug*` prefix) whose destination itself resolves (recursive, max depth 5).
+
+When CI flags a URL, pick one (in order of preference):
+
+1. **Add a redirect** in `docs.json` — best when a substitute page exists.
+2. **Deprecate in place** — remove the page from `docs.json` navigation but leave the `.mdx` on disk (the URL stays served, just undiscoverable). Add a `<Note>` deprecation banner.
+3. **Mark deleted** — move the URL from `active` to `deleted` in `link-snapshot.yaml`. Bare URLs are fine; commit history is the record. Use only when no substitute exists.
+
+Don't edit `active` by hand — moving a URL to `deleted` causes the next `snapshot:update` (which the pre-commit hook runs automatically) to drop it from `active`. Manual commands: `npm run snapshot:update` to regenerate, `npm run snapshot:check` to run what CI runs. Both call `scripts/generateLinkSnapshot.ts` via `tsx`; new TypeScript scripts should follow the same `tsx scripts/<file>.ts` pattern.
+
 ## Git Commits
 
 - Never create a single monolithic commit for multi-step work. Break commits into logical units (e.g., infrastructure/scaffolding, feature A, feature B, fixes).

README.md

@@ -29,6 +29,7 @@ This is the **official documentation repository** for Liquid AI. It contains com
   - [Making Changes](#making-changes)
   - [Submitting Changes](#submitting-changes)
   - [Link Check](#link-check)
+  - [Link Snapshot](#link-snapshot)
 - [License](#license)
 
 ---
@@ -148,6 +149,7 @@ Navigate to the docs directory and start the development server:
 
 ```bash
 cd docs
+npm i
 mintlify dev
 ```
 
@@ -173,8 +175,22 @@ For more details on Mintlify setup and configuration, visit the [official Mintli
 
 The [`check-docs.yaml`](.github/workflows/check-docs.yaml) workflow has a `check-link` job that examine markdown links. Customize the config in [`link-check.json`](./link-check.json). If a link cannot be accessed (e.g. Github private repo), add the URL pattern to the `ignorePatterns` array.
 
+### Link Snapshot
+
+[`link-snapshot.yaml`](./link-snapshot.yaml) records every URL the docs site has served. The [`check-link-snapshot.yaml`](.github/workflows/check-link-snapshot.yaml) workflow fails any PR that would make a recorded URL stop resolving. Run `npm install` once to install the pre-commit hook that keeps the snapshot in sync.
+
+How it works:
+
+- `link-snapshot.yaml` has two sections: `active:` (URLs the site is currently committed to keep serving) and `deleted:` (URLs intentionally retired).
+- The pre-commit hook regenerates the file whenever `docs.json` or any `.mdx`/`.md` file is staged.
+- The `active:` section is **append-only** — new URLs are added when pages are created, but existing entries are never silently dropped, even after you delete the underlying page.
+- CI re-checks every URL in `active:` on each PR. A URL is satisfied if it's still in the navigation, still on disk, or reachable via a redirect chain.
+- The only way to retire a URL is to move it from `active:` to `deleted:` by hand. This forces every removal to be a deliberate choice — redirect, deprecate-but-keep, or formally retire.
+
+See [CLAUDE.md](./CLAUDE.md#link-snapshot-contract) for the remediation paths and the full resolution algorithm.
+
 ---
 
 ## License
 
-This documentation is licensed under [Attribution-ShareAlike 4.0 International](./LICENSE).
+This documentation is licensed under [Attribution-ShareAlike 4.0 International](./LICENSE).

link-snapshot.yaml

@@ -0,0 +1,175 @@
+# Auto-managed by scripts/generateLinkSnapshot.ts.
+# `active` is append-only — pre-commit adds new URLs but never removes them.
+# To intentionally retire a URL without a redirect, move it from `active` to
+# `deleted`. The CI check skips entries listed under `deleted`.
+active:
+  - /customization/finetuning-frameworks/datasets
+  - /customization/finetuning-frameworks/leap-finetune
+  - /customization/finetuning-frameworks/trl
+  - /customization/finetuning-frameworks/unsloth
+  - /customization/getting-started/connect-ai-tools
+  - /customization/getting-started/welcome
+  - /customization/tools/workbench
+  - /deployment/getting-started/connect-ai-tools
+  - /deployment/getting-started/welcome
+  - /deployment/gpu-inference/baseten
+  - /deployment/gpu-inference/fal
+  - /deployment/gpu-inference/modal
+  - /deployment/gpu-inference/sglang
+  - /deployment/gpu-inference/transformers
+  - /deployment/gpu-inference/vllm
+  - /deployment/on-device/android/advanced-features
+  - /deployment/on-device/android/ai-agent-usage-guide
+  - /deployment/on-device/android/android-quick-start-guide
+  - /deployment/on-device/android/cloud-ai-comparison
+  - /deployment/on-device/android/constrained-generation
+  - /deployment/on-device/android/conversation-generation
+  - /deployment/on-device/android/function-calling
+  - /deployment/on-device/android/messages-content
+  - /deployment/on-device/android/model-loading
+  - /deployment/on-device/android/openai-client
+  - /deployment/on-device/android/utilities
+  - /deployment/on-device/android/voice-assistant
+  - /deployment/on-device/ios/advanced-features
+  - /deployment/on-device/ios/ai-agent-usage-guide
+  - /deployment/on-device/ios/cloud-ai-comparison
+  - /deployment/on-device/ios/constrained-generation
+  - /deployment/on-device/ios/conversation-generation
+  - /deployment/on-device/ios/function-calling
+  - /deployment/on-device/ios/ios-quick-start-guide
+  - /deployment/on-device/ios/messages-content
+  - /deployment/on-device/ios/model-loading
+  - /deployment/on-device/ios/openai-client
+  - /deployment/on-device/ios/utilities
+  - /deployment/on-device/ios/voice-assistant
+  - /deployment/on-device/leap-sdk-changelog
+  - /deployment/on-device/llama-cpp
+  - /deployment/on-device/lm-studio
+  - /deployment/on-device/mlx
+  - /deployment/on-device/ollama
+  - /deployment/on-device/onnx
+  - /deployment/on-device/sdk/advanced-features
+  - /deployment/on-device/sdk/ai-agent-usage-guide
+  - /deployment/on-device/sdk/cloud-ai-comparison
+  - /deployment/on-device/sdk/constrained-generation
+  - /deployment/on-device/sdk/conversation-generation
+  - /deployment/on-device/sdk/desktop-platforms
+  - /deployment/on-device/sdk/function-calling
+  - /deployment/on-device/sdk/messages-content
+  - /deployment/on-device/sdk/model-loading
+  - /deployment/on-device/sdk/openai-client
+  - /deployment/on-device/sdk/quick-start
+  - /deployment/on-device/sdk/utilities
+  - /deployment/on-device/sdk/voice-assistant
+  - /deployment/tools/model-bundling/authentication
+  - /deployment/tools/model-bundling/bundle-creation
+  - /deployment/tools/model-bundling/bundle-management
+  - /deployment/tools/model-bundling/changelog
+  - /deployment/tools/model-bundling/configuration
+  - /deployment/tools/model-bundling/data-privacy
+  - /deployment/tools/model-bundling/download
+  - /deployment/tools/model-bundling/quick-start
+  - /deployment/tools/model-bundling/reference
+  - /docs/fine-tuning/datasets
+  - /docs/fine-tuning/trl
+  - /docs/fine-tuning/unsloth
+  - /docs/fine-tuning/workbench
+  - /docs/getting-started/connect-ai-tools
+  - /docs/getting-started/welcome
+  - /docs/inference/baseten-deployment
+  - /docs/inference/fal-deployment
+  - /docs/inference/llama-cpp
+  - /docs/inference/lm-studio
+  - /docs/inference/mlx
+  - /docs/inference/modal-deployment
+  - /docs/inference/ollama
+  - /docs/inference/onnx
+  - /docs/inference/sglang
+  - /docs/inference/transformers
+  - /docs/inference/vllm
+  - /examples/android/leap-koog-agent
+  - /examples/android/recipe-generator-constrained-output
+  - /examples/android/slogan-generator
+  - /examples/android/vision-language-model-example
+  - /examples/android/web-content-summarizer
+  - /examples/connect-ai-tools
+  - /examples/customize-models/car-maker-identification
+  - /examples/customize-models/home-assistant
+  - /examples/customize-models/satellite-vlm
+  - /examples/customize-models/wildfire-prevention
+  - /examples/index
+  - /examples/laptop-examples/audio-car-cockpit
+  - /examples/laptop-examples/audio-to-text-in-real-time
+  - /examples/laptop-examples/browser-control
+  - /examples/laptop-examples/flight-search-assistant
+  - /examples/laptop-examples/invoice-extractor-tool-with-liquid-nanos
+  - /examples/laptop-examples/lfm2-english-to-korean
+  - /examples/laptop-examples/meeting-summarization
+  - /examples/web/audio-webgpu-demo
+  - /examples/web/hand-voice-racer
+  - /examples/web/vl-webgpu-demo
+  - /leap/edge-sdk/overview
+  - /lfm/fine-tuning
+  - /lfm/fine-tuning/datasets
+  - /lfm/fine-tuning/trl
+  - /lfm/fine-tuning/unsloth
+  - /lfm/getting-started/connect-ai-tools
+  - /lfm/getting-started/model-license
+  - /lfm/getting-started/welcome
+  - /lfm/help/connect-ai-tools
+  - /lfm/help/contributing
+  - /lfm/help/faqs
+  - /lfm/help/model-license
+  - /lfm/help/troubleshooting
+  - /lfm/inference
+  - /lfm/inference/llama-cpp
+  - /lfm/inference/lm-studio
+  - /lfm/inference/mlx
+  - /lfm/inference/ollama
+  - /lfm/inference/transformers
+  - /lfm/inference/vllm
+  - /lfm/key-concepts/chat-template
+  - /lfm/key-concepts/text-generation-and-prompting
+  - /lfm/key-concepts/tool-use
+  - /lfm/models/audio-models
+  - /lfm/models/complete-library
+  - /lfm/models/lfm2-1.2b
+  - /lfm/models/lfm2-1.2b-extract
+  - /lfm/models/lfm2-1.2b-rag
+  - /lfm/models/lfm2-1.2b-tool
+  - /lfm/models/lfm2-2.6b
+  - /lfm/models/lfm2-2.6b-exp
+  - /lfm/models/lfm2-2.6b-transcript
+  - /lfm/models/lfm2-24b-a2b
+  - /lfm/models/lfm2-350m
+  - /lfm/models/lfm2-350m-enjp-mt
+  - /lfm/models/lfm2-350m-extract
+  - /lfm/models/lfm2-350m-math
+  - /lfm/models/lfm2-350m-pii-extract-jp
+  - /lfm/models/lfm2-700m
+  - /lfm/models/lfm2-8b-a1b
+  - /lfm/models/lfm2-audio-1.5b
+  - /lfm/models/lfm2-colbert-350m
+  - /lfm/models/lfm2-vl-1.6b
+  - /lfm/models/lfm2-vl-3b
+  - /lfm/models/lfm2-vl-450m
+  - /lfm/models/lfm25-1.2b-base
+  - /lfm/models/lfm25-1.2b-instruct
+  - /lfm/models/lfm25-1.2b-jp
+  - /lfm/models/lfm25-1.2b-thinking
+  - /lfm/models/lfm25-350m
+  - /lfm/models/lfm25-audio-1.5b
+  - /lfm/models/lfm25-vl-1.6b
+  - /lfm/models/lfm25-vl-450m
+  - /lfm/models/liquid-nanos
+  - /lfm/models/text-models
+  - /lfm/models/vision-models
+# Examples of `deleted` entries (uncomment and adapt):
+#
+# deleted:
+#   # Minimal form — git history is the canonical record of why this was retired:
+#   - /lfm/old/experimental-thing
+#   # Or, if you want the reason inline:
+#   - url: /lfm/another-old-thing
+#     reason: "Page retired in DOC-12; no substitute exists."
+deleted: []