Pro-repo pass: README overhaul, cleanliness audit, submodules, CI

.env.example

@@ -22,4 +22,5 @@ DEMO_AAVE_POOL=
 
 # ── Target chain ──
 CHAIN=robinhood            # robinhood (chain 46630) | arbitrumSepolia
-GUARDIAN_IMPL=             # GuardianModule on the target chain (empty => Arb Sepolia constant)
+GUARDIAN_IMPL=             # required: GuardianModule impl on the target chain (printed by DeployGuardian)
+RULES_ENGINE=              # RulesEngineV1 (printed by DeployRules); also set VITE_RULES_ENGINE in site/.env

.github/workflows/ci.yml

@@ -0,0 +1,62 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  contracts:
+    name: contracts · forge test
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: contracts
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - uses: foundry-rs/foundry-toolchain@v1
+      - run: forge --version
+      - run: forge build --sizes
+      - run: forge test
+        # The real-Aave fork test self-skips unless ARBITRUM_ONE_RPC is set.
+
+  watcher:
+    name: watcher · vitest
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: watcher
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+          cache-dependency-path: watcher/pnpm-lock.yaml
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm test
+
+  site:
+    name: site · build + lint
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: site
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+          cache-dependency-path: site/pnpm-lock.yaml
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build
+      - run: pnpm lint

.gitmodules

@@ -0,0 +1,6 @@
+[submodule "contracts/lib/forge-std"]
+	path = contracts/lib/forge-std
+	url = https://github.com/foundry-rs/forge-std
+[submodule "contracts/lib/openzeppelin-contracts"]
+	path = contracts/lib/openzeppelin-contracts
+	url = https://github.com/OpenZeppelin/openzeppelin-contracts

CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing
+
+Thanks for taking a look. coincoin is an experimental, testnet-only research prototype — contributions, bug reports, and ideas are welcome.
+
+## Layout
+
+| Path | Stack | What |
+|---|---|---|
+| `contracts/` | Solidity + Foundry | GuardianModule (EIP-7702), RulesEngineV1, SafeVault, mocks |
+| `watcher/` | TypeScript + viem | detection → rescue daemon (CLI) |
+| `site/` | Vite + React + Tailwind | landing page + `/app` dashboard |
+| `video/` | Remotion | pitch + demo videos |
+
+## Setup
+
+Prerequisites: [Foundry](https://getfoundry.sh), Node ≥ 22, [pnpm](https://pnpm.io).
+
+```bash
+git clone --recursive https://github.com/gamween/coincoin.git   # Foundry deps are git submodules
+cd coincoin
+# already cloned without --recursive? run:
+git submodule update --init --recursive
+```
+
+## Run the checks (do this before opening a PR)
+
+```bash
+cd contracts && forge build && forge test          # set ARBITRUM_ONE_RPC to also run the Aave fork test
+cd ../watcher && pnpm install && pnpm test
+cd ../site    && pnpm install && pnpm build && pnpm lint
+```
+
+CI (`.github/workflows/ci.yml`) runs the same matrix on every PR — it must be green to merge.
+
+## Conventions
+
+- **TypeScript** is strict; **Solidity** is `0.8.24`, written test-first with Foundry.
+- **English only** in code, comments, and docs.
+- **Conventional Commits** for messages (`feat:`, `fix:`, `chore:`, `docs:`, …).
+- Keep changes focused; add or update tests for behavior changes.
+- Never commit secrets — `.env` is gitignored; use disposable testnet keys only.
+
+## Security
+
+Found a vulnerability? Please follow the private disclosure process in [SECURITY.md](SECURITY.md).

SECURITY.md

@@ -0,0 +1,18 @@
+# Security Policy
+
+coincoin is an **experimental, unaudited research prototype on testnet**. Do not use it with funds at risk.
+
+## Reporting a vulnerability
+
+Please report security issues **privately** — do not open a public issue or PR.
+
+Contact: [X (@dvb_fianso)](https://x.com/dvb_fianso) or [Telegram (@dvb_fianso)](https://t.me/dvb_fianso).
+
+We'll acknowledge the report, work on a fix, and coordinate disclosure before anything is made public.
+
+## Scope
+
+- `contracts/` — `GuardianModule` (EIP-7702 delegate), `RulesEngineV1` (firewall), `SafeVault`
+- `watcher/` — the detection daemon and bounded keeper
+
+Known limitations and the trust model are documented in the [README](README.md#security--trust-model).

contracts/foundry.lock

@@ -0,0 +1,14 @@
+{
+  "lib/forge-std": {
+    "tag": {
+      "name": "v1.16.1",
+      "rev": "620536fa5277db4e3fd46772d5cbc1ea0696fb43"
+    }
+  },
+  "lib/openzeppelin-contracts": {
+    "tag": {
+      "name": "v5.6.1",
+      "rev": "5fd1781b1454fd1ef8e722282f86f9293cacf256"
+    }
+  }
+}