swarm-ui: let the create-agent form set the new agent's initial AGENTS.md

The form gets a collapsed "instructions" section with a plain text box. Its
text goes in the optional agents_md field of the create request, and is left
out while the box is empty or only whitespace. The controller's size refusal
shows under the box instead of in the form's general error panel. The text
box empties after a successful create.

The send and refusal logic sits in its own module with tests, and
docs/swarm/ui.md describes the field.

frontend/packages/swarm-ui/src/pages/CreateAgentAgentsMd.ts

@@ -0,0 +1,23 @@
+// The create-agent form's initial `AGENTS.md` field, kept out of the
+// component so `npm test` can run it.
+import type { ProblemDetails } from "@hive/shared/api-error.js";
+
+/**
+ * The `agents_md` to send with a create: nothing while the box is empty or
+ * holds only whitespace, so the agent starts without the file; otherwise the
+ * text as typed.
+ */
+export function agentsMdBody(text: string): { agents_md?: string } {
+  return text.trim() === "" ? {} : { agents_md: text };
+}
+
+/**
+ * The controller's refusal of the text, when `problem` is one: a 400 whose
+ * detail starts with the field's name. It shows beside the box, so any other
+ * failure stays with the form's general error.
+ */
+export function agentsMdRefusal(problem: ProblemDetails): string | null {
+  return problem.status === 400 && problem.detail?.startsWith("agents_md ")
+    ? problem.detail
+    : null;
+}

frontend/packages/swarm-ui/src/pages/CreateAgentForm.css

@@ -69,6 +69,11 @@
 .create-agent-result-ok {
   color: var(--green);
 }
+/* The controller's refusal of the AGENTS.md text, under its box. */
+.create-agent-field-error {
+  margin: 0;
+  color: var(--red);
+}
 /* The picked archetype's description, under its select. */
 .create-agent-archetype-description {
   margin: 0;

frontend/packages/swarm-ui/src/pages/CreateAgentForm.tsx

@@ -38,6 +38,7 @@ import {
   SelectField,
   type SelectOption,
 } from "../ui/select-field/SelectField.js";
+import { TextAreaField } from "../ui/text-area-field/TextAreaField.js";
 import { Button } from "../ui/button/Button.js";
 import { capsBody, LimitsFields } from "../agent/detail/AgentLimits.js";
 import {
@@ -60,6 +61,7 @@ import {
   requestArchetype,
   type ArchetypeList,
 } from "./CreateAgentArchetype.js";
+import { agentsMdBody, agentsMdRefusal } from "./CreateAgentAgentsMd.js";
 import "./CreateAgentForm.css";
 
 // Mirrors swarm-controller's `HiveEntry` — same shape `HivesPage`
@@ -144,6 +146,8 @@ export function CreateAgentForm({
     null,
   );
   const [archetype, setArchetype] = useState("");
+  // The text the agent's `AGENTS.md` starts with; empty sends none.
+  const [agentsMd, setAgentsMd] = useState("");
   const picked = archetypes?.archetypes.find(
     (a) => archetypeKey(a) === archetype,
   );
@@ -211,6 +215,9 @@ export function CreateAgentForm({
     label: h.name,
   }));
   const hivesReady = hives !== null && hives.length > 0;
+  // The controller's size refusal of the AGENTS.md text, shown by its box.
+  const refusal =
+    result.status === "error" ? agentsMdRefusal(result.problem) : null;
 
   async function submit(e: Event) {
     e.preventDefault();
@@ -232,6 +239,7 @@ export function CreateAgentForm({
             ? requestPermissions(selected, catalogue.default)
             : undefined,
           archetype: requestArchetype(picked),
+          ...agentsMdBody(agentsMd),
         }),
       });
       if (!r.ok) {
@@ -241,6 +249,7 @@ export function CreateAgentForm({
       const data = (await r.json()) as CreateAgentResponse;
       setResult({ status: "done", nodeId: data.node_id });
       setName("");
+      setAgentsMd("");
       pickArchetype("");
       if (catalogue)
         setSelected(
@@ -258,8 +267,8 @@ export function CreateAgentForm({
           <p class="create-agent-intro">
             Create a new agent's swarm-level identity. This only queues the job
             — check <Link href="/jobs">jobs</Link> to watch it settle. Resource
-            caps and inference are optional; leave them empty to set nothing. A
-            name set up before keeps the settings stored for it.
+            caps, inference and instructions are optional; leave them empty to
+            set nothing. A name set up before keeps the settings stored for it.
           </p>
           {hivesError && (
             <ApiErrorPanel
@@ -365,6 +374,22 @@ export function CreateAgentForm({
                 />
               </div>
             </details>
+            <details class="create-agent-section">
+              <summary>instructions</summary>
+              <div class="create-agent-section-body">
+                <TextAreaField
+                  id="agent-agents-md"
+                  label="AGENTS.md"
+                  value={agentsMd}
+                  rows={8}
+                  placeholder="the text the agent's AGENTS.md starts with; leave empty for none"
+                  onInput={setAgentsMd}
+                />
+                {refusal !== null && (
+                  <p class="create-agent-field-error">{refusal}</p>
+                )}
+              </div>
+            </details>
             <Button
               variant="primary"
               type="submit"
@@ -384,7 +409,7 @@ export function CreateAgentForm({
               <Link href="/jobs">watch it in jobs</Link>
             </p>
           )}
-          {result.status === "error" && (
+          {result.status === "error" && refusal === null && (
             <ApiErrorPanel context="failed to queue" problem={result.problem} />
           )}
         </Panel>