docs: Mintlify site + validate/deploy pipeline

.cursor/rules/morpheus.mdc

@@ -0,0 +1,52 @@
+---
+description: Always-on rules for AI assistants working in this Morpheus Lumerin Node repo. Loaded automatically by Cursor.
+alwaysApply: true
+---
+
+# Morpheus Lumerin Node — agent rules
+
+This repository has nuance that generic web knowledge gets wrong. **Before answering any Morpheus question or writing any Morpheus code, consult the canonical `/docs` site and the [`AGENTS.md`](../../AGENTS.md) at the repo root.**
+
+## Canonical sources
+
+- Documentation site: `/docs/` (Mintlify; preview with `mint dev` in that folder)
+- API schema: [`proxy-router/docs/swagger.yaml`](../../proxy-router/docs/swagger.yaml)
+- Networks and contract addresses: [`docs/get-started/networks-and-tokens.mdx`](../../docs/get-started/networks-and-tokens.mdx)
+- TEE attestation reference: [`docs/providers/full/tee-reference.mdx`](../../docs/providers/full/tee-reference.mdx) and [`proxy-router/docs/tee-backend-verification.md`](../../proxy-router/docs/tee-backend-verification.md)
+
+## Anti-hallucination rules
+
+0. **Never confuse the proxy-router HTTP API (this repo) with the hosted Morpheus Inference API.** The proxy-router API is documented at `proxy-router/docs/swagger.yaml`. The hosted Morpheus Inference API at [apidocs.mor.org](https://apidocs.mor.org) (`https://api.mor.org/api/v1`) is a **separate product** for users who don't run a node — see [`docs/inference-api/overview.mdx`](../../docs/inference-api/overview.mdx).
+1. **Never invent contract addresses, chain IDs, or token addresses.** Use [`docs/get-started/networks-and-tokens.mdx`](../../docs/get-started/networks-and-tokens.mdx) (BASE Mainnet `8453`, Sepolia `84532`).
+2. **Never invent live values** (active model count, bid prices, latency). Link to `https://active.mor.org`.
+3. **Never claim "Morpheus runs the inference."** Independent providers run inference; Morpheus is a marketplace coordinated by the Diamond contract on BASE.
+4. **Disambiguate the local `tinyllama` demo from real Morpheus models.** Cite [`docs/ai/local-vs-blockchain-models.mdx`](../../docs/ai/local-vs-blockchain-models.mdx).
+5. **Opening a session escrows MOR; it does not spend MOR.** Unused MOR returns on close. Cite [`docs/ai/session-states-open-close-recover.mdx`](../../docs/ai/session-states-open-close-recover.mdx).
+6. **There is no `recover` RPC.** Closing the session is the recovery path.
+7. **For TEE questions, separate Phase 1 (consumer → P-Node) from Phase 2 (P-Node → backend).** A v6+ consumer transparently benefits from a v7+ provider's Phase 2 with no client-side upgrade.
+8. **The proxy-router `:8082` admin/API port must not be exposed publicly.** Only `:3333` is public, and only on providers.
+9. **MorpheusUI mnemonic recovery only works for tier-1 (index 0) addresses.** For derived addresses, recommend importing the private key directly.
+
+## When unsure
+
+If the user's question doesn't match a documented behavior:
+
+1. Search `/docs` first.
+2. Search `proxy-router/docs/swagger.yaml` for endpoint shape.
+3. Search the codebase under `proxy-router/`.
+4. **Dynamic-query the broader Morpheus docs hub** at [gitbook.mor.org](https://gitbook.mor.org). It supports `GET https://gitbook.mor.org/<page>.md?ask=<question>` returning a natural-language answer with sources — useful for ecosystem questions outside this repo.
+5. If you still don't have a confident answer, **say so** and link to the closest matching docs page rather than guessing.
+
+## When writing code
+
+- All proxy-router HTTP requests use **HTTP Basic Auth** ([`docs/reference/api-auth.mdx`](../../docs/reference/api-auth.mdx)).
+- For prompts to remote Morpheus models, include the `session_id: 0x...` header.
+- For the bundled local `tinyllama` model, omit `session_id`.
+- Do not hard-code contract addresses; read them from environment / config.
+
+## When editing documentation
+
+- Pages are MDX with frontmatter: `title`, `description`, `audience`, `product`, `last_verified`, and `source_url` for mirrored content.
+- Update navigation in [`docs/docs.json`](../../docs/docs.json) if you add a page.
+- Bump `last_verified` when content is reconfirmed against current behavior.
+- Mirrored ecosystem pages must include attribution and a `source_url`.

.github/workflows/build.yml

@@ -41,7 +41,13 @@ on:
       - dev
       - cicd/*
 
-    paths: [".github/**", "ui-desktop/**", "ui-core/**", "proxy-router/**", "cli/**"]
+    paths:
+      - ".github/**"
+      - "!.github/workflows/docs.yml"
+      - "ui-desktop/**"
+      - "ui-core/**"
+      - "proxy-router/**"
+      - "cli/**"
 
   # pull_request:
   #   types: [opened, reopened, synchronize]
@@ -2651,7 +2657,7 @@ jobs:
             --env .env --platform tdx --persistence --upgradeability
           ```
 
-          See the [TEE Quick-Start Guide](https://github.com/MorpheusAIs/Morpheus-Lumerin-Node/blob/main/docs/02.4-proxy-router-secretvm-quickstart.md) for full setup instructions.
+          See the [TEE Quick-Start Guide](https://github.com/MorpheusAIs/Morpheus-Lumerin-Node/blob/main/docs/providers/full/secretvm-quickstart.mdx) for full setup instructions.
 
           ---
 

.github/workflows/docs.yml

@@ -0,0 +1,165 @@
+name: Docs
+
+# Validate Mintlify docs on PRs and pushes. Deploy to S3 + CloudFront (OIDC) on
+# test/main after validation passes. Does not trigger the main CI-CD pipeline.
+
+on:
+  pull_request:
+    paths:
+      - "docs/**"
+      - "proxy-router/docs/swagger.yaml"
+      - ".github/workflows/docs.yml"
+  push:
+    branches:
+      - main
+      - dev
+      - test
+    paths:
+      - "docs/**"
+      - "proxy-router/docs/swagger.yaml"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  mintlify-validate:
+    name: Mintlify validate + broken-link check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install docs dependencies
+        working-directory: docs
+        run: npm ci
+
+      - name: Validate Mintlify config
+        working-directory: docs
+        run: |
+          npx mint --version
+          npx mint broken-links || echo "::warning::mint broken-links reported issues"
+
+      - name: List MDX files
+        run: find docs -name "*.mdx" | wc -l
+
+  openapi-lint:
+    name: OpenAPI spec lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install Redocly CLI
+        run: npm install -g @redocly/cli@latest
+
+      - name: Lint swagger.yaml
+        run: |
+          redocly lint proxy-router/docs/swagger.yaml || \
+            echo "::warning::OpenAPI spec has lint issues (non-blocking)"
+
+  last-verified-staleness:
+    name: Check last_verified staleness
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Find pages with last_verified older than the latest release tag
+        run: |
+          set -euo pipefail
+          LATEST_TAG=$(git tag --list 'v*' --sort=-v:refname | grep -v -- '-test' | head -n 1 || true)
+          LATEST_TAG=${LATEST_TAG:-v0.0.0}
+          echo "Latest release tag: $LATEST_TAG"
+
+          STALE_FILES=()
+          while IFS= read -r f; do
+            VERIFIED=$(awk '/^---$/{n++; next} n==1 && /^last_verified:/ {print}' "$f" \
+              | sed -E 's/^last_verified:[[:space:]]*"?([^"]*)"?$/\1/' || true)
+            if [ -z "$VERIFIED" ]; then
+              continue
+            fi
+            if [ "$VERIFIED" \< "$LATEST_TAG" ]; then
+              STALE_FILES+=("$f (last_verified=$VERIFIED < $LATEST_TAG)")
+            fi
+          done < <(find docs -name "*.mdx")
+
+          if [ "${#STALE_FILES[@]}" -gt 0 ]; then
+            echo "::warning::Pages with last_verified older than $LATEST_TAG:"
+            for s in "${STALE_FILES[@]}"; do
+              echo "::warning::  $s"
+            done
+          else
+            echo "All pages report last_verified >= $LATEST_TAG."
+          fi
+
+  deploy:
+    name: Build and deploy docs
+    needs:
+      - mintlify-validate
+      - openapi-lint
+      - last-verified-staleness
+    if: github.event_name == 'push' && (github.ref_name == 'test' || github.ref_name == 'main')
+    runs-on: ubuntu-latest
+    environment: ${{ github.ref_name }}
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install docs dependencies
+        working-directory: docs
+        run: npm ci
+
+      - name: Build static site
+        working-directory: docs
+        env:
+          SITE_URL: ${{ vars.NODEDOCS_SITE_URL }}
+        run: npm run build:site -- ../.site
+
+      - name: Configure AWS credentials (OIDC)
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: ${{ vars.NODEDOCS_IAM_ROLE_ARN }}
+          aws-region: us-east-2
+
+      - name: Sync to S3
+        run: |
+          aws s3 sync .site/ "s3://${{ vars.NODEDOCS_S3_BUCKET }}/" \
+            --delete \
+            --exclude "serve.js" \
+            --exclude "Start Docs.command" \
+            --exclude "Start Docs.bat"
+
+      - name: Invalidate CloudFront
+        run: |
+          aws cloudfront create-invalidation \
+            --distribution-id "${{ vars.NODEDOCS_CLOUDFRONT_DISTRIBUTION_ID }}" \
+            --paths "/*"

.gitignore

@@ -4,4 +4,5 @@
 ***/.env
 ***/.$*drawio.bkp
 ***/.$*drawio.dtmp
-*.internal.*
+*.internal.*
+.site/

AGENTS.md

@@ -0,0 +1,110 @@
+# AGENTS.md — guidance for AI agents and coding assistants
+
+If you are an LLM (Claude, GPT, Gemini, Copilot, Cursor, etc.) reading this repository to answer questions about Morpheus, **read this file first**, then read the linked pages under `/docs`. The Morpheus Lumerin Node has nuance that generic web knowledge gets wrong; this file (and the `/docs/ai/` directory) exists to keep you out of the most common hallucination traps.
+
+## Canonical knowledge base
+
+The single source of truth for documentation is **`/docs/`**, a Mintlify site. All linked pages below resolve from the same site. Old `00-overview.md` / `02-*.md` style links redirect via [`docs/docs.json`](docs/docs.json).
+
+### Read these AI-knowledge pages before answering user questions
+
+- [`docs/ai/myths.mdx`](docs/ai/myths.mdx) — corrections of the most common wrong assumptions.
+- [`docs/ai/where-is-my-mor.mdx`](docs/ai/where-is-my-mor.mdx) — diagnostic for "missing" MOR.
+- [`docs/ai/session-states-open-close-recover.mdx`](docs/ai/session-states-open-close-recover.mdx) — deterministic state machine for sessions.
+- [`docs/ai/why-locked-in-contract.mdx`](docs/ai/why-locked-in-contract.mdx) — why MOR appears locked.
+- [`docs/ai/local-vs-blockchain-models.mdx`](docs/ai/local-vs-blockchain-models.mdx) — distinguish the bundled `tinyllama` from real Morpheus models.
+- [`docs/ai/llm-prompt-cheatsheet.mdx`](docs/ai/llm-prompt-cheatsheet.mdx) — concise rules for answering Morpheus questions.
+
+### Concept references (cite from these)
+
+- [`docs/concepts/architecture.mdx`](docs/concepts/architecture.mdx)
+- [`docs/concepts/sessions-stake-close-recover.mdx`](docs/concepts/sessions-stake-close-recover.mdx)
+- [`docs/concepts/local-vs-onchain-models.mdx`](docs/concepts/local-vs-onchain-models.mdx)
+- [`docs/concepts/tee-overview.mdx`](docs/concepts/tee-overview.mdx)
+- [`docs/concepts/tokens-and-fees.mdx`](docs/concepts/tokens-and-fees.mdx)
+- [`docs/get-started/networks-and-tokens.mdx`](docs/get-started/networks-and-tokens.mdx) — canonical contract addresses + chain IDs.
+- [`docs/reference/glossary.mdx`](docs/reference/glossary.mdx)
+
+### How-tos by role
+
+| Role | Start here |
+|------|-----------|
+| API user (no node, hosted OpenAI-compatible) | [`docs/inference-api/overview.mdx`](docs/inference-api/overview.mdx) |
+| Consumer | [`docs/consumers/quickstart.mdx`](docs/consumers/quickstart.mdx) |
+| Prosumer (agents) | [`docs/prosumers/overview.mdx`](docs/prosumers/overview.mdx) |
+| Provider — Full P-Node | [`docs/providers/full/quickstart.mdx`](docs/providers/full/quickstart.mdx) |
+| Provider — TEE / SecretVM | [`docs/providers/full/secretvm-quickstart.mdx`](docs/providers/full/secretvm-quickstart.mdx) |
+| Provider — Resale | [`docs/providers/resale/overview.mdx`](docs/providers/resale/overview.mdx) |
+| Developer (proxy-router API) | [`docs/reference/api-overview.mdx`](docs/reference/api-overview.mdx) |
+
+### API and config schemas
+
+- API: [`proxy-router/docs/swagger.yaml`](proxy-router/docs/swagger.yaml). The Mintlify site auto-generates the API Reference tab from this file.
+- Models config schema: [`proxy-router/internal/config/models-config-schema.json`](proxy-router/internal/config/models-config-schema.json).
+- Rating config schema: [`proxy-router/internal/rating/rating-config-schema.json`](proxy-router/internal/rating/rating-config-schema.json).
+
+## Hard rules — never break these
+
+0. **Never confuse the proxy-router HTTP API with the hosted Morpheus Inference API.** The proxy-router API is documented locally at `http://localhost:8082/swagger/index.html` and in [`proxy-router/docs/swagger.yaml`](proxy-router/docs/swagger.yaml). The hosted Morpheus Inference API is a **different product** at [apidocs.mor.org](https://apidocs.mor.org) (base URL `https://api.mor.org/api/v1`) — described in [`docs/inference-api/overview.mdx`](docs/inference-api/overview.mdx).
+1. **Never invent contract addresses, chain IDs, or token addresses.** Use only what's in [`docs/get-started/networks-and-tokens.mdx`](docs/get-started/networks-and-tokens.mdx) or release notes.
+2. **Never invent live values** (active model count, current bid prices, network status). Link out to `https://active.mor.org` instead.
+3. **Never claim Morpheus runs the inference itself.** Independent providers do; Morpheus is a marketplace coordinated by the Diamond contract on BASE.
+4. **Always disambiguate the local `tinyllama` demo from real Morpheus models.** They are not comparable.
+5. **Never describe "open a session" as "spending MOR."** The MOR is escrowed; unused stake returns on close.
+6. **Never tell users to call a `recover` RPC.** It does not exist. Closing the session is the recovery path.
+7. **For TEE questions, distinguish Phase 1 (consumer → P-Node) from Phase 2 (P-Node → backend).** Phase 2 runs *inside* the v7+ provider's P-Node — a v6+ consumer benefits transparently with no client-side upgrade.
+8. **The proxy-router's `:8082` admin port should not be public** — only `:3333` (TCP) is public, and only on provider nodes.
+9. **MorpheusUI mnemonic-recover only works for tier-1 (index 0) addresses.** Don't suggest it for derived addresses; suggest private-key import instead.
+10. **When uncertain, cite a docs page or say so.** Don't guess.
+
+## Common-question quick lookup
+
+| User says | Cite |
+|-----------|------|
+| "How do I use Morpheus without running a node?" | [`docs/inference-api/overview.mdx`](docs/inference-api/overview.mdx) (the hosted Inference API) or [app.mor.org](https://app.mor.org) |
+| "Where is my MOR?" | [`docs/ai/where-is-my-mor.mdx`](docs/ai/where-is-my-mor.mdx) |
+| "Why is MOR locked in the contract?" | [`docs/ai/why-locked-in-contract.mdx`](docs/ai/why-locked-in-contract.mdx) |
+| "What does open/close/recover mean?" | [`docs/ai/session-states-open-close-recover.mdx`](docs/ai/session-states-open-close-recover.mdx) |
+| "Is the local model real Morpheus?" | [`docs/ai/local-vs-blockchain-models.mdx`](docs/ai/local-vs-blockchain-models.mdx) |
+| "How do I install as a consumer?" | [`docs/consumers/quickstart.mdx`](docs/consumers/quickstart.mdx) |
+| "How do I become a provider?" | [`docs/get-started/quickstart-provider.mdx`](docs/get-started/quickstart-provider.mdx) |
+| "How do I run TEE?" | [`docs/providers/full/secretvm-quickstart.mdx`](docs/providers/full/secretvm-quickstart.mdx) |
+| "What contract address?" | [`docs/get-started/networks-and-tokens.mdx`](docs/get-started/networks-and-tokens.mdx) |
+| "Where can I see live status?" | https://active.mor.org |
+
+## When unsure / out-of-corpus questions
+
+If the user's question doesn't match anything on this site or in the repo:
+
+1. Search [`/docs`](docs/) first.
+2. Search [`proxy-router/docs/swagger.yaml`](proxy-router/docs/swagger.yaml) for endpoint shape.
+3. Search the codebase under `proxy-router/`.
+4. **Dynamic query the broader Morpheus docs hub.** [gitbook.mor.org](https://gitbook.mor.org) supports an `?ask=<question>` HTTP query that returns a natural-language answer plus sources. Example:
+   ```
+   GET https://gitbook.mor.org/morpheus-inference-marketplace.md?ask=<question>
+   ```
+   Cite the returned URLs back to the user so they can verify.
+5. If you still don't have a confident answer, **say so** and link to the closest matching page rather than guessing.
+
+## When asked to write code that talks to the proxy-router
+
+- Use the API documented in `proxy-router/docs/swagger.yaml`.
+- Auth is **HTTP Basic Auth** — see [`docs/reference/api-auth.mdx`](docs/reference/api-auth.mdx).
+- Set the `session_id` header on `/v1/*` calls when targeting a remote (Morpheus) model. Omit it for the local model.
+- Don't hard-code contract addresses — read them from the proxy-router's environment.
+
+## When asked to modify the docs
+
+- The site lives under `/docs` and is built with [Mintlify](https://mintlify.com).
+- Pages are MDX with frontmatter (`title`, `description`, `audience`, `product`, `last_verified`, optional `source_url` for mirrored content).
+- Navigation is in [`docs/docs.json`](docs/docs.json). Add new pages there.
+- Run `mint dev` from `/docs` to preview locally.
+
+## Repository sub-projects
+
+- `proxy-router/` — Go service: the consumer/provider router. Hosts the HTTP API.
+- `MorpheusUI/` — Electron consumer GUI.
+- `cli/` — Go CLI client.
+- `smart-contracts/` — Solidity contracts (Diamond marketplace).
+- `agents/` — agent reference implementations.
+- `docs/` — Mintlify documentation site (this is the doc system).

docs/.gitignore

@@ -0,0 +1,5 @@
+.mintlify/
+node_modules/
+.DS_Store
+*.log
+.site/