# G-Form User Manual

A role-based guide to G-Form, with troubleshooting and FAQ.

> Screenshots live in [`docs/screenshots/`](./screenshots). Interface language can be switched between **English** and **ລາວ (Lao)** from the header at any time.
>
> 🇱🇦 ພາສາລາວ: [`USER_MANUAL.lo.md`](./USER_MANUAL.lo.md)

---

## Roles Overview

G-Form has three roles. Each role sees a different menu and set of pages.

| Role | Who it is | What they can do |
|---|---|---|
| **General user** | Anyone who signs up | Create, edit, publish, and analyze their own forms; collect submissions. |
| **Org admin** | Assigned by a super admin | Everything a general user can, plus manage users inside their organization. |
| **Super admin** | Platform owner (first user auto-becomes super admin) | Full platform control: users, organizations, branding, mail, translations, system config. |

Jump to your section:

- [Part A — General Users](#part-a--general-users)
- [Part B — Org Admins](#part-b--org-admins)
- [Part C — Super Admins](#part-c--super-admins)
- [Part D — Troubleshooting](#part-d--troubleshooting)
- [Part E — FAQ](#part-e--faq)

---

# Part A — General Users

Applies to every signed-in user.

## A1. Getting Started

![Landing page](./screenshots/landing.png)

- Open the site and click **Get started** or **Sign in** (top right).
- Toggle **EN / ລາວ** from the language switcher in the header any time.

## A2. Signing In & Account Security

![Authentication](./screenshots/auth.png)

- Sign up with email + password, or **Continue with Google**.
- New accounts must confirm their email before signing in.
- Rate limiting + a server-validated **challenge question** kick in after repeated failed attempts (bots cannot bypass it).
- If an admin created your account for you, you'll receive a temporary password by email and be forced to change it on first sign-in at `/force-password`.

## A3. Dashboard: Managing Your Forms

![Dashboard](./screenshots/dashboard.png)

- **Search** by title.
- **Filter** by status: All / Draft / Published / Archived.
- **Sort** by newest, oldest, or most submissions.
- **Pagination**: 10 / 20 / 30 / 40 / 50 per page (safe for hundreds of forms).
- Each row: title, status, view count, submission count, and actions (Edit, Submissions, Analytics, Share, PDF, Delete).

Click **+ New form** to create a form.

## A4. Creating a Form

![New form](./screenshots/form-new.png)

- Enter a **title** and optional **description**.
- Choose a unique **slug** (public URL: `/f/<slug>`).
- Click **Create** to open the editor.

## A5. Form Editor & Elements

Three areas: **Elements panel (left)**, **Canvas (center)**, **Properties panel (right)**.

**Auto-hide panels** — Clicking the canvas collapses side panels for more room. Hover the edge or use shortcuts to reopen.

Keyboard shortcuts:
- `[` toggle left panel
- `]` toggle right panel
- `\` toggle both

On mobile: swipe from edge (≥60px) to open a panel.

Supported elements:
- Short text, Long text (textarea)
- Email, Phone, Number
- Single choice (radio), Multiple choice (checkbox), Dropdown
- Date, Time
- File upload
- **Image** — insert a static image (logos, banners, illustrations)
- Section header / divider
- Rich text block (sanitized server-side)

Each field supports: label, help text, placeholder, required flag, validation rules, options (for choice fields). Elements support **vertical alignment** (Top/Middle/Bottom) and an optional **Float freely** position mode.

Click **Save** to persist, **Publish** to make public.

## A6. Publishing & Sharing

- **Draft**: only you can preview it.
- **Published**: live at `https://<your-domain>/f/<slug>`.
- **Archived**: hidden from the public URL but retained.

Share options: copy the public link; toggle "Powered by" branding (if allowed).

## A7. Viewing Submissions

From the dashboard, click **Submissions** on a form.

- Table view of responses; filter by date, search content.
- **Export** to CSV.
- Delete or update submissions (requires workspace membership).

Submissions are protected by row-level security — only workspace members of the form owner can read them.

## A8. Analytics

Per-form analytics:
- Views over time
- Submissions over time
- Conversion rate (submissions / views)
- Referrer breakdown

## A9. PDF Export

- From the dashboard or editor, click **PDF** to preview and download the form as a print-ready PDF.
- Images and logos are embedded automatically.

## A10. Account Settings

![Settings](./screenshots/settings.png)

- Update display name and avatar.
- Change password.
- Manage your workspace / org membership.
- Delete your account (org admin approval may apply).

You **cannot** self-elevate roles — a database trigger blocks edits to `role` or `suspended`.

---

# Part B — Org Admins

Everything in Part A, plus organization-scoped user management.

## B1. Managing Members

Org admins can:
- **Invite users by email.** Unregistered users are auto-provisioned: a temporary password is emailed to them and they are forced to change it on first sign-in.
- **Suspend / reactivate** members.
- **Delete** members.
- **Toggle "Use own branding"** for the organization (only available if super admin has enabled per-org branding).

## B2. Organization Branding

If the super admin enabled per-org branding for you, `/org` exposes:
- Logo
- Favicon
- Brand color / theme

Otherwise your org inherits platform branding.

## B3. Sharing Forms Inside the Org

Workspace membership determines who can read submissions. Add teammates to your workspace so they can view responses and export CSVs.

---

# Part C — Super Admins

Everything in Parts A and B, plus platform-wide administration. Super-admin menu items appear in the header for these users only.

## C1. `/admin/users` — Users

![Admin users](./screenshots/admin-users.png)

- View every user on the platform.
- Grant / revoke the **super_admin** role (you cannot revoke your own; the system guarantees at least one super admin remains).
- Suspend accounts.
- Filter/search by email or role.

## C2. `/admin/organizations` — Organizations & Branding

![Admin organizations](./screenshots/admin-organizations.png)

- Create organizations.
- Assign admins by email (auto-provisions the user if needed).
- Toggle **Use own branding** per organization.
- Delete or rename organizations.

## C3. `/admin/system` — System

![Admin system](./screenshots/admin-system.png)

- Inspect environment variables (redacted).
- Check database health.
- View app settings; toggle feature flags.
- Manage **global branding** (logo, favicon, theme colors) applied to any org that doesn't override.

Non-super-admins see a clean **Access denied** screen — no retry loop.

## C4. `/admin/smtp` — Mail

![Admin SMTP](./screenshots/admin-smtp.png)

Choose a provider:

| Provider | Transport | Notes |
|---|---|---|
| **SMTP (via relay)** | TCP 25/465/587 through the `smtp-relay` sidecar | Required on Cloudflare-hosted deployments where raw SMTP is blocked. |
| **Resend HTTP API** | HTTPS | Paste `re_...` key. |
| **SMTP2GO HTTP API** | HTTPS | Paste `api-...` key. |
| **SendGrid HTTP API** | HTTPS | Paste `SG.` key. Sender/domain must be verified. |

Credential security:
- Passwords and API keys are encrypted at rest with AES-256-GCM using `SMTP_ENCRYPTION_KEY`.
- The plaintext value is **never** returned by the API.
- **Rotate & re-encrypt** supports zero-downtime two-key overlap.

Testing:
- Enter a recipient and click **Send test**.
- The diagnostics panel shows: **config → connect → auth → send**, raw server response, accepted/rejected recipients, and hints (e.g. "try port 465 with TLS on").

## C5. `/translations` — Translations

![Translations](./screenshots/translations.png)

- Live-edit **English** and **Lao** strings without redeploying.
- Search keys, edit inline, save. Changes apply immediately for all users.

## C6. MCP / Agent Integrations

- Endpoint: `/mcp`
- Discovery: `/.well-known/oauth-authorization-server`
- Auth: **OAuth 2.1** (consent at `/.lovable/oauth/consent`)

Tools exposed: `list_forms`, `get_form`, `list_submissions`, `create_form`, `update_form`, `delete_form`, `publish_form`, `archive_form`.

All calls are scoped to the caller and enforced by row-level security.

---

# Part D — Troubleshooting

Common issues, root cause, and fix. Try these before opening a ticket.

## D1. Sign-in issues

| Symptom | Likely cause | Fix |
|---|---|---|
| "Invalid email or password" after correct entry | Email not confirmed | Open the confirmation email and click the link. Resend from the sign-in screen if expired. |
| Challenge question appears | Too many failed attempts from your IP | Answer the challenge. It resets after a successful sign-in. |
| Redirected to `/force-password` | Org admin created your account with a temporary password | Set a new password to continue. |
| "Unsupported provider" clicking Google | Google OAuth not configured for this deployment | Ask your super admin to configure Google in `/admin/system`. |
| Sign-in loops back to `/auth` | Session cookie blocked by browser | Enable third-party cookies for the site, or use a different browser. |

## D2. Form creation / editing

| Symptom | Fix |
|---|---|
| "new row violates row-level security policy for table 'forms'" | Your saved `workspace_id` is stale. Sign out and back in — the app will pick your current workspace. |
| Side panels won't reopen | Press `[` or `]`, or hover the edge of the canvas. On mobile, swipe from the edge. |
| PDF preview spins forever | Hard-reload the page (fonts VFS may have been blocked by an ad-blocker). Try a different browser. |
| Image element doesn't upload | File must be under the storage limit and an allowed image mime type (`png`, `jpg`, `webp`, `svg`). |

## D3. Public form submissions

| Symptom | Fix |
|---|---|
| "Form not found" on `/f/<slug>` | Form is Draft or Archived. Publish it. |
| Respondent hits rate limit | Anti-spam is per IP. Wait a few minutes or contact the form owner. |
| Duplicate submission blocked | Same payload was submitted recently from the same IP. Change any field or try again later. |

## D4. Email (super admin)

| Symptom | Fix |
|---|---|
| Test email stuck at **connect** | Wrong host/port, firewall blocking outbound SMTP, or Cloudflare Worker cannot open raw TCP. Use the SMTP relay sidecar or switch to an HTTP API provider. |
| Stuck at **auth** | Wrong username/password or API key. For Gmail/Workspace, use an App Password. |
| Send succeeds but email never arrives | Check SPF/DKIM/DMARC on your sending domain; check the recipient's spam folder; check the provider's dashboard for suppressions. |
| "Sender not verified" (SendGrid) | Complete Sender Authentication in SendGrid before sending. |
| Rotate key fails | Ensure the new `SMTP_ENCRYPTION_KEY` is set alongside the old one, then click **Rotate & re-encrypt**. |

## D5. Admin pages

| Symptom | Fix |
|---|---|
| `Forbidden: super_admin role required` | You are not a super admin. Ask an existing super admin to grant the role at `/admin/users`. |
| `/admin/system` shows Access denied | Same as above — expected for non-super-admins. |
| Branding doesn't apply to an org | Super admin must toggle **Use own branding** off for that org, or the org admin must upload their own logo/favicon in `/org`. |

## D6. MCP / agent integration

| Symptom | Fix |
|---|---|
| Agent gets 401 from `/mcp` | Complete OAuth consent at `/.lovable/oauth/consent`. |
| Tool returns "no rows" for `list_forms` | The connected user has no forms, or the wrong account was used at consent. Reconnect. |

---

# Part E — FAQ

**Q. Who becomes super admin?**
The first user to sign up automatically becomes super admin. After that, super admins grant the role from `/admin/users`.

**Q. Can I have multiple super admins?**
Yes. The system prevents you from revoking the *last* remaining super admin, so there's always at least one.

**Q. What happens if I invite an unregistered user as an org admin?**
They are auto-provisioned with a temporary password, emailed the credentials, and forced to change the password on first sign-in.

**Q. Can end-users register themselves as org admins?**
No. Role changes are blocked by a database trigger (`prevent_profile_self_escalation`). Only super admins can assign roles.

**Q. Is my data isolated between organizations?**
Yes. Row-Level Security ensures workspace members can only see their own workspace's forms, submissions, and files.

**Q. Are form responses anonymous?**
Public forms accept anonymous submissions by default. If you require sign-in, enable the "authenticated only" flag on the form.

**Q. How are SMTP passwords stored?**
Encrypted at rest with AES-256-GCM using `SMTP_ENCRYPTION_KEY`. Plaintext is never returned by any API. Rotation is supported without downtime.

**Q. Which email provider should I choose?**
- Hosted on Cloudflare / serverless → an **HTTP API** provider (Resend, SMTP2GO, SendGrid). Raw SMTP is blocked.
- Self-hosted with Docker → any option works. Use the `smtp-relay` sidecar if you want to keep the app on Cloudflare but relay SMTP through your own server.

**Q. How do I self-host G-Form?**
See [`DEPLOYMENT.md`](../DEPLOYMENT.md):
- **Option A:** Hosted backend + Dockerized app (`docker/option-a-hosted/`).
- **Option B:** Full self-hosted, including Supabase (`docker/option-b-selfhosted/`).

**Q. Can I edit translations without a redeploy?**
Yes. Super admins can edit English and Lao strings live at `/translations`.

**Q. Can I connect Claude / ChatGPT / Cursor to my forms?**
Yes, via the built-in MCP server at `/mcp` with OAuth 2.1. See [C6](#c6-mcp--agent-integrations).

**Q. How do I export data?**
Per-form CSV export is available on the Submissions page. For bulk export, super admins can query the database directly.

**Q. What are the file upload limits?**
Enforced by the underlying storage bucket. Ask your super admin to check `/admin/system` for the current cap.

---

## Getting Help

- **Docs**: [`README.md`](../README.md) · [`DEPLOYMENT.md`](../DEPLOYMENT.md)
- **Self-hosting**: [`docker/option-a-hosted`](../docker/option-a-hosted) or [`docker/option-b-selfhosted`](../docker/option-b-selfhosted)
- **Email relay**: [`docker/smtp-relay`](../docker/smtp-relay)