@gxp-dev/tools 2.0.76 → 2.0.77

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 this is a **form app** (quiz, survey, questionnaire, signup flow). If yes, set `formTemplate: true` in `app-manifest.json` and populate `configuration.json`\'s `formTemplate` root array with starter question cards (`config_add_card` with `parent_path: "/formTemplate"` — auto-initializes). See the instructions file for the full pattern. Keep end-user questions in `formTemplate` and admin config in `additionalTabs` — do not mix the two.',
 		"",
 		"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.77",
 	"description": "Dev tools to create platform plugins",
 	"type": "commonjs",
 	"publishConfig": {

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

@@ -522,6 +522,74 @@ 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`
+
+Some plugins _are_ a form: a quiz, a survey, a signup flow. For those, ship a starter question set an admin can customize on install. Two keys, kept consistent:
+
+1. **`app-manifest.json` → `"formTemplate": true`** — flags the plugin as a form app so the platform opts into form-specific UI (question editor, response viewer).
+2. **`configuration.json` → `"formTemplate": [ ...cards ]`** — array of cards defining the starter form sections, same shape as `additionalTabs`. Typically `fields_list` cards whose `fieldsList` items are the end-user questions.
+
+### Minimal example
+
+```json
+// app-manifest.json
+{
+	"name": "welcome-quiz",
+	"version": "0.1.0",
+	"formTemplate": true,
+	"settings": {},
+	"strings": { "default": { "title": "Welcome Quiz" } },
+	"assets": {},
+	"dependencies": [],
+	"permissions": []
+}
+```
+
+```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,78 @@ 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`
+
+Some plugins _are_ a form — a quiz, a survey, a signup questionnaire, a check-in flow. For those, the configuration file ships a second root-level card array, `formTemplate`, that holds the starter questions an admin customizes on install.
+
+**Two keys tie this together. You must set both consistently.**
+
+1. **`app-manifest.json` → `"formTemplate": true`** — declares the plugin as a form app. Platforms use this to opt the install into form-specific UI (question editor, response viewer, etc.).
+2. **`configuration.json` → `"formTemplate": [ ...cards ]`** — the starter question set, structured identically to `additionalTabs`: an array of cards, typically `fields_list` sections, each with a `fieldsList` of question fields.
+
+### Minimal example
+
+```json
+// app-manifest.json
+{
+	"name": "welcome-quiz",
+	"version": "0.1.0",
+	"formTemplate": true,
+	"settings": {},
+	"strings": { "default": { "title": "Welcome Quiz" } },
+	"assets": {},
+	"dependencies": [],
+	"permissions": []
+}
+```
+
+```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.
+
+### When to use `formTemplate` vs `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.
+
+Don't confuse them. 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,21 @@ 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`
+
+If the plugin _is_ a form (quiz, survey, questionnaire), ship a starter question set the admin can customize on install. Two keys, both required, must be kept consistent:
+
+1. `app-manifest.json` → `"formTemplate": true` — marks the plugin as a form app.
+2. `configuration.json` → `"formTemplate": [ ...cards ]` — array of cards (same shape as `additionalTabs`), typically `fields_list` sections whose `fieldsList` items are the questions.
+
+Build it with the same MCP tools, pointed at `/formTemplate`:
+
+- `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.
+
+Mental model: `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: