sinapse-ai 9.3.0 → 9.5.0

package/.sinapse-ai/development/knowledge-base/software-architecture-patterns.md

@@ -0,0 +1,299 @@
+# Software Architecture Patterns
+
+> **Agente(s):** @architect (Stratum), @developer (Pixel)
+> **Fonte:** fullstack-engineering-animations.md (DEFINITIVE research)
+> **Complementa:** `infrastructure-decision-framework.md` (infra) -- este documento foca em SOFTWARE architecture
+> **Uso:** Consultar ao iniciar projetos novos, escolher patterns, ou avaliar arquitetura existente
+
+---
+
+## 1. Architecture Decision Tree
+
+### By Project Type
+
+| Tipo de Projeto | Arquitetura | State Mgmt | Rendering | DB Pattern |
+|----------------|-------------|-----------|-----------|------------|
+| Landing Page | JAMstack (SSG + Edge) | nuqs (URL) | SSG/ISR | N/A ou Supabase Free |
+| Blog/Content | JAMstack (SSG + ISR) | TanStack Query | SSG + ISR | Supabase + MDX |
+| SaaS B2B | Modular Monolith + Clean Architecture | TanStack Query + Zustand | SSR + Streaming | Multi-tenant shared table |
+| E-commerce | Modular Monolith + CQRS | TanStack Query + Zustand | ISR + SSR | CQRS read models |
+| Fintech | Modular Monolith + DDD + Event Sourcing | TanStack Query + Zustand | SSR | Append-only + audit log |
+| Marketplace | Modular Monolith (evolving) | TanStack Query + Zustand | ISR + SSR | Schema-per-module |
+| Real-time App | Event-Driven + WebSockets | Zustand + Supabase Realtime | SSR + Client | Realtime subscriptions |
+
+### By Team Size
+
+```
+Projeto novo?
+  |
+  +-- Equipe <= 5 devs?
+  |     +-- SIM --> Monolith (com boa estrutura de pastas)
+  |     +-- NAO --> Modular Monolith
+  |
+  +-- Equipe > 10 devs?
+  |     +-- Times independentes com dominios distintos?
+  |           +-- SIM --> Microservices (seletivo)
+  |           +-- NAO --> Modular Monolith
+  |
+  +-- Necessidade de scaling independente comprovada?
+        +-- SIM --> Extrair modulo especifico para microservice
+        +-- NAO --> Manter no Modular Monolith
+```
+
+**Default for SINAPSE projects:** Modular Monolith. Microservices only with proven need.
+
+---
+
+## 2. Architecture Patterns Decision Matrix
+
+| Criterio | Clean Architecture | DDD | Hexagonal | Serverless | JAMstack |
+|----------|-------------------|-----|-----------|------------|----------|
+| **Complexidade de dominio** | Media-Alta | Alta | Media-Alta | Baixa | Baixa |
+| **Team size minimo** | 2+ | 3+ | 2+ | 1+ | 1+ |
+| **Learning curve** | Media | Alta | Media | Baixa | Baixa |
+| **Testabilidade** | Excelente | Excelente | Excelente | Boa | Boa |
+| **Melhor para** | SaaS, enterprise | Dominio complexo | Ports swappable | APIs, event-driven | Content, marketing |
+| **Evitar quando** | CRUDs simples | Dominio trivial | Equipe junior | Long-running jobs | Apps interativas |
+| **Custo de manter** | Medio | Alto | Medio | Baixo | Baixo |
+
+### When to Use What
+
+```
+Dominio simples (CRUD)?
+  +-- SIM --> Serverless/JAMstack (sem over-engineering)
+  +-- NAO --> Regras de negocio complexas?
+        +-- SIM --> Bounded Contexts claros?
+        |     +-- SIM --> DDD + Clean Architecture
+        |     +-- NAO --> Clean Architecture (sem tactical DDD)
+        +-- NAO --> Hexagonal (swap adapters easily)
+```
+
+---
+
+## 3. Modular Monolith Structure (Golden Standard)
+
+```
+src/
+  modules/
+    auth/
+      domain/          # Entities, Value Objects
+      application/     # Use Cases, Services
+      infrastructure/  # Repos, APIs externas
+      presentation/    # Controllers, Routes
+      index.ts         # Public API (barrel export)
+    billing/
+      ...
+    notifications/
+      ...
+  shared/
+    kernel/            # Shared types, Events
+    infrastructure/    # Database, Logging, Config
+```
+
+**5 Principles:**
+1. Each module exposes ONLY a public API (barrel export)
+2. Modules NEVER import directly from another module -- use the public API
+3. Inter-module communication via Domain Events (decoupling)
+4. Each module can have its own DB schema (schema-per-module)
+5. A module can be extracted to microservice when needed
+
+---
+
+## 4. State Management Patterns
+
+### The Modern Stack (2025-2026)
+
+| State Type | Tool | When |
+|-----------|------|------|
+| Server State | **TanStack Query** | API data, cache, revalidation |
+| Client State | **Zustand** | UI state, global without boilerplate |
+| URL State | **nuqs** | Filters, pagination, tabs, search params |
+| Form State | **React Hook Form + Zod** | Complex forms with validation |
+| Local State | `useState/useReducer` | Simple component-scoped state |
+
+### Decision Flow
+
+```
+Data comes from API?
+  +-- YES --> TanStack Query (staleTime, cache, optimistic updates)
+  +-- NO --> State needs to persist in URL?
+        +-- YES --> nuqs (shareable, bookmarkable)
+        +-- NO --> State shared across components?
+              +-- YES --> Zustand (lightweight global store)
+              +-- NO --> useState (local)
+```
+
+**Key insight:** TanStack Query reduces network requests by 40-60% vs Redux for same features. Redux is only for existing legacy projects.
+
+---
+
+## 5. Testing Pyramid
+
+```
+           /\
+          /  \
+         / E2E \         ~10% -- Playwright
+        /________\       Critical user flows only
+       /          \
+      / Integration \    ~30% -- Vitest + MSW
+     /______________\    API + components with data
+    /                \
+   /     Unit Tests   \  ~60% -- Vitest
+  /____________________\ Domain logic, utils, hooks
+```
+
+### Stack
+
+| Layer | Tool | Target |
+|-------|------|--------|
+| Unit | **Vitest** | Pure functions, hooks, utils, domain logic |
+| Component | **Vitest + Testing Library** | React components with interaction |
+| Integration | **Vitest + MSW** | API integration with HTTP mocks |
+| E2E | **Playwright** | Critical flows in real browser |
+| Visual | **Storybook + Chromatic** | Component visual regression |
+
+### What to Test at Each Layer
+
+| Layer | DO Test | DO NOT Test |
+|-------|---------|-------------|
+| Unit | Domain logic, calculations, validations, transformations | UI rendering, API calls, database |
+| Component | User interaction, conditional rendering, accessibility | API responses, business logic |
+| Integration | API contract, data flow, error handling | Visual layout, pixel-perfect |
+| E2E | Happy path flows, critical business paths | Edge cases (cover in unit/integration) |
+
+### MSW Reuse Pattern
+
+The same MSW handlers can be shared across Vitest, Playwright, Storybook, and React Native -- define once, reuse everywhere.
+
+---
+
+## 6. Next.js App Router Patterns
+
+### Server-Client Boundary
+
+**Rule:** Everything is a Server Component by default. Add `'use client'` only when needed.
+
+```
+Server Components (default)     Client Components ('use client')
+- DB access, file system        - useState, useEffect, hooks
+- Env vars, secrets             - Browser APIs (window, document)
+- Zero JS to browser            - Event handlers (onClick, etc.)
+- async/await in render         - Third-party client libs
+```
+
+### Recommended Folder Structure
+
+```
+app/
+  (auth)/                      # Route group -- auth pages
+    login/page.tsx
+    register/page.tsx
+    layout.tsx
+  (dashboard)/                 # Route group -- app pages
+    dashboard/page.tsx
+    settings/page.tsx
+    layout.tsx
+  api/
+    webhooks/stripe/route.ts   # Webhook handlers
+  layout.tsx                   # Root layout
+  error.tsx                    # Global error boundary
+  loading.tsx                  # Global loading
+  not-found.tsx
+
+src/
+  components/
+    ui/                        # Design system (Button, Input, Card)
+    features/                  # Feature-specific components
+    layouts/                   # Layout components
+  lib/
+    actions/                   # Server Actions
+    db/                        # Database client, queries
+    auth/                      # Auth utilities
+    validations/               # Zod schemas (shared client/server)
+  hooks/                       # Custom hooks
+  types/                       # TypeScript types
+  utils/                       # Pure utility functions
+```
+
+### Rendering Strategy Decision
+
+```
+Data changes per user?
+  +-- NO --> Data changes rarely?
+  |     +-- YES --> SSG (build time)
+  |     +-- NO --> ISR (revalidate: N seconds)
+  +-- YES --> Data is time-sensitive?
+        +-- YES --> SSR (force-dynamic)
+        +-- NO --> ISR + client-side fetching
+```
+
+---
+
+## 7. Performance Optimization Checklist
+
+### Core Web Vitals Targets
+
+| Metric | Target | What It Measures |
+|--------|--------|-----------------|
+| **LCP** | < 2.5s | Largest visible element load time |
+| **INP** | < 200ms | Interaction responsiveness |
+| **CLS** | < 0.1 | Visual stability (layout shifts) |
+
+### Pre-Deploy Checklist
+
+**Bundle:**
+- [ ] Route-based code splitting (automatic in Next.js)
+- [ ] `dynamic()` import for heavy components (charts, editors, maps)
+- [ ] Tree-shaking: named imports only (`import { debounce } from 'lodash-es'`)
+- [ ] No barrel file re-exports in large libraries
+
+**Images:**
+- [ ] `next/image` with `priority` on LCP image
+- [ ] `sizes` attribute set for responsive images
+- [ ] WebP/AVIF format (automatic with next/image)
+
+**Fonts:**
+- [ ] `next/font` for zero layout shift font loading
+- [ ] `display: 'swap'` for text visibility during load
+
+**Data:**
+- [ ] TanStack Query with appropriate `staleTime` (avoid over-fetching)
+- [ ] Server Components for initial data (zero client JS)
+- [ ] Streaming/Suspense for progressive loading
+
+**Rendering:**
+- [ ] Static pages use SSG/ISR (not SSR)
+- [ ] `loading.tsx` for instant navigation feedback
+- [ ] Prefetching enabled on navigation links
+
+**Accessibility:**
+- [ ] Semantic HTML first, ARIA only when needed
+- [ ] Keyboard navigation works for all interactive elements
+- [ ] Touch targets minimum 44x44px (WCAG 2.2)
+- [ ] `prefers-reduced-motion` media query respects user preference
+- [ ] Color contrast ratio >= 4.5:1 for normal text
+
+---
+
+## 8. API Design Decision
+
+```
+Full-stack TypeScript monorepo?
+  +-- YES --> tRPC (end-to-end type safety, zero codegen)
+  +-- NO --> API is public / multi-language consumers?
+        +-- YES --> REST + OpenAPI schema
+        +-- NO --> Multiple clients with varied data needs?
+              +-- YES --> GraphQL
+              +-- NO --> REST (simplest)
+```
+
+**SINAPSE default:** tRPC for internal SaaS, REST for public APIs.
+
+---
+
+## 9. Cross-References
+
+- Infrastructure scaling: see `infrastructure-decision-framework.md`
+- Database patterns: see `database-scaling-patterns.md`
+- Security pre-deploy: see `security-pre-deploy-checklist.md`
+- Environment config: see `environment-deployment-patterns.md`

package/.sinapse-ai/development/knowledge-base/token-economy-guide.md

@@ -0,0 +1,198 @@
+# Token Economy Guide
+
+> Practical strategies for managing Claude Code context window efficiently.
+> Based on SINAPSE research-02 (token economy) findings.
+
+---
+
+## When to Compact
+
+| Trigger | Default | Recommended |
+|---------|---------|-------------|
+| Auto-compact threshold | 83% context usage | 60% context usage |
+| Manual `/compact` | User-initiated | At every agent switch, after large file reads |
+| Pre-agent-switch | Not automatic | Use handoff protocol (~379 tokens vs ~3-5K) |
+
+**Why 60%?** At 83% the model is already losing coherence on early context. Compacting at 60% preserves decision quality and avoids "context amnesia" on key instructions.
+
+---
+
+## What Survives Compaction
+
+| Component | Survives? | Notes |
+|-----------|-----------|-------|
+| CLAUDE.md (project + global) | YES | Always re-injected |
+| Active rules (`.claude/rules/`) | YES | Path-filtered rules re-evaluated |
+| Tool definitions (Tier 1) | YES | Native tools always available |
+| Current file contents | NO | Must re-read after compact |
+| Conversation history | PARTIAL | Summarized, not verbatim |
+| Agent persona | NO | Must re-activate agent |
+| Handoff artifacts | YES | Stored in `.sinapse/handoffs/` |
+| PreCompact hook digest | YES | `precompact-wrapper.cjs` saves session state |
+
+---
+
+## Token Cost per Component
+
+### Fixed Costs (every session)
+
+| Component | Approx. Tokens | Notes |
+|-----------|---------------|-------|
+| Global CLAUDE.md | ~890 | `~/.claude/CLAUDE.md` |
+| Project CLAUDE.md | ~1,800 | `.claude/CLAUDE.md` |
+| Each rule file | 500-2,000 | `.claude/rules/*.md` |
+| Total rules (12 files) | ~12,000 | Loaded on session start |
+| System prompt overhead | ~2,000 | Claude Code harness |
+| **Baseline per session** | **~17,000** | Before any work begins |
+
+### Variable Costs
+
+| Component | Approx. Tokens | Notes |
+|-----------|---------------|-------|
+| Agent persona activation | ~800 | Full agent profile |
+| Agent handoff artifact | ~379 | Compacted from ~3-5K |
+| Sub-agent spawn | ~20,000 min | Task tool creates new context |
+| Tool search result | ~500-1,500 | Per deferred tool schema loaded |
+| File read (typical) | ~1,000-5,000 | Depends on file size |
+| Grep/Glob results | ~200-2,000 | Depends on match count |
+| MCP tool definition | ~300-800 | Per tool schema |
+
+---
+
+## Model Routing Table
+
+| Task Type | Recommended Model | Rationale |
+|-----------|------------------|-----------|
+| Architecture decisions | Opus | Needs deep reasoning |
+| Code implementation | Opus / Sonnet | Opus for complex, Sonnet for routine |
+| Code review | Sonnet | Pattern matching, fast feedback |
+| Research / analysis | Opus | Multi-source synthesis |
+| Documentation | Sonnet | Structured output, fast |
+| Quick Q&A / lookups | Haiku | Minimal context needed |
+| Sub-agent workers | Haiku / Sonnet | Cost-effective for scoped tasks |
+| Bulk file processing | Haiku | High throughput, low cost |
+
+---
+
+## Optimization Strategies
+
+### 1. YAML over JSON for Configuration
+
+YAML is 15-30% more token-efficient than JSON for the same data:
+
+```yaml
+# YAML: ~45 tokens
+name: feature
+status: active
+tags:
+  - ci
+  - security
+```
+
+```json
+// JSON: ~60 tokens
+{
+  "name": "feature",
+  "status": "active",
+  "tags": ["ci", "security"]
+}
+```
+
+### 2. Path-Filtered Rules
+
+Rules with `paths:` frontmatter only load when working on matching files:
+
+```yaml
+---
+paths:
+  - "packages/db/**"
+  - "migrations/**"
+---
+# Database rules (only loaded for DB work)
+```
+
+This avoids loading ~2K tokens of DB rules when doing frontend work.
+
+### 3. Deferred Tool Loading (3-Tier Mesh)
+
+| Tier | Loading | Token Impact |
+|------|---------|-------------|
+| Tier 1 (Always) | Session start | ~5K fixed cost |
+| Tier 2 (Deferred) | Agent activation | ~2K per agent |
+| Tier 3 (Deferred) | Tool search | ~500-1.5K on demand |
+
+Never load Tier 3 tools speculatively. Use `ToolSearch` only when needed.
+
+### 4. Agent Handoff Compaction
+
+Each agent switch without handoff protocol wastes ~3-5K tokens. With protocol:
+
+| Switches | Without Protocol | With Protocol | Savings |
+|----------|-----------------|---------------|---------|
+| 1 | ~8K | ~5.4K | 33% |
+| 2 | ~12K | ~5.2K | 57% |
+| 3 | ~16K | ~5.6K | 65% |
+
+### 5. Batch Tool Calls
+
+Independent operations should run in parallel:
+
+```
+# Bad: 3 sequential turns (~500 tokens overhead each)
+Read file A → Read file B → Read file C
+
+# Good: 1 parallel turn (~500 tokens overhead once)
+Read file A | Read file B | Read file C
+```
+
+### 6. Targeted File Reads
+
+```
+# Bad: Read entire 500-line file
+Read(file, offset=0)
+
+# Good: Read only the function you need
+Read(file, offset=142, limit=30)
+```
+
+### 7. Limit Search Results
+
+Always use `head_limit` on Grep/Glob to avoid flooding context:
+
+```
+# Bad: returns 250 matches (default)
+Grep(pattern="TODO")
+
+# Good: returns top 10
+Grep(pattern="TODO", head_limit=10)
+```
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Token Waste | Fix |
+|-------------|-------------|-----|
+| Reading same file multiple times | ~2-5K per read | Read once, reference line numbers |
+| Loading all MCP tools eagerly | ~10-20K | Use 3-Tier deferred loading |
+| Full agent persona on every switch | ~3-5K per switch | Use handoff protocol |
+| Unbounded grep results | ~5-10K | Use head_limit |
+| Re-reading files after edit | ~2-5K | Edit tool confirms success |
+| Spawning sub-agents for simple tasks | ~20K minimum | Do inline if <5 tool calls |
+| Not compacting before long tasks | Gradual degradation | Compact at 60% |
+
+---
+
+## Quick Reference: Context Budget
+
+For a 200K token context window:
+
+| Allocation | Tokens | % |
+|-----------|--------|---|
+| System + CLAUDE.md + Rules | ~17K | 8.5% |
+| Active agent + tools | ~5K | 2.5% |
+| Working memory (files, results) | ~80K | 40% |
+| Conversation history | ~58K | 29% |
+| Safety buffer (compact at 60%) | ~40K | 20% |
+
+**Target:** Keep working memory under 80K by reading only what you need and compacting frequently.

package/.sinapse-ai/development/scripts/populate-entity-registry.js

@@ -16,7 +16,11 @@ const SCAN_CONFIG = [
   { category: 'templates', basePath: '.sinapse-ai/product/templates', glob: '**/*.{yaml,yml,md}', type: 'template' },
   { category: 'scripts', basePath: '.sinapse-ai/development/scripts', glob: '**/*.{js,mjs}', type: 'script' },
   { category: 'modules', basePath: '.sinapse-ai/core', glob: '**/*.{js,mjs}', type: 'module' },
-  { category: 'agents', basePath: '.sinapse-ai/development/agents', glob: '**/*.{md,yaml,yml}', type: 'agent' },
+  // Story A.4: restrict to top-level *.md so agent MEMORY.md files under
+  // agents/{name}/MEMORY.md are NOT indexed as agents (they are memory, not
+  // persona definitions). Without this restriction, `extractEntityId`
+  // collapses every MEMORY.md to a single agent entry named "MEMORY".
+  { category: 'agents', basePath: '.sinapse-ai/development/agents', glob: '*.md', type: 'agent' },
   { category: 'checklists', basePath: '.sinapse-ai/development/checklists', glob: '**/*.md', type: 'checklist' },
   { category: 'data', basePath: '.sinapse-ai/data', glob: '**/*.{yaml,yml,md}', type: 'data' },
   { category: 'workflows', basePath: '.sinapse-ai/development/workflows', glob: '**/*.{yaml,yml}', type: 'workflow' },

package/.sinapse-ai/development/skills/captcha-handler.md

@@ -0,0 +1,82 @@
+---
+name: captcha-handler
+description: Handle CAPTCHAs encountered during browser automation
+trigger: When Chrome Brain or Playwright hits a CAPTCHA challenge
+agents: [developer, analyst]
+---
+
+# CAPTCHA Handler Skill
+
+## Usage
+
+Invoke with `*captcha-handler` or `/captcha-handler` when browser automation is blocked by a CAPTCHA.
+
+## Detection
+
+Identify the CAPTCHA type from the page:
+
+| Type | Detection Signal |
+|------|-----------------|
+| reCAPTCHA v2 | `iframe[src*="recaptcha"]`, `.g-recaptcha` |
+| reCAPTCHA v3 | `grecaptcha.execute` in page scripts |
+| Cloudflare Turnstile | `iframe[src*="challenges.cloudflare.com"]`, `.cf-turnstile` |
+| hCaptcha | `iframe[src*="hcaptcha.com"]`, `.h-captcha` |
+
+```bash
+# Quick detection via page source
+grep -i "recaptcha\|turnstile\|hcaptcha\|captcha" /tmp/page-source.html
+```
+
+## Strategies (ordered by preference)
+
+### Strategy 1: Avoidance (PREFERRED)
+Prevent CAPTCHA from triggering in the first place:
+- Use `puppeteer-extra-plugin-stealth` for headless sessions
+- Rotate User-Agent strings to match real browsers
+- Add realistic delays between actions (500-2000ms)
+- Avoid rapid-fire requests to the same domain
+- Set viewport to common resolution (1920x1080)
+- Enable JavaScript and cookies
+
+### Strategy 2: Manual Solve (FALLBACK)
+When avoidance fails, notify user to solve manually:
+1. Take screenshot of the CAPTCHA page
+2. Display: "CAPTCHA detected ({type}). Please solve it in the browser window."
+3. Wait for page navigation or CAPTCHA element removal (poll every 2s, timeout 120s)
+4. Resume automation after solve confirmed
+
+### Strategy 3: API Solve (OPTIONAL)
+If `CAPTCHA_API_KEY` environment variable is set (2captcha.com):
+1. Extract sitekey from CAPTCHA element
+2. Submit to 2captcha API with page URL and sitekey
+3. Poll for solution (max 60s)
+4. Inject solution token into page
+5. Submit form
+
+```bash
+# Check if API is configured
+echo $CAPTCHA_API_KEY | head -c 4
+```
+
+**Only use Strategy 3 when:**
+- User has explicitly configured the API key
+- Strategy 1 and 2 are impractical (batch automation)
+- User consents to per-solve costs
+
+## Output
+
+```
+## CAPTCHA Handler Report
+- Type: {captcha_type}
+- Strategy Used: {avoidance|manual|api}
+- Result: {SOLVED|TIMEOUT|FAILED}
+- Time: {seconds}s
+- Recommendation: {next steps if failed}
+```
+
+## Rules
+- ALWAYS prefer avoidance over solving
+- NEVER store or log CAPTCHA API keys
+- Timeout after 120s for manual solve, 60s for API solve
+- If all strategies fail, document the blocker and suggest alternative approach (API instead of scraping)
+- Respect website ToS — CAPTCHAs exist for a reason

package/.sinapse-ai/development/skills/chrome-brain.md

@@ -0,0 +1,81 @@
+---
+name: chrome-brain
+description: Intelligent browser automation with persistent sessions, memory, and auto-learning
+trigger: When any agent needs to browse, scrape, test UI, or interact with web services
+---
+
+# Chrome Brain — Intelligent Browser Skill
+
+## Connection Architecture
+
+```
+Priority 1: --autoConnect (user's real Chrome, all sessions preserved)
+Priority 2: --browserUrl (persistent debug profile, seeded from user's Chrome)
+Priority 3: Launch fresh Chrome (last resort)
+```
+
+**Setup (one-time):** Open Chrome → `chrome://inspect/#remote-debugging` → Enable toggle.
+
+## Available Tools (29 via chrome-devtools MCP)
+
+| Category | Tools | Use When |
+|----------|-------|----------|
+| Navigation | navigate_page, new_page, close_page, list_pages, select_page | Open/switch pages |
+| Interaction | click, fill, fill_form, type_text, press_key, hover, drag, upload_file | Interact with UI |
+| Capture | take_screenshot, take_snapshot, take_memory_snapshot | Visual verification |
+| Scripting | evaluate_script | Extract data, manipulate DOM |
+| Monitoring | list_console_messages, list_network_requests, get_network_request | Debug, intercept |
+| Performance | performance_start_trace, performance_stop_trace, lighthouse_audit | Performance testing |
+| Dialog | handle_dialog, wait_for | Handle alerts, wait for elements |
+| Device | emulate, resize_page | Test responsive, mobile |
+
+## CAPTCHA Protocol
+
+```
+1. DETECT: Check for CAPTCHA indicators (iframe[src*=recaptcha], .cf-turnstile, .h-captcha)
+2. AVOID FIRST:
+   - autoConnect = user's real Chrome = already authenticated = rare CAPTCHAs
+   - --disable-blink-features=AutomationControlled (stealth mode active)
+   - Human-like delays between actions (200-500ms)
+3. IF CAPTCHA APPEARS:
+   a. Simple checkbox: try click() — sometimes works with real Chrome profile
+   b. Visual challenge: take_screenshot → notify user "CAPTCHA detected, please solve"
+   c. Cloudflare Turnstile: usually auto-passes with real Chrome profile
+4. NEVER: Use CAPTCHA-solving services without explicit user authorization
+```
+
+## Auto-Learning Protocol
+
+After every browsing session, extract and store:
+
+```yaml
+# ~/.chrome-brain/memory.jsonl (appended automatically by PostToolUse hook)
+session_log:
+  urls_visited: []
+  data_extracted: {}
+  errors_encountered: []
+  patterns_discovered: []
+```
+
+## Best Practices
+
+1. **Screenshots budget:** Max 12 per session (warning at 12, critical at 15)
+2. **Always take_screenshot after navigation** to verify page loaded correctly
+3. **Use evaluate_script for data extraction** (faster than multiple clicks)
+4. **Check console messages** for JavaScript errors before interacting
+5. **Use wait_for** before clicking elements that load asynchronously
+6. **Prefer fill_form** over individual fill() calls for multi-field forms
+7. **Use emulate** to test mobile layouts before desktop
+
+## Session Persistence
+
+- Cookies, localStorage, and sessions persist between uses (autoConnect)
+- No need to re-login to services between sessions
+- If session expires, user logs in once in their normal Chrome — done
+
+## Security Notes
+
+- autoConnect exposes all user cookies/tokens to the MCP client
+- Never navigate to untrusted URLs in authenticated sessions
+- Prefer using a dedicated tab for automation work
+- Close sensitive tabs before running automated browsing tasks