docs: overhaul README with system architecture diagram and roadmap

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 StepFi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -58,6 +58,12 @@ From the web app, a mentor can:
 
 ## How this fits into the StepFi ecosystem
 
+<div align="center">
+
+<img src="./public/architecture.svg" alt="StepFi system architecture — StepFi-Web highlighted" width="900" />
+
+</div>
+
 StepFi is split across multiple repositories that together form one protocol:
 
 | Repo | Purpose | Stack |
@@ -139,6 +145,37 @@ No local backend setup is required to start contributing to the frontend.
 
 ---
 
+## Scripts
+
+| Command | What it does |
+|---------|--------------|
+| `npm run dev` | Start the Vite dev server |
+| `npm run build` | Type-check (`tsc -b`) and produce a production build |
+| `npm run preview` | Preview the production build locally |
+| `npm run lint` | Lint with ESLint |
+| `npm test` | Run the Vitest suite once |
+| `npm run test:coverage` | Run tests with a coverage report |
+| `npm run test:a11y` | Build, then run the accessibility checks (`test-a11y.mjs`) |
+
+## 🔄 CI/CD
+
+Every push and PR runs [`.github/workflows/ci.yml`](.github/workflows/ci.yml) — a **required check on `main`** — covering lint, type-check, unit tests, and the production build. The app deploys to Netlify ([`netlify.toml`](netlify.toml)); the landing page is served from Vercel ([`vercel.json`](vercel.json)).
+
+## 🛣️ Roadmap
+
+| Milestone | Status |
+|-----------|--------|
+| Sponsor pool dashboard — deposits, shares, live pool stats | ✅ |
+| Vendor registration, catalog, and payment history | ✅ |
+| Mentor vouching — review, submit, track, revoke | ✅ |
+| Wallet connect (Freighter) + TanStack Query data layer | ✅ |
+| Enforced CI gate (lint · type-check · test · build) | ✅ |
+| Accessibility test pass (`test:a11y`) | ✅ |
+| Live wallet-signature JWT auth (shared with StepFi-App) | 🚧 |
+| Editable sponsor/vendor profiles · notification preferences | 🗺️ |
+
+---
+
 ## Contributing
 
 StepFi-Web is open source and welcomes contributors of all experience levels.
@@ -179,4 +216,4 @@ https://contribute.grantfox.xyz/org/StepFi-app
 
 ## License
 
-MIT
+Released under the [MIT License](./LICENSE).