ADVANCED GUIDE · v1.6.2 · Bombelli

Guia Avançado

Tudo que um desenvolvedor ou power user precisa saber para extrair o máximo do Imaginne.

🏗️ Arquitetura

O Imaginne é composto por 6 camadas:

Camada	Responsabilidade
Interface	TUI (Bubble Tea) ou Desktop (Wails v2). Aceita texto e voz.
Rationalizer	Orquestrador central. Monta prompt, gerencia contexto, executa tool loop (até 10 iterações por turno).
Modelos	3 modelos [N]umbers via gateway seguro. Chaves de provedor ficam no servidor.
Tools	30+ ferramentas nativas: Read, Write, Edit, Execute, Grep, Glob, WebFetch, TodoWrite, etc.
Subagentes	7 tipos especializados (explorer, analyzer, reviewer, implementer, tester, refactorer, documenter).
Workspace	`.imaginne/` — PROJECT.md, RULES.yaml, MEMORY.md, skills/, hooks/, commands/.

🤖 Modelos & Soberania de IA

O Imaginne opera sob o princípio de Soberania de IA: nenhuma chave de provedor reside no cliente. Sua chave imn_xxx autentica contra a infraestrutura da [N]umbers, que roteia para o modelo certo usando chaves internas isoladas no servidor.

⚡

[N]umbers

nnumbers — Uso geral. Rápido e versátil. Código, conversação, tarefas do dia a dia. Raciocínio implícito.

🧠

[N]umbers R1

nnumbers-r1 — Raciocínio profundo com chain-of-thought. Arquitetura, debugging complexo, análise crítica.

💻

[N]umbers Code

nnumbers-code — Especializado em código com thinking mode visível. Refatoração, geração e análise.

Troque com /model ou Ctrl+B. O contexto é preservado entre trocas de modelo — o sistema traduz o histórico para o formato do novo modelo automaticamente.

📌No Desktop, os modelos disponíveis são [N]umbers, [N]umbers R1, [N]umbers Code e Opus. O seletor fica em Settings → Info.

🎛️ Níveis de Autonomia

Nível	Lê	Escreve	Executa	Quando usar
low	Pede	Pede	Pede	Ambiente de produção, aprendizado
medium	Livre	Pede	Pede	Desenvolvimento com controle de escrita
high	Livre	Livre	Livre	Projetos pessoais, automação batch

Altere com /autonomy ou Ctrl+A. O nível persiste na sessão.

🔧 Sistema de Tools

O Imaginne possui 30+ ferramentas nativas organizadas em tiers:

📄

Leitura/Escrita

Read Write Create Edit MultiEdit Append BatchWrite

⚙️

Sistema/Execução

Execute Stat Move Copy Delete Mkdir Tail

🔍

Busca/Web

LS Grep Glob Explore WebSearch WebFetch

📓

Notebooks

NotebookRead NotebookWrite NotebookEdit

📋

Gestão

TodoWrite (tarefas) Task (subagentes) DeliverPlan (planos)

💡A política de segurança impede escrita de arquivos via Execute (redirecionamentos como >, >>, tee são bloqueados). O Imaginne usa Read/Write/Edit para operações de arquivo — nunca o shell.

🎯 Core Skills

/strategy — Análise Estratégica

9 frameworks disponíveis: SWOT, Porter Five Forces, PESTEL, Blue Ocean, BCG Matrix, Ansoff Matrix, Value Chain, McKinsey 7S, Balanced Scorecard.

/strategy swot "startup de fintech"
/strategy porter "mercado de delivery"
/strategy pestel "indústria farmacêutica"Imaginne

/ppt — Apresentações PowerPoint

278+ templates profissionais em 20+ categorias. Geração automática com dados reais.

/ppt "revisão trimestral Q1 2026"
/ppt list                              # Navegar categorias
/ppt-auto "plano de negócios 2026"     # Modo totalmente automáticoImaginne

⚙️ Skills Avançadas

Skills são automações reutilizáveis definidas por SKILL.yaml + SKILL.md. Repositório com 51+ skills em 13 categorias.

/skill install download-image    # Instalar do repositório
/skill list                      # Listar instaladas
/skill info download-image       # Ver detalhes
/skill remove download-image     # RemoverImaginne

Skills podem ter modos (Platform, Module, Routine) e hooks (pre.sh, post.sh).

🪝 Hooks

Hooks executam ações automáticas em eventos do ciclo de vida. Configure em .imaginne/hooks.yaml:

Hook	Quando dispara
`on_session_start`	Ao iniciar o Imaginne
`on_session_end`	Ao sair
`pre_edit` / `post_edit`	Antes/depois de editar arquivo
`pre_skill` / `post_skill`	Antes/depois de executar skill
`on_error`	Quando ocorre erro

🛡️ Firewall

O firewall bloqueia operações em caminhos e comandos perigosos. Configure em RULES.yaml:

firewall:
  blocked_paths:
    - .env
    - "*.key"
    - .git
    - node_modules
  blocked_commands:
    - "rm -rf /"RULES.yaml

Regras internas (sempre ativas): deny_rm_rf, deny_system_files, deny_credentials. Validação word-boundary com regex. Shell-aware (Bash, PowerShell, Cmd).

🧠 Memória & Contexto

Camada	Arquivo	Comportamento
Hot	MEMORY.md	Sempre carregado. Fatos e decisões que persistem entre sessões.
Warm	PROJECT.md + RULES.yaml	Carregados no início da sessão. Contexto do projeto e regras.
Cold	Histórico compactado	Automaticamente resumido quando o contexto atinge o limite. Use `/compact` para forçar.

Use /sync para gerar um SNAPSHOT.md com o estado atual do projeto.

🔄 Workflows

/iterate — Debate entre Modelos

Dentro do modo /plan, quando um plano aparece, pressione I para que um segundo modelo critique e refine o plano original.

/plan — Planejamento

Ative com Shift+Tab. O Imaginne cria um plano estruturado antes de executar. Opções: Y (aprovar), E (editar), I (iterar com outro modelo), N (rejeitar).

/ask — Investigação

Modo somente leitura. O Imaginne explora e lê arquivos sem modificar nada. Ideal para entender código antes de fazer mudanças.

💻 Subagentes

Subagentes são instâncias especializadas que executam tarefas em paralelo:

Tipo	Função
explorer	Navega e mapeia estrutura do projeto
analyzer	Analisa código e dados em profundidade
reviewer	Revisão de código e sugestões
implementer	Implementa funcionalidades
tester	Cria e roda testes
refactorer	Refatora código existente
documenter	Gera documentação

/agent explorer "mapeie a estrutura do módulo de pagamentos"
/agent list     # Ver subagentes ativosImaginne

🎙️ Entrada por Voz

O Imaginne suporta entrada por voz via STT (speech-to-text) processado nos servidores da [N]umbers. O áudio nunca é armazenado.

Como usar

Pressione F2 ou Ctrl+C → fale → a transcrição aparece em tempo real no campo de entrada → pressione novamente para parar → revise e envie com Enter.

Arquitetura

O Imaginne captura áudio do microfone, detecta quando você está falando e transmite para os servidores da [N]umbers, que fazem a transcrição. A autenticação usa sua chave imn_xxx. Resultados parciais e finais aparecem em tempo real no campo de entrada.

Plataformas

macOS: prompt de permissão de microfone no primeiro uso (requer NSMicrophoneUsageDescription no Info.plist do app Desktop).
Windows: ative em Configurações → Privacidade → Microfone → Permitir apps desktop.
Linux: funciona automaticamente se o sistema de áudio estiver disponível.

⚙️ Configuração

Arquivo: ~/.imaginne/config.yaml

cloud:
  endpoint: https://imaginne.nnumbers.com.br/api
  api_key: imn_xxx...

llm:
  model: nnumbers-code    # Modelo padrão
  max_tokens: 16000       # Máximo de tokens por resposta
  temperature: 0          # 0 = determinísticoconfig.yaml

Variáveis de Ambiente

Variável	Função
`IMAGINNE_API_KEY`	Chave API (alternativa ao config.yaml)
`IMAGINNE_DEBUG`	Ativa logs de debug em stderr
`IMAGINNE_DEBUG_WIRE`	Grava log wire-level (SSE, request, response) em `~/.imaginne/wire-debug.log`

🔍 Troubleshooting

Problema	Solução
API key inválida	Verifique `~/.imaginne/config.yaml`. Obtenha nova em imaginne.nnumbers.com.br
Modelo lento (>15s)	Normal para [N]umbers R1 (chain-of-thought). Para respostas rápidas, use `/model nnumbers`.
Voz não funciona (macOS)	Aceite o prompt de permissão de microfone. Se já negou, vá em System Settings → Privacy → Microphone.
Voz não funciona (Windows)	Settings → Privacy → Microphone → Allow desktop apps. Não há prompt automático.
Voz não funciona (Linux)	Verifique se o microfone está conectado e se outro aplicativo de áudio (ex: gravador de voz do sistema) funciona. Se não, verifique as configurações de áudio do sistema.
Voz não funciona (SSH)	Não é possível. SSH não tunela áudio do microfone local. Use sessão física.
Tool call não executa	O modelo pode ter emitido um formato não nativo. O normalizer recupera XML/DSML/freestyle automaticamente. Se persistir, ative `IMAGINNE_DEBUG_WIRE=1` e inspecione `~/.imaginne/wire-debug.log`.
Crash (SIGKILL) no macOS	Binário precisa de ad-hoc codesign: `codesign --sign - --force /usr/local/bin/imaginne`
Context cheio	O Imaginne compacta automaticamente. Para forçar: `/compact`.
Atualizar versão	Re-execute o comando de instalação. O binário é substituído automaticamente.

ADVANCED GUIDE · v1.6.2 · Bombelli

Advanced Guide

Everything a developer or power user needs to know to get the most out of Imaginne.

🏗️ Architecture

Imaginne is composed of 6 layers:

Layer	Responsibility
Interface	TUI (Bubble Tea) or Desktop (Wails v2). Accepts text and voice.
Rationalizer	Central orchestrator. Builds prompt, manages context, runs tool loop (up to 10 iterations per turn).
Models	3 [N]umbers models via secure gateway. Provider keys stay server-side.
Tools	30+ native tools: Read, Write, Edit, Execute, Grep, Glob, WebFetch, TodoWrite, etc.
Subagents	7 specialized types (explorer, analyzer, reviewer, implementer, tester, refactorer, documenter).
Workspace	`.imaginne/` — PROJECT.md, RULES.yaml, MEMORY.md, skills/, hooks/, commands/.

🤖 Models & AI Sovereignty

Imaginne operates under the principle of AI Sovereignty: no provider keys reside on the client. Your imn_xxx key authenticates against the [N]umbers infrastructure, which routes to the right model using internal keys isolated on the server.

⚡

[N]umbers

nnumbers — General purpose. Fast and versatile. Code, conversation, everyday tasks. Implicit reasoning.

🧠

[N]umbers R1

nnumbers-r1 — Deep reasoning with chain-of-thought. Architecture, complex debugging, critical analysis.

💻

[N]umbers Code

nnumbers-code — Code-specialized with visible thinking mode. Refactoring, generation and analysis.

Switch with /model or Ctrl+B. Context is preserved across model switches — the system translates history to the new model's format automatically.

📌On Desktop, available models are [N]umbers, [N]umbers R1, [N]umbers Code and Opus. The selector is in Settings → Info.

🎛️ Autonomy Levels

Level	Read	Write	Execute	When to use
low	Asks	Asks	Asks	Production environments, learning
medium	Free	Asks	Asks	Development with write control
high	Free	Free	Free	Personal projects, batch automation

Change with /autonomy or Ctrl+A. Persists for the session.

🔧 Tool System

Imaginne has 30+ native tools organized in tiers:

📄

Read/Write

Read Write Create Edit MultiEdit Append BatchWrite

⚙️

System/Execution

Execute Stat Move Copy Delete Mkdir Tail

🔍

Search/Web

LS Grep Glob Explore WebSearch WebFetch

📓

Notebooks

NotebookRead NotebookWrite NotebookEdit

📋

Management

TodoWrite (tasks) Task (subagents) DeliverPlan (plans)

💡Security policy prevents file writes via Execute (redirections like >, >>, tee are blocked). Imaginne uses Read/Write/Edit for file operations — never the shell.

🎯 Core Skills

/strategy — Strategic Analysis

9 frameworks: SWOT, Porter Five Forces, PESTEL, Blue Ocean, BCG Matrix, Ansoff Matrix, Value Chain, McKinsey 7S, Balanced Scorecard.

/strategy swot "fintech startup"
/strategy porter "delivery market"
/strategy pestel "pharma industry"Imaginne

/ppt — PowerPoint Presentations

278+ professional templates in 20+ categories. Automatic generation with real data.

/ppt "quarterly business review Q1 2026"
/ppt list                                # Browse categories
/ppt-auto "business plan 2026"           # Fully automatic modeImaginne

⚙️ Advanced Skills

Skills are reusable automations defined by SKILL.yaml + SKILL.md. Repository with 51+ skills in 13 categories.

/skill install download-image    # Install from repository
/skill list                      # List installed
/skill info download-image       # View details
/skill remove download-image     # RemoveImaginne

Skills can have modes (Platform, Module, Routine) and hooks (pre.sh, post.sh).

🪝 Hooks

Hooks execute automatic actions on lifecycle events. Configure in .imaginne/hooks.yaml:

Hook	When it fires
`on_session_start`	When Imaginne starts
`on_session_end`	On exit
`pre_edit` / `post_edit`	Before/after editing a file
`pre_skill` / `post_skill`	Before/after running a skill
`on_error`	When an error occurs

🛡️ Firewall

The firewall blocks operations on dangerous paths and commands. Configure in RULES.yaml:

firewall:
  blocked_paths:
    - .env
    - "*.key"
    - .git
    - node_modules
  blocked_commands:
    - "rm -rf /"RULES.yaml

Internal rules (always active): deny_rm_rf, deny_system_files, deny_credentials. Word-boundary regex validation. Shell-aware (Bash, PowerShell, Cmd).

🧠 Memory & Context

Layer	File	Behavior
Hot	MEMORY.md	Always loaded. Facts and decisions that persist across sessions.
Warm	PROJECT.md + RULES.yaml	Loaded at session start. Project context and rules.
Cold	Compacted history	Automatically summarized when context hits the limit. Use `/compact` to force.

Use /sync to generate a SNAPSHOT.md with the current project state.

🔄 Workflows

/iterate — Model Debate

Inside /plan mode, when a plan appears, press I so a second model critiques and refines the original plan.

/plan — Planning

Activate with Shift+Tab. Imaginne creates a structured plan before executing. Options: Y (approve), E (edit), I (iterate with another model), N (reject).

/ask — Investigation

Read-only mode. Imaginne explores and reads files without modifying anything. Ideal for understanding code before making changes.

💻 Subagents

Subagents are specialized instances that run tasks in parallel:

Type	Function
explorer	Navigates and maps project structure
analyzer	Deep analysis of code and data
reviewer	Code review and suggestions
implementer	Implements features
tester	Creates and runs tests
refactorer	Refactors existing code
documenter	Generates documentation

/agent explorer "map the payments module structure"
/agent list     # View active subagentsImaginne

🎙️ Voice Input

Imaginne supports voice input via STT (speech-to-text) processed on [N]umbers servers. Audio is never stored.

How to use

Press F2 or Ctrl+C → speak → transcription appears in real-time in the input field → press again to stop → review and send with Enter.

Architecture

Imaginne captures audio from the microphone, detects when you're speaking and transmits it to [N]umbers servers, which perform the transcription. Authentication uses your imn_xxx key. Partial and final results appear in real-time in the input field.

Platforms

macOS: prompts for microphone permission on first use (requires NSMicrophoneUsageDescription in the Desktop app's Info.plist).
Windows: enable in Settings → Privacy → Microphone → Allow desktop apps.
Linux: works automatically if the audio system is available.

⚙️ Configuration

File: ~/.imaginne/config.yaml

cloud:
  endpoint: https://imaginne.nnumbers.com.br/api
  api_key: imn_xxx...

llm:
  model: nnumbers-code    # Default model
  max_tokens: 16000       # Max tokens per response
  temperature: 0          # 0 = deterministicconfig.yaml

Environment Variables

Variable	Purpose
`IMAGINNE_API_KEY`	API key (alternative to config.yaml)
`IMAGINNE_DEBUG`	Enable debug logging to stderr
`IMAGINNE_DEBUG_WIRE`	Write wire-level log (SSE, request, response) to `~/.imaginne/wire-debug.log`

🔍 Troubleshooting

Problem	Solution
Invalid API key	Check `~/.imaginne/config.yaml`. Get a new one at imaginne.nnumbers.com.br
Slow model (>15s)	Normal for [N]umbers R1 (chain-of-thought). For fast responses, use `/model nnumbers`.
Voice not working (macOS)	Accept the microphone permission prompt. If denied, go to System Settings → Privacy → Microphone.
Voice not working (Windows)	Settings → Privacy → Microphone → Allow desktop apps. No automatic prompt.
Voice not working (Linux)	Check that the microphone is connected and that another audio app (e.g., system voice recorder) works. If not, check your system audio settings.
Voice not working (SSH)	Not possible. SSH doesn't tunnel local microphone audio. Use a physical session.
Tool call not executing	The model may have emitted a non-native format. The normalizer recovers XML/DSML/freestyle automatically. If it persists, enable `IMAGINNE_DEBUG_WIRE=1` and inspect `~/.imaginne/wire-debug.log`.
Crash (SIGKILL) on macOS	Binary needs ad-hoc codesign: `codesign --sign - --force /usr/local/bin/imaginne`
Context full	Imaginne compacts automatically. To force: `/compact`.
Update version	Re-run the installation command. The binary is replaced automatically.

📄 This document was generated by Imaginne — AI development assistant by [N]umbers