documentation and agent nav files

CLAUDE.md

@@ -0,0 +1,36 @@
+# CLAUDE.md
+
+Concise guidance for Claude Code in this repository.
+
+## Canonical agent entry
+
+Start with `docs/index.md` and load only task-relevant docs it references.
+
+## Quick commands
+
+```bash
+pnpm install
+pnpm run dev
+pnpm run build
+pnpm run preview
+pnpm test
+pnpm test:watch
+```
+
+## Non-negotiables
+
+- Use `pnpm` only.
+- Do not `git commit` or `git push`. Ask before staging with `git add`.
+- Prefer existing files; do not create new docs unless explicitly requested.
+- Use `mgrep` for code search.
+
+## Environment
+
+Set `GEMINI_API_KEY` in `.env.local`.
+
+## Pointers
+
+- Entry flow: `index.html` → `index.tsx` → `App.tsx`
+- Routes: `pages/`
+- Shared UI: `components/`
+- Types: `types.ts`

README.md

@@ -8,13 +8,17 @@ This contains everything you need to run your app locally.
 
 View your app in AI Studio: https://ai.studio/apps/drive/1XC-Q0YPDamuw1PItnxd0vSYWMNqnQjCX
 
+## Agent navigation
+
+For AI agents, start with the canonical entry point at `docs/index.md`, then include any task-specific docs it references.
+
 ## Run Locally
 
 **Prerequisites:**  Node.js
 
 
 1. Install dependencies:
-   `npm install`
+   `pnpm install`
 2. Set the `GEMINI_API_KEY` in [.env.local](.env.local) to your Gemini API key
 3. Run the app:
-   `npm run dev`
+   `pnpm run dev`

_bmad-output/planning-artifacts/bmm-workflow-status.yaml

@@ -0,0 +1,101 @@
+# Workflow Status Template
+
+# This tracks progress through BMM methodology Analysis, Planning, and Solutioning phases.
+# Implementation phase is tracked separately in sprint-status.yaml
+
+# STATUS DEFINITIONS:
+# ==================
+# Initial Status (before completion):
+#   - required: Must be completed to progress
+#   - optional: Can be completed but not required
+#   - recommended: Strongly suggested but not required
+#   - conditional: Required only if certain conditions met (e.g., if_has_ui)
+#
+# Completion Status:
+#   - {file-path}: File created/found (e.g., "docs/product-brief.md")
+#   - skipped: Optional/conditional workflow that was skipped
+
+generated: "2026-01-12"
+project: "prototype"
+project_type: "software"
+selected_track: "method"
+field_type: "brownfield"
+workflow_path: "_bmad/bmm/workflows/workflow-status/paths/method-brownfield.yaml"
+
+workflow_status:
+  phase_0_documentation:
+    name: "Documentation"
+    note: "Prerequisite for brownfield without docs"
+    workflows:
+      document-project:
+        status: docs/index.md
+        agent: analyst
+        command: /bmad:bmm:workflows:document-project
+        purpose: "Understand existing codebase before planning"
+        completed: 2026-01-12
+
+  phase_1_analysis:
+    name: "Analysis (Optional)"
+    note: "User-selected discovery workflows"
+    workflows:
+      brainstorm-project:
+        status: optional
+        agent: analyst
+        command: /bmad:core:workflows:brainstorming
+        note: "Creative exploration and ideation"
+      research:
+        status: skipped
+        agent: analyst
+        command: /bmad:bmm:workflows:research
+      product-brief:
+        status: skipped
+        agent: analyst
+        command: /bmad:bmm:workflows:create-product-brief
+
+  phase_2_planning:
+    name: "Planning"
+    workflows:
+      prd:
+        status: required
+        agent: pm
+        command: /bmad:bmm:workflows:prd
+        output: "Product Requirements Document with FRs and NFRs"
+      create-ux-design:
+        status: conditional
+        condition: if_has_ui
+        agent: ux-designer
+        command: /bmad:bmm:workflows:create-ux-design
+        note: "Determined after PRD - user/agent decides if needed"
+
+  phase_3_solutioning:
+    name: "Solutioning"
+    workflows:
+      create-architecture:
+        status: required
+        agent: architect
+        command: /bmad:bmm:workflows:create-architecture
+        output: "System architecture document"
+      create-epics-and-stories:
+        status: required
+        agent: pm
+        command: /bmad:bmm:workflows:create-epics-and-stories
+        note: "Break down PRD into implementable epics and stories"
+      test-design:
+        status: optional
+        agent: tea
+        command: /bmad:bmm:workflows:testarch-test-design
+        output: "System-level testability review"
+      implementation-readiness:
+        status: required
+        agent: architect
+        command: /bmad:bmm:workflows:check-implementation-readiness
+        note: "Validates PRD + Architecture + Epics + UX (if applicable)"
+
+  phase_4_implementation:
+    name: "Implementation"
+    workflows:
+      sprint-planning:
+        status: required
+        agent: sm
+        command: /bmad:bmm:workflows:sprint-planning
+        note: "Creates sprint plan - subsequent work tracked in sprint-status.yaml"

docs/api-architecture.md

@@ -0,0 +1,170 @@
+# API Architecture & State Management
+
+**Project:** Ocobo Revenue Operations Agency
+**Type:** Web Application (React + TypeScript)
+**Generated:** 2026-01-12
+**Scan Level:** Quick (pattern-based)
+
+## Overview
+
+This document describes the API integration points and state management approach identified in the project.
+
+## External API Integration
+
+### Google Gemini API
+- **Provider:** Google AI
+- **Purpose:** AI-powered features integration
+- **Configuration:**
+  - Environment Variable: `GEMINI_API_KEY`
+  - Configured in: `vite.config.ts`
+  - Exposed as: `process.env.GEMINI_API_KEY` and `process.env.API_KEY`
+
+**Configuration Code:**
+```typescript
+define: {
+  'process.env.API_KEY': JSON.stringify(env.GEMINI_API_KEY),
+  'process.env.GEMINI_API_KEY': JSON.stringify(env.GEMINI_API_KEY)
+}
+```
+
+### API Client Patterns
+
+Based on the project structure and modern React practices:
+
+**Likely API Integration Patterns:**
+- Client-side API calls from React components
+- TypeScript interfaces for API responses (defined in `types.ts`)
+- Environment-based configuration for API endpoints
+
+## State Management
+
+### Approach
+Based on React 19.2.3 and project structure, the application likely uses:
+
+**React Built-in State Management:**
+- `useState` for local component state
+- `useContext` for shared state across components
+- React 19 features for modern state handling
+
+### State Patterns Identified
+
+**Component-Level State:**
+- Form inputs (Contact, Newsletter)
+- UI state (modals, navigation)
+- Local component data
+
+**Application-Level State:**
+- Navigation state
+- Theme configuration
+- User preferences
+
+## Data Flow Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│              User Interface Layer                │
+│  (React Components + TypeScript)                │
+└─────────────────┬───────────────────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────────────────┐
+│           State Management Layer                 │
+│  (React Hooks: useState, useContext)            │
+└─────────────────┬───────────────────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────────────────┐
+│              API Integration Layer               │
+│  (Google Gemini API)                            │
+└─────────────────────────────────────────────────┘
+```
+
+## API Call Patterns
+
+### Expected Patterns
+
+**1. Fetch API Usage**
+Modern React applications typically use the Fetch API for HTTP requests:
+```typescript
+const response = await fetch(endpoint, options);
+const data = await response.json();
+```
+
+**2. Async/Await Pattern**
+TypeScript with modern async handling for API calls
+
+**3. Error Handling**
+Try-catch blocks for API error management
+
+## Configuration Management
+
+### Environment Variables
+- **File:** `.env.local`
+- **Purpose:** Store API keys and configuration
+- **Variables:**
+  - `GEMINI_API_KEY` - Google Gemini API authentication
+
+### Build-Time Configuration
+- **Tool:** Vite
+- **Config File:** `vite.config.ts`
+- **Features:**
+  - Environment variable injection
+  - API key exposure to runtime
+  - Development server configuration (port 3000)
+
+## Security Considerations
+
+### API Key Management
+- ✓ API keys stored in `.env.local` (not in source control)
+- ✓ Keys injected at build time via Vite config
+- ⚠️ Client-side API key exposure (typical for client-side apps)
+
+### Recommendations
+- Consider implementing API proxy for sensitive operations
+- Rotate API keys regularly
+- Implement rate limiting if needed
+- Monitor API usage
+
+## Integration Points
+
+### Identified Integration Patterns
+
+1. **AI Features (Gemini API)**
+   - Purpose: AI-powered functionality
+   - Type: External REST API
+   - Authentication: API Key
+
+2. **Font Loading**
+   - Source: `https://www.ocobo.co/fonts/`
+   - Custom fonts: Bermia, Bornia
+
+3. **CDN Resources**
+   - Tailwind CSS: `https://cdn.tailwindcss.com`
+   - Google Fonts: Inter font family
+
+## State Persistence
+
+### Browser Storage Patterns
+Likely usage patterns (common in SPA):
+- LocalStorage for user preferences
+- SessionStorage for temporary data
+- Cookies for authentication (if implemented)
+
+## Notes
+
+- This is a quick scan analysis based on configuration and patterns
+- For detailed API endpoint mappings, perform a deep scan
+- For complete state management flow, analyze component implementations
+- Current architecture supports modern React patterns and external AI integration
+
+## Recommendations for Deep Scan
+
+When performing a deep scan, analyze:
+1. Actual API endpoints being called
+2. Request/response data structures
+3. Error handling implementations
+4. State management library usage (Context, Redux, Zustand)
+5. API caching strategies
+6. Loading and error states
+7. API response type definitions
+8. Authentication flows (if implemented)