@agentprojectcontext/apx 1.34.0 → 1.36.0

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

@@ -1,44 +1,39 @@
 ---
 name: apx-voice
 scope: optional
-description: How APX handles voice — TTS engines (Piper local, ElevenLabs / OpenAI / Gemini cloud), the unified /voice/turn channel, and apx voice CLI. Load when the user wants to speak with APX, configure a voice engine, or troubleshoot silent output.
+description: APX TTS — Piper (local), ElevenLabs/OpenAI/Gemini (cloud), unified /voice/turn channel, `apx voice` CLI. Load when the user wants to speak with APX, configure a voice engine, or troubleshoot silent output.
 ---
 
 # apx-voice
 
-APX has a Text-to-Speech (TTS) facade in `core/voice/` with five engines. STT (speech-to-text) lives separately in `host/daemon/transcription.js` (Whisper). The "voice channel" combines both for a full mic→agent→speaker turn.
+TTS facade in `core/voice/` with five engines. STT lives separately in `host/daemon/transcription.js` (Whisper). The "voice channel" combines both for mic→agent→speaker.
 
 ## Engines
 
-| id | Local? | Needs key? | Quality | Notes |
-|---|---|---|---|---|
-| `piper`      | yes | no  | Good (es_AR-daniela-high recommended) | Local, offline. Requires `piper` CLI + `.onnx` voice model. |
-| `elevenlabs` | no  | yes | Excellent | Free tier 10k chars/mo. `eleven_multilingual_v2`. |
-| `openai`     | no  | yes | Good | Reuses `engines.openai.api_key`. `tts-1`. |
-| `gemini`     | no  | yes | Good | Returns raw L16 PCM — APX wraps in WAV automatically. |
-| `mock`       | yes | no  | Silent | Silent WAV; placeholder for tests. |
+| id | Local? | Needs key? | Notes |
+|---|---|---|---|
+| `piper`      | yes | no  | Local, offline. Requires `piper` CLI + `.onnx` model. es_AR-daniela-high recommended. |
+| `elevenlabs` | no  | yes | Excellent. Free tier 10k chars/mo. `eleven_multilingual_v2`. |
+| `openai`     | no  | yes | Reuses `engines.openai.api_key`. `tts-1`. |
+| `gemini`     | no  | yes | Returns raw L16 PCM — APX wraps in WAV automatically. |
+| `mock`       | yes | no  | Silent WAV; placeholder for tests. |
 
-`auto` provider probes in order: piper → elevenlabs → openai → gemini → mock.
+`auto` probes: piper → elevenlabs → openai → gemini → mock.
 
 ## Concrete CLI calls
 
 ```bash
-# Inspect what's configured + available
-apx voice providers
-
-# Synthesize and play
+apx voice providers                              # what's configured + available
 apx voice say "Hello from APX" --provider piper
-apx voice say "Hello from APX" --provider gemini
-apx voice say "Hello from APX" --provider gemini --voice Aoede   # pick a specific voice
-apx voice say "..." --no-play          # generate WAV, don't play
+apx voice say "Hello from APX" --provider gemini --voice Aoede
+apx voice say "..." --no-play                    # generate WAV, don't play
 
-# Listen (mic → STT)
-apx voice listen                       # records until silence (sox) or Ctrl+C
-apx voice listen --seconds 5           # fixed-duration capture
-apx voice listen --provider <id>       # override the STT/transcription provider
+apx voice listen                                 # mic → STT, records until silence (sox) or Ctrl+C
+apx voice listen --seconds 5                     # fixed-duration capture
+apx voice listen --provider <id>                 # override STT provider
 ```
 
-Playback uses system binaries (`afplay`, `paplay`, `aplay`, `play`, `ffplay`) — APX doesn't bundle an audio runtime. If none is found, you get the file path and no playback.
+Playback uses system binaries (`afplay`, `paplay`, `aplay`, `play`, `ffplay`). If none found, you get the file path and no playback.
 
 ## Configuration
 
@@ -60,9 +55,7 @@ Playback uses system binaries (`afplay`, `paplay`, `aplay`, `play`, `ffplay`)
 
 `apx config set voice.tts.provider <name>` to switch.
 
-## Quick setup paths
-
-### Piper local (recommended, no internet)
+## Quick setup: Piper local (recommended, no internet)
 
 ```bash
 # 1. Install binary (macOS arm64)
@@ -70,21 +63,18 @@ curl -L https://github.com/rhasspy/piper/releases/latest/download/piper_macos_aa
   -o /tmp/piper.tar.gz
 sudo tar xzf /tmp/piper.tar.gz -C /usr/local/bin --strip-components=1
 
-# 2. Voice model (es_AR — Argentine Spanish, voice "daniela")
-mkdir -p ~/.apx/voices
-cd ~/.apx/voices
+# 2. Voice model (es_AR, "daniela")
+mkdir -p ~/.apx/voices && cd ~/.apx/voices
 curl -LO https://huggingface.co/rhasspy/piper-voices/resolve/main/es/es_AR/daniela/high/es_AR-daniela-high.onnx
 curl -LO https://huggingface.co/rhasspy/piper-voices/resolve/main/es/es_AR/daniela/high/es_AR-daniela-high.onnx.json
 
-# 3. APX config
+# 3. Configure + test
 apx config set voice.tts.provider piper
 apx config set voice.tts.piper.model "$HOME/.apx/voices/es_AR-daniela-high.onnx"
-
-# 4. Test
-apx voice say "hola, soy APX" --provider piper   # Spanish text exercises the es_AR voice
+apx voice say "hola, soy APX" --provider piper
 ```
 
-### Gemini cloud (quick if you already have a key)
+## Quick setup: Gemini cloud
 
 ```bash
 apx config set voice.tts.provider gemini
@@ -93,45 +83,35 @@ apx config set engines.gemini.api_key   '<GEMINI_KEY>'    # reuse for LLM router
 apx voice say "Hello from APX" --provider gemini
 ```
 
-## The unified voice channel
+## Unified voice channel
 
-`POST /voice/turn` is one round-trip: send audio (or text), get back `{ user_text, reply_text, reply_audio_path }`. STT in, agent loop, TTS out. Surface for the overlay and any future "voice room" client.
+`POST /voice/turn` is one round-trip: send audio (or text), get back `{ user_text, reply_text, reply_audio_path }`. STT in, agent loop, TTS out. For overlay and future "voice room" clients.
 
 ```bash
-# Drive from curl with already-transcribed text (skip STT)
 curl -X POST http://127.0.0.1:7430/voice/turn \
   -H "Authorization: Bearer $(cat ~/.apx/daemon.token)" \
   -H "Content-Type: application/json" \
   -d '{"text":"Hello APX","channel":"voice"}'
 ```
 
-Telegram voice messages and the overlay mascot still have their own STT pipelines today — they don't go through `/voice/turn` (yet). The endpoint exists for callers that want one-shot bidirectional voice.
+Telegram voice messages and overlay mascot still have their own STT pipelines — they don't go through `/voice/turn` yet.
 
 ## Anti-examples
 
-```bash
-# DON'T trust `apx voice providers` saying "mock available" as a green light.
-# Mock is silence; useful for tests, useless for talking to humans.
-# If only mock is "available", configure a real provider.
-
-# DON'T set voice.tts.provider to a provider with no key.
-# It will fall through `auto` to the next, but that's not what you asked for.
-
-# DON'T expect Gemini TTS to give you an MP3.
-# Today it returns raw L16 PCM. APX wraps it in a 44-byte WAV header so afplay
-# accepts it. Files are .wav, mime "audio/wav". If you need MP3, convert with ffmpeg.
-```
+- DON'T trust `apx voice providers` saying "mock available" as green light — mock is silence. Configure a real provider.
+- DON'T set `voice.tts.provider` to a provider with no key. It falls through `auto` to the next, but that's not what you asked.
+- DON'T expect Gemini TTS to return MP3 — it returns raw L16 PCM; APX wraps in WAV. Files are `.wav`, mime `audio/wav`. Convert with ffmpeg if you need MP3.
 
 ## Troubleshooting silent output
 
 1. `apx voice providers` — what's actually available?
-2. `apx voice say "test" --provider <engine> --no-play` — does the file exist?
-3. `file <path>` — is it a valid container? Gemini's output should be `RIFF WAVE Microsoft PCM`.
-4. `afplay <path>` directly — does the OS player open it?
-5. If 3 fails for Gemini, you may be on an older APX before the PCM-wrap fix (commit `ba5c416` or later).
+2. `apx voice say "test" --provider <engine> --no-play` — file exists?
+3. `file <path>` — valid container? Gemini output should be `RIFF WAVE Microsoft PCM`.
+4. `afplay <path>` — does the OS player open it?
+5. If 3 fails for Gemini, you may be on APX before the PCM-wrap fix (commit `ba5c416`+).
 
 ## Don't
 
-- Don't paste base64 audio into chat. Use file paths or upload via `send_voice` / `send_audio`.
-- Don't switch providers mid-routine without testing — voice quality varies a lot between Piper voices and cloud engines.
-- Don't expect TTS streaming yet — `apx voice say` returns a complete file. A `/tts/stream` endpoint with chunked audio is open work.
+- Paste base64 audio into chat. Use file paths or `send_voice` / `send_audio`.
+- Switch providers mid-routine without testing — quality varies a lot across Piper voices and cloud engines.
+- Expect TTS streaming yet — `apx voice say` returns a complete file. `/tts/stream` is open work.

package/src/core/stores/conversations.js

@@ -27,7 +27,7 @@ export function conversationPath(storagePath, agentSlug, idOrFilename) {
   return path.join(storagePath, "agents", agentSlug, "conversations", filename);
 }
 
-export function startConversation({ storagePath, agentSlug, engine, system }) {
+export function startConversation({ storagePath, agentSlug, engine, system, channel }) {
   const dir = path.join(storagePath, "agents", agentSlug, "conversations");
   fs.mkdirSync(dir, { recursive: true });
   const id = generateConversationId(storagePath, agentSlug);
@@ -38,6 +38,7 @@ export function startConversation({ storagePath, agentSlug, engine, system }) {
     `id: ${id}\n` +
     `agent: ${agentSlug}\n` +
     `engine: ${engine}\n` +
+    (channel ? `channel: ${channel}\n` : "") +
     `started: ${started}\n` +
     `last_turn: \n` +
     `status: open\n` +
@@ -98,7 +99,31 @@ export function listConversations(storagePath, agentSlug) {
     .filter((f) => f.endsWith(".md"))
     .sort()
     .reverse()
-    .map((f) => ({ filename: f, id: f.replace(/\.md$/, "") }));
+    .map((f) => summarizeConversation(path.join(dir, f), agentSlug, f))
+    .filter(Boolean);
+}
+
+// Lightweight summary used by the chat list sidebar — reads frontmatter and
+// counts turns without loading the whole conversation into memory beyond what
+// `fs.readFileSync` already does. The fields match `ConversationListEntry` on
+// the frontend so the sidebar can group + filter without a second roundtrip.
+function summarizeConversation(filePath, agentSlug, filename) {
+  let text;
+  try { text = fs.readFileSync(filePath, "utf8"); } catch { return null; }
+  const { fm, turns } = parseConversation(text);
+  const messages = turns.filter((t) => t.role !== "system" && t.role !== "compact").length;
+  const firstUser = turns.find((t) => t.role === "user");
+  const title = (firstUser?.content || "").split("\n")[0].slice(0, 80).trim() || undefined;
+  return {
+    id: filename.replace(/\.md$/, ""),
+    filename,
+    agent_slug: agentSlug,
+    started_at: fm.started || fm.last_turn || "",
+    ended_at: fm.status === "closed" ? (fm.last_turn || undefined) : undefined,
+    channel: fm.channel || undefined,
+    messages,
+    title,
+  };
 }
 
 export function setStatus(filePath, status) {

package/src/host/daemon/api/exec.js

@@ -116,6 +116,7 @@ export function register(app, { projects, project, config }) {
       model: modelOverride,
       temperature,
       maxTokens,
+      channel,
     } = req.body || {};
     if (!prompt) return res.status(400).json({ error: "prompt required" });
     const agents = readAgents(p.path);
@@ -171,6 +172,7 @@ export function register(app, { projects, project, config }) {
           agentSlug: agent.slug,
           engine: modelId,
           system,
+          channel,
         });
         convPath = conv.path;
         convId = conv.id;

package/src/host/daemon/api/skills.js

@@ -1,12 +1,42 @@
-// Lightweight `/skills` listing for UI surfaces (web composer picker,
-// future palettes). Same data backing `list_skills` tool, but here without
-// auth-binding to a project — anyone with a valid daemon token can ask
-// "which skills are around right now?".
+// `/skills` listing + Skill Inspector control surface for UI clients.
 //
-// Returns the catalog already condensed (slug + first-sentence description)
-// so the picker doesn't have to repeat the cleanup work.
+//   GET  /skills                       catalog (slug + condensed description)
+//   GET  /skills/inspector             inspector config + index status
+//   PUT  /skills/inspector             toggle / tune inspector config
+//   POST /skills/index                 (re)build the inspector vector index
+//   POST /skills/inspect               dry-run the inspector for a prompt
+//
+// The listing is the same data backing `list_skills` (no auth-binding to a
+// project). The inspector routes mirror /embeddings/* so the web admin can
+// configure the skill RAG exactly like it configures the memory RAG.
 import { listSkills } from "#core/agent/skills/loader.js";
 import { condenseSkillDescription } from "#core/agent/skills/catalog.js";
+import {
+  inspectPromptForSkills,
+  INSPECTOR_DEFAULTS,
+} from "#core/agent/skills/inspector.js";
+import {
+  ensureIndex,
+  planIndex,
+  readIndex,
+} from "#core/agent/skills/index-store.js";
+import { readConfig, writeConfig } from "#core/config/index.js";
+
+const KNOWN_KEYS = Object.keys(INSPECTOR_DEFAULTS);
+
+function mergedInspectorConfig(cfg) {
+  return { ...INSPECTOR_DEFAULTS, ...(cfg?.skills?.inspector || {}) };
+}
+
+function indexStatus() {
+  const idx = readIndex();
+  return {
+    count: Object.keys(idx.items || {}).length,
+    embedder: idx.embedder || null,
+    dim: idx.dim || null,
+    updated_at: idx.updated_at || null,
+  };
+}
 
 export function register(app /*, ctx */) {
   app.get("/skills", (req, res) => {
@@ -27,4 +57,108 @@ export function register(app /*, ctx */) {
       res.status(500).json({ error: e.message });
     }
   });
+
+  // ---- Inspector config + status -----------------------------------------
+
+  app.get("/skills/inspector", (_req, res) => {
+    try {
+      const cfg = readConfig();
+      res.json({
+        config: mergedInspectorConfig(cfg),
+        defaults: INSPECTOR_DEFAULTS,
+        keys: KNOWN_KEYS,
+        index: indexStatus(),
+      });
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  });
+
+  app.put("/skills/inspector", (req, res) => {
+    try {
+      const patch = req.body || {};
+      const cfg = readConfig();
+      cfg.skills = cfg.skills || {};
+      const current = mergedInspectorConfig(cfg);
+      const next = { ...current };
+
+      for (const [k, v] of Object.entries(patch)) {
+        if (!KNOWN_KEYS.includes(k)) continue;
+        const def = INSPECTOR_DEFAULTS[k];
+        if (typeof def === "boolean") next[k] = !!v;
+        else if (typeof def === "number") {
+          const n = Number(v);
+          if (Number.isFinite(n)) next[k] = n;
+        } else {
+          next[k] = v;
+        }
+      }
+
+      cfg.skills.inspector = next;
+      writeConfig(cfg);
+      res.json({ ok: true, config: next, index: indexStatus() });
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  });
+
+  // ---- Index build --------------------------------------------------------
+
+  app.post("/skills/index", async (req, res) => {
+    try {
+      const { project_path, force } = req.body || {};
+      const cfg = readConfig();
+      const plan = planIndex({ projectPath: project_path });
+      const out = await ensureIndex({
+        projectPath: project_path,
+        embedOpts: { globalConfig: cfg },
+        force: !!force,
+      });
+      res.json({
+        ok: true,
+        embedder: out.embedder,
+        dim: out.dim,
+        planned: {
+          missing: plan.missing.length,
+          stale: plan.stale.length,
+          gone: plan.gone.length,
+          total: plan.total,
+        },
+        changed: {
+          added: out.changed.added.length,
+          refreshed: out.changed.refreshed.length,
+          removed: out.changed.removed.length,
+          kept: out.changed.kept.length,
+        },
+        index: indexStatus(),
+      });
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  });
+
+  // ---- Dry-run ------------------------------------------------------------
+
+  app.post("/skills/inspect", async (req, res) => {
+    try {
+      const { prompt, project_path } = req.body || {};
+      if (!prompt || typeof prompt !== "string") {
+        return res.status(400).json({ error: "prompt required" });
+      }
+      const cfg = readConfig();
+      // Force enabled for the dry-run so the operator sees what it WOULD do
+      // even when the feature is currently off.
+      const probed = structuredClone(cfg);
+      probed.skills = probed.skills || {};
+      probed.skills.inspector = { ...mergedInspectorConfig(cfg), enabled: true };
+      const out = await inspectPromptForSkills({
+        prompt,
+        projectPath: project_path,
+        globalConfig: probed,
+      });
+      res.json({ trace: out.trace, contextNote: out.contextNote });
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  });
 }

package/src/host/daemon/api/super-agent.js

@@ -15,10 +15,30 @@ import { appendGlobalMessage } from "#core/stores/messages.js";
 import { createWebConfirmAdapter } from "#core/confirmation/adapters/web.js";
 import { tryResolveSkillCommand } from "#core/agent/skills/trigger.js";
 import { suggestSkillForPrompt } from "#core/agent/skills/rag.js";
+import { inspectPromptForSkills, isInspectorEnabled, summarizeTrace } from "#core/agent/skills/inspector.js";
 import { CHANNELS } from "#core/constants/channels.js";
 
 const log = loggerFor("super-agent");
 
+// Emit a single, readable line so `apx log -f` shows exactly what the skill
+// inspector decided this turn (which skills it loaded/hinted, the embedder, and
+// the top similarity). Best-effort: logging must never break a reply.
+function logInspectorDecision(trace, { trace_id, channel } = {}) {
+  if (!trace) return;
+  try {
+    const top = trace.scored?.[0];
+    const topStr = top ? ` top=${top.slug}@${top.sim}` : "";
+    log.info(`skill inspector: ${summarizeTrace(trace)} [${trace.embedder || "?"}]${topStr}`, {
+      trace_id,
+      channel,
+      loaded: trace.loaded || [],
+      hinted: trace.hinted || [],
+    });
+  } catch {
+    /* logging is best-effort */
+  }
+}
+
 // Persist human web turns to the cross-channel message store so they feed the
 // RAG index, search_messages, and the "active threads" awareness block. Only
 // the human surfaces (web big chat + sidebar) — not generic "api"/automation
@@ -79,10 +99,25 @@ export function register(app, { projects, registries, plugins, project, config }
     // slug is unknown.
     const slashed = tryResolveSkillCommand(rawPrompt, { projectPath: p.path });
     const prompt = slashed.handled ? slashed.prompt : rawPrompt;
+    const inspectorOn = isInspectorEnabled(config);
+    let inspectorTrace = null;
     if (slashed.handled) {
       ctx.contextNote = [ctx.contextNote, slashed.contextNote].filter(Boolean).join("\n\n");
+    } else if (inspectorOn) {
+      // Inspector middleware: per-turn semantic RAG. Replaces both the passive
+      // suggestSkillForPrompt nudge AND the static slug-dump in the system
+      // prompt — see runSuperAgent({ skipSkillsHint }).
+      const out = await inspectPromptForSkills({
+        prompt,
+        projectPath: p.path,
+        globalConfig: config,
+      });
+      inspectorTrace = out.trace;
+      if (out.contextNote) {
+        ctx.contextNote = [ctx.contextNote, out.contextNote].filter(Boolean).join("\n\n");
+      }
     } else {
-      // Semantic skill nudge — only when there was no explicit /slug.
+      // Legacy path — passive nudge, still works when inspector is off.
       const hint = await suggestSkillForPrompt(prompt, { projectPath: p.path });
       if (hint) ctx.contextNote = [ctx.contextNote, hint].filter(Boolean).join("\n\n");
     }
@@ -101,6 +136,14 @@ export function register(app, { projects, registries, plugins, project, config }
       channel: ctx.channel,
     });
 
+    // Surface the inspector decision to clients before model_start so the web
+    // debug panel / TUI can render "loaded: X" the moment the turn begins.
+    if (inspectorTrace) {
+      try { onEvent({ type: "skill_inspector", inspector: inspectorTrace }); }
+      catch { /* trace is best-effort */ }
+      logInspectorDecision(inspectorTrace, { trace_id: req.apxTraceId, channel: ctx.channel });
+    }
+
     // Web/TUI channels receive a "confirmation_required" SSE event and respond
     // via POST /super-agent/confirm/:correlationId (see api/confirm.js).
     const requestConfirmation = createWebConfirmAdapter({ onEvent });
@@ -122,6 +165,7 @@ export function register(app, { projects, registries, plugins, project, config }
         ...(completionContract ? { completionContract: true } : {}),
         onEvent,
         requestConfirmation,
+        skipSkillsHint: inspectorOn,
       });
       projects.rebuild(p.id);
       logWebTurn(ctx.channel, { prompt, replyText: saResult.text });
@@ -194,6 +238,16 @@ export function register(app, { projects, registries, plugins, project, config }
       req.body || {};
     if (!prompt) return res.status(400).json({ error: "prompt required" });
     const ctx = resolveSuperAgentContext(req, p);
+    const inspectorOn = isInspectorEnabled(config);
+    if (inspectorOn) {
+      try {
+        const out = await inspectPromptForSkills({ prompt, projectPath: p.path, globalConfig: config });
+        if (out.contextNote) {
+          ctx.contextNote = [ctx.contextNote, out.contextNote].filter(Boolean).join("\n\n");
+        }
+        logInspectorDecision(out.trace, { trace_id: req.apxTraceId, channel: ctx.channel });
+      } catch { /* inspector failure must not block the turn */ }
+    }
     try {
       const saResult = await runSuperAgent({
         globalConfig: config,
@@ -213,6 +267,7 @@ export function register(app, { projects, registries, plugins, project, config }
           trace_id: req.apxTraceId,
           channel: ctx.channel,
         }),
+        skipSkillsHint: inspectorOn,
       });
       projects.rebuild(p.id);
       logWebTurn(ctx.channel, { prompt, replyText: saResult.text });

package/src/host/daemon/index.js

@@ -218,6 +218,23 @@ async function main() {
     // store, and start the incremental RAG indexer. Best-effort — never blocks
     // boot and never throws into the daemon.
     initMemory({ config: cfg, log }).catch((e) => log(`memory: init failed: ${e?.message || e}`));
+    // Skill Inspector: if enabled, refresh its vector index in the background so
+    // any SKILL.md added/edited while the daemon was down is picked up without a
+    // manual `apx skills index`. Best-effort; never blocks boot.
+    (async () => {
+      try {
+        const { isInspectorEnabled } = await import("#core/agent/skills/inspector.js");
+        if (!isInspectorEnabled(cfg)) return;
+        const { backgroundRefreshIfStale } = await import("#core/agent/skills/index-store.js");
+        const r = backgroundRefreshIfStale({
+          embedOpts: { globalConfig: cfg },
+          onDone: (out) => log(`skill inspector: index refreshed (${out.embedder}, +${out.changed.added.length} -${out.changed.removed.length} ~${out.changed.refreshed.length})`),
+        });
+        if (r.started) log(`skill inspector: reindexing ${r.missing} new / ${r.stale} stale / ${r.gone} gone skills…`);
+      } catch (e) {
+        log(`skill inspector: index refresh skipped (${e?.message || e})`);
+      }
+    })();
     // Fire wake-up message after a short delay so plugins (Telegram) are ready
     setTimeout(() => triggerWakeup(cfg, log), 3000);
     // Preload whisper-server in the background so first desktop transcription is fast.

package/src/interfaces/cli/branding.js

@@ -0,0 +1,53 @@
+// APX CLI branding — a consistent "you're running APX vX" mark on every command.
+//
+// Two shapes:
+//   apxBanner(version, subtitle)  big ASCII wordmark for branding-heavy moments
+//                                 (onboarding, top-level entry). Loud on purpose.
+//   apxHeader(version, subtitle)  one-line "▸ APX CLI · vX · <subtitle>" for the
+//                                 everyday commands. Quiet, never in the way.
+//
+// Both write to STDERR so they never pollute piped stdout (`apx exec … | jq`,
+// `apx config show > file`). Like mascot.js, they always print (so the mark is
+// truly on every run), and self-suppress only when APX_QUIET / APX_NO_BANNER is
+// set — the escape hatch for scripts and CI.
+//
+// Color: reuses raw ANSI like mascot.js. Honors NO_COLOR.
+
+const NO_COLOR = !!process.env.NO_COLOR;
+const c = (code) => (s) => (NO_COLOR ? s : `\x1b[${code}m${s}\x1b[0m`);
+const B = c("1");
+const DI = c("2");
+const GR = c("32");
+const CY = c("36");
+const WH = c("97");
+
+function suppressed() {
+  return !!(process.env.APX_NO_BANNER || process.env.APX_QUIET);
+}
+
+// Compact, single-line header. The default for everyday subcommands.
+//   ▸ APX CLI · v1.34.0 · skills inspector
+export function apxHeader(version, subtitle = "") {
+  if (suppressed()) return;
+  const tag = `${GR("▸")} ${B(WH("APX"))} ${DI("CLI")}`;
+  const ver = DI(`v${version}`);
+  const sub = subtitle ? `  ${DI("·")}  ${CY(subtitle)}` : "";
+  process.stderr.write(`\n${tag}  ${DI("·")}  ${ver}${sub}\n\n`);
+}
+
+// Big ASCII wordmark for branding-heavy commands.
+export function apxBanner(version, subtitle = "") {
+  if (suppressed()) return;
+  const g = (s) => GR(s);
+  const lines = [
+    "",
+    `  ${g("█████╗ ██████╗ ██╗  ██╗")}`,
+    `  ${g("██╔══██╗██╔══██╗╚██╗██╔╝")}`,
+    `  ${g("███████║██████╔╝ ╚███╔╝ ")}   ${B(WH("Agent Project Context"))}`,
+    `  ${g("██╔══██║██╔═══╝  ██╔██╗ ")}   ${DI(`v${version}`)}`,
+    `  ${g("██║  ██║██║     ██╔╝ ██╗")}${subtitle ? `   ${CY(subtitle)}` : ""}`,
+    `  ${g("╚═╝  ╚═╝╚═╝     ╚═╝  ╚═╝")}`,
+    "",
+  ];
+  process.stderr.write(lines.join("\n") + "\n");
+}