Update Agent Shape

packages/bare-os-coreutils/man/pages/agent.json

@@ -1,15 +1,92 @@
 {
   "name": "agent",
   "section": 1,
-  "title": "agent",
+  "title": "Bare OS coding agent",
   "synopsis": [
-    "agent [OPTION]... [OPERAND]..."
+    "agent [OPTION]... REQUEST...",
+    "agent --setup",
+    "agent --status",
+    "agent --plan REQUEST...",
+    "agent --auto GOAL...",
+    "agent skills | todos | plan | compact | reset"
+  ],
+  "description": "Runs the in-guest ReAct coding agent (QVAC local or OpenAI-compatible REST). Full guest admin by default (denylist). Tools include grep, apply_patch, web_search, git_status, todos, plan mode, and skills. History lives in ~/.agent/history.json.",
+  "options": [
+    {
+      "flag": "--setup, --config",
+      "meaning": "Interactive QVAC or REST setup; only the chosen backend is stored"
+    },
+    {
+      "flag": "--auto, --autonomous",
+      "meaning": "Keep the tool loop running until task_complete, stop, or timebox"
+    },
+    {
+      "flag": "--plan",
+      "meaning": "Start in plan mode (read-only except ~/.agent/plan.md)"
+    },
+    {
+      "flag": "--new, --reset",
+      "meaning": "Clear chat history; with a request, start a fresh session then run"
+    },
+    {
+      "flag": "--continue, -c",
+      "meaning": "Resume ~/.agent/history.json (default)"
+    },
+    {
+      "flag": "--compact",
+      "meaning": "Compact history now; with a request, compact then run"
+    },
+    {
+      "flag": "--max-turns N",
+      "meaning": "Cap ReAct iterations for this run"
+    },
+    {
+      "flag": "--model NAME",
+      "meaning": "Override QVAC or REST model for this run"
+    },
+    {
+      "flag": "--system FILE",
+      "meaning": "Append extra instructions from an absolute guest path"
+    },
+    {
+      "flag": "--status",
+      "meaning": "Print backend, compaction, plan mode, and autonomous state"
+    },
+    {
+      "flag": "-h, --help",
+      "meaning": "Show usage"
+    }
   ],
-  "description": "Bare OS implementation of agent. Full behavior is defined in packages/bare-os-coreutils/src/agent.js.",
-  "options": [],
   "keywords": [
     "agent",
+    "qvac",
+    "llm",
+    "coding",
     "bare-os",
     "coreutils"
+  ],
+  "seeAlso": [
+    {
+      "name": "discord-bot",
+      "section": 1
+    }
+  ],
+  "examples": [
+    {
+      "caption": "one-shot request",
+      "code": "agent \"summarize ~/README and list /bin\""
+    },
+    {
+      "caption": "plan first",
+      "code": "agent --plan \"design a /bin/foo utility\""
+    },
+    {
+      "caption": "autonomous run",
+      "code": "agent --auto --max-turns 40 \"add agent tests and run them\""
+    },
+    {
+      "caption": "inspect skills",
+      "code": "agent skills"
+    }
   ]
 }