diff --git a/README.md b/README.md
new file mode 100644
index 0000000..87f6740
--- /dev/null
+++ b/README.md
@@ -0,0 +1,68 @@
+<div align="center">
+
+# StepFi-Docs
+
+**The protocol documentation for StepFi — reputation-based, collateral-light credit on Stellar.**
+
+Guides, contract references, API references, and contributor docs for the whole StepFi protocol, published with [docs.page](https://docs.page).
+
+[![CI](https://github.com/StepFi-app/StepFi-Docs/actions/workflows/ci.yml/badge.svg)](https://github.com/StepFi-app/StepFi-Docs/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/badge/docs-live-22C55E.svg)](https://docs.page/StepFi-app/StepFi-Docs)
+[![Stellar](https://img.shields.io/badge/Stellar-Soroban-7D00FF?logo=stellar&logoColor=white)](https://stellar.org)
+
+**📖 Read the docs:** https://docs.page/StepFi-app/StepFi-Docs
+
+</div>
+
+---
+
+## 📖 What is this?
+
+StepFi lets learners and interns borrow small amounts against an **on-chain reputation score** instead of collateral, repay in installments, and build credit — while sponsors fund a shared liquidity pool, vendors get paid directly, and mentors vouch to boost reputation. This repository is the **documentation** for that protocol: how it works, every smart contract, every API surface, the mobile client, and how to contribute.
+
+## 🗺️ Where it fits
+
+<div align="center">
+
+<img src="./architecture.svg" alt="StepFi system architecture — StepFi-Docs highlighted" width="900" />
+
+</div>
+
+StepFi-Docs is the reference layer that documents every other repository in the protocol — the contracts, the API, and the clients.
+
+## 🧭 What's inside
+
+Content lives in [`docs/`](docs) as MDX, with the site structure and navigation defined in [`docs.json`](docs.json):
+
+| Section | Covers |
+|---------|--------|
+| **Overview · Architecture · Quick Start** | Protocol intro, system architecture, getting started |
+| **Protocol** | How it works, learner flow, sponsor flow, mentor vouching, the reputation system |
+| **Smart Contracts** | Creditline, Reputation, Liquidity Pool, Vendor Registry, Parameters |
+| **API** | Authentication, loans, liquidity, sponsors, vendors, reputation, vouching, the playground |
+| **Mobile** | App overview, screens, wallet connection |
+| **Contributing** | Contribution overview and per-area guides (backend, contracts, mobile, code standards) |
+
+## ✍️ Editing the docs
+
+The site is rendered directly from this repository by **docs.page** — there is no build step or generated output to commit.
+
+1. Edit or add an `.mdx` file under [`docs/`](docs).
+2. If you add, remove, or move a page, update its entry in [`docs.json`](docs.json) so it appears in the sidebar.
+3. Open a PR. docs.page serves a preview for your branch/PR, and the changes go live at the URL above once merged to `main`.
+
+> Note: this project uses docs.page's `docs.json` format — it is **not** a Mintlify site, so don't reach for the Mintlify CLI.
+
+## 🔄 CI
+
+Every push and PR runs [`.github/workflows/ci.yml`](.github/workflows/ci.yml), which executes [`.github/scripts/validate-docs.mjs`](.github/scripts/validate-docs.mjs) to validate `docs.json` and check that every sidebar link resolves to a real page. Keep it green — broken links fail the build.
+
+## 🌐 The StepFi protocol
+
+| Repo | Role |
+|------|------|
+| **StepFi-Docs** (this repo) | Protocol documentation |
+| [StepFi-Contracts](https://github.com/StepFi-app/StepFi-Contracts) | Soroban smart contracts (credit, reputation, liquidity) |
+| [StepFi-API](https://github.com/StepFi-app/StepFi-API) | Backend — auth/JWT, orchestration, jobs |
+| [StepFi-App](https://github.com/StepFi-app/StepFi-App) | Learner mobile client (Expo / React Native) |
+| [StepFi-Web](https://github.com/StepFi-app/StepFi-Web) | Sponsor / vendor / mentor web app |
diff --git a/architecture.svg b/architecture.svg
new file mode 100644
index 0000000..4e06057
--- /dev/null
+++ b/architecture.svg
@@ -0,0 +1,115 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1000" height="660" viewBox="0 0 1000 660" font-family="'Segoe UI',Helvetica,Arial,sans-serif">
+  <defs>
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0 0L10 5L0 10z" fill="#64748B"/>
+    </marker>
+    <filter id="soft" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="2" stdDeviation="3" flood-color="#0F172A" flood-opacity="0.08"/>
+    </filter>
+  </defs>
+
+  <!-- page -->
+  <rect x="0" y="0" width="1000" height="660" rx="18" fill="#F8FAFC"/>
+  <text x="40" y="46" font-size="27" font-weight="700" fill="#0F172A">StepFi — System Architecture</text>
+  <text x="40" y="70" font-size="14" fill="#475569">Reputation-based micro-credit for students & small vendors, settled on Stellar</text>
+
+  <!-- docs badge -->
+  <g filter="url(#soft)">
+    <rect id="box-docs" x="784" y="24" width="176" height="52" rx="10" fill="#FFFFFF" stroke="#F59E0B" stroke-width="3.5"/>
+  </g>
+  <text x="872" y="47" font-size="14" font-weight="700" fill="#0F172A" text-anchor="middle">📚 StepFi-Docs</text>
+  <text x="872" y="65" font-size="11" fill="#64748B" text-anchor="middle">Protocol documentation</text>
+
+  <!-- USERS -->
+  <text x="40" y="118" font-size="12" font-weight="700" fill="#94A3B8" letter-spacing="1">USERS</text>
+  <g filter="url(#soft)">
+    <rect x="60" y="98" width="158" height="44" rx="22" fill="#EEF2F7" stroke="#CBD5E1" stroke-width="1.5"/>
+    <rect x="238" y="98" width="158" height="44" rx="22" fill="#EEF2F7" stroke="#CBD5E1" stroke-width="1.5"/>
+    <rect x="416" y="98" width="158" height="44" rx="22" fill="#EEF2F7" stroke="#CBD5E1" stroke-width="1.5"/>
+  </g>
+  <text x="139" y="126" font-size="14" fill="#0F172A" text-anchor="middle">🎓 Learners</text>
+  <text x="317" y="126" font-size="14" fill="#0F172A" text-anchor="middle">💚 Sponsors</text>
+  <text x="495" y="126" font-size="14" fill="#0F172A" text-anchor="middle">🏪 Vendors</text>
+
+  <!-- CLIENTS -->
+  <text x="40" y="188" font-size="12" font-weight="700" fill="#94A3B8" letter-spacing="1">CLIENTS</text>
+  <g filter="url(#soft)">
+    <rect id="box-app" x="60" y="198" width="236" height="92" rx="14" fill="#E7EEFD" stroke="#2F6FED" stroke-width="1.8"/>
+    <rect id="box-web" x="318" y="198" width="236" height="92" rx="14" fill="#E7EEFD" stroke="#2F6FED" stroke-width="1.8"/>
+  </g>
+  <text x="178" y="232" font-size="16" font-weight="700" fill="#1E3A8A" text-anchor="middle">📱 StepFi-App</text>
+  <text x="178" y="255" font-size="12" fill="#334155" text-anchor="middle">Expo · React Native</text>
+  <text x="178" y="273" font-size="12" fill="#334155" text-anchor="middle">learner & sponsor mobile client</text>
+  <text x="436" y="232" font-size="16" font-weight="700" fill="#1E3A8A" text-anchor="middle">🌐 StepFi-Web</text>
+  <text x="436" y="255" font-size="12" fill="#334155" text-anchor="middle">marketing site &</text>
+  <text x="436" y="273" font-size="12" fill="#334155" text-anchor="middle">web dashboard</text>
+
+  <!-- WALLETS -->
+  <text x="620" y="188" font-size="12" font-weight="700" fill="#94A3B8" letter-spacing="1">WALLETS</text>
+  <g filter="url(#soft)">
+    <rect id="box-wallets" x="620" y="198" width="320" height="92" rx="14" fill="#F3E8FF" stroke="#9333EA" stroke-width="1.8"/>
+  </g>
+  <text x="780" y="230" font-size="16" font-weight="700" fill="#6B21A8" text-anchor="middle">🔐 Wallets</text>
+  <text x="780" y="253" font-size="12" fill="#334155" text-anchor="middle">Freighter (web) · Lobstr (mobile)</text>
+  <text x="780" y="271" font-size="12" fill="#334155" text-anchor="middle">via WalletConnect · sign XDR / message</text>
+
+  <!-- API -->
+  <text x="40" y="330" font-size="12" font-weight="700" fill="#94A3B8" letter-spacing="1">BACKEND</text>
+  <g filter="url(#soft)">
+    <rect id="box-api" x="60" y="340" width="494" height="104" rx="14" fill="#E4F6EE" stroke="#1FA971" stroke-width="1.8"/>
+  </g>
+  <text x="80" y="372" font-size="16" font-weight="700" fill="#065F46">⚙️ StepFi-API</text>
+  <text x="215" y="372" font-size="12" fill="#334155">NestJS backend · REST</text>
+  <g font-size="11.5" fill="#0F172A">
+    <rect x="76" y="392" width="150" height="30" rx="15" fill="#FFFFFF" stroke="#1FA971" stroke-width="1.2"/>
+    <text x="151" y="411" text-anchor="middle">🔑 Auth · JWT</text>
+    <rect x="238" y="392" width="160" height="30" rx="15" fill="#FFFFFF" stroke="#1FA971" stroke-width="1.2"/>
+    <text x="318" y="411" text-anchor="middle">🔗 Orchestration</text>
+    <rect x="410" y="392" width="128" height="30" rx="15" fill="#FFFFFF" stroke="#1FA971" stroke-width="1.2"/>
+    <text x="474" y="411" text-anchor="middle">⏱ Jobs</text>
+  </g>
+
+  <!-- top arrows -->
+  <g stroke="#64748B" stroke-width="1.6" fill="none">
+    <line x1="178" y1="144" x2="178" y2="196" marker-end="url(#arrow)"/>
+    <line x1="360" y1="144" x2="430" y2="196" marker-end="url(#arrow)"/>
+    <line x1="558" y1="244" x2="616" y2="244" marker-end="url(#arrow)"/>
+    <line x1="178" y1="292" x2="178" y2="338" marker-end="url(#arrow)"/>
+  </g>
+  <text x="586" y="238" font-size="10.5" fill="#64748B" text-anchor="middle">sign</text>
+  <text x="205" y="318" font-size="10.5" fill="#64748B">REST · JWT</text>
+
+  <!-- STELLAR / CONTRACTS -->
+  <g filter="url(#soft)">
+    <rect id="box-contracts" x="60" y="486" width="880" height="150" rx="14" fill="#EFF6FF" stroke="#2F6FED" stroke-width="1.8" stroke-dasharray="6 5"/>
+  </g>
+  <text x="80" y="514" font-size="14" font-weight="700" fill="#1E3A8A">✦ Stellar Network — Soroban platform (testnet) · StepFi-Contracts</text>
+  <g font-size="13" font-weight="700" fill="#1E3A8A">
+    <rect x="80" y="536" width="150" height="76" rx="12" fill="#FFFFFF" stroke="#2F6FED" stroke-width="1.4"/>
+    <rect x="252" y="536" width="150" height="76" rx="12" fill="#FFFFFF" stroke="#2F6FED" stroke-width="1.4"/>
+    <rect x="424" y="536" width="150" height="76" rx="12" fill="#FFFFFF" stroke="#2F6FED" stroke-width="1.4"/>
+    <rect x="596" y="536" width="150" height="76" rx="12" fill="#FFFFFF" stroke="#2F6FED" stroke-width="1.4"/>
+    <rect x="768" y="536" width="150" height="76" rx="12" fill="#FFFFFF" stroke="#2F6FED" stroke-width="1.4"/>
+    <text x="155" y="570" text-anchor="middle">Creditline</text>
+    <text x="327" y="570" text-anchor="middle">Reputation</text>
+    <text x="499" y="570" text-anchor="middle">Liquidity Pool</text>
+    <text x="671" y="570" text-anchor="middle">Vendor Registry</text>
+    <text x="843" y="570" text-anchor="middle">Parameters</text>
+  </g>
+  <g font-size="11" font-weight="400" fill="#475569">
+    <text x="155" y="592" text-anchor="middle">loans & repayment</text>
+    <text x="327" y="592" text-anchor="middle">score & tiers</text>
+    <text x="499" y="592" text-anchor="middle">sponsor funds</text>
+    <text x="671" y="592" text-anchor="middle">verified merchants</text>
+    <text x="843" y="592" text-anchor="middle">governance · multisig</text>
+  </g>
+
+  <!-- bottom arrows -->
+  <g stroke="#64748B" stroke-width="1.6" fill="none">
+    <line x1="300" y1="444" x2="300" y2="484" marker-end="url(#arrow)"/>
+    <line x1="780" y1="292" x2="780" y2="484" marker-end="url(#arrow)"/>
+  </g>
+  <text x="316" y="468" font-size="10.5" fill="#64748B">Soroban RPC</text>
+  <text x="792" y="392" font-size="10.5" fill="#64748B">submit signed XDR</text>
+  <g transform="translate(837,13)"><rect x="0" y="0" width="70" height="22" rx="11" fill="#F59E0B"/><text x="35" y="15" font-size="10.5" font-weight="700" fill="#FFFFFF" text-anchor="middle">this repo</text></g>
+</svg>