jitokim
diff --git a/‎CHANGELOG.md‎
Lines changed: 35 additions & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 35 additions & 0 deletions
diff --git a/‎internal/handoff/handoff.go‎
Lines changed: 15 additions & 2 deletions b/‎internal/handoff/handoff.go‎
Lines changed: 15 additions & 2 deletions
diff --git a/‎internal/handoff/handoff_test.go‎
Lines changed: 47 additions & 0 deletions b/‎internal/handoff/handoff_test.go‎
Lines changed: 47 additions & 0 deletions
@@ -12,6 +12,41 @@ oh-my-graph is **alpha software**. The graph YAML schema, the CLI, and the
 
 ### Changed
 
+- **An unresolvable `{{ inputs.x }}` or `{{ artifacts.id }}` now says that a
+  merely-quoted placeholder is resolved too, and how to quote one.** The two
+  reasons were written as if the graph had meant the token — the artifact one
+  asserts "its producing node has not completed" about a node that may not
+  exist — so a prompt that only explains the syntax to the model got a
+  diagnostic pointing at wiring that was never there.
+
+  Before, both errors said only what was missing:
+
+  ```
+  cannot resolve {{ inputs.demo }}: no such input was provided
+  cannot resolve {{ artifacts.nosuch }}: artifact not available (its producing node has not completed)
+  ```
+
+  After, each carries a second line stating the rule and the way out:
+
+  ```
+  cannot resolve {{ inputs.demo }}: no such input was provided
+  note: every {{ ... }} in a prompt is resolved, including one that is only being quoted or explained — to keep such text literal, break the two braces apart ("{ {"), or pass the text in as an input or artifact instead of writing it in the prompt
+  ```
+
+  The artifacts form gains the same single line after `artifact not available
+  (its producing node has not completed)`. The command those two captures came
+  from is the address for them — a graph whose prompts only *mention* the
+  syntax:
+
+  ```sh
+  go run ./cmd/oh-my-graph run /tmp/omg-repro-placeholder.yaml --dry-run
+  ```
+
+  Appended at exactly those two sites and nowhere else: a filter on a feedback
+  token and an unreadable artifact file are real wiring bugs, where this advice
+  would mislead. Wording only — no escaping syntax, no flag, and what
+  `Interpolate` resolves is unchanged.
+
 - **`runs list` collapses the per-run skip warnings into one summary line, and
   the detail moves behind `--show-skipped`.** Option chosen: *collapse by
   default, restore on demand* — not silence, and not a filter. Every skipped
 
@@ -44,6 +44,19 @@ func (e *InterpolationError) Error() string {
 	return fmt.Sprintf("cannot resolve {{ %s.%s }}: %s", e.Kind, e.Reference, e.Reason)
 }
 
+// quotingHint is the second line of the two diagnostics a prompt earns when it
+// only MENTIONS a placeholder instead of using one. Both reasons below name a
+// wiring bug ("no such input", "its producing node has not completed"), which
+// presumes the graph meant the token — but the commonest way to reach them is a
+// prompt that quotes the syntax from another graph or explains it to the model.
+// The hint states the rule and the way out, so the reader is not left debugging
+// a node that does not exist. It is appended ONLY at those two sites: a filter
+// on a feedback token, or an unreadable artifact file, are real wiring bugs
+// where this advice would mislead.
+const quotingHint = "\nnote: every {{ ... }} in a prompt is resolved, including one that is only being quoted or explained — " +
+	"to keep such text literal, break the two braces apart (\"{ {\"), or pass the text in as an input or artifact " +
+	"instead of writing it in the prompt"
+
 // placeholderPattern matches {{ inputs.name }} / {{ artifacts.id }} /
 // {{ feedback.id }} with an optional `| inline` filter. Group 1 = kind,
 // group 2 = reference, group 3 = filter (empty or "inline"). Whitespace
@@ -143,7 +156,7 @@ func (h *Handoff) resolveLocked(kind, ref, filter string) (string, error) {
 	if kind == "inputs" {
 		value, ok := h.inputs[ref]
 		if !ok {
-			return "", &InterpolationError{Kind: kind, Reference: ref, Reason: "no such input was provided"}
+			return "", &InterpolationError{Kind: kind, Reference: ref, Reason: "no such input was provided" + quotingHint}
 		}
 		return value, nil
 	}
@@ -167,7 +180,7 @@ func (h *Handoff) resolveLocked(kind, ref, filter string) (string, error) {
 		return "", &InterpolationError{
 			Kind:      kind,
 			Reference: ref,
-			Reason:    "artifact not available (its producing node has not completed)",
+			Reason:    "artifact not available (its producing node has not completed)" + quotingHint,
 		}
 	}
 	if filter != "inline" {
 
@@ -33,6 +33,7 @@ func TestInterpolate_MissingInput(t *testing.T) {
 	if iErr.Reference != "nope" || iErr.Kind != "inputs" {
 		t.Fatalf("error identified the wrong reference: %+v", iErr)
 	}
+	assertQuotingHint(t, err)
 }
 
 // --- interpolation: artifacts ----------------------------------------------
@@ -103,6 +104,52 @@ func TestInterpolate_ArtifactNotYetAvailable(t *testing.T) {
 	if iErr.Kind != "artifacts" || iErr.Reference != "pending" {
 		t.Fatalf("wrong reference in error: %+v", iErr)
 	}
+	assertQuotingHint(t, err)
+}
+
+// assertQuotingHint pins the second diagnostic line by its own words, not by
+// the constant that produces it: an assertion written against quotingHint
+// would keep passing if the sentence lost the rule or the remedy.
+func assertQuotingHint(t *testing.T, err error) {
+	t.Helper()
+	if err == nil {
+		t.Fatal("expected an interpolation error, got nil")
+	}
+	for _, want := range []string{
+		"every {{ ... }} in a prompt is resolved, including one that is only being quoted or explained",
+		`break the two braces apart ("{ {")`,
+		"pass the text in as an input or artifact",
+	} {
+		if !strings.Contains(err.Error(), want) {
+			t.Fatalf("error is missing the quoting hint %q:\n%v", want, err)
+		}
+	}
+}
+
+// TestInterpolate_MentionedPlaceholderExplainsItself is the reported defect: a
+// prompt that only TALKS ABOUT a placeholder is interpolated like any other,
+// and the bare reason then asserts a wiring bug — for artifacts, that a node
+// which does not exist "has not completed". Both forms must carry the hint,
+// because both reach the reader with nothing else to explain what happened.
+func TestInterpolate_MentionedPlaceholderExplainsItself(t *testing.T) {
+	h := New(t.TempDir(), nil)
+
+	for _, tc := range []struct {
+		name string
+		tmpl string
+	}{
+		{"inputs", "In another graph you would write {{ inputs.demo }} to read an input."},
+		{"artifacts", "In another graph you would write {{ artifacts.nosuch }} to read an artifact."},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			_, err := h.Interpolate(tc.tmpl)
+			var iErr *InterpolationError
+			if !errors.As(err, &iErr) {
+				t.Fatalf("expected *InterpolationError, got %T: %v", err, err)
+			}
+			assertQuotingHint(t, err)
+		})
+	}
 }
 
 func TestPersistOutput_WritesFile(t *testing.T) {