Document the built-in Harper Agent (`agent:` config, `agent_prompt` ops, `harper agent` CLI)

[DavidCockerill]

Problem

Harper 5.1+ ships an in-process agent component (Built-in Harper Agent Component, landed in feat(agent): scaffold built-in Harper Agent component, first release tag v5.1.0). Nothing on docs.harper.fast describes it. The two pages that mention agents cover different things:

• Using AI Agents documents harper-agent, the external CLI from HarperFast/agent that runs on the developer's machine.
• AI & Models overview and Tool calling document the Models.generate({ toolMode: 'auto' }) library loop.

Zero hits in the repo (all branches) for agent_prompt, hdb_agent, agent.enabled, or harper agent.

What to document

A new reference page under AI & Models (reference/models/agent.md or similar), plus a short pointer from the getting-started agents page distinguishing the two agents.

Source of truth, all in HarperFast/harper main:

• Config — the agent block in config-root.schema.json (~L694): enabled (default false, off to avoid surprise LLM cost), provider, model, maxTurns (default 50), maxCostUsd, autoApprove, allowDestructive, user (default hdb_agent, created at startup), componentsScope, systemPromptAppend. Requires a models.generative entry for the model it uses.
• Operations API — agent/operations.ts: agent_prompt, get_agent_session, list_agent_sessions, approve_agent_action, set_agent_config. Grantable to a non-super_user role via operations: ['agent'].
• CLI — bin/agentCli.ts: harper agent [message] (alias harper chat), one-shot and REPL modes, --target/--session/--json/--once, local UDS or remote ops API, approval prompts on awaiting_approval.
• Toolset and safety posture — agent/toolset.ts, agent/tools/: read-only by default (read/list/grep/tail files, http_fetch, inspector attach + CPU profile, best-practices lookup, schedule_followup); allowDestructive: true adds write_file scoped to components; operations-profile tools follow the mcp.operations.allow list and the agent user's permissions. Document what it can and cannot do out of the box so nobody expects self-deploy.
• Lifecycle — component edits need a restart to take effect (no hot class reload); session continuation.

Suggested outline: What it is (vs. harper-agent CLI, vs. toolMode: 'auto') → Enable (config, generative model, cost guard) → Talk to it (CLI, ops API) → Tools and permissions → Approval flow → Limits.

Out of scope

• Fabric provisioning does not enable the agent on instances; that is central-manager#457. The page should state the agent is off by default and link nowhere Fabric-specific until that lands.
• models.* cannot be set via set_configuration (harper#2267). Mention as a known limit, do not work around it in the docs.

Acceptance

• Reference page live under AI & Models, listed in sidebarsReference.ts.
• Every config key, operation, and CLI flag above is covered and verified against harper main at time of writing (note the SHA in the source comment, as tool-calling.md does).
• Getting-started agents page gains a two-sentence pointer: external harper-agent CLI vs. in-process built-in agent.
• Searching the site for agent_prompt or harper agent finds the page.