terum-skills / desktop
AGENTS.md28 starsChanged 58 days agoApache-2.0View on GitHub
This repo is the terum-skills desktop frontend: a Vite + React 19 + TypeScript (strict) app that runs in a browser on a mock backend and is held pixel-faithful to the boards of a private design canvas that is not part of this repository. When that canvas is on the machine, TERUM_DESIGN_DIR names its folder (build.py there generates <Board>.dc.html; .shots/<Board>.png are the read-only renders that the fidelity gate diffs against); when it is not, every design-dependent gate skips or fails…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository9 other files it gives its agents.
- AGENTS.mdAGENTS.md
- eval-reportSkill
- evalSkill
- list-skillsSkill
- search-skillsSkill
- skill-infoSkill
- skill-statusSkill
- sync-skillsSkill
- terum-skillsSkill
The file
We split this AGENTS.md into the rules it gives an agent
3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 51
Pixels come from the boards: Every screen reproduces the geometry of its <Board>.dc.html exactly: same box model, same px values, same font …
- Very specific: line 63
No shortcuts in tests or lint: Never delete or weaken a test to make a suite pass (declare any test change in testsModified).
- Very specific: line 81
Every screen, dialog, note and card also obeys desktop/docs/ui-policy.md (2026-09-14): anything printed is copyable (commands through …
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md — terum-skills-app (read this first, follow it exactly)
This repo is the terum-skills desktop frontend: a Vite + React 19 + TypeScript (strict) app that runs in a
browser on a mock backend and is held pixel-faithful to the boards of a private design canvas that is not part of this repository. When that
canvas is on the machine, TERUM_DESIGN_DIR names its folder (build.py there generates <Board>.dc.html;
.shots/<Board>.png are the read-only renders that the fidelity gate diffs against); when it is not, every
design-dependent gate skips or fails with a one-line message. Implementing agents write the app code from written
specs; the maintainers write the specs, run every gate themselves, and do all git.
The eight invariants (report each one you touch in invariantsTouched)
- The seam.
src/backend/owns every non-mock capability. Nothing outsidesrc/backend/imports@tauri-apps/*, readslocation-independent I/O, touches the filesystem, or opens a socket. No component ever branches onisTauri()or any platform probe: platform-shaped behaviour (window chrome mode, editor opening, clipboard) comes fromBackend.capabilities()and the backend methods. Screens import onlysrc/backend/types+src/backend/index(useBackend()), neversrc/backend/mock/**,src/backend/tauri/**orsrc/fixtures/**. An ESLintno-restricted-importsrule and a vitest test that greps the tree enforce this. Seam names follow the CLI pinned atb5c0507: the verb isconnect(Backend.connect(args: ConnectArgs): Run<ConnectOutcome | undefined>,ConnectResult,ConnectBatch),Backend.uninstallMachine,Backend.setup({ target?, offerConnect? }),ValidateResult { name, findings, warnings }. The Prompter has exactly five members:interactive,confirm,text,select,print(there is nosecret()). - Flags come from the CLI, and every flag has exactly one consumer.
capabilities()carriesdisablePerMachine,inboxEventLog,offtargetKind,machineRegistry,perCaseEvalTables(plus the platform-shapedwindowChrome,windowControlsEnd,openInEditor,clipboard);features()carries the CLI's twelvehello.featuresswitches plusmemberRole. The real adapter fills both from thehelloframe it caches from any run (disablePerMachinestraight across,perCaseEvalTablesfromperCase, a missing keyfalse;inboxEventLog,offtargetKind,machineRegistrystay hardfalseuntil a mechanism exists). The mock answerstrueto all of them and the UI renders every board as drawn. A control whose switch isfalseis hidden (or degraded exactly as the S7q spec table says), never disabled or stubbed; a screen reads a switch throughuseFeatures()/useCapabilities(), never by probing the platform, and never invents a flag. Gaps are recorded by the maintainers in the tracking issues; an implementing agent never invents a flag to close one,FIDELITY.md,AGENTS.md,README.mdorpackage.json— describe what you found in the report'sopenQuestions/deviationsinstead. A newls --localkey is declared optional in the app before or with the CLI that emits it, never after. - Generated files.
src/styles/tokens.cssandsrc/fixtures/design.jsonare written only bypython3 tools/export-design.py(which imports the design canvas'sbuild.pyfromTERUM_DESIGN_DIRor--design, and exits 2 with one line when neither is given;--checkexits 1 when either file is stale). Never hand-edit them; regenerate them. Fixture strings arebuild.py's values verbatim (some carry HTML entities such as<or', or inline<b>tags): decode entities for text rendering; render<b>as the design does. - The fidelity oracle.
$TERUM_DESIGN_DIR/.shots/<Board>.pngis read-only: never write, update, or "re-baseline" there, and never point Playwright's snapshot directory at it. The per-class tolerance map lives ine2e/fidelity/tolerance.tsand is authoritative:screen: 0.0030,dialog: 0.0035,state: 0.0020(empty / loading / error / no-results),full: 0.0025(full-page and stretched boards); Main and Light are exact (0 differing pixels). Those four numbers never change. No mask without a written reason inFIDELITY.md(today: none), and a test never reads a tolerance or a mask fromFIDELITY.md— it reads only each row's status. Printed command strings are the boards' verbatim (npx -y terum-skills@latest <verb>, andsharewhere the boards printshare), never re-derived from the CLI's current verbs. - Pixels come from the boards. Every screen reproduces the geometry of its
<Board>.dc.htmlexactly: same box model, same px values, same font sizes and weights (400 / 500 / 510 / 590), same colours via the tokens. Inter is@fontsource-variable/inter/standard.css(family"Inter Variable"; the default import is the wrong, wght-only binary); the mono face is@fontsource-variable/jetbrains-mono(family"JetBrains Mono Variable").bodycarriesfont-feature-settings: "cv01", "ss03"and-webkit-font-smoothing: antialiased. Icons are the design's inlinedICON_PATHS(24-viewBox, stroke 1.5,currentColor), never Lucide. Theme isdata-theme="dark" | "light"on<html>, stamped before React mounts (default dark). - The eval report is components over the receipt JSON. The UI never runs an eval itself — it drives the
CLI's
evalverb over--framesand renders its frames — and never derives a statistic: no list is sorted or ranked by a receipt number, no lift-style decimal at card level beyond what the board draws,—when there is no receipt, a greyed verdict when the run is partial, and numbers from differentmodel/cc_versionnever share one comparison surface. - No shortcuts in tests or lint. Never delete or weaken a test to make a suite pass (declare any test
change in
testsModified). Noeslint-disablewithout a reason on the same line. No test-only branches in components: every board state is reachable from the URL (?tab=,?dialog=,?rail=closed,?theme=,?menu=,?filters=open,?q=,?overview=0) and the mock scenario switch?__mock=(error | empty | loading | slow | disabled | not-installed). Handle failure modes explicitly (aResult.ok === falserenders the board's error state; an unexpected prompter question opens a new dialog; a stale fixture parse throws at boot with the field path). - The gates and the sandbox. An implementing agent runs
npm run typecheck && npm run lint && npm testand reports real counts. The maintainers run those three plusnpm run export:check,npx playwright test e2e/routes --workers=2andnpx playwright test e2e/fidelity --workers=2outside the sandbox (never runplaywright installon a maintainer's machine; CI installs its own Chromium). Inside the sandbox: no git (not evengit status), no network, nonpm install(node_modules and the generated files are already in place), no commits; verify every write by reading the file back; if a step cannot run in the sandbox (a browser will not launch), say so in the report and do not fake a result. Ambiguity → implement the most conservative reading and record the fork inopenQuestions; never resolve a design fork yourself.
The UI policy (docs/ui-policy.md)
Every screen, dialog, note and card also obeys desktop/docs/ui-policy.md (2026-09-14): anything printed is
copyable (commands through CliBox / TerminalHint / CollapsibleCommand / AdviceBlock, errors and logs through
useCopyMenu), a path is never prose (PathText, root labels), a long command collapses to a summary that still
copies the full line, a card row never wraps into another, work in flight shows in the top-bar chip and as a dot on
the covered cards, a shared hint is said once, and a long list folds. The guard test
src/components/domain/__tests__/ui-policy.test.ts fails a command printed outside those primitives.
Stack pins (do not add, remove or bump without a spec saying so)
vite 8.2.2 · react / react-dom 19.2.8 · typescript 5.9.3 (strict, noUncheckedIndexedAccess,
exactOptionalPropertyTypes, verbatimModuleSyntax) · tailwindcss 4.3.3 via @tailwindcss/vite (the theme
is reset with --*: initial and rebuilt from the design's scale; tokens.css is generated) · @base-ui/react
1.8.0 · react-router 8.3.1 with HashRouter (never react-router-dom) · @tanstack/react-query 5.102.8 ·
zustand 5.0.15 with persist (localStorage in the mock) · react-markdown 10.1.0 + remark-gfm 4.0.1 ·
zod 4.5.4 at the fixture boundary · @fontsource-variable/inter 5.3.0 (standard.css) ·
@fontsource-variable/jetbrains-mono 5.3.0 · vitest 4.1.11 + Testing Library + jsdom 30.0.1 ·
@playwright/test 1.63.0 · pixelmatch 7.2.0 + pngjs 7.0.0 for the fidelity diff · eslint 10.10.0 flat config +
typescript-eslint 8.70.0 + eslint-plugin-react-hooks + eslint-plugin-react-refresh. No Storybook, no Lucide,
no shadcn, no msw. Native: src-tauri/ (tauri 2.11, plugins opener · store · clipboard-manager · window-state · log) and @tauri-apps/api 2.11 + the matching plugin JS packages, imported only under src/backend/tauri/ (M5/M6, 2026-09-08).
Layout
index.html theme boot script (stamps data-theme from localStorage before React mounts), #root
vite.config.ts port 1420 strictPort; host from TAURI_DEV_HOST; watch.ignored src-tauri; envPrefix VITE_ + TAURI_ENV_*
tools/export-design.py build.py constants -> src/styles/tokens.css + src/fixtures/design.json (--check)
src/main.tsx createRoot; providers (backend, QueryClient, theme); ErrorBoundary
src/app/ App.tsx (HashRouter), routes.tsx (the one route table), store.ts (useUiStore), providers.tsx
src/backend/ types.ts · Backend.ts · prompter.ts · index.ts (pickBackend, useBackend) · mock/ · tauri/ (the real adapter; README there)
src-tauri/ the Tauri shell: tauri.conf.json (macOS Overlay chrome, ad-hoc signing), src/lib.rs (the CLI bridge), capabilities/
src/components/ui/ Base UI wrappers + Icon, Kbd, Button, Skeleton, Chip, Tooltip, Menu, Popover, Dialog, Select, Switch, RadioGroup, Checkbox, Slider, Tabs
src/components/domain/ TopBar, Sidebar, Footer (the shell), ViewHeader, StatTile, SkillCard, ... (design components)
src/screens/<family>/ one folder per board family (frame, library, skill, inbox, marketplace, share, settings, onboarding, search)
src/fixtures/ design.json (GENERATED) + schema.ts (zod)
src/styles/ tokens.css (GENERATED) + app.css (@import tailwindcss; @import tokens.css; @theme; fonts)
e2e/routes/ one Playwright smoke test per route + state (*.spec.ts)
e2e/fidelity/ boards.ts (name -> route, class, viewport, hover), tolerance.ts, fidelity.spec.ts, fidelity.md-parser
e2e/out/ gitignored: actual / diff PNGs and report.json
FIDELITY.md maintainer-owned board status table (never edited by an implementing agent)Conventions: .spec.ts under e2e/ is Playwright; *.test.ts(x) anywhere is vitest. PascalCase components,
use*.ts hooks, kebab-case lib modules. Every screen renders inside <ScreenFrame> which marks
document.documentElement.dataset.appReady = "true" once its content has committed (the gates wait on it).
The clock the mock reports is the design's TODAY (2026-09-06); relative times derive from it. Commit
messages, branches and merges are the maintainers' job; an implementing agent leaves changes in the working tree, unstaged.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

