@cyprnet/node-red-contrib-uibuilder-formgen 0.4.11

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to this package will be documented in this file.
+
+## 0.4.0
+
+- Added **offline-first licensing framework** (Free vs Licensed).
+- Added **PortalSmith License** config node (`portalsmith-license`) that stores a license key in Node-RED credentials.
+- Added **license status indicator** in the `uibuilder-formgen` editor UI (local validation endpoint).
+- Added generated portal **watermark + default branding** in Free mode and gated custom branding/logo when unlicensed.
+- Added MIT license files and npm/Flow Library metadata polish.
+
+## 0.4.2
+
+- Added `tools/generate-license.js` (internal helper) to generate signed license strings offline.
+
+## 0.4.3
+
+- Added `tools/license-key.js` alias for `tools/generate-license.js`.
+
+## 0.4.4
+
+- Show which verifier public key is being used (env vs embedded) in License Status to help troubleshoot `signature_invalid`.
+
+## 0.4.5
+
+- Do not include `tools/` in the packaged install `.tgz` (repo-only development utilities).
+
+## 0.4.6
+
+- Add `PORTALSMITH_LICENSE_PUBLIC_KEY_PEM_FILE` support for robust license verification in systemd/docker environments.
+
+

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 CyprNet Solutions, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,58 @@
+## PortalSmith FormGen (uibuilder-formgen)
+
+PortalSmith FormGen is a Node-RED contrib module that generates schema-driven uibuilder portals (HTML/JS) from a JSON schema. It is designed for **no-build-step** operation: generate → open in browser → submit back to Node-RED.
+
+### Website
+
+CyprNet Solutions: `https://www.cyprnetsolutions.com`
+
+### Features
+
+- **Schema-driven forms**: sections + fields + basic validation
+- **Export**: JSON/CSV/HTML (client-side)
+- **Draft save/load**: browser + file workflows
+- **Theme + branding**: light/dark theme support; logo support (licensed)
+- **Results page**: optional result rendering after HTTP submit
+
+### Requirements (dependencies)
+
+- **Node.js**: 18+ (20.x recommended)
+- **Node-RED**: 3.1+ (4.x recommended)
+- **node-red-contrib-uibuilder**: v7.x
+- **Browser**: modern Chrome/Firefox/Edge
+
+### Installation
+
+Install into your Node-RED userDir:
+
+```bash
+cd ~/.node-red
+npm install @cyprnet/node-red-contrib-uibuilder-formgen
+```
+
+Then restart Node-RED.
+
+### Quick start
+
+1. Create a `uibuilder` instance (example URL: `form-jobapp`) and deploy.
+2. Send a schema into `uibuilder-formgen` as `msg.schema` (or use the example flow).
+3. Open `/uibuilder/<instance>/` in your browser.
+
+### Licensing (offline-first)
+
+- **Free (default)**: watermarked portal + default PortalSmith branding.
+- **Licensed (PRO)**: allows watermark removal and custom branding/logo (if enabled by your license features).
+
+To apply a license, paste the license key provided by CyprNet into the shared **`portalsmith-license`** config node and reference it from your `uibuilder-formgen` nodes. Restart Node-RED after installing/updating the module.
+
+### Documentation & examples
+
+- **Offline user guide** (packaged): `docs/user-guide.html`
+- **Example flow**: `examples/portalsmith-formgen-example.json`
+- **Industry schemas**: `examples/schemas/`
+- **Schema Builder frontend files**: `examples/formgen-builder/src/index.html` and `examples/formgen-builder/src/index.js`
+
+### License
+
+MIT. See `LICENSE`.
+

package/docs/user-guide.html

@@ -0,0 +1,565 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>PortalSmith FormGen - Offline User Guide</title>
+  <style>
+    :root {
+      --bg: #ffffff;
+      --text: #111827;
+      --muted: #4b5563;
+      --border: #e5e7eb;
+      --panel: #f9fafb;
+      --accent: #2563eb;
+      --codebg: #0b1020;
+      --codetext: #e5e7eb;
+    }
+    @media (prefers-color-scheme: dark) {
+      :root {
+        --bg: #0b1220;
+        --text: #e5e7eb;
+        --muted: #aab3c2;
+        --border: #243041;
+        --panel: #0f172a;
+        --accent: #60a5fa;
+        --codebg: #060913;
+        --codetext: #e5e7eb;
+      }
+    }
+    html, body { height: 100%; }
+    body {
+      margin: 0;
+      background: var(--bg);
+      color: var(--text);
+      font-family: system-ui, -apple-system, Segoe UI, Roboto, Helvetica, Arial, sans-serif;
+      line-height: 1.5;
+    }
+    a { color: var(--accent); text-decoration: none; }
+    a:hover { text-decoration: underline; }
+    .container {
+      max-width: 1100px;
+      margin: 0 auto;
+      padding: 28px 18px 60px;
+    }
+    .topbar {
+      border: 1px solid var(--border);
+      background: var(--panel);
+      border-radius: 10px;
+      padding: 14px 16px;
+      margin-bottom: 18px;
+    }
+    h1 { margin: 0 0 6px; font-size: 28px; }
+    .subtitle { color: var(--muted); margin: 0; }
+    .grid {
+      display: grid;
+      grid-template-columns: 320px 1fr;
+      gap: 18px;
+      align-items: start;
+    }
+    @media (max-width: 980px) {
+      .grid { grid-template-columns: 1fr; }
+    }
+    .toc {
+      position: sticky;
+      top: 14px;
+      border: 1px solid var(--border);
+      border-radius: 10px;
+      padding: 14px 14px 10px;
+      background: var(--panel);
+    }
+    .toc h2 { margin: 0 0 8px; font-size: 16px; }
+    .toc ul { margin: 0; padding-left: 18px; }
+    .toc li { margin: 4px 0; }
+    .content section {
+      border: 1px solid var(--border);
+      border-radius: 10px;
+      padding: 16px;
+      background: rgba(0,0,0,0.01);
+      margin-bottom: 14px;
+    }
+    .content h2 { margin: 0 0 8px; font-size: 20px; }
+    .content h3 { margin: 14px 0 6px; font-size: 16px; }
+    .note {
+      border-left: 4px solid var(--accent);
+      background: var(--panel);
+      padding: 10px 12px;
+      border-radius: 8px;
+      margin: 10px 0;
+      color: var(--muted);
+    }
+    .warn {
+      border-left: 4px solid #f59e0b;
+    }
+    .ok {
+      border-left: 4px solid #10b981;
+    }
+    code, pre {
+      font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
+    }
+    pre {
+      background: var(--codebg);
+      color: var(--codetext);
+      padding: 12px 12px;
+      border-radius: 10px;
+      overflow: auto;
+      border: 1px solid rgba(255,255,255,0.08);
+    }
+    .pill {
+      display: inline-block;
+      border: 1px solid var(--border);
+      border-radius: 999px;
+      padding: 2px 10px;
+      background: var(--panel);
+      font-size: 12px;
+      color: var(--muted);
+      margin-right: 6px;
+    }
+    table {
+      width: 100%;
+      border-collapse: collapse;
+      margin: 10px 0;
+      border: 1px solid var(--border);
+      border-radius: 10px;
+      overflow: hidden;
+    }
+    th, td {
+      border-bottom: 1px solid var(--border);
+      padding: 10px 10px;
+      text-align: left;
+      vertical-align: top;
+    }
+    th { background: var(--panel); }
+    .footer {
+      margin-top: 22px;
+      color: var(--muted);
+      font-size: 13px;
+    }
+    @media print {
+      .toc { position: static; }
+      a { color: #000; text-decoration: underline; }
+      .topbar, .content section { break-inside: avoid; }
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <div class="topbar">
+      <h1>PortalSmith FormGen - Offline User Guide</h1>
+      <p class="subtitle">Everything you need to install, configure, generate portals, use the schema builder, and customize formgen (offline HTML).</p>
+      <div class="subtitle">
+        <span class="pill">Node-RED contrib: <code>node-red-contrib-uibuilder-formgen</code></span>
+        <span class="pill">Works with: <code>uibuilder</code> + Vue 2 portals</span>
+      </div>
+    </div>
+
+    <div class="grid">
+      <nav class="toc" aria-label="Table of Contents">
+        <h2>Contents</h2>
+        <ul>
+          <li><a href="#what-you-get">What you get</a></li>
+          <li><a href="#requirements">Requirements & versions</a></li>
+          <li><a href="#install">Install & upgrade</a></li>
+          <li><a href="#licensing">Licensing (Free vs Licensed)</a></li>
+          <li><a href="#folders">Folder locations (standard + Projects)</a></li>
+          <li><a href="#schema-builder">Schema Builder (form designer)</a></li>
+          <li><a href="#schemas">Schema examples library (industry templates)</a></li>
+          <li><a href="#schema-reference">Schema reference (field types)</a></li>
+          <li><a href="#generate">Generating a portal (uibuilder-formgen)</a></li>
+          <li><a href="#customize">Customization options (theme, logo, submit, API proxy)</a></li>
+          <li><a href="#submit-results">Submitting & results page</a></li>
+          <li><a href="#drafts-exports">Drafts & exports</a></li>
+          <li><a href="#troubleshooting">Troubleshooting</a></li>
+          <li><a href="#security">Security notes</a></li>
+        </ul>
+      </nav>
+
+      <main class="content">
+        <section id="what-you-get">
+          <h2>What you get</h2>
+          <p>
+            PortalSmith FormGen generates a complete uibuilder portal (HTML + JS) from a simple JSON schema.
+            You can design schemas using the Schema Builder and then generate portals on demand.
+          </p>
+          <ul>
+            <li><strong>Schema Builder</strong>: a UI that helps you create schemas without hand-writing JSON.</li>
+            <li><strong>Generated Form Portal</strong>: a user-facing form app with:
+              <ul>
+                <li>Validation</li>
+                <li>Draft save/load</li>
+                <li>Export JSON/CSV/HTML</li>
+                <li>Submit + Result page (Table/JSON)</li>
+              </ul>
+            </li>
+            <li><strong>Industry templates</strong>: ready-to-use example schemas (IT, HR, Banking, Healthcare, Maintenance).</li>
+          </ul>
+        </section>
+
+        <section id="requirements">
+          <h2>Requirements & versions</h2>
+
+          <p>
+            PortalSmith FormGen generates uibuilder portals that rely on the modern uibuilder client API and
+            recent Node.js runtime behavior. The following versions are the recommended baseline for a
+            clean install.
+          </p>
+
+          <h3>Minimum versions (recommended baseline)</h3>
+          <ul>
+            <li><strong>Node.js:</strong> 18.x LTS or newer (recommended: 20.x LTS)</li>
+            <li><strong>npm:</strong> use the version bundled with Node.js (Node 18 typically npm 9+, Node 20 typically npm 10+)</li>
+            <li><strong>Node-RED:</strong> 3.1+ minimum (4.x recommended)</li>
+            <li><strong>node-red-contrib-uibuilder:</strong> v7.x (recommended: latest v7)</li>
+            <li><strong>Browser:</strong> modern Chrome / Firefox / Edge</li>
+          </ul>
+
+          <h3>Why these minimums matter</h3>
+          <ul>
+            <li>
+              Generated portals assume the <strong>uibuilder v7 IIFE client</strong>
+              (<code>uibuilder.iife.min.js</code>) and use the modern
+              <code>onChange('msg', ...)</code> client API style.
+            </li>
+            <li>
+              Draft <strong>Load</strong> uses a browser file picker, which is supported reliably only by
+              modern browsers.
+            </li>
+          </ul>
+
+          <div class="note ok">
+            <strong>Known-good test environment:</strong>
+            Node.js 20.19.x, Node-RED 4.0.x, uibuilder v7.x
+          </div>
+
+          <div class="note warn">
+            <strong>Browser TLS note:</strong>
+            Browsers cannot bypass invalid or self-signed TLS certificates for direct HTTP requests.
+            If you must call a self-signed API, use the <strong>server-side API proxy</strong> feature in
+            <code>uibuilder-formgen</code>.
+          </div>
+
+          <div class="note">
+            <strong>uibuilder sanity check:</strong>
+            If a generated portal appears broken or does not receive messages, verify that the page
+            successfully loads
+            <code>../uibuilder/uibuilder.iife.min.js</code>. This confirms that uibuilder v7 is installed
+            and serving the client bundle.
+          </div>
+        </section>
+
+        <section id="install">
+          <h2>Install & upgrade</h2>
+          <h3>Install the node</h3>
+          <ol>
+            <li>In Node-RED: Menu → Manage palette → Install</li>
+            <li>Install <code>node-red-contrib-uibuilder-formgen</code> (or install from a <code>.tgz</code> file)</li>
+            <li><strong>Restart Node-RED</strong></li>
+          </ol>
+
+          <h3>Install/upgrade uibuilder</h3>
+          <ol>
+            <li>In Node-RED: Menu → Manage palette → Install</li>
+            <li>Install/upgrade <code>node-red-contrib-uibuilder</code></li>
+            <li>Restart Node-RED if prompted</li>
+          </ol>
+        </section>
+
+        <section id="licensing">
+          <h2>Licensing (Free vs Licensed)</h2>
+          <p>
+            PortalSmith FormGen supports an <strong>offline-first</strong> licensing model. License validation happens locally in Node-RED.
+            There is <strong>no phone-home</strong> and no external verification service.
+          </p>
+
+          <h3>Free mode (default)</h3>
+          <ul>
+            <li>Fully functional form generation</li>
+            <li>Generated portals show a small watermark: <strong>“Powered by PortalSmith FormGen”</strong></li>
+            <li>Default PortalSmith branding is used</li>
+            <li>Custom logo/branding is disabled (attempts are ignored with a warning)</li>
+          </ul>
+
+          <h3>Licensed (PRO)</h3>
+          <ul>
+            <li>Allows watermark removal (if enabled in the license features)</li>
+            <li>Allows custom branding/logo (if enabled in the license features)</li>
+          </ul>
+
+          <h3>Where to set the license key</h3>
+          <ul>
+            <li><strong>Shared (recommended):</strong> create a <code>portalsmith-license</code> config node and select it in each <code>uibuilder-formgen</code> node.</li>
+            <li><strong>Per-node override:</strong> paste a key into the <code>uibuilder-formgen</code> node’s <strong>License Key</strong> field.</li>
+            <li><strong>Environment variable (optional):</strong> <code>PORTALSMITH_LICENSE</code></li>
+          </ul>
+
+          <div class="note">
+            <strong>Format:</strong> License keys are deterministic signed strings of the form <code>PSLF1.&lt;payload&gt;.&lt;signature&gt;</code>.
+            The payload is not secret; the signature provides authenticity.
+          </div>
+        </section>
+
+        <section id="folders">
+          <h2>Folder locations (standard + Projects)</h2>
+          <p>There are two common layouts:</p>
+
+          <h3>Standard Node-RED userDir</h3>
+          <pre>~/.node-red/
+  uibuilder/
+    &lt;instance&gt;/
+      src/
+        index.html
+        index.js
+        form.schema.json</pre>
+
+          <h3>Node-RED Projects</h3>
+          <pre>~/.node-red/projects/&lt;projectName&gt;/
+  uibuilder/
+    &lt;instance&gt;/
+      src/
+        index.html
+        index.js
+        form.schema.json</pre>
+
+          <div class="note ok">
+            <strong>Tip:</strong> FormGen can write to either layout using path options (Project name / uibRootDir / instanceRootDir).
+          </div>
+        </section>
+
+        <section id="schema-builder">
+          <h2>Schema Builder (form designer)</h2>
+          <p>The Schema Builder is a uibuilder instance that you host like any other uibuilder page.</p>
+
+          <h3>What it does</h3>
+          <ul>
+            <li>Create/edit sections and fields visually</li>
+            <li>Validate schema structure</li>
+            <li>Generate JSON preview</li>
+            <li>Send schema to Node-RED (“Generate Form”)</li>
+            <li><strong>New Schema</strong> button resets your current schema</li>
+          </ul>
+
+          <h3>How to host it</h3>
+          <ol>
+            <li>Create a uibuilder instance (example name: <code>formgen-builder</code>)</li>
+            <li>Copy the builder files into that instance’s <code>src/</code> folder</li>
+            <li>Deploy and open: <code>/uibuilder/formgen-builder/</code></li>
+          </ol>
+
+          <div class="note">
+            <strong>Builder dependencies:</strong> the builder’s HTML includes scripts for Vue/Bootstrap/Bootstrap-Vue/jQuery via CDN in the builder page itself.
+          </div>
+
+          <div class="note ok">
+            <strong>Where to get the Schema Builder files:</strong>
+            After installing <code>node-red-contrib-uibuilder-formgen</code>, copy these files from the package:
+            <ul>
+              <li><code>examples/formgen-builder/src/index.html</code></li>
+              <li><code>examples/formgen-builder/src/index.js</code></li>
+            </ul>
+            Into your uibuilder instance folder:
+            <ul>
+              <li><code>&lt;userDir&gt;/uibuilder/formgen-builder/src/</code></li>
+              <li>or Projects: <code>&lt;userDir&gt;/projects/&lt;projectName&gt;/uibuilder/formgen-builder/src/</code></li>
+            </ul>
+          </div>
+        </section>
+
+        <section id="schemas">
+          <h2>Schema examples library (industry templates)</h2>
+          <p>Example schemas are included with the node package under:</p>
+          <pre>node-red-contrib-uibuilder-formgen/examples/schemas/</pre>
+
+          <h3>Industry folders</h3>
+          <ul>
+            <li><strong>IT</strong>: <code>examples/schemas/IT/</code></li>
+            <li><strong>Maintenance</strong>: <code>examples/schemas/Maintenance/</code></li>
+            <li><strong>HR</strong>: <code>examples/schemas/HR/</code></li>
+            <li><strong>Banking</strong>: <code>examples/schemas/Banking/</code></li>
+            <li><strong>Healthcare</strong>: <code>examples/schemas/Healthcare/</code></li>
+          </ul>
+
+          <h3>How to use a template</h3>
+          <ol>
+            <li>Pick a schema JSON file from the templates folder</li>
+            <li>Paste it into an Inject node as <code>msg.schema</code></li>
+            <li>Inject → <code>uibuilder-formgen</code> to generate a portal</li>
+            <li>Open the portal URL in a browser</li>
+          </ol>
+        </section>
+
+        <section id="schema-reference">
+          <h2>Schema reference (field types)</h2>
+          <p>Each schema is a JSON object with:</p>
+          <ul>
+            <li><code>schemaVersion</code></li>
+            <li><code>formId</code></li>
+            <li><code>title</code></li>
+            <li><code>description</code> (optional)</li>
+            <li><code>sections[]</code> → each section has <code>fields[]</code></li>
+            <li><code>actions[]</code> (optional)</li>
+          </ul>
+
+          <h3>Supported field types</h3>
+          <table>
+            <thead><tr><th>Type</th><th>Description</th></tr></thead>
+            <tbody>
+              <tr><td><code>text</code></td><td>Single-line input (supports email/tel/url/password via <code>inputType</code>)</td></tr>
+              <tr><td><code>textarea</code></td><td>Multi-line text input (<code>rows</code>)</td></tr>
+              <tr><td><code>number</code></td><td>Numeric input (<code>min</code>/<code>max</code>/<code>step</code>)</td></tr>
+              <tr><td><code>select</code></td><td>Dropdown with <code>options</code></td></tr>
+              <tr><td><code>radio</code></td><td>Radio group with <code>options</code></td></tr>
+              <tr><td><code>checkbox</code></td><td>Boolean checkbox</td></tr>
+              <tr><td><code>date</code></td><td>Date picker</td></tr>
+              <tr><td><code>keyvalue</code></td><td>Key/value entry. Two modes: pairs or delimiter text.</td></tr>
+            </tbody>
+          </table>
+
+          <h3>Key/value fields (keyvalue)</h3>
+          <p><strong>Pairs mode</strong> stores an array of objects:</p>
+          <pre>{
+  "id": "labels",
+  "type": "keyvalue",
+  "label": "Labels",
+  "keyvalueMode": "pairs",
+  "pairs": [{ "key": "env", "value": "prod" }]
+}</pre>
+          <p><strong>Delimiter mode</strong> uses a textarea in the UI, and submits as <strong>array of strings</strong> (one per line):</p>
+          <pre>{
+  "id": "udfs",
+  "type": "keyvalue",
+  "label": "UDF lines",
+  "keyvalueMode": "delimiter",
+  "keyvalueDelimiter": "="
+}</pre>
+        </section>
+
+        <section id="generate">
+          <h2>Generating a portal (uibuilder-formgen)</h2>
+          <p>You generate portals by sending a schema into the <code>uibuilder-formgen</code> node.</p>
+
+          <h3>Minimum input</h3>
+          <pre>{
+  "schema": { ... }
+}</pre>
+
+          <h3>Recommended input shape</h3>
+          <pre>{
+  "schema": { ...schema json... },
+  "uibuilder": "my-portal-instance",
+  "options": {
+    "overwrite": true
+  }
+}</pre>
+        </section>
+
+        <section id="customize">
+          <h2>Customization options (theme, logo, submit, API proxy)</h2>
+
+          <h3>Theme</h3>
+          <ul>
+            <li><code>themeMode</code>: <code>auto</code>, <code>light</code>, or <code>dark</code></li>
+          </ul>
+
+          <h3>Logo</h3>
+          <ul>
+            <li><code>logoPath</code>: absolute path (copied into <code>src/images/</code>) or filename (assumed in <code>src/images/</code>)</li>
+            <li><code>logoAlt</code>: alt text</li>
+          </ul>
+
+          <h3>Submit modes</h3>
+          <ul>
+            <li><strong>uibuilder</strong>: send to Node-RED via uibuilder messages (recommended)</li>
+            <li><strong>http</strong>: browser fetch POST (HTTPS only for secure pages; cannot bypass invalid certs)</li>
+          </ul>
+
+          <h3>Server-side API proxy (recommended for TLS control)</h3>
+          <p>
+            When enabled, Node-RED receives form submissions and calls an external API.
+            This is where you can allow self-signed TLS if needed.
+          </p>
+          <ul>
+            <li><code>apiUrl</code> (required to enable)</li>
+            <li><code>apiMethod</code>: POST/PUT/PATCH</li>
+            <li><code>apiHeadersJson</code>: JSON headers</li>
+            <li><code>apiInsecureTls</code>: allow self-signed certs (server-side only)</li>
+            <li><code>apiTimeoutMs</code></li>
+          </ul>
+        </section>
+
+        <section id="submit-results">
+          <h2>Submitting & results page</h2>
+          <p>After Submit, the portal shows a Result page with:</p>
+          <ul>
+            <li><strong>Table view</strong> and <strong>JSON view</strong> toggle</li>
+            <li><strong>Download JSON</strong></li>
+          </ul>
+          <p>Table view formatting:</p>
+          <ul>
+            <li>Top-level object keys show as rows</li>
+            <li>Arrays show as <code>a | b | c</code></li>
+          </ul>
+        </section>
+
+        <section id="drafts-exports">
+          <h2>Drafts & exports</h2>
+          <h3>Drafts</h3>
+          <ul>
+            <li><strong>Save Draft</strong>: downloads a draft JSON, and uses browser localStorage if available</li>
+            <li><strong>Load Draft</strong>: loads from localStorage if available; otherwise loads from a selected draft JSON file</li>
+          </ul>
+
+          <h3>Exports</h3>
+          <ul>
+            <li>JSON/CSV/HTML exports download directly in the browser</li>
+          </ul>
+
+          <h3>Clear Form</h3>
+          <ul>
+            <li><strong>Clear Form</strong> resets all fields to defaults (with confirmation)</li>
+          </ul>
+        </section>
+
+        <section id="troubleshooting">
+          <h2>Troubleshooting</h2>
+          <h3>“I don’t see my result page”</h3>
+          <ul>
+            <li>Ensure the message returned to the portal is shaped as <code>msg.payload.type = "submit:ok"</code> and includes <code>msg.payload.result</code>.</li>
+            <li>If you set <code>msg.type</code> instead, the portal will ignore it.</li>
+          </ul>
+
+          <h3>“HTTPS works, but my self-signed API fails”</h3>
+          <ul>
+            <li>Direct browser submit cannot ignore cert errors.</li>
+            <li>Use server-side API proxy and enable insecure TLS there (if required).</li>
+          </ul>
+
+          <h3>uibuilder warning about <code>sioUse.js</code></h3>
+          <ul>
+            <li>That warning means the uibuilder root path is pointing at a folder with an invalid <code>.config/sioUse.js</code>.</li>
+            <li>Fix by correcting the uibuilder root path (Projects vs standard) or disabling the file.</li>
+          </ul>
+        </section>
+
+        <section id="security">
+          <h2>Security notes</h2>
+          <div class="note warn">
+            Generated portals are not authenticated by default. Put authentication in front of Node-RED/uibuilder if required.
+          </div>
+          <ul>
+            <li>Do not enable insecure TLS in production unless you fully understand the risk.</li>
+            <li>Prefer trusted certificates (reverse proxy, internal CA, or public CA) wherever possible.</li>
+            <li>License keys (if used) are stored in the Node-RED credentials store (encrypted at rest when <code>credentialsSecret</code> is configured).</li>
+          </ul>
+        </section>
+
+        <div class="footer">
+          <div>File: <code>docs/user-guide.html</code></div>
+          <div>This guide is designed to be viewed offline and printed.</div>
+        </div>
+      </main>
+    </div>
+  </div>
+</body>
+</html>
+
+