Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 4 additions & 8 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
@@ -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:
Expand All @@ -16,7 +16,7 @@ permissions:
contents: read

jobs:
build:
mintlify:
runs-on: ubuntu-latest
timeout-minutes: 15
defaults:
Expand All @@ -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
38 changes: 38 additions & 0 deletions .github/workflows/trust.yml
Original file line number Diff line number Diff line change
@@ -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'
6 changes: 4 additions & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand All @@ -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`).
Expand Down
37 changes: 13 additions & 24 deletions apps/docs/CLAUDE.md
Original file line number Diff line number Diff line change
@@ -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 `<details>`), `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): `/<path>.md` and requests that prefer `Accept: text/markdown` are served from `/md/<path>`; on a `trust.*` host, `/`, `/resources`, `/subprocessors`, `/faq` and `/updates` are served from `/trust/...`. `next.config.ts` adds `Link: </llms.txt>; 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 `<details>` 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 `<page>.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`.
Original file line number Diff line number Diff line change
@@ -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`.
Expand Down
4 changes: 2 additions & 2 deletions apps/docs/content/agent.md → apps/docs/agent.mdx
Original file line number Diff line number Diff line change
@@ -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/`.
Expand Down
Original file line number Diff line number Diff line change
@@ -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).
Expand Down
4 changes: 2 additions & 2 deletions apps/docs/content/api.md → apps/docs/api.mdx
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
69 changes: 0 additions & 69 deletions apps/docs/app/(docs)/[[...slug]]/page.tsx

This file was deleted.

19 changes: 0 additions & 19 deletions apps/docs/app/(docs)/layout.tsx

This file was deleted.

23 changes: 0 additions & 23 deletions apps/docs/app/.well-known/mcp/route.ts

This file was deleted.

24 changes: 0 additions & 24 deletions apps/docs/app/_components/Sidebar.tsx

This file was deleted.

Loading
Loading