Skip to content

Commit 2aea2b8

Browse files
nomadicroguenomadicrogue
authored
docs: Mintlify site + validate/deploy pipeline (#727)
## Summary - Replace legacy `/docs/*.md` with Mintlify MDX site (`docs/docs.json`, role-based navigation, AI knowledge pages, redirects). - Add `AGENTS.md` and `.cursor/rules/morpheus.mdc` for agent/human canonical guidance. - Add unified `docs.yml` workflow: validate on PRs and pushes to `dev`/`test`/`main`; deploy to S3 + CloudFront via GitHub OIDC on `test` and `main` only. - Add docs build toolchain (`mint export`, Pagefind search index, `llms.txt` / `llms-full.txt` generation). - Exclude `docs.yml` from main `build.yml` path triggers so doc-only changes do not start node builds or AWS deploys. ## Test plan - [ ] Merge to `dev`; confirm `Docs` workflow runs validate jobs only (no deploy on `dev`). - [ ] After `test` promotion PR: confirm deploy to https://nodedocs.dev.mor.org - [ ] Spot-check navigation, `/llms.txt`, and Pagefind search on deployed site - [ ] Confirm push with only `docs/**` changes does not trigger main CI-CD pipeline Made with [Cursor](https://cursor.com)
2 parents bbb36fb + bc23a1b commit 2aea2b8

101 files changed

Lines changed: 20494 additions & 2425 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.cursor/rules/morpheus.mdc‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
description: Always-on rules for AI assistants working in this Morpheus Lumerin Node repo. Loaded automatically by Cursor.
3+
alwaysApply: true
4+
---
5+
6+
# Morpheus Lumerin Node — agent rules
7+
8+
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.**
9+
10+
## Canonical sources
11+
12+
- Documentation site: `/docs/` (Mintlify; preview with `mint dev` in that folder)
13+
- API schema: [`proxy-router/docs/swagger.yaml`](../../proxy-router/docs/swagger.yaml)
14+
- Networks and contract addresses: [`docs/get-started/networks-and-tokens.mdx`](../../docs/get-started/networks-and-tokens.mdx)
15+
- 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)
16+
17+
## Anti-hallucination rules
18+
19+
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).
20+
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`).
21+
2. **Never invent live values** (active model count, bid prices, latency). Link to `https://active.mor.org`.
22+
3. **Never claim "Morpheus runs the inference."** Independent providers run inference; Morpheus is a marketplace coordinated by the Diamond contract on BASE.
23+
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).
24+
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).
25+
6. **There is no `recover` RPC.** Closing the session is the recovery path.
26+
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.
27+
8. **The proxy-router `:8082` admin/API port must not be exposed publicly.** Only `:3333` is public, and only on providers.
28+
9. **MorpheusUI mnemonic recovery only works for tier-1 (index 0) addresses.** For derived addresses, recommend importing the private key directly.
29+
30+
## When unsure
31+
32+
If the user's question doesn't match a documented behavior:
33+
34+
1. Search `/docs` first.
35+
2. Search `proxy-router/docs/swagger.yaml` for endpoint shape.
36+
3. Search the codebase under `proxy-router/`.
37+
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.
38+
5. If you still don't have a confident answer, **say so** and link to the closest matching docs page rather than guessing.
39+
40+
## When writing code
41+
42+
- All proxy-router HTTP requests use **HTTP Basic Auth** ([`docs/reference/api-auth.mdx`](../../docs/reference/api-auth.mdx)).
43+
- For prompts to remote Morpheus models, include the `session_id: 0x...` header.
44+
- For the bundled local `tinyllama` model, omit `session_id`.
45+
- Do not hard-code contract addresses; read them from environment / config.
46+
47+
## When editing documentation
48+
49+
- Pages are MDX with frontmatter: `title`, `description`, `audience`, `product`, `last_verified`, and `source_url` for mirrored content.
50+
- Update navigation in [`docs/docs.json`](../../docs/docs.json) if you add a page.
51+
- Bump `last_verified` when content is reconfirmed against current behavior.
52+
- Mirrored ecosystem pages must include attribution and a `source_url`.

‎.github/workflows/build.yml‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,13 @@ on:
4141
- dev
4242
- cicd/*
4343

44-
paths: [".github/**", "ui-desktop/**", "ui-core/**", "proxy-router/**", "cli/**"]
44+
paths:
45+
- ".github/**"
46+
- "!.github/workflows/docs.yml"
47+
- "ui-desktop/**"
48+
- "ui-core/**"
49+
- "proxy-router/**"
50+
- "cli/**"
4551

4652
# pull_request:
4753
# types: [opened, reopened, synchronize]
@@ -2651,7 +2657,7 @@ jobs:
26512657
--env .env --platform tdx --persistence --upgradeability
26522658
```
26532659
2654-
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.
2660+
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.
26552661
26562662
---
26572663

‎.github/workflows/docs.yml‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
name: Docs
2+
3+
# Validate Mintlify docs on PRs and pushes. Deploy to S3 + CloudFront (OIDC) on
4+
# test/main after validation passes. Does not trigger the main CI-CD pipeline.
5+
6+
on:
7+
pull_request:
8+
paths:
9+
- "docs/**"
10+
- "proxy-router/docs/swagger.yaml"
11+
- ".github/workflows/docs.yml"
12+
push:
13+
branches:
14+
- main
15+
- dev
16+
- test
17+
paths:
18+
- "docs/**"
19+
- "proxy-router/docs/swagger.yaml"
20+
- ".github/workflows/docs.yml"
21+
workflow_dispatch:
22+
23+
concurrency:
24+
group: docs-${{ github.ref }}
25+
cancel-in-progress: true
26+
27+
permissions:
28+
contents: read
29+
pull-requests: write
30+
31+
jobs:
32+
mintlify-validate:
33+
name: Mintlify validate + broken-link check
34+
runs-on: ubuntu-latest
35+
steps:
36+
- name: Checkout
37+
uses: actions/checkout@v4
38+
39+
- name: Setup Node
40+
uses: actions/setup-node@v4
41+
with:
42+
node-version: "20"
43+
cache: npm
44+
cache-dependency-path: docs/package-lock.json
45+
46+
- name: Install docs dependencies
47+
working-directory: docs
48+
run: npm ci
49+
50+
- name: Validate Mintlify config
51+
working-directory: docs
52+
run: |
53+
npx mint --version
54+
npx mint broken-links || echo "::warning::mint broken-links reported issues"
55+
56+
- name: List MDX files
57+
run: find docs -name "*.mdx" | wc -l
58+
59+
openapi-lint:
60+
name: OpenAPI spec lint
61+
runs-on: ubuntu-latest
62+
steps:
63+
- name: Checkout
64+
uses: actions/checkout@v4
65+
66+
- name: Setup Node
67+
uses: actions/setup-node@v4
68+
with:
69+
node-version: "20"
70+
71+
- name: Install Redocly CLI
72+
run: npm install -g @redocly/cli@latest
73+
74+
- name: Lint swagger.yaml
75+
run: |
76+
redocly lint proxy-router/docs/swagger.yaml || \
77+
echo "::warning::OpenAPI spec has lint issues (non-blocking)"
78+
79+
last-verified-staleness:
80+
name: Check last_verified staleness
81+
runs-on: ubuntu-latest
82+
steps:
83+
- name: Checkout
84+
uses: actions/checkout@v4
85+
86+
- name: Find pages with last_verified older than the latest release tag
87+
run: |
88+
set -euo pipefail
89+
LATEST_TAG=$(git tag --list 'v*' --sort=-v:refname | grep -v -- '-test' | head -n 1 || true)
90+
LATEST_TAG=${LATEST_TAG:-v0.0.0}
91+
echo "Latest release tag: $LATEST_TAG"
92+
93+
STALE_FILES=()
94+
while IFS= read -r f; do
95+
VERIFIED=$(awk '/^---$/{n++; next} n==1 && /^last_verified:/ {print}' "$f" \
96+
| sed -E 's/^last_verified:[[:space:]]*"?([^"]*)"?$/\1/' || true)
97+
if [ -z "$VERIFIED" ]; then
98+
continue
99+
fi
100+
if [ "$VERIFIED" \< "$LATEST_TAG" ]; then
101+
STALE_FILES+=("$f (last_verified=$VERIFIED < $LATEST_TAG)")
102+
fi
103+
done < <(find docs -name "*.mdx")
104+
105+
if [ "${#STALE_FILES[@]}" -gt 0 ]; then
106+
echo "::warning::Pages with last_verified older than $LATEST_TAG:"
107+
for s in "${STALE_FILES[@]}"; do
108+
echo "::warning:: $s"
109+
done
110+
else
111+
echo "All pages report last_verified >= $LATEST_TAG."
112+
fi
113+
114+
deploy:
115+
name: Build and deploy docs
116+
needs:
117+
- mintlify-validate
118+
- openapi-lint
119+
- last-verified-staleness
120+
if: github.event_name == 'push' && (github.ref_name == 'test' || github.ref_name == 'main')
121+
runs-on: ubuntu-latest
122+
environment: ${{ github.ref_name }}
123+
permissions:
124+
contents: read
125+
id-token: write
126+
steps:
127+
- name: Checkout
128+
uses: actions/checkout@v4
129+
130+
- name: Setup Node
131+
uses: actions/setup-node@v4
132+
with:
133+
node-version: "20"
134+
cache: npm
135+
cache-dependency-path: docs/package-lock.json
136+
137+
- name: Install docs dependencies
138+
working-directory: docs
139+
run: npm ci
140+
141+
- name: Build static site
142+
working-directory: docs
143+
env:
144+
SITE_URL: ${{ vars.NODEDOCS_SITE_URL }}
145+
run: npm run build:site -- ../.site
146+
147+
- name: Configure AWS credentials (OIDC)
148+
uses: aws-actions/configure-aws-credentials@v4
149+
with:
150+
role-to-assume: ${{ vars.NODEDOCS_IAM_ROLE_ARN }}
151+
aws-region: us-east-2
152+
153+
- name: Sync to S3
154+
run: |
155+
aws s3 sync .site/ "s3://${{ vars.NODEDOCS_S3_BUCKET }}/" \
156+
--delete \
157+
--exclude "serve.js" \
158+
--exclude "Start Docs.command" \
159+
--exclude "Start Docs.bat"
160+
161+
- name: Invalidate CloudFront
162+
run: |
163+
aws cloudfront create-invalidation \
164+
--distribution-id "${{ vars.NODEDOCS_CLOUDFRONT_DISTRIBUTION_ID }}" \
165+
--paths "/*"

‎.gitignore‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,5 @@
44
***/.env
55
***/.$*drawio.bkp
66
***/.$*drawio.dtmp
7-
*.internal.*
7+
*.internal.*
8+
.site/

‎AGENTS.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# AGENTS.md — guidance for AI agents and coding assistants
2+
3+
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.
4+
5+
## Canonical knowledge base
6+
7+
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).
8+
9+
### Read these AI-knowledge pages before answering user questions
10+
11+
- [`docs/ai/myths.mdx`](docs/ai/myths.mdx) — corrections of the most common wrong assumptions.
12+
- [`docs/ai/where-is-my-mor.mdx`](docs/ai/where-is-my-mor.mdx) — diagnostic for "missing" MOR.
13+
- [`docs/ai/session-states-open-close-recover.mdx`](docs/ai/session-states-open-close-recover.mdx) — deterministic state machine for sessions.
14+
- [`docs/ai/why-locked-in-contract.mdx`](docs/ai/why-locked-in-contract.mdx) — why MOR appears locked.
15+
- [`docs/ai/local-vs-blockchain-models.mdx`](docs/ai/local-vs-blockchain-models.mdx) — distinguish the bundled `tinyllama` from real Morpheus models.
16+
- [`docs/ai/llm-prompt-cheatsheet.mdx`](docs/ai/llm-prompt-cheatsheet.mdx) — concise rules for answering Morpheus questions.
17+
18+
### Concept references (cite from these)
19+
20+
- [`docs/concepts/architecture.mdx`](docs/concepts/architecture.mdx)
21+
- [`docs/concepts/sessions-stake-close-recover.mdx`](docs/concepts/sessions-stake-close-recover.mdx)
22+
- [`docs/concepts/local-vs-onchain-models.mdx`](docs/concepts/local-vs-onchain-models.mdx)
23+
- [`docs/concepts/tee-overview.mdx`](docs/concepts/tee-overview.mdx)
24+
- [`docs/concepts/tokens-and-fees.mdx`](docs/concepts/tokens-and-fees.mdx)
25+
- [`docs/get-started/networks-and-tokens.mdx`](docs/get-started/networks-and-tokens.mdx) — canonical contract addresses + chain IDs.
26+
- [`docs/reference/glossary.mdx`](docs/reference/glossary.mdx)
27+
28+
### How-tos by role
29+
30+
| Role | Start here |
31+
|------|-----------|
32+
| API user (no node, hosted OpenAI-compatible) | [`docs/inference-api/overview.mdx`](docs/inference-api/overview.mdx) |
33+
| Consumer | [`docs/consumers/quickstart.mdx`](docs/consumers/quickstart.mdx) |
34+
| Prosumer (agents) | [`docs/prosumers/overview.mdx`](docs/prosumers/overview.mdx) |
35+
| Provider — Full P-Node | [`docs/providers/full/quickstart.mdx`](docs/providers/full/quickstart.mdx) |
36+
| Provider — TEE / SecretVM | [`docs/providers/full/secretvm-quickstart.mdx`](docs/providers/full/secretvm-quickstart.mdx) |
37+
| Provider — Resale | [`docs/providers/resale/overview.mdx`](docs/providers/resale/overview.mdx) |
38+
| Developer (proxy-router API) | [`docs/reference/api-overview.mdx`](docs/reference/api-overview.mdx) |
39+
40+
### API and config schemas
41+
42+
- API: [`proxy-router/docs/swagger.yaml`](proxy-router/docs/swagger.yaml). The Mintlify site auto-generates the API Reference tab from this file.
43+
- Models config schema: [`proxy-router/internal/config/models-config-schema.json`](proxy-router/internal/config/models-config-schema.json).
44+
- Rating config schema: [`proxy-router/internal/rating/rating-config-schema.json`](proxy-router/internal/rating/rating-config-schema.json).
45+
46+
## Hard rules — never break these
47+
48+
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).
49+
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.
50+
2. **Never invent live values** (active model count, current bid prices, network status). Link out to `https://active.mor.org` instead.
51+
3. **Never claim Morpheus runs the inference itself.** Independent providers do; Morpheus is a marketplace coordinated by the Diamond contract on BASE.
52+
4. **Always disambiguate the local `tinyllama` demo from real Morpheus models.** They are not comparable.
53+
5. **Never describe "open a session" as "spending MOR."** The MOR is escrowed; unused stake returns on close.
54+
6. **Never tell users to call a `recover` RPC.** It does not exist. Closing the session is the recovery path.
55+
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.
56+
8. **The proxy-router's `:8082` admin port should not be public** — only `:3333` (TCP) is public, and only on provider nodes.
57+
9. **MorpheusUI mnemonic-recover only works for tier-1 (index 0) addresses.** Don't suggest it for derived addresses; suggest private-key import instead.
58+
10. **When uncertain, cite a docs page or say so.** Don't guess.
59+
60+
## Common-question quick lookup
61+
62+
| User says | Cite |
63+
|-----------|------|
64+
| "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) |
65+
| "Where is my MOR?" | [`docs/ai/where-is-my-mor.mdx`](docs/ai/where-is-my-mor.mdx) |
66+
| "Why is MOR locked in the contract?" | [`docs/ai/why-locked-in-contract.mdx`](docs/ai/why-locked-in-contract.mdx) |
67+
| "What does open/close/recover mean?" | [`docs/ai/session-states-open-close-recover.mdx`](docs/ai/session-states-open-close-recover.mdx) |
68+
| "Is the local model real Morpheus?" | [`docs/ai/local-vs-blockchain-models.mdx`](docs/ai/local-vs-blockchain-models.mdx) |
69+
| "How do I install as a consumer?" | [`docs/consumers/quickstart.mdx`](docs/consumers/quickstart.mdx) |
70+
| "How do I become a provider?" | [`docs/get-started/quickstart-provider.mdx`](docs/get-started/quickstart-provider.mdx) |
71+
| "How do I run TEE?" | [`docs/providers/full/secretvm-quickstart.mdx`](docs/providers/full/secretvm-quickstart.mdx) |
72+
| "What contract address?" | [`docs/get-started/networks-and-tokens.mdx`](docs/get-started/networks-and-tokens.mdx) |
73+
| "Where can I see live status?" | https://active.mor.org |
74+
75+
## When unsure / out-of-corpus questions
76+
77+
If the user's question doesn't match anything on this site or in the repo:
78+
79+
1. Search [`/docs`](docs/) first.
80+
2. Search [`proxy-router/docs/swagger.yaml`](proxy-router/docs/swagger.yaml) for endpoint shape.
81+
3. Search the codebase under `proxy-router/`.
82+
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:
83+
```
84+
GET https://gitbook.mor.org/morpheus-inference-marketplace.md?ask=<question>
85+
```
86+
Cite the returned URLs back to the user so they can verify.
87+
5. If you still don't have a confident answer, **say so** and link to the closest matching page rather than guessing.
88+
89+
## When asked to write code that talks to the proxy-router
90+
91+
- Use the API documented in `proxy-router/docs/swagger.yaml`.
92+
- Auth is **HTTP Basic Auth** — see [`docs/reference/api-auth.mdx`](docs/reference/api-auth.mdx).
93+
- Set the `session_id` header on `/v1/*` calls when targeting a remote (Morpheus) model. Omit it for the local model.
94+
- Don't hard-code contract addresses — read them from the proxy-router's environment.
95+
96+
## When asked to modify the docs
97+
98+
- The site lives under `/docs` and is built with [Mintlify](https://mintlify.com).
99+
- Pages are MDX with frontmatter (`title`, `description`, `audience`, `product`, `last_verified`, optional `source_url` for mirrored content).
100+
- Navigation is in [`docs/docs.json`](docs/docs.json). Add new pages there.
101+
- Run `mint dev` from `/docs` to preview locally.
102+
103+
## Repository sub-projects
104+
105+
- `proxy-router/` — Go service: the consumer/provider router. Hosts the HTTP API.
106+
- `MorpheusUI/` — Electron consumer GUI.
107+
- `cli/` — Go CLI client.
108+
- `smart-contracts/` — Solidity contracts (Diamond marketplace).
109+
- `agents/` — agent reference implementations.
110+
- `docs/` — Mintlify documentation site (this is the doc system).

‎docs/.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
.mintlify/
2+
node_modules/
3+
.DS_Store
4+
*.log
5+
.site/

0 commit comments

Comments
 (0)