Centralize the shared BYOS specification

.github/workflows/docs.yml

@@ -0,0 +1,46 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      # Dead links fail the build: a broken anchor here means an ADR in an
+      # implementation repo is citing a section that no longer exists.
+      - run: npm run build
+      - uses: actions/upload-pages-artifact@v3
+        if: github.ref == 'refs/heads/main'
+        with:
+          path: .vitepress/dist
+
+  deploy:
+    if: github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -0,0 +1,9 @@
+node_modules/
+.vitepress/dist/
+.vitepress/cache/
+
+# Entirely generated by scripts/gen-llms.ts at build time: llms.txt, llms-full.txt,
+# and raw markdown mirrors of every page.
+public/
+
+.DS_Store

.vitepress/config.ts

@@ -0,0 +1,86 @@
+import { withMermaid } from 'vitepress-plugin-mermaid'
+
+// Deployed as a GitHub Pages project site, so every URL is prefixed with the repo name.
+const base = '/byos-docs/'
+
+export default withMermaid({
+  base,
+  title: 'BYOS',
+  description: 'Bring Your Own Solver — shared specification',
+  cleanUrls: true,
+  lastUpdated: true,
+
+  // README.md is the site home too, so the entry point cannot drift between
+  // GitHub and the published site.
+  rewrites: { 'README.md': 'index.md' },
+
+  // A broken link here means an ADR in an implementation repo is about to cite a
+  // section that no longer exists. Fail the build instead.
+  ignoreDeadLinks: false,
+
+  themeConfig: {
+    nav: [
+      { text: 'Overview', link: '/overview' },
+      { text: 'Design document', link: '/design-document' },
+      { text: 'Sub-solver guide', link: '/guides/sub-solver-integration' },
+      { text: 'Glossary', link: '/glossary' },
+    ],
+
+    sidebar: [
+      {
+        text: 'Overview',
+        items: [{ text: 'What is BYOS', link: '/overview' }],
+      },
+      {
+        text: 'Specification',
+        items: [
+          { text: 'Design document', link: '/design-document' },
+          { text: 'Contracts reference', link: '/contracts' },
+          { text: 'Service architecture', link: '/service' },
+          { text: 'Glossary', link: '/glossary' },
+        ],
+      },
+      {
+        text: 'Guides',
+        items: [{ text: 'Sub-solver integration', link: '/guides/sub-solver-integration' }],
+      },
+      {
+        text: 'Operations',
+        items: [{ text: 'SLO targets', link: '/operations/slo-targets' }],
+      },
+      {
+        text: 'Security',
+        items: [
+          {
+            text: 'Trampoline / settlement isolation',
+            link: '/security/trampoline-settlement-isolation',
+          },
+        ],
+      },
+      {
+        text: 'CoW protocol reference',
+        collapsed: false,
+        items: [
+          { text: 'Fee collection', link: '/reference/cow-fee-collection' },
+          { text: 'Solver slashing policy', link: '/reference/cow-solver-slashing-policy' },
+          { text: 'Solver auctions', link: '/reference/solver-auctions' },
+          { text: 'Solver CIPs', link: '/reference/solver-cips' },
+        ],
+      },
+    ],
+
+    socialLinks: [{ icon: 'github', link: 'https://github.com/bleu/byos-docs' }],
+
+    search: { provider: 'local' },
+
+    editLink: {
+      pattern: 'https://github.com/bleu/byos-docs/edit/main/:path',
+      text: 'Edit this page on GitHub',
+    },
+
+    footer: {
+      message:
+        'This specification is normative. Where an implementation disagrees with it, the implementation is wrong.',
+    },
+  },
+})

README.md

@@ -0,0 +1,53 @@
+# BYOS documentation
+
+The shared, normative specification for **BYOS (Bring Your Own Solver)** — a bonded CoW Protocol solver whose solutions are sourced from a permissionless set of external sub-solvers.
+
+Published at **https://bleu.github.io/byos-docs**.
+
+## What lives here, and what does not
+
+This repo owns everything that constrains more than one implementation, or that a reader outside bleu needs: the design, the vocabulary, the sub-solver integration path, and the CoW protocol background all of it rests on.
+
+Each implementation repo keeps its own ADRs. An ADR records *why* a decision was made; this repo records *what is true*. An ADR does not restate the specification — it cites a section of it:
+
+```
+Spec: docs/shared/design-document.md#penalties
+      https://bleu.github.io/byos-docs/design-document#penalties
+```
+
+The local path is what agents, offline readers, and `grep` use, and it is pinned to the commit being audited. The URL is for anyone browsing on github.com, which cannot follow links into a submodule.
+
+| Repo | Owns |
+|---|---|
+| [bleu/byos-contracts](https://github.com/bleu/byos-contracts) | Escrow, Trampoline, TrampolineFactory; Solidity style, contract-side rationale |
+| [bleu/byos-service](https://github.com/bleu/byos-service) | The Rust service; the proposal API OpenAPI document; Rust engineering conventions |
+| [bleu/byos-service-ts](https://github.com/bleu/byos-service-ts) | The TypeScript service |
+
+## Where to start
+
+**New to BYOS?** — [What is BYOS](overview.md). The problem it solves, how it works at a high level, what sub-solvers get and don't get, why proposals get discarded, and the slashing policy.
+
+**Auditors** — [the design document](design-document.md), top to bottom. It is normative: where an implementation disagrees with it, the implementation is wrong, unless the document carries a dated revision note saying otherwise. The status table at the top says what is built today. The adversarial isolation proof is in [trampoline / settlement isolation](security/trampoline-settlement-isolation.md). The [contracts reference](contracts.md) and [service architecture](service.md) pages consolidate interfaces, interactions, and design decisions from the implementation repos.
+
+**Sub-solvers** — [the integration guide](guides/sub-solver-integration.md). It is the path from zero to a settled proposal, and it links into the design document for anything normative.
+
+**CoW team** — the design document's [order flow](design-document.md#order-flow) and [gas accounting](design-document.md#gas) sections cover everything that touches the protocol. Our reading of CoW's own mechanics is under [fee collection](reference/cow-fee-collection.md), [slashing policy](reference/cow-solver-slashing-policy.md), [auctions](reference/solver-auctions.md), and [CIPs](reference/solver-cips.md); corrections welcome.
+
+**Agents** — read [`glossary.md`](glossary.md) and the design document sections relevant to your task. Inside an implementation repo these files are on disk at `docs/shared/`, pinned to the commit you are working on. From the web, [`/llms.txt`](https://bleu.github.io/byos-docs/llms.txt) indexes the corpus and [`/llms-full.txt`](https://bleu.github.io/byos-docs/llms-full.txt) is all of it in one fetch.
+
+## Using it from an implementation repo
+
+```bash
+git submodule add https://github.com/bleu/byos-docs docs/shared
+git submodule update --init --recursive   # in an existing clone
+```
+
+`docs/shared/` is read-only. Changes go through a PR here, then a pointer bump in the consuming repo.
+
+## Local development
+
+```bash
+npm install
+npm run dev      # http://localhost:5173/byos-docs/
+npm run build    # also regenerates llms.txt and llms-full.txt
+```