@agentprojectcontext/apx 1.80.2 → 1.89.1

package/src/core/routines/signals.js

@@ -18,6 +18,7 @@
 // summaries drift from the data they claim to describe.
 import { listTasks } from "#core/stores/tasks.js";
 import { listCommitments } from "#core/stores/commitments.js";
+import { readProjectMessages } from "#core/stores/messages.js";
 import { nowIso } from "#core/util/time.js";
 
 /** Every detector, keyed by the type it emits. */
@@ -27,6 +28,7 @@ export const SIGNAL_TYPES = Object.freeze([
   "stale_project",
   "commitment_due",
   "overdue_commitment",
+  "a2a_message",
 ]);
 
 /** Defaults chosen to be quiet. A watcher that cries on day one gets turned off. */
@@ -161,12 +163,76 @@ function detectOverdueCommitments(project, { now }) {
     );
 }
 
+/**
+ * An agent-to-agent message that landed for this project since the last sweep.
+ *
+ * This is the seam that lets a2a "reach" {{owner_name}}: an a2a turn never pings
+ * the owner directly (buildA2AReplySystem), it lands in the project's `a2a`
+ * ledger channel. The watch picks the recent inbound ones up as signals, and —
+ * because the watch now delivers to the profile's channel — the owner hears the
+ * ones Roby judges worth it, timed and batched, instead of a raw ping per message.
+ *
+ * Only DIRECTION "in" (something another agent sent into this project), and only
+ * since `a2a_since` (the watch's last run), so a message is surfaced once, not
+ * re-raised every two hours. A promise buried in an a2a message is already
+ * captured as a commitment by the a2a triage, so it resurfaces through the
+ * commitment detectors — this detector is for everything that is not a promise.
+ */
+/**
+ * The a2a severity contract: a sender tags a message [blocker | status | fyi],
+ * and the tag maps to a signal severity so the watch prioritises it.
+ *
+ * `blocker` is "critical": the owner chose that a blocker crosses even quiet
+ * hours (canNudge lets critical bypass, audited), because a blocker that waits
+ * until morning is not a blocker. `status`/`fyi` are gated like any other
+ * unrequested message. An untagged a2a message is a plain "normal" signal.
+ */
+export const A2A_SEVERITY = Object.freeze({ blocker: "critical", status: "normal", fyi: "low" });
+
+function detectA2A(project, { now, a2a_since, a2a_alerts = false }) {
+  // No last run yet → a bounded window, so a first sweep does not dump history.
+  const since = a2a_since || new Date(Date.parse(now) - 6 * 3_600_000).toISOString();
+  let msgs = [];
+  try {
+    msgs = readProjectMessages(project.storagePath, { channel: "a2a", since, limit: 50 });
+  } catch {
+    return []; // unreadable ledger → no evidence, surfaced as a skip by the caller
+  }
+  return msgs
+    // `owner_notified` rows were already pinged to the owner in the act (a
+    // `blocker` relayed with severity — see the /send route). The watch must not
+    // notify them a second time; the message still lives in the thread.
+    .filter((m) => m.direction === "in" && !m.meta?.owner_notified && (m.body || "").trim())
+    // TODO(notifications-menu): a2a alerting is OFF by default. Agent↔agent
+    // chatter — and simulated/test blockers like Magui's — was pinging the owner
+    // as noise, sometimes twice. Until there is a per-notification preferences
+    // menu (choose which agents / severities / channels may alert, and on which
+    // surface), only messages the owner EXPLICITLY asked to be told about
+    // (`solicited`) surface here. Set `a2a_alerts: true` on the profile to
+    // restore the old "Roby judges every a2a" behavior in the meantime.
+    .filter((m) => a2a_alerts === true || m.meta?.solicited === true)
+    .map((m) => {
+      const tag = String(m.meta?.severity || "").toLowerCase();
+      // The owner explicitly asked to be told about this one → the delivery is
+      // solicited, which crosses the interruption budget and quiet-hours (a
+      // reply is never held back). Only an explicit flag counts, never inferred.
+      const solicited = m.meta?.solicited === true;
+      return signal(project, {
+        type: "a2a_message",
+        severity: A2A_SEVERITY[tag] || "normal",
+        subject: `${m.author || "another agent"} sent (a2a${tag && A2A_SEVERITY[tag] ? `, ${tag}` : ""}): ${firstLine(m.body)}`,
+        payload: { from: m.author, ts: m.ts, body: m.body, tag: A2A_SEVERITY[tag] ? tag : null, solicited },
+      });
+    });
+}
+
 const DETECTORS = {
   overdue_task: detectOverdueTasks,
   blocked_task: detectBlockedTasks,
   stale_project: detectStaleProject,
   commitment_due: detectCommitmentsDue,
   overdue_commitment: detectOverdueCommitments,
+  a2a_message: detectA2A,
 };
 
 // ---------------------------------------------------------------------------
@@ -247,6 +313,9 @@ export function thresholdsFromConfig(profileConfig = {}) {
     blocked_hours: pick("blocked_task_hours", DEFAULT_THRESHOLDS.blocked_hours),
     stale_project_days: pick("stale_project_days", DEFAULT_THRESHOLDS.stale_project_days),
     commitment_lead_hours: pick("commitment_lead_hours", DEFAULT_THRESHOLDS.commitment_lead_hours),
+    // Whether agent↔agent chatter alerts the owner at all. OFF by default (see
+    // the TODO in detectA2A) — only `true` restores "Roby judges every a2a".
+    a2a_alerts: profileConfig.a2a_alerts === true,
   };
 }
 
@@ -261,6 +330,12 @@ function signal(project, fields) {
   };
 }
 
+/** First non-empty line of a body, trimmed to a signal-sized preview. */
+function firstLine(body) {
+  const line = String(body || "").split("\n").map((s) => s.trim()).find(Boolean) || "";
+  return line.length > 140 ? `${line.slice(0, 137)}…` : line;
+}
+
 /** Whole days between two YYYY-MM-DD strings. Negative when `to` precedes `from`. */
 function daysBetween(from, to) {
   const a = Date.parse(`${String(from).slice(0, 10)}T00:00:00Z`);

package/src/core/runtime-skills/apc-context/SKILL.md

@@ -45,7 +45,7 @@ Classify content:
 | Agent definitions: name, model, description | Put in `.apc/agents/<name>.md` and/or `AGENTS.md` |
 | Shared project rules, stack notes, commands, testing policy | Keep in `AGENTS.md` |
 | Reusable instruction blocks | Move to `.apc/skills/<name>.md` |
-| Durable safe facts useful to all contributors | Add to `.apc/agents/<name>/memory.md` only after curation |
+| Durable safe facts useful to all contributors | Add to `.apc/memory.md` only after curation |
 | MCP expectations without secrets | Add to `.apc/mcps.json` |
 | Raw sessions, transcripts, conversations, messages, tool logs | Do not move into `.apc/`; leave with source runtime |
 | Secrets, tokens, credentials, private headers | Do not store in repository |
@@ -69,7 +69,7 @@ AGENTS.md                        ← root project contract
   project.json                   ← project metadata
   .gitignore                     ← safety guard
   agents/<name>.md               ← agent definition
-  agents/<name>/memory.md        ← optional curated project memory
+  memory.md                      ← optional curated project memory (committed)
   skills/<name>.md               ← reusable project instructions
   mcps.json                      ← MCP hints without secrets
 ```
@@ -77,6 +77,7 @@ AGENTS.md                        ← root project contract
 Do not store:
 
 ```text
+.apc/agents/<name>/memory.md     ← agent memory is runtime state; see below
 .apc/agents/<name>/sessions/
 .apc/sessions/
 .apc/conversations/
@@ -92,7 +93,8 @@ Do not store:
 | Data | Visibility | Commit? |
 |---|---|---|
 | Agent definitions, skills, project rules | `stable` / `project` | Yes |
-| Curated safe `memory.md` | `project` | Yes, if team-safe |
+| Curated safe `.apc/memory.md` | `project` | Yes, if team-safe |
+| A single agent's `memory.md` | `local` | No; runtime-owned (`~/.apx/projects/<apx_id>/agents/<slug>/`) |
 | MCP hints without secrets | `project` | Yes |
 | Sessions, conversations, messages | `local` | No; runtime-owned |
 | Secrets, tokens, `*.secret.json`, `*.env` | `private` | Never |
@@ -102,7 +104,7 @@ Do not store:
 
 1. Read `AGENTS.md` and relevant `.apc/` files before assuming project context.
 2. Read agent definitions from `.apc/agents/<name>.md` when present.
-3. Read curated project memory from `.apc/agents/<name>/memory.md` when present.
+3. Read curated project memory from `.apc/memory.md` when present. An individual agent's own memory is runtime state and lives at `~/.apx/projects/<apx_id>/agents/<slug>/memory.md` — never under `.apc/`.
 4. Write only durable, safe, curated facts to APC memory.
 5. Never write raw sessions, transcripts, messages, conversations, or tool logs into `.apc/`.
 6. Keep secrets out of APC and out of git.
@@ -110,17 +112,22 @@ Do not store:
 
 ## Normalization
 
-If agent formats are broken or use legacy fields (role, skills in YAML), offer to normalize:
+`role`, `model`, `language`, `description`, `skills` and `tools` in YAML frontmatter
+are the canonical shape — this is exactly what `apx agent add` writes. Do NOT strip
+them.
 
 ```yaml
 ---
 name: agent-name
+role: what this agent is for
 model: inherit
 description: Semantic activation trigger
+skills: skill-a, skill-b
 ---
 ```
 
-Identify and fix inconsistencies in `model` (use technical IDs or `inherit`) and ensure `description` is present for semantic activation.
+Only fix genuine breakage: frontmatter that does not parse, a `model` that is neither
+a technical ID nor `inherit`, or a missing `description` (semantic activation needs it).
 
 ## Sessions
 
@@ -136,7 +143,7 @@ OpenCode runtime storage
 ```
 
 At task end, provide the user a concise result. If project memory should be updated, write a short
-sanitized fact to `.apc/agents/<name>/memory.md` only when useful and safe.
+sanitized fact to `.apc/memory.md` only when useful and safe.
 
 ## APX
 

package/src/core/runtime-skills/apx/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: apx
-description: "APX CLI umbrella — routes operations to sub-skills (sessions, MCPs, routines, tasks, telegram, projects, agents, runtimes). Activate on `apx`, the APX daemon, or coordinating/running/delegating agents. Not for `.apc/` alone (use apc-context). Triggers: 'apx', 'apx run', 'apx daemon', 'coordinate agents'."
+description: "APX CLI umbrella — routes operations to sub-skills (sessions, MCPs, routines, tasks, commitments, telegram, projects, agents, agent vault, profiles, runtimes). Activate on `apx`, the APX daemon, or coordinating/running/delegating agents. Not for `.apc/` alone (use apc-context). Triggers: 'apx', 'apx run', 'apx daemon', 'coordinate agents'."
 homepage: https://github.com/agentprojectcontext/apx
 ---
 
@@ -22,9 +22,13 @@ If you can spawn a subagent natively in the current IDE (Claude Code, Cursor,
 | Delegate to external coding CLI | **apx-runtime** | `apx run <agent> --runtime claude-code\|codex\|...` |
 | List/read/resume/summarise/continue sessions | **apx-sessions** | `apx session resume`, `apx sessions list`, "import a codex session" |
 | Use a registered MCP tool | **apx-mcp** | `apx mcp tools`, `apx mcp run`, "call MCP filesystem", "MCP failing" |
+| Connect/diagnose a service connector | **apx-integrations** | Asana/Calendar/GitHub/Obsidian, "not connected", "read-only calendar", Plugins tab |
 | Add/configure/use a project agent | **apx-agent** | "add an agent", vault import, per-agent model, agent memory |
+| Reusable agent templates (vault) | **apx-agency-agents** | "spawn Cody/Rocky/Tessa", "list agents", import a bundled default |
+| Install/activate an agent profile (line of work) | **apx-profile** | "install the secretary", "go back to vanilla", "why does it message me" |
 | Register/list/configure a project | **apx-project** | "register this project", `apx project list`, per-project config |
 | Per-project TODO list | **apx-task** | "add a task", "remind me to…", "what's pending" |
+| Promises made to a named person | **apx-commitment** | "I told X I would…", "le dije a X que…", "what do I owe X" |
 | Scheduled/recurring agents | **apx-routine** | `apx routine add`, every-5m, cron-like jobs |
 | Telegram I/O | **apx-telegram** | configure bot, channels, send a message |
 | Voice channel (TTS, speech) — *optional* | **apx-voice** | only if voice is being set up |
@@ -33,6 +37,94 @@ If you can spawn a subagent natively in the current IDE (Claude Code, Cursor,
 
 > *internal/dev* sub-skills aren't pushed to IDE skill dirs by default. They live in the APX repo; install to IDE with `apx skills add <slug> --global`.
 
+## Talk to a peer (a2a) — an agent OR another coding CLI
+
+When the user says "hablá con Roby" / "avisale a <agent>" / "pasale esto a <peer>",
+message them on the **a2a channel** — NOT `apx exec` (that posts as the user):
+
+```bash
+apx send <you> <peer> "<message>" --deliver [--project <name>]
+```
+
+- `<you>`: your own identity as sender — a coding CLI passes its runtime name
+  (`claude-code`, `codex`, `opencode`). It need NOT be a registered agent.
+- `<peer>`: whoever answers. Either:
+  - an **agent slug** from AGENTS.md — answered by that agent's model; or
+  - a **runtime id** (`claude-code`, `codex`, `opencode`, `aider`, `cursor-agent`,
+    `gemini-cli`, `qwen-code`, `antigravity`) — answered by spawning that CLI.
+    This is how one coding IDE talks to another through APX.
+- `:<thread>` opens a SECOND, independent exchange with the same peer —
+  `apx send claude-code opencode:review "…"`. Separate history, separate
+  session.
+- An agent slug wins over a runtime of the same name. If a slug lives in several
+  projects, `apx send` refuses and lists them — pass `--project`.
+  `apx agent list --all` shows every agent with its project. A runtime peer is
+  registered nowhere: it runs in the project you are standing in, in YOUR cwd.
+- `--deliver` runs the peer now and returns its reply on stdout. The exchange
+  shows in the web inbox as a "claude-code · opencode" group chat.
+
+### Two kinds of exchange: talking, and working
+
+By default an a2a message opens a **conversation**: the peer runs in its own
+read-only mode (`claude --permission-mode plan`, `codex --sandbox read-only`,
+`opencode --agent plan`). It can read anything and answer anything, but it
+cannot change the codebase. That is deliberate — being messaged is not consent
+to have your checkout edited.
+
+`--code` opens a **coding session** instead: write access on, the peer is told to
+do the work rather than describe it, and the exchange is mirrored into the **Code
+module** (`/code`) so it shows up where every other coding session does — the
+sender's messages as the user turns, the peer's replies as the assistant's.
+
+`claude-code` and `codex` are never `--code` peers. They are the CLIs you drive
+yourself, and a message must not also start them writing to the same checkout;
+they answer read-only. Send the work to `opencode`, or use `apx run`.
+
+```bash
+apx send claude-code opencode "¿qué le falta a src/auth?" --deliver
+apx send claude-code opencode "agregá el retry al fetch helper" --deliver --code
+```
+
+The peer runs in YOUR current directory, so `--code` edits the checkout you are
+standing in, not the project record's path.
+
+A coding session can take minutes. `--background` hands the turn back at once and
+the reply lands on the thread when it finishes (`--timeout <s>` caps it; default
+300s foreground, 3600s background):
+
+```bash
+apx send claude-code opencode "migrá los tests a node:test" --deliver --code --background
+```
+
+### The exchange keeps its own session
+
+A runtime peer continues its OWN session between turns (`claude -p --resume`,
+`codex exec resume`, `opencode run --session`). APX stores that id on the thread
+and resumes it next message, so the peer is not handed the transcript again and
+does not redo work it already did. `apx send` prints the session it used.
+
+A peer that cannot keep a session still works — APX carries the thread history in
+the prompt instead. Either way the conversation continues; sessions only make it
+cheaper. When there is no session, `apx send` says why instead of leaving the
+line blank.
+
+Runtimes with native sessions today: `claude-code`, `codex`, `opencode`. The rest
+(`aider`, `cursor-agent`, `gemini-cli`, `qwen-code`, `antigravity`) fall back to
+the carried thread.
+
+### Answering an a2a message
+
+Your output IS the reply: APX logs it and hands it back to the sender. Do NOT
+also run `apx send` with that same answer — it files the exchange twice. Use
+`apx send` only to open a NEW exchange: a follow-up once this turn is over, or a
+message to somebody else. Every a2a message carries its own return address.
+
+- The agent decides whether/how to tell the user on its own channel (respecting
+  quiet-hours) — you don't `apx telegram send` the user yourself.
+- `--severity blocker|status|fyi` tags urgency when relaying up to Roby: a
+  `blocker` alerts the owner **in the act** (Roby pings, crossing quiet-hours);
+  `status`/`fyi` ride the end-of-day digest and never interrupt.
+
 ## Generic patterns (apply to every sub-skill)
 
 ### Verify commands before recommending

package/src/core/runtime-skills/apx-agency-agents/SKILL.md

@@ -74,7 +74,7 @@ Agent defaults tab (`/p/0/agent-defaults`): same CRUD — "New" (POST `/api/agen
 
 - User says **"spawn/use Cody/Rocky/Tessa/Max/Arch/Sid/Vera/Roby/Finn"** → import that exact slug from named team.
 - User wants **"developer"/"QA"/"marketing" without a persona** → use generics (`development`, `qa`, `marketing`, …).
-- **Not in vault** → `apx agent vault add <slug>` for a new template, or `apx agent add <slug>` directly in a project for a one-off.
+- **Not in vault** → `apx agent vault add <slug>` for a new template, or `apx agent add <slug> --prompt -` directly in a project for a one-off. A new agent needs its system prompt (the file body), not just `--role`/`--description` — see `apx-agent`.
 - **Fresh install** → bundled defaults are always present (no sync step); appear in `apx agent vault list` immediately.
 
 ## File locations
@@ -110,7 +110,7 @@ is_master: false
 | `description` | Shown in `/api/agents/vault` and AgentDefaultsTab cards. |
 | `language` | Adds "Default language: <code>" to system prompt. |
 | `skills` | Per-agent skill names; bodies loaded by skill resolution. |
-| `tools` | Tool hints; actual callable tools depend on invocation surface. |
+| `tools` | Allowlist that *narrows* the agent's callable tools. Catalog names (`glob`, `memory_get`, `run_command`) map to native handlers. **Empty → broad default: the whole registry minus a few host-only tools** (`set_identity`, `set_permission_mode`, `add_project`, `import_agent`). Declaring the field takes tools away, so list everything the agent needs. |
 | `is_master` | If true, marked master in project (badge + ordering). |
 
 ## Related skills

package/src/core/runtime-skills/apx-agent/SKILL.md

@@ -1,11 +1,70 @@
 ---
 name: apx-agent
-description: Create, configure, use project agents in APX. Load when user wants to add an agent, import from vault, set a per-agent model, or write agent memory. Triggers: 'add agent', 'new agent', 'import agent', 'agent memory', 'per-agent model'.
+description: Create, configure, use project agents in APX — including writing an agent's SYSTEM PROMPT (the body of its definition file, required for the agent to do anything) and its identity (typology, area, role, avatar blob). Load when user wants to add an agent, write or change an agent's prompt/instructions/persona, set an agent's type/area/role/avatar, import from vault, set a per-agent model, or write agent memory. Triggers: 'add agent', 'new agent', 'create agent', 'agent prompt', 'agent instructions', 'agent type', 'agent area', 'agent avatar', 'import agent', 'agent memory', 'per-agent model'.
 ---
 
 # apx-agent
 
-A project agent is a named persona inside an APC project. Definition: `.apc/agents/<slug>.md` (flat); `AGENTS.md` auto-regenerated for discovery. Runtime data (memory, conversations, sessions) under `~/.apx/projects/<apx_id>/agents/<slug>/`, never committed. Legacy `.apc/agents/<slug>/memory.md` still read as migration fallback.
+A project agent is a named persona inside an APC project. Definition: `.apc/agents/<slug>.md` (flat) — that file **is** the agent; the roster is discovered by reading `.apc/agents/*.md` directly (`readAgents`). Runtime data (memory, conversations, sessions) under `~/.apx/projects/<apx_id>/agents/<slug>/`, never committed. That is the only place an agent's memory lives — nothing reads or writes a `memory.md` under `.apc/`.
+
+> **`AGENTS.md` is NOT the agent registry.** It's a generic startup-rules file written once by `apx init` and then owned by the user; APX **never** regenerates it (`scaffold.js`) and adding/removing an agent does not touch it. Editing it by hand is safe. Some projects (like the super-agent's `default`) have no `AGENTS.md` at all — that is normal, not a broken state.
+
+## The definition file has two halves — both matter
+
+```markdown
+---
+role: Social Media Producer      ← frontmatter: METADATA
+language: es
+description: One line for listings.
+type: specialist                 ← typology
+area: growth                     ← org-chart area
+icon: kiwi                       ← avatar blob preset
+---
+
+You are Magui, the social producer for …   ← body: THE SYSTEM PROMPT
+## Responsibilities
+- …
+## Hard limits
+- …
+```
+
+The **body** is the agent's real instruction set. `buildAgentSystem()` injects it as `# Custom instructions` (`src/core/agent/build-agent-system.js`), capped at 6000 chars. **`description` is not a substitute** — it is one line of metadata for listings. An agent created with frontmatter only runs on `role` + `description` + `language` and is told nothing about what to do, how, or what never to do.
+
+**Creating an agent without a prompt is the single most common mistake here, and nothing errors when you do it.** Always write the body.
+
+## Build it with a tool, not a shell (super-agent)
+
+If you are the super-agent, you have native tools for the agent lifecycle — use them, the same way you use `create_task` and `remember_routine`. Do **not** shell out to `apx agent add` and do **not** `write_file` the `.md` by hand (a raw write skips the daemon-registry rebuild the tools do for you, so the running daemon won't see the agent, and it's how a body-less agent gets papered over):
+
+| Tool | Does | Notes |
+|---|---|---|
+| `create_agent` | Creates the agent **with its system prompt** in one call | `system` is **required** — it refuses a body-less agent. Pass `slug` + `system`; add `role`/`skills`/`area`/`model` as needed. Omit `tools` unless narrowing. |
+| `set_agent_prompt` | Replaces an existing agent's prompt | Keeps every frontmatter field. |
+| `configure_agent` | Edits frontmatter (model, type, area, role, skills, …) | Keeps the prompt. Only the fields you pass change; empty string clears one. |
+| `remove_agent` | Deletes the agent + its runtime data | Irreversible — confirm first unless clearly asked. |
+| `write_agent_memory` | Seeds/updates **another** agent's `memory.md` | Not `remember` (that's YOUR notebook). `mode: append` (default) or `replace`. |
+
+Typical build: `create_agent({ slug, system, role, skills:["golf-lvl-2"] })` → optionally `write_agent_memory({ agent: slug, content: "..." })` to seed progress → `remember_routine(...)` for any schedule. One tool each, no shell, prompt inline.
+
+## Identity: typology, area, role, avatar
+
+Set these on create — they are what the team view, the hierarchy graph and every avatar render read. All optional except that leaving them empty makes the agent an untyped, unplaced face in a list.
+
+**`type`** — one of five, owned by `src/core/apc/agent-identity.js`:
+
+| type | meaning |
+|---|---|
+| `orchestrator` | Coordinates the team and delegates. Also marks the agent as master (it gets sub-agents). |
+| `specialist` | Domain expert; runs tasks. |
+| `assistant` | Conversational helper. |
+| `worker` | Runs autonomous tasks. |
+| `monitor` | Watches state and reports. |
+
+**`area` / `role`** — slugs from the project org chart (`.apc/organization.json`). **List them first, don't invent them:** `apx org show`, or the `org_list` MCP tool, or `GET /api/projects/:pid/organization`. Store the **slug** (`growth`), never the display name (`Growth`) — mixed case splits the team view into two groups that look identical. Free text is accepted and slugified on write. Create a missing area with `apx org area add "<name>"`.
+
+**`icon`** — the animated blob avatar. **You don't have to pick one:** every create path (CLI, MCP, API, web) now assigns one automatically, drawn from the blobs this project isn't using yet, so a team of six has six distinguishable faces. Pass `--icon <key>` only to pin a specific one. Keys: `menta parche trino cubi nimbo papa noche kiwi gajo campana cobalto rubi trebol saturno onyx`. `noche` is the super-agent's face and is never auto-assigned to a project agent.
+
+**`parent`** — the orchestrator this agent reports to, for the hierarchy view.
 
 ## Concrete CLI calls
 
@@ -13,14 +72,42 @@ A project agent is a named persona inside an APC project. Definition: `.apc/agen
 # List (agent commands are cwd-scoped — run from project root)
 apx agent list
 
-# Create (writes .apc/agents/<slug>.md, creates runtime dir, regenerates AGENTS.md)
+# See the areas/roles this project defines, before assigning one
+apx org show
+
+# Create WITH its system prompt (writes .apc/agents/<slug>.md, creates runtime
+# dir, rebuilds the daemon's agent registry). Heredoc, because a prompt is many lines:
 apx agent add reviewer \
+  --type specialist \
   --role "Code reviewer" \
+  --area engineering \
   --model ollama:llama3.2:3b \
   --language es \
   --description "Reviews PRs and pushes back on hand-wavy diffs." \
-  --tools read,write,run \
-  --skills code-review,git
+  --skills code-review,git \
+  --prompt - <<'EOF'
+You are the code reviewer for this project.
+
+## Responsibilities
+- Review diffs for correctness, not style.
+- Name the specific line and the specific failure mode.
+
+## Hard limits
+- Never approve a diff you could not explain back.
+- Never invent a test result you did not run.
+EOF
+
+# Same thing from a file
+apx agent add reviewer --role "Code reviewer" --prompt-file ./prompts/reviewer.md
+
+# Give a prompt to an agent that has none / replace an existing one
+apx agent set reviewer --prompt - < ./prompts/reviewer.md
+apx agent set reviewer --model gpt-5.2          # field-only edit keeps the prompt
+apx agent set reviewer --type specialist --area growth --icon kiwi
+# Aliases: apx agent edit, apx agent update
+
+# Read it back to confirm the body is there (not just the fields)
+apx agent get reviewer
 
 # Import from global vault (~/.apx/agents/)
 apx agent vault list                 # see what's available
@@ -39,16 +126,17 @@ apx memory <slug> --replace < file.md      # full replace from stdin
 
 ## Agent system prompt composition
 
-`buildAgentSystem()` (`src/core/agent-system.js`) composes:
+`buildAgentSystem()` (`src/core/agent/build-agent-system.js`) composes:
 
 1. Identity: `You are <slug>` + project name.
-2. Description (from AGENTS.md).
+2. Description (from the agent's own frontmatter).
 3. Role + Language fields.
-4. Invocation context: `engine | telegram | routine | runtime` — the channel calling.
-5. Memory: `~/.apx/projects/<apx_id>/agents/<slug>/memory.md` (legacy `.apc/agents/<slug>/memory.md` fallback).
-6. Skills from agent's `Skills:` field, loaded from `.apc/skills/<slug>.md` or bundled set.
-7. The `apx` meta-skill (so agent knows how to operate APX).
-8. ACTION_DISCIPLINE_RULES (fixed footer — anti-ghost, anti-disclaimer, action-first).
+4. **The agent's own body → `# Custom instructions`.** Empty body ⇒ this block is absent and the agent has no instructions.
+5. Invocation context: `engine | telegram | routine | runtime` — the channel calling.
+6. Memory: `~/.apx/projects/<apx_id>/agents/<slug>/memory.md` — the single location, no fallback.
+7. Skills from agent's `Skills:` field, loaded from `.apc/skills/<slug>.md` or bundled set.
+8. The `apx` meta-skill (so agent knows how to operate APX).
+9. ACTION_DISCIPLINE_RULES (fixed footer — anti-ghost, anti-disclaimer, action-first).
 
 That's the prompt on every `apx exec <agent>` / `apx chat <agent>`. The super-agent (default APX mode) uses a *different* prompt — see `apx-routine` for super-agent vs exec_agent.
 
@@ -67,12 +155,38 @@ Language: es
 
 A routine `kind: exec_agent` with `spec.agent: reviewer` uses that model.
 
+## Other surfaces (same capability, same required prompt)
+
+| Surface | Create | Set prompt | List areas/roles |
+|---|---|---|---|
+| Super-agent tool | `create_agent` (`system` required) | `set_agent_prompt` | `list_agents` / org |
+| CLI | `apx agent add <slug> --prompt -` | `apx agent set <slug> --prompt -` | `apx org show` |
+| MCP (`apx-mcp`) | `agent_create` (`prompt` required) | `agent_set_prompt` | `org_list` |
+| Daemon API | `POST /api/projects/:pid/agents` `{system}` | `PATCH .../agents/:slug` `{system}` | `GET .../organization` |
+| Web UI | Agents tab → new agent | agent detail → Prompt tab | Config tab pickers |
+
+All four write the same file, assign an avatar blob when none is given, and accept the same `type` / `area` / `role` / `parent`. `system` in the API is the same thing as `--prompt` in the CLI and the body of the `.md`.
+
 ## Anti-examples
 
 ```bash
-# DON'T hand-write .apc/agents/<slug>.md without regenerating AGENTS.md.
+# DON'T create an agent with metadata only. It exits 0 and the agent is useless.
+apx agent add magui --role "Social Media Producer" --description "Productora social."
+# ↑ No --prompt ⇒ no instructions. Fix: apx agent set magui --prompt - <<'EOF' … EOF
+
+# DON'T pack the instructions into --description. It is ONE LINE of metadata,
+# truncated in listings, and it is not the prompt.
+
+# DON'T invent an --area / --role slug. Run `apx org show` first; create the
+# area if it's missing (apx org area add "Growth").
+
+# DON'T make up an --icon. Only the 15 blob keys render; anything else is
+# rejected. Omit the flag and one is chosen for you.
+
+# DON'T hand-write .apc/agents/<slug>.md — the running daemon won't see it until a rebuild.
 echo "..." > /path/.apc/agents/reviewer.md
-# ↑ Use `apx agent add` or `apx agent import` so AGENTS.md stays consistent.
+# ↑ Use `apx agent add/set`, `apx agent import`, or the create_agent tool so the
+#   running daemon reloads its registry (a raw write it won't see until a rebuild).
 
 # DON'T set Model: to a provider without keys — fails on first call.
 # DON'T put long-running context in `Description` (one line). Put it in memory.md.
@@ -82,16 +196,17 @@ echo "..." > /path/.apc/agents/reviewer.md
 
 | Aspect | Super-agent (default APX) | Project agent |
 |---|---|---|
-| Has tools? | Yes (full registry) | No (text-in/text-out via callEngine) |
-| Loop? | Multi-iteration tool loop | Single call |
+| Has tools? | Yes (full registry) | Yes. **No declared `tools:` → the broad default: the whole registry minus a few host-only tools** (`set_identity`, `set_permission_mode`, `add_project`, `import_agent`). Declaring `tools:` *narrows* to that allowlist. |
+| Loop? | Multi-iteration tool loop | Multi-iteration, in a normal conversation or on `exec_agent`; one-shot text only when `spec.no_tools: true` |
 | System prompt | `super-agent-base.md` + channel template + identity | `buildAgentSystem()` per-agent |
 | Conversation in | super-agent surfaces | `<storagePath>/agents/<slug>/conversations/*.md` |
-| Configured via | `super_agent.*` in config | `AGENTS.md` + per-agent files |
+| Configured via | `super_agent.*` in config | `.apc/agents/<slug>.md` per-agent files |
 
 When in doubt: super-agent is APX itself; agents are personas inside a project.
 
 ## Don't
 
-- Don't expect a project agent to call tools. It can't. For tools, use super-agent or call MCPs from a routine `kind: shell`.
-- Don't overwrite `AGENTS.md` manually — `apx agent add/remove` regenerates it. Hand edits get clobbered.
+- Don't create an agent without a system prompt. Nothing errors; the agent just has no instructions. Verify with `apx agent get <slug>` — if you see only fields and no body, it isn't done.
+- Don't declare a `tools:` allowlist unless you mean to *narrow* the agent. Capability is the default: an agent with no `tools:` field already gets the whole registry minus a few host-only tools (`set_identity`, `set_permission_mode`, `add_project`, `import_agent`). Declaring the field takes tools *away* — so if you list one, list every tool the agent needs (`write_file`, `run_command`, `load_skill`, its MCP tools), or it silently loses the rest. When unsure, leave `tools:` off.
+- Don't assume `AGENTS.md` is the agent list — it isn't. It's a user-owned startup-rules file APX never regenerates; agents live in `.apc/agents/*.md`. A project with no `AGENTS.md` (the super-agent's `default`) is fine, not broken.
 - Don't use the same slug across projects expecting shared memory. Memory is per-project.