diff --git a/.env.local.example b/.env.local.example
new file mode 100644
index 0000000..18c0f22
--- /dev/null
+++ b/.env.local.example
@@ -0,0 +1,45 @@
+# ILN Frontend local environment
+#
+# Copy this file to .env.local and fill only the values needed for the feature
+# you are testing. Never commit real secrets.
+
+# Stellar / Soroban testnet defaults
+NEXT_PUBLIC_CONTRACT_ID=CD3TE3IAHM737P236XZL2OYU275ZKD6MN7YH7PYYAXYIGEH55OPEWYJC
+NEXT_PUBLIC_NETWORK_PASSPHRASE=Test SDF Network ; September 2015
+NEXT_PUBLIC_RPC_URL=https://soroban-testnet.stellar.org
+NEXT_PUBLIC_NETWORK_NAME=TESTNET
+NEXT_PUBLIC_STELLAR_NETWORK=testnet
+NEXT_PUBLIC_TESTNET_USDC_TOKEN_ID=CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75
+NEXT_PUBLIC_TESTNET_EURC_TOKEN_ID=GDHU6WRG4IEQXM5NZ4BMPKOXHW76MZM4Y2IEMFDVXBSDP6SJY4ITNPP
+NEXT_PUBLIC_TESTNET_XLM_TOKEN_ID=native-xlm
+NEXT_PUBLIC_GOVERNANCE_ADMIN_ADDRESS=GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF
+
+# Optional feature flags
+NEXT_PUBLIC_INSURANCE_POOL_ENABLED=false
+NEXT_PUBLIC_NFT_ENABLED=false
+NEXT_PUBLIC_NFT_CONTRACT_ID=
+NEXT_PUBLIC_NFT_METADATA_METHOD=token_uri
+NEXT_PUBLIC_NFT_EVENT_HINTS=
+NEXT_PUBLIC_ORACLE_ENABLED=false
+NEXT_PUBLIC_API_MOCKING=
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+NEXT_PUBLIC_APP_VERSION=dev
+NEXT_PUBLIC_INDEXER_API_URL=https://api.iln.example.com
+NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=
+
+# Optional Supabase-backed reminder preferences
+NEXT_PUBLIC_SUPABASE_URL=
+NEXT_PUBLIC_SUPABASE_ANON_KEY=
+SUPABASE_SERVICE_ROLE_KEY=
+
+# Optional server/API integrations
+RESEND_API_KEY=
+CRON_SECRET=
+GITHUB_TOKEN=
+GITHUB_OWNER=
+GITHUB_REPO=
+NOTIFICATION_API=
+INDEXER_URL=
+
+# Optional visual regression testing
+CHROMATIC_PROJECT_TOKEN=
diff --git a/README.md b/README.md
index 63b7b50..07bb5cb 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,21 @@
 This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
 
+## Developer Quickstart
+
+New contributors should start with the [developer quickstart](docs/developer-quickstart.md).
+It covers prerequisites, `.env.local` setup, Stellar testnet wallet notes, local
+development, tests, and common setup issues.
+
+For the shortest path:
+
+```bash
+npm install
+cp .env.local.example .env.local
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) to view the app.
+
 ## Snapshot Tests
 
 The frontend includes Vitest snapshot coverage for the main invoice UI surfaces in `__tests__`.
@@ -18,7 +34,7 @@ npm test -- --update-snapshots
 
 ## Getting Started
 
-First of all, run the development server:
+After following the quickstart, run the development server:
 
 ```bash
 npm run dev
diff --git a/docs/developer-quickstart.md b/docs/developer-quickstart.md
new file mode 100644
index 0000000..fa597f4
--- /dev/null
+++ b/docs/developer-quickstart.md
@@ -0,0 +1,197 @@
+# Developer quickstart
+
+This guide gets a new contributor from a fresh clone to a running ILN
+Frontend development environment. It focuses on the frontend repository and
+uses the npm workflow that is currently committed in `package-lock.json`.
+
+## Prerequisites
+
+- Node.js 20 or newer.
+- npm, included with Node.js.
+- Git, for cloning and branching.
+- Freighter browser extension, for wallet-connected flows.
+- Stellar CLI, for testnet and contract workflow checks.
+- A Stellar testnet account funded with Friendbot.
+
+Optional tools:
+
+- Docker Desktop, if you want to run local supporting services.
+- Playwright browser dependencies, for end-to-end tests.
+- A Chromatic project token, only if you need to run visual regression checks.
+
+## Platform notes
+
+Linux and macOS can follow the commands below directly.
+
+On Windows, use WSL 2 with Ubuntu for the most consistent Node, Playwright, and
+Stellar CLI behavior. Run the commands inside the WSL shell, not from a Windows
+PowerShell path mounted into WSL.
+
+## 1. Clone the repository
+
+```bash
+git clone https://github.com/Invoice-Liquidity-Network/ILN-Frontend.git
+cd ILN-Frontend
+```
+
+Create a working branch:
+
+```bash
+git checkout -b docs/developer-quickstart
+```
+
+## 2. Install dependencies
+
+```bash
+npm install
+```
+
+The repository currently uses `package-lock.json`, so npm is the safest default
+package manager. If maintainers later move the project to pnpm, follow the
+updated lockfile and README instead.
+
+## 3. Create local environment variables
+
+Copy the example file:
+
+```bash
+cp .env.local.example .env.local
+```
+
+The defaults target Stellar testnet and are enough for many UI and mock-backed
+flows. Fill optional values only when you need the related feature:
+
+- `NEXT_PUBLIC_SUPABASE_URL` and `NEXT_PUBLIC_SUPABASE_ANON_KEY` for Supabase
+  backed reminder preferences.
+- `SUPABASE_SERVICE_ROLE_KEY` for server-side Supabase admin access.
+- `RESEND_API_KEY` and `CRON_SECRET` for reminder email routes.
+- `NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID` for WalletConnect.
+- `CHROMATIC_PROJECT_TOKEN` for Chromatic visual regression testing.
+
+Do not commit real secrets in `.env.local`.
+
+## 4. Start the development server
+
+```bash
+npm run dev
+```
+
+Open http://localhost:3000.
+
+For wallet flows, unlock Freighter and connect to Stellar testnet. If your
+testnet account has no XLM, fund it with Friendbot before testing transactions.
+
+## 5. Verify the app locally
+
+Run the production build:
+
+```bash
+npm run build
+```
+
+Run unit and component tests:
+
+```bash
+npm test
+```
+
+Run lint checks:
+
+```bash
+npm run lint
+```
+
+Run end-to-end tests:
+
+```bash
+npm run test:e2e
+```
+
+If Playwright reports missing browsers, install them once:
+
+```bash
+npx playwright install
+```
+
+## 6. Storybook and visual checks
+
+Start Storybook:
+
+```bash
+npm run storybook
+```
+
+Build Storybook:
+
+```bash
+npm run build-storybook
+```
+
+Run Chromatic if you have a project token:
+
+```bash
+CHROMATIC_PROJECT_TOKEN=your_token_here npm run chromatic
+```
+
+## 7. Common issues
+
+### Freighter is not detected
+
+Install the Freighter extension, unlock it, and refresh the page. Make sure the
+wallet is on testnet when testing testnet contract interactions.
+
+### RPC or contract reads fail
+
+Confirm these variables in `.env.local`:
+
+```bash
+NEXT_PUBLIC_RPC_URL=https://soroban-testnet.stellar.org
+NEXT_PUBLIC_STELLAR_NETWORK=testnet
+NEXT_PUBLIC_NETWORK_NAME=TESTNET
+```
+
+Also check that `NEXT_PUBLIC_CONTRACT_ID` points to the contract you expect to
+test.
+
+### Supabase errors appear
+
+Most Supabase-backed features require:
+
+```bash
+NEXT_PUBLIC_SUPABASE_URL=
+NEXT_PUBLIC_SUPABASE_ANON_KEY=
+```
+
+Server-only reminder routes can also require `SUPABASE_SERVICE_ROLE_KEY`.
+
+### Reminder email routes fail
+
+Set `RESEND_API_KEY` and `CRON_SECRET` before testing reminder jobs. Use local
+test values only; never commit production credentials.
+
+### WalletConnect is disabled
+
+Set `NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID`. Without it, the app intentionally
+keeps WalletConnect unavailable and shows guidance in the wallet modal.
+
+### Playwright cannot start on Linux or WSL
+
+Install Playwright browser dependencies:
+
+```bash
+npx playwright install --with-deps
+```
+
+If that needs system packages, run it in an environment where you can install
+Linux dependencies.
+
+## Pull request checklist
+
+Before opening a PR:
+
+- Rebase or update from `main`.
+- Run `npm run lint`.
+- Run `npm test`.
+- Run `npm run build`.
+- Add screenshots or notes for UI changes.
+- Link the issue with `Closes #221` when this quickstart work is complete.