chore: complete v3.1 Deck Discovery milestone

Archive milestone artifacts (roadmap, requirements, phase directories),
evolve PROJECT.md with validated requirements and decisions,
reorganize ROADMAP.md with collapsed milestone entry.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: claude

.planning/MILESTONES.md

@@ -1,5 +1,34 @@
 # Milestones: Lumio
 
+## v3.1 Deck Discovery (Shipped: 2026-03-16)
+
+**Delivered:** End-to-end deck discovery pipeline — from deck.yaml metadata authoring in the deck builder, through Docora webhook indexing into a fulltext-searchable deck_index table, to a Discovery tab in the Android app where users search, browse by tag, and subscribe to shared decks with a single tap.
+
+**Phases completed:** 41-44 (8 plans total)
+
+**Key accomplishments:**
+
+- deck_index table with weighted tsvector/GIN fulltext search (name > tags > description) and immutable wrapper function for generated column
+- search_decks RPC with prefix matching for search-as-you-type, tag filtering, and card_count computed at query time
+- Subfolder-aware study RPCs: transparent subfolder_path filtering on 7 JOINs across get_study_cards_for_session and get_due_card_count
+- docora-webhook deck.yaml detection, parsing (parseYaml wrapper), and idempotent deck_index upsert/delete
+- deck-commit commit_yaml action with server-enforced author, language validation, and lightweight YAML serialization
+- DeckMetadataForm in deck builder with collapsible UI, dirty tracking, YAML load/save, EN/IT i18n
+- Discovery tab (4th bottom tab, compass icon) with search-as-you-type, tag chip bar, optimistic subscribe/unsubscribe
+- Shared deck entries in Repos screen with display_name enrichment from deck_index
+
+**Stats:**
+
+- 52 files changed (+7,691 / -78 lines)
+- 4 phases, 8 plans, 17 tasks
+- 4 days (2026-03-13 to 2026-03-16)
+
+**Git range:** `2cca21a` → `734b67d` (31 commits)
+
+**What's next:** v3.2 TBD
+
+---
+
 ## v3.0 Deck Builder Web (Shipped: 2026-03-13)
 
 **Delivered:** React SPA deck builder at deck.lumio.toto-castaldi.com where authenticated users create decks and flashcards in markdown, committed via edge function to a shared Git repo, synced by Docora for AI question generation.

.planning/PROJECT.md

@@ -2,7 +2,7 @@
 
 ## What This Is
 
-Lumio è una piattaforma di studio basata su flashcard che sfrutta l'AI per trasformare concetti in sessioni di apprendimento interattive con ripetizione spaziata. Due frontend: app nativa Android (React Native/Expo) per lo studio e web app React SPA (deck.lumio.toto-castaldi.com) per la creazione di deck e carte. L'app Android è bilingue IT/EN con branding Lumio, ripetizione spaziata SM-2, sessioni configurabili con cap RPC, dashboard compatta 2x2, card browse, storico sessioni, gestione errori sync, autenticazione dual-mode (Google OAuth + email/password), account linking bidirezionale, e password reset via OTP. Il deck builder web permette di creare/modificare deck e carte in markdown con editor live preview, committate via edge function su un repo Git condiviso. Il contenuto viene dai repository Git, le domande sono pre-generate dal sistema. Docora sincronizza e genera domande AI per entrambi i flussi (repo utente e repo condiviso).
+Lumio è una piattaforma di studio basata su flashcard che sfrutta l'AI per trasformare concetti in sessioni di apprendimento interattive con ripetizione spaziata. Due frontend: app nativa Android (React Native/Expo) per lo studio e web app React SPA (deck.lumio.toto-castaldi.com) per la creazione di deck e carte. L'app Android è bilingue IT/EN con branding Lumio, ripetizione spaziata SM-2, sessioni configurabili con cap RPC, dashboard compatta 2x2, card browse, storico sessioni, gestione errori sync, autenticazione dual-mode (Google OAuth + email/password), account linking bidirezionale, password reset via OTP, e discovery di deck condivisi con ricerca fulltext e iscrizione. Il deck builder web permette di creare/modificare deck e carte in markdown con editor live preview e metadata (nome, descrizione, lingua, tag) salvati in deck.yaml, committate via edge function su un repo Git condiviso. Il contenuto viene dai repository Git, le domande sono pre-generate dal sistema. Docora sincronizza e genera domande AI per entrambi i flussi (repo utente e repo condiviso), e indicizza i metadata deck nel deck_index per la ricerca fulltext.
 
 ## Core Value
 
@@ -101,20 +101,20 @@ Gli utenti studiano concetti tramite quiz generati dall'AI — il contenuto vien
 - ✓ Edge function deck-commit con 8 azioni GitHub API e isolamento path utente — v3.0
 - ✓ Docora sync repo condiviso per generazione AI — v3.0
 - ✓ Deploy produzione deck.lumio.toto-castaldi.com con SSL e CI/CD — v3.0
+- ✓ deck_index table con fulltext search tsvector/GIN e ranking pesato (name > tags > description) — v3.1
+- ✓ search_decks RPC con prefix matching per search-as-you-type e filtro tag — v3.1
+- ✓ Iscrizione a sottocartella deck (subfolder_path su user_repositories) con studio filtrato — v3.1
+- ✓ lumio-decks repo piattaforma sempre disponibile per sync Docora — v3.1
+- ✓ docora-webhook indicizza deck.yaml in deck_index (upsert/delete) — v3.1
+- ✓ deck-commit commit_yaml action con autore server-enforced e serializzazione YAML — v3.1
+- ✓ DeckMetadataForm nel deck builder (nome, descrizione, lingua, tag) con caricamento/salvataggio YAML — v3.1
+- ✓ Discovery tab (4° tab, icona bussola) con ricerca fulltext, chip tag, subscribe/unsubscribe ottimistico — v3.1
+- ✓ Deck condivisi visibili nella schermata Repos con display_name arricchito da deck_index — v3.1
+- ✓ i18n completa Discovery IT/EN (17 chiavi per lingua) — v3.1
 
 ### Active
 
-## Current Milestone: v3.1 Deck Discovery
-
-**Goal:** Permettere agli utenti mobile di scoprire e aggiungere deck creati con il deck builder, tramite ricerca fulltext su metadata deck nel repo condiviso lumio-decks.
-
-**Target features:**
-- Metadata a livello deck nel deck builder (nome, descrizione, categoria, tag) salvati in file deck.yaml
-- Indice deck in Supabase con fulltext search Postgres, popolato dal sync Docora di lumio-decks
-- Sincronizzazione lumio-decks a livello piattaforma (sempre presente)
-- Schermata discovery nell'app mobile con search bar fulltext su nome, categoria, tag, autore
-- Iscrizione utente a sottocartella specifica del repo condiviso (non intero repo)
-- Visualizzazione carte filtrate per deck scelto
+(None — planning next milestone)
 
 **Future milestones:**
 - v3.2: TBD
@@ -155,18 +155,19 @@ Gli utenti studiano concetti tramite quiz generati dall'AI — il contenuto vien
 
 ## Context
 
-**Stato attuale (post v3.0):**
+**Stato attuale (post v3.1):**
 - Monorepo pnpm: apps/android (Expo/React Native), apps/deck-builder (Vite/React SPA), apps/landing (static HTML), packages/core, packages/shared
-- Backend Supabase: auth (Google OAuth + email/password), DB, storage, edge functions (deck-commit con 8 azioni GitHub API), Docora webhook + study_sessions + card_review_schedule tables
+- Backend Supabase: auth (Google OAuth + email/password), DB, storage, edge functions (deck-commit con 9 azioni GitHub API + docora-webhook con deck.yaml indexing), Docora webhook + study_sessions + card_review_schedule + deck_index tables
 - Tech stack Android: Expo SDK 54, React Native 0.81, react-navigation, @lumio/core, i18n-js, react-native-marked, supermemo@2.0.23
 - Tech stack Deck Builder: Vite 7, React 19, react-router 7, Tailwind 4, @uiw/react-md-editor 4, vitest
 - CI/CD: lint-and-typecheck → build-apk → deploy-landing → deploy-deck-builder → deploy-migrations → deploy-functions
 - Versioning: STATE.md milestone → extract-version.cjs → version.ts, APK versionName, landing page, edge function
 - Auth condivisa: dual-mode Google OAuth + email/password, OTP verification, password reset, account linking bidirezionale
-- App Android bilingue IT/EN con branding Lumio, SM-2, sessioni configurabili, dashboard 2x2, card browse, study history, sync error handling
-- Deck builder web bilingue IT/EN con dark mode, deck CRUD, card authoring con markdown editor, live preview, toolbar
-- ~49,200 LOC (TS/TSX/CSS/SQL) — ~20,600 Android + ~28,600 deck-builder
-- 12 milestones shipped: v1.1 → v2.3 (mobile), v3.0 (deck builder web)
+- App Android bilingue IT/EN con branding Lumio, SM-2, sessioni configurabili, dashboard 2x2, card browse, study history, sync error handling, Discovery tab
+- Deck builder web bilingue IT/EN con dark mode, deck CRUD, card authoring con markdown editor, live preview, toolbar, metadata form (deck.yaml)
+- Discovery pipeline: deck.yaml → Docora webhook → deck_index (tsvector/GIN) → search_decks RPC → Discovery screen
+- ~56,900 LOC (TS/TSX/CSS/SQL) — ~28,300 Android + ~28,600 deck-builder
+- 13 milestones shipped: v1.1 → v3.1
 
 ## Constraints
 
@@ -262,6 +263,20 @@ Gli utenti studiano concetti tramite quiz generati dall'AI — il contenuto vien
 | Responsive MDEditor: split desktop, toggle mobile | Optimal UX per viewport via matchMedia | ✓ Good — v3.0 |
 | HTTP-only Nginx template, Certbot adds SSL on server | SSL config is server-specific, not repo-portable | ✓ Good — v3.0 |
 | deploy-deck-builder parallels deploy-landing in CI | Independent apps, no build dependency between them | ✓ Good — v3.0 |
+| Immutable wrapper function for tsvector generated column | PostgreSQL requires IMMUTABLE for generated columns; to_tsvector is STABLE | ✓ Good — v3.1 |
+| 'simple' tsvector config (no stemming) | Multilingual deck names need exact token match, not language-specific stemming | ✓ Good — v3.1 |
+| subfolder_path on user_repositories (not separate table) | Simpler schema, reuses existing subscription model | ✓ Good — v3.1 |
+| COALESCE-based unique index for nullable subfolder_path | Broader compatibility than NULLS NOT DISTINCT, clearer semantics | ✓ Good — v3.1 |
+| websearch_to_tsquery replaced with prefix matching | Search-as-you-type requires partial word matching (:* suffix) | ✓ Good — v3.1 |
+| Card count computed at query time (not stored) | Avoids sync complexity between cards table and deck_index | ✓ Good — v3.1 |
+| Transparent subfolder filter via JOIN conditions | No RPC signature changes, backward compatible with NULL subfolder_path | ✓ Good — v3.1 |
+| parseYaml wrapper reusing parseFrontmatter | No new YAML library needed; existing parser handles deck.yaml structure | ✓ Good — v3.1 |
+| Server-enforced author from user profile | Client value always ignored; prevents impersonation | ✓ Good — v3.1 |
+| UPSERT for idempotent webhook delivery | Handles out-of-order Docora webhook events gracefully | ✓ Good — v3.1 |
+| Client-side join for user_repositories + deck_index | No FK relationship, PostgREST cannot embed | ✓ Good — v3.1 |
+| 409 conflict as success in subscribeToDeck | Idempotent double-tap handling without error UI | ✓ Good — v3.1 |
+| Optimistic UI with Set rollback for subscribe | Immediate visual feedback, revert on error | ✓ Good — v3.1 |
+| Collapsible metadata form (collapsed by default) | Non-intrusive for quick deck browsing, expand when needed | ✓ Good — v3.1 |
 
 ---
-*Last updated: 2026-03-13 after v3.1 milestone start*
+*Last updated: 2026-03-16 after v3.1 milestone*

.planning/ROADMAP.md

@@ -14,7 +14,7 @@
 - ✅ **v2.2 Session Limits** — Phases 32-33 (shipped 2026-03-05)
 - ✅ **v2.3 Dashboard Polish** — Phases 34-35 (shipped 2026-03-05)
 - ✅ **v3.0 Deck Builder Web** — Phases 36-40 (shipped 2026-03-13)
-- 🚧 **v3.1 Deck Discovery** — Phases 41-44 (in progress)
+- ✅ **v3.1 Deck Discovery** — Phases 41-44 (shipped 2026-03-16)
 
 ## Phases
 
@@ -154,83 +154,19 @@ Full details: `.planning/milestones/v3.0-ROADMAP.md`
 
 </details>
 
-### v3.1 Deck Discovery (In Progress)
-
-**Milestone Goal:** Permettere agli utenti mobile di scoprire e aggiungere deck creati con il deck builder, tramite ricerca fulltext su metadata deck nel repo condiviso lumio-decks.
-
-- [x] **Phase 41: Database Foundation** - Schema, RPCs, RLS, and study pipeline updates for deck discovery and subfolder subscription (completed 2026-03-13)
-- [x] **Phase 42: Backend Pipeline** - Edge function enhancements for deck.yaml ingestion and commit support (completed 2026-03-13)
-- [x] **Phase 43: Deck Builder Metadata** - Metadata authoring UI for deck authors to publish discoverable decks (completed 2026-03-13)
-- [x] **Phase 44: Mobile Discovery** - Discovery tab with fulltext search, category browse, and deck subscription in the Android app (completed 2026-03-16)
-
-## Phase Details
-
-### Phase 41: Database Foundation
-**Goal**: Platform has a searchable deck index and subfolder-aware subscription model that integrates with existing study pipeline
-**Depends on**: Phase 40 (v3.0 shipped)
-**Requirements**: DBSR-01, DBSR-02, DBSR-03, DBSR-04, DBSR-05, STDY-01
-**Success Criteria** (what must be TRUE):
-  1. A fulltext search query against deck_index returns ranked results weighted by name > tags > description
-  2. A user can subscribe to a specific deck subfolder in the shared repo and the subscription is persisted in user_repositories with subfolder_path
-  3. Study RPCs return only cards from the subscribed subfolder (not the entire shared repo) when subfolder_path is set
-  4. The lumio-decks shared repo exists at platform level and is always available for Docora sync
-  5. A user with zero subscriptions sees zero results from study RPCs for the shared repo (no data leakage)
-**Plans**: 2 plans
-
-Plans:
-- [ ] 41-01-PLAN.md — Schema foundation: deck_index table with tsvector/GIN, subfolder_path on user_repositories, platform repo seed
-- [ ] 41-02-PLAN.md — RPCs: search_decks fulltext search function, study RPCs subfolder filtering
-
-### Phase 42: Backend Pipeline
-**Goal**: Edge functions can ingest deck.yaml metadata into the deck index and authors can commit deck.yaml from the deck builder
-**Depends on**: Phase 41
-**Requirements**: PIPE-01, PIPE-02, PIPE-03
-**Success Criteria** (what must be TRUE):
-  1. When Docora syncs a repo containing deck.yaml files, each deck's metadata appears in deck_index with correct name, description, category, tags, and author
-  2. When a deck.yaml file is deleted from the repo, the corresponding deck_index row is removed
-  3. The deck-commit edge function accepts a commit_yaml action that writes deck.yaml to the correct user path with validation
-**Plans**: 2 plans
-
-Plans:
-- [ ] 42-01-PLAN.md — docora-webhook deck.yaml handling: parseYaml wrapper, upsert into deck_index on create/update, delete on removal
-- [ ] 42-02-PLAN.md — deck-commit commit_yaml action: metadata validation, server-enforced author, YAML serialization, GitHub commit
-
-### Phase 43: Deck Builder Metadata
-**Goal**: Deck authors can describe their decks with structured metadata that flows into the discovery pipeline
-**Depends on**: Phase 42
-**Requirements**: DKBL-01, DKBL-02, DKBL-03
-**Success Criteria** (what must be TRUE):
-  1. User can fill in deck display name, description, category (from predefined list), and tags via a form in the deck builder
-  2. Saving metadata writes a deck.yaml file to the deck folder in the shared repo via deck-commit
-  3. When selecting a deck that already has a deck.yaml, the metadata form loads with existing values
-**Plans**: 2 plans
-
-Plans:
-- [ ] 43-01-PLAN.md — API layer: get_yaml server action, getDeckYaml/commitYaml client functions, unit tests
-- [ ] 43-02-PLAN.md — UI: DeckMetadataForm component, DeckDetailPanel integration, i18n keys (EN+IT)
-
-### Phase 44: Mobile Discovery
-**Goal**: Mobile users can discover shared decks via search, browse by category, and subscribe to study them
-**Depends on**: Phase 43
-**Requirements**: DISC-01, DISC-02, DISC-03, DISC-04, DISC-05, DISC-06, DISC-07, DISC-08
-**Success Criteria** (what must be TRUE):
-  1. A 4th bottom tab (compass icon) opens the Discovery screen with a search bar and category chip bar
-  2. Typing in the search bar returns matching decks (debounced) showing name, description, card count, and author
-  3. Tapping a category chip filters results to that category without typing
-  4. User can subscribe to a deck with a single tap and the deck's cards appear in their next study session
-  5. User can unsubscribe from a deck, removing its cards from future study sessions
-  6. Empty states display contextual guidance (no decks available, no search results, all decks already subscribed)
-  7. All discovery UI text is available in both IT and EN
-**Plans**: 2 plans
-
-Plans:
-- [ ] 44-01-PLAN.md — Data layer: discovery functions in @lumio/core (searchDecks, subscribe, unsubscribe, subscriptions, flag emoji) + i18n strings (EN/IT)
-- [ ] 44-02-PLAN.md — Discovery UI: 4th tab in MainNavigator, DiscoveryScreen with search/tags/subscribe, DeckCard, TagChipBar, Repos screen shared deck entries
+<details>
+<summary>✅ v3.1 Deck Discovery (Phases 41-44) — SHIPPED 2026-03-16</summary>
 
-## Progress
+- [x] Phase 41: Database Foundation (2 plans) — completed 2026-03-13
+- [x] Phase 42: Backend Pipeline (2 plans) — completed 2026-03-13
+- [x] Phase 43: Deck Builder Metadata (2 plans) — completed 2026-03-13
+- [x] Phase 44: Mobile Discovery (2 plans) — completed 2026-03-16
+
+Full details: `.planning/milestones/v3.1-ROADMAP.md`
 
-**Execution Order:**
-Phases execute in numeric order: 41 → 42 → 43 → 44
+</details>
+
+## Progress
 
 | Phase | Milestone | Plans Complete | Status | Completed |
 |-------|-----------|----------------|--------|-----------|
@@ -246,11 +182,8 @@ Phases execute in numeric order: 41 → 42 → 43 → 44
 | 32-33. Session Limits | v2.2 | 2/2 | Complete | 2026-03-05 |
 | 34-35. Dashboard Polish | v2.3 | 2/2 | Complete | 2026-03-05 |
 | 36-40. Deck Builder Web | v3.0 | 10/10 | Complete | 2026-03-13 |
-| 41. Database Foundation | 2/2 | Complete    | 2026-03-13 | - |
-| 42. Backend Pipeline | 2/2 | Complete    | 2026-03-13 | - |
-| 43. Deck Builder Metadata | 2/2 | Complete    | 2026-03-13 | - |
-| 44. Mobile Discovery | 2/2 | Complete    | 2026-03-16 | - |
+| 41-44. Deck Discovery | v3.1 | 8/8 | Complete | 2026-03-16 |
 
 ---
 *Roadmap created: 2026-01-29*
-*Last updated: 2026-03-15 -- Phase 44 plans created (2 plans)*
+*Last updated: 2026-03-16 -- v3.1 Deck Discovery shipped*