feat(miniapp): add telegram-authenticated shell

docs/specs/HOUSEBOT-040-miniapp-shell.md

@@ -0,0 +1,60 @@
+# HOUSEBOT-040: Mini App Shell with Telegram Auth Gate
+
+## Summary
+
+Build the first usable SolidJS mini app shell with a real Telegram initData verification flow and a household membership gate.
+
+## Goals
+
+- Verify Telegram mini app initData on the backend.
+- Block non-members from entering the mini app shell.
+- Provide a bilingual RU/EN shell with navigation ready for later dashboard features.
+- Keep local development usable with a demo fallback.
+
+## Non-goals
+
+- Full balances and ledger data rendering.
+- House wiki content population.
+- Production analytics or full design-system work.
+
+## Scope
+
+- In: backend auth endpoint, membership lookup, CORS handling, shell layout, locale toggle, runtime bot API URL injection.
+- Out: real balances API, ledger API, notification center.
+
+## Interfaces and Contracts
+
+- Backend endpoint: `POST /api/miniapp/session`
+- Request body:
+  - `initData: string`
+- Success response:
+  - `authorized: true`
+  - `member`
+  - `telegramUser`
+- Membership failure:
+  - `authorized: false`
+  - `reason: "not_member"`
+
+## Security and Privacy
+
+- Telegram initData is verified with the bot token before membership lookup.
+- Mini app access depends on an actual household membership match.
+- CORS can be limited via `MINI_APP_ALLOWED_ORIGINS`; if unset, the endpoint falls back to permissive origin reflection for deployment simplicity.
+
+## UX Notes
+
+- RU/EN switch is always visible.
+- Demo shell appears automatically in local development when Telegram data is unavailable.
+- Layout is mobile-first and Telegram webview friendly.
+
+## Test Plan
+
+- Unit tests for Telegram initData verification.
+- Unit tests for mini app auth handler membership outcomes.
+- Full repo typecheck, tests, and build.
+
+## Acceptance Criteria
+
+- [ ] Unauthorized users are blocked.
+- [ ] RU/EN language switch is present.
+- [ ] Base shell and navigation are ready for later finance views.