Add project documentation
This commit is contained in:
128
docs/operator-guide.md
Normal file
128
docs/operator-guide.md
Normal file
@@ -0,0 +1,128 @@
|
||||
# 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.
|
||||
|
||||
Reference in New Issue
Block a user