@agentprojectcontext/apx 1.31.2 → 1.32.2

package/src/interfaces/web/src/i18n/es.ts

@@ -287,8 +287,8 @@ export const es = {
     chat: {
       title:       "Chat con agente",
       subtitle:    "Conversaciones directas con agentes del proyecto. El super-agent no interviene.",
-      roby_title:  "Chat con Roby",
-      roby_subtitle: "Chat con Roby — el super-agente APX. Puede usar tools (proyectos, tasks, mcps, agentes).",
+      superagent_title:  "Chat con {persona}",
+      superagent_subtitle: "Chat con {persona} — el super-agente APX. Puede usar tools (proyectos, tasks, mcps, agentes).",
       empty:       "Mandá un mensaje para arrancar la conversación.",
       placeholder: "Escribí algo y enter para enviar (shift+enter = nueva línea)",
       send:        "Enviar",
@@ -711,13 +711,13 @@ export const es = {
     delete_btn:  "Borrar",
   },
 
-  roby: {
-    title:          "Roby",
+  superagent: {
+    title:          "{persona}",
     badge:          "super-agent · APX",
     desc:           "Conversación rápida con tu super-agente. Tiene acceso a tools (proyectos, tasks, mcps, agentes); para un hilo más largo y persistente, abrí Chats.",
-    empty:          "Mandale un mensaje a Roby para arrancar.",
-    thinking:       "Roby está pensando…",
-    talk:           "Hablar con Roby",
+    empty:          "Mandale un mensaje a {persona} para arrancar.",
+    thinking:       "{persona} está pensando…",
+    talk:           "Hablar con {persona}",
     new_chat:       "Nuevo chat",
     placeholder:    "Escribí y enter para enviar (shift+enter = nueva línea)…",
   },
@@ -727,6 +727,18 @@ export const es = {
     message: "Esa ruta no existe.",
   },
 
+  ask_panel: {
+    answers_header: "Respuestas",
+    other:          "Otro",
+    other_placeholder: "Escribí tu propia respuesta acá",
+    text_placeholder:  "Escribí tu respuesta…",
+    back:           "Atrás",
+    skip:           "Omitir",
+    next:           "Siguiente",
+    submit:         "Enviar",
+    status_waiting: "Esperando respuesta…",
+    status_received: "Respuestas recibidas",
+  },
   code_module: {
     title:        "Code",
     badge:        "super-agent",
@@ -748,6 +760,14 @@ export const es = {
     mode_plan_hint:  "Plan — solo lectura, propone cambios sin tocar archivos",
     tab_context:  "Contexto",
     tab_changes:  "Cambios",
+    tab_artifacts: "Artifacts",
+    artifacts_none: "Todavía no hay artifacts. Pedile al agente que cree un script en `artifacts/<nombre>`.",
+    artifacts_count: "{n} artifact(s)",
+    artifacts_copy_path: "Copiar path",
+    artifacts_run: "Run",
+    artifacts_run_hint: "Para ejecutarlo desde la terminal:",
+    artifacts_delete: "Eliminar",
+    artifacts_delete_confirm: "¿Eliminar este artifact? El archivo se borra del disco.",
     ctx_model:    "Modelo",
     ctx_tokens:   "Tokens",
     ctx_input:    "Entrada",

package/src/interfaces/web/src/lib/api/artifacts.ts

@@ -0,0 +1,47 @@
+import { http } from "../http";
+
+export interface ArtifactEntry {
+  name: string;
+  path: string;
+  size: number;
+  modified: string;
+}
+
+export interface ArtifactContent {
+  name: string;
+  path: string;
+  content: string;
+}
+
+// Shape of POST /projects/:pid/artifacts/:name/run. On success the daemon
+// returns the captured stdout/stderr and exit metadata; on 4xx an error
+// payload is thrown by the http client instead.
+export interface ArtifactRunResult {
+  ok: boolean;
+  exitCode?: number | null;
+  signal?: string | null;
+  timedOut?: boolean;
+  truncated?: boolean;
+  stdout?: string;
+  stderr?: string;
+  durationMs?: number;
+  error?: string;
+}
+
+export const Artifacts = {
+  list: (pid: string) =>
+    http.get<ArtifactEntry[]>(`/projects/${encodeURIComponent(pid)}/artifacts`),
+  read: (pid: string, name: string) =>
+    http.get<ArtifactContent>(
+      `/projects/${encodeURIComponent(pid)}/artifacts/${encodeURIComponent(name)}`,
+    ),
+  run: (pid: string, name: string, args: string[] = []) =>
+    http.post<ArtifactRunResult>(
+      `/projects/${encodeURIComponent(pid)}/artifacts/${encodeURIComponent(name)}/run`,
+      { args },
+    ),
+  remove: (pid: string, name: string) =>
+    http.del<void>(
+      `/projects/${encodeURIComponent(pid)}/artifacts/${encodeURIComponent(name)}`,
+    ),
+};

package/src/interfaces/web/src/lib/api/skills.ts

@@ -0,0 +1,25 @@
+import { http } from "../http";
+
+export type SkillEntry = {
+  slug: string;
+  source: "bundled" | "user" | "project" | string;
+  description: string;
+};
+
+export type SkillsList = {
+  count: number;
+  skills: SkillEntry[];
+};
+
+export const Skills = {
+  /**
+   * List installed skills (bundled + user + optional project-scoped). The
+   * description is already condensed for one-line rendering.
+   */
+  list: (projectPath?: string) =>
+    http.get<SkillsList>(
+      projectPath
+        ? `/skills?project_path=${encodeURIComponent(projectPath)}`
+        : "/skills",
+    ),
+};

package/src/interfaces/web/src/lib/api.ts

@@ -21,6 +21,8 @@ export * from "./api/filesystem";
 export * from "./api/voice";
 export * from "./api/deck";
 export * from "./api/code";
+export * from "./api/artifacts";
+export * from "./api/skills";
 
 // Re-export the daemon types so older imports of "../lib/api" still work.
 export type {

package/src/interfaces/web/src/screens/modules/CodeScreen.tsx

@@ -1,13 +1,14 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import useSWR from "swr";
-import { Code2 } from "lucide-react";
 import { Code, Projects } from "../../lib/api";
 import { Badge, Empty, Loading } from "../../components/ui";
+import { useSetPageLabel } from "../../hooks/useNavCollapseCtx";
 import { MessageList } from "../../components/chat/MessageList";
 import { CodeProjectPicker } from "../../components/code/CodeProjectPicker";
 import { CodeSessionList } from "../../components/code/CodeSessionList";
 import { CodeComposer } from "../../components/code/CodeComposer";
 import { CodeSidePanel } from "../../components/code/CodeSidePanel";
+import { InlineAskPanel, pendingAskQuestions } from "../../components/chat/InlineAskPanel";
 import { useToast } from "../../components/Toast";
 import { t } from "../../i18n";
 import { applyStreamEvent, textOf, type ChatMsg } from "../../hooks/useChat";
@@ -151,8 +152,8 @@ export function CodeScreen() {
       return copy;
     });
 
-  const send = async () => {
-    const prompt = draft.trim();
+  const send = async (overridePrompt?: string) => {
+    const prompt = (overridePrompt ?? draft).trim();
     if (!prompt || busy || !pid || !sid) return;
     const now = new Date().toISOString();
     setMsgs((curr) => [
@@ -208,27 +209,34 @@ export function CodeScreen() {
 
   const hasProjects = !projects.isLoading && projectList.length > 0;
   const turns: CodeTurn[] = useMemo(() => msgs as unknown as CodeTurn[], [msgs]);
+  const activeTitle = useMemo(
+    () => sessions.data?.find((s) => s.id === sid)?.title || "",
+    [sessions.data, sid],
+  );
+  useSetPageLabel(activeTitle);
 
-  return (
-    <div className="flex h-full min-h-0 flex-col overflow-hidden p-4" data-testid="screen-code">
-      <header className="mb-3 flex items-center justify-between gap-3">
-        <div className="min-w-0">
-          <h1 className="flex items-center gap-2 text-2xl font-bold tracking-tight">
-            <Code2 size={22} /> {t("code_module.title")}
-          </h1>
-          <p className="text-sm text-muted-fg">{t("code_module.desc")}</p>
-        </div>
-        <Badge tone="success">{t("code_module.badge")}</Badge>
-      </header>
+  // Detect unanswered ask_questions in the last assistant turn. Local "dismissed"
+  // ref keys off the turn id so the panel re-appears for a fresh batch.
+  const [dismissedKey, setDismissedKey] = useState<string | null>(null);
+  const pending = !busy ? pendingAskQuestions(msgs) : null;
+  const askVisible = pending && pending.turnKey !== dismissedKey;
 
+  const submitAnswers = (compiled: string) => {
+    void send(compiled);
+  };
+
+  return (
+    <div className="flex h-full min-h-0" data-testid="screen-code">
       {projects.isLoading ? (
         <Loading />
       ) : !hasProjects ? (
-        <Empty>{t("code_module.no_projects")}</Empty>
+        <div className="grid flex-1 place-items-center">
+          <Empty>{t("code_module.no_projects")}</Empty>
+        </div>
       ) : (
-        <div className="flex min-h-0 flex-1 overflow-hidden rounded-xl border border-border bg-card/40">
-          {/* Left rail: project picker + session list */}
-          <aside className="flex w-60 shrink-0 flex-col border-r border-border">
+        <>
+          {/* Left: project picker + session list */}
+          <aside className="flex w-52 shrink-0 flex-col border-r border-border">
             <div className="shrink-0 border-b border-border p-2">
               <CodeProjectPicker
                 projects={projectList}
@@ -246,6 +254,9 @@ export function CodeScreen() {
               onRename={onRenameSession}
               onDelete={onDeleteSession}
             />
+            <div className="shrink-0 border-t border-border px-3 py-2">
+              <Badge tone="success">{t("code_module.badge")}</Badge>
+            </div>
           </aside>
 
           {/* Center: transcript + composer */}
@@ -263,6 +274,15 @@ export function CodeScreen() {
                 </div>
               )}
             </div>
+            {askVisible && pending && (
+              <InlineAskPanel
+                turnKey={pending.turnKey}
+                questions={pending.questions}
+                onSubmit={submitAnswers}
+                onDismiss={() => setDismissedKey(pending.turnKey)}
+                disabled={busy}
+              />
+            )}
             <div className="border-t border-border bg-card/60 p-3" data-testid="code-input">
               <CodeComposer
                 value={draft}
@@ -280,15 +300,16 @@ export function CodeScreen() {
           </main>
 
           {/* Right: context + changes */}
-          <aside className="hidden w-80 shrink-0 flex-col border-l border-border lg:flex">
+          <aside className="hidden w-72 shrink-0 flex-col border-l border-border lg:flex">
             <CodeSidePanel
+              pid={pid}
               turns={turns}
               changes={changes.data}
               changesLoading={changes.isLoading}
               onRefreshChanges={() => void changes.mutate()}
             />
           </aside>
-        </div>
+        </>
       )}
     </div>
   );

package/src/interfaces/web/src/screens/modules/DeckScreen.tsx

@@ -76,24 +76,6 @@ export function DeckScreen() {
 
   return (
     <div className="mx-auto max-w-4xl space-y-6 p-6" data-testid="screen-deck">
-      <header className="flex items-start justify-between gap-4">
-        <div>
-          <h1 className="text-2xl font-bold tracking-tight">Deck</h1>
-          <p className="text-sm text-muted-fg">
-            App companion · widgets y escritorios.
-          </p>
-        </div>
-        <Button
-          size="sm"
-          variant="ghost"
-          onClick={() => mutate()}
-          disabled={isLoading}
-          title="Recargar manifest"
-        >
-          <RefreshCw size={14} className={isLoading ? "animate-spin" : ""} />
-        </Button>
-      </header>
-
       {/* Daemon info card */}
       {data && <DaemonCard manifest={data} />}
 
@@ -107,6 +89,11 @@ export function DeckScreen() {
             ? "Error al cargar el manifest."
             : `${widgets.length} widgets · ${enabledCount} externos habilitados`
         }
+        action={
+          <Button size="sm" variant="ghost" onClick={() => mutate()} disabled={isLoading} title="Recargar manifest">
+            <RefreshCw size={14} className={isLoading ? "animate-spin" : ""} />
+          </Button>
+        }
       >
         {isLoading && <Loading label="Cargando manifest del Deck…" />}
 

package/src/interfaces/web/src/screens/modules/DesktopScreen.tsx

@@ -96,15 +96,8 @@ export function DesktopScreen() {
 
   return (
     <div className="mx-auto max-w-6xl space-y-6 p-6" data-testid="screen-desktop">
-      <header>
-        <h1 className="text-2xl font-bold tracking-tight">Escritorio</h1>
-        <p className="text-sm text-muted-fg">
-          Ventana flotante de voz (Electron): atajo global, escucha por micrófono y muestra el chat.
-        </p>
-      </header>
-
       {/* ── Two-column layout: config on the left, last conversation on the right. ── */}
-      <div className="grid gap-6 lg:grid-cols-[1fr_1fr]">
+      <div className="grid gap-6 xl:grid-cols-[1fr_1fr]">
         {/* ── LEFT: configuration + status ─────────────────────────────── */}
         <div className="space-y-6">
           <Section title="Estado" description="La ventana se lanza desde la terminal o por autostart.">

package/src/interfaces/web/src/screens/modules/VoiceScreen.tsx

@@ -119,48 +119,47 @@ export function VoiceScreen() {
   };
 
   return (
-    <div className="mx-auto max-w-4xl space-y-6 p-6" data-testid="screen-voice">
-      <header>
-        <h1 className="text-2xl font-bold tracking-tight">Voces</h1>
-        <p className="text-sm text-muted-fg">
-          Configurá el texto a voz (TTS) y la transcripción (STT), elegí el motor por defecto y probá la voz.
-        </p>
-      </header>
+    <div className="mx-auto max-w-6xl p-6" data-testid="screen-voice">
+      <div className="grid gap-6 xl:grid-cols-2">
+        {/* Left: TTS providers */}
+        <Section
+          title="Proveedores de voz (TTS)"
+          description="Motores de síntesis. El estado lo reporta el daemon en vivo. Elegí cuál usar por defecto."
+        >
+          {provLoading || cfgLoading ? (
+            <Loading />
+          ) : provError ? (
+            <Empty>No se pudieron cargar los proveedores: {(provError as Error).message}</Empty>
+          ) : (
+            <VoiceProviderList
+              engines={engines}
+              order={order}
+              mode={mode}
+              configuredProvider={configuredProvider}
+              onSetMode={setMode}
+              onSetDefault={setDefault}
+              onToggleEnabled={toggleEnabled}
+              onReorder={reorder}
+              onConfigure={(id) => setEditing(id)}
+              busy={busyDefault}
+            />
+          )}
+        </Section>
 
-      <Section
-        title="Proveedores de voz (TTS)"
-        description="Motores de síntesis. El estado lo reporta el daemon en vivo. Elegí cuál usar por defecto."
-      >
-        {provLoading || cfgLoading ? (
-          <Loading />
-        ) : provError ? (
-          <Empty>No se pudieron cargar los proveedores: {(provError as Error).message}</Empty>
-        ) : (
-          <VoiceProviderList
-            engines={engines}
-            order={order}
-            mode={mode}
-            configuredProvider={configuredProvider}
-            onSetMode={setMode}
-            onSetDefault={setDefault}
-            onToggleEnabled={toggleEnabled}
-            onReorder={reorder}
-            onConfigure={(id) => setEditing(id)}
-            busy={busyDefault}
-          />
-        )}
-      </Section>
+        {/* Right: test + STT */}
+        <div className="space-y-6">
+          <Section title="Probar voz" description='Elegí con qué motor sintetizar y, si aplica, cómo querés que hable.'>
+            <VoiceTestCard engines={engines} defaultProvider={configuredProvider} mode={mode} />
+          </Section>
 
-      <Section title="Probar voz" description='Elegí con qué motor sintetizar y, si aplica, cómo querés que hable.'>
-        <VoiceTestCard engines={engines} defaultProvider={configuredProvider} mode={mode} />
-      </Section>
-
-      <Section
-        title="Transcripción (STT)"
-        description="Motor de voz a texto que usan el deck, Telegram y la CLI al escuchar."
-      >
-        {cfgLoading ? <Loading /> : <VoiceSttCard config={transcriptionCfg} onPatch={patchStt} />}
-      </Section>
+          <Section
+            title="Transcripción (STT)"
+            description="Motor de voz a texto que usan el deck, Telegram y la CLI al escuchar."
+          >
+            {cfgLoading ? <Loading /> : <VoiceSttCard config={transcriptionCfg} onPatch={patchStt} />}
+          </Section>
+        </div>
+      </div>
 
       <VoiceProviderModal
         open={!!editing}

package/src/interfaces/web/src/screens/project/ChatTab.tsx

@@ -8,9 +8,11 @@ import { UiSelect } from "../../components/UiSelect";
 import { Composer } from "../../components/chat/Composer";
 import { MessageList } from "../../components/chat/MessageList";
 import { ContextBar } from "../../components/chat/ContextBar";
+import { InlineAskPanel, pendingAskQuestions } from "../../components/chat/InlineAskPanel";
 import { useChat } from "../../hooks/useChat";
 import { useToast } from "../../components/Toast";
 import { t } from "../../i18n";
+import { usePersonaName } from "../../hooks/usePersonaName";
 import type { AgentEntry } from "../../types/daemon";
 
 // Virtual entry slug used in the agent dropdown to address the daemon-level
@@ -25,19 +27,21 @@ export function ChatTab({ pid }: { pid: string }) {
   const [activeSlug, setActiveSlug] = useState(params.get("agent") || "");
   const [creating, setCreating] = useState(false);
   const [model, setModel] = useState("");
+  const [dismissedAskKey, setDismissedAskKey] = useState<string | null>(null);
   const { msgs, send: sendChat, stop, clear, streaming } = useChat(pid, (m) => toast.error(m));
+  const persona = usePersonaName();
 
   const agentList = agents.data || [];
-  // Virtual options shown in the dropdown — Roby is always first, then the
-  // real project agents. Roby works on every project (calls /projects/:pid
-  // /super-agent/chat) so we expose it everywhere, not just /base.
+  // Virtual options shown in the dropdown — the super-agent is always first,
+  // then the real project agents. It works on every project (calls
+  // /projects/:pid/super-agent/chat) so we expose it everywhere, not just /base.
   const isRoby = (slug: string | null | undefined) => slug === ROBY_SLUG;
   const dropdownOptions = useMemo(
     () => [
-      { value: ROBY_SLUG, label: "Roby (super-agent)" },
+      { value: ROBY_SLUG, label: `${persona} (super-agent)` },
       ...agentList.map((a) => ({ value: a.slug, label: a.slug })),
     ],
-    [agentList],
+    [agentList, persona],
   );
   const activeAgent = useMemo(
     () => agentList.find((a) => a.slug === activeSlug) || agentList[0],
@@ -73,10 +77,11 @@ export function ChatTab({ pid }: { pid: string }) {
 
   if (agents.isLoading) return <Loading />;
 
-  // Header subtitle differs: with Roby selected the chat goes through the
-  // super-agent (it CAN call tools); a project agent is a direct LLM call.
+  // Header subtitle differs: with the super-agent selected the chat goes
+  // through the super-agent loop (it CAN call tools); a project agent is a
+  // direct LLM call.
   const headerSubtitle = activeIsRoby
-    ? t("project.chat.roby_subtitle")
+    ? t("project.chat.superagent_subtitle", { persona })
     : t("project.chat.subtitle");
 
   return (
@@ -84,7 +89,7 @@ export function ChatTab({ pid }: { pid: string }) {
       <header className="flex shrink-0 items-center justify-between gap-3 border-b border-border px-4 py-3">
         <div className="min-w-0">
           <h2 className="text-sm font-semibold">
-            {activeIsRoby ? t("project.chat.roby_title") : t("project.chat.title")}
+            {activeIsRoby ? t("project.chat.superagent_title", { persona }) : t("project.chat.title")}
           </h2>
           <p className="truncate text-[11px] text-muted-fg">{headerSubtitle}</p>
         </div>
@@ -117,6 +122,19 @@ export function ChatTab({ pid }: { pid: string }) {
         )}
       </div>
       <ContextBar msgs={msgs} />
+      {(() => {
+        const pending = !streaming ? pendingAskQuestions(msgs) : null;
+        if (!pending || pending.turnKey === dismissedAskKey) return null;
+        return (
+          <InlineAskPanel
+            turnKey={pending.turnKey}
+            questions={pending.questions}
+            onSubmit={(compiled) => void send(compiled)}
+            onDismiss={() => setDismissedAskKey(pending.turnKey)}
+            disabled={streaming}
+          />
+        );
+      })()}
       <Composer
         onSend={send}
         onStop={stop}

package/src/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/`.