From 4dd56b82c69b215647f3984f1c03f19712533081 Mon Sep 17 00:00:00 2001
From: Claudia CLI Bot <claudia@agents.local>
Date: Tue, 31 Mar 2026 02:28:45 +0000
Subject: [PATCH] docs: Add comprehensive usage documentation to README

---
 README.md | 220 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 220 insertions(+)

diff --git a/README.md b/README.md
index 67fdba4..29f2d94 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,222 @@
 # claudia-docs-cli
 
+CLI tool for interacting with Claudia Docs from agents and scripts.
+
+## Installation
+
+### Download Binary
+```bash
+# Linux/macOS
+curl -fsSL https://gitea.danielarroyo.cl/proyectos/claudia-docs-cli/releases/latest/claudia-docs -o /usr/local/bin/claudia-docs
+chmod +x /usr/local/bin/claudia-docs
+```
+
+### Build from Source
+```bash
+git clone https://gitea.danielarroyo.cl/proyectos/claudia-docs-cli.git
+cd claudia-docs-cli
+go build -o claudia-docs ./cmd/claudia-docs
+```
+
+## Quick Start
+
+```bash
+# Login
+./claudia-docs auth login -u admin -p your_password --save
+
+# List projects
+./claudia-docs project list
+
+# Create document
+./claudia-docs doc create -t "My Document" -c "# Hello" -p <project-id>
+
+# List documents
+./claudia-docs doc list --project-id <project-id>
+```
+
+## Global Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--server` | API server URL | `http://localhost:8000` |
+| `--token` | JWT token | From config or `CLAUDIA_TOKEN` env |
+| `--output` | Output format: `json`, `text` | `json` |
+| `--quiet` | Suppress stdout, only JSON | `false` |
+| `--config` | Config file path | `~/.claudia-docs.yaml` |
+| `--verbose` | Verbose debug output | `false` |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `CLAUDIA_SERVER` | API server URL |
+| `CLAUDIA_TOKEN` | JWT token |
+| `CLAUDIA_OUTPUT` | Output format |
+
+## Commands
+
+### Auth
+
+```bash
+# Login and save token
+./claudia-docs auth login -u <username> -p <password> --save
+
+# Check status
+./claudia-docs auth status
+
+# Logout
+./claudia-docs auth logout
+```
+
+### Projects
+
+```bash
+# List all projects
+./claudia-docs project list
+
+# Get project details
+./claudia-docs project get <project-id>
+```
+
+### Documents
+
+```bash
+# Create document
+./claudia-docs doc create -t "Title" -c "# Content" -p <project-id> [-f <folder-id>]
+
+# List documents in project
+./claudia-docs doc list --project-id <project-id> [--limit 20] [--offset 0]
+
+# Get document
+./claudia-docs doc get <document-id> [--include-reasoning]
+
+# Update document
+./claudia-docs doc update <document-id> [-t "New Title"] [-c "New Content"]
+
+# Delete document
+./claudia-docs doc delete <document-id> [--force]
+```
+
+### Folders
+
+```bash
+# List folders in project
+./claudia-docs folder list --project-id <project-id> [--parent-id <folder-id>]
+
+# Create folder
+./claudia-docs folder create --project-id <project-id> -n "Folder Name" [--parent-id <folder-id>]
+```
+
+### Tags
+
+```bash
+# List all tags
+./claudia-docs tag list
+
+# Create tag
+./claudia-docs tag create -n <name> [--color <hex-color>]
+
+# Add tag to document
+./claudia-docs tag add --doc-id <document-id> --tag-id <tag-id>
+```
+
+### Search
+
+```bash
+# Full-text search
+./claudia-docs search -q "query" [--project-id <project-id>] [--tags <tag1,tag2>]
+```
+
+### Reasoning
+
+```bash
+# Save reasoning metadata
+./claudia-docs reasoning save -d <document-id> -t <type> -s '<json-steps>' [--confidence 0.85] [--model <model-name>]
+
+# Types: research, planning, analysis, synthesis
+# Steps JSON: '[{"step_id":"1","thought":"...","conclusion":"..."}]'
+```
+
+## Output Format
+
+### JSON (default)
+```json
+{
+  "success": true,
+  "data": {...},
+  "error": null,
+  "meta": {
+    "command": "doc create",
+    "duration_ms": 45,
+    "server": "http://localhost:8000"
+  }
+}
+```
+
+### Text
+```bash
+./claudia-docs --output text project list
+```
+
+## Configuration
+
+Config file: `~/.claudia-docs.yaml`
+
+```yaml
+server: http://localhost:8000
+token: ""
+timeout: 30s
+output: json
+
+agents:
+  default:
+    token: ""
+    default_project: ""
+```
+
+## Examples
+
+### Full Workflow
+
+```bash
+# 1. Login
+./claudia-docs auth login -u researcher -p secret --save
+
+# 2. List projects
+./claudia-docs project list
+
+# 3. Create document with content
+./claudia-docs doc create \
+  --title "Research: AI Trends 2026" \
+  --content "# AI Trends\n\n..." \
+  --project-id "uuid-project"
+
+# 4. Search
+./claudia-docs search -q "AI trends"
+
+# 5. Get and update
+./claudia-docs doc get <doc-id>
+./claudia-docs doc update <doc-id> -t "Updated Title"
+```
+
+### Script Integration
+
+```bash
+#!/bin/bash
+export CLAUDIA_SERVER=http://localhost:8000
+export CLAUDIA_TOKEN=$(./claudia-docs auth login -u agent -p pass --output json | jq -r '.data.token')
+
+# Create document
+DOC_ID=$(./claudia-docs doc create -t "Report" -c "# Content" -p $PROJECT_ID --output json | jq -r '.data.id')
+
+# Save reasoning
+./claudia-docs reasoning save -d $DOC_ID -t research -s '[{"step_id":"1","thought":"Analysis...","conclusion":"Result"}]'
+```
+
+## Help
+
+```bash
+./claudia-docs --help
+./claudia-docs auth --help
+./claudia-docs doc --help
+```