@agentprojectcontext/apx 1.80.2 → 1.89.1

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

@@ -0,0 +1,134 @@
+---
+name: apx-commitment
+description: Promises made to a named person — counterparty, the date you gave them, the channel you said it on. Sibling of apx-task, deliberately NOT the same thing. Load whenever someone else is waiting on something. Triggers: 'I told X I would…', 'le dije a X que…', 'I promised…', 'quedé en…', 'me comprometí a…', 'what do I owe X', 'qué le debo a X', 'overdue promises', 'mark it kept', 'push the date'.
+---
+
+# apx-commitment
+
+A `task` is something to do. A `commitment` is something **promised to a specific person**: it has a counterparty, a date you gave them, and the channel you said it on. Breaking one costs trust, not throughput.
+
+Append-only JSONL per month at `~/.apx/projects/<apxId>/commitments/YYYY-MM.jsonl`, folded the same way as tasks. No event is ever removed from the log — `drop` hides a row that was filed by mistake, it does not erase its history.
+
+## When it is a commitment and not a task
+
+The test is one question: **is a named person waiting?**
+
+| What was said | Which | Why |
+|---|---|---|
+| "I have to send the quote" | task | Nobody is named. |
+| "I told Ana I'd send her the quote Friday" | commitment | Ana is waiting, and Friday is a date you gave her. |
+| "we should refactor the parser" | task | Internal work. |
+| "I promised the client a demo next week" | commitment | The client will notice if it slips. |
+| "remind me to review the PR" | task | A reminder to yourself. |
+| "I said I'd get back to Bruno today" | commitment | Bruno is expecting it. |
+
+Undated is still a commitment. "I promised Ana the quote, no date yet" → record it with no `due`. Refusing to record it because a date is missing means the promise goes unrecorded, which is strictly worse.
+
+## Catching them in conversation
+
+This is the main way they get recorded — nobody opens a form to log a promise. Listen for a name plus an obligation, in either language:
+
+- "le dije a Ana que el viernes le mando el presupuesto"
+- "quedé en pasarle el informe a Bruno"
+- "me comprometí con el cliente a tener la demo el 10"
+- "I told the team I'd have the migration plan by Thursday"
+
+Record it and say in ONE line what you filed and for whom. Do not ask permission to record something you clearly heard — asking makes recording cost more than not recording, and then nothing gets recorded.
+
+Resolve a loose date to a real one ("Friday" → that date) and say which date you used, so a wrong guess is visible and correctable.
+
+## Super-agent tools
+
+`record_commitment` and `list_commitments` are in the base set — a promise is caught mid-sentence, so they are always loaded. **`mark_commitment`** (kept | missed | drop | renegotiate) closes one out with a tool, no shelling to `apx commitment kept`.
+
+```json
+{ "name": "record_commitment",
+  "arguments": { "project": "acme", "counterparty": "Ana",
+                 "body": "send the revised quote", "due": "2026-05-30",
+                 "origin_channel": "telegram" } }
+```
+
+`list_commitments` searches **every project** unless you pass one. Omit `project` for "what do I owe people" — that question does not respect a repo boundary.
+
+```json
+{ "name": "list_commitments", "arguments": { "overdue": true } }
+{ "name": "list_commitments", "arguments": { "counterparty": "ana" } }
+```
+
+Counterparty matching is case-insensitive substring, so `"ana"` finds "Ana Pérez". It is free text, not a contact record — write the name the way the owner says it.
+
+## Concrete CLI calls
+
+```bash
+# Record
+apx commitment add "send the revised quote" --to "Ana" --due 2026-05-30 --project acme
+apx commitment add "the deck for the board" --to "Bruno" --project acme   # no date yet
+
+# Read
+apx commitment list --all                      # every project, soonest deadline first
+apx commitment list --all --overdue            # what you owe and already missed
+apx commitment list --to Ana --state all       # everything ever promised to her
+apx commitment show c_abc123 --project acme
+
+# Close it out
+apx commitment kept   c_abc123 --project acme
+apx commitment missed c_abc123 --project acme --note "forgot entirely"
+apx commitment renegotiate c_abc123 --due 2026-06-15 --project acme --note "agreed on the call"
+
+# Filed by mistake — not a broken promise
+apx commitment drop c_abc123 --project acme --note "this was a task, not a promise"
+```
+
+## The ways one ends
+
+| Verb | Means | State after |
+|---|---|---|
+| `kept` | Delivered. | `kept` |
+| `missed` | The date passed and it did not happen. | `missed` |
+| `drop` | Filed by mistake — nobody was ever waiting. | `dropped` |
+| `renegotiate` | A NEW date, agreed with them. | back to `open` |
+
+**`drop` is not a polite `missed`.** Reach for it only when the row should not
+have existed (a task recorded as a promise, a duplicate). Using it on something
+a person actually expected launders a broken promise into a clerical error, and
+the overdue count — the only number here that means anything — stops being true.
+
+**`renegotiate` reopens rather than closing.** A promise with a new date is a live promise, and every date it has ever had stays in `history`. Moving a date twice is a fact about the relationship; it is only visible because the log keeps it.
+
+**`missed` records, it does not hide.** A system that quietly drops what you failed to do cannot tell you that you keep failing the same person.
+
+Never mark `kept` on the owner's behalf. If a commitment came due, ASK whether it was kept — you cannot see whether the email was sent.
+
+## Where they show up on their own
+
+- **The morning anchor leads with them.** Overdue promises go first, named as a promise to a person, never folded into the task list.
+- **`overdue_commitment` is a CRITICAL signal** (`core/routines/signals.js`), the only detector at that severity. It is the one thing allowed to cross a spent interruption budget.
+- **`commitment_due` fires inside the lead window** (default 48h) — a warning that arrives in time is worth more than one that arrives after.
+
+## ID format
+
+`c_` + 6 base36 chars. Prefix matching at ≥3 chars when unique, same as tasks.
+
+## Endpoint surface
+
+```
+GET    /api/commitments                                   cross-project; ?state=open|kept|missed|all
+                                                          &counterparty=X&overdue=1&due_before=ISO
+                                                          &sort=due|newest&limit=N&offset=N
+GET    /api/projects/:pid/commitments                     same filters, one project
+POST   /api/projects/:pid/commitments                     { counterparty, body, due?, origin_channel?, … }
+GET    /api/projects/:pid/commitments/:id
+PATCH  /api/projects/:pid/commitments/:id                 { patch: {...} }
+POST   /api/projects/:pid/commitments/:id/kept            { note? }
+POST   /api/projects/:pid/commitments/:id/missed          { note? }
+POST   /api/projects/:pid/commitments/:id/drop            { note? }   filed by mistake
+POST   /api/projects/:pid/commitments/:id/renegotiate     { due, note? }
+GET    /api/projects/:pid/commitments-summary             → { open, kept, missed, dropped, overdue, total }
+```
+
+## Don't
+
+- **Don't record a task as a commitment to make it feel urgent.** The whole value is that a commitment means someone is waiting. Inflate the type and the morning anchor becomes noise.
+- **Don't use tags on tasks for this.** It was considered and rejected: the day you want "everything I owe Ana" you would be substring-matching titles, and `kept` vs `renegotiated` — the distinction that tells you whether a relationship is fine — has nowhere to live.
+- **Don't invent a counterparty.** If you genuinely cannot tell who is waiting, it is a task.
+- **Don't renegotiate without a date.** The CLI refuses it: a promise with no new date is a promise that vanished.

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

@@ -0,0 +1,60 @@
+---
+name: apx-image
+scope: optional
+description: Generate images from a text prompt with `apx image`, routed to a local, LAN, or cloud diffusion server. Load when asked to draw, render, illustrate, or make a picture, logo sketch, thumbnail, or cover; to pick between image engines; to set image size, steps, guidance, seed, or a negative prompt; or when an image engine is unreachable or ignoring options.
+---
+
+# apx-image
+
+`apx image` turns a prompt into a file. It is a thin CLI over the daemon's `POST /api/images/generate`, which routes to whichever engine is configured and reachable — so the same command works against a diffusion server on this machine, a box on the network, or a cloud key, without the caller knowing which.
+
+## Usage
+
+```bash
+apx image "a green origami fox on a white background"
+apx image "portrait of a fox" --size 768x512 --steps 8 --cfg 1.0 --out fox.png
+apx image "a logo sketch" --provider a1111 --seed 123 --json
+apx image "cover art" --negative "text, watermark" --count 2 --open
+apx image providers                      # what is configured and reachable
+apx image capabilities --provider sdcpp  # models, samplers, schedulers
+```
+
+Without `--out`, the file lands in `~/.apx/images/<date>/` and the path is printed on stdout. **Nothing is written into a project checkout unless `--out` says so.**
+
+## Engines
+
+| id | Dialect | Notes |
+|---|---|---|
+| `a1111` | `POST /sdapi/v1/txt2img`, synchronous | The universal one: AUTOMATIC1111, Forge, SD.Next, Draw Things on macOS, stable-diffusion.cpp. Carries every sampling knob. |
+| `sdcpp` | `POST /sdcpp/v1/img_gen` + job polling | stable-diffusion.cpp's native queue. The socket closes immediately and the job is polled, so a queued render never looks like a hung request. One checkpoint per server. |
+| `openai` | `POST /v1/images/generations` | Cloud (`gpt-image-1` / `dall-e-3`), or any OpenAI-compatible server when `base_url` is set. |
+| `mock` | none | Offline test engine, always last and always available. |
+
+Add any number of extra endpoints under `images.custom.<slug>`, each naming the dialect it speaks in `kind`. They surface as `custom:<slug>`.
+
+## Routing
+
+Engines are tried in `images.order` and the first reachable one draws — the same chain/single model as TTS. Set `images.mode` to `single` plus `images.provider` to pin one. `--provider` overrides the routing for one call. A configured but unreachable server is skipped rather than failing the call.
+
+```bash
+apx config set --global images.a1111.base_url http://127.0.0.1:7860
+apx config set --global images.a1111.defaults '{"steps":8,"cfg_scale":1}'
+```
+
+Settings live in `~/.apx/config.json` under `images.*`, and the same settings have a screen at **Settings → Images** in the web panel.
+
+## Options resolve in four layers
+
+`images.defaults` → `images.<engine>.defaults` → the call. Later wins. Steps and guidance belong to the **engine**, not to the prompt: a turbo checkpoint wants about 8 steps at cfg 1, a standard one 20 at cfg 7, and putting that in the engine's block means no caller has to remember it.
+
+## Not every engine honors every option
+
+The OpenAI dialect has no steps, guidance, sampler, scheduler, seed or negative prompt. stable-diffusion.cpp hosts one checkpoint and cannot switch models. Whatever an engine cannot honor is **reported** after the run (`ignored` in `--json`) instead of being silently dropped — so a picture that came out wrong can be traced to the dialect rather than the prompt.
+
+## Don't
+
+- Don't call a diffusion server directly with `curl` when an engine is configured — routing, defaults, the seed report and the ignored-options report all live behind `apx image`, and a raw call has none of them.
+- Don't reach for Ollama: it serves language and vision models and cannot generate images at all. On macOS point the `a1111` engine at Draw Things' HTTP API, or any local A1111-compatible server, instead.
+- Don't set steps or guidance in `images.defaults` when several engines are configured — they belong to `images.<engine>.defaults`, because the right value depends on the checkpoint that server loaded.
+- Don't ask the `openai` engine for a negative prompt or a fixed seed and assume it took: check `ignored`.
+- Don't write generated images into a repository by default — leave them in `~/.apx/images/` and pass `--out` only when a file is genuinely wanted on disk somewhere.

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

@@ -0,0 +1,82 @@
+---
+name: apx-integrations
+description: "APX connectors (integrations/plugins) — Asana, Google Calendar, GitHub, Obsidian, WhatsApp. Load when a connector tool says \"not connected\" / \"read-only\" / \"not authorized\", or the user wants to connect/configure/check a plugin. NOT the same as MCP servers (apx-mcp) or the Telegram channel (apx-telegram). Triggers: 'connect Asana/Calendar/GitHub', 'why can't you see my calendar', 'integration not connected', 'plugins tab', 'read-only calendar'."
+---
+
+# apx-integrations
+
+A **connector** (a.k.a. integration / plugin) is a stored, per-project connection to an external service — Asana, Google Calendar, GitHub, Obsidian. It gives the agent's tools live access to that service. It is a **different mechanism** from an MCP server (`apx-mcp`) and from the Telegram channel (`apx-telegram`, a channel, not a plugin).
+
+Catalog source of truth: `src/core/integrations/catalog.js`. Adding a plugin = drop a module in `plugins/` + register it in `PLUGIN_SERVICES` — no route changes.
+
+## The catalog
+
+| slug | name | auth | State |
+|---|---|---|---|
+| `asana` | Asana | token (PAT) | ✅ implemented |
+| `calendar` | Google Calendar | **user OAuth** | ✅ implemented |
+| `github` | GitHub | token | ✅ implemented |
+| `obsidian` | Obsidian | path (local Vault) | ✅ implemented — has a CLI |
+| `whatsapp` | WhatsApp | QR pairing | ⏳ `coming_soon` — do not attempt to connect |
+
+## The one rule: connecting happens OUT OF BAND
+
+**The agent cannot connect a plugin itself.** It cannot paste a token, pick a Vault folder, or complete an OAuth consent screen. Connection is done by the user in the **web panel → Integrations → Plugins** (the generic `PluginConnect` form). Your job is to *guide the user there and then re-check*, never to invent a connect command.
+
+- The **only** connector with a CLI is Obsidian: `apx obsidian …` (a thin client over the same daemon routes — configure/validate/status/sync/remove).
+- There is **no** `apx integrations` / `apx plugins connect` command. ⚠️ `apx plugins` is a **different, unrelated** thing (it lists *daemon* plugins at `/api/plugins`) — don't confuse it for connectors.
+
+## Reading the tool errors (this is the main reason you're here)
+
+The connector-backed tools (`calendar_*`, `asana_*`, `github_*`, `obsidian_*`) throw errors written to be relayed verbatim-ish to the user. Recognize them and tell the user the exact next step:
+
+| Error says… | What it means | Tell the user |
+|---|---|---|
+| "…is not connected. Ask the user to connect it in the web panel → Integrations → Plugins → X" | No usable record for this project | Open the panel, connect X. |
+| "The calendar isn't authorized yet." | Configured but no `refresh_token` (OAuth not completed) | Finish the "Connect with Google" step in the panel. |
+| "connected read-only … enable write access" | Calendar `write_access: false` | Toggle write access in the panel, then retry. |
+| "No Asana workspace selected." | Token valid, workspace not chosen | Pick the workspace in the panel. |
+
+Don't retry the tool in a loop against one of these — the fix is a human action in the panel.
+
+## Scope precedence: project → default(global)
+
+`resolveIntegration()` (`src/core/integrations/store.js`) resolves per project: the project's **own** enabled+active record wins; otherwise the **default** project's record is inherited. So a connector configured once on the `default` project works for every project that hasn't overridden it — the same "global = default project" pattern as MCPs (`apx-mcp`). Records live in the per-project integrations store (like tasks); the API redacts secrets in responses.
+
+## Google Calendar specifics (user OAuth, not a service account)
+
+Calendar acts **as the user** (invites + Google Meet), so it uses OAuth, not a key:
+
+1. User creates a Google Cloud OAuth app and enters `client_id` + `client_secret` in the panel.
+2. Panel runs the consent flow (`action: authorize` → Google → redirect back to `/api/integrations/oauth/callback`), which stores a `refresh_token`. APX caches short-lived access tokens from it.
+3. `write_access` toggle (default on) = create/edit events, invites, Meet. Off = read-only. `meet` toggle adds a Meet link on create.
+4. The calendar is always the account's own `primary` — there is nothing to pick.
+
+Tools: `calendar_list_events`, `calendar_find_slot`, `calendar_create_event` (invitees + Meet), `calendar_update_event`. See `plugins/calendar.js` + `plugins/_google-oauth.js`.
+
+## Daemon API (for reference — the panel and `apx obsidian` use these)
+
+```
+GET    /api/projects/:pid/integrations                     # configured, this project (+ scope)
+GET    /api/projects/:pid/integrations/catalog             # what's available
+GET    /api/projects/:pid/integrations/:slug
+POST   /api/projects/:pid/integrations/:slug/configure     # save creds/config
+POST   /api/projects/:pid/integrations/:slug/validate      # verify against the provider, persist result
+POST   /api/projects/:pid/integrations/:slug/action/:action  # plugin action (asana list workspaces, calendar authorize)
+POST   /api/projects/:pid/integrations/:slug/deactivate    # disable, keep creds
+DELETE /api/projects/:pid/integrations/:slug               # remove entirely
+GET    /api/integrations/oauth/callback                    # OAuth redirect target (signed state, no bearer)
+```
+
+`?scope=project|global` selects which store the write lands in.
+
+## Don't
+
+- Don't tell the user to "run a command" to connect a token/OAuth plugin — there's a CLI only for Obsidian. Everything else is the web panel.
+- Don't confuse `apx plugins` (daemon plugins list) with connectors. Different subsystem.
+- Don't treat a connector as an MCP. If the user wants to *register an MCP server*, that's `apx-mcp`.
+- Don't try to connect `whatsapp` — it's `coming_soon` (needs a QR-pairing bridge APX doesn't ship yet).
+  This is the CONNECTOR, not the `whatsapp` **channel**: a phone-side bridge already posts incoming
+  WhatsApp messages to the super-agent with `channel: "whatsapp"`, and that works. Never answer a
+  message that arrived on it with "WhatsApp is not supported yet".
+- Don't retry a tool after a "not connected / read-only / not authorized" error — surface the panel step and stop.

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

@@ -13,24 +13,28 @@ APX exposes MCP servers via three scopes; resolution priority **runtime > shared
 | `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 |
 
+## Super-agent tool
+
+The super-agent registers an MCP with the **`add_mcp`** tool (name + `command`/`args`/`env` for stdio, or `url`/`headers` for http; `scope` = runtime | shared | global, default runtime) — no shelling to `apx mcp add`. Then `list_mcp_tools` to see what it exposes and `call_mcp` to run one. Secrets go in `runtime`/`global` scope, never `shared` (committed).
+
 ## 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 --project acme
+apx mcp list --scope runtime --project acme
+apx mcp list --scope shared  --project acme
 apx mcp list --scope global
 
 # Inspect sources and conflicts
-apx mcp check --project iacrmar
+apx mcp check --project acme
 
 # Add — shared (commit to repo)
-apx mcp add filesystem --command npx --project iacrmar \
+apx mcp add filesystem --command npx --project acme \
   -- -y @modelcontextprotocol/server-filesystem .
 
 # Add — runtime (per-project, local, secrets safe)
-apx mcp add github --scope runtime --project iacrmar \
+apx mcp add github --scope runtime --project acme \
   --command npx --env GITHUB_TOKEN=ghp_xxx \
   -- -y @modelcontextprotocol/server-github
 
@@ -40,12 +44,12 @@ apx mcp add brave --scope global \
   -- -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
+apx mcp remove filesystem --project acme
+apx mcp remove github     --scope runtime --project acme
 
 # Toggle (defaults to owning scope)
-apx mcp enable  filesystem --project iacrmar
-apx mcp disable filesystem --project iacrmar
+apx mcp enable  filesystem --project acme
+apx mcp disable filesystem --project acme
 
 # Discover tools — list catalog, then inspect one tool's schema
 apx mcp tools filesystem                     # table: tool name + description
@@ -66,20 +70,47 @@ Default if unclear: `shared` inside an APC project, `global` outside.
 
 ## Command shapes by transport
 
+Two transports. `--command` = local process (stdio), `--url` = remote endpoint (http).
+There is no third option, and no flag outside this list — if a shape isn't here,
+run `apx help mcp add` instead of guessing.
+
 ```bash
-# stdio MCP (most common — npx, uvx, node, python)
+# stdio MCP — a local process (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)
+# stdio 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
+
+# http MCP — a remote streamable-HTTP endpoint. No command, no npx, no install.
+apx mcp add <name> --url https://mcp.example.com/mcp --scope runtime
+
+# http with auth headers (repeatable; "Name: value" or Name=value both parse)
+apx mcp add <name> --url https://mcp.example.com/mcp --scope runtime \
+  --header "Authorization: Bearer $TOKEN" \
+  --header "X-Workspace: acme"
+```
+
+Everything after `--` is forwarded verbatim as args to a stdio command. Quote carefully.
+`--env` and `--` args are stdio-only; `--header` is http-only — mixing them errors.
+
+Remote servers almost always carry a token, so they belong in `--scope runtime`
+(chmod 0600, never committed). Read the token from the environment rather than
+pasting it: `--header "Authorization: Bearer $TOKEN"`.
+
+## After adding: prove it works
+
+```bash
+apx mcp tools <name>     # spawns/connects and lists tools — this is the real check
+apx mcp logs <name>      # if the above is empty or errors: request/response log
 ```
 
-Everything after `--` is forwarded verbatim as args. Quote carefully.
+`apx mcp add` only writes JSON — it never contacts the server. An MCP that "was
+added fine" but has no tools is a failed connection, not a successful install.
 
 ## Anti-examples
 
@@ -99,7 +130,7 @@ apx mcp remove github          # errors if github lives in runtime
 ## Debugging
 
 ```bash
-apx mcp check --project iacrmar      # scopes seen + which files exist
+apx mcp check --project acme      # scopes seen + which files exist
 apx mcp tools <name>                 # spawn server + list its tools (proves init works)
 apx mcp logs <name>                  # spawn/init event log + stderr tail
 apx mcp run <name> <tool> '{...}'    # call a tool for real

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

@@ -54,7 +54,7 @@ pip install fastmcp
 # or: uv tool install fastmcp
 
 apx mcp add my-server \
-  --command uv --project iacrmar \
+  --command uv --project acme \
   -- run python /abs/path/my_server.py
 ```
 
@@ -106,7 +106,7 @@ await server.connect(new StdioServerTransport());
 
 ```bash
 apx mcp add my-server \
-  --command npx --project iacrmar \
+  --command npx --project acme \
   -- -y my-server-package
 ```
 
@@ -122,7 +122,7 @@ apx mcp add my-server \
 
 ```bash
 apx mcp add github \
-  --scope runtime --project iacrmar \
+  --scope runtime --project acme \
   --command npx \
   --env GITHUB_TOKEN=ghp_xxx \
   --env GITHUB_OWNER=manuel \
@@ -165,7 +165,7 @@ apx mcp logs my-server
 apx log -f
 
 # Scopes / files / env APX sees
-apx mcp check --project iacrmar
+apx mcp check --project acme
 ```
 
 ## Don't

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

@@ -33,11 +33,13 @@ apx profile install secretary         # a bundled id
 apx profile install ./my-profile      # a local package directory
 apx profile use secretary             # activates + installs its routines
 apx profile use tutor --force         # replace whatever is active
+apx profile sync                      # re-read the active package from disk (after an APX update)
 
 # Configure — this is where white-label happens
 apx profile config                                  # show current settings
-apx profile config --set day_open_at="30 8 * * 1-5"
+apx profile config --set day_open_schedule="30 8 * * 1-5"
 apx profile config --set nudge_budget_per_day=3 --set quiet_hours=22:00-07:30
+apx profile config --set watch_schedule="0 */2 * * *" --set formality=vos
 apx profile config --interactive                    # walk the whole schema
 
 # Health and removal
@@ -96,6 +98,25 @@ settings, not core behaviour. If the answer is "it shouldn't have", the fix is u
   `profile_name`) or a schema property **with a default**. A property declared without a
   default is rejected, because it would silently render as an empty string.
 
+**In `routines/*.json`, settings render as VALUES, not as text.** The file is parsed first
+and each string leaf rendered after, so a setting carrying quotes (a shell command with JSON
+arguments, say) cannot break the document. Two consequences worth knowing:
+
+- A `pre_commands` / `post_commands` entry that renders empty is dropped entirely, so an
+  optional command is just a setting defaulting to `""` — no empty shell step, no pre phase.
+- `{{pre_output}}` is left alone by the renderer and filled by the routine runner at run
+  time. That is how a routine hands itself data without spending a tool call or a permission
+  on it — the secretary's `calendar_command` is the live example.
+
+## A package updates, its installed routines do not
+
+The prompt block is rendered every turn, so it improves the moment APX updates. Routines are
+records in the super-agent's store, written at install time — nothing carries a better anchor
+across. `apx profile sync` re-renders them from the package on disk, leaving settings and
+activation alone; `apx profile doctor` reports the drift so it is not silent. A routine the
+owner edited is skipped forever, by design, which also means a profile SETTING that lands in
+a routine stops taking effect on that routine once they have touched it.
+
 ## Channel overlays
 
 `channels/<ch>.md` is rendered and appended after the core `channels/<ch>.md`, only on that
@@ -115,7 +136,11 @@ install. Check the real number with `apx profile show <id>` or
 
 `GET /api/profiles` · `GET /api/profiles/:id` (includes `preview`) · `GET /api/profiles/doctor` ·
 `POST /api/profiles/install` · `POST /api/profiles/use` · `POST /api/profiles/off` ·
-`PATCH /api/profiles/config` · `DELETE /api/profiles/:id`
+`POST /api/profiles/sync` (re-applies a package's routines after an update — `apx profile sync`) ·
+`PATCH /api/profiles/config` · `DELETE /api/profiles/:id` ·
+`POST /api/profiles/readopt` (force the active profile's routines back to the package, past the
+user_modified/user_owned skips sync respects — `{ routine }` targets one, omit for all; the
+web "Re-sync routines" button. It discards local edits to the affected routines.)
 
 ## Gotchas
 

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

@@ -40,7 +40,7 @@ Every `project config` write triggers `POST /api/admin/reload` so the daemon pic
 
 ## `<project>` argument resolution
 
-Accepted: numeric id (`1`), exact name from `.apc/project.json` (`iacrmar`), absolute path, relative path (resolved from cwd). The CLI's `resolveProjectId()` does fuzzy id/name/path matching. If "project not found", run `apx project list` first.
+Accepted: numeric id (`1`), exact name from `.apc/project.json` (`acme`), absolute path, relative path (resolved from cwd). The CLI's `resolveProjectId()` does fuzzy id/name/path matching. If "project not found", run `apx project list` first.
 
 ## What lives where
 
@@ -49,6 +49,7 @@ Accepted: numeric id (`1`), exact name from `.apc/project.json` (`iacrmar`), abs
 ├── AGENTS.md                                   ← agent definitions (committed)
 └── .apc/
     ├── project.json                            ← { apxId, name, ... }
+    ├── memory.md                               ← curated project memory (committed, human-written)
     ├── agents/<slug>.md
     ├── skills/<slug>.md or <slug>/SKILL.md
     ├── mcps.json                               ← shared MCPs (committed)
@@ -56,6 +57,7 @@ Accepted: numeric id (`1`), exact name from `.apc/project.json` (`iacrmar`), abs
     └── config.json                             ← project-only overrides (edited by `project config`)
 
 ~/.apx/projects/<apxId>/                        ← runtime state (never committed)
+├── memory.md                                   ← local project memory (what `remember` writes)
 ├── messages/YYYY-MM-DD.jsonl
 ├── agents/<slug>/{memory.md, sessions/, conversations/}
 ├── routines.json
@@ -64,6 +66,25 @@ Accepted: numeric id (`1`), exact name from `.apc/project.json` (`iacrmar`), abs
 └── mcps.json                                   ← per-project runtime MCPs (local, may hold tokens)
 ```
 
+## Project memory — two files, and you write only one
+
+What the PROJECT knows lives in two places, and the difference is a safety boundary:
+
+| File | Committed? | Written by |
+|---|---|---|
+| `~/.apx/projects/<apxId>/memory.md` | Never | You, with `remember` + `project` |
+| `<repo>/.apc/memory.md` | Yes, git carries it | The owner, by hand, after reading it |
+
+Write with `remember` and a `project` — never by creating a memory file yourself. A `MEMORY.md` at the repo root, or any other name, is read by nothing.
+
+```
+remember(note: "Northwind runs on Postgres in production", project: "northwind")
+```
+
+It lands in the local file on purpose. A note you write automatically can carry something the owner pasted into a chat, and a committed file is forever — APC keeps private runtime memory out of `.apc/`, which is only for curated facts that are safe for the team. If a fact belongs in the repo, say so and let the owner promote it from the Memories screen; do not write `.apc/memory.md` yourself unless they explicitly ask.
+
+Read either with `read_file`. Both are shown in the project's Memories screen and both are indexed for retrieval. For facts that matter on every channel, call `remember` with no `project` — those go to your own notebook.
+
 ## Anti-examples
 
 ```bash
@@ -74,7 +95,7 @@ mkdir -p /path/repo/.apc && echo "{...}" > /path/repo/.apc/project.json
 # Use `apx init <path>` then `apx project add <path>`.
 
 # DON'T set super_agent.model to a model lacking an engine key.
-apx project config set iacrmar super_agent.model gemini:gemini-1.5-pro
+apx project config set acme super_agent.model gemini:gemini-1.5-pro
 # ↑ Fails at first call unless engines.gemini.api_key is set.
 ```