InkGraph

O InkGraph é um estúdio literário open-source local-first, motor de construção de mundos (worldbuilding) e gerenciador de lore epistêmica — utilizável 100% offline/sem IA na nuvem ou integrado via Model Context Protocol (MCP) em stdio.

Projetado sob a filosofia de Design Silencioso e Responsabilidade Única (SRP), o projeto combina um estúdio visual em React com editor CodeMirror 6 (MIT), controle de versões local por ramificações com diff visual linha/palavra, grafo de relações 2D, mapas mentais 360°, compilador de memória em 4 camadas e motor de indexação SQLite/FTS5 sobre cofres Markdown (./workspace/).

Sumário

• Recursos Implementados (Fases 1 a 4)

• Arquitetura do Monorepo

• Como Começar

  • Pré-requisitos

  • Instalação

  • Executando o Estúdio Web

  • Executando o Servidor MCP

  • Verificação de Tipos, Build e Testes

• Estrutura do Cofre e Frontmatter YAML

• Servidor MCP Nativo (@inkgraph/mcp)

• Documentação e Padrões do Repositório

• Créditos e Licença

Related MCP server: Continuity by Ouroboros Apps

Recursos Implementados (Fases 1 a 4)

• Meu Espaço & Cabeçalho Navegável:

  • Catálogo multi-workspace com criação, duplicação, favoritos, arquivo e importação/exportação JSON.

  • Breadcrumb com Triplo Clique: clicar 3 vezes sobre a trilha (InkGraph / ...) abre edição direta de caminho estilo pastas com autocompletar e truncamento responsivo em telas estreitas.

  • Botão Salvar & Verificar: posicionado ao lado direito da pesquisa global (Ctrl+K), executa gravação imediata (flush), relê os dados no armazenamento local (localStorage / IndexedDB) e confirma a integridade visualmente.

• Tematização Dual-Mode, 26 Atalhos & Configurações Explícitas:

  • 6 paletas com suporte a Claro | Escuro | Sépia, fonte/escala/cantos da interface, barra lateral retrátil em acordeão e SettingsSaveBar confirmando alterações em todas as abas.

  • Central de 26 atalhos de teclado editáveis em 4 categorias com gravação ao vivo e detecção de conflitos, além da aba Sobre com diagnóstico do armazenamento local e créditos Open Source.

• Painel Vivo, Grafo 2D, Mapas Mentais 360° & Quadro de Cenas:

  • Gráficos SVG interativos no Painel e no Rastreador de Progresso (hover rico com tooltip e clique direto para a cena/módulo correspondente) e Curva de Tensão interativa.

  • Grafo de Relações 2D (d3-force / react-force-graph-2d) com física calibrada, fixação de nós (fx/fy), foco de vizinhança de 1 salto (computeOneHopNeighborhood), duplo clique para o dossiê e inspetor lateral modular.

  • Mapas Mentais em SVG com pan livre 360°, zoom focado no cursor (0.35x–2.5x), curvas Bézier e criação de conexões no canvas; Quadro de Cenas em Três Atos, Tela 2D e Linha do Tempo.

• Controle de Versões Local & Fila de Staging (gitEngine.ts):

  • Popover direto no cabeçalho para alternar, criar ramificações e gravar instantâneos (snapshots) sem sair da tela atual.

  • Estado completo isolado por ramificação, diff determinístico LCS linha a linha e palavra por palavra (computeLineDiff, computeWordDiff), modal de mesclagem com resolução de conflitos (Manter Ramo Atual vs Adotar Ramo Fonte), Viagem no Tempo com backup automático pré-restauração e revisão visual em StagingGatekeeperPanel.

• Estúdio Markdown CodeMirror 6 (CodeMirrorEditorSurface.tsx):

  • 3 modos alternáveis (Escrever Markdown, Painel Dividido, Leitura Formatada), barra de formatação (H1–H3, negrito, itálico, epígrafe, checklist, divisor ***, blocos [!NOTA]/[!SEGREDO], comentários ocultos %%...%%).

  • Autocomplete contextual para @Personagem, #Local, &Facção, !Objeto e comandos /, localizar & substituir (Ctrl+F/Ctrl+H), modos Máquina de Escrever, Foco e Zen, leitura em voz alta (speechSynthesis) e inspetor lateral em PT-BR com checklist epistêmico.

• Memória em 4 Camadas & Copiloto Epistêmico (memoryCompiler.ts):

  • Compilação local de contexto em 4 camadas (1. Memória de Trabalho, 2. Memória Episódica & Epistêmica, 3. Memória Semântica, 4. Síntese Contínua & Voz), respeitando orçamento de tokens, detectando possíveis vazamentos epistêmicos na cena ativa e mantendo o envio externo bloqueado nos modos local e eco.

  • Sugestões de prosa enviadas para Staging com diff visual ou aplicadas ao rascunho após criação automática de snapshot de segurança.

• Construção Mundial em 10 Pilares Adaptativos & Atlas (WorldbuildingStudioView.tsx):

  • 10 pilares completos (Visão Geral, Geografia, Cultura, Política, Economia, História, Locais, Atlas / Mapas, Sistemas & Leis e Linha do Tempo) com sub-barra lateral retrátil em telas largas (>= 960px) e pílulas horizontais roláveis em janelas estreitas (< 960px).

  • Upload múltiplo de mapas (PNG, JPG, WebP, SVG) e plantas locais armazenados em IndexedDB (storageAdapter.ts), filtro de camadas temáticas, pinos arrastáveis por porcentagem (0–100%) e rotas visuais conectando locais.

• Notas Universais 1–10 (canonScoreCalculator.ts), Radar de Cânone (canonRadarEngine.ts) & Pré-Exportação:

  • Escala universal de maturidade de 1 a 10 (#ef4444 Esboço Inicial → #f59e0b Em Construção → #3b82f6 Consistente → #10b981 Cânone Maduro) com checklist acionável do que falta preencher em cada pilar e entidade.

  • Varredura ao vivo via "Escanear Tudo Agora" (Ctrl+Shift+R) detectando citações @/#/&/!, nomes compostos não catalogados, vínculos pendentes de cena e alertas epistêmicos, operando nos 3 níveis de permissão (Observador, Rascunho Staging e Auto-Catalogar Universo sem reescrever a prosa) com escopos granulares.

  • Auditoria pré-exportação (ExportPreflightCard.tsx) resumindo cenas em rascunho, propostas em Staging e alertas epistêmicos antes da compilação. Acompanhe o detalhamento no Guia do Usuário e nos Registros de Arquitetura.

Arquitetura do Monorepo

inkgraph/
├── .github/
│   ├── workflows/ci.yml       # Pipeline CI (isolamento de ./workspace/, typecheck, test, build)
│   ├── PULL_REQUEST_TEMPLATE.md
│   └── ISSUE_TEMPLATE/        # Templates padronizados de bug e melhoria
├── AGENTS.md                  # Constituição operacional de agentes e regras de arquitetura
├── CODE_OF_CONDUCT.md         # Código de conduta da comunidade (Contributor Covenant)
├── CONTRIBUTING.md            # Diretrizes de contribuição e SRP
├── LICENSE                    # Licença MIT
├── README.md                  # Documentação principal
├── SECURITY.md                # Política de segurança e proteção do cofre local
├── docs/
│   ├── STUDIO_TABS_REPORT.md  # Auditoria funcional, grau de uso e requisitos de todas as 22 abas
│   ├── USER_GUIDE.md          # Guia de uso, Markdown e referência dos 26 atalhos
│   └── architecture/
│       └── DECISIONS.md       # Registro de decisões arquiteturais (ADR 001)
├── packages/
│   ├── core/                  # Motor Node: parser Markdown/YAML, validação Zod e SQLite + FTS5
│   ├── mcp/                   # Servidor MCP via stdio conectado ao @inkgraph/core
│   ├── ui/                    # Estúdio visual React + Vite + CodeMirror 6 + motores puros em src/domain/
│   └── desktop/               # Scaffold desktop nativo em Tauri v2 (Rust + Webview, sem Electron)
└── workspace/                 # [IGNORADO NO GIT] Cofre privado local do autor

Como Começar

Pré-requisitos

• Node.js: v20.0.0 ou superior (v18+ suportado)

• pnpm: v9+ (ou corepack pnpm)

• Opcional (Desktop Nativo): Toolchain Rust (rustup) e dependências do Tauri v2 para @inkgraph/desktop

Instalação

git clone https://github.com/WiltonGabriel/inkgraph.git
cd inkgraph
pnpm install

Executando o Estúdio Web

pnpm dev

O servidor Vite inicia por padrão em http://localhost:5173.

Executando o Servidor MCP

Compile primeiro @inkgraph/core e @inkgraph/mcp e inicie o servidor stdio:

pnpm --filter @inkgraph/core run build
pnpm --filter @inkgraph/mcp run build
pnpm mcp

Exemplo de configuração para clientes MCP locais via stdio:

{
  "mcpServers": {
    "inkgraph": {
      "command": "node",
      "args": ["/caminho/absoluto/para/inkgraph/packages/mcp/dist/index.js"],
      "env": {
        "INKGRAPH_WORKSPACE": "/caminho/absoluto/para/inkgraph/workspace"
      }
    }
  }
}

Verificação de Tipos, Build e Testes

# Verificação de tipos em todos os pacotes do workspace
pnpm typecheck

# Suíte de testes unitários e de integração (Vitest)
pnpm test

# Build completo em todos os pacotes
pnpm build

Em ambientes sem pnpm diretamente no PATH, utilize corepack pnpm <comando> (ou corepack.cmd pnpm no Windows).

Estrutura do Cofre e Frontmatter YAML

Todo dado criativo do usuário no disco reside em ./workspace/, diretório estritamente bloqueado no .gitignore:

• workspace/lore/ — Dossiês canônicos de personagens, facções, locais, objetos, conceitos, eventos e sistemas de regras.

• workspace/manuscript/ — Capítulos e cenas do manuscrito.

• workspace/staging/ — Propostas pendentes aguardando revisão e aprovação do autor.

• workspace/timeline/ — Marcadores temporais e batidas narrativas.

• workspace/assets/ — Mapas, retratos e ativos gráficos.

Exemplo de frontmatter YAML reconhecido por @inkgraph/core:

---
id: "char_elias_vance"
type: "character" # character | faction | location | item | concept | event | rule_system
subtype: "militar"
name: "Elias Vance"
aliases: ["O Corvo Cego", "Lorde Comandante"]
status: "canon" # canon | provisional | draft
tags: ["nobreza", "militar"]
relationships:
  - target: "faction_iron_order"
    relation: "exiled_member"
    since_scene: "scene_01_prologue"
    sentiment: -0.8
epistemic:
  secrets_kept:
    - "Portador da Lâmina de Valdor"
  known_by:
    - "self"
    - "char_queen_morrigan"
---
Comandante exilado após o Cerco de Vael.

Servidor MCP Nativo (@inkgraph/mcp)

O servidor MCP expõe 8 ferramentas via stdio sobre o índice SQLite FTS5 e o diretório de staging (packages/mcp/src/toolDefinitions.ts):

Documentação e Padrões do Repositório

• Relatório e Guia Funcional das 22 Abas do Estúdio: docs/STUDIO_TABS_REPORT.md

• Guia do Usuário & Atalhos: docs/USER_GUIDE.md

• Decisões Arquiteturais (ADR 001): docs/architecture/DECISIONS.md

• Constituição Operacional de Agentes: AGENTS.md

• Guia de Contribuição: CONTRIBUTING.md

• Política de Segurança: SECURITY.md

• Código de Conduta: CODE_OF_CONDUCT.md

• Shell Desktop Tauri v2: packages/desktop/README.md

Créditos e Licença

O InkGraph é software livre distribuído sob a Licença MIT.

• Editor Markdown: CodeMirror 6 (Licença MIT)

• Inspiração Arquitetural de Memória em Camadas: projeto aberto AI Memory de Fabio Akita (MIT/Open Source)

• Visualização & Interface: React, Vite (MIT), Lucide Icons (ISC), D3 Force (ISC) e React Force Graph 2D (MIT)