@agentprojectcontext/apx 1.33.1 → 1.35.0

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

@@ -0,0 +1,159 @@
+---
+name: apc-context
+description: "ALWAYS activate when the project has a .apc/ directory or AGENTS.md file. Do not wait to be asked. Read .apc/ before making any assumption about agents, memory, or project structure. Activate on: .apc/, AGENTS.md, 'which agents', 'list agents', 'agent context', 'who are the agents', any question about agents or memory in this project. IMPORTANT: if .apc/migrate.md exists, open the conversation with a migration offer before answering anything else. If the user declines, delete .apc/migrate.md immediately so it is not shown again."
+homepage: https://github.com/agentprojectcontext/agentprojectcontext
+---
+
+# Agent Project Context
+
+This project uses APC. APC stores portable project context in `.apc/` and `AGENTS.md`.
+
+APC does not store raw runtime sessions. Sessions, conversations, messages, caches, provider
+threads, and private runtime memory stay in the IDE, CLI, daemon, or user-level store that created
+them.
+
+## FIRST: check for pending migration
+
+Before doing anything else, check if `.apc/migrate.md` exists:
+
+```bash
+cat .apc/migrate.md 2>/dev/null
+```
+
+If it exists, open with this offer before answering anything else:
+
+> I see this project was initialized with Agent Project Context (APC).
+>
+> I found context files that may need migration:
+> [list files from .apc/migrate.md]
+>
+> I can read them, separate durable project context from runtime/private state, and migrate only
+> what belongs in APC.
+>
+> Want me to start?
+
+If the user says no or later, delete `.apc/migrate.md` so the offer is not repeated.
+
+## Migration rule: think, do not copy
+
+Read detected files first. Also read `AGENTS.md` if it exists.
+
+Classify content:
+
+| Content | Action |
+|---|---|
+| 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 |
+| 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 |
+| IDE UI settings or personal aliases | Leave in IDE/user config |
+| Instructions to store sessions under `.apc/` | Drop as obsolete |
+
+After migration:
+
+1. Update `AGENTS.md` as the root project contract.
+2. Create or update `.apc/agents/`, `.apc/skills/`, `.apc/mcps.json` as needed.
+3. Do not create `.apc/**/sessions`, `.apc/messages`, or `.apc/conversations`.
+4. Delete obsolete source files only when their useful project context was migrated or intentionally dropped.
+5. Delete `.apc/migrate.md`.
+6. Summarize what moved, what stayed local, and what was dropped.
+
+## APC structure
+
+```text
+AGENTS.md                        ← root project contract
+.apc/
+  project.json                   ← project metadata
+  .gitignore                     ← safety guard
+  agents/<name>.md               ← agent definition
+  agents/<name>/memory.md        ← optional curated project memory
+  skills/<name>.md               ← reusable project instructions
+  mcps.json                      ← MCP hints without secrets
+```
+
+Do not store:
+
+```text
+.apc/agents/<name>/sessions/
+.apc/sessions/
+.apc/conversations/
+.apc/messages/
+.apc/cache/
+.apc/tmp/
+.apc/private/
+.apc/secrets/
+```
+
+## Visibility rules
+
+| Data | Visibility | Commit? |
+|---|---|---|
+| Agent definitions, skills, project rules | `stable` / `project` | Yes |
+| Curated safe `memory.md` | `project` | Yes, if team-safe |
+| MCP hints without secrets | `project` | Yes |
+| Sessions, conversations, messages | `local` | No; runtime-owned |
+| Secrets, tokens, `*.secret.json`, `*.env` | `private` | Never |
+| Caches, temp files, databases | `ephemeral` | No |
+
+## Operating rules
+
+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.
+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.
+7. Treat `.apc/mcps.json` as MCP configuration hints, not as an MCP implementation.
+
+## Normalization
+
+If agent formats are broken or use legacy fields (role, skills in YAML), offer to normalize:
+
+```yaml
+---
+name: agent-name
+model: inherit
+description: Semantic activation trigger
+---
+```
+
+Identify and fix inconsistencies in `model` (use technical IDs or `inherit`) and ensure `description` is present for semantic activation.
+
+## Sessions
+
+Sessions belong to the runtime that created them.
+
+Examples:
+
+```text
+Codex runtime storage
+Claude Code runtime storage
+OpenCode runtime storage
+~/.apx/projects/<project-id>/agents/<name>/sessions/
+```
+
+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.
+
+## APX
+
+Read `.apc/project.json` if present. It may contain an `apx` field:
+
+- `"installed"`: APX is available; use `apx` commands when useful.
+- `"declined"`: user chose not to install; do not suggest or run APX.
+- missing or `null`: unknown; do not assume APX is available.
+
+If APX is installed, it may manage runtime state outside the repository:
+
+```text
+~/.apx/projects/<project-id>/
+```
+
+APX can provide a local daemon, MCP management, Telegram bridge, routines, and runtime dispatch
+across Codex, Claude Code, OpenCode, Aider, or direct LLM engines. Those are APX runtime features,
+not APC portable-core requirements.
+
+Never use APX to write secrets or raw sessions into `.apc/`.

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

@@ -0,0 +1,83 @@
+---
+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'."
+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. 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.
+
+## When to use APX (vs. native subagent)
+
+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
+
+| Topic | Sub-skill | When |
+|-------|-----------|------|
+| 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 |
+| 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** | 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
+
+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
+
+When you want APX to capture a structured value from an agent (any runtime), instruct the agent to print on its last meaningful line:
+
+```
+APC_RESULT: <one-line value>
+```
+
+APX's `extractApfResult()` parses that and stores it as the session's `result` field. Useful for automation, routines, CI.
+
+### Tool permissions
+
+```bash
+apx permission show
+apx permission set automatico   # total | automatico | permiso
+```
+
+`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. No raw transcripts or secrets.
+
+```bash
+apx memory <slug>                       # read agent's memory.md
+apx memory <slug> --append "<fact>"     # append durable note
+apx memory <slug> --replace < file.md   # replace entire memory from stdin
+```
+
+### Observe activity
+
+```bash
+apx messages tail                               # last 50 messages, all channels
+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 (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

@@ -0,0 +1,125 @@
+---
+name: apx-agency-agents
+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
+
+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. 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"`. 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 (14 templates)
+
+### Named team (from nicho-apps)
+
+| 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)
+
+`development`, `marketing`, `ops`, `qa`, `support` — plain functional roles without a persona.
+
+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.
+
+## Commands
+
+```bash
+# List (bundled + overrides, tagged [bundled]/[user]/[override])
+apx agent vault list
+apx agent vault list --all              # include tombstoned
+
+# Create (writes ~/.apx/agents/<slug>.md)
+apx agent vault add reviewer \
+  --role "Code reviewer" \
+  --model ollama:llama3.2:3b \
+  --language es \
+  --skills code-review,git \
+  --description "Reviews PRs and pushes back on hand-wavy diffs."
+
+# Delete: user-only → physical delete; bundled → tombstone
+apx agent vault rm tessa-qa
+apx agent vault restore tessa-qa        # un-tombstone
+
+# 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
+
+# Daemon tool API equivalents:
+list_vault_agents()
+import_agent({ slug: "cody-developer", project: "<name-or-path>" })
+```
+
+## Web equivalents
+
+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.
+
+## Which agent to use
+
+- 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.
+
+## File locations
+
+```
+<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)
+```
+
+Vault format = project agent format:
+
+```
+---
+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 — system prompt extension>
+```
+
+## Frontmatter fields the runtime reads
+
+| Field | Effect |
+|---|---|
+| `role` | Shown in CLI/web; appears as "Role: …" in prompt. |
+| `model` | Default model for engine routing. |
+| `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. 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** — 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

@@ -0,0 +1,97 @@
+---
+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'.
+---
+
+# 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.
+
+## Concrete CLI calls
+
+```bash
+# 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)
+apx agent add reviewer \
+  --role "Code reviewer" \
+  --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
+
+# 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
+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; cwd-scoped)
+apx memory <slug>                          # read
+apx memory <slug> --append "fact"          # append under "## Recent context"
+apx memory <slug> --replace < file.md      # full replace from stdin
+```
+
+## Agent system prompt composition
+
+`buildAgentSystem()` (`src/core/agent-system.js`) composes:
+
+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.
+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 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.
+
+## Per-agent models
+
+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    ← independent of super_agent.model
+Language: es
+---
+```
+
+A routine `kind: exec_agent` with `spec.agent: reviewer` uses that model.
+
+## Anti-examples
+
+```bash
+# DON'T hand-write .apc/agents/<slug>.md without regenerating AGENTS.md.
+echo "..." > /path/.apc/agents/reviewer.md
+# ↑ Use `apx agent add` or `apx agent import` so AGENTS.md stays consistent.
+
+# 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.
+```
+
+## Super-agent vs project agent
+
+| 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 |
+| 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 |
+
+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 use the same slug across projects expecting shared memory. Memory is per-project.

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

@@ -0,0 +1,111 @@
+---
+name: apx-mcp
+description: Register, list, debug, scope MCP servers in APX. Load BEFORE adding any MCP — three scopes (shared/runtime/global) with different commit and secrecy semantics. Triggers: 'add MCP', 'apx mcp', 'MCP scope', 'MCP failing', 'list MCPs'.
+---
+
+# apx-mcp
+
+APX exposes MCP servers via three scopes; resolution priority **runtime > shared > global**, conflicts via `apx mcp check`:
+
+| Scope | File | Committed? | Secrets OK? | When |
+|---|---|---|---|---|
+| `shared` | `<repo>/.apc/mcps.json` | yes | **no** | Team-wide (filesystem, brave, github public) |
+| `runtime` | `~/.apx/projects/<apxId>/mcps.json` (chmod 0600) | no | yes | Per-project — tokens, machine-specific endpoints |
+| `global` | `~/.apx/mcps.json` | n/a | yes | Machine-wide, not tied to a project |
+
+## Concrete CLI calls
+
+```bash
+# List (defaults to all scopes)
+apx mcp list --project iacrmar
+apx mcp list --scope runtime --project iacrmar
+apx mcp list --scope shared  --project iacrmar
+apx mcp list --scope global
+
+# Inspect sources and conflicts
+apx mcp check --project iacrmar
+
+# Add — shared (commit to repo)
+apx mcp add filesystem --command npx --project iacrmar \
+  -- -y @modelcontextprotocol/server-filesystem .
+
+# Add — runtime (per-project, local, secrets safe)
+apx mcp add github --scope runtime --project iacrmar \
+  --command npx --env GITHUB_TOKEN=ghp_xxx \
+  -- -y @modelcontextprotocol/server-github
+
+# Add — global (machine-wide)
+apx mcp add brave --scope global \
+  --command npx --env BRAVE_API_KEY=BSAxxx \
+  -- -y @modelcontextprotocol/server-brave-search
+
+# Remove (pass --scope when not in default: shared inside APC project, else global)
+apx mcp remove filesystem --project iacrmar
+apx mcp remove github     --scope runtime --project iacrmar
+
+# Toggle (defaults to owning scope)
+apx mcp enable  filesystem --project iacrmar
+apx mcp disable filesystem --project iacrmar
+
+# Call a tool through the daemon (debugging)
+apx mcp run filesystem read_file '{"path":"README.md"}'
+```
+
+## Scope decision tree
+
+1. **Has secrets/tokens?** → `runtime`. Always.
+2. **Part of project's shared dev environment?** → `shared` (committed).
+3. **Used across all your projects?** → `global`.
+
+Default if unclear: `shared` inside an APC project, `global` outside.
+
+## Command shapes by transport
+
+```bash
+# stdio MCP (most common — npx, uvx, node, python)
+apx mcp add <name> --command npx -- -y <package-or-flag-list>
+apx mcp add <name> --command uvx -- <python-cli-name>
+apx mcp add <name> --command python -- /abs/path/to/server.py
+
+# Env vars (one --env per var)
+apx mcp add <name> --command npx \
+  --env GITHUB_TOKEN=ghp_xxx \
+  --env GITHUB_OWNER=manuel \
+  -- -y @modelcontextprotocol/server-github
+```
+
+Everything after `--` is forwarded verbatim as args. Quote carefully.
+
+## Anti-examples
+
+```bash
+# DON'T put tokens in shared scope — it commits.
+apx mcp add github --scope shared --env GITHUB_TOKEN=ghp_xxx ...
+# ↑ Token ends up in .apc/mcps.json in your repo. Use --scope runtime.
+
+# DON'T remove from the wrong scope — daemon returns 409 with the right scope.
+apx mcp remove github          # errors if github lives in runtime
+
+# DON'T expect IDE-foreign configs (~/.cursor/mcps.json, ~/.claude/mcps.json)
+# to be removable via apx mcp remove. APX reads them advisory (source=cursor/claude)
+# but won't write them. Edit the IDE config directly.
+```
+
+## Debugging
+
+```bash
+apx mcp check --project iacrmar      # scopes seen + which files exist
+apx mcp run <name> <tool> '{...}'    # spawn server, call a tool
+apx log -f                           # tail unified log for spawn errors
+```
+
+"Doesn't show tools" = command failed to start (missing env vars, package not found) or crashed during initialize. Unified log holds the stderr buffer.
+
+> `apx mcp tools <name>` is a placeholder stub ("coming in v0.2"). Use `apx mcp run` to verify spawn.
+
+## Don't
+
+- Don't mix scopes for the same MCP name unless you want shadowing — highest priority wins, others stay invisible.
+- Don't edit `~/.apx/projects/<id>/mcps.json` by hand; use `apx mcp add --scope runtime` (the file is chmod 0600 — CLI preserves it).
+- Don't put tokens via `--env KEY=` inline if shell history is public. Set them in your shell first, then `--env KEY=$KEY`.
+- Don't forget to `apx daemon reload` after hand-editing JSON. `apx mcp` does this for you.