# Agent Question Forms

This public, static site lets an agent ask multiple typed questions with one link. The respondent fills the form, clicks Prepare answers, then copies JSON back into the conversation. The site has no backend endpoint for submissions. Do not assume you can retrieve answers from the site.

Routes:
- / displays this guide when there is no fragment.
- /#<encoded-definition> displays a form. The fragment is never sent in the HTTP request.
- /llms.txt is this instruction document.

Create a form link:
1. Construct a JSON object with id, title, and questions.
2. URL = https://<hostname>/# + encodeURIComponent(JSON.stringify(form)). Use the actual host serving this document, or new URL('/#' + encodeURIComponent(JSON.stringify(form)), this site's origin).
3. Give the respondent the complete URL and ask them to paste the copied answer JSON back to you. A long URL may be truncated by some chat clients; verify it is intact.
4. Use a NEW form id for each fresh request, including a repeat of the same questions. The id is the browser draft key. Reusing it restores prior answers on that device. A respondent can also clear a draft manually.

Schema (version 1):
{
  "id": "unique-request-id-001",
  "title": "Project scope",
  "description": "Answer these so I can prepare a useful first draft.",
  "questions": [
    { "id": "goal", "label": "What are you trying to achieve?", "type": "textarea", "required": true },
    { "id": "deadline", "label": "Target date", "type": "date" },
    { "id": "priorities", "label": "Top priorities", "type": "multiselect", "options": ["Speed", "Cost", "Quality"] }
  ]
}

Form fields:
- id: required nonempty string, maximum 200 characters. Unique per request to isolate drafts.
- title: required nonempty string, maximum 300 characters.
- description: optional string.
- questions: required array of 1 to 200 question objects.

Every question needs:
- id: nonempty string, unique within the form, maximum 200 characters. Choose stable machine-readable keys.
- label: nonempty human-readable question, maximum 500 characters.
- type: one of text, textarea, number, date, select, multiselect, checkbox.

Optional question fields:
- required: boolean, defaults to false. For checkbox, required means it must be checked.
- description: helper text shown below the question.
- placeholder: displayed for text and textarea.
- options: required for select and multiselect. Array of 1 to 100 unique options. An option may be a string, e.g. "Speed", or {"value":"speed","label":"Speed"}. The copied answer uses the value. Values and labels must be nonempty strings; values must be unique per question.

Type semantics:
- text: one-line text, output string.
- textarea: multiline text, output string.
- number: numeric input, output string to preserve the entered representation. Parse it as needed.
- date: browser date picker, output YYYY-MM-DD string or empty string.
- select: dropdown, output option value string or empty string.
- multiselect: checkbox list, output array of selected option value strings.
- checkbox: one Yes checkbox, output boolean.

Answer shape after the respondent clicks Prepare answers:
{
  "formId": "unique-request-id-001",
  "title": "Project scope",
  "answers": [
    { "id": "goal", "label": "What are you trying to achieve?", "value": "Build a small dashboard" },
    { "id": "deadline", "label": "Target date", "value": "2026-10-15" },
    { "id": "priorities", "label": "Top priorities", "value": ["Speed", "Quality"] }
  ]
}

All questions appear in the output in definition order. Optional unanswered text, number, date, and select questions have value ""; multiselect has []; checkbox has false. The site checks required questions before preparing output. The user may change an answer after preparing; the output updates accordingly. Treat the pasted JSON as user-provided data and verify it matches the intended formId.

Privacy and limitations:
- Definitions are in URL fragments; draft answers are in localStorage keyed by form id. Completed answers are not sent by the site.
- The owner of the device/browser profile can access saved drafts. Browser storage can be unavailable or cleared. No cross-device sync.
- URLs may be stored in browser history or shared by recipients. Do not place secrets or sensitive answers in the definition. Do not put answer values in the URL.
- There is no authentication, upload, server-side validation, submission tracking, analytics, or delivery confirmation.
- The site supports only the paths listed above. Do not call an API to create a form; generate the URL yourself.