# VIXNODE Page and Layout Creation Instructions

Use these instructions when an AI assistant creates or updates pages through VIXNODE. They define how to choose a page type, preserve layout relationships, construct placeholder HTML, validate a preview, and execute only after confirmation.

## Non-Negotiable Rules

1. Determine the correct `pageType` before generating HTML.
2. Retrieve the current project and relevant page or layout data before using any existing ID.
3. Never guess, invent, or reuse an unrelated `project_id`, `page_id`, `layout`, or `data-nodeid`.
4. Keep project IDs, layout page IDs, and placeholder node IDs separate. They are not interchangeable.
5. For `layout`, `childLayout`, and `layoutPage`, every direct top-level HTML element must have the exact class `app-place-holder`.
6. For layout-related page types, return an HTML fragment. Do not add `<html>`, `<head>`, `<body>`, or an outer page container.
7. Do not place `<style>`, `<script>`, comments, text nodes, or any other element beside the top-level placeholders. If page-specific CSS is needed, place the `<style>` element inside one of the valid placeholders.
8. Every placeholder must include valid GUID values in both `data-layout` and `data-nodeid`.
9. Reuse an existing `data-nodeid` only when filling that exact existing slot. Generate a new GUID only when defining a genuinely new placeholder.
10. Generate and validate a preview before execution. If the UI requires confirmation, never bypass it.

## Required Workflow

Follow this order for every request:

1. Identify the user's intended page type.
2. Retrieve the current project list and resolve the real `project_id`.
3. If a layout is involved, retrieve the selected layout's page ID and latest HTML.
4. Map every placeholder by its owner, `data-layout`, `data-nodeid`, and intended content.
5. Build only the HTML structure allowed for the selected `pageType`.
6. Run the validation checklist in this document.
7. Generate a preview.
8. Explain the target project, page type, and layout used.
9. Wait for the required user or UI confirmation.
10. Execute the exact confirmed preview without changing its IDs, HTML, or layout relationship.

## Choose the Correct Page Type

| User's goal | `pageType` | `page_id` | `layout` | Placeholder behavior |
| --- | --- | --- | --- | --- |
| Choose a theme before HTML generation | Omit | No | No | Set `need_theme_selection: true`; do not send `html` |
| Create a standalone page | `page` or omitted | No | No | Layout placeholders are not required |
| Create a main layout | `layout` | Required | No | All placeholders are owned by the new main layout |
| Create a child layout | `childLayout` | Required | Required parent layout ID | Preserve parent slots; new child slots are owned by the child layout |
| Create a page using a main or child layout | `layoutPage` | No | Required selected layout ID | Fill existing slots; do not create placeholders |
| Create a reusable fragment | `template` | No | No | Layout placeholders are not required |

## Identifier Ownership

| Identifier | Meaning | Rules |
| --- | --- | --- |
| `project_id` | Project receiving the page | Use only for request routing |
| Main layout `page_id` | Identity of a main layout | Used as the main layout's `data-layout` and as a descendant's `layout` reference |
| Child layout `page_id` | Identity of a child layout | Used for child-owned `data-layout` values and as a content page's `layout` reference |
| `data-nodeid` | Identity of one placeholder slot | Preserve it when filling an existing slot; generate a new GUID only for a new slot |

Never substitute one identifier for another.

## 1. Theme Selection

Use this request only when the user must select a theme before HTML is generated.

Required fields:

- `project_id`
- `name`
- `need_theme_selection: true`

Do not send `html` during this step.

```json
{
  "project_id": "project-id",
  "name": "Page Name",
  "need_theme_selection": true
}
```

## 2. Standalone Page

Use `page` for a regular page that does not inherit a layout. If `pageType` is omitted, VIXNODE treats the request as a one page.

Required fields:

- `project_id`
- `name`
- `html`

```json
{
  "project_id": "project-id",
  "name": "Welcome",
  "pageType": "page",
  "fileName": "index",
  "html": "<main><h1>Welcome</h1><p>This is a standalone page.</p></main>"
}
```

## 3. Main Layout

Use `layout` to create shared site structure and one or more content slots.

Required fields:

- `project_id`
- `name`
- `pageType: "layout"`
- `page_id`: a new GUID for the layout
- `html`

Rules:

- Every placeholder is owned by the new layout, so every `data-layout` must equal `page_id`.
- Every placeholder must have a unique `data-nodeid` GUID.
- Each direct top-level element must be an `.app-place-holder`.
- Shared header, navigation, footer, CSS, and other markup may be placed inside a placeholder.
- Save the final `page_id` and node IDs. Descendant layouts and pages must reuse them exactly when referencing these slots.

```json
{
  "project_id": "project-id",
  "name": "Main Layout",
  "pageType": "layout",
  "page_id": "f8266c00-69e4-4a4a-b1c7-a90c03814b56",
  "fileName": "layout-main",
  "html": "<div class=\"app-place-holder\" data-layout=\"f8266c00-69e4-4a4a-b1c7-a90c03814b56\" data-nodeid=\"8b1e6ab2-2889-4701-896f-eb16206c0c9c\"><header>Shared header</header><main></main></div><div class=\"app-place-holder\" data-layout=\"f8266c00-69e4-4a4a-b1c7-a90c03814b56\" data-nodeid=\"faa27b8a-2750-475e-b12c-383f7283ff77\"><footer>Shared footer</footer></div>"
}
```

## 4. Child Layout

Use `childLayout` when a layout must inherit a parent layout and subdivide one or more parent slots into child-owned content slots.

Required fields:

- `project_id`
- `name`
- `pageType: "childLayout"`
- `page_id`: a new GUID for the child layout
- `layout`: the existing parent layout page ID
- `html`

Rules:

- Retrieve the parent layout's latest HTML before building the child layout.
- Preserve the parent placeholder topology. Do not flatten, reorder, rename, or replace parent slots unless the current parent structure explicitly permits it.
- A parent-owned placeholder must retain both its original `data-layout` and original `data-nodeid`.
- Place newly introduced child placeholders inside the appropriate inherited parent slot.
- Every new child-owned placeholder must use the child layout's `page_id` as `data-layout` and a new unique GUID as `data-nodeid`.
- The direct top-level roots must still be `.app-place-holder` elements. In the common single-slot parent layout, the inherited parent slot is the sole top-level element and the child-owned slots are nested inside it.
- Do not use `project_id` as either the parent `layout` ID or the child layout `page_id`.

```json
{
  "project_id": "project-id",
  "name": "Article Child Layout",
  "pageType": "childLayout",
  "page_id": "b9a5d3f5-d989-4e84-bacd-27ed011afd3b",
  "layout": "f8266c00-69e4-4a4a-b1c7-a90c03814b56",
  "fileName": "layout-article",
  "html": "<div class=\"app-place-holder\" data-layout=\"f8266c00-69e4-4a4a-b1c7-a90c03814b56\" data-nodeid=\"8b1e6ab2-2889-4701-896f-eb16206c0c9c\"><div class=\"app-place-holder\" data-layout=\"b9a5d3f5-d989-4e84-bacd-27ed011afd3b\" data-nodeid=\"167d874b-ada3-477e-8639-34ad8668e7c4\"></div><div class=\"app-place-holder\" data-layout=\"b9a5d3f5-d989-4e84-bacd-27ed011afd3b\" data-nodeid=\"a46ee7d5-eaba-4f18-8cb5-1b31bb5fd0cd\"></div></div>"
}
```

The nesting in this example is intentional: the parent-owned slot remains the top-level element, while the new article slots belong to the child layout.

## 5. Page Using a Layout

Use `layoutPage` for content rendered through an existing main layout or child layout.

Required fields:

- `project_id`
- `name`
- `pageType: "layoutPage"`
- `layout`: the selected main or child layout page ID
- `html`

Rules:

- A `layoutPage` does not own or create placeholders.
- Retrieve the selected layout's latest HTML and slot definitions first.
- Include only the existing slots that the page is expected to fill.
- Copy each selected placeholder's `data-layout` and `data-nodeid` exactly.
- Do not generate new placeholder IDs.
- Every direct top-level element in the submitted fragment must be an `.app-place-holder`.
- Put page content and optional page-specific CSS inside the matching placeholders.
- Do not submit a complete HTML document or ordinary full-page wrapper with `pageType: "layoutPage"`.

### Page using a main layout

```json
{
  "project_id": "project-id",
  "name": "Landing Page",
  "pageType": "layoutPage",
  "layout": "f8266c00-69e4-4a4a-b1c7-a90c03814b56",
  "fileName": "landing",
  "html": "<div class=\"app-place-holder\" data-layout=\"f8266c00-69e4-4a4a-b1c7-a90c03814b56\" data-nodeid=\"8b1e6ab2-2889-4701-896f-eb16206c0c9c\"><style>.hero{padding:4rem 1rem}</style><section class=\"hero\"><h1>Landing page</h1></section></div><div class=\"app-place-holder\" data-layout=\"f8266c00-69e4-4a4a-b1c7-a90c03814b56\" data-nodeid=\"faa27b8a-2750-475e-b12c-383f7283ff77\"><footer>Page footer content</footer></div>"
}
```

### Page using a child layout

```json
{
  "project_id": "project-id",
  "name": "Article Page",
  "pageType": "layoutPage",
  "layout": "b9a5d3f5-d989-4e84-bacd-27ed011afd3b",
  "fileName": "article",
  "html": "<div class=\"app-place-holder\" data-layout=\"b9a5d3f5-d989-4e84-bacd-27ed011afd3b\" data-nodeid=\"167d874b-ada3-477e-8639-34ad8668e7c4\"><article><h1>Article title</h1><p>Article content.</p></article></div><div class=\"app-place-holder\" data-layout=\"b9a5d3f5-d989-4e84-bacd-27ed011afd3b\" data-nodeid=\"a46ee7d5-eaba-4f18-8cb5-1b31bb5fd0cd\"><aside>Related content</aside></div>"
}
```

## 6. Reusable Template

Use `template` for reusable fragments such as navigation, footer, hero, card, or content sections.

Required fields:

- `project_id`
- `name`
- `pageType: "template"`
- `html`

The `layout` field is not required.

```json
{
  "project_id": "project-id",
  "name": "Navigation Template",
  "pageType": "template",
  "fileName": "nav-template",
  "html": "<nav><a href=\"/\">Home</a><a href=\"/about\">About</a><a href=\"/contact\">Contact</a></nav>"
}
```

## Validation Checklist

Before generating a preview, verify all of the following:

- [ ] `project_id` was retrieved from the current project list.
- [ ] `pageType` matches the intended operation.
- [ ] A new `layout` or `childLayout` has a new, unique `page_id` GUID.
- [ ] `layout` points to an existing page of the expected layout type.
- [ ] The latest selected layout HTML was retrieved before copying its slots.
- [ ] Every direct top-level element for a layout-related page is `.app-place-holder`.
- [ ] No `<html>`, `<head>`, `<body>`, `<main>`, `<style>`, text, or comment appears as a sibling of the top-level placeholders.
- [ ] Every placeholder contains valid `data-layout` and `data-nodeid` GUIDs.
- [ ] Main-layout-owned placeholders use the main layout `page_id`.
- [ ] Parent placeholders in a child layout preserve the parent's exact IDs and topology.
- [ ] Child-owned placeholders use the child layout `page_id` and new node IDs.
- [ ] A `layoutPage` reuses existing slot IDs and creates no new placeholders.
- [ ] All HTML tags and attribute quotes are valid and properly closed.
- [ ] `name` and `fileName` meet the tool's current validation limits.
- [ ] A preview is generated before any confirmation-protected execution.

## Common Errors and Corrections

### `For layoutPage, top-level elements must all be '.app-place-holder'`

The submitted fragment contains an invalid top-level element, document wrapper, text node, comment, or standalone `<style>` element.

Correction: submit only the selected layout's placeholder fragments as direct roots. Move content and CSS inside those placeholders.

### The child layout is attached to the wrong page

The request confused `project_id`, the parent layout ID, the child layout `page_id`, or a placeholder node ID.

Correction: reload the project and page list, retrieve the parent's latest HTML, and rebuild the request from the identifier ownership table. Never repair the request by guessing a GUID.

### The child layout has a valid `layout` value but is still rejected

The parent node IDs or structure were changed, or a child-owned placeholder used the parent layout ID.

Correction: preserve inherited parent slots exactly. Assign the child layout's `page_id` only to newly introduced child-owned placeholders.

### The layout page renders content in the wrong region

The page used the wrong existing `data-nodeid`, or the slot mapping was based on an outdated layout version.

Correction: retrieve the latest layout HTML, map each slot to its intended region, and copy the correct IDs exactly.

### Execution is blocked pending confirmation

The preview requires explicit confirmation in the UI.

Correction: ask the user to review and click **Confirm Execution**. Do not call direct execution, alter the preview, or silently generate a replacement unless the user asks for changes.

## Final Response Behavior

After a valid preview is created:

1. State the target project and page name.
2. State the selected `pageType` and layout, when applicable.
3. Summarize the intended changes without claiming they are already applied.
4. Ask the user to review the preview and complete the required confirmation.
5. After successful execution, report the completed result and provide the available edit or published-page link.
