docs: add roadmap, ADRs, and initial HOUSEBOT specs

docs/decisions/ADR-001-tech-stack.md

@@ -0,0 +1,42 @@
+# ADR-001: V1 Tech Stack
+
+## Status
+Accepted
+
+## Context
+The project needs to be modern, modular, and scalable while still delivering v1 quickly.
+
+## Decision
+- Runtime/package manager/test runner: Bun
+- Language: TypeScript (strict mode)
+- Bot framework: grammY
+- Database: Supabase Postgres
+- Deployment runtime: Google Cloud Run
+- Scheduling: Google Cloud Scheduler
+- Frontend mini app: SolidJS (Vite SPA) + Tailwind
+- Validation: Zod
+- Linting: Oxlint
+- Error tracking: Sentry
+- Logging/metrics baseline: Cloud Logging/Monitoring
+
+## Rationale
+- Bun provides a fast unified developer workflow.
+- grammY is TypeScript-friendly with strong middleware patterns.
+- Supabase keeps SQL-first data modeling while reducing ops overhead.
+- Cloud Run + Scheduler offers serverless simplicity and predictable scheduling.
+- Solid SPA provides modern UI performance with lightweight runtime cost.
+- Oxlint enables fast linting suitable for small-commit workflow.
+
+## Consequences
+Positive:
+- Strong portfolio architecture with pragmatic service count.
+- Clear path to production without heavy platform ops.
+
+Negative:
+- Some enterprise tooling (Prometheus/Grafana/K8s) is deferred.
+- Serverless constraints require disciplined idempotency and stateless design.
+
+## Alternatives Considered
+- Fly.io runtime: good DX, but Cloud Run better matches serverless objective.
+- Convex backend: strong DX, but SQL/reporting fit is weaker for financial ledger.
+- Telegraf bot framework: mature ecosystem, but less desirable TS ergonomics.

docs/decisions/ADR-002-hexagonal-architecture.md

@@ -0,0 +1,50 @@
+# ADR-002: Hexagonal Architecture (Ports and Adapters)
+
+## Status
+Accepted
+
+## Context
+The project combines domain-heavy finance logic, Telegram integration, mini-app APIs, and scheduled jobs. Without strict boundaries, framework and infrastructure concerns will leak into core logic.
+
+## Decision
+Adopt hexagonal architecture with explicit layers:
+- Domain: pure business model and invariants.
+- Application: use-case orchestration.
+- Ports: interfaces for repositories/services.
+- Adapters: Telegram, DB, LLM, scheduler, HTTP.
+- Composition root: runtime wiring only.
+
+## Boundary Rules
+- Domain cannot import adapters, SDKs, HTTP, or SQL clients.
+- Application cannot import concrete adapter implementations.
+- Adapters can depend on SDKs and infra concerns but must implement ports.
+- Entry points create dependency graph and pass ports to use-cases.
+
+## Module Layout
+- `packages/domain`
+- `packages/application`
+- `packages/ports`
+- `packages/adapters-*`
+- `apps/*` for composition and delivery endpoints
+
+## Rationale
+- Keeps financial logic testable and framework-independent.
+- Enables incremental replacement of adapters (e.g., parser provider).
+- Supports clean growth from v1 to larger-scale architecture.
+
+## Consequences
+Positive:
+- High maintainability and clear ownership of concerns.
+- Better interview-readability of architecture.
+
+Negative:
+- Requires initial discipline and more explicit interfaces.
+- Slight boilerplate overhead for small features.
+
+## Risks and Mitigations
+Risk:
+- Overengineering through too many tiny abstractions.
+
+Mitigation:
+- Create ports only for external boundaries and meaningful seams.
+- Keep use-cases focused; avoid generic base classes.