@gxp-dev/tools 2.0.85 → 2.0.87

package/bin/lib/commands/init.js

@@ -77,6 +77,11 @@ function copyTemplateFiles(projectPath, paths, overwrite = false) {
 			dest: "src/DemoPage.vue",
 			desc: "DemoPage.vue (Example component)",
 		},
+		{
+			src: "src/DemoExperience.vue",
+			dest: "src/DemoExperience.vue",
+			desc: "DemoExperience.vue (Example experience flow)",
+		},
 	]
 
 	// Copy template files
@@ -168,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.85",
+	"version": "2.0.87",
 	"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