@gxp-dev/tools 2.0.76 → 2.0.78

package/bin/lib/lint/schemas/app-manifest.schema.json

@@ -29,6 +29,10 @@
 		"configurationFile": { "type": "string" },
 		"appInstructionsFile": { "type": "string" },
 		"defaultStylingFile": { "type": "string" },
+		"formTemplate": {
+			"type": "boolean",
+			"description": "Declares this plugin as a form/quiz/survey app. When true, the platform expects `configuration.json` to include a `formTemplate` root key — an array of cards defining the starter question set an admin can customize on install."
+		},
 		"appInstructions": { "type": "string" },
 		"defaultStyling": { "type": "string" },
 		"configuration": {

package/bin/lib/lint/schemas/configuration.schema.json

@@ -11,6 +11,11 @@
 			"description": "Top-level array of tab definitions. Each item is a card (usually card_list or fields_list) rendered under the plugin's configuration panel.",
 			"items": { "$ref": "card.schema.json" }
 		},
+		"formTemplate": {
+			"type": "array",
+			"description": "Starter form/quiz/survey question set for plugins that act as a form app. Each item is a card defining a form section (use `fields_list` for question groups or `card_list` to nest further). The admin can copy/customize these when they install the plugin. Only meaningful when `formTemplate` is true in app-manifest.json.",
+			"items": { "$ref": "card.schema.json" }
+		},
 		"title": { "type": ["string", "null"] },
 		"description": { "type": ["string", "null"] },
 		"version": { "type": ["string", "integer", "null"] }

package/bin/lib/utils/ai-scaffold.js

@@ -1009,6 +1009,7 @@ function buildInteractiveInitialPrompt(projectName, description, provider) {
 		"- What real-world data it reads/writes — identify the concrete platform operationIds via the MCP, never invent them",
 		"- Which real-time events matter (use `api_find_events_for_operation` for each planned operationId)",
 		"- Every piece of admin-editable content: strings, assets, colors/thresholds/settings, feature toggles",
+		'- Whether the plugin uses the platform\'s **form/quiz/survey API** at all. The rule has two independent parts — do not collapse them. (a) **Capability flag.** Any time the plugin calls form/quiz operationIds (creating a form, reading questions, submitting responses, listing form data), set `"formTemplate": true` in `app-manifest.json`. The platform uses this to auto-provision a `ProjectForm` for the install. Required regardless of whether you ship starter questions. (b) **Prepopulated questions.** If you want the admin to install with a starter question set instead of an empty form, also populate `configuration.json`\'s `formTemplate` root array (`config_add_card` with `parent_path: "/formTemplate"` — auto-initializes). Optional payload; the platform seeds the auto-provisioned form from it. At runtime the plugin still declares its form dependencies in `app-manifest.json` (e.g. a `quiz_form` identifier bound to `ProjectForm`) and calls `store.callApi("forms.show", "quiz_form")` / `store.callApi("form_responses.store", "quiz_form", {...})`. End-user questions go in `formTemplate`; admin plugin config stays in `additionalTabs`. Never mix.',
 		"",
 		"Then propose a plan — screens/components, data flow, admin configuration form, and the exact keys you'll add to `app-manifest.json` — and get my confirmation before implementing.",
 		"",

package/mcp/lib/config-ops.js

@@ -163,7 +163,12 @@ function moveItem(doc, fromPointer, targetArrayPointer, position = "end") {
  * cards with their JSON pointer, type, title, and a summary of children.
  *
  * Cards are discovered under:
- *   additionalTabs[]                          (root array of cards)
+ *   additionalTabs[]                          (root array of cards — admin form)
+ *   formTemplate[]                            (root array of cards — starter
+ *                                              form/quiz/survey questions; only
+ *                                              present on form apps where
+ *                                              app-manifest.json has
+ *                                              `formTemplate: true`)
  *   <card>.cards[]                            (card_list)
  *   <card>.tabsList[].cards[]                 (tabs_list)
  */
@@ -201,6 +206,9 @@ function listCards(doc) {
 	if (Array.isArray(doc?.additionalTabs)) {
 		doc.additionalTabs.forEach((c, i) => walk(c, `/additionalTabs/${i}`))
 	}
+	if (Array.isArray(doc?.formTemplate)) {
+		doc.formTemplate.forEach((c, i) => walk(c, `/formTemplate/${i}`))
+	}
 	return out
 }
 

package/mcp/lib/config-tools.js

@@ -224,7 +224,7 @@ const CONFIG_TOOLS = [
 	{
 		name: "config_add_card",
 		description:
-			"Add a card under a parent container (additionalTabs, a card_list's cards[], or a tabs_list tab).",
+			"Add a card under a parent container (additionalTabs, formTemplate, a card_list's cards[], or a tabs_list tab). The `/additionalTabs` and `/formTemplate` root arrays are auto-initialized if missing, so the first add works without seeding.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -232,7 +232,7 @@ const CONFIG_TOOLS = [
 				parent_path: {
 					type: "string",
 					description:
-						"JSON pointer to the parent array of cards (e.g. '/additionalTabs' or '/additionalTabs/0/cards').",
+						"JSON pointer to the parent array of cards. Top-level options: '/additionalTabs' (admin configuration form) or '/formTemplate' (starter form/quiz questions for form apps). Nested options: '/additionalTabs/0/cards', '/formTemplate/0/cards', etc.",
 				},
 				card: {
 					type: "object",
@@ -448,6 +448,18 @@ async function handleConfigToolCall(name, args = {}) {
 		case "config_add_card": {
 			const abs = resolveProjectPath(args.path)
 			const doc = readJson(abs)
+
+			// Auto-initialize known root-level card arrays if they're missing
+			// so the first `config_add_card` against /formTemplate (or
+			// /additionalTabs) works without a separate seeding step.
+			const KNOWN_ROOT_ARRAYS = ["/formTemplate", "/additionalTabs"]
+			if (KNOWN_ROOT_ARRAYS.includes(args.parent_path)) {
+				const rootKey = args.parent_path.slice(1)
+				if (!Array.isArray(doc[rootKey])) {
+					doc[rootKey] = []
+				}
+			}
+
 			const parent = getByPointer(doc, args.parent_path)
 			if (!Array.isArray(parent)) {
 				throw new Error(

package/package.json

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

package/runtime/vite.config.js

@@ -313,19 +313,25 @@ export default defineConfig(async (ctx) => {
 			vue(),
 			// GxP Inspector plugin for browser extension integration
 			...(useInspector ? [gxpInspectorPlugin()] : []),
-			externalGlobals(
-				{
+			// `externalGlobals` rewrites `import ... from "vue"` → references to
+			// the `Vue` global that the GxP platform exposes on `window`. This is
+			// only desirable at **build** time — in dev, the toolkit runtime
+			// bootstraps its own Vue + Pinia (via main.js → createApp + app.use),
+			// and rewriting `from "pinia"` to a non-existent `window.Pinia`
+			// crashes `getActivePinia()` at store init.
+			//
+			// Using `apply: "build"` restricts the transform to production builds,
+			// where it rewrites every module in the final bundle (including
+			// transitive node_modules deps) so no bare specifiers leak through.
+			{
+				...externalGlobals({
 					vue: "Vue",
 					pinia: "Pinia",
 					"@/stores/gxpPortalConfigStore":
 						"(window.useGxpStore || (() => { console.warn('useGxpStore not found on window, using fallback'); return {}; }))",
-				},
-				// No `include` filter — rewrite `from "vue"` / `from "pinia"`
-				// in every module of the final bundle, including transitive deps
-				// from node_modules (component libraries, etc.). Without this,
-				// deps' internal `import { h } from "vue"` leak through as bare
-				// specifiers and crash at runtime on the platform.
-			),
+				}),
+				apply: "build",
+			},
 			// Custom request logging and CORS plugin
 			{
 				name: "request-logger-cors",

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

@@ -522,6 +522,105 @@ Each field's `name` must exactly match the manifest key it controls — that's t
 
 Every mutation is linter-guarded against `bin/lib/lint/schemas/`. If a write is refused, read the validation error and fix the input — do not reach for `force: true`.
 
+## Form / Quiz / Survey Apps — `formTemplate`
+
+`formTemplate` appears in **two** files and the two meanings are **independent**. Don't collapse them — treat the manifest flag and the configuration array as separate decisions.
+
+### The two keys
+
+**1. `app-manifest.json` → `"formTemplate": true` — capability flag.**
+
+Set this **any time** the plugin calls the platform's form/quiz/survey API: creating a form, reading questions, submitting responses, listing form data. It tells the platform "this plugin uses a form resource" and opts the install into form-specific behavior — auto-provisioning a `ProjectForm` for the install, enabling the question editor and response viewer in the admin UI, etc. **Required whenever form/quiz operationIds are in play, regardless of whether you ship starter questions.**
+
+**2. `configuration.json` → `"formTemplate": [ ...cards ]` — prepopulated starter questions.**
+
+An array of cards (same shape as `additionalTabs`, typically `fields_list`) that the platform seeds into the auto-provisioned `ProjectForm` at install time. **Optional** — omit it if you want the admin to build the form from scratch.
+
+### The rule — three scenarios
+
+| Scenario                                                    | Manifest `formTemplate`                                     | Configuration `formTemplate` |
+| ----------------------------------------------------------- | ----------------------------------------------------------- | ---------------------------- |
+| Uses form/quiz API, no starter questions                    | **`true`** (required)                                       | omit                         |
+| Uses form/quiz API, with starter questions                  | **`true`** (required)                                       | `[ ...cards ]`               |
+| Doesn't touch the form/quiz API                             | omit / `false`                                              | must not be set              |
+| You have starter questions but the manifest flag is missing | — wrong: the array is dead content until the flag is `true` | —                            |
+
+In one line: **uses form API → flag is true.** **Wants to prepopulate questions → array is populated.** These are independent decisions.
+
+### How it lands at runtime
+
+1. Install-time: platform sees `formTemplate: true` in the manifest → auto-provisions a `ProjectForm` for this plugin install.
+2. If `configuration.json` has a `formTemplate` array → platform seeds that new form with those cards/questions. If absent → the form is empty and the admin fills it in.
+3. The plugin still declares its form dependencies in `app-manifest.json` (e.g. `{ "identifier": "quiz_form", "model": "ProjectForm" }`) and the admin binds that identifier to the auto-provisioned form. Plugin code then calls `store.callApi("forms.show", "quiz_form")`, `store.callApi("form_responses.store", "quiz_form", {...})`, etc.
+4. Discover the right operationIds via MCP: `api_list_tags`, then `api_list_operation_ids --tag Forms` (or `search_api_endpoints quiz`). Never invent them.
+5. After install the admin owns the form — they can add/remove/reorder questions. Your `formTemplate` is a starting point, not a lock.
+
+### Minimal example — form app with starter questions and a dependency
+
+```json
+// app-manifest.json
+{
+	"name": "welcome-quiz",
+	"version": "0.1.0",
+	"formTemplate": true,
+	"settings": {},
+	"strings": { "default": { "title": "Welcome Quiz" } },
+	"assets": {},
+	"dependencies": [{ "identifier": "quiz_form", "model": "ProjectForm" }],
+	"permissions": [
+		{
+			"identifier": "quiz_form",
+			"description": "Read questions and submit responses"
+		}
+	]
+}
+```
+
+```json
+// configuration.json
+{
+	"additionalTabs": [
+		/* admin-facing plugin config (unchanged) */
+	],
+	"formTemplate": [
+		{
+			"type": "fields_list",
+			"title": "About You",
+			"fieldsList": [
+				{ "type": "text", "name": "full_name", "label": "Full name" },
+				{
+					"type": "radio",
+					"name": "experience",
+					"label": "Experience level",
+					"options": [
+						{ "label": "Beginner", "value": "beginner" },
+						{ "label": "Advanced", "value": "advanced" }
+					]
+				}
+			]
+		}
+	]
+}
+```
+
+### Building with the MCP
+
+Pointer-based adds work against `/formTemplate` the same way they do against `/additionalTabs`:
+
+- `config_add_card` with `parent_path: "/formTemplate"` — the array auto-initializes on first add, no seed step.
+- `config_add_card` with `parent_path: "/formTemplate/0/cards"` — nest under a `card_list` for grouped sections.
+- `config_add_field` with `card_path: "/formTemplate/0"` — add a question to the first section.
+- `config_list_cards` — returns cards from both `/additionalTabs` and `/formTemplate` with their JSON pointers.
+
+Use any valid field type (`text`, `textarea`, `number`, `radio`, `checkbox`, `select`, `asyncSelect`, `selectAsset`, etc.). The `name` of each field becomes the response key the platform stores.
+
+### Mental model
+
+- `additionalTabs` → **admin** configuration (every plugin). Strings, assets, color pickers, dependency binding, feature toggles.
+- `formTemplate` → **end-user** questions (only form apps). Only add here if `app-manifest.json` has `formTemplate: true`.
+
+Don't mix. Quiz questions never belong in `additionalTabs`; admin config never belongs in `formTemplate`. Both roots validate against the same card/field schema, so `gxdev lint --all` catches malformed structures in either place.
+
 ## Component Template
 
 When creating new components, use this pattern:

package/template/AGENTS.md

@@ -321,6 +321,111 @@ Group related fields into `fields_list` cards (`config_add_card` then `config_ad
 
 If a mutation is refused, read the validation error and fix the input — do not reach for `force: true`.
 
+## Form / Quiz / Survey Apps — `formTemplate`
+
+`formTemplate` appears in **two** places and they mean **two different things**. Read this section carefully — treat the manifest flag and the configuration array as independent decisions.
+
+### The two keys
+
+**1. `app-manifest.json` → `"formTemplate": true` — the capability flag.**
+
+Set this any time the plugin calls the platform's form/quiz/survey API — creating a form, reading responses, submitting answers, listing questions. It tells the platform "this plugin owns or consumes a form resource" and opts the install into form-specific behavior (question editor in the admin UI, response viewer, auto-provisioned `ProjectForm`, etc.). **Required** whenever you're using form/quiz operationIds, regardless of whether you ship prepopulated questions.
+
+**2. `configuration.json` → `"formTemplate": [ ...cards ]` — the prepopulated questions.**
+
+A starter question set the platform seeds into the auto-provisioned form at install time, so the admin doesn't start from an empty form. Structured identically to `additionalTabs`: an array of cards (usually `fields_list`) whose `fieldsList` items are the questions. **Optional** — only set it when you actually want to ship starter content. If omitted, the platform provisions an empty form and the admin builds it from scratch.
+
+### The rule
+
+| Scenario                                                    | Manifest `formTemplate`                                        | Configuration `formTemplate` |
+| ----------------------------------------------------------- | -------------------------------------------------------------- | ---------------------------- |
+| Plugin calls form/quiz API, ships no starter questions      | **`true`** (required)                                          | omit / leave empty           |
+| Plugin calls form/quiz API, ships starter questions         | **`true`** (required)                                          | `[ ...cards ]`               |
+| Plugin does **not** touch the form/quiz API                 | omit / `false`                                                 | must not be set              |
+| You want starter questions but didn't set the manifest flag | — fix this — the array is dead content unless the flag is true | —                            |
+
+Short version:
+
+- **Uses form/quiz API → manifest `formTemplate: true`.** Non-negotiable.
+- **Wants to prepopulate questions → configuration `formTemplate: [...]`.** Optional payload.
+
+### How the pieces connect at runtime
+
+1. At install time the platform sees `formTemplate: true` in the manifest and auto-provisions a `ProjectForm` for this plugin install.
+2. If `configuration.json` includes a `formTemplate` array, the platform seeds the new `ProjectForm` with those questions. If not, it creates an empty form.
+3. The plugin code still declares whichever form/quiz dependencies it needs in `app-manifest.json` (e.g. `quiz_form`, `response_stream`) and calls `store.callApi("forms.show", "quiz_form")` / `store.callApi("form_responses.store", "quiz_form", {...})` etc. Discover the right operationIds via the MCP (`search_api_endpoints quiz`, `api_list_operation_ids --tag Forms`).
+4. The admin can edit, add, or remove questions on the auto-provisioned form after install. Your `formTemplate` array is a starting point, not a lock — the admin owns the form once it's provisioned.
+
+So: the manifest flag wires up the form backing store; the configuration array pre-seeds its contents; the dependency bindings scope which form the plugin talks to at runtime. Three independent concerns, all of which you need for a proper form app.
+
+### Minimal example — form app with starter questions
+
+```json
+// app-manifest.json
+{
+	"name": "welcome-quiz",
+	"version": "0.1.0",
+	"formTemplate": true,
+	"settings": {},
+	"strings": { "default": { "title": "Welcome Quiz" } },
+	"assets": {},
+	"dependencies": [{ "identifier": "quiz_form", "model": "ProjectForm" }],
+	"permissions": [
+		{
+			"identifier": "quiz_form",
+			"description": "The quiz form — read questions and submit responses"
+		}
+	]
+}
+```
+
+```json
+// configuration.json
+{
+	"additionalTabs": [
+		/* admin-facing plugin config goes here as always */
+	],
+	"formTemplate": [
+		{
+			"type": "fields_list",
+			"title": "About You",
+			"fieldsList": [
+				{ "type": "text", "name": "full_name", "label": "Full name" },
+				{
+					"type": "radio",
+					"name": "experience",
+					"label": "Experience level",
+					"options": [
+						{ "label": "Beginner", "value": "beginner" },
+						{ "label": "Advanced", "value": "advanced" }
+					]
+				}
+			]
+		}
+	]
+}
+```
+
+### Building `formTemplate` with the MCP
+
+Use the same `config_*` tools you'd use for `additionalTabs`, pointed at the `/formTemplate` root:
+
+- `config_add_card` with `parent_path: "/formTemplate"` — the array is auto-initialized on first add, no seed step needed.
+- `config_add_card` with `parent_path: "/formTemplate/0/cards"` — nest sub-cards if you need a `card_list` grouping.
+- `config_add_field` with `card_path: "/formTemplate/0"` — add questions to a section.
+- `config_list_cards` — lists cards from both `/additionalTabs` and `/formTemplate` with their JSON pointers.
+
+Use the same field types as any other form (`text`, `textarea`, `number`, `radio`, `checkbox`, `select`, `asyncSelect`, `selectAsset`, etc.). Question names live under `fieldsList[].name` — these become the response keys the platform stores.
+
+### Don't confuse `formTemplate` with `additionalTabs`
+
+- `additionalTabs` — **admin** configuration form (every plugin has this). The person installing the plugin fills this in once.
+- `formTemplate` — **end-user** form questions (only form apps). Admins may tweak these before publishing; end users (attendees, staff) answer them at runtime.
+
+Strings, assets, dependencies, colors → `additionalTabs`. Quiz/survey questions that end users will answer → `formTemplate`.
+
+Finish with `gxdev lint --all`. The linter validates both roots against the same card/field schema, so malformed questions fail in the same way malformed admin fields do.
+
 ## Component Kit
 
 Import UI components from `@gramercytech/gx-componentkit`:

package/template/GEMINI.md

@@ -231,6 +231,39 @@ Every admin-editable piece of content goes through a directive — that's the br
 
 Tools: `config_list_card_types`, `config_list_field_types`, `config_get_field_schema`, `config_add_card`, `config_add_field`, `config_move_field`, `config_remove_field`, `config_validate`, `config_extract_strings`. Every mutation is linter-guarded against schemas in `bin/lib/lint/schemas/`.
 
+## Form / Quiz / Survey Apps — `formTemplate`
+
+`formTemplate` lives in two files and the two meanings are independent — don't treat them as a single toggle.
+
+### The two keys
+
+- **`app-manifest.json` → `"formTemplate": true` — capability flag.** Set **any time** the plugin uses the platform's form/quiz/survey API (creating a form, reading questions, submitting responses, etc.). Tells the platform to auto-provision a `ProjectForm` for this install and opt into form-specific admin UI. Required whenever form/quiz operationIds are in play, regardless of whether you ship starter questions.
+
+- **`configuration.json` → `"formTemplate": [ ...cards ]` — prepopulated questions.** Starter question set the platform seeds into the auto-provisioned form at install time. Structured identically to `additionalTabs`. Optional — omit to let the admin build the form from scratch.
+
+### The rule
+
+- Uses form/quiz API → manifest `formTemplate: true`. Non-negotiable.
+- Wants to ship starter questions → configuration `formTemplate: [...]`. Optional payload.
+- Doesn't touch the form/quiz API → neither key.
+
+### Runtime flow
+
+1. `formTemplate: true` in the manifest → platform auto-provisions a `ProjectForm` on install.
+2. `formTemplate` array in configuration.json (if present) → seeds the new form with those starter questions.
+3. Plugin code still declares form dependencies (e.g. `quiz_form`) in `app-manifest.json` and calls `store.callApi("forms.show", "quiz_form")` / `store.callApi("form_responses.store", "quiz_form", {...})` — discover operationIds via the MCP (`search_api_endpoints quiz` / `api_list_operation_ids --tag Forms`).
+4. The admin owns the form after install; your array is a starting point, not a lock.
+
+### Building `formTemplate` with the MCP
+
+- `config_add_card` with `parent_path: "/formTemplate"` (the array is auto-initialized on first add).
+- `config_add_field` with `card_path: "/formTemplate/0"` to add questions to a section.
+- `config_list_cards` surfaces both `/additionalTabs` and `/formTemplate` cards.
+
+### Don't confuse with `additionalTabs`
+
+`additionalTabs` = **admin** config (every plugin). `formTemplate` = **end-user** questions (only form apps). Admin strings, assets, colors, dependency bindings → `additionalTabs`. Questions an attendee/user will answer → `formTemplate`.
+
 ## Component Kit
 
 Use `@gramercytech/gx-componentkit` for UI: