ai-flow-dev 2.1.2 → 2.1.3

package/README.md

@@ -133,7 +133,7 @@ Or using uv (Python tool manager):
 uv tool install ai-flow-dev
 ```
 
-**Current version:** 2.1.1
+**Current version:** 2.1.2
 
 ---
 
@@ -261,8 +261,9 @@ After initialization, use these slash commands in your AI tool:
 
 > **Note:** Command prefix may vary by AI tool. Examples use `/flow-` (GitHub Copilot), but Claude may use `/` alone, Cursor may use `@`, etc. Check your tool's documentation.
 
-**Backend Projects:** 19 commands  
-**Frontend/Mobile Projects:** 2 commands (build + docs-sync)  
+**Backend Projects:** 8 commands  
+**Frontend Projects:** 2 commands  
+**Mobile Projects:** 2 commands  
 **Fullstack Projects:** Combined backend + frontend commands
 
 **Documentation & Build:**
@@ -338,7 +339,7 @@ After initialization, use these slash commands in your AI tool:
 
 ## 🎯 Generated Documentation
 
-**Backend** (14 docs): AGENT.md, ai-instructions.md, copilot-instructions.md, project-brief.md, plus 8 technical docs and 2 specs
+**Backend** (14 docs): AGENT.md, ai-instructions.md, copilot-instructions.md, project-brief.md, README.md, plus 8 technical docs and 1 spec
 
 **Frontend** (15 docs): AGENT.md, ai-instructions.md, project-brief.md, plus 9 technical docs and 3 specs
 

package/dist/cli.js

@@ -625,7 +625,7 @@ async function initializeProject(targetPath, aiTool, projectType, projectName, p
 program
     .name('ai-flow')
     .description('AI-powered development workflow from idea to production. Generate specs, plan features, and build with AI assistance.')
-    .version('2.1.2');
+    .version('2.1.3');
 program
     .command('init')
     .description('Initialize AI Flow in current directory')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-flow-dev",
-  "version": "2.1.2",
+  "version": "2.1.3",
   "description": "AI-powered development workflow from idea to production. Generate specs, plan features, and build with AI assistance throughout your project lifecycle.",
   "type": "module",
   "main": "dist/cli.js",

package/prompts/backend/flow-build-phase-0.md

@@ -6,6 +6,7 @@
 ### 🎯 Objective
 
 Efficiently analyze existing projects using a **layered, incremental approach** that:
+
 - ✅ Minimizes context usage (50-75% reduction)
 - ✅ Supports ALL major backend languages and frameworks
 - ✅ Provides smart caching for instant re-runs
@@ -36,7 +37,7 @@ Result Synthesis & Pre-population
 
 **Actions:**
 
-1. Check if `.ai-flow/analysis.json` exists
+1. Check if `.ai-flow/cache/docs-analysis.json` exists
 2. If exists:
    - Read `analyzedAt` timestamp
    - Read `filesAnalyzed` with their timestamps
@@ -448,6 +449,7 @@ This scans directory organization and file counts without reading code.
 **Language-specific directory patterns:**
 
 **Node.js/TypeScript:**
+
 ```
 Scanning directories:
 • src/**/* or app/**/* or lib/**/*
@@ -465,6 +467,7 @@ Counting files by pattern:
 ```
 
 **Python:**
+
 ```
 Scanning directories:
 • app/**/*.py or src/**/*.py
@@ -479,6 +482,7 @@ Counting files by pattern:
 ```
 
 **PHP:**
+
 ```
 Scanning directories:
 • app/**/*.php or src/**/*.php
@@ -492,6 +496,7 @@ Counting files by pattern:
 ```
 
 **Java:**
+
 ```
 Scanning directories:
 • src/main/java/**/*.java
@@ -506,6 +511,7 @@ Counting files by pattern:
 ```
 
 **C#/.NET:**
+
 ```
 Scanning directories:
 • **/*.cs (excluding obj/, bin/)
@@ -520,6 +526,7 @@ Counting files by pattern:
 ```
 
 **Go:**
+
 ```
 Scanning directories:
 • **/*.go (excluding vendor/)
@@ -533,6 +540,7 @@ Counting files by pattern:
 ```
 
 **Ruby:**
+
 ```
 Scanning directories:
 • app/**/*.rb
@@ -559,56 +567,68 @@ Counting files by pattern:
 **Based on detected ORM:**
 
 **Prisma:**
+
 - Read `prisma/schema.prisma`
 - Extract model names only (regex: `model (\w+)`)
 - Count total models
 - Count relationships (count occurrences of `@relation`)
 
 **TypeORM:**
+
 - Glob `*.entity.{ts,js}`
 - Extract entity names from `@Entity()` decorator (regex, no full parsing)
 - Count entities
 
 **Sequelize:**
+
 - Glob `models/**/*.{ts,js}`
 - Count model files
 
 **Mongoose:**
+
 - Glob `*.schema.{ts,js}` or `models/**/*.{ts,js}`
 - Search for `new Schema(` pattern
 - Count schemas
 
 **Django:**
+
 - Read `*/models.py` files
 - Extract class names inheriting from `models.Model` (regex)
 - Count models
 
 **SQLAlchemy:**
+
 - Read `**/models.py` or `**/*_model.py`
 - Extract classes with `Base` or `db.Model` (regex)
 - Count models
 
 **Eloquent (Laravel):**
+
 - Glob `app/Models/**/*.php`
 - Count model files
 
 **Doctrine (Symfony/PHP):**
+
 - Glob `src/Entity/**/*.php`
 - Count entity files
 
 **Hibernate/JPA (Java):**
+
 - Glob `**/*Entity.java`
 - Count entity files
 
 **Entity Framework (.NET):**
+
 - Glob `**/Models/**/*.cs` or `**/Entities/**/*.cs`
 - Count entity files
 
 **GORM (Go):**
+
 - Search for `type.*struct` in `models/**/*.go`
 - Count structs
 
 **ActiveRecord (Ruby):**
+
 - Glob `app/models/**/*.rb`
 - Count model files
 
@@ -639,6 +659,7 @@ Checking docs/ directory...
 ```
 
 **Maturity Level:**
+
 - 🌱 **Minimal:** 0-1 docs → Suggest **MVP or Production-Ready scope**
 - 🌿 **Basic:** 2-4 docs → Suggest **Production-Ready scope**
 - 🌳 **Comprehensive:** 5-7 docs → Suggest **Production-Ready or Enterprise scope**
@@ -781,11 +802,11 @@ function selectFilesToAnalyze(files: string[], category: string, maxFiles: numbe
     services: 9,
     entities: 10,
     repositories: 8,
-    dto: 7
+    dto: 7,
   };
 
   // Group by module/feature
-  const byModule = groupBy(files, file => file.split('/')[1]);
+  const byModule = groupBy(files, (file) => file.split('/')[1]);
 
   // Sample proportionally from each module
   const samples = [];
@@ -851,6 +872,7 @@ Your choice: __
 **Node.js/TypeScript:**
 
 **API Endpoints (NestJS):**
+
 ```typescript
 // Sample up to 30 controller files
 const controllerFiles = glob('**/*.controller.{ts,js}').slice(0, 30);
@@ -867,7 +889,7 @@ for (const file of controllerFiles) {
     ...content.matchAll(/@Post\(['"](.+?)['"]\)\s+(\w+)/g),
     ...content.matchAll(/@Put\(['"](.+?)['"]\)\s+(\w+)/g),
     ...content.matchAll(/@Delete\(['"](.+?)['"]\)\s+(\w+)/g),
-    ...content.matchAll(/@Patch\(['"](.+?)['"]\)\s+(\w+)/g)
+    ...content.matchAll(/@Patch\(['"](.+?)['"]\)\s+(\w+)/g),
   ];
 
   for (const [fullMatch, path, handlerName, method] of routes) {
@@ -875,13 +897,14 @@ for (const file of controllerFiles) {
       method: method,
       path: `${basePath}/${path}`,
       handler: handlerName,
-      file: file
+      file: file,
     });
   }
 }
 ```
 
 **API Endpoints (Express):**
+
 ```typescript
 const routeFiles = glob('**/routes/**/*.{ts,js}').slice(0, 20);
 
@@ -890,16 +913,17 @@ for (const file of routeFiles) {
 
   const routes = [
     ...content.matchAll(/router\.(get|post|put|delete|patch)\(['"](.+?)['"],\s*(\w+)/g),
-    ...content.matchAll(/app\.(get|post|put|delete|patch)\(['"](.+?)['"],\s*(\w+)/g)
+    ...content.matchAll(/app\.(get|post|put|delete|patch)\(['"](.+?)['"],\s*(\w+)/g),
   ];
 
   for (const [, method, path, handler] of routes) {
-    endpoints.push({method: method.toUpperCase(), path, handler, file});
+    endpoints.push({ method: method.toUpperCase(), path, handler, file });
   }
 }
 ```
 
 **Entities (Prisma):**
+
 ```typescript
 // Read prisma/schema.prisma
 const schema = readFile('prisma/schema.prisma');
@@ -915,9 +939,9 @@ for (const [, modelName, body] of models) {
     fields: fields.map(([, name, type, decorator]) => ({
       name,
       type,
-      decorator
+      decorator,
     })),
-    relationships: [...body.matchAll(/@relation\(([^)]+)\)/g)].map(m => m[1])
+    relationships: [...body.matchAll(/@relation\(([^)]+)\)/g)].map((m) => m[1]),
   };
 
   entities.push(entity);
@@ -927,6 +951,7 @@ for (const [, modelName, body] of models) {
 **Python:**
 
 **API Endpoints (FastAPI):**
+
 ```python
 # Sample router files
 routerFiles = glob('**/*routes.py', '**/*router.py')[:20]
@@ -947,6 +972,7 @@ for file in routerFiles:
 ```
 
 **Entities (Django):**
+
 ```python
 # Read models.py files
 modelFiles = glob('**/models.py')[:15]
@@ -970,6 +996,7 @@ for file in modelFiles:
 **PHP:**
 
 **API Endpoints (Laravel):**
+
 ```php
 // Read routes/api.php and routes/web.php
 $routeFiles = ['routes/api.php', 'routes/web.php'];
@@ -992,6 +1019,7 @@ foreach ($routeFiles as $file) {
 ```
 
 **Entities (Eloquent):**
+
 ```php
 // Glob app/Models/*.php
 $modelFiles = glob('app/Models/*.php');
@@ -1014,6 +1042,7 @@ foreach ($modelFiles as $file) {
 **Java:**
 
 **API Endpoints (Spring Boot):**
+
 ```java
 // Glob **/*Controller.java (sample 25)
 List<String> controllerFiles = glob("**/*Controller.java").subList(0, 25);
@@ -1040,6 +1069,7 @@ for (String file : controllerFiles) {
 ```
 
 **Entities (JPA/Hibernate):**
+
 ```java
 // Glob **/*Entity.java
 List<String> entityFiles = glob("**/*Entity.java").subList(0, 30);
@@ -1069,6 +1099,7 @@ for (String file : entityFiles) {
 **C#/.NET:**
 
 **API Endpoints (ASP.NET Core):**
+
 ```csharp
 // Glob **/*Controller.cs
 var controllerFiles = Directory.GetFiles(".", "*Controller.cs", SearchOption.AllDirectories).Take(25);
@@ -1095,6 +1126,7 @@ foreach (var file in controllerFiles) {
 ```
 
 **Entities (Entity Framework):**
+
 ```csharp
 // Glob **/Models/**/*.cs or **/Entities/**/*.cs
 var entityFiles = Directory.GetFiles(".", "*.cs", SearchOption.AllDirectories)
@@ -1125,6 +1157,7 @@ foreach (var file in entityFiles) {
 **Go:**
 
 **API Endpoints (Gin):**
+
 ```go
 // Read handler files
 handlerFiles := filepath.Glob("**/handlers/**/*.go")[:20]
@@ -1148,6 +1181,7 @@ for _, file := range handlerFiles {
 ```
 
 **Entities (GORM):**
+
 ```go
 // Read model files
 modelFiles := filepath.Glob("**/models/**/*.go")[:20]
@@ -1180,6 +1214,7 @@ for _, file := range modelFiles {
 **Ruby:**
 
 **API Endpoints (Rails):**
+
 ```ruby
 # Read routes.rb
 routes_file = 'config/routes.rb'
@@ -1214,6 +1249,7 @@ end
 ```
 
 **Entities (ActiveRecord):**
+
 ```ruby
 # Glob app/models/*.rb
 model_files = Dir.glob('app/models/**/*.rb')[0..20]
@@ -1242,6 +1278,7 @@ end
 **Rust:**
 
 **API Endpoints (Actix):**
+
 ```rust
 // Read handler files
 let handler_files: Vec<_> = glob("**/handlers/**/*.rs").unwrap().take(15).collect();
@@ -1264,6 +1301,7 @@ for file in handler_files {
 ```
 
 **Entities (Diesel):**
+
 ```rust
 // Read schema.rs and models.rs
 let schema = fs::read_to_string("src/schema.rs").ok();
@@ -1287,12 +1325,14 @@ if let Some(schema_content) = schema {
 **Scan for security patterns across all languages:**
 
 **Authentication:**
+
 - JWT libraries: `jsonwebtoken`, `@nestjs/jwt`, `pyjwt`, `jjwt`, etc.
 - Session libraries: `express-session`, `django.contrib.sessions`
 - OAuth libraries: `passport`, `authlib`, `spring-security-oauth2`
 - Password hashing: `bcrypt`, `argon2`, `password_hash` (PHP)
 
 **Validation:**
+
 - `class-validator`, `joi`, `zod` (Node.js)
 - `pydantic`, `marshmallow` (Python)
 - Laravel validation rules (PHP)
@@ -1300,16 +1340,19 @@ if let Some(schema_content) = schema {
 - Data Annotations (.NET)
 
 **Rate Limiting:**
+
 - `express-rate-limit`, `@nestjs/throttler`
 - `django-ratelimit`, `slowapi`
 - Bucket4j (Java)
 
 **CORS:**
+
 - `cors` package (Node.js)
 - `django-cors-headers` (Python)
 - Spring CORS configuration (Java)
 
 **Security Headers:**
+
 - `helmet` (Node.js)
 - `django-csp`
 - OWASP Java Encoder
@@ -1395,7 +1438,7 @@ Sample Endpoints:
   • GET /api/users/:id → UsersController.findOne
   • POST /api/products → ProductsController.create
   • PUT /api/orders/:id → OrdersController.update
-  [View full list in analysis.json]
+  [View full list in docs-analysis.json]
 
 🗄️  Database Entities: [18 detected]
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -1407,7 +1450,7 @@ Core Entities:
   • Order (10 fields, 4 relationships)
     - Relationships: ManyToOne → User, OneToMany → OrderItems, etc.
 
-  [+15 more entities - see analysis.json for full schema]
+  [+15 more entities - see docs-analysis.json for full schema]
 
 🔒 Security Patterns:
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -1492,13 +1535,16 @@ Your choice: __
 ```
 
 **If user selects A:**
+
 - Mark suggestions to be addressed in relevant phases
 - When reaching those phases, reference: "Earlier analysis detected X, let's configure it now"
 
 **If user selects B:**
+
 - Create `suggestions.md` with all recommendations formatted for reference
 
 **If user selects C:**
+
 - Continue without suggestions
 
 ---
@@ -1508,7 +1554,7 @@ Your choice: __
 ```
 💾 Export Analysis to JSON?
 
-This creates .ai-flow/analysis.json with all detected information:
+This creates .ai-flow/cache/docs-analysis.json with all detected information:
 • Project metadata and tech stack
 • Complete endpoint list with methods, paths, handlers
 • Full entity schemas with relationships
@@ -1592,13 +1638,13 @@ Your choice: __
       "source": "prisma",
       "file": "prisma/schema.prisma",
       "fields": [
-        {"name": "id", "type": "String", "required": true, "primary": true},
-        {"name": "email", "type": "String", "required": true, "unique": true},
-        {"name": "password", "type": "String", "required": true}
+        { "name": "id", "type": "String", "required": true, "primary": true },
+        { "name": "email", "type": "String", "required": true, "unique": true },
+        { "name": "password", "type": "String", "required": true }
       ],
       "relationships": [
-        {"type": "OneToMany", "target": "Order", "field": "orders"},
-        {"type": "OneToMany", "target": "Review", "field": "reviews"}
+        { "type": "OneToMany", "target": "Order", "field": "orders" },
+        { "type": "OneToMany", "target": "Review", "field": "reviews" }
       ]
     }
     // ... 17 more
@@ -1638,7 +1684,7 @@ Your choice: __
     "count": 87,
     "paths": [
       "src/users/users.controller.ts",
-      "src/products/products.controller.ts",
+      "src/products/products.controller.ts"
       // ... all analyzed files
     ],
     "timestamps": {
@@ -1651,7 +1697,7 @@ Your choice: __
 ```
 
 ```
-✅ Analysis exported to .ai-flow/analysis.json
+✅ Analysis exported to .ai-flow/cache/docs-analysis.json
 
 File size: 142 KB
 Contains:
@@ -1813,7 +1859,7 @@ Analysis Results:
   ✅ 18 database entities with 45 relationships
   ✅ Security patterns analyzed
   ✅ 7 improvement suggestions generated
-  ✅ Analysis exported to .ai-flow/analysis.json
+  ✅ Analysis exported to .ai-flow/cache/docs-analysis.json
 
 Pre-population Status:
   • 45% of questionnaire answers populated
@@ -1836,7 +1882,5 @@ Press Enter to continue to Project Scope Selection...
 **After Phase 0 completes, ALWAYS proceed to Project Scope Selection before Phase 1.**
 
 ---
-## PHASE 1: Discovery & Business (15-20 min)
-
-
 
+## PHASE 1: Discovery & Business (15-20 min)

package/prompts/backend/flow-build-phase-1.md

@@ -1,4 +1,4 @@
-## PHASE 1: Discovery & Business (15-20 min)
+## PHASE 1: Discovery & Business (15-20 min)
 
 > **Order for this phase:** 1.1 → 1.2 → 1.3 → 1.4 → 1.5 → 1.6 → 1.7 → 1.8 → 1.9 → 1.10
 

package/prompts/backend/flow-build-phase-10.md

@@ -30,7 +30,7 @@ Generate executable User Stories following agile best practices with:
 
 Before executing Phase 10, verify:
 
-- ✅ Phase 9 completed (`roadmap.md` exists)
+- ✅ Phase 9 completed (`docs/roadmap.md` exists)
 - ✅ All Phase 1-8 documentation exists
 - ✅ Roadmap contains Epics, Features, and Tasks
 
@@ -70,6 +70,8 @@ if (!args || args.length === 0) {
       /flow-build fase 10              → Generate all (or Sprint 1)
       /flow-build fase 10 EP-001       → Generate Epic 001 User Stories
       /flow-build fase 10 HU-001-001   → Generate specific User Story
+    
+    Output location: docs/user-stories/
   `);
   exit();
 }
@@ -90,7 +92,7 @@ Mode: [ALL | EPIC: EP-001 | STORY: HU-001-001]
 ```
 Loading project context...
 
-✅ roadmap.md (5 Epics, 18 Features, 89 SP)
+✅ docs/roadmap.md (5 Epics, 18 Features, 89 SP)
 ✅ project-brief.md (business context)
 ✅ ai-instructions.md (tech stack, patterns)
 ✅ docs/data-model.md (entities, relationships)
@@ -100,12 +102,12 @@ Loading project context...
 ✅ docs/testing.md (test strategy)
 ```
 
-**If roadmap.md NOT found:**
+**If docs/roadmap.md NOT found:**
 
 ```
-❌ Error: roadmap.md not found
+❌ Error: docs/roadmap.md not found
 
-Phase 10 requires roadmap.md from Phase 9.
+Phase 10 requires docs/roadmap.md from Phase 9.
 
 Options:
 1. ✅ Generate roadmap first: /flow-build fase 9
@@ -129,7 +131,7 @@ Your choice (1): _
 📋 Scope Selection
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-Found 5 Epics with 18 Features in roadmap.md
+Found 5 Epics with 18 Features in docs/roadmap.md
 
 Total Story Points: 89 SP (~4-5 weeks for 1 dev)
 
@@ -185,7 +187,7 @@ Generating...
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Created:
-📁 user-stories/
+📁 .ai-flow/user-stories/
   ├── EP-001/
   │   ├── HU-001-001.md ✅
   │   ├── HU-001-002.md ✅
@@ -202,7 +204,7 @@ Total: 8 User Stories (34 SP)
 🚀 Ready to start Sprint 1!
 
 Next steps:
-1. Review User Stories in user-stories/ folder
+1. Review User Stories in .ai-flow/user-stories/ folder
 2. Start implementing: /flow-dev-feature HU-001-001
 3. Generate more Epics later: /flow-build fase 10 EP-003
 ```
@@ -216,7 +218,7 @@ Next steps:
 📖 Generating User Stories for EP-001
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-Loading Epic from roadmap.md...
+Loading Epic from docs/roadmap.md...
 
 Epic: EP-001 - Autenticación y Seguridad
 Priority: P0 (Critical)
@@ -246,7 +248,7 @@ Generating...
 ✅ EP-001 User Stories Generated
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-Location: user-stories/EP-001/
+Location: .ai-flow/user-stories/EP-001/
 
 Files created:
 - HU-001-001.md (5 SP, 6 tasks, 8 test cases)
@@ -271,7 +273,7 @@ Next: Start implementing with /flow-dev-feature HU-001-001
 
 Checking if file exists...
 
-⚠️ user-stories/EP-001/HU-001-001.md already exists
+⚠️ .ai-flow/user-stories/EP-001/HU-001-001.md already exists
 
 File size: 4.2 KB
 Last modified: 2025-12-10 15:30
@@ -294,9 +296,9 @@ Your choice (2): _
 
 Backup current file? (Y/n): Y
 
-✅ Backup created: user-stories/EP-001/.backup/HU-001-001.2025-12-12.md
+✅ Backup created: docs/user-stories/EP-001/.backup/HU-001-001.2025-12-12.md
 
-Loading context from roadmap.md...
+Loading context from docs/roadmap.md...
 - Epic: EP-001 Autenticación
 - Feature: 1.1 Login básico (5 SP)
 - Priority: P0
@@ -311,8 +313,8 @@ Changes:
 + Refreshed Definition of Done
 ~ No changes to technical tasks
 
-Location: user-stories/EP-001/HU-001-001.md
-Backup: user-stories/EP-001/.backup/HU-001-001.2025-12-12.md
+Location: .ai-flow/user-stories/EP-001/HU-001-001.md
+Backup: .ai-flow/user-stories/EP-001/.backup/HU-001-001.2025-12-12.md
 
 [If file doesn't exist - New User Story]
 
@@ -322,7 +324,7 @@ Context from roadmap:
 - Epic: EP-001 Autenticación
 - Feature: 1.1 Login básico (5 SP)
 - Priority: P0 (Critical)
-- Tasks: 6 (from roadmap.md)
+- Tasks: 6 (from docs/roadmap.md)
 
 Generating User Story with:
 ✅ User Story format (Como/Quiero/Para)
@@ -335,7 +337,7 @@ Generating User Story with:
 
 ✅ HU-001-001.md created successfully!
 
-Location: user-stories/EP-001/HU-001-001.md
+Location: .ai-flow/user-stories/EP-001/HU-001-001.md
 Size: 4.2 KB
 Tasks: 6
 Test Cases: 8
@@ -398,7 +400,7 @@ EP-{{XXX}}: {{EPIC_NAME}}
 
 ## Tareas Técnicas
 
-> **Source:** Inherited from roadmap.md Feature {{FEATURE_NUMBER}}
+> **Source:** Inherited from docs/roadmap.md Feature {{FEATURE_NUMBER}}
 
 ### Backend
 
@@ -539,24 +541,24 @@ EP-{{XXX}}: {{EPIC_NAME}}
 
 ### Step 10.4: Update Roadmap with Links
 
-**After generating User Stories, update roadmap.md to add links:**
+**After generating User Stories, update docs/roadmap.md to add links:**
 
 ```
-Updating roadmap.md with User Story links...
+Updating docs/roadmap.md with User Story links...
 
 ✅ Updated Feature 1.1 with link to HU-001-001
 ✅ Updated Feature 1.2 with link to HU-001-002
 ✅ Updated Feature 1.3 with link to HU-001-003
 
-roadmap.md updated successfully!
+docs/roadmap.md updated successfully!
 ```
 
-**Updated roadmap.md format:**
+**Updated docs/roadmap.md format:**
 
 ```markdown
 ### Feature 1.1: Login básico • 5 SP (~6-8h)
 
-**User Story:** 📖 [HU-001-001](./user-stories/EP-001/HU-001-001.md)
+**User Story:** 📖 [HU-001-001](./.ai-flow/user-stories/EP-001/HU-001-001.md)
 
 **Status:** ⚪ Not Started
 
@@ -586,7 +588,7 @@ roadmap.md updated successfully!
 
 ### **3. Technical Tasks**
 
-- **Inherit from roadmap:** Use Tasks from roadmap.md Feature
+- **Inherit from roadmap:** Use Tasks from docs/roadmap.md Feature
 - **Add file paths:** Exact location where code goes
 - **Add dependencies:** Which tasks block others
 - **Keep Story Points:** From roadmap estimation
@@ -633,7 +635,7 @@ roadmap.md updated successfully!
 - ❌ Skip acceptance criteria
 - ❌ Generate test cases without criteria
 - ❌ Use generic DoD (personalize per story if needed)
-- ❌ Forget to update roadmap.md with links
+- ❌ Forget to update docs/roadmap.md with links
 
 ### **ALWAYS:**
 
@@ -642,7 +644,7 @@ roadmap.md updated successfully!
 - ✅ Derive 1-2 test cases per scenario
 - ✅ Link back to Epic and Feature
 - ✅ Include technical context from docs
-- ✅ Update roadmap.md with User Story links
+- ✅ Update docs/roadmap.md with User Story links
 - ✅ Create backup before regenerating
 
 ---
@@ -662,18 +664,18 @@ Total Tasks: {{TASKS}}
 Total Test Cases: {{TC}}
 
 Files created:
-📁 user-stories/
+📁 docs/user-stories/
   ├── EP-001/ (5 stories, 13 SP)
   ├── EP-002/ (3 stories, 21 SP)
   └── EP-003/ (4 stories, 18 SP)
 
 Updated:
-✅ roadmap.md (added User Story links)
+✅ docs/roadmap.md (added User Story links)
 
 🚀 Ready to start development!
 
 Next steps:
-1. Review User Stories in user-stories/ folder
+1. Review User Stories in docs/user-stories/ folder
 2. Start implementing: /flow-dev-feature HU-001-001
 3. Track progress: /flow-dev-work
 4. Generate more stories: /flow-build fase 10 EP-004

package/prompts/backend/flow-build-phase-7.md

@@ -1042,7 +1042,7 @@ When executing this master prompt:
   - [ ] Present suggestions with actions and impacts
 - [ ] **Offer export option (0.3):**
   - [ ] Ask if user wants to export analysis to JSON
-  - [ ] If yes, create .ai-flow/analysis.json with complete analysis
+  - [ ] If yes, create .ai-flow/cache/docs-analysis.json with complete analysis
 - [ ] Let user choose: A) Use detected info, B) Start fresh, C) Review/edit detected info
 - [ ] **Handle suggestions:**
   - [ ] If user selected A (address during build), integrate suggestions into relevant phases

package/prompts/backend/flow-build-phase-9.md

@@ -788,14 +788,14 @@ With 3 developers: ~9 weeks (47% time savings)
 
 ### Step 9.5: Generate Roadmap Document (2-5 minutes - automatic)
 
-**Generate `roadmap.md` with complete implementation plan:**
+**Generate `docs/roadmap.md` with complete implementation plan:**
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 📝 Step 9.5/6: Generating Roadmap Document
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-Writing to roadmap.md...
+Writing to docs/roadmap.md...
 ```
 
 **Roadmap Document Structure:**
@@ -1159,7 +1159,7 @@ Update this roadmap as you complete features:
 
 ```
 ✅ Roadmap document generated
-✅ Location: roadmap.md
+✅ Location: docs/roadmap.md
 ✅ Total: {{TOTAL_EPICS}} Epics, {{TOTAL_FEATURES}} Features, {{TOTAL_TASKS}} Tasks
 ✅ Estimated: {{TOTAL_SP}} Story Points (~{{TOTAL_WEEKS}} weeks)
 ```
@@ -1184,7 +1184,7 @@ Update this roadmap as you complete features:
 ✅ Estimated time: {{SOLO_WEEKS}} weeks (1 dev) | {{TWO_DEV_WEEKS}} weeks (2 devs)
 ✅ Dependency graph: Generated
 ✅ Execution order: Optimized for parallelization
-✅ Roadmap document: roadmap.md
+✅ Roadmap document: docs/roadmap.md
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 🎯 What This Roadmap Guarantees
@@ -1213,14 +1213,14 @@ Update this roadmap as you complete features:
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 1. **Open the roadmap**
-   └─ Open roadmap.md in your editor
+   └─ Open docs/roadmap.md in your editor
 
 2. **Review and adjust priorities**
    └─ Decide which features are MVP vs future phases
    └─ Adjust P0/P1/P2/P3 priorities if needed
 
 3. **Commit the roadmap**
-   └─ git add roadmap.md
+   └─ git add docs/roadmap.md
    └─ git commit -m "docs: add implementation roadmap with Story Points"
 
 4. **Start implementation**
@@ -1258,7 +1258,7 @@ Update this roadmap as you complete features:
 
 Ready to start building? 🚀
 
-Open roadmap.md and let's ship this! 💪
+Open docs/roadmap.md and let's ship this! 💪
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
@@ -1276,10 +1276,10 @@ B) ✅ Start implementing from roadmap directly
    → Will execute: /flow-dev-feature {{FIRST_FEATURE_ID}}
 
 C) 📋 Review roadmap first
-   → Will open roadmap.md
+   → Will open docs/roadmap.md
 
 D) ✏️ Customize roadmap
-   → Will open roadmap.md for editing
+   → Will open docs/roadmap.md for editing
 
 Your choice (A/B/C/D): __
 ```
@@ -1396,7 +1396,7 @@ Please fix documentation and re-run Phase 9
 
 **9.5 Generate Roadmap Document:**
 
-- [ ] Create `roadmap.md`
+- [ ] Create `docs/roadmap.md`
 - [ ] Include project overview
 - [ ] Include Story Points reference table
 - [ ] Include Epic overview table

package/prompts/backend/flow-build.md

@@ -587,7 +587,7 @@ Read .ai-flow/prompts/backend/flow-build-phase-4-security.md and execute only Ph
 
 **Generates:**
 
-- `.ai-flow/roadmap.md` (complete implementation plan)
+- `docs/roadmap.md` (complete implementation plan)
 
 **Output includes:**
 
@@ -733,12 +733,12 @@ As your project evolves, your documentation may become out of sync with your cod
 
 **How it works:**
 
-1. Compares current code state with last documented state (`.ai-flow/analysis.json`)
+1. Compares current code state with last documented state (`.ai-flow/cache/docs-analysis.json`)
 2. Detects changes in endpoints, entities, dependencies, architecture, configuration
 3. Shows report of documents that need updating
 4. Asks for confirmation to update all detected documents
 5. Updates documents incrementally (only changed sections)
-6. Updates `analysis.json` with new state
+6. Updates `docs-analysis.json` with new state
 
 **When to use:**
 

package/prompts/backend/flow-dev-feature.md

@@ -60,15 +60,15 @@ const input = getArguments(); // From /feature [args]
 if (input.match(/^HU-\d{3}-\d{3}$/)) {
   mode = 'USER_STORY';
   storyId = input; // e.g., HU-001-001
-  // Load from user-stories/EP-XXX/HU-XXX-XXX.md
-} else if (fs.existsSync('roadmap.md')) {
-  // Search for Feature in roadmap.md matching input
-  const roadmapContent = readFile('roadmap.md');
+  // Load from docs/user-stories/EP-XXX/HU-XXX-XXX.md
+} else if (fs.existsSync('docs/roadmap.md')) {
+  // Search for Feature in docs/roadmap.md matching input
+  const roadmapContent = readFile('docs/roadmap.md');
   const featureMatch = roadmapContent.match(new RegExp(`### Feature.*${input}.*• (\d+) SP`));
   if (featureMatch) {
     mode = 'ROADMAP_FEATURE';
     featureName = input;
-    // Extract tasks from roadmap.md
+    // Extract tasks from docs/roadmap.md
   } else {
     mode = 'INTERACTIVE'; // Fallback to manual questions
   }
@@ -79,11 +79,11 @@ if (input.match(/^HU-\d{3}-\d{3}$/)) {
 
 **Mode behavior:**
 
-| Mode              | Source                              | Skip Phase 1             |
-| ----------------- | ----------------------------------- | ------------------------ |
-| `USER_STORY`      | `user-stories/EP-XXX/HU-XXX-XXX.md` | ✅ Yes (auto-load spec)  |
-| `ROADMAP_FEATURE` | `roadmap.md` Feature section        | ✅ Yes (auto-load tasks) |
-| `INTERACTIVE`     | Manual questions                    | ❌ No (ask user)         |
+| Mode              | Source                                   | Skip Phase 1             |
+| ----------------- | ---------------------------------------- | ------------------------ |
+| `USER_STORY`      | `docs/user-stories/EP-XXX/HU-XXX-XXX.md` | ✅ Yes (auto-load spec)  |
+| `ROADMAP_FEATURE` | `docs/roadmap.md` Feature section        | ✅ Yes (auto-load tasks) |
+| `INTERACTIVE`     | Manual questions                         | ❌ No (ask user)         |
 
 ---
 
@@ -98,7 +98,7 @@ if (input.match(/^HU-\d{3}-\d{3}$/)) {
 
 📖 Loading User Story: HU-001-001
 
-Source: user-stories/EP-001/HU-001-001.md
+Source: .ai-flow/user-stories/EP-001/HU-001-001.md
 
 ✅ Title: Login básico con email y contraseña
 ✅ Priority: Alta (P0)
@@ -118,7 +118,7 @@ Skipping manual questions (spec already defined)...
 🚀 Feature Workflow  |  Phase 1/4: Specification (AUTO-LOADED)
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-🗺️ Loading Feature from roadmap.md: User Entity & Repository
+🗺️ Loading Feature from docs/roadmap.md: User Entity & Repository
 
 ✅ Epic: 2 - Data Layer
 ✅ Priority: P0
@@ -144,10 +144,10 @@ Ask 3-5 key questions to understand requirements:
 
 **IF loaded from User Story (HU-XXX-XXX):**
 
-- Copy `user-stories/EP-XXX/HU-XXX-XXX.md` → `.ai-flow/work/NNN-HU-XXX-XXX/spec.md`
+- Copy `docs/user-stories/EP-XXX/HU-XXX-XXX.md` → `.ai-flow/work/NNN-HU-XXX-XXX/spec.md`
 - Include: User Story format, Acceptance Criteria (Gherkin), Technical Tasks, Test Cases, DoD
 
-**IF loaded from roadmap.md Feature:**
+**IF loaded from docs/roadmap.md Feature:**
 
 - Extract Feature section → `.ai-flow/work/NNN-feature-name/spec.md`
 - Include: Scope, Tasks (T001-T00N), Dependencies, Ready-to-execute command
@@ -1417,7 +1417,7 @@ Dependencies resolved:
 ✅ Blocks: HU-002-001 (User CRUD) - Ready to start
 
 📖 User Story Status: COMPLETED ✅
-   File: user-stories/EP-001/HU-001-001.md updated with completion date
+   File: .ai-flow/user-stories/EP-001/HU-001-001.md updated with completion date
 ```
 
 **IF mode = `ROADMAP_FEATURE` or `INTERACTIVE`:**

package/prompts/backend/flow-docs-sync.md

@@ -10,7 +10,7 @@ Your mission is to detect changes in the codebase and update the project documen
 
 ### Objective
 
-Detect changes in the codebase compared to the last documented state (stored in `.ai-flow/analysis.json`) and update all affected documentation files automatically.
+Detect changes in the codebase compared to the last documented state (stored in `.ai-flow/cache/docs-analysis.json`) and update all affected documentation files automatically.
 
 ---
 
@@ -19,12 +19,12 @@ Detect changes in the codebase compared to the last documented state (stored in
 ### Step 1: Check for Analysis File
 
 ```
-First, check if `.ai-flow/analysis.json` exists:
+First, check if `.ai-flow/cache/docs-analysis.json` exists:
 
 - ✅ If exists → Proceed to Step 2 (Compare Changes)
 - ❌ If NOT exists → Execute full Phase 0 analysis first:
   - Run complete code analysis (as described in Phase 0)
-  - Create `.ai-flow/analysis.json` with current state
+  - Create `.ai-flow/cache/docs-analysis.json` with current state
   - Then proceed to Step 2
 ```
 
@@ -33,7 +33,6 @@ First, check if `.ai-flow/analysis.json` exists:
 **Reuse Phase 0 Analysis Logic:**
 
 1. **Perform Current Code Analysis:**
-
    - Execute the same analysis as Phase 0 (section 0.1):
      - File structure analysis
      - AST-based code parsing (endpoints, entities, dependencies)
@@ -42,8 +41,7 @@ First, check if `.ai-flow/analysis.json` exists:
    - Generate current state snapshot
 
 2. **Compare with Previous State:**
-
-   - Load `.ai-flow/analysis.json`
+   - Load `.ai-flow/cache/docs-analysis.json`
    - Compare current state vs previous state
    - Detect changes in:
      - **Endpoints:** New, modified, or deleted endpoints
@@ -96,6 +94,7 @@ When regenerating or updating diagrams in documentation files, follow these **cr
 **Diagram Type:** `erDiagram`
 
 **Requirements:**
+
 1. Show ALL entities and their relationships
 2. Include field types and constraints (PK, FK, UK)
 3. Add descriptions for complex or business-critical fields
@@ -103,6 +102,7 @@ When regenerating or updating diagrams in documentation files, follow these **cr
 5. Keep entity order logical (core entities first, then related)
 
 **Quality Checklist:**
+
 - [ ] Code fence is exactly ` ```mermaid ` (lowercase, no spaces)
 - [ ] All entities from database are represented
 - [ ] All foreign key relationships are shown
@@ -113,6 +113,7 @@ When regenerating or updating diagrams in documentation files, follow these **cr
 - [ ] Diagram renders without errors
 
 **Example:**
+
 ````markdown
 ```mermaid
 erDiagram
@@ -156,6 +157,7 @@ erDiagram
 **Diagram Type:** `graph TD` (or `graph LR`)
 
 **Requirements:**
+
 1. Show ALL major system components (services, databases, caches, queues)
 2. Label connections with protocols/methods (HTTPS, gRPC, REST, etc.)
 3. Use consistent styling (databases as cylinders, services as boxes)
@@ -164,6 +166,7 @@ erDiagram
 6. Include deployment context (load balancers, CDN) if relevant
 
 **Quality Checklist:**
+
 - [ ] Code fence is exactly ` ```mermaid ` (lowercase, no spaces)
 - [ ] All services/components from codebase are shown
 - [ ] Database connections are labeled
@@ -175,6 +178,7 @@ erDiagram
 - [ ] Diagram renders without errors
 
 **Example:**
+
 ````markdown
 ```mermaid
 graph TD
@@ -203,6 +207,7 @@ graph TD
 **Diagram Type:** `flowchart TD` (or `flowchart LR`)
 
 **Requirements:**
+
 1. Start with `([Start Terminal])`
 2. End with `([End Terminal])`
 3. Use `{Diamond}` for ALL decision points
@@ -212,6 +217,7 @@ graph TD
 7. Use consistent styling for node types
 
 **Quality Checklist:**
+
 - [ ] Code fence is exactly ` ```mermaid ` (lowercase, no spaces)
 - [ ] Flow starts with a terminal node
 - [ ] Flow ends with terminal node(s)
@@ -224,6 +230,7 @@ graph TD
 - [ ] Diagram renders without errors
 
 **Example:**
+
 ````markdown
 ```mermaid
 flowchart TD
@@ -250,19 +257,22 @@ flowchart TD
 ### Common Formatting Rules (ALL Diagrams)
 
 **CRITICAL - Code Fence Syntax:**
-```
+
+````
 ✅ CORRECT: ```mermaid
 ❌ WRONG:   ```Mermaid (capital M)
 ❌ WRONG:   ``` mermaid (extra space)
 ❌ WRONG:   ``mermaid (missing backtick)
-```
+````
 
 **Indentation:**
+
 - Start Mermaid syntax at column 0 (no leading spaces/tabs)
 - Only indent within Mermaid syntax according to Mermaid rules
 - Do NOT indent the entire code block
 
 **Validation Steps:**
+
 1. After generating/updating diagram, verify syntax at https://mermaid.live/
 2. Check that diagram renders in VS Code markdown preview
 3. Verify all nodes and relationships are present
@@ -270,6 +280,7 @@ flowchart TD
 5. Test that styling is applied correctly
 
 **When Updating Existing Diagrams:**
+
 1. Read the current diagram first
 2. Identify what needs to be added/removed/modified
 3. Maintain existing styling and layout patterns
@@ -286,7 +297,6 @@ flowchart TD
 1. **For each document that needs updating:**
 
    **A) `docs/api.md`** (if endpoints changed):
-
    - Read current `docs/api.md`
    - Identify new/modified endpoints from analysis
    - Add new endpoints following existing API conventions
@@ -296,7 +306,6 @@ flowchart TD
    - Regenerate affected sections only
 
    **B) `docs/data-model.md`** (if entities changed):
-
    - Read current `docs/data-model.md`
    - Update entity definitions with new fields
    - Update relationships if changed
@@ -304,41 +313,35 @@ flowchart TD
    - Maintain all existing content that hasn't changed
 
    **C) `ai-instructions.md`** (if dependencies changed):
-
    - Read current `ai-instructions.md`
    - Add new dependencies to appropriate sections
    - Update version numbers if changed
    - Maintain all existing rules and patterns
 
    **D) `docs/architecture.md`** (if architecture changed):
-
    - Read current `docs/architecture.md`
    - Update architecture diagram (mermaid) if structure changed
    - Update module descriptions
    - Maintain all existing content
 
    **E) `specs/configuration.md`** (if env vars changed):
-
    - Read current `specs/configuration.md`
    - Add new environment variables
    - Update descriptions if changed
    - Maintain existing variables
 
    **F) `.env.example`** (if env vars changed):
-
    - Read current `.env.example`
    - Add new environment variables with example values
    - Maintain existing variables
 
    **G) `specs/security.md`** (if security patterns changed):
-
    - Read current `specs/security.md`
    - Update security policies if authentication/authorization changed
    - Maintain existing policies
 
-2. **Update `analysis.json`:**
-
-   - Save current state to `.ai-flow/analysis.json`
+2. **Update `docs-analysis.json`:**
+   - Save current state to `.ai-flow/cache/docs-analysis.json`
    - Update timestamp
    - Include all detected changes in metadata
 
@@ -359,7 +362,7 @@ flowchart TD
 - Agregada dependencia "@nestjs/swagger"
 - Actualizada sección de herramientas
 
-✅ analysis.json actualizado con nuevo estado
+✅ docs-analysis.json actualizado con nuevo estado
 ```
 
 ### Step 5: Handle Cancellation
@@ -456,32 +459,28 @@ Actualización cancelada. Ejecuta `/flow-docs-sync` cuando estés listo para act
 ## Important Rules
 
 1. **Incremental Updates Only:**
-
    - Only modify sections that changed
    - Preserve all existing content that hasn't changed
    - Maintain document structure and formatting
 
 2. **Follow Existing Patterns:**
-
    - Use same format as existing documentation
    - Follow conventions established in original build
    - Maintain consistency with existing docs
 
 3. **Update Analysis File:**
-
-   - Always update `.ai-flow/analysis.json` after document updates
+   - Always update `.ai-flow/cache/docs-analysis.json` after document updates
    - Include timestamp and change summary
    - Save complete current state for next comparison
 
 4. **Mermaid Diagrams:**
-
    - Regenerate ER diagrams when entities change
    - Regenerate architecture diagrams when structure changes
    - Use mermaid format for all diagrams
 
 5. **Error Handling:**
    - If document doesn't exist, create it following template
-   - If analysis.json is corrupted, regenerate it
+   - If docs-analysis.json is corrupted, regenerate it
    - If comparison fails, show error and suggest full Phase 0 re-run
 
 ---
@@ -515,7 +514,7 @@ AI:
 - Agregado campo "avatarUrl" (String, nullable) a entidad User
 - Actualizado diagrama ER (mermaid) con nuevo campo
 
-✅ analysis.json actualizado con nuevo estado
+✅ docs-analysis.json actualizado con nuevo estado
 
 Documentación sincronizada exitosamente.
 ```
@@ -523,5 +522,3 @@ Documentación sincronizada exitosamente.
 ---
 
 **BEGIN EXECUTION when user runs `/flow-docs-sync`**
-
-

package/prompts/frontend/flow-docs-sync.md

@@ -10,7 +10,7 @@ Your mission is to detect changes in the frontend codebase and update the projec
 
 ### Objective
 
-Detect changes in the frontend codebase compared to the last documented state (stored in `.ai-flow/analysis.json`) and update all affected documentation files automatically.
+Detect changes in the frontend codebase compared to the last documented state (stored in `.ai-flow/cache/docs-analysis.json`) and update all affected documentation files automatically.
 
 ---
 
@@ -19,12 +19,12 @@ Detect changes in the frontend codebase compared to the last documented state (s
 ### Step 1: Check for Analysis File
 
 ```
-First, check if `.ai-flow/analysis.json` exists:
+First, check if `.ai-flow/cache/docs-analysis.json` exists:
 
 - ✅ If exists → Proceed to Step 2 (Compare Changes)
 - ❌ If NOT exists → Execute full Phase 0 analysis first:
   - Run complete frontend code analysis (as described in Phase 0)
-  - Create `.ai-flow/analysis.json` with current state
+  - Create `.ai-flow/cache/docs-analysis.json` with current state
   - Then proceed to Step 2
 ```
 
@@ -45,7 +45,7 @@ First, check if `.ai-flow/analysis.json` exists:
 
 2. **Compare with Previous State:**
 
-   - Load `.ai-flow/analysis.json`
+   - Load `.ai-flow/cache/docs-analysis.json`
    - Compare current state vs previous state
    - Detect changes in:
      - **Components:** New, modified, or deleted components
@@ -149,9 +149,9 @@ No updates required.
    - Add new test examples if patterns changed
    - Maintain existing testing strategy
 
-2. **Update `analysis.json`:**
+2. **Update `docs-analysis.json`:**
 
-   - Save current state to `.ai-flow/analysis.json`
+   - Save current state to `.ai-flow/cache/docs-analysis.json`
    - Update timestamp
    - Include all detected changes in metadata
 
@@ -176,7 +176,7 @@ No updates required.
 - Added dependency "@tanstack/react-query"
 - Updated tools section
 
-✅ analysis.json updated with new state
+✅ docs-analysis.json updated with new state
 ```
 
 ### Step 5: Handle Cancellation
@@ -299,7 +299,7 @@ Update cancelled. Run `/flow-docs-sync` when you're ready to update the document
 
 3. **Update Analysis File:**
 
-   - Always update `.ai-flow/analysis.json` after document updates
+   - Always update `.ai-flow/cache/docs-analysis.json` after document updates
    - Include timestamp and change summary
    - Save complete current state for next comparison
 
@@ -515,7 +515,7 @@ graph TB
 
 5. **Error Handling:**
    - If document doesn't exist, create it following template
-   - If analysis.json is corrupted, regenerate it
+   - If docs-analysis.json is corrupted, regenerate it
    - If comparison fails, show error and suggest full Phase 0 re-run
 
 ---
@@ -549,7 +549,7 @@ AI:
 - Added new Zustand store (useCartStore)
 - Updated state management patterns section
 
-✅ analysis.json updated with new state
+✅ docs-analysis.json updated with new state
 
 Documentation synchronized successfully.
 ```

package/prompts/mobile/flow-docs-sync.md

@@ -10,7 +10,7 @@ Your mission is to detect changes in the mobile codebase and update the project
 
 ### Objective
 
-Detect changes in the mobile codebase compared to the last documented state (stored in `.ai-flow/analysis.json`) and update all affected documentation files automatically.
+Detect changes in the mobile codebase compared to the last documented state (stored in `.ai-flow/cache/docs-analysis.json`) and update all affected documentation files automatically.
 
 ---
 
@@ -19,12 +19,12 @@ Detect changes in the mobile codebase compared to the last documented state (sto
 ### Step 1: Check for Analysis File
 
 ```
-First, check if `.ai-flow/analysis.json` exists:
+First, check if `.ai-flow/cache/docs-analysis.json` exists:
 
 - ✅ If exists → Proceed to Step 2 (Compare Changes)
 - ❌ If NOT exists → Execute full Phase 0 analysis first:
   - Run complete mobile code analysis (as described in Phase 0)
-  - Create `.ai-flow/analysis.json` with current state
+  - Create `.ai-flow/cache/docs-analysis.json` with current state
   - Then proceed to Step 2
 ```
 
@@ -47,7 +47,7 @@ First, check if `.ai-flow/analysis.json` exists:
 
 2. **Compare with Previous State:**
 
-   - Load `.ai-flow/analysis.json`
+   - Load `.ai-flow/cache/docs-analysis.json`
    - Compare current state vs previous state
    - Detect changes in:
      - **Screens:** New, modified, or deleted screens
@@ -173,9 +173,9 @@ No updates required.
    - Update app store configuration if app.json or build config changed
    - Maintain existing configuration
 
-2. **Update `analysis.json`:**
+2. **Update `docs-analysis.json`:**
 
-   - Save current state to `.ai-flow/analysis.json`
+   - Save current state to `.ai-flow/cache/docs-analysis.json`
    - Update timestamp
    - Include all detected changes in metadata
 
@@ -208,7 +208,7 @@ No updates required.
 📝 specs/build-configuration.md
 - Updated build.gradle configuration
 
-✅ analysis.json updated with new state
+✅ docs-analysis.json updated with new state
 ```
 
 ### Step 5: Handle Cancellation
@@ -360,7 +360,7 @@ Update cancelled. Run `/flow-docs-sync` when you're ready to update the document
 
 3. **Update Analysis File:**
 
-   - Always update `.ai-flow/analysis.json` after document updates
+   - Always update `.ai-flow/cache/docs-analysis.json` after document updates
    - Include timestamp and change summary
    - Save complete current state for next comparison
 
@@ -588,7 +588,7 @@ graph TB
 
 5. **Error Handling:**
    - If document doesn't exist, create it following template
-   - If analysis.json is corrupted, regenerate it
+   - If docs-analysis.json is corrupted, regenerate it
    - If comparison fails, show error and suggest full Phase 0 re-run
 
 ---
@@ -622,7 +622,7 @@ AI:
 - Added new permission (Location)
 - Updated permission handling section
 
-✅ analysis.json updated with new state
+✅ docs-analysis.json updated with new state
 
 Documentation synchronized successfully.
 ```