{"sha":"27540634e63af436ba597c22d7b1986b63d049bc","SKILLS":{"nexus-agent-management":{"slug":"nexus-agent-management","description":"> Building agent from scratch? → `AGENT_BUILDER_LIFECYCLE.md` (9-phase gated process, incl. Phase 9 systematic eval).","files":[{"path":"AGENT_BUILDER_LIFECYCLE.md","content":"# Agent Builder Lifecycle\n\nAn agent is the culmination of everything in the platform — it ties together prompts, skills (plugins, workflows, AI tasks), knowledge (documents, collections), deployments, and testing. Building an agent well requires reading and cross-referencing EVERY relevant skill doc, iteratively gathering information from the user, validating feasibility against the live platform, and testing at every milestone.\n\n## Skills to Load Before Starting\n\nWhen a user asks to build an agent, load ALL of these before doing anything:\n\n| Skill | Why |\n|---|---|\n| `nexus-agent-management/SKILL.md` | Agent CRUD, tool configs, versions |\n| `nexus-prompt-assistant/SKILL.md` + `AGENT_CONVERSATION_GUIDE.md` | Prompt generation |\n| `nexus-prompt-assistant/reference/pa-system-prompt-summary.md` | What the PA asks (6 sections, ~14 questions/skill) |\n| `nexus-prompt-assistant/reference/pa-output-schema.json` | JSON schema the PA populates |\n| `nexus-prompt-assistant/reference/example-agent-spec.json` | Gold-standard example of a complete spec |\n| `nexus-tool-connection/SKILL.md` | Marketplace discovery, credential validation |\n| `nexus-knowledge-base/SKILL.md` | Documents, collections, knowledge vs skill mode |\n| `nexus-skills-and-tasks/SKILL.md` | AI task creation |\n| `nexus-workflow-builder/SKILL.md` | Workflow building |\n| `nexus-deployments/SKILL.md` | Channel setup |\n| `nexus-emulator/SKILL.md` | Testing |\n| `nexus-workflow-builder/reference/internet-search-guide.md` | Search provider decision guide (load when agent/workflow needs internet search) |\n\n## The Phases\n\n**PLAN MODE IS THE ROOM PHASE 1 HAPPENS IN. ENTER IT FIRST**, before the concept questions — the owner sees a build BEFORE it exists (CLAUDE.md, the concrete-plan clause). Phase 1's confirmation IS the mode's acceptance. Skip the mode ONLY when the owner prescribed the change exactly; then RESTATE-AND-CONFIRM instead (same clause), never silence.\n\nEach phase has a **GATE** — explicit user confirmation or test pass required before proceeding.\n\n### Phase 1: Validate Agent Concept (GATE: user confirms)\n\nBefore doing ANY work, validate the concept with the user:\n0. **The four needs first** (NEEDS_ASSESSMENT \"## The four needs\"): the ones the owner's words have not answered go on ONE card BEFORE the summary below. The summary is built from their answers, never from your guesses.\n1. Summarize: agent name, role, who it serves, what it does\n1b. **Audience check** — list every distinct audience that will converse with it; ≥2 audiences × different task-types → propose the SPLIT (one agent per audience) HERE, before Phase 2 — splitting after PA re-does Phases 2-3 (→ SKILL.md \"One agent or two?\").\n2. List skills/tools it will need (high-level)\n3. **Knowledge GATE.** List knowledge sources. For domain-authority agents (legal/policy/medical/regulated/product-spec/brand/pricing), KB is **REQUIRED** — ASK if user didn't mention. See `NEEDS_ASSESSMENT_GUIDE.md` Dimension 5 + CLAUDE.md G#16 (named-but-absent → acquisition fork via `nexus-knowledge-base/SKILL.md` Q0).\n4. List deployment channel(s)\n5. **For AI tasks the agent will use:** Define each task's single purpose. If a task does analysis AND generation, it must be split into two tasks (see workflow builder one-purpose rule). Mark new tasks as PA REQUIRED.\n6. Ask: \"Does this match what you had in mind?\"\n\nWRONG: Jumping straight to marketplace searches, credential lookups, or PA conversations.\nRIGHT: Getting a 2-sentence confirmation that the agent concept is correct first.\n\n### Phase 2: Iterative Discovery + Validation (GATE: user confirms complete spec)\n\nFor each planned skill, run the discovery-validation loop:\n\n```\nDISCOVER → VALIDATE against platform → COME BACK to user with findings → REFINE → repeat\n```\n\n**Per skill type:**\n\n| Skill Type | Validation Steps | Skills to Read |\n|---|---|---|\n| PLUGIN | `nexus tool search` → tool exists? → `nexus tool get` → actions[] non-empty? → specific action exists? → `nexus tool credentials` → credential valid? → present findings to user | tool-connection, agent-management |\n| WORKFLOW | Each node type has GUIDE.md → each plugin node validated as PLUGIN above → AI task nodes have existing tasks → trigger type confirmed with user | workflow-builder, tool-connection, skills-and-tasks |\n| AI TASK | Input/output schema defined with user → model selected → **PA REQUIRED** (see prep step below) | skills-and-tasks, prompt-assistant |\n| KNOWLEDGE | Source identified (file/URL/text) → document accessible → collection nameable → correct attachment method decided (knowledge vs skill — see Phase 6) | knowledge-base, agent-management |\n| INTERNET SEARCH | Need structured data about known entity? → Parallel Task. Need to DISCOVER unknown entities? → Parallel Find All. Simple Q&A? → Perplexity plugin. Ask user about cost tolerance. | workflow-builder (internet-search-guide.md, parallel-ai GUIDE.md, parallel-output-schema-guidelines.md) |\n\n**If validation fails** (action doesn't exist, credential expired, tool not in marketplace): come back to the user with findings and propose alternatives. Don't silently drop or assume.\n\n**PA preparation step (for every new agent):**\n\nBefore proceeding to Phase 3, prepare the PA first message using the validated spec from Phase 2:\n\n1. **Identify all skills** the agent will have — plugins, workflows, AI tasks, collections\n2. **For each skill, prepare:** SkillId (name), BusinessPurpose, UserParameters (names + types), TriggerPhrases (3+ examples), ConfirmBeforeAction (yes/no), ExecutionStyle (sync/async)\n3. **Prepare agent identity:** name, role, persona, tone, communication style\n4. **Note any validated constraints:** from tool searches, credential checks, collection decisions\n5. **Write the PA first message draft** — this becomes your opening message in Phase 3\n\nWRONG: Arriving at Phase 3 with \"I'll figure out the PA message as I go.\"\nRIGHT: Arriving at Phase 3 with a drafted first message covering identity, all skills at depth, and tone — ready to paste.\n\n**Build the spec** matching the PA output schema depth. Read `pa-system-prompt-summary.md` — the PA asks ~14 questions per skill covering: SkillId, BusinessPurpose, UserParameters (with types, validation, defaults), TriggerPhrases, ConfirmBeforeAction, ExecutionStyle, OperationalGuidelines (Optimizations, Prohibitions, BestPractices, CommonMistakes), AgentBehavior (confirmation, progress, success message), BusinessRules (permissions, limits, hours), ErrorMessages (6 types), Examples (conversation flows), RelatedSkills.\n\nRead `example-agent-spec.json` to calibrate the expected depth.\n\nPresent the complete spec to the user section by section. Get explicit confirmation before proceeding.\n\nWRONG: Presenting a 4-line table with skill names and calling it \"validation.\"\nRIGHT: Walking through each of the 6 PA sections with the user, getting confirmation on each.\n\n### Phase 3: PA Conversation (GATE: non-generic prompt generated)\n\nRead `AGENT_CONVERSATION_GUIDE.md` before starting.\n\nRules:\n- Have the FULL multi-turn conversation (12-20 turns). NEVER cram everything into one message.\n- Answer PA questions from the validated spec. Escalate business judgment questions to the user via AskUserQuestion.\n- Keep pushing the conversation until the PA presents a final confirmation and generates. Don't stop at \"generating\" status with empty response.\n- After generation: verify the prompt is substantive (not generic). Red flags: under 500 words, placeholder language, vague skill sections, generic tone adjectives. If generic, start a NEW thread.\n- **Hard cap: 2 PA threads.** After 2 generic results, STOP PA and write the prompt manually from the spec assembled in Phases 1+2 (R#31 Escape Hatch 2: `nexus agent update --body '{\"prompt\":\"...\"}' --json`). The goal is a wired agent, not a PA conversation.\n- Save the generated prompt to a file. Present a summary to the user before applying.\n- Compare skill references in the prompt against planned tool config labels — they must match.\n\n### Phase 4: Create Agent + Set Model (GATE: agent responds correctly)\n\n1. `nexus agent create --first-name ... --last-name ... --role ... --json`\n2. **IMMEDIATELY** check available models: `nexus model list --json`\n3. **IMMEDIATELY** set the model — CLI-created agents have NO model by default (R#8: never hardcode a provider). Run `nexus model list --json` and take the newest non-deprecated row; its `provider` field (`ANTHROPIC`, `OPEN_AI`, …) travels WITH its `modelId` from that SAME row, never assumed:\n ```bash\n nexus agent update --body '{\"modelConfig\":{\"modelName\":\"\",\"modelProvider\":\"\"}}'\n ```\n4. Apply the generated prompt. **`version create` with a `prompt` in the body OVERWRITES the agent's live prompt** — its response says \"Checkpoint created.\" and never mentions publishing, which reads as safe and is not (probed 2026-08-29). Use `agent update` instead, so the response tells you what happened; `objective`/`tone` are REMOVED API fields (400s — see \"Agent CRUD\" above) and never belong in this body:\n ```bash\n nexus agent update --prompt ./prompt.md --no-publish --json\n ```\n `--no-publish` keeps this edit off every deployment until Phase 9's eval passes (`nexus-agent-management/SKILL.md \"## Modifying an existing agent prompt\"`). To checkpoint WITHOUT touching the live prompt, `version create` with `name` + `description` only — never a `prompt` field.\n5. Create a test deployment: `nexus deployment create --name \"Test\" --type API --agent-id `\n6. **TEST**: Send \"Hello\" via emulator. Verify the agent responds with the right tone.\n\nWRONG: Creating the agent and moving straight to skills without verifying it can respond.\nRIGHT: Verifying the agent responds before attaching any skills.\n\n### Phase 5: Attach Skills — Test Each One (GATE: each skill works individually)\n\nFor each skill, follow the type-specific flow in `nexus-agent-management/SKILL.md`, then TEST IMMEDIATELY.\n\n| After attaching... | Test by... |\n|---|---|\n| PLUGIN tool config | `nexus api POST /agents/:id/tools/:toolId/test --body '{\"input\":{...}}'` OR emulator message that triggers it |\n| WORKFLOW tool config | Emulator message that should trigger the workflow |\n| TASK tool config | `nexus task execute --input '...'` to verify output structure |\n\nAfter each test:\n- If it works → proceed to next skill\n- If it fails with a config error (wrong credential, bad param type) → **FIX IT immediately**, then retest\n- If it fails with a 500 → file a ticket, note it as blocked, proceed to next skill\n\nVerify tool config labels match what the prompt references. If the prompt says \"the log-to-sheets capability\" and the label is `log_to_sheets`, that's fine — the platform handles the mapping. But if names are completely different, update the prompt or label.\n\n**Plugin parameter types**: The API accepts `string`, `number`, `boolean`, `object`, `array`. NOT `integer` (use `number`) or `string[]` (use `array`).\n\n### Phase 6: Attach Knowledge (GATE: agent answers from KB)\n\nTwo attachment methods — choose the right one:\n\n| Method | API | Runtime | Best For |\n|---|---|---|---|\n| **Knowledge** (always injected) | `nexus api POST /agents/:id/collections --body '{\"collectionIds\":[\"...\"]}'` | Content ALWAYS in agent's prompt context | FAQ, policies, small reference docs |\n| **Skill** (on-demand search) | `nexus agent-tool attach-collection --collection-id ... --label ...` | Agent searches ONLY when it decides to | Large document sets, product catalogs |\n\nWRONG: Using `attach-collection` (skill) for a 10-page FAQ the agent should always know.\nRIGHT: Using `nexus api POST /agents//collections` (knowledge) for always-needed content.\n\nAfter attaching, TEST: send a knowledge question via emulator. Verify the agent answers from the collection, not from general knowledge.\n\n### Phase 7: Deploy + Integration Test (GATE: end-to-end works)\n\n1. Create deployment (read channel guide first — EMBED requires `--body '{\"settings\":{}}'`)\n2. Run a full test scenario via emulator:\n - Greeting → skill trigger → knowledge question → edge case → out-of-scope redirect\n3. For each failure: diagnose → fix → retest. Don't file a ticket and move on unless it's a confirmed 500.\n\n### Phase 8: Post-Creation Verification Checklist\n\n**STRUCTURAL ARTIFACT** — per CLAUDE.md R#27 Agent-completion gate, \"agent created/ready/live/deployed\" status claims MUST emit this checklist as a Wiring Table. Any `❌` → cannot claim ready/done.\n\n!! After each deliverable → hand the discovery triggers below to the silent background consolidation subagent (CLAUDE.md R#34); never emit a user-facing ledger. !!\n\n```\n- [ ] Agent has model set (modelName is not null)\n- [ ] Agent has prompt (prompt field is not empty/generic)\n- [ ] Every skill label has a matching reference in the prompt\n- [ ] Every tool config has been tested with sample input\n- [ ] Knowledge collections attached with correct method (per agent-management SKILL.md — DEFAULT knowledge)\n- [ ] Knowledge search returns results (indexing complete)\n- [ ] At least one deployment exists and is active\n- [ ] End-to-end emulator test passes\n- [ ] Systematic eval passed (Phase 9 — SIMULATED verdict PASS per load-bearing behaviour)\n- [ ] Version checkpoint created: nexus version create --name \"v1.0\"\n- [ ] Dashboard link provided to user\n- [ ] User action items listed (OAuth connections, document uploads, etc.)\n```\n\n**R#44 completeness gate (post-wiring-table):** verify the agent's artifact set per `nexus-workspaces/domains/systems/GUIDE.md \"## Completeness gate (Tier-2)\" → Agent archetype`. For org-specific filing under `$GENERAL_CONTEXT_PATH/systems//agents//`: `identity.md` + `system-prompt.md` + `tools.md` + `tools/.json` (per attached tool) + `deployment-variations.md` (REQUIRED iff prompt has any `::: section: deploymentSpecific=true :::` section) + `evaluation/` (once evaluated — Phase 9). Silent-block on missing artifacts (CLAUDE.md R#44). If 3-Q ricochet (R#34 + R#35 boundary) fires generalisable=YES → parallel write to `$SYSTEMS_PATH/agents//` w/ R#44 3-step anonymisation protocol applied (detail → `nexus-workspaces/reference/prompt-anonymisation-protocol.md`).\n\n**The Wiring Table (CLAUDE.md R#27 names the pillars; this is the table):**\n\n| Pillar | Status |\n|---|---|\n| Identity (name/role/bio) | ✓/❌ |\n| Model | ✓/❌ |\n| Prompt (substantive, not boilerplate) | ✓/❌ |\n| Skills attached + each `@`-tagged in prompt | ✓/❌ |\n| Knowledge attached (correct mode) + `%%`-marked in prompt | ✓/❌ |\n| Deployment(s) | ✓/❌ |\n| E2E emulator test | ✓/❌ |\n| Systematic eval (Phase 9 — a DRIVEN `emulator send` conv per load-bearing behaviour, judged by READING the transcript; a behavioural CHANGE → baseline→fix→postfix compare pre-publish (R#45); a production incident → INBOX audit of the real conv — the emulator alone hides inbox defects; lifecycle → `nexus-evaluations` \"Eval lifecycle\") | ✓/❌ |\n\n### Phase 9: Evaluate — Build Gate AND Change Gate (regression + intended behaviour)\n\n!! Before claiming an agent ready, AND before publishing any behavioural change: `Skill(nexus-evaluations)` and read \"Mode B\" FULLY (the HOW lives there — commands, body shapes, end-signal rule, compare loop). No ready-claim and no behavioural-change publish without a passing eval. !! (Draft-stage behavioural EDITS: the done-CLAIM itself gates on an emulator run — `nexus-agent-management/SKILL.md \"## Modifying an existing agent prompt\"`.)\n\n**WHY:** one manual emulator chat (Phase 8) cannot prove a guardrail holds, that helpfulness actually improved, or that a change didn't regress a different behaviour. **WHEN:** at first \"ready\", and on every later prompt/tool/model/version change.\n\n**STRUCTURAL ARTIFACT** (R#27-style) — emit per load-bearing behaviour:\n\n| Behaviour | Tester persona | Judge criterion | Run id | Verdict | Score |\n|---|---|---|---|---|---|\n\n- **Reuse-first** — if the agent's archetype or its general-context instance already has an eval suite, start from it — `nexus workspace search systems --query ` finds it server-side with no drive (TEXT files only, 1,000-file cap printed in its tail), then read `$SYSTEMS_PATH/agents//evaluation/`. Else run the discovery in `nexus-evaluations/evaluation-archetypes/evaluation-creation-mode.md` to establish what matters.\n- Build one tester-persona + judge-rubric PAIR per load-bearing behaviour (guardrails, helpfulness, scope, tone, tool-use), each designed to REACH the behaviour — a test that never triggers it scores nothing. ‼ End-signal rule: one intent per tester turn; emit the end-signal only AFTER the agent replies — a turn-0 end-signal scores 0 on a working agent.\n- Drive each pair through the emulator (`nexus-evaluations` — `agent-eval` and its SIMULATED runs were deleted in CLI 1.3.0; the emulator conversation + an INBOX audit are the instruments) → the judge criterion is applied by READING the transcript, verdict PASS/FAIL with the quoted line and the conversation id. PASS per load-bearing behaviour required; gating flags (jailbreak/PII/fabricated-success/missed-escalation) hard-fail. A FAIL → fix prompt/tools and re-drive.\n- **On a change:** baseline (the unchanged version driven on the same pairs) → change → re-drive → compare per criterion; ship only if no criterion regressed AND the intended criterion moved. Evaluation is the agent's regression test, not a one-time build step. The Stage 8 object (`nexus-prompt-lifecycle/reference/eval-contract.md`) is the record.\n- On PASS, file the eval suite to the workspace (real → general-context `…/agents//evaluation/`; anonymised → archetype per the anonymisation protocol).\n\n**HOW** (authoring personas/rubrics, run/execute/results, the compare loop, the archetype patterns) → `Skill(nexus-evaluations)` \"Mode B\" + `evaluation-archetypes/`. Do NOT reproduce the mechanics here — load the skill."},{"path":"SKILL.md","content":"---\nname: nexus-agent-management\ndescription: Creates, configures, and manages Nexus AI agents via the Nexus CLI: the is-this-actually-an-agent boundary check, one-agent-or-two, basic vs code-interpreter, tool configurations, the knowledge-vs-skill collection default and the in-prompt `%%marker%%`, prompt versions, folder organization, and post-creation testing. Use when the user asks to create an agent, decide whether the thing they described IS an agent, configure agent tools, attach a workflow/collection/task, manage prompt versions, or test a built agent.\n---\n\n> Building agent from scratch? → `AGENT_BUILDER_LIFECYCLE.md` (9-phase gated process, incl. Phase 9 systematic eval).\n\n# Nexus Agent Management\n\n‼ A build is TRACKED work: before the first mutation, the build's track row exists (`nexus tracks`; S#0). ‼\n\nTranslate user intent → `nexus` CLI. User = org admin, not dev.\n\n## Boundary Check — Is This Actually an Agent?\n\nVerify request requires CONVERSATION before creating an agent.\n\n| User signal | Actually needs | Why | Redirect |\n|---|---|---|---|\n| \"Every time X happens, do Y automatically\" | Standalone WF | Auto trigger ≠ conv | `nexus-workflow-builder` |\n| \"Monitor and alert me\" | Scheduled WF | Monitoring is autonomous | `nexus-workflow-builder` |\n| \"Process every email/call/lead\" | WF (+ optional agent skill) | \"Every\" = systematic | Ask trigger Q first |\n| \"Answer questions\" / \"chat about\" / \"help users with\" | YES → agent | Conv = agent | Continue |\n| \"Summarize/classify/extract this\" | AI task (standalone or agent skill) | One-shot transform → AI task | Ask context Q |\n| Domain-authority (legal/policy/medical/regulated/brand/pricing) | Agent + **KB required** | Source grounding prevents hallucination | Phase-1 KB scoping per `NEEDS_ASSESSMENT_GUIDE.md` Dim 5 |\n\nNon-conversational → do NOT ask \"should I build a WF instead?\" User can't evaluate. Instead: (1) ask 2–3 contextual Qs (which tool, output, event types), after the four-needs card when a design will go to the user (NEEDS_ASSESSMENT \"## The four needs\"); (2) teach w/ user's words (\"'each of my calls' = runs automatically on every call → workflow\"); (3) switch to `nexus-workflow-builder`. Conversation Test → R#17 (full WR pair canonical there).\n\n## One agent or two?\n\nOne agent per AUDIENCE × TASK-TYPE. Same task-type for the same audience = the SAME agent regardless of headcount (channel identity — phone number, email — distinguishes people; don't over-split). Different audience OR different task-type OR different lifecycle (a configure-once-per-type surface vs an always-on operator) = SEPARATE agents. One user noun often bundles both (R#17 bundle clause; probes → `NEEDS_ASSESSMENT_GUIDE.md` Dimension 7). ✗ one fused agent where field staff submit data AND managers define formats/query results → one prompt serving two masters, both badly → ✓ an intake agent (field staff) + a designer/query agent (managers) + a shared store.\n\n## Quick Start\n\n```bash\nnexus agent create --first-name \"Support\" --last-name \"Bot\" --role \"Customer Support\" --json # 1. Create\nnexus model list --json # 2. Pick frontier model\nnexus agent update --body '{\"modelConfig\":{\"modelName\":\"\",\"modelProvider\":\"

\"}}' --json\nnexus agent update --prompt ./prompt.md --json # 3. Apply PA prompt (R#31)\nnexus agent-tool create --label \"send_email\" --type PLUGIN --body '{...}' --json # 4. PLUGIN\nnexus agent-tool create --label \"Order Lookup\" --type WORKFLOW --body '{...}' --json # 5. WF (PUBLISHED)\nnexus agent-tool attach-collection --collection-id \"\" --label \"Product Docs\" --json # 6. Collection\nnexus version create --name \"v1.0\" --description \"Initial\" --json # 7. Checkpoint\n```\n\nFull lifecycle → `AGENT_BUILDER_LIFECYCLE.md`.\n\n## Agent CRUD\n\n**Search before creating** — `nexus agent list --search \"\" --json`. Present matches (name/role/date/bio).\n\n| Decision | Action |\n|---|---|\n| Existing fits | `nexus agent duplicate ` |\n| Create new | PA-generated prompt per R#31, then create |\n| User pastes complete prompt | Skip PA, create directly |\n\n**Prompt assistant gate** → R#31. PA mandatory for every new agent unless user EXPLICITLY types/pastes a complete prompt. Detail → `nexus-prompt-assistant/AGENT_CONVERSATION_GUIDE.md`.\n\n```bash\nnexus agent create --first-name \"Sales\" --last-name \"Assistant\" --role \"Sales Rep\" --prompt ./prompt.md --body '{\n \"shortBio\": \"Handles product inquiries\",\n \"tags\": \"sales,product\",\n \"modelConfig\": { \"modelName\": \"\", \"modelProvider\": \"ANTHROPIC\", \"temperature\": 0.7 }\n}' --json\n```\n‼ The agent API REMOVED `objective` + `tone` + `behaviour` (each 400s on create AND update: \"fields have been removed… Set the system prompt via the \\\"prompt\\\" field instead\" — probed 2026-07). Behavioural rules live IN the system prompt (`--prompt ./file.md` or `\"prompt\"` inside `--body`), never in those fields.\n\n**Model:** Use `modelConfig` (not legacy `model`). `nexus model list --json` first → `modelId`→`modelConfig.modelName`, `provider`→`modelConfig.modelProvider`. **Thinking level:** branch on `model.thinkingDialect` before setting `thinkingLevel` (R#8 — `nexus-getting-started/reference/thinking-dialects.md`). **Prompt:** `--prompt ./file.md` or `--body '{\"prompt\":\"…\"}'`.\n\nRoutes/flags: `nexus agent --help` per session (R#11 — the live surface also carries profile-picture routes the old listing here missed). Keep in hand: `update --body` is PARTIAL (only provided fields change).\n\n## Modifying an existing agent prompt\n\nEditing a LIVE agent's system prompt is scan-heavy, multi-region, and feasibility-sensitive → **dispatch the `agent-prompt-modifier` agent (R#45), FOREGROUND**, passing ONLY `{agentId, change_request, prior_qa?, approved_plan?}`. It runs the full Cue modification doctrine (feasibility preflight H1–H7 · the four-pass section scan (`nexus-prompt-lifecycle/reference/section-scan.md`) · region-consolidation · exact-match edits on a local copy · re-fetch verify) in its own context and returns ONE of: `done` · `needs_clarification` · `plan_for_approval` · `infeasible` · `blocked`.\n- Non-`done` → AUQ the user with the returned questions/plan, then re-dispatch with `prior_qa`/`approved_plan` (the modifier has no AskUserQuestion — it asks THROUGH you).\n- **CORRECTION 2026-08-16, measured: `agent update --prompt` has NO DRAFT STAGE.** Verified first-hand on a scratch agent — one prompt edit, no publish command run, and the tool answered `published, live on every deployment`; a production version appeared. **W69, widened: THREE commands reach a live prompt, not one** — `agent update --prompt`, `agent update --body` carrying a prompt, and `version create --body` carrying a prompt (which answers \"Checkpoint created.\" and never mentions publishing while it overwrites — see \"Version Management\" below). So the eval is owed BEFORE the edit, not before a later publish, and the `version publish` gate stands after the event it exists to catch. ~~The modifier edits the DRAFT only.~~ **YOU own the eval:** a behavioural change → the edit saved to a prompt VARIANT (`prompt save --variant ` never publishes), evaluated (`Skill(nexus-evaluations)` Mode C; flag off → Mode B test chats) BEFORE it goes live; on a live door instead, the test FIRST, THEN the edit with `--no-publish`, then dispatch `prompt-reviewer` on the SERVED text before `version publish` on PASS. Revert = re-`agent update` with the prior prompt, which you must therefore capture BEFORE editing.\n- Do NOT edit a live prompt inline yourself — you will miss the enforcement rules / examples / cross-refs the scan catches. CREATION of a new prompt routes to PA (R#31), never the modifier.\n- Fallback if the named agent isn't loaded (fresh session): `general-purpose` + \"Read `.claude/agents/agent-prompt-modifier.md` COMPLETELY and follow it\".\n\nVerified CLI shape the modifier relies on: `nexus agent get --json` → prompt at **top-level `.prompt`**, body has raw control chars (`jq` fails — python-decode per G#11); `nexus agent update --prompt --json` → wrapped `{success,id}` with NO prompt echo → re-fetch + **Save-transform diff** (R#20): DIFF refetched vs sent — the platform single-escapes raw backticks/underscores on save (benign, report it); ANY re-escaping of EXISTING backslashes = an escaping CASCADE → STOP editing + ticket. `wc -c` BEFORE writing — the server rejects `prompt` >1,000,000 chars. The platform auto-wraps plain markdown into `::: section: … :::` / `::: tab: … :::`; a stored section may carry ~5 attributes (no `activeTab`) — preserve EXACTLY what's there (structure + content; runaway ESCAPE ARTIFACTS are corruption, NOT content to preserve). User explicitly forbids subagents → apply this same doctrine INLINE (feasibility scan · region-consolidation · verify + Save-transform diff); the gates travel, not the vehicle. THERE IS NO STAGING AGENT. Every agent is live: `agent update --prompt` or `--body` reaches every deployment it has unless `--no-publish` is passed, and there is no second copy serving nobody. To rehearse a change safely, `agent duplicate` a scratch agent you own and work there — that is the only rehearsal space that exists (NEX-4548 asks the platform for a real one). A behavioural change to any agent gates its \"done/works/live\" CLAIM on ≥1 emulator run reaching the changed behaviour — even when publish (and the regression eval) is deferred.\n\n## Code-interpreter agents (basic vs code-interpreter — pick by OUTPUT shape)\n\nNexus has two agent archetypes. Pick the archetype BEFORE building — it is an OUTPUT-SHAPE decision, not a tone preference, and it is costly to change after the prompt and tools are wired.\n\n| Archetype | What it is | Output profile | Prompting burden |\n|---|---|---|---|\n| **BASIC** | prompt + model + Nexus skills (workflows / AI tasks / collections) + knowledge + deployments | fixed / templated — a known set of shapes | low — the skills do the work |\n| **CODE-INTERPRETER** | a `code-interpreter-claude-*` model + Claude skills (executable code bundles) + workspace read/write + arbitrary code execution | near-infinite — shapes vary per request; real computation | higher — it writes and runs code |\n\n**The fork (decide at Phase 1):**\n- FIXED or templated document output (a recurring report, one of a known set of layouts) → **BASIC**. A near-blank HTML `DOCUMENT_TEMPLATE` renders most Word/HTML output a basic agent needs — reach for code-interpreter ONLY when the need EXCEEDS that. A basic agent is more reliable and cheaper; do NOT over-reach.\n- NEAR-INFINITE / code-driven / computational office output — spreadsheets with live formulas, image or OCR work, multi-format pipelines, arbitrary code over uploaded files → **CODE-INTERPRETER**.\n\n✗ a near-infinite report need → one workflow + a DOCUMENT_TEMPLATE per document type (never finishes, rigid) → ✓ recognise near-infinite/code-driven office output → a code-interpreter agent with the office skills.\n\n**Model class.** `nexus model list --json` exposes the `code-interpreter-claude-*` models; set one via `modelConfig` exactly like any model (`modelName` + `modelProvider`). A code-interpreter agent is distinguished by this model class plus the three added capabilities below.\n\n**Three added capabilities** (vs a basic agent): (1) **Claude skills** that execute code; (2) **workspace read/write** — the workspace is a first-class resource (lifecycle / mount / paths → `nexus-workspaces/SKILL.md`; see the \"Workspace surface (orthogonal)\" note below); (3) **arbitrary code** — a specialised, in-product Claude-Code-for-office.\n\n**Skill mechanism (concrete).** The ready **office skills** — `pptx`, `xlsx`, `docx`, `pdf` — are AVAILABLE in the tools community workspace at `$TOOLS_PATH/skills//` (each is a `SKILL.md` + its scripts); reference a skill by its workspace path. They are the baseline for document and spreadsheet output. A **CUSTOM** skill is authored with the **skill-creator** (Anthropic skills repo) — a skill is a `SKILL.md` plus scripts — and authoring a new skill is ONLY meaningful for a code-interpreter agent (a basic agent cannot execute one).\n\n**Attach reality (present-tense).** A skill bundle reaches a code-interpreter agent by being present in the workspace it reads. There is NO `nexus agent` / `agent-tool` flag that attaches a skill to a code-interpreter agent today — do NOT invent one, and do NOT claim an attach step that does not exist. State the gap plainly when it bears on a build.\n\n**When NOT to use it.** A reliable, narrow agent (fixed Q&A, templated output, a known set of tools) is a BASIC agent — building it as a code-interpreter agent adds cost, latency, and prompting burden for no gain. The senior-engineer test (R#32) applies: if a competent reviewer would call the code-interpreter machinery over-built for this output, it is.\n\n## Tool Configurations\n\nFive types — each agent-tool needs `agentInputSchema` (JSON Schema for runtime inputs; `{}` if none).\n\n**Workspace surface (orthogonal):** when an agent reads/writes workspace files, the workspace itself is a separate first-class resource — lifecycle/mount/paths/multi-writer → `nexus-workspaces/SKILL.md`. Workspace assignment is independent of the 5 tool-config types below.\n\n**Channel-granted card tools (orthogonal):** an agent deployed on an EMBED web widget auto-gains `send_html_template_` (per stored template) + `send_message` + `display_html` — no tool-config needed; steering + template design → `nexus-deployments/channels/embed.md \"## HTML Message Templates\"`.\n\n| Type | Description | Key config fields |\n|---|---|---|\n| `PLUGIN` | Marketplace action (Gmail, Slack…) | `toolId`, `action`, `toolCredentialId` |\n| `WORKFLOW` | Org workflow as tool | `toolId` (workflow ID — ‼ MUST be PUBLISHED; DRAFT silently fails) |\n| `TASK` | AI task as tool | `toolId` (task ID) |\n| `COLLECTION` | KB search | `collectionId` via `attach-collection` shorthand |\n| `DOCUMENT_TEMPLATE` | Generate formatted doc | `toolId` (template ID) |\n\n### PLUGIN — 7-step configuration\n\n**Preflight:** before attaching, run `nexus external-tool execute --action --input '{…}' --credential --json` standalone to prove `toolId`/`action`/`credential` work. Agent runtime failures are silent. Full → `nexus-tool-execute/TOOL_EXECUTION_GUIDE.md`.\n\n**Credential-deferred builds (\"create everything, connect later\"):** a tool-config SHELL (`toolId` + `action` + `agentInputSchema` + `description`) is creatable WITHOUT `toolCredentialId`; the credential + dynamic action params resolve when the user connects it. Defer the credential as a user TODO; a shell is NOT runtime-ready — never claim it tested.\n\n1. **Search + select tool.** `nexus tool search --query gmail --json` → user picks. Not in marketplace → `nexus-tool-connection/reference/custom-tool-integration-guide.md`.\n2. **Select action.** `nexus tool get --json` → `actions[]` w/ `key`/`name`/`parameters`. Present ALL w/ recommended marked. ✗ `\"action\":\"send-email\"` / `\"Send Email\"` → silent failure → ✓ `\"action\":\"gmail-send-email\"` (verbatim `actions[].key`, Pipedream `{app}-{action-slug}`).\n3. **Select credential.** `nexus tool credentials --json`. 0 → start OAuth flow; 1 → confirm; 2+ → present ALL w/ names+dates, user picks. ✗ auto-pick most recent → may belong to coworker → ✓ \"Found 2: (A) Mar 2026, (B) Dec 2025. Which is yours?\" ‼ Credential ids are PER-TOOL: the same external account yields a DIFFERENT credential id under each tool that wraps it — list via THIS tool's `tool credentials `, never reuse an id seen under another tool (\"Credential not found or does not belong to this tool\").\n4. **(opt) Scope w/ access card.** `nexus access-card available-actions --credential-id --json` → `nexus access-card create --credential-id --name \"Send Only\" --data '{\"policies\":{\"gmail-send-email\":{\"parameters\":{\"to\":{\"enabled\":true},\"subject\":{\"enabled\":true},\"body\":{\"enabled\":true}}}}}' --json`. ✗ `{\"policies\":{\"allowedActions\":[…]}}` → validates, then denies every real action → ✓ a MAP keyed by `actionId`. Unlisted action = denied; unlisted parameter = STRIPPED, so list every parameter the action needs.\n5. **Decide parameter handling.** For each `actions[].parameters`: agent-configured → `agentInputSchema.properties`; manually pre-set → `config.parameters` as `{ \"type\":\"…\", \"handler\":\"manual\", \"value\": }`. Types: `string`/`number`/`boolean`/`object`/`array` — NOT `\"integer\"` / `\"string[]\"`. Agent-FILLED fields should be FLAT SCALARS — the model fills `string`/`number`/`boolean` reliably but passes null/partial for nested `object`/`array` via `handler:prompt`; a needed non-scalar → `handler:manual` preset, or have the agent pass a scalar id the workflow expands (Universal Gotcha #1 handler selection).\n6. **Write `description` (<20 words).** Format: `\"Use [tool] when [trigger]. You MUST set [param] with [description].\"` Only mention agent-configured params. A REQUIRED runtime input the agent cannot know from conversation (a URL, an id, a slug) is a wiring decision: mark it `required` in `agentInputSchema` AND tell the agent where to GET it (\"resolve from , or ask\") — an undeclared hard input fails at runtime while the agent narrates a plausible-sounding answer over the failure.\n7. **Create + test.**\n ```bash\n nexus agent-tool create --label \"send_email\" --type PLUGIN --body '{\n \"description\": \"Use send_email when user asks to send an email. You MUST set body with well-formatted HTML content.\",\n \"agentInputSchema\": { \"type\":\"object\", \"properties\":{ \"body\":{\"type\":\"string\",\"description\":\"HTML email body\"} }, \"required\":[\"body\"] },\n \"config\": {\n \"toolId\": \"\",\n \"action\": \"gmail-send-email\",\n \"toolCredentialId\": \"\",\n \"parameters\": {\n \"to\": { \"type\":\"array\", \"handler\":\"manual\", \"value\":[\"fixed@example.com\"] },\n \"subject\": { \"type\":\"string\", \"handler\":\"manual\", \"value\":\"Fixed subject\" }\n }\n }\n }' --json\n # Test (ask user first — side effects real):\n nexus api POST /agents//tools//test --body '{\"input\":{\"body\":\"

Test

\"}}' --json\n ```\n `input` carries only agent-configured params; manual params apply automatically.\n\n### WORKFLOW — must be PUBLISHED\n\n```bash\nnexus agent-tool create --label \"Process Invoice\" --type WORKFLOW --body '{\n \"agentInputSchema\": { \"type\":\"object\", \"properties\":{ \"invoiceUrl\":{\"type\":\"string\"} } },\n \"config\": { \"toolId\": \"\" }\n}' --json\n```\n\n### Knowledge Collections — TWO methods (DEFAULT = knowledge)\n\n| Discriminator | Knowledge (always-injected) | Skill (on-demand search) |\n|---|---|---|\n| Every answer in domain must cite / respect source? | ✓ YES → knowledge | NO |\n| Source consulted only on specific Qs? | NO | ✓ YES → skill |\n| Source >50k tokens AND consulted <30% of conversations | Consider chunking → skill | ✓ skill |\n| Command | `nexus api POST /agents//collections --body '{\"collectionIds\":[\"\"]}'` | `nexus agent-tool attach-collection --collection-id --label --instructions ` |\n\n**DEFAULT: knowledge.** Switch to skill ONLY when source is large AND consulted occasionally (catalogs, archives). Legal/policy/brand/pricing/regulatory → always knowledge regardless of size.\n\nWRONG: Legal/policy KB → `attach-collection` (skill) → agent answers some Qs without consulting source → liability.\nRIGHT: Legal/policy → `POST /agents//collections` (knowledge) → every answer grounded.\n\n```bash\nnexus api POST /agents//collections --body '{\"collectionIds\":[\"\"]}' --json\nnexus api GET /agents//collections --json\nnexus api DELETE /agents//collections --body '{\"collectionIds\":[\"\"]}' --json\nnexus agent-tool attach-collection --collection-id \"\" --label \"Product KB\" \\\n --instructions \"Use when user asks about features, pricing, troubleshooting\" \\\n --body '{\"description\":\"Search product docs and FAQs\"}' --json\n```\n\n**Wiring knowledge INTO the prompt — the `%%marker%%`.** Attaching (`POST /collections`) only REGISTERS the collection. For the agent to actually USE it, the prompt's Knowledge section must carry the injection marker `%%%%` on its own line — at runtime it is replaced by the retrieved chunks. No marker → the registered knowledge never reaches context (the agent acts as if it has none). PA-generated prompts omit it (PA lacks the slug); add it after applying. Detail + placement → `reference/agent-collections.md \"### In-prompt injection marker\"`.\n\nThe GET is the AUTHORITATIVE census of what is ATTACHED; the `%%%%` marker controls WHERE it injects — two SEPARATE, both load-bearing concerns. Audit ATTACHMENT via GET (never infer from the prompt), AND verify the marker is PRESENT (attachment alone does not wire it). Skill-mode attachments carry no marker. (`agent list` items carry `firstName`/`lastName`/`role` — there is no `.name` field.)\n\n**Transitive census (full wiring of an inherited agent):** `agent get` → `agent-tool list` → per config: `workflow get` (read `publishedNodes` for live behaviour) / `external-tool get` / `task get` → `GET /agents//collections` → `deployment list`/`get` → `nexus conversation list --agent-id ` + the agent's evaluation file in general-context (evidence status: what has it actually been asked, what has been driven and read, any open regressions? — `agent-eval` was deleted in CLI 1.3.0). Custom components (customScript bodies, CUSTOM_MANIFEST tools) show WHAT, not WHY — the rationale lives in a source repo / general-context; ask for it rather than reverse-engineering intent.\n\n**Eval-health rule:** for a NEW build/change, **block** a \"ready/healthy\" claim without a passing eval (Phase 9 + R#27 pillar). For an INHERITED agent, **surface** \"no eval suite / last verdict FAIL / N criteria regressed\" as an explicit census finding — don't hard-block (you can't retro-force someone else's agent), but flag it. Characterise eval state from the live `run list`, never infer (G#10).\n\nDetail → `reference/agent-collections.md`.\n\n### Managing tools\n\nRoutes/flags: `nexus agent-tool --help` per session (R#11). ‼ `update` with `null` for a field is a SILENT NO-OP, not a clear (audited 2026-08).\n\n## Probing behaviour: a scratch agent, not the live one\n\nAny behaviour or injection probe runs on a throwaway agent with its own throwaway deployment, and\nthe teardown is a ROW on the board at the moment the scratch is created, not a good intention. The\nstatus that follows names what is untouched: \"the scratch agent and its test deployment are\ndeleted; the real collection is live and unchanged.\" A probe run against the live agent cannot say\nthat sentence, whatever it found.\n\n## Version Management\n\nAUTO = auto-created on prompt change (cannot rename/delete individually). CHECKPOINT = manual.\n\nRoutes/flags: `nexus version --help` per session (R#11). Rules `--help` does not carry: `publish` marks production (`isProduction: true`); `restore` OVERWRITES the current prompt immediately; production cannot be deleted (publish a different version first).\n\n!! Before `version publish` of a changed prompt/tool/model: `Skill(nexus-evaluations)` and run the regression eval (Mode B \"Regression & improvement loop\"). No behavioural-change publish without it. !! WHY: catch regression + confirm the intended behaviour improved. WHEN: every prompt/tool/model/version change. The tester persona + judge rubric must REACH the behaviour being changed. HOW → `nexus-evaluations` Mode B + `AGENT_BUILDER_LIFECYCLE.md` Phase 9 (load the skill — don't guess the mechanics).\n\n## Folder Organization\n\nOne level of nesting (parent/child). `folder delete` unassigns agents, doesn't delete them.\n\nRoutes/flags: `nexus folder --help` per session (R#11). Facts to keep: `assign` also MOVES; `--folder-id null` = unassign; `list` returns `{ folders[], assignments[] }`.\n\n## Attach Workflow to Agent (cross-domain hand-off)\n\n1. Build WF via `nexus-workflow-builder`.\n2. Validate + publish WF (DRAFT silently fails when attached).\n3. Attach: `nexus agent-tool create --label \"…\" --type WORKFLOW --body '{\"config\":{\"toolId\":\"\"},\"agentInputSchema\":{}}' --json`.\n4. Verify: `nexus agent-tool list --json`.\n\nDeployment hand-off → `nexus-deployments`.\n\n### PLUGIN fails ONLY at agent runtime → wrap as a WORKFLOW skill\n\nIf a PLUGIN tool works standalone (`external-tool execute`) and in `workflow test` but fails ONLY when the agent invokes it (a credential/variable that won't resolve in the agent-invocation context), do NOT declare a platform bug (CLAUDE.md Diagnosis self-check + R#10 cross-instance gate). AFTER localizing — confirm the action+credential resolve on another org/agent and via a workflow node — wrap the action in a tiny published workflow (agentInputTrigger → action → output) and attach it as a `WORKFLOW` skill: the workflow execution path resolves vars the direct-plugin agent path may not. Post-diagnosis remediation, not a reflex.\n\n## Post-Creation Testing\n\n1. `nexus agent get --json` → `modelName` set, `prompt` not empty, `status: ACTIVE`.\n2. `nexus agent-tool list --json` → labels match prompt refs, `isActive: true`, PLUGIN `config.toolCredentialId` valid. Test each via `nexus api POST /agents//tools//test`.\n3. Knowledge → correct method (knowledge vs skill); `documentCount > 0`.\n4. E2E via `nexus-emulator` → greeting tone, each skill triggers tool, knowledge Q hits collection. Tool INVOKED ≠ side-effect committed: after a write tool, query the row/record to confirm it landed — `debug.toolsInvoked` and the agent saying \"done\" are not proof (R#20/R#27). **Duration plausibility:** a seconds-fast reply where the invoked skill is a minutes-long workflow = a masked failure — the run FAILED or never fired and the agent answered from priors (often an honest-sounding \"nothing found\") — confirm a real execution exists (`execution list` → execId + status) before trusting any tool-backed claim.\n5. !! Systematic eval — `Skill(nexus-evaluations)`, Mode B (Phase 9): SIMULATED run per load-bearing behaviour, verdict PASS before \"ready\"; on later changes `run compare` vs baseline to catch regression. No \"ready\" without it. !! HOW lives in the skill.\n6. **Wiring verification — read the prompt FULLY (chunked, never a partial scan), then diff its `@skill` tags + `%%collection%%` markers against the AUTHORITATIVE census (`agent-tool list` + `GET /agents//collections`).** Skill attached but no `@` tag, OR collection attached but no `%%%%` marker → ask the prompt EDITOR to add it (pa-prompt-author for a new prompt; agent-prompt-modifier for a live edit), NAMING the skill/collection + what it does + when to use it (the editor writes the tool-use instructions; you don't hand-write them) — **never insert either token yourself.** A single marker is still a live-prompt write (`agent update --body`, one of the three doors in \"Modifying an existing agent prompt\" above): unrouted, it skips the modifier's region-consolidated edit, the Save-transform diff, and the `--no-publish` habit, for the same corruption risk that section warns against. An attached-but-unreferenced capability is INVISIBLE at runtime. Detail → `reference/agent-collections.md`.\n\nSteps 1–6 ARE the R#27 Agent Wiring Table evidence — no \"wired / ready / deployed / live\" claim without them, however plausible the happy-path answer looked: an agent that skipped this gate answers convincingly in a demo while its attached capabilities never fire (and its eval pillar — step 5 — is what catches the behaviour the demo hides).\n\n## Conversation context\n\n!! Before `{{conversation.satisfaction.*}}` references or topic-update CLI: Read `reference/conversation-context.md`. No prompt/CLI without it. !!\n\n## General-context integration\n\n> Every `pulse`/`final` path below is a DESTINATION for the background filing agent, which owns the write and resolves its own route from the drive's engine. Cue does not glob these paths: a duplicate check goes through `nexus workspace search --query `, server-side.\n\nWorkspace at `${GENERAL_CONTEXT_PATH}`. NO DRIVE ON THIS MACHINE, or one that will not read? Do NOT mount to find out: `nexus workspace search --query ` answers server-side, and `skills/shared/scripts/workspace-doctor.py` says what this machine needs. Its zero is BOUNDED: it opens text documents only, by extension — a PDF, an image or an extension-less file is never read, so its absence is not reported — and it stops at 1,000 files scanned, saying so in its tail. Installing a drive is the OWNER's step, never Cue's. Surface/drives/multi-writer/path-resolution → `nexus-workspaces`; the ROUTE follows the drive's engine → its \"## Engine matrix\", and the FUSE restrictions bind the fallback engines only (R#39). Env/auth/envelopes/dashboard → CLAUDE.md.\n\n| Trigger | Mode | Target |\n|---|---|---|\n| Persona / tone reference / stakeholders / tools / decisions / glossary / persona patterns | read | `/company/brand-guidelines.md` · `/people/.md` · `/tools/.md` · `/systems//decisions.md` · `/knowledge/glossary.md` · `/knowledge/patterns/agent-personas/*.md` |\n| Model-choice rationale (org-specific) | pulse | `/systems//decisions.md` (append H2) |\n| Reusable persona pattern (org-specific 1st instance) | pulse | `/knowledge/patterns/agent-personas/.md` (new-file) |\n| Tool-attachment gotcha (PLUGIN cred mismatch / WORKFLOW DRAFT silent-fail) | pulse | `/tools/.md \"## Gotchas\"` (append H3) |\n| **Cross-org** reusable agent archetype | pulse | `$SYSTEMS_PATH/agents//README.md` (new-file + INDEX) |\n| **Cross-org** persona / prompt pattern | pulse | `$SYSTEMS_PATH/agents//prompts.md` (append H2) |\n| **Cross-org** model-tier selection rationale | pulse | `$SYSTEMS_PATH/agents//lessons.md` (append H2) |\n| Agent created + wired + tested into known system | final | `/systems//agents/.md` (new-file, `templates/agent.md`) |\n| Tool integrated for this agent | final | `/tools/.md` (new-file or `## Used by` append) |\n| Persona/prompt pattern reusable across agents | final | `/knowledge/patterns/agent-personas/.md` (new-file, `templates/prompt-rule.md`) |\n| Postmortem (rebuild / wrong-tool runtime) | final | `/systems//learnings.md` (append H2) |\n\n✗ After agent build, file ONLY the agent spec (1 write) → ✓ Wiring Table completion fires 5 writes: agent spec + decision + persona (if reusable) + tool cross-link + glossary entries, each in its correct folder.\n\n## Gotchas (agent-specific — universals at CLAUDE.md G#)\n\n1. **`agentInputSchema` required** on every tool config — `{}` if no agent input.\n2. **`toolCredentialId`** (NOT `credentialId`) is the PLUGIN field name. ✗ silently dropped, runtime fails.\n3. **Credential ids are PER-TOOL** — the same mailbox/account has a different credential id under each tool wrapping it; an id from another tool's list → \"Credential not found or does not belong to this tool\". Resolve via THIS tool's `tool credentials `.\n4. **DELETE returns `{ id, deleted: true }`** (200, not 204) for agents/tools/versions/folders. Folder delete unassigns agents, doesn't delete them.\n5. **`behaviour` is a REMOVED field** (400 on create + update as of 2026-07 — rules go in the prompt); **`tags`** = comma-separated string.\n6. **COLLECTION uses `attach-collection` shorthand**, not the standard `agent-tool create` flow.\n7. **Tool config `description` is how agent knows WHEN to use it** — `<20 words`, \"Use X when Y. You MUST set Z.\"\n ✗ `\"Sends emails via Gmail\"` (no trigger, no params, agent guesses) → ✓ `\"Use send_email when user asks to send email. You MUST set body with HTML.\"`.\n8. **CLI-created agents have NO model by default** — set `modelConfig` immediately (R#8).\n9. **Verify tool labels match prompt refs** — prompt `@log-to-sheets` vs label `log_to_sheets` → agent can't find tool.\n10. **`agentInputSchema` is FLAT Nexus format** (`{type, properties, required}`). A WRAPPED schema (extra envelope, `$schema`/`definitions`, schema-inside-schema) is accepted on create but SILENTLY HANGS the run (`IN_PROGRESS`, 0 tokens, no validation error) — a run that never returns. Keep it flat; re-verify after any schema edit. As of 2026-07 a `required:` array nested inside a property object is silently dropped on create — declare requiredness at the schema ROOT; retest + supersede.\n\n## Error handling\n\n500 → file ticket per R#7 (`nexus-tickets`). Otherwise read `error.code`, fix, retry. Common: `VALIDATION_ERROR`, `NOT_FOUND`, `CONFLICT`, `INVALID_API_KEY`.\n\n## User-facing questions\n\nEvery Q through AUQ (R#3). Design → `nexus-getting-started/reference/clarification-guide.md`.\n\n| Category | Pre-populate from |\n|---|---|\n| Existing agent to modify | `nexus agent list --json` |\n| Tool attachment type | Domain-fixed + per-type platform query |\n| Folder destination | `nexus folder list --json` |\n| Prompt style | Domain-fixed short list |"},{"path":"examples/01-agent-crud.ts","content":"#!/usr/bin/env npx tsx\n/**\n * Agent CRUD -- Full lifecycle\n *\n * Demonstrates: create with all fields, list with pagination, get detail,\n * update (partial), duplicate, delete. Self-verifying with assertions.\n *\n * Run:\n * NEXUS_API_KEY=nxs_your_key npx tsx examples/01-agent-crud.ts\n */\n\nimport { createClient } from \"../../shared/api-client\";\nimport {\n assert,\n assertContains,\n assertDefined,\n assertEqual,\n log,\n onCleanup,\n runCleanup,\n success\n} from \"../../shared/helpers\";\n\nasync function main() {\n const api = createClient();\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 1: Create an agent with all available fields\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"create\", \"Creating agent with full configuration...\");\n\n const { data: agent } = await api.post(\"/agents\", {\n firstName: \"Revenue\",\n lastName: \"Analyst\",\n role: \"Financial Data Analyst\",\n shortBio: \"Analyzes revenue data and generates reports\",\n bio: \"A specialized financial analyst agent that tracks revenue metrics, identifies trends, and produces executive summaries for quarterly reviews.\",\n // objective/tone/behaviour are REMOVED fields (400 on create AND update, probed 2026-07):\n // behavioural rules live in the system prompt (set below via PATCH).\n tags: \"finance,revenue,analytics,reporting\",\n model: \"gpt-4o\"\n });\n\n assertDefined(agent.id, \"agent.id\");\n assertEqual(agent.firstName, \"Revenue\", \"firstName\");\n assertEqual(agent.lastName, \"Analyst\", \"lastName\");\n assertEqual(agent.role, \"Financial Data Analyst\", \"role\");\n log(\n \"create\",\n `Behaviours stored: ${(agent.behaviour ?? []).length} (behaviour may be empty until PATCH update)`\n );\n\n onCleanup(async () => {\n log(\"cleanup\", `Deleting agent ${agent.id}...`);\n await api.del(`/agents/${agent.id}`);\n });\n\n success(`Agent created: ${agent.firstName} ${agent.lastName} (${agent.id})`);\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 2: List agents with pagination\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"list\", \"Listing agents (page 1, limit 5)...\");\n\n const { data: agents, meta } = await api.get(\"/agents?page=1&limit=5\");\n\n assert(Array.isArray(agents), \"agents should be an array\");\n assert(agents.length >= 1, \"Should have at least 1 agent\");\n\n log(\"list\", `Found ${meta?.total ?? agents.length} agent(s)`);\n\n // Verify our agent appears in the list\n assertContains(agents, (a: any) => a.id === agent.id, \"Created agent should appear in list\");\n\n success(`List returned ${agents.length} agents on page 1`);\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 3: List with search filter\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"search\", \"Searching for agent by name...\");\n\n const { data: searchResult } = await api.get(`/agents?search=Revenue&page=1&limit=10`);\n\n assert(Array.isArray(searchResult), \"search result should be an array\");\n assertContains(\n searchResult,\n (a: any) => a.id === agent.id,\n \"Agent should appear in search results for 'Revenue'\"\n );\n\n success(`Search for 'Revenue' returned ${searchResult.length} result(s)`);\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 4: Get agent detail\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"get\", \"Fetching agent detail...\");\n\n const { data: detail } = await api.get(`/agents/${agent.id}`);\n\n assertEqual(detail.id, agent.id, \"detail.id\");\n assertEqual(detail.firstName, \"Revenue\", \"detail.firstName\");\n assertEqual(detail.role, \"Financial Data Analyst\", \"detail.role\");\n // Note: shortBio and tags may not be set via create -- they persist only via PATCH.\n // objective/tone/behaviour are removed fields; the GET never returns them.\n log(\"get\", `shortBio: ${detail.shortBio || \"(empty)\"}`);\n log(\"get\", `tags: ${detail.tags || \"(empty)\"}`);\n\n success(\"Agent detail verified with all fields\");\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 5: Update agent (partial -- only changed fields)\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"update\", \"Updating agent prompt and tone...\");\n\n const { data: updated } = await api.patch(`/agents/${agent.id}`, {\n prompt: [\n \"You are a revenue analyst at a SaaS company.\",\n \"\",\n \"Capabilities:\",\n \"- Analyze monthly recurring revenue (MRR) trends\",\n \"- Calculate churn rates and net revenue retention\",\n \"- Produce executive summary reports\",\n \"\",\n \"Rules:\",\n \"- Always show percent change vs. prior period\",\n \"- Use tables for data with 3+ rows\"\n ].join(\"\\n\")\n // tone/behaviour are REMOVED fields (400) — the Rules block above IS the behaviour surface.\n });\n\n assert(\n updated.prompt != null && updated.prompt.includes(\"revenue analyst\"),\n \"Prompt should be updated\"\n );\n\n // Verify unchanged fields were not affected\n assertEqual(updated.firstName, \"Revenue\", \"firstName should be unchanged\");\n assertEqual(updated.role, \"Financial Data Analyst\", \"role should be unchanged\");\n\n success(\"Agent updated (prompt carries the rules) -- other fields unchanged\");\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 6: Duplicate agent\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"duplicate\", \"Duplicating agent...\");\n\n const { data: duplicate } = await api.post(`/agents/${agent.id}/duplicate`);\n\n assertDefined(duplicate.id, \"duplicate.id\");\n assert(duplicate.id !== agent.id, \"Duplicate should have a new ID\");\n assertEqual(duplicate.role, \"Financial Data Analyst\", \"Duplicate should preserve role\");\n log(\"duplicate\", `Duplicate behaviours: ${(duplicate.behaviour ?? []).length}`);\n\n onCleanup(async () => {\n log(\"cleanup\", `Deleting duplicate ${duplicate.id}...`);\n await api.del(`/agents/${duplicate.id}`);\n });\n\n success(`Duplicated: ${duplicate.id} (copy of ${agent.id})`);\n\n // Verify both exist in list\n const { data: afterDup } = await api.get(\"/agents?page=1&limit=50\");\n assert(Array.isArray(afterDup), \"agent list should be an array\");\n const ids = afterDup.map((a: any) => a.id);\n assert(ids.includes(agent.id), \"Original should still exist\");\n assert(ids.includes(duplicate.id), \"Duplicate should exist\");\n\n success(\"Both original and duplicate verified in agent list\");\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 7: Delete agents\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"delete\", \"Deleting duplicate...\");\n\n const { data: deleteResult } = await api.del(`/agents/${duplicate.id}`);\n assertEqual(deleteResult.deleted, true, \"deleted flag\");\n assertEqual(deleteResult.id, duplicate.id, \"deleted id\");\n\n // Remove from cleanup since we manually deleted\n success(\"Duplicate deleted\");\n\n // Verify it no longer appears\n const { data: afterDelete } = await api.get(\"/agents?page=1&limit=50\");\n assert(Array.isArray(afterDelete), \"agent list should be an array\");\n const remainingIds = afterDelete.map((a: any) => a.id);\n assert(!remainingIds.includes(duplicate.id), \"Duplicate should no longer appear in list\");\n assert(remainingIds.includes(agent.id), \"Original should still exist\");\n\n success(\"Verified duplicate removed from list, original intact\");\n\n // ═══════════════════════════════════════════════════════════════════════════\n // Cleanup\n // ═══════════════════════════════════════════════════════════════════════════\n\n await runCleanup();\n\n console.log(\"\\n\" + \"=\".repeat(60));\n success(\"Agent CRUD complete!\");\n console.log(\"=\".repeat(60));\n}\n\nmain().catch((err) => {\n console.error(\"\\n\\x1b[31mFailed:\\x1b[0m\", err.message);\n runCleanup().then(() => process.exit(1));\n});"},{"path":"examples/02-configure-agent-tools.ts","content":"#!/usr/bin/env npx tsx\n/**\n * Configure Agent Tools -- Multiple tool types\n *\n * Creates an agent, then adds tools of different types:\n * - PLUGIN tool (marketplace integration via search + detail)\n * - WORKFLOW tool (reference an existing workflow)\n * - COLLECTION tool (via attach-collection shorthand)\n * Lists tools, updates one, deletes one. Self-verifying.\n *\n * Run:\n * NEXUS_API_KEY=nxs_your_key npx tsx examples/02-configure-agent-tools.ts\n */\n\nimport { createClient } from \"../../shared/api-client\";\nimport {\n assert,\n assertDefined,\n assertEqual,\n log,\n onCleanup,\n runCleanup,\n success\n} from \"../../shared/helpers\";\n\nasync function main() {\n const api = createClient();\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 1: Create the agent\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"setup\", \"Creating agent...\");\n\n const { data: agent } = await api.post(\"/agents\", {\n firstName: \"Operations\",\n lastName: \"Hub\",\n role: \"Business Operations Manager\",\n prompt:\n \"You are an operations manager. Use your tools to manage emails, trigger workflows, and search the knowledge base.\"\n });\n\n assertDefined(agent.id, \"agent.id\");\n onCleanup(async () => {\n log(\"cleanup\", `Deleting agent ${agent.id}...`);\n await api.del(`/agents/${agent.id}`);\n });\n success(`Agent created: ${agent.id}`);\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 2: Add a PLUGIN tool (marketplace integration)\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"plugin\", \"Searching marketplace for email tools...\");\n\n const { data: searchResults } = await api.get(\"/tools/search?q=gmail&limit=5\");\n assertDefined(searchResults.tools, \"search results\");\n assert(searchResults.tools.length > 0, \"Should find Gmail in marketplace\");\n\n const gmailTool = searchResults.tools[0];\n log(\"plugin\", `Found: ${gmailTool.name} (${gmailTool.id})`);\n\n // Get full detail with actions\n log(\"plugin\", \"Getting tool detail with actions...\");\n const { data: toolDetail } = await api.get(`/tools/${gmailTool.id}`);\n\n if (toolDetail.actions && toolDetail.actions.length > 0) {\n log(\"plugin\", `Actions available: ${toolDetail.actions.length}`);\n for (const action of toolDetail.actions.slice(0, 3)) {\n log(\"plugin\", ` - ${action.name} (${action.key})`);\n }\n }\n\n // Check for existing credentials\n const { data: credData } = await api.get(`/tools/${gmailTool.id}/credentials`);\n const existingCred = credData.credentials?.[0]?.id ?? null;\n log(\"plugin\", existingCred ? `Using credential: ${existingCred}` : \"No credential available\");\n\n // Create PLUGIN tool config with agentInputSchema\n log(\"plugin\", \"Creating PLUGIN tool config...\");\n\n const firstAction = toolDetail.actions?.[0];\n const pluginConfig: Record = {\n label: `${gmailTool.name} - ${firstAction?.name ?? \"Action\"}`,\n description: `Send emails via ${gmailTool.name}`,\n type: \"PLUGIN\",\n agentInputSchema: {\n type: \"object\",\n properties: {\n to: { type: \"string\", description: \"Recipient email address\" },\n subject: { type: \"string\", description: \"Email subject line\" },\n body: { type: \"string\", description: \"Email body content\" }\n },\n required: [\"to\", \"subject\", \"body\"]\n },\n config: {\n toolId: gmailTool.id,\n action: firstAction?.key ?? \"send-email\",\n ...(existingCred ? { toolCredentialId: existingCred } : {})\n }\n };\n\n const { data: pluginTool } = await api.post(`/agents/${agent.id}/tools`, pluginConfig);\n\n assertDefined(pluginTool.id, \"pluginTool.id\");\n assertEqual(pluginTool.type, \"PLUGIN\", \"tool type\");\n onCleanup(async () => {\n log(\"cleanup\", `Deleting plugin tool ${pluginTool.id}...`);\n await api.del(`/agents/${agent.id}/tools/${pluginTool.id}`);\n });\n success(`PLUGIN tool created: ${pluginTool.id} (${pluginTool.label})`);\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 3: Add a WORKFLOW tool\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"workflow\", \"Creating a test workflow to attach...\");\n\n // Create a simple workflow\n const { data: workflow } = await api.post(\"/workflows\", {\n name: \"Invoice Processor\",\n description: \"Processes incoming invoices\"\n });\n onCleanup(async () => {\n log(\"cleanup\", `Deleting workflow ${workflow.id}...`);\n await api.del(`/workflows/${workflow.id}`);\n });\n\n // Set trigger so it has a real trigger type\n await api.put(`/workflows/${workflow.id}/trigger`, { type: \"agentInputTrigger\" });\n\n log(\"workflow\", \"Creating WORKFLOW tool config...\");\n\n const { data: workflowTool } = await api.post(`/agents/${agent.id}/tools`, {\n label: \"Process Invoice\",\n description: \"Processes incoming invoices and extracts key data\",\n type: \"WORKFLOW\",\n agentInputSchema: {\n type: \"object\",\n properties: {\n invoiceUrl: { type: \"string\", description: \"URL of the invoice document\" },\n vendor: { type: \"string\", description: \"Vendor name (optional)\" }\n },\n required: [\"invoiceUrl\"]\n },\n config: {\n toolId: workflow.id\n }\n });\n\n assertDefined(workflowTool.id, \"workflowTool.id\");\n assertEqual(workflowTool.type, \"WORKFLOW\", \"tool type\");\n onCleanup(async () => {\n log(\"cleanup\", `Deleting workflow tool ${workflowTool.id}...`);\n await api.del(`/agents/${agent.id}/tools/${workflowTool.id}`);\n });\n success(`WORKFLOW tool created: ${workflowTool.id} (${workflowTool.label})`);\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 4: Add a COLLECTION tool via attach-collection\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"collection\", \"Creating a test collection...\");\n\n // Try to find an existing collection or create one\n let collectionId: string;\n try {\n const { data: skills } = await api.get(\"/tools/skills?type=COLLECTION&limit=1\");\n const existingCollection = skills.items?.[0] ?? skills.skills?.[0];\n if (existingCollection) {\n collectionId = existingCollection.id;\n log(\"collection\", `Using existing collection: ${existingCollection.name} (${collectionId})`);\n } else {\n // Create a new collection\n const { data: newCollection } = await api.post(\"/skills/collections\", {\n name: `ops-knowledge-base-${Date.now()}`,\n displayName: \"Operations Knowledge Base\",\n description: \"Company policies and procedures\"\n });\n collectionId = newCollection.id;\n log(\"collection\", `Created collection: ${collectionId}`);\n }\n } catch {\n // Fallback: create collection with unique name\n const { data: newCollection } = await api.post(\"/skills/collections\", {\n name: `ops-kb-fallback-${Date.now()}`,\n displayName: \"Operations KB\"\n });\n collectionId = newCollection.id;\n }\n\n log(\"collection\", \"Attaching collection to agent via shorthand endpoint...\");\n\n const { data: collectionTool } = await api.post(`/agents/${agent.id}/tools/attach-collection`, {\n collectionId: collectionId,\n label: \"Operations Knowledge Base\",\n description: \"Search company policies, procedures, and guidelines\",\n instructions:\n \"Use this tool when the user asks about company policies, HR procedures, or operational guidelines.\"\n });\n\n assertDefined(collectionTool.id, \"collectionTool.id\");\n assertEqual(collectionTool.type, \"COLLECTION\", \"tool type\");\n onCleanup(async () => {\n log(\"cleanup\", `Deleting collection tool ${collectionTool.id}...`);\n await api.del(`/agents/${agent.id}/tools/${collectionTool.id}`);\n });\n success(`COLLECTION tool created: ${collectionTool.id} (${collectionTool.label})`);\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 5: List all tools on agent\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"list\", \"Listing all tools on agent...\");\n\n const { data: tools } = await api.get(`/agents/${agent.id}/tools`);\n assert(Array.isArray(tools), \"Tools response should be array\");\n assert(tools.length >= 3, `Expected at least 3 tools, got ${tools.length}`);\n\n log(\"list\", `Agent has ${tools.length} tool(s):`);\n for (const t of tools) {\n log(\"list\", ` - ${t.label} (${t.type}) [${t.isActive ? \"active\" : \"inactive\"}]`);\n }\n\n // Verify each type appears\n const types = tools.map((t: any) => t.type);\n assert(types.includes(\"PLUGIN\"), \"Should have PLUGIN tool\");\n assert(types.includes(\"WORKFLOW\"), \"Should have WORKFLOW tool\");\n assert(types.includes(\"COLLECTION\"), \"Should have COLLECTION tool\");\n\n success(\"All 3 tool types verified on agent\");\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 6: Get a specific tool\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"get\", \"Getting specific tool detail...\");\n\n const { data: fetchedTool } = await api.get(`/agents/${agent.id}/tools/${workflowTool.id}`);\n\n assertEqual(fetchedTool.id, workflowTool.id, \"tool id\");\n assertEqual(fetchedTool.type, \"WORKFLOW\", \"tool type\");\n assertEqual(fetchedTool.label, \"Process Invoice\", \"tool label\");\n assertDefined(fetchedTool.agentInputSchema, \"agentInputSchema\");\n\n success(\"Tool detail verified\");\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 7: Update a tool config\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"update\", \"Updating PLUGIN tool label and description...\");\n\n const { data: updatedTool } = await api.patch(`/agents/${agent.id}/tools/${pluginTool.id}`, {\n label: \"Gmail - Send Professional Email\",\n description: \"Sends professional emails with signature via Gmail\",\n isActive: true\n });\n\n assertEqual(updatedTool.label, \"Gmail - Send Professional Email\", \"updated label\");\n assertEqual(\n updatedTool.description,\n \"Sends professional emails with signature via Gmail\",\n \"updated description\"\n );\n assertEqual(updatedTool.type, \"PLUGIN\", \"type should be unchanged\");\n\n success(\"Tool config updated\");\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 8: Delete a tool config\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"delete\", \"Deleting COLLECTION tool config...\");\n\n const { data: deleteResult } = await api.del(`/agents/${agent.id}/tools/${collectionTool.id}`);\n assertEqual(deleteResult.deleted, true, \"deleted flag\");\n\n // Verify it no longer appears\n const { data: remainingTools } = await api.get(`/agents/${agent.id}/tools`);\n const remainingIds = remainingTools.map((t: any) => t.id);\n assert(!remainingIds.includes(collectionTool.id), \"Deleted tool should not appear\");\n assert(remainingTools.length === tools.length - 1, \"Should have one fewer tool\");\n\n success(`Tool deleted. Agent now has ${remainingTools.length} tool(s)`);\n\n // ═══════════════════════════════════════════════════════════════════════════\n // Cleanup\n // ═══════════════════════════════════════════════════════════════════════════\n\n await runCleanup();\n\n console.log(\"\\n\" + \"=\".repeat(60));\n success(\"Configure Agent Tools complete!\");\n console.log(\"=\".repeat(60));\n}\n\nmain().catch((err) => {\n console.error(\"\\n\\x1b[31mFailed:\\x1b[0m\", err.message);\n runCleanup().then(() => process.exit(1));\n});"},{"path":"examples/03-version-management.ts","content":"#!/usr/bin/env npx tsx\n/**\n * Version Management -- Checkpoints, publish, restore, delete\n *\n * Creates an agent, makes prompt changes (generates AUTO versions), creates\n * named CHECKPOINT versions, publishes one to production, restores from a\n * checkpoint, and cleans up. Self-verifying.\n *\n * Run:\n * NEXUS_API_KEY=nxs_your_key npx tsx examples/03-version-management.ts\n */\n\nimport { createClient } from \"../../shared/api-client\";\nimport {\n assert,\n assertDefined,\n assertEqual,\n log,\n onCleanup,\n runCleanup,\n success\n} from \"../../shared/helpers\";\n\nasync function main() {\n const api = createClient();\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 1: Create agent with initial prompt\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"setup\", \"Creating agent with initial prompt...\");\n\n const initialPrompt = [\n \"You are a customer support agent.\",\n \"\",\n \"Guidelines:\",\n \"- Be polite and helpful\",\n \"- Escalate complex issues to a human\"\n ].join(\"\\n\");\n\n const { data: agent } = await api.post(\"/agents\", {\n firstName: \"Support\",\n lastName: \"Agent\",\n role: \"Customer Support\"\n });\n\n assertDefined(agent.id, \"agent.id\");\n onCleanup(async () => {\n log(\"cleanup\", `Deleting agent ${agent.id}...`);\n await api.del(`/agents/${agent.id}`);\n });\n\n // Note: prompt is not set via POST /agents -- must use PATCH\n log(\"setup\", \"Setting initial prompt via PATCH...\");\n await api.patch(`/agents/${agent.id}`, { prompt: initialPrompt });\n success(`Agent created and prompt set: ${agent.id}`);\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 2: List initial versions (should have AUTO versions)\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"versions\", \"Listing initial versions...\");\n\n const { data: versions } = await api.get(`/agents/${agent.id}/versions?page=1&limit=20`);\n\n log(\"versions\", `Found ${versions.length} initial version(s)`);\n for (const v of versions) {\n log(\"versions\", ` - ${v.type}: ${v.name ?? \"(unnamed)\"} | production: ${v.isProduction}`);\n }\n\n success(\"Initial version list retrieved\");\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 3: Create a named CHECKPOINT\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"checkpoint\", \"Creating named checkpoint 'v1.0 - Initial Setup'...\");\n\n const { data: checkpoint1 } = await api.post(`/agents/${agent.id}/versions`, {\n name: \"v1.0 - Initial Setup\",\n description: \"Basic support agent with escalation rules\"\n });\n\n assertDefined(checkpoint1.id, \"checkpoint1.id\");\n assertEqual(checkpoint1.type, \"CHECKPOINT\", \"type\");\n assertEqual(checkpoint1.name, \"v1.0 - Initial Setup\", \"name\");\n log(\"checkpoint\", `Prompt captured: ${checkpoint1.prompt ? \"yes\" : \"no (empty for new agents)\"}`);\n\n success(`Checkpoint created: ${checkpoint1.id} (${checkpoint1.name})`);\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 4: Update checkpoint metadata\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"update\", \"Updating checkpoint metadata...\");\n\n const { data: updatedCheckpoint } = await api.patch(\n `/agents/${agent.id}/versions/${checkpoint1.id}`,\n {\n name: \"v1.0 - Initial Setup (Reviewed)\",\n description: \"Reviewed and approved by team lead\"\n }\n );\n\n assertEqual(updatedCheckpoint.name, \"v1.0 - Initial Setup (Reviewed)\", \"updated name\");\n assertEqual(\n updatedCheckpoint.description,\n \"Reviewed and approved by team lead\",\n \"updated description\"\n );\n\n success(\"Checkpoint metadata updated\");\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 5: Publish the checkpoint to production\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"publish\", \"Publishing checkpoint to production...\");\n\n const { data: published } = await api.post(\n `/agents/${agent.id}/versions/${checkpoint1.id}/publish`\n );\n\n // After publish, the version should have isProduction true\n // Note: prompt may be empty for new agents\n log(\"publish\", `Published version isProduction: ${published.isProduction}`);\n assert(published.isProduction === true || published.id != null, \"Publish should succeed\");\n\n // Verify by listing versions\n const { data: publishedVersions } = await api.get(`/agents/${agent.id}/versions?page=1&limit=20`);\n log(\"publish\", `Versions after publish: ${publishedVersions.length}`);\n // Note: isProduction may not be reflected in the list endpoint -- trust the publish response\n const productionVersion = publishedVersions.find((v: any) => v.isProduction);\n if (productionVersion) {\n assertEqual(\n productionVersion.id,\n checkpoint1.id,\n \"Production version should be our checkpoint\"\n );\n } else {\n log(\"publish\", \"isProduction not reflected in list -- verified via publish response\");\n }\n\n success(`Version ${checkpoint1.id} published to production`);\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 6: Make prompt changes (generates AUTO version)\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"change\", \"Updating agent prompt (triggers AUTO version)...\");\n\n const updatedPrompt = [\n \"You are a senior customer support agent.\",\n \"\",\n \"Capabilities:\",\n \"- Handle billing inquiries\",\n \"- Process refund requests up to $100\",\n \"- Look up order status using the order tracker tool\",\n \"\",\n \"Guidelines:\",\n \"- Be polite and professional\",\n \"- Escalate requests over $100 to a manager\",\n \"- Always verify customer identity first\"\n ].join(\"\\n\");\n\n await api.patch(`/agents/${agent.id}`, { prompt: updatedPrompt });\n\n // Verify prompt changed\n const { data: agentAfterChange } = await api.get(`/agents/${agent.id}`);\n assert(agentAfterChange.prompt.includes(\"senior customer support\"), \"Prompt should be updated\");\n\n success(\"Prompt updated to v2\");\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 7: Create second checkpoint\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"checkpoint\", \"Creating second checkpoint 'v2.0 - Enhanced'...\");\n\n const { data: checkpoint2 } = await api.post(`/agents/${agent.id}/versions`, {\n name: \"v2.0 - Enhanced Capabilities\",\n description: \"Added billing, refunds, and order lookup\"\n });\n\n assertDefined(checkpoint2.id, \"checkpoint2.id\");\n assert(\n checkpoint2.prompt.includes(\"senior customer support\"),\n \"v2 checkpoint should capture updated prompt\"\n );\n\n success(`Second checkpoint: ${checkpoint2.id} (${checkpoint2.name})`);\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 8: List versions with type filter\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"list\", \"Listing only CHECKPOINT versions...\");\n\n const { data: checkpoints } = await api.get(\n `/agents/${agent.id}/versions?type=CHECKPOINT&page=1&limit=20`\n );\n\n log(\"list\", `Found ${checkpoints.length} checkpoint(s)`);\n for (const cp of checkpoints) {\n log(\"list\", ` - ${cp.name} | production: ${cp.isProduction} | ${cp.id}`);\n }\n\n assert(checkpoints.length >= 2, \"Should have at least 2 checkpoints\");\n assert(\n checkpoints.every((v: any) => v.type === \"CHECKPOINT\"),\n \"All should be CHECKPOINT type\"\n );\n\n // Note: meta does not include checkpointCount -- use the array length directly\n\n success(\"Checkpoint filter verified\");\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 9: Restore from first checkpoint\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"restore\", \"Restoring prompt from v1.0 checkpoint...\");\n\n const { data: restoreResult } = await api.post(\n `/agents/${agent.id}/versions/${checkpoint1.id}/restore`\n );\n\n // Restore may return the prompt or a message confirming the restore\n if (restoreResult.prompt) {\n log(\"restore\", `Prompt restored: ${restoreResult.prompt.slice(0, 80)}...`);\n }\n if (restoreResult.message) {\n log(\"restore\", `Message: ${restoreResult.message}`);\n }\n log(\"restore\", `Restore result keys: ${Object.keys(restoreResult).join(\", \")}`);\n\n // Verify agent's current prompt matches v1\n const { data: agentAfterRestore } = await api.get(`/agents/${agent.id}`);\n const restoredPrompt = agentAfterRestore.prompt ?? \"\";\n log(\"restore\", `Agent prompt after restore: ${restoredPrompt.slice(0, 80)}...`);\n // Note: prompt may be null/empty for agents that haven't had prompts explicitly set\n // The restore operation restores whatever the checkpoint captured\n log(\"restore\", `Prompt present: ${restoredPrompt ? \"yes\" : \"no (prompt was never set)\"}`);\n\n success(\"Version restore completed successfully\");\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 10: Get version detail (includes prompt)\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"detail\", \"Getting version detail with prompt...\");\n\n const { data: versionDetail } = await api.get(`/agents/${agent.id}/versions/${checkpoint2.id}`);\n\n assertEqual(versionDetail.id, checkpoint2.id, \"version id\");\n assertEqual(versionDetail.type, \"CHECKPOINT\", \"version type\");\n assertDefined(versionDetail.prompt, \"Version detail should include prompt\");\n assert(\n versionDetail.prompt.includes(\"senior customer support\"),\n \"v2 checkpoint should still have v2 prompt\"\n );\n\n success(\"Version detail includes full prompt snapshot\");\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 11: Delete non-production checkpoint\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"delete\", \"Deleting v2.0 checkpoint (non-production)...\");\n\n const { data: deleteResult } = await api.del(`/agents/${agent.id}/versions/${checkpoint2.id}`);\n assertEqual(deleteResult.deleted, true, \"deleted flag\");\n\n // Verify it no longer appears\n const { data: remainingCheckpoints } = await api.get(\n `/agents/${agent.id}/versions?type=CHECKPOINT&page=1&limit=20`\n );\n const deletedIds = remainingCheckpoints.map((v: any) => v.id);\n assert(!deletedIds.includes(checkpoint2.id), \"Deleted checkpoint should not appear\");\n\n success(\"Non-production checkpoint deleted\");\n\n // ═══════════════════════════════════════════════════════════════════════════\n // Cleanup\n // ═══════════════════════════════════════════════════════════════════════════\n\n await runCleanup();\n\n console.log(\"\\n\" + \"=\".repeat(60));\n success(\"Version Management complete!\");\n console.log(\"=\".repeat(60));\n}\n\nmain().catch((err) => {\n console.error(\"\\n\\x1b[31mFailed:\\x1b[0m\", err.message);\n runCleanup().then(() => process.exit(1));\n});"},{"path":"examples/04-folder-organization.ts","content":"#!/usr/bin/env npx tsx\n/**\n * Folder Organization -- Create, nest, assign, move, unassign, delete\n *\n * Demonstrates: parent/child folders, assigning agents to folders,\n * moving agents between folders, unassigning, and deleting folders\n * (verifying agents survive deletion). Self-verifying.\n *\n * Run:\n * NEXUS_API_KEY=nxs_your_key npx tsx examples/04-folder-organization.ts\n */\n\nimport { createClient } from \"../../shared/api-client\";\nimport {\n assert,\n assertContains,\n assertDefined,\n assertEqual,\n log,\n onCleanup,\n runCleanup,\n success\n} from \"../../shared/helpers\";\n\nasync function main() {\n const api = createClient();\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 1: Create parent folder\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"folders\", \"Creating parent folder...\");\n\n const { data: parentFolder } = await api.post(\"/folders\", {\n name: \"Production Agents\"\n });\n\n assertDefined(parentFolder.id, \"parentFolder.id\");\n assertEqual(parentFolder.name, \"Production Agents\", \"folder name\");\n assert(parentFolder.parentId == null, \"Parent folder should have no parentId\");\n\n onCleanup(async () => {\n log(\"cleanup\", `Deleting parent folder ${parentFolder.id}...`);\n try {\n await api.del(`/folders/${parentFolder.id}`);\n } catch {\n /* best effort */\n }\n });\n\n success(`Parent folder created: ${parentFolder.name} (${parentFolder.id})`);\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 2: Create child folder\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"folders\", \"Creating child folder...\");\n\n const { data: childFolder } = await api.post(\"/folders\", {\n name: \"Customer Support Team\",\n parentId: parentFolder.id\n });\n\n assertDefined(childFolder.id, \"childFolder.id\");\n assertEqual(childFolder.name, \"Customer Support Team\", \"child name\");\n assertEqual(childFolder.parentId, parentFolder.id, \"child parentId should match parent\");\n\n onCleanup(async () => {\n log(\"cleanup\", `Deleting child folder ${childFolder.id}...`);\n try {\n await api.del(`/folders/${childFolder.id}`);\n } catch {\n /* best effort */\n }\n });\n\n success(`Child folder created: ${childFolder.name} (parent: ${parentFolder.id})`);\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 3: Create two agents\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"agents\", \"Creating two agents...\");\n\n const { data: agent1 } = await api.post(\"/agents\", {\n firstName: \"Tier1\",\n lastName: \"Support\",\n role: \"L1 Support Agent\"\n });\n onCleanup(async () => {\n log(\"cleanup\", `Deleting agent ${agent1.id}...`);\n await api.del(`/agents/${agent1.id}`);\n });\n\n const { data: agent2 } = await api.post(\"/agents\", {\n firstName: \"Tier2\",\n lastName: \"Support\",\n role: \"L2 Support Agent\"\n });\n onCleanup(async () => {\n log(\"cleanup\", `Deleting agent ${agent2.id}...`);\n await api.del(`/agents/${agent2.id}`);\n });\n\n success(`Agent 1: ${agent1.firstName} ${agent1.lastName} (${agent1.id})`);\n success(`Agent 2: ${agent2.firstName} ${agent2.lastName} (${agent2.id})`);\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 4: Assign agents to folders\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"assign\", \"Assigning agent1 to parent folder...\");\n\n const { data: assign1 } = await api.post(\"/folders/assign\", {\n agentId: agent1.id,\n folderId: parentFolder.id\n });\n assertEqual(assign1.agentId, agent1.id, \"assigned agentId\");\n assertEqual(assign1.folderId, parentFolder.id, \"assigned folderId\");\n\n success(`Agent1 assigned to '${parentFolder.name}'`);\n\n log(\"assign\", \"Assigning agent2 to child folder...\");\n\n const { data: assign2 } = await api.post(\"/folders/assign\", {\n agentId: agent2.id,\n folderId: childFolder.id\n });\n assertEqual(assign2.agentId, agent2.id, \"assigned agentId\");\n assertEqual(assign2.folderId, childFolder.id, \"assigned folderId\");\n\n success(`Agent2 assigned to '${childFolder.name}'`);\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 5: List folders with assignments\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"list\", \"Listing all folders with assignments...\");\n\n const { data: folderList } = await api.get(\"/folders\");\n\n assertDefined(folderList.folders, \"folders array\");\n assertDefined(folderList.assignments, \"assignments array\");\n\n log(\"list\", `Folders: ${folderList.folders.length}`);\n for (const f of folderList.folders) {\n log(\"list\", ` - ${f.name} (parent: ${f.parentId ?? \"root\"})`);\n }\n\n log(\"list\", `Assignments: ${folderList.assignments.length}`);\n for (const a of folderList.assignments) {\n log(\"list\", ` - agent ${a.agentId} -> folder ${a.folderId}`);\n }\n\n // Verify our assignments\n assertContains(\n folderList.assignments,\n (a: any) => a.agentId === agent1.id && a.folderId === parentFolder.id,\n \"Agent1 should be assigned to parent folder\"\n );\n assertContains(\n folderList.assignments,\n (a: any) => a.agentId === agent2.id && a.folderId === childFolder.id,\n \"Agent2 should be assigned to child folder\"\n );\n\n success(\"Folder list with assignments verified\");\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 6: Move agent between folders\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"move\", \"Moving agent1 from parent to child folder...\");\n\n const { data: moveResult } = await api.post(\"/folders/assign\", {\n agentId: agent1.id,\n folderId: childFolder.id\n });\n assertEqual(moveResult.folderId, childFolder.id, \"New folder should be child\");\n\n // Verify both agents are now in child folder\n const { data: afterMove } = await api.get(\"/folders\");\n const agent1Assignment = afterMove.assignments.find((a: any) => a.agentId === agent1.id);\n assertDefined(agent1Assignment, \"Agent1 should still have an assignment\");\n assertEqual(agent1Assignment.folderId, childFolder.id, \"Agent1 should now be in child folder\");\n\n success(\"Agent1 moved to child folder\");\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 7: Unassign agent (folderId: null)\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"unassign\", \"Unassigning agent1 from all folders...\");\n\n const { data: unassignResult } = await api.post(\"/folders/assign\", {\n agentId: agent1.id,\n folderId: null\n });\n assert(unassignResult.folderId == null, \"folderId should be null after unassign\");\n\n // Verify agent1 no longer has an assignment\n const { data: afterUnassign } = await api.get(\"/folders\");\n const agent1AfterUnassign = afterUnassign.assignments.find((a: any) => a.agentId === agent1.id);\n assert(agent1AfterUnassign == null, \"Agent1 should have no folder assignment\");\n\n // Agent2 should still be assigned\n assertContains(\n afterUnassign.assignments,\n (a: any) => a.agentId === agent2.id && a.folderId === childFolder.id,\n \"Agent2 should still be in child folder\"\n );\n\n success(\"Agent1 unassigned, Agent2 still in folder\");\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 8: Update folder name\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"update\", \"Renaming child folder...\");\n\n const { data: updatedFolder } = await api.patch(`/folders/${childFolder.id}`, {\n name: \"Support Team (Renamed)\"\n });\n assertEqual(updatedFolder.name, \"Support Team (Renamed)\", \"updated name\");\n assertEqual(updatedFolder.parentId, parentFolder.id, \"parentId should be unchanged\");\n\n success(\"Child folder renamed\");\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 9: Delete child folder (agents should be unassigned, not deleted)\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"delete\", \"Deleting child folder...\");\n\n const { data: deleteChildResult } = await api.del(`/folders/${childFolder.id}`);\n assertEqual(deleteChildResult.deleted, true, \"deleted flag\");\n\n success(\"Child folder deleted\");\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 10: Delete parent folder\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"delete\", \"Deleting parent folder...\");\n\n const { data: deleteParentResult } = await api.del(`/folders/${parentFolder.id}`);\n assertEqual(deleteParentResult.deleted, true, \"deleted flag\");\n\n success(\"Parent folder deleted\");\n\n // ═══════════════════════════════════════════════════════════════════════════\n // STEP 11: Verify agents still exist (just unassigned)\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"verify\", \"Verifying agents survived folder deletion...\");\n\n const { data: agent1Detail } = await api.get(`/agents/${agent1.id}`);\n assertDefined(agent1Detail.id, \"Agent1 should still exist\");\n assertEqual(agent1Detail.firstName, \"Tier1\", \"Agent1 name intact\");\n\n const { data: agent2Detail } = await api.get(`/agents/${agent2.id}`);\n assertDefined(agent2Detail.id, \"Agent2 should still exist\");\n assertEqual(agent2Detail.firstName, \"Tier2\", \"Agent2 name intact\");\n\n // Verify no folder assignments remain\n const { data: finalFolders } = await api.get(\"/folders\");\n const ourAssignments = finalFolders.assignments.filter(\n (a: any) => a.agentId === agent1.id || a.agentId === agent2.id\n );\n assertEqual(ourAssignments.length, 0, \"No assignments should remain for our agents\");\n\n success(\"Both agents exist and are unassigned -- folder deletion is safe\");\n\n // ═══════════════════════════════════════════════════════════════════════════\n // Cleanup\n // ═══════════════════════════════════════════════════════════════════════════\n\n await runCleanup();\n\n console.log(\"\\n\" + \"=\".repeat(60));\n success(\"Folder Organization complete!\");\n console.log(\"=\".repeat(60));\n}\n\nmain().catch((err) => {\n console.error(\"\\n\\x1b[31mFailed:\\x1b[0m\", err.message);\n runCleanup().then(() => process.exit(1));\n});"},{"path":"examples/05-attach-workflow-to-agent.ts","content":"#!/usr/bin/env npx tsx\n/**\n * Attach Workflow to Agent -- Cross-domain recipe\n *\n * Creates a workflow with trigger -> textFormatter -> output, validates it,\n * tests it, creates an agent, attaches the workflow as a WORKFLOW tool,\n * verifies, and cleans up.\n *\n * This example spans two API domains: workflows and agents.\n *\n * Run:\n * NEXUS_API_KEY=nxs_your_key npx tsx examples/05-attach-workflow-to-agent.ts\n */\n\nimport { createClient } from \"../../shared/api-client\";\nimport {\n assert,\n assertContains,\n assertDefined,\n assertEqual,\n log,\n onCleanup,\n pollUntil,\n runCleanup,\n success} from \"../../shared/helpers\";\n\nasync function main() {\n const api = createClient();\n\n // ═══════════════════════════════════════════════════════════════════════════\n // PHASE 1: Build the Workflow\n // ═══════════════════════════════════════════════════════════════════════════\n\n // ── Step 1: Create workflow ─────────────────────────────────────────────\n log(\"workflow\", \"Creating workflow...\");\n\n const { data: workflow } = await api.post(\"/workflows\", {\n name: \"Order Status Lookup\",\n description: \"Accepts an order ID from the agent, formats a response message\"\n });\n\n assertDefined(workflow.id, \"workflow.id\");\n assertEqual(workflow.status, \"DRAFT\", \"initial status\");\n onCleanup(async () => {\n log(\"cleanup\", `Deleting workflow ${workflow.id}...`);\n await api.del(`/workflows/${workflow.id}`);\n });\n\n success(`Workflow created: ${workflow.id} (${workflow.status})`);\n\n // ── Step 2: Replace placeholder trigger with agentInputTrigger ──────────\n log(\"workflow\", \"Setting trigger to agentInputTrigger...\");\n\n const { data: triggerResult } = await api.put(`/workflows/${workflow.id}/trigger`, {\n type: \"agentInputTrigger\"\n });\n\n // Find the trigger node from the response\n const triggerNode = triggerResult.node ?? triggerResult;\n assertDefined(triggerNode.id, \"trigger node id\");\n\n success(`Trigger set: ${triggerNode.type ?? \"agentInputTrigger\"} (${triggerNode.id})`);\n\n // ── Step 3: Add a textFormatter processing node ─────────────────────────\n log(\"workflow\", \"Adding textFormatter node...\");\n\n const { data: textNode } = await api.post(`/workflows/${workflow.id}/nodes`, {\n type: \"textFormatter\",\n data: {\n text: `Order Status Report\\n\\nOrder ID: {{${triggerNode.id}.body}}\\nStatus: Processing\\nEstimated Delivery: 3-5 business days\\n\\nThank you for your patience.`\n }\n });\n\n assertDefined(textNode.id, \"textNode.id\");\n success(`TextFormatter node: ${textNode.id}`);\n\n // ── Step 4: Add an output node ──────────────────────────────────────────\n log(\"workflow\", \"Adding output node...\");\n\n const { data: outputNode } = await api.post(`/workflows/${workflow.id}/nodes`, {\n type: \"outputNode\"\n });\n\n assertDefined(outputNode.id, \"outputNode.id\");\n success(`Output node: ${outputNode.id}`);\n\n // ── Step 5: Connect trigger -> textFormatter -> output ──────────────────\n log(\"workflow\", \"Wiring edges...\");\n\n const { data: edge1 } = await api.post(`/workflows/${workflow.id}/edges`, {\n source: triggerNode.id,\n target: textNode.id\n });\n success(`Edge: trigger -> textFormatter (${edge1.id})`);\n\n const { data: edge2 } = await api.post(`/workflows/${workflow.id}/edges`, {\n source: textNode.id,\n target: outputNode.id\n });\n success(`Edge: textFormatter -> output (${edge2.id})`);\n\n // ── Step 6: Validate the workflow ───────────────────────────────────────\n log(\"workflow\", \"Validating workflow...\");\n\n const { data: validation } = await api.get(`/workflows/${workflow.id}/validate`);\n\n log(\"workflow\", `Valid: ${validation.isValid}, Ready to publish: ${validation.readyToPublish}`);\n\n if (validation.errors?.length > 0) {\n for (const err of validation.errors) {\n log(\"workflow\", ` Error: ${err.message} (${err.nodeType})`);\n }\n }\n\n // ═══════════════════════════════════════════════════════════════════════════\n // PHASE 2: Test the Workflow\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"test\", \"Testing workflow with sample data...\");\n\n try {\n const { data: testExec } = await api.post(`/workflows/${workflow.id}/test`, {\n triggerData: { body: \"ORD-12345\" }\n });\n\n if (testExec.executionId) {\n log(\"test\", `Execution started: ${testExec.executionId}`);\n\n // Poll for completion\n const result = await pollUntil(\n () => api.get(`/workflows/${workflow.id}/executions/${testExec.executionId}`),\n (res) => res.data.status !== \"RUNNING\",\n { intervalMs: 2000, timeoutMs: 30000, label: \"workflow-test\" }\n );\n\n log(\"test\", `Execution status: ${result.data.status}`);\n success(\"Workflow test completed\");\n } else {\n log(\"test\", \"No execution ID returned (may be awaiting trigger)\");\n }\n } catch (err: any) {\n log(\"test\", `Test skipped: ${err.message}`);\n }\n\n // ═══════════════════════════════════════════════════════════════════════════\n // PHASE 3: Create the Agent\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"agent\", \"Creating agent...\");\n\n const { data: agent } = await api.post(\"/agents\", {\n firstName: \"Order\",\n lastName: \"Tracker\",\n role: \"Order Status Assistant\",\n prompt: [\n \"You are an order status assistant.\",\n \"\",\n \"When a customer asks about their order:\",\n \"1. Ask for their order ID (format: ORD-XXXXX)\",\n \"2. Use the Order Status Lookup tool to check the status\",\n \"3. Relay the results to the customer in a friendly way\",\n \"\",\n \"If the customer does not have their order ID, suggest they check their confirmation email.\"\n ].join(\"\\n\")\n });\n\n assertDefined(agent.id, \"agent.id\");\n onCleanup(async () => {\n log(\"cleanup\", `Deleting agent ${agent.id}...`);\n await api.del(`/agents/${agent.id}`);\n });\n\n success(`Agent created: ${agent.firstName} ${agent.lastName} (${agent.id})`);\n\n // ═══════════════════════════════════════════════════════════════════════════\n // PHASE 4: Attach Workflow as Tool\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"attach\", \"Creating WORKFLOW tool config on agent...\");\n\n const { data: toolConfig } = await api.post(`/agents/${agent.id}/tools`, {\n label: \"Order Status Lookup\",\n description: \"Looks up the current status of a customer order by order ID\",\n type: \"WORKFLOW\",\n agentInputSchema: {\n type: \"object\",\n properties: {\n orderId: {\n type: \"string\",\n description: \"The order ID to look up (format: ORD-XXXXX)\"\n }\n },\n required: [\"orderId\"]\n },\n config: {\n toolId: workflow.id\n }\n });\n\n assertDefined(toolConfig.id, \"toolConfig.id\");\n assertEqual(toolConfig.type, \"WORKFLOW\", \"tool type\");\n\n success(`Workflow attached as tool: ${toolConfig.id}`);\n\n // ═══════════════════════════════════════════════════════════════════════════\n // PHASE 5: Verify the Setup\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"verify\", \"Verifying tool appears in agent's tool list...\");\n\n const { data: tools } = await api.get(`/agents/${agent.id}/tools`);\n\n assert(Array.isArray(tools), \"Tools should be an array\");\n assert(tools.length >= 1, \"Agent should have at least 1 tool\");\n\n assertContains(\n tools,\n (t: any) => t.id === toolConfig.id && t.type === \"WORKFLOW\",\n \"WORKFLOW tool should appear in agent tools\"\n );\n\n log(\"verify\", `Agent tools (${tools.length}):`);\n for (const t of tools) {\n log(\"verify\", ` - ${t.label} (${t.type})`);\n }\n\n // Verify the specific tool\n const { data: fetchedTool } = await api.get(`/agents/${agent.id}/tools/${toolConfig.id}`);\n assertEqual(fetchedTool.type, \"WORKFLOW\", \"tool type\");\n assertEqual(fetchedTool.label, \"Order Status Lookup\", \"tool label\");\n assertDefined(fetchedTool.agentInputSchema, \"agentInputSchema\");\n\n success(\"Full setup verified: workflow is attached to agent\");\n\n // ═══════════════════════════════════════════════════════════════════════════\n // PHASE 6: Summary\n // ═══════════════════════════════════════════════════════════════════════════\n\n log(\"summary\", \"Cross-domain setup complete:\");\n log(\"summary\", ` Workflow: ${workflow.name} (${workflow.id})`);\n log(\"summary\", ` Agent: ${agent.firstName} ${agent.lastName} (${agent.id})`);\n log(\"summary\", ` Tool: ${toolConfig.label} (${toolConfig.id})`);\n\n // ═══════════════════════════════════════════════════════════════════════════\n // Cleanup\n // ═══════════════════════════════════════════════════════════════════════════\n\n await runCleanup();\n\n console.log(\"\\n\" + \"=\".repeat(60));\n success(\"Attach Workflow to Agent complete!\");\n console.log(\"=\".repeat(60));\n}\n\nmain().catch((err) => {\n console.error(\"\\n\\x1b[31mFailed:\\x1b[0m\", err.message);\n runCleanup().then(() => process.exit(1));\n});"},{"path":"reference/agent-collections.md","content":"# Agent Collections\n\n## Two Attachment Methods\n\nCollections can be attached to agents in two fundamentally different ways:\n\n| Method | API | Runtime Behavior | Best For |\n|---|---|---|---|\n| **Knowledge** (always injected) | `nexus api POST /agents//collections --body '{\"collectionIds\":[\"...\"]}'` | Content ALWAYS included in agent's prompt context | FAQ, policies, pricing — small docs needed every conversation |\n| **Skill** (on-demand search) | `nexus agent-tool attach-collection` | Agent searches ONLY when it decides to, based on tool description | Large knowledge bases, product catalogs — searched when relevant |\n\n**Decision rule:** If the agent needs this information in EVERY conversation → knowledge mode. If only for specific questions → skill mode.\n\nWRONG: Using skill mode for a 10-page FAQ — agent won't search unless it \"decides\" to.\nWRONG: Using knowledge mode for 500 documents — wastes tokens injecting everything.\n\n## Knowledge Mode (Always Injected)\n\n```bash\n# Attach\nnexus api POST /agents//collections --body '{\"collectionIds\":[\"\"]}' --json\n\n# List\nnexus api GET /agents//collections --json\n\n# Detach\nnexus api DELETE /agents//collections --body '{\"collectionIds\":[\"\"]}' --json\n```\n\n### In-prompt injection marker (`%%collection%%`) — REQUIRED for the agent to actually use the knowledge\n\nAttaching a collection (`POST /agents//collections`) only REGISTERS it — `GET /agents//collections` is the authoritative census of what is registered. Registration alone does NOT place the content in the prompt. The agent only SEES the knowledge where the prompt's Knowledge section carries the injection marker:\n\n```\n%%collectionName%%\n```\n\nAt runtime the platform embeds the user's message, retrieves the top-N most similar chunks from that collection, and REPLACES the `%%collectionName%%` marker with those chunks as plain text. No marker → no injection point → the registered collection NEVER reaches the model context (the agent behaves as if it has no knowledge, even though `GET` shows it attached).\n\nPlacement rules:\n- The marker MUST sit ALONE on its own line/paragraph (chunks replace it; mid-sentence placement produces garbled output).\n- Put it in a dedicated Knowledge section with a one-line intro, e.g.:\n\n ```\n Knowledge you can draw on (retrieved per question):\n\n %%base_knowledge%%\n ```\n- One marker per collection; multiple collections → separate blocks, never crammed together.\n\nWRONG: collection attached via `POST /collections`, prompt says \"answer from the attached knowledge base\" but has no `%%...%%` marker → the agent has ZERO knowledge at runtime.\nRIGHT: collection attached AND `%%base_knowledge%%` present on its own line in a Knowledge section → chunks injected per question.\n\nNote: PA-generated prompts usually OMIT the marker (PA is not told the collection slug). After applying a PA prompt to an agent with an attached collection, add the marker — see the wiring-verification step in the main SKILL.md \"## Post-Creation Testing\".\n\n## Skill Mode (On-Demand Search)\n\nSee \"Knowledge Collections — Two Attachment Methods\" in the main SKILL.md.\n\n```bash\nnexus agent-tool attach-collection \\\n --collection-id \"\" \\\n --label \"Product KB\" \\\n --instructions \"Search when user asks about product features\" --json\n```"},{"path":"reference/conversation-context.md","content":"---\ntitle: Conversation context — agent prompt vars + workflow context\nparent: nexus-agent-management\npurpose: Fields agents / workflows reference for conversation context. Some need an opt-in query (`--satisfaction latest` / `--satisfaction summary`). nanoId interop notes. Topic-update CLI.\nlast_verified: 2026-06-10\n---\n\n# Conversation context\n\n## Fields agents / workflows reference\n\n| Field | Where / How | Notes |\n|---|---|---|\n| `conversation.id` / `conversation.nanoId` | List + Get response | Both accepted as input on every `/conversations/:id` endpoint. `nanoId` (5+5 uppercase alnum, e.g. `WLOX3_P18X5`) is user-surface-safe; nullable on pre-migration rows. |\n| `conversation.satisfaction.latest` | `nexus conversation get --satisfaction latest --json` (typed). Shape: `{ id, framework, source, rawScore, score, reasoning, comment, createdAt } \\| null`. Frameworks: `LEGACY_5_STAR \\| NPS \\| CSAT \\| AI_PASSIVE \\| CUSTOM`. Sources: `CUSTOMER_PROMPTED \\| AI_PASSIVE \\| LEGACY`. | Detractor escalation, NPS gates, negative-feedback routing. Default omits the field — must opt in. |\n| `conversation.satisfaction` (summary) | `nexus conversation get --satisfaction summary --json` — adds `totalCount` alongside `latest`. Counts only; the full array surface from earlier `?satisfaction=all` is retired. | Trend gating (\"only escalate if `totalCount > 3`\"). Most agents only need `.latest`. |\n\nWRONG: agent prompt references `{{conversation.satisfaction.latest.score}}` w/o opting in to `--satisfaction latest` first → field absent at runtime.\nRIGHT: workflow node fetches via `nexus conversation get --satisfaction latest --json` → passes `satisfaction.latest.score` to the agent prompt as a downstream variable.\n\n## Update conversation topic\n\n`nexus conversation update-topic --topic \"\" --json` (1–500 chars; accepts UUID or nanoId). Returns updated conversation. Use for programmatic relabeling / topic-from-summary patterns.\n\n## Channel-injected runtime variables\n\nReal deployment channels inject sender/context vars the agent prompt / workflow params can reference. Populated by the CHANNEL (not `conversation.*`), and EMPTY in the emulator (test in-message).\n\n| Var | Channel(s) | Use |\n|---|---|---|\n| `{{customerPhone}}` | WhatsApp / SMS / voice | Sender's number — key for per-sender lookups. |\n| `{{wa_id}}` | WhatsApp | Sender's WhatsApp id. |\n\nWRONG: reference `{{customerPhone}}` in the emulator → empty → \"the var is broken\".\nRIGHT: emulator → pass the number in-message; prod → reference `{{customerPhone}}` in the tool param/prompt.\n(Var names per observed live builds; extend the table only as channels surface more — verified-runs only, R#36.)"},{"path":"reference/endpoints.md","content":"# Agent Management CLI Reference\n\nAll commands require authentication via `nexus auth login` or the `NEXUS_API_KEY` environment variable.\nAdd `--json` to any command to get machine-readable JSON output.\n\n---\n\n## 0. Models (1 command)\n\n### List Models\n\n```bash\nnexus model list --json\n```\n\nNo parameters. Returns all enabled AI models available for agents.\n\n**Response:**\n\n```json\n{\n \"models\": [\n {\n \"id\": \"uuid\",\n \"modelId\": \"GPT_4_1\",\n \"provider\": \"OPEN_AI\",\n \"displayName\": \"GPT-4.1\",\n \"modelName\": \"gpt-4.1\",\n \"contextSize\": 1047576,\n \"streaming\": true,\n \"supportsThinking\": false,\n \"supportsReasoning\": false,\n \"deprecated\": false\n }\n ]\n}\n```\n\nUse the `modelId` value when setting the `model` field on agents. For example: `\"model\": \"GPT_4_1\"`.\n\n---\n\n## 1. Agents (7 commands)\n\n### List Agents\n\n```bash\nnexus agent list [--status ACTIVE|DRAFT] [--search ] [--limit ] --json\n```\n\n| Flag | Type | Required | Notes |\n| -------- | ------ | -------- | ------------------ |\n| --status | string | no | ACTIVE or INACTIVE |\n| --search | string | no | Search by name |\n| --limit | number | no | Default 20 |\n\n**Response:**\n\n```json\n{\n \"agents\": [\n {\n \"id\": \"uuid\",\n \"firstName\": \"Support\",\n \"lastName\": \"Bot\",\n \"role\": \"Customer Support\",\n \"shortBio\": \"Handles tickets\",\n \"profilePicture\": \"https://...\",\n \"status\": \"ACTIVE\",\n \"model\": \"gpt-4o\",\n \"createdAt\": \"2026-01-01T00:00:00.000Z\",\n \"updatedAt\": \"2026-01-01T00:00:00.000Z\"\n }\n ],\n \"meta\": { \"total\": 42, \"page\": 1, \"hasMore\": true }\n}\n```\n\n---\n\n### Get Agent\n\n```bash\nnexus agent get --json\n```\n\n| Param | Type | Notes |\n| ------- | ---- | -------------- |\n| agentId | uuid | Positional arg |\n\n**Response:** Full agent detail including prompt, bio, behaviour, tags, and model info. The system prompt is at **top-level `.prompt`** (flat resource); its body carries raw control chars (literal newlines) that break `jq` — decode with python (`json.JSONDecoder(strict=False)`, per CLAUDE.md G#11). `agent update` returns a wrapped `{success,id}` with NO prompt echo → re-fetch to verify the write persisted (SILENT-ACCEPTANCE).\n\n```json\n{\n \"id\": \"uuid\",\n \"firstName\": \"Support\",\n \"lastName\": \"Bot\",\n \"role\": \"Customer Support\",\n \"shortBio\": \"Handles tickets\",\n \"bio\": \"Detailed background...\",\n \"objective\": \"Resolve customer issues quickly\",\n \"tone\": \"Professional\",\n \"explanation\": null,\n \"behaviour\": [\"Always greet the customer\", \"Escalate complex issues\"],\n \"tags\": \"support,customer\",\n \"gender\": null,\n \"profilePicture\": null,\n \"status\": \"ACTIVE\",\n \"model\": \"gpt-4o\",\n \"modelName\": \"gpt-4o\",\n \"modelProvider\": \"OPEN_AI\",\n \"playgroundFirstMessage\": \"Hi! How can I help you today?\",\n \"prompt\": \"You are a customer support agent...\",\n \"createdAt\": \"2026-01-01T00:00:00.000Z\",\n \"updatedAt\": \"2026-01-01T00:00:00.000Z\"\n}\n```\n\n**Status codes:** 200 OK, 401 Unauthorized, 404 Not found\n\n---\n\n### Create Agent\n\n```bash\nnexus agent create --first-name --last-name --role [--model ] [--prompt ] [--body ] --json\n```\n\n| Flag | Type | Required | Notes |\n| ------------ | ------ | -------- | ---------------------------------- |\n| --first-name | string | yes | Min 1 character |\n| --last-name | string | yes | Min 1 character |\n| --role | string | yes | Min 1 character |\n| --model | string | no | Model name shorthand |\n| --prompt | string | no | File path or `-` for stdin |\n| --body | json | no | Full JSON body for advanced fields |\n\nAdditional fields via `--body`:\n\n| Field | Type | Notes |\n| ---------------------- | -------- | ----------------------------------------------------------------------- |\n| shortBio | string | |\n| bio | string | |\n| ~~objective~~ | — | REMOVED from the create API (400s); set the system prompt via `--prompt`/`prompt` |\n| ~~tone~~ | — | REMOVED from the create API (400s); set the system prompt via `--prompt`/`prompt` |\n| explanation | string | |\n| behaviour | string[] | Array of behaviour rules |\n| tags | string | Comma-separated string |\n| gender | string | |\n| model | string | Legacy model enum (OpenAI/Mistral only). Prefer `modelConfig`. |\n| modelConfig | object | Unified model config -- see below. Use `nexus model list --json` first. |\n| playgroundFirstMessage | string | Nullable; greeting message |\n\n**modelConfig object:**\n\n| Field | Type | Required | Notes |\n| ------------------- | ------ | -------- | ----------------------------------------------------------- |\n| modelName | string | yes | Model ID from `nexus model list` (e.g. \"claude-sonnet-4-6\") |\n| modelProvider | string | yes | OPEN_AI, ANTHROPIC, or GOOGLE_AI |\n| thinkingLevel | string | no | Anthropic only: fast, detailed, extended |\n| reasoningEffort | string | no | OpenAI only: none, auto, low, medium, high, xhigh |\n| geminiThinkingLevel | string | no | Google AI only: dynamic, minimal, low, medium, high |\n| temperature | number | no | 0-1 sampling temperature |\n\n**Response (201):** Full agent detail.\n\n**Status codes:** 201 Created, 400 Validation error, 401 Unauthorized\n\n---\n\n### Update Agent\n\n```bash\nnexus agent update [--first-name] [--last-name] [--role] [--model] [--prompt ] [--body ] --json\n```\n\nAll fields from Create are optional. Additionally:\n\n| Flag | Type | Notes |\n| -------- | ------ | ------------------------------------------------------ |\n| --prompt | string | Agent system instructions (file path or `-` for stdin) |\n\n**Response (200):** Updated agent detail.\n\n**Status codes:** 200 OK, 400 Validation error, 401 Unauthorized, 404 Not found\n\n---\n\n### Delete Agent\n\n```bash\nnexus agent delete [--yes]\n```\n\n**Response:**\n\n```json\n{ \"id\": \"uuid\", \"deleted\": true }\n```\n\n**Status codes:** 200 OK, 401 Unauthorized, 404 Not found\n\n---\n\n### Duplicate Agent\n\n```bash\nnexus agent duplicate --json\n```\n\nNo additional flags. Creates a copy with all configuration including prompt and tool configs.\n\n**Response (201):** Full detail of the new agent.\n\n**Status codes:** 201 Created, 401 Unauthorized, 404 Not found\n\n---\n\n### Upload Profile Picture\n\n```bash\nnexus api POST /agents//profile-picture --file avatar.png\n```\n\n| Field | Type | Required | Notes |\n| ----- | ---- | -------- | ------------------- |\n| file | file | yes | Image file (binary) |\n\n**Response:**\n\n```json\n{ \"profilePicture\": \"https://...\" }\n```\n\n**Status codes:** 200 OK, 400 No file, 401 Unauthorized, 404 Not found\n\n---\n\n## 2. Agent Tools (6 commands)\n\n### List Agent Tools\n\n```bash\nnexus agent-tool list --json\n```\n\n**Response:**\n\n```json\n{\n \"tools\": [\n {\n \"id\": \"uuid\",\n \"label\": \"Gmail - Send Email\",\n \"description\": \"Send emails via Gmail\",\n \"iconUrl\": \"https://...\",\n \"iconType\": \"url\",\n \"type\": \"PLUGIN\",\n \"agentInputSchema\": { \"type\": \"object\", \"properties\": {} },\n \"config\": { \"toolId\": \"google_gmail\", \"action\": \"send-email\", \"toolCredentialId\": \"cred-id\" },\n \"isActive\": true,\n \"createdAt\": \"2026-01-01T00:00:00.000Z\",\n \"updatedAt\": null\n }\n ]\n}\n```\n\n---\n\n### Get Agent Tool\n\n```bash\nnexus agent-tool get --json\n```\n\n**Response:** Single tool config object (same shape as list items).\n\n---\n\n### Create Agent Tool\n\n```bash\nnexus agent-tool create --label