@agent-native/core 0.127.3 → 0.128.1

package/corpus/templates/clips/desktop/src/lib/audio-meter.ts

@@ -14,7 +14,12 @@ export const METER_IDLE_HEIGHT = 0.14;
 export const METER_LEVEL_DECAY = 0.82;
 /** Floor a new sample must clear, so the meter falls smoothly instead of snapping. */
 export const METER_ATTACK_DECAY = 0.55;
-export const METER_SAMPLE_MS = 50;
+/**
+ * How long the meter waits for the next capture buffer before decaying on its
+ * own. Capture drives the bars; this only covers pause / teardown, where the
+ * events stop and a frozen tall bar would claim someone is still talking.
+ */
+export const METER_IDLE_MS = 120;
 
 /** Fold an incoming 0-1 audio level into the current level. */
 export function nextMeterLevel(current: number, incoming: number): number {
@@ -23,6 +28,30 @@ export function nextMeterLevel(current: number, incoming: number): number {
   return Math.max(current * METER_ATTACK_DECAY, clamped);
 }
 
+export type MeterSource = "mic" | "system";
+export type MeterSourceLevels = Record<MeterSource, number>;
+
+export const EMPTY_METER_SOURCES: MeterSourceLevels = { mic: 0, system: 0 };
+
+/**
+ * Fold one capture buffer into the per-source levels. Mic and system audio
+ * interleave on a single event, so each stream has to decay on its own frames
+ * only — one shared level lets a silent mic halve the level of whoever is
+ * actually talking on every other event, which pins the meter to its floor.
+ */
+export function foldMeterSources(
+  levels: MeterSourceLevels,
+  source: MeterSource,
+  incoming: number,
+): MeterSourceLevels {
+  return { ...levels, [source]: nextMeterLevel(levels[source], incoming) };
+}
+
+/** What the bars show: whichever side of the conversation is louder. */
+export function combinedMeterLevel(levels: MeterSourceLevels): number {
+  return Math.max(levels.mic, levels.system);
+}
+
 /** One decay tick. Snaps to silence below a threshold so bars settle at rest. */
 export function decayMeterLevel(current: number): number {
   const decayed = current * METER_LEVEL_DECAY;
@@ -46,6 +75,6 @@ export function advanceMeterLevels(levels: number[], sample: number): number[] {
 export function meterBarHeight(level: number, barIndex: number): number {
   const gain = METER_BAR_GAINS[barIndex] ?? 1;
   const safe = Number.isFinite(level) ? Math.max(0, Math.min(1, level)) : 0;
-  const shaped = safe > 0 ? Math.min(1, Math.pow(safe, 0.52) * 1.08) : 0;
+  const shaped = safe > 0 ? Math.min(1, Math.pow(safe, 0.45) * 1.25) : 0;
   return (METER_IDLE_HEIGHT + shaped * gain * (1 - METER_IDLE_HEIGHT)) * 100;
 }

package/corpus/templates/clips/desktop/src/lib/recorder.ts

@@ -138,6 +138,10 @@ const CLOUD_RECORDING_VIDEO_BITRATE_BPS = 8_000_000;
 const CLOUD_RECORDING_AUDIO_BITRATE_BPS = 128_000;
 const TRANSCRIPT_SAVE_TIMEOUT_MS = 8_000;
 const FINALIZING_RESULT_STORAGE_KEY = "clips-finalizing-result";
+const NO_SPEECH_TRANSCRIPT_FAILURE =
+  "No speech was captured during this recording. If you spoke or played system audio, check System Audio, Microphone input, Speech Recognition permission, and the selected mic, then retry transcription.";
+const TRANSCRIPTION_START_FAILURE =
+  "macOS Speech recognition could not start for this recording. Check Speech Recognition, System Audio, and Microphone permissions, then retry transcription.";
 
 function isMacPlatform(): boolean {
   if (typeof navigator === "undefined") return false;
@@ -2117,6 +2121,51 @@ async function tryStartRewindFullscreenRecording(
   const hasAudio = includeMic || includeSystemAudio;
   let id = folderName;
   let uploadMode: UploadMode = "buffered";
+  let transcriptionCapture: TranscriptionCapture | null = null;
+  let transcriptionAborted = false;
+  let transcriptFailureSaved = false;
+  const saveTranscriptFailure = async (
+    failureReason: string,
+  ): Promise<boolean> => {
+    if (localOnly || !hasAudio || transcriptFailureSaved || !id) return false;
+    transcriptFailureSaved = true;
+    return saveRecordingTranscriptFailure(
+      params.serverUrl,
+      id,
+      failureReason,
+      params.authToken,
+    );
+  };
+  // Whisper always subscribes to the shared Rewind producer's microphone leg,
+  // so a mic-off clip can only fall back to a competing physical capture. Leave
+  // those to server-side transcription instead of fighting the live producer.
+  const canTranscribeLocally = !localOnly && includeMic;
+  const startRewindTranscription = async () => {
+    if (!canTranscribeLocally || transcriptionCapture) return;
+    // Runs after `rewind_clip_prepare`, so the Rewind producer already carries
+    // mic (+system) and whisper attaches to it instead of opening its own
+    // ScreenCaptureKit stream — which would mute the clip's own audio legs.
+    // This runs inside the countdown's Promise.all: a transcription failure
+    // must never reject there, or it would abort the recording itself.
+    const capture = await startTranscriptionCapture(
+      { deviceId: params.micId, label: params.micLabel },
+      includeSystemAudio,
+      { voiceProcessing: false },
+    ).catch((err) => {
+      console.warn("[clips-recorder] rewind transcription start failed:", err);
+      return null;
+    });
+    // A countdown cancel can land while the engine was still starting; the
+    // catch below already ran, so tear this down instead of leaking capture.
+    if (transcriptionAborted) {
+      await capture?.cancel().catch(() => {});
+      return;
+    }
+    transcriptionCapture = capture;
+    if (!capture && shouldSaveLocalTranscriptionStartupFailure()) {
+      void saveTranscriptFailure(TRANSCRIPTION_START_FAILURE);
+    }
+  };
   await invoke("show_preparing");
   const recordingPromise = localOnly
     ? Promise.resolve<{ id: string; uploadMode: UploadMode }>({
@@ -2165,7 +2214,12 @@ async function tryStartRewindFullscreenRecording(
       async countdown() {
         console.log("[rewind-latency] countdown shown after preparation");
         await invoke("hide_preparing").catch(() => {});
-        await runRecordingCountdown(true);
+        // Overlap whisper startup with the countdown so the capture boundary
+        // never waits on it, but have both settled before activation.
+        await Promise.all([
+          runRecordingCountdown(true),
+          startRewindTranscription(),
+        ]);
         console.log("[rewind-latency] countdown completed");
       },
       async activate(preparedRecording) {
@@ -2174,6 +2228,13 @@ async function tryStartRewindFullscreenRecording(
         console.log(
           `[rewind-latency] countdown completion to start acknowledgement ${Math.round(performance.now() - activationStarted)}ms`,
         );
+        // Rebase transcript segment timestamps onto the real recording start.
+        await transcriptionCapture?.resetTimeline().catch((err) => {
+          console.warn(
+            "[clips-recorder] transcription timeline reset failed:",
+            err,
+          );
+        });
         return preparedRecording;
       },
       onActivated() {
@@ -2194,6 +2255,13 @@ async function tryStartRewindFullscreenRecording(
     }
   } catch (err) {
     await invoke("hide_preparing").catch(() => {});
+    transcriptionAborted = true;
+    // Cast: `transcriptionCapture` is only assigned inside the
+    // `startRewindTranscription` closure, which TS's control-flow analysis
+    // cannot see past — it narrows this read to `never`.
+    await (transcriptionCapture as TranscriptionCapture | null)
+      ?.cancel()
+      .catch(() => {});
     if (id) forgetRewindClipOrigin(id);
     await invoke("rewind_clip_cancel").catch(() => {});
     audioCue.cleanup();
@@ -2300,6 +2368,25 @@ async function tryStartRewindFullscreenRecording(
             `[rewind-latency] stop command dispatched in ${Math.round(performance.now() - stopStarted)}ms`,
           );
           uploadPromise.catch(() => {});
+          // Stop transcription only after the clip stop is dispatched (Rust
+          // measures duration when it runs, and stop() blocks on a settle
+          // window), then persist it alongside the upload.
+          const capturedTranscript = await transcriptionCapture
+            ?.stop()
+            .catch((err) => {
+              console.warn("[clips-recorder] transcript stop failed:", err);
+              return null;
+            });
+          const transcriptSavePromise = capturedTranscript?.text.trim()
+            ? saveRecordingTranscript(
+                params.serverUrl,
+                id,
+                capturedTranscript,
+                params.authToken,
+              )
+            : hasAudio
+              ? saveTranscriptFailure(NO_SPEECH_TRANSCRIPT_FAILURE)
+              : Promise.resolve(true);
           await invoke("hide_recording_chrome").catch(() => {});
           if (wantsCamera) await invoke("close_bubble").catch(() => {});
           await openNativeUploadUrl(
@@ -2315,6 +2402,19 @@ async function tryStartRewindFullscreenRecording(
                 authToken: params.authToken,
               });
             }
+            if (
+              !(await transcriptSavePromise) &&
+              capturedTranscript?.text.trim()
+            ) {
+              // The first write races the upload; retry once after finalize so
+              // a pre-ready action request can't strand a captured transcript.
+              void saveRecordingTranscript(
+                params.serverUrl,
+                id,
+                capturedTranscript,
+                params.authToken,
+              );
+            }
             return { recordingId: uploaded.recordingId, viewUrl };
           } catch (err) {
             if (
@@ -2346,6 +2446,10 @@ async function tryStartRewindFullscreenRecording(
       cancelPromise = (async () => {
         stopped = true;
         cleanupUi();
+        transcriptionAborted = true;
+        void transcriptionCapture?.cancel().catch((err) => {
+          console.warn("[clips-recorder] transcription cancel failed:", err);
+        });
         await invoke("rewind_clip_cancel").catch(() => {});
         audioCue.cleanup();
         await invoke("hide_overlays").catch(() => {});
@@ -2376,6 +2480,11 @@ async function tryStartRewindFullscreenRecording(
         pausedAt = null;
       }
       pauseRequestedAt = null;
+      // The Rewind producer keeps running while a clip is paused, so the
+      // transcript would otherwise keep collecting speech the clip never saw.
+      void (
+        paused ? transcriptionCapture?.pause() : transcriptionCapture?.resume()
+      )?.catch(() => {});
       emitState(paused);
     },
     onError(_err, _attemptedPaused) {
@@ -2459,9 +2568,7 @@ async function startNativeFullscreenRecording(
       !transcriptionCapture &&
       shouldSaveLocalTranscriptionStartupFailure()
     ) {
-      void saveTranscriptFailure(
-        "macOS Speech recognition could not start for this recording. Check Speech Recognition, System Audio, and Microphone permissions, then retry transcription.",
-      );
+      void saveTranscriptFailure(TRANSCRIPTION_START_FAILURE);
     }
   };
 
@@ -2965,9 +3072,7 @@ async function startNativeFullscreenRecording(
                 params.authToken,
               )
             : wantsRecordedAudio
-              ? saveTranscriptFailure(
-                  "No speech was captured during this recording. If you spoke or played system audio, check System Audio, Microphone input, Speech Recognition permission, and the selected mic, then retry transcription.",
-                )
+              ? saveTranscriptFailure(NO_SPEECH_TRANSCRIPT_FAILURE)
               : Promise.resolve(true);
 
           // The finalizing window owns the whole stop -> optimized upload ->
@@ -4127,9 +4232,7 @@ async function startRecordingInner(
       !transcriptionCapture &&
       shouldSaveLocalTranscriptionStartupFailure()
     ) {
-      void saveTranscriptFailure(
-        "macOS Speech recognition could not start for this recording. Check Speech Recognition, System Audio, and Microphone permissions, then retry transcription.",
-      );
+      void saveTranscriptFailure(TRANSCRIPTION_START_FAILURE);
     }
 
     // 6. Bubble + toolbar visibility are owned by the popover's session
@@ -4275,9 +4378,7 @@ async function startRecordingInner(
             params.authToken,
           );
         } else if (wantsRecordedAudio) {
-          await saveTranscriptFailure(
-            "No speech was captured during this recording. If you spoke or played system audio, check System Audio, Microphone input, Speech Recognition permission, and the selected mic, then retry transcription.",
-          );
+          await saveTranscriptFailure(NO_SPEECH_TRANSCRIPT_FAILURE);
         }
       }
       if (popoverOwnsCamera) {

package/corpus/templates/clips/desktop/src/lib/updater.ts

@@ -44,18 +44,27 @@ function setStatus(next: UpdateStatus) {
 }
 
 async function runCheck() {
-  if (cachedStatus.state === "downloaded") return;
   if (checkInFlight) return checkInFlight;
 
+  // A staged update keeps checking on the normal cadence. Stopping here is what
+  // made "Restart to update" land on a binary that was already out of date and
+  // immediately ask to restart again — every check runs against the *running*
+  // version, so it re-offers the staged version until a newer one ships.
+  const staged =
+    cachedStatus.state === "downloaded" ? cachedStatus.version : null;
+
   lastCheckStartedAt = Date.now();
   checkInFlight = (async () => {
     try {
-      setStatus({ state: "checking" });
+      if (!staged) setStatus({ state: "checking" });
       const update = await check();
       if (!update) {
-        setStatus({ state: "not-available" });
+        // The endpoint answering "current" while a newer bundle sits staged is
+        // a contradiction, not a reason to drop the download. Keep it staged.
+        if (!staged) setStatus({ state: "not-available" });
         return;
       }
+      if (staged && update.version === staged) return;
       pendingUpdate = update;
       const version = update.version;
       const notes = update.body ?? undefined;
@@ -98,7 +107,6 @@ async function runCheck() {
 
 function maybeCheckForUpdate() {
   if (!canRunUpdateChecks()) return;
-  if (cachedStatus.state === "downloaded") return;
   if (
     checkInFlight ||
     Date.now() - lastCheckStartedAt < UPDATE_FOCUS_CHECK_MIN_INTERVAL_MS

package/corpus/templates/clips/desktop/src/overlays/live-audio-bars.tsx

@@ -3,12 +3,16 @@ import { useEffect, useRef, useState } from "react";
 
 import {
   advanceMeterLevels,
+  combinedMeterLevel,
   decayMeterLevel,
+  EMPTY_METER_SOURCES,
+  foldMeterSources,
   METER_BAR_COUNT,
   METER_BAR_GAINS,
-  METER_SAMPLE_MS,
+  METER_IDLE_MS,
   meterBarHeight,
-  nextMeterLevel,
+  type MeterSource,
+  type MeterSourceLevels,
 } from "../lib/audio-meter";
 
 interface LiveAudioBarsProps {
@@ -28,24 +32,33 @@ export function LiveAudioBars({
   const [levels, setLevels] = useState<number[]>(() =>
     new Array(METER_BAR_COUNT).fill(0),
   );
-  const levelRef = useRef(0);
+  const sourcesRef = useRef<MeterSourceLevels>(EMPTY_METER_SOURCES);
+  const lastEventRef = useRef(0);
 
   useEffect(() => {
     let stopped = false;
     let unlisten: (() => void) | null = null;
 
-    const sampleTimer = window.setInterval(() => {
-      const current = levelRef.current;
-      levelRef.current = decayMeterLevel(current);
-      setLevels((prev) => advanceMeterLevels(prev, current));
-    }, METER_SAMPLE_MS);
-
-    listen<{ level?: number }>("voice:audio-level", (event) => {
-      levelRef.current = nextMeterLevel(
-        levelRef.current,
-        Number(event.payload?.level),
+    const push = () =>
+      setLevels((prev) =>
+        advanceMeterLevels(prev, combinedMeterLevel(sourcesRef.current)),
       );
-    })
+
+    // Drive the bars straight off the capture events rather than resampling on
+    // a timer — both taps already emit at ~25 Hz, and a timer tick landing
+    // between them just showed a decayed copy of a live level.
+    listen<{ level?: number; source?: MeterSource }>(
+      "voice:audio-level",
+      (event) => {
+        sourcesRef.current = foldMeterSources(
+          sourcesRef.current,
+          event.payload?.source === "system" ? "system" : "mic",
+          Number(event.payload?.level),
+        );
+        lastEventRef.current = Date.now();
+        push();
+      },
+    )
       .then((cleanup) => {
         if (stopped) {
           cleanup();
@@ -55,9 +68,21 @@ export function LiveAudioBars({
       })
       .catch(() => {});
 
+    // Capture buffers keep arriving through silence, so they settle the meter on
+    // their own. This only covers pause / teardown, where the events stop.
+    const idleTimer = window.setInterval(() => {
+      if (Date.now() - lastEventRef.current < METER_IDLE_MS) return;
+      if (combinedMeterLevel(sourcesRef.current) === 0) return;
+      sourcesRef.current = {
+        mic: decayMeterLevel(sourcesRef.current.mic),
+        system: decayMeterLevel(sourcesRef.current.system),
+      };
+      push();
+    }, METER_IDLE_MS);
+
     return () => {
       stopped = true;
-      window.clearInterval(sampleTimer);
+      window.clearInterval(idleTimer);
       unlisten?.();
     };
   }, []);

package/corpus/templates/clips/desktop/src/styles.css

@@ -824,14 +824,14 @@ body[data-clips-route="recording-pill"] #root {
 
 .live-audio-bars-compact {
   width: 24px;
-  height: 22px;
-  gap: 3px;
+  height: 24px;
+  gap: 3.5px;
 }
 
 .live-audio-bar {
   display: block;
-  width: 2.5px;
-  min-height: 2.5px;
+  width: 3.5px;
+  min-height: 3.5px;
   border-radius: 999px;
   background: rgba(132, 204, 22, 0.98);
   box-shadow: 0 0 5px rgba(132, 204, 22, 0.35);
@@ -5499,7 +5499,10 @@ body[data-clips-route="recording-pill"] #root {
 .pill-inner-compact {
   width: fit-content;
   height: fit-content;
-  border-radius: 18px;
+  /* Stadium, not a squircle — the collapsed capsule reads as a pill at any
+     height. A fixed radius on the ~44x64 vertical form looks like a rounded
+     rectangle. */
+  border-radius: 999px;
   cursor: pointer;
   transition:
     background 120ms ease,
@@ -5574,7 +5577,7 @@ body[data-clips-route="recording-pill"] #root {
   gap: 6px;
   height: auto;
   width: auto;
-  padding: 12px 10px 10px;
+  padding: 12px 10px;
   cursor: pointer;
 }
 
@@ -5589,7 +5592,7 @@ body[data-clips-route="recording-pill"] #root {
 }
 
 .pill-vertical .pill-wave-meter {
-  height: 22px;
+  height: 24px;
   width: 24px;
 }
 

package/corpus/templates/clips/desktop/src-tauri/src/recording_indicator.rs

@@ -86,7 +86,8 @@ const PILL_DETACHED_W_LOGICAL: u32 = 180;
 const PILL_DETACHED_H_LOGICAL: u32 = 40;
 const PILL_DETACHED_TOP_MARGIN_LOGICAL: u32 = 24;
 const PILL_DETACHED_RIGHT_MARGIN_LOGICAL: u32 = 24;
-const PILL_RIGHT_MARGIN_LOGICAL: u32 = 24;
+/// Gap between the visible capsule and the right screen edge, logical px.
+const PILL_RIGHT_MARGIN_LOGICAL: u32 = 28;
 const OVERLAY_SHADOW_GUTTER_LOGICAL: f64 = 18.0;
 
 #[derive(Debug, Clone, Copy, Default, Serialize, Deserialize)]
@@ -107,6 +108,15 @@ fn overlay_shadow_gutter_physical(app: &AppHandle) -> u32 {
     (OVERLAY_SHADOW_GUTTER_LOGICAL * scale_factor(app).max(1.0)).round() as u32
 }
 
+/// Screen-edge margin for the *visible* capsule. The window is padded out with
+/// a transparent shadow gutter, so that gutter comes off the window margin —
+/// measured from the window frame the pill floats a whole gutter further from
+/// the edge than the constant says.
+fn edge_margin_physical(app: &AppHandle, logical: u32) -> i32 {
+    let margin = (logical as f64 * scale_factor(app)) as i32;
+    (margin - overlay_shadow_gutter_physical(app) as i32).max(0)
+}
+
 /// Persist the last-known pill position so the next `show` re-opens at the
 /// user's chosen spot.
 fn pill_position_path(app: &AppHandle) -> Option<PathBuf> {
@@ -236,8 +246,7 @@ fn default_bottom_center(app: &AppHandle, w: u32, h: u32) -> (i32, i32) {
 }
 
 fn default_center_right(app: &AppHandle, w: u32, h: u32) -> (i32, i32) {
-    let scale = scale_factor(app);
-    let right_margin = (PILL_RIGHT_MARGIN_LOGICAL as f64 * scale) as i32;
+    let right_margin = edge_margin_physical(app, PILL_RIGHT_MARGIN_LOGICAL);
     let (mx, my, mw, mh) = tray_monitor_physical_rect(app);
     let x = (mx + mw as i32 - w as i32 - right_margin).max(mx);
     // Center whatever is actually on screen — meetings now open collapsed, so
@@ -283,9 +292,8 @@ fn pill_size_physical(app: &AppHandle, expanded: bool) -> (u32, u32) {
 
 /// Default top-right anchor (physical px) for detached mode.
 fn default_top_right(app: &AppHandle, w: u32, _h: u32) -> (i32, i32) {
-    let scale = scale_factor(app);
-    let top_margin = (PILL_DETACHED_TOP_MARGIN_LOGICAL as f64 * scale) as i32;
-    let right_margin = (PILL_DETACHED_RIGHT_MARGIN_LOGICAL as f64 * scale) as i32;
+    let top_margin = edge_margin_physical(app, PILL_DETACHED_TOP_MARGIN_LOGICAL);
+    let right_margin = edge_margin_physical(app, PILL_DETACHED_RIGHT_MARGIN_LOGICAL);
     let (mx, my, mw, _mh) = tray_monitor_physical_rect(app);
     let x = (mx + mw as i32 - w as i32 - right_margin).max(mx);
     let y = (my + top_margin).max(my);
@@ -398,15 +406,14 @@ pub async fn recording_pill_show(
     );
 
     if let Some(existing) = app.get_webview_window(PILL_LABEL) {
-        // Already alive — re-emit context and bring it back into view.
-        let prev_size = existing.outer_size().ok();
-        let prev_pos = existing.outer_position().ok();
-        let previous = match (prev_pos, prev_size) {
-            (Some(p), Some(s)) => Some((p.x, p.y, s.width, s.height)),
-            _ => None,
-        };
+        // Already alive — re-emit context and bring it back into view. Re-anchor
+        // from the saved/default position for this mode, never from where the
+        // window happens to sit: the pill window is reused across sessions, so
+        // carrying the previous rect over pins a meeting pill to the last clip
+        // recording's bottom-center spot. `previous` exists for expand/collapse,
+        // where the anchor must not move.
         let expanded = PILL_EXPANDED.load(Ordering::Relaxed);
-        let (w, h, x, y) = anchored_rect(&app, expanded, previous);
+        let (w, h, x, y) = anchored_rect(&app, expanded, None);
         let _ = existing.set_size(tauri::Size::Physical(PhysicalSize::new(w, h)));
         let _ = existing.set_position(PhysicalPosition::new(x, y));
         use tauri::Emitter;

package/corpus/templates/clips/shared/transcript-status.ts

@@ -1,5 +1,15 @@
 export const STALE_PENDING_TRANSCRIPT_MS = 5 * 60 * 1000;
 
+/**
+ * How often a worker that is still transcribing must re-stamp its pending row.
+ *
+ * `updatedAt` is the only liveness signal a pending row carries, so this must
+ * stay well under STALE_PENDING_TRANSCRIPT_MS: a run whose slowest single step
+ * (media fetch, ffmpeg extraction, provider call) outlives the heartbeat is
+ * indistinguishable from a worker that died.
+ */
+export const PENDING_TRANSCRIPT_HEARTBEAT_MS = 60 * 1000;
+
 export const STALE_PENDING_TRANSCRIPT_REASON =
   "Transcription stopped before it finished. Retry transcription to start a fresh attempt.";
 

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

@@ -305,6 +305,38 @@ export default defineAction({
 
 On success the validated value is returned, so coercion/defaults on `outputSchema` apply. Omit `outputSchema` and behavior is byte-for-byte unchanged (no wrapping).
 
+### Authorization (`authorize`)
+
+`authorize` decides whether the caller may run the action at all. It wraps
+`run`, so it holds at **all six dispatch sites** — agent tool, HTTP, frontend
+hook, MCP, A2A, CLI — unlike `needsApproval`, which is honoured only in the
+agent loop. Use `authorize` for "not everyone may do this"; use `needsApproval`
+to ask a human to bless one call a permitted caller is already allowed to make.
+
+```ts
+import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
+
+export default defineAction({
+  description: "Archive a client roster.",
+  schema: z.object({ id: z.string() }),
+  authorize: coachAccess.requireAny("coach-admin"),
+  run: async (args) => {
+    /* ... */
+  },
+});
+```
+
+The wrappers compose as `validate input -> authorize -> run -> validate output
+-> audit`: the gate sits inside input validation, so a guard reading `args` gets
+the parsed, coerced value, and auditing is outermost, so denials are recorded.
+
+A guard that throws denies with its own message; returning `false` denies
+generically; anything else (including `undefined`) allows. A guarded action
+needs a user identity, so an unattended CLI/cron caller with no user email is
+denied. `authorize` gates the operation; `accessFilter` / `assertAccess` still
+scope which rows a permitted caller may touch. See the `authentication` skill
+for `defineAppRoles` and the `sharing` skill for row scoping.
+
 ### Human-in-the-Loop Approval (`needsApproval`)
 
 For high-consequence, outward-facing, hard-to-undo actions (sending an email, charging a card, deleting an account), set `needsApproval` so the agent **cannot** run the action without a human approving the specific call:

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

@@ -159,6 +159,35 @@ whole site. Data scoping lives in actions and API routes; the client gates
 private UI after the shell loads. See the `authentication` skill and
 `guard:ssr-cache-shell` / `ssr-handler.spec.ts`.
 
+**Authorization beyond "is there a session" — `authorize`.** The auth guard only
+proves *someone* is signed in. To restrict an operation to some teammates, set
+`authorize` on the `defineAction`. It wraps `run`, so it applies at every
+dispatch site (agent tool, HTTP, frontend, MCP, A2A, CLI) — unlike
+`needsApproval`, which is honoured only in the agent loop.
+
+```ts
+import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
+
+export default defineAction({
+  description: "Archive a client roster.",
+  schema: z.object({ id: z.string() }),
+  authorize: coachAccess.requireAny("coach-admin"),
+  run: async (args) => {
+    /* ... */
+  },
+});
+```
+
+A guard that throws denies with its own message; returning `false` denies
+generically; anything else (including `undefined`) allows. Guarded actions need
+a user identity — an unattended CLI/cron caller with no user email is denied.
+
+`authorize` is **not** a substitute for `accessFilter` / `assertAccess`. It
+decides whether this caller may perform the operation at all; `accessFilter` /
+`assertAccess` scope which rows a permitted caller may see or touch. A
+restricted write action needs both. See the `authentication` skill for
+`defineAppRoles` and the `actions` skill for the full surface.
+
 ## Human-in-the-Loop Approval for High-Consequence Actions
 
 For a small set of outward-facing, hard-to-undo operations — sending an email, charging a card, deleting an account, posting publicly — auth and access control are necessary but not sufficient: you also do not want the **agent** to perform them autonomously. Set `needsApproval` on the `defineAction` so the agent cannot run the action without a human approving the specific call.
@@ -274,6 +303,8 @@ Run `pnpm action db-check-scoping` to verify. Use `--require-org` for multi-org
 - [ ] New env vars in `.env` only, not committed
 - [ ] New user-data tables have `owner_email` column
 - [ ] Custom routes call `getSession` and reject unauthenticated requests
+- [ ] Actions only some teammates may run set `authorize` (in addition to any
+      `accessFilter` / `assertAccess` row scoping)
 
 ## Related Skills
 

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

@@ -34,6 +34,8 @@ Visibility is coarse. Explicit share grants are fine-grained (per user or per or
 - **`editor`** — read + write.
 - **`admin`** — read + write + manage shares. Does NOT replace the single `owner_email` on the resource.
 
+There are three role systems and they never imply one another. A share role answers "what may this person do to **one row**". An org role (`org_members.role`) answers "what may this person do to the **team**". An app role (`defineAppRoles`, see the `authentication` skill) answers "what may this person do inside **one app**". A share `admin` is not an app admin and neither is an org admin.
+
 ### Anonymous public URLs stay separate
 
 Form "publish" slugs, booking-link slugs, any feature that exposes a URL to unauthenticated users — these are a different axis and are NOT controlled by the sharing system. Keep them alongside it.
@@ -137,6 +139,8 @@ export default defineAction({
 
 For delete actions use `"admin"` (or fold in `"owner"` to require the real owner).
 
+`authorize` is a different axis, not an alternative: it gates whether the caller may run the operation at all, while `assertAccess` scopes which row they may touch. A write action restricted to some teammates needs both — `authorize: appAccess.requireAny(...)` on the action, `assertAccess` inside `run`.
+
 ## Create actions must set owner
 
 When inserting a new row, fill `ownerEmail` and `orgId` from the request context:

package/corpus/templates/content/_gitignore

@@ -8,8 +8,10 @@ npm-debug.log*
 pnpm-debug.log*
 
 node_modules
+build/
 dist
 dist-ssr
+.output/
 *.local
 
 # Editor directories and files

package/corpus/templates/crm/.agents/skills/sharing/SKILL.md

@@ -34,6 +34,8 @@ Visibility is coarse. Explicit share grants are fine-grained (per user or per or
 - **`editor`** — read + write.
 - **`admin`** — read + write + manage shares. Does NOT replace the single `owner_email` on the resource.
 
+There are three role systems and they never imply one another. A share role answers "what may this person do to **one row**". An org role (`org_members.role`) answers "what may this person do to the **team**". An app role (`defineAppRoles`, see the `authentication` skill) answers "what may this person do inside **one app**". A share `admin` is not an app admin and neither is an org admin.
+
 ### Anonymous public URLs stay separate
 
 Form "publish" slugs, booking-link slugs, any feature that exposes a URL to unauthenticated users — these are a different axis and are NOT controlled by the sharing system. Keep them alongside it.
@@ -137,6 +139,8 @@ export default defineAction({
 
 For delete actions use `"admin"` (or fold in `"owner"` to require the real owner).
 
+`authorize` is a different axis, not an alternative: it gates whether the caller may run the operation at all, while `assertAccess` scopes which row they may touch. A write action restricted to some teammates needs both — `authorize: appAccess.requireAny(...)` on the action, `assertAccess` inside `run`.
+
 ## Create actions must set owner
 
 When inserting a new row, fill `ownerEmail` and `orgId` from the request context: