Skip to content

feat(docs): docs.hellonear.xyz with Swagger, llms.txt and MCP, and the Trust Center at trust.hellonear.xyz - #306

Merged
Lexirieru merged 9 commits into
mainfrom
feat/docs-site
Nov 12, 2026
Merged

Lexirieru merged 9 commits into
mainfrom
feat/docs-site

Conversation

@Lexirieru

Copy link
Copy Markdown
Contributor

New app apps/docs: the docs site and the Trust Center in one Next.js app, deployed to Vercel (project hellonear-docs) with the Vercel CLI, not from the box.

What

  • Docs (docs.hellonear.xyz): Introduction, Quickstart, concepts, the six track features, API (Swagger UI from docs/openapi.json, 63 operations, servers https://api.hellonear.xyz and http://localhost:4000), streaming events, errors, status, contracts, run locally, hackathon phase. Most text is taken from the README and docs/api-contract.md, so it says what the repo says.
  • Trust Center (trust.hellonear.xyz, laid out like trust.anthropic.com): Overview (scope × controls table where every "Yes" links to its proof, controls, subprocessors, latest updates), Resources, Subprocessors (11, each checked against the code), FAQ (5 categories, expand/collapse, anchor per question), Updates (dated, only what git log and the README prove). No compliance badges, no "audit" claim, no team names.
  • For agents: /llms.txt, /llms-full.txt, /<page>.md (and Accept: text/markdown), /skill.md, a read-only MCP server at /mcp (search_docs, read_page) and /.well-known/mcp.
  • proxy.ts serves /trust/* on a trust.* host.
  • CI docs.yml: typecheck, unit tests, next build. Root CLAUDE.md and apps/docs/CLAUDE.md updated.

Tests (local)

  • bun run typecheck ok; bun run test 16 pass, 0 fail (content, nav, links, llms, search, markdown, proxy, MCP); bun run build ok.
  • Chrome on localhost:3300: docs pages, /api-reference (an opened operation shows its parameters; this needed the last commit, swagger-ui-react under Turbopack never finished loading one), /trust and its four tabs, no console errors, no sideways scroll at phone width.
  • curl: /llms.txt, /skill.md, /quickstart.md, /.well-known/mcp, /openapi.json 200; MCP tools/list returns both tools; Host: trust.hellonear.xyz /faq serves the Trust Center FAQ.
  • Load test: not run. These are static pages, no backend or shared path changes; /mcp is a stateless read of bundled JSON.

Not proven yet

  • Not deployed, and the DNS records for docs and trust don't exist yet; trust host routing was only tested with a Host: header.
  • Next replaces the Vary: Accept header with its own, so a cache in between may not keep HTML and Markdown of one URL apart.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Q5ZrzK8une3S2YyhDG746e

Lexirieru and others added 9 commits November 13, 2026 04:37
… and trust.hellonear.xyz

Next 16.4.4, React 19.3.1, TypeScript 6.0.3, every dependency pinned; bun.lock in format 1 like the rest of the repo. Stone & Lime tokens from apps/status, light and dark. scripts/build-content.mjs turns content/*.md into one JSON bundle so no route reads files at request time, and copies docs/openapi.json into public/. Tests: added later in this branch (bun run test, typecheck and next build all pass at the end of it).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q5ZrzK8une3S2YyhDG746e
Most pages are README sections (images stripped, relative links pointed at GitHub) and api-contract §3, so they say what the repo says; intro, concepts, track features, errors and status are written from the README, apps/be/CLAUDE.md and the code. No en or em dashes (the content build refuses them).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q5ZrzK8une3S2YyhDG746e
…r the API reference

One catch-all route renders every content page (GitHub-style heading ids, so README anchors still work). The API reference adds Swagger UI over /openapi.json, client-only, with the hosted server https://api.hellonear.xyz. The phone menu is a <details>, so it works without JavaScript.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q5ZrzK8une3S2YyhDG746e
…bprocessors, FAQ and updates

Laid out like a trust center (hero, tabs, cards), with HelloNear's own facts only: every Yes in the scope table links to its proof (TEE Explorer report, OutLayer policy tx, SourceScan, source files), N/A where a control does not apply, no compliance badges, no team names. Subprocessors and FAQ answers were checked against the code and the folders' CLAUDE.md; updates only from git log and the README. The git history (all branches, 1230 commits) was scanned for key-shaped strings on 13 Nov: only a 1Click quote signature in a test fixture and placeholder Telegram tokens in tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q5ZrzK8une3S2YyhDG746e
…ly MCP server

/<path>.md and Accept: text/markdown serve the page's Markdown (proxy.ts); every response links /llms.txt; /skill.md is an Agent Skill. /mcp is stateless Streamable HTTP (initialize, ping, tools/list, tools/call) with search_docs and read_page, CORS *, and /.well-known/mcp describes it. trust.* hosts serve /trust/* at their root.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q5ZrzK8une3S2YyhDG746e
bun run test: 16 tests, 16 pass. bun run typecheck: clean. bun run build: 77 static pages, /mcp dynamic.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q5ZrzK8une3S2YyhDG746e
docs.yml runs typecheck, tests and next build on Bun 1.3.9 and Node 24.22.1, like status.yml, also when docs/openapi.json changes. Root CLAUDE.md gets the layout and CI rows.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q5ZrzK8une3S2YyhDG746e
swagger-ui-react bundled by Turbopack threw "OpenApi3_1Element.refract is
not a function" in resolveSubtree, and every operation opened on
/api-reference spun forever (seen in Chrome on localhost:3300). The page
now loads swagger-ui-dist 5.34.0's prebuilt bundle from /swagger, copied
there by the content script, with next/script.

Tests: bun run typecheck ok; bun run test 16 pass, 0 fail; bun run build
ok. Chrome: GET /v1/minds/{mindId} opens with its parameters, no console
errors.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q5ZrzK8une3S2YyhDG746e
… locally

CI failed with ENOENT copying openapi.json: public/ holds only generated
files, so a fresh checkout has no public/ folder. A remote Vercel build
failed too, since deploying from apps/docs does not upload the repo's
docs/openapi.json; CLAUDE.md now says to deploy with vercel build and
deploy --prebuilt.

Tests: rm -rf public lib/generated, then the content script recreates
both; typecheck, test and build run below before push.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q5ZrzK8une3S2YyhDG746e
@Lexirieru
Lexirieru merged commit 879764b into main Nov 12, 2026
1 check passed
@Lexirieru

Copy link
Copy Markdown
Contributor Author

Merged with Axel's approval, and deployed with the Vercel CLI (project hellonear-docs): https://hellonear-docs.vercel.app (Trust Center: https://hellonear-docs.vercel.app/trust). Checked live: /, /trust, /trust/faq, /api-reference, /llms.txt, /skill.md, /quickstart.md, /openapi.json, /.well-known/mcp all 200, and MCP tools/list answers.

@Lin1er could you add two DNS records in the hellonear.xyz Cloudflare zone (DNS only, not proxied)? Both domains are already added to the Vercel project, Vercel gave this target:

Type Name Target
CNAME docs 7e20a43f07962fca.vercel-dns-017.com
CNAME trust 7e20a43f07962fca.vercel-dns-017.com

(status → e658d8fd4c40ebb3.vercel-dns-017.com from #303 is still pending too, if you can do the three together.)

@AncungAulia please review the UI on the Vercel URL above: the docs pages, the Swagger API reference, and the Trust Center tabs (Overview, Resources, Subprocessors, FAQ, Updates; laid out like trust.anthropic.com). If you want to change anything, go ahead in a PR and mention Axel; he merges it.

@Lin1er

Lin1er commented Nov 12, 2026

Copy link
Copy Markdown
Contributor

Live on the hosted demo: main 879764b (automatic deploy after the merge).

  • Before: 72106cf, and the box matched git at that revision. CI: passed: build.
  • GET /v1/health → {"ok":true,"engine":true,"revision":"879764b"}. No rollback.
  • Rollback target: 72106cf (/opt/hellonear/release-old).

@Lexirieru

Copy link
Copy Markdown
Contributor Author

@Lin1er small change to the DNS request above: please hold the docs CNAME for now. Axel moved the docs to Mintlify, so docs will point to a target Mintlify gives (I'll post it once the Mintlify site is live). trust and status stay as written: trust → 7e20a43f07962fca.vercel-dns-017.com for the moment (it moves to its own Vercel project, I'll confirm the target before you add it), status → `e658d8fd4c40ebb3.vercel-dns-017.com".

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants