docs: troubleshooting guide, hidden-streams ADR; chore: Dependabot config

.github/dependabot.yml

@@ -0,0 +1,37 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    groups:
+      npm-minor-patch:
+        update-types:
+          - "minor"
+          - "patch"
+    labels:
+      - "dependencies"
+      - "npm"
+
+  - package-ecosystem: "cargo"
+    directory: "/contracts"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    groups:
+      cargo-minor-patch:
+        update-types:
+          - "minor"
+          - "patch"
+    labels:
+      - "dependencies"
+      - "rust"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+      - "ci"

docs/TROUBLESHOOTING.md

@@ -0,0 +1,68 @@
+# Troubleshooting
+
+Common issues when setting up or developing FlowStar locally. For
+wallet/RPC/contract-deployment issues, see
+[CONTRIBUTING.md's Troubleshooting section](../CONTRIBUTING.md#troubleshooting)
+— this page covers the setup issues not already covered there.
+
+## `npm install` fails with a peer-dependency conflict
+
+**Symptom**: `npm install` fails with `ERESOLVE unable to resolve dependency
+tree` or similar.
+
+**Fix**: install with `--legacy-peer-deps`, as documented in the README/
+CONTRIBUTING setup steps:
+
+```bash
+npm install --legacy-peer-deps
+```
+
+This also runs Husky's `prepare` script, installing pre-commit hooks. If you
+previously ran a plain `npm install` that failed partway, remove
+`node_modules` and `package-lock.json` before retrying with the flag above to
+avoid a partially-resolved tree.
+
+## Mock mode vs. live contract confusion
+
+FlowStar runs in one of two modes, chosen automatically by
+`isMockMode = !config.streamContractId` in `lib/contract.ts`:
+
+- **Mock mode** (default, no env var set): all stream data comes from
+  `lib/mock-data.ts`. No wallet or testnet funds required. Good for UI work.
+- **Live contract mode**: set `NEXT_PUBLIC_STREAM_CONTRACT_ID_TESTNET` (or
+  `_MAINNET`) in `.env.local` to a real deployed contract ID, and restart the
+  dev server. The app then reads/writes real on-chain data via Freighter.
+
+If you're unexpectedly seeing mock data when you expect live data (or vice
+versa), see CONTRIBUTING.md's "App running in mock mode unexpectedly" entry —
+the most common cause is the dev server not having been restarted after
+setting the env var.
+
+There is no partial state between these two modes: `isMockMode` is a single
+boolean, so a page either shows entirely mock data or entirely live data,
+never a mix.
+
+## Freighter wallet not detected
+
+See [CONTRIBUTING.md's "Freighter not detected / connecting"](../CONTRIBUTING.md#troubleshooting)
+entry. In short: confirm Freighter is set to **Testnet**, is enabled for
+`localhost`, and reload the page after unlocking it.
+
+## Testnet faucet rate limits
+
+Funding a new testnet account via
+[Stellar Laboratory's Friendbot](https://laboratory.stellar.org/#account-creator?network=test)
+is rate-limited per IP/account. If funding fails or you're asked to wait:
+
+- Reuse an already-funded testnet keypair instead of generating a new one for
+  every test run.
+- Wait a few minutes between funding attempts from the same network/IP.
+- If you're running automated tests that create many accounts, fund a small
+  pool of keypairs up front and reuse them, rather than funding fresh per test.
+
+## Still stuck?
+
+Check [CONTRIBUTING.md's Troubleshooting section](../CONTRIBUTING.md#troubleshooting)
+for RPC failures, contract deployment errors, and Husky/pre-commit hook
+issues, or open an issue with the exact error message and your `.env.local`
+configuration (with any secrets redacted).

docs/adr/ADR-009-hidden-streams-frontend-only.md

@@ -0,0 +1,69 @@
+# ADR-009: Hidden Streams / Blocked Senders — Frontend-Only (localStorage)
+
+## Status
+
+Accepted
+
+## Context
+
+Anyone can currently create a stream to any address without the recipient's
+consent — there is no contract-level opt-in or allow-list for who may stream
+funds to a given recipient (see issue #151). A practical consequence is
+dashboard clutter and unwanted-sender annoyance: a recipient may want to
+declutter their view of streams they don't care about, or stop seeing streams
+from a specific sender, without waiting for a full on-chain consent/opt-in
+mechanism to be designed and shipped.
+
+Two options were considered (tracked as issue #151):
+
+- **Option A (chosen)**: a purely client-side hide/block mechanism, stored in
+  the browser's `localStorage`, with zero on-chain effect.
+- **Option B (rejected for now)**: an on-chain opt-in/allow-list mechanism —
+  e.g. a contract-level registry of blocked senders per recipient, enforced
+  at stream-creation time so a blocked sender's `create_stream` call would
+  actually fail.
+
+## Decision
+
+Implement Option A: `lib/hidden-streams.ts` maintains two sets — hidden
+stream IDs and blocked sender addresses — persisted in `localStorage` under
+`flowstar:hidden-streams` and `flowstar:blocked-senders`. This is purely a
+display-layer filter:
+
+- The stream (or sender's future streams) is **not** hidden or blocked
+  on-chain — it still exists, and is still fully cancellable/withdrawable by
+  anyone with a direct link or who queries the contract directly.
+- The hide/block state lives **on this device only** — it does not sync
+  across the recipient's other browsers/devices, and clearing browser data
+  resets it.
+- A same-tab pub/sub (`subscribeHiddenStreams`) keeps the UI reactive to
+  changes made through this module without a page reload.
+
+Option B (on-chain enforcement) was rejected *for now*, not permanently — it
+requires contract changes, a migration path for existing streams, and a
+design for how a sender could contest an incorrect/malicious block. That is
+substantially more design and implementation work than the dashboard-clutter
+problem currently needs solving.
+
+## Consequences
+
+**Easier:**
+- Shippable immediately with no contract changes, audit, or migration.
+- Recipients get a working declutter/block tool today.
+
+**Harder / accepted limitations:**
+- A "blocked" sender is not actually prevented from creating new streams to
+  that recipient — blocking only hides those streams from *this recipient's
+  dashboard on this device*. A sender determined to be seen (or a recipient
+  checking from a different device) is unaffected.
+- No cross-device sync: a recipient who hides a stream on their laptop will
+  still see it on their phone until they hide it there too.
+- `localStorage` is per-origin and can be cleared by the user or browser
+  (private browsing, storage limits) at any time, silently resetting hidden/
+  blocked state with no warning.
+- If/when Option B (on-chain opt-in) is built, this module's state does not
+  automatically migrate — it would need an explicit decision on whether
+  existing local hide/block lists inform the initial on-chain allow-list.
+
+Revisit this ADR if user reports of unwanted streams grow enough to justify
+the on-chain design work for Option B.

docs/adr/README.md

@@ -16,6 +16,7 @@ This directory captures the significant technical decisions made in FlowStar —
 | [ADR-007](./ADR-007-integer-division-dust.md) | Integer Division Dust Handling | Accepted |
 | [ADR-008](./ADR-008-delegate-withdrawal-authorization.md) | Delegate Withdrawal Authorization | Accepted (open questions) |
 | [ADR-008](./ADR-008-notification-polling-and-dedup.md) | Notification Polling, Dedup, and Per-Wallet Scoping | Accepted |
+| [ADR-009](./ADR-009-hidden-streams-frontend-only.md) | Hidden Streams / Blocked Senders — Frontend-Only (localStorage) | Accepted |
 | [ADR-009](./ADR-009-webhook-retry-backoff.md) | Webhook Delivery Retry, Backoff, and History Retention | Accepted |
 | [ADR-009](./ADR-009-auto-withdraw-strategy-pattern.md) | Auto-Withdraw Strategy Pattern | Accepted (open correctness issues) |
 | [ADR-010](./ADR-010-csv-column-alias-resolution.md) | CSV Batch-Import Column-Alias Resolution | Accepted |