patch-docs.patch

From cd1382625a48e06450e3ace78ead47a8b527e7f8 Mon Sep 17 00:00:00 2001
From: Richard Pinedo <richard.pinedo@yahoo.com>
Date: Sat, 28 Mar 2026 02:17:01 -0400
Subject: [PATCH] docs: memorialize Phase 2 character bazaar vision and update
 roadmap

---
 docs/design-onboarding-character-selection.md | 35 +++++++++++++++++++
 docs/project-roadmap-and-progress-tracking.md |  8 +++--
 2 files changed, 41 insertions(+), 2 deletions(-)

diff --git a/docs/design-onboarding-character-selection.md b/docs/design-onboarding-character-selection.md
index f631ac25f..432637ceb 100644
--- a/docs/design-onboarding-character-selection.md
+++ b/docs/design-onboarding-character-selection.md
@@ -65,5 +65,40 @@ location.reload()
 ## Open Questions
 
 1. **JannyAI Priority**: JannyAI is now the primary recommendation. JanitorAI is removed from the "Cleanest Experience" list due to export friction.
+
 2. **First Greeting Preview**: I will use the first greeting (`greetings[0]`) as the descriptive sub-text in the selection card.
 
+---
+
+## Phase 2: The Integrated Character Bazaar (Concept)
+
+We want to move from a manual "Upload" feel to a "Magical Discovery" feel.
+
+### 1. Interactive Browse View
+Instead of just external links, clicking a community site (JannyAI, Chub.ai, etc.) will open a **New View** (likely an Electron-managed iframe or webview) with:
+- **Navigation Controls**: A simple "Back" button to return to the selection grid.
+- **Task Guidance**: A overlay or header explaining: *"Find a character you like and click their download (PNG) button."*
+
+### 2. Download Interception
+The core technical "magic" is intercepting the `.png` download from the browser view:
+- **Electron Hook**: Listen for download events targeting `.png` files with `chara_card_v2` metadata.
+- **Immediate Ingestion**: Automatically call `cardStore.addCard()` as soon as the download starts/finishes.
+- **Dynamic Update**: The Onboarding UI detects this new card and automatically selects it.
+
+### 3. Quick Association Layer
+Once a "soul" (PNG) is found, the user is prompted to:
+- **Choose a Vessel**: Select which built-in VRM or Live2D model to associate with this custom character.
+- **Model Palette**: A small gallery of our premium models (ReLU, Hiyori, etc.) simplified for quick association.
+
+### 4. Completion Flow
+- **Locked State**: The "Start Your Journey" button remains disabled or "unlit" until a character is successfully selected or imported.
+- **Flow**: `Click Website -> Find Character -> Click Download -> Character Auto-Imports -> Select Model Vessel -> Finish button lights up -> Start Journey.`
+
+---
+
+## Upcoming Tasks (Phase 2)
+- [ ] Research Electron `session.on('will-download')` for iframe/webview interception.
+- [ ] Implement the "Character Bazaar" fullscreen iframe layout in `OnboardingDialog`.
+- [ ] Add the "Model Association" mini-gallery to the import success state.
+- [ ] Update character selection logic to support an "Unlocked-by-Action" finish state.
+
diff --git a/docs/project-roadmap-and-progress-tracking.md b/docs/project-roadmap-and-progress-tracking.md
index 6434dfe5b..947811832 100644
--- a/docs/project-roadmap-and-progress-tracking.md
+++ b/docs/project-roadmap-and-progress-tracking.md
@@ -72,8 +72,12 @@ This document tracks the current development state of the AIRI project, specific
 ## Pending Items (Roadmap)
 - **AIRI Card Export Preview Modes**: Explore an optional export mode that bakes the currently selected stage background into the composed PNG preview, while keeping the current transparent/framed export as the default. This should stay optional so card portability and predictable framing are not lost.
 - **Character Photo Mode / Saved Shots**: Explore a lightweight "photo mode" for capturing stills of the current character pose/frame directly from stage. Initial scope should be simple one-click image capture and download; a later extension could allow cards to keep a preferred preview shot for export. Keep this intentionally small to avoid overengineering into a full screenshot studio too early.
-- **Onboarding Flow Repackaging (Phase 1)**: (Current Focus) Redesign the initial setup to include a character picker and import links (e.g., character hubs) early in the flow. Move character settings to be more approachable, ensuring users know how to edit personality/behavior immediately after import.
-- **Browser-Integrated Card Imports (Phase 2)**: Deep integration with external character sites via an in-app Electron browser. Hooks for direct importing while respecting site ads/iframes.
+- **Onboarding Flow Repackaging (Phase 1)**: (Completed) Redesigned the initial setup to include a high-fidelity character selection grid, restored the logical step order (Providers -> Config -> Model -> Character), and refined the seeded 'Founder' profiles (ReLU, Dr. Aria, Lupin).
+- **The Integrated Character Bazaar (Phase 2)**: Deep integration with external character sites (JannyAI, Chub.ai, etc.) via an in-app Electron browser view.
+  - **Download Interception**: System-level hooks to catch `.png` character cards and auto-import them into the character list.
+  - **Task Guidance**: In-view overlays to help users find and "capture" new souls.
+  - **Quick Association**: A "Vessel Picker" to instantly link imported souls to built-in VRM/Live2D models.
+  - **Magical Flow**: The onboarding "Start Your Journey" button only unlocks once a character has been successfully associated.
 - **Agentic Asset Creation (Continued)**:
   - **Outfits (textures)**: (Coming soon)
   - **Simple 3D Props**: (Coming eventually)
-- 
2.46.2.windows.1