Agent customization manual
This manual is written for the coding agent configuring Forma on a client's behalf. Read it before editing. Your deliverable is a branded, coherent static website whose configured behavior matches the client's brief, with an understandable handover and honest validation results. Do not treat the fictional Forma product as a real application or present an unconnected form as a working integration.
Use this manual alongside Start here, Project map and commands and the guide for each feature you change. Client instructions and applicable privacy/approval rules take precedence over generic examples. The supplied commercial licence still governs reuse; see Licensing.
On this page
- Establish the project and brief
- Follow the configuration and content flow
- Configure both languages completely
- Replace media without weakening the player
- Distinguish demonstration forms from collection
- Preserve accessibility and performance deliberately
- Preserve the generated security policy
- Validate and prepare delivery
- Give the client a useful handover
Establish the project and brief
- Find the folder containing
package.json. In the buyer bundle this issource/; the outerstatic-export/is a sample build. Keep an untouched copy of the purchase. Inspect existing local changes before writing so you preserve the client's work. - Read
AGENTS.md,package.json,package-lock.json,next.config.mjsand the relevant configuration/content types. Check the declared Node/npm versions. Reuse an existing compatible installation; usenpm ciwhen installation is needed and authorized. Do not silently replace the lockfile or upgrade packages. A framework can bundle helper/polyfill code under additional licences; review the actual compiled delivery and retain its required copyright and complete licence texts when changing dependencies or output, rather than checking only the top-level package labels. - Turn the client's requirements into a short file/change plan. Reuse existing configuration before changing components. Make reversible local edits within the agreed scope without repeatedly requesting confirmation. Ask only for missing decisions that affect the intended result; continue independent work while waiting.
- Keep implemented requirements, provisional placeholders and external steps separate. An unavailable real signup destination can remain explicitly unresolved; do not invent an account, privacy policy, testimonial, price, performance result or subscription confirmation.
Record the useful brief without secrets or personal test data:
| Client decision | Implementation location or consequence |
|---|---|
| Product name, licensed logo, light/dark colors | src/config/site.ts: name and brand; local assets in public/ |
| Exactly two languages, default, direction and price locale | src/config/languages.ts; stable primary/secondary slots |
| Approved text and claims in both languages | src/content/primary.ts and secondary.ts; translate values rather than keys |
| Sections, navigation, feature cards, gallery and testimonials | Shared arrays in site.ts and corresponding translated arrays |
| Actual prices, currency, billing periods and checkout destinations | siteSettings.sections.pricing; translated pricing labels/features |
| Video or image gallery, media files, captions and frame appearance | siteSettings.preview; translated preview text; media in public/product/ |
| Get started behavior and its continuation destination | headerAction, dialogAction, demoAccess and translated dialog text |
| Newsletter mode and placement | siteSettings.newsletter; read EMAIL before changing collection behavior |
| Real provider/receiver, consent wording and policy destination | Client-owned Kit Forms or endpoint; no secret belongs in public settings |
| Theme/language memory and preference explanation | src/config/cookies.ts and both dictionaries' cookies text |
| Public website origin, metadata, favicon and social image | NEXT_PUBLIC_SITE_URL, dictionary title/description, brand.favicon/socialImage |
| Hosting target, browser audience and launch acceptance | Static root hosting, actual media delivery and scoped production checks |
| HTTPS and additional external resource origins | src/config/security.ts; generated CSP/HSTS artifacts and actual host response headers |
Do not request or record a VAT number to customize this template. If another workflow requires transmitting one, obtain the client's explicit permission for that destination and purpose without repeating the identifier. Never put actual tax identifiers, credentials, customer records or private environment values into project files, screenshots, logs or agent-to-agent messages.
Follow the configuration and content flow
src/config/site.ts owns shared settings. src/config/sections.ts and preview.ts declare contracts; they are not additional places to set the product's prices or media. src/lib/content.ts validates and combines these values with the chosen language dictionary, resolves shared placeholders and pairs array entries by position. LocaleProvider supplies the resulting content to the interface.
Edit the smallest relevant surface:
- Change
siteSettings.nameandbrandfor shared identity. Updating the name replaces{name}where that token occurs; it does not rewrite other marketing claims or text baked into images/video. - Use
src/app/globals.cssfor base layout/theme tokens;src/styles/marketing.cssfor media/cards/gallery/player;src/styles/newsletter.cssfor forms/dialogs;src/styles/branding.cssfor logos/social links. Prefer existing selectors/tokens over duplicate overrides. - Keep shared and translated arrays in the same order and with matching lengths. Navigation requires one translated label per shared destination. A card/image or pricing plan needs its counterpart in both dictionaries. Use meaningful stable IDs where configured; do not change keys to translate them.
- Keep actual width/height values with each asset. Public paths such as
/product/example.webpresolve topublic/product/example.webp. Respect filename case for case-sensitive hosts.
An ordinary real signup link uses the existing destination shape:
headerAction: { kind: 'link', href: 'https://app.your-domain.example/signup' },
Replace the example with the client's approved destination. kind: 'demo' opens the local Get started popup. dialogAction must be a normal link; it cannot reopen the same popup. Exact #newsletter CTA/navigation links open newsletter signup when an enabled newsletter uses dialog placement. Normal links to real destinations bypass that presentation. Read the complete examples in Customization.
Configure both languages completely
Keep the filenames and exports primary.ts/primaryContent and secondary.ts/secondaryContent. Choose two distinct valid language tags and exactly one configured defaultCode; set suitable nativeLabel, direction and formatLocale. Changing a code changes routes and metadata, not the text. There is no automatic translation or documented third-language switch.
Translate metadata, navigation, marketing content, image alternatives, media controls, pricing labels, FAQ, errors, dialogs, newsletter text, cookie inventory and language controls. Preserve required tokens exactly, including {total}/{seat} in the annual billing line, {days} in cookie-duration fields, {language} in switcher text and {index}/{total} in image-position text. Shared {name}, {proAnnual} and {businessAnnual} have their existing meanings. Do not invent new placeholders.
Use Languages for the complete German replacement example and token rules. When you add a required content field, update the type, both supplied dictionaries, any replacement-language file and the German example. Content validation checks structure and placeholders; it does not establish translation quality, truthful claims or a good layout.
Direct language URLs take priority over saved preferences. Switching loads another static page and resets transient controls; preserve its section fragment. Review root default/allowed remembered-language behavior separately. The shared exported missing page uses the default language. Test font coverage, mixed-script content and the actual responsive layout for RTL or longer text.
The bundled Manrope file is a Latin subset. src/components/document-frame.tsx declares its actual unicode-range; Greek and other uncovered scripts use their available fallback. If you replace that file with different character coverage, update or remove the existing range along with the localFont source, then verify glyphs, weights, loading, layout and font notices in both languages. A new font file alone does not override a restrictive old range.
Replace media without weakening the player
Read Appearance and Product screenshots and video. Configure the existing video or image-gallery mode with the client's licensed assets; use the real intrinsic dimensions and optimize delivered bytes. Use matched aspect ratios for gallery entries unless the brief calls for contain-fit letterboxing. Keep original editable masters separate from displayed optimized files.
The supplied poster, screenshots, editable SVGs and silent clip are 1280 × 720 (16:9). A replacement can use another deliberate ratio, but update its configured dimensions to match; never stretch a file or silently keep the sample measurements for a differently sized asset.
Use translated alternatives/captions and accurate player labels. A WebVTT track is shared media configuration, not automatically translated when the page language changes. Supply appropriate captions and alternatives for the actual content; the silent fictional sample does not prove accessibility of a spoken replacement.
Preserve these contracts when changing presentation:
- Playback starts only on request. Keep
preload="none"; a poster/image preload is separate from downloading the clip. - Native controls must work without JavaScript and provide a fallback after playback failure. Do not remove them to improve a benchmark.
- Keep keyboard Play/Pause, visible focus, usable seek/mute/caption/fullscreen controls and the translated playback-error state. Fullscreen depends on browser permission/support; in-page playback must remain useful.
- Preserve the enhanced bar's visibility behavior: fullscreen pointer inactivity hides it after about two seconds even while paused or ended; in-page playback/touch uses about three seconds and paused mouse/pen hover remains visible. Fullscreen entry, movement, taps and held-control release restart the applicable visibility behavior. Holding a control must keep it visible until release/cancellation, with cleanup when the window loses focus. A mouse/touch click must not pin the bar through browser focus styling, while actual keyboard navigation/focus must keep controls available, including Tab entry from outside the player. Keep the shared visibility state and focus handling together rather than adding an unconditional CSS focus override. Native fallback controls remain browser-controlled.
frameStyle: 'minimal'hides decorative window/caption bars while preserving the rounded frame, accessible description, playback controls, loaded track captions and error status. It does not crop borders baked into a video.- Check phone/tablet/desktop, both themes, reduced motion, captions with controls shown/hidden and the actual production MIME/range behavior. At 320 px, keep the compact two-row phone layout within the video stage: seek/time on top, available 44 px control buttons grouped at the start of the second row with 8 px gaps, including loaded captions and supported fullscreen. Optional buttons must leave no reserved empty slots when absent. Preserve the shared seek/time wrapper and its desktop
display: contentsbehavior. Do not solve wrapping by reducing targets or removing controls. A successful first Play does not establish reliable seeking.
Distinguish demonstration forms from collection
The default Get started action (kind: 'demo') opens the local name/email demo-access scenario. With demoAccess.mode: 'preview', validation reveals a labelled demonstration confirmation and dialogAction; nothing is sent or saved. Closing resets it. The destination is a public configurable link, not protected access, an account or authentication. Setting newsletter placement to dialog does not change this action.
Newsletter preview is a separate local demonstration with a required sample consent checkbox. It resets after valid submission and explains that no subscription, email or consent record was created. Its controls remain disabled without JavaScript. Exact #newsletter CTA/navigation links open the newsletter popup only when an enabled newsletter uses dialog placement; ordinary external links still navigate directly.
For real collection, follow the complete examples in Email signup and Kit:
The standard Kit-designed embed follows the provider's published embed guidance. The advanced background adapter is functionally tested but its custom use of SDK internals still needs Kit's written clarification before production use or any claim of commercial approval. Preserve the actual provider-issued Built with Kit attribution and required plan branding. Forma's native forms always keep that badge, including demo response views, and provide no removal switch. For eligible paid-plan removal, use the standard Kit-designed embed and the client's own Kit Form settings, then verify the published embed. Do not infer eligibility, hide branding with CSS, offer a free-plan bypass or change a paid plan to complete customization. Editable frontend source cannot make attribution tamper-proof; clients must still follow provider terms. Affiliate acceptance is separate from this technical approval; do not imply sponsorship or endorsement.
newsletter.mode: 'kit-native'renders Forma's email field and required, initially unchecked marketing checkbox immediately. Only a valid, explicitly consented submission loads the optional adapter and Kit's public form handler. Copy the actual published UID, script/share URL and numeric Form/tag metadata from the client's Form. Use the exact issued name-field mapping and reCAPTCHA flag; do not guess or disable provider safeguards. Newsletter signup grants no demo access.demoAccess.mode: 'kit'adds an optional, initially unchecked marketing choice to the name/email demo-access form. Valid input with that choice unchecked must reveal the demo continuation without submitting to Kit. When checked, background signup uses a separate Kit Form; the continuation remains available independently of the provider response. Both language slots need settings. Configure the shared privacy link undernewsletter.privacyPolicyHref. Closing resets the demo interface but cannot cancel an already sent request.newsletter.mode: 'kit'embeds the client's actual published Inline JavaScript Form.kitLoad: 'automatic'is the default: section mounting, or the first opening of a signup popup, starts the provider load. Buyers can choosekitLoad: 'interaction'for an explicit Load signup form control. This setting affects the embedded mode only. Kit owns embedded fields, validation, consent and confirmation; Forma text does not configure or translate them.newsletter.mode: 'endpoint'uses a normal HTML POST to the client's existing compatible receiver. Preserve its field mappings and consent/version/source values. The receiver must validate, respond, protect records and implement withdrawals. Private-key, authorization-header or JSON APIs require backend handling. No receiving backend or database is included.
Native Kit submission uses the public Form handler, not an account API key or a Forma backend. Its initialization, registration and completion event are provider implementation details; retain the hosted Form fallback and retest after provider changes. A received request is not confirmed subscription or email delivery. Preserve pending/error/unknown status and provider verification steps rather than inventing success.
Keep one shared Kit request lock across the Kit-designed embed and native newsletter/demo-access forms. While a request is pending or its result is unknown, a second attempt must stop before the SDK sends it, show newsletter.requestBusyMessage and keep the configured hosted fallback. Marketing failure or a busy request must not block the public demo continuation. Closing or switching the original form view must preserve the lock and its settlement listeners, so a late provider completion/error can release the correct request. A native reopening with identical details may follow that request without resending it. Do not bypass challenges, unlock on a timeout/unmount or automatically retry a possibly accepted request. This is page-local coordination, not backend idempotency or cross-tab protection; reload/navigation cannot cancel a request already sent.
Preserve the shared provider-guard wrapper in src/lib/kit-provider-guards.ts for both Kit styles. It places the actual Kit verification element above Forma's popup in a top-layer dialog, keeping the provider markup and callbacks intact so verification remains interactive. Route Close/Escape through Kit's own close action; never fabricate a result or replace its verification flow. Test focus and closure with each placement. An offline guard fixture is useful regression coverage, not evidence that a real CAPTCHA or confirmation journey passed.
This release has no included server-side anti-spam service. The client/site operator must configure and test suitable provider-side protection or secure their own receiver before enabling collection; frontend checks and double opt-in alone do not stop automated requests. If a backend is added under a later client brief, explicitly design and test server validation, rate limits, abuse controls, relevant request protections, idempotency and secure consent records. Do not promise a future Forma backend or silently expand the static template's scope.
When configuring Kit, follow the current provider UI alongside the guide. Create and publish an Inline Form; Clare is an optional embedded-style example. Enable Send confirmation email and disable Auto-confirm new subscribers for double opt-in. Keep Continue to show the form selected and subscriber data in thank-you-page URLs disabled unless the client deliberately requires it. Configure the permission checkbox/tag and retain notice history in Kit or the client's records. Forma's consentVersion and formId are not automatically sent to Kit; the native path submits the email, selected numeric permission tag and, for demo access, the configured name field. Use a different Form for demo access and newsletter when both are active.
Preserve the embedded loader's actual-Form check. After the Form renders, the optional Load control disappears and accessible ready status remains. Move focus into it only when that control still owns focus. Do not pull focus from a visitor who moved elsewhere. Keep retry, privacy information and hosted fallback usable. Kit can remove its script element after executing, so a script count alone does not establish readiness or successful subscription.
The shared signup dialog retains newsletter content on close/reopen for that page visit. Opening the demo-access purpose replaces it and resets that newsletter instance. Refreshing, leaving the page or changing language starts fresh interface state. Neither preserving nor closing the dialog saves addresses to browser storage, unloads Kit, revokes provider storage or unsubscribes an address.
Provider-only styling for embedded mode belongs in the client's Kit builder. Read the optional Clare styling example: the tested Custom CSS editor adds its UID prefix automatically, so do not duplicate that prefix. Check published output in both themes and a fresh context after allowing for provider propagation/cache delays. If a provider edit introduces a new external font, image or other resource origin, review the CSP allowance and rebuild Forma even when the Form identity is unchanged. The native Forma fields already use the template's styling; the Clare example is not needed for those fields.
Use only authorized owned recipients for real account tests. Check the response, confirmation, correct Form/name/tag, confirmed status and unsubscribe. Keep personal values and confirmation tokens out of source, logs, screenshots and handovers. A tag may remain after unsubscribe; a sending audience must require active/confirmed status and appropriate permission, not tag membership alone. Report only journeys actually tested, including any unresolved provider challenge, blocked-script, translated-provider or delivery checks.
Translate dialog.nameError, dialog.emailError, dialog.kitFormNote, dialog.kitSuccessDescription and all newsletter fields in both dictionaries. Kit feedback additionally uses newsletter.nativeNotice, submitPendingLabel, requestReceivedMessage, requestUnknownMessage, requestBusyMessage, submissionErrorMessage and guardTitle. Update the complete German replacement example when changing required fields. Local enhanced forms use native validity with translated inline messages, invalid-field descriptions and focus on the first invalid field. Preserve spaces-only name rejection, required constraints, themed checkbox focus and forced-colors fallback. Endpoint mode retains native validation/POST without JavaScript; preview and native newsletter controls stay disabled, while the hosted Kit fallback remains available for native signup. Embedded Kit validation remains provider-owned.
Never put private API keys, webhook credentials or passwords in site.ts, public/ or NEXT_PUBLIC_ values. Cookie preferences control optional theme/language memory; they do not unsubscribe emails, supply a third-party consent platform or certify legally sufficient consent records. Browser validation improves usability and does not replace receiver validation or consent-record responsibilities.
Preserve accessibility and performance deliberately
Use semantic headings/links, useful labels and quiet decorative graphics. Preserve dialog Escape/close/focus return, nested-confirmation behavior, mobile-menu closure and visible keyboard operation. Test at narrow widths and 200% zoom rather than hiding overflowing text or controls. Check color contrast after changing both palettes; a pleasing screenshot is not a contrast measurement.
Measure production output after a relevant change. Keep asset dimensions, a local appropriately licensed font, selective media priority and lazy later images. Do not preload every asset or add animation/player libraries for small effects. Review the existing offscreen-section rendering/print rules after substantial content changes; these rules defer rendering, not the application's hydration.
Compare repeated runs under the same URL/build, browser, viewport, network/CPU settings and cache conditions. Retain slower runs and warnings. Inspect document latency, media discovery/transfer, initial layout and main-thread work before selecting a fix. Separate code evidence from a network/CDN hypothesis. A Lighthouse score and loading-time TBT do not establish field INP or real-user 75th-percentile Core Web Vitals; do not promise a score or claim an unmeasured pass.
Use these launch targets: LCP ≤ 2.5 seconds, INP ≤ 200 milliseconds and CLS ≤ 0.1, assessed at the 75th percentile of real visits, separately for mobile and desktop. All three need suitable field evidence to claim a Core Web Vitals pass. When a new site lacks enough field data, report that gap and use repeatable lab loading, layout and interaction checks to find issues. Do not substitute TBT for INP, combine device groups to hide a failing group or declare the target met from a single favorable run. Fix proven regressions while preserving visuals, features, accessibility and native/no-JavaScript fallback.
Use Launch checklist for the complete manual scope. Automatic checks and accessibility scans do not replace the actual keyboard, responsive, no-JavaScript or provider journeys you claim to support.
Preserve the generated security policy
Read HSTS and Content Security Policy before adding scripts, services or hosting rules. src/config/security.ts owns HSTS settings and reviewed additional CSP origins. The build hashes inline scripts in the actual exported HTML and creates matching out/forma-security.json and out/_headers; do not maintain hand-copied hashes, insert a per-request nonce or switch the template to server rendering to configure these headers.
Keep the build, preview and security helpers together when applying updates. Run npm run security:check after the production build; it compares the export and policy artifacts with current settings. The local preview checks requested HTML against the manifest and applies its document-specific CSP, rather than checking edited source settings or all of _headers at startup. Its ordinary HTTP loopback responses intentionally omit HSTS. A live HTTPS host needs its own response-header configuration and verification. The default production HSTS value is 30 days without subdomain coverage or preload; do not enable broader coverage without checking all affected hosts and the client's brief.
Enabled Kit modes and the endpoint form destination contribute the supported integration permissions automatically. Google reCAPTCHA permissions are path-limited and conditional; custom Kit fonts, analytics and other added services need deliberate review. Configured external image/media origins are derived from actual URLs, including dark variants, avatars, posters and caption files; the policy does not permit all HTTPS images or media. Add an additional service only after reviewing its actual resource destinations, using exact HTTPS origins in the relevant additionalSources arrays: script, connect, frame, style, font, form, image and media. Never clear a browser error by adding script unsafe-inline, unsafe-eval or broad wildcard sources. Inline styles remain supported deliberately, while workers are blocked; permitted third-party scripts are still trusted code with page access. A policy allowance does not grant provider approval or marketing permission, and does not secure a receiving backend.
After changing content, collection modes, security settings or scripts, rebuild and test both languages, theme/preference startup, navigation, video and the configured forms under the generated policy. A provider's verification/fallback journey needs its own authorized test; synthetic checks do not establish real confirmation or delivery. Publish HTML, assets and headers from the same build, account for existing additional CSP headers and CDN script transformations, and inspect the final HTTPS responses. COOP and Trusted Types enforcement are outside this update's scope.
Validate and prepare delivery
Run commands in the project folder. On Windows, substitute npm.cmd if PowerShell blocks npm.ps1; do not change execution policy as a setup shortcut.
npm run languages:check
npm run docs
npm run check
npm run start
Generate docs when their Markdown changes; first format only the files you edited, using the installed formatter, and review the diff. For example, if those three source files changed, run node node_modules/prettier/bin/prettier.cjs --write src/config/site.ts src/content/primary.ts src/content/secondary.ts. Adapt that explicit file list to your actual changes. npm run format formats the whole editable project under its ignore rules, so it is broader than a scoped agent edit. The complete check runs languages/content, generated docs, formatting, ESLint, TypeScript, tests and a production build. Do not present this example command list as a passed result. Stop your own dev server before production preview because both default to port 3100. Preview the built output over HTTP; source edits need another build.
Before publishing, set the real public HTTPS origin as NEXT_PUBLIC_SITE_URL beside package.json in .env.local or in the build environment. Keep private environment files out of delivery. Rebuild and inspect both language pages, canonical/alternate/social URLs, sitemap, robots, favicon, font and missing-page status. Upload the contents of out/ to the approved static root, retaining all legal notices. Deployment under a subdirectory requires separate configuration/testing. Read Build and deploy.
npm run package is optional for a licensed website handover. It copies the current built export; it does not neutralize branding/metadata or prove a fresh build. Preserve the applicable licence and notices. Do not redistribute the original template as another template/source product. Do not overwrite a frozen existing ZIP; a new package release needs a deliberate version decision and matching manifest/lockfile versions.
Obtain any missing authorization for the concrete target/action before publishing, sending mail or changing an external system. General customization or deployment authorization never approves a purchase, chargeable trial, plan upgrade or increased billable usage. State the exact provider, action, quantity, term, total/currency, recurring charges and payment method and obtain direct approval before spending.
Give the client a useful handover
Finish with the implemented result and its limits, not a transcript of tools:
- Identify the configured brand, language pair, preview mode, conversion destinations and newsletter behavior.
- List the main editable files and any remaining placeholders or client decisions.
- State the exact checks actually run and their results; distinguish unrun browser/provider/hosting/performance checks from passed ones.
- Explain how to start/edit/rebuild the project, where the final export is and what the approved publication step requires.
- Preserve private source/environment ownership and provide the required licence/font/runtime notices. Do not include credentials, personal test data, internal notes or unrelated projects in the public export.
Leave the client with a maintainable website they can understand. Do not claim account creation, authentication, payment processing, email delivery, consent-record persistence or legal/accessibility/performance certification merely because the page displays the corresponding words.