build-with-fillo

Build with Fillo

Add a real form inside the host product, or create a hosted Fillo link when the user explicitly asks for a standalone, shareable form. For an embed, keep the host app in control of its route, layout, components, account context, and post-submit behavior. Let Fillo own schema, validation, uploads, responses, versions, exports, and delivery.

Use the repository, browser, and test tools available in the current agent. Never require a provider-specific agent command.

Work in this order

1. On a first-time setup — installing Fillo or provisioning a workspace — open with a three-line plan before running anything, for example: "1) I install Fillo's SDK and skill. 2) I build the form inside your app. 3) You get an email to claim your workspace, where responses live." Add that a few permission prompts may need approving along the way. Skip the recap when Fillo is already set up in the repo.
2. Inspect the task environment and any host repository. For an embed, identify its framework, package manager, target route, existing Fillo packages, theme provider/switch, light and dark selectors, CSS color-scheme, design tokens, and the input, label, button, error, focus, spacing, radius, and typography primitives already used beside the form. For a standalone hosted form, a host route and renderer may not exist. In either path, preserve any supplied form id, key, setup command, or run token.
3. If the form may need uploads, check storage readiness before choosing the schema, not after a blocked publish. The canPublishFileFields boolean answers whether an unpinned storage = null file field can publish now; it does not confirm a specifically pinned provider. A provider can also show connected while no default destination is resolved. With a CLI login, read the generic signal and provider-specific status from fillo whoami or fillo storage status (both --json). On the unclaimed preview (no login), those commands are unreachable — read the generic signal from agent bootstrap or push --json, and treat an exact durable selection as pending until the owner connects it. Do not defensively drop a needed file field; ask the user to finish connecting its destination instead.
4. Establish the form's source of truth:
   • Published form id or slug: render it directly. No client key is required.
   • React-owned schema: use <Fillo.Form> or defineForm() with @usefillo/react.
   • Vue, Svelte, Astro, or browser-owned schema: use defineForm() and renderForm() from @usefillo/dom.
   • Dashboard or CLI-owned schema: keep the schema there and embed the returned formId.
   • Fully custom UI: use FilloProvider and hooks in React, or createFormController() elsewhere.
   • Standalone hosted request: keep it in Fillo and return the published /f/{slug} URL. Do not add a host-app route or embed unless the user asks. For a file request, read the deployment's /request-files.md and use its exact CLI-ready object with stable id file-request instead of regenerating a similar schema. Its top-level id is the stable push handle; do not rename it to templateId or omit it and create duplicates. Set its top-level storage to the owner's exact gdrive, box, s3, or r2 choice so the form records the intended durable destination. Every interactive embed must have exactly one submission identity: a published formId, or a defineForm() / <Fillo.Form> value plus a client. A plain FormSchema plus a client is not a code-defined form and cannot resolve a target. Use explicit renderOnly only for a deliberately non-submitting UI preview.
5. Ask only for missing product decisions that change the result: purpose, placement, required questions or files, conditional behavior, and what happens after submit. Infer routine implementation details from the repo.
6. If the prompt supplies a handoff command, project key, form id, or run token, follow that handoff exactly. Do not create another project or save a run token.
7. Implement the smallest complete form and verify the requested hosted page or host-app route. Treat a rendered form as preview proof only, never as proof that Fillo will save responses. Before closing, inspect the lifecycle result from sync or push and, with a CLI login, run npx @usefillo/cli@latest status <formId|handle>. Complete any publication the user authorized and verify published status. If review, credentials, or a blocker leaves it draft or staged, lead the handoff with Not live — responses will not be saved and the exact Publish or setup action. Never describe a draft as deployed, ready, or complete.