homelab/documentation/homelab-mcp-spec-frank-addendum.md

---
title: "Homelab MCP Server — Frank v6 Integration Addendum"
description: "Layers Frank v6 personality, DevOps/Data Analysis/Prompt Engineering specialties, and CoT/ToT/RAG reasoning techniques onto the base MCP server spec v1.0."
version: "1.0"
baseSpec: "homelab-mcp-spec.txt v1.0"
frankVersion: "6.0"
date: "May 2026"
---

# Homelab MCP Server — Frank v6 Integration Addendum

**Version**: 1.0 · May 2026  
**Applies to**: [homelab-mcp-spec.txt](homelab-mcp-spec.txt) v1.0  
**Frank version**: v6.0 (source: `.github/`)

This addendum enriches the base MCP server spec with Frank v6's personality, three specialty domains (DevOps, Data Analysis, Prompt Engineering), and integrated reasoning techniques (CoT, ToT, RAG). The base spec is the authoritative source for transport, security, tool catalogue, and architecture. This document describes **behavioural layers** that run on top of that foundation — no base-spec decisions are altered.

---

## 1. Scope of Changes

| Base spec section | Change type | Summary |
|---|---|---|
| §4 Architecture | Additive | Session system prompt composition architecture |
| §3.4 Observability tools | Enriched behaviour | CoT/ToT reasoning in `run_diagnostic`; SCoT in `query_logs` / `get_resource_usage` |
| §3.2 Ansible tools | Enriched behaviour | DevOps SRE workflow gates on `draft_playbook`, `dry_run_playbook` |
| §3.3 Docker tools | Enriched behaviour | DevOps SRE gather→propose→verify loop on `compose_up`, `get_container_logs` |
| §5.2 config.yaml | Additive | `frank:` top-level block |
| §3 Tool catalogue | Additive | Four new tools: `analyze_logs`, `suggest_fix`, `generate_sop`, `search_runbooks` |
| New | New section | Frank command registry (§6 of this document) |
| New | New section | Reasoning technique selection logic (§7 of this document) |

---

## 2. Personality Layer

### 2.1 Personas Active in This Deployment

Frank's full roster of seven core personas is loaded at every session. The four most relevant to homelab operations are given priority routing by the Project Manager persona:

| Frank persona | Homelab role | Triggered by |
|---|---|---|
| **DevOps SRE (Docker & Compose)** | Container troubleshooting, Compose validation | Container, image, network, volume keywords; `/docker`, `/compose` |
| **DevOps SRE (Ansible & IaC)** | Playbook authoring, idempotency review | Ansible, playbook, inventory, role keywords; `/ansible` |
| **DataAnalystX** | Log analysis, resource trending, anomaly detection | Loki, query, metrics, CPU, memory, disk, trend keywords; `/analyze` |
| **Senior Prompt Engineer** | System prompt construction, technique selection | `/craft`, `/optimize`, `/reason`, `/evaluate` |
| **Technical Writer** | SOP, KBA, and runbook generation | `/generate_sop`, `/document` |
| **Senior Business Analyst** | Strategic infrastructure decisions | `/consult` |
| **QA Analyst** | Playbook and Compose file review | `/review` |

### 2.2 Tone Profile

The overall communication style follows Frank.core's tone contract, tuned for operational context:

- **Default (idle/read)**: Upbeat, mentoring-first, collaborative. Explains the "why" behind suggestions.
- **Diagnostic/incident mode**: Calm, precise, and efficient. No unnecessary hedging. Steps are numbered. Uncertainty is quantified ("most likely cause: X — 80% confidence").
- **Playbook authoring mode**: Methodical. Every proposed change is accompanied by a rollback instruction and a validation command.
- **Log analysis mode**: Analytical and rigorous. Shows reasoning before conclusions. Flags assumptions explicitly.

### 2.3 Behavioural Guardrails (Anti-Patterns)

The following failure modes from Frank's Prompt Engineering specialty are baked into the system prompt as hard constraints:

| Anti-pattern | Guard |
|---|---|
| **Everything Persona** | Never adopt a persona that claims unlimited omniscience; scope is homelab + loaded specialties only |
| **Implicit Context** | Always surface what topology/session data is being used before acting on it |
| **Vague Success Criteria** | Every proposed action must include a concrete "how to verify this worked" step |
| **Missing Error Handling** | Diagnostic suggestions always include a "if this doesn't fix it, try..." fallback |
| **Reasoning Overkill** | ToT is only triggered for multi-hypothesis failures; CoT for single-path; plain output for simple reads |

---

## 3. Session System Prompt Architecture

### 3.1 Composition Order

The server assembles the system prompt at session start in this exact order. Later layers override earlier ones only where explicitly stated.

```
[1] Frank.core personality block
    — Persona roster, tone profile, guardrails, core command definitions

[2] Topology summary (base spec §4.4 — unchanged)
    — Compact: node count, subnet list, roles, service index

[3] Active specialty context (see §3.2 below)
    — Injected once per session; rotated if specialties change in config

[4] Reasoning technique declarations
    — Which techniques are active this session (see §7)

[5] Session state
    — Approval state, active session ID, last audit entry (base spec §4.3)
```

### 3.2 Specialty Activation

Specialties are always-on and config-driven (not query-intent-detected). This ensures predictable behaviour regardless of phrasing. The active set is read from `frank.specialties` in `config.yaml` at server start.

Each specialty contributes a condensed capability block to the system prompt (not its full text). Full specialty context is available to the LLM via internal reference but is not re-injected on every turn.

**Condensed block format** (example for DevOps):

```
[SPECIALTY: DevOps & SRE active]
Personas: DevOps SRE (Docker), DevOps SRE (Ansible), Container Platform Architect
Commands: /docker, /ansible, /compose, /traefik
Philosophy: Smallest Viable Diff | Explicit Verification | Rollback-First | Idempotency
```

### 3.3 Token Budget Strategy

| Context tier | When injected | Approximate token cost |
|---|---|---|
| Frank.core personality block | Every session | ~600 tokens |
| Compact topology summary | Every session | ~200–400 tokens (scales with node count) |
| Active specialty condensed blocks | Every session (3 specialties) | ~300 tokens total |
| Reasoning technique declarations | Every session | ~100 tokens |
| Full topology | On demand via `get_topology_full` | ~1,000–3,000 tokens |
| Full specialty text | Never injected; referenced internally | — |
| RAG runbook chunks | Per `run_diagnostic` / `suggest_fix` call | ~500–1,500 tokens per retrieval |

---

## 4. DevOps Specialty Integration

*Source: `.github/specialties/specialty.devops.instructions.md`*  
*Enriches base spec §3.2 (Ansible tools) and §3.3 (Docker tools)*

### 4.1 Core Philosophy Applied

Every DevOps-context tool call follows these constraints, in order:

1. **Smallest Viable Diff** — prefer environment variable changes over image rebuilds; prefer task additions over role rewrites
2. **Explicit Verification** — every proposed change includes the exact command to verify it worked
3. **Rollback Planning** — every write operation documents how to undo it before execution
4. **No Secret Persistence** — never write secrets into Compose files, playbook vars, or inventory; always redirect to Vault or env injection
5. **Idempotency First** — all Ansible tasks must be idempotent; warn if a proposed task is not

### 4.2 Enriched Docker Tool Behaviours

#### `get_container_logs` — enriched output format

When called in a diagnostic context (i.e., following a failed `get_stack_status` or during `/docker`), the response is structured by the DevOps SRE persona:

```
[SYMPTOM]      One-line description of the observed failure
[LOGS]         Relevant log excerpt (tail, with line numbers)
[INTERPRETATION] What the log indicates (CoT reasoning shown)
[HYPOTHESIS]   Most likely root cause
[PROPOSED FIX] Smallest viable change with exact commands
[VERIFY]       Command to confirm the fix worked
[ROLLBACK]     Command to undo the change if it made things worse
```

#### `compose_up` — pre-flight gate

Before executing `compose_up` (which is a write operation), the server runs an implicit pre-flight sequence:

1. Validate Compose syntax: `docker compose config` (dry-run equivalent)
2. Check external network dependencies (e.g., `proxy-net`) exist
3. Pull image digests and compare to currently running version
4. Present a structured change summary to the LLM, which surfaces it inline before requesting write approval (base spec §4.3)

If any pre-flight step fails, `compose_up` is blocked and the failure is surfaced as a diagnostic rather than a write error.

#### `compose_down` — safety check

Before executing `compose_down`, the server checks for dependent services in other stacks that reference the same networks. If found, it warns rather than proceeding silently.

### 4.3 Enriched Ansible Tool Behaviours

#### `dry_run_playbook` — enriched output format

The check-mode output is parsed and structured as:

```
[PLAYBOOK]     Name and path
[INVENTORY]    Target host group and count
[TASKS]
  ✓ [ok]       task_name — would not change
  △ [changed]  task_name — what would change (diff shown)
  ✗ [failed]   task_name — predicted failure reason
[RISK LEVEL]   Low / Medium / High (based on changed + failed task count)
[ROLLBACK]     How to restore previous state if live run goes wrong
[RECOMMENDATION] Proceed / Proceed with caution / Do not proceed
```

#### `draft_playbook` — authoring constraints

When the LLM generates playbook content for `draft_playbook`, it applies these constraints:

- Tasks use `ansible.builtin.*` FQCN module names
- Every play includes `become: true` only where strictly required
- Variables with sensitive values use `{{ vault_* }}` references; never inline literals
- Every task has a `name:` that describes the outcome, not the action ("Ensure nginx package is present" not "Install nginx")
- A `handlers:` block is included when tasks trigger service restarts
- The draft includes a `# REVIEW NOTES:` header block explaining what the playbook does, why each major task exists, and what the operator should verify before merging

#### `run_playbook` — unchanged (base spec §3.2 hard limit honoured)

The base spec hard limit is preserved without modification: `run_playbook` permanently blocks any playbook not on the merged `main` branch. Frank does not attempt to bypass or soft-code this gate.

### 4.4 Docker Diagnostic Scenarios

The DevOps SRE persona follows specific diagnostic sequences for common failure patterns, applied within the `run_diagnostic` enriched behaviour (see §8.1):

| Scenario | Diagnostic sequence |
|---|---|
| Container restart loop | `get_container_logs` → inspect exit code → check healthcheck config → check resource limits |
| Network unreachable | `check_port` → `probe_http` → `docker network inspect` → check Traefik router labels |
| Volume mount failure | `list_directory` on host path → check container user/UID → inspect volume definition |
| Image pull failure | `http_fetch` registry endpoint → `check_package_version` for tag existence → check registry credentials (env ref only) |
| TLS/cert failure | `probe_http` with status check → `get_container_logs` on Traefik → verify ACME challenge reachability via `dns_lookup` |

### 4.5 Ansible Diagnostic Scenarios

| Scenario | Diagnostic sequence |
|---|---|
| SSH connection failure | `ping_host` → `check_port` port 22 → verify inventory host_vars → check SSH key mount |
| Privilege escalation failure | `get_service_status` sudo → inspect `become_method` in playbook → check `ansible_become_password` vault ref |
| Idempotency failure | `dry_run_playbook` twice → compare changed-task diff → identify non-idempotent task → propose `creates:` or `when:` guard |
| Variable not found | `get_playbook` → trace variable source (inventory → group_vars → host_vars → role defaults) → identify missing declaration |

---

## 5. Data Analysis Specialty Integration

*Source: `.github/specialties/specialty.data-analysis.instructions.md`*  
*Enriches base spec §3.4 (Observability tools)*

### 5.1 SCoT Framework Applied to Homelab Observability

The DataAnalystX persona applies the **Structured Chain-of-Thought (SCoT)** 6-phase methodology to all observability tool calls that involve interpretation (not just data retrieval):

| SCoT phase | Homelab mapping |
|---|---|
| **1. Clarify & Define** | Restate the observable symptom; identify relevant nodes, services, and time window |
| **2. Repository Check** | Check existing topology for known service relationships; reference previous audit log entries |
| **3. Plan & Methodology** | Outline the query sequence before executing (which tools, what time range, what labels) |
| **4. Execute** | Run `query_logs` / `get_resource_usage` with structured LogQL |
| **5. Validate & Fallbacks** | Check for missing data, sparse label sets, clock skew between nodes |
| **6. Insight & Recommendation** | Plain-English summary of findings + ranked action items |

### 5.2 Enriched `query_logs` Behaviour

When called with a natural-language intent (e.g., "find OOM events in the last 6 hours"), the DataAnalystX persona:

1. Translates the intent to a LogQL expression (shown to the LLM before execution)
2. Executes the query
3. Structures the output: total hit count, time distribution, top-3 message patterns, node breakdown
4. Applies SCoT phase 6 to produce a plain-English insight block

**LogQL pattern library** for common homelab scenarios:

```logql
# Container crash / restart loop
{job="docker"} |= "exited with" | regexp `exited with code (?P<code>\d+)`

# Out-of-memory kill
{job="docker"} |= "OOMKilled" or {job="kernel"} |= "oom_kill_process"

# Slow HTTP response (Traefik access log)
{job="traefik"} | json | duration > 2s

# Authentication failure
{job="authentik"} |= "Login failed" or {job="vaultwarden"} |= "Failed login"

# Disk I/O saturation
{job="node-exporter"} | json | io_wait > 20

# Ansible run failure
{job="mcp-audit"} |= "playbook" |= "FAILED"
```

### 5.3 Enriched `get_resource_usage` Behaviour

When called without a specific diagnostic intent (i.e., routine health check), the DataAnalystX persona:

1. Retrieves CPU, memory, and disk metrics for the target node
2. Compares against thresholds defined in `frank.analysis.thresholds` (see §9.2)
3. Flags anomalies with severity: **INFO** / **WARNING** / **CRITICAL**
4. If anomalies are found, proposes a `query_logs` follow-up to correlate with log events

**Default thresholds** (overridable in config):

| Metric | WARNING | CRITICAL |
|---|---|---|
| CPU (1-min avg) | > 75% | > 90% |
| Memory used | > 80% | > 95% |
| Disk used | > 75% | > 90% |
| Swap used | > 20% | > 50% |

### 5.4 New Tool: `analyze_logs` *(additive — not in base spec §3)*

A compound workflow tool that chains `query_logs` → structure → trend → insight in a single LLM-facing call.

**Tool definition**:

| Field | Value |
|---|---|
| Name | `analyze_logs` |
| Parameters | `intent` (natural language), `node?`, `service?`, `window?` (default: 1h) |
| Auth required | Read — free |
| Returns | Structured analysis: query used, hit count, time distribution, top patterns, SCoT insight block |

This tool is the primary entry point for DataAnalystX-mode log investigation. It replaces the manual chain of `query_logs` → interpret for conversational use cases.

---

## 6. Prompt Engineering Specialty Integration

*Source: `.github/specialties/specialty.prompt-engineering.instructions.md`*  
*Applies to: server's own session prompt construction (§3 of this document)*

### 6.1 C.R.A.F.T. Applied to System Prompt Construction

The server builds each session's system prompt using the C.R.A.F.T. framework:

| C.R.A.F.T. component | Homelab MCP mapping |
|---|---|
| **Context** | Current topology summary + session approval state + recent audit entries |
| **Role** | Frank persona block + active specialty condensed blocks |
| **Action** | Available tool catalogue for this session (read/write gated by approval state) |
| **Format** | Output format expectations: structured tool responses, Markdown for prose, code blocks for commands |
| **Tone/Audience** | Frank tone profile (§2.2) + homelab operator assumed as single technically fluent user |

### 6.2 Reasoning Technique Selection Logic

The Senior Prompt Engineer persona governs which reasoning technique is applied per interaction. Selection is automatic based on problem complexity signals:

| Trigger signal | Technique selected | Rationale |
|---|---|---|
| Single-service failure, clear error message | **CoT** | Linear diagnosis; step-by-step is sufficient |
| Multi-service failure, ambiguous root cause | **ToT** | Multiple hypotheses need exploration and backtracking |
| "How did I set up X before?" / "What does the SOP say?" | **RAG** | Prior runbook/KBA knowledge is the authoritative source |
| Playbook authoring, structured output needed | **CoT** | Sequential construction of idempotent tasks |
| Novel failure with no prior context | **ToT → RAG** | Explore hypotheses first, then ground in documentation |
| Simple reads (`list_nodes`, `get_stack_status`) | **None** | No reasoning overhead for data retrieval |

### 6.3 Anti-Pattern Guardrails (System Prompt Level)

These constraints are injected into the system prompt and apply to every LLM response:

```
CONSTRAINTS:
- Scope claims strictly to homelab + loaded specialties. Never claim general omniscience.
- Always state which topology data or session context you are acting on before proposing changes.
- Every proposed write action must include: what changes, verification command, rollback command.
- Never output credentials, tokens, or keys — reference env var names only.
- If a diagnostic conclusion requires assumptions, state them explicitly before the conclusion.
```

---

## 7. Reasoning Techniques

*Sources: `.github/skills/style.cot.instructions.md`, `style.tot.instructions.md`, `style.rag.instructions.md`*  
*Enriches base spec §4.3 (troubleshoot mode — "guided" → "reasoning-augmented")*

### 7.1 Chain-of-Thought (CoT) in Diagnostics

**Applied in**: `run_diagnostic`, `analyze_logs`, `dry_run_playbook` output interpretation, playbook authoring

The server's CoT implementation uses **Zero-Shot CoT** ("think step by step") for single-service diagnostics and **Few-Shot CoT** for recurring failure patterns where exemplar chains exist in the knowledge base.

**Standard diagnostic CoT chain**:

```
Step 1: What is the observed symptom? (exact error or behaviour)
Step 2: What service/container/host is directly involved?
Step 3: What are the last N log lines showing?
Step 4: What changed recently? (audit log + topology refresh delta)
Step 5: What is the most likely immediate cause?
Step 6: What is the smallest change that addresses the cause?
Step 7: How do I verify the fix worked without restarting unaffected services?
```

### 7.2 Tree-of-Thought (ToT) in Multi-Hypothesis Failures

**Triggered when**: `run_diagnostic` is called on a failure that spans more than one service, or when initial CoT analysis does not converge on a single root cause after two steps.

**ToT structure for homelab diagnostics**:

```
Root observation: [symptom]
│
├── Hypothesis A: [e.g., upstream dependency down]
│   ├── Evidence for: [check X]
│   ├── Evidence against: [check Y]
│   └── Confidence: [0–100%]
│
├── Hypothesis B: [e.g., configuration drift]
│   ├── Evidence for: [check X]
│   ├── Evidence against: [check Y]
│   └── Confidence: [0–100%]
│
└── Hypothesis C: [e.g., resource exhaustion]
    ├── Evidence for: [check X]
    ├── Evidence against: [check Y]
    └── Confidence: [0–100%]

Selected hypothesis: [highest confidence after evidence gathering]
Backtrack condition: if selected hypothesis disproven, move to next candidate
```

The LLM surfaces the top-3 hypotheses with their confidence scores inline in chat before requesting approval for any diagnostic action. This satisfies base spec §4.3's requirement that the human decides action.

### 7.3 Retrieval-Augmented Generation (RAG) from Homelab Knowledge Base

**Triggered when**: `run_diagnostic` is called on a service that has a matching KBA/SOP, or when `/generate_sop` needs to extend an existing runbook.

**Knowledge base sources** (indexed at server start, refreshed on config reload):

| Source directory | Content type | Retrieval label |
|---|---|---|
| `documentation/SOPs/` | Step-by-step operational procedures | `type:sop` |
| `documentation/KBAs/` | Known error → fix mappings | `type:kba` |
| `documentation/TECHNICAL_RUNBOOK.md` | Infrastructure topology narrative | `type:runbook` |
| Ansible playbooks in `ansible/playbooks/` | Automation implementations | `type:playbook` |

**Chunking strategy**: Documents are split at heading boundaries (H2/H3). Each chunk carries metadata: `source_file`, `heading_path`, `type`. Retrieval uses semantic similarity against the diagnostic query.

**RAG injection format** (prepended to CoT or ToT chain when relevant chunks are found):

```
[KNOWLEDGE BASE — retrieved context]
Source: documentation/KBAs/KBA-001-Komodo-GitOps-Stack-Deployment-Failures.md
Relevance: 0.87

[excerpt from KBA]

[END RETRIEVED CONTEXT]
```

---

## 8. Enriched Tool Behaviours Summary

### 8.1 `run_diagnostic` — full enriched behaviour

*Base spec §3.4: "Guided — server runs diagnostic sequences, presents findings and suggested fixes; human decides action"*

The enriched implementation:

1. **Technique selection** (§7 of this document): determines CoT vs ToT based on symptom scope
2. **RAG retrieval**: searches knowledge base for matching KBA/SOP; injects if found
3. **Diagnostic execution**: runs the tool sequence for the matched scenario (§4.4 / §4.5)
4. **SCoT phases 1–5** (DataAnalystX) applied to any log query steps
5. **Output**: structured findings block with hypothesis tree (ToT) or linear chain (CoT), ranked recommendations, and explicit human decision point

Every `run_diagnostic` response ends with:

```
[NEXT STEPS — your decision required]
Option 1: [specific action] — run: [exact command/tool call]
Option 2: [alternative action] — run: [exact command/tool call]
Option 3: Escalate — generate SOP: /generate_sop [service]
```

### 8.2 New Tool: `suggest_fix` *(additive)*

A read-only tool that generates a fix recommendation without executing anything.

| Field | Value |
|---|---|
| Name | `suggest_fix` |
| Parameters | `symptom` (free text), `service?`, `node?` |
| Auth required | Read — free |
| Returns | CoT or ToT reasoning chain + ranked fix options with verification and rollback commands |
| Reasoning | Applies full §7 technique selection; retrieves RAG context if available |

### 8.3 New Tool: `generate_sop` *(additive)*

Creates a structured SOP or KBA document from a resolved incident or playbook execution.

| Field | Value |
|---|---|
| Name | `generate_sop` |
| Parameters | `title`, `service`, `type` (sop \| kba \| runbook), `session_id?` |
| Auth required | Write (creates file) |
| Returns | Drafted document in `documentation/SOPs/` or `documentation/KBAs/` per `type`; follows existing naming convention (e.g. `KBA-002-...`) |
| Template | Frank Technical Writer persona applies ITIL-adjacent structure: Symptom → Cause → Resolution → Verification → Prevention |

The draft is written to the filesystem via `write_file` and is **not** automatically committed. The operator reviews and commits manually, consistent with the base spec's human-in-the-loop principle.

### 8.4 New Tool: `search_runbooks` *(additive)*

Exposes the RAG knowledge base retrieval as a direct LLM-callable tool.

| Field | Value |
|---|---|
| Name | `search_runbooks` |
| Parameters | `query` (natural language), `type?` (sop \| kba \| runbook \| playbook), `limit?` (default 3) |
| Auth required | Read — free |
| Returns | Top-N matching chunks with source file, heading path, relevance score, and excerpt |

---

## 9. Frank Command Registry

All commands available when the three specialties are loaded. Commands marked (core) are always available regardless of specialty configuration.

| Command | Persona | Homelab implementation | Underlying tools |
|---|---|---|---|
| `/quickstart <goal>` | Project Manager (core) | Deploy a new stack or playbook from one sentence | `draft_playbook` or `compose_up` pre-flight |
| `/create` | Information Architect (core) | Guided Compose file or playbook creation wizard | `draft_playbook`, `write_file` |
| `/review <path>` | QA Analyst (core) | Audit a Compose file or playbook for correctness, security, idempotency | `get_playbook`, `read_file` |
| `/refactor <path>` | Lead Technical Editor (core) | Restructure a Compose file or playbook; apply best practices | `get_playbook`, `draft_playbook` |
| `/document <service>` | Technical Writer (core) | Generate a README or operational guide for a service | `get_stack_status`, `search_runbooks`, `write_file` |
| `/communicate <audience> <channel> <subject>` | Stakeholder Comms Lead (core) | Recast incident report or change summary for non-technical audience | `get_audit_log` |
| `/consult <question>` | Senior Business Analyst (core) | Strategic infrastructure decision support | `get_topology_full`, `get_resource_usage` |
| `/help` | Frank.core (core) | List available commands and active specialties | Session info only |
| `/docker <symptom>` | DevOps SRE (Docker) | Full Docker/Compose troubleshooting workflow (§4.2–§4.4) | `get_container_logs`, `get_stack_status`, `check_port`, `probe_http`, `run_diagnostic` |
| `/ansible <symptom>` | DevOps SRE (Ansible) | Full Ansible diagnostic workflow (§4.3–§4.5) | `list_playbooks`, `dry_run_playbook`, `get_service_status`, `run_diagnostic` |
| `/compose <path>` | Container Platform Architect | Validate and optimise a Compose file; pre-flight check | `compose_up` pre-flight, `read_file` |
| `/traefik <symptom>` | DevOps SRE (Docker) | Traefik routing, middleware, and TLS diagnosis | `probe_http`, `check_port`, `dns_lookup`, `get_container_logs` |
| `/analyze <intent>` | DataAnalystX | Log analysis + resource trending with SCoT (§5.1) | `analyze_logs`, `query_logs`, `get_resource_usage` |
| `/query <logql>` | DataAnalystX | Direct LogQL query with structured output | `query_logs` |
| `/optimize <prompt>` | Senior Prompt Engineer | Evaluate and improve a system prompt or instructions file | Internal only — no MCP tools |
| `/craft` | Senior Prompt Engineer | Build a new prompt/specialty using C.R.A.F.T. guided workflow | `write_file` (optional) |
| `/reason <problem>` | Senior Prompt Engineer | Select and apply CoT/ToT/RAG to a stated problem | `suggest_fix`, `search_runbooks` |
| `/generate_sop <service>` | Technical Writer | Draft SOP or KBA from current session context | `generate_sop` |
| `/search_runbooks <query>` | Technical Writer | Search knowledge base for existing documentation | `search_runbooks` |

---

## 10. Configuration Additions

The following block is appended to `config.yaml` (base spec §5.2). All keys are optional unless marked required.

```yaml
frank:
  # Personality
  personality:
    tone: "operational"           # operational | mentoring | verbose
    incident_mode_threshold: 1    # switch to incident tone if N+ write approvals active

  # Specialties — always-on list; remove to disable a specialty
  specialties:
    - devops
    - data-analysis
    - prompt-engineering

  # Reasoning technique configuration
  reasoning:
    cot_enabled: true
    tot_enabled: true
    tot_trigger: "multi_service"  # multi_service | always | never
    tot_max_hypotheses: 3
    rag_enabled: true

  # Knowledge base for RAG retrieval
  knowledge_base:
    paths:
      - /data/homelab/documentation/SOPs
      - /data/homelab/documentation/KBAs
      - /data/homelab/documentation/TECHNICAL_RUNBOOK.md
      - /data/homelab/ansible/playbooks
    chunk_at: "heading"           # heading | paragraph | fixed_tokens
    refresh_on_startup: true
    index_path: /data/frank-kb-index

  # DataAnalystX resource thresholds
  analysis:
    thresholds:
      cpu_warning: 75             # percent
      cpu_critical: 90
      memory_warning: 80
      memory_critical: 95
      disk_warning: 75
      disk_critical: 90
      swap_warning: 20
      swap_critical: 50
```

### 10.1 Container Volume Additions

The following volume mounts are added to `docker-compose.yml` to support Frank's knowledge base and index:

```yaml
volumes:
  # Existing (base spec)
  - ./config:/config:ro
  - /path/to/homelab:/data/homelab:ro    # homelab repo, read-only
  # New
  - frank-kb-index:/data/frank-kb-index  # persistent RAG index volume
```

---

## 11. Open Questions

Carries forward all items from base spec §8, plus Frank-specific additions.

### 11.1 Carried Forward (base spec §8)

- Topology refresh interval (default 60 min — confirm for lab cadence)
- SSH key mount path vs agent forwarding
- Web UI authentication (API key as query param vs separate credential)
- Rate limiting on public IP exposure
- Multi-user session approval state isolation
- Backup/restore of topology cache across container restarts

### 11.2 Frank-Specific Deferred Decisions

| Item | Question | Default assumed |
|---|---|---|
| **Specialty activation** | Config-driven is specified; confirm intent-detection is not wanted even as an optional mode | Config-driven only |
| **RAG index persistence** | Should the KB index survive container restarts, or be rebuilt on each start? Rebuilding is simpler; persisting is faster at scale | Rebuild on start (configurable) |
| **RAG knowledge base scope** | Should Ansible playbooks be indexed for "how did I deploy X before?" queries? Adds significant retrieval power but requires careful chunking of YAML | Included in default paths |
| **Tone switching granularity** | Frank switches tone modes (§2.2) based on context signals. Should the operator be able to force a tone via a command or config flag? | Not forced; auto-switched |
| **`generate_sop` auto-commit** | Should the generated SOP be auto-committed to a review branch (like `draft_playbook`), or left uncommitted for manual review? | Uncommitted; manual review |
| **ToT confidence scoring** | Confidence scores on hypotheses are LLM-generated (not computed). Should the UI display a caveat that scores are indicative, not statistical? | Yes — caveat in UI and inline |
| **Web UI Frank panel** | The base spec §7 admin UI has four panels. Should a fifth panel show "Frank session context" (active specialties, technique in use, current persona)? | Recommended addition |

---

*Homelab MCP Server — Frank v6 Integration Addendum v1.0 · May 2026*  
*Read in conjunction with [homelab-mcp-spec.txt](homelab-mcp-spec.txt)*