Add foundational architecture, context, invariants, quality bar, and vision documents

.cursorrules

@@ -1 +0,0 @@
-tools/content/CONTEXT.md

.cursorrules

@@ -0,0 +1,20 @@
+# Zapstore — Cursor Rules
+
+Source of truth:
+- specs/guidelines/CONTEXT.md (orientation only)
+- specs/guidelines/VISION.md
+- specs/guidelines/ARCHITECTURE.md
+- specs/guidelines/INVARIANTS.md
+- specs/guidelines/QUALITY_BAR.md
+
+Hard constraints:
+- Do NOT edit files under specs/guidelines unless explicitly instructed by a human.
+- If specs are unclear or contradictory, STOP and report a "Spec Issue". Do not guess.
+
+Working rules:
+- Prefer small, localized changes. Avoid unrelated refactors.
+- After dependency changes, run: fvm flutter pub get
+- Fix any analyze/lint errors introduced by your changes.
+- Do not use polling or artificial Future.delayed; await Futures/Streams correctly.
+- Keep lib/widgets/common generic and reusable.
+- Assume Android as default target unless instructed otherwise.

specs/guidelines/ARCHITECTURE.md

@@ -0,0 +1,35 @@
+# Zapstore — Architecture
+
+## Core Principle
+Architecture exists to prevent accidental coupling and hidden ownership.
+Each package has clear responsibilities and must not exceed them.
+
+## Package Responsibilities
+
+### models
+- Domain models for Nostr events, kinds, zaps, releases, and NWC
+- Parsing, validation, signing, encryption, and verification
+- Pure domain logic only
+- Must not depend on storage, networking, isolates, or UI
+
+### purplebase
+- Local-first storage and indexing (SQLite)
+- Relay synchronization and subscription lifecycle management
+- Background work and isolate execution
+- Must not depend on UI or presentation logic
+
+### zapstore
+- Flutter UI and application orchestration
+- Navigation, presentation, and user interaction
+- Coordinates use cases across packages
+- Must not contain domain rules or persistence logic
+
+## Dependency Rules
+- zapstore → purplebase → models
+- Reverse dependencies are forbidden
+- UI widgets must not manage relay connections, storage, or background jobs
+
+## Ownership & Orchestration
+- Relay pools and subscriptions are owned by purplebase
+- Background work lifecycle is explicit and cancellable
+- zapstore orchestrates flows but does not own low-level resources

specs/guidelines/CONTEXT.md

@@ -0,0 +1,82 @@
+# Zapstore — Project Context
+
+This document provides **orientation only**.
+It does **not** define rules, behavior, or constraints.
+
+If anything in this file conflicts with files under `specs/00_foundation/`,
+this file is wrong.
+
+---
+
+## What This Repository Is
+
+Zapstore is a Flutter-based, local-first application store built on top of
+the Nostr protocol and Bitcoin Lightning payments.
+
+It allows users to:
+- discover apps published via Nostr,
+- verify and install applications safely,
+- and directly support developers through zaps.
+
+Zapstore prioritizes trust, verification, and user sovereignty over scale,
+growth, or engagement metrics.
+
+---
+
+## Core Stack (High Level)
+
+- **Frontend**: Flutter (Android-first)
+- **Protocols**: Nostr, Lightning Network
+- **Payments**: Zaps, NWC (NIP-47)
+- **Data Model**: Nostr event kinds (apps, releases, files, zaps)
+- **Storage**: Local-first (SQLite), relay-backed sync
+- **Execution Model**: Async + isolates (non-blocking UI)
+
+---
+
+## Repository Structure (Conceptual)
+
+This repository is organized into three main packages:
+
+- **zapstore**
+  - Flutter UI and application orchestration
+  - Navigation, presentation, and user interaction
+
+- **purplebase**
+  - Local-first storage, indexing, and relay synchronization
+  - Background work and isolate execution
+
+- **models**
+  - Pure domain models and utilities
+  - Nostr kinds, parsing, signing, encryption, verification
+
+Details and dependency rules are defined in `ARCHITECTURE.md`.
+
+---
+
+## How to Read the Specs (Important)
+
+The following files define the actual guardrails of the project:
+
+1. **VISION.md**
+   - What Zapstore is and is not
+2. **ARCHITECTURE.md**
+   - Package responsibilities and dependency boundaries
+3. **INVARIANTS.md**
+   - Non-negotiable behavioral guarantees
+4. **QUALITY_BAR.md**
+   - Definition of acceptable work and anti-patterns
+
+These files are human-owned and change slowly.
+
+---
+
+## What This File Is Not
+
+- This file does **not** define invariants or rules
+- This file does **not** describe UI flows or behavior
+- This file does **not** override any foundation spec
+- This file should remain small and stable
+
+Its sole purpose is to provide initial context for humans and AI agents
+before reading the foundation specifications.

specs/guidelines/INVARIANTS.md

@@ -0,0 +1,36 @@
+# Zapstore — Invariants
+
+The following guarantees are non-negotiable.
+If any invariant is violated, the implementation is incorrect.
+
+## UI Safety
+- The UI thread must never block on network, file I/O, cryptography, or relay operations.
+- UI rendering must remain responsive under partial or total network failure.
+
+## Async Discipline
+- No polling or artificial delays (e.g., Future.delayed for timing).
+- Background work must surface results asynchronously and non-blockingly.
+- All async work must be cancellable.
+
+## Local-First Guarantees
+- Cached data must be preferred over network data when available.
+- Installed apps and metadata must be accessible offline.
+- Network failures must degrade gracefully.
+
+## Security & Verification
+- APKs must never be installed unless their hash matches the expected value.
+- Signed Nostr events must be verified before use.
+- NWC secrets must be stored securely and must never be logged or exposed.
+
+## Data Robustness
+- Parsing unknown, missing, or future tags must not crash the app.
+- Partial or invalid data must degrade gracefully.
+
+## Lifecycle Safety
+- Subscriptions must always be cancellable.
+- Isolates and background jobs must not leak resources.
+- Reconnection or retries must not duplicate events or actions.
+
+## UX Safety
+- All user-visible processes must have explicit states (loading, empty, success, error).
+- Silent failures are unacceptable.

specs/guidelines/QUALITY_BAR.md

@@ -0,0 +1,44 @@
+# Zapstore — Quality Bar
+
+## General Expectations
+- Correct behavior matters more than coverage numbers.
+- Happy-path-only implementations are insufficient.
+- Failures must be explicit and observable.
+
+## Layer Expectations
+
+### models
+- Parsing and serialization behavior must be tested.
+- Unknown or future fields must be tolerated.
+
+### purplebase
+- Storage and query behavior must be testable without network access.
+- Subscription, cancellation, and isolate behavior must be validated.
+
+### zapstore UI
+- UI state machines must be explicit and testable.
+- Loading, empty, error, and retry states are mandatory.
+- UI must remain usable under degraded network conditions.
+
+## Implementation Expectations
+- Follow existing patterns in the nearest module.
+- Avoid introducing new architectural layers unless required by a spec.
+- Do not perform broad or stylistic refactors.
+- Prefer clarity and locality over abstraction.
+
+## Testing Expectations
+- Tests must validate behavior, not implementation details.
+- Failure, cancellation, and degraded-network paths must be covered.
+- Tests that only assert the happy path are insufficient.
+
+## Anti-Patterns
+- Silent failures
+- Blocking the UI thread
+- Artificial delays or polling
+- Large refactors unrelated to the task
+
+## Editing Policy (Human-Owned)
+- These files are human-owned and change slowly.
+- Keep them small, focused, and easy to reason about.
+- Prefer explicit constraints over prose.
+- Create new markdown files only when unavoidable.

specs/guidelines/VISION.md

@@ -0,0 +1,24 @@
+# Zapstore — Vision
+
+## What Zapstore Is
+Zapstore is a local-first, Nostr-native app distribution platform focused on trust,
+verification, and user sovereignty.
+
+It enables discovering, installing, and supporting apps using open protocols
+(Nostr + Bitcoin/Lightning), without centralized app store control.
+
+## Who It Is For
+- Users who value open networks and self-custody
+- Developers distributing apps via Nostr
+- Communities curating and funding software directly
+
+## What Success Means
+- Users can reliably discover and install apps offline-first
+- Installs and updates are verifiable and safe
+- Developers can be supported directly via zaps
+
+## Non-Goals
+- Zapstore is not a general-purpose app marketplace
+- Zapstore does not optimize for engagement or growth metrics
+- Zapstore does not require real-world identity or accounts
+- Zapstore does not hide trust, verification, or provenance from users