# PoolScout v0.4.0: Rules for the AI coding agent

This file goes with `PRD-v0.4.0.md` (Draft 1.4). The PRD says **what** to build. This file says **how** to build it and **what you must never do**. Read both files in full before you write any code.

---

## 1. Role and mission

You are the engineer building **PoolScout v0.4.0** for the owner, King. PoolScout is a self-custody LP workstation for Meteora on Solana.

- **The PRD is the source of truth** for features, priorities, milestones, APIs, data model and acceptance criteria. Cite PRD sections by number (for example "PRD 4.10") in commits, PR notes and reports.
- **If this file and the PRD conflict, this file's prohibitions (section 3) and mandatory rules (section 4) win.** Flag the conflict in your report.
- **Do not guess.** If a requirement is ambiguous, missing, or depends on an open decision (section 8.4), stop that item, write down the question, and continue with work that is not blocked.
- **Work in small, verifiable steps.** Every change must keep the app working for the owner's current v0.3.1 setup.
- **Safety is more important than speed.** This software signs real Solana transactions with real money. When in doubt, choose the safer default and report it.

---

## 2. Product context (brief)

| Item | Value |
|---|---|
| Surfaces | Chrome MV3 **side-panel extension** (React, TypeScript, Vite); a **local Node backend** (Node 22, TypeScript, Hono, better-sqlite3, run with `tsx`); a **web app** (M4, UI only, pairs with the extension); a **mobile app** (M5, Expo / React Native + TypeScript, Android and iOS, UI only, pairs with the user's backend or VPS) |
| Where it runs | The owner's Windows PC, install folder `C:\Users\Ponks_sol\PoolScout`. The backend listens on `http://localhost:8787` |
| Venues | **Meteora only: DLMM (`LBUZ…`) and DAMM v2 (`cpam…`).** PumpSwap is postponed; its code stays off behind `ENABLE_PUMPSWAP` |
| Deployed version | **v0.3.1** (extension 0.3.1, backend 0.3.x) |
| Target version | **v0.4.0** |
| Repo layout | Today: `extension/`, `server/`, `docs/`. From M4: a **pnpm + Turborepo monorepo** (a suggestion, PRD 4.24) with `apps/extension`, `apps/web`, `apps/mobile`, `apps/server` and shared packages for types, API client, Meteora math and formatting, and design tokens. Do not restructure in M1 unless the owner asks. |
| Key SDKs | `@meteora-ag/dlmm` 1.9.x, `@meteora-ag/cp-amm-sdk` 1.5.x, `@solana/web3.js` 1.x, Jupiter swap API, Helius RPC and WebSocket. Mobile (M5): Expo, EAS Build, `expo-updates`, `expo-notifications`. Optional later: Solana Mobile Wallet Adapter (development build only, not Expo Go, Android-first). |

### Milestones (PRD section 7)

| Milestone | Theme | PRD features |
|---|---|---|
| **M0** | Prerequisites | Fresh Helius key, small live smoke test. **Owner-run only** (see 3.6) |
| **M1 Parity** | Close the gaps | 4.15 Self-hosted VPS mode, 4.16 Jito landing, 4.10 Copy quality (with the 4.7 fee-checked filter and the 4.11 rugged-token exit), 4.4 Token safety, 4.9 Open positions UI |
| **M2 Win** | Differentiators | 4.12 Demo, 4.6 Wallet Tracker, 4.1 Create pool, 4.13 PnL card v2, 4.5 New pool alerts, 4.18 Indonesian locale, 4.19 Pre-open simulation, 4.20 Daily recap, 4.21 Token watchlist, 4.22 Copy backtest |
| **M3 Depth** | Completeness | 4.2 Discover, 4.3 Pools filters, 4.7 Smart LP (rest), 4.8 Portfolio, 4.11 Automation refine (rest), 4.17 Trust and security page |
| **M4 Reach** | Web | 4.23 and 4a Web app paired with the extension, 4.14 Referral (UI and tracking only); introduce the monorepo |
| **M5 Mobile** | Phone | 4.24 Expo mobile app (Android and iOS), pairing, push. **Do not start M5 until the owner explicitly approves it.** |
| **Gated** | Owner decision | Fee collection, referral rewards, open-source release. **Do not build** (see 3.9) |

**Build order: M1 first, then M2, M3, M4, then M5, in that order.** Do not start a later milestone until the earlier one meets its Definition of Done (section 8.2), unless the owner says otherwise. **M5 must not start before the owner explicitly approves starting the mobile app**, even if M4 is done. Before M2 (and before M5), check whether the PRD 4b design-coverage table still lists that milestone's screens as "Missing". If it does, ask the owner for mockups or approval of your layout first.

---

## 3. Hard prohibitions (MUST NOT)

Any violation is a release blocker. If a task seems to need one of these, stop and ask.

### 3.1 Custody and signing
- **MUST NOT** add a hosted signer, cloud wallet, MPC or custodial service, or any server that holds or uses a private key.
- **MUST NOT** add a custody vault program, an on-chain operator key, a delegated authority, or any key other than the user's own hot-wallet key.
- **MUST NOT** send a private key, keystore file or master key over any network. The only exception is the user's own self-hosted VPS (PRD 4.15), where the key is generated or imported **in the server terminal**. Extension key import is disabled for remote backends by default.
- The **web app (M4) is UI only.** It pairs with the installed extension (PRD 4a). It never signs, never holds keys, never calls `localhost` directly, and never sees `X-PoolScout-Token`. All signing and automation stay in the extension and the local backend, or the user's own VPS.
- The **mobile app (M5, PRD 4.24) is UI only**, under the same custody model as the web app (PRD 4a). It pairs with the user's local backend (HTTPS or a secure tunnel) or self-hosted VPS. **MUST NOT** store, import, generate, or display a private key, seed phrase, or PIN on the device (not in the app, Keychain, Keystore, or secure enclave). **MUST NOT** sign transactions in the mobile app, except through the user's external wallet via Solana Mobile Wallet Adapter **and only if the owner later approves that scope**. **MUST NOT** assume Expo Go for MWA or other native modules: MWA requires an Expo development build (or EAS build), is Android-first, and must not be offered inside Expo Go. The phone never receives `X-PoolScout-Token` or the keystore. There is no hosted signer.

### 3.2 Secrets
- **MUST NOT** log, print, return from an endpoint, show in the UI, write to SQLite, include in an error, test fixture, screenshot or commit any of these:
  - private keys;
  - `data/keystore.json` contents or `data/.master.key`;
  - Helius API keys;
  - `COPY_API_TOKEN`;
  - Telegram bot tokens;
  - WAHA API keys;
  - any `.env` content.
- The single allowed exception is the existing one: the newly created private key is shown **once**, blurred, after *Create new wallet*.
- Keep the redaction helpers. Every new log line or error that could contain a URL with a key or a token must go through redaction.
- `.env`, `data/`, keystore files and `pairing.json` stay in `.gitignore`. Never commit them and never put them in a release zip.

### 3.3 Onboarding and keys
- **MUST NOT** add seed phrases, mnemonics or BIP39 in any form, including in the mobile app. Backend onboarding is **private key only**:
  - *Create* generates a keypair and shows the key once.
  - *Import* accepts a base58 secret key or a 64-number JSON array.
- **MUST NOT** add a PIN, password or unlock step, including on the phone.
- The key is stored encrypted (AES-256-GCM) with the machine master key on the backend (`data/keystore.json` plus `data/.master.key`). The `.env` fallback `COPY_WALLET_PRIVATE_KEY` must keep working; if both exist, the keystore wins.
- The mockups `copy/onboarding/set-pin` and `copy/onboarding/create-seed` are **obsolete**. Do not implement them.

### 3.4 Privacy
- **MUST NOT** add telemetry, analytics or crash reporting that sends wallet addresses, balances, positions or any user data to third parties.
- Allowed outbound traffic:
  - Solana RPC (Helius, the public RPC, a Jito block engine);
  - Meteora APIs, Jupiter, RugCheck;
  - Telegram, the user's own WAHA;
  - from M4, the referral service and web origin, as PRD 6 "Privacy" allows.
- Any new outbound host must be listed in your report.

### 3.5 Safe defaults
- **MUST NOT** change these defaults, for new installs, migrations, Demo mode exits or any "reset":
  - copy master switch **OFF**;
  - dry run **ON**;
  - 0.05 SOL reserve;
  - risk limits: max 0.1 SOL per position, 0.5 SOL total, 3 positions;
  - Meme Protection **ON**;
  - fund-loss pause **ON** (20%);
  - skip Risky tokens **ON**.
- Only the user may turn dry run off or arm copy, through an explicit UI action.
- **MUST NOT** silently turn on copy, Auto Range or TP/SL for existing positions during a migration. The only automation that defaults ON is the rugged-token safety exit (4.9).

### 3.6 Live transactions
- **MUST NOT** send any mainnet transaction from tests, scripts, CI or your own verification without **explicit written approval from the owner for that specific run**: amount, action and wallet.
- Tests use mocks, simulation (`simulateTransaction`), dry run, Demo mode or devnet.
- M0 live smoke tests are run by the owner, or by you only after approval.

### 3.7 Scope
- **MUST NOT** add chains, DEXes or protocols beyond the PRD: no Raydium, Orca, Uniswap or EVM, and no PumpSwap unless the owner re-enables it.
- **MUST NOT** add a public API, CLI for third parties, or MCP server (PRD 1, non-goals).
- **MUST NOT** build features that are not in the PRD. Propose them in your report instead.

### 3.8 Data honesty
- **MUST NOT** show fake, placeholder or sample data as real. Mockup sample values (for example "mihao", "Whale A", referral rates) are not product data.
- Demo mode, dry run, estimates and simulations must always be labelled ("DEMO", "Dry run", "Estimate", "Simulation").
- **Missing data never passes.** Any safety check, pool filter, copy filter or screening rule whose input is missing, stale or errored counts as **not passed**. The token or pool is skipped and the reason is logged.
- **Unknown safety is never shown as Safe** (PRD 4.4).
- If data is unavailable, say so ("Unavailable", plus the reason). Never show 0, an empty list or a default that looks real.

### 3.9 Money
- **MUST NOT** add any PoolScout fee, fee transfer instruction, treasury wallet, subscription check or referral reward payout. These are gated until the owner decides the fee model (PRD 5 and 8).
- Referral (PRD 4.14) is UI and tracking only. Reward amounts must not appear anywhere.

### 3.10 Content and formats
- **MUST NOT** add a Story (9:16) share card. PnL cards are only **Landscape 1600×900** and **Square 1080×1080** (PRD 4.13).
- **MUST NOT** use Indonesian (or any non-English language) in code, identifiers, comments, UI copy, notifications, docs or commit messages. The only exception is the planned Indonesian locale file(s) for PRD 4.18 (for example `locales/id.json`).
- English is the default and source locale. All project content is professional English.
- **MUST NOT** use offensive or unverifiable token logos on share cards. Fall back to a letter badge.

### 3.11 Destructive operations
- **MUST NOT** delete, rewrite or reset the owner's SQLite database, keystore or `.env`.
- **MUST NOT** change the existing column meanings in v0.3.1 tables (section 7.6).
- **MUST NOT** run `git push --force`, rewrite published history, or delete branches without the owner's approval.

---

## 4. Mandatory safety and trading rules

These apply to every code path that builds or sends a transaction: manual, copy, automation and create pool.

1. **Simulate before signing.** Every transaction is simulated (`simulateTransaction`) before it is signed and sent. If simulation fails, do not send; show a friendly error and log the reason code.
2. **Dry run and Demo never send.** In dry run or Demo mode, no `sendTransaction`, `sendRawTransaction` or Jito bundle call may happen. Enforce this with a single guarded sender module and a unit test.
3. **Confirmation for destructive or value-moving actions.** These need an explicit confirm sheet that shows amounts, fees and rent:
   - close, remove liquidity, panic close-all;
   - create pool;
   - remove wallet;
   - turning dry run off;
   - arming copy.

   From the web app (M4), every write needs a confirm **in the extension** (PRD 4a). From the mobile app (M5), every write needs a confirm **in the app**; the backend signs. The phone cannot remove the wallet, export the key, or rotate the backend token.
4. **Rent preview** before signing, shown on open, add, rebalance and create pool (PRD 4.1, 4.9):
   - DLMM **position rent ~0.057 SOL is refundable** on close;
   - each new DLMM **bin array ~0.071 SOL is non-refundable**. List every new bin array and its cost;
   - DLMM pool accounts ~0.012 SOL are non-refundable; DAMM v2 pool creation ~0.02–0.03 SOL.
   - These figures are estimates. Use simulated values when available and label the rest as estimates.
5. **DLMM limits:**
   - max **69 bins per position**. Larger ranges are refused or split, only if the PRD allows it;
   - **bin step and base fee are immutable** after pool creation. Say so in the create-pool review;
   - one pool per pair + bin step + base fee. Check for duplicates before create (PRD 4.1).
6. **Initial price guard** for create pool: warn when the price is more than 5% from market, block when more than 20%.
7. **Slippage and limits:**
   - default slippage 100 bps;
   - always respect the risk limits, the 0.05 SOL reserve, per-wallet limits (PRD 4.10) and daily caps;
   - if the balance is below the next position plus reserve, pause opens and show the Deposit link.
8. **Auto Range fee-coverage gate** (PRD 4.11), default ON at 100%:
   - re-centre a DLMM position only when recent fees cover the estimated swap cost plus any new non-refundable bin-array rent; otherwise hold and log `NOT_COVERED`;
   - enforce max rebalances per day (default 8) and the minimum gap (default 30 min).
9. **Rugged-token auto-exit** (PRD 4.4, 4.11), default ON: when the RugCheck monitor flags a token in an open position, close, claim and swap to SOL, then notify. **Exit wins over rebalance.**
10. **Copy quality** (PRD 4.10):
    - Meme Protection: skip when more than 95% of the deposit would be in the non-SOL token;
    - fund-loss pause at 20%. Exits still follow the leader while paused;
    - fee-checked leaders: skip when fees are under 10% of profit, unless the user overrides;
    - every leader action writes exactly **one** Copy Log row with a reason code.
11. **Jito and fees** (PRD 4.16):
    - never exceed the tip cap per bundle or the daily tip budget;
    - clamp the priority fee to the user's max;
    - on fallback to RPC, use an idempotency check (same blockhash and signature tracking) so a transaction **never executes twice**;
    - when the daily tip budget is used up, switch to RPC only and notify.
12. **Re-check before live open:** re-check mint and freeze authority immediately before every live open.
13. **Panic close-all** must keep working and must turn auto-copy off.
14. **Restart reconciliation** (PRD 6 "Reliability"): on start, reconcile open positions on-chain, process missed leader exits first, then run automation, then send one summary.
15. **One signer per key:** two backends (PC and VPS) must never run automation for the same key. The second refuses and alerts (PRD 4.15).

---

## 5. UI and design system

Build on the v0.3.1 compact CSS (`extension/src/native.css` plus the v0.3.1 override block). Match the mockups.

### 5.1 Layout
- Compact, native-mobile look inside the side panel.
- **Bottom tab bar:** Pools, Radar, Copy, Wallets, More.
- Spacious, with **few borders and dividers**. Group with spacing, not boxes.
- **Details stay hidden until tapped** (sheets, expandable rows). Lists show only the essentials.

### 5.2 Type scale (max font weight 600)

| Use | Size |
|---|---|
| Screen titles | 17 px |
| Body | 13 px |
| Key numbers | 15 px (hero numbers 22 px) |
| Secondary and meta | 11 px |
| Tab labels | 10 px |

### 5.3 Color and components
- **One accent color.** **Green and red only for PnL** (and the PnL figure on share cards). Do not use red or green for anything else; use neutral tones or the accent.
- **Circular token logos.** Use a letter badge when a logo is missing or unverifiable.
- **Small, soft, borderless badges** (tier S/A/B, In range, Copying, DEMO, Dry run, Estimate).
- **Toggles are 32×18.**
- **Pool type is plain text**, not a colored chip:
  - DLMM rows look like `DLMM · Bin 80 · Fee 0.8%`;
  - DAMM v2 rows show the fee schedule, for example `DAMM v2 · Fee 12.4% → 1%`, or `DAMM v2 · Fee 1%` when the fee is fixed.
- **Errors** are friendly mapped messages (`extension/src/errors.ts`): no bordered error boxes and no raw backend text. A disabled button gets a one-line hint, plus an action (for example Deposit) when it helps.
- All times are shown in **UTC+7** with a label.
- PnL share cards (PRD 4.13):
  - only **Landscape 1600×900** and **Square 1080×1080**, Terminal style;
  - layout: black background, brand lockup at the top left, referral at the top right, big token name, large SOL PnL, and Invested / Position / PnL columns with USD in brackets;
  - customizable, with choices saved as the default.

### 5.4 Mockups

Location: `/workspace/poolscout-mockup/`. These are the owner's working files; ask him for a copy if they are not in your workspace. PNG and HTML pairs, 400×800 at 2×.

| Folder | Covers (PRD) |
|---|---|
| `positions/` | 4.9 Open positions list, detail, close, add, claim, empty |
| `bin-step/` | Bin step and fee display, pools filter sheet (4.3), pool detail, positions, wallet profile, Radar |
| `safety/` | 4.4 Token safety chip, sheets, open warnings, copy skip |
| `create-pool/` | 4.1 Create pool flow, steps 0 to g |
| `wallet-tracker/` | 4.6 Tracker and leaderboard star |
| `demo/` | 4.12 Demo mode |
| `alerts/` | 4.5 New pool alerts, Telegram message style |
| `pnl-card-v2/` | 4.13 Share cards (current). `pnl-card/` is the older v1 and includes the excluded Story format |
| `referral/` | 4.14 Referral (rates shown are sample terms only) |
| `copy/` | v0.3 baseline screens: copy settings, feed, notifications, more, wallet profile, PnL calendar, open position, calculator |
| `copy/onboarding/` | v0.3 onboarding. **`set-pin` and `create-seed` are obsolete**; the current onboarding is in `extension/screens/compact/onb-*.png` |
| `ref/` | A visual reference image only |

Current extension screenshots: `/workspace/poolscout/extension/screens/compact/`.

**Screens with no mockup** are listed in PRD 4b as "Missing" or "Partial". Before building one, either get a mockup from the owner, or build it with the design system above and include screenshots in your report for approval.

---

## 6. Notifications

- Channels are **Telegram** (a bot token plus chat ID) and **WhatsApp through the user's self-hosted WAHA** (`devlikeapro/waha` in Docker on the user's machine, session `default`). There is no hosted messaging service. The mobile app (M5) also uses **expo-notifications** for position, take-profit, stop-loss, rugged-token and out-of-range alerts; the push provider is an open question (PRD 8). Push payloads must not include secrets or keys; the app should fetch details from the paired backend.
- In WAHA setup screens and docs, advise users to **use a secondary or backup WhatsApp number**, because automated messages can get a number banned. Telegram is the primary channel.
- Messages:
  - are in English by default, or Indonesian when the locale is `id` (PRD 4.18);
  - include pool and transaction links;
  - never include secrets or full private data beyond what the user configured.
- Respect per-event toggles, minimum size, **quiet hours (UTC+7)** and rate limits; group bursts into one summary.
- If WhatsApp is disconnected, fall back to Telegram and show the channel as disconnected in the app.
- New v0.4.0 events:
  - copy skipped or failed, fund-loss pause, rug exit (M1);
  - backend down, restart and offline summary (PRD 4.15);
  - new pool and watchlist (PRD 4.5, 4.21);
  - daily recap (PRD 4.20).
- Every channel has *Send test*.

---

## 7. Engineering standards

### 7.1 Language and structure
- **TypeScript in strict mode** everywhere. No `any` without a comment explaining why.
- Backend:
  - Hono routes per domain (`server/src/<domain>/routes.ts`);
  - logic in services;
  - SQLite access in store modules;
  - Solana transaction building in `server/src/copy/` (or a new `server/src/chain/`). Keep one guarded sender (rule 4.2).
- Extension:
  - one tab or screen per file in `src/tabs/`;
  - shared UI in `src/ui.tsx`;
  - API calls only through `src/api.ts`;
  - error mapping in `src/errors.ts`;
  - user-facing strings through the i18n layer once PRD 4.18 lands. Prepare for it: do not hard-code new strings deep inside components.
- Endpoints follow the PRD paths. Write endpoints need `X-PoolScout-Token`. Keep CORS lockable to the extension origin.
- Mobile (M5): Expo app in `apps/mobile` once the monorepo exists. Share types, the API client, math/formatting and design tokens with the extension and web. Use EAS Build and `expo-updates`. Verify native behaviour (MWA, some push and update paths) on a development or EAS build, not Expo Go. Expo Go is acceptable for UI work only.

### 7.2 Configuration
- All configuration goes through env vars, read in `server/src/env.ts` or `config.ts`, with safe defaults. Document every new variable in `server/.env.example` with a comment, no real values.
- Never require a new env var for the app to start; missing optional config degrades gracefully. For example: no Helius key means "Polling 60s".

### 7.3 Error handling
- Never crash the backend on an upstream failure (RPC, Meteora, Jupiter, RugCheck, Telegram, WAHA). Use timeouts, retries with backoff where safe, and cached fallbacks.
- Use typed error codes. The backend returns `{ error: { code, message } }`, and the extension maps the codes to friendly English.
- Transaction errors record the stage (`build`, `simulate`, `send`, `confirm`) and a reason code in the trade or log tables.

### 7.4 Logging
- Use structured logs with redaction for keys, tokens and `api-key=`/`?api-key` query params. Never log request bodies of the wallet, import or pair endpoints.
- Log every automation decision (acted or skipped, and why). These rows feed Copy Logs and the activity timeline.

### 7.5 Tests
- Keep all existing tests green: `server/test/*.test.ts`, run with `npm test`; `npm run typecheck` in `server/` and `extension/`.
- Add tests for every PRD acceptance criterion that can be tested offline, especially:
  - the dry run and Demo no-send guard;
  - missing data never passes;
  - Unknown is never Safe;
  - the Meme Protection threshold;
  - fund-loss pause;
  - the fee-coverage gate;
  - rug exit wins over rebalance;
  - Jito tip cap and no double execution;
  - secret redaction;
  - keystore round-trip;
  - migrations on a copy of a v0.3.1 database;
  - web pairing replay rejection (M4);
  - mobile pairing: no key on device, replay rejection, revoke (M5).
- Tests never use real keys, never hit mainnet send endpoints, and use fixtures or mocks for external APIs.

### 7.6 Data and migrations
- Migrations are **additive and idempotent**: `CREATE TABLE IF NOT EXISTS`, `ALTER TABLE ADD COLUMN` with defaults.
- Never drop or rename v0.3.1 tables or columns: `wallets`, `wallet_scores`, `holdings`, `events`, `candidates`, `copy_wallets`, `copy_settings`, `copy_positions`, `copy_trades`, `notify_settings`, `notify_log`, `stream_txs`, `token_logos`, `ranking_runs`.
- Keep a `schema_version` and back up `poolscout.db` (a file copy) before migrating.
- New tables follow the PRD data model of each feature.

### 7.7 Windows compatibility
- The primary target is Windows 10 and 11 with Node 22. Also keep macOS and Linux working, because the VPS runs Ubuntu.
- Use `path.join` and `os` APIs, with no hard-coded `/` paths. Use CRLF-safe scripts and keep `start.bat` working; no native build tools required (`better-sqlite3` prebuilt binaries).
- Keep file permission hardening best effort (`icacls` on Windows, `0600` elsewhere).
- No bash-only steps in the owner's install flow.

### 7.8 Versioning and release
- Use SemVer:
  - bump `extension/package.json`, `extension/public/manifest.json` and `server/package.json` together;
  - pre-releases are `0.4.0-m1`, `0.4.0-m2` and so on, and the final release is `0.4.0`.
- Maintain `CHANGELOG.md` at the repo root. Each entry lists Added, Changed, Fixed and Security, with PRD section references.
- Release artifacts:
  - `poolscout-extension.zip` (built `dist/`);
  - `poolscout-backend.zip`, with no `node_modules`, `data/` or `.env`.
- Update `README.md` for any change to setup, settings or behavior.

---

## 8. Workflow

### 8.1 Per-feature checklist
For each PRD feature, in milestone order:

1. Re-read the PRD section, the related 4a, 4b and 6 rules, and this file's sections 3 and 4.
2. List the open decisions the feature depends on (8.4). If any of them blocks the work, skip the feature and report it.
3. Check the mockups (5.4) and the 4b coverage status.
4. Data: add migrations (7.6).
5. Backend: build services and routes with dry-run and Demo paths, redaction and reason codes.
6. Extension: build the UI per section 5, with friendly errors, labels (Estimate, Simulation, DEMO, Dry run) and empty or unavailable states.
7. Tests: one or more per acceptance criterion; run typecheck and the full test suite.
8. Run it locally in dry run and Demo mode. Capture side-panel screenshots at 400×800.
9. Update README, `.env.example` and CHANGELOG.
10. Report (8.3).

### 8.2 Definition of Done (per feature)
- [ ] Every acceptance criterion in the feature's PRD section is met, each one mapped to a test or a manual check in the report.
- [ ] No prohibition in section 3 is violated, and the section 4 rules apply where relevant.
- [ ] Safe defaults are unchanged (3.5), and dry run and Demo send nothing (4.2).
- [ ] Typecheck is clean and all tests pass, old and new.
- [ ] Migrations are additive and tested on a copy of a v0.3.1 database.
- [ ] The UI follows section 5, with screenshots attached.
- [ ] Secrets are redacted, and no new outbound host is left unreported.
- [ ] README, `.env.example` and CHANGELOG are updated.
- [ ] It works on Windows (paths, `start.bat`).

**A milestone is done** when all its features are done and the milestone's exit criteria in PRD 7 are met. Live checks in those criteria are run only with the owner's approval (3.6).

### 8.3 What to report back (per feature or milestone)
- PRD sections covered, and their status (Done, Partial or Blocked).
- Files changed (a summary), new tables and columns, new endpoints, new env vars.
- An acceptance-criteria table: criterion, then test name or manual check, then result.
- Screenshots of new or changed screens.
- Deviations from the PRD or mockups, and why.
- Open questions and blocked items.
- New outbound hosts and new dependencies (name, version, why).
- Exact steps for the owner to update their install, on Windows.

### 8.4 Stop and ask the owner (open decisions, PRD 8)
Do not decide these yourself. Build behind a setting with the PRD's proposed default only where this list says so; otherwise leave the item blocked.

| # | Decision | What to do until it is decided |
|---|---|---|
| 1 | Fee model and referral rates and terms | Build nothing fee-related (3.9) |
| 2 | Domain for the web app and referral links | Use a config value; no hard-coded domain |
| 3 | Hosting for the web app and referral service | Do not deploy; build and test locally only |
| 4 | Demo starting balance | Setting, default 10 SOL (proposal) |
| 5 | Fee-checked threshold | Setting, default 10% (proposal) |
| 6 | Pricing after the free launch | Build nothing (3.9) |
| 7 | Open-source decision and license | Do not publish code or add a license file |
| 8 | Jito tip cap and daily tip budget | Setting, default 0.0001 SOL per bundle (proposal); daily budget required before enabling Jito |
| 9 | VPS provider and setup to document first | Support Ubuntu with Docker and a Node service; ask before writing provider-specific guides |
| 10 | Indonesian Telegram group moderation | Not an engineering task; link only once the owner provides it |
| 11 | Daily recap default time | Setting, default 21:00 UTC+7 (proposal) |
| 12 | Web session expiry | Setting, 12 h idle and 7 days absolute (proposal) |
| 13 | Apple Developer and Google Play accounts, and who submits for review | Do not submit to a store; build and test with EAS locally until the owner decides |
| 14 | Push provider and privacy of device tokens | Do not hard-wire a paid provider; abstract the sender; keep payloads minimal |
| 15 | Solana Mobile Wallet Adapter scope and timing | Do not implement MWA in M5 unless the owner approves it. Never offer it in Expo Go |
| 16 | iOS signing (certificates, provisioning, account type) | Ask before enrolling or buying an Apple Developer account |

**Also stop and ask when:**
- a task needs a live mainnet transaction;
- a task needs a new chain, DEX or third-party service;
- a requirement would weaken custody, defaults or a prohibition;
- the PRD and a mockup disagree;
- a needed API or data source is unavailable or paid;
- a migration could lose data;
- you would need to see or handle a secret.

When blocked, continue with the next unblocked item and list the blocker in your report.

---

## 9. Quick reference: never forget

- Key never leaves the user's machine (PC or the user's own VPS). It never lives on a phone. No vault, no operator key, no hosted signer.
- Copy OFF, dry run ON by default. Simulate before signing. No live transactions without the owner's approval.
- Missing data never passes. Unknown is never Safe. Estimates and simulations are labelled.
- Meteora DLMM and DAMM v2 only. Max 69 bins per position. Bin-array rent is non-refundable; show it.
- English only (except the `id` locale file). Share cards are 1600×900 and 1080×1080 only.
- No fees or rewards until the owner decides.
- Cite PRD sections. Ask instead of guessing.