# API Reference
Source: https://docs.squidy.run/api/introduction

Documentação da API do Squidy

# API Reference

Esta seção contém a documentação da API interna do Squidy.

<Note>
  O Squidy é primariamente uma CLI. A API documentada aqui é para uso interno e extensões.
</Note>

## Módulos Principais

### Core

Módulos de domínio e lógica de negócio:

* `squidy.core.domain` - Entidades e value objects
* `squidy.core.ports` - Interfaces (ports & adapters)

### Adapters

Implementações das interfaces:

* `squidy.adapters.providers` - Provedores de IA
* `squidy.adapters.filesystem` - Sistema de arquivos

### Audit

Sistema de auditoria:

* `squidy.audit.engine` - Motor de auditoria
* `squidy.audit.checkers` - Verificadores
* `squidy.audit.detectors` - Detectores

### CLI

Interface de linha de comando:

* `squidy.cli.app` - Aplicação principal
* `squidy.cli.commands` - Comandos

## Uso Programático

```python theme={null}
from squidy.core.domain.project import Project
from squidy.audit.engine import AuditEngine

# Carregar projeto
project = Project.from_path("./meu-projeto")

# Executar auditoria
engine = AuditEngine()
result = engine.audit(project)

print(result.score)  # 0-100
print(result.issues)  # Lista de problemas
```

## Extensão

Para criar um checker personalizado:

```python theme={null}
from squidy.audit.checkers.base import BaseChecker

class MeuChecker(BaseChecker):
    def check(self, project):
        # Sua lógica aqui
        return CheckResult(
            name="meu-checker",
            passed=True,
            message="Tudo OK"
        )
```

<Card title="Arquitetura" icon="diagram-project" href="/architecture/overview">
  Entenda a arquitetura do Squidy.
</Card>


# Sistema de Arquivos
Source: https://docs.squidy.run/architecture/filesystem

Abstração do sistema de arquivos no Squidy

# Sistema de Arquivos

O Squidy usa uma abstração de sistema de arquivos para facilitar testes.

## Interface (Port)

```python theme={null}
class FileSystem(ABC):
    @abstractmethod
    def read(self, path: str) -> str:
        """Lê conteúdo do arquivo"""
        pass
    
    @abstractmethod
    def write(self, path: str, content: str):
        """Escreve conteúdo no arquivo"""
        pass
    
    @abstractmethod
    def exists(self, path: str) -> bool:
        """Verifica se arquivo existe"""
        pass
    
    @abstractmethod
    def mkdir(self, path: str):
        """Cria diretório"""
        pass
```

## Implementações

### LocalFileSystem

Implementação para uso real no sistema de arquivos local.

```python theme={null}
from squidy.adapters.filesystem.local_fs import LocalFileSystem

fs = LocalFileSystem()
content = fs.read("./readme-agent.md")
```

### MockFileSystem

Implementação em memória para testes.

```python theme={null}
from squidy.adapters.filesystem.mock_fs import MockFileSystem

fs = MockFileSystem()
fs.write("/test/file.md", "conteúdo")
assert fs.exists("/test/file.md")
```

## Uso nos Use Cases

Injeção de dependência permite trocar implementações:

```python theme={null}
# Produção
use_case = InitUseCase(fs=LocalFileSystem())

# Teste
use_case = InitUseCase(fs=MockFileSystem())
```

## Benefícios

* **Testes rápidos** - Sem I/O de disco
* **Testes determinísticos** - Sem dependência de estado
* **Paralelismo** - Testes isolados
* **CI/CD** - Funciona em qualquer ambiente


# Visão Geral
Source: https://docs.squidy.run/architecture/overview

Arquitetura do Squidy

# Arquitetura

O Squidy segue uma arquitetura limpa baseada em **Ports & Adapters** (Arquitetura Hexagonal).

## Diagrama

```
┌─────────────────────────────────────────┐
│              CLI Layer                  │
│         (Typer + Rich UI)               │
└──────────────────┬──────────────────────┘
                   │
┌──────────────────▼──────────────────────┐
│           Application Layer             │
│    (Use Cases: Init, Audit, Status)     │
└──────────────────┬──────────────────────┘
                   │
┌──────────────────▼──────────────────────┐
│            Domain Layer                 │
│  (Project, Config, AuditResult, etc)    │
└──────────────────┬──────────────────────┘
                   │
┌──────────────────▼──────────────────────┐
│           Ports (Interfaces)            │
│  (AIProvider, FileSystem, Storage)      │
└──────────────────┬──────────────────────┘
                   │
┌──────────────────▼──────────────────────┐
│          Adapters (Implementações)      │
│  (OpenAI, Anthropic, LocalFS, etc)      │
└─────────────────────────────────────────┘
```

## Camadas

### 1. CLI Layer

Interface com o usuário:

* Comandos Typer
* UI com Rich (tabelas, painéis, spinner)
* Formatação de saída

### 2. Application Layer

Casos de uso:

* `InitUseCase` - Setup de projeto
* `AuditUseCase` - Auditoria
* `StatusUseCase` - Status rápido

### 3. Domain Layer

Entidades e regras:

* `Project` - Representação do projeto
* `Config` - Configurações
* `AuditResult` - Resultado de auditoria

### 4. Ports

Interfaces abstratas:

* `AIProvider` - Provedores de IA
* `FileSystem` - Sistema de arquivos
* `Storage` - Persistência

### 5. Adapters

Implementações concretas:

* `OpenAIAdapter` / `AnthropicAdapter`
* `LocalFileSystem` / `MockFileSystem`

## Benefícios

* **Testável** - Fácil mockar dependências
* **Extensível** - Novos adapters sem mudar core
* **Manutenível** - Separação clara de responsabilidades
* **Flexível** - Troca de provedores de IA

## Fluxo de Dados

```
Usuário → CLI → Use Case → Domain → Port → Adapter → External
              ↑___________________________________________|
                        (retorno)
```


# Provedores de IA
Source: https://docs.squidy.run/architecture/providers

Como funcionam os provedores de IA no Squidy

# Provedores de IA

O Squidy suporta múltiplos provedores de IA através de uma interface unificada.

## Interface (Port)

```python theme={null}
class AIProvider(ABC):
    @abstractmethod
    def generate(self, prompt: str, context: dict) -> str:
        """Gera resposta da IA"""
        pass
    
    @abstractmethod
    def interview(self, answers: list) -> dict:
        """Conduz entrevista estruturada"""
        pass
```

## Provedores Suportados

### OpenAI

Modelos: GPT-4o, GPT-4o-mini

```python theme={null}
from squidy.adapters.providers.openai_adapter import OpenAIAdapter

provider = OpenAIAdapter(api_key="sk-...")
response = provider.generate(prompt, context)
```

### Anthropic

Modelos: Claude 3 Sonnet, Claude 3 Haiku

```python theme={null}
from squidy.adapters.providers.anthropic_adapter import AnthropicAdapter

provider = AnthropicAdapter(api_key="sk-ant-...")
response = provider.generate(prompt, context)
```

## Configuração

Defina a chave via variável de ambiente:

```bash theme={null}
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
```

Ou em arquivo `.env`:

```
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
```

## Seleção de Provedor

O Squidy seleciona automaticamente baseado em:

1. Qual chave está configurada
2. Preferência do usuário (futuro)

## Adicionar Novo Provedor

Para adicionar um novo provedor:

1. Crie uma classe herdando de `AIProvider`
2. Implemente os métodos abstratos
3. Registre no factory

```python theme={null}
class NovoProvider(AIProvider):
    def generate(self, prompt: str, context: dict) -> str:
        # Implementação
        pass
    
    def interview(self, answers: list) -> dict:
        # Implementação
        pass
```


# squidy audit
Source: https://docs.squidy.run/commands/audit

Audita a saúde do projeto Squidy

# squidy audit

Audita a saúde do projeto verificando estrutura, consistência e atualizações.

## Uso

```bash theme={null}
squidy audit [PATH] [OPTIONS]
```

## Argumentos

| Argumento | Descrição            | Padrão          |
| --------- | -------------------- | --------------- |
| `PATH`    | Diretório do projeto | Diretório atual |

## Opções

| Opção             | Descrição                        |         |
| ----------------- | -------------------------------- | ------- |
| `--format`, `-f`  | Formato de saída: `text`, `json` | `text`  |
| `--fix`           | Aplica correções automáticas     | `False` |
| `--verbose`, `-v` | Saída detalhada                  | `False` |
| `--help`          | Mostra ajuda do comando          |         |

## Exemplos

### Auditoria básica

```bash theme={null}
squidy audit
```

### Auditoria de projeto específico

```bash theme={null}
squidy audit ./meu-projeto
```

### Saída em JSON

```bash theme={null}
squidy audit -f json
```

### Aplicar correções

```bash theme={null}
squidy audit --fix
```

## Checkers

O audit executa verificações em múltiplas áreas:

### StructureChecker

Verifica se todos os arquivos obrigatórios existem:

* `readme-agent.md`
* `.squidy/manifest.json`
* Arquivos em `doc/`

### KanbanChecker

Analisa o kanban do projeto:

* WIP limit respeitado
* Tarefas bloqueadas
* Épicos sem tasks

### FreshnessChecker

Identifica arquivos desatualizados:

* `constituicao.md` > 30 dias
* `oraculo.md` sem atualização
* Tasks concluídas não arquivadas

### ConsistencyChecker

Verifica consistência entre arquivos:

* IDs de tasks únicos
* Referências de épicos válidas
* Tags consistentes

## Saída de Exemplo

```
🦑 Audit Report

Estrutura:     ✅ 10/10 arquivos OK
Kanban:        ⚠️  2 tarefas acima do WIP
Freshness:     ⚠️  constituicao.md (45 dias)
Consistência:  ✅ Tudo OK

Score: 85/100
```

## Correções Automáticas

Com `--fix`, o Squidy pode:

* Criar arquivos faltantes
* Arquivar tasks concluídas
* Atualizar índices
* Corrigir referências quebradas


# squidy init
Source: https://docs.squidy.run/commands/init

Inicializa um novo projeto com estrutura de governança

# squidy init

Inicializa um novo projeto com estrutura completa de governança para Agentes de IA.

## Uso

```bash theme={null}
squidy init [PATH] [OPTIONS]
```

## Argumentos

| Argumento | Descrição            | Padrão          |
| --------- | -------------------- | --------------- |
| `PATH`    | Diretório do projeto | Diretório atual |

## Opções

| Opção       | Descrição                  |
| ----------- | -------------------------- |
| `--dry-run` | Simula sem criar arquivos  |
| `--manual`  | Setup sem entrevista de IA |
| `--help`    | Mostra ajuda do comando    |

## Exemplos

### Setup interativo (padrão)

```bash theme={null}
squidy init
```

### Projeto específico

```bash theme={null}
squidy init ./minha-api
```

### Dry run (simulação)

```bash theme={null}
squidy init --dry-run
```

### Setup manual

```bash theme={null}
squidy init --manual
```

## Fluxo de Entrevista

O Squidy conduz uma entrevista inteligente em 5 fases:

1. **Visão Geral** - Tipo de projeto e stack
2. **Arquitetura** - Padrões e decisões técnicas
3. **Governança** - Regras e restrições
4. **Workflow** - Processo de desenvolvimento
5. **Refinamento** - Ajustes finais

## Arquivos Gerados

```
projeto/
├── readme-agent.md          # Guia principal para IA
├── .squidy/manifest.json    # Manifesto do projeto
├── doc/
│   ├── AGENT.md             # Referência rápida
│   ├── constituicao.md      # Princípios e regras
│   ├── oraculo.md           # Decisões de arquitetura
│   ├── politicas.md         # Stack e convenções
│   ├── kanban.md            # Gestão de tarefas
│   ├── emergencia.md        # Bloqueios críticos
│   ├── indice-diario.md     # Índice de logs
│   └── contexto-sessao.md   # Cache de sessão
└── diario/
    └── YYYY-MM.md           # Log mensal
```

## Próximos Passos

Após executar `init`, instrua seu agente de IA:

> "Leia o arquivo `readme-agent.md` e siga o ritual de onboarding"

<Card title="squidy audit" icon="magnifying-glass" href="/commands/audit">
  Aprenda a auditar seu projeto.
</Card>


# squidy status
Source: https://docs.squidy.run/commands/status

Mostra o status atual do projeto

# squidy status

Mostra o status atual do projeto de forma rápida.

## Uso

```bash theme={null}
squidy status [PATH]
```

## Argumentos

| Argumento | Descrição            | Padrão          |
| --------- | -------------------- | --------------- |
| `PATH`    | Diretório do projeto | Diretório atual |

## Exemplos

### Status do diretório atual

```bash theme={null}
squidy status
```

### Status de projeto específico

```bash theme={null}
squidy status ./meu-projeto
```

## Informações Exibidas

* ✅ Status da estrutura Squidy
* 📋 Tarefas em progresso (WIP)
* 🚨 Bloqueios críticos
* 📅 Última atualização
* 🏷️ Tags do projeto
* 📊 Versão do manifesto

## Saída de Exemplo

```
🦑 Project Status

📁 Projeto: minha-api
🎯 Versão: 2.0.1
📅 Atualizado: 2026-02-25

📋 Kanban:
   Em progresso: 2/3
   Backlog: 5 tarefas
   Concluído: 12 tarefas

🚨 Bloqueios: 0

✅ Estrutura: OK
```

## Alias

```bash theme={null}
squidy doctor    # Mesmo que status
```


# Auditoria
Source: https://docs.squidy.run/concepts/audit

Como funciona o sistema de auditoria do Squidy

# Auditoria

O sistema de auditoria do Squidy verifica a saúde e consistência do projeto.

## Checkers

### StructureChecker

Verifica se a estrutura de arquivos está completa.

**Verifica:**

* ✅ `readme-agent.md` existe
* ✅ `.squidy/manifest.json` existe
* ✅ Diretório `doc/` existe
* ✅ Arquivos obrigatórios em `doc/`

**Erros comuns:**

* Arquivos deletados acidentalmente
* Projeto movido sem estrutura

### KanbanChecker

Analisa a saúde do Kanban.

**Verifica:**

* ✅ WIP limit respeitado (máx 3)
* ✅ Tasks não bloqueadas por muito tempo
* ✅ Épicos têm tasks associadas
* ✅ IDs únicos

**Warnings:**

* Muitas tasks em progresso
* Tasks bloqueadas > 7 dias
* Épicos órfãos

### FreshnessChecker

Identifica arquivos desatualizados.

**Limites:**

| Arquivo           | Limite               |
| ----------------- | -------------------- |
| `constituicao.md` | 30 dias              |
| `oraculo.md`      | 14 dias              |
| `politicas.md`    | 60 dias              |
| Tasks concluídas  | 7 dias para arquivar |

### ConsistencyChecker

Verifica consistência entre arquivos.

**Verifica:**

* ✅ Referências de épicos válidas
* ✅ Tasks mencionadas existem
* ✅ Tags consistentes
* ✅ IDs no formato correto

## Pontuação

O score de auditoria varia de 0 a 100:

| Range  | Status             |
| ------ | ------------------ |
| 90-100 | 🟢 Excelente       |
| 70-89  | 🟡 Bom             |
| 50-69  | 🟠 Precisa atenção |
| 0-49   | 🔴 Crítico         |

## Correções Automáticas

Com `--fix`, o Squidy pode:

1. **Criar arquivos faltantes** - Gera templates básicos
2. **Arquivar tasks** - Move concluídas para histórico
3. **Atualizar índices** - Reconstrói índice-diario.md
4. **Corrigir IDs** - Normaliza formatos

<Note>
  Sempre revise as correções antes de aplicar em produção.
</Note>


# Governança
Source: https://docs.squidy.run/concepts/governance

Entenda como o Squidy estrutura a governança do projeto

# Governança

O Squidy implementa uma estrutura de governança completa para projetos com Agentes de IA.

## Princípios

### 1. Contexto Persistente

A IA tem acesso a todo o contexto do projeto através de arquivos estruturados.

### 2. Regras Explícitas

Proibições, restrições e convenções são documentadas de forma clara.

### 3. Rastreabilidade

Todas as decisões são registradas e podem ser auditadas.

### 4. Autonomia Controlada

A IA tem autonomia dentro dos limites definidos.

## Arquivos de Governança

### constituicao.md

Define os princípios fundamentais:

* **Propósito** - Por que o projeto existe
* **Princípios** - Valores e diretrizes
* **Proibições** - O que nunca fazer
* **Definition of Done** - Critérios de aceitação

### politicas.md

Especifica as regras técnicas:

* **Stack** - Tecnologias permitidas
* **Convenções** - Padrões de código
* **Padrões** - Arquitetura e design
* **Processo** - Fluxo de trabalho

### oraculo.md

Registra decisões de arquitetura (ADRs):

* Decisões tomadas
* Contexto e motivação
* Alternativas consideradas
* Consequências

## Ciclo de Governança

```
┌─────────────┐
│   Setup     │ ← squidy init
│   Inicial   │
└──────┬──────┘
       ▼
┌─────────────┐
│ Desenvolver │ ← IA segue regras
│   com IA    │
└──────┬──────┘
       ▼
┌─────────────┐
│   Auditar   │ ← squidy audit
│   Regular   │
└──────┬──────┘
       ▼
┌─────────────┐
│  Atualizar  │ ← Evoluir regras
│  Regras     │
└─────────────┘
```

## Benefícios

* **Consistência** - A IA sempre segue as mesmas regras
* **Qualidade** - Definition of Done garante padrões
* **Segurança** - Proibições previnem erros graves
* **Evolução** - Decisões são documentadas e revisáveis


# Kanban
Source: https://docs.squidy.run/concepts/kanban

Sistema de gestão de tarefas do Squidy

# Kanban

O Squidy inclui um sistema de gestão de tarefas baseado em Kanban.

## Estrutura Hierárquica

```markdown theme={null}
## 🔥 ÉPICOS
### ÉPICO-001: Sistema de Autenticação
**Prioridade:** P0 | **Complexidade:** M
**Tasks:** TASK-001, TASK-002

## 📋 BACKLOG
### TASK-001: Setup JWT [ÉPICO-001]
**Complexidade:** S | **Prioridade:** P0
**Subtarefas:**
- [ ] SUB-001: Instalar biblioteca (XS - 30min)
- [ ] SUB-002: Configurar middleware (S - 1h)

## 🏗️ EM PROGRESSO (WIP: 1/3)
- [ ] TASK-001: Setup JWT

## ✅ CONCLUÍDO
- [x] TASK-000: Setup inicial
```

## Níveis

| Nível     | Prefixo  | Exemplo   | Descrição           |
| --------- | -------- | --------- | ------------------- |
| Épico     | `ÉPICO-` | ÉPICO-001 | Grande iniciativa   |
| Task      | `TASK-`  | TASK-001  | Unidade de trabalho |
| Subtarefa | `SUB-`   | SUB-001   | Passo específico    |

## Prioridades

| Prioridade | Significado          |
| ---------- | -------------------- |
| P0         | Crítico - bloqueante |
| P1         | Alto - importante    |
| P2         | Médio - desejável    |
| P3         | Baixo - futuro       |

## Complexidade (T-shirt Sizes)

| Tamanho | Tempo estimado       |
| ------- | -------------------- |
| XS      | \~30 min             |
| S       | \~1-2 horas          |
| M       | \~4-8 horas          |
| L       | \~1-2 dias           |
| XL      | \~3-5 dias           |
| XXL     | +1 semana (decompor) |

## WIP Limit

Limite de trabalho em progresso:

* Máximo 3 tasks simultâneas
* Evita multitasking
* Foco em entregar

## Workflow

1. **Criar** épicos no início do projeto
2. **Decompor** em tasks durante o planejamento
3. **Mover** tasks para "Em Progresso" ao iniciar
4. **Completar** subtarefas uma a uma
5. **Revisar** e marcar como concluído

## Comandos Relacionados

```bash theme={null}
# Ver status do kanban
squidy status

# Auditar estrutura
squidy audit
```


# Squidy - Documentação
Source: https://docs.squidy.run/index

Setup inteligente para projetos com Agentes de IA

# 🦑 Squidy

**Setup inteligente para projetos com Agentes de IA**

Governança, Auditoria e Documentação Automática para Claude, GPT-4, Cursor e mais.

<Card title="Comece em 2 minutos" icon="rocket" href="/quickstart">
  Instale o Squidy e configure seu primeiro projeto.
</Card>

## O Problema

Você usa **Claude**, **ChatGPT** ou **Cursor** para programar, mas:

* 🤯 A IA esquece tudo na próxima conversa
* 📝 Você reescreve os mesmos requisitos toda semana
* 🎨 O agente fica "criativo" e muda sua arquitetura
* 📂 Seu projeto vira bagunça porque ninguém documenta
* ⏱️ Gasta 30 min configurando prompt antes de codar

**O Squidy resolve isso em 2 minutos.**

## O Que é o Squidy?

O **Squidy** é uma CLI que cria automaticamente a estrutura de governança para projetos com Agentes de IA.

<Columns>
  <Card title="Setup com IA" icon="robot" href="/commands/init">
    Converse com IA sobre seu projeto e receba documentação completa.
  </Card>

  <Card title="Auditoria" icon="magnifying-glass" href="/commands/audit">
    Verifique a saúde do projeto e identifique problemas.
  </Card>

  <Card title="Kanban" icon="table-columns" href="/concepts/kanban">
    Gestão de tarefas com Épicos → Tasks → Subtarefas.
  </Card>

  <Card title="Governança" icon="shield-check" href="/concepts/governance">
    Regras, proibições e Definition of Done para sua IA.
  </Card>
</Columns>

## Instalação Rápida

```bash theme={null}
pip install squidy
squidy --version
```

<Card title="Veja o guia completo de instalação" icon="download" href="/installation">
  Opções de instalação via pip, pipx ou desenvolvimento.
</Card>

## Estrutura Criada

O Squidy gera uma estrutura completa de governança:

```
meu-projeto/
├── readme-agent.md          # 🤖 Guia completo para o agente
├── .squidy/
│   └── manifest.json        # 📋 Manifesto do projeto
├── doc/
│   ├── AGENT.md             # 🎯 Referência rápida
│   ├── constituicao.md      # ⚖️ Princípios e regras
│   ├── oraculo.md           # 🧙 Decisões de arquitetura
│   ├── politicas.md         # 📋 Stack e convenções
│   ├── kanban.md            # 📊 Gestão de tarefas
│   ├── emergencia.md        # 🚨 Bloqueios críticos
│   ├── indice-diario.md     # 📑 Índice do histórico
│   └── contexto-sessao.md   # 💾 Cache do estado
└── diario/
    └── 2026-02.md           # 📅 Log de decisões
```

## Próximos Passos

<Columns>
  <Card title="Quickstart" icon="play" href="/quickstart">
    Configure seu primeiro projeto em minutos.
  </Card>

  <Card title="Comandos" icon="terminal" href="/commands/init">
    Aprenda os comandos principais do Squidy.
  </Card>
</Columns>

***

<Card title="Suporte" icon="headset" href="mailto:contato@squidy.run">
  Precisa de ajuda? Entre em contato.
</Card>


# Instalação
Source: https://docs.squidy.run/installation

Como instalar o Squidy no seu ambiente

# 📦 Instalação

## Via pip (recomendado)

```bash theme={null}
pip install squidy
```

Verifique a instalação:

```bash theme={null}
squidy --version
```

## Via pipx (isolado)

Para instalação isolada sem conflitos:

```bash theme={null}
pipx install squidy
squidy --version
```

## Desenvolvimento

Clone o repositório e instale em modo de desenvolvimento:

```bash theme={null}
git clone https://github.com/seomarc/squidyrun.git
cd squidyrun
python -m venv venv && source venv/bin/activate  # Linux/Mac
# ou: python -m venv venv && venv\Scripts\activate  # Windows
pip install -e ".[dev]"
squidy --version
```

## Requisitos

* **Python:** 3.9 ou superior
* **Sistema:** Linux, macOS, Windows (WSL recomendado)

## Variáveis de Ambiente

Configure as chaves de API para uso com IA:

```bash theme={null}
# OpenAI
export OPENAI_API_KEY="sk-..."

# Anthropic (Claude)
export ANTHROPIC_API_KEY="sk-ant-..."
```

Ou use um arquivo `.env` no diretório do projeto.

## Atualização

```bash theme={null}
pip install --upgrade squidy
```

## Desinstalação

```bash theme={null}
pip uninstall squidy
```

## Solução de Problemas

### Comando não encontrado

Adicione o diretório de scripts do Python ao PATH:

```bash theme={null}
# Linux/Mac
export PATH="$HOME/.local/bin:$PATH"

# Windows
set PATH=%APPDATA%\Python\Scripts;%PATH%
```

### Conflitos de dependência

Use ambiente virtual:

```bash theme={null}
python -m venv venv
source venv/bin/activate
pip install squidy
```


# Links
Source: https://docs.squidy.run/links

Links úteis relacionados ao Squidy

# Links

Acesse todos os recursos relacionados ao Squidy.

## 🌐 Oficial

<CardGroup>
  <Card title="Site Oficial" icon="globe" href="https://squidy.run">
    squidy.run
  </Card>

  <Card title="PyPI" icon="box" href="https://pypi.org/project/squidy/">
    pip install squidy
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/seomarc/squidyrun">
    Código fonte e issues
  </Card>

  <Card title="Documentação" icon="book" href="https://docs.squidy.run">
    Você está aqui!
  </Card>
</CardGroup>

## 👤 Desenvolvedor

* **Marcos Tadeu**
  * 🌐 [Site Pessoal](https://www.marcostadeu.com.br/)
  * 💼 [LinkedIn](https://www.linkedin.com/in/seomarc/)
  * 💻 [GitHub](https://github.com/seomarc)
  * ▶️ [YouTube](https://www.youtube.com/@seomarcos)

* **SearchOps**
  * 🌐 [searchops.io](https://searchops.io/)

## ☕ Apoie o Projeto

Se o Squidy te ajudou, considere apoiar:

<Card title="Buy Me a Coffee" icon="mug-hot" href="https://buymeacoffee.com/seomarcos">
  Contribua com o desenvolvimento
</Card>

## Comunidade

* ⭐ [GitHub Stars](https://github.com/seomarc/squidyrun) - Deixe uma estrela!
* 🐛 [Issues](https://github.com/seomarc/squidyrun/issues) - Reporte bugs
* 💡 [Discussions](https://github.com/seomarc/squidyrun/discussions) - Sugestões e ideias

## Contato

📧 **Email:** [contato@squidy.run](mailto:contato@squidy.run)


# Quickstart
Source: https://docs.squidy.run/quickstart

Configure seu primeiro projeto com Squidy em minutos

# 🚀 Quickstart

Configure seu primeiro projeto com Squidy em 3 passos simples.

## 1. Instalação

```bash theme={null}
pip install squidy
```

Verifique a instalação:

```bash theme={null}
squidy --version
```

## 2. Inicialize seu Projeto

Execute o comando `init` para iniciar o setup interativo:

```bash theme={null}
squidy init
```

O Squidy fará perguntas sobre seu projeto:

```
🦑 Setup com Agente IA

🤖 Agente: Olá! Me conte sobre o projeto que você quer configurar.
           Exemplo: "API REST para delivery com Node e PostgreSQL"
   
Você: API REST para delivery com Node e PostgreSQL

🤖 Agente: Legal! Qual framework frontend você vai usar?
   
Você: React com TypeScript

... (mais 2-3 perguntas contextuais) ...

✅ Configuração gerada com sucesso!
```

## 3. Use com sua IA

Após o setup, instrua seu agente de IA:

> "Acesse `./readme-agent.md` e siga o ritual de onboarding"

Ou para um projeto específico:

```bash theme={null}
squidy init ./meu-novo-projeto
```

## Comandos Úteis

| Comando         | Descrição                |
| --------------- | ------------------------ |
| `squidy init`   | Setup interativo com IA  |
| `squidy audit`  | Audita o projeto atual   |
| `squidy status` | Mostra status do projeto |

## Opções do Init

```bash theme={null}
# Simular sem criar arquivos (dry-run)
squidy init --dry-run

# Setup manual (sem IA)
squidy init --manual

# Especificar diretório
squidy init ./meu-projeto
```

## Próximos Passos

<Card title="Comando Init" icon="terminal" href="/commands/init">
  Detalhes completos do comando de inicialização.
</Card>

<Card title="Conceitos de Governança" icon="shield-check" href="/concepts/governance">
  Entenda como o Squidy estrutura a governança do projeto.
</Card>


# CLI Reference
Source: https://docs.squidy.run/reference/cli

Referência completa dos comandos CLI

# CLI Reference

Referência completa dos comandos disponíveis no Squidy.

## Comandos Globais

### `--version`

Mostra a versão do Squidy.

```bash theme={null}
squidy --version
# squidy 2.0.1
```

### `--help`

Mostra ajuda geral ou de um comando específico.

```bash theme={null}
squidy --help
squidy init --help
```

## Comandos Principais

### init

Inicializa um novo projeto.

```bash theme={null}
squidy init [PATH] [--dry-run] [--manual]
```

**Argumentos:**

* `PATH` - Diretório do projeto (padrão: atual)

**Opções:**

* `--dry-run` - Simula sem criar arquivos
* `--manual` - Setup sem IA

### audit

Audita o projeto.

```bash theme={null}
squidy audit [PATH] [-f FORMAT] [--fix] [-v]
```

**Argumentos:**

* `PATH` - Diretório do projeto

**Opções:**

* `-f, --format` - Formato: `text`, `json`
* `--fix` - Aplica correções
* `-v, --verbose` - Saída detalhada

### status

Mostra status do projeto.

```bash theme={null}
squidy status [PATH]
```

**Alias:**

```bash theme={null}
squidy doctor
```

## Variáveis de Ambiente

| Variável            | Descrição          | Obrigatória |
| ------------------- | ------------------ | ----------- |
| `OPENAI_API_KEY`    | Chave da OpenAI    | Opcional\*  |
| `ANTHROPIC_API_KEY` | Chave da Anthropic | Opcional\*  |

\* Pelo menos uma é necessária para uso com IA.

## Códigos de Saída

| Código | Significado            |
| ------ | ---------------------- |
| 0      | Sucesso                |
| 1      | Erro geral             |
| 2      | Erro de validação      |
| 3      | Projeto não encontrado |


# Configuração
Source: https://docs.squidy.run/reference/configuration

Opções de configuração do Squidy

# Configuração

O Squidy pode ser configurado via variáveis de ambiente ou arquivo `.env`.

## Variáveis de Ambiente

### Provedores de IA

| Variável              | Descrição          | Exemplo                 |
| --------------------- | ------------------ | ----------------------- |
| `OPENAI_API_KEY`      | Chave da OpenAI    | `sk-...`                |
| `ANTHROPIC_API_KEY`   | Chave da Anthropic | `sk-ant-...`            |
| `DEFAULT_AI_PROVIDER` | Provedor padrão    | `openai` ou `anthropic` |

### Configurações Gerais

| Variável           | Descrição      | Padrão  |
| ------------------ | -------------- | ------- |
| `SQUIDY_LOG_LEVEL` | Nível de log   | `INFO`  |
| `SQUIDY_DRY_RUN`   | Modo simulação | `false` |

## Arquivo .env

Crie um arquivo `.env` no diretório do projeto:

```bash theme={null}
# Provedores de IA
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxx

# Configurações
SQUIDY_LOG_LEVEL=DEBUG
```

O Squidy carrega automaticamente as variáveis do `.env`.

## Manifesto do Projeto

O arquivo `.squidy/manifest.json` contém metadados do projeto:

```json theme={null}
{
  "version": "2.0.1",
  "name": "meu-projeto",
  "created_at": "2026-02-25T10:00:00Z",
  "updated_at": "2026-02-25T15:30:00Z",
  "config": {
    "language": "python",
    "framework": "fastapi",
    "database": "postgresql"
  }
}
```

**Campos:**

* `version` - Versão do Squidy usada
* `name` - Nome do projeto
* `created_at` - Data de criação
* `updated_at` - Última atualização
* `config` - Configurações específicas

## Prioridade de Configuração

Configurações são carregadas na ordem (última prevalece):

1. Valores padrão
2. Variáveis de ambiente do sistema
3. Arquivo `.env`
4. Argumentos de linha de comando


# Templates
Source: https://docs.squidy.run/reference/templates

Templates de arquivos gerados pelo Squidy

# Templates

O Squidy usa templates Jinja2 para gerar a documentação do projeto.

## Estrutura de Templates

```
squidy/generation/templates/
├── readme-agent.md.j2
├── agent.md.j2
├── constituicao.md.j2
├── oraculo.md.j2
├── politicas.md.j2
├── kanban.md.j2
├── emergencia.md.j2
└── manifest.json.j2
```

## Variáveis Disponíveis

Todos os templates recebem um objeto `project`:

```python theme={null}
{
  "name": "nome-do-projeto",
  "description": "Descrição do projeto",
  "stack": {
    "language": "python",
    "framework": "fastapi",
    "database": "postgresql"
  },
  "conventions": [...],
  "rules": [...],
  "created_at": "..."
}
```

## Exemplo de Template

```jinja2 theme={null}
# {{ project.name }}

## Descrição
{{ project.description }}

## Stack
- **Linguagem:** {{ project.stack.language }}
- **Framework:** {{ project.stack.framework }}
- **Database:** {{ project.stack.database }}

## Convenções
{% for convention in project.conventions %}
- {{ convention }}
{% endfor %}
```

## Personalização (Futuro)

Em versões futuras, você poderá:

* Criar templates customizados
* Estender templates existentes
* Definir templates por stack

## Template Engine

O Squidy usa Jinja2 com configurações específicas:

```python theme={null}
from jinja2 import Environment, PackageLoader

env = Environment(
    loader=PackageLoader('squidy', 'templates'),
    trim_blocks=True,
    lstrip_blocks=True
)
```

Isso garante:

* **Whitespace control** - Saída limpa
* **Escaping automático** - Segurança
* **Extensibilidade** - Macros e includes