Monaco docs

Monaco is an iOS app where friends pool USDC into a shared pot (a cabal), vote on which tokenized US stocks to buy on Solana, and compete on leaderboards. A cabal can also hand part of its pot to a trading agent.

Start here

Read these in order to understand the repo:

1. Product: what the app does, the words it uses, and the rules for cabals, votes, shares and money in and out.
2. Architecture: the parts of the system that stay true through the backend rewrite: outside services, wallets, and how each money flow works.
3. Architecture decisions: the decision log, one file per topic, with the reasoning and what the code has not caught up with yet.
4. Backend platform: the target design for the rewritten backend. When it and architecture.md disagree, this file states the target and architecture.md states the present.
5. README: clone, configure and run everything locally.

Reference

Doc	Read it when
architecture/backend-platform.md	You are building the new backend: rings, lint, tests, flows, NATS, deploy. The rewrite's source of truth
architecture/ci.md	You are changing CI: what runs on which PRs, runner choice, minute budget
agent-trading.md	You are building or debugging a trading agent
design.md	You are changing the iOS UI: colours, type, layout rules
multi-user-verification.md	You changed auth, membership, money or boards and need to re-verify

How-to

Guide	For
Agent workflow setup	Giving a clone the plugins, model roles, skills and rules the agent workflow runs with
Ship a ticket	Taking one ticket from its issue to a merge on the feature branch, as a person or an agent owner
Run a milestone	Orchestrating a milestone: tickets, batches, owners and verifiers, landing, restacks and the checkpoint into main
Connect a trading agent	Hooking up ClawPump or any LLM agent
Demo checklist	A manual end-to-end pass before a demo
Run on the local simulator	Simulator signing and keychain issues
Debug login	"I can't sign in"
Overnight QA	The nightly test and screenshot run, and what CI runs
Read iOS app logs	Matching a Console.app line to an API request, crash diagnostics
Gardener	The nightly dead-code, candidate-lint and generator-drift report
TestFlight	Shipping an iOS build

Operations

Doc	For
ops-profile-photos.md	Where profile photos are stored

Other folders

• demo/: the demo film's storyboard. Recording scripts are in scripts/demo.
• legacy/: older versions of the codebase and their docs, including the docs for the deleted legacy backend (api.md, ops-observability.md, ops-sweep-usdc.md, the full old architecture.md) and the build history. Not updated. Trust the docs above over anything in it.

Conventions for these docs

• Product rules go in product.md. What stays true about the system goes in architecture.md. Why it is built that way, and decisions the code has not caught up with, go in architecture/, one file per topic with a dated Log section. How to run things goes in the README or how-to/.
• Link to code by path rather than copying it.
• When code changes a rule or a flow, update the doc in the same pull request.