NOW RAG is actually usable... might switch to gemma3:4b from glm-4.6 cloud for expenses reasons but we'll see

docs/rag/tools/git-tools.md

@@ -0,0 +1,94 @@
+# Git Tools
+
+## Read Operations
+
+| Tool | Purpose |
+|------|---------|
+| `roboco_git_status` | View working tree status |
+| `roboco_git_log` | View commit history |
+| `roboco_git_branch_list` | List branches |
+| `roboco_git_diff` | View changes |
+
+## Status and Diff
+
+```python
+# Check status
+status = roboco_git_status(project_slug="roboco")
+
+# View changes
+diff = roboco_git_diff(project_slug="roboco")
+
+# View history
+log = roboco_git_log(
+    project_slug="roboco",
+    branch="feature/backend/a1b2c3d4"
+)
+```
+
+## Branch Operations
+
+```python
+# List branches
+branches = roboco_git_branch_list(project_slug="roboco")
+
+# Create branch (PM only)
+roboco_git_create_branch(
+    project_slug="roboco",
+    task_id=task_id,
+    branch_type="feature"  # feature, fix, refactor, docs
+)
+# Creates: feature/backend/a1b2c3d4
+
+# Checkout branch
+roboco_git_checkout(
+    project_slug="roboco",
+    branch="feature/backend/a1b2c3d4"
+)
+```
+
+## Commit and Push
+
+```python
+# Commit with task link
+roboco_git_commit(
+    project_slug="roboco",
+    task_id=task_id,
+    message="Add rate limiting endpoint"
+)
+# Creates: [a1b2c3d4] Add rate limiting endpoint
+
+# Push to remote
+roboco_git_push(project_slug="roboco")
+```
+
+## Pull Requests
+
+```python
+# Create PR
+roboco_git_create_pr(
+    project_slug="roboco",
+    task_id=task_id,
+    title="[TASK-a1b2c3d4] Add rate limiting",
+    body="## Summary\n..."
+)
+
+# Merge PR (PM only)
+roboco_git_merge_pr(
+    project_slug="roboco",
+    pr_number=123,
+    merge_method="squash"  # squash, merge, rebase
+)
+```
+
+## Branch Naming
+
+```
+{type}/{team}/{task-id-prefix}
+```
+
+| Type | Use |
+|------|-----|
+| `feature/` | New functionality |
+| `fix/` | Bug fixes |
+| `refactor/` | Code restructuring |
+| `docs/` | Documentation |

docs/rag/tools/journal-tools.md

@@ -0,0 +1,92 @@
+# Journal Tools
+
+## Creating Entries
+
+| Tool | Purpose |
+|------|---------|
+| `roboco_journal_entry` | General entry |
+| `roboco_journal_decision` | Decision log |
+| `roboco_journal_learning` | Learning capture |
+| `roboco_journal_struggle` | Problem/solution |
+| `roboco_journal_reflect` | Task reflection |
+
+## General Entry
+
+```python
+roboco_journal_entry({
+    type: "learning",
+    title: "Redis SCAN vs KEYS",
+    content: "SCAN is better for large datasets",
+    task_id: task_id,
+    tags: ["redis", "performance"]
+})
+```
+
+Entry types: `task_reflection`, `decision_log`, `learning`, `struggle`, `general`
+
+## Decision Log
+
+```python
+roboco_journal_decision({
+    title: "Session storage choice",
+    context: "Need fast session lookups",
+    options: ["PostgreSQL", "Redis"],
+    chosen: "Redis",
+    rationale: "Sub-ms reads, ephemeral data"
+})
+```
+
+## Learning
+
+```python
+roboco_journal_learning({
+    content: "asyncio.gather for parallel calls",
+    how_applied: "Reduced latency 50%",
+    category: "performance",
+    tags: ["async"]
+})
+```
+
+## Struggle (Problem/Solution)
+
+```python
+roboco_journal_struggle({
+    task_id: task_id,
+    problem: "Tests failing intermittently",
+    attempts: ["Timeout increase", "Retry logic"],
+    resolution: "Race condition in setup"
+})
+```
+
+## Reflection (Required)
+
+```python
+roboco_journal_reflect({
+    task_id: task_id,
+    what_done: "Implemented rate limiting",
+    what_learned: "Lua scripts for atomicity",
+    what_struggled: "Testing concurrency"
+})
+```
+
+## Reading Journals
+
+```python
+# Search your journal
+roboco_journal_search("rate limiting", top_k=5)
+
+# Recent entries
+roboco_journal_recent(limit=10)
+
+# Read team journals (if permitted)
+roboco_journal_read_team(
+    target_agent="be-dev-1",
+    task_id=task_id
+)
+
+# Your stats
+roboco_journal_stats()
+
+# Check access scope
+roboco_journal_scope()
+```

docs/rag/tools/kb-tools.md

@@ -0,0 +1,111 @@
+# Knowledge Base Tools
+
+## Search and Query
+
+| Tool | Purpose |
+|------|---------|
+| `roboco_kb_search` | Semantic search |
+| `roboco_rag_query` | AI-synthesized answer |
+| `roboco_ask_mentor` | Conversational help |
+| `roboco_kb_stats` | Index statistics |
+
+## Semantic Search
+
+```python
+roboco_kb_search(
+    query="rate limiting redis",
+    top_k=5,
+    project="roboco",
+    index_types=["code", "docs"]
+)
+```
+
+## AI-Generated Answers
+
+```python
+roboco_rag_query(
+    query="How does authentication work?",
+    top_k=5
+)
+```
+
+## Mentor (Conversational)
+
+```python
+response = roboco_ask_mentor(
+    question="How do I handle auth?",
+    domain="coding"
+)
+
+# Follow-up
+roboco_ask_mentor(
+    question="What about refresh tokens?",
+    conversation_id=response["conversation_id"]
+)
+```
+
+## Indexing
+
+```python
+# Index code (PM, Developer)
+roboco_kb_index_code(
+    sources=["src/**/*.py"],
+    project="roboco"
+)
+
+# Index docs (PM, Documenter)
+roboco_kb_index_docs(
+    sources=["docs/**/*.md"],
+    project="roboco"
+)
+```
+
+## Error Tracking
+
+```python
+# Search for similar errors
+roboco_search_error(
+    error_message="Redis connection timed out",
+    context="startup"
+)
+
+# Record solution
+roboco_record_error_solution(
+    error_message="Redis connection timed out",
+    solution="Added retry with backoff",
+    worked=True
+)
+```
+
+## Decision Tracking
+
+```python
+# Check for similar decisions
+roboco_check_decision(topic="session storage")
+
+# Record decision
+roboco_record_decision(params={
+    topic: "Session storage",
+    decision: "Use Redis",
+    rationale: "Sub-ms reads"
+})
+```
+
+## Standards
+
+```python
+# Get standards
+roboco_get_standards(domain="coding", language="python")
+
+# Validate action
+roboco_validate_action(
+    action_type="create_endpoint",
+    context="Adding user API"
+)
+
+# Code review
+roboco_review_code(
+    code="def handle(...):",
+    file_path="src/api/auth.py"
+)
+```

docs/rag/tools/messaging-tools.md

@@ -0,0 +1,84 @@
+# Messaging Tools
+
+## Sending Messages
+
+```python
+roboco_message_send({
+    channel: "backend-cell",
+    content: "Starting work on rate limiting",
+    task_id: task_id
+})
+```
+
+## Channel History
+
+```python
+# Read channel history
+roboco_channel_history(
+    channel="backend-cell",
+    limit=50
+)
+```
+
+## Notifications
+
+### Sending (PM/Board only)
+
+```python
+roboco_notify_send({
+    recipient: "be-dev-1",
+    type: "task_assignment",
+    task_id: task_id,
+    message: "Task ready for you"
+})
+```
+
+### Receiving
+
+```python
+# List notifications
+notifications = roboco_notify_list()
+
+# Acknowledge
+roboco_notify_ack(notification_id)
+```
+
+### Notification Types
+
+| Type | Purpose |
+|------|---------|
+| `task_assignment` | New task assigned |
+| `priority_change` | Priority updated |
+| `blocker_escalation` | Task blocked |
+| `review_request` | Review needed |
+| `documentation_request` | Docs needed |
+| `alert` | General alert |
+| `broadcast` | Org-wide message |
+
+## Sessions
+
+```python
+# Create session for tasks
+roboco_session_create_for_tasks({
+    title: "Feature X Implementation",
+    task_ids: [task_1_id, task_2_id]
+})
+
+# Start collaborative session
+roboco_session_start(
+    channel="backend-cell",
+    session_type="collaborative",
+    task_id=task_id
+)
+```
+
+## Message Types
+
+| Type | Use For |
+|------|---------|
+| `reasoning` | Thought process |
+| `dialogue` | Discussion |
+| `decision` | Decisions made |
+| `action` | Actions taken |
+| `blocker` | Blocking issues |
+| `technical` | Technical details |

docs/rag/tools/task-tools.md

@@ -0,0 +1,92 @@
+# Task Management Tools
+
+## Core Operations
+
+| Tool | Purpose |
+|------|---------|
+| `roboco_task_get` | Get task details |
+| `roboco_task_scan` | Find available tasks |
+| `roboco_task_claim` | Take ownership |
+| `roboco_task_start` | Begin work |
+
+## Task Retrieval
+
+```python
+# Get specific task
+task = roboco_task_get(task_id)
+
+# Scan for available tasks
+tasks = roboco_task_scan(
+    team="backend",        # Optional filter
+    status="pending"       # Optional filter
+)
+```
+
+## Task Lifecycle
+
+```python
+# Claim task
+roboco_task_claim(task_id)
+
+# Start work (also resumes paused tasks)
+roboco_task_start(task_id)
+
+# Pause work
+roboco_task_pause(task_id, reason="Waiting for clarification")
+
+# Resume paused work (use start)
+roboco_task_start(task_id)  # Works on paused tasks
+
+# Block (waiting on another task)
+roboco_task_block(task_id, blocker_task_id, reason)
+
+# Unblock (PM only)
+roboco_task_unblock(task_id)
+```
+
+## Submission
+
+```python
+# Submit for verification
+roboco_task_submit_verification(task_id)
+
+# Submit for QA
+roboco_task_submit_qa(task_id, notes)
+
+# QA actions
+roboco_task_qa_pass(task_id, {notes: "..."})
+roboco_task_qa_fail(task_id, {notes: "...", issues: [...]})
+
+# Documentation complete
+roboco_task_docs_complete(task_id)
+
+# PM complete
+roboco_task_complete(task_id)
+```
+
+## PM Operations
+
+```python
+# Create task
+roboco_task_create({
+    title: "...",
+    description: "...",
+    team: "backend",
+    status: "backlog"
+})
+
+# Activate (backlog -> pending)
+roboco_task_activate(task_id)
+
+# Cancel
+roboco_task_cancel(task_id, reason)
+
+# Plan
+roboco_task_plan(task_id, approach, steps)
+```
+
+## Progress Updates
+
+```python
+roboco_task_progress(task_id, "Implementing API", 50)
+```