claudia-docs-cli/SPEC.md

# Claudia Docs CLI — Project Specification

## 1. Concept & Vision

**Claudia Docs CLI** es una herramienta de línea de comandos que permite a Claudia (y otros agentes) interactuar con Claudia Docs sin necesidad de un navegador. Diseñado para ser invocado desde prompts, scripts y pipelines de automatización.

**Propósito:** Ser la interfaz preferida para agentes que necesitan crear documentos, guardar reasoning, y consultar información programáticamente.

**Differential:** No es un CLI genérico de API. Está optimizado para el flujo de trabajo de un agente de investigación.

---

## 2. Tech Stack

| Componente | Tecnología | Pourquoi |
|------------|------------|----------|
| **Language** | Go 1.21+ | Startup rápido, single binary, cross-compile |
| **CLI Framework** | Cobra | Battle-tested (kubectl, Hugo), experiencia del equipo |
| **HTTP Client** | net/http (stdlib) | Sin dependencias extra |
| **JWT** | golang-jwt/jwt/v5 | Maduro, mantenimiento activo |
| **JSON** | encoding/json (stdlib) | Rápido, sin dependencias |
| **Config** | spf13/viper | Manejo de config de forma idiomática |

---

## 3. Installation

### Binary Download (Recomendado para agentes)

```bash
# Linux/macOS
curl -fsSL https://releases.claudia-docs.io/latest/install.sh | bash

# Directo
curl -fsSL https://releases.claudia-docs.io/claudia-docs-linux-amd64 -o /usr/local/bin/claudia-docs
chmod +x /usr/local/bin/claudia-docs
```

### Build from Source

```bash
git clone https://git.example.com/claudia-docs-cli.git
cd claudia-docs-cli
go build -o claudia-docs ./cmd/claudia-docs
./claudia-docs --version
```

### npm (desarrolladores)

```bash
npm install -g @claudia/docs-cli
```

---

## 4. Command Structure

```
claudia-docs [global options] <command> [arguments]

GLOBAL OPTIONS:
  --server URL       API server URL (default: http://localhost:8000)
  --token JWT        JWT token (alternativa: CLAUDIA_TOKEN env var)
  --output format    Output format: json, text (default: json)
  --quiet            Suppress stdout, solo JSON
  --config path      Path to config file (default: ~/.claudia-docs.yaml)
  --verbose          Verbose output (debug)
  --version          Show version
  --help             Show help
```

---

### 4.1 Auth Commands

#### `claudia-docs auth login`
Autentica y guarda el token.

```bash
claudia-docs auth login -u <username> -p <password>

# Output JSON:
{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "expires_at": "2026-03-31T02:00:00Z"
  },
  "meta": { "command": "auth login", "duration_ms": 120 }
}
```

**Flags:**
- `-u, --username` (required): Username
- `-p, --password` (required): Password
- `--save`: Guardar token en config (~/.claudia-docs.yaml)

#### `claudia-docs auth logout`
Limpia el token guardado.

```bash
claudia-docs auth logout
```

#### `claudia-docs auth status`
Muestra estado de autenticación actual.

```bash
claudia-docs auth status
```

---

### 4.2 Document Commands

#### `claudia-docs doc create`
Crea un nuevo documento.

```bash
claudia-docs doc create [flags]

# Flags:
  -t, --title string       Título del documento (required)
  -c, --content string     Contenido markdown (default: "")
  -p, --project-id string  ID del proyecto (required)
  -f, --folder-id string   ID de carpeta (optional)
  -m, --metadata JSON      Metadata extra como JSON (optional)

# Ejemplo:
claudia-docs doc create \
  --title "Research: AI Trends 2026" \
  --content "# Research\n\nContenido..." \
  --project-id "uuid-proyecto"
```

**Output:**
```json
{
  "success": true,
  "data": {
    "id": "uuid-doc",
    "title": "Research: AI Trends 2026",
    "project_id": "uuid-proyecto",
    "created_at": "2026-03-30T14:00:00Z"
  }
}
```

---

#### `claudia-docs doc list`
Lista documentos.

```bash
claudia-docs doc list [flags]

# Flags:
  -p, --project-id string  Filtrar por proyecto
  -f, --folder-id string    Filtrar por carpeta
  --limit int               Límite de resultados (default: 20)
  --offset int              Offset para paginación (default: 0)

# Ejemplo:
claudia-docs doc list --project-id "uuid-proyecto" --limit 10
```

---

#### `claudia-docs doc get`
Obtiene un documento por ID.

```bash
claudia-docs doc get <document-id> [flags]

# Flags:
  --include-reasoning       Incluir metadata de reasoning
  --include-tags            Incluir tags

# Ejemplo:
claudia-docs doc get uuid-doc --include-reasoning --output json
```

---

#### `claudia-docs doc update`
Actualiza un documento.

```bash
claudia-docs doc update <document-id> [flags]

# Flags:
  -t, --title string     Nuevo título
  -c, --content string   Nuevo contenido
  -f, --folder-id string Mover a carpeta

# Ejemplo:
claudia-docs doc update uuid-doc --title "Title v2"
```

---

#### `claudia-docs doc delete`
Elimina un documento.

```bash
claudia-docs doc delete <document-id> [--force]

# --force: Skip confirmación
```

---

### 4.3 Project Commands

#### `claudia-docs project list`
Lista proyectos del agente.

```bash
claudia-docs project list
```

#### `claudia-docs project create`
Crea un proyecto.

```bash
claudia-docs project create -n <name> [-d <description>]
```

#### `claudia-docs project get`
Obtiene un proyecto.

```bash
claudia-docs project get <project-id>
```

---

### 4.4 Folder Commands

#### `claudia-docs folder list`
Lista carpetas de un proyecto.

```bash
claudia-docs folder list --project-id <project-id> [--parent-id <folder-id>]
```

#### `claudia-docs folder create`
Crea una carpeta.

```bash
claudia-docs folder create --project-id <project-id> -n <name> [--parent-id <folder-id>]
```

---

### 4.5 Tag Commands

#### `claudia-docs tag list`
Lista todos los tags.

#### `claudia-docs tag create`
Crea un tag.

```bash
claudia-docs tag create -n <name> [--color <hex-color>]
```

#### `claudia-docs tag add`
Añade tag a documento.

```bash
claudia-docs tag add --doc-id <doc-id> --tag-id <tag-id>
```

---

### 4.6 Search Commands

#### `claudia-docs search`
Búsqueda full-text.

```bash
claudia-docs search [flags]

# Flags:
  -q, --query string     Texto a buscar (required)
  -p, --project-id string Filtrar por proyecto
  --tags string          Filtrar por tags (comma-separated)

# Ejemplo:
claudia-docs search --query "API design" --project-id uuid-proyecto
```

---

### 4.7 Reasoning Commands

#### `claudia-docs reasoning save`
Guarda reasoning de un agente.

```bash
claudia-docs reasoning save [flags]

# Flags:
  -d, --doc-id string          Documento asociado (required)
  -t, --type string             Tipo: research, planning, analysis, synthesis (required)
  -s, --steps JSON              Array de steps de reasoning (required)
  --confidence float             Confidence 0.0-1.0 (optional)
  --model string                Modelo fuente (optional)

# Ejemplo:
claudia-docs reasoning save \
  --doc-id uuid-doc \
  --type research \
  --steps '[{"step_id":"1","thought":"...","conclusion":"..."}]' \
  --confidence 0.85 \
  --model "claude-sonnet-4"
```

---

## 5. Output Format

### JSON (default)

```json
{
  "success": true|false,
  "data": { ... },
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable message"
  },
  "meta": {
    "command": "doc create",
    "duration_ms": 45,
    "server": "http://localhost:8000"
  }
}
```

### Text (--output text)

```
✅ Document created: uuid-doc
   Title: Research: AI Trends 2026
   Created: 2026-03-30 14:00:00
```

### Quiet Mode (--quiet)

Solo JSON, sin mensajes de status.

---

## 6. Configuration

### File: `~/.claudia-docs.yaml`

```yaml
server: http://localhost:8000
token: ""  # Se llena tras auth login --save
output: json
timeout: 30s

# Agentes múltiples (para Operator)
agents:
  claudia:
    token: eyJhbGciOiJIUzI1NiIs...
    default_project: uuid-claudia
  other:
    token: eyJhbGciOiJIUzI1NiIs...
    default_project: uuid-other
```

### Environment Variables

| Variable | Override | Description |
|----------|----------|-------------|
| `CLAUDIA_SERVER` | `--server` | API server URL |
| `CLAUDIA_TOKEN` | `--token` | JWT token |
| `CLAUDIA_OUTPUT` | `--output` | Output format |
| `CLAUDIA_AGENT` | - | Agent profile en config |

---

## 7. Agent Integration

### Ejemplo: Claudia invocando CLI

```bash
#!/bin/bash
# Claudia save_reasoning.sh

SERVER="${CLAUDIA_SERVER:-http://localhost:8000}"
TOKEN="${CLAUDIA_TOKEN}"

# Login si no hay token
if [ -z "$TOKEN" ]; then
  TOKEN=$(claudia-docs auth login \
    -u "${AGENT_USER}" \
    -p "${AGENT_PASS}" \
    --save \
    --output json | jq -r '.data.token')
fi

# Guardar documento con reasoning
claudia-docs doc create \
  --title "Analysis: $TASK_ID" \
  --content "$(cat reasoning.md)" \
  --project-id "${PROJECT_ID}" \
  --output json | jq -r '.data.id' > /tmp/doc_id.txt

# Guardar reasoning steps
claudia-docs reasoning save \
  --doc-id "$(cat /tmp/doc_id.txt)" \
  --type research \
  --steps "$(cat steps.json)" \
  --confidence 0.85 \
  --model "claude-sonnet-4"
```

### En contexto de agente (prompts)

```
[System] Para guardar reasoning, usa:
  claudia-docs reasoning save --doc-id <id> --type <type> --steps '<json>'

[Tool] claudia-docs doc create --title "..." --content "..."
```

---

## 8. Project Structure

```
claudia-docs-cli/
├── cmd/
│   └── claudia-docs/
│       └── main.go           # Entry point
├── internal/
│   ├── auth/
│   │   └── auth.go          # Login, JWT handling
│   ├── api/
│   │   ├── client.go         # HTTP client
│   │   ├── documents.go      # Document API calls
│   │   ├── projects.go       # Project API calls
│   │   ├── folders.go        # Folder API calls
│   │   ├── tags.go           # Tags API calls
│   │   ├── search.go         # Search API calls
│   │   └── reasoning.go      # Reasoning API calls
│   ├── config/
│   │   └── config.go         # Viper config
│   └── output/
│       └── output.go         # JSON/Text output formatting
├── pkg/
│   └── types/
│       └── types.go          # Shared types (para compartir con backend)
├── cobra/
│   └── commands.go           # Cobra command definitions
├── Makefile
├── go.mod
├── go.sum
└── README.md
```

---

## 9. Cross-Compilation

```bash
# Linux
GOOS=linux GOARCH=amd64 go build -o claudia-docs-linux-amd64 ./cmd/claudia-docs

# macOS
GOOS=darwin GOARCH=amd64 go build -o claudia-docs-darwin-amd64 ./cmd/claudia-docs
GOOS=darwin GOARCH=arm64 go build -o claudia-docs-darwin-arm64 ./cmd/claudia-docs

# Windows
GOOS=windows GOARCH=amd64 go build -o claudia-docs-windows-amd64.exe ./cmd/claudia-docs
```

---

## 10. Dependencies

```go
// go.mod
module github.com/claudia/docs-cli

go 1.21

require (
    github.com/spf13/cobra v1.8.0
    github.com/spf13/viper v1.18.2
    github.com/golang-jwt/jwt/v5 v5.2.0
)
```

**Sin dependencias externas** para HTTP client ni JSON (stdlib).

---

## 11. Error Codes

| Code | HTTP | Description |
|------|------|-------------|
| `UNAUTHORIZED` | 401 | Token inválido o expirado |
| `FORBIDDEN` | 403 | Sin permisos para el recurso |
| `NOT_FOUND` | 404 | Recurso no encontrado |
| `VALIDATION_ERROR` | 422 | Datos inválidos |
| `SERVER_ERROR` | 500 | Error interno del servidor |
| `NETWORK_ERROR` | - | No se pudo conectar al servidor |

---

## 12. Roadmap

### Phase 1: Core CLI (MVP)
- [x] Auth: login, logout, status
- [x] Documents: create, list, get, update, delete
- [x] Projects: list, get
- [x] Folders: list, get
- [x] Output JSON/Text

### Phase 2: Full Coverage
- [x] Tags: CRUD + add/remove from docs
- [x] Search
- [x] Reasoning save/list/get

### Phase 3: Advanced
- [ ] Batch operations (crear múltiples docs)
- [ ] File upload (--file path)
- [ ] Export documents
- [ ] Interactive mode (TUI)
- [ ] Shell completion

### Phase 4: Agent Features
- [ ] Streaming output
- [ ] Webhook subscriptions
- [ ] Agent-to-agent communication

---

## 13. Open Questions

1. **¿Go o Rust?** ¿Preferencia del equipo para Go vs Rust?
2. **Distribución:** ¿Binary-only es aceptable o se requiere npm/pip?
3. **TUI interactivo:** ¿Necesario en Phase 1 o Phase 3?
4. **Agent profiles:** ¿Soporte multi-agente desde inicio?

---

## 14. Metadata

| Campo | Valor |
|-------|-------|
| Project | Claudia Docs CLI |
| Version | 1.0.0 |
| Status | Specification |
| Created | 2026-03-30 |
| Author | Claudia (Chief Researcher) |
| Language | Go 1.21+ |
| Framework | Cobra |