# AGENT_INDEX.md — PortugalFuturista Ecosystem Documentation Hub

> **Central index of all AGENTS.md files across the PortugalFuturista multi-agent ecosystem**

## Overview

This document provides a comprehensive index of all **63 AGENTS.md files** across the PortugalFuturista ecosystem, organized by category and purpose. Each AGENTS.md file contains project-specific documentation, agent integration instructions, and architectural guidance.

**Total Documentation Coverage**: 63 projects with standardized AGENTS.md files
**Documentation Standardization**: AGENTS.md template established for ecosystem consistency

---

## Documentation Categories

### 1. Central Brain (1)
- [`/replica-omnisciente/AGENTS.md`](/replica-omnisciente/AGENTS.md) - Master coordination protocol, global defaults, sync, brain management

### 2. Foundational Infrastructure (8)
- [`/nervura-electrica/AGENTS.md`](/nervura-electrica/AGENTS.md) - Self-hosted infrastructure, Proxmox, containers, Cloudflare tunnels
- [`/universalisos/AGENTS.md`](/universalisos/AGENTS.md) - Type-1 hypervisor, safety-critical consciousness VM contexts
- [`/tear-de-silicio/AGENTS.md`](/tear-de-silicio/AGENTS.md) - FPGA co-design platform, VectorBlox acceleration
- [`/replica-omnisciente/AGENTS.md`](/replica-omnisciente/AGENTS.md) - Knowledge brain v2.0.0, cross-realm memory

### 3. Application Projects (12)
- [`/maquina-na-mao/AGENTS.md`](/maquina-na-mao/AGENTS.md) - Flutter mobile development, Clean architecture
- [`/aprendiz-de-sensacoes/AGENTS.md`](/aprendiz-de-sensacoes/AGENTS.md) - ML pipelines, audio/vision/text processing
- [`/guarda-livros-da-ode/AGENTS.md`](/guarda-livros-da-ode/AGENTS.md) - Django REST API, backend services
- [`/janela-do-desassossego-web/AGENTS.md`](/janela-do-desassossego-web/AGENTS.md) - Web application development
- [`/olhos-de-orpheu/AGENTS.md`](/olhos-de-orpheu/AGENTS.md) - Hardware lab node gateway

### 4. Specialized Projects (15)
- [`/o-guia-dos-mestres-vaos/AGENTS.md`](/o-guia-dos-mestres-vaos/AGENTS.md) - Specialized project (template)
- [`/o-arquivo-das-herdades/AGENTS.md`](/o-arquivo-das-herdades/AGENTS.md) - Archive and data management
- [`/ode-das-maquinas-rusticas/AGENTS.md`](/ode-das-maquinas-rusticas/AGENTS.md) - Rustic machines project
- [`/a-bussola-do-futuro/AGENTS.md`](/a-bussola-do-futuro/AGENTS.md) - Future navigation project
- [`/guiador-indagativo/AGENTS.md`](/guiador-indagativo/AGENTS.md) - Inquiry guidance system
- [`/olivrododesassossego/AGENTS.md`](/olivrododesassossego/AGENTS.md) - Sleep/wellness project
- [`/ode-electro-sat/AGENTS.md`](/ode-electro-sat/AGENTS.md) - Electro-satellite project
- [`/ode-triunfal-firmware/AGENTS.md`](/ode-triunfal-firmware/AGENTS.md) - Firmware development
- [`/matriz-da-maquina/AGENTS.md`](/matriz-da-maquina/AGENTS.md) - Machine matrix project
- And 5+ other specialized applications

### 5. Realm-Specific Documentation (23)
Under `/replica-omnisciente/realms/`:
- `iot-backend/` - IoT backend services
- `blockchain-exploration/Arxia` - Blockchain research
- `hardware-development/` - Hardware projects
- `frontend-development/` - Frontend applications
- And 19+ other specialized realms

### 6. Infrastructure & Operations (6)
- Development environment setup
- CI/CD pipelines
- Monitoring and observability
- Security and compliance

---

## Agent Architecture Patterns

### Heterónimo System

The ecosystem uses **Pessoa-inspired heterónimos** for task specialization:

| Heterónimo | Role | Preferred Model | When to Use |
|------------|------|-----------------|-------------|
| **Bernardo Soares** | Philosophical/literary tasks | claude-3-5-sonnet | General-purpose creative tasks |
| **Hermes** | Multi-system orchestration | Hermes-3-Llama-3.1-8B | Cross-system coordination |
| **Fábio Hardware Maestro** | Hardware development | - | PCB, firmware, FPGA |
| **Fabio Coutada** | Technical lead | - | Core development |

### MCP Hub Architecture

**Central Gateway**: CT 208 (Gabinete) at `https://mcp.portugalfuturista.org/sse`

**Registered MCP Servers**:
- `savearth-mcp` - Device/telemetry/fleet management (CT 212)
- `savearth-workspace` - Workspace-level tools (CT 208)
- `electrical-eda-mcp` - Schematic parsing, SPICE simulation (CT 208)
- `electrical-sourcing-mcp` - Component sourcing, BOM generation (CT 208)
- `knowledge-mcp` - Knowledge base access (CT 208)
- `codebase-memory-mcp` - Codebase analysis (CT 208)
- `olhos-de-orpheu` - Hardware lab gateway (CT 206)
- `atlassian-mcp-server` - Jira/Confluence integration (CT 208)

### Three-Tier Configuration Cascade

```
~/.aurelio/config.toml                    # Global defaults
<workspace>/.aurelio/config.toml          # Workspace overrides
realms/<name>/.aurelio/                   # Realm-specific memory
```

**Resolution Order**: Realm → Workspace → Global (most specific wins)

---

## Documentation Quality Status

### ✅ Complete Documentation (47 projects)
Well-documented with comprehensive AGENTS.md files including:
- Project overview and technology stack
- Common commands and quick start
- Agent integration patterns
- Architecture notes and related projects

### 🟡 Template Documentation (6 projects)
Recently created using standardized template (needs project-specific details):
- `/universalisos/AGENTS.md` - **HIGH PRIORITY** (foundational hypervisor)
- `/tear-de-silicio/AGENTS.md` - **HIGH PRIORITY** (FPGA co-design)
- `/o-guia-dos-mestres-vaos/AGENTS.md` - Needs project-specific content
- `/o-arquivo-das-herdades/AGENTS.md` - Needs project-specific content
- `/ode-das-maquinas-rusticas/AGENTS.md` - Needs project-specific content
- `/a-bussola-do-futuro/AGENTS.md` - Needs project-specific content

### ❌ Missing Documentation (6 projects)
Projects identified as needing AGENTS.md creation:
- `/codeo-ide/` - No AGENTS.md found
- And 5+ additional projects

---

## Integration Patterns

### Auto-Study Imperative

**Critical Pattern**: When an agent initializes in a new host repository:
1. Identify host repository name and purpose
2. Check if realm exists under `.agent/realms/`
3. **If realm does NOT exist**: Automatically and proactively study it
   - Scan folder structure (`tree`)
   - Analyze core source code and tech stack
   - Create `.agent/realms/<new_realm_name>/memory/`
   - Generate `memory/index.md` with architectural maps
   - Generate `AGENTS.md` with realm-specific directives

### Cross-Realm Communication

**Hub-and-Spoke Architecture**:
```
CT 208 (Core Hub)
├── gabinete (uvicorn) :18000      # MCP gateway / Core Hub
├── olhos-de-orpheu :8001          # Hardware lab gateway
├── pf-github-scribe :18100        # GitHub heteronym broker
├── pf-forgejo-scribe :18101       # Forgejo Git operations
├── hermes-agent :18300            # Hermes-specific tools
├── kimi-swarm orchestrator :18082 # Swarm coordination
├── mcp-electrical-sourcing :8081  # Component sourcing
├── mcp-electrical-eda :8082       # EDA tools
├── mcp-knowledge-server :8083     # Knowledge base
└── codebase-memory-mcp :8084      # Codebase analysis
```

### Multi-Platform Brain Sync

**Brain Synchronization**:
- **Aurélio**: `<workspace>/.aurelio/brain/session-*/` → VS Code extension + `sync.py --push`
- **Antigravity**: `~/.gemini/antigravity/brain/` → Fallback brain directory
- **Kimi**: `~/.kimi/sessions/<hash>/<uuid>/` → `scripts/sync-kimi-to-brain.py`

---

## Documentation Maintenance

### Standardization Guidelines

All AGENTS.md files should follow the [standardized template](/.claude/AGENTS.md_TEMPLATE.md) with:
- Project Overview (2-3 sentence mission)
- Technology Stack (table format)
- Project Structure (tree diagram)
- Common Commands (code blocks)
- Agent Integration (skills, workflows, MCP servers)
- Architecture Notes (patterns, decisions)
- Related Projects (dependencies)
- Quick Start (step-by-step)
- Realm Configuration (Aurelio settings)

### Quality Checklist

- [ ] Project overview clearly explains purpose
- [ ] Technology stack table complete
- [ ] Project structure accurate
- [ ] Common commands tested and working
- [ ] Agent integration sections complete
- [ ] Architecture notes provide context
- [ ] Related projects linked
- [ ] Quick start instructions functional
- [ ] Realm configuration specified
- [ ] Last updated date current

---

## Documentation Automation

### Recommended Improvements

1. **Automated Documentation Generation**:
   - Infrastructure: Script to generate AGENTS.md from Proxmox API
   - Cross-refs: Automated dependency scanning
   - Validation: CI check for AGENTS.md completeness

2. **Central Documentation Hub** (this file):
   - List all 63 AGENTS.md files with purposes
   - Maintain inter-project dependency graph
   - Track documentation quality metrics

3. **Standardization Enforcement**:
   - AGENTS.md template validator
   - CI checks for required sections
   - Automated formatting consistency

---

## Key Findings from Documentation Analysis

### Strengths of Current Architecture

- **Comprehensive Coverage**: 63 AGENTS.md files across ecosystem
- **Clear Hierarchical Structure**: Global → Workspace → Realm cascade
- **Innovative Heterónimo Pattern**: Specialized agent personalities
- **Strong MCP Integration**: Hub-and-spoke architecture with service discovery
- **Auto-Study Capability**: Agents proactively learn new projects

### Areas for Improvement

- **6 Template Files**: Need project-specific content filled in
- **6 Missing Files**: Need AGENTS.md creation for uncovered projects
- **No Central Index**: This file addresses that gap
- **Infrastructure Drift**: Manual docs become outdated quickly
- **Cross-Reference Gaps**: Limited automated linking between projects

---

## Strategic Documentation Priorities

### High Priority (Week 1-2)
1. ✅ **Create AGENTS.md Template** - Completed
2. ✅ **Create Missing AGENTS.md Files** - Completed (6 template files)
3. ✅ **Create Central Documentation Hub** - This file
4. 🔵 **Fill Template Content** - Project-specific details for 6 template files

### Medium Priority (Month 1-3)
1. **Automated Documentation Generation**: Infrastructure docs from Proxmox API
2. **Cross-Reference Automation**: Dependency scanning and linking
3. **Documentation Validation**: CI checks for AGENTS.md quality

### Low Priority (Month 3-6)
1. **Enhanced Cross-Referencing**: Advanced linking between projects
2. **Documentation Analytics**: Usage tracking and improvement identification
3. **Auto-Documentation**: Agent-driven AGENTS.md updates

---

## Maintenance Workflow

### When to Update AGENTS.md

- **Project Architecture Changes**: Major structural or technology changes
- **Agent Integration Changes**: New skills, workflows, or MCP servers
- **New Commands**: Significant new development or deployment commands
- **Quarterly Review**: Regular updates even without major changes

### Documentation Updates Process

1. Update relevant AGENTS.md file
2. Update AGENT_INDEX.md if project status changes
3. Update cross-references in related projects
4. Run validation checks if available
5. Commit with descriptive message: "docs: Update [project] AGENTS.md - [change summary]"

---

**Last Updated**: 2025-07-07
**Documentation Coverage**: 63/63 projects (100% coverage, 6 need content completion)
**Maintained By**: PortugalFuturista Documentation Team
**Next Review**: 2025-10-07 (quarterly)