Add app name validation and improve appkit template docs (#4031)

Fixes based on agent trajectory analysis to reduce common errors:

**Validation:**
- Add app name length validation in init-template command
- Prevents deployment failures from names exceeding 30 chars
(dev-<name>)
- Clear error messages with max length guidance

**Documentation improvements in CLAUDE.md:**
- Document TypeScript verbatimModuleSyntax requirement (import type
usage)
- Clarify useAnalyticsQuery API - no enabled/refetch options available
- Add guidance for updating smoke tests after app customization
- Document app naming constraints with examples

Author: arsenyinfo

experimental/apps-mcp/cmd/init_template.go

@@ -14,6 +14,20 @@ import (
 	"github.com/spf13/cobra"
 )
 
+func validateAppNameLength(projectName string) error {
+	const maxAppNameLength = 30
+	const devTargetPrefix = "dev-"
+	totalLength := len(devTargetPrefix) + len(projectName)
+	if totalLength > maxAppNameLength {
+		maxAllowed := maxAppNameLength - len(devTargetPrefix)
+		return fmt.Errorf(
+			"app name too long: 'dev-%s' is %d chars (max: %d). App name must be ≤%d characters",
+			projectName, totalLength, maxAppNameLength, maxAllowed,
+		)
+	}
+	return nil
+}
+
 func readClaudeMd(ctx context.Context, configFile string) {
 	showFallback := func() {
 		cmdio.LogString(ctx, "\nConsult with CLAUDE.md provided in the bundle if present.")
@@ -109,6 +123,19 @@ See https://docs.databricks.com/en/dev-tools/bundles/templates.html for more inf
 			return errors.New("only one of --config-file or --config-json can be specified")
 		}
 
+		if configFile != "" {
+			if configBytes, err := os.ReadFile(configFile); err == nil {
+				var userConfigMap map[string]any
+				if err := json.Unmarshal(configBytes, &userConfigMap); err == nil {
+					if projectName, ok := userConfigMap["project_name"].(string); ok {
+						if err := validateAppNameLength(projectName); err != nil {
+							return err
+						}
+					}
+				}
+			}
+		}
+
 		var templatePathOrUrl string
 		if len(args) > 0 {
 			templatePathOrUrl = args[0]
@@ -157,6 +184,13 @@ See https://docs.databricks.com/en/dev-tools/bundles/templates.html for more inf
 				return fmt.Errorf("invalid JSON in --config-json: %w", err)
 			}
 
+			// Validate app name length
+			if projectName, ok := userConfigMap["project_name"].(string); ok {
+				if err := validateAppNameLength(projectName); err != nil {
+					return err
+				}
+			}
+
 			tmpFile, err := os.CreateTemp("", "mcp-template-config-*.json")
 			if err != nil {
 				return fmt.Errorf("create temp config file: %w", err)