@agent-native/core 0.122.3 → 0.123.0

package/corpus/templates/clips/server/routes/api/uploads/[recordingId]/chunk.post.ts

@@ -38,7 +38,6 @@ import { getDb, schema } from "../../../../db/index.js";
 import { debugLog } from "../../../../lib/debug.js";
 import {
   deleteRecordingChunks,
-  pruneStaleRecordingChunks,
   sumRecordingChunkBytes,
 } from "../../../../lib/recording-upload-state.js";
 import {
@@ -52,6 +51,7 @@ import {
 } from "../../../../lib/resumable-session.js";
 import { resolveResumableUploadProvider } from "../../../../lib/resumable-upload-provider.js";
 import { isStreamingUploadDisabled } from "../../../../lib/streaming-upload-mode.js";
+import { renewUploadLease } from "../../../../lib/upload-lease.js";
 import {
   allowsSqlRecordingChunkScratch,
   shouldRejectVideoUploadWithoutStorage,
@@ -211,25 +211,14 @@ export default defineEventHandler(async (event: H3Event) => {
   debugLog("[chunk] resolved owner:", ownerEmail);
 
   return runWithRequestContext({ userEmail: ownerEmail, orgId }, async () => {
-    await pruneStaleRecordingChunks(ownerEmail).catch((err) => {
-      console.warn("[chunk] stale recording chunk prune failed:", {
-        ownerEmail,
-        err: err instanceof Error ? err.message : String(err),
-      });
-    });
-
     const db = getDb();
 
-    // Verify the recording belongs to the current user.
+    // Verify the recording belongs to the current user. Everything else about
+    // its state comes back from the lease renewal below.
     const [existing] = await db
       .select({
         id: schema.recordings.id,
         status: schema.recordings.status,
-        failureReason: schema.recordings.failureReason,
-        ownerEmail: schema.recordings.ownerEmail,
-        videoUrl: schema.recordings.videoUrl,
-        videoSizeBytes: schema.recordings.videoSizeBytes,
-        durationMs: schema.recordings.durationMs,
       })
       .from(schema.recordings)
       .where(
@@ -247,6 +236,68 @@ export default defineEventHandler(async (event: H3Event) => {
       throw createError({ statusCode: 404, message: "Recording not found" });
     }
 
+    const failedUploadResponse = (reason: string, bytes?: number) => {
+      setResponseStatus(
+        event,
+        reason === RECORDING_TOO_LARGE_REASON ? 413 : 409,
+      );
+      return {
+        ok: false,
+        error: reason,
+        bytesReceived: bytes,
+        maxBytes: MAX_RECORDING_UPLOAD_BYTES,
+      };
+    };
+
+    // The first renewal admits the request. Later renewals immediately before
+    // every durable write/finalization boundary close the body-read/provider
+    // gap where /abort can otherwise commit while this request is in flight.
+    const lease = await renewUploadLease(recordingId, {
+      uploadProgress:
+        total > 0
+          ? Math.min(100, Math.round(((index + 1) / total) * 100))
+          : undefined,
+    });
+    if (!lease.held) {
+      if (lease.status === "ready") {
+        const readyState = await readAppState(
+          `recording-upload-${recordingId}`,
+        ).catch(() => null);
+        return {
+          ok: true,
+          finalized: true,
+          status: "ready" as const,
+          videoUrl: lease.videoUrl,
+          videoSizeBytes: lease.videoSizeBytes,
+          durationMs: lease.durationMs,
+          sourceSizeBytes: stateNumber(readyState, "sourceSizeBytes"),
+        };
+      }
+      await deleteRecordingChunks(ownerEmail, recordingId).catch((err) => {
+        console.warn("[chunk] failed upload chunk cleanup failed:", {
+          recordingId,
+          err: err instanceof Error ? err.message : String(err),
+        });
+      });
+      return failedUploadResponse(
+        lease.failureReason ?? "Recording upload has already failed.",
+      );
+    }
+
+    const rejectIfLeaseLost = async () => {
+      const current = await renewUploadLease(recordingId);
+      if (current.held) return null;
+      await deleteRecordingChunks(ownerEmail, recordingId).catch((err) => {
+        console.warn("[chunk] failed upload chunk cleanup failed:", {
+          recordingId,
+          err: err instanceof Error ? err.message : String(err),
+        });
+      });
+      return failedUploadResponse(
+        current.failureReason ?? "Recording upload has already failed.",
+      );
+    };
+
     if (isFinal && existing.status === "processing") {
       const pendingState = pendingMediaVerificationState(
         await readAppState(`recording-upload-${recordingId}`).catch(() => null),
@@ -276,44 +327,10 @@ export default defineEventHandler(async (event: H3Event) => {
       );
     }
 
-    const failedUploadResponse = (reason: string, bytes?: number) => {
-      setResponseStatus(
-        event,
-        reason === RECORDING_TOO_LARGE_REASON ? 413 : 409,
-      );
-      return {
-        ok: false,
-        error: reason,
-        bytesReceived: bytes,
-        maxBytes: MAX_RECORDING_UPLOAD_BYTES,
-      };
-    };
-
-    if (existing.status === "failed") {
-      return failedUploadResponse(
-        existing.failureReason ?? "Recording upload has already failed.",
-      );
-    }
-
-    // Already finalized — retried final chunk after session was deleted. Skip
-    // buffered path writes so recording-upload-* state stays correct.
-    if (existing.status === "ready") {
-      const readyState = await readAppState(
-        `recording-upload-${recordingId}`,
-      ).catch(() => null);
-      return {
-        ok: true,
-        finalized: true,
-        status: "ready" as const,
-        videoUrl: existing.videoUrl,
-        videoSizeBytes: existing.videoSizeBytes,
-        durationMs: existing.durationMs,
-        sourceSizeBytes: stateNumber(readyState, "sourceSizeBytes"),
-      };
-    }
-
     // Store chunks in application_state, assemble on finalize.
     if (await shouldRejectVideoUploadWithoutStorage()) {
+      const leaseFailure = await rejectIfLeaseLost();
+      if (leaseFailure) return leaseFailure;
       const now = new Date().toISOString();
       await db
         .update(schema.recordings)
@@ -379,61 +396,11 @@ export default defineEventHandler(async (event: H3Event) => {
       uploadStateRaw && typeof uploadStateRaw === "object"
         ? uploadStateRaw
         : null;
-    const failedReason =
-      typeof uploadState?.failureReason === "string"
-        ? uploadState.failureReason
-        : RECORDING_TOO_LARGE_REASON;
-    if (uploadState?.status === "failed") {
-      return failedUploadResponse(failedReason);
-    }
     let bytesReceived = stateNumber(uploadState, "bytesReceived") ?? 0;
 
-    const stopIfUploadFailed = async () => {
-      const latestState = await readAppState(`recording-upload-${recordingId}`);
-      const latestReason =
-        latestState && typeof latestState.failureReason === "string"
-          ? latestState.failureReason
-          : "Recording upload has already failed.";
-      if (latestState?.status === "failed") {
-        await deleteRecordingChunks(ownerEmail, recordingId).catch((err) => {
-          console.warn("[chunk] failed upload chunk cleanup failed:", {
-            recordingId,
-            err: err instanceof Error ? err.message : String(err),
-          });
-        });
-        return failedUploadResponse(latestReason);
-      }
-
-      const [current] = await db
-        .select({
-          status: schema.recordings.status,
-          failureReason: schema.recordings.failureReason,
-        })
-        .from(schema.recordings)
-        .where(eq(schema.recordings.id, recordingId));
-      if (current?.status === "failed") {
-        const reason =
-          current.failureReason ?? "Recording upload has already failed.";
-        await deleteRecordingChunks(ownerEmail, recordingId).catch((err) => {
-          console.warn("[chunk] failed recording chunk cleanup failed:", {
-            recordingId,
-            err: err instanceof Error ? err.message : String(err),
-          });
-        });
-        await writeAppState(`recording-upload-${recordingId}`, {
-          recordingId,
-          status: "failed",
-          failureReason: reason,
-          bytesReceived: await sumRecordingChunkBytes(ownerEmail, recordingId),
-          maxBytes: MAX_RECORDING_UPLOAD_BYTES,
-          updatedAt: new Date().toISOString(),
-        });
-        return failedUploadResponse(reason);
-      }
-      return null;
-    };
-
     const failRecordingTooLarge = async (nextBytes: number) => {
+      const leaseFailure = await rejectIfLeaseLost();
+      if (leaseFailure) return leaseFailure;
       const now = new Date().toISOString();
       await db
         .update(schema.recordings)
@@ -468,11 +435,7 @@ export default defineEventHandler(async (event: H3Event) => {
 
     // Only persist non-empty chunks. The final sentinel can legitimately be
     // empty — writing a zero-byte chunk would just clutter application_state.
-    // Check for abort/failure before writing so parallel in-flight requests
-    // don't recreate scratch chunk rows after /abort already cleared them.
     if (bytes.byteLength > 0) {
-      const failedBeforeWrite = await stopIfUploadFailed();
-      if (failedBeforeWrite) return failedBeforeWrite;
       // Pad index to 6 digits so string-sort order matches numeric order if the
       // finalize path ever sorts lexically. (finalize also parses back to a number.)
       const paddedIndex = String(index).padStart(6, "0");
@@ -490,6 +453,8 @@ export default defineEventHandler(async (event: H3Event) => {
         return failRecordingTooLarge(nextBytes);
       }
 
+      const leaseFailure = await rejectIfLeaseLost();
+      if (leaseFailure) return leaseFailure;
       await writeAppState(chunkKey, {
         recordingId,
         index,
@@ -510,8 +475,6 @@ export default defineEventHandler(async (event: H3Event) => {
     // max of the current persisted value and the incoming index to keep
     // progress monotonically non-decreasing.
     if (total > 0) {
-      const failedResponse = await stopIfUploadFailed();
-      if (failedResponse) return failedResponse;
       const chunksReceived = Math.max(
         stateNumber(uploadState, "chunksReceived") ?? 0,
         index + 1,
@@ -520,6 +483,8 @@ export default defineEventHandler(async (event: H3Event) => {
         stateNumber(uploadState, "progress") ?? 0,
         Math.min(100, Math.round((chunksReceived / total) * 100)),
       );
+      const leaseFailure = await rejectIfLeaseLost();
+      if (leaseFailure) return leaseFailure;
       await writeAppState(`recording-upload-${recordingId}`, {
         recordingId,
         status: isFinal ? "processing" : "uploading",
@@ -538,21 +503,9 @@ export default defineEventHandler(async (event: H3Event) => {
         mimeType,
         updatedAt: new Date().toISOString(),
       });
-      const failedAfterStateWrite = await stopIfUploadFailed();
-      if (failedAfterStateWrite) return failedAfterStateWrite;
-
-      await db
-        .update(schema.recordings)
-        .set({ uploadProgress: progress, updatedAt: new Date().toISOString() })
-        .where(
-          and(
-            eq(schema.recordings.id, recordingId),
-            eq(schema.recordings.status, existing.status),
-          ),
-        );
     } else if (bytes.byteLength > 0 || isFinal) {
-      const failedResponse = await stopIfUploadFailed();
-      if (failedResponse) return failedResponse;
+      const leaseFailure = await rejectIfLeaseLost();
+      if (leaseFailure) return leaseFailure;
       await writeAppState(`recording-upload-${recordingId}`, {
         recordingId,
         status: isFinal ? "processing" : "uploading",
@@ -572,19 +525,19 @@ export default defineEventHandler(async (event: H3Event) => {
         mimeType,
         updatedAt: new Date().toISOString(),
       });
-      const failedAfterStateWrite = await stopIfUploadFailed();
-      if (failedAfterStateWrite) return failedAfterStateWrite;
     }
 
     // Final chunk — kick off finalize. We await so the client gets a single
     // "done" response with the final URL (instead of needing to poll).
     if (isFinal) {
+      const leaseFailure = await rejectIfLeaseLost();
+      if (leaseFailure) return leaseFailure;
       bytesReceived = await sumRecordingChunkBytes(ownerEmail, recordingId);
       if (bytesReceived > MAX_RECORDING_UPLOAD_BYTES) {
         return failRecordingTooLarge(bytesReceived);
       }
-      const failedResponse = await stopIfUploadFailed();
-      if (failedResponse) return failedResponse;
+      const finalLease = await rejectIfLeaseLost();
+      if (finalLease) return finalLease;
       debugLog("[chunk] isFinal — invoking finalize", { recordingId });
       try {
         const result = await finalizeRecording.run(
@@ -818,6 +771,14 @@ async function handleResumableChunk(
         error: "Cannot finalize an empty resumable upload",
       };
     }
+    const lease = await renewUploadLease(recordingId);
+    if (!lease.held) {
+      setResponseStatus(event, 409);
+      return {
+        ok: false,
+        error: lease.failureReason ?? "Recording upload has already failed.",
+      };
+    }
     // 0-byte sentinel from the recorder after stop(). All data chunks have
     // already been PUT to the provider; send Content-Range: bytes */<total>
     // to close the session before handing off to finalize-recording.
@@ -837,6 +798,16 @@ async function handleResumableChunk(
       };
     }
     if (closeRes.updatedMeta) {
+      const postCloseLease = await renewUploadLease(recordingId);
+      if (!postCloseLease.held) {
+        setResponseStatus(event, 409);
+        return {
+          ok: false,
+          error:
+            postCloseLease.failureReason ??
+            "Recording upload has already failed.",
+        };
+      }
       await setResumableSession(recordingId, {
         ...session,
         meta: { ...session.meta, ...closeRes.updatedMeta },
@@ -864,6 +835,14 @@ async function handleResumableChunk(
         };
       }
     } else {
+      const lease = await renewUploadLease(recordingId);
+      if (!lease.held) {
+        setResponseStatus(event, 409);
+        return {
+          ok: false,
+          error: lease.failureReason ?? "Recording upload has already failed.",
+        };
+      }
       // Forward the data chunk to the provider and advance offsets only after
       // the provider confirms receipt (308 Resume Incomplete for non-final, 2xx for final).
       const start = session.bytesUploaded;
@@ -894,6 +873,16 @@ async function handleResumableChunk(
         };
       }
 
+      const postUploadLease = await renewUploadLease(recordingId);
+      if (!postUploadLease.held) {
+        setResponseStatus(event, 409);
+        return {
+          ok: false,
+          error:
+            postUploadLease.failureReason ??
+            "Recording upload has already failed.",
+        };
+      }
       await setResumableSession(recordingId, {
         ...session,
         ...(putResult.updatedMeta
@@ -912,6 +901,14 @@ async function handleResumableChunk(
 
   // isFinal — delegate to finalize-recording, which reads the resumable
   // session and calls provider.resumable.completeSession.
+  const finalLease = await renewUploadLease(recordingId);
+  if (!finalLease.held) {
+    setResponseStatus(event, 409);
+    return {
+      ok: false,
+      error: finalLease.failureReason ?? "Recording upload has already failed.",
+    };
+  }
   try {
     const result = await finalizeRecording.run(
       buildFinalizeArgs(recordingId, mimeType, query),

package/corpus/templates/clips/server/routes/api/uploads/[recordingId]/reset-chunks.post.ts

@@ -52,6 +52,7 @@ import {
   setResumableSession,
 } from "../../../../lib/resumable-session.js";
 import { shouldEnableStreamingUpload } from "../../../../lib/streaming-upload-mode.js";
+import { uploadLeaseExpiry } from "../../../../lib/upload-lease.js";
 import { allowsSqlRecordingChunkScratch } from "../../../../lib/video-storage.js";
 
 interface CompressionMeta {
@@ -250,6 +251,9 @@ export default defineEventHandler(async (event: H3Event) => {
         status: "uploading",
         failureReason: null,
         uploadProgress: 0,
+        // A retry re-takes the lease. Without this the row would go back to
+        // 'uploading' still carrying the expired lease that killed it.
+        uploadLeaseExpiresAt: uploadLeaseExpiry(),
         updatedAt: now,
       })
       .where(eq(schema.recordings.id, recordingId));

package/corpus/templates/clips/server/routes/api/uploads/[recordingId]/resume.get.ts

@@ -0,0 +1,118 @@
+// guard:allow-api-route — Upload transport resume endpoint returns lease and offset state for the chunk protocol.
+
+/**
+ * Report the authoritative received-offset for an in-flight upload, so a
+ * client whose stream dropped can continue instead of stranding.
+ *
+ * The chunk-POST protocol is unchanged: a client resumes by POSTing the next
+ * chunk at `nextChunkIndex`. Asking also renews the lease, because a client
+ * asking where to resume is a live writer.
+ *
+ * Route: GET /api/uploads/:recordingId/resume
+ */
+
+import { runWithRequestContext } from "@agent-native/core/server";
+import { and, eq } from "drizzle-orm";
+import {
+  createError,
+  defineEventHandler,
+  getRouterParam,
+  setResponseHeader,
+  setResponseStatus,
+  type H3Event,
+} from "h3";
+
+import { getDb, schema } from "../../../../db/index.js";
+import {
+  listRecordingChunkKeys,
+  recordingChunkIndexFromKey,
+  sumRecordingChunkBytes,
+} from "../../../../lib/recording-upload-state.js";
+import {
+  getEventOwnerContext,
+  ownerEmailMatches,
+} from "../../../../lib/recordings.js";
+import { getResumableSession } from "../../../../lib/resumable-session.js";
+import { renewUploadLease } from "../../../../lib/upload-lease.js";
+
+export default defineEventHandler(async (event: H3Event) => {
+  setResponseHeader(event, "Cache-Control", "private, max-age=0, no-store");
+  const recordingId = getRouterParam(event, "recordingId");
+  if (!recordingId) {
+    throw createError({ statusCode: 400, message: "Missing recordingId" });
+  }
+
+  let ownerEmail: string;
+  let orgId: string | undefined;
+  try {
+    const context = await getEventOwnerContext(event);
+    ownerEmail = context.userEmail;
+    orgId = context.orgId;
+  } catch {
+    throw createError({ statusCode: 401, message: "Unauthorized" });
+  }
+
+  return runWithRequestContext({ userEmail: ownerEmail, orgId }, async () => {
+    const [recording] = await getDb()
+      .select({
+        id: schema.recordings.id,
+        status: schema.recordings.status,
+        failureReason: schema.recordings.failureReason,
+        videoUrl: schema.recordings.videoUrl,
+      })
+      .from(schema.recordings)
+      .where(
+        and(
+          eq(schema.recordings.id, recordingId),
+          ownerEmailMatches(schema.recordings.ownerEmail, ownerEmail),
+        ),
+      );
+
+    if (!recording) {
+      setResponseStatus(event, 404);
+      return { error: "Recording not found" };
+    }
+
+    const lease = await renewUploadLease(recordingId);
+    if (!lease.held) {
+      return {
+        resumable: false,
+        recordingId,
+        status: lease.status,
+        failureReason: lease.failureReason,
+        videoUrl: lease.videoUrl,
+      };
+    }
+
+    const session = await getResumableSession(recordingId).catch(() => null);
+    if (session) {
+      return {
+        resumable: true,
+        recordingId,
+        status: recording.status,
+        uploadMode: "streaming" as const,
+        bytesReceived: session.bytesUploaded,
+        nextChunkIndex: (session.lastCommittedIndex ?? -1) + 1,
+      };
+    }
+
+    const stored = new Set(
+      (await listRecordingChunkKeys(ownerEmail, recordingId))
+        .map(recordingChunkIndexFromKey)
+        .filter((index): index is number => index !== null),
+    );
+    // Finalize requires chunks contiguous from 0, so resume at the first gap
+    // rather than after the highest index we happen to hold.
+    let nextChunkIndex = 0;
+    while (stored.has(nextChunkIndex)) nextChunkIndex += 1;
+
+    return {
+      resumable: true,
+      recordingId,
+      status: recording.status,
+      uploadMode: "buffered" as const,
+      bytesReceived: await sumRecordingChunkBytes(ownerEmail, recordingId),
+      nextChunkIndex,
+    };
+  });
+});

package/corpus/templates/clips/server/routes/api/uploads/reap.post.ts

@@ -0,0 +1,69 @@
+/**
+ * Run the upload reaper once. Invoked by the per-minute Clips scheduled
+ * function (see `jobs/emit-netlify-brain-export-cron.ts`), never by
+ * `setInterval` — an in-process timer only fires while traffic keeps a lambda
+ * warm, which is why the old startup sweeps effectively never ran in prod.
+ *
+ * `dryRun=1` reports what would be reaped without writing.
+ *
+ * Route: POST /api/uploads/reap
+ */
+
+import { timingSafeEqual } from "node:crypto";
+
+import {
+  createError,
+  defineEventHandler,
+  getHeader,
+  getQuery,
+  type H3Event,
+} from "h3";
+
+import { reapExpiredUploads } from "../../../lib/upload-lease.js";
+
+declare global {
+  var __AGENT_NATIVE_CLIPS_BRAIN_EXPORT_SCHEDULED_RUNTIME__:
+    | boolean
+    | undefined;
+}
+
+function headerMatchesSecret(header: string | undefined, secret: string) {
+  const expected = `Bearer ${secret}`;
+  const value = header?.trim() ?? "";
+  return (
+    value.length === expected.length &&
+    timingSafeEqual(Buffer.from(value), Buffer.from(expected))
+  );
+}
+
+export default defineEventHandler(async (event: H3Event) => {
+  const scheduled =
+    globalThis.__AGENT_NATIVE_CLIPS_BRAIN_EXPORT_SCHEDULED_RUNTIME__ === true;
+  const secret = process.env.CLIPS_BRAIN_EXPORT_JOBS_SECRET?.trim(); // guard:allow-env-credential — deployment scheduler route secret
+  if (!scheduled) {
+    if (!secret) {
+      throw createError({
+        statusCode: 503,
+        statusMessage: "CLIPS_BRAIN_EXPORT_JOBS_SECRET is required",
+      });
+    }
+    if (
+      secret &&
+      !headerMatchesSecret(getHeader(event, "authorization"), secret)
+    ) {
+      throw createError({ statusCode: 401, statusMessage: "Unauthorized" });
+    }
+  }
+
+  const query = getQuery(event);
+  const result = await reapExpiredUploads({
+    dryRun: query.dryRun === "1" || query.dryRun === "true",
+  });
+  if (result.failed > 0 || result.scratchKeysDeleted > 0) {
+    console.log("[uploads] reaped expired uploads", {
+      failed: result.failed,
+      scratchKeysDeleted: result.scratchKeysDeleted,
+    });
+  }
+  return { ok: true, ...result };
+});

package/corpus/templates/content/.agents/skills/actions/SKILL.md

@@ -18,6 +18,8 @@ Actions in `actions/` are the **single source of truth** for app operations. The
 
 Before creating any custom REST/API route for app data, inspect `actions/` and the action table in `AGENTS.md`. If an action already exists, call it directly from the agent or with `useActionQuery` / `useActionMutation` from the UI. If the capability is missing, create or update a `defineAction`. Do not add `/api/*`, `server/routes/*`, or other pass-through endpoints whose main job is to call, repackage, or re-export an action.
 
+**Stop trigger:** the moment you are about to create a file under `server/routes/api/` — or add server middleware to guard one — stop and check it against the exception list in *When You Still Need Custom `/api/` Routes* below. If it is not on that list, write a `defineAction` instead. This applies even when you already started the route; abandoning a half-written action to hand-roll routes is the exact failure this rule exists to prevent.
+
 ## Why
 
 Actions give the agent callable tools with structured input/output, AND they give the frontend a typed client contract through hooks. One implementation serves both the agent and the UI. They keep the agent's chat context clean, they're reusable, and they can be tested independently.
@@ -390,12 +392,28 @@ This is the canonical approach for new apps. Action names must be lowercase with
 
 ## When You Still Need Custom `/api/` Routes
 
-Most operations should be actions. You only need custom routes in `server/routes/api/` for:
+This is the complete exception list. A route in `server/routes/api/` is only
+justified when the caller is not your own UI or agent, or when the payload is
+not JSON:
 
 - **File uploads** — actions receive JSON params, not multipart form data
 - **Streaming responses** — SSE or chunked responses that need direct H3 control
 - **Webhooks** — external services POST to a specific URL
 - **OAuth callbacks** — redirect-based flows that need specific URL patterns
+- **Public unauthenticated endpoints** — SEO/OG images, share links, and other
+  URLs opened directly by a browser or crawler
+- **Binary or non-JSON responses** — media, exports, generated assets
+
+Everything else is an action: CRUD, settings, search, list/detail reads, auth
+state, and anything the UI fetches as JSON. If a route needs new middleware to
+scope it to the current user, that is a signal it should be an action — actions
+already run inside request context with access checks.
+
+Existing first-party templates still contain a shrinking, explicitly
+grandfathered set of older `/api/*` CRUD routes for app data. The repository's
+`guard:no-action-twin-routes` CI check ratchets that baseline down across the
+first-party template route trees (with the separately owned Plan template
+fenced out); it is not a substitute for keeping generated apps action-first.
 
 When the agent needs a durable image or file URL, call the core `upload-image`
 action or use `uploadFile()` in server code. Do not write base64 into SQL,

package/corpus/templates/content/.agents/skills/content/SKILL.md

@@ -193,6 +193,10 @@ guesswork:
   writing. If a named person cannot be resolved unambiguously, clarify in the
   originating Slack thread; never omit, downgrade, or silently drop the person.
 
+### Cross-App A2A / Slack Artifact Rule
+
+Create or update the document through the normal action path (never a bespoke route) so the artifact stays visible and shareable. When a request arrives from Slack, Dispatch, or another app via A2A, the caller cannot see Content's local UI or navigation state: reply with the concrete document ID and URL/path only after the action succeeds. Use `/page/<id>` for private app documents (or `/p/<id>` only for documents you explicitly made public). Never say a document is ready without including the exact ID or URL/path returned by the action.
+
 ## Local Folder Sources
 
 Install into an existing repo with:

package/corpus/templates/content/.agents/skills/creative-context/SKILL.md

@@ -78,6 +78,14 @@ When the user corrects reused context, call `record-context-feedback` against
 the exact item/version and signal whether it was unhelpful, incorrect, or
 outdated. Never invent a source or silently overwrite source history.
 
+## Submitting to a governed context
+
+To submit a document to a governed Creative Context, use the Context tab or
+`manage-context-membership`; the app flushes live collaboration and captures
+one immutable Markdown version. Reuse only its opaque native clone reference.
+Use `operation="submit-latest"` with a Library membership id when its native
+update status reports `update-available`.
+
 ## Content reuse
 
 Search voice, terminology, audience, and factual evidence as separate intents.