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)

Milestones (PRD section 7)

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)

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×.

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.

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.