# Tool Documentation Architecture

This document explains how tool documentation is structured in Akmatori and provides guidelines for contributors adding new tools.

## Overview

Akmatori uses a simplified documentation architecture where import paths are embedded directly in SKILL.md:

```
AGENTS.md (incident level)
    └── Points to skills
            └── SKILL.md (skill level) ← Contains embedded tool imports
                    └── __init__.py has full API docs via help()
```

## File Responsibilities

### AGENTS.md (`.codex/AGENTS.md`)

**Purpose:** High-level incident manager instructions

**Contains:**
- Incident manager role and responsibilities
- Investigation workflow
- Critical instructions: "DO NOT run ls commands or read .env files"
- Pointer to SKILL.md for each skill

**Does NOT contain:**
- Tool-specific code examples
- Import statements
- Function documentation

**Generated by:** `generateIncidentAgentsMd()` in `skill_service.go`

---

### SKILL.md (`skills/{skill-name}/SKILL.md`)

**Purpose:** Skill description with embedded Quick Start imports

**Contains:**
- YAML frontmatter (name, description)
- Quick Start section with embedded Python imports
- User-defined prompt/instructions

**Quick Start Format:**
```markdown
## Quick Start

```python
import sys; sys.path.insert(0, './.codex/skills/linux-agent')
from scripts.ssh import execute_command, test_connectivity

# Full API docs: help(execute_command)
```
```

**Generated by:** `generateSkillMd()` in `skill_service.go`

---

### __init__.py (`scripts/{tool}/__init__.py`)

**Purpose:** Full API documentation via docstrings

**Contains:**
- Complete function documentation with Args, Returns, Examples
- Accessible via `help(function_name)` in Python

**Not generated:** Manually written by tool developers

---

## Key Principles

### 1. Embedded Import Paths

Import paths are embedded directly in SKILL.md's Quick Start section. This eliminates the need for a separate tools.md file.

Benefits:
- One less file to read
- Immediate access to import paths
- `help()` provides full documentation

### 2. Auto-Generated Based on Assigned Tools

SKILL.md is regenerated when tools are assigned, embedding the correct import paths for each tool.

### 3. Configuration Auto-Loads

Tools automatically load configuration from the MCP Gateway. Users should NEVER:
- List directories to find config
- Read .env files directly
- Manually configure tools

### 4. No Redundant Exploration

Documentation should eliminate the need for:
- `ls` commands to find paths
- Reading source code beyond help()
- Trial-and-error imports

---

## Adding a New Tool

When adding a new tool, update `generateSkillMd()` in `skill_service.go`:

```go
switch toolName {
case "ssh":
    quickStart.WriteString("from scripts.ssh import execute_command, test_connectivity\n")
case "zabbix":
    quickStart.WriteString("from scripts.zabbix import get_hosts, get_problems, get_history\n")
case "your_new_tool":
    quickStart.WriteString("from scripts.your_new_tool import function1, function2\n")
default:
    quickStart.WriteString(fmt.Sprintf("from scripts.%s import *\n", toolName))
}
```

### Checklist for New Tools

1. Add tool to `switch` statement in `generateSkillMd()`
2. List commonly used function imports
3. Ensure `__init__.py` has comprehensive docstrings
4. Test that `help(function_name)` shows useful documentation
5. Test that Quick Start code works when copied directly

---

## File Generation Flow

```
User assigns tool to skill via UI
         ↓
API calls AssignTools()
         ↓
AssignTools() regenerates SKILL.md with embedded imports
         ↓
On container startup:
         ↓
RegenerateAllSkillMds() regenerates ALL SKILL.md files
         ↓
When incident is created:
         ↓
generateIncidentAgentsMd() creates AGENTS.md pointing to skills
         ↓
skills/ copied to incident .codex/skills/
```

---

## Troubleshooting

### Quick Start not showing correct tools

Check that tools are properly assigned to the skill in the database. Run:
```sql
SELECT * FROM skill_tools WHERE skill_id = ?;
```

### Duplicate sections in SKILL.md

The `stripResourceInstructions()` function removes auto-generated sections. Check that the marker is correct:
```go
const marker = "## Quick Start"
```

### Agent still exploring directories

Ensure AGENTS.md has the instruction to read SKILL.md. Check `generateIncidentAgentsMd()` includes:
```go
sb.WriteString("1. Read `./.codex/skills/{skill-name}/SKILL.md`\n")
```
