# AGENTS.md

## Ejecución de comandos Go — OBLIGATORIO vía Docker

**No hay Go ni agentes instalados en el host (macOS).** Todos los comandos Go/lint/build se ejecutan dentro del contenedor DevPod:

```bash
# Resolver el nombre del contenedor (es auto-generado, puede cambiar):
docker ps --filter ancestor=mcr.microsoft.com/devcontainers/go --format '{{.Names}}'

# Ejecutar comandos dentro (workspace montado en /workspaces/outline-mcp):
docker exec <container> sh -c "cd /workspaces/outline-mcp && go build ./..."
```

- El nombre actual es `great_jang`, pero NO asumirlo: resolverlo con `docker ps` cada sesión.
- Las ediciones de archivos se hacen en el host (ruta normal del repo); solo la ejecución va por `docker exec`.
- `openspec` CLI se ejecuta en el **host** (no está en el contenedor).

## Toolchain

- Go 1.26 (imagen `mcr.microsoft.com/devcontainers/go:1-trixie`). NO bajar a 1.22: `mcp-go` v1.0.0 requiere Go ≥ 1.25.5.
- `golangci-lint` v2 solo dentro del contenedor.
- Módulo: `outline-mcp`. Todo el código en `main.go` (decisión de diseño D2: monolito deliberado).

## Build y verificación

```bash
# Dentro del contenedor:
go build -o outline-mcp .
go build -ldflags "-X main.Version=v0.0.1-dev -X main.GiteaURL=https://gitea.example.com -X main.RepoOwner=owner -X main.RepoName=outline-mcp" -o outline-mcp .
golangci-lint run
# Ver tools/list del servidor MCP (handshake + listing por stdio):
printf '{"jsonrpc":"2.0","id":1,"method":"initialize",...}' | ./outline-mcp
```

Sin tests aún; verificación = `go build` + `golangci-lint run` + prueba manual por stdio.

## Contrato crítico: nombres de assets

El pipeline de release (`.gitea/workflows/release.yml`) y el auto-update (`doUpdate` en main.go) comparten un contrato implícito: los assets DEBEN llamarse `outline-mcp_{GOOS}_{GOARCH}` (con `.exe` para windows). Cambiar una parte rompe la otra.

## Convenciones del repo

- Artefactos OpenSpec (`openspec/changes/*/`) en **español**, tono formal; tasks con formato Given/When/Than (regla de `openspec/config.yaml`).
- Flujo: `openspec new change` → proposal → specs → design → tasks → implementar marcando checkboxes en `tasks.md`.
- Errores de configuración (`OUTLINE_URL`, `OUTLINE_API_KEY`) se devuelven como resultado MCP de error, nunca panic.
- La API key de Outline nunca se loguea.