# Operator Guide

This guide explains how an operator uses Agentic OS day to day.

## Dashboard

The dashboard at `/` is the operations view. Use it to answer:

- What is running now?
- What needs approval or attention?
- Were recent tasks saved to memory and Obsidian?
- Are cloud model balances healthy?
- Are MCP servers loaded?

Main sections:

- **Active Tasks**: queued, running, and waiting approval tasks.
- **Attention Needed**: failed tasks, pending approvals, Obsidian push failures, and low/errored API balances.
- **Recent Findings**: compact summaries of completed reports.
- **Budgets**: OpenRouter, DeepSeek, and other configured cloud balances.
- **Platform Readiness**: MCP server status and tool counts.

## Inventory

Inventory describes vessels and onboard devices.

1. Open `/inventory`.
2. Create or edit a vessel with public IP/site notes.
3. Enable device slots such as `proxmox`, `pfsense`, `docker_vm`, `asterisk_geneseasx`, `fortigate`, or `fortiswitch`.
4. Add address, port, username, and secret only when they differ from environment defaults.

Secrets are encrypted before being stored. Do not put plaintext credentials in vessel notes.

## Creating a Task

1. Open `/tasks`.
2. Select **New task**.
3. Pick a quick template or enter a title and issue manually.
4. Select the vessel.
5. Review **What will be checked**.
6. Choose:
   - **Create & watch live** to go to the task page.
   - **Run in background** to return to the dashboard.

The preview is important: it shows which devices and check groups the agent will run. If the preview says no devices match, rewrite the issue with explicit device names or ask for a full stack health check.

Example issue text:

```text
check status of proxmox and pfsense
```

Expected preview:

- Proxmox: VM/LXC status, guest configuration, host health.
- pfSense: system status, interfaces, gateways, firewall/NAT when requested.

## Understanding Live Status

The task page shows the run as phases:

1. **Context** — searching prior memory and Obsidian notes.
2. **Plan** — deciding scope and diagnostic approach.
3. **Connect** — connecting to MCP/device targets.
4. **Diagnose** — running checks.
5. **Analyze** — reasoning about results.
6. **Report** — writing final report and artifacts.

The timeline is intentionally concise. Expand command or evidence details only when you need raw output.

## Approvals

Some actions require approval:

- MCP source patches proposed by MCP development.
- Config-changing tool calls.
- Git pushes for generated MCP changes when auto-push is disabled.

When a task enters `waiting_approval`, open it and review the approval card. Approve only if the proposed change matches the intended fix and the risk is acceptable.

## Reports

Reports are structured to be readable first and evidential second.

Default sections:

- **Scope**: what was requested and what was actually checked.
- **Report**: summary, scope checked, findings, recommendations.
- **Evidence**: collapsed per-tool output and formatted tables.
- **Saved Artifacts**: memory ID, Obsidian path, push status.
- **Models & Cost**: LLM routing and cost summary.
- **Run History**: follow-up runs on the same task.

Important rule: a report should not imply a device was checked if it was not in `scope_checked` or `devices_checked`.

## Continuing or Restarting Tasks

Use **Continue investigation** when the first run is incomplete or you want targeted follow-up checks. The agent receives prior findings and your follow-up note.

Use **Restart from scratch** when you want to discard run history and rerun the original task.

Use **Stop task** for stuck or no-longer-needed queued/running tasks.

## Memory and Obsidian

At task completion:

- Project memory receives a durable summary under `MEMORY_TASK_PROJECT_ID`.
- Obsidian receives a markdown note under `OBSIDIAN_TASKS_FOLDER`.
- The task report shows IDs/paths and push errors if any.

If Obsidian push fails, the note may still exist in the backend runtime vault clone. Fix git/reachability and rerun or inspect logs before assuming the report was lost.

## Rules and Skills

Rules and skills guide the agent.

- `/rules`: controls device selection, priority, severity hints, and standard checklist hints.
- `/skills`: adds deeper procedures for known scenarios such as VoIP, DNS/captive portal, or safe pfSense changes.

Use rules for **which devices to check**. Use skills for **how to investigate** a class of problem.

## MCP Page

Use `/mcp` to inspect MCP server health, tools, reload/upgrade servers, or trigger controlled development for MCP bugs.

If a tool fails because of infrastructure permissions, fix the target system. If a tool fails because the MCP is missing a capability or has a code exception, MCP development may propose a patch.