@agentprojectcontext/apx 1.25.0 → 1.27.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentprojectcontext/apx",
-  "version": "1.25.0",
+  "version": "1.27.2",
   "description": "APX — unified CLI + daemon for the Agent Project Context (APC) standard.",
   "publishConfig": {
     "access": "public"
@@ -8,45 +8,74 @@
   "license": "MIT",
   "type": "module",
   "bin": {
-    "apx": "./src/cli/index.js",
-    "apx-daemon": "./src/daemon/index.js",
-    "apx-mcp": "./src/mcp/index.js"
+    "apx": "./src/interfaces/cli/index.js",
+    "apx-daemon": "./src/host/daemon/index.js",
+    "apx-mcp": "./src/interfaces/mcp-server/index.js"
   },
   "files": [
     "src/",
     "skills/",
-    "README.md"
+    "README.md",
+    "!**/node_modules/**",
+    "!**/e2e/**",
+    "!**/playwright-report/**",
+    "!**/test-results/**",
+    "!**/*.tsbuildinfo"
   ],
   "engines": {
     "node": ">=18"
   },
   "scripts": {
-    "start": "node src/daemon/index.js",
-    "smoke": "node src/daemon/smoke.js",
+    "start": "node src/host/daemon/index.js",
+    "smoke": "node src/host/daemon/smoke.js",
     "test": "node --test --test-reporter=spec tests/*.test.js",
+    "build:web": "node scripts/build-web.js",
+    "preflight": "npm test && node scripts/build-web.js && (cd src/interfaces/web && npx --no-install tsc --noEmit)",
     "upgrade": "pnpm install && pnpm add -g .",
-    "prepack": "node scripts/sync-apc-skill.js",
-    "postinstall": "node src/cli/postinstall.js"
+    "prepare": "node scripts/install-githooks.js",
+    "prepack": "node scripts/sync-apc-skill.js && node scripts/build-web.js",
+    "postinstall": "node src/interfaces/cli/postinstall.js"
   },
   "packageManager": "pnpm@10.25.0",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "@opentui/core": "^0.2.16",
+    "@opentui/keymap": "^0.2.16",
+    "@opentui/solid": "^0.2.16",
+    "@solid-primitives/event-bus": "^1.1.3",
+    "@solid-primitives/scheduled": "^1.5.2",
     "chalk": "^5.6.2",
     "cli-cursor": "^5.0.0",
+    "cli-sound": "^1.1.3",
+    "clipboardy": "^4.0.0",
     "cron-parser": "^5.5.0",
+    "effect": "^3.21.2",
+    "esbuild-plugin-solid": "^0.6.0",
     "express": "^4.21.0",
-    "node-fetch": "^3.3.2"
+    "fuzzysort": "^3.1.0",
+    "iconv-lite": "^0.6.3",
+    "node-fetch": "^3.3.2",
+    "open": "^10.1.2",
+    "opentui-spinner": "^0.0.6",
+    "qrcode-terminal": "^0.12.0",
+    "raw-body": "^3.0.0",
+    "react": "^19.2.0",
+    "remeda": "^2.21.0",
+    "safer-buffer": "^2.1.2",
+    "solid-js": "^1.9.13"
   },
   "optionalDependencies": {
+    "better-sqlite3": "^11.3.0",
     "fast-glob": "^3.3.2",
-    "puppeteer": "^22.0.0"
+    "puppeteer": "^22.0.0",
+    "sqlite-vec": "^0.1.6"
   },
   "devDependencies": {
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@types/node": "^25.7.0",
-    "better-sqlite3": "^11.3.0",
     "conventional-changelog-conventionalcommits": "^9.3.1",
+    "electron": "^33.4.11",
     "esbuild": "^0.28.0",
     "typescript": "^6.0.3"
   },
@@ -62,6 +91,7 @@
   "pnpm": {
     "onlyBuiltDependencies": [
       "better-sqlite3",
+      "electron",
       "puppeteer"
     ]
   },

package/skills/apx/SKILL.md

@@ -1,164 +1,95 @@
 ---
 name: apx
-description: "APX CLI skill. Activate when: user asks to run or coordinate agents, use MCP tools from .apc/mcps.json, install agents from a team workspace, or explicitly mentions apx commands. Do NOT activate just because .apc/ exists — that is handled by the apc-context skill. Activate on: 'apx run', 'apx exec', 'run an agent', 'coordinate agents', 'MCP not working', 'install agent', 'team agents', 'apx memory', 'daemon'."
+description: "APX CLI umbrella skill — what APX is, when to call it, and which sub-skill to use for each operation. Activate when the user mentions `apx`, asks to coordinate / run / delegate agents, brings up the APX daemon, or wants any APX-managed surface (sessions, MCPs, routines, tasks, telegram, projects, agents). Do NOT activate just because `.apc/` exists — that is handled by the apc-context skill. Triggers: 'apx', 'apx run', 'apx exec', 'apx daemon', 'coordinate agents', 'run an agent in codex', 'apx memory', 'apx help'."
 homepage: https://github.com/agentprojectcontext/apx
 ---
 
 # APX — Agent Project Context Runtime
 
-The daemon runs on `127.0.0.1:7430` and auto-starts on first `apx` call.
+APX is a daemon (`127.0.0.1:7430`, auto-starts on first call) that turns external coding CLIs (Claude Code, Codex, OpenCode, Aider, …) and configurable agents into a unified orchestration surface.
 
-APX reads APC project context from `.apc/`, but APX runtime state belongs outside the repository
-under `~/.apx/projects/<project-id>/`.
-
-The APX super-agent has an always-available default workspace at `~/.apx/projects/default`.
-When no project is named, system-level work belongs there.
+It reads APC project context from `.apc/` (committed) but keeps runtime state outside the repo under `~/.apx/projects/<project-id>/`. The super-agent has a default workspace at `~/.apx/projects/default` for system-level work.
 
 ---
 
-## Coordinate with other agents
-
-**First: can you spawn a subagent natively in this IDE?**
-
-If yes — do that. No APX needed. Claude Code, Cursor, and other IDEs can spawn subagents directly using your current context.
+## When to use APX (vs. spawning a subagent natively)
 
-Use `apx run` only when:
-- The user explicitly asks to run the agent in a specific external runtime ("run this in Codex", "run the QA agent outside this session")
-- You need to run an agent in a runtime different from the one you're in
-- You're orchestrating from outside any IDE (e.g. a script, Telegram bot, CI)
+If you can spawn a subagent natively in the IDE you're in (Claude Code, Cursor, …) — **do that**. No APX needed.
 
-```bash
-# Run agent in an external runtime — full isolated session
-apx run <slug> --runtime claude-code "<prompt>"
-apx run <slug> --runtime codex        "<prompt>"
-apx run <slug> --runtime opencode     "<prompt>"
-apx run <slug> --runtime aider        "<prompt>"
-apx run <slug> --runtime cursor-agent "<prompt>"
-apx run <slug> --runtime gemini-cli   "<prompt>"
-apx run <slug> --runtime qwen-code    "<prompt>"
-
-# Example: run the qa agent in codex with a specific task
-apx run qa --runtime codex "run the full test suite and report failures"
-```
+Use APX when:
+- The user explicitly asks for a specific external runtime ("run this in Codex", "delegate to OpenCode").
+- You need to run an agent in a runtime different from the one you're in.
+- You're orchestrating from outside any IDE (a script, Telegram bot, CI, routine).
 
-The output is the agent's full stdout. If it printed `APC_RESULT: <value>`, that value is captured as structured output.
+---
 
-```bash
-# Quick one-shot LLM call (no external CLI needed, uses ~/.apx/config.json engine key)
-apx exec <slug> "<prompt>"
-```
+## Sub-skill index — open the one that matches the task
 
-## Command accuracy
+| Topic | Sub-skill | When |
+|-------|-----------|------|
+| Delegate to an external coding CLI | **apx-runtime** | `apx run <agent> --runtime claude-code\|codex\|...` |
+| List / read / resume / summarise / continue sessions across engines | **apx-sessions** | `apx session resume`, `apx sessions list`, "traer sesión de codex" |
+| Use a registered MCP tool | **apx-mcp** | `apx mcp run`, "call MCP filesystem", "the MCP is failing" |
+| Add / configure / use a project agent | **apx-agent** | "add an agent", "import from vault", per-agent model, agent memory |
+| Register / list / configure a project | **apx-project** | "register this project", `apx project list`, per-project config |
+| Per-project TODO list | **apx-task** | "anotame", "recordame que…", "qué tengo pendiente" |
+| 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 |
+| Build a new MCP server — *internal/dev* | **apx-mcp-builder** | when developing a brand-new MCP from scratch |
+| Author a new APX skill — *internal/dev* | **apx-skill-builder** | when adding to APX itself |
 
-Do not invent APX subcommands. Before telling another runtime to call APX, verify the exact CLI
-form with `apx --help` or `apx <command> --help`.
+> Sub-skills marked *internal/dev* are not pushed to IDE skill dirs by default. They live in the APX repo and are loaded by APX itself; install one to your IDE with `apx skills add <slug> --global` if you want it there.
 
-Known Telegram form:
+---
 
-```bash
-apx telegram status
-apx telegram send "message"
-apx telegram send "message" --chat 123456
-```
+## Generic patterns (apply to every sub-skill)
 
-Do not use guessed aliases such as `apx send-telegram` or `apx telegram "message"` unless current
-`apx --help` shows that exact form.
+### Verify commands before recommending them
 
-## MCP tools
+Do not invent APX subcommands. Confirm exact CLI form with `apx --help` or `apx <command> --help` before telling another runtime to invoke APX. Avoid guessed aliases (e.g. `apx send-telegram` is *not* a thing — see apx-telegram).
 
-MCPs declared in `.apc/mcps.json` are proxied through the APX daemon. Use `apx mcp` only for MCPs registered there — not for MCPs that are already running locally in your IDE session.
+### `APC_RESULT` contract — structured return values
 
-```bash
-apx mcp list                            # MCPs registered in .apc/mcps.json
-apx mcp tools <server>                  # tools a server exposes
-apx mcp run   <server> <tool> '<json>'  # call a tool
+When you want APX to capture a structured value from an agent (any runtime), instruct the agent to print on its last meaningful line:
 
-# Example:
-apx mcp tools filesystem
-apx mcp run filesystem read_file '{"path": "README.md"}'
 ```
-
-## Memory
-
-Write memory only for durable, safe project facts. Do not store raw transcripts or secrets.
-
-```bash
-apx memory <slug>                       # read agent's memory.md
-apx memory <slug> --append "<fact>"     # append a durable note
-apx memory <slug> --replace < file.md  # replace entire memory from stdin
+APC_RESULT: <one-line value>
 ```
 
-## Sessions
+APX's `extractApfResult()` parses that and stores it as the session's `result` field. Useful for automation, routines, and CI.
 
-Sessions are APX runtime state. They do not belong in `.apc/`.
+### Tool permissions
 
 ```bash
-apx session new <slug> --title "What you did"   # create APX local session file
-apx session list <slug>                          # list sessions
-apx session check                                # exits 1 if session already active
+apx permission show
+apx permission set automatico   # total | automatico | permiso
 ```
 
-### List sessions of other AI engines
+`automatico` runs read/list/safe shell checks directly and asks before destructive shell, MCP, runtime, outbound, config, or filesystem mutation actions.
 
-`apx sessions list` lists sessions of external AI engines (Claude Code, Codex)
-without opening their interactive pickers. It resolves the project directory
-from a registered APX project (`--project`) or an explicit path (`--dir`).
+### Memory
 
-```bash
-apx sessions list                                       # APX engine projects (default)
-apx sessions list --engine claude                       # Claude Code project folders
-apx sessions list --engine claude --project iacrmar     # sessions of a registered project
-apx sessions list --engine claude --dir /path/to/repo   # sessions of any directory
-apx sessions list --engine codex  --dir /path/to/repo   # Codex sessions
-```
-
-Output prints date + session id + title, newest first, plus the exact resume command.
-
-**Resume a Claude Code session** (run from the project directory):
+Write memory only for durable, safe project facts. Do not store raw transcripts or secrets.
 
 ```bash
-claude --continue                       # resume the most recent session
-claude -p --resume <session-id> "..."   # resume a specific session, always with -p (print mode)
+apx memory <slug>                       # read agent's memory.md
+apx memory <slug> --append "<fact>"     # append a durable note
+apx memory <slug> --replace < file.md  # replace entire memory from stdin
 ```
 
-## Observe activity
+### Observe activity
 
 ```bash
 apx messages tail                               # last 50 messages, all channels
-apx messages chat --channel telegram -n 20      # chat view with user/agent/system type
-apx messages tail --channel runtime             # only agent invocations
-apx messages tail --agent <slug> -n 20
-```
-
-Message rows expose `type` (`user`, `agent`, `tool`, `system`) and `actor_id`; use `messages chat`
-when you need a readable transcript.
-
-## APX tool permissions
-
-```bash
-apx permission show
-apx permission set automatico   # total | automatico | permiso
+apx messages chat --channel telegram -n 20      # readable chat view
+apx messages tail --channel runtime --agent <slug> -n 20
 ```
 
-`automatico` runs read/list/safe shell checks directly and asks before destructive shell, MCP,
-runtime, outbound, config, or filesystem mutation actions.
-
-## Routines
-
-```bash
-apx routine list
-apx routine get <name>
-apx routine history <name>
-apx routine add clima --kind super_agent --schedule every:5m \
-  --permission-mode total \
-  --spec '{"prompt":"Check weather and send Telegram update."}'
-```
-
-Routine kinds: `heartbeat`, `exec_agent`, `super_agent`, `telegram`, `shell`.
+---
 
-## APC_RESULT
+## Anti-patterns
 
-Print on the last meaningful line of your output so the invoker captures it:
-```
-APC_RESULT: <one-line summary or value>
-```
+- Don't activate APX-sessions inside a request that's purely about `apx run` orchestration — use apx-runtime.
+- Don't activate apx-mcp-builder unless the user is actually authoring a new MCP server (it's a deep developer guide, not a usage guide).
+- Don't push state to `.apc/` that belongs in `~/.apx/projects/<id>/` (sessions, conversations, runtime logs).

package/skills/apx-agency-agents/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: apx-agency-agents
+description: "Manage the APX agent vault — a library of reusable agent templates (Roby, Cody, Rocky, Tessa, Max, Arch, Sid, Vera, Finn, plus generic specialists: development, marketing, ops, qa, support). Load this when the user wants to: spawn a specialized agent, look up which templates are available, import a template into a project, create a new vault template, delete/hide a bundled default, or restore a previously hidden one. Trigger on: 'lanzar agente', 'spawn agent', 'usar a Cody/Rocky/Tessa/Max/Arch/Sid/Vera/Roby', 'qué agentes hay', 'agent vault list', 'apx agent vault', 'importar agente', 'nuevo agente', 'crear agente nuevo', 'borrar agente default', 'restaurar agente'."
+---
+
+# apx-agency-agents — the APX agent vault
+
+The vault is the **global, project-agnostic library of agent templates** in APX. Two layers, deduped per-slug, with the user layer winning:
+
+| Layer | Where | Mutability |
+|---|---|---|
+| **Bundled** | `<repo>/assets/agent-vault-defaults/<slug>.md` | Read-only on disk. Always visible unless tombstoned. |
+| **User** | `~/.apx/agents/<slug>.md` | Read-write. Overrides the bundled with the same slug. |
+| **Tombstones** | `~/.apx/agents/.removed.json` | List of bundled slugs the user explicitly hid. |
+
+Listing returns `bundled ∪ user`, with `source: "bundled" | "user" | "user-override"` per entry. Editing a bundled entry is **copy-on-write** — it materializes into the user layer the moment you save. Deleting a bundled entry **tombstones** it (you can restore later); deleting a user-only entry physically removes the file.
+
+## Bundled starter pack
+
+APX ships 14 templates out of the box, two families:
+
+### Named team (from nicho-apps)
+A characterful crew already used in production by NichoApps:
+
+| Slug | Role | Strength |
+|---|---|---|
+| `roby-orchestrator` | Pipeline orchestrator | Autonomous task routing, multi-agent coordination |
+| `arch-architect` | Software architect | System design, tradeoffs, ADRs |
+| `cody-developer` | Senior Laravel dev | Code, refactors, technical leadership |
+| `tessa-qa` | QA / beta tester | Reality checks, test plans, real-user empathy |
+| `max-marketing` | Growth hacker | Content, campaigns, SEO, copy |
+| `sid-security` | Security specialist | Audits, threat models, hardening |
+| `rocky-pm` | Senior PM | Tasklists, roadmaps, stakeholder comms |
+| `vera-ui` | UI/UX reviewer | Visual audits, usability (uses browser-use) |
+| `finn-billing` | Billing / commercial ops | Stripe, invoicing, plan logic |
+
+### Generic specialists (from PandaProject)
+Plain functional roles — useful when you want capabilities without a persona:
+
+| Slug | Role |
+|---|---|
+| `development` | Engineering & code |
+| `marketing` | Marketing & growth |
+| `ops` | Ops, deploys & incidents |
+| `qa` | Quality assurance & testing |
+| `support` | Customer support & escalations |
+
+Both families default to `model: openrouter:meta-llama/llama-3.3-70b-instruct` and `language: es`. Override on import or by editing the vault file directly.
+
+## Concrete commands
+
+```bash
+# List the vault (bundled + your overrides, with [bundled] / [user] / [override] tags)
+apx agent vault list
+
+# Include tombstoned bundled defaults (the ones you hid)
+apx agent vault list --all
+
+# Create a new template (writes ~/.apx/agents/<slug>.md)
+apx agent vault add reviewer \
+  --role "Code reviewer" \
+  --model claude-haiku-4-5 \
+  --language es \
+  --skills code-review,git \
+  --description "Reviews PRs and pushes back on hand-wavy diffs."
+
+# Delete a template:
+#   - user-only slug → file is physically deleted
+#   - bundled slug   → tombstoned, hidden from listings
+apx agent vault rm tessa-qa
+
+# Bring back a tombstoned bundled default
+apx agent vault restore tessa-qa
+
+# Import a vault template into the current project
+apx agent import cody-developer
+apx agent import tessa-qa --copy     # copy into .apc/agents/ for local edits
+apx agent import roby-orchestrator --force   # overwrite an existing local def
+
+# Inside the daemon's tool API, the same flow:
+list_vault_agents()
+import_agent({ slug: "cody-developer", project: "<name-or-path>" })
+```
+
+## The web equivalents
+
+The Agent defaults tab (`/p/0/agent-defaults`) has the same CRUD: a "Nuevo" button (POST `/agents/vault`), "Editar" per card (PATCH `/agents/vault/:slug`, copy-on-write for bundled), "Borrar"/"Ocultar" (DELETE), and a "Mostrar removidos" toggle that surfaces tombstoned bundled defaults with a "Restaurar" button.
+
+## When to use which agent
+
+- **User says "lanzar a Cody/Rocky/Tessa/Max/Arch/Sid/Vera/Roby/Finn"** → that exact slug exists in the named team. Import it.
+- **User wants a "developer" / "QA" / "marketing" agent without a persona** → use the generic specialists (`development`, `qa`, `marketing`, …).
+- **User wants something not in the vault** → either `apx agent vault add <slug>` to create a blank one, or `apx agent add <slug>` directly inside a project for a one-off.
+- **The vault is empty on a fresh install** → suggest `apx agent vault sync` first.
+
+## Where the files live
+
+```
+<APX repo>/assets/agent-vault-defaults/<slug>.md   ← canonical bundle (committed)
+~/.apx/agents/<slug>.md                            ← user vault (sync target)
+<project>/.apc/agents/<slug>.md                    ← project-local copy (after import --copy)
+```
+
+The vault file format is identical to a project agent file:
+
+```
+---
+role: <human-readable role>
+model: <provider:model>
+description: <short description shown in UI grid>
+language: es
+skills: a, b, c
+tools: x, y
+is_master: false
+---
+
+<markdown body — the agent's system prompt extension>
+```
+
+## Frontmatter fields the runtime reads
+
+| Field | Effect |
+|---|---|
+| `role` | Shown in CLI/web. Appears in the agent's prompt as "Role: …". |
+| `model` | Default model for engine routing. |
+| `description` | Shown in `/agents/vault` and the AgentDefaultsTab cards. |
+| `language` | Adds "Default language: <code>" to the system prompt. |
+| `skills` | Per-agent skill names; relevant skill bodies are loaded by skill resolution. |
+| `tools` | Declared tool hints; actual callable tools depend on the invocation surface. |
+| `is_master` | If true, marked as a master agent in the project (badge + ordering). |
+
+## Related skills
+
+- **[apx-agent](../apx-agent/SKILL.md)** — per-project agent CRUD (add / edit / memory / list). The vault is the *library*; this skill is the *workshop*.
+- **[apx-runtime](../apx-runtime/SKILL.md)** — delegating to external coding CLIs (claude-code, codex, etc) from inside an agent.
+
+## Gotchas
+
+- **Bundled defaults are always present** — there's no sync step. They appear in `apx agent vault list` and in the web UI the moment APX is installed. Removing one tombstones it; editing one copies it to your user layer.
+- The slug `roby-orchestrator` is intentionally **not** `roby` — the APX super-agent persona is already named "Roby" via `~/.apx/identity.json`. Importing a project agent called `roby` would shadow that and cause confusion. Use `roby-orchestrator` for a *project-level* orchestrator.
+- The `agency-agents` skill in `~/.claude/skills/` pulls from an external GitHub repo (`msitarzewski/agency-agents`). APX bundles a snapshot in `assets/agent-vault-defaults/` so installs are offline-first. To refresh from upstream, edit the bundle and re-commit; existing users' overrides are untouched.

package/skills/apx-agent/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: apx-agent
+description: How to create, configure, and use project agents in APX. Load when the user wants to "add an agent", import from the vault, set a per-agent model, or write agent memory.
+---
+
+# apx-agent
+
+A project agent is a named persona inside an APC project. Canonical definition: `.apc/agents/<slug>.md` (flat file). `AGENTS.md` is auto-regenerated for discovery. Per-agent runtime data: `.apc/agents/<slug>/memory.md` (and optional `sessions/` only when using external runtimes that write APC session stubs — APX-native sessions live under `~/.apx/projects/<id>/`).
+
+## Concrete CLI calls
+
+```bash
+# List agents in a project
+apx agent list --project iacrmar
+
+# Create a new agent (writes .apc/agents/<slug>.md + regenerates AGENTS.md)
+apx agent add reviewer \
+  --role "Code reviewer" \
+  --model claude-haiku-4-5 \
+  --language es \
+  --description "Reviews PRs and pushes back on hand-wavy diffs." \
+  --tools read,write,run \
+  --skills code-review,git
+
+# Import an agent template from the global vault (~/.apx/agents/)
+apx agent vault list                 # see what's available
+apx agent import <slug>              # register vault slug in this project
+apx agent import <slug> --copy       # copy vault .md into .apc/agents/ for local edits
+apx agent import <slug> --force      # overwrite existing local definition
+
+# Show details (config + memory)
+apx agent get <slug>                 # alias: apx agent show <slug>
+
+# Per-agent memory (drives system prompt for that agent)
+apx memory <slug> --project iacrmar                          # read
+apx memory <slug> --project iacrmar --append "fact"          # append a line
+apx memory <slug> --project iacrmar --replace < file.md       # full replace from stdin
+```
+
+## What the agent's system prompt looks like
+
+`buildAgentSystem()` (`src/core/agent-system.js`) composes:
+
+1. Identity block: `You are <slug>` + project name.
+2. Description (from AGENTS.md).
+3. Role + Language fields.
+4. Invocation context: `engine | telegram | routine | runtime` — the channel calling the agent.
+5. Memory: `.apc/agents/<slug>/memory.md` if it exists.
+6. Skills declared in the agent's `Skills:` field, each loaded from `.apc/skills/<slug>.md` or the bundled set.
+7. The `apx` meta-skill (so the agent knows how to operate APX).
+8. ACTION_DISCIPLINE_RULES (fixed footer — anti-ghost, anti-disclaimer, action-first).
+
+That's the prompt the engine sees on every `apx exec <agent>` or `apx chat <agent>`. The super-agent (default APX mode) uses a *different* prompt — see `apx-routine` for when the super-agent runs vs. when an exec_agent runs.
+
+## Models per agent
+
+Each agent can set `Model:` in its `AGENT.md` to override the global super-agent model. Useful when a particular agent should use a cheaper / smaller / specialized model.
+
+```markdown
+# .apc/agents/reviewer.md
+---
+Role: Code reviewer
+Model: claude-haiku-4-5      ← this agent always uses Haiku, independent of super_agent.model
+Language: es
+---
+```
+
+When a routine `kind: exec_agent` runs with `spec.agent: reviewer`, it uses that model.
+
+## Anti-examples
+
+```bash
+# DON'T hand-write .apc/agents/<slug>.md without matching AGENTS.md regeneration.
+echo "..." > /path/.apc/agents/reviewer.md
+# ↑ Prefer `apx agent add` or `apx agent import` so AGENTS.md stays consistent.
+
+# DON'T set Model: to a provider you don't have keys for.
+# An agent with Model: openai:gpt-4o on a machine with no openai.api_key fails on first call.
+
+# DON'T put long-running context in `Description`. Put it in memory.md.
+# Description is one line, Role is a noun phrase, memory is unlimited.
+```
+
+## How agents differ from the super-agent
+
+| Aspect | Super-agent (default APX) | Project agent |
+|---|---|---|
+| Has tools? | Yes (the full registry) | No (text-in/text-out via callEngine) |
+| Loop? | Multi-iteration tool loop | Single call |
+| System prompt | `super-agent-base.md` + channel template + identity | `buildAgentSystem()` per-agent |
+| Conversation persisted in | super-agent surfaces | `<storagePath>/agents/<slug>/conversations/*.md` |
+| Configured via | `super_agent.*` in config | `AGENTS.md` + per-agent files |
+
+When in doubt: the 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. If you want tools, use the 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 use the same slug across projects expecting shared memory. Memory is per-project.