# AGENTS.md — Veskslop

Veskslop controls Discord user accounts without a visible client window. It runs the real Vesktop
client and drives it through a small, validated capability layer. All logic lives in the external
daemon.

**Read the docs first:** [docs/INDEX.md](docs/INDEX.md), [CURRENT.md](CURRENT.md), and
[TODO.md](TODO.md).

`CURRENT.md` tracks the work state: the current focus, the completed work, the current task, and the
next steps. `TODO.md` holds the ordered backlog. Read both before you start. Update `CURRENT.md`
before you stop.

- [architecture.md](docs/architecture.md) — system parts and boundaries
- [core-bridge.md](docs/core-bridge.md) — the Vesktop-side capability layer
- [daemon.md](docs/daemon.md) — the external MCP daemon
- [communication.md](docs/communication.md) — trust model, commands, trigger log
- [auth.md](docs/auth.md) — QR login and token persistence
- [testing.md](docs/testing.md) — tests and live test setup
- [decisions.md](docs/decisions.md) — design decisions

## Locked decisions

- Use the real Vesktop client. Do not use selfbot protocol libraries. Most are archived, and stale
  protocol emulation is a ban risk.
- The core validates. The daemon requests. The core rejects bad input with a structured error.
  The client must not crash, and the daemon must not send malformed data to Discord.
- Keep core patches isolated. Add actions in `src/renderer/puppet/` and the bridge in
  `src/main/puppetBridge.ts`. Do not spread logic through upstream files.
- The daemon holds the logic: triggers, trust list, command parsing, trigger log, and pacing.
- The daemon binds to localhost. Remote access goes over LAN or Tailscale only.
- Pacing: the daemon delays every command by 500 to 2800 ms. The core adds a hard limit of 500 ms
  between sends and 30 sends per minute.

## Guardrails

- Never commit tokens, credentials, or `.env` files.
- Do not hardcode Discord limits from memory. Make the limits configurable.
- All outbound actions go through the paced queue.
- Triggers come from trusted users only: one-to-one DMs and direct mentions.
- Test with throwaway accounts and private test guilds only.
- Live send tests: only DMs to user **zzib** (`177117296140091393`).
- Run `pnpm testTypes` and `pnpm lint` before you report done. Run `pnpm build` to compile.

## Status

| Area | Status |
| --- | --- |
| Action protocol and renderer actions | Implemented |
| Main bridge, event push, hooks | Implemented |
| Daemon on the core-bridge transport | Implemented and verified live |
| QR login, pacing, trigger log | Implemented |
| Trusted-only triggers and context cache | Implemented |
| Response policy (channel or DM) | Implemented |
| Auth persistence in the core | Implemented and verified live |
| CDP transport | Kept as a development fallback |
| Notification parsing, persistent log | Not started |
| Voice, audio, video | Not started |

## Work items

See [CURRENT.md](CURRENT.md) and [TODO.md](TODO.md) for the live list. The main items are:

1. Notification parsing: edits, deletes, reactions, and replies.
2. Persistent trigger log with rotation.
3. Per-user rate limit and command cooldowns.
4. MCP event delivery for agents.
5. Later: voice, audio, video, client lightening, web debug UI.

## Dev commands

```sh
pnpm install
pnpm build        # esbuild bundle into dist/
pnpm testTypes    # tsc --noEmit
pnpm lint

cd poc
pnpm check        # type check the daemon
pnpm test:comm    # unit tests
```