aitools: warn when --experimental is set but manifest has none

The default DATABRICKS_SKILLS_REF pin is a release tag that pre-dates
the experimental_skills manifest section (see
databricks/databricks-agent-skills#73). Users who pass --experimental
against that ref today silently get no experimental skills installed.

Log a Warnf at install time pointing them at the env var override
(=main, or a future release that includes the section).

Helper: manifestHasExperimental(), unit-tested in source_test.go.

Co-authored-by: Isaac

Author: jamesbroadhead

experimental/aitools/lib/installer/installer.go

@@ -30,6 +30,17 @@ const (
 	experimentalSuffix   = "-experimental"
 )
 
+// manifestHasExperimental reports whether the flattened manifest contains
+// at least one entry marked Experimental=true.
+func manifestHasExperimental(m *Manifest) bool {
+	for _, meta := range m.Skills {
+		if meta.Experimental {
+			return true
+		}
+	}
+	return false
+}
+
 // alternateVariantKey returns the manifest key of the same logical skill
 // under the opposite experimental status. For "databricks-jobs" it returns
 // "databricks-jobs-experimental"; for "databricks-jobs-experimental" it
@@ -135,6 +146,12 @@ func InstallSkillsForAgents(ctx context.Context, src ManifestSource, targetAgent
 		return err
 	}
 
+	// Helpful nudge for users testing --experimental against a ref that
+	// pre-dates the experimental_skills manifest section.
+	if opts.IncludeExperimental && !manifestHasExperimental(manifest) {
+		log.Warnf(ctx, "--experimental was set but the manifest at %s exposes no experimental skills. Set DATABRICKS_SKILLS_REF to a release that includes them (or =main for the latest).", ref)
+	}
+
 	scope := opts.Scope
 	if scope == "" {
 		scope = ScopeGlobal

experimental/aitools/lib/installer/source_test.go

@@ -60,6 +60,25 @@ func TestFlattenManifestCollidingNamesCoexist(t *testing.T) {
 	assert.Equal(t, "databricks-jobs", exp.SourceName, "SourceName is the un-suffixed name for the fetch URL")
 }
 
+func TestManifestHasExperimental(t *testing.T) {
+	stableOnly := &Manifest{Skills: map[string]SkillMeta{
+		"databricks-apps": {Version: "0.1.0"},
+	}}
+	flattenManifest(stableOnly)
+	assert.False(t, manifestHasExperimental(stableOnly))
+
+	withExperimental := &Manifest{
+		Skills: map[string]SkillMeta{
+			"databricks-apps": {Version: "0.1.0"},
+		},
+		ExperimentalSkills: map[string]SkillMeta{
+			"databricks-iceberg": {Version: "0.0.1"},
+		},
+	}
+	flattenManifest(withExperimental)
+	assert.True(t, manifestHasExperimental(withExperimental))
+}
+
 func TestAlternateVariantKey(t *testing.T) {
 	assert.Equal(t, "databricks-jobs-experimental", alternateVariantKey("databricks-jobs"))
 	assert.Equal(t, "databricks-jobs", alternateVariantKey("databricks-jobs-experimental"))