Operator Surfaces

Which surface to use for setup, paper runs, runtime monitoring, review, and troubleshooting.

Which surface should you use?

Agentic Trader has several operator surfaces because different tasks need different levels of detail.

Surface	Best for	What to verify
No-argument launcher	choosing Web GUI, paper daemon, Ink, Rich, setup, or model-service paths	it explains choices before starting anything
CLI commands	setup, JSON checks, one-off paper runs, evidence capture	command output, exit code, persisted records
Rich menu	terminal navigation and quick status review	same backend/runtime truth as CLI JSON
Ink control room	live local monitoring, settings, recent runs, operator instructions	resize behavior, current runtime mode, latest activity
observer API	Web GUI attach flows and machine-readable status	dashboard, status, supervisor, broker, research payloads
Web GUI	browser-based command center and review panels	route-boundary validation, section errors, dashboard parity
docs site	product guidance, feature explanations, and contributor boundaries	docs match the runtime, not a desired future state

Shared truth rule

No surface should invent a private runtime model. If a screen shows runtime, broker, memory, review, or health state, that should come from shared contracts.

All screens should agree on the same account, broker backend, runtime mode, latest decision, readiness gates, and degraded states. When they do not agree, trust the lower-layer runtime and persistence evidence first.

Common operator tasks

Check whether the system is ready

Use:

agentic-trader setup-status --json
agentic-trader model-service status --json
agentic-trader webgui-service status --json
agentic-trader provider-diagnostics --json
agentic-trader v1-readiness --json
agentic-trader broker-status --json
agentic-trader finance-ops --json
agentic-trader supervisor-status --json
agentic-trader proposal-candidates --json
agentic-trader trade-proposals --json

These commands answer whether provider evidence, model readiness, broker mode, account/PnL/exposure evidence, runtime state, and daemon health are visible enough to continue.

Review a trade idea before it can execute

Scanner or research output should become a broker-free proposal candidate first, not an immediate order. Use proposal-candidate-create to persist a candidate, proposal-candidates to inspect scanner/research evidence, and proposal-candidate-promote to turn a checked candidate into a pending manual-review proposal. Use proposal-create only for manual paper-desk ideas, trade-proposals to inspect pending and terminal decisions, and proposal-approve or proposal-reject for the explicit human review step. Approval still goes through the configured paper or external-paper broker adapter and records an execution intent/outcome audit trail.

External-paper broker acknowledgements such as accepted stay in-flight until proposal-refresh reads the original broker order and proves a fill, partial-fill, cancel, or reject state.

The Web GUI Proposal Desk reads the same queue and can only call those explicit approve, reject, reconcile, or refresh contracts. It is not a generic broker console and does not create orders outside the proposal queue.

Run or review a paper cycle

Use the CLI for the first strict run, then review through CLI JSON, Rich/Ink, Web GUI panels, and the evidence bundle. Do not rely on a single UI card when broker/account or execution truth matters.

Troubleshoot a background service

Use supervisor-status --json, observer /supervisor, and recent log tails. Blocked gates, dead PIDs, stale heartbeat state, and stop requests should be visible instead of hidden behind a generic "not running" message.

Choose the first surface

Use agentic-trader without arguments for the product launcher. It should show setup, Web GUI, model-service, and daemon readiness, then ask which surface to open. It must not silently start a trading daemon. Use agentic-trader tui when you specifically want the Ink control room.

What the Web GUI is allowed to do

validate web input at the API boundary
delegate to existing runtime contracts
present operator-focused copy and controls
poll or refresh shared status safely

What the Web GUI is not allowed to do

create a parallel orchestration path
invent web-only execution semantics
hide safety gates behind optimistic UI
mutate operator intent through a loose chat path

Docs-specific surface rule

The docs app is also a surface. Its job is to explain the runtime and product workflows, not to create a second runtime story.

That means:

feedback copy must explain whether data is logged locally, forwarded to GitHub, or both
docs pages should reflect what is shipped, gated, scaffolded, or future scope
product memory, review evidence, and contributor .ai notes should be separated in language

Change checklist for surface work

confirm the backend contract first
confirm the UI is reading the right fields
confirm degraded states are visible
run at least one operator-facing QA pass when behavior changes

On this page