perf(prompt): cut the fixed per-turn prefix by 30% — collapse delegation, honour empty belts, move the flows manual into a skill

AGENTS.md

@@ -480,6 +480,69 @@ the wrong index. `tests/orchestrator_thread_list_wiring.rs`, which existed to
 pin that fix, was deleted with the tool. If threads need a chat route again, the
 cheap fix is a single read-only `thread_list` rather than restoring the family.
 
+### Bundled skills — `src/openhuman/skills/bundled/`
+
+A skill can ship **inside the binary**. `BUNDLED` is a `const` table of
+`include_str!`'d SKILL.md bundles; `run_workspace_migrations` writes each into
+`<workspace>/.openhuman/builtin-skills/<dir>/` at boot, and from there discovery,
+`describe_workflow`, `read_workflow_resource` and `run_skill` treat it exactly
+like a skill the user installed. There is no second reader and no
+`location: None` case downstream.
+
+Five things to know before adding one:
+
+- **It is not an extension point.** The table is compiled in, for the same
+  reason `modules::registry` is: a table config or RPC could add rows to would
+  let a remote party place instructions in front of the model. A skill the user
+  wants comes from `skill_registry_install`.
+- **`WorkflowScope::Builtin` is the LOWEST precedence**, below `Legacy`. A user
+  or project skill of the same name shadows it, so shipping a bundle can never
+  take a name away from a workspace already using it.
+  (`a_user_skill_of_the_same_name_shadows_the_builtin` pins this.)
+- **Builtin bypasses the per-profile skill allowlist**, like `Profile` does.
+  The allowlist scopes *user content*; these are neither the user's nor scoped,
+  and one of them is the reference manual an agent's own prompt points at.
+  `tools::is_builtin_skill` is the single place that decision lives, and the
+  exempt set is fixed at compile time.
+- **Materialised, not served from memory**, because every consumer downstream
+  resolves a real path and inherits `read_workflow_resource`'s traversal and
+  symlink hardening. `install_one` deletes and rewrites a bundle whose digest
+  moved rather than overwriting file-by-file — a stale reference page left
+  behind would keep answering reads after the skill stopped shipping it — and
+  writes the digest LAST, so an interrupted install is redone.
+- **Boot, not `init_workspace`.** That RPC is a one-shot an existing workspace
+  never runs again, so a shipped page would reach nobody after an upgrade.
+
+**What belongs in a bundled skill, and what does not.** `flow-authoring` (in
+`src/openhuman/flows/skills/`) holds ~25 KB that used to be `workflow_builder`'s
+standing prompt: expression and jq syntax, `memory`/`dedup`/trigger node config,
+per-node error handling, how to read a dry run. **A rule that binds stays in the
+prompt; a rule you look up moves.** "Propose, never persist" cannot live in a
+manual, because a manual only binds a model that chose to open it. This line is
+easy to get wrong and is guarded by tests, not review: "prefer the minimal
+viable graph" was moved into the skill on the first pass and moved back, because
+`standing_prompt_keeps_minimal_graph_warning_alongside_specialist_guidance`
+pins it — correctly, since it constrains an instinct the model has before it
+would consult anything.
+
+**`skill_search`** (`skills::search`) ranks installed skills by capability, over
+the shared BM25 in `util::bm25`. It lives **in** the withheld `skills` toolpack
+with `describe_workflow` and `run_skill`: advertised on its own it cost 748 B on
+every wildcard agent to produce an id those agents could not act on. The
+orchestrator's `## Installed Skills` catalogue is capped at `MAX_LISTED_SKILLS`
+(20) and points past the cap at search — the catalogue is a per-turn cost frozen
+for the session, so it grows silently with every install.
+
+**`util::bm25` names nothing from `crate::`** and must stay that way; it is the
+half of skill discovery that is the same for every host. Two rules there cost a
+debugging pass each: the IDF keeps its `+ 1` so a one-document corpus stays
+searchable, and because that lets stopwords score, queries are filtered by BOTH
+a document-frequency threshold (`df >= max(2, ceil(0.8n))`) and a small
+`STOPWORDS` list. Neither alone is enough — with three skills installed, "a"
+appeared in exactly one description, making it by frequency the *most*
+distinguishing term in "provision a kubernetes cluster", which duly returned a
+changelog skill.
+
 **Skills runtime**: the QuickJS per-skill VM engine is gone. `src/openhuman/skills/` holds skill metadata/tool descriptors; execution of installed `SKILL.md` workflows lives in `src/openhuman/skills/runtime/` (starts/cancels runs, hosts the `skill_executor` agent, reuses `runtime::node`/`runtime::python`, which are clients for the `tinyruntime` module).
 
 ### Tool calling lives in tinyagents — `src/openhuman/agent/dispatcher.rs` is a seam
@@ -665,6 +728,23 @@ So `GroupMode` has three states, not two:
 
 `Off` is the state that could not be said before, and it is the one an embedder reaches for most — absence beats a registered tool that fails, the same reasoning the `flows` compile gate already documents. Enforcement is two-sited and mirrors the existing filters: `Off` drops the tool in `all_tools_with_runtime`'s post-filter block (a third `retain`, right after the `DomainSet` and memory-capability ones), and `Withheld` is what `strip_packed_from_visible` acts on. **The three narrow, they never widen** — `Advertised` cannot conjure a tool that a Cargo gate compiled out or that the ambient `DomainSet` dropped.
 
+### Three ways a tool leaves the wire, and how to pick
+
+The fixed per-turn prefix is the system prompt plus every advertised tool schema. Three mechanisms shrink the second half, and they are **not** interchangeable — the criterion is how often a turn needs the capability:
+
+| Mechanism | Cost when needed | Use for |
+| --- | --- | --- |
+| **Collapse** (`memory`, `cron`, `delegate_to`, `delegate_to_integrations_agent`) | none — one extra enum field on a call being made anyway | families a turn needs *often*, or that are near-identical to each other |
+| **Pack** (`load_skill` / `use_skill`) | one round trip, per pack per conversation | capabilities most turns never touch — crypto, MCP setup, the `.pptx` writer |
+| **Defer** (`ToolExposure::Deferred` + `tool_search`) | one round trip, per tool | a long tail on a wildcard belt, where the *group* is not the natural unit |
+
+**A family of near-identical schemas hides from both ratchets, and that is how the biggest one survived.** `ArchetypeDelegationTool::parameters_schema` is a `json!` literal that never reads `self`, so all 16 synthesised delegates carried a byte-identical envelope: 17,746 B, **41% of the orchestrator's whole tool budget**, was one object sixteen times. Every individual tool sat under `check-prompt-budget.sh`'s 1,600 B attention threshold, so nothing flagged it, and the per-agent total shows a number without a cause. When looking for the next one, **group by schema body, not by size**.
+
+Two rules fell out of doing that collapse, both learned from regressions that measurement caught and review did not:
+
+- **Hiding a member is not enough on a `Named` belt.** `ToolExposure::Hidden` is applied by `strip_deferred_from_visible`, which deliberately runs **only for a wildcard belt** — a hand-written `[tools] named` list is already an answer to "what should this agent see". But synthesised delegates are force-inserted into that list by `factory.rs` and again by `refresh_delegation_tools`, so marking them Hidden changed nothing and the first version of the collapse made the budget go **up** (43,153 → 52,513 B). Both insertion points now skip a Hidden tool. That is the right place: those names were never chosen by a human, so skipping one takes nothing an author asked for.
+- **A collapse must never widen what a pack narrowed.** Folding the delegates into one tool silently re-advertised seven routes the pack table withholds (`do_crypto`, `setup_mcp_server`, `use_mcp_server`, `setup_skills`, `run_skill`, `build_workflow`, `discover_workflows`). Each one stopped being a tool — so `strip_packed_from_visible` had nothing to remove — and came back as a *string inside another tool's schema*, where no visible-set subtraction reaches it. `toolpacks::is_withheld_from` is the predicate for exactly this case. **Check it whenever a surface moves from "a tool" to "a value"**: enum members, description tables and generated catalogues are all advertised surface that the `visible` set cannot police.
+
 **Packs now carry an `owners` list, and a pack is skipped entirely for its owner.** This is new with the raw-tool packs and was not needed before: the original packs held only synthesised `delegate_*` tools, which exist on the orchestrator alone. A pack over raw tools is different — `settings_agent` exists precisely to run `config_*` / `health_*` / `service_*`, so withholding the `system` pack from it would put a `load_skill` round trip in front of the first call of every one of its turns and hide nothing that was idle. Its whole belt *is* the pack. `strip_packed_from_visible` therefore takes the agent id.
 
 **`DomainGroup` tracks family directories 1:1.** After the domain reorg (#5328) each variant names a `src/openhuman/` family, so the runtime axis stopped sweeping half the surface into the `Platform` catch-all. Groups: the harness families (`Agent`, `Memory`, `Threads`, `Config`, `Security`), the compile-gate families (`Flows`, `Skills`, `Mcp`, `Channels`, `Web3`, `Voice`, `Media`, `Medulla`), the families carved out of `Platform` (`Inference`, `Integrations`, `Automation` = cron, `Runtimes` = runtime + sandbox, `Desktop`, `Hosted`, `Relay` = tinyplace, `Modules` = the native module host), and `Platform` itself — now only the kernel surfaces with no family of their own (`platform/`, `tools/`, `http_host/`, `test_support/`).

app/src/components/flows/FlowListRow.test.tsx

@@ -18,6 +18,7 @@ function makeFlow(overrides: Partial<Flow> = {}): Flow {
   return {
     id: 'flow-1',
     name: 'Daily digest',
+    description: '',
     enabled: true,
     graph: { nodes: [], edges: [] },
     created_at: '2026-01-01T00:00:00Z',

app/src/pages/FlowsPage.test.tsx

@@ -61,6 +61,7 @@ function makeFlow(overrides: Partial<Flow> = {}): Flow {
   return {
     id: 'flow-1',
     name: 'Daily digest',
+    description: '',
     enabled: true,
     graph: { nodes: [], edges: [] },
     created_at: '2026-01-01T00:00:00Z',

app/src/pages/__tests__/FlowCanvasPage.test.tsx

@@ -87,6 +87,7 @@ function makeFlow(overrides: Partial<Flow> = {}): Flow {
   return {
     id: 'test-id',
     name: 'Daily digest',
+    description: '',
     enabled: true,
     graph: {
       schema_version: 1,

app/src/services/api/flowsApi.ts

@@ -135,6 +135,15 @@ export interface Flow {
   id: string;
   /** Human-readable name shown in the Workflows UI. */
   name: string;
+  /**
+   * One line saying what this automation is for.
+   *
+   * Empty is normal and must be rendered as such, not as a missing value:
+   * every flow saved before this field existed has none, and the canvas does
+   * not require one. Surfaced in the agent's skills catalogue, where an empty
+   * description falls back to describing the graph's shape.
+   */
+  description: string;
   /** Whether this flow may currently be triggered/run. */
   enabled: boolean;
   /** The validated, migrated workflow graph — opaque to this client. */
@@ -237,6 +246,8 @@ export interface FlowConnection {
 /** Optional fields for {@link updateFlow}. Omitted fields are left untouched. */
 interface FlowUpdate {
   name?: string;
+  /** Omit to leave the stored description untouched; `''` clears it. */
+  description?: string;
   graph?: unknown;
   requireApproval?: boolean;
   /**
@@ -373,16 +384,14 @@ function unwrapCliEnvelope<T>(payload: unknown): T {
 export async function createFlow(
   name: string,
   graph: unknown,
-  requireApproval?: boolean
+  requireApproval?: boolean,
+  description?: string
 ): Promise<Flow> {
   log('createFlow: request name=%s requireApproval=%s', name, requireApproval ?? 'default');
-  const response = await callCoreRpc<unknown>({
-    method: 'openhuman.flows_create',
-    params:
-      requireApproval === undefined
-        ? { name, graph }
-        : { name, graph, require_approval: requireApproval },
-  });
+  const params: Record<string, unknown> = { name, graph };
+  if (requireApproval !== undefined) params.require_approval = requireApproval;
+  if (description !== undefined) params.description = description;
+  const response = await callCoreRpc<unknown>({ method: 'openhuman.flows_create', params });
   const flow = unwrapCliEnvelope<Flow>(response);
   log('createFlow: response id=%s name=%s enabled=%s', flow.id, flow.name, flow.enabled);
   return flow;
@@ -650,6 +659,7 @@ export async function updateFlow(id: string, update: FlowUpdate): Promise<Flow>
   );
   const params: Record<string, unknown> = { id };
   if (update.name !== undefined) params.name = update.name;
+  if (update.description !== undefined) params.description = update.description;
   if (update.graph !== undefined) params.graph = update.graph;
   if (update.requireApproval !== undefined) params.require_approval = update.requireApproval;
   if (update.expectedVersion !== undefined) params.expected_version = update.expectedVersion;