AGENTS.md — BOTSU local development

Mission

Work on the BOTSU collaborative suite from this repository. Keep development local and reversible. Production is never a development target.

Start here

Read README.md, DESIGN.md, and docs/adr/0001-development-isolation.md.
Use Node.js from .nvmrc / .node-version.
Run npm ci from the repository root. Do not run separate installs in workspaces.
Copy .env.example to .env.local if it does not exist.
Use npm run dev for the local client and presence API.

Local endpoints:

client: http://127.0.0.1:5173
presence API: http://127.0.0.1:8091
generated local state: .data/ (ignored by Git)

Repository map

apps/client: Cinny-based Matrix client and BOTSU UI
apps/client/src/botsu: BOTSU-only frontend features
apps/presence-api: local/realtime HTTP and WebSocket service
packages/protocol: validated shared wire protocol
packages/ui: BOTSU design tokens and primitives
docs: architecture, ADRs, and security notes
scripts: repeatable setup, development, and verification commands

Required workflow

Inspect existing code and tests before editing.
For behavior changes, write or update a focused test first.
Keep BOTSU code isolated from inherited Cinny code where practical.
Run the narrow test while iterating, then npm run check before committing.
Never hide inherited lint/type errors by weakening global rules.
Do not commit .env.local, .data/, credentials, Matrix tokens, generated dist/, or node_modules/.
Use conventional commits on a dedicated branch.

Safety boundaries

Do not deploy, edit /opt/services, change DNS, Traefik, firewall, SSH, NAT, or expose ports. Do not push to or merge main unless the user explicitly asks. A production promotion always requires separate explicit approval.

Useful commands

npm run dev
npm test
npm run typecheck:botsu
npm run typecheck:presence
npm run build:client
npm run check

npm run typecheck:client and npm run lint:client include inherited Cinny debt; see the ADR. npm run check contains the BOTSU-owned green gates plus a production client build.

2.1 KiB Raw Permalink Blame History