chore: keep widget sources only

2026-09-17 23:29:09 +03:00
commit e0404617d2
125 changed files with 8935 additions and 0 deletions
@@ -0,0 +1,43 @@
+---
+name: shd-agents-operations
+description: Use when the user asks to inspect SHD agents, controllers, diagnostics, tunnels, access rules, endpoints, monitoring or agent runtime actions.
+---
+
+# SHD agents operations
+
+See `references/agent-operations.md` before touching runtime, network or access
+configuration.
+
+## Diagnose first
+
+- Resolve the controller, user agent or tunnel identity from
+  `shd_agents_overview`, status and diagnostic tools.
+- Read current access policies, settings, history and async status before
+  proposing an action.
+- Keep diagnostics, configuration, endpoint publication and network routing as
+  separate operations. Never expose credentials, private keys or tunnel data.
+
+## Controller data and widgets
+
+- For a controller device list, call `shd_get_controller_source_inventory`, then
+  `shd_render_controller_devices_widget` with the complete result and scoped
+  `meta.sourceArgs`.
+- For current states across controllers, call `shd_get_home_live_state`, then
+  `shd_render_controller_live_state_widget`.
+- For one presence, binary state or numeric sensor statistics, call
+  `shd_get_controller_state_statistics`, then
+  `shd_render_controller_statistics_widget`. The server result is authoritative
+  for counts, intervals, durations, percentages, medians and hourly buckets;
+  do not calculate them from raw history in the model.
+- For raw time-series history, call `shd_get_controller_source_history`, then
+  `shd_render_controller_history_widget`. Keep the detailed rows in the widget
+  after a successful render and use plain text only when the UI call is
+  unavailable or fails.
+
+## High-impact actions
+
+Creating/closing tunnels, publishing or revoking endpoints, replacing access
+policies, rebooting an agent, changing exit-network routing or enabling
+monitoring requires an explicit target and user request. For asynchronous
+actions, return the operation ID, poll only as needed and report terminal
+status. Do not retry a network or reboot action blindly.
@@ -0,0 +1,5 @@
+interface:
+  display_name: "SHD agents operations"
+  short_description: "Diagnose agents and guarded runtime actions"
+policy:
+  allow_implicit_invocation: false
@@ -0,0 +1,14 @@
+# Agent operations contract
+
+Start with `shd_agents_overview`, `shd_get_controller_status`,
+`shd_agents_get_controller_diagnostics`, `shd_agents_get_diagnostics`, history
+and the relevant access-policy tools. Use `shd_agents_get_async_status` for an
+operation already returned by the server.
+
+Treat tunnels, endpoint publication/revocation, access-policy replacement,
+agent reboot, exit-node/network routing and controller/user-agent settings as
+high-impact mutations. Tools such as `shd_agents_create_tunnel`,
+`shd_agents_close_tunnel`, `shd_agents_publish_controller_endpoint`,
+`shd_agents_revoke_controller_endpoint`, `shd_agents_reboot_user_agent` and
+`shd_agents_force_exit_network_route` require explicit authorization and exact
+scope. Preserve audit/readback and never print secrets returned by diagnostics.