Metadata-Version: 2.4
Name: guardiancontext
Version: 0.1.17
Summary: Contexto versionado em Git e coordenação de tarefas para agentes de programação.
Author: IronStack
License: Licença de Uso — GuardianContext
        Copyright (c) 2026 IronStack. Todos os direitos reservados.
        
        1. Concessão. A IronStack concede a você uma licença limitada, não exclusiva,
           intransferível e revogável para instalar e usar este software (CLI `guardian`,
           Desktop Manager e componentes distribuídos com eles) em conjunto com o serviço
           GuardianContext, conforme os Termos de Uso vigentes (docs/termos-de-uso.md ou
           https://api.ironstack.dev.br/termos), que integram esta licença.
        
        2. Restrições. Salvo autorização escrita da IronStack, você não pode: redistribuir,
           sublicenciar, vender ou alugar o software; remover avisos de autoria; usar o
           software para construir serviço concorrente; nem extrair a biblioteca curada de
           padrões para uso fora do serviço. Modificações para uso próprio são permitidas.
        
        3. Arquivos gerados no seu repositório (router.md, quadro.md, wiki/, decisoes/,
           claims/, handoffs/, hook pre-commit e afins) são seus, sem restrição.
        
        4. SEM GARANTIAS. O SOFTWARE É FORNECIDO "NO ESTADO EM QUE SE ENCONTRA", SEM GARANTIA
           DE QUALQUER NATUREZA, EXPRESSA OU IMPLÍCITA, INCLUINDO COMERCIALIZAÇÃO, ADEQUAÇÃO
           A UM FIM ESPECÍFICO E NÃO VIOLAÇÃO.
        
        5. LIMITAÇÃO DE RESPONSABILIDADE. EM NENHUMA HIPÓTESE A IRONSTACK RESPONDERÁ POR
           DANOS INDIRETOS, INCIDENTAIS, ESPECIAIS OU CONSEQUENCIAIS, PERDA DE DADOS, DE
           CÓDIGO OU DE LUCROS, DECORRENTES DO USO DO SOFTWARE OU DE AÇÕES DE AGENTES DE IA
           OPERADOS PELO USUÁRIO, AINDA QUE AVISADA DA POSSIBILIDADE. AGENTES DE IA EXECUTAM
           COMANDOS REAIS; A REVISÃO DO QUE ELES FAZEM É RESPONSABILIDADE DO USUÁRIO.
        
        6. Lei aplicável: República Federativa do Brasil.
        
Project-URL: Homepage, https://ironstack.dev.br/guardiancontext/
Project-URL: Documentation, https://ironstack.dev.br/guardiancontext/manual/
Project-URL: Terms, https://api.ironstack.dev.br/termos
Keywords: agents,coordination,git,multi-agent,control-plane
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0
Provides-Extra: mcp
Requires-Dist: mcp==2.2.0; python_version >= "3.10" and extra == "mcp"
Provides-Extra: update
Requires-Dist: packaging<27,>=24; extra == "update"
Requires-Dist: cryptography<51,>=43; extra == "update"
Provides-Extra: security
Requires-Dist: cryptography<51,>=43; extra == "security"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Provides-Extra: semantic
Requires-Dist: fastembed==0.5.1; extra == "semantic"
Provides-Extra: obsidian
Requires-Dist: watchdog>=3.0.0; extra == "obsidian"
Provides-Extra: desktop
Requires-Dist: PySide6>=6.6; extra == "desktop"
Dynamic: license-file

# GuardianContext

[English](#english) · [Español](#español) · [Português (Brasil)](#português-brasil)

## English

GuardianContext helps you and your AI agents resume work on a project. It organizes rules, decisions, and tasks as Markdown files in your Git repository.

Before starting a task, you can search these files and gather the relevant instructions for your agent. This makes project decisions available across Codex and Claude Code sessions. Since the files live in Git, you can also review changes and consult their history.

The product includes terminal commands, a graphical interface, and MCP integration with Codex and Claude Code. Agent connections need to be configured for each project.

[User manual](https://ironstack.dev.br/guardiancontext/manual/) · [Product website](https://ironstack.dev.br/guardiancontext/) · [Support](mailto:suporte@ironstack.dev.br)

### What you can do

- Record rules and decisions that need to remain available in future sessions.
- Search project information and prepare a task brief with document excerpts and source file references.
- Reserve a scope of work for a limited time using claims, and pass tasks between sessions using handoffs.
- Check document organization with `guardian doctor` and `guardian audit`.
- Connect Codex and Claude Code to the local protocol through MCP.

These features depend on configuration and on the people working on the project. Keep reviewing changes, tests, and commits. GuardianContext does not guarantee that an agent will follow the recorded rules.

### Install with the graphical interface

The official installer uses [uv](https://docs.astral.sh/uv/) to set up a Python 3.11 environment. It installs the graphical interface and the semantic search, MCP, and update components.

#### Windows, in PowerShell

```powershell
irm https://api.ironstack.dev.br/install.ps1 | iex
```

#### macOS or Linux

```sh
curl -fsSL https://api.ironstack.dev.br/install.sh | sh
```

These commands download and run the installer. You can open the URL and read the script before running it.

Installation may download Python and other components. Semantic search downloads a model on first use. On Linux, the graphical interface also needs the Qt libraries.

When Desktop Manager opens:

1. Create an account and accept the Terms of Use, or sign in to your existing account.
2. Choose a Git repository folder and your team's working mode.
3. Run setup and check the diagnostics.

If the window does not open, run `guardian-desktop` in a new terminal.

#### Check your agent's configuration

An active license or a high audit score does not confirm that your agent is using GuardianContext.

Check the project instructions, hook, and claims policy in the diagnostics. Features that have not been enabled should appear as pending items. The Internal license also requires this setup.

To use MCP, select the client, register the integration, and open a new client session to review the trust request and confirm the connection.

### Install from the terminal

To try the document structure and text search, install the base package with [uv](https://docs.astral.sh/uv/getting-started/installation/):

```sh
uv tool install --python 3.11 guardiancontext
cd meu-repositorio
guardian init
guardian doctor
```

Replace `meu-repositorio` with your project's folder.

These commands create and check the local structure. Hooks and MCP need to be configured separately. To connect your account to the service, run `guardian signup` or `guardian login` in that folder. The command prompts you for your password.

The base package requires Python 3.9 or later. Python 3.11 is recommended for optional components. The manual explains how to install them, configure hooks, and choose between working in the same folder or in separate worktrees.

### Example: look up a decision before changing the database

After initializing GuardianContext, create `decisoes/0001-migrations.md`:

```markdown
# Database migrations

Every migration must include a rollback plan and be reviewed before deployment.
```

Update the index and find the decision:

```sh
guardian index rebuild --lexical
guardian brief "migrations" --tool agents --max-tokens 1500
```

The first command updates local search. The second prepares a task brief with matching excerpts and their source file paths.

Give the brief to your agent before it starts the change, and review the proposed actions.

This example uses text search from the base package. Results depend on the recorded content and the search terms.

### Where the files live

The default structure includes:

- `router.md`, `quadro.md`, `wiki/`, and `decisoes/` to organize project information.
- `claims/` and `handoffs/` to record work reservations and transfers between sessions.
- `docs/trabalho/` for task records.

Local state and the index live in `.guardian/`. Review generated files before adding them to Git.

### What works offline

Local structure and search commands can work without a connection to the service.

Registration, synchronization, and licensed features have their own connection and authorization requirements. The manual included in the package can also be read offline.

### What data is sent to the service

Audit reports send metrics and counts. Pattern synchronization sends metadata and vectors. When calling the service, the client also reports its version, the interface in use, and a random installation profile identifier.

The `guardian contribute` command lets you propose a document for the curated library. Before submission, the text is anonymized and shown for your review and confirmation. Check the content to avoid sharing sensitive information.

The API key is stored in your user profile, outside the repository. MCP configurations contain machine-specific paths; follow the manual when setting them up.

### Updates

Official installations use automatic updates with safety checks. Updates are deferred while the runtime is in use. Check the status with `guardian update status`.

Other installation methods may require manual updates.

### Manual and support

The [full manual](https://ironstack.dev.br/guardiancontext/manual/) is available on the website. To read the packaged manual in English, Spanish, or Portuguese:

```sh
guardian manual --lang en
guardian manual --lang es
guardian manual --lang pt
```

To report a problem, email [suporte@ironstack.dev.br](mailto:suporte@ironstack.dev.br). Include your operating system, the output of `guardian --version`, the action you took, and the error message. Remove credentials and private data from logs.

GuardianContext is an IronStack product, distributed under a proprietary use license. The license is in the `LICENSE` file included in the package. Service conditions are in the [Terms of Use](https://api.ironstack.dev.br/termos).

---

## Español

[English](#english) · [Español](#español) · [Português (Brasil)](#português-brasil)

GuardianContext te ayuda a ti y a tus agentes de IA a retomar el trabajo en un proyecto. Organiza las reglas, decisiones y tareas en archivos Markdown dentro del repositorio Git.

Antes de empezar una tarea, puedes buscar en esos archivos y reunir las instrucciones relevantes para el agente. Así puedes usar las decisiones del proyecto en distintas sesiones de Codex y Claude Code. Como los archivos están en Git, también puedes revisar los cambios y consultar su historial.

El producto incluye comandos de terminal, una interfaz gráfica e integración MCP con Codex y Claude Code. La conexión con los agentes debe configurarse en cada proyecto.

[Manual de uso](https://ironstack.dev.br/guardiancontext/manual/) · [Sitio del producto](https://ironstack.dev.br/guardiancontext/) · [Soporte](mailto:suporte@ironstack.dev.br)

### Para qué sirve

- Registrar las reglas y decisiones que deben seguir disponibles en las próximas sesiones.
- Buscar información del proyecto y preparar un resumen para una tarea, con fragmentos de los documentos y referencias a los archivos de origen.
- Reservar un ámbito de trabajo durante un tiempo limitado mediante claims y transferir tareas entre sesiones mediante handoffs.
- Comprobar la organización de los documentos con `guardian doctor` y `guardian audit`.
- Conectar Codex y Claude Code al protocolo local mediante MCP.

Estas funciones dependen de la configuración y de la participación de quienes trabajan en el proyecto. Sigue revisando los cambios, las pruebas y los commits. GuardianContext no garantiza que un agente cumpla las reglas registradas.

### Instalación con interfaz gráfica

El instalador oficial usa [uv](https://docs.astral.sh/uv/) para preparar un entorno con Python 3.11. Instala la interfaz gráfica y los componentes de búsqueda semántica, MCP y actualización.

#### Windows, en PowerShell

```powershell
irm https://api.ironstack.dev.br/install.ps1 | iex
```

#### macOS o Linux

```sh
curl -fsSL https://api.ironstack.dev.br/install.sh | sh
```

Estos comandos descargan y ejecutan el instalador. Puedes abrir la URL y leer el script antes de ejecutarlo.

La instalación puede descargar Python y otros componentes. La búsqueda semántica descarga un modelo en el primer uso. En Linux, la interfaz gráfica también necesita las bibliotecas de Qt.

Cuando se abra Desktop Manager:

1. Crea una cuenta y acepta los Términos de Uso o inicia sesión con tu cuenta existente.
2. Elige la carpeta de un repositorio Git y el modo de trabajo del equipo.
3. Ejecuta la configuración y revisa el diagnóstico.

Si la ventana no se abre, ejecuta `guardian-desktop` en una terminal nueva.

#### Comprueba la configuración del agente

Tener una licencia activa o una buena puntuación en la auditoría no confirma que el agente esté usando GuardianContext.

Revisa las instrucciones del proyecto, el hook y la política de claims en el diagnóstico. Las funciones que aún no se hayan activado deben aparecer como pendientes. La licencia Internal también requiere esta configuración.

Para usar MCP, selecciona el cliente, registra la integración y abre una nueva sesión del cliente para revisar la solicitud de confianza y confirmar la conexión.

### Instalación desde la terminal

Para probar la estructura de documentos y la búsqueda textual, instala el paquete básico con [uv](https://docs.astral.sh/uv/getting-started/installation/):

```sh
uv tool install --python 3.11 guardiancontext
cd meu-repositorio
guardian init
guardian doctor
```

Sustituye `meu-repositorio` por la carpeta de tu proyecto.

Estos comandos crean y comprueban la estructura local. Los hooks y MCP deben configurarse por separado. Para conectar tu cuenta al servicio, ejecuta `guardian signup` o `guardian login` en esa carpeta. El comando solicita la contraseña durante la ejecución.

El paquete básico requiere Python 3.9 o posterior. Para los componentes opcionales se recomienda Python 3.11. El manual explica cómo instalarlos, configurar los hooks y elegir entre trabajar en la misma carpeta o en worktrees separados.

### Ejemplo: consultar una decisión antes de modificar la base de datos

Después de inicializar GuardianContext, crea el archivo `decisoes/0001-migrations.md`:

```markdown
# Migraciones de la base de datos

Toda migración debe incluir un plan de reversión y revisarse antes del despliegue.
```

Actualiza el índice y busca la decisión:

```sh
guardian index rebuild --lexical
guardian brief "migrations" --tool agents --max-tokens 1500
```

El primer comando actualiza la búsqueda local. El segundo prepara un resumen para la tarea, con los fragmentos encontrados y las rutas de los archivos de origen.

Entrega ese resumen al agente antes de que empiece el cambio y revisa las acciones propuestas.

El ejemplo usa la búsqueda textual del paquete básico. Los resultados dependen del contenido registrado y de los términos de búsqueda.

### Dónde están los archivos

La estructura predeterminada incluye:

- `router.md`, `quadro.md`, `wiki/` y `decisoes/` para organizar la información del proyecto.
- `claims/` y `handoffs/` para registrar reservas de trabajo y transferencias entre sesiones.
- `docs/trabalho/` para los registros de tareas.

El estado y el índice local están en `.guardian/`. Revisa los archivos generados antes de añadirlos a Git.

### Qué funciona sin conexión

Los comandos locales de estructura y búsqueda pueden funcionar sin conexión con el servicio.

El registro, la sincronización y las funciones sujetas a licencia tienen sus propios requisitos de conexión y autorización. El manual incluido en el paquete también se puede consultar sin conexión.

### Qué datos se envían al servicio

Los informes de auditoría envían métricas y recuentos. La sincronización de patrones envía metadatos y vectores. En las llamadas al servicio, el cliente también informa su versión, la interfaz utilizada y un identificador aleatorio del perfil de instalación.

El comando `guardian contribute` permite proponer un documento para la biblioteca seleccionada. Antes del envío, el texto se anonimiza y se presenta para tu revisión y confirmación. Comprueba el contenido para evitar compartir información sensible.

La clave de API se guarda en el perfil del usuario, fuera del repositorio. Las configuraciones MCP contienen rutas específicas de la máquina; sigue las indicaciones del manual al configurarlas.

### Actualizaciones

Las instalaciones oficiales usan actualizaciones automáticas con comprobaciones de seguridad. La actualización se aplaza mientras el runtime está en uso. Consulta el estado con `guardian update status`.

Otras formas de instalación pueden requerir actualizaciones manuales.

### Manual y soporte

El [manual completo](https://ironstack.dev.br/guardiancontext/manual/) está disponible en el sitio web. Para consultar el manual del paquete en español, inglés o portugués:

```sh
guardian manual --lang es
guardian manual --lang en
guardian manual --lang pt
```

Para informar de un problema, escribe a [suporte@ironstack.dev.br](mailto:suporte@ironstack.dev.br). Incluye el sistema operativo, la salida de `guardian --version`, la acción realizada y el mensaje de error. Elimina las credenciales y los datos privados de los registros.

GuardianContext es un producto de IronStack, distribuido bajo una licencia de uso propietaria. La licencia está en el archivo `LICENSE`, incluido en el paquete. Las condiciones del servicio se encuentran en los [Términos de Uso](https://api.ironstack.dev.br/termos).

---

## Português (Brasil)

[English](#english) · [Español](#español) · [Português (Brasil)](#português-brasil)

O GuardianContext ajuda você e seus agentes de IA a retomar o trabalho em um projeto. Ele organiza as regras, decisões e tarefas em arquivos Markdown dentro do repositório Git.

Antes de começar uma tarefa, você pode buscar nesses arquivos e reunir as instruções relevantes para entregar ao agente. Isso permite usar as decisões do projeto em diferentes sessões de Codex e Claude Code. Como os arquivos estão no Git, você também pode revisar o que mudou e consultar o histórico.

O produto tem comandos de terminal, uma interface gráfica e integração MCP com Codex e Claude Code. A conexão com os agentes precisa ser configurada em cada projeto.

[Manual de uso](https://ironstack.dev.br/guardiancontext/manual/) · [Site do produto](https://ironstack.dev.br/guardiancontext/) · [Suporte](mailto:suporte@ironstack.dev.br)

### Para que serve

- Registrar as regras e decisões que precisam continuar disponíveis nas próximas sessões.
- Buscar informações do projeto e montar um resumo para uma tarefa, com trechos dos documentos e referências aos arquivos.
- Reservar um escopo de trabalho por um período, usando claims, e passar tarefas entre sessões por meio de handoffs.
- Verificar a organização dos documentos com `guardian doctor` e `guardian audit`.
- Conectar Codex e Claude Code ao protocolo local pelo MCP.

Esses recursos dependem da configuração e da participação de quem trabalha no projeto. Continue revisando as alterações, os testes e os commits. O GuardianContext não garante que um agente siga as regras registradas.

### Instalação com interface gráfica

O instalador oficial usa o [uv](https://docs.astral.sh/uv/) para preparar o ambiente com Python 3.11. Ele instala a interface gráfica e os componentes de busca semântica, MCP e atualização.

#### Windows, no PowerShell

```powershell
irm https://api.ironstack.dev.br/install.ps1 | iex
```

#### macOS ou Linux

```sh
curl -fsSL https://api.ironstack.dev.br/install.sh | sh
```

Esses comandos baixam e executam o instalador. Você pode abrir a URL e ler o script antes de executá-lo.

A instalação pode baixar Python e outros componentes. A busca semântica baixa um modelo no primeiro uso. No Linux, a interface gráfica também precisa das bibliotecas do Qt.

Quando o Desktop Manager abrir:

1. Crie uma conta e aceite os Termos de Uso ou entre na sua conta existente.
2. Escolha a pasta de um repositório Git e o modo de trabalho da equipe.
3. Execute a configuração e confira o diagnóstico.

Se a janela não abrir, execute `guardian-desktop` em um terminal novo.

#### Confira a configuração do agente

Ter uma licença ativa ou uma boa nota na auditoria não comprova que o agente está usando o GuardianContext.

Confira no diagnóstico as instruções do projeto, o hook e a política de claims. Recursos ainda não ativados devem aparecer como pendências. Essa configuração também é necessária para a licença Internal.

Para usar MCP, selecione o cliente, registre a integração e abra uma nova sessão do cliente para revisar a solicitação de confiança e confirmar a conexão.

### Instalação pelo terminal

Para experimentar a estrutura de documentos e a busca textual, instale o pacote básico com [uv](https://docs.astral.sh/uv/getting-started/installation/):

```sh
uv tool install --python 3.11 guardiancontext
cd meu-repositorio
guardian init
guardian doctor
```

Substitua `meu-repositorio` pela pasta do seu projeto.

Esses comandos criam e verificam a estrutura local. Hooks e MCP precisam ser configurados separadamente. Para conectar a conta ao serviço, execute `guardian signup` ou `guardian login` nessa pasta. O comando solicita a senha durante a execução.

O pacote básico requer Python 3.9 ou superior. Para os componentes opcionais, o ambiente recomendado é Python 3.11. O manual explica como instalar esses componentes, configurar os hooks e escolher entre trabalhar na mesma pasta ou em worktrees separadas.

### Exemplo: consultar uma decisão antes de alterar o banco

Depois de inicializar o GuardianContext, crie o arquivo `decisoes/0001-migrations.md`:

```markdown
# Migrations de banco

Toda migration deve incluir um plano de rollback e ser revisada antes do deploy.
```

Atualize o índice e busque a decisão:

```sh
guardian index rebuild --lexical
guardian brief "migrations" --tool agents --max-tokens 1500
```

O primeiro comando atualiza a busca local. O segundo prepara um briefing: um resumo para a tarefa, com trechos encontrados e os caminhos dos arquivos de origem.

Entregue esse resumo ao agente antes de ele trabalhar na alteração e revise as ações propostas.

O exemplo usa a busca textual do pacote básico. Os resultados dependem do conteúdo registrado e dos termos usados na busca.

### Onde ficam os arquivos

A estrutura padrão inclui:

- `router.md`, `quadro.md`, `wiki/` e `decisoes/` para organizar as informações do projeto.
- `claims/` e `handoffs/` para registrar reservas de trabalho e passagens entre sessões.
- `docs/trabalho/` para os registros das tarefas.

O estado e o índice local ficam em `.guardian/`. Revise os arquivos gerados antes de adicioná-los ao Git.

### O que funciona sem conexão

Os comandos locais de estrutura e busca podem funcionar sem conexão com o serviço.

Cadastro, sincronização e recursos sujeitos a licença têm seus próprios requisitos de conexão e autorização. O manual incluído no pacote também pode ser consultado sem conexão.

### Quais dados são enviados ao serviço

O relatório de auditoria envia métricas e contagens. A sincronização de padrões envia metadados e vetores. Nas chamadas ao serviço, o cliente também informa sua versão, a interface usada e um identificador aleatório do perfil de instalação.

O comando `guardian contribute` permite propor um documento à biblioteca curada. Antes do envio, o texto passa por anonimização e é apresentado para sua revisão e confirmação. Confira o conteúdo para evitar o compartilhamento de informações sensíveis.

A chave de API fica no perfil do usuário, fora do repositório. As configurações MCP contêm caminhos específicos da máquina; siga as orientações do manual ao configurá-las.

### Atualizações

Instalações oficiais usam atualização automática com verificações de segurança. Quando o runtime está em uso, a atualização é adiada. Consulte o estado com `guardian update status`.

Outras formas de instalação podem exigir atualização manual.

### Manual e suporte

O [manual completo](https://ironstack.dev.br/guardiancontext/manual/) está disponível no site. Para consultar o manual do pacote em português, inglês ou espanhol:

```sh
guardian manual --lang pt
guardian manual --lang en
guardian manual --lang es
```

Para reportar um problema, escreva para [suporte@ironstack.dev.br](mailto:suporte@ironstack.dev.br). Informe o sistema operacional, a saída de `guardian --version`, a ação executada e a mensagem de erro. Remova credenciais e dados privados dos logs.

GuardianContext é um produto da IronStack, distribuído sob licença proprietária de uso. A licença está no arquivo `LICENSE`, incluído no pacote. As condições do serviço estão nos [Termos de Uso](https://api.ironstack.dev.br/termos).
