@agentprojectcontext/apx 1.34.0 → 1.36.0

package/src/core/agent/tools/registry.js

@@ -29,9 +29,13 @@ import askQuestions from "./handlers/ask-questions.js";
 import createTask from "./handlers/create-task.js";
 import listTasks from "./handlers/list-tasks.js";
 import discoverTools from "./handlers/discover-tools.js";
+import gitStatus from "./handlers/git-status.js";
+import gitDiff from "./handlers/git-diff.js";
+import gitLog from "./handlers/git-log.js";
+import gitShow from "./handlers/git-show.js";
 import { createPermissionGuard } from "./helpers.js";
 import { buildBridgedTools, DEFAULT_CATEGORIES } from "./registry-bridge.js";
-import { TOOLS } from "./names.js";
+import { TOOLS, CODE_CHANNEL_TOOLS } from "./names.js";
 import { CHANNELS } from "#core/constants/channels.js";
 
 const NATIVE_TOOLS = [
@@ -66,6 +70,10 @@ const NATIVE_TOOLS = [
   createTask,
   listTasks,
   discoverTools,
+  gitStatus,
+  gitDiff,
+  gitLog,
+  gitShow,
 ];
 
 // Registry-backed bridges. Categories can be overridden per-process via env
@@ -135,6 +143,15 @@ const FULL_CHANNELS = new Set([
   CHANNELS.API,
   CHANNELS.WEB,
   CHANNELS.CODE,
+  CHANNELS.WEB_CODE,
+]);
+
+// Coding surfaces — even on the lightweight set, these channels get the
+// git_* tools promoted into the base so the model can inspect the repo
+// without round-tripping through discover_tools every turn.
+const CODE_CHANNELS = new Set([
+  CHANNELS.CODE,
+  CHANNELS.WEB_CODE,
 ]);
 
 // Category labels for grouping the discover_tools catalog. Native tools have no
@@ -172,6 +189,10 @@ const NATIVE_CATEGORY = {
   [TOOLS.LIST_FILES]:          "files",
   [TOOLS.SEARCH_FILES]:        "files",
   [TOOLS.RUN_SHELL]:           "shell",
+  [TOOLS.GIT_STATUS]:          "code",
+  [TOOLS.GIT_DIFF]:            "code",
+  [TOOLS.GIT_LOG]:             "code",
+  [TOOLS.GIT_SHOW]:            "code",
 };
 
 function categoryOf(tool) {
@@ -200,14 +221,24 @@ export const BASE_TOOL_SCHEMAS = ALL_TOOLS
 
 const schemaName = (s) => s?.function?.name || s?.name;
 
+// Code-channel base = BASE + git_* tools. Pre-computed once.
+const CODE_BASE_TOOL_NAMES = new Set([...BASE_TOOL_NAMES, ...CODE_CHANNEL_TOOLS]);
+const CODE_BASE_TOOL_SCHEMAS = ALL_TOOLS
+  .filter((t) => CODE_BASE_TOOL_NAMES.has(t.name))
+  .map((t) => t.schema);
+
 /**
- * Choose the INITIAL tool schema list for a channel. Full channels get the
- * whole registry; lightweight channels (telegram/desktop/deck/web_sidebar) get
- * the base set and expand on demand via discover_tools. `full: true` forces the
- * complete registry regardless of channel.
+ * Choose the INITIAL tool schema list for a channel.
+ *   - FULL_CHANNELS (api, web, code, web_code, routine) get the whole registry.
+ *   - CODE_CHANNELS overlap with FULL, but when something forces a smaller set
+ *     (CODE_PLAN_TOOLS allowlist) the git_* tools are still in their base.
+ *   - Everything else is "lightweight" and starts on BASE_TOOL_NAMES.
+ *
+ * `full: true` forces the complete registry regardless of channel.
  */
 export function schemasForChannel(channel, { full = false } = {}) {
   if (full || FULL_CHANNELS.has(channel)) return TOOL_SCHEMAS;
+  if (CODE_CHANNELS.has(channel)) return CODE_BASE_TOOL_SCHEMAS;
   return BASE_TOOL_SCHEMAS;
 }
 

package/src/core/config/index.js

@@ -117,6 +117,27 @@ const DEFAULT_CONFIG = {
     compact_model: "ollama:gemma4:31b-cloud", // light LLM for compaction (Ollama, local endpoint)
     compact_fallback_model: "",        // "" → falls back to super_agent.model (APX default)
   },
+  skills: {
+    // Skill Inspector — opt-in test feature. When enabled, the static
+    // "Available skills" hint block (slug dump) is removed from the system
+    // prompt; instead a local RAG inspects each turn's user prompt and
+    // injects either the matching skill's body (high confidence) or a hint
+    // to call load_skill (mid confidence). Below threshold → nothing.
+    // Re-evaluated every turn → natural decay (a skill that stopped matching
+    // disappears next turn).
+    // Embedding provider is whatever memory.embeddings resolves to (defaults
+    // to local: ollama → gemini → openai → offline TF). No paid keys needed.
+    inspector: {
+      enabled: false,
+      load_threshold: 0.55,
+      hint_threshold: 0.40,
+      margin: 0.04,
+      max_loaded: 1,
+      max_hints: 2,
+      prompt_floor: 8,
+      body_char_cap: 6000,
+    },
+  },
   voice: {
     // Text-to-speech configuration. Selector reads voice.tts.provider; "auto"
     // probes engines in preference order (piper → elevenlabs → openai →

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

@@ -1,55 +1,45 @@
 ---
 name: apx
-description: "APX CLI umbrella — which sub-skill handles each operation (sessions, MCPs, routines, tasks, telegram, projects, agents, runtimes). Activate when the user mentions `apx`, the APX daemon, or wants to coordinate/run/delegate agents. Not for `.apc/` alone (use apc-context). Triggers: 'apx', 'apx run', 'apx daemon', 'coordinate agents', 'apx help'."
+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'."
 homepage: https://github.com/agentprojectcontext/apx
 ---
 
 # APX — Agent Project Context Runtime
 
-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 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. It reads APC project context from `.apc/` (committed) but keeps runtime state outside the repo under `~/.apx/projects/<project-id>/`. Super-agent has a default workspace at `~/.apx/projects/default` for system-level work.
 
-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.
+## When to use APX (vs. native subagent)
 
----
-
-## When to use APX (vs. spawning a subagent natively)
-
-If you can spawn a subagent natively in the IDE you're in (Claude Code, Cursor, …) — **do that**. No APX needed.
-
-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).
-
----
+If you can spawn a subagent natively in the current IDE (Claude Code, Cursor, …) — **do that**. No APX needed. Use APX when:
+- User explicitly asks for a specific external runtime ("run this in Codex", "delegate to OpenCode").
+- You need an agent in a runtime different from the one you're in.
+- Orchestrating from outside any IDE (script, Telegram bot, CI, routine).
 
-## Sub-skill index — open the one that matches the task
+## Sub-skill index
 
 | 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`, "import a codex session" |
-| 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 |
+| 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 run`, "call MCP filesystem", "MCP failing" |
+| Add/configure/use a project agent | **apx-agent** | "add an agent", vault import, 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** | "add a task", "remind me to…", "what's pending" |
-| Scheduled / recurring agents | **apx-routine** | `apx routine add`, every-5m, cron-like jobs |
+| 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 |
-
-> 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.
+| Build a new MCP server — *internal/dev* | **apx-mcp-builder** | authoring a brand-new MCP from scratch |
+| Author a new APX skill — *internal/dev* | **apx-skill-builder** | adding to APX itself |
 
----
+> *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`.
 
 ## Generic patterns (apply to every sub-skill)
 
-### Verify commands before recommending them
+### Verify commands before recommending
 
-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).
+Don't invent APX subcommands. Confirm exact 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).
 
-### `APC_RESULT` contract — structured return values
+### `APC_RESULT` contract
 
 When you want APX to capture a structured value from an agent (any runtime), instruct the agent to print on its last meaningful line:
 
@@ -57,7 +47,7 @@ When you want APX to capture a structured value from an agent (any runtime), ins
 APC_RESULT: <one-line value>
 ```
 
-APX's `extractApfResult()` parses that and stores it as the session's `result` field. Useful for automation, routines, and CI.
+APX's `extractApfResult()` parses that and stores it as the session's `result` field. Useful for automation, routines, CI.
 
 ### Tool permissions
 
@@ -66,16 +56,16 @@ apx permission show
 apx permission set automatico   # total | automatico | permiso
 ```
 
-`automatico` runs read/list/safe shell checks directly and asks before destructive shell, MCP, runtime, outbound, config, or filesystem mutation actions.
+`automatico` runs read/list/safe shell checks directly; asks before destructive shell, MCP, runtime, outbound, config, or filesystem mutation.
 
 ### Memory
 
-Write memory only for durable, safe project facts. Do not store raw transcripts or secrets.
+Write memory only for durable, safe project facts. No 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
+apx memory <slug> --append "<fact>"     # append durable note
+apx memory <slug> --replace < file.md   # replace entire memory from stdin
 ```
 
 ### Observe activity
@@ -86,10 +76,8 @@ apx messages chat --channel telegram -n 20      # readable chat view
 apx messages tail --channel runtime --agent <slug> -n 20
 ```
 
----
-
 ## Anti-patterns
 
-- 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 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 (deep dev guide, not usage).
 - Don't push state to `.apc/` that belongs in `~/.apx/projects/<id>/` (sessions, conversations, runtime logs).

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

@@ -1,26 +1,23 @@
 ---
 name: apx-agency-agents
-description: "Manage the APX agent vault — reusable agent templates (Roby, Cody, Rocky, Tessa, Max, Arch, Sid, Vera, Finn + generic dev/marketing/ops/qa/support). Load to spawn a specialist, list templates, import one into a project, create a template, or hide/restore a bundled default. Triggers: 'spawn agent', 'use Cody/Rocky/Tessa', 'list agents', 'agent vault', 'import agent', 'new agent'."
+description: "APX agent vault — reusable templates (Roby, Cody, Rocky, Tessa, Max, Arch, Sid, Vera, Finn + generic dev/marketing/ops/qa/support). Spawn a specialist, list, import into a project, create, or hide/restore a bundled default. Triggers: 'spawn agent', 'use Cody/Rocky/Tessa', 'list agents', 'agent vault', 'import agent', 'new agent'."
 ---
 
 # 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:
+Global, project-agnostic library of agent templates. Two layers, deduped per-slug, user wins:
 
 | 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. |
+| **Bundled** | `<repo>/assets/agent-vault-defaults/<slug>.md` | Read-only. Visible unless tombstoned. |
+| **User** | `~/.apx/agents/<slug>.md` | Read-write. Overrides bundled with same slug. |
+| **Tombstones** | `~/.apx/agents/.removed.json` | Bundled slugs the user 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.
+Listing returns `bundled ∪ user`, with `source: "bundled" | "user" | "user-override"`. Editing a bundled entry is **copy-on-write** (materializes into user layer on save). Deleting bundled **tombstones** (restorable); deleting user-only removes the file.
 
-## Bundled starter pack
-
-APX ships 14 templates out of the box, two families:
+## Bundled starter pack (14 templates)
 
 ### Named team (from nicho-apps)
-A characterful crew already used in production by NichoApps:
 
 | Slug | Role | Strength |
 |---|---|---|
@@ -35,28 +32,19 @@ A characterful crew already used in production by NichoApps:
 | `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 |
+`development`, `marketing`, `ops`, `qa`, `support` — plain functional roles without a persona.
 
-Bundled templates ship with `language: es` and **no `model:` set** — they inherit the project/global default model. Set a model on import or by editing the vault file directly.
+Bundled templates ship with `language: es` and **no `model:`** — they inherit the project/global default. Set a model on import or by editing the vault file.
 
-## Concrete commands
+## Commands
 
 ```bash
-# List the vault (bundled + your overrides, with [bundled] / [user] / [override] tags)
+# List (bundled + overrides, tagged [bundled]/[user]/[override])
 apx agent vault list
+apx agent vault list --all              # include tombstoned
 
-# Include tombstoned bundled defaults (the ones you hid)
-apx agent vault list --all
-
-# Create a new template (writes ~/.apx/agents/<slug>.md)
+# Create (writes ~/.apx/agents/<slug>.md)
 apx agent vault add reviewer \
   --role "Code reviewer" \
   --model ollama:llama3.2:3b \
@@ -64,36 +52,32 @@ apx agent vault add reviewer \
   --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
+# Delete: user-only → physical delete; bundled → tombstone
 apx agent vault rm tessa-qa
+apx agent vault restore tessa-qa        # un-tombstone
 
-# Bring back a tombstoned bundled default
-apx agent vault restore tessa-qa
-
-# Import a vault template into the current project
+# Import into 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
+apx agent import tessa-qa --copy        # copy into .apc/agents/ for local edits
+apx agent import roby-orchestrator --force
 
-# Inside the daemon's tool API, the same flow:
+# Daemon tool API equivalents:
 list_vault_agents()
 import_agent({ slug: "cody-developer", project: "<name-or-path>" })
 ```
 
-## The web equivalents
+## Web equivalents
 
-The Agent defaults tab (`/p/0/agent-defaults`) has the same CRUD: a "New" button (POST `/agents/vault`), "Edit" per card (PATCH `/agents/vault/:slug`, copy-on-write for bundled), "Delete"/"Hide" (DELETE), and a "Show removed" toggle that surfaces tombstoned bundled defaults with a "Restore" button.
+Agent defaults tab (`/p/0/agent-defaults`): same CRUD — "New" (POST `/agents/vault`), per-card "Edit" (PATCH `/agents/vault/:slug`, copy-on-write for bundled), "Delete"/"Hide" (DELETE), "Show removed" toggle with "Restore" button.
 
-## When to use which agent
+## Which agent to use
 
-- **User says "spawn/use 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.
-- **Fresh install** → bundled defaults are always present (no sync step); they appear in `apx agent vault list` immediately.
+- 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.
+- **Fresh install** → bundled defaults are always present (no sync step); appear in `apx agent vault list` immediately.
 
-## Where the files live
+## File locations
 
 ```
 <APX repo>/assets/agent-vault-defaults/<slug>.md   ← canonical bundle (committed)
@@ -101,7 +85,7 @@ The Agent defaults tab (`/p/0/agent-defaults`) has the same CRUD: a "New" button
 <project>/.apc/agents/<slug>.md                    ← project-local copy (after import --copy)
 ```
 
-The vault file format is identical to a project agent file:
+Vault format = project agent format:
 
 ```
 ---
@@ -114,28 +98,28 @@ tools: x, y
 is_master: false
 ---
 
-<markdown body — the agent's system prompt extension>
+<markdown body — system prompt extension>
 ```
 
 ## Frontmatter fields the runtime reads
 
 | Field | Effect |
 |---|---|
-| `role` | Shown in CLI/web. Appears in the agent's prompt as "Role: …". |
+| `role` | Shown in CLI/web; appears as "Role: …" in prompt. |
 | `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). |
+| `description` | Shown in `/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. |
+| `is_master` | If true, marked master in 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.
+- **[apx-agent](../apx-agent/SKILL.md)** — per-project agent CRUD. Vault = library; this = workshop.
+- **[apx-runtime](../apx-runtime/SKILL.md)** — delegating to external coding CLIs 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.
+- **Bundled defaults are always present** — no sync step. Removing tombstones; editing copies to user layer.
+- Slug is `roby-orchestrator`, **not** `roby` — the APX super-agent persona is "Roby" via `~/.apx/identity.json`. A project agent called `roby` would shadow it.
+- The `agency-agents` skill in `~/.claude/skills/` pulls from `msitarzewski/agency-agents` on GitHub. APX bundles a snapshot in `assets/agent-vault-defaults/` so installs are offline-first. To refresh upstream, edit the bundle and re-commit; user overrides are untouched.

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

@@ -1,19 +1,19 @@
 ---
 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.
+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'.
 ---
 
 # 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 (memory, conversations, sessions) lives under `~/.apx/projects/<apx_id>/agents/<slug>/` and is never committed. APX still reads legacy `.apc/agents/<slug>/memory.md` as a migration fallback only.
+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.
 
 ## Concrete CLI calls
 
 ```bash
-# List agents in the current project (agent commands are cwd-scoped — run from the project root)
+# List (agent commands are cwd-scoped — run from project root)
 apx agent list
 
-# Create a new agent (writes .apc/agents/<slug>.md, creates runtime dir, regenerates AGENTS.md)
+# Create (writes .apc/agents/<slug>.md, creates runtime dir, regenerates AGENTS.md)
 apx agent add reviewer \
   --role "Code reviewer" \
   --model ollama:llama3.2:3b \
@@ -22,7 +22,7 @@ apx agent add reviewer \
   --tools read,write,run \
   --skills code-review,git
 
-# Import an agent template from the global vault (~/.apx/agents/)
+# Import from 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
@@ -31,70 +31,67 @@ 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; cwd-scoped — run from the project root)
+# Per-agent memory (drives system prompt; cwd-scoped)
 apx memory <slug>                          # read
-apx memory <slug> --append "fact"          # append a line under "## Recent context"
+apx memory <slug> --append "fact"          # append under "## Recent context"
 apx memory <slug> --replace < file.md      # full replace from stdin
 ```
 
-## What the agent's system prompt looks like
+## Agent system prompt composition
 
 `buildAgentSystem()` (`src/core/agent-system.js`) composes:
 
-1. Identity block: `You are <slug>` + project name.
+1. Identity: `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: `~/.apx/projects/<apx_id>/agents/<slug>/memory.md` if it exists, with legacy `.apc/agents/<slug>/memory.md` as a migration fallback.
-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).
+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).
 
-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.
+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.
 
-## Models per agent
+## Per-agent models
 
-Each agent can set `Model:` in its `.apc/agents/<slug>.md` definition to override the global super-agent model. Leave it empty when the agent should follow the project/global default.
+Set `Model:` in `.apc/agents/<slug>.md` to override the global super-agent model. Leave empty to follow project/global default.
 
 ```markdown
 # .apc/agents/reviewer.md
 ---
 Role: Code reviewer
-Model: ollama:llama3.2:3b    ← this agent uses this model, independent of super_agent.model
+Model: ollama:llama3.2:3b    ← independent of super_agent.model
 Language: es
 ---
 ```
 
-When a routine `kind: exec_agent` runs with `spec.agent: reviewer`, it uses that model.
+A routine `kind: exec_agent` with `spec.agent: reviewer` uses that model.
 
 ## Anti-examples
 
 ```bash
-# DON'T hand-write .apc/agents/<slug>.md without matching AGENTS.md regeneration.
+# DON'T hand-write .apc/agents/<slug>.md without regenerating AGENTS.md.
 echo "..." > /path/.apc/agents/reviewer.md
-# ↑ Prefer `apx agent add` or `apx agent import` so AGENTS.md stays consistent.
+# ↑ Use `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.
+# 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.
 ```
 
-## How agents differ from the super-agent
+## Super-agent vs project agent
 
 | Aspect | Super-agent (default APX) | Project agent |
 |---|---|---|
-| Has tools? | Yes (the full registry) | No (text-in/text-out via callEngine) |
+| Has tools? | Yes (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` |
+| Conversation 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.
+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. If you want tools, use the super-agent or call MCPs from a routine `kind: shell`.
+- 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 use the same slug across projects expecting shared memory. Memory is per-project.