@gxp-dev/tools 2.0.86 → 2.0.88

package/bin/lib/cli.js

@@ -157,6 +157,12 @@ const cli = yargs
 				default: false,
 				alias: "m",
 			},
+			json: {
+				describe:
+					"Emit all dev-server logs as newline-delimited JSON (one record per line) for cloud log collectors",
+				type: "boolean",
+				default: false,
+			},
 		},
 		devCommand,
 	)

package/bin/lib/commands/dev.js

@@ -7,6 +7,7 @@
 
 const path = require("path")
 const fs = require("fs")
+const { spawn } = require("child_process")
 const shell = require("shelljs")
 const dotenv = require("dotenv")
 const {
@@ -16,6 +17,123 @@ const {
 	findExistingCertificates,
 } = require("../utils")
 
+const ANSI_REGEX = /\x1b\[[0-9;]*[a-zA-Z]/g
+
+/**
+ * Create a logger that either emits NDJSON lines or plain text.
+ * In JSON mode, every record is a single line: {timestamp, service, level, message}
+ */
+function createLogger(jsonMode) {
+	function emit(level, service, message) {
+		if (jsonMode) {
+			process.stdout.write(
+				JSON.stringify({
+					timestamp: new Date().toISOString(),
+					service,
+					level,
+					message,
+				}) + "\n",
+			)
+			return
+		}
+		const stream =
+			level === "error" || level === "warn" ? process.stderr : process.stdout
+		stream.write(message + "\n")
+	}
+	return {
+		jsonMode,
+		info: (message, service = "GXDEV") => emit("info", service, message),
+		warn: (message, service = "GXDEV") => emit("warn", service, message),
+		error: (message, service = "GXDEV") => emit("error", service, message),
+	}
+}
+
+/**
+ * Spawn a service and pipe each line of its stdout/stderr through the logger.
+ * Returns the child process.
+ */
+function spawnService(name, command, logger) {
+	const child = spawn(command, {
+		shell: true,
+		stdio: ["ignore", "pipe", "pipe"],
+		env: process.env,
+	})
+
+	function pipe(stream, level) {
+		let buffer = ""
+		stream.setEncoding("utf8")
+		stream.on("data", (chunk) => {
+			buffer += chunk
+			let idx
+			while ((idx = buffer.indexOf("\n")) !== -1) {
+				const line = buffer.slice(0, idx).replace(/\r$/, "")
+				buffer = buffer.slice(idx + 1)
+				const clean = line.replace(ANSI_REGEX, "")
+				if (clean.length > 0) {
+					logger[level](clean, name)
+				}
+			}
+		})
+		stream.on("end", () => {
+			if (buffer.length > 0) {
+				const clean = buffer.replace(ANSI_REGEX, "").trim()
+				if (clean) {
+					logger[level](clean, name)
+				}
+				buffer = ""
+			}
+		})
+	}
+
+	pipe(child.stdout, "info")
+	pipe(child.stderr, "error")
+	return child
+}
+
+/**
+ * Run a list of services concurrently, wiring up line-by-line JSON logging
+ * and best-effort shutdown when any one exits or the user hits Ctrl+C.
+ */
+function runServicesJson(services, logger) {
+	const children = services.map((svc) => {
+		logger.info(`starting ${svc.name}: ${svc.command}`, svc.name)
+		return { svc, child: spawnService(svc.name, svc.command, logger) }
+	})
+
+	let shuttingDown = false
+	function shutdown(code) {
+		if (shuttingDown) {
+			return
+		}
+		shuttingDown = true
+		for (const { child } of children) {
+			if (!child.killed && child.exitCode === null) {
+				child.kill("SIGTERM")
+			}
+		}
+		process.exit(code ?? 0)
+	}
+
+	for (const { svc, child } of children) {
+		child.on("exit", (code, signal) => {
+			logger.info(
+				`${svc.name} exited (code=${code ?? "null"}${
+					signal ? `, signal=${signal}` : ""
+				})`,
+				svc.name,
+			)
+			shutdown(code ?? 0)
+		})
+		child.on("error", (err) => {
+			logger.error(`${svc.name} failed to spawn: ${err.message}`, svc.name)
+			shutdown(1)
+		})
+	}
+
+	process.on("SIGINT", () => shutdown(130))
+	process.on("SIGTERM", () => shutdown(143))
+}
+
 /**
  * Get browser extension paths and commands
  * @param {string} browser - "firefox" or "chrome"
@@ -96,6 +214,7 @@ function getBrowserExtensionConfig(browser, projectPath, paths, options = {}) {
  * Development command - starts the dev server
  */
 function devCommand(argv) {
+	const logger = createLogger(!!argv.json)
 	const paths = resolveGxPaths()
 	const projectPath = findProjectRoot()
 
@@ -105,13 +224,13 @@ function devCommand(argv) {
 
 	// Load .env file into process.env
 	if (fs.existsSync(envPath)) {
-		console.log("📋 Loading environment variables from .env file")
+		logger.info("📋 Loading environment variables from .env file")
 		dotenv.config({ path: envPath })
 	} else if (fs.existsSync(envExamplePath)) {
-		console.log(
+		logger.info(
 			"💡 Tip: Create .env file from .env.example to customize your environment settings",
 		)
-		console.log("   cp .env.example .env")
+		logger.info("   cp .env.example .env")
 	}
 
 	// Check for SSL certificates unless explicitly disabled
@@ -124,32 +243,32 @@ function devCommand(argv) {
 		const existingCerts = findExistingCertificates(certsDir)
 
 		if (!existingCerts) {
-			console.log(
+			logger.warn(
 				"⚠ SSL certificates not found. Run 'npm run setup-ssl' to enable HTTPS",
 			)
-			console.log("🌐 Starting HTTP development server...")
+			logger.info("🌐 Starting HTTP development server...")
 			useHttps = false
 		} else {
-			console.log("🔒 Starting HTTPS development server...")
-			console.log(
+			logger.info("🔒 Starting HTTPS development server...")
+			logger.info(
 				`📁 Using certificate: ${path.basename(existingCerts.certPath)}`,
 			)
-			console.log(`🔑 Using key: ${path.basename(existingCerts.keyPath)}`)
+			logger.info(`🔑 Using key: ${path.basename(existingCerts.keyPath)}`)
 			certPath = existingCerts.certPath
 			keyPath = existingCerts.keyPath
 		}
 	} else {
-		console.log("🌐 Starting HTTP development server...")
+		logger.info("🌐 Starting HTTP development server...")
 	}
 
 	// Determine final port value (priority: CLI arg > .env > default)
 	const finalPort = argv.port || process.env.NODE_PORT || 3000
-	console.log(`🌐 Development server will start on port: ${finalPort}`)
+	logger.info(`🌐 Development server will start on port: ${finalPort}`)
 
 	// Check if mock API should be enabled
 	const withMock = argv["with-mock"]
 	if (withMock) {
-		console.log("🎭 Mock API will be enabled")
+		logger.info("🎭 Mock API will be enabled")
 	}
 
 	// Socket server starts by default unless --no-socket is passed
@@ -159,15 +278,15 @@ function devCommand(argv) {
 		// Check for local server.js first, then runtime directory
 		const serverJs = resolveFilePath("server.cjs", "", "runtime")
 		if (!fs.existsSync(serverJs.path)) {
-			console.warn("⚠ server.js not found. Skipping Socket.IO server.")
+			logger.warn("⚠ server.js not found. Skipping Socket.IO server.")
 		} else {
 			serverJsPath = serverJs.path
-			console.log(
+			logger.info(
 				`📡 Starting Socket.IO server with nodemon... (${
 					serverJs.isLocal ? "local" : "package"
 				} version)`,
 			)
-			console.log(`📁 Using: ${serverJsPath}`)
+			logger.info(`📁 Using: ${serverJsPath}`)
 		}
 	}
 
@@ -184,16 +303,16 @@ function devCommand(argv) {
 		fs.existsSync(path.join(projectPath, "vite.extend.mjs"))
 
 	if (hasLocalIndexHtml) {
-		console.log("📁 Using local index.html")
+		logger.info("📁 Using local index.html")
 	}
 	if (hasLocalMainJs) {
-		console.log("📁 Using local main.js")
+		logger.info("📁 Using local main.js")
 	}
 	if (hasLocalExtend) {
-		console.log("🧩 Extending vite config from vite.extend.js")
+		logger.info("🧩 Extending vite config from vite.extend.js")
 	}
 	if (!hasLocalIndexHtml && !hasLocalMainJs && !hasLocalExtend) {
-		console.log(
+		logger.info(
 			"📦 Using runtime dev files (create vite.extend.js to customize)",
 		)
 	}
@@ -234,11 +353,11 @@ function devCommand(argv) {
 			port: finalPort,
 		})
 		if (firefoxConfig) {
-			console.log("🦊 Firefox extension will launch with dev server")
-			console.log(`📁 Extension path: ${firefoxConfig.extensionPath}`)
-			console.log(`🌐 Start URL: ${firefoxConfig.startUrl}`)
+			logger.info("🦊 Firefox extension will launch with dev server")
+			logger.info(`📁 Extension path: ${firefoxConfig.extensionPath}`)
+			logger.info(`🌐 Start URL: ${firefoxConfig.startUrl}`)
 		} else {
-			console.warn("⚠️ Firefox extension not found, skipping")
+			logger.warn("⚠️ Firefox extension not found, skipping")
 		}
 	}
 
@@ -248,11 +367,11 @@ function devCommand(argv) {
 			port: finalPort,
 		})
 		if (chromeConfig) {
-			console.log("🚀 Chrome extension will launch with dev server")
-			console.log(`📁 Extension path: ${chromeConfig.extensionPath}`)
-			console.log(`🌐 Start URL: ${chromeConfig.startUrl}`)
+			logger.info("🚀 Chrome extension will launch with dev server")
+			logger.info(`📁 Extension path: ${chromeConfig.extensionPath}`)
+			logger.info(`🌐 Start URL: ${chromeConfig.startUrl}`)
 		} else {
-			console.warn("⚠️ Chrome extension not found, skipping")
+			logger.warn("⚠️ Chrome extension not found, skipping")
 		}
 	}
 
@@ -261,54 +380,58 @@ function devCommand(argv) {
 		process.env.CHROME_EXTENSION_PATH = chromeConfig.extensionPath
 	}
 
-	// Build the command based on what's requested
-	let command
-
-	// Collect all processes to run
-	const processes = []
-	const names = []
-	const colors = []
-
 	// Normalize path separators to forward slashes for cross-platform shell compatibility
 	const normalizedViteConfigPath = viteConfigPath.replace(/\\/g, "/")
 
-	// Vite is always included
-	const viteCommand = `npx vite dev --config "${normalizedViteConfigPath}"`
-	processes.push(`"${viteCommand}"`)
-	names.push("VITE")
-	colors.push("cyan")
+	// Build the canonical service list (raw commands, no concurrently wrapping)
+	const services = []
+	services.push({
+		name: "VITE",
+		color: "cyan",
+		command: `npx vite dev --config "${normalizedViteConfigPath}"`,
+	})
 
-	// Socket server (on by default, skip if --no-socket or server.js not found)
 	if (serverJsPath) {
 		const normalizedServerPath = serverJsPath.replace(/\\/g, "/")
-		processes.push(`"npx nodemon \\"${normalizedServerPath}\\""`)
-		names.push("SOCKET")
-		colors.push("green")
+		services.push({
+			name: "SOCKET",
+			color: "green",
+			command: `npx nodemon "${normalizedServerPath}"`,
+		})
 	}
 
-	// Firefox extension (optional)
 	if (firefoxConfig) {
-		processes.push(`"${firefoxConfig.command}"`)
-		names.push(firefoxConfig.name)
-		colors.push(firefoxConfig.color)
+		services.push({
+			name: firefoxConfig.name,
+			color: firefoxConfig.color,
+			command: firefoxConfig.command,
+		})
 	}
 
-	// Chrome extension (optional)
 	if (chromeConfig) {
-		processes.push(`"${chromeConfig.command}"`)
-		names.push(chromeConfig.name)
-		colors.push(chromeConfig.color)
+		services.push({
+			name: chromeConfig.name,
+			color: chromeConfig.color,
+			command: chromeConfig.command,
+		})
 	}
 
-	// Build the final command
-	if (processes.length > 1) {
-		// Use concurrently to run multiple processes
-		command = `npx concurrently --names "${names.join(
-			",",
-		)}" --prefix-colors "${colors.join(",")}" ${processes.join(" ")}`
+	// In JSON mode we orchestrate the children ourselves so we can wrap every
+	// stdout/stderr line as NDJSON. Concurrently's prefixed output would defeat
+	// that. Outside JSON mode, keep the legacy concurrently-based behavior.
+	if (logger.jsonMode) {
+		runServicesJson(services, logger)
+		return
+	}
+
+	let command
+	if (services.length > 1) {
+		const quoted = services.map((s) => `"${s.command}"`).join(" ")
+		const names = services.map((s) => s.name).join(",")
+		const colors = services.map((s) => s.color).join(",")
+		command = `npx concurrently --names "${names}" --prefix-colors "${colors}" ${quoted}`
 	} else {
-		// Just run Vite dev server alone
-		command = `npx vite dev --config "${normalizedViteConfigPath}"`
+		command = services[0].command
 	}
 
 	shell.exec(command)

package/bin/lib/commands/init.js

@@ -173,6 +173,11 @@ function copyBundleFiles(projectPath, paths, overwrite = false) {
 			dest: "GEMINI.md",
 			desc: "GEMINI.md (Gemini Code Assist instructions)",
 		},
+		{
+			src: "CLAUDE.md",
+			dest: "CLAUDE.md",
+			desc: "CLAUDE.md (Claude Code project instructions)",
+		},
 		{
 			src: ".claude/agents/gxp-developer.md",
 			dest: ".claude/agents/gxp-developer.md",

package/mcp/lib/config-tools.js

@@ -285,7 +285,7 @@ const CONFIG_TOOLS = [
 	{
 		name: "config_extract_strings",
 		description:
-			"Scan a plugin's src/ directory for GxP datastore usage and directives (gxp-string, gxp-src, store.getString/getSetting/getAsset/getState calls) and return the extracted keys. Optionally merge them into app-manifest.json (linter-guarded — invalid writes are refused unless force=true).",
+			"Scan a plugin's src/ directory for GxP datastore usage and directives (gxp-string, gxp-src, store.getString/getSetting/getAsset/getState calls) and return the extracted keys. Optionally merge them into app-manifest.json (linter-guarded — invalid writes are refused unless force=true). Note: store.getUser/getUserName/getUserEmail/isAuthenticated and store.user are also valid accessors but read the platform-injected logged-in user (null when logged out) and have no manifest entry.",
 		inputSchema: {
 			type: "object",
 			properties: {

package/mcp/lib/server.js

@@ -46,7 +46,8 @@ const SERVER_INFO = {
 }
 
 const SERVER_DESCRIPTION =
-	"GxP toolkit MCP server: API specs, data models, config/manifest editing, documentation search, and plugin test helpers for AI coding assistants. UIKit component/story tools are served by the uikit's own Storybook MCP (gxdev storybook)."
+	"GxP toolkit MCP server: API specs, data models, config/manifest editing, documentation search, and plugin test helpers for AI coding assistants. UIKit component/story tools are served by the uikit's own Storybook MCP (gxdev storybook).\n\n" +
+	"IMPORTANT context for plugin authors: GxP is a multi-tenant platform. The platform admin UI (not the plugin) owns all configuration of forms, quizzes, surveys, quiz builders, leaderboards, settings, strings, assets, and project metadata. Plugins do NOT define these — they consume them. At runtime the platform injects manifest data (settings, strings, assets, dependencies, permissions) and the logged-in user into the GxP store, and exposes platform-managed resources via the REST API documented in the OpenAPI spec. Plugins should access forms/quizzes/surveys and their admin-built questions exclusively through `store.callApi(operationId, identifier, data)` — for example `forms.show`, `forms.fields.index`, `forms.responses.store`, `quiz.state`, `quiz.questions`, `quiz.answer`, `quiz.leaderboard`, `survey.metrics`. Use the API spec tools (`search_api_endpoints`, `api_list_tags`, `get_endpoint_details`, `describe_data_models`) to discover the exact operationIds, parameters, and response schemas. The logged-in user is read via `store.user` / `store.getUser()` / `store.getUserName()` / `store.getUserEmail()` (null when logged out)."
 
 /* -------------------- API spec search helpers (in-file) ------------------- */
 
@@ -348,7 +349,10 @@ async function startServer() {
 
 	const server = new Server(
 		{ name: SERVER_INFO.name, version: SERVER_INFO.version },
-		{ capabilities: { tools: {} } },
+		{
+			capabilities: { tools: {} },
+			instructions: SERVER_DESCRIPTION,
+		},
 	)
 
 	server.setRequestHandler(ListToolsRequestSchema, async () => ({

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@gxp-dev/tools",
-	"version": "2.0.86",
+	"version": "2.0.88",
 	"description": "Dev tools to create platform plugins",
 	"type": "commonjs",
 	"publishConfig": {

package/runtime/dev-tools/StoreInspector.vue

@@ -212,6 +212,31 @@
 			</div>
 		</div>
 
+		<div class="inspector-section">
+			<h3 class="section-title" @click="toggleSection('user')">
+				<span class="toggle-icon">{{ expandedSections.user ? "▼" : "▶" }}</span>
+				Logged-in User
+				<span class="item-count">{{ store.user ? "auth" : "null" }}</span>
+			</h3>
+			<div v-if="expandedSections.user" class="section-content">
+				<div v-if="!store.user" class="empty-state">
+					No user logged in (store.user === null)
+				</div>
+				<div v-else class="property-list">
+					<div
+						v-for="(value, key) in store.user"
+						:key="key"
+						class="property-item"
+					>
+						<span class="property-key">{{ key }}</span>
+						<span class="property-value" :class="getValueType(value)">
+							{{ formatValue(value) }}
+						</span>
+					</div>
+				</div>
+			</div>
+		</div>
+
 		<div class="inspector-actions">
 			<button
 				class="action-btn"
@@ -251,6 +276,7 @@ const expandedSections = reactive({
 	assetList: false,
 	triggerState: false,
 	dependencyList: false,
+	user: false,
 })
 
 const editingKey = ref(null)

package/runtime/stores/gxpPortalConfigStore.js

@@ -94,6 +94,19 @@ function getApiConfig() {
 	}
 }
 
+// Dev-only fallback user. In production the platform injects the real
+// authenticated user (or null) — this dummy only ships when running under
+// the Vite dev server so plugins can develop against the happy-path shape.
+const DEV_DUMMY_USER = {
+	id: "dev-user-001",
+	first_name: "Jane",
+	last_name: "Developer",
+	name: "Jane Developer",
+	email: "jane.developer@example.com",
+	avatar: null,
+	roles: ["attendee"],
+}
+
 // Default values used when app-manifest.json doesn't exist or is missing keys
 const defaultData = {
 	pluginVars: {
@@ -108,6 +121,7 @@ const defaultData = {
 	triggerState: {},
 	auth: null,
 	userSession: null,
+	user: import.meta.env.DEV ? { ...DEV_DUMMY_USER } : null,
 	pluginData: {},
 	portalAssets: {},
 	portal: null,
@@ -126,6 +140,7 @@ export const useGxpStore = defineStore("gxp-portal-app", () => {
 	// User session data (injected by platform in production)
 	const auth = ref(defaultData.auth)
 	const userSession = ref(defaultData.userSession)
+	const user = ref(defaultData.user ? { ...defaultData.user } : null)
 	const pluginData = ref({ ...defaultData.pluginData })
 	const portalAssets = ref({ ...defaultData.portalAssets })
 	const portal = ref(defaultData.portal)
@@ -599,6 +614,46 @@ export const useGxpStore = defineStore("gxp-portal-app", () => {
 		return permissionFlags.value.includes(flag)
 	}
 
+	/**
+	 * Return the logged-in user object, or null when no user is authenticated.
+	 *
+	 * In production the platform injects the real user. In dev (Vite dev
+	 * server) a dummy user is provided so plugins can develop against the
+	 * happy path without a backend — clear it from the Dev Tools store
+	 * inspector to simulate the logged-out state.
+	 */
+	function getUser() {
+		return user.value ?? null
+	}
+
+	function isAuthenticated() {
+		return user.value !== null && user.value !== undefined
+	}
+
+	/**
+	 * Convenience helper — returns the user's display name (or `name`,
+	 * or `first_name + last_name` if `name` is absent). Returns `fallback`
+	 * when no user is logged in.
+	 */
+	function getUserName(fallback = null) {
+		const u = user.value
+		if (!u) {
+			return fallback
+		}
+		if (u.name) {
+			return u.name
+		}
+		const parts = [u.first_name, u.last_name].filter(Boolean)
+		return parts.length > 0 ? parts.join(" ") : fallback
+	}
+
+	/**
+	 * Returns the user's email, or `fallback` when no user is logged in.
+	 */
+	function getUserEmail(fallback = null) {
+		return user.value?.email ?? fallback
+	}
+
 	// Convenience method to add dev assets with proper URL
 	function addDevAsset(key, filename) {
 		const appPort =
@@ -640,9 +695,7 @@ export const useGxpStore = defineStore("gxp-portal-app", () => {
 			const callback = arg3
 			const primary = socketConnections.primary
 			if (!primary) {
-				console.warn(
-					"[GxP Store] listen(): primary socket not initialized",
-				)
+				console.warn("[GxP Store] listen(): primary socket not initialized")
 				return () => {}
 			}
 			if (
@@ -753,6 +806,7 @@ export const useGxpStore = defineStore("gxp-portal-app", () => {
 		permissionFlags,
 		auth,
 		userSession,
+		user,
 		pluginData,
 		portalAssets,
 		portal,
@@ -775,6 +829,10 @@ export const useGxpStore = defineStore("gxp-portal-app", () => {
 		getSetting,
 		getAsset,
 		getState,
+		getUser,
+		getUserName,
+		getUserEmail,
+		isAuthenticated,
 		hasPermission,
 		findDependency,
 

package/template/.claude/agents/gxp-developer.md

@@ -9,6 +9,19 @@ model: sonnet
 
 You are an expert GxP plugin developer. You help build Vue 3 components for the GxP kiosk platform. You have access to the `gxp-api` MCP server — use it; do not guess at API shapes.
 
+## Platform vs. plugin — read first
+
+The **GxP platform itself** (not the plugin) manages all admin configuration. Plugins consume what the platform provides:
+
+- **Forms, quizzes, surveys, and the quiz builder** are admin-built in the platform UI. The plugin reads admin-built form fields, quiz questions, scoring rules, leaderboards, and response data through `store.callApi` — never define them locally. Key operation families (discover the full set with `api_list_operation_ids` / `search_api_endpoints`):
+  - **Forms** — `forms.index`, `forms.show`, `forms.fields.index`, `forms.fields.show`, `forms.responses.index/store/show/update/destroy`, `my-responses.index/show`.
+  - **Quizzes** — `quiz.state`, `quiz.start`, `quiz.restart`, `quiz.questions`, `quiz.answer`, `quiz.answer.status`, `quiz.complete`, `quiz.timeout`, `quiz.leaderboard`.
+  - **Surveys** — `survey.metrics`, `survey.metrics.question`, `survey.metrics.questions`, `survey.metrics.timeseries`, `survey.live-results`.
+- **Project settings, assets, strings, dependencies, permissions, and the logged-in user** are injected into the GxP store at boot. The plugin reads them via `store.getSetting/getString/getAsset/getState/hasPermission/getUser`.
+- The plugin's `app-manifest.json` + `configuration.json` describe **only what the admin needs to configure for this specific plugin instance** — text, images, colors, which form/quiz the plugin should bind to (via `asyncSelect` against the platform list endpoints). Anything that already exists in the platform belongs upstream; don't recreate it.
+
+If you're unsure whether the platform already provides something, search before building.
+
 ## Workflow — Follow This Every Time
 
 Every plugin feature goes through seven phases. Do not skip phases. Do not implement before the plan is confirmed.
@@ -189,8 +202,19 @@ store.getSetting("primary_color", "#FFD600")
 store.getAsset("hero_image", "/fallback.jpg")
 store.getState("current_step", 0)
 store.hasPermission("admin")
+
+// Logged-in user (returns null when no user is authenticated)
+store.getUser() // Full user object or null
+store.getUserName("Guest") // Display name with fallback
+store.getUserEmail() // Email or null
+store.isAuthenticated() // boolean
 ```
 
+`store.user` is **null when no user is logged in** — always guard. The
+shape is `{ id, first_name, last_name, name, email, avatar, roles[] }`.
+The platform injects this in production; `gxdev dev` ships a dummy
+authenticated user so happy-path UI renders without a backend.
+
 ## API Calls — `store.callApi(operationId, identifier, data)`
 
 **Every call to the GxP platform goes through `store.callApi`.** It is the primary, permission-aware API method. The low-level verb methods (`apiGet`/`apiPost`/...) still exist as escape hatches but they bypass the permission model — prefer `callApi` for all real work. Never use axios or fetch directly.

package/template/AGENTS.md

@@ -2,6 +2,16 @@
 
 This is a GxP plugin project for the GxP kiosk platform. Follow these guidelines when working with this codebase.
 
+## Platform vs. plugin — who owns what
+
+**The GxP platform itself owns all admin configuration.** Plugins are consumers, not configurators:
+
+- **Forms, quizzes, and surveys (including the quiz builder)** are built by admins in the platform UI. The plugin never defines fields, questions, scoring rules, leaderboards, or response schemas. At runtime the plugin reads the admin-built form/quiz/survey — and its questions — through `store.callApi`. Relevant operations: `forms.show`, `forms.fields.index`, `forms.responses.store/show/update`, `quiz.state`, `quiz.start`, `quiz.questions`, `quiz.answer`, `quiz.complete`, `quiz.leaderboard`, `survey.metrics`, `survey.live-results`. Discover the full set with `api_list_operation_ids` filtered by the `forms`/`quiz`/`survey` tags.
+- **Project settings, assets, strings, dependencies, permissions, and the logged-in user** are injected into the GxP store at boot — plugins read them, they don't create them.
+- The plugin's own `app-manifest.json` + `configuration.json` describe **what the admin must configure for THIS plugin instance** (text, images, colors, which form/quiz to bind to, etc.). Everything else lives upstream.
+
+When in doubt, search for the operation via `search_api_endpoints` / `api_list_tags` before inventing local state.
+
 ## Development Workflow
 
 Every task starts with understanding and ends with a validated, linted build. Do not skip steps.
@@ -222,6 +232,22 @@ store.updateAsset("key", "url")
 store.updateState("key", "value")
 ```
 
+### Logged-in user
+
+```javascript
+const user = store.getUser() // Full user object, or `null` if logged out
+store.getUserName("Guest") // Display name with fallback
+store.getUserEmail() // Email or null
+store.isAuthenticated() // boolean
+// Or read the ref directly: store.user
+```
+
+`store.user` is **`null` when no user is authenticated** — always guard
+before dereferencing. Shape: `{ id, first_name, last_name, name, email,
+avatar, roles[] }`. In `gxdev dev` a dummy authenticated user is injected
+so the happy path renders without a backend; in production the platform
+injects the real user.
+
 ## Real-Time Events
 
 Every plugin has two streams of real-time events, both surfaced through the store:

package/template/CLAUDE.md

@@ -0,0 +1,25 @@
+# GxP Plugin — Claude Code Instructions
+
+This is a GxP plugin project for the GxP kiosk platform. Use the shared
+project guidelines below for everything you do here.
+
+## Project guidelines (shared with Codex/Cursor)
+
+@AGENTS.md
+
+## Claude Code specifics
+
+- **Subagent:** `.claude/agents/gxp-developer.md` — auto-invoked for GxP
+  plugin tasks. Use it for any non-trivial Vue/store/`callApi` work.
+- **MCP servers:** wired in `.mcp.json` at the project root.
+  - `gxp-api` (via `mcp-serve` on PATH) — API specs, data models,
+    config/manifest editing, docs search, test helpers.
+  - `gxp-uikit-storybook` — UIKit component/story tools (only available
+    when `gxdev storybook` is running, served at
+    `http://localhost:6006/mcp`).
+- **Settings:** `.claude/settings.json` — pre-allows the `gxp-api` MCP
+  tools so you don't get prompted on every call.
+
+If the `api_*` / `config_*` / `docs_*` MCP tools aren't available, run
+`claude mcp add gxp-api mcp-serve` and restart the session before
+proceeding. Do not invent endpoints — discover them through the MCP.

package/template/GEMINI.md

@@ -2,6 +2,14 @@
 
 This is a GxP plugin project for the GxP kiosk platform built with Vue 3.
 
+## Platform vs. plugin
+
+The GxP platform owns admin configuration. Plugins consume it, they don't define it.
+
+- **Forms, quizzes, surveys (including the quiz builder) are built in the platform admin UI.** The plugin reads admin-built fields/questions/scoring/leaderboards at runtime via `store.callApi` — operations like `forms.show`, `forms.fields.index`, `forms.responses.store`, `quiz.state`, `quiz.questions`, `quiz.answer`, `quiz.leaderboard`, `survey.metrics`. Use `api_list_operation_ids` / `search_api_endpoints` to discover the full set.
+- **Project settings, assets, strings, dependencies, permissions, and the logged-in user** are injected into the GxP store at boot.
+- The plugin's `app-manifest.json` + `configuration.json` describe only what the admin needs to configure for this plugin instance (text, images, colors, which form/quiz to bind to). Don't reinvent platform features locally.
+
 ## Development Workflow
 
 Work through these steps in order. Do not skip.
@@ -157,6 +165,12 @@ store.updateString("key", "value")
 store.updateSetting("key", "value")
 store.updateAsset("key", "url")
 store.updateState("key", "value")
+
+// Logged-in user — returns `null` when no user is authenticated
+store.getUser() // Full user object or null
+store.getUserName("Guest") // Display name with fallback
+store.getUserEmail() // Email or null
+store.isAuthenticated() // boolean
 ```
 
 ## Real-Time Events