@agent-native/core 0.161.16 → 0.161.20

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!(
@@ -4055,7 +4107,11 @@ fn recording_file_has_bytes(path: &Path) -> bool {
 }
 
 fn remove_empty_recording_artifacts(session: &NativeFullscreenSession) {
-    for path in session.segments.iter().chain(std::iter::once(&session.path)) {
+    for path in session
+        .segments
+        .iter()
+        .chain(std::iter::once(&session.path))
+    {
         if !path.exists() {
             continue;
         }
@@ -4163,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('.')
     )))
 }
@@ -4495,8 +4551,7 @@ fn write_bytes_atomically(path: &Path, data: &[u8], label: &str) -> Result<(), S
         .and_then(|value| value.to_str())
         .unwrap_or("recording");
     let temporary = path.with_file_name(format!(".{file_name}.tmp"));
-    std::fs::write(&temporary, data)
-        .map_err(|error| format!("{label} write failed: {error}"))?;
+    std::fs::write(&temporary, data).map_err(|error| format!("{label} write failed: {error}"))?;
     if let Err(error) = std::fs::rename(&temporary, path) {
         let _ = std::fs::remove_file(&temporary);
         return Err(format!("{label} finalize failed: {error}"));

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

@@ -1,3 +1,9 @@
+use std::{
+    ffi::OsString,
+    path::{Path, PathBuf},
+    process::{Command, Stdio},
+};
+
 use tauri::{AppHandle, Emitter, Manager, WebviewUrl, WebviewWindow, WebviewWindowBuilder};
 
 use crate::dlog;
@@ -505,6 +511,78 @@ pub fn frontmost_bundle_id() -> Option<String> {
     None
 }
 
+fn bundle_path_from_executable_path(executable_path: &Path) -> Option<PathBuf> {
+    let macos_dir = executable_path.parent()?;
+    if macos_dir.file_name()?.to_str()? != "MacOS" {
+        return None;
+    }
+    let contents_dir = macos_dir.parent()?;
+    let bundle_path = contents_dir.parent()?;
+    Some(bundle_path.to_path_buf())
+}
+
+#[tauri::command]
+pub fn restart_bundle_path() -> Result<String, String> {
+    let executable_path = std::env::current_exe().map_err(|err| format!("current_exe: {err}"))?;
+    #[cfg(target_os = "macos")]
+    let bundle_path = bundle_path_from_executable_path(&executable_path).ok_or_else(|| {
+        format!(
+            "could not derive macOS bundle path from {}",
+            executable_path.display()
+        )
+    })?;
+    #[cfg(not(target_os = "macos"))]
+    let bundle_path = executable_path;
+    Ok(bundle_path.to_string_lossy().into_owned())
+}
+
+#[cfg(target_os = "macos")]
+fn spawn_macos_restart_helper(bundle_path: &Path, args: &[OsString]) -> Result<(), String> {
+    let parent_pid = std::process::id().to_string();
+    let mut command = Command::new("/bin/sh");
+    command
+        .arg("-c")
+        .arg(
+            r#"
+parent_pid="$1"
+bundle_path="$2"
+shift 2
+while kill -0 "$parent_pid" >/dev/null 2>&1; do
+  sleep 0.1
+done
+if [ "$#" -gt 0 ]; then
+  exec /usr/bin/open -n "$bundle_path" --args "$@"
+else
+  exec /usr/bin/open -n "$bundle_path"
+fi
+"#,
+        )
+        .arg("clips-restart-helper")
+        .arg(parent_pid)
+        .arg(bundle_path)
+        .args(args.iter().skip(1))
+        .stdin(Stdio::null())
+        .stdout(Stdio::null())
+        .stderr(Stdio::null());
+
+    command
+        .spawn()
+        .map_err(|err| format!("spawn restart helper: {err}"))?;
+    Ok(())
+}
+
+#[cfg(not(target_os = "macos"))]
+fn spawn_macos_restart_helper(_bundle_path: &Path, _args: &[OsString]) -> Result<(), String> {
+    Err("macOS restart helper is unavailable on this platform".to_string())
+}
+
+#[tauri::command]
+pub fn schedule_restart_after_exit(bundle_path: String) -> Result<(), String> {
+    let bundle_path = PathBuf::from(bundle_path);
+    let args: Vec<OsString> = std::env::args_os().collect();
+    spawn_macos_restart_helper(&bundle_path, &args)
+}
+
 pub fn set_dictation_active(app: &AppHandle, active: bool) {
     if let Some(state) = app.try_state::<DictationActive>() {
         if let Ok(mut g) = state.0.lock() {
@@ -537,3 +615,23 @@ pub fn hide_voice_wake_popover(app: &AppHandle) {
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::bundle_path_from_executable_path;
+    use std::path::Path;
+
+    #[test]
+    fn derives_macos_bundle_path_from_app_executable() {
+        let executable = Path::new("/Applications/Clips.app/Contents/MacOS/Clips");
+        let bundle =
+            bundle_path_from_executable_path(executable).expect("expected macOS bundle path");
+        assert_eq!(bundle, Path::new("/Applications/Clips.app"));
+    }
+
+    #[test]
+    fn rejects_non_bundle_executable_paths() {
+        let executable = Path::new("/Users/steve/dev/Clips");
+        assert!(bundle_path_from_executable_path(executable).is_none());
+    }
+}

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

@@ -174,6 +174,14 @@ export default defineEventHandler(async (event: H3Event) => {
     uploadGenerationId?: string;
     useGenerationFence?: boolean;
   } | null;
+  const requestedStreamingMimeType =
+    body?.requestStreaming === true
+      ? normalizeVideoMimeType(body.mimeType)
+      : null;
+  if (body?.requestStreaming === true && !requestedStreamingMimeType) {
+    setResponseStatus(event, 400);
+    return { error: "A supported video mimeType is required for retry" };
+  }
   const recoveryEnabled = await isFeatureFlagEnabled(UPLOAD_RETRY_RESUME_FLAG, {
     userEmail: ownerEmail,
     userKey: ownerEmail,
@@ -353,6 +361,7 @@ export default defineEventHandler(async (event: H3Event) => {
       if (claimed) cleanupClaim = candidate;
     }
 
+    let resumableCleanupFailed = false;
     if (discardedResumableSession) {
       if (cleanupClaim) {
         const cleaned = await abortResumableUploadSession(
@@ -360,21 +369,34 @@ export default defineEventHandler(async (event: H3Event) => {
           { label: `reset-${recordingId}` },
         );
         if (!cleaned) {
-          setResponseStatus(event, 502);
-          return {
-            error:
-              "The previous recording upload could not be cleaned up. Retry the upload restart.",
-          };
-        }
-        const released = await compareAndSetAppState(
-          cleanupStateKey,
-          cleanupClaim as unknown as Record<string, unknown>,
-          null,
-        );
-        if (!released) {
+          if (!allowsSqlRecordingChunkScratch()) {
+            setResponseStatus(event, 502);
+            return {
+              error:
+                "The previous recording upload could not be cleaned up. Retry the upload restart.",
+            };
+          }
+          // The provider-side session may remain orphaned when abort fails,
+          // but local buffered scratch is a complete recovery path for the
+          // saved file. Keep the cleanup claim for a later retry, remove the
+          // stale local session handle, and force the new chunks through the
+          // buffered handler instead of returning the same 502 repeatedly.
           console.warn(
-            `[reset-chunks-${recordingId}] cleanup claim changed while releasing it`,
+            `[reset-chunks-${recordingId}] provider cleanup failed; using buffered retry and retaining cleanup claim`,
           );
+          resumableCleanupFailed = true;
+        }
+        if (!resumableCleanupFailed) {
+          const released = await compareAndSetAppState(
+            cleanupStateKey,
+            cleanupClaim as unknown as Record<string, unknown>,
+            null,
+          );
+          if (!released) {
+            console.warn(
+              `[reset-chunks-${recordingId}] cleanup claim changed while releasing it`,
+            );
+          }
         }
       }
     }
@@ -385,22 +407,34 @@ export default defineEventHandler(async (event: H3Event) => {
     );
     // Clear any stale resumable session so a buffered retry does not
     // accidentally route through handleResumableChunk with stale offsets.
-    if (!discardedResumableSession || cleanupClaim) {
-      await deleteResumableSession(recordingId, discardedGenerationId).catch(
-        () => {},
-      );
+    if (!discardedResumableSession || cleanupClaim || resumableCleanupFailed) {
+      try {
+        await deleteResumableSession(recordingId, discardedGenerationId);
+      } catch (error) {
+        console.warn(
+          `[reset-chunks-${recordingId}] local resumable session cleanup failed`,
+          error,
+        );
+        setResponseStatus(event, 502);
+        return {
+          error:
+            "The previous recording upload could not be reset locally. Retry the upload restart.",
+        };
+      }
     }
 
     let uploadMode: UploadMode = "buffered";
     let compensateStartedSession: (() => Promise<void>) | null = null;
-    if (body?.requestStreaming === true) {
-      const mimeType = normalizeVideoMimeType(body.mimeType);
+    const bufferedFallbackAvailable = allowsSqlRecordingChunkScratch();
+    const shouldRetryStreaming =
+      body?.requestStreaming === true && !resumableCleanupFailed;
+    if (shouldRetryStreaming) {
+      const mimeType = requestedStreamingMimeType;
       if (!mimeType) {
         setResponseStatus(event, 400);
         return { error: "A supported video mimeType is required for retry" };
       }
 
-      const bufferedFallbackAvailable = allowsSqlRecordingChunkScratch();
       const uploadProvider = await getActiveFileUploadProviderForRequest();
       if (
         shouldEnableStreamingUpload({

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
 

package/corpus/templates/crm/.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/crm/.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/crm/.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/crm/AGENTS.md

@@ -30,6 +30,7 @@ HubSpot/Salesforce lens; UI and agent share actions.
 
 - Workspace Connections own provider credentials. Never request, store, log, or
   return a provider token.
+- For external integrations, inspect the workspace/provider connection catalog first; reuse its scoped resolver.
 - The mirror is thin: unknown fields are remote-only, sensitive ones redacted,
   only allow-listed fields mirrored. Raw payloads, transcripts, media, and
   base64 never enter SQL — evidence is a URL/id plus a bounded quote.

package/corpus/templates/design/.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/design/.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/design/.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