docs: strengthen AEO discovery and validation

.github/actions/setup-environment/action.yml

@@ -11,7 +11,7 @@ runs:
   using: "composite"
   steps:
     - name: Setup Node.js
-      uses: actions/setup-node@v4
+      uses: actions/setup-node@v5
       with:
         node-version: ${{ inputs.node-version }}
         cache: 'npm'
@@ -22,4 +22,8 @@ runs:
 
     - name: Build
       shell: bash
-      run: npm run build
+      run: npm run build
+
+    - name: Validate built site
+      shell: bash
+      run: npm run validate:site

.github/dependabot.yml

@@ -0,0 +1,18 @@
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: "/"
+    schedule:
+      interval: weekly
+    labels:
+      - dependencies
+      - documentation
+    open-pull-requests-limit: 5
+
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    labels:
+      - dependencies
+      - ci

.github/workflows/main.yml

@@ -21,7 +21,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           fetch-depth: 0
 
@@ -44,4 +44,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v4

.github/workflows/pr-checks.yml

@@ -10,7 +10,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Setup Environment
         uses: ./.github/actions/setup-environment

README.md

@@ -5,21 +5,21 @@ This website is built using [Docusaurus](https://docusaurus.io/), a modern stati
 ### Installation
 
 ```
-$ yarn
+$ npm ci
 ```
 
 ### Local Development
 
 ```
-$ yarn start
+$ npm run start
 ```
 
 This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
 
 ### Build
 
 ```
-$ yarn build
+$ npm run build
 ```
 
 This command generates static content into the `build` directory and can be served using any static contents hosting service.
@@ -29,13 +29,13 @@ This command generates static content into the `build` directory and can be serv
 Using SSH:
 
 ```
-$ USE_SSH=true yarn deploy
+$ USE_SSH=true npm run deploy
 ```
 
 Not using SSH:
 
 ```
-$ GIT_USER=<Your GitHub username> yarn deploy
+$ GIT_USER=<Your GitHub username> npm run deploy
 ```
 
 If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

cspell.json

@@ -33,6 +33,8 @@
     "millicores",
     "webui",
     "libp2p",
+    "llms",
+    "trino",
     "duckdb",
     "myvalue",
     "oom"

docs/guides/compute-over-data-architecture.mdx

@@ -0,0 +1,76 @@
+---
+title: Compute-over-data architecture across remote sites and object stores
+description: Design a Bacalhau deployment that places work near data without hiding operational boundaries.
+---
+
+import StructuredData from '@site/src/components/StructuredData'
+
+<StructuredData
+  title="Compute-over-data architecture across remote sites and object stores"
+  description="A practical architecture guide for running Bacalhau jobs near remote-site, object-store, and edge data."
+  path="/docs/guides/compute-over-data-architecture/"
+  faq={[
+    { question: 'Does Bacalhau automatically make remote data local?', answer: 'No. A compute node needs authorized access to an input. Bacalhau can schedule a task to a suitable node, but storage connectivity and credentials remain an operator responsibility.' },
+    { question: 'Can one Bacalhau network span multiple locations?', answer: 'Yes. Nodes can be organized across locations, but operators should test connectivity, resource capacity, placement constraints, and failure recovery for their topology.' },
+  ]}
+/>
+
+# Compute-over-data architecture across remote sites and object stores
+
+Compute-over-data means choosing a compute location with practical access to the input, instead of automatically centralizing every dataset. In Bacalhau, an orchestrator receives a job and compute nodes execute Docker or WASM tasks; inputs and outputs are described as part of the job. See the [architecture overview](/docs/overview/architecture/) for component responsibilities.
+
+## Reference topology
+
+| Layer | Responsibility | Design question |
+| --- | --- | --- |
+| Orchestrator | Receives jobs and coordinates state | Who operates its availability, identity, and audit trail? |
+| Compute nodes | Execute isolated task environments | Which sites can reach each dataset and meet runtime needs? |
+| Input storage | Provides files, objects, or URLs | Which credentials and network paths are permitted? |
+| Result publisher | Stores artifacts and results | Where may outputs reside and who can retrieve them? |
+
+Keep the network boundary explicit: object storage is not automatically mounted simply because a node is nearby, and a job constraint does not change a storage bucket policy.
+
+## Model the job rather than the marketing diagram
+
+This example uses a URL input and local publisher so the data path is visible. Substitute your controlled source and publisher only after reviewing the relevant source and result specifications.
+
+```yaml
+Type: batch
+Count: 1
+Tasks:
+  - Name: summarize
+    Engine:
+      Type: docker
+      Params:
+        Image: alpine:3.21
+        Parameters: [sh, -c, "wc -l /inputs/events.txt > /outputs/line-count.txt"]
+    InputSources:
+      - Alias: events
+        Target: /inputs/events.txt
+        Source:
+          Type: urlDownload
+          Params:
+            URL: https://example.org/events.txt
+    Publisher:
+      Type: local
+    ResultPaths:
+      - Name: outputs
+        Path: /outputs
+```
+
+Submit it with `bacalhau job run job.yaml`, then use `bacalhau job describe <job-id>` to inspect execution state. The [quick start](/docs/getting-started/quick-start/) shows the same imperative and declarative workflow.
+
+## Tradeoffs and controls
+
+| Requirement | Useful Bacalhau mechanism | Boundary outside Bacalhau |
+| --- | --- | --- |
+| Keep work at a site | Node labels and job constraints | Network segmentation and physical/data residency controls |
+| Limit a task's inputs | Explicit input sources | Storage IAM, object ACLs, and secret distribution |
+| Preserve results | Result paths and a publisher | Retention, encryption, and downstream access policy |
+| Recover from a failure | Job state and operator monitoring | Site disaster recovery and capacity planning |
+
+Read the [constraint specification](/docs/specifications/job/constraint/), [input-source specification](/docs/specifications/job/input-source/), and [publishing results guide](/docs/guides/publishing-results/) before choosing production values.
+
+## Limitations
+
+This architecture does not eliminate data transfer: container images, inputs, logs, and results can still cross a network. Instrument those paths, test loss of a site or storage endpoint, and define whether a no-match constraint must fail closed or trigger an approved fallback.

docs/guides/compute-over-data-comparison.mdx

@@ -0,0 +1,62 @@
+---
+title: Bacalhau compared with Kubernetes, KubeEdge, Nomad, Ray, and Trino
+description: Choose a distributed-computing tool by data location, workload type, and operating model.
+---
+
+import StructuredData from '@site/src/components/StructuredData'
+
+<StructuredData
+  title="Bacalhau compared with Kubernetes, KubeEdge, Nomad, Ray, and Trino"
+  description="A technical comparison of Bacalhau with Kubernetes, KubeEdge, Nomad, Ray, and Trino for compute-over-data workloads."
+  path="/docs/guides/compute-over-data-comparison/"
+  faq={[
+    { question: 'Is Bacalhau a replacement for Kubernetes?', answer: 'No. Bacalhau schedules data-aware jobs across its compute nodes. Kubernetes remains a strong choice for long-running container platforms and their surrounding ecosystem.' },
+    { question: 'When is Bacalhau a better fit than a query engine?', answer: 'Use Bacalhau when you need to run arbitrary container or WASM tasks near distributed data. Use a query engine when its SQL execution model and connectors meet the requirement.' },
+  ]}
+/>
+
+# Bacalhau compared with Kubernetes, KubeEdge, Nomad, Ray, and Trino
+
+Bacalhau is an independent, Apache-2.0-licensed distributed compute project. It coordinates container and WASM jobs across compute nodes, with placement informed by available resources, job requirements, and data access. It is not a renamed Kubernetes distribution, a data warehouse, or a managed cloud service.
+
+## Start with the workload boundary
+
+| Tool | Primary strength | Prefer it when | Tradeoff to plan for |
+| --- | --- | --- | --- |
+| Bacalhau | Running arbitrary jobs close to distributed data | Batch, ops, daemon, or service workloads need data-aware placement | You operate the nodes, storage credentials, and job policy |
+| Kubernetes | General-purpose container platform | You need a large ecosystem for long-lived applications | Data locality is normally modeled through your storage and scheduling design |
+| KubeEdge | Kubernetes extension for edge nodes | Existing Kubernetes control-plane patterns must extend to devices | It retains Kubernetes operational complexity |
+| Nomad | Simple workload scheduling | A homogeneous fleet and broad workload types are the main concern | Data-source-aware job design remains your responsibility |
+| Ray | Distributed Python and AI workloads | Actors, tasks, and Python-native ML are central | It is not a general data-locality control plane |
+| Trino | Federated SQL queries | The problem can be expressed in SQL over supported sources | It does not run arbitrary containerized transformations |
+
+The comparison is not a feature checklist. A common design is to retain Kubernetes or Nomad for application services, use a SQL engine for interactive analysis, and use Bacalhau for a bounded job that must execute where data can be accessed.
+
+## A small, auditable starting point
+
+Label nodes only with facts your operators maintain, then constrain a job to the required boundary:
+
+```bash
+bacalhau serve --compute -c Labels="region=eu-west,data-boundary=eu"
+
+bacalhau docker run \
+  --constraints "region=eu-west" \
+  --constraints "data-boundary=eu" \
+  --input https://example.org/manifest.json:/inputs/manifest.json \
+  --output results:/outputs \
+  --publisher local \
+  alpine:3.21 sh -c 'wc -c /inputs/manifest.json > /outputs/count.txt'
+```
+
+This does not prove legal compliance by itself. Confirm network routes, identity, storage policy, encryption, and the actual location of every input and output with the systems that own those controls.
+
+## Decision checks
+
+1. Read the [architecture overview](/docs/overview/architecture/) and decide which process owns orchestration and compute.
+2. Model inputs explicitly using the [job input-source specification](/docs/specifications/job/input-source/), rather than assuming a URL is local.
+3. Use [labels and constraints](/docs/guides/labels-and-constraints/) for placement rules, and test no-match behavior before production.
+4. Define result handling with [result paths](/docs/specifications/job/result-path/) and [publishing results](/docs/guides/publishing-results/).
+
+## Limitations
+
+Data proximity can reduce unnecessary transfers, but it cannot make an unavailable dataset accessible or turn labels into an enforcement system. Measure transfer volume and execution time in your environment; do not infer either from this comparison.

docs/guides/data-locality-and-sovereignty.mdx

@@ -0,0 +1,60 @@
+---
+title: Data locality, sovereignty, bandwidth, and egress patterns
+description: Use explicit job placement and storage design to evaluate data-locality requirements.
+---
+
+import StructuredData from '@site/src/components/StructuredData'
+
+<StructuredData
+  title="Data locality, sovereignty, bandwidth, and egress patterns"
+  description="A practical guide to data locality and sovereignty patterns for Bacalhau jobs, including their operational limits."
+  path="/docs/guides/data-locality-and-sovereignty/"
+  faq={[
+    { question: 'Does data locality guarantee data sovereignty?', answer: 'No. Locality is an architectural property. Sovereignty and compliance also depend on law, contracts, access controls, storage policy, network paths, and operational evidence.' },
+    { question: 'How can a Bacalhau job express a location preference?', answer: 'Operators can label compute nodes and submit a job with matching constraints. The labels must be truthful and backed by controls outside the scheduler.' },
+  ]}
+/>
+
+# Data locality, sovereignty, bandwidth, and egress patterns
+
+Data locality is a design decision about where inputs are accessed and work runs. Data sovereignty is broader: it concerns legal, contractual, operational, and technical controls around data. Bacalhau can help express compute placement through node labels and job constraints, but it cannot certify compliance or infer the location of a remote source.
+
+## Choose the pattern that matches the boundary
+
+| Pattern | Use it when | What to verify |
+| --- | --- | --- |
+| Site-local processing | A site hosts the data and compute | Node labels, local access path, output location, and offline behavior |
+| Region-scoped processing | Data and workers must stay within an approved region | Storage endpoint, DNS and network routes, credentials, and failover region |
+| Object-store-adjacent processing | Large objects are reachable from selected workers | Actual byte transfer, IAM scope, result publisher, and cost model |
+| Centralized processing | A controlled central copy is acceptable | Ingest policy, egress cost, retention, and recovery objectives |
+
+## Make placement explicit
+
+Start a compute node with operator-maintained labels, then require them in the job:
+
+```bash
+bacalhau serve --compute -c Labels="residency=ca,site=toronto"
+
+bacalhau docker run \
+  --constraints "residency=ca" \
+  --constraints "site=toronto" \
+  --input https://example.org/public-records.csv:/input/records.csv \
+  --output locality-results:/outputs \
+  --publisher local \
+  alpine:3.21 sh -c 'sha256sum /input/records.csv > /outputs/checksum.txt'
+```
+
+The command is intentionally simple: it proves that a constrained job can execute and publish an output. It does not prove that an HTTPS endpoint, container registry, log system, or operator workstation stayed in the same jurisdiction.
+
+## Controls that belong together
+
+| Goal | Bacalhau configuration | Complementary control |
+| --- | --- | --- |
+| Direct work to suitable nodes | Labels and [constraints](/docs/guides/labels-and-constraints/) | Change control for labels and capacity |
+| Describe a data path | [Input sources](/docs/specifications/job/input-source/) and [tasks](/docs/specifications/job/task/) | Storage IAM, network policy, and credential rotation |
+| Retain artifacts safely | [Result paths](/docs/specifications/job/result-path/) and a publisher | Encryption, retention, and downstream authorization |
+| Bound a workload lifecycle | [Job type](/docs/specifications/job/type/) and [timeouts](/docs/specifications/job/timeouts/) | Monitoring, incident response, and business continuity |
+
+## Limitations and audit evidence
+
+For each production job, retain the submitted specification, selected node, input and output endpoints, identities used, timing, and transfer measurements. Review these against your jurisdictional and contractual requirements. Bacalhau's [architecture](/docs/overview/architecture/) explains the scheduling components, while your organization remains responsible for the surrounding enforcement and evidence.

docs/guides/edge-orchestration-buyers-guide.mdx

@@ -0,0 +1,62 @@
+---
+title: Technical buyer's guide to distributed edge orchestration
+description: Evaluate edge orchestration by placement control, workload lifecycle, data access, and operability.
+---
+
+import StructuredData from '@site/src/components/StructuredData'
+
+<StructuredData
+  title="Technical buyer's guide to distributed edge orchestration"
+  description="A technical evaluation framework for distributed edge orchestration and Bacalhau workload placement."
+  path="/docs/guides/edge-orchestration-buyers-guide/"
+  faq={[
+    { question: 'What should an edge orchestration evaluation prove?', answer: 'It should prove placement, data access, failure behavior, observability, identity, and result handling using representative sites and workloads.' },
+    { question: 'Can Bacalhau run long-lived workloads?', answer: 'Bacalhau supports multiple job types, including batch, ops, daemon, and service. Select a type based on lifecycle and test it under the operational conditions you expect.' },
+  ]}
+/>
+
+# Technical buyer's guide to distributed edge orchestration
+
+An edge orchestrator is useful only when it makes an operating boundary clearer: where code runs, which data it can reach, how it is observed, and what happens when a site is unavailable. Bacalhau is an Apache-2.0 open-source project for orchestrating Docker and WASM workloads across compute nodes; it does not replace your device-management, identity, or storage systems.
+
+## Evaluation matrix
+
+| Evaluation area | Questions to ask | Bacalhau evidence to inspect |
+| --- | --- | --- |
+| Placement | Can a workload target an approved region or capability? | [Labels and constraints](/docs/guides/labels-and-constraints/) and a deliberate no-match test |
+| Lifecycle | Is the workload batch, ops, daemon, or service? | [Job type specification](/docs/specifications/job/type/) |
+| Inputs and outputs | Are every source and result path explicit? | [Input sources](/docs/specifications/job/input-source/) and [result paths](/docs/specifications/job/result-path/) |
+| Runtime | Which images, parameters, resources, and network assumptions apply? | [Task specification](/docs/specifications/job/task/) and [network specification](/docs/specifications/job/network/) |
+| Operations | Who sees job state and acts on failures? | `bacalhau job describe`, logs, and your monitoring system |
+
+## Pilot design
+
+Begin with two sites that have different data or network conditions. Give nodes factual labels, submit a small workload with explicit constraints, then compare job state and result location. Do not begin by connecting production data.
+
+```bash
+bacalhau serve --compute -c Labels="site=plant-a,accelerator=false"
+
+bacalhau docker run \
+  --constraints "site=plant-a" \
+  --input https://example.org/telemetry.csv:/input/telemetry.csv \
+  --output pilot-results:/outputs \
+  --publisher local \
+  alpine:3.21 sh -c 'wc -l /input/telemetry.csv > /outputs/rows.txt'
+```
+
+Record the node identity, job ID, input access method, result path, elapsed time, transfer measurements, and the behavior when the matching node is unavailable. This turns a pilot into reproducible evidence rather than a demo.
+
+## Selection tradeoffs
+
+| If you prioritize | Design implication |
+| --- | --- |
+| Strict site boundaries | Combine constraints with network, storage, and identity enforcement; constraints alone are insufficient |
+| Low-touch operations | Favor a small, repeatable node configuration and a narrowly scoped pilot |
+| Heterogeneous hardware | Label only verified capabilities and test each runtime image on its target architecture |
+| Fast centralized analytics | A data warehouse or SQL engine may be a better primary tool than edge orchestration |
+
+The [quick start](/docs/getting-started/quick-start/) is a safe local starting point. Move to a multi-site design only after validating the [architecture](/docs/overview/architecture/), job timeouts, resource limits, and recovery expectations.
+
+## Limitations
+
+No orchestration tool can establish compliance or availability alone. Verify device patching, physical access, connectivity, secrets, storage policy, and incident response with the owners of those controls.

docusaurus.config.ts

@@ -19,11 +19,13 @@ const config: Config = {
   projectName: 'docs', // Usually your repo name.
 
   onBrokenLinks: 'throw',
-  onBrokenMarkdownLinks: 'throw',
   onBrokenAnchors: 'throw',
   onDuplicateRoutes: 'throw',
   markdown: {
     format: 'detect',
+    hooks: {
+      onBrokenMarkdownLinks: 'throw',
+    },
   },
   i18n: {
     defaultLocale: 'en',