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
6 changes: 6 additions & 0 deletions apps/docs/CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,12 @@ The docs site, **docs.hellonear.xyz**, a **Mintlify** project (Starter plan) con
- **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.
- **Our own look (Ancung, 13 Nov):** `style.css` (Mintlify loads every `.css` in this folder) gives the docs the web app's quiet scrollbars and the diagrams' colours, light and dark (`html.dark`).
- **Diagrams:** "How it works" draws its two diagrams in SVG from `snippets/how-it-works.jsx` (`Architecture`, `PaymentSteps`), not Mermaid, which shrank to unreadable text. Rounded nodes and curved, labelled links like the app's Mind Graph, dots travelling along them (hidden for reduced motion); HelloNear's own parts tinted lime, outside services plain. Desktop flows left to right; under 768 px the architecture is redrawn top to bottom and the payment becomes a step list, so text keeps its size. They show the same parts and steps the Mermaid diagrams did; change them together with the README. Mintlify's dev server doesn't reload a changed snippet: restart it.
- **Logos:** the Tech stack table shows each technology's logo left of its name (a fixed-width box and a hanging indent, so every name lines up; above the name on phones), where the README has one (copies in `images/brands/` from `design/brands/` and `docs/readme/brands/`; Mintlify can't read outside this folder). The README keeps them in a column of their own, which here was mostly empty. Dark mode swaps in the white versions (`hn-on-light` / `hn-on-dark` in `style.css`); NEAR AI has no white file, so its black mark is inverted.
- **Icons:** The agent's skill table and Connectors' app table show each item's icon left of its name, the README's own (`images/skills/`, `images/apps/`, copied from `docs/readme/icons/`), in a narrow 24 px box (`hn-icons`), kept on the left on phones. Two-column label and value tables have no column titles, so their empty header row is hidden (`style.css`).
- **Tab titles:** `title.js` (Mintlify loads every `.js` here) turns Mintlify's "Page - HelloNear" into "Page | HelloNear", like the web app's (docs.json has no separator setting). Only the tab changes; the server-sent title (search engines, link previews) stays Mintlify's.
- **Search** works on the deployed site only; `mint dev` asks for `mint login` (Axel's Mintlify account) to search locally.

## Commands

Expand Down
76 changes: 40 additions & 36 deletions apps/docs/agent.mdx

Large diffs are not rendered by default.

36 changes: 20 additions & 16 deletions apps/docs/connectors.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,21 +5,25 @@ description: "The apps and services a Mind can use, and what each one is for."

What a Mind can work with. Logos are the ones the web app shows on the Connections screen (rendered from `apps/fe/src/components/elements/AppLogos.tsx`); each is its owner's trademark, used to name the app.

| | Connector | How it connects | What a Mind can do with it |
|---|---|---|---|
| | **Gmail** | Composio (OAuth, the owner's account) | Read and search mail, save drafts, archive or label after approval. No send tool exists |
| | **Google Calendar** | Composio | Read events, find free time, add an event, move an event, all with times on the owner's clock |
| | **Google Meet** | Composio | Schedule a meeting with guests the owner named and a Meet link, after approval |
| | **Google Sheets** | Composio | Find and read sheets, add a row, change cells with the old value shown first |
| | **Google Drive** | Composio | Search files by name and content |
| | **Google Docs** | Composio | Read a Doc, create one, add text at the end (never replaces) |
| | **Notion** | Composio | Search and read pages and databases, add a page or a row, change a row's properties |
| | **Slack** | Composio | List channels, post a message the owner approved |
| | **Outlook** | Composio | Read mail and save reply drafts (no send) |
| | **Zoom** | Composio | List meetings, schedule one with a join link, read Zoom's AI summary of a past meeting |
| | **Telegram** | A bot per Mind, made by the owner with BotFather | Chat with the Mind, streamed replies, Approve / Decline buttons on cards; only the owner's chat is answered |
| | **The Mind's own email address** | AgentMail, one inbox per Mind | Send from `…@agentmail.to` after approval, only to addresses the owner typed; read its own inbox with spam and phishing warnings |
| | **NEAR wallet** (Meteor first) | NEAR Connect, NEP-413 sign-in | The owner signs in, sets the Mind wallet's limits and freezes it; the Mind never holds the owner's keys |
| | **HTTP request** (your own APIs) | API keys the owner saves in Connections, stored encrypted | Call any HTTPS API the owner uses (a store, a CRM, a webhook) with the owner's key, only on the hosts the owner listed; the Mind writes `{{secrets.NAME}}` and never sees the key |
<div className="hn-tech hn-icons">

| Connector | How it connects | What a Mind can do with it |
|---|---|---|
| <img src="/images/apps/gmail.svg" alt="" className="hn-logo hn-icon" noZoom /> **Gmail** | Composio (OAuth, the owner's account) | Read and search mail, save drafts, archive or label after approval. No send tool exists |
| <img src="/images/apps/google-calendar.svg" alt="" className="hn-logo hn-icon" noZoom /> **Google Calendar** | Composio | Read events, find free time, add an event, move an event, all with times on the owner's clock |
| <img src="/images/apps/google-meet.svg" alt="" className="hn-logo hn-icon" noZoom /> **Google Meet** | Composio | Schedule a meeting with guests the owner named and a Meet link, after approval |
| <img src="/images/apps/google-sheets.svg" alt="" className="hn-logo hn-icon" noZoom /> **Google Sheets** | Composio | Find and read sheets, add a row, change cells with the old value shown first |
| <img src="/images/apps/google-drive.svg" alt="" className="hn-logo hn-icon" noZoom /> **Google Drive** | Composio | Search files by name and content |
| <img src="/images/apps/google-docs.svg" alt="" className="hn-logo hn-icon" noZoom /> **Google Docs** | Composio | Read a Doc, create one, add text at the end (never replaces) |
| <img src="/images/apps/notion.svg" alt="" className="hn-logo hn-icon" noZoom /> **Notion** | Composio | Search and read pages and databases, add a page or a row, change a row's properties |
| <img src="/images/apps/slack.svg" alt="" className="hn-logo hn-icon" noZoom /> **Slack** | Composio | List channels, post a message the owner approved |
| <img src="/images/apps/outlook.svg" alt="" className="hn-logo hn-icon" noZoom /> **Outlook** | Composio | Read mail and save reply drafts (no send) |
| <img src="/images/apps/zoom.svg" alt="" className="hn-logo hn-icon" noZoom /> **Zoom** | Composio | List meetings, schedule one with a join link, read Zoom's AI summary of a past meeting |
| <img src="/images/apps/telegram.svg" alt="" className="hn-logo hn-icon" noZoom /> **Telegram** | A bot per Mind, made by the owner with BotFather | Chat with the Mind, streamed replies, Approve / Decline buttons on cards; only the owner's chat is answered |
| <span className="hn-logo-space" /> **The Mind's own email address** | AgentMail, one inbox per Mind | Send from `…@agentmail.to` after approval, only to addresses the owner typed; read its own inbox with spam and phishing warnings |
| <img src="/images/apps/meteor.svg" alt="" className="hn-logo hn-icon" noZoom /> **NEAR wallet** (Meteor first) | NEAR Connect, NEP-413 sign-in | The owner signs in, sets the Mind wallet's limits and freezes it; the Mind never holds the owner's keys |
| <img src="/images/skills/http-request.svg" alt="" className="hn-logo hn-icon" noZoom /> **HTTP request** (your own APIs) | API keys the owner saves in Connections, stored encrypted | Call any HTTPS API the owner uses (a store, a CRM, a webhook) with the owner's key, only on the hosts the owner listed; the Mind writes `{{secrets.NAME}}` and never sees the key |

</div>

---
2 changes: 1 addition & 1 deletion apps/docs/events.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ Common fields on every event:
| `step.finished` | `step`, `usage` | `step-finish` |
| `run.finished` | `finishReason`, `text`, `usage`, `costUsd`, `verification: { status: "pending" }` | `finish` |
| `run.finished` (canceled) | `status: "canceled"`, `finishReason: "canceled"`; no `text`, `usage` or `costUsd`, and no `run.verified` after it | **backend**, not the engine: the last event of a run stopped with `POST /v1/runs/{runId}/cancel` (#121); a builder run gets `workflow.finished` with `status: "canceled"` instead |
| `attack.verdict` | `attackId`, `attacker`, `paymentTool` (the Mind's skills grant `send_payment`), `stoppedBy`: `model` (refused, asked for no payment) · `no_tool` (no payment tool) · `approval` (a payment card waits for the owner) · `policy` (approved, then refused by the wallet in OutLayer's TEE before signing: `policy_denied` / `wallet_frozen`, no tx) · `none` (a payment was sent), `detail`, optional `to`, `status`, `attackerTargeted` (the payment went to the scenario's attacker), `txHash` (only for `none`) | engine (`src/attacks.ts`, #16), on a run that carries `attackId`, after `run.finished` and before `run.verified` |
| `attack.verdict` | `attackId`, `attacker`, `paymentTool` (the Mind's skills grant `send_payment`), `stoppedBy`: `model` (refused, asked for no payment); `no_tool` (no payment tool); `approval` (a payment card waits for the owner); `policy` (approved, then refused by the wallet in OutLayer's TEE before signing: `policy_denied` / `wallet_frozen`, no tx); `none` (a payment was sent), `detail`, optional `to`, `status`, `attackerTargeted` (the payment went to the scenario's attacker), `txHash` (only for `none`) | engine (`src/attacks.ts`, #16), on a run that carries `attackId`, after `run.finished` and before `run.verified` |
| `thread.titled` | `threadId`, `title` (3 to 6 words summing up the user's first message, in the user's language, no quotes or final period) | engine (`src/titles.ts`, #86, #93), after the `run.finished` of a thread's first run and before `run.verified`; skipped if making the title fails or takes too long, and then the backend keeps the first-message cut |
| `run.verified` | `model`, `nodeId`, `verification` (see below). Always the run's **last** event | engine, after the stream is read |
| `run.error` | `error` | `error` chunk or a thrown error. The backend adds one itself when the engine stream breaks (`engine_stream_interrupted`), and when a run stayed `running` after a backend restart (`run_interrupted`, #218) |
Expand Down
66 changes: 5 additions & 61 deletions apps/docs/how-it-works.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,71 +3,15 @@ title: "How it works"
description: "The parts of HelloNear and how one payment goes from a chat message to a NEAR transaction."
---

```mermaid
flowchart LR
O([Owner]) -->|chat, approve| FE[Web app Next.js]
O -->|chat, approve| TG[Telegram bot]
O -->|signs policy, freeze| MW[Meteor wallet]
FE --> BE[Backend API NEP-413 sign-in, runs, approvals]
TG --> BE
BE -->|mind config + skills| EN
import { Architecture, PaymentSteps } from "/snippets/how-it-works.jsx";

subgraph EN[Engine · Mastra 1.81]
direction TB
AG[One generic Mind agent persona, memory, skills from RequestContext]
TL[[53 tools granted only by equipped skills]]
WF[Visual Builder workflows + Autopilot schedules]
AG --> TL
WF --> TL
end

EN -->|every model call| NAI[(NEAR AI Cloud TEE inference)]
NAI -->|signature + attestation| VER{{verify before the badge}}
TL -->|wallet routes| BE
BE -->|transfer| OL[(OutLayer wallet policy checked in a TEE)]
MW -->|store_wallet_policy, freeze_wallet| OLC[(outlayer.testnet)]
OL --> NEAR[(NEAR testnet)]
TL -->|dry quote| INT[(NEAR Intents 1Click)]
TL -->|Gmail, Calendar, Sheets, Notion…| CMP[(Composio)]
BE -->|Intel quote| TEX[(Phala TEE Explorer)]
TL -->|view_account, tx| RPC[(NEAR RPC)]
BE -.->|registry| REG[(hellonear-registry.testnet)]
```
## The parts

### One payment, call by call
<Architecture />

```mermaid
sequenceDiagram
autonumber
participant O as Owner
participant A as Mind (Mastra agent)
participant M as NEAR AI Cloud (TEE)
participant B as Backend
participant W as OutLayer (TEE)
participant N as NEAR testnet
## One payment, call by call

O->>A: "Pay 0.01 NEAR to alice.testnet"
A->>M: model call (streamed)
M-->>A: tool call near_view_account
A->>N: RPC view_account alice.testnet
N-->>A: account exists
M-->>A: tool call send_payment
Note over A: requireApproval: the run pauses (unless an owner rule covers it)
A-->>O: approval card: amount, recipient, checks
O->>B: Approve
B->>A: resume the run
A->>B: /internal/v1/wallet/send_payment (wallet token)
B->>W: transfer request
alt inside the policy
W->>N: signed transfer
N-->>W: tx hash
W-->>A: sent + txHash
else over the limit, not on the list, or frozen
W-->>A: policy_denied / wallet_frozen, no tx
end
A-->>O: receipt (or "refused before signing")
A->>M: fetch signatures + attestation
Note over A: run.verified: badge shown only if every step matches the attested key
```
<PaymentSteps />

---
1 change: 1 addition & 0 deletions apps/docs/images/apps/gmail.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions apps/docs/images/apps/google-calendar.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions apps/docs/images/apps/google-docs.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions apps/docs/images/apps/google-drive.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Loading