docs: upgrade README layout with local setup guides, engineering insights, and recruiter CTAs

README.md

@@ -28,10 +28,64 @@ Como profissional neurodivergente **(TEA)**, este projeto traduz hiperfoco, lóg
 
 🚀 Acesse a aplicação completa ao vivo: **[Visualizar Portfólio na Vercel](https://franferrazdev-portfolio.vercel.app/)**
 
-### 🎥 Demonstração Visual (Project Showcase)
+## 🚀 Como Executar o Projeto Localmente
+
+Siga os passos abaixo para clonar e rodar o simulador em sua máquina de desenvolvimento:
+
+1. **Clone o repositório:**
+
+```bash
+git clone https://github.com/franferrazdev/franferrazdev-portfolio.git
+cd franferrazdev-portfolio
+```
+
+2. **Instale as dependências:**
+
+```bash
+pnpm install
+```
+
+3. **Inicie o servidor de desenvolvimento:**
+
+```bash
+pnpm dev
+```
+
+Abra [http://localhost:3000](http://localhost:3000) no seu navegador para ver o resultado.
+
+4. **Execução de Testes:**
+
+- **Testes Unitários (Jest):** `pnpm test` ou `pnpm test:watch`
+- **Testes End-to-End (Playwright):** `npx playwright test`
+
+---
+
+### 🎥 Demonstração Visual e Âncoras do Sistema
+
+As capturas abaixo ilustram a experiência inicial do usuário, a componentização responsiva e os fluxos de captação de leads projetados para o ecossistema do portfólio:
+
+#### 1. Hero Section (Apresentação Inicial e Terminal Fluid)
+
+Visão principal do portfólio destacando a digitação fluida e dinâmica, controles de internacionalização instantânea e os seletores de acessibilidade (Light/Dark Mode).
 
 <div align="center">
-  <img src="public/portfolio-hero.png?v=4" alt="Portfolio Preview" width="100%" style="border-radius: 12px; border: 1px solid #1e293b;" />
+  <img src="public/showcase/portfolio-hero.png?v=4" alt="Portfolio Preview" width="100%" style="border-radius: 12px; border: 1px solid #1e293b;" />
+</div>
+
+#### 2. Vitrine de Engenharia (Grid de Projetos em Destaque)
+
+Exibição modular dos repositórios encapsulados em cards tridimensionais reativos, destacando as badges técnicas de testes e links de produção.
+
+<div align="center">
+  <img src="/public/showcase/portfolio-projects-grid.png" alt="Grid de Projetos do Portfólio" width="100%" />
+</div>
+
+#### 3. Terminal de Captura Asincrônica (Formulário de Contato)
+
+Formulário dinâmico integrado à API externa do Formspree, contendo validações de estados, feedbacks de sucesso instantâneos e proteção de campos.
+
+<div align="center">
+  <img src="/public/showcase/portfolio-contact-form.png" alt="Formulário de Contato do Portfólio" width="100%" />
 </div>
 
 ### 🛠️ Diferenciais Técnicos e Arquitetura
@@ -50,6 +104,27 @@ Este ambiente possui uma suíte de testes rigorosa para blindar o código contra
 
 ---
 
+## 🧠 Desafios e Aprendizados
+
+O desenvolvimento deste hub centralizado de engenharia consolidou competências avançadas em otimização de interfaces reativas e resiliência de código:
+
+- **Sincronização de Viewport com IntersectionObserver:** Arquitetar um gerenciamento de estados centralizado no `src/App.tsx` para monitorar o scroll reativo exigiu o domínio de APIs nativas do navegador. Essa abordagem garante a mutação fluida de hashes na URL, disparos de animações direcionais e atualização dos marcadores da Navbar em tempo real no eixo Y, sem causar gargalos de renderização ou travamentos de layout.
+- **Navegação Síncrona Imune a Concorrência:** Implementar o componente `ScrollArrow` demandou soluções sólidas de controle de concorrência. Utilizando blocos de reatividade isolados com `useRef`, foi possível blindar as travas de cliques rápidos, garantindo que a rolagem cronológica salte de seção em seção de forma linear e elástica, impedindo o pulo acidental de blocos curtos de conteúdo.
+- **Cultura de Testes Multicamadas e Automação de CI:** Estruturar uma pirâmide de testes completa unificando Jest, React Testing Library e Playwright E2E expandiu significativamente minha visão de governança de código. Isolar o ciclo de vida de contextos globais (`LanguageContext` e `ThemeContext`) e criar robôs que simulam a jornada real do recrutador desde o boot da tela de carregamento até o disparo do formulário de contato via Formspree — tudo isso orquestrado por um pipeline automatizado de CI no GitHub Actions — garante uma interface blindada contra regressões visuais em ambiente de produção.
+
+---
+
+## 🤝 Quer conversar sobre uma oportunidade ou agendar uma entrevista técnica?
+
+Se você gostou da arquitetura dos meus projetos, da cobertura de testes automatizados com Jest e Playwright ou quer trocar uma ideia sobre desenvolvimento front-end, meu terminal está sempre aberto! Você pode me encontrar diretamente pelos canais oficiais:
+
+- **E-mail Profissional:** [franferraz.dev@gmail.com](mailto:franferraz.dev@gmail.com)
+- **LinkedIn Oficial:** [Francielle Ferraz de Sousa](https://www.linkedin.com/in/francielle-ferraz-de-sousa-franferrazdev)
+
+Vamos construir soluções eficientes e robustas juntos! 🚀
+
+---
+
 ## 🇺🇸 English
 
 ### 📝 Description
@@ -62,10 +137,63 @@ As a neurodivergent professional **(ASD)**, this project converts hyperfocus, sh
 
 🚀 Access the live running application: **[View Portfolio on Vercel](https://franferrazdev-portfolio.vercel.app/)**
 
-### 🎥 Visual Demonstration (Project Showcase)
+## 🚀 How to Run Locally
+
+Follow these steps to clone and run the technical simulator on your local workspace:
+
+1. **Clone the repository:**
+
+   ```bash
+   git clone https://github.com/franferrazdev/franferrazdev-portfolio.git
+   cd franferrazdev-portfolio
+   ```
+
+2. **Install dependencies:**
+
+   ```bash
+   pnpm install
+   ```
+
+3. **Run the development environment:**
+
+   ```bash
+   pnpm dev
+   ```
+
+   Open [http://localhost:3000](http://localhost:3000) inside your browser.
+
+4. **Executing Tests:**
+   - **Unit Tests (Jest):** `pnpm test`
+   - **End-to-End Tests (Playwright):** `npx playwright test`
+
+---
+
+### 🎥 Visual Presentation & System Anchors
+
+The captures below illustrate the initial user experience, responsive component layouts, and async lead capturing workflows engineered for the portfolio ecosystem:
+
+#### 1. Hero Section (Dynamic Splash and Fluid Terminal)
+
+Primary viewport view showcasing real-time fluid typography typing arrays, immediate internationalization dictionaries, and accessible dynamic theme triggers (Light/Dark Mode).
+
+<div align="center">
+  <img src="public/showcase/portfolio-hero.png?v=4" alt="Preview Portfolio" width="100%" style="border-radius: 12px; border: 1px solid #1e293b;" />
+</div>
+
+#### 2. Engineering Showcase (Featured Projects Grid)
+
+Modular layout exhibiting repositories encapsulated inside reactive 3D cards, highlighting tech test badges and live demo targets.
 
 <div align="center">
-  <img src="public/portfolio-hero.png?v=4" alt="Preview Portfolio" width="100%" style="border-radius: 12px; border: 1px solid #1e293b;" />
+  <img src="/public/showcase/portfolio-projects-grid.png" alt="Portfolio Projects Grid Layout" width="100%" />
+</div>
+
+#### 3. Asynchronous Lead Terminal (Contact Form Section)
+
+Dynamic form integrated with the external Formspree API, featuring real-time input validation, structural toast feedbacks, and security masks.
+
+<div align="center">
+  <img src="/public/showcase/portfolio-contact-form.png" alt="Portfolio Contact Form Section" width="100%" />
 </div>
 
 ### 🛠️ Technical Highlights & Architecture
@@ -84,6 +212,27 @@ This workspace maintains a strict testing matrix to safeguard interfaces against
 
 ---
 
+## 🧠 Technical Challenges and Learnings
+
+Building this centralized engineering hub solidified core frontend system architectures, performance tuning, and multi-layered testing paradigms:
+
+- **Viewport Synchronization via IntersectionObserver:** Engineering a centralized hook architecture within `src/App.tsx` to monitor layout scrolling patterns required a deep mastery of native browser APIs. This setup guarantees seamless URL hash shifts, smooth directional viewport transitions, and real-time navigation link state updates across the Y-axis without inducing performance lag or layout breaking.
+- **Concurrency-Immune Synchronous Navigation:** Developing the reactive `ScrollArrow` component required strict operational control solutions. Utilizing isolated boundaries with `useRef` tokens effectively protected the application against rapid clicking race conditions, assuring that chronological transitions move linearly across semantic elements without skipping shorter section layouts.
+- **Multi-Tier Testing Matrix and Workflow CI Automation:** Establishing a complete automated verification matrix by intertwining Jest, React Testing Library, and Playwright E2E advanced my system design practices. Validating global application contexts (`LanguageContext` and `ThemeContext`) alongside creating actions that simulate a recruiter's path—waiting for the loading screen system boot, handling strict floating component clicks, and testing form dispatches via Formspree API—all managed by an automated GitHub Actions CI pipeline, provides full regression protection across modern deployments.
+
+---
+
+## 🤝 Want to discuss an opportunity or schedule a technical interview?
+
+If you liked the architecture of my systems, the automated test matrix using Jest and Playwright, or want to chat about front-end engineering, my workspace is always open! You can reach me directly through my official networks:
+
+- **Professional Email:** [franferraz.dev@gmail.com](mailto:franferraz.dev@gmail.com)
+- **Official LinkedIn:** [Francielle Ferraz de Sousa](https://www.linkedin.com/in/francielle-ferraz-de-sousa-franferrazdev)
+
+Let's build efficient, robust software together! 🚀
+
+---
+
 <div align="center">
   <sub>Desenvolvido com hiperfoco por <strong>Francielle Ferraz</strong> · © 2026</sub>
 </div>