Setup MacBook Noelia · Phase 1

Configuración paso a paso del MacBook Air M2 (8GB, macOS Sequoia 15.6). Marcá cada step cuando lo completés, el progreso se guarda automáticamente en este browser.

Atelier Noelia · Sharkcode · documento bilingual ES Latam + EN tecnicismi · 23 mayo 2026

Progreso setup: 0 / 12 ~3-5h restantes
12
Steps totales
3-5h
Tiempo primer setup
8GB
RAM MacBook M2
123GB
Storage libre

🎉 ¡Felicitaciones Noelia! Setup completado.

Tu MacBook está configurado para Atelier Noelia. Próximo paso: Welcome App Tutorial →

Avisá a Michel que terminaste 💛

Antes de empezar · Pre-check

1. Verificar especificaciones del Mac

Abrir menú Apple (esquina superior izquierda) → Acerca de esta Mac.

2. Verificar storage libre

Apple menu → Acerca de esta Mac → Almacenamiento. Tu Mac tiene 123GB libres de 245GB, espacio de sobra: el clone + install completo pesa ~5,5GB y entra cómodo.

Cuidado iCloud sync: NO actives "Desktop & Documents Folders" sync por default (puede mover archivos de trabajo a la nube y romper paths locales). Si querés ahorrar espacio, usá Optimise Mac Storage en Settings → Apple ID → iCloud, que mantiene los archivos recientes locales.

3. Apple ID + iCloud activo

Apple ID configurado, iCloud Drive activado para backup automático.

4. Contraseña administrador

Tenés a mano la contraseña de tu Mac (la necesitás para instalar cosas).

1

Homebrew · gestor de paquetes Mac

Permite instalar herramientas con un solo comando, sin descargar .dmg manualmente.

Mac M2 vergine = primer install: Homebrew installer richiede Xcode Command Line Tools (CLT) cómo prerequisito. Lo detecta automatic + ti popa popup "Install Xcode Command Line Tools" → click "Install" + accetta termini Apple + aspetta ~5-10 min download (~1.5 GB). Brew install procede automatic post-CLT done. NO skip popup, e' mandatorio per Bun/pnpm/git native deps.

Abrir Terminal (Spotlight → "Terminal" → Enter) y pegar:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Cuando pida contraseña, escribirla (no se ve mientras tipeás, es normal). ~5-10 min (15-20 min con CLT primer install)

Verificación

brew --version

Debería decir Homebrew 4.x.x.

Si dice "command not found": 
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc
brew --version
2

Git + Node + Bun + pnpm · herramientas dev

Git para versionar código, Node runtime, Bun como runtime moderno principal Sharkcode, pnpm necesario para Wedding-Templates sibling repo (stack distinto).

brew install git node
curl -fsSL https://bun.sh/install | bash
npm install -g pnpm
Por qué pnpm también? Wedding-Templates sibling repo usa pnpm (monorepo workspace con pnpm-workspace.yaml), NO Bun. Day 1 lei clone Wedding-Templates + pnpm install + pnpm dev:maira. Sharkcode main resta su Bun. Convivenza pacifica.
Node es obligatorio (Bun NO lo reemplaza para los hooks): 5 hooks .mjs de Claude Code (protected-paths, auto-retrieval, ecc.) corren con node, no con Bun. Si node --version NO devuelve v20.x o v22.x, instalalo: brew install node. Sin Node los hooks fallan silenciosos y pueden bloquear cada Edit/Write.

Verificación

git --version
node --version
bun --version
pnpm --version
Si bun no funciona: 
echo 'export BUN_INSTALL="$HOME/.bun"' >> ~/.zshrc
echo 'export PATH="$BUN_INSTALL/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
3

VSCode · editor de código

Donde vas a editar archivos. Como Word pero para código.

brew install --cask visual-studio-code

Si pide contraseña → la tuya del Mac.

Configurar comando code en PATH

Abrir VSCode. Dentro: Cmd + Shift + P → buscar "shell command: Install 'code' command in PATH" → Enter.

Step 3 ahora = solo VSCode + comando code en PATH (arriba). NADA MÁS. Los 2 bloques de abajo (extensiones + settings.json) hacen cd ~/Code/sharkcode, pero esa carpeta NO existe hasta el Step 7 (clone del repo). Si los corrés ahora dan no such file or directory. Marcá el Step 3 como hecho con solo VSCode + code en PATH, y seguí al Step 4.

A) Extensiones esenciales · correr DESPUÉS del Step 7 (1 comando)

Cuando ya clonaste el repo (Step 7), volvé acá y corré este comando UNO:

cd ~/Code/sharkcode
cat .planning/business/atelier-noelia/dotfiles/vscode-extensions.txt | grep -v "^#" | grep -v "^$" | xargs -L1 code --install-extension

Installa 5 essenziali (GitLens + Tailwind + Astro + Volar + spell-checker EN/ES/IT) + skip commenti. ~30 sec.

B) settings.json Mac · NO lo hagas a mano

Lo copia solo el script del Step 10 (setup-mac-user-scope.sh, su paso 6). No corras ningún cp de settings.json acá: te lo hace el script más adelante (lightweight 8GB + claudeCode.defaultLanguage: es).
8GB RAM: NO instalar muchas más extensiones.
4

Claude Code CLI

Asistente Claude para terminal/VSCode. Tu compañero en cada tarea.

npm install -g @anthropic-ai/claude-code

Si "permission denied":

sudo npm install -g @anthropic-ai/claude-code

Login (Michel pair-mode)

Michel te guía esto. Usás credenciales sub Michel Max plan.

claude auth login

Verificación

claude --version
claude

Dentro del chat: "Hola, ¿podés decirme qué herramientas tenés disponibles?" Debería responder en español. Si no, decirle "Por favor responde en español".

5

GitHub account + SSH key + invite Collaborator

Cuenta GitHub propia separada de Michel. Después Michel te invita como Collaborator a sus repos (sync automático, audit trail limpio).

Si hiciste Day 0 prep: Steps 5.1-5.5 ya están hechos (cuenta + SSH key + invitation aceptada). Skippá a Step 5.6 verificación. Tutorial Day 0: TUTORIAL-GITHUB-DAY-0-NOELIA.html. Ahorro Day 1 ~25 min.

5.1 Crear cuenta GitHub

Browser → https://github.com/signup:

  • Username sugerido: noelia-sharkcode o noelia-[tu-apellido]
  • Email: tu email personal
  • Password fuerte (Apple Keychain)
  • Verificar email

5.2 Generar SSH key

ssh-keygen -t ed25519 -C "tu-email-github@example.com"

Donde guardar → Enter (default). Passphrase → opcional.

5.3 Copiar public key

pbcopy < ~/.ssh/id_ed25519.pub

5.4 Agregar SSH key a GitHub

  1. GitHub → Settings (foto perfil arriba derecha) → SSH and GPG keys
  2. Click New SSH key
  3. Title: MacBook Noelia
  4. Key: Cmd + V
  5. Click Add SSH key

5.5 Verificación

ssh -T git@github.com

Debería decir: "Hi noelia-sharkcode! You've successfully authenticated..."

5.6 Michel te invita como Collaborator

Michel hace este paso: en GitHub.com/Michel9329/sharkcode → Settings → Collaborators → Add people → tu username → Write access. Mismo para Wedding-Templates. Vos recibís email con invitation → click Accept. Audit trail limpio + sync automático con upstream Michel.

5.7 Git workflow colaboracion (read post-clone)

Lectura mandatoria post-setup: GIT-WORKFLOW-COLLAB.html · 3 escenarios commit con Michel + ownership map quien toca que + daily workflow pull/push + conflict resolution. 15-20 min lettura. Critico per non pisarse commits mutui Day 1-30.
6

Git config global

Configurar tu nombre/email para que aparezcan en cada commit.

git config --global user.name "Noelia [tu nombre]"
git config --global user.email "tu-email-github@example.com"
git config --global init.defaultBranch main
git config --global pull.rebase false

Verificación

git config --global --list
7

Clonar repos Sharkcode + Wedding-Templates + install deps

Clonar = bajar copia del código al Mac. Sharkcode via sparse-checkout (sin la carpeta clients/ de otros clientes). Wedding-Templates completo. Mismo URL upstream que Michel (vos sos Collaborator).

Memory pressure 8GB warning: bun install Sharkcode (~500MB deps) + pnpm install Wedding-Templates (~700MB deps) son pesanti su Mac M2 8GB. PRIMA di lanciare install:
  • Chiudere Chrome (Cmd+Q completo, NON solo finestra)
  • Chiudere altre app non essenziali (Slack, Spotify, ecc.)
  • Monitorare Activity Monitor (Spotlight → Activity Monitor → tab Memory) durante install
  • Se "Memory pressure" rosso = stop install + restart Mac + retry
mkdir -p ~/Code
cd ~/Code

# Sharkcode: sparse-checkout SIN clients/ (datos de otros clientes, NO los necesitas)
# Se mantiene solo clients/noelia-etsy/ (tu workspace Etsy)
git clone --no-checkout git@github.com:Michel9329/sharkcode.git
cd sharkcode
git sparse-checkout set --no-cone '/*' '!/clients/*' '/clients/noelia-etsy/'
git checkout main
cd ..

# Wedding-Templates: clone completo (master ya listo)
git clone git@github.com:Michel9329/Wedding-Templates.git

Sharkcode via sparse-checkout (sin clients/ de otros). Wedding-Templates completo. ~30-60s por repo

Por que sparse-checkout: el repo Sharkcode tiene clients/ con datos de otros clientes (Mary, Valerio, Lindorug: preventivi, propuestas, contactos de terceros). Por GDPR no deben estar en tu Mac y no los necesitas. El sparse-checkout baja todo MENOS clients/, manteniendo solo clients/noelia-etsy/ (tuyo). Verifica con ls clients/: debe mostrar solo noelia-etsy.

Install Node deps Sharkcode (OBLIGATORIO hooks Mac + MCP local)

cd ~/Code/sharkcode
bun install

Install ~500MB deps + 1500+ packages (~2-3 min). Include picomatch + js-yaml necessari per hooks Mac auto-retrieval + protected-paths.

NO skippear este bun install: sin node_modules el hook de seguridad protected-paths-block.mjs crashea y puede bloquear CADA Edit/Write de Claude. Tampoco arrancan los servers MCP locales sharkcode-core (knowledge graph, dashboard events). Es el paso que hace que Claude funcione perfecto Day 1.

Generar knowledge graph (gitignored, no llega con el clone)

cd ~/Code/sharkcode
bun run build-graph

Genera tools/dashboard/apps/server/data/knowledge-graph.json. Ese archivo está gitignored (no viene con el clone): sin él, la tool query_knowledge_graph que usa Claude falla. ~10-20 seg.

Install deps Wedding-Templates (pnpm, NO bun)

cd ~/Code/Wedding-Templates
pnpm install

Wedding-Templates usa pnpm (stack React 19 + Vite 6 + Tailwind 4 + Supabase + Resend + Vercel), NO bun. ~700MB deps (~2-3 min). Cerrá Chrome antes (ver warning memory pressure arriba).

Verificación

cd ~/Code/sharkcode && ls
cd ~/Code/Wedding-Templates && ls

Abrir Sharkcode en VSCode (single root, multi-root viene Step 10.2)

cd ~/Code/sharkcode
code .
8

Canva account (Free Day 1, Pro decision Day 7+)

Day 1 crear cuenta Canva free. Decisión Pro upgrade DEFERRED post-Welcome Tutorial T1-T5 (D5 audit mattina 2026-05-24).

Decisión D5 Michel: Day 0/1 NO upgrade Canva Pro. Lei prova free Day 1-7, decide Pro upgrade Day 7+ post-Welcome Tutorial cuando vede valore concreto para Etsy production. Skin in the game M0 NO es Canva Pro (decisión posticipata).
  1. canva.com/signup (TU cuenta free, con tu email personal y tu tarjeta cuando llegue el momento Pro)
  2. NO upgrade Pro Day 1 (postergar Day 7+)
  3. Es una cuenta 100% tuya, independiente. NO hay team Sharkcode ni invitación que esperar.
Nada de team Canva: Michel NO usa Canva, así que no hay ningún "team Sharkcode" para compartir ni invitación que aceptar. Tu cuenta es solo tuya.

Brand kit Sharkcode (vive en el repo, no en Canva)

El brand kit Sharkcode para los trabajos Wedding (colores, fuentes, logo) está en el repo, en templates/brand/, no en Canva. Cuando armes un diseño Wedding, tomás los valores de ahí (o Claude te los pasa). No necesitás importar nada a Canva Day 1.

Day 7+ decisión Pro upgrade

Post Welcome Tutorial T1-T5, evaluación: ¿necesitás magic resize / background remover / brand kit unlimited / 100GB storage? Si SI → upgrade Pro 11,99 EUR/mes o 109,99 EUR/año (a tu nombre, tu tarjeta). Si NO → mantener free. Para Etsy alcanza con Pro, NO hace falta Business.

9

Chrome dedicado · perfil separado

Browser separado solo para trabajo, no mezclado con tabs personales.

Si no tenés Chrome:

brew install --cask google-chrome
  1. Abrir Chrome
  2. Click foto perfil arriba derecha → Add → crear perfil "Noelia Sharkcode"
  3. SOLO este perfil para: Etsy seller + Canva + GitHub + sitios cliente
  4. Tabs máximo 5-7 8GB RAM tight

Extension recomendada: OneTab (Chrome Web Store) → convierte tabs en lista, libera RAM.

10

Dotfiles Sharkcode + workspace VSCode + user-scope ambient (Wave 3 enhanced)

Aliases zshrc + multi-root VSCode workspace + hooks essential Claude Code (auto-retrieval + protected-paths + ecc) + TAVILY API + markitdown-mcp Mac override + verifica deps.

10.1 zshrc Sharkcode brand prompt + alias

cd ~/Code/sharkcode
cp .planning/business/atelier-noelia/dotfiles/zshrc-noelia ~/.zshrc-noelia
echo 'source ~/.zshrc-noelia' >> ~/.zshrc
source ~/.zshrc

10.2 VSCode workspace multi-root copy (Wave 3 fix)

Workspace 5-folder (Sharkcode + Wedding-Templates + Pinna + Etsy Noelia + Atelier docs):

cp ~/Code/sharkcode/.planning/business/atelier-noelia/dotfiles/noelia.code-workspace ~/Code/noelia.code-workspace
code ~/Code/noelia.code-workspace

10.3 User-scope ambient (hooks + TAVILY + Mac MCP override) script automatic (Wave 3 fix)

Script lancia automatic: copy 10 hook Mac-friendly in ~/.claude/hooks/ + register ~/.claude/settings.json 4 hook events + TAVILY_API_KEY setup info + markitdown-mcp Win override Mac + verify Node deps (picomatch + js-yaml):

bash ~/Code/sharkcode/tools/atelier-noelia/setup-mac-user-scope.sh
Output script: 7 step interactive feedback (✓ success / ⚠ skip / ❌ error). Se TAVILY_API_KEY missing, script ti mostra steps signup free tier 1000 req/mese (necessario Welcome Tutorial T2 Etsy research).

10.4 Restart Claude Code per attivare hooks

Hook registrati in ~/.claude/settings.json richiedono Claude Code restart per essere triggered:

# Quit Claude Code: Cmd+Q
# Riapri: type "claude" in nuovo terminal OR via VSCode integrated terminal
Memory Sharkcode shared cross-machine: el dotfile incluye SHARKCODE_MEMORY_DIR=~/Code/sharkcode/memory-shared y ~90 memorie cross-cliente sincronizadas desde Win Michel via PowerShell weekly Sunday 21:00. Pero ojo (ver 10.5): Claude Code nativo NO lee esa env var para cargar las memorias, hay que hacer un symlink.

10.5 Symlink memory nativo Claude → memory-shared (CRÍTICO para que Claude lea las memorias)

Por qué este paso: SHARKCODE_MEMORY_DIR NO es una env var real de Anthropic, Claude Code nativo NO la lee. Claude busca las memorias en su carpeta nativa ~/.claude/projects/<hash-del-proyecto>/memory/. El <hash> depende del path absoluto del repo en el Mac, así que se crea recién al abrir Claude la primera vez dentro del repo. Por eso primero abrimos Claude, después hacemos el symlink.

Paso 1: abrir Claude UNA vez dentro del repo para que cree la carpeta del proyecto:

cd ~/Code/sharkcode
claude "hola"   # con esto Claude crea ~/.claude/projects/<hash>/
# Salí del chat: escribí /exit o Ctrl+C

Paso 2: encontrar la carpeta del proyecto creada (suele ser la más reciente) y enlazar su subcarpeta memory a memory-shared:

# Ver la carpeta del proyecto (la que contiene "sharkcode" en el nombre)
ls -dt ~/.claude/projects/*sharkcode* 2>/dev/null

# Guardar ese path en una variable (toma la más reciente)
PROJ=$(ls -dt ~/.claude/projects/*sharkcode* 2>/dev/null | head -1)
echo "Proyecto detectado: $PROJ"

# Crear el symlink memory -> memory-shared (borra primero si ya existe vacío)
rm -rf "$PROJ/memory"
ln -s ~/Code/sharkcode/memory-shared "$PROJ/memory"

# Verificar
ls -la "$PROJ/memory" | head -3
Test empírico: abrí Claude (cdsc + claude) y preguntale: "cita la memoria del perfil ansioso de Mary". Si te describe el contenido (Mary cliente ansioso, batch 1 respuesta/día, frase-tappo), el symlink funciona. Si dice que no encuentra ninguna memoria, repetí Paso 2.

10.6 Silenciar MCP servers y hooks Windows-only (settings.local.json Mac)

Dos servers MCP y unos hooks son de Windows y crashean en el Mac:
  • markitdown-mcp usa un comando Windows (cmd/.exe), crashea al arrancar en Mac.
  • sharkcode-local-llm necesita Ollama, que NO está en el Mac de Noelia.
  • Los hooks de dashboard que llaman python send_event.py fallan: en Sequoia NO existe el comando python (solo python3), y además la dashboard no corre en tu Mac.
El archivo .mcp.json.local NO sirve: Claude Code NO lo lee automáticamente (lanzarlo con claude --mcp-config es frágil y hay que recordarlo cada vez). La vía correcta es disabledMcpjsonServers dentro de un settings.local.json Mac (gitignored, específico de este Mac).

Crear el settings local Mac (deshabilita los 2 MCP problemáticos). Pegá este comando tal cual:

cd ~/Code/sharkcode
cat > .claude/settings.local.json <<'JSON'
{
  "disabledMcpjsonServers": ["markitdown-mcp", "sharkcode-local-llm"]
}
JSON
echo "settings.local.json creado:"
cat .claude/settings.local.json

Neutralizar los hooks Windows-only (los que llaman python send_event.py) en tu user settings Mac, así no dan error en cada tool use. Si el script de 10.3 ya registró hooks, sacá de ~/.claude/settings.json cualquier entry que invoque python ... send_event.py (la dashboard no corre en tu Mac, no perdés nada). Revisá con:

cat ~/.claude/settings.json | grep -n "send_event"

Si aparece alguna línea con send_event, abrí el archivo en VSCode (code ~/.claude/settings.json) y borrá ese bloque de hook, o cambiá python por python3 si querés conservarlo (no necesario Day 1). Después Cmd+Q + reabrir Claude.

Aliases disponibles

AliasComando
gsgit status
gpgit pull
gcgit commit -m
cdsccd ~/Code/sharkcode
cdwtcd ~/Code/Wedding-Templates
devbun dev
cclaude
11

Test final ambient end-to-end (Wave 3 esteso)

7 verifiche che ambient è perfetto: zsh + alias + Sharkcode + Claude ES + memory-shared + hooks attivi + workspace + Wedding-Templates.

11.1 zsh brand prompt + alias funzionano

# Vedi prompt Sharkcode (linea blu/magenta con shark logo)
cdsc                  # alias = cd ~/Code/sharkcode
gs                    # alias = git status (deve mostrare branch main + clean)
gl                    # alias = git log oneline -10

✓ Se alias funzionano + prompt mostra brand Sharkcode = zshrc-noelia attivo OK.

11.2 Hello-world Claude Code (ES default + memorias via symlink 10.5)

cdsc
claude "Hola Claude, soy Noelia. Listame los archivos en este directorio y citá la memoria del perfil ansioso de Mary."

✓ Atteso: risposta ES + lista file + descrizione corretta della memoria (Mary cliente ansioso, batch 1 respuesta/día). Se risponde EN = settings.json non attivo, re-run Step 3 + restart. Se dice che NON trova memorie = manca il symlink, re-fai Step 10.5.

11.3 Verify hooks attivi (Wave 3 fix)

# Lista hook installati
ls ~/.claude/hooks/

# Atteso: 10 file (auto-retrieval-preload.mjs + protected-paths-block + desktop-notification + ecc.)
# Verify settings.json registra hook
cat ~/.claude/settings.json | grep -E "UserPromptSubmit|PreToolUse|Stop|PostToolUse"

✓ Atteso: 10 file + 4 hook events registrati. Se settings.json vuoto, re-run Step 10.3 setup-mac-user-scope.sh.

11.4 Verify VSCode workspace multi-root abierto

VSCode dovrebbe mostrare sidebar left con 5 folder colorati: 🦈 Sharkcode OS + 💍 Wedding-Templates + 🪶 Pinna + 🛍️ Etsy Noelia + 📋 Atelier Noelia docs. Se solo 1 folder → re-run Step 10.2 code ~/Code/noelia.code-workspace.

11.5 Hello-world Wedding-Templates pnpm

cdwt
git checkout master   # NO main, master è branch default
ls templates/         # vedi 5 templates production + 1 draft
pnpm --version        # verify pnpm installato Step 2

11.6 Verify memory-shared/ + agenti + skill project scope (CRITICO Wave 3)

cdsc
ls memory-shared/ | wc -l           # ~90 file memorie cross-cliente
ls .claude/agents/*.md | wc -l      # ~47 agenti Sharkcode OS
ls .claude/skills/ | wc -l          # ~83 project skill (inclusi cluster Phase 106.7 mandatory)
ls .claude/commands/*.md | wc -l    # ~24 slash commands OS

✓ Tutti numeri devono essere > 0. Garantisce Claude main session ha accesso a agenti + skill + commands Sharkcode OS via project scope.

11.7 Verify topic injection hooks via test prompt Claude (Wave 3 fix)

claude "Dime cuáles son las decisiones cementadas sobre el setup de Noelia."

✓ Atteso: risposta Claude cita le decisioni del setup (Bitwarden free, Mac dedicato, Canva free Day 1, ecc.) da reference_noelia_setup_choices.md. Se NON le trova = manca il symlink Step 10.5 OPPURE l'hook auto-retrieval non è attivo (re-run Step 10.3 + Cmd+Q restart).

12

Backup + Password manager + storage check

Storage libre

Apple menu → Acerca de esta Mac → Almacenamiento. Con 123GB libres de partida y un setup que pesa ~5,5GB, vas a quedar cómodamente arriba de 110GB libres. No hay problema de espacio.

Backup dual: Time Machine + iCloud Drive

Estrategia decidida Michel sera tardi 7: dual layer para resiliencia (Mac muere → recuperación garantizada).

Time Machine (disco externo, ~80 EUR one-time)

  1. Conectar SSD externo 1TB+ (recomendado: SanDisk Extreme Portable o equivalente)
  2. System Settings → Time Machine → Add Backup Disk → seleccionar disco externo
  3. Activar "Back Up Automatically"
  4. Primer backup full ~1-3h dependiendo de cuánto hay en el Mac. Después incrementales automatic cada hora.

iCloud Drive (cloud, ~3 EUR/mese plan 200 GB)

  1. System Settings → Apple ID → iCloud → activar iCloud Drive
  2. Si plan actual es 5 GB free: upgrade a 200 GB (~2.99 EUR/mese). Settings → Apple ID → iCloud → Manage Storage → Change Storage Plan.
  3. NO actives Desktop & Documents Folders sync por default (puede mover archivos de trabajo a la nube y romper paths locales del repo). Si querés liberar espacio activá Optimise Mac Storage, no el sync de Desktop/Documents.
  4. Los archivos Canva exports + designs locales pueden vivir en iCloud Drive sin problema, accesibles también desde iPhone. Pero el repo (~/Code) NUNCA en iCloud sync.
Por qué dual: si Mac muere y disco TM también muere mismo evento (poco probable pero posible), iCloud Drive te recupera todo en cloud. Si Mac muere solo, TM restore full system en otro Mac en ~2h. Belt + suspenders strategy.

Bitwarden Password Manager (Free, open-source)

Para gestionar 10+ credenciales (GitHub + Etsy + PayPal + Canva + Cloudflare + Apple ID + Bitwarden master + etc).

brew install --cask bitwarden
  1. Abrir Bitwarden app después install
  2. Click "Create Account" → email tuyo + master password fuerte (16+ caracteres, frase memorable)
  3. Anotar master password en lugar seguro físico (papel, no digital). Si la perdés, perdés todo el vault.
  4. Install extension Chrome también: Bitwarden Free Password Manager
  5. Login en extension con mismas credenciales → auto-fill funciona en todos sitios
Workflow Bitwarden: cada vez que creás account nuevo (GitHub, Etsy, PayPal, etc), Bitwarden propone generar password fuerte aleatoria + guardarla. Vos solo necesitás recordar el master password. Costo 0 EUR (plan Free suficiente para uso personal solo).

✓ Checkpoint Phase 1 exit

Si marcaste los 12 steps arriba, ya completaste Phase 1 Setup. Próximo paso: Welcome App Tutorial →

El tutorial es 2-3h, autónoma. Con Claude vas a hacer 5 ejercicios reales (Etsy research + ideas + traducción + git commit via Claude). NO aprendés código, aprendés a usar Claude conversacional.

🚨 Troubleshooting común (Wave 4 expand)

Casos base (Step 1-7)

command not found: brew

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc

Permission denied (publickey) al clonar

SSH key no agregada bien. Repetir Step 5.2-5.5 carefully (OR verifica Day 0 prep TUTORIAL-GITHUB-DAY-0 done + Michel ti ha invitato Collaborator).

command not found: bun OR pnpm

# Bun PATH manuale
echo 'export BUN_INSTALL="$HOME/.bun"' >> ~/.zshrc
echo 'export PATH="$BUN_INSTALL/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# pnpm install via npm
npm install -g pnpm

VSCode muy lento / Out of memory / Mac muy lento

8GB RAM tight. Cerrar Chrome tabs no necesarias. Cerrar otras apps. Reiniciar Mac. Verificar que ningún dev server quedó en background:

ps aux | grep -E "astro|vite|bun|pnpm" | grep -v grep
# Per kill: kill -9 [PID]

Casos Wave 4 (Step 10 + 11)

Hook auto-retrieval NO triggera Topic Matches en Claude response

Verifica registrazione hook + restart Claude Code:

# 1. Verifica hook installato
ls ~/.claude/hooks/auto-retrieval-preload.mjs

# 2. Verifica settings.json registra hook
cat ~/.claude/settings.json | grep -A 5 "UserPromptSubmit"

# 3. Verifica env attivo
echo $SHARKCODE_AUTO_RETRIEVAL  # deve restituire "1"

# 4. Restart Claude Code (Cmd+Q + riapri)
# 5. Test prompt + check Topic Matches inietta

Se ancora fail: re-run bash ~/Code/sharkcode/tools/atelier-noelia/setup-mac-user-scope.sh.

Tavily MCP error TAVILY_API_KEY undefined

API key non settata. Signup free tier + setup .env:

# 1. Signup https://tavily.com (free tier 1000 req/mese)
# 2. Dashboard → API Keys → Create → copy key
# 3. Aggiungi a ~/.zshrc (uncomment riga template):
echo 'export TAVILY_API_KEY="tvly-YOUR-KEY-HERE"' >> ~/.zshrc
source ~/.zshrc

# 4. Restart Claude Code per pick up env var

VSCode workspace NON multi-root abierto (vedi solo 1 folder sharkcode)

Step 10.2 workspace copy mancante:

cp ~/Code/sharkcode/.planning/business/atelier-noelia/dotfiles/noelia.code-workspace ~/Code/noelia.code-workspace
code ~/Code/noelia.code-workspace

VSCode chiede "Open workspace?" → click Yes. Sidebar mostra 5 folder.

markitdown-mcp / sharkcode-local-llm errore startup Claude Code (Win-only)

Errore log noisy. La via correcta es deshabilitarlos via disabledMcpjsonServers en settings.local.json (NO .mcp.json.local, que Claude Code no lee). Ver Step 10.6. Quick fix:

cd ~/Code/sharkcode
cat > .claude/settings.local.json <<'JSON'
{
  "disabledMcpjsonServers": ["markitdown-mcp", "sharkcode-local-llm"]
}
JSON
# Cmd+Q + reabrir Claude

setup-mac-user-scope.sh fails 1 step (es. hook copy permission denied)

Verifica permissions ~/.claude/ + retry:

mkdir -p ~/.claude/hooks
chmod 755 ~/.claude ~/.claude/hooks
bash ~/Code/sharkcode/tools/atelier-noelia/setup-mac-user-scope.sh

VSCode settings.json non applica (claudeCode default lang EN)

File copy fallito OR conflict. Overwrite manuale:

cp ~/Code/sharkcode/.planning/business/atelier-noelia/dotfiles/vscode-settings.json "$HOME/Library/Application Support/Code/User/settings.json"
# Restart VSCode (Cmd+Q + riapri)

Claude Code "rate limited" (sub Max compartido Michel)

Quota weekly Max shared. Esperar 1-2 min OR coordinar con Michel (lui pausa work tuo). Se persistente: Guest Pass option (Michel genera /passes command in suo Claude Code).

Claude NO cita ninguna memoria (memory-shared no se carga)

Causa real: falta el symlink nativo del Step 10.5. SHARKCODE_MEMORY_DIR por sí sola NO carga las memorias en Claude Code nativo. Verifica el symlink:

# 1. Confirmar que la carpeta de memorias existe y tiene ~90 archivos
ls ~/Code/sharkcode/memory-shared | wc -l   # ~90

# 2. Ver el proyecto nativo de Claude y su symlink memory
PROJ=$(ls -dt ~/.claude/projects/*sharkcode* 2>/dev/null | head -1)
ls -la "$PROJ/memory"   # debe ser un symlink -> .../memory-shared

# 3. Si NO es symlink (o no existe), rehacerlo:
rm -rf "$PROJ/memory"
ln -s ~/Code/sharkcode/memory-shared "$PROJ/memory"

# 4. Test: claude "cita la memoria del perfil ansioso de Mary"
?