diff --git a/src/lib/components/StackEnvVarsPanel.svelte b/src/lib/components/StackEnvVarsPanel.svelte
index 17ffb0c..b51a734 100644
--- a/src/lib/components/StackEnvVarsPanel.svelte
+++ b/src/lib/components/StackEnvVarsPanel.svelte
@@ -88,6 +88,16 @@
 	// Count of secrets (for display in hint)
 	const secretCount = $derived(variables.filter(v => v.isSecret && v.key.trim()).length);
 
+	// True when any variable's VALUE is a provider reference (op:// / pass://).
+	// Such a reference is resolved only here (stack env), never when written
+	// straight into a compose environment: block - so we surface a hint.
+	const hasProviderReference = $derived(
+		variables.some((v) => {
+			const val = (v.value ?? '').trim();
+			return val.startsWith('op://') || val.startsWith('pass://');
+		})
+	);
+
 	// Generate text representation from variables (non-secrets only)
 	// This is used for text view display
 	const generatedRawContent = $derived.by(() => {
@@ -486,6 +496,15 @@
 				</div>
 			</div>
 		{/if}
+		<!-- Provider-reference placement hint: op:// / pass:// only resolve here, not in compose environment: -->
+		{#if hasProviderReference}
+			<div class="flex items-start gap-2 px-2.5 py-2 rounded bg-amber-50 dark:bg-amber-900/20 border border-amber-200 dark:border-amber-800/50">
+				<Info class="w-4 h-4 text-amber-500 shrink-0 mt-0.5" />
+				<p class="text-xs text-amber-700 dark:text-amber-300">
+					A <code class="bg-amber-100 dark:bg-amber-800/40 px-1 rounded">op://</code> / <code class="bg-amber-100 dark:bg-amber-800/40 px-1 rounded">pass://</code> reference is resolved <strong>here</strong>, in the stack's environment. It is <strong>not</strong> resolved when written directly in a compose <code class="bg-amber-100 dark:bg-amber-800/40 px-1 rounded">environment:</code> block - reference the variable there with <code class="bg-amber-100 dark:bg-amber-800/40 px-1 rounded">${'{VAR}'}</code> instead.
+				</p>
+			</div>
+		{/if}
 		<!-- Parse warnings (form mode only) -->
 		{#if viewMode === 'form' && parseWarnings.length > 0}
 			<div class="flex items-start gap-2 px-2 py-1.5 rounded bg-amber-50 dark:bg-amber-900/20 border border-amber-200 dark:border-amber-800/50">