Make BackAI SupportDesk-first and public-ready

.env.example

@@ -1,5 +1,8 @@
-# AF Stack environment configuration
-# Copy this file to .env and fill in your values.
+# BackAI environment configuration.
+#
+# Copy this file to .env and fill in your values. Public docs use the BackAI
+# name. Existing runtime/package variables intentionally keep the stable
+# AF_STACK_* namespace to avoid breaking deploys and forks.
 
 # ---------- Required ----------
 
@@ -56,13 +59,17 @@ AF_STACK_KMS_KEY=change-me-to-a-real-key
 
 # ---------- LLM providers (set what you use) ----------
 #
-# AF Stack runs a LiteLLM Proxy sidecar (image
+# BackAI runs a LiteLLM Proxy sidecar (image
 # ghcr.io/berriai/litellm:main-stable) on port 4000. Every /api/v1/llm/*
 # call from customers is forwarded there. You drop in a provider key
 # here, the matching `model_list` entry in
 # apps/backend/litellm-config.yaml activates, and 100+ models become
 # usable without code changes.
 
+# First-run mode. "auto" uses the deterministic no-key demo provider when no
+# provider key below is set, and switches to LiteLLM when you add a real key.
+AF_STACK_DEMO_MODE=auto
+
 # Recommended for quickstart: one OpenRouter key gets you many models.
 # The sample agent picks a cheap-but-capable default model
 # (qwen/qwen-2.5-72b-instruct, about $0.35/$0.40 per 1M tokens) so demos
@@ -150,7 +157,7 @@ AF_STACK_S3_REGION=us-east-1
 # GOOGLE_CLIENT_ID=
 # GOOGLE_CLIENT_SECRET=
 #
-# Enterprise SSO/SAML (#26): AF Stack accepts OIDC here. For SAML
+# Enterprise SSO/SAML (#26): BackAI accepts OIDC here. For SAML
 # customers, put Authentik in front as the self-hosted SAML-to-OIDC
 # bridge, or use WorkOS as the managed broker. Register:
 #   <BETTER_AUTH_URL>/api/auth/oauth2/callback/enterprise-sso
@@ -178,7 +185,7 @@ AF_STACK_S3_REGION=us-east-1
 # E2B_API_KEY=
 # AF_STACK_E2B_BASE_URL=https://api.e2b.dev
 
-# Shipwright coding-agent factory. AF Stack stores task metadata; AgentField
+# Shipwright coding-agent factory. BackAI stores task metadata; AgentField
 # owns the execution graph, harness calls, logs, spans, traces, and memory.
 # AF_STACK_SHIPWRIGHT_AGENT_CALL=shipwright.build
 
@@ -237,5 +244,16 @@ LOG_FORMAT=json
 # ---------- Development ----------
 
 NODE_ENV=development
-PORT=8080
-DASHBOARD_PORT=3000
+# Advanced coding-agent surfaces are available but hidden from first-run
+# navigation unless explicitly enabled.
+AF_STACK_SHOW_SHIPWRIGHT=false
+POSTGRES_PORT=5432
+MINIO_PORT=9000
+MINIO_CONSOLE_PORT=9001
+LITELLM_PORT=4000
+AGENTFIELD_PORT=8081
+AF_STACK_PORT=8080
+AF_STACK_METRICS_PORT=9090
+AF_STACK_DASHBOARD_PORT=33000
+AF_STACK_CUSTOMER_APP_PORT=34000
+SVIX_PORT=8071

.gitignore

@@ -40,7 +40,8 @@ htmlcov/
 .tox/
 .hypothesis/
 dist/
-build/
+**/dist/
+/build/
 .venv/
 .venv-*/
 venv/
@@ -50,6 +51,7 @@ venv/
 *.out
 vendor/
 bin/
+/af-stack
 
 # Next.js
 .next/
@@ -58,9 +60,13 @@ next-env.d.ts
 
 # Build artifacts
 dist/
-build/
+**/dist/
+/build/
 *.tsbuildinfo
 
+# Local verification captures
+development/*.png
+
 # Test artifacts
 coverage/
 .nyc_output/

Makefile

@@ -1,12 +1,13 @@
-.PHONY: help dev test test-go test-py test-ts lint lint-go lint-py lint-ts \
+.PHONY: help preflight dev test test-go test-py test-ts lint lint-go lint-py lint-ts \
         build build-go build-dashboard build-images \
         up down logs clean install-deps fmt
 
 # Default target
 help:
-	@echo "AF Stack - common development commands"
+	@echo "BackAI - common development commands"
 	@echo ""
 	@echo "  make install-deps   Install all language-level deps (Go, Python, Node)"
+	@echo "  make preflight      Check local port conflicts before Docker starts"
 	@echo "  make dev            Start dev environment (docker-compose up + hot reload)"
 	@echo "  make up             docker-compose up -d"
 	@echo "  make down           docker-compose down"
@@ -28,11 +29,14 @@ install-deps:
 	@echo "==> Installing Python deps"
 	@command -v uv >/dev/null && uv sync || echo "uv not found, skipping"
 
-dev:
+preflight:
+	node scripts/preflight.mjs
+
+dev: preflight
 	@echo "==> Starting docker-compose stack"
 	docker compose up
 
-up:
+up: preflight
 	docker compose up -d
 
 down: