hive-sh4re + docs: extract Approval lifecycle prose (#717 batch 3)

docs/approvals.md

@@ -88,6 +88,55 @@ creates the container; subsequent ones rebuild it with new config.
 This gives the manager (and operator) an explicit review gate on the
 initial configuration before any container is created.
 
+### Approval kinds (wire shapes)
+
+`ApprovalKind` carries five variants; each maps to a different
+`commit_ref` encoding because that field is overloaded as the
+kind-specific payload carrier.
+
+- `ApplyCommit` — `commit_ref` is the manager-supplied git sha
+  (7-40 hex chars). The canonical, hive-c0re-vouched sha after the
+  proposal fetch lives in `fetched_sha` on the same `Approval`
+  row (only `ApplyCommit` populates it). See the End-to-end flow
+  above.
+- `Spawn` — direct container creation under the default
+  `agent.nix` template. `commit_ref` is empty. Submitted via
+  `HostRequest::RequestSpawn` (operator-gated, the
+  `◆ R3QU3ST SP4WN` dashboard button + `hive-c0re request-spawn`
+  CLI). The host-level `HostRequest::Spawn` variant bypasses the
+  approval queue entirely — privileged-context use only (operator
+  on the host shell, test scripts, one-off recoveries). The
+  manager-side `RequestSpawn` is gone; managers go through the
+  `InitConfig` → `ApplyCommit` two-step instead so the spawn
+  captures their customised config.
+- `InitConfig` — `commit_ref` is empty; the variant just gates
+  "seed the proposed repo with the default template" against
+  operator approval. Step 1 of the two-step spawn flow above.
+- `UpdateMetaInputs` — `commit_ref` stores the JSON-encoded inputs
+  array (`"[]"` = all inputs, `"[\"nixpkgs\"]"` = just nixpkgs,
+  etc.). `agent` field is set to `hm1nd` (the requesting manager).
+  On approve hive-c0re runs `nix flake update [inputs...]` on the
+  meta flake and commits the resulting lock changes.
+- `SchedulePrompt` — `commit_ref` stores the JSON-encoded
+  `SchedulePromptPayload` (target list, body, schedule) so the
+  approval row carries the full submission verbatim. On approve
+  hive-c0re inserts a row into `scheduled_prompts` with
+  `source = approval:<id>`; the worker fans the body out as
+  inbox messages to each target at the scheduled time, recurring
+  when `interval_seconds` is set.
+
+### Destroy semantics
+
+`HostRequest::Destroy { name, purge }` is the lifecycle tear-down,
+not an approval. Stops + removes the nspawn container, drops the
+systemd drop-in, fails any pending approvals. Persistent state
+(proposed/applied repos, claude credentials, `/state/` notes) is
+**kept by default** — recreating the agent with the same name
+reuses prior config + login. With `purge = true` the agent's
+`/var/lib/hyperhive/{agents,applied}/<name>/` trees are also
+wiped (config history + creds + notes gone forever). The manager
+refuses to destroy itself.
+
 ## Meta flake
 
 The hive-c0re-owned repo at `/var/lib/hyperhive/meta/`