okam 0.2.0__tar.gz

okam-0.2.0/.agents/rules/governance-standards.md

@@ -0,0 +1,43 @@
+# 🌐 Padrões de Governança
+
+Este manual estabelece os padrões técnicos para projetos que utilizam o framework Okam.
+
+## 📂 Estrutura de Projeto Padrão
+
+- `.agents/`: Configuração de agentes de IA.
+  - `rules/`: Documentos de governança e regramentos técnicos.
+  - `skills/`: Capacidades modulares dos agentes.
+  - `workflows/`: Fluxos de trabalho e automações.
+- `knowledge/`: Base de conhecimento persistente.
+  - `wiki/`: Páginas de síntese (OKF).
+  - `raw-sources/`: Fontes brutas e imutáveis.
+  - `scripts/`: Utilitários de validação e manutenção.
+- `templates/`: Templates reutilizáveis para novos documentos.
+- `docs/`: Documentação técnica e conceitual.
+
+## 📝 Documentação e Código
+
+- **README.md**: Todo projeto deve ter um arquivo explicando o objetivo e como rodar.
+- **Comentários**: Explicar o "Porquê", não apenas o "O quê".
+- **Idioma**: Código (variáveis/funções) em Inglês; Documentação em Português (PT-BR).
+
+## 🚀 Fluxo de Trabalho Git
+
+- **Commits**: Atômicos e descritivos.
+- **Limpeza**: Nunca subir `node_modules`, `.env` ou artefatos de build.
+
+## 🛡️ Segurança e Qualidade
+
+- **Variáveis de Ambiente**: Credenciais e tokens SEMPRE em arquivos `.env` protegidos.
+- **Refatoração**: Só deve ser feita se houver um ganho claro em manutenibilidade ou performance medível.
+
+## ⚖️ Priorização
+
+- Antes de iniciar qualquer tarefa, os agentes DEVEM consultar o contexto do projeto.
+- Priorizar implementações que gerem valor direto.
+- Se a tarefa não estiver no escopo prioritário, confirmar se é uma tarefa rápida (Quick Win) ou se deve ser agendada.
+
+## 🔄 Gestão de Sessão e Continuidade
+
+- Ao final de cada sessão, o agente deve documentar o que foi feito e os próximos passos claros.
+- O documento de handoff deve ser um prompt "pronto para uso" para o próximo agente.

okam-0.2.0/.agents/skills/deep-metadata-analysis/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: DeepMetadataAnalysis
+description: Executa o pipeline de análise profunda em um projeto para extrair sua "alma" e atualizar a governança.
+---
+
+# 🔭 Deep Metadata Analysis
+
+Use esta skill para realizar uma análise holística de um projeto, inspirada no padrão "Understand Anything".
+
+## 📋 Instruções de Execução
+
+1. **Invocação:** O usuário solicita análise de um projeto específico.
+2. **Execução das Fases:**
+   - Rode o **Scanner** (liste arquivos, leia configurações de projeto).
+   - Mude sua mentalidade para o **Relational** (deduza a regra de negócio lendo o código).
+   - Audite via **Governance** (compare com os guias de estilo em `.agents/rules/`).
+3. **Padrão de Saída para o Índice:**
+   ```markdown
+   ### [Nome do Projeto]
+   - **Stack:** [Techs]
+   - **Objetivo:** [Breve resumo]
+   - **Fluxo:** [A -> B -> C]
+   - **Status de Governança:** [OK/Pendente]
+   ```
+4. **Finalização:** Link o projeto no `./knowledge/wiki/index.md` e confirme o sucesso.

okam-0.2.0/.agents/skills/knowledge-wiki/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: KnowledgeWiki
+description: Operações de Ingest, Query e Lint para manter o sistema de conhecimento persistente.
+---
+
+# 📚 Knowledge Wiki
+
+Esta skill define as operações para manter o sistema de conhecimento persistente do workspace.
+
+## Estrutura do Wiki
+
+- **Localização**: `./knowledge/`
+- **raw-sources/**: Fontes brutas, imutáveis (PDFs, Markdown clippado, logs).
+- **wiki/**: Páginas de síntese geradas por IA seguindo o formato OKF.
+
+## Operações Principais
+
+### 1. Ingest (Ingestão)
+
+Sempre que uma nova fonte for adicionada a `raw-sources/`:
+
+1. Leia o conteúdo da fonte.
+2. Identifique os temas, entidades e conceitos principais.
+3. Compare com o conhecimento já existente no `wiki/`.
+4. **Crie ou Atualize** páginas no `wiki/`.
+5. Atualize o `index.md` e o `log.md`.
+
+### 2. Query (Consulta)
+
+Ao responder perguntas sobre o conhecimento acumulado:
+
+1. Comece consultando o `index.md` do Wiki.
+2. Siga os links para as páginas de síntese relevantes.
+3. Se houver lacunas, consulte as `raw-sources/`.
+4. Se a descoberta for valiosa, **protocole** a resposta como uma nova página no Wiki.
+
+### 3. Lint (Auditoria)
+
+Periodicamente, revise o Wiki em busca de:
+
+- Contradições entre documentos novos e antigos.
+- Páginas órfãs (sem links de entrada).
+- Conceitos mencionados mas sem página própria.
+
+## Padrões de Escrita
+
+- Use links `[[Nome da Página]]` para referências cruzadas.
+- Adicione frontmatter YAML no formato OKF (title, description, type, resource, timestamp, tags, parent).
+- Valide antes de commitar: `python ./knowledge/scripts/okf_manager.py --validate`.

okam-0.2.0/.agents/skills/memory-maintenance/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: MemoryMaintenance
+description: Extrai lições aprendidas e destila no índice de conhecimento para evitar repetição de erros.
+---
+
+# 🧠 Memory Maintenance
+
+Esta skill deve ser invocada sempre que uma sessão de trabalho termina ou uma lição importante é aprendida.
+
+## 🎯 Objetivo
+
+Garantir que o "Subconsciente" do Workspace seja alimentado com informações úteis, evitando que agentes futuros repitam os mesmos erros ou perguntem as mesmas coisas.
+
+## 📋 Fluxo de Trabalho
+
+1. **Análise:** Revise o histórico da conversa e identifique decisões, bugs corrigidos ou preferências do usuário.
+2. **Destilação:** Resuma a lição em 1 ou 2 frases curtas e diretas.
+3. **Escrita:** Localize o arquivo `./knowledge/wiki/index.md` e adicione a lição na categoria correta.
+4. **Confirmação:** Informe ao usuário qual lição foi "eternizada" na memória de governança.

okam-0.2.0/.agents/workflows/deep-metadata-pipeline.md

@@ -0,0 +1,27 @@
+---
+description: Fluxo multi-agente para extração profunda de metadados e "alma" de projetos.
+---
+
+# 🌊 Workflow: Deep Metadata Extraction
+
+Este workflow deve ser seguido para documentar e entender novos projetos ou atualizar a visão macro do workspace.
+
+## 1. 🔍 Fase: Scanner (Técnico)
+- Identificar stack principal (Linguagem, Frameworks).
+- Listar dependências críticas (APIs externas, Bancos de Dados).
+- Localizar pontos de entrada (`index.js`, `main.py`, etc.).
+
+## 2. 🧠 Fase: Relational (Lógica e Negócio)
+- Entender o "Porquê": Qual problema este projeto resolve?
+- Mapear fluxos principais (ex: "Recebe webhook → Valida → Envia para Sheet").
+- Identificar conexões com outros projetos do workspace.
+
+## 3. ⚖️ Fase: Governance (Compliance)
+- Verificar se segue o `governance-standards.md`.
+- Checar se existem segredos expostos (vazamento de `.env`).
+- Validar se a documentação local está alinhada com as regras de Agentes.
+
+## 4. 🧪 Fase: Synthesis (Eternização)
+- Destilar as fases anteriores em um bloco de metadados.
+- Atualizar o índice de conhecimento em `./knowledge/wiki/index.md`.
+- (Opcional) Gerar um grafo Mermaid se a complexidade for alta.

okam-0.2.0/.github/workflows/validate-okf.yml

@@ -0,0 +1,31 @@
+name: OKF Compliance CI
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  validate-okf:
+    name: Validate OKF Compliance
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+          cache: "pip"
+
+      - name: Install Okam Package
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+
+      - name: Run OKF Validation
+        run: |
+          okam validate

okam-0.2.0/.gitignore

@@ -0,0 +1,13 @@
+# Okam
+node_modules/
+dist/
+.env
+.env.*
+!.env.example
+*.log
+.DS_Store
+Thumbs.db
+__pycache__/
+*.pyc
+.vscode/
+.idea/

okam-0.2.0/AGENTS.md

@@ -0,0 +1,52 @@
+# 🏛️ Governança de Agentes
+
+Este documento define a arquitetura operacional de todos os Agentes de IA neste workspace. Objetivo: **Entendimento Holístico e Execução de Baixo Churn**.
+
+## Visão Geral
+
+Este é um repositório de inteligência com governança centralizada. A estratégia vive na raiz e o conhecimento vive em `./knowledge/`.
+
+## Pipeline de Inteligência (Core Agent Pipeline)
+
+Todos os agentes devem seguir o fluxo `/deep-metadata-pipeline` para garantir que o contexto nunca seja perdido:
+
+1. **Scanner** (Técnico): Listar arquivos, identificar stacks e dependências críticas.
+2. **Relational** (Psique): Deduzir o "porquê" do código e suas conexões inter-projeto.
+3. **Governance** (Compliance): Auditar contra `governance-standards.md` e buscar segredos vazados.
+4. **Synthesis** (Eternização): Destilar lições no Index e manter o **Wiki de Conhecimento** em `./knowledge/wiki/` como Memória Persistente de longo prazo.
+
+## Wiki de Conhecimento (Memória Persistente - OKF)
+
+O projeto utiliza o padrão **Open Knowledge Format (OKF)** para evitar a redescoberta de conhecimento do zero.
+
+- **Princípio**: O conhecimento deve ser compilado e mantido atualizado no Wiki, não re-derivado a cada query.
+- **Formato OKF**: Todos os arquivos do Wiki (`./knowledge/wiki/`) devem possuir frontmatter YAML contendo obrigatoriamente: `title`, `description`, `type`, `resource`, `timestamp`, `tags` e `parent`.
+- **Valores de Type**: Os tipos devem ser `index`, `concept`, `architecture`, `runbook`, `entity` ou `benchmark`.
+- **Validação**: Antes de criar ou modificar qualquer documento na Wiki, o agente deve validar a conformidade rodando `python ./knowledge/scripts/okf_manager.py --validate`.
+- **Indexação**: Use `python ./knowledge/scripts/okf_manager.py --dump-index` para consultar rapidamente o índice de metadados de toda a Wiki antes de planejar mudanças.
+- **Manutenção**: Use a skill `/knowledge-wiki` para operações de Ingest e Auditoria.
+
+## Persistência e Economia de Contexto
+
+- Agentes NÃO devem despejar dumps de logs ou análises brutas no chat.
+- Resultados intermediários e planos complexos DEVEM ser gravados em artefatos organizados.
+- O chat deve servir apenas para sínteses executivas e pedidos de aprovação.
+
+## Convenções e Regras de Ouro
+
+- **Slow is Fast**: Prefira soluções simples e legíveis em vez de abstrações complexas.
+- **Respeito à Autonomia**: Subpastas são projetos independentes. Nunca compartilhe contextos entre eles.
+- **Leitura Cirúrgica**: Evite ler arquivos extensos por completo. Use buscas específicas e leituras por blocos para economizar tokens.
+- **Escrita Não-Destrutiva**: Evite sobrescrever arquivos inteiros. Dê preferência a edições incrementais ou cirúrgicas.
+
+## Proibições Cruciais
+
+- **Zero Temporary Files**: É proibido usar arquivos temporários para lógica de negócio ou dados persistentes.
+- **No Secret Leaks**: Nunca grave segredos, dumps de banco ou chaves de API nos artefatos.
+
+## Ciclo de Vida do Trabalho
+
+1. **PLANNING**: Criar `implementation_plan.md` para mudanças de alto risco ou multi-arquivo.
+2. **EXECUTION**: Mudanças pequenas, focadas e reversíveis.
+3. **VERIFICATION**: Validar via `walkthrough.md` e evidências reais.
+4. **HANDOFF**: Ao encerrar a sessão, resumir o progresso e apontar os próximos passos claros.

okam-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Okam Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

okam-0.2.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: okam
+Version: 0.2.0
+Summary: Framework de governança de IA, memória persistente e gestão de conhecimento
+Author: Juliano Ceconi
+License: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# ⬡ Okam
+
+**Pare de Redescobrir. Comece a Governar.**
+
+Framework open-source para governança de IA, memória persistente e gestão de conhecimento.
+
+[![MIT License](https://img.shields.io/badge/Licença-MIT-blue.svg)](./LICENSE)
+[![Python 3.8+](https://img.shields.io/badge/Python-3.8+-green.svg)](https://python.org)
+[![PRs Welcome](https://img.shields.io/badge/PRs-Welcome-brightgreen.svg)](https://github.com/juliano-ceconi/okam/pulls)
+
+</div>
+
+---
+
+## O Que É Isso?
+
+**Okam** é um framework que resolve um problema simples: **seus agentes de IA não têm memória.**
+
+Toda vez que você abre uma sessão com seu copilot, ele começa do zero. Sem contexto das decisões passadas, sem governança, sem reutilização de conhecimento.
+
+Okam resolve isso com:
+
+- 🏛️ **Governança** — Regras claras para seus agentes (AGENTS.md + pipeline de 4 fases)
+- 🧩 **Skills** — Capacidades modulares reutilizáveis entre projetos
+- 📚 **Wiki de Conhecimento** — Memória persistente no formato OKF (não é RAG)
+- 🔍 **Pipeline de Metadados** — Extrai a "alma" dos seus projetos automaticamente
+
+## Quick Start (5 minutos)
+
+```bash
+# 1. Clone e instale localmente em modo de desenvolvimento
+git clone https://github.com/juliano-ceconi/okam.git
+cd okam
+pip install -e .
+
+# 2. Inicialize o wiki com seed pages
+okam init
+
+# 3. Customize o AGENTS.md com as regras do seu projeto
+# (edite AGENTS.md com suas preferências)
+
+# 4. Valide a conformidade
+okam validate
+
+# 5. Crie uma nova skill interativamente
+okam new-skill
+```
+
+*Nota: O script legado `python knowledge/scripts/okf_manager.py` continua funcionando como um wrapper de compatibilidade.*
+
+Para o guia completo, veja o [QUICKSTART.md](./QUICKSTART.md).
+
+## Conceitos Core
+
+| Conceito | O Que É | Doc |
+|:---|:---|:---|
+| **LLM Wiki** | Memória persistente vs RAG tradicional | [docs/concepts/llm-wiki.md](./docs/concepts/llm-wiki.md) |
+| **OKF** | Formato padronizado de metadados para conhecimento | [docs/concepts/okf-format.md](./docs/concepts/okf-format.md) |
+| **Deep Metadata** | Pipeline de 4 fases para extrair contexto | [docs/concepts/deep-metadata.md](./docs/concepts/deep-metadata.md) |
+| **Guided Tours** | Padrão TOUR.md para onboarding de agentes | [docs/concepts/guided-tours.md](./docs/concepts/guided-tours.md) |
+| **Git Hooks** | Governança automatizada via hooks pre-commit/push | [docs/concepts/git-hooks.md](./docs/concepts/git-hooks.md) |
+
+## Estrutura do Projeto
+
+```
+okam/
+├── .agents/
+│   ├── rules/           # Padrões de governança
+│   ├── skills/          # Capacidades modulares
+│   │   ├── deep-metadata-analysis/
+│   │   ├── knowledge-wiki/
+│   │   └── memory-maintenance/
+│   └── workflows/       # Pipelines de execução
+├── hooks/               # Git hooks portáveis (POSIX sh)
+│   ├── pre-commit       # Validação OKF + detecção de segredos
+│   ├── commit-msg       # Conventional Commits
+│   └── pre-push         # Validação OKF completa
+├── knowledge/
+│   ├── wiki/            # Páginas de síntese (OKF)
+│   ├── raw-sources/     # Fontes brutas
+│   └── scripts/         # Validador OKF
+├── templates/           # Templates reutilizáveis
+├── docs/
+│   ├── concepts/        # Documentação de conceitos
+│   └── diagrams/        # Diagramas Mermaid
+├── landing/             # Landing page
+├── AGENTS.md            # Governança central
+├── QUICKSTART.md        # Guia rápido
+└── LICENSE              # MIT
+```
+
+## Construído Com
+
+- **Python** — Validador OKF (zero dependências, stdlib only)
+- **Markdown** — Documentação e Wiki
+- **YAML** — Metadados estruturados
+
+## Contribuindo
+
+1. Fork o repositório
+2. Crie uma branch para sua feature (`git checkout -b feat/minha-feature`)
+3. Instale os hooks de governança (`okam hooks install`)
+4. Commit suas mudanças (`git commit -m 'feat: adiciona minha feature'`)
+5. Push para a branch (`git push origin feat/minha-feature`)
+6. Abra um Pull Request
+
+## Licença
+
+Este projeto está sob a licença MIT. Veja [LICENSE](./LICENSE) para mais detalhes.
+
+---
+
+<div align="center">
+
+**⬡ Feito por devs, para devs.**
+
+[Landing Page](./landing/index.html) · [Quick Start](./QUICKSTART.md) · [Documentação](./docs/)
+
+</div>

okam-0.2.0/Projeto_okam.md

@@ -0,0 +1,33 @@
+---
+tags:
+  - projeto
+  - okam
+status: 🟡 Em Desenvolvimento
+prioridade: 🔴 Alta
+faturamento_previsto: 0
+data_criacao: 2026-07-01
+data_revisao: 2026-07-01
+impacto_pareto: 20%
+---
+
+# Projeto: okam
+
+## 🎯 Objetivo
+Empacotar a infraestrutura de governança de IA existente no workspace como um template público (open-source) chamado Okam.
+
+## 💰 Valor Estratégico (Pareto)
+- [x] **Impacto Financeiro:** Baixo (Open-Source público, mas serve como gerador de autoridade e base para consultorias Enterprise)
+- [x] **Esforço Estimado:** Médio
+- [x] **Alinhamento Vida-OS:** Sim (Melhora a governança de IA em todo o workspace)
+
+## 📝 Notas e Contexto
+Framework de governança de IA para desenvolvedores brasileiros. Inclui AGENTS.md, Skills, Wiki OKF com validador zero-dependencies e landing page premium.
+
+Links Úteis:
+- [README local](file:///d:/projetos/juliano-ceconi/03_Inteligencia/okam/README.md)
+- [QUICKSTART.md](file:///d:/projetos/juliano-ceconi/03_Inteligencia/okam/QUICKSTART.md)
+
+## ⏭️ Próximos Passos
+- [ ] Criar repositório GitHub público em `juliano-ceconi/okam`
+- [ ] Publicar a primeira versão do framework
+- [ ] Monitorar feedbacks de desenvolvedores

okam-0.2.0/QUICKSTART.md

@@ -0,0 +1,102 @@
+# ⚡ Quick Start — Okam em 5 Minutos
+
+## Pré-requisitos
+
+- Python 3.8+ (para o validador OKF)
+- Git
+
+## 1. Instale o CLI
+
+Clone o repositório e instale o CLI localmente em modo editável:
+
+```bash
+git clone https://github.com/juliano-ceconi/okam.git
+cd okam
+pip install -e .
+```
+
+Isso tornará o comando global `okam` disponível no seu terminal.
+
+## 2. Inicialize o Wiki
+
+O comando `okam init` cria a estrutura inicial do wiki e gera 3 seed pages com frontmatter OKF válido:
+
+```bash
+okam init
+```
+
+Saída esperada:
+```
+Inicializando base de conhecimento OKF em: .../knowledge/wiki...
+  [CRIADO] index.md
+  [CRIADO] getting-started.md
+  [CRIADO] architecture.md
+
+✅ 3 seed page(s) criada(s) em ...
+```
+
+## 3. Customize o AGENTS.md
+
+Abra o `AGENTS.md` na raiz e ajuste as regras para o seu projeto:
+
+- Edite o **Pipeline de Inteligência** para refletir seus workflows
+- Ajuste as **Convenções e Regras de Ouro** para o seu time
+- Configure as **Proibições Cruciais** conforme seu contexto
+
+## 4. Crie Sua Primeira Skill de Forma Interativa
+
+Você não precisa copiar templates manualmente. Use o comando interativo:
+
+```bash
+okam new-skill
+```
+
+O CLI perguntará interativamente o nome, descrição, versão, prioridade e se você deseja criar as subpastas padrão (`scripts/`, `examples/`, `resources/`, `references/`) de apoio, gerando tudo estruturado.
+
+## 5. Valide Tudo e Gere Índices
+
+```bash
+# Valida frontmatter OKF de todos os arquivos do wiki
+okam validate
+
+# Gera tabela com índice de metadados
+okam index
+```
+
+## 6. Instale os Git Hooks de Governança
+
+O Okam inclui hooks que validam automaticamente antes de cada commit e push:
+
+| Hook | O que faz |
+|:---|:---|
+| `pre-commit` | Valida OKF dos arquivos staged + detecta segredos vazados |
+| `commit-msg` | Garante o formato [Conventional Commits](https://www.conventionalcommits.org/) |
+| `pre-push` | Re-valida OKF completo antes de enviar ao remote |
+
+```bash
+# Instalar todos os hooks
+okam hooks install
+
+# Instalar sem o hook de Conventional Commits
+okam hooks install --skip-commit-msg
+
+# Ver status
+okam hooks status
+
+# Remover (restaura backups de hooks anteriores)
+okam hooks uninstall
+```
+
+> **Nota:** Os hooks são scripts shell portáveis (POSIX `sh`) com zero dependências externas. No Windows, rodam automaticamente via Git Bash. Para bypass emergencial, use `--no-verify` (ex: `git commit --no-verify`).
+
+## Próximos Passos
+
+- 📖 Leia a [documentação de conceitos](./docs/concepts/)
+- 🧩 Explore as [skills incluídas](./.agents/skills/)
+- 📚 Adicione conhecimento ao [wiki](./knowledge/wiki/)
+- 🏗️ Crie um [TOUR.md](./templates/tour-template.md) para seu projeto
+- 🔒 Instale os [Git hooks de governança](#6-instale-os-git-hooks-de-governança)
+
+---
+
+> **Dica:** O okam CLI funciona com zero dependências externas de runtime. O script legado `python knowledge/scripts/okf_manager.py` continua totalmente operacional e atua como wrapper redirecionando comandos para manter compatibilidade.

okam-0.2.0/README.md

@@ -0,0 +1,121 @@
+<div align="center">
+
+# ⬡ Okam
+
+**Pare de Redescobrir. Comece a Governar.**
+
+Framework open-source para governança de IA, memória persistente e gestão de conhecimento.
+
+[![MIT License](https://img.shields.io/badge/Licença-MIT-blue.svg)](./LICENSE)
+[![Python 3.8+](https://img.shields.io/badge/Python-3.8+-green.svg)](https://python.org)
+[![PRs Welcome](https://img.shields.io/badge/PRs-Welcome-brightgreen.svg)](https://github.com/juliano-ceconi/okam/pulls)
+
+</div>
+
+---
+
+## O Que É Isso?
+
+**Okam** é um framework que resolve um problema simples: **seus agentes de IA não têm memória.**
+
+Toda vez que você abre uma sessão com seu copilot, ele começa do zero. Sem contexto das decisões passadas, sem governança, sem reutilização de conhecimento.
+
+Okam resolve isso com:
+
+- 🏛️ **Governança** — Regras claras para seus agentes (AGENTS.md + pipeline de 4 fases)
+- 🧩 **Skills** — Capacidades modulares reutilizáveis entre projetos
+- 📚 **Wiki de Conhecimento** — Memória persistente no formato OKF (não é RAG)
+- 🔍 **Pipeline de Metadados** — Extrai a "alma" dos seus projetos automaticamente
+
+## Quick Start (5 minutos)
+
+```bash
+# 1. Clone e instale localmente em modo de desenvolvimento
+git clone https://github.com/juliano-ceconi/okam.git
+cd okam
+pip install -e .
+
+# 2. Inicialize o wiki com seed pages
+okam init
+
+# 3. Customize o AGENTS.md com as regras do seu projeto
+# (edite AGENTS.md com suas preferências)
+
+# 4. Valide a conformidade
+okam validate
+
+# 5. Crie uma nova skill interativamente
+okam new-skill
+```
+
+*Nota: O script legado `python knowledge/scripts/okf_manager.py` continua funcionando como um wrapper de compatibilidade.*
+
+Para o guia completo, veja o [QUICKSTART.md](./QUICKSTART.md).
+
+## Conceitos Core
+
+| Conceito | O Que É | Doc |
+|:---|:---|:---|
+| **LLM Wiki** | Memória persistente vs RAG tradicional | [docs/concepts/llm-wiki.md](./docs/concepts/llm-wiki.md) |
+| **OKF** | Formato padronizado de metadados para conhecimento | [docs/concepts/okf-format.md](./docs/concepts/okf-format.md) |
+| **Deep Metadata** | Pipeline de 4 fases para extrair contexto | [docs/concepts/deep-metadata.md](./docs/concepts/deep-metadata.md) |
+| **Guided Tours** | Padrão TOUR.md para onboarding de agentes | [docs/concepts/guided-tours.md](./docs/concepts/guided-tours.md) |
+| **Git Hooks** | Governança automatizada via hooks pre-commit/push | [docs/concepts/git-hooks.md](./docs/concepts/git-hooks.md) |
+
+## Estrutura do Projeto
+
+```
+okam/
+├── .agents/
+│   ├── rules/           # Padrões de governança
+│   ├── skills/          # Capacidades modulares
+│   │   ├── deep-metadata-analysis/
+│   │   ├── knowledge-wiki/
+│   │   └── memory-maintenance/
+│   └── workflows/       # Pipelines de execução
+├── hooks/               # Git hooks portáveis (POSIX sh)
+│   ├── pre-commit       # Validação OKF + detecção de segredos
+│   ├── commit-msg       # Conventional Commits
+│   └── pre-push         # Validação OKF completa
+├── knowledge/
+│   ├── wiki/            # Páginas de síntese (OKF)
+│   ├── raw-sources/     # Fontes brutas
+│   └── scripts/         # Validador OKF
+├── templates/           # Templates reutilizáveis
+├── docs/
+│   ├── concepts/        # Documentação de conceitos
+│   └── diagrams/        # Diagramas Mermaid
+├── landing/             # Landing page
+├── AGENTS.md            # Governança central
+├── QUICKSTART.md        # Guia rápido
+└── LICENSE              # MIT
+```
+
+## Construído Com
+
+- **Python** — Validador OKF (zero dependências, stdlib only)
+- **Markdown** — Documentação e Wiki
+- **YAML** — Metadados estruturados
+
+## Contribuindo
+
+1. Fork o repositório
+2. Crie uma branch para sua feature (`git checkout -b feat/minha-feature`)
+3. Instale os hooks de governança (`okam hooks install`)
+4. Commit suas mudanças (`git commit -m 'feat: adiciona minha feature'`)
+5. Push para a branch (`git push origin feat/minha-feature`)
+6. Abra um Pull Request
+
+## Licença
+
+Este projeto está sob a licença MIT. Veja [LICENSE](./LICENSE) para mais detalhes.
+
+---
+
+<div align="center">
+
+**⬡ Feito por devs, para devs.**
+
+[Landing Page](./landing/index.html) · [Quick Start](./QUICKSTART.md) · [Documentação](./docs/)
+
+</div>