@agentprojectcontext/apx 1.12.0 → 1.13.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentprojectcontext/apx",
-  "version": "1.12.0",
+  "version": "1.13.1",
   "description": "APX — unified CLI + daemon for the Agent Project Context (APC) standard.",
   "publishConfig": {
     "access": "public"

package/skills/apc-context/SKILL.md

@@ -0,0 +1,110 @@
+---
+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/apx
+---
+
+# 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, offer to migrate before answering anything else. Read detected files, separate durable
+project context from runtime/private state, and migrate only what belongs in APC.
+
+If the user says no or later, delete `.apc/migrate.md` so the offer is not repeated.
+
+## Migration rule: think, do not copy
+
+Classify content:
+
+| Content | Action |
+|---|---|
+| Agent definitions: role, model, skills, description | Put in `.apc/agents/<slug>.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/<slug>/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 |
+
+## APC structure
+
+```text
+AGENTS.md                        ← root project contract
+.apc/
+  project.json                   ← project metadata
+  .gitignore                     ← safety guard
+  agents/<slug>.md               ← agent definition
+  agents/<slug>/memory.md        ← optional curated project memory
+  skills/<name>.md               ← reusable project instructions
+  mcps.json                      ← MCP hints without secrets
+```
+
+Do not store:
+
+```text
+.apc/agents/<slug>/sessions/
+.apc/sessions/
+.apc/conversations/
+.apc/messages/
+.apc/project.db
+.apc/cache/
+.apc/tmp/
+.apc/private/
+.apc/secrets/
+```
+
+## Operating rules
+
+1. Read `AGENTS.md` and relevant `.apc/` files before assuming project context.
+2. Read agent definitions from `.apc/agents/<slug>.md` when present.
+3. Read curated project memory from `.apc/agents/<slug>/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.
+
+## 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/<slug>/sessions/
+```
+
+At task end, provide the user a concise result. If project memory should be updated, write a short
+sanitized fact to `.apc/agents/<slug>/memory.md` only when useful and safe.
+
+## APX
+
+APX can provide a local daemon, MCP management, Telegram bridge, routines, and runtime dispatch
+across Codex, Claude Code, OpenCode, Aider, Cursor Agent, Gemini CLI, Qwen Code, or direct LLM
+engines. Those are APX runtime features, not APC portable-core requirements.
+
+The APX super-agent uses `~/.apx/projects/default` for system-level work when no project is named.
+APX routines can run heartbeat, shell, Telegram, project agent, or super-agent tasks on a schedule.
+
+APX runtime state belongs outside the repository:
+
+```text
+~/.apx/projects/<project-id>/
+```

package/src/daemon/plugins/telegram.js

@@ -131,6 +131,48 @@ export async function sendAudio(token, chatId, audio, { caption, title, performe
   return json.result;
 }
 
+/**
+ * Transcribe an audio file via OpenAI Whisper.
+ * Reads OPENAI_API_KEY from env or engines.openai.api_key in ~/.apx/config.json.
+ * Returns the transcribed text, or throws if no key / API failure.
+ */
+async function transcribeAudio(filePath) {
+  let apiKey = process.env.OPENAI_API_KEY;
+  if (!apiKey) {
+    try {
+      const { readConfig } = await import("../../core/config.js");
+      apiKey = readConfig()?.engines?.openai?.api_key || "";
+    } catch { /* ignore */ }
+  }
+  if (!apiKey) throw new Error("OPENAI_API_KEY not set (env or engines.openai.api_key)");
+
+  const fileBuf = fs.readFileSync(filePath);
+  const ext = path.extname(filePath).slice(1).toLowerCase() || "ogg";
+  const mimeMap = {
+    oga: "audio/ogg", ogg: "audio/ogg", opus: "audio/ogg",
+    mp3: "audio/mpeg", m4a: "audio/mp4", mp4: "audio/mp4",
+    wav: "audio/wav", webm: "audio/webm",
+  };
+  const mime = mimeMap[ext] || "audio/ogg";
+  const blob = new Blob([fileBuf], { type: mime });
+
+  const form = new FormData();
+  form.append("file", blob, `audio.${ext}`);
+  form.append("model", "whisper-1");
+
+  const res = await fetch("https://api.openai.com/v1/audio/transcriptions", {
+    method: "POST",
+    headers: { Authorization: `Bearer ${apiKey}` },
+    body: form,
+  });
+  if (!res.ok) {
+    const err = await res.text().catch(() => "");
+    throw new Error(`Whisper ${res.status}: ${err.slice(0, 200)}`);
+  }
+  const json = await res.json();
+  return String(json.text || "").trim();
+}
+
 /**
  * Download a file from Telegram servers.
  * Returns the local file path where it was saved.
@@ -389,6 +431,65 @@ class ChannelPoller {
       if (!text) return;
     }
 
+    // ── Incoming voice / audio handling ──────────────────────────────────
+    // Telegram sends `voice` for the press-and-hold mic recording (.oga/opus)
+    // and `audio` for uploaded audio files (mp3/m4a/etc.). Either way we
+    // download, run it through Whisper, prefix the result with `[audio] `
+    // and let the rest of the message flow handle it as plain text.
+    const incomingAudio = msg.voice || msg.audio;
+    if (incomingAudio && incomingAudio.file_id) {
+      const token = resolveBotToken(this.channel);
+      const mediaDir = path.join(APX_HOME, "media");
+      fs.mkdirSync(mediaDir, { recursive: true });
+      let localPath = null;
+      let transcript = "";
+      let transcribeError = null;
+      try {
+        localPath = await downloadTelegramFile(token, incomingAudio.file_id, mediaDir);
+        this.log(`telegram[${this.channel.name}] audio saved: ${localPath}`);
+      } catch (e) {
+        this.log(`telegram[${this.channel.name}] audio download failed: ${e.message}`);
+      }
+      if (localPath) {
+        try {
+          transcript = await transcribeAudio(localPath);
+          this.log(`telegram[${this.channel.name}] audio transcribed (${transcript.length} chars)`);
+        } catch (e) {
+          transcribeError = e.message;
+          this.log(`telegram[${this.channel.name}] audio transcription failed: ${e.message}`);
+        }
+      }
+      const audioBody = transcript
+        ? `[audio] ${transcript}`
+        : `[audio] (transcription unavailable${transcribeError ? ": " + transcribeError : ""})`;
+
+      appendGlobalMessage({
+        channel: "telegram",
+        direction: "in",
+        type: "audio",
+        actor_id: msg.from?.id ? String(msg.from.id) : author,
+        external_id: String(u.update_id),
+        author,
+        body: audioBody,
+        meta: {
+          chat_id,
+          user_id: msg.from?.id || null,
+          message_id: msg.message_id,
+          tg_channel: this.channel.name,
+          local_path: localPath,
+          file_id: incomingAudio.file_id,
+          duration: incomingAudio.duration,
+          mime_type: incomingAudio.mime_type,
+          transcription_error: transcribeError,
+        },
+      });
+
+      // Inject the transcribed text into `text` so the rest of the agent
+      // pipeline treats it identically to a typed message. If there was a
+      // caption alongside the audio, prepend the audio marker to it.
+      text = text ? `${audioBody}\n${text}` : audioBody;
+    }
+
     // /reset or /new wipes the rolling context for this chat. We just
     // remember a marker timestamp; subsequent inbounds will only consider
     // history newer than this. Implemented by writing a synthetic message

package/src/daemon/skills-loader.js

@@ -0,0 +1,228 @@
+// daemon/skills-loader.js
+// Discover and load APX skills on-demand for the super-agent.
+//
+// The super-agent reads skills from immutable INTERNAL sources under
+// src/core/ — they ship with apx and can never be deleted by the user. This
+// guarantees apx/apc/runtime knowledge is always available regardless of
+// what the user does to ~/.apx/skills/. Distribution copies under
+// <package>/skills/ are a separate concern (scaffold.js handles them) and
+// the loader does NOT read from there.
+//
+// Discovery order (priority high → low):
+//   1. <projectPath>/.apc/skills/<slug>.md          ← project-scoped
+//   1b.<projectPath>/.apc/skills/<slug>/SKILL.md    ← same, dir-style
+//   2. ~/.apx/skills/<slug>/SKILL.md                ← user-installed global
+//   3. <packageRoot>/src/core/runtime-skills/<slug>.md ← built-in runtime docs
+//                                                       (claude-code, codex-cli,
+//                                                       opencode-cli, openrouter)
+//   4. <packageRoot>/src/core/apx-skill.md          ← built-in intrinsic apx
+//   4b.<packageRoot>/src/core/apc-context-skill.md  ← built-in intrinsic apc-context
+//
+// A slug found in a higher-priority location SHADOWS lower ones — so a user
+// who drops `~/.apx/skills/apx/SKILL.md` overrides the intrinsic one, but the
+// intrinsic stays in the package as a safety net.
+
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname  = path.dirname(__filename);
+const PACKAGE_ROOT = path.resolve(__dirname, "..", "..");
+
+const RUNTIME_SKILLS_DIR = path.join(PACKAGE_ROOT, "src", "core", "runtime-skills");
+const GLOBAL_DIR         = path.join(os.homedir(), ".apx", "skills");
+const CORE_DIR           = path.join(PACKAGE_ROOT, "src", "core");
+
+// Intrinsic built-in skills whose source files (src/core/*-skill.md) do NOT
+// carry frontmatter — the scaffold.js wrapper adds frontmatter when copying
+// these out to external IDE skill dirs. For the super-agent's catalog we
+// supply slug + description inline. Keep in sync with scaffold.js.
+const INTRINSIC = [
+  {
+    slug: "apx",
+    file: path.join(CORE_DIR, "apx-skill.md"),
+    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'.",
+  },
+  {
+    slug: "apc-context",
+    file: path.join(CORE_DIR, "apc-context-skill.md"),
+    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.",
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Frontmatter parsing (minimal — handles the YAML we ship)
+// ---------------------------------------------------------------------------
+
+function parseFrontmatter(raw) {
+  if (!raw.startsWith("---")) return { fm: {}, body: raw };
+  const end = raw.indexOf("\n---", 3);
+  if (end < 0) return { fm: {}, body: raw };
+
+  const fmBlock = raw.slice(3, end).trim();
+  const body = raw.slice(end + 4).replace(/^\n/, "");
+
+  const fm = {};
+  for (const line of fmBlock.split("\n")) {
+    const m = line.match(/^([a-zA-Z_][a-zA-Z0-9_-]*)\s*:\s*(.*)$/);
+    if (!m) continue;
+    let val = m[2].trim();
+    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+      val = val.slice(1, -1);
+    }
+    fm[m[1]] = val;
+  }
+  return { fm, body };
+}
+
+// ---------------------------------------------------------------------------
+// Directory scanners
+// ---------------------------------------------------------------------------
+
+/** Returns [{slug, source, file}] from a directory using <slug>/SKILL.md layout. */
+function scanDirStyle(baseDir, source) {
+  if (!baseDir || !fs.existsSync(baseDir)) return [];
+  const out = [];
+  let entries;
+  try { entries = fs.readdirSync(baseDir, { withFileTypes: true }); }
+  catch { return []; }
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    const file = path.join(baseDir, e.name, "SKILL.md");
+    if (fs.existsSync(file)) out.push({ slug: e.name, source, file });
+  }
+  return out;
+}
+
+/** Returns [{slug, source, file}] from a directory using <slug>.md layout. */
+function scanFlatStyle(baseDir, source) {
+  if (!baseDir || !fs.existsSync(baseDir)) return [];
+  const out = [];
+  let entries;
+  try { entries = fs.readdirSync(baseDir, { withFileTypes: true }); }
+  catch { return []; }
+  for (const e of entries) {
+    if (!e.isFile() || !e.name.endsWith(".md")) continue;
+    if (e.name === "README.md") continue;
+    out.push({
+      slug: e.name.replace(/\.md$/, ""),
+      source,
+      file: path.join(baseDir, e.name),
+    });
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Discover available skills across all locations.
+ * Returns lightweight metadata only — body is NOT read.
+ *
+ * @param {object} opts
+ * @param {string=} opts.projectPath  optional project root to also scan
+ * @returns {Array<{slug, source, description, file}>}
+ */
+export function listSkills({ projectPath } = {}) {
+  const found = [];
+
+  // priority 1: project-scoped
+  if (projectPath) {
+    const apcSkills = path.join(projectPath, ".apc", "skills");
+    found.push(...scanDirStyle(apcSkills, "project"));
+    found.push(...scanFlatStyle(apcSkills, "project"));
+  }
+
+  // priority 2: user-installed global
+  found.push(...scanDirStyle(GLOBAL_DIR, "global"));
+
+  // priority 3: built-in runtime docs (have frontmatter)
+  found.push(...scanFlatStyle(RUNTIME_SKILLS_DIR, "builtin"));
+
+  // priority 4: intrinsic built-ins (no frontmatter — descriptions hardcoded)
+  for (const it of INTRINSIC) {
+    if (fs.existsSync(it.file)) {
+      found.push({ slug: it.slug, source: "builtin", file: it.file, _description: it.description });
+    }
+  }
+
+  // dedupe by slug (first-wins = higher priority shadows lower)
+  const seen = new Set();
+  const result = [];
+  for (const entry of found) {
+    if (seen.has(entry.slug)) continue;
+    seen.add(entry.slug);
+
+    // Description: prefer inline (intrinsic) → frontmatter → empty
+    let description = entry._description || "";
+    if (!description) {
+      try {
+        const raw = fs.readFileSync(entry.file, "utf8");
+        const { fm } = parseFrontmatter(raw);
+        description = fm.description || "";
+      } catch { /* unreadable — skip description */ }
+    }
+
+    result.push({
+      slug: entry.slug,
+      source: entry.source,
+      description,
+      file: entry.file,
+    });
+  }
+  return result;
+}
+
+/**
+ * Load the full body of a skill (frontmatter stripped if present). Resolves
+ * via the same priority chain as listSkills().
+ *
+ * @param {string} slug
+ * @param {object} opts
+ * @param {string=} opts.projectPath
+ * @returns {{slug, source, file, description, body, frontmatter}}
+ */
+export function loadSkill(slug, { projectPath } = {}) {
+  if (!slug) throw new Error("loadSkill: slug required");
+
+  const list = listSkills({ projectPath });
+  const entry = list.find(s => s.slug === slug);
+  if (!entry) {
+    throw new Error(`skill "${slug}" not found. Available: ${list.map(s => s.slug).join(", ") || "(none)"}`);
+  }
+
+  const raw = fs.readFileSync(entry.file, "utf8");
+  const { fm, body } = parseFrontmatter(raw);
+  return {
+    slug: entry.slug,
+    source: entry.source,
+    file: entry.file,
+    description: entry.description || fm.description || "",
+    frontmatter: fm,
+    body: body.trim(),
+  };
+}
+
+// Useful for diagnostics
+export const SKILL_LOCATIONS = {
+  runtime_skills: RUNTIME_SKILLS_DIR,
+  intrinsic: CORE_DIR,
+  global: GLOBAL_DIR,
+};

package/src/daemon/super-agent-tools/index.js

@@ -19,6 +19,8 @@ import sendTelegram from "./tools/send-telegram.js";
 import setIdentity from "./tools/set-identity.js";
 import setPermissionMode from "./tools/set-permission-mode.js";
 import searchFiles from "./tools/search-files.js";
+import listSkills from "./tools/list-skills.js";
+import loadSkill from "./tools/load-skill.js";
 import { createPermissionGuard } from "./helpers.js";
 import { buildBridgedTools, DEFAULT_CATEGORIES } from "./registry-bridge.js";
 
@@ -44,6 +46,8 @@ const NATIVE_TOOLS = [
   setIdentity,
   setPermissionMode,
   searchFiles,
+  listSkills,
+  loadSkill,
 ];
 
 // Registry-backed bridges. Categories can be overridden per-process via env

package/src/daemon/super-agent-tools/tools/add-project.js

@@ -1,36 +1,66 @@
+import fs from "node:fs";
 import path from "node:path";
 import { readConfig, addProject as addProjectInConfig } from "../../../core/config.js";
+import { initApf } from "../../../core/scaffold.js";
 import { confirmedProperty, projectMeta } from "../helpers.js";
 
+function isApcProject(absPath) {
+  return (
+    fs.existsSync(path.join(absPath, "AGENTS.md")) &&
+    fs.existsSync(path.join(absPath, ".apc", "project.json"))
+  );
+}
+
 export default {
   name: "add_project",
   schema: {
     type: "function",
     function: {
       name: "add_project",
-      description: "Register an existing APC project path with the APX daemon. The path must contain AGENTS.md and .apc/project.json.",
+      description:
+        "Register a project path with the APX daemon. If the path is not yet an APC project (missing AGENTS.md or .apc/project.json), the tool runs the init scaffold first and then registers it — one call covers both cases. Pass init=false to require the path to already be an APC project (strict mode).",
       parameters: {
         type: "object",
         properties: {
-          path: { type: "string", description: "absolute or relative filesystem path to an APC project" },
+          path: { type: "string", description: "absolute or relative filesystem path to add" },
+          name: { type: "string", description: "optional project name (used only when initializing a new APC project)" },
+          init: { type: "boolean", description: "auto-create AGENTS.md and .apc/project.json if missing (default true)" },
           confirmed: confirmedProperty("true only after explicit user confirmation for this exact project registration"),
         },
         required: ["path"],
       },
     },
   },
-  makeHandler: ({ projects, requirePermission }) => ({ path: projectPath, confirmed = false }) => {
+  makeHandler: ({ projects, requirePermission }) => ({ path: projectPath, name, init = true, confirmed = false }) => {
     requirePermission("add_project", { dangerous: true, confirmed });
     if (!projectPath) throw new Error("add_project: path required");
 
+    const abs = path.resolve(projectPath);
+    if (!fs.existsSync(abs)) {
+      throw new Error(`add_project: path does not exist: ${abs}`);
+    }
+
+    let initialized = false;
+    if (!isApcProject(abs)) {
+      if (!init) {
+        throw new Error(
+          `not an APC project: ${abs} (no AGENTS.md / .apc/project.json). ` +
+          `Pass init=true to scaffold it before registering.`
+        );
+      }
+      initApf(abs, { name });
+      initialized = true;
+    }
+
     const cfg = readConfig();
-    const result = addProjectInConfig(cfg, projectPath);
+    const result = addProjectInConfig(cfg, abs);
     const p = projects.register(result.project.path);
     return {
       ok: true,
       added: result.added,
+      initialized,
       project: projectMeta(projects, p),
-      normalized_path: path.resolve(projectPath),
+      normalized_path: abs,
     };
   },
 };

package/src/daemon/super-agent-tools/tools/list-skills.js

@@ -0,0 +1,32 @@
+import { listSkills, SKILL_LOCATIONS } from "../../skills-loader.js";
+
+export default {
+  name: "list_skills",
+  schema: {
+    type: "function",
+    function: {
+      name: "list_skills",
+      description:
+        "List available skills (documentation modules) the super-agent can load on demand. Returns slug + 1-line description for each — NO body content (cheap). Call load_skill(slug) to actually fetch the doc when needed. Scans built-in skills shipped with apx, user-installed globals in ~/.apx/skills/, and project-scoped skills in <project>/.apc/skills/.",
+      parameters: {
+        type: "object",
+        properties: {
+          project_path: {
+            type: "string",
+            description: "optional project root to also scan for project-scoped skills (use the CWD when the user is working in a project)",
+          },
+        },
+      },
+    },
+  },
+  makeHandler: () => ({ project_path } = {}) => {
+    const skills = listSkills({ projectPath: project_path });
+    return {
+      ok: true,
+      count: skills.length,
+      locations: SKILL_LOCATIONS,
+      project_path: project_path || null,
+      skills: skills.map(({ slug, source, description }) => ({ slug, source, description })),
+    };
+  },
+};

package/src/daemon/super-agent-tools/tools/load-skill.js

@@ -0,0 +1,31 @@
+import { loadSkill } from "../../skills-loader.js";
+
+export default {
+  name: "load_skill",
+  schema: {
+    type: "function",
+    function: {
+      name: "load_skill",
+      description:
+        "Load the full body of a named skill (markdown documentation, frontmatter stripped). Use after list_skills found a relevant slug. Resolves the slug via priority: project > global (~/.apx/skills/) > built-in. The body is loaded into the conversation only on the turn you call this — keeps baseline tokens at zero.",
+      parameters: {
+        type: "object",
+        properties: {
+          slug: {
+            type: "string",
+            description: "skill slug as listed by list_skills (e.g. \"apx\", \"apc-context\")",
+          },
+          project_path: {
+            type: "string",
+            description: "optional project root for resolving project-scoped skills",
+          },
+        },
+        required: ["slug"],
+      },
+    },
+  },
+  makeHandler: () => ({ slug, project_path } = {}) => {
+    if (!slug) throw new Error("load_skill: slug required");
+    return loadSkill(slug, { projectPath: project_path });
+  },
+};

package/src/daemon/super-agent-tools/tools/send-telegram.js

@@ -1,30 +1,54 @@
 import { confirmedProperty } from "../helpers.js";
 
+function decodePhoto({ photo_base64, photo_path, photo_url }) {
+  if (photo_url)  return String(photo_url);
+  if (photo_path) return String(photo_path);
+  if (photo_base64) {
+    // Strip "data:image/...;base64," prefix if present
+    const clean = String(photo_base64).replace(/^data:image\/[a-z]+;base64,/, "");
+    return Buffer.from(clean, "base64");
+  }
+  return null;
+}
+
 export default {
   name: "send_telegram",
   schema: {
     type: "function",
     function: {
       name: "send_telegram",
-      description: "Send a Telegram message via the daemon's Telegram plugin.",
+      description:
+        "Send a Telegram message via the daemon's Telegram plugin. Text only by default; pass photo_base64 (from browser_screenshot) / photo_path / photo_url to attach an image — the text becomes the caption. Use this AFTER a browser_screenshot when the user asks for a screenshot or visual reply.",
       parameters: {
         type: "object",
         properties: {
-          channel: { type: "string", description: "telegram channel name; omit for default" },
-          chat_id: { type: "string", description: "destination chat id; omit to use channel default" },
-          text: { type: "string" },
-          confirmed: confirmedProperty("true only after explicit user confirmation for this exact outbound message"),
+          channel:      { type: "string", description: "telegram channel name; omit for default" },
+          chat_id:      { type: "string", description: "destination chat id; omit to use channel default" },
+          text:         { type: "string", description: "message body (becomes the photo caption when a photo_* arg is passed)" },
+          photo_base64: { type: "string", description: "raw base64 PNG/JPG (or 'data:image/...;base64,...' data URI). Pass the `base64` field returned by browser_screenshot here." },
+          photo_path:   { type: "string", description: "absolute filesystem path to an image file" },
+          photo_url:    { type: "string", description: "public https URL of an image" },
+          confirmed:    confirmedProperty("true only after explicit user confirmation for this exact outbound message"),
         },
         required: ["text"],
       },
     },
   },
-  makeHandler: ({ plugins, requirePermission }) => async ({ channel, chat_id, text, confirmed = false }) => {
+  makeHandler: ({ plugins, requirePermission }) => async ({ channel, chat_id, text, photo_base64, photo_path, photo_url, confirmed = false }) => {
     requirePermission("send_telegram", { dangerous: true, confirmed });
     if (!plugins) throw new Error("plugins unavailable");
     const telegram = plugins.get("telegram");
     if (!telegram) throw new Error("telegram plugin not loaded");
+
+    const photo = decodePhoto({ photo_base64, photo_path, photo_url });
+    if (photo) {
+      const result = await telegram.sendPhoto({
+        channel, chat_id, photo, caption: text, author: "apx",
+      });
+      return { ok: true, kind: "photo", message_id: result.message_id };
+    }
+
     const result = await telegram.send({ channel, chat_id, text, author: "apx" });
-    return { ok: true, message_id: result.message_id };
+    return { ok: true, kind: "text", message_id: result.message_id };
   },
 };

package/src/daemon/super-agent.js

@@ -13,6 +13,7 @@
 //   }
 import { callEngine } from "./engines/index.js";
 import { TOOL_SCHEMAS, makeToolHandlers } from "./super-agent-tools.js";
+import { listSkills } from "./skills-loader.js";
 import {
   extractPseudoToolCalls,
   cleanTextOfPseudoToolCalls,
@@ -62,7 +63,9 @@ HARD RULES (do not deviate):
 16. IDENTITY RULE: when the user asks you to change your name, call yourself something, or update your personality/language, call set_identity and persist the change. Then confirm with your new name.
 17. ROUTINES RULE: NEVER create a routine in the default project (id=0). Routines MUST be tied to a specific registered project. Before adding a routine, call list_projects to find the correct project id or name. Then pass --project <id|name> to apx routine add. If no project fits, ask the user which project to use. Creating routines in project 0/default mixes unrelated projects' schedules and corrupts state.
 18. **NO EMPTY RESPONSES**: Never respond with only text when you have tools available and the user is asking you to DO something. Call the tool FIRST, then explain. Never say "I'll do X" without immediately calling the tool. Empty acknowledgments ("ok", "entendido", "dame un minuto", "voy", "checking", "stand by") without a tool call are invalid responses — they will be re-prompted and waste a turn.
-19. **CWD RULE**: When the channel context includes a "CWD: <path>" line, that is the user's current working directory. References to "este directorio", "este proyecto", "esta carpeta", "acá", "aquí", "this directory", "this project", "current dir/folder" all mean that exact CWD path. Use it as the path argument directly — DO NOT ask the user "what's the path?" when CWD is already given. Example: if user says "agregá este proyecto a la lista", call add_project({path: <CWD>}) immediately.`;
+19. **CWD RULE**: When the channel context includes a "CWD: <path>" line, that is the user's current working directory. References to "este directorio", "este proyecto", "esta carpeta", "acá", "aquí", "this directory", "this project", "current dir/folder" all mean that exact CWD path. Use it as the path argument directly — DO NOT ask the user "what's the path?" when CWD is already given. Example: if user says "agregá este proyecto a la lista", call add_project({path: <CWD>}) immediately.
+20. **NO MANUAL SCAFFOLDING**: To register or scaffold a project, ALWAYS use add_project — it auto-creates AGENTS.md and .apc/project.json when missing (one call, atomic). NEVER write AGENTS.md, .apc/project.json, or any APC scaffold file by hand via run_shell / write_file / shell pipes. The schema must come from the official initApf scaffold, not improvised. If add_project errors, report the error to the user — don't try to work around it with shell hacks. Same for any other APC-managed file (.apc/agents/*, .apc/skills/*, etc.) — use the dedicated tool, never raw filesystem writes.
+21. **SKILLS — ON DEMAND**: The "# Available skills" section below lists every skill available to you (slug + description, NO body). When the user asks about specific APX/APC commands, project structure, agent runtimes, or anything where exact syntax or detailed behavior matches a skill description (in ANY language — match semantically, not by keyword), call load_skill({slug}) to fetch the full markdown body. If a CWD is in the contextNote, pass it as project_path so project-scoped skills resolve. If the user explicitly asks "what skills do you have?", you can either read the catalog below directly OR call list_skills to get a fresh enumeration. Do NOT load skills for trivial / unrelated questions — that wastes tokens. Don't guess CLI syntax when a skill can tell you; load it.`;
 
 function isShortConfirmation(text) {
   return /^(yes|y|si|si dale|dale|ok|okay|confirm|confirmed|go|proceed|do it)\b/i
@@ -136,12 +139,32 @@ export async function runSuperAgent({
     "When a tool schema has confirmed, set confirmed=true only after explicit user confirmation for that exact action.",
   ].join("\n");
 
+  // Build a lightweight catalog of available skills (slug + 1-line description).
+  // Skill BODIES are NOT included — only the catalog. The model decides which
+  // (if any) to load on demand via load_skill(slug). Cross-lingual matching is
+  // handled by the LLM itself (no router needed). Empty if no skills found.
+  const skillsCatalog = (() => {
+    let list = [];
+    try { list = listSkills(); } catch { /* loader failure → empty catalog */ }
+    if (!list.length) return "";
+    return [
+      "# Available skills (load on demand)",
+      "Below is the catalog of skills (slug + description). Bodies are NOT loaded yet.",
+      "If the user asks how something works, requests syntax/docs, or otherwise needs",
+      "knowledge that matches a skill description (in any language — match semantically),",
+      "call load_skill({slug}) to load the full markdown into your context.",
+      "",
+      ...list.map(s => `- **${s.slug}** [${s.source}]: ${s.description || "(no description)"}`),
+    ].join("\n");
+  })();
+
   const system = [
     sa.system || DEFAULT_SYSTEM,
     permissionNote,
     contextNote,
     "# Registered projects (just the index — call tools for details)",
     projectIndex || "(no projects registered)",
+    skillsCatalog,
   ]
     .filter(Boolean)
     .join("\n\n");