docs(claude): correct import alias and document this checkout's real state

.claude/CLAUDE.md

@@ -106,6 +106,38 @@ O AIOX usa um modelo de 4 camadas (L1-L4) para separar artefatos do framework e
 
 ---
 
+<!-- PROJECT-CUSTOMIZED: Safe to modify for your project -->
+## Notas do Contribuidor (estado real deste checkout)
+
+**Boundary L1-L4 está OFF neste repo agora.** `.aiox-core/core-config.yaml` → `boundary.frameworkProtection: false` (comentário no arquivo: "TEMPORARY: TOK-3 contributor mode"). Ou seja, as deny rules do L1/L2 acima (nunca editar `.aiox-core/core/`, `bin/aiox.js`) **não estão ativas neste checkout** — faz sentido, já que este É o repo fonte do framework, não um projeto que o instalou. `protected`/`exceptions` (fonte de verdade do boundary) vivem no mesmo `core-config.yaml`; mudar o valor sozinho não adiciona/remove deny rules em `.claude/settings.json` — isso exige reexecutar o installer.
+
+**Mapa de `.aiox-core/core/`** (27 subpastas — o "motor" do framework):
+- `orchestration/` — invoca agentes, coordena builds (`bob-orchestrator`, `brownfield-handler`)
+- `execution/` — motor de execução (`autonomous-build-loop`, `parallel-executor`), chamado por `orchestration/`
+- `synapse/` — engine de contexto de sessão (context/diagnostics/domain/memory layers)
+- `memory/` — persistência de `MEMORY.md` por agente (`gotchas-memory.js`)
+- `resilience/` — Agent Immortality Protocol (recuperação após falha fatal de agente)
+- `health-check/` + `doctor/` — checks + healers de autodiagnóstico/reparo (cobertos por `test:health-check`, não pelo jest)
+- `quality-gates/` — layer1-precommit, layer2-pr-automation, human-review-orchestrator
+- `registry/` — Service Registry (catálogo de workers/tasks/templates/scripts)
+- `ids/` — Entity Registry do Incremental Development System
+- `mcp/` — config/symlink de servidores MCP
+- `code-intel/`, `permissions/`, `manifest/`, `errors/` — client de code intel; operation-guard/permission-mode; gerador/validador do install manifest; aiox-error/error-registry
+- `elicitation/` + `session/` — prompting interativo + detecção de contexto (ver `.aiox-core/core/README.md` para detalhe completo)
+- `graph-dashboard/` e `external-executors/` — CLIs por trás de `bin/aiox-graph.js` e `bin/aiox-delegate.js`
+
+**CLI entry points (`bin/`):** `aiox.js` é o roteador principal (lê versão do `package.json`, despacha para `packages/installer/src/wizard/index.js`). `aiox-init.js` e `aiox-minimal.js` estão **deprecated** (fallback legado, remoção prevista v5.0.0) — não construir sobre eles.
+
+**Monorepo `packages/*` (npm workspaces):** `aiox-install` (instalador NPX), `aiox-pro-cli` (CLI do AIOX Pro), `installer` (wizard greenfield/brownfield), `gemini-aiox-extension` (sem package.json — arquivos de extensão crus). `apps/dashboard/`, citado no README, **não existe neste checkout**. `squads/` só tem `_example` e `claude-code-mastery` localmente (catálogo completo é distribuído via package publicado). `pro/` é git submodule (`SynkraAI/aiox-pro.git`) **não inicializado** aqui.
+
+**`docs/stories/` na prática:** não há split `active/`/`completed/` como o README sugere — é um diretório por epic (`epic-<n>-<slug>/`), cada um com `EPIC-<n>-<SLUG>.md` + `STORY-<epic>.<n>-<SLUG>.md`. Stories não iniciadas ficam em `docs/stories/backlog` (`core-config.yaml` → `storyBacklog.location`).
+
+**`.claude/rules/*.md` além de `agent-authority.md`, `mcp-usage.md`, `tool-examples.md`, `agent-handoff.md`:** `agent-memory-imports.md`, `coderabbit-integration.md`, `handoff-consolidation.md`, `ids-principles.md`, `story-lifecycle.md`, `tool-response-filtering.md`, `workflow-execution.md` — maioria usa frontmatter `paths:` e só carrega ao tocar nos arquivos correspondentes.
+
+**`.cursor/rules/agents/*.mdc` são artefatos gerados** por `npm run sync:ide:cursor` a partir de `.aiox-core/development/agents/` — não editar à mão.
+
+---
+
 <!-- FRAMEWORK-OWNED: Generated by AIOX installer, do not customize -->
 ## Sistema de Agentes
 
@@ -174,13 +206,13 @@ Use prefixo `*` para comandos:
 | Interfaces | PascalCase + sufixo | `WorkflowListProps` |
 
 ### Imports
-**Sempre use imports absolutos.** Nunca use imports relativos.
+**Sempre use imports absolutos, nunca relativos.** O único alias válido neste repo é `aiox-core/*` (também espelhado como `@aiox-core/*` em `jest.config.js` `moduleNameMapper`, embora só `aiox-core`/`aiox-core/*` estejam declarados em `tsconfig.json` `paths`). O alias `@/*` citado em templates genéricos de React **não existe neste checkout** — pertence a `apps/dashboard/`, que não está presente aqui. Não há regra ESLint (`no-restricted-imports` ou similar) que force o uso de imports absolutos — é convenção, não gate automático.
 ```typescript
 // ✓ Correto
-import { useStore } from '@/stores/feature/store'
+import { AgentInvoker } from 'aiox-core/orchestration/agent-invoker'
 
 // ✗ Errado
-import { useStore } from '../../../stores/feature/store'
+import { AgentInvoker } from '../../../.aiox-core/core/orchestration/agent-invoker'
 ```
 
 **Ordem de imports:**
@@ -221,6 +253,12 @@ npm run lint                # ESLint
 npm run typecheck           # TypeScript
 ```
 
+### Rodando um teste único
+```bash
+npx jest caminho/para/arquivo.test.js -t "nome do teste"
+```
+`jest.config.js` é single-project. `testPathIgnorePatterns` exclui deliberadamente arquivos específicos de testes legados em quarentena (não os diretórios inteiros) — ex.: `tests/tools/backward-compatibility.test.js`, `tests/tools/clickup-helpers.test.js` (débito técnico OSR-10/migração v2.1 → v4.31.0), além de `pro/` (roda via CI `pro-integration.yml`, não localmente) e testes Windows-only. Thresholds de cobertura: `global` = 19% branches / 22% functions, lines, statements; `.aiox-core/core/` = 38% lines — comentários no config marcam esses valores como "TEMPORARY". `npm run test:health-check` roda **mocha** (não jest) sobre `tests/health-check/**` — cobre o engine/healers/reporters de `.aiox-core/core/health-check/`, mantido separado porque o próprio `jest.config.js` exclui `.aiox-core/core/health-check/checks/**` da cobertura como candidato a teste de integração.
+
 ### Quality Gates (Pre-Push)
 Antes de push, todos os checks devem passar:
 ```bash