Toju/AGENTS.md

AGENTS.md

Read these files at the start of every session before doing any work:

1. agents-docs/AGENT_WORKFLOW.md — workflow and operating rules
2. agents-docs/LESSONS.md — durable rules learned from past corrections; apply any that match this session's work
3. agents-docs/AGENTS_FEATURES.md — when and how to update feature docs
4. agents-docs/FEATURES.md — feature index
5. agents-docs/ENGINEERING.md — engineering standards
6. agents-docs/CONTEXT-MAP.md — index of bounded contexts in this repo

Reference on-demand (when the workflow triggers them — see agents-docs/AGENT_WORKFLOW.md §§ 4–5):

• agents-docs/AGENTS_CONTEXT.md — contract for updating CONTEXT.md / CONTEXT-MAP.md
• agents-docs/AGENTS_ADRS.md — contract for writing architecture decision records

When working in a subdomain, also read its CONTEXT.md first:

• Product client (Angular 21): toju-app/CONTEXT.md
• Desktop shell (Electron main + preload): electron/CONTEXT.md
• Signaling server (Express + WebSocket): server/CONTEXT.md
• End-to-end tests (Playwright): e2e/CONTEXT.md
• Marketing site (Angular 19): website/CONTEXT.md
• Application documentation (Docusaurus): docs-site/CONTEXT.md

---

MetoYou (also called Toju) is a desktop-first, P2P Discord-style chat application managed as an npm-workspaces monorepo. It bundles an Angular 21 product client, an Electron 39 desktop shell with TypeORM + sql.js for local persistence, a small Node/TypeScript Express signaling server with WebSocket-based realtime, a Playwright end-to-end suite, an Angular 19 marketing site, and a Docusaurus app/plugin documentation site that ships inside the Electron build. Voice and screen-share are WebRTC, with RNNoise denoising via a WASM audio worklet.

CRITICAL — Non-negotiable rules for all agents

Test-Driven Development (MANDATORY)

Write tests before implementation code.

When creating or changing anything:

1. STOP — do not write implementation first
2. Write failing tests (RED)
3. Run tests and confirm failure (npm run test for the product client; npm run test:e2e for end-to-end; place spec files colocated with source, suffix .spec.ts)
4. Write minimal code to pass tests (GREEN)
5. Refactor while keeping tests green

This applies to all code — Angular components and services, NgRx effects/reducers, Electron IPC handlers, server CQRS handlers, websocket message handlers, plugin runtime, and domain logic. If the code lives in a package without a configured test runner (server, website, docs-site), surface that gap before adding logic there.

Lint correctness (MANDATORY)

Before completing any task:

1. Run npm run lint from the repo root (ESLint 9 flat config in eslint.config.js covers every package)
2. Fix all errors
3. Do not consider work complete until it exits with code 0

Type / build correctness (MANDATORY)

Type checks live in build scripts:

• Product client (toju-app/): npm run build (Angular CLI runs tsc with strict settings)
• Electron (electron/): npm run build:electron (invokes tsc -p tsconfig.electron.json)
• Server (server/): cd server && npm run build (invokes tsc)

If your change touches one of these packages, run the corresponding build and ensure it exits 0 before marking work complete.

Most important rule

After any change that affects API contracts, schemas, invariants, workflows, or major behavior: update the relevant agents-docs/features/<slug>.md as part of the same task — not as a follow-up. New feature area → create agents-docs/features/<slug>.md and add an entry to agents-docs/FEATURES.md (alphabetical).

The product client already maintains per-domain READMEs under toju-app/src/app/domains/<name>/README.md. When the change is fully internal to one of those bounded contexts and its surface stays the same, the domain README is the right place to update; cross-context contracts (websocket envelopes, IPC channels, server routes, plugin manifests) belong in agents-docs/features/.

Structure of further instructions

• Agent workflow & operating rules: agents-docs/AGENT_WORKFLOW.md
• Agent lessons (durable cross-session rules): agents-docs/LESSONS.md
• Engineering standards: agents-docs/ENGINEERING.md
• Feature documentation contract: agents-docs/AGENTS_FEATURES.md
• CONTEXT documentation contract: agents-docs/AGENTS_CONTEXT.md
• ADR contract: agents-docs/AGENTS_ADRS.md
• Feature index: agents-docs/FEATURES.md
• Feature docs: agents-docs/features/
• Architecture decisions: agents-docs/adr/
• Context map: agents-docs/CONTEXT-MAP.md
• Product-client domain: toju-app/CONTEXT.md
• Desktop-shell domain: electron/CONTEXT.md
• Server domain: server/CONTEXT.md
• E2E suite domain: e2e/CONTEXT.md
• Marketing-site domain: website/CONTEXT.md
• App-docs domain: docs-site/CONTEXT.md

Keep this file minimal. Do not duplicate detailed rules here.

Completion checklist

Before marking work complete:

• Tests written before implementation
• All tests passing (npm run test, plus npm run test:e2e if behavior is user-visible)
• npm run lint passes
• Affected package builds: npm run build / npm run build:electron / cd server && npm run build
• Naming conventions followed (kebab-case files; domain *.rules.ts / *.model.ts / *.component.ts suffixes)
• Errors handled
• Feature docs updated if contract/schema/invariant changed (see agents-docs/AGENTS_FEATURES.md)
• CONTEXT.md updated if a domain term was resolved or introduced (see agents-docs/AGENTS_CONTEXT.md)
• ADR written if a hard-to-reverse decision was made (see agents-docs/AGENTS_ADRS.md)
• Lesson recorded in agents-docs/LESSONS.md if this session produced a correction, revert, or hidden constraint (see triggers in agents-docs/AGENT_WORKFLOW.md)
• PR opened with summary and linked issues (Fixes #<n> / Relates to #<n>)
• Gitea Workflows checks passing