diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 238418ef..3f658ae8 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,4 +1,4 @@ -# Docs and Trust Center CI: typecheck, unit tests (content, llms, search, MCP, proxy) and a production build. No secrets. +# Docs CI (Mintlify): docs.json and every page build, and no internal link or anchor is broken. No secrets. name: docs on: @@ -16,7 +16,7 @@ permissions: contents: read jobs: - build: + mintlify: runs-on: ubuntu-latest timeout-minutes: 15 defaults: @@ -30,9 +30,5 @@ jobs: - uses: oven-sh/setup-bun@v2 with: bun-version: 1.3.9 - - run: bun install --frozen-lockfile - - run: bun run typecheck - - run: bun run test - - run: bun run build - env: - NEXT_TELEMETRY_DISABLED: '1' + - run: bunx mint@4.2.1184 validate + - run: bunx mint@4.2.1184 broken-links --check-anchors diff --git a/.github/workflows/trust.yml b/.github/workflows/trust.yml new file mode 100644 index 00000000..9a2eb81d --- /dev/null +++ b/.github/workflows/trust.yml @@ -0,0 +1,38 @@ +# Trust Center CI: typecheck, unit tests (content rules, links, llms.txt, proxy) and a production build. No secrets. +name: trust + +on: + pull_request: + paths: ['apps/trust/**', '.github/workflows/trust.yml'] + push: + branches: [main] + paths: ['apps/trust/**', '.github/workflows/trust.yml'] + +concurrency: + group: trust-${{ github.ref }} + cancel-in-progress: true + +permissions: + contents: read + +jobs: + build: + runs-on: ubuntu-latest + timeout-minutes: 15 + defaults: + run: + working-directory: apps/trust + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 24.22.1 + - uses: oven-sh/setup-bun@v2 + with: + bun-version: 1.3.9 + - run: bun install --frozen-lockfile + - run: bun run typecheck + - run: bun run test + - run: bun run build + env: + NEXT_TELEMETRY_DISABLED: '1' diff --git a/CLAUDE.md b/CLAUDE.md index edcf00fe..c313527a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -46,7 +46,8 @@ HelloNear is an AI agent persona platform on NEAR, built for NEAR HACKATHON (1 | `apps/be` | Backend API, Postgres + pgvector, NEP-413 login, OutLayer + Composio | James | | `engine` | AI engine (Mastra + NEAR AI Cloud) | Axel | | `sc` | Mind registry contract (Rust `near-sdk`) | Axel | -| `apps/docs` | Docs site (docs.hellonear.xyz) and Trust Center (trust.hellonear.xyz), with llms.txt, Markdown export and an MCP server; Vercel | Axel | +| `apps/docs` | Docs site, docs.hellonear.xyz: a Mintlify project deployed from `main` (Endpoints tab from `docs/openapi.json`; llms.txt, Markdown, skill.md and MCP from Mintlify) | Axel | +| `apps/trust` | Trust Center, trust.hellonear.xyz (Vercel): what protects users' data and funds, each claim linked to its proof | Axel | | `docs` | Shared technical docs, incl. `api-contract.md` | James + Axel | | `design` | Design tokens, screens, Mind characters (`hellonear.pen`, pen.dev) | Nabil | | `deploy` | Hosted demo: systemd units + `deploy.sh` for one Proxmox LXC, and the automatic deploy after a merge (`deploy/autodeploy/`) (#22) | James | @@ -73,7 +74,8 @@ Each folder has its own workflow in `.github/workflows/`. It runs on pull reques | `fe` | `apps/fe` | lint, typecheck, `next build` | | `sc` | `sc` | unit tests, sandbox tests (incl. upgrades from the fixtures), clippy | | `landing` | `apps/landing` | typecheck, `next build` | -| `docs` | `apps/docs` (and `docs/openapi.json`) | typecheck, unit tests, `next build` | +| `docs` | `apps/docs` (and `docs/openapi.json`) | Mintlify `validate`, `broken-links --check-anchors` | +| `trust` | `apps/trust` | typecheck, unit tests, `next build` | | `status` | `apps/status` | typecheck, unit tests, `next build` | CI does not replace the local integration and load tests required by the rules below. Nothing deploys from CI itself. A merged `main` is deployed to the hosted demo after its CI passes, by a poller on James's always-on LAN machine that comments the result on the merged PR (rule 3, `deploy/README.md`). diff --git a/apps/docs/CLAUDE.md b/apps/docs/CLAUDE.md index b2ea2e5c..cc5df487 100644 --- a/apps/docs/CLAUDE.md +++ b/apps/docs/CLAUDE.md @@ -1,37 +1,26 @@ # CLAUDE.md — apps/docs -The docs site, **docs.hellonear.xyz**, and the Trust Center, **trust.hellonear.xyz**: one Next.js app, one Vercel project (`hellonear-docs`). Built 13 Nov 2026. Owner: Axel. Root rules in `/CLAUDE.md` also apply. +The docs site, **docs.hellonear.xyz**, a **Mintlify** project (Starter plan) connected to this repository. Moved from a Next.js app to Mintlify on 13 Nov 2026; the Trust Center moved out to `apps/trust` at the same time. Owner: Axel. Root rules in `/CLAUDE.md` also apply. -**Update this file in the same PR whenever you change setup, commands, routes, content rules or where it is deployed.** +**Update this file in the same PR whenever you change pages, navigation, the Mintlify settings or where it is deployed.** ## How it works -- **One source:** every page is a Markdown file in `content/` (frontmatter `title`, `description`). `scripts/build-content.mjs` turns them into `lib/generated/pages.json` (gitignored; runs before `dev`, `build`, `typecheck` and `test`) and copies `../../docs/openapi.json` to `public/openapi.json` and Swagger UI to `public/swagger/` (both gitignored). The HTML pages, the `.md` export, `/llms.txt`, `/llms-full.txt` and the MCP tools all read that JSON, so nothing reads files at request time. The build fails on an en or em dash. -- **Content is true to the repo.** Most pages were sliced from `README.md` and `docs/api-contract.md` §3 on 13 Nov (README images stripped, relative links pointed at GitHub); they do not update by themselves, so change the page when the README section changes. Never invent features, numbers or claims; link proof (tx, report, file) where you can. -- **Sidebar order** is `lib/nav.ts`. A test fails if a page in `content/` is missing from it or listed twice; the trust pages are the `TRUST_TABS`. -- **Routes:** `app/(docs)/[[...slug]]` (docs pages; `api-reference` adds Swagger UI from `/openapi.json`, client-only: `swagger-ui-dist`'s prebuilt bundle copied to `public/swagger/` by the content script and loaded with `next/script`, because swagger-ui-react bundled by Turbopack throws `OpenApi3_1Element.refract is not a function` and an opened operation never loads), `app/trust` (Trust Center: Overview, `resources`, `subprocessors`, `faq`, `updates`, each built from its Markdown by heading: `###` sections become cards, FAQ `##` categories and `###` questions become `
`), `app/md/[[...slug]]` (Markdown), `app/llms.txt`, `app/llms-full.txt`, `app/skill.md` (`lib/skill.ts`, an Agent Skill), `app/mcp` and `app/.well-known/mcp`. -- **`proxy.ts`** (Next 16's middleware): `/.md` and requests that prefer `Accept: text/markdown` are served from `/md/`; on a `trust.*` host, `/`, `/resources`, `/subprocessors`, `/faq` and `/updates` are served from `/trust/...`. `next.config.ts` adds `Link: ; rel="llms-txt"` to every response. -- **MCP** (`lib/mcp.ts`): stateless Streamable HTTP, one JSON-RPC message per POST, JSON answers, no sessions. `initialize`, `ping`, `tools/list`, `tools/call` with `search_docs` (`search()` in `lib/content.ts`: keyword scoring, title > description > body) and `read_page`. Read-only, CORS `*`; GET answers 405. -- **Trust Center rules (Axel, 13 Nov):** no compliance badges or certifications (HelloNear has none), no "audit" as a claim, no team members' names, no emoji. Every "Yes" in the scope table links to its proof; "N/A" where a control does not apply. Updates only for what git log or the README proves. -- Styles: plain CSS (`app/globals.css`) with the web app's Stone & Lime tokens, light and dark by `prefers-color-scheme`. Sidebar on desktop, a `
` menu on phones (no JavaScript needed), 16px gutters, no horizontal scroll (checked at 390 px). +- **Pages:** one `.mdx` file per page in this folder (frontmatter `title`, `description`), `index.mdx` is the introduction. Most text was sliced from `README.md` and `docs/api-contract.md` §3 on 13 Nov; it does not update by itself, so change the page when the README section changes. Never invent features, numbers or claims; link proof (tx, report, file) where you can. No en or em dashes. MDX: `{`, `}` and `<` outside code are JSX, keep them in backticks. +- **`docs.json`** is the whole configuration: theme, Stone & Lime colors (primary `#3E5C00`, lime `#D8F04A` in dark mode), logo (`logo/`, copied from `design/logo/`), favicon, navbar (Trust, Status, GitHub) and navigation. A new page must be added to `navigation` or it does not show in the sidebar. +- **API reference:** the **Endpoints** tab is generated by Mintlify from `docs/openapi.json` on `main`, referenced by its raw GitHub URL. Mintlify refuses paths outside this folder (`../` is not allowed), and a copy here would drift from the one source the backend maintains. So an endpoint change shows on the site once it is on `main` and Mintlify rebuilds (any push that changes `apps/docs`, or a manual redeploy in the dashboard). Each endpoint has a playground that calls `servers` from the spec (the hosted API). `api-reference.mdx` is the prose page in the sidebar. +- **For agents, from Mintlify itself:** `/llms.txt`, `/llms-full.txt`, every page as Markdown at `.md`, `/skill.md` and a search MCP server at `/mcp`. Nothing to maintain here. +- **Deploys:** Mintlify's GitHub app watches `main`. Git settings in the Mintlify dashboard: repository `Hellonear-AI/hellonear`, branch `main`, "docs.json is in a subdirectory" on, path `/apps/docs`. Custom domain `docs.hellonear.xyz` is set in Mintlify's Domain setup; its `CNAME` in the `hellonear.xyz` Cloudflare zone (DNS only) is on the box owner's side (James), with Axel's approval. Pull requests get a Mintlify preview if the GitHub app is allowed to comment. +- The public repo `Hellonear-AI/docs` is Mintlify's onboarding starter, not used. ## Commands -```sh -bun install -bun run dev # http://localhost:3300 -bun run typecheck -bun run test # node:test: content, nav, links, llms, search, markdown, proxy, MCP -bun run build -``` - -Try the MCP server locally: +The Mintlify CLI is run with `bunx` at a pinned version (it needs Node 20.17+ and does not run on Node 25): ```sh -curl -s localhost:3300/mcp -H 'content-type: application/json' \ - -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_docs","arguments":{"query":"daily limit"}}}' +bunx mint@4.2.1184 dev --no-open --port 3333 # http://localhost:3333 +bunx mint@4.2.1184 validate +bunx mint@4.2.1184 broken-links --check-anchors ``` -## Deploy - -On **Vercel**, project `hellonear-docs` (created 13 Nov), deployed by Axel with the Vercel CLI from this folder. **Build locally and upload the result** (`vercel build --prod` then `vercel deploy --prebuilt --prod`): the content script copies `../../docs/openapi.json`, which a plain `vercel deploy` from this folder does not upload, so a remote build fails with ENOENT. Domains on the project: `docs.hellonear.xyz` and `trust.hellonear.xyz`, each a `CNAME` in the `hellonear.xyz` Cloudflare zone to the target Vercel gives (DNS only, not proxied). The DNS change is on the box owner's side (James), with Axel's approval. No env vars. +Never run `mint signup`, `mint deploy` or `mint claim`: the project already exists and deploys from Git. CI: `.github/workflows/docs.yml` runs `validate` and `broken-links --check-anchors`. diff --git a/apps/docs/content/agent-market.md b/apps/docs/agent-market.mdx similarity index 84% rename from apps/docs/content/agent-market.md rename to apps/docs/agent-market.mdx index dc4ad178..b1e013a1 100644 --- a/apps/docs/content/agent-market.md +++ b/apps/docs/agent-market.mdx @@ -1,6 +1,6 @@ --- -title: Hire on Agent Market -description: How a Mind searches the NEAR AI Agent Market, gets each agent's price for a job and recommends the cheapest within budget, without hiring. +title: "Hire on Agent Market" +description: "How a Mind searches the NEAR AI Agent Market, gets each agent's price for a job and recommends the cheapest within budget, without hiring." --- **Track:** `agents`. **Skill:** Hire on Agent Market (`agent-market`), in the General Assistant template. **Tools:** `market_search`, `market_quote`. diff --git a/apps/docs/content/agent.md b/apps/docs/agent.mdx similarity index 99% rename from apps/docs/content/agent.md rename to apps/docs/agent.mdx index 953bc3b7..ddfd1fca 100644 --- a/apps/docs/content/agent.md +++ b/apps/docs/agent.mdx @@ -1,6 +1,6 @@ --- -title: The agent -description: How each Mind runs on Mastra and NEAR AI Cloud: design, every tool, every skill, and how it is tested. +title: "The agent" +description: "How each Mind runs on Mastra and NEAR AI Cloud: design, every tool, every skill, and how it is tested." --- This is the core of HelloNear, and the part a judge can read end to end in `engine/`. diff --git a/apps/docs/content/api-reference.md b/apps/docs/api-reference.mdx similarity index 60% rename from apps/docs/content/api-reference.md rename to apps/docs/api-reference.mdx index ecc777d4..84f52c83 100644 --- a/apps/docs/content/api-reference.md +++ b/apps/docs/api-reference.mdx @@ -1,9 +1,9 @@ --- -title: API reference -description: Every route of the HelloNear backend API, rendered from the OpenAPI spec, with the hosted server at https://api.hellonear.xyz. +title: "API reference" +description: "How the HelloNear backend API is described: the OpenAPI spec, the server, auth, errors and streams. Every route is in the Endpoints tab." --- -The HelloNear backend API is described by an OpenAPI 3 spec, kept in the repository at [`docs/openapi.json`](https://github.com/Hellonear-AI/hellonear/blob/main/docs/openapi.json) and served here at [/openapi.json](/openapi.json). The prose contract, with every field and event, is [`docs/api-contract.md`](https://github.com/Hellonear-AI/hellonear/blob/main/docs/api-contract.md). +The HelloNear backend API is described by an OpenAPI 3 spec, kept in the repository at [`docs/openapi.json`](https://github.com/Hellonear-AI/hellonear/blob/main/docs/openapi.json) and rendered from it in the **Endpoints** tab of this site, where each route has a playground that can call the hosted API. The prose contract, with every field and event, is [`docs/api-contract.md`](https://github.com/Hellonear-AI/hellonear/blob/main/docs/api-contract.md). - **Server:** `https://api.hellonear.xyz` (NEAR testnet), or `http://localhost:4000` when you [run it locally](/run-locally). - **Auth:** every route except health, status and auth needs the session cookie `hn_session`. Get one as a guest with `POST /v1/auth/demo`, or sign in with a NEAR wallet (NEP-413). diff --git a/apps/docs/content/api.md b/apps/docs/api.mdx similarity index 98% rename from apps/docs/content/api.md rename to apps/docs/api.mdx index 36b62690..75fce77a 100644 --- a/apps/docs/content/api.md +++ b/apps/docs/api.mdx @@ -1,6 +1,6 @@ --- -title: API overview -description: How the public HTTP API works, every route, and where the OpenAPI spec lives. +title: "API overview" +description: "How the public HTTP API works, every route, and where the OpenAPI spec lives." --- The web app is a client of a public HTTP API, and everything it does can be done with `curl`. The full spec is **[`docs/openapi.json`](https://github.com/Hellonear-AI/hellonear/blob/main/docs/openapi.json)** (OpenAPI 3.1, 63 operations): open it in [Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/Hellonear-AI/hellonear/main/docs/openapi.json) or any OpenAPI viewer to read every route and try it against the hosted API. Every server-sent event type is described in [`docs/api-contract.md`](https://github.com/Hellonear-AI/hellonear/blob/main/docs/api-contract.md) §3. diff --git a/apps/docs/app/(docs)/[[...slug]]/page.tsx b/apps/docs/app/(docs)/[[...slug]]/page.tsx deleted file mode 100644 index 1b6bcbbc..00000000 --- a/apps/docs/app/(docs)/[[...slug]]/page.tsx +++ /dev/null @@ -1,69 +0,0 @@ -import type { Metadata } from "next"; -import Link from "next/link"; -import { notFound } from "next/navigation"; -import { getPage, markdownUrl, orderedSections, pages } from "@/lib/content"; -import { render } from "@/lib/markdown"; -import { REPO_URL } from "@/lib/site"; -import { NavList } from "../../_components/Sidebar"; -import { Swagger } from "../../_components/Swagger"; - -type Props = { params: Promise<{ slug?: string[] }> }; - -export const dynamicParams = false; - -export function generateStaticParams() { - return pages.filter((p) => !p.slug.startsWith("trust")).map((p) => ({ slug: p.slug ? p.slug.split("/") : [] })); -} - -async function pageOf(props: Props) { - const { slug } = await props.params; - const page = getPage((slug ?? []).join("/")); - if (!page || page.slug.startsWith("trust")) notFound(); - return page; -} - -export async function generateMetadata(props: Props): Promise { - const page = await pageOf(props); - return { - title: page.slug ? page.title : { absolute: "HelloNear Docs" }, - description: page.description, - alternates: { canonical: `/${page.slug}`, types: { "text/markdown": markdownUrl(page.slug) } }, - }; -} - -export default async function DocPage(props: Props) { - const page = await pageOf(props); - const flat = orderedSections().flatMap((s) => s.pages).filter((p) => !p.slug.startsWith("trust")); - const i = flat.findIndex((p) => p.slug === page.slug); - const prev = flat[i - 1]; - const next = flat[i + 1]; - return ( -
- -
- Menu - -
-
-
-

{orderedSections().find((s) => s.pages.some((p) => p.slug === page.slug))?.title}

-

{page.title}

-

{page.description}

-
- {page.slug === "api-reference" && } -
- -
-
- ); -} diff --git a/apps/docs/app/(docs)/layout.tsx b/apps/docs/app/(docs)/layout.tsx deleted file mode 100644 index b8e6e2fc..00000000 --- a/apps/docs/app/(docs)/layout.tsx +++ /dev/null @@ -1,19 +0,0 @@ -import Link from "next/link"; -import { Brand } from "../_components/Brand"; -import { REPO_URL, STATUS_URL } from "@/lib/site"; - -export default function DocsLayout({ children }: { children: React.ReactNode }) { - return ( - <> -
- -
- Trust - Status - GitHub -
-
- {children} - - ); -} diff --git a/apps/docs/app/.well-known/mcp/route.ts b/apps/docs/app/.well-known/mcp/route.ts deleted file mode 100644 index cad812ba..00000000 --- a/apps/docs/app/.well-known/mcp/route.ts +++ /dev/null @@ -1,23 +0,0 @@ -import { SERVER_INFO, TOOLS } from "@/lib/mcp"; -import { SITE_URL } from "@/lib/site"; - -export const dynamic = "force-static"; - -// Discovery for agents that look for an MCP server at a well-known path. -export const GET = () => - Response.json( - { - servers: [ - { - name: SERVER_INFO.name, - title: SERVER_INFO.title, - description: "Read-only search and reading of the HelloNear docs and Trust Center.", - url: `${SITE_URL}/mcp`, - transport: "streamable-http", - authentication: "none", - tools: TOOLS.map((t) => ({ name: t.name, description: t.description })), - }, - ], - }, - { headers: { "access-control-allow-origin": "*" } }, - ); diff --git a/apps/docs/app/_components/Sidebar.tsx b/apps/docs/app/_components/Sidebar.tsx deleted file mode 100644 index 890cd8a0..00000000 --- a/apps/docs/app/_components/Sidebar.tsx +++ /dev/null @@ -1,24 +0,0 @@ -import Link from "next/link"; -import { orderedSections } from "@/lib/content"; - -// Server-rendered nav. On phones it sits inside a
menu, so it works without JavaScript. -export function NavList({ current }: { current: string }) { - return ( - - ); -} diff --git a/apps/docs/app/_components/Swagger.tsx b/apps/docs/app/_components/Swagger.tsx deleted file mode 100644 index 4d54f87f..00000000 --- a/apps/docs/app/_components/Swagger.tsx +++ /dev/null @@ -1,37 +0,0 @@ -"use client"; - -import Script from "next/script"; -import { useEffect, useRef, useState } from "react"; - -type SwaggerBundle = (options: Record) => unknown; -declare global { - interface Window { - SwaggerUIBundle?: SwaggerBundle; - } -} - -// Swagger UI only runs in the browser; the prose above it is server-rendered and readable without JavaScript. -// It loads swagger-ui-dist's prebuilt bundle from /swagger (copied by scripts/build-content.mjs), not through the -// bundler: Turbopack breaks swagger-ui-react's OpenAPI resolver, so an opened operation never finished loading. -export function Swagger({ url }: { url: string }) { - const node = useRef(null); - const [ready, setReady] = useState(false); - - useEffect(() => { - if (window.SwaggerUIBundle) setReady(true); - }, []); - - useEffect(() => { - if (!ready || !node.current || !window.SwaggerUIBundle) return; - window.SwaggerUIBundle({ url, domNode: node.current, docExpansion: "list", defaultModelsExpandDepth: 0, tryItOutEnabled: false }); - }, [ready, url]); - - return ( -
- -