From 0185fb22417afe0b6b753c6f5d0bad902850e5c2 Mon Sep 17 00:00:00 2001 From: Guillaume De Saint Martin Date: Sat, 19 Sep 2026 09:27:45 +0200 Subject: [PATCH] [Cloud env] add UI agent guidance --- .cursor/rules/octobot-cloud.mdc | 1 + .cursor/skills/cloud-roadmap/SKILL.md | 2 + .cursor/skills/end-user-ui/SKILL.md | 65 +++++++++++++++++++ .cursor/skills/octobot-cloud/SKILL.md | 1 + AGENTS.md | 1 + packages/tentacles/AGENTS.md | 11 ++++ .../Interfaces/node_web_interface/AGENTS.md | 38 +++++++++++ .../Interfaces/node_web_interface/README.md | 5 ++ .../Interfaces/web_interface/AGENTS.md | 34 ++++++++++ 9 files changed, 158 insertions(+) create mode 100644 .cursor/skills/end-user-ui/SKILL.md create mode 100644 packages/tentacles/Services/Interfaces/node_web_interface/AGENTS.md create mode 100644 packages/tentacles/Services/Interfaces/web_interface/AGENTS.md diff --git a/.cursor/rules/octobot-cloud.mdc b/.cursor/rules/octobot-cloud.mdc index ed1c5f3e2d..5c4e11f6a3 100644 --- a/.cursor/rules/octobot-cloud.mdc +++ b/.cursor/rules/octobot-cloud.mdc @@ -11,6 +11,7 @@ alwaysApply: true - **Tentacles:** edit only `packages/tentacles/`; after changes run `bash .cursor/reinstall-tentacles.sh`. Never commit repo-root `tentacles/`. - **Git:** checkout `dev` (or user base) → feature branch → commit → open PR to **`dev`** unless the user specifies another target. Do not commit agent plan files (`PLAN-*.md`, `*.plan.md`, `.cursor/plans/`); use Plan mode or chat only — delete scratch plans before staging (`path.deny_agent_plans`). Do **not** edit agent docs (`**/AGENTS.md`, `.cursor/skills/**`, `.cursor/rules/**`, `.cursor/README.md`, `CONTRIBUTING-agent.md`, `tools/**/README.md`, `tools/**/ARCHITECTURE.md`) unless the task owns them; if diffs are out of scope, `git checkout origin/ -- ` before commit (`agent_docs.no_regression_vs_merge_base`). - **Node UI tests:** Vitest (`npm test`) + Python/API tests; do not add `node_web_interface/e2e/` or Playwright specs (`path.deny_node_web_playwright_e2e`). Optional live UI QA via skill **agent-seed**, not committed e2e. +- **UI copy/layout:** For `packages/tentacles/Services/Interfaces/node_web_interface/` or `.../web_interface/`, read skill **end-user-ui** (entry-level trading OK, no pro jargon, minimal, no slop, no em dash in UI strings). - Before handoff: `python -m tools.extended_linter --base origin/dev` (use `origin/` matching the PR target). - No `pip install` / `npm install` to fix imports. No edits under `user/` or secret/env files. - Cross-package or tentacles work: read root `AGENTS.md` and colocated `AGENTS.md` for every area you touch (`octobot/`, `packages//`, `packages/tentacles/`). diff --git a/.cursor/skills/cloud-roadmap/SKILL.md b/.cursor/skills/cloud-roadmap/SKILL.md index 619b5a155c..f2059f5b15 100644 --- a/.cursor/skills/cloud-roadmap/SKILL.md +++ b/.cursor/skills/cloud-roadmap/SKILL.md @@ -96,6 +96,7 @@ Pytest matrix: [reference-pytest.md](../octobot-cloud/reference-pytest.md) (skil |-------|-------------|--------| | Unit (Python) | Test path + enumerated behaviors | Package `tests/` or `tools/tests/…` per `AGENTS.md` **Tests** | | Unit (Node UI) | TS under `packages/tentacles/Services/Interfaces/node_web_interface/` | `src/**/__tests__`; cwd that directory; `npm test` (vitest). Profile **`ui-node-web`** if build env needed. | +| UI copy / UX | User-visible strings or layout in `node_web_interface` or `web_interface` | Review against skill **end-user-ui** (incl. no em dash in copy); Vitest or `web_interface` pytest per stack. | | Functional / integration | Cross-package or I/O flows | `tools/tests`, integration dirs, tentacles-dependent pytest | | UI functional | Browser / seeded grid | Default **N/A — Vitest + API tests**; **agent-seed** only when the user explicitly wants manual `/app` QA — **not** new Playwright `e2e/` files in git (`path.deny_node_web_playwright_e2e`) | @@ -117,6 +118,7 @@ Pytest matrix: [reference-pytest.md](../octobot-cloud/reference-pytest.md) (skil | Implement / verify in cloud | **octobot-cloud** | | Pytest cwd / PYTHONPATH | **octobot-cloud** → `reference-pytest.md` | | Node UI unit tests | `packages/tentacles/Services/Interfaces/node_web_interface/` → `npm test` | +| End-user UI copy | skill **end-user-ui** + colocated UI `AGENTS.md` | | Node UI browser QA | **agent-seed** | | Package boundaries | colocated `AGENTS.md` | | Contributor workflow | `CONTRIBUTING-agent.md` | diff --git a/.cursor/skills/end-user-ui/SKILL.md b/.cursor/skills/end-user-ui/SKILL.md new file mode 100644 index 0000000000..a65cf8c6cd --- /dev/null +++ b/.cursor/skills/end-user-ui/SKILL.md @@ -0,0 +1,65 @@ +--- +name: end-user-ui +description: >- + End-user UX for node_web_interface (React) and web_interface (Flask/templates): + entry-level trading terms OK, no pro-trader jargon, minimal UI, situational focus, + no AI slop, no em dash in UI strings. Apply on any UI copy, + layout, error, or help change. +paths: + - packages/tentacles/Services/Interfaces/node_web_interface/** + - packages/tentacles/Services/Interfaces/web_interface/** +--- + +# End-user UI (node + classic web) + +Apply whenever you change user-visible copy, layout, errors, or help in the Node React UI or the classic Flask web UI tentacles. + +## Sources only (tentacles) + +- Edit UI only under `packages/tentacles/Services/Interfaces/node_web_interface/` or `packages/tentacles/Services/Interfaces/web_interface/`. +- Do not open or patch repo-root `tentacles/` (install output). After tentacles source changes: `bash .cursor/reinstall-tentacles.sh`. + +Colocated guides: `packages/tentacles/Services/Interfaces/node_web_interface/AGENTS.md`, `.../web_interface/AGENTS.md`. Technical Node UI workflow (when present in the monorepo): workspace skill **node-web-interface-workflow**; cloud agents: skill **octobot-cloud** and `node_web_interface/README.md` for npm cwd. + +## Audience + +- Assume an **average non-technical** user who may be new to OctoBot but is using a **trading bot**. Not a developer, not a pro desk. +- One primary goal per screen or step: show status, fix one problem, or confirm one action. + +## Language: entry-level trading OK; pro/advanced not + +- **OK:** everyday trading vocabulary users expect: buy/sell, order, pair, exchange, balance, profit/loss, stop loss, take profit, market/limit, position (when the feature uses it). Keep terms **short and consistent** with labels elsewhere in the app. +- **Avoid:** advanced or pro-trader jargon: maker/taker fee tiers, funding rate mechanics, delta-neutral, basis, slippage models, OCO/iceberg unless the UI is explicitly an advanced screen; desk slang; dense acronyms without expansion on first use in that flow. +- **Dev/infra:** still translate. Avoid "credentials", "auth payload", "session invalidated" without plain-language equivalent ("password" / "passphrase" per product). + +## Understandable + +- Short sentences; active voice; say what happened and what to do next. +- If a term is required, prefer **entry-level trading** over **pro**; add one short gloss only when the screen cannot work without it (not a glossary block). +- Errors: **title + one explanation**; optional **at most 1–2** tips only when they change behavior. Not a wall of suggestions. + +## Simple (less is better) + +- Remove or defer secondary info, debug detail, and duplicate controls. +- Progressive disclosure: advanced fields behind "Advanced" or debug routes only (`/app/debug` stays operator-facing). +- Empty states: one line what this is plus one action. Not essays. + +## No AI slop + +- Ban list (examples): filler openers ("Certainly", "Great question"), **marketing** buzzwords ("seamless", "robust", "empower", "leverage" as hype), emoji decoration, generic tip lists, three-panel "guidance" when one line suffices, marketing tone in errors. +- **No em dash (`—`) in user-visible UI copy** (labels, titles, errors, toasts, template text). Use a period, comma, colon, or parentheses instead; match punctuation already used on the same screen. +- Match **existing** OctoBot/Node UI tone in nearby components; read siblings before inventing new patterns. +- Do not add UI "just to be helpful" if Vitest/API already cover behavior; user-visible text must earn its space. + +## By stack + +| Stack | Where copy lives | +|-------|------------------| +| `node_web_interface` | React components, route copy, toasts; keep logic in code/tests per skill **octobot-cloud** (Vitest, no e2e). | +| `web_interface` | Jinja templates, flash messages, modal titles; Python strings visible in templates. | + +## Before handoff (UI PR) + +- Re-read changed strings aloud as a non-expert. +- `npm test` in `packages/tentacles/Services/Interfaces/node_web_interface/` when touched; pytest for `web_interface/tests` when touched. +- No new Playwright e2e; agent-seed only if the user asked for live QA. diff --git a/.cursor/skills/octobot-cloud/SKILL.md b/.cursor/skills/octobot-cloud/SKILL.md index 9f52fb72aa..35760294b7 100644 --- a/.cursor/skills/octobot-cloud/SKILL.md +++ b/.cursor/skills/octobot-cloud/SKILL.md @@ -63,6 +63,7 @@ See **[reference-pytest.md](reference-pytest.md)** for cwd and PYTHONPATH per CI ## Node UI tests (agents) +- **User-visible UI:** For copy, layout, errors, or help in `node_web_interface` or classic `web_interface`, read skill **end-user-ui** (`.cursor/skills/end-user-ui/SKILL.md`) and colocated `AGENTS.md` under those tentacle paths. - **In PRs:** Vitest in `packages/tentacles/Services/Interfaces/node_web_interface/` (`npm test`) plus Python/API tests (`node_api_interface`, `packages/node`, tentacles pytest as needed). **Do not** add Playwright e2e under `e2e/` or `test:e2e` scripts (`path.deny_node_web_playwright_e2e`). - CI runs Vitest for tentacles `package.json` projects; e2e is not in the matrix. diff --git a/AGENTS.md b/AGENTS.md index 1f7690e166..5546ec3bb3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,6 +29,7 @@ Colocated **`AGENTS.md`** files describe package boundaries (owns, deps, tests). | Single package task | `packages//AGENTS.md` | | Core app / CLI / config | [`octobot/AGENTS.md`](octobot/AGENTS.md) | | Tentacles sources vs install | [`packages/tentacles/AGENTS.md`](packages/tentacles/AGENTS.md) | +| Node UI or classic web UI (copy, layout, errors) | [`packages/tentacles/Services/Interfaces/node_web_interface/AGENTS.md`](packages/tentacles/Services/Interfaces/node_web_interface/AGENTS.md), [`packages/tentacles/Services/Interfaces/web_interface/AGENTS.md`](packages/tentacles/Services/Interfaces/web_interface/AGENTS.md), skill **end-user-ui** (`.cursor/skills/end-user-ui/SKILL.md`) | | Cross-package or tentacles | This file + every involved colocated `AGENTS.md` | | Node UI demo / agent-seed QA | [`tools/agent_seed/README.md`](tools/agent_seed/README.md) + skill **agent-seed** (`.cursor/skills/agent-seed/SKILL.md`) | diff --git a/packages/tentacles/AGENTS.md b/packages/tentacles/AGENTS.md index 1a81dea071..65ddd26343 100644 --- a/packages/tentacles/AGENTS.md +++ b/packages/tentacles/AGENTS.md @@ -61,6 +61,17 @@ npm run generate-client See `node_web_interface/README.md` (openapi generated by node_api_interface). Wire protocol models: [`../protocol/AGENTS.md`](../protocol/AGENTS.md). + +## End-user UI + +Node and classic web UI tentacles share end-user copy rules. Before layout or user-visible text changes, read: + +- `packages/tentacles/Services/Interfaces/node_web_interface/AGENTS.md` +- `packages/tentacles/Services/Interfaces/web_interface/AGENTS.md` +- Skill **end-user-ui** (`.cursor/skills/end-user-ui/SKILL.md`) + +Edit sources only under `packages/tentacles/`; never repo-root `tentacles/`. + ## Tests - Often via `octobot` job: `pytest --ignore=tentacles/Trading/Exchange tentacles` diff --git a/packages/tentacles/Services/Interfaces/node_web_interface/AGENTS.md b/packages/tentacles/Services/Interfaces/node_web_interface/AGENTS.md new file mode 100644 index 0000000000..1f72a2e219 --- /dev/null +++ b/packages/tentacles/Services/Interfaces/node_web_interface/AGENTS.md @@ -0,0 +1,38 @@ +# Agents: node_web_interface + +## Role + +Node product **React** web UI (`octobot-node`): Vite, TanStack Router/Query, Tailwind. Built bundle in `dist/` ships with the tentacle. + +## End-user UX (mandatory) + +Read skill **end-user-ui** (`.cursor/skills/end-user-ui/SKILL.md`) before any user-visible copy, layout, error, or help change. + +- Entry-level trading terms OK; no pro-trader jargon. +- Minimal UI; one primary goal per screen. +- No AI slop; no em dash (`—`) in user-visible strings. + +## Owns + +- `src/`, tests, `package.json` under **this** `packages/tentacles/.../node_web_interface/` path +- Not `src/client/*` (generated via `npm run generate-client`) +- Not repo-root `tentacles/` (install output) + +## Do not + +- Edit repo-root `tentacles/`; after source changes run `bash .cursor/reinstall-tentacles.sh` +- Hand-edit `openapi.json` or generated client files (see [`../../../AGENTS.md`](../../../AGENTS.md#node-rest-openapi-node_api_interface--node_web_interface)) +- Add Playwright e2e under `e2e/` (`path.deny_node_web_playwright_e2e`) + +## Tests + +- `npm test` (Vitest) from this directory; see [README.md](README.md) + +## Related + +- Tentacles index: [`packages/tentacles/AGENTS.md`](../../../AGENTS.md) +- Node REST OpenAPI: `node_api_interface` tentacle (same parent `Services/Interfaces/`) + +## Last reviewed + +- 2026-09-19 diff --git a/packages/tentacles/Services/Interfaces/node_web_interface/README.md b/packages/tentacles/Services/Interfaces/node_web_interface/README.md index 5377fd2c52..6b0ed4693b 100644 --- a/packages/tentacles/Services/Interfaces/node_web_interface/README.md +++ b/packages/tentacles/Services/Interfaces/node_web_interface/README.md @@ -3,6 +3,11 @@ React web UI for the OctoBot node API, packaged as a tentacle. Built with Vite, TanStack Router/Query, and Tailwind. The compiled bundle in `dist/` is what ships in the tentacle package. +**Agents:** User-visible copy and layout follow [AGENTS.md](AGENTS.md) and skill **end-user-ui** +([`.cursor/skills/end-user-ui/SKILL.md`](../../../../../.cursor/skills/end-user-ui/SKILL.md)) +under the OctoBot repo root. Edit sources here in `packages/tentacles/.../node_web_interface/` only; +never repo-root `tentacles/`. + ## Requirements Node 24 (see `.nvmrc`). Run `nvm use` before any npm command. diff --git a/packages/tentacles/Services/Interfaces/web_interface/AGENTS.md b/packages/tentacles/Services/Interfaces/web_interface/AGENTS.md new file mode 100644 index 0000000000..afb82c5d50 --- /dev/null +++ b/packages/tentacles/Services/Interfaces/web_interface/AGENTS.md @@ -0,0 +1,34 @@ +# Agents: web_interface + +## Role + +Classic OctoBot **Flask** web UI: Jinja templates, static assets, and controllers that drive user-facing pages. + +## End-user UX (mandatory) + +Read skill **end-user-ui** (`.cursor/skills/end-user-ui/SKILL.md`) before templates, flash messages, modal titles, or any user-visible string change. + +- Entry-level trading terms OK; no pro-trader jargon. +- Minimal UI; one primary goal per screen. +- No AI slop; no em dash (`—`) in user-visible strings. + +## Owns + +- `templates/`, `static/`, and user-visible controller copy under **this** `packages/tentacles/.../web_interface/` path +- Tests under `tests/` when present + +## Do not + +- Edit repo-root `tentacles/` (install output). After source changes: `bash .cursor/reinstall-tentacles.sh` + +## Tests + +- Pytest under this tentacle's `tests/` when present; follow [`packages/tentacles/AGENTS.md`](../../../AGENTS.md) for broader tentacles pytest invocations + +## Related + +- Tentacles index: [`packages/tentacles/AGENTS.md`](../../../AGENTS.md) + +## Last reviewed + +- 2026-09-19