Harden docs reliability and deployment checks

.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Check pull request diff
+        if: github.event_name == 'pull_request'
+        run: git diff --check "${{ github.event.pull_request.base.sha }}...${{ github.sha }}"
+      - name: Check push diff
+        if: github.event_name == 'push'
+        run: |
+          before="${{ github.event.before }}"
+          after="${{ github.sha }}"
+          empty_tree="$(git hash-object -t tree -w /dev/null)"
+          if [ "$before" = "0000000000000000000000000000000000000000" ] ||
+            ! git cat-file -e "$before^{commit}" 2>/dev/null
+          then
+            git diff --check "$empty_tree" "$after"
+          else
+            git diff --check "$before..$after"
+          fi
+      - name: Set up Node.js
+        uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: package-lock.json
+      - name: Install dependencies
+        run: npm ci --ignore-scripts
+      - name: Check repository
+        run: npm run check

.github/workflows/deployment-health.yml

@@ -0,0 +1,27 @@
+name: Deployment health
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  deployment-health:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          persist-credentials: false
+      - name: Set up Node.js
+        uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: package-lock.json
+      - name: Install dependencies
+        run: npm ci --ignore-scripts
+      - name: Check deployment
+        run: npm run check:deploy

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Linkout
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,42 @@
+# Linkout documentation
+
+This repository contains the public documentation site for Linkout and
+`linkout-scraper`, published at [docs.linkout.space](https://docs.linkout.space).
+
+## Development
+
+Use Node.js 22 or newer and install the locked dependencies:
+
+```sh
+npm ci
+```
+
+Start the local development server with `npm start`. To test the production
+site locally, run `npm run build` followed by `npm run serve`.
+
+## Checks
+
+- `npm run check:local` checks the working-tree diff, types, tests, and
+  production build.
+- `npm run check:source` checks live source contracts against the public
+  `linkout-scraper` repository.
+- `npm run check:deps` checks the patched dependency tree and production audit.
+- `npm run check:deploy` checks the live deployment and its TLS certificate.
+- `npm run check` is the complete repository gate: local, dependency, and live
+  source checks. Deployment health remains a separate operational check.
+
+The live source contract check fetches public files from the public
+`linkoutapp/linkout-scraper` repository's `main` branch. It retries transient
+network, timeout, rate-limit, and server failures; a persistent fetch failure or
+contract drift fails the check.
+
+## Contributions and operations
+
+Contributions are accepted only through pull requests. CI runs for pull requests
+and updates to `main`.
+
+The documentation targets a dedicated Vercel project serving
+`docs.linkout.space`. Repository changes do not mutate that project or DNS.
+Maintainers can run the manual **Deployment health** GitHub Actions workflow to
+check the deployed endpoints and TLS certificate outside the normal repository
+gate.

package.json

@@ -3,23 +3,27 @@
   "version": "0.1.0",
   "private": true,
   "description": "Documentation for Linkout and linkout-scraper",
+  "license": "MIT",
   "scripts": {
     "start": "docusaurus start",
     "build": "docusaurus build",
     "clear": "docusaurus clear",
     "serve": "docusaurus serve",
     "typecheck": "tsc",
     "test": "node --test tests/*.test.mjs",
-    "check:deps": "npm ls brace-expansion serialize-javascript uuid --all --silent && npm audit --omit=dev",
+    "check:local": "git diff --check && npm run typecheck && npm test && npm run build",
+    "check:deploy": "node scripts/check-deployment.mjs",
+    "check:deps": "node scripts/check-dependencies.mjs",
     "check:source": "node scripts/check-source-contracts.mjs",
-    "check": "npm run typecheck && npm test && npm run check:deps && npm run check:source && npm run build"
+    "check": "npm run check:local && npm run check:deps && npm run check:source"
   },
   "dependencies": {
     "@docusaurus/core": "3.10.2",
     "@docusaurus/preset-classic": "3.10.2",
     "@docusaurus/theme-mermaid": "3.10.2",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
+    "parse5": "7.3.0",
     "prism-react-renderer": "^2.3.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
@@ -28,6 +32,7 @@
     "@docusaurus/module-type-aliases": "3.10.2",
     "@docusaurus/tsconfig": "3.10.2",
     "@docusaurus/types": "3.10.2",
+    "js-yaml": "4.3.0",
     "typescript": "~5.6.2"
   },
   "overrides": {