operator
adfcd2e602
- box passkey [show|fetch] (+ muse passkey): documents VM-only passkey (/srv/box/passkey.txt, fallback /etc/netvm/passkey.txt on 34.139.37.135), probes VM over SSH with graceful fallback; --json supported. No secrets on bl. - approvals: request_key_approval / check_node_key_request; KEY_APPROVAL status surfaced in `box approvals check`; allow/deny resolve + audit to box-ctl.jsonl; never auto-approved. New `box approvals request-key <node> --reason`. - box lookup (summary|fleet|threads|unread|approvals|key|docs) and docs-lookup engine with lookup_internal/ database (docs_internal symlink). - muse-tmux: non-TTY attach falls back to scrollback capture; prune NameError fix. - box/muse passthrough for tmux/muse/docs; thread list/view alias + prefix resolve. - Docs: AGENTS.md, AGENT-TOOLING.md, BOX-WEB-SURFACE-GUIDE.md, README. - Tests: key-approval + passkey tests; sync stale sidechat UUIDs and manifest name. - .gitignore runtime trackers (subagent-sessions, conversation-nudge-tracker).
78 lines
2.7 KiB
Markdown
78 lines
2.7 KiB
Markdown
# Internal Agent & Operator Documentation (`docs_internal/`)
|
|
|
|
> **Box is the main surface.** All operator work goes through Box (`box.muse-dev.online`). The web UI, `box` CLI, and agents share the same API endpoints, protocol grammar, and lookup structures.
|
|
|
|
Welcome to `docs_internal/`. This directory serves as a dual Markdown (`.md`) and structured JSON (`.json`) lookup database for autonomous agents, background daemons, and off-board operators across NetVM.
|
|
|
|
---
|
|
|
|
## 1. Directory Structure
|
|
|
|
```text
|
|
docs_internal/
|
|
├── manifest.json # Master database manifest and collections schema
|
|
├── README.md # This file
|
|
├── sentence_structure.json # Agent sentence structures, protocols, and grammar
|
|
├── SENTENCE-STRUCTURE.md # Comprehensive guide to agent communication protocols
|
|
├── regex_patterns.json # Master regular expression database with test fixtures
|
|
├── REGEX-PATTERNS.md # Guide to regex parsing, capture groups, and testing
|
|
├── assistive_surfaces.json # UI tabs, DOM selectors, data-testids & REST endpoints for box.muse-dev.online
|
|
├── SURFACES.md # Guide to interacting with box.muse-dev.online
|
|
├── cli_tools.json # CLI command catalog and syntax database
|
|
├── CLI-TOOLS.md # Guide to super, box, and muse CLI tools
|
|
├── fleet_nodes.json # Fleet node topology, namespaces, and ports
|
|
└── FLEET-NODES.md # Guide to fleet agents and network topology
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Using the CLI Lookup Engine
|
|
|
|
You can query this database directly from the shell using `super docs` or `box docs`:
|
|
|
|
### 2.1 Full-Text Search
|
|
```bash
|
|
box docs search "work order"
|
|
box docs search "cdp"
|
|
```
|
|
|
|
### 2.2 Inspect Assistive Surfaces for `box.muse-dev.online`
|
|
```bash
|
|
# List all surfaces and views
|
|
box docs surfaces
|
|
|
|
# Inspect a specific surface (e.g. jobs, dms, loops, dashboard)
|
|
box docs surfaces jobs
|
|
box docs surfaces dms
|
|
```
|
|
|
|
### 2.3 Inspect Agent Sentence Grammar & Protocols
|
|
```bash
|
|
# List all sentence structures
|
|
box docs sentence
|
|
|
|
# View full structure specification
|
|
box docs sentence work_order
|
|
box docs sentence result
|
|
```
|
|
|
|
### 2.4 Regex Passing & Testing
|
|
```bash
|
|
# List available regex patterns
|
|
box docs regex
|
|
|
|
# Test a string against a specific pattern
|
|
box docs regex work_order --test "[WO:7fce46e0] [from super] Audit — Check status"
|
|
|
|
# Parse an agent sentence through all patterns to extract captured tokens
|
|
box docs parse "[RESULT 7fce46e0] OK Verified 14 endpoints"
|
|
```
|
|
|
|
### 2.5 Machine-Readable JSON Output
|
|
Add `--json` to any command for structured JSON output:
|
|
```bash
|
|
box docs sentence work_order --json
|
|
box docs surfaces dashboard --json
|
|
box docs parse "[CLAIM 7fce46e0]" --json
|
|
```
|