@agent-native/core 0.161.17 → 0.161.20

package/corpus/templates/clips/app/components/player/video-player.tsx

@@ -183,6 +183,8 @@ export interface VideoPlayerProps {
   defaultSpeed?: number;
   /** Autoplay on mount. */
   autoPlay?: boolean;
+  /** Persist resume position for an authenticated viewer. */
+  persistPlaybackPosition?: boolean;
   /** Start time in ms. */
   startMs?: number;
   /** Comment + chapter overlays for the scrubber. */
@@ -247,6 +249,7 @@ export const VideoPlayer = forwardRef<VideoPlayerHandle, VideoPlayerProps>(
       thumbnailUrl,
       defaultSpeed = 1.2,
       autoPlay,
+      persistPlaybackPosition = true,
       startMs,
       editsJson,
       comments,
@@ -520,6 +523,7 @@ export const VideoPlayer = forwardRef<VideoPlayerHandle, VideoPlayerProps>(
       recordingId,
       videoEl: playbackVideoEl,
       durationMs,
+      enabled: persistPlaybackPosition,
       explicitStartMs: startMs,
       allowRestoreWhilePlaying: autoPlay,
       onRestore: restorePlaybackPosition,

package/corpus/templates/clips/app/hooks/use-playback-position.ts

@@ -13,6 +13,7 @@ export interface UsePlaybackPositionOptions {
   recordingId: string;
   videoEl: HTMLVideoElement | null;
   durationMs: number;
+  enabled?: boolean;
   explicitStartMs?: number;
   allowRestoreWhilePlaying?: boolean;
   onRestore?: (positionMs: number) => void;
@@ -27,6 +28,7 @@ export function usePlaybackPosition({
   recordingId,
   videoEl,
   durationMs,
+  enabled = true,
   explicitStartMs,
   allowRestoreWhilePlaying = false,
   onRestore,
@@ -38,7 +40,7 @@ export function usePlaybackPosition({
   onRestoreRef.current = onRestore;
 
   useEffect(() => {
-    if (!videoEl || !recordingId) return;
+    if (!enabled || !videoEl || !recordingId) return;
 
     const controller = new AbortController();
     let cancelled = false;
@@ -184,5 +186,11 @@ export function usePlaybackPosition({
       window.removeEventListener("pagehide", onPageHide);
       document.removeEventListener("visibilitychange", onVisibilityChange);
     };
-  }, [allowRestoreWhilePlaying, explicitStartMs, recordingId, videoEl]);
+  }, [
+    allowRestoreWhilePlaying,
+    enabled,
+    explicitStartMs,
+    recordingId,
+    videoEl,
+  ]);
 }

package/corpus/templates/clips/app/routes/embed.$shareId.tsx

@@ -236,6 +236,7 @@ export default function EmbedRoute() {
         videoFormat={recording.videoFormat}
         embedProvider={isLoomEmbedBacked ? "loom" : null}
         durationMs={recording.durationMs}
+        persistPlaybackPosition={false}
         editsJson={recording.editsJson}
         thumbnailUrl={recording.thumbnailUrl}
         defaultSpeed={parsePlaybackSpeed(recording.defaultSpeed) ?? 1.2}

package/corpus/templates/clips/app/routes/r.$recordingId.tsx

@@ -187,6 +187,30 @@ function nativeSaveFailureMessage(reason: string | null | undefined): string {
   return "The desktop recorder finished and saved a local copy, but Clips could not upload it. You can retry from the Clips menu without recording again.";
 }
 
+export function BackToLibraryButton() {
+  const t = useT();
+  const navigate = useNavigate();
+
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button
+          variant="ghost"
+          size="icon"
+          className="shrink-0"
+          onClick={() => navigate("/library", { replace: true })}
+          aria-label={t("recordingPage.backToLibrary")}
+        >
+          <IconArrowLeft className="h-4 w-4 rtl:-scale-x-100" />
+        </Button>
+      </TooltipTrigger>
+      <TooltipContent side="bottom" align="start">
+        {t("recordingPage.backToLibrary")}
+      </TooltipContent>
+    </Tooltip>
+  );
+}
+
 function parseTimeParam(raw: string | null): number {
   if (!raw) return 0;
   const value = raw.trim();
@@ -965,17 +989,7 @@ export default function RecordingPage() {
       return (
         <div className="flex min-h-screen w-full flex-col bg-background">
           <header className="flex min-w-0 shrink-0 items-center gap-3 border-b border-border px-3 py-2 sm:px-4 sm:py-3">
-            <Button
-              asChild
-              variant="ghost"
-              size="icon"
-              className="shrink-0"
-              aria-label={t("recordingPage.backToLibrary")}
-            >
-              <Link to="/library" replace>
-                <IconArrowLeft className="h-4 w-4 rtl:-scale-x-100" />
-              </Link>
-            </Button>
+            <BackToLibraryButton />
             <div className="min-w-0 flex-1">
               <p className="truncate text-sm font-medium">{visibleTitle}</p>
               <p className="truncate text-xs text-muted-foreground">
@@ -1294,20 +1308,7 @@ export default function RecordingPage() {
       {/* Main video column */}
       <div className="flex w-full min-w-0 flex-col xl:flex-1">
         <header className="flex min-w-0 shrink-0 items-center gap-2 border-b border-border px-3 py-2 sm:gap-3 sm:px-4 sm:py-3">
-          <Button
-            asChild
-            variant="ghost"
-            size="icon"
-            className="shrink-0 sm:w-auto sm:px-2"
-            aria-label={t("recordingPage.backToLibrary")}
-          >
-            <Link to="/library" replace>
-              <IconArrowLeft className="h-4 w-4 rtl:-scale-x-100" />
-              <span className="hidden sm:inline">
-                {t("recordingPage.backToLibrary")}
-              </span>
-            </Link>
-          </Button>
+          <BackToLibraryButton />
           <div className="flex-1 min-w-0">
             <EditableRecordingTitle
               recordingId={recording.id}

package/corpus/templates/clips/app/routes/share.$shareId.tsx

@@ -1226,6 +1226,7 @@ export default function ShareRoute() {
               videoFormat={recording.videoFormat}
               embedProvider={isLoomEmbedBacked ? "loom" : null}
               durationMs={recording.durationMs}
+              persistPlaybackPosition={Boolean(session)}
               editsJson={recording.editsJson}
               thumbnailUrl={recording.thumbnailUrl}
               role={viewerRole ?? (viewerCanEdit ? "owner" : "viewer")}

package/corpus/templates/clips/changelog/2026-08-18-clips-no-longer-opens-welcome-window-on-first-launch.md

@@ -0,0 +1,6 @@
+---
+type: removed
+date: 2026-08-18
+---
+
+Clips no longer opens a welcome window on first launch.

package/corpus/templates/clips/changelog/2026-08-18-pending-recording-files-now-use-a-clips-prefixed-name.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-18
+---
+
+Pending recording files now use a Clips-prefixed name instead of a feature-ambiguous stem.

package/corpus/templates/clips/desktop/src/main.tsx

@@ -11,7 +11,6 @@ import { FlowBar } from "./overlays/flow-bar";
 import { MeetingNotification } from "./overlays/meeting-notification";
 import { MeetingNub } from "./overlays/meeting-nub";
 import { MonitorPicker } from "./overlays/monitor-picker";
-import { Onboarding } from "./overlays/onboarding";
 import { Preparing } from "./overlays/preparing";
 import { RecordingPill } from "./overlays/recording-pill";
 import { RegionGuideEditor, RegionGuides } from "./overlays/region-guides";
@@ -47,8 +46,6 @@ function pickRoute(route: string): React.ReactElement {
       return <Finalizing />;
     case "preparing":
       return <Preparing />;
-    case "onboarding":
-      return <Onboarding />;
     case "meeting-notif":
       return <MeetingNotification />;
     case "meeting-nub":

package/corpus/templates/clips/desktop/src/shared/config.ts

@@ -129,7 +129,6 @@ export interface FeatureConfig {
   showInScreenCapture: boolean;
   regionGuides: RegionGuidesConfig;
   screenMemory: ScreenMemoryConfig;
-  onboardingComplete: boolean;
   whisperModelEnabled: boolean;
   whisperModelId: string;
 }

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

@@ -5263,124 +5263,6 @@ body[data-clips-route="recording-pill"] #root {
   }
 }
 
-/* ------------------------------------------------------------------------- */
-/* Overlay: onboarding                                                        */
-/* ------------------------------------------------------------------------- */
-
-.onboarding-root {
-  position: fixed;
-  inset: 0;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  background: #212121;
-  color: #f5f5f5;
-}
-
-.onboarding-card {
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  gap: 20px;
-  padding: 40px 36px;
-  max-width: 380px;
-  width: 100%;
-}
-
-.onboarding-title {
-  font-size: 22px;
-  font-weight: 700;
-  color: white;
-  margin: 0;
-  letter-spacing: -0.3px;
-}
-
-.onboarding-subtitle {
-  font-size: 14px;
-  color: #a3a3a3;
-  margin: -8px 0 0;
-}
-
-.onboarding-features {
-  display: flex;
-  flex-direction: column;
-  gap: 10px;
-  width: 100%;
-}
-
-.onboarding-feature {
-  display: flex;
-  align-items: flex-start;
-  gap: 12px;
-  padding: 14px 16px;
-  background: rgba(255, 255, 255, 0.04);
-  border: 1px solid rgba(255, 255, 255, 0.08);
-  border-radius: 12px;
-  cursor: pointer;
-  user-select: none;
-}
-
-.onboarding-feature:hover {
-  background: rgba(255, 255, 255, 0.06);
-}
-
-.onboarding-checkbox {
-  width: 18px;
-  height: 18px;
-  margin: 1px 0 0;
-  accent-color: #16a34a;
-  cursor: pointer;
-  flex-shrink: 0;
-}
-
-.onboarding-feature-text {
-  display: flex;
-  flex-direction: column;
-  gap: 3px;
-}
-
-.onboarding-feature-name {
-  font-size: 14px;
-  font-weight: 600;
-  color: white;
-}
-
-.onboarding-feature-desc {
-  font-size: 12px;
-  color: #a3a3a3;
-  line-height: 1.4;
-}
-
-.onboarding-cta {
-  width: 100%;
-  border: none;
-  border-radius: 12px;
-  padding: 12px 16px;
-  background: #f5f5f5;
-  color: #212121;
-  font-size: 14px;
-  font-weight: 600;
-  cursor: pointer;
-  height: 44px;
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  margin-top: 4px;
-}
-
-.onboarding-cta:hover {
-  background: #e5e5e5;
-}
-
-.onboarding-cta:active {
-  transform: translateY(1px);
-}
-
-.onboarding-cta:disabled {
-  opacity: 0.6;
-  cursor: not-allowed;
-}
-
 /* ------------------------------------------------------------------------- */
 /* Overlay: meeting notification                                              */
 /* ------------------------------------------------------------------------- */

package/corpus/templates/clips/desktop/src-tauri/capabilities/default.json

@@ -9,7 +9,6 @@
     "bubble",
     "signin",
     "finalizing",
-    "onboarding",
     "meeting-notif",
     "meeting-nub",
     "flow-bar",

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

@@ -48,7 +48,6 @@ const REGION_GUIDES_LABEL: &str = "region-guides";
 const REGION_GUIDE_EDITOR_LABEL: &str = "region-guide-editor";
 const REGION_RECORD_BORDER_LABEL: &str = "region-record-border";
 const MONITOR_PICKER_LABEL_PREFIX: &str = "monitor-picker-";
-const ONBOARDING_LABEL: &str = "onboarding";
 const OVERLAY_LABELS: &[&str] = &[
     COUNTDOWN_LABEL,
     TOOLBAR_LABEL,
@@ -59,8 +58,6 @@ const OVERLAY_LABELS: &[&str] = &[
     REGION_GUIDES_LABEL,
     REGION_RECORD_BORDER_LABEL,
 ];
-const ONBOARDING_WIDTH_LOGICAL: f64 = 560.0;
-const ONBOARDING_HEIGHT_LOGICAL: f64 = 640.0;
 
 /// Physical-pixel bubble sizes. Logical px on retina = physical / 2, so these
 /// map to ~96 (small) and ~180 (medium) logical px — matching Loom's camera
@@ -599,48 +596,6 @@ pub async fn hide_finalizing(app: AppHandle) -> Result<(), String> {
     Ok(())
 }
 
-/// First-run onboarding window (ONBOARD-WINDOW). Unlike the transparent,
-/// click-through overlays above, this is a normal decorated, focused window
-/// with its own solid dark background (`.onboarding-root` in styles.css) —
-/// centered on the primary display so it reads as a real app window, not a
-/// HUD. Called once from `lib.rs`'s `setup()` when `onboarding_complete` is
-/// false. Reuses an existing window if one is somehow already open (e.g. a
-/// hot-reload re-triggering setup in dev) instead of building a second one.
-pub fn show_onboarding_window(app: &AppHandle) {
-    if let Some(existing) = app.get_webview_window(ONBOARDING_LABEL) {
-        let _ = existing.show();
-        let _ = existing.set_focus();
-        return;
-    }
-    let win =
-        match WebviewWindowBuilder::new(app, ONBOARDING_LABEL, build_overlay_url("onboarding"))
-            .title("Welcome to Clips")
-            .inner_size(ONBOARDING_WIDTH_LOGICAL, ONBOARDING_HEIGHT_LOGICAL)
-            .resizable(false)
-            .center()
-            .focused(true)
-            .build()
-        {
-            Ok(w) => w,
-            Err(e) => {
-                eprintln!("[clips-tray] onboarding window build failed: {}", e);
-                return;
-            }
-        };
-    let _ = win.show();
-}
-
-/// Close the first-run onboarding window once the overlay's finish handler
-/// has saved feature config + opened the popover. Idempotent — closing an
-/// already-closed/never-built window is a no-op.
-#[tauri::command]
-pub async fn hide_onboarding_window(app: AppHandle) -> Result<(), String> {
-    if let Some(w) = app.get_webview_window(ONBOARDING_LABEL) {
-        let _ = w.close();
-    }
-    Ok(())
-}
-
 /// Full-screen, click-through recording guides. The React view renders the
 /// saved translucent rectangles, while AppKit marks the whole overlay as
 /// non-shareable so the guides stay private to the recorder.

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

@@ -134,7 +134,6 @@ pub struct FeatureConfig {
     pub region_guides: RegionGuidesConfig,
     #[serde(default)]
     pub screen_memory: ScreenMemoryConfig,
-    pub onboarding_complete: bool,
     #[serde(default = "default_whisper_model_enabled")]
     pub whisper_model_enabled: bool,
     #[serde(default = "default_whisper_model_id")]
@@ -238,7 +237,6 @@ impl Default for FeatureConfig {
             show_in_screen_capture: false,
             region_guides: RegionGuidesConfig::default(),
             screen_memory: ScreenMemoryConfig::default(),
-            onboarding_complete: false,
             whisper_model_enabled: default_whisper_model_enabled(),
             whisper_model_id: default_whisper_model_id(),
         }
@@ -437,8 +435,7 @@ mod tests {
         let config: FeatureConfig = serde_json::from_value(serde_json::json!({
             "clipsEnabled": true,
             "meetingsEnabled": true,
-            "voiceEnabled": true,
-            "onboardingComplete": true
+            "voiceEnabled": true
         }))
         .unwrap();
 

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

@@ -116,7 +116,6 @@ pub fn run() {
             clips::close_signin,
             clips::show_flow_bar,
             clips::hide_flow_bar,
-            clips::hide_onboarding_window,
             clips::complete_voice_dictation,
             clips::paste_last_dictation,
             clips::set_recording_state,
@@ -343,15 +342,6 @@ pub fn run() {
             tray::build_tray(app)?;
             config::sync_launch_at_login(app.handle());
             let feature_config = config::feature_config(app.handle());
-            // ONBOARD-WINDOW: first-run onboarding never had a Rust-side
-            // window to appear in — the `#onboarding` hash route and overlay
-            // component existed, but nothing ever called
-            // WebviewWindowBuilder for it. Build it here, after the popover
-            // exists, gated on the persisted `onboarding_complete` flag so
-            // returning users never see it again.
-            if !feature_config.onboarding_complete {
-                clips::show_onboarding_window(app.handle());
-            }
             screen_memory::sync_from_config(app.handle(), &feature_config);
             // Re-show always-on region guides after relaunch/reboot when the
             // setting is on (no-op if a recording owns the window or the

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

@@ -270,6 +270,19 @@ mod native_upload_mode_tests {
     }
 }
 
+#[cfg(test)]
+mod pending_recording_file_name_tests {
+    use super::pending_recording_file_stem;
+
+    #[test]
+    fn uses_a_clips_specific_pending_recording_prefix() {
+        assert_eq!(
+            pending_recording_file_stem("FxGL6zX7HWhU", 4242),
+            "clips-pending-recording-FxGL6zX7HWhU-4242",
+        );
+    }
+}
+
 #[derive(Default)]
 pub struct NativeFullscreenRecordingState {
     inner: Mutex<Option<NativeFullscreenSession>>,
@@ -2764,14 +2777,26 @@ fn discard_session(session: &mut NativeFullscreenSession) {
 
 /// Sibling path next to the original pending recording, numbered with
 /// the segment counter so multiple resume cycles don't clobber each
-/// other. Example: `clips-fullscreen-<id>-<pid>-seg2.mp4`.
+/// other. Example: `clips-pending-recording-<id>-<pid>-seg2.mp4`.
 fn segment_path_for(
     app: &AppHandle,
     safe_id: &str,
     extension: &str,
     counter: u32,
 ) -> Result<PathBuf, String> {
-    pending_recording_path(app, &format!("{safe_id}-seg{counter}"), extension)
+    let base_path = pending_recording_path(app, safe_id, extension)?;
+    let base_stem = base_path
+        .file_stem()
+        .and_then(|value| value.to_str())
+        .ok_or_else(|| "pending recording path has no valid file stem".to_string())?;
+    Ok(base_path.with_file_name(format!(
+        "{base_stem}-seg{counter}.{}",
+        extension.trim_start_matches('.')
+    )))
+}
+
+fn pending_recording_file_stem(safe_id: &str, pid: u32) -> String {
+    format!("clips-pending-recording-{safe_id}-{pid}")
 }
 
 /// Dispatches to the right backend starter for resume. Mirrors the
@@ -3202,7 +3227,9 @@ fn orphan_recording_id(path: &Path) -> Option<String> {
         return None;
     }
     let stem = path.file_stem().and_then(|value| value.to_str())?;
-    let value = if let Some(value) = stem.strip_prefix("rewind-") {
+    let value = if let Some(value) = stem.strip_prefix("clips-pending-recording-") {
+        value
+    } else if let Some(value) = stem.strip_prefix("rewind-") {
         value
     } else if let Some(value) = stem.strip_prefix("clips-fullscreen-") {
         value
@@ -3525,15 +3552,40 @@ mod orphan_recovery_tests {
             orphan_recording_id(Path::new("clips-fullscreen-e4esSx9NZCZa-1234.mov")),
             Some("e4esSx9NZCZa".into())
         );
+        assert_eq!(
+            orphan_recording_id(Path::new("clips-pending-recording-e4esSx9NZCZa-1234.mp4")),
+            Some("e4esSx9NZCZa".into())
+        );
         assert!(is_recording_segment_path(Path::new(
             "clips-fullscreen-e4esSx9NZCZa-1234-seg2.mp4"
         )));
+        assert!(is_recording_segment_path(Path::new(
+            "clips-pending-recording-e4esSx9NZCZa-1234-seg2.mp4"
+        )));
         assert!(
             orphan_recording_id(Path::new("clips-fullscreen-e4esSx9NZCZa-1234-seg2.mp4")).is_none()
         );
+        assert!(orphan_recording_id(Path::new(
+            "clips-pending-recording-e4esSx9NZCZa-1234-seg2.mp4"
+        ))
+        .is_none());
         assert!(orphan_recording_id(Path::new("unrelated.mp4")).is_none());
     }
 
+    #[test]
+    fn recovers_new_pending_recording_name_without_intent_sidecar() {
+        let intent = orphan_recording_intent(
+            Path::new("clips-pending-recording-recording-123-456.mp4"),
+            "https://clips.example.test/",
+        )
+        .unwrap()
+        .unwrap();
+
+        assert_eq!(intent.recording_id, "recording-123");
+        assert_eq!(intent.server_url, "https://clips.example.test");
+        assert!(!intent.custom_pipeline);
+    }
+
     #[test]
     fn intent_sidecars_round_trip_and_map_back_to_media() {
         let root = std::env::temp_dir().join(format!(
@@ -4167,8 +4219,8 @@ fn pending_recording_path(
     extension: &str,
 ) -> Result<PathBuf, String> {
     Ok(pending_uploads_dir(app)?.join(format!(
-        "clips-fullscreen-{safe_id}-{}.{}",
-        std::process::id(),
+        "{}.{}",
+        pending_recording_file_stem(safe_id, std::process::id()),
         extension.trim_start_matches('.')
     )))
 }

package/corpus/templates/content/.agents/skills/adding-a-feature/SKILL.md

@@ -76,6 +76,16 @@ Builder/internal data, or customer data in the action, UI, seed data, fixtures,
 docs, prompts, or generated extension/app content. Register required secrets,
 use OAuth helpers, or read scoped values from the vault/credential store.
 
+Before writing custom setup or credential UI, perform the shared-primitive
+preflight from `agent-native-toolkit`: inspect the workspace/provider connection
+catalog first, then settings, secrets/vault, OAuth, onboarding, and provider API
+support. Reuse an existing connection's app grant and scoped credential
+resolver; only use app-local vault or OAuth primitives when no reusable
+connection exists. Keep any wizard thin and provider-specific - it may explain
+prerequisites, ordering, or readiness, but must not become a second vault or
+custom credential transport. Do not mark each field `required` by reflex;
+model onboarding around the logical connection outcome.
+
 If the feature involves attachments, images, recordings, screenshots, exports,
 or other file-like payloads, design the upload path in the same change:
 provider upload first, then URL/id/blob handle in SQL. Do not add base64/binary

package/corpus/templates/content/.agents/skills/agent-native-toolkit/SKILL.md

@@ -152,6 +152,30 @@ preference, notification preference, or usage/billing surface, register it as a
 settings tab or app settings panel first. Only add sidebar UI when it is needed
 in the moment of agent use.
 
+## Integration Setup Preflight
+
+Before building any setup, settings, credential, OAuth, or connection surface,
+search the workspace/provider connection catalog first. If the provider already
+has a reusable connection, use its catalog, app grant, and scoped credential
+resolver rather than registering a parallel secret. Only then classify fields
+that still need app-local setup by lifecycle and scope:
+
+| Need | Default primitive |
+| --- | --- |
+| Deploy- or app-level configuration | Runtime configuration or deployment env vars |
+| Existing workspace/provider connection | Workspace-connection catalog/grant plus `resolveWorkspaceConnectionCredential(s)ForApp` |
+| App-local API/service key with no reusable connection | `registerRequiredSecret({ kind: "api-key" })` and the vault |
+| Authorization-code or refresh-token flow | `kind: "oauth"` with `@agent-native/core/oauth-tokens` |
+| Account, customer, or other non-secret identifiers | Scoped connection metadata or app data |
+| Provider-specific prerequisites, sequencing, or health | A thin app-local guide over the shared primitives |
+
+Do not register every provider field as a generic secret, mark every field as
+required, or create a second credential-management surface. One logical
+connection should normally produce one onboarding outcome. A custom setup page
+is appropriate only when it adds domain-specific guidance or readiness checks;
+it should link to or call the shared settings, OAuth, and action surfaces rather
+than duplicating their storage or transport.
+
 ## Reusable Kits
 
 - **Settings kit**: a searchable settings page with account, workspace, AI

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

@@ -3,8 +3,8 @@ name: secrets
 description: >-
   Declaratively register API keys and service credentials a template needs so
   they appear in the agent sidebar settings UI and the onboarding checklist.
-  Use for any third-party API key (OpenAI, Stripe, Twilio, etc.) and for
-  surfacing OAuth connections in the unified settings UI.
+  Use before adding any third-party credential or setup UI so API keys, OAuth
+  connections, and scoped configuration use the correct shared primitive.
 scope: dev
 metadata:
   internal: true
@@ -24,6 +24,33 @@ encrypted `app_secrets` vault, `saveCredential` / `resolveCredential`, OAuth, or
 `${keys.NAME}` substitution. Examples must use obvious placeholders such as
 `<OPENAI_API_KEY>` or `${keys.SLACK_WEBHOOK}`, not real-looking copied values.
 
+## Credential Modeling Preflight
+
+Before registering a provider's fields, inspect the workspace/provider connection
+catalog first. If a reusable connection exists, use its app grant and scoped
+`resolveWorkspaceConnectionCredential(s)ForApp` path instead of registering a
+parallel secret. Only classify fields for app-local setup when no reusable
+connection exists:
+
+- **API or service key** - register it as `kind: "api-key"` with the narrowest
+  correct `scope`, a human label, a description, a docs link, and a validator.
+- **OAuth authorization or refresh token** - use the OAuth token store and
+  register a `kind: "oauth"` entry so the shared UI renders Connect and the
+  runtime owns status, refresh, and reauthorization.
+- **Deploy- or app-level configuration** - use deployment/runtime
+  configuration, not a per-user secret row.
+- **Account, customer, manager, or other non-secret identifier** - store it as
+  scoped connection metadata or app data, not as a masked secret field.
+
+`required: true` is for a logical setup requirement. If a provider needs
+several values, do not automatically create one required checklist item per
+field; use one composite onboarding step or a registered connection readiness
+check.
+
+Custom setup UI is allowed for provider-specific prerequisites, ordering, or
+health checks, but it must delegate credential storage and connection state to
+the shared vault/OAuth/settings surfaces.
+
 ## When to use
 
 Use this for any external credential your template needs: API keys, service

package/corpus/templates/content/AGENTS.md

@@ -49,6 +49,7 @@ Read the relevant skill before deeper work:
   thumbnails, or replay chunks in app tables, `application_state`, `settings`,
   or `resources`; persist URLs, ids, or handles instead.
 - Never hardcode API keys, tokens, webhook URLs, signing secrets, private Builder/internal data, customer data, or credential-looking literals. Use secrets/OAuth/runtime configuration and obvious placeholders in examples.
+- For external integrations, inspect the workspace/provider connection catalog first; reuse its scoped resolver.
 
 ## Application State