DEV Community: Keo Fung | FormLM

When Your AI Duplicates Every Field: A Story About Idempotency

Keo Fung | FormLM — Fri, 24 Jul 2026 08:55:00 +0000

I had a form with 12 fields. Then my Claude Desktop session crashed. I restarted it, asked Claude to "continue building the form," and ended up with 24 fields. Half of them were exact duplicates — same IDs, same titles, same types. The form rendered with two "Email" fields, two "Name" fields, and two of every radio button.

This is the story of how field_add isn't idempotent, why that matters when an AI is driving, and the pattern I adopted to fix it.

Update (v0.2.0): The field_add command is now accessed via formlm_exec. The formlm_generate smart pipeline eliminates this entire class of problem — the server-side AssessAgent handles field creation atomically and idempotently. The find-before-add pattern remains useful when using formlm_exec for manual field operations.

What Happened

Here's the sequence:

I asked Claude to build a customer satisfaction survey with 12 fields
Claude created the app, added 8 fields, and then the session timed out
I started a new session and said "continue building the customer satisfaction survey"
Claude called app_list, found the existing app, and started adding fields again
It re-added all 12 fields — including the 8 that were already there

The result was a form with 20 fields total (8 original + 12 duplicate). The duplicate field IDs were auto-suffixed by the server (email became email, email_1, email_2...). To the user filling out the form, it looked like the form had been designed by someone who really, really wanted your email address.

Why `field_add` Isn't Idempotent

Here's the thing about field_add — it's a create operation, not an upsert. If you call it twice with the same field ID, the server creates two fields. The field ID isn't a unique constraint; it's a label.

Looking at the MCP tool definition:

server.tool('field_add', 'Add a new field', {
  appId: z.string().describe('App ID'),
  id: z.string().describe('Field ID'),
  type: z.string().default('input').describe('Field type (default: input)'),
  title: z.string().optional().describe('Field title / question text'),
  // ...
}, async (params) => {
  let cmd = `assess form add --app ${params.appId} --id ${params.id} --type ${params.type}`;
  // ...
});

There's no check for "does this field ID already exist?" The tool just sends the add command and the server creates a new field. If a field with that ID already exists, the server either appends a suffix or creates a duplicate.

From a CLI perspective, this is fine. A human running formlm-cli field add knows whether they've already added a field. They don't need the CLI to check for them.

From an AI perspective, this is a problem. The AI doesn't remember what it did in a previous session. It doesn't check whether fields exist before adding them. It just executes the plan, and if the plan says "add 12 fields," it adds 12 fields — regardless of whether 8 of them are already there.

The Fix: Find Before Add

The pattern I now enforce is: always check before adding. Before calling field_add, call field_find to see if a field with that ID already exists:

# Step 1: Check if the field already exists
field_find --app <appId> --id email

# If the response is "field not found", proceed with add:
field_add --app <appId> --id email --type input --title "Email" --required

# If the field already exists, skip the add (or update it instead)

In practice, I instruct Claude to batch this: call field_list once to get all existing fields, then only add the ones that are missing.

# Get the current state
field_list --app <appId>
# Response: [name, email, phone, rating]

# Claude now knows which fields exist and only adds the missing ones
# It needs to add: comments, feedback_source
field_add --app <appId> --id comments --type textarea --title "Additional comments"
field_add --app <appId> --id feedback_source --type radio --options "Search:1,Social:2,Friend:3"

This is the read-before-write pattern again (same as find-then-set from the previous article), but applied to creation instead of updates.

Why Not Just Make `field_add` Idempotent?

I considered making field_add an upsert — if the field exists, update it; if not, create it. But that has its own problems:

Silent overwrites. If the AI accidentally re-adds a field with different options, the upsert would silently overwrite the existing field's options. No error, no warning — just changed data.
No explicit "create" semantics. Sometimes you want to fail if a field already exists — like when you're setting up a new form and a duplicate field ID indicates a bug in your plan.
The update path is different. Creating a field and updating a field go through different server-side validation. Merging them into one operation muddies the API.

So I kept field_add as a pure create operation and moved the idempotency check to the caller. The AI is responsible for checking before adding.

The Idempotency Wrapper

In my system prompt for Claude, I now include this instruction:

"Before adding any field, call field_list to get the current field set. Only add fields whose IDs don't already exist in the form. If a field already exists and needs changes, use field_update or field_set_property instead of field_add."

This is a soft constraint — it relies on Claude reading and following the instruction. In practice, it works about 90% of the time. The other 10%, Claude skips the field_list call and goes straight to field_add, usually when it's "in a hurry" (i.e., the context window is getting full and it's trying to save tokens).

The hard constraint would be making the server reject duplicate field IDs. But as I mentioned, field IDs aren't unique constraints — they're labels. Making them unique would break existing forms that intentionally use the same ID across different field types (don't ask).

The Deeper Lesson: AI Agents Need Idempotency Everywhere

This isn't just about field_add. Every create operation in an AI-accessible API needs an idempotency story:

app_create — what if the AI creates the same app twice? Currently it creates two apps with the same name. I should probably check for existing apps with the same name before creating.
share_publish — what if the AI publishes the same form twice? Currently it's idempotent (publishing an already-published form is a no-op). This one got it right.
auth_login — what if the AI logs in twice? Currently it overwrites the existing token. Also fine.

The pattern I now follow for any create operation:

Check-first: Provide a read operation that lets the AI verify whether the resource already exists
Document it: In the schema description, explicitly say "Check with [X] before calling this to avoid duplicates"
Soft idempotency: If the operation is called with the same parameters, make it a no-op rather than creating a duplicate, where possible

The Cleanup

Cleaning up the duplicated form was painful. I had to:

Call field_list to see all 20 fields
Identify the duplicates (fields with suffixed IDs like email_1, email_2)
Call field_remove for each duplicate
Re-order the remaining fields with field_move

Twelve field_remove calls. Each one was a round-trip to the server. It took longer to clean up than it took to create the mess.

After that experience, I wrote a cleanup script that detects and removes duplicate fields by comparing titles and types. It's not part of the CLI — it's a one-off shell script I keep in my snippets folder. If this happens often enough, I might add a field_dedup command to the CLI. But for now, the find-before-add pattern is enough.

The formlm-cli MCP server documents the find-before-add pattern in tool descriptions. Open source at github.com/formlm/cli — try the platform at formlm.me.

The Boolean Trap: When Your AI Literally Cannot Say "False"

Keo Fung | FormLM — Thu, 23 Jul 2026 09:31:48 +0000

This one took me two hours to debug. Two hours of staring at a form where every single field was marked "required" — even the ones I'd explicitly told Claude to make optional. The AI wasn't ignoring me. It physically could not express what I was asking for.

Here's how a TypeScript boolean type and a commander.js flag convention teamed up to make false an impossible value.

Update (v0.2.0): The field_add tool is now accessed via formlm_exec (direct command execution). The boolean trap and its fix (normBool() + !== undefined checks) remain fully applicable. The formlm_generate smart pipeline bypasses this issue entirely by letting the server-side AssessAgent handle field creation.

The Setup

I was building a customer feedback form. Most fields were required (name, email, rating), but a few were optional — a text field for "additional comments" and a radio for "how did you hear about us." Standard stuff.

I told Claude:

"Create a feedback form. Name and email are required. The comments field is optional. The 'how did you hear about us' field is optional."

Claude went to work. It created the app, added the name and email fields with required: true, and then... this happened.

What Claude Did

For the required fields, Claude called field_add with required: true. Clean, correct:

{
  "appId": "app_abc123",
  "id": "email",
  "type": "input",
  "title": "Email address",
  "required": true
}

For the optional fields, Claude called field_add and simply... didn't include the required parameter:

{
  "appId": "app_abc123",
  "id": "comments",
  "type": "textarea",
  "title": "Additional comments"
  // no "required" field at all
}

On the surface, this looks fine. The field was created. The form rendered. But every single field — including the "optional" ones — showed up with a red asterisk. Every field was required.

The Root Cause

Here's the thing. In the MCP schema, required is defined as:

required: z.boolean().optional().describe('Mark as required'),

z.boolean().optional() means the parameter accepts true, false, or undefined (not provided). When Claude wants to make a field optional, it has two options:

Pass required: false — explicitly set it to false
Don't pass required at all — leave it undefined

Claude chose option 2. And here's where the problem starts.

When required is undefined, the CLI builds the command string like this:

const required = normBool(opts.required);
if (required !== undefined) cmd += ` --required=${required}`;

If required is undefined, the --required flag is never added to the command. The server receives the assess form add command without any --required parameter.

And the server's default behavior? When no --required flag is present, it defaults to true.

So "I didn't say required" became "required by default." Every optional field silently became mandatory.

Why Claude Didn't Pass `false`

I tested this. I explicitly told Claude: "Make the comments field NOT required. Set required to false."

Claude tried. It passed required: false in the MCP parameters. But here's what happened on the CLI side:

The normBool function in field.ts handles three cases:

function normBool(v: unknown): boolean | undefined {
  if (v === undefined) return undefined;
  if (typeof v === 'boolean') return v;
  return v === 'true' || v === '1';
}

When the MCP server receives required: false (a proper boolean), it passes it through and builds:

assess form add --app <appId> --id comments --required=false --json

This should work. And in my local testing, it did work. But in Claude Desktop, something weirder happened — Claude kept omitting the parameter instead of passing false. When I checked the conversation log, Claude's reasoning was:

"The field is optional, so I don't need to set required."

Claude was treating "optional" as "don't set the flag" rather than "set the flag to false." From a human perspective, that makes sense — if something is optional, you don't mention it. But from a programmatic perspective, "not setting it" and "setting it to false" are different operations when the default is true.

The Real Problem: Defaults That Bite

The deeper issue is the server-side default. When field_add is called without --required, the server treats it as required=true. That's a reasonable default for form fields — most fields in most forms are required.

But it creates a trap: the only way to make a field optional is to explicitly pass required=false. And AI agents are bad at explicitly passing false for boolean parameters because:

They've been trained on tons of code where "optional" means "don't pass it"
The schema says .optional(), which reinforces the "just don't include it" pattern
Passing false feels redundant when the field isn't required — why state the obvious?

The result is a silent data corruption: fields that should be optional become required, and nobody notices until a user complains that they can't submit the form without filling in the "optional" comments field.

The Fix

I tried three approaches before settling on one.

Attempt 1: Change the server default. Make required default to false when not specified. This fixed the AI problem but broke every existing form build — now Claude had to explicitly pass required: true for every required field, and it kept forgetting. Same problem, opposite direction.

Attempt 2: Remove the default entirely. Force the parameter to be required. This made the schema non-optional, which meant Claude had to always pass required: true or required: false. It worked, but it made every field_add call noisier. And for fields where required-ness doesn't matter (like a description field), it was confusing.

Attempt 3: Fix the schema description. This is what I went with. I changed the .describe() string to be explicit about the default:

required: z.boolean().optional().describe('Mark as required. Defaults to true if omitted. To make a field optional, explicitly set this to false.'),

That one sentence — "To make a field optional, explicitly set this to false" — was the instruction Claude needed. After this change, Claude started passing required: false for optional fields instead of omitting the parameter.

It's a band-aid, not a real fix. The real fix is making the server's default behavior match the common-sense expectation: if you don't specify required, the field should be optional, not required. But changing a default that existing forms depend on is a migration I'm not ready to do.

The `normBool` Safety Net

The normBool function itself is fine — it correctly handles true, false, the string "false", and undefined. The problem was never in the function. It was in the gap between:

What the schema says (.optional() → "you can skip this")
What the server does (defaults to true when skipped)
What the AI assumes (skipping = not required)

Three layers, each reasonable in isolation, combine to produce a bug where "optional" silently means "required."

The Pattern I Now Follow

For any boolean parameter where false is a meaningful value, I:

Make the description explicit about the default. If the default is true, say so. If omitting it means true, say that explicitly.
Test the false path. Every boolean parameter gets tested with true, false, and omitted. The omitted case is the one that bites you.
Don't rely on "omit means false." In a world where an AI is reading your schema and making decisions, the safest approach is to make every state explicit. If false is a valid and important value, make the parameter required, not optional.

The boolean trap isn't unique to my CLI. It's a general problem with AI-accessible APIs: optional booleans with non-null defaults are a footgun. The AI's instinct is to omit rather than to explicitly negate, and if your default doesn't match "omitted = the safe option," you'll get silent bugs.

The formlm-cli MCP server has explicit descriptions for all boolean parameters. Open source at github.com/formlm/cli — try the platform at formlm.me.

MCP Tools, One Weekend: Stress-Testing an AI-Accessible Form Builder

Keo Fung | FormLM — Wed, 22 Jul 2026 09:02:27 +0000

I have 20 MCP tools in formlm-cli. On paper they cover the full lifecycle: auth, app management, field CRUD, and sharing. But "covers the lifecycle" and "actually works when you throw a complex real-world task at an AI agent" are different things.

Update (v0.2.0): The architecture has been redesigned from 20 flat tools to 6 layered tools + 6 knowledge resources. The formlm_generate tool now handles app creation + field generation + scoring + publishing in a single call via the server-side AssessAgent pipeline. The formlm_exec tool provides direct access to all whitelisted CLI commands. The individual tools described in this article (app_create, field_add, share_publish, etc.) are now accessed through formlm_exec. The "current app" state issue mentioned below has been fixed via server-side SessionContext.

So I spent a weekend trying to build a genuinely complex form — an enterprise onboarding assessment with multiple field types, conditional logic, and scoring — using only Claude Desktop and the MCP tools. Here's what worked, what didn't, and what surprised me.

The Task

Build an "Enterprise Onboarding Readiness Assessment" with:

5 text/input fields (employee name, department, role, manager, start date)
2 radio fields with scoring (technical proficiency, communication level)
3 scale fields (1-10) for confidence dimensions
1 textarea for open feedback
Field ordering (specific sequence)
Published with a shareable URL

Not the most complex form in the world, but complex enough to exercise most of the toolset. I wanted to hit at least 15 of the 20 tools in a single session.

Saturday: Building the Form

Tools used: app_create, field_schema, field_config, field_add (×11)

I started with a prompt describing the full form. Claude's first move was app_create — clean, no issues.

Then it did something I've come to expect: it called field_schema before adding any fields. It wanted to see the available types. The response listed input, textarea, radio, scale, date, and others. Claude picked date for the start date field instead of input, which was smart — it means the form will show a date picker instead of a text box.

The field_config --type radio call came next. Claude wanted to know what properties a radio field accepts. The response showed options (comma-separated with label:score format) and required. Claude then added the radio fields with properly scored options:

field_add --app <appId> --id tech --type radio --options "Beginner:1,Intermediate:2,Advanced:3,Expert:4" --required
field_add --app <appId> --id comm --type radio --options "Needs improvement:1,Meets expectations:2,Exceeds expectations:3" --required

The scale fields came next:

field_add --app <appId> --id conf_tools --type scale --min 1 --max 10 --title "How confident are you with the tools?"
field_add --app <appId> --id conf_team --type scale --min 1 --max 10 --title "How confident are you with your team?"
field_add --app <appId> --id conf_process --type scale --min 1 --max 10 --title "How confident are you with the processes?"

Eleven field_add calls. All succeeded. No issues.

Tools used: field_list, field_move

Here's where I hit my first snag. The fields were added in the right order, but I wanted the textarea (open feedback) to appear last, after the scale fields. Claude had added it in the middle.

Claude called field_list to see the current ordering:

field_list --app <appId>
# Response: [name, department, role, manager, start_date, tech, comm, conf_tools, conf_team, conf_process, feedback]

Then field_move:

field_move --app <appId> --id feedback --pos 11

Worked. The feedback field moved to the end.

This was a good test of field_move — it's a tool that seems simple but has edge cases. What if the position is out of range? What if the field doesn't exist? I tested both scenarios manually afterward. Out-of-range position silently clamps to the end. Non-existent field ID returns an error. Reasonable behavior.

Tools used: field_find

I asked Claude to check the scoring on the tech field. It called field_find:

field_find --app <appId> --id tech
# Response: { id: "tech", type: "radio", options: [{label: "Beginner", score: 1}, ...] }

The find response was clean and structured. Claude could read the scores and confirm they were correct.

One thing I noticed: the field_find response includes a lot of metadata — field type, validation rules, placeholder text, etc. For a human reading the JSON, it's fine. For an AI parsing it, the extra fields add tokens but don't cause confusion. Claude had no trouble extracting what it needed.

Sunday: Publishing and Cleanup

Tools used: share_publish, share_url, share_query

Publishing was the easiest part. One share_publish call, one share_url call. Done.

I tested share_query to check the publish status:

share_query --app <appId>
# Response: { published: true, formType: "all", formPerm: 1, formDay: 3650000 }

The formDay: 3650000 is the "never expires" default I hardcoded in the MCP tool. That's intentional — the AI doesn't need to decide expiry dates for public forms. Safe defaults matter.

Tools used: share_unpublish, app_remove

After testing, I unpublished and deleted the app to clean up. Both worked without issue. The app_remove is permanent — no confirmation prompt, no undo. That's slightly terrifying for an AI-accessible tool, but the whitelist on the backend would block a clear command (which deletes ALL apps). Individual deletes are safe as long as the AI targets the right app ID.

What I Didn't Use

Out of 20 tools, I used 11 in this session:

auth_login, auth_status — skipped, I was already logged in
app_list, app_get, app_update — didn't need to list or update apps
field_update, field_remove, field_set_property — didn't need to modify or remove fields

That's fine. Not every form build needs all 20 tools. The test was whether the tools I did need worked correctly when chained together by an AI agent. They did.

What Broke

Two things went wrong over the weekend:

1. Claude forgot the app ID mid-session. After adding about eight fields, Claude lost track of the app ID it had created at the start. It tried to use field_add without the --app parameter. The error message was clear ("Missing required option: --app"), and Claude recovered by calling app_list to find the app. But it cost three extra API calls and broke the flow.

Fix idea: The MCP server could maintain a "current app" state, similar to how git remembers your current branch. app_get could set the active app, and subsequent field commands could default to it.

Update (v0.2.0): This has been implemented. The server-side SessionContext now maintains the current app ID. When an app is created or used, the session automatically tracks it, and subsequent commands default to the active app.

2. The --filter parameter on field_find returned too many results. When Claude searched for "confidence" (trying to find the scale fields), the filter matched on field titles and returned all three confidence fields plus the textarea (which mentioned "confident" in its placeholder text). Not wrong, but noisier than expected. Claude handled it by reading the response and picking the right fields, but the filter could be more precise — maybe matching on field ID or key instead of title text.

The Scorecard

Tool Category	Tools	Used This Weekend	Worked?
Auth	2	0	N/A (already logged in)
App	5	2 (create, delete)	✅
Field	9	9 (all of them, across the session)	✅ with minor issues
Share	4	4 (all of them)	✅
Total	20	15	15/15 passed

Every tool I used worked. The issues were with Claude's context management (forgetting the app ID) and search precision (filter returning too many results), not with the tools themselves.

The takeaway: 20 tools was enough coverage for a complex form build. In v0.2.0, the architecture was streamlined to 6 layered tools — formlm_generate handles the entire build in one call, while formlm_exec provides direct access for fine-grained control. The gaps aren't in the toolset — they're in the workflow ergonomics (state management, search precision). Those are fixable without adding new tools.

All MCP tools are available in formlm-cli. Open source at github.com/formlm/cli — try the platform at formlm.me.

The find-then-set Pattern: How I Stopped My AI Agent From Breaking Fields

Keo Fung | FormLM — Tue, 21 Jul 2026 10:38:08 +0000

It started with a radio field that lost its scores. Claude was trying to update one option's label on a question, and somehow every score on that field vanished. The form still worked — it just stopped scoring anything. Nobody noticed until a respondent completed the assessment and got a zero.

Here's how it happened, and the pattern I adopted to make sure it never happens again.

Update (v0.2.0): The individual field tools (field_find, field_set_property, field_update) are now accessed via formlm_exec — the direct command execution tool. The find-then-set pattern remains the recommended approach for fine-grained field updates. For bulk changes, formlm_modify wraps the server-side BuilderAgent pipeline which handles field updates safely.

The Incident

I had a radio field with three options:

field: q3
type: radio
options:
  - "Satisfied:3"
  - "Neutral:2"
  - "Unsatisfied:1"

I asked Claude: "Change the 'Neutral' label to 'Okay' on field q3."

Claude called field_update:

field_update --app <appId> --id q3 --options "Satisfied:3,Okay:2,Unsatisfied:1"

Looks fine, right? It passed all three options, keeping the scores intact. The label changed. The scores stayed. Problem solved.

Except that's not what happened every time. In a different session, Claude decided to be "efficient" and only pass the option it wanted to change:

field_update --app <appId> --id q3 --options "Okay:2"

The --options parameter in field_update replaces the entire options list. It doesn't merge. So that command wiped out "Satisfied:3" and "Unsatisfied:1" and left the field with a single option: "Okay:2."

The form now had one radio button instead of three. The other two options were gone. And since the remaining option had a score of 2, every respondent who clicked it got 2 points — for a question that used to have a range of 1 to 3.

The respondent who triggered the discovery answered "Okay" on this question and nothing else — because there was nothing else to answer. They got a 2 where they should've gotten context-dependent scoring.

Why This Happened

The field_update command is documented as "Update a field." From an AI's perspective, that's a reasonable tool to use when you want to change something about a field. The schema says:

options: z.string().optional().describe('Options list — replaces existing options')

The description says "replaces existing options." That's accurate. But AI agents don't always read carefully when they're in the middle of a task. They see "update field" and "options" and they pass the option they want to change. The "replaces" part gets lost in the context window.

This isn't Claude's fault. It's a UX problem with the tool design. field_update is a blunt instrument — it replaces whatever you pass. If you only pass --options, you get a new options list. If you only pass --title, you get a new title and everything else stays. But the options parameter is particularly dangerous because it's a list — partial replacement of a list silently destroys data.

The Fix: find-then-set

I added field_set_property specifically for this scenario. Instead of replacing the whole field, it updates a single property at a precise path:

server.tool('field_set_property', 'Fine-grained field property update', {
  appId: z.string().describe('App ID'),
  id: z.string().optional().describe('Field ID'),
  key: z.string().optional().describe('Field Key'),
  property: z.string().describe('Property path (e.g. options.1.score)'),
  value: z.string().describe('Property value'),
}, async (params) => {
  let cmd = `assess form set-property --app ${params.appId}`;
  if (params.id) cmd += ` --id ${params.id}`;
  if (params.key) cmd += ` --key ${params.key}`;
  cmd += ` --property ${params.property} --value "${params.value}"`;
  const r = await execCommand(cmd);
  // ...
});

Now, to change the "Neutral" label without touching scores, the AI uses:

field_set_property --app <appId> --id q3 --property options.1.label --value "Okay"

This updates exactly one property — the label of option index 1. Nothing else changes. The scores, the other options, the field type — all untouched.

But there's a catch. The AI needs to know that option index 1 is "Neutral" before it can update it. That's where field_find comes in.

The Full Pattern

The pattern I now enforce in my prompts is: find first, then set property.

Call field_find to get the current field state
Identify the exact property path that needs changing
Call field_set_property with that precise path

# Step 1: Find the field
field_find --app <appId> --id q3

# Response includes:
# options: [
#   { label: "Satisfied", score: 3 },
#   { label: "Neutral", score: 2 },
#   { label: "Unsatisfied", score: 1 }
# ]

# Step 2: I want to change options[1].label

# Step 3: Set the property
field_set_property --app <appId> --id q3 --property options.1.label --value "Okay"

This is more API calls (find + set vs. a single update). But it's safe. The AI can't accidentally destroy data because it's only touching one property at a time, and it saw the current state before making the change.

When to Use update vs. set-property

I still use field_update for legitimate full replacements — when I actually want to replace the entire options list, or change the field type, or update multiple properties at once. The rule I follow:

Use field_update when you're replacing the entire structure of a field (new type, new options list, new title — a deliberate full replacement)
Use field_set_property when you're tweaking one thing (one option's label, one option's score, one property)

The AI needs to be told this explicitly. In my system prompt, I now include: "When changing a single property of a field, always use field_set_property with a property path. Use field_update only for full field replacement."

That instruction, combined with the find-first pattern, has eliminated the "disappearing options" bug entirely. The cost is one extra API call per update. The benefit is not silently destroying form data.

The Bigger Lesson

When you design tools for AI agents, you have to think about what happens when the AI takes you literally but incompletely. "Update the label" doesn't mean "replace the entire options list with just the new label." But if the only tool available is a blunt "update" command, that's what can happen.

Fine-grained tools (set-property) combined with a read-before-write pattern (find before set) make AI interactions safer. Not because the AI is malicious — but because partial updates on complex objects are inherently dangerous when the tool doesn't distinguish between "replace this one thing" and "replace everything."

The find-then-set pattern isn't new. It's how most database transactions work. But in the MCP world, where tools are the API and the AI is the client, it's easy to forget that your tools need the same safety patterns your database does.

The formlm-cli MCP server includes field_set_property (accessible via formlm_exec) specifically for this use case. Open source at github.com/formlm/cli — try it at formlm.me.

I Let Claude Desktop Build My Entire Assessment Form. Here's What Happened.

Keo Fung | FormLM — Tue, 21 Jul 2026 01:37:46 +0000

Series: Building an AI-Native Assessment Platform (11/20)

I've been building FormLM's CLI and MCP server for a while now. The architecture is solid, the tools are defined, the zod schemas are clean. But there's a difference between "the code works" and "watching an AI agent actually use your tools to build something real."

Last weekend I decided to stop testing in isolation and let Claude Desktop build a complete assessment form from scratch — using only the MCP tools I'd built. No hand-holding, no manual CLI commands, no editing the form in the web UI afterward. Just Claude, the MCP server, and a natural language prompt.

Here's the full timeline, including the parts where it broke.

The Setup

I'd already installed formlm-cli globally and configured it in Claude Desktop's config:

{
  "mcpServers": {
    "formlm": {
      "command": "formlm-cli",
      "args": ["mcp"]
    }
  }
}

I'd logged in via formlm-cli auth login beforehand so the token was already stored. Claude didn't need to authenticate — it could just start using the tools.

The Prompt

I gave Claude this instruction:

"Build a burnout self-assessment form. Three dimensions: exhaustion, cynicism, and professional efficacy. Use the Maslach framework. Each dimension needs 3 questions on a 1-7 Likert scale. Add one reverse-scored item for the efficacy dimension. Then publish it and give me the URL."

That's it. No field IDs, no type names, no scoring configuration details. I wanted to see if Claude could figure out the right tool calls from the schema descriptions alone.

What Claude Did (Step by Step)

Step 1: Create the app

Claude called app_create with the name "Burnout Self-Assessment" and a brief description. Got back an app ID. Straightforward.

Step 2: Check available field types

This surprised me. Before adding any fields, Claude called field_schema to see what field types were available. It didn't assume it knew the types — it checked. The response listed all supported types including scale, radio, input, textarea, etc.

Then it called field_config --type scale to see what properties a scale field accepts. It found min, max, and the scoring options.

This was the moment I realized the schema descriptions mattered more than I thought. Claude was reading them like documentation. The .describe() strings on every zod field weren't just metadata — they were the instructions the AI followed.

Step 3: Add the exhaustion dimension (3 fields)

Claude added three scale fields for the exhaustion dimension:

field_add: id=ex1, type=scale, title="I feel emotionally drained by my work", min=1, max=7
field_add: id=ex2, type=scale, title="I feel used up at the end of the workday", min=1, max=7
field_add: id=ex3, type=scale, title="I feel fatigued when I get up in the morning and have to face another day", min=1, max=7

So far so good. The field IDs were sensible (ex1, ex2, ex3). The titles were actual Maslach Burnout Inventory items, not made-up questions. Claude knew the framework.

Step 4: Add cynicism and efficacy

Same pattern for cynicism (cy1, cy2, cy3) and professional efficacy (pe1, pe2, pe3).

Here's where it got interesting. For the efficacy dimension, I'd asked for a reverse-scored item. Claude added:

field_add: id=pe3, type=scale, title="I do NOT feel I am making an effective contribution to my organization", min=1, max=7

The "NOT" was Claude's way of making a reverse-scored item — by phrasing the question negatively so that a high score indicates low efficacy. Not how I'd implement reverse scoring (I'd use the --negFields mechanism in the scale configuration), but for a form-only build without scale config, it was a reasonable approach.

Step 5: Publish

Claude called share_publish with the app ID, then share_url to get the fill-in URL. The whole thing came back as a link.

Total time: about 90 seconds. Nine fields across three dimensions, published, with a live URL.

Where It Got Weird

The form worked. People could fill it out. But there were a few things that made me realize the tools weren't quite enough on their own.

No dimensional grouping. Claude added nine fields, but they were just nine individual scale questions. There was no "dimension" concept in the form — that lives in the Scale module, which the MCP server doesn't expose yet. So the form collected answers but couldn't compute dimension scores. That's a gap I need to fill.

No scoring logic. Even if dimensions were configured, the MCP tools don't include scale configuration commands (by design — those are in the whitelist's blocked list because they're administrative). So the form was a data collection tool, not an assessment engine. To get scoring, I'd need to configure the Scale module separately.

The reverse-scored item was textual, not structural. Claude handled reverse scoring by writing a negatively-phrased question. That works for data collection but doesn't tell the scoring engine to invert the score. The real fix is the --negFields parameter in scale configuration — but that's not exposed via MCP.

What I Learned

The MCP tools are good at form construction. Claude figured out the right field types, the right scale ranges, the right question wording — all from the schema descriptions. The .describe() strings did their job.

But form construction is only the first 20% of an assessment. The other 80% — dimensional scoring, tier assignment, report generation — lives in modules the MCP server doesn't expose. That's intentional (security), but it means an AI agent can build the input form but not the assessment logic.

My next step: figure out how to safely expose scale configuration to the MCP server without opening up the administrative commands that shouldn't be AI-accessible. The whitelist exists for a reason, but there's a middle ground between "AI can add fields" and "AI can reconfigure scoring rules."

For now, the workflow is: Claude builds the form, I configure the scoring by hand. That's still way faster than building the whole thing manually. But it's not the fully AI-driven assessment pipeline I want it to be.

Still — watching Claude build a complete, publishable form in 90 seconds from a one-sentence prompt was a moment. The tools work. The schemas work. There's just more pipeline to expose.

This is part of a series on building AI-native tooling for FormLM. The CLI and MCP server are open source — check them out at github.com/formlm/cli or try the platform at formlm.me.

[10/10]PDF Rendering War: SVG-to-PNG Conversion, Emoji Font Routing, and the iText NPE

Keo Fung | FormLM — Tue, 21 Jul 2026 01:36:46 +0000

Series: Building a Modular Assessment Engine (10/10)

The final boss of this project: PDF rendering. The report module generates HTML, which iText converts to PDF. In theory, HTML → PDF is straightforward. In practice, it's a warzone of SVG crashes, emoji invisibility, and font routing nightmares. This post covers the three rendering battles and how each was won.

Battle 1: The SVG NPE That Crashed Every Report

The Bug

Reports with charts (radar charts, bar charts) would crash during PDF generation with:

com.itextpdf.kernel.PdfException: Cannot convert PdfArray to float array.
    at com.itextpdf.kernel.pdf.PdfArray.toFloatArray(...)
    at com.itextpdf.svg.converter.SvgConverter.drawToPdf(...)

The NPE occurred in iText's SVG renderer (Batik-based) when it tried to parse SVG path data. The crash was total — no PDF was produced. The user saw "Report generation failed."

The Root Cause

The chart widgets generated SVG as data:image/svg+xml;base64,... URLs embedded in <img> tags. This works fine in browsers. But iText's SVG renderer has known issues with:

Complex <path> d attributes — Batik's PdfArray.toFloatArray() fails on certain path command sequences
CSS-in-SVG attributes — iText doesn't fully support CSS properties on SVG elements
<text> with text-anchor — partially supported, causes PdfNumber parsing errors

Four different widget types were affected:

ChartWidget (general charts)
FieldChartWidget (per-field charts)
ScaleChartWidget (dimension score charts)
TrainExpertWidget (expert QR code widget)

The Fix: SVG → PNG Conversion

Instead of feeding SVG to iText's fragile renderer, convert SVG to PNG before PDF generation:

// In WidgetEntity.toHtml()
if (context.isForPdf()) {
    // PDF mode: convert SVG to PNG data URL
    String pngDataUrl = SvgToPngConverter.convertToPngDataUrl(svgContent);
    return "<img src=\"" + pngDataUrl + "\" />";
} else {
    // Browser mode: keep SVG as-is
    return "<img src=\"data:image/svg+xml;base64," 
           + Base64.encode(svgContent.getBytes()) + "\" />";
}

The context.isForPdf() flag is set by the report engine when generating PDFs. Every widget that produces SVG checks this flag and routes to the PNG converter.

The SvgToPngConverter

The converter uses Batik (the same library iText uses internally, but in standalone mode):

public static String convertToPngDataUrl(String svgContent) {
    // Parse SVG with Batik
    SAXSVGDocumentFactory factory = new SAXSVGDocumentFactory(...);
    SVGDocument doc = factory.createSVG(null, new StringReader(svgContent));

    // Render to BufferedImage
    SVGConverter converter = new SVGConverter();
    converter.setDestinationType(DestinationType.PNG);
    // ... configure dimensions from viewBox

    // Convert to base64 data URL
    ByteArrayOutputStream baos = new ByteArrayOutputStream();
    ImageIO.write(bufferedImage, "PNG", baos);
    return "data:image/png;base64," + Base64.encode(baos.toByteArray());
}

The key insight: Batik standalone (for PNG conversion) is more stable than Batik embedded in iText (for direct SVG rendering). The same SVG that crashes iText's PdfArray parser renders fine as a standalone PNG.

The viewBox Dimension Bug

But the PNG converter had its own bug. SVGs specify their dimensions through viewBox (e.g., viewBox="0 0 280 64"). The converter was ignoring viewBox and using default full-page dimensions:

SVG viewBox: 280×64 (wide and short)
PNG output:  1024×768 (default, wrong aspect ratio)
→ Chart renders as a tiny strip in the middle of a huge transparent PNG
→ PDF shows a microscopic chart

The fix: extract width and height from viewBox and use them for PNG dimensions:

// Parse viewBox="minX minY width height"
Pattern vbPattern = Pattern.compile("viewBox\\s*=\\s*['\"]([^'\"]+)['\"]");
Matcher m = vbPattern.matcher(svgContent);
if (m.find()) {
    String[] parts = m.group(1).split("\\s+");
    float vbWidth = Float.parseFloat(parts[2]);
    float vbHeight = Float.parseFloat(parts[3]);
    // Use viewBox dimensions, scaled up for resolution
    converter.setWidth(vbWidth * 2);   // 2x for retina-quality PNG
    converter.setHeight(vbHeight * 2);
}

Battle 2: Emoji Rendering in PDF

The Bug

The report HTML contains emoji — 🎉 in congratulations, 📊 in chart titles, ✅ in checklists. In the browser, these render fine. In the PDF, they show as blank squares (tofu) or disappear entirely.

The Root Cause

iText uses font registration to render text. The default fonts (Helvetica, Times-Roman) don't include emoji glyphs. When iText encounters an emoji codepoint, it looks for a font that covers it, finds none, and renders nothing.

The Font Routing Problem

The solution sounds simple: register an emoji font (like Noto Color Emoji or Apple Color Emoji). But it's not that simple because:

Color emoji fonts (Noto Color Emoji, Apple Color Emoji) use bitmap/COLR tables. iText's font engine doesn't fully support color emoji — it renders them as monochrome or not at all.
Monochrome emoji fonts (Symbola, DejaVu Sans) cover emoji codepoints but render them as simple black-and-white symbols. Better than nothing, but not great.
Font fallback chains — iText needs explicit font registration for each Unicode range. There's no automatic fallback like browsers have.

The Solution: Font Coverage Matrix

PdfFontFactory.register("/fonts/NotoSans-Regular.ttf", "noto-sans");
PdfFontFactory.register("/fonts/Symbola.ttf", "symbola-emoji");
// ... other fonts

// Font routing: for each character, find a font that has it
public PdfFont getFontForChar(char c) {
    if (Character.isSupplementaryCodePoint(c)) {
        // Emoji range (U+1F000-U+1FAFF, U+2600-U+27BF)
        if (isEmojiCodepoint(c)) {
            return symbolaEmojiFont;  // Monochrome but visible
        }
    }
    return defaultFont;  // Noto Sans for regular text
}

The approach is imperfect — emoji render as black-and-white symbols, not color. But they're visible, which is the minimum acceptable outcome. A blank square where "🎉" should be is worse than a monochrome party popper.

The `setSplitCharacter` Fix

Even with the right font registered, iText would sometimes split emoji codepoints across lines, corrupting them. Emoji are often represented as surrogate pairs (two char values). iText's default splitter treats each char independently, splitting surrogate pairs.

The fix: a custom ISplitCharacter that doesn't split surrogate pairs:

public class EmojiSafeSplitCharacter implements ISplitCharacter {
    @Override
    public boolean isSplitCharacter(int start, int current, int end, 
                                     char[] cc, PdfChunk[] ck) {
        // Don't split between surrogate pairs
        if (Character.isHighSurrogate(cc[current]) 
            && current + 1 < cc.length 
            && Character.isLowSurrogate(cc[current + 1])) {
            return false;
        }
        return defaultSplit.isSplitCharacter(start, current, end, cc, ck);
    }
}

Battle 3: Background Image SVG Compatibility

The Bug

Report pages with SVG background images would render with a black opaque rectangle covering the entire page in PDF mode. The content underneath was hidden.

The Root Cause

The SVG backgrounds used <rect> elements with fill for the background color. In browser mode, these render as semi-transparent overlays. In iText's SVG renderer, fill-opacity and rgba() opacity are partially supported — the opacity is ignored, and the fill renders as fully opaque.

So fill="rgba(0,0,0,0.6)" (semi-transparent dark overlay) becomes fill="rgb(0,0,0)" (solid black) in PDF.

The Fix: Background SVG Cleaning

A "washing" step before PDF rendering that removes or adjusts opacity-incompatible elements:

public static String cleanSvgForPdf(String svg) {
    // Remove <rect> background elements (they render as opaque in PDF)
    svg = svg.replaceAll(
        "<rect[^>]*fill=\"rgba\\([^)]+\\)\"[^>]*/>", "");

    // Replace rgba() with solid color + reduced opacity attribute
    // (iText handles opacity attribute better than rgba())

    // Remove CSS background-image references
    svg = svg.replaceAll(
        "background-image:\\s*url\\([^)]+\\)", "");

    return svg;
}

This runs before the SVG→PNG conversion, ensuring the background renders correctly.

The Batik Namespace Requirement

One more SVG gotcha: Batik requires the SVG to declare the standard namespace:

<!-- Without namespace: Batik throws "not a valid SVG document" -->
<svg viewBox="0 0 280 64">
  ...
</svg>

<!-- With namespace: works -->
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 280 64">
  ...
</svg>

The fix: ensure all generated SVG includes xmlns="http://www.w3.org/2000/svg". The SKILL.md for the connect module now includes this as a P0 rule.

The forPdf Context Flag

All these fixes hang off one flag: context.isForPdf(). This flag flows through the entire rendering pipeline:

public class RenderContext {
    private boolean forPdf;

    public boolean isForPdf() { return forPdf; }

    // In PDF generation:
    context.setForPdf(true);
    String html = widget.toHtml(context);  // Widgets check isForPdf()
    // → SVG becomes PNG data URL
    // → Opacity-incompatible elements cleaned
    // → Font routing uses emoji-safe fonts
}

Every widget's toHtml() method checks this flag and routes accordingly:

// ChartWidget.toHtml()
if (context.isForPdf()) {
    svgData = SvgToPngConverter.convertToPngDataUrl(svgContent);
} else {
    svgData = "data:image/svg+xml;base64," + Base64.encode(svgContent.getBytes());
}

// Background SVG
if (context.isForPdf()) {
    svgContent = SvgCleaner.cleanForPdf(svgContent);
}

This dual-path rendering ensures the same widget HTML works in both browser and PDF, with each path optimized for its target.

Lessons Learned

Don't trust iText's SVG renderer. Convert SVG to PNG before feeding it to iText. Batik standalone is more stable than Batik-in-iText.
viewBox dimensions are not optional. Without explicit dimensions from viewBox, PNG conversion produces wrong-sized images. Always parse and use viewBox.
Emoji in PDF is a font routing problem, not a rendering problem. You need a font that covers the codepoints, and you need to prevent surrogate pair splitting. Color emoji may not be achievable, but visible monochrome emoji is good enough.
Opacity doesn't survive PDF conversion. rgba() and fill-opacity are partially or unsupported. Clean SVG backgrounds before rendering.
The forPdf flag is the cleanest routing mechanism. Instead of maintaining separate HTML templates for browser and PDF, use one template with conditional rendering based on the target.

Series Conclusion

This 10-part series covered the full architecture of a modular assessment engine:

Architecture overview — six modules, one plan agent, streaming execution
Planning engine — decision matrix, YAML task list, knowledge self-containment
Form module — field types, inline scoring, reverse questions
Scale module — dimension direction, range continuity, storage-time reversal
Connect module — cover page conversion, visual styles, SVG illustrations
Report module — page templates, widget grid, variable system, logic tiers
Expert module — prompt framework, behavior red lines, PATCH mode
One-click pipeline — four-phase SSE stream, loading UX, input modes
SSE reliability — ReentrantLock, virtual threads, timeout handling
PDF rendering — SVG→PNG conversion, emoji font routing, opacity cleaning

The core architectural decisions that made this work:

AI generates CLI commands, not code — safer, more controllable, easier to validate
Each skill is independent — self-contained knowledge, no cross-task references
Templates are engine-computed — the AI declares intent, the engine builds structure
Streaming execution — commands run as they're generated, cutting time by 40%
Dual-path rendering — one HTML template, conditional browser/PDF output

If you're building something similar — AI-driven code generation, modular skill systems, or PDF rendering pipelines — I hope this series saves you some of the pain I went through.

[9/10]SSE Reliability: Three Rounds of Fixing Event Loss in JAX-RS SseEventSink

Keo Fung | FormLM — Sat, 18 Jul 2026 05:11:24 +0000

Series: Building a Modular Assessment Engine (9/10)

Server-Sent Events (SSE) is the backbone of the streaming pipeline. When it works, it's elegant — events flow from server to client in real-time. When it breaks, events silently vanish and the user sees a loading spinner forever. This post covers the three rounds of debugging that made SSE reliable.

The Setup

The backend uses JAX-RS (Jakarta REST) with SseEventSink for SSE streaming:

@POST
@Produces(MediaType.SERVER_SENT_EVENTS)
@Consumes(MediaType.APPLICATION_JSON)
public void chat(@Context Sse sse, @Context SseEventSink eventSink,
                 @Context HttpServletRequest http, AgentRequest request) {
    AgentClient client = ExpertBuilder.create()
            .clientId(appId)
            .eventSink(eventSink)
            .sse(sse)
            .build();

    // Plan or execute...
    // Events sent via client.sendToClient()
}

Events are sent through AgentClient.sendToClient():

public void sendToClient(String input, MediaType mediaType) {
    if (!this.hasEventSink()) return;
    OutboundSseEvent sseEvent = sse.newEventBuilder()
            .data(input)
            .mediaType(mediaType)
            .build();
    eventSink.send(sseEvent);  // ← THE PROBLEM IS HERE
}

Round 1: The Missing `await`

The Bug

eventSink.send() returns CompletionStage<?> — it's asynchronous. The I/O write happens on a different thread. But the original code discarded the return value:

eventSink.send(sseEvent);  // Fire and forget
// ... immediately continues to next line
// ... eventually calls client.close()

The close() call would execute before the I/O write completed. The connection would close, and the last few events (including the critical done event) would be lost.

The client would sit there waiting for a done event that was never actually sent over the wire.

The Fix (Attempt 1)

Add .toCompletableFuture().join() to wait for the write to complete:

eventSink.send(sseEvent).toCompletableFuture().join();

This worked... until it didn't.

Round 2: The Concurrent Write Crash

The Bug

With join() in place, a new problem emerged: UT010035: Stream in async mode was not ready for IO operation.

This happened because two threads were calling send() simultaneously:

The main execution thread sending task events
A heartbeat thread sending periodic heartbeats every 10 seconds

JAX-RS SseEventSink is not thread-safe for concurrent writes. Two simultaneous send() calls corrupt the internal buffer state.

The Fix (Attempt 2)

Add a synchronized block:

public void sendToClient(String input, MediaType mediaType) {
    if (!this.hasEventSink()) return;
    synchronized(this) {
        if (!this.hasEventSink()) return;
        eventSink.send(sseEvent).toCompletableFuture().join();
    }
}

This fixed the concurrent write crash... but introduced a new problem on JDK 21+.

Round 3: The Virtual Thread Pinning

The Bug

The system runs on JDK 21 with virtual threads. Virtual threads are lightweight, user-mode threads that should never block the carrier thread. But synchronized blocks pin the virtual thread to its carrier thread — the carrier can't be freed for other virtual threads while one is blocked inside a synchronized block.

With synchronized(this) + join():

The heartbeat thread acquires the lock, starts an I/O write, calls join() which blocks
The carrier thread is now pinned — it can't run other virtual threads
The main execution thread tries to send an event, blocks on the synchronized lock
All virtual threads on this carrier are now stuck
Under load, the entire thread pool exhausts

The application would freeze after 3-4 concurrent users.

The Final Fix: ReentrantLock + get(timeout)

private final ReentrantLock writeLock = new ReentrantLock();

public void sendToClient(String input, MediaType mediaType) {
    if (!this.hasEventSink()) return;
    writeLock.lock();
    try {
        // Double-check: connection may have closed while waiting for lock
        if (!this.hasEventSink()) return;

        OutboundSseEvent sseEvent = sse.newEventBuilder()
                .data(input)
                .mediaType(mediaType)
                .build();

        // Wait for I/O completion with timeout
        eventSink.send(sseEvent).toCompletableFuture()
                .get(10, TimeUnit.SECONDS);

        lastSendTimeMs = System.currentTimeMillis();
    } catch (TimeoutException e) {
        // I/O didn't complete in 10s — connection is likely dead
        this.close();
    } catch (Exception e) {
        // Unwrap CompletionException to get real cause
        Throwable cause = (e.getCause() != null) ? e.getCause() : e;
        if (cause instanceof IllegalStateException) {
            // Connection already closed
            this.close();
        } else {
            FLog.e(TAG, "SSE send failed", cause);
            this.close();
        }
    } finally {
        writeLock.unlock();
    }
}

Why ReentrantLock Instead of synchronized

ReentrantLock doesn't pin virtual threads. When a virtual thread blocks on ReentrantLock.lock(), the JVM can unmount it from the carrier thread, freeing the carrier for other work. With synchronized, the JVM must keep the virtual thread mounted — this is the "pinning" problem.

Why `get(10, SECONDS)` Instead of `join()`

join() blocks indefinitely. If the network connection is half-open (TCP alive but SSE broken), join() waits forever, holding the lock. No other thread can send events. The heartbeat thread can't even send a heartbeat to check if the connection is alive.

get(10, TimeUnit.SECONDS) adds a timeout. If I/O doesn't complete in 10 seconds, something is wrong. The TimeoutException handler calls close(), releasing the lock and cleaning up the connection.

Why Double-Check `hasEventSink()`

Between acquiring the lock and sending, another thread might have closed the connection:

Thread A: writeLock.lock() ← acquired
Thread B: close() called, eventSink = null
Thread A: eventSink.send() ← NPE!

The double-check prevents this:

Thread A: writeLock.lock() ← acquired
Thread A: if (!hasEventSink()) return ← connection closed by Thread B, exit safely

The Heartbeat Problem

Heartbeats are sent every 10 seconds to keep the SSE connection alive. Without heartbeats, proxies and load balancers close idle connections after 30-60 seconds.

But heartbeats introduce a new problem: the heartbeat thread and the main thread both call sendToClient(). With the ReentrantLock, this is safe — one waits for the other. But the heartbeat thread must not block for too long:

// Heartbeat thread
if (System.currentTimeMillis() - lastSendTimeMs > 10_000) {
    sendToClient("{\"event\":\"heartbeat\"}", MediaType.APPLICATION_JSON_TYPE);
}

If the main thread is mid-write and the heartbeat thread tries to send, it waits on the lock. Once the main thread finishes, the heartbeat sends. Total delay: the duration of one I/O write (usually <1 second). Acceptable.

But what if the main thread's I/O is stuck? The heartbeat thread waits for the lock, and get(10, SECONDS) is the main thread's timeout. After 10 seconds, the main thread calls close(), the lock releases, and the heartbeat thread's sendToClient() sees hasEventSink() == false and exits. Clean.

The JSON Serialization Bug

One more SSE bug, unrelated to threading but worth mentioning: the ConvertUtil.toJson() method had a quirk where it didn't properly escape strings containing special characters.

When a task description contained a quote or newline, the JSON payload would be malformed:

{"event":"task.start","data":{"taskId":"t1","title":"Assess "stress" levels"}}
                                                              ↑ broken JSON

The client's JSON.parse() would throw, and the event would be silently dropped. The user would see a task that never starts.

The fix: ensure ConvertUtil.toJson() properly escapes all string values:

// Before (bug): raw string insertion
sb.append("\"title\":\"").append(task.getTitle()).append("\"");

// After (fixed): proper JSON string escaping
sb.append("\"title\":\"").append(jsonEscape(task.getTitle())).append("\"");

The Nginx Configuration

Behind all the Java code, Nginx needs specific configuration for SSE:

location /api/v1/assess/ {
    proxy_pass http://backend;
    proxy_read_timeout 300s;      # 5 minutes for long-running AI calls
    proxy_buffering off;          # SSE needs unbuffered transfer
    proxy_cache off;
    proxy_set_header Connection '';
    proxy_http_version 1.1;
    chunked_transfer_encoding on;
}

proxy_buffering off is critical. With buffering on, Nginx collects events in a buffer and sends them in batches. The client sees nothing for 30 seconds, then gets everything at once. SSE is supposed to be real-time.

proxy_read_timeout 300s prevents Nginx from closing the connection during long AI generation. Default is 60s, which is too short for a 30-second planning phase.

Lessons Learned

SseEventSink.send() is async. Always await it. Discarding the CompletionStage means events are lost. Use .get(timeout) not .join().
Virtual threads need ReentrantLock, not synchronized. synchronized pins virtual threads to carrier threads, killing the scalability benefit. This is a JDK 21+ specific issue.
Always timeout. Network connections fail in mysterious ways. A timeout is the difference between a recoverable error and a permanently stuck thread.
Double-check after acquiring a lock. State can change between lock acquisition and use. The double-check pattern prevents NPEs on closed connections.
proxy_buffering off is mandatory for SSE. Without it, events arrive in batches, not in real-time. The UX difference is dramatic.

Next: [PDF Rendering War — SVG, emoji, and the iText NPE]

[8/10]The One-Click Pipeline: How One SSE Stream Orchestrates Everything

Keo Fung | FormLM — Thu, 16 Jul 2026 06:57:23 +0000

Series: Building a Modular Assessment Engine (8/10)

The previous posts covered individual modules. This one covers the glue — the frontend pipeline in newapp.html that takes a user's single input and drives it through knowledge creation, AI planning, streaming execution, and publishing. All through one SSE connection.

The User Experience

The user sees a text box. They type (or paste) their request — a document, a URL, or just a sentence like "build a workplace stress assessment." Two buttons appear:

Review & Edit — see the AI's plan before execution
Create Directly — skip the plan review, go straight to generation

Either way, the pipeline is the same. The only difference is whether the user sees and edits the plan before execution.

The Four-Phase Pipeline

Phase 1: Generate     → POST /api/v1/fetch/generate
Phase 2: Plan (SSE)   → SSE  /api/v1/assess/v1/chat (plan mode)
Phase 3: Execute (SSE) → SSE /api/v1/assess/v1/chat (execute mode)
Phase 4: Publish      → GET  /api/v1/fetch/share

Phase 1: Knowledge + App Skeleton

const res = await $server.post('/api/v1/fetch/generate', {
    name: title,
    content: reqContent,           // pasted text
    sourceUrl: reqSourceUrl,       // URL to scrape
    goal: reqGoal,                 // user's intent
    knowledgeId: prefillKnowledgeId || null,
    contentPreprocessed: hasFiles, // skip backend compression if files pre-processed
    lang: lang
});

This call does three things:

Creates a knowledge base from the input (text, URL, or file attachments)
Creates an app skeleton (empty Flower domain object)
Returns structured input for the plan agent

The response includes:

appId — the new app's ID
input — structured input with context tags
displayContent — clean text for the textarea (no tags)

Phase 2: Plan (SSE Stream)

runPlanPhase(appId, input, option) {
    this.startPlanLoadingTimer();
    $agent.assessChat(appId, input, null, (event, data) => {
        if (event === 'plan' && data) {
            this.stopPlanLoadingTimer();
            this.currentPlan = data;
            // Either show for review or start execution
        } else if (event === 'heartbeat') {
            this.advancePlanLoading();  // rotate loading messages
        } else if (event === 'error') {
            this.onError('Plan generation failed');
        } else if (event === 'close' && !this.currentPlan) {
            this.onError('Plan timeout');
        }
    });
}

The plan phase sends user input to the AssessAgent, which:

Loads agents/assess-plan.md as system prompt
Dynamically injects available skill list
Calls the AI model
Parses the YAML response into an AssessPlan object
Streams the plan back as a plan event

The Loading Message Problem

AI planning takes 10-30 seconds. During that time, the user stares at a loading spinner. If nothing changes for 15 seconds, they assume it's broken and leave.

The solution: a progressive loading message timer that rotates messages every 8 seconds:

const steps = [
    'newapp.loading.plan',
    'newapp.loading.plan_step1',  // "Analyzing your request..."
    'newapp.loading.plan_step2',  // "Designing assessment dimensions..."
    'newapp.loading.plan_step3',  // "Planning scoring logic..."
    'newapp.loading.plan_step4'   // "Preparing report structure..."
];

These messages are cosmetic — they don't reflect actual progress. But they give the user a sense that things are moving. Combined with SSE heartbeats (which advance the message rotation), the user always sees changing content.

Is this honest? Partially. The messages describe what the AI is conceptually doing (analyzing, designing dimensions, planning scoring) even if we can't track exact progress. It's better than a static spinner.

Phase 3: Execute (SSE Stream)

startExecute() {
    this.stage = 'executing';
    const plan = Object.assign({}, this.currentPlan);

    // Initialize progress tracking
    this.progressTasks = plan.tasks.map(t => ({
        name: t.title,
        status: 'pending',
        taskId: t.taskId,
        description: ''
    }));

    // Execute via SSE
    $agent.assessChat(this.appId, null, plan, (ev, evData) => {
        this.onExecuteEvent(ev, evData);
    });
}

The execute phase drives the AssessAgent's execute() method. Events flow back:

Event	When	UI Update
`task.start`	A module begins	Mark task as "running"
`cmd.done`	A CLI command completes	Update task description with result
`task.done`	A module finishes	Mark task as "done"
`task.error`	A module fails	Mark task as "error"
`share.url`	Share URL generated	Store for final display
`plan.done`	All modules complete	Trigger completion sequence
`done`	Final event with credits	Accumulate credit cost
`close`	SSE connection closes	Finalize if still executing

The SSE Event Processing

onExecuteEvent(event, data) {
    if (event === 'task.start' && data) {
        const t = this.findProgTask(data.taskId);
        if (t) t.status = 'running';
    } else if (event === 'cmd.done' && data) {
        // Update task with latest command result
        const ct = this.findProgTask(data.task.taskId);
        if (ct && data.result) {
            const lines = data.result.split('\n').map(l => l.trim()).filter(l => l);
            ct.description = lines[0] ? lines[0].substring(0, 100) : '';
        }
    } else if (event === 'share.url' && data) {
        this.shareUrl = data;
    } else if (event === 'plan.done') {
        this.onPlanDone();
    } else if (event === 'close') {
        if (this.stage === 'executing') {
            this.onPlanDone();  // SSE closed, finalize
        }
    }
}

Each event updates the UI in real-time. The user sees:

"Designing form..." → running
"Created field: workload_1" → description updates
"Created field: workload_2" → description updates
"Form complete" → task done
"Configuring scoring..." → next task starts

This transparency builds trust. The user can see the AI working, not just a spinner.

Phase 4: Completion

async onPlanDone() {
    if (this.isDone) return;
    this.isDone = true;

    // Mark all pending tasks as done
    this.progressTasks.forEach(t => {
        if (t.status === 'pending' || t.status === 'running') t.status = 'done';
    });

    // Fetch share URL if not already received
    if (!this.shareUrl && this.appId) {
        const res = await $server.get('/api/v1/fetch/share?appId=' + this.appId);
        if (res.data.code === 200) {
            this.shareUrl = res.data.data.shareUrl;
            this.appUrl = res.data.data.appUrl;
        }
    }

    // Switch to done screen after 600ms
    setTimeout(() => {
        this.stage = 'done';
        this.$nextTick(() => this.renderShareQr());
    }, 600);
}

The 600ms delay is deliberate — it lets the last progress animation complete before the screen switches. Without it, the transition feels jarring.

The Knowledge Base Input Modes

The pipeline handles four input modes, each with different preprocessing:

Mode	Input	Processing
Text paste	`content` field	Backend AI compresses and structures
URL scrape	`sourceUrl` field	Backend fetches + extracts content
File upload	`content` from files	Frontend AI pre-formats, `contentPreprocessed=true`
Knowledge base	`knowledgeId`	Backend reads existing KB, no new creation
Pure text (no KB)	`goal` only	No KB created, app generated from goal alone

The contentPreprocessed flag is important: when files are uploaded, the frontend already runs an AI extraction step to format the content. If the backend tries to compress it again, it double-processes and loses information. The flag tells the backend to skip compression.

The PlanType Override

Users can optionally specify a plan type before generation:

let directInput = genData.input;
if (this.planConfig.planType) {
    directInput = 'planType=' + this.planConfig.planType + '\n\n' + directInput;
}

This injects a constraint directive at the top of the input. The plan agent sees it and respects it — if the user says planType=exam, the agent generates an exam sequence even if the content could work as an assessment.

Without this, the plan agent might choose assessment for a knowledge test, which would use Likert scales instead of correct/incorrect marking. Wrong plan type = wrong entire app structure.

The SSE Connection Lifecycle

The SSE connection lives across both plan and execute phases. In plan mode, it's a read-only stream — the client listens for the plan event. In execute mode, the client sends the plan object and listens for task events.

// Plan phase: input only, no plan
$agent.assessChat(appId, input, null, callback);

// Execute phase: plan only, no input  
$agent.assessChat(appId, null, plan, callback);

The backend distinguishes the two by checking request.hasPlan():

if (request.hasPlan()) {
    // Execute phase
    agent.execute(request.getPlan(), session, listener);
} else {
    // Plan phase
    AssessPlan plan = agent.plan(input, session);
    sendChatEvent(client, "plan", ConvertUtil.toJson(plan));
}

The Close Event Ambiguity

The close event is ambiguous — it fires when the SSE connection closes, which can happen:

Normally — after all events are sent
Due to timeout — network issue or server timeout
Due to error — unhandled exception on the server

The frontend handles this by checking state:

} else if (event === 'close') {
    if (this.stage === 'executing') {
        this.onPlanDone();  // SSE closed during execution, assume done
    }
    // If stage === 'planning', the plan-phase close handler already fires onError
}

If the connection closes during planning (before a plan is received), it's an error. If it closes during execution, it's treated as completion — the server may have finished sending all events before closing.

This is imperfect. A server crash during execution would be treated as successful completion. But the alternative — treating all closes as errors — would generate false error messages when the server cleanly finishes.

Lessons Learned

Loading messages must rotate. A static spinner for 20+ seconds kills conversion. Even cosmetic progress helps.
Input mode matters. Different input types (text, URL, files, KB) need different preprocessing. Don't double-process.
SSE event types must be unambiguous. close during planning ≠ close during execution. Check application state before interpreting events.
The 600ms completion delay is a UX detail that matters. Instant screen switches after long loading feel jarring. A small delay makes the transition feel natural.
Plan type override is a safety valve. When the AI picks the wrong plan type, the user can force it. This single feature prevented countless support tickets.

Next: [SSE Reliability — Three rounds of fixing event loss]

[7/10]Giving AI Assistants a Personality: Role, Boundaries, and Contextual Awareness

Keo Fung | FormLM — Thu, 16 Jul 2026 06:56:43 +0000

Series: Building a Modular Assessment Engine (7/10)

The expert module configures an AI chatbot that users can interact with after completing an assessment. Not a generic "ask me anything" bot — one that knows the user's assessment results and stays within professional boundaries. This post covers the prompt engineering, the behavior red lines, and the consistency problems that made early versions dangerous.

The Configuration Surface

The expert is configured through a single config command plus an avatar command:

assess expert config \
  --name "Stress Coach" \
  --role "Senior Workplace Psychological Counselor" \
  --description "Helps you analyze stress sources and provides personalized advice." \
  --style "Warm, empathetic, supportive, and inspiring" \
  --welcome "Hi! I'm your stress coach. I can see your results across Workload, Role Stress, and Social Support. What would you like to discuss first?" \
  --question1 "What do my scores mean?" \
  --question2 "How can I reduce workload stress?" \
  --question3 "How do I talk to my manager about this?" \
  --theme "Warm" \
  --kbText "Workplace stress is caused by..." \
  --prompt "【Role】You are a senior counselor with 10 years of experience...
    【Knowledge】Based on the user's assessment results...
    【Communication】Warm, empathetic, uses guiding questions...
    【Boundaries】1. Never provide medical or psychiatric diagnosis.
    2. If user shows extreme distress, gently suggest professional help.
    3. Keep responses under 200 words." \
  --enable

assess expert avatar --url "/page/assets/img/avatar/a4.png" --enable

That's 12 parameters in one command. Omitting any of them leaves the assistant with a gap — no name, no welcome message, no behavior boundaries.

The Four-Element Prompt Framework

The --prompt field is the system prompt for the chatbot. It must contain four elements:

1. Role Definition

"You are a senior workplace psychological counselor with 10 years of experience in cognitive behavioral therapy and stress management."

Specific, not generic. "You are a helpful assistant" is useless. "You are a senior counselor with CBT experience" gives the AI a professional frame.

2. Knowledge Boundary

"Based on the user's Workplace Stress Assessment results, analyze their scores across Workload, Role Stress, and Social Support dimensions."

This tells the AI what it knows and what it doesn't. It knows the assessment results. It doesn't know the user's medical history. It doesn't have access to real-time data. The knowledge boundary prevents hallucination.

3. Communication Style

"Tone is warm, empathetic, and supportive. Use guiding questions. Avoid lecturing."

The style must match the --style parameter. If --style says "professional and rigorous," the prompt shouldn't say "casual and fun." Consistency between these two fields was a recurring bug — the AI would set --style "warm" but write a prompt that says "maintain professional distance."

4. Behavior Red Lines

"1. Never provide medical or psychiatric diagnosis.

If user shows extreme negative emotions, gently suggest seeking professional medical help.

Keep each response under 200 words."

Red lines are the most important element. Without them, the AI will happily diagnose depression, recommend medication, or give legal advice. Each red line is a specific, testable constraint.

The Welcome Message Dimension Problem

The welcome message must reference the assessment dimensions by name:

✅ "I can see your results across Workload, Role Stress, and Social Support."
❌ "I can see your assessment results."

Why? Because generic welcome messages feel impersonal. Naming the dimensions tells the user "I actually know your specific results, not just that you took some test."

The trap: the dimension names must come from the scale-dimensions reference, not from the plan agent's knowledge field. The plan agent might say "Workload" but the scale module might have created "Workload Intensity." The welcome message must use the exact name from the scale data.

The SKILL.md enforces this:

Welcome message dimension names MUST be read verbatim from the scale-dimensions reference ## Scales table name column. Never guess from knowledge.

The PATCH Problem

When modifying an existing expert configuration, the AI would frequently rewrite everything — new name, new role, new prompt — even when the user only asked to change the welcome message.

The fix: a [CURRENT] / [PATCH] protocol in the knowledge field:

[CURRENT]
name: Stress Coach
role: Senior Counselor
style: Warm, empathetic
welcome: Hi! I'm your stress coach...
question1: What do my scores mean?
...

[PATCH]
Update the welcome message to be more casual and friendly.

The rule: only modify what [PATCH] explicitly mentions. Everything in [CURRENT] must be preserved verbatim. The AI reads the current config, applies only the patch, and outputs the full config with the changes merged in.

This sounds obvious, but without explicit enforcement, the AI would "improve" the role description while updating the welcome message, or rewrite the behavior red lines because they "could be better phrased."

The Theme Mismatch

The expert has its own --theme parameter (same 12 presets as connect). The rule: it must match the connect/report theme.

If the assessment uses Noir (dark professional), the expert chat should also be Noir. A Fresh (light green) expert chat inside a Noir assessment feels like walking from a dimly lit room into a fluorescent-lit hallway.

The lookAndFeel field from the plan agent carries the theme, and the expert skill must extract it:

lookAndFeel: 'theme:Noir; look:dark professional...'
→ --theme Noir (not Fresh, not Warm, not whatever the AI thinks is "calmer")

The common failure: the AI decides that a stress assessment needs a "warmer" expert theme and overrides Noir with Warm. Now the assessment pages are dark blue and the chat is amber. Visual whiplash.

The Avatar Selection Logic

Nine preset avatars are available, each matching a professional archetype:

ID	Style	Matches
1	Middle-aged doctor, white coat	Medical, health
2	Middle-aged male consultant, suit	Business, strategy
3	Young female teacher, warm	Education, learning
4	Young male, energetic	Fitness, motivation
5	Middle-aged male, formal	Legal, compliance
6	Middle-aged female mentor, casual	Career, coaching
7	Young female manager, sharp	Leadership, management
8	Tech engineer, minimal	Technical, IT
9	Young female, bright	Creative, lifestyle

When the user doesn't provide a custom avatar URL, the AI must select from this list based on the --role and --style:

Psychological counselor → avatar 4 (young, energetic) or 6 (female mentor, casual)
Legal compliance trainer → avatar 5 (formal male)
Leadership coach → avatar 7 (sharp female manager)

The AI must not skip the avatar command. An expert without an avatar displays a broken image icon in the chat interface.

The `--enable` Flag

The --enable flag on both config and avatar commands is a bare flag (no value). Its presence means true. Its absence means false.

# Enabled
assess expert config --name "Coach" ... --enable

# Not enabled (config exists but chat is disabled)
assess expert config --name "Coach" ...

The AI would sometimes write --enable true or --enable false. The CLI rejects both — it's a bare flag, not a key-value pair. This was a minor but frequent syntax error.

The Empty Expert Problem

The expert module only runs for consultation plan type. For assessment, exam, and report types, there's no expert task. But sometimes the AI would add an expert task anyway:

# Wrong — assessment doesn't include expert
planType: assessment
tasks:
  - skill: form
  - skill: scale
  - skill: connect
  - skill: report
  - skill: expert   # ← not allowed for assessment
  - skill: share

The decision matrix prevents this: assessment maps to form→scale→connect→report→share (no expert). Only consultation includes expert. The plan agent's system prompt explicitly lists which modules each plan type allows.

Lessons Learned

Behavior red lines are not optional. Without explicit "don't do X" rules, the AI will diagnose, prescribe, and advise on things it shouldn't. Each red line must be specific and testable.
Dimension names in the welcome message build trust. "I see your results in Workload and Social Support" beats "I see your results" every time.
PATCH mode requires explicit preservation rules. The AI will rewrite everything if given the chance. [CURRENT] / [PATCH] separation forces surgical changes.
Theme consistency across modules is a lookAndFeel rule, not a style preference. The expert theme must match the assessment theme. No exceptions.
Avatar selection is part of the configuration, not an afterthought. An expert without an avatar is a broken feature, not a minor cosmetic gap.

Next: [The One-Click Pipeline — How one SSE stream orchestrates everything]

[6/10]Page-Templated PDF Generation: From YAML Slots to BentoUI Widgets

Keo Fung | FormLM — Fri, 10 Jul 2026 01:07:53 +0000

Series: Building a Modular Assessment Engine (6/10)

The report module generates personalized PDF reports. Each user who completes an assessment gets a unique report with their scores, dimension interpretations, and visualizations. This post covers the page template system, the widget grid, and the variable pipeline that makes personalization work.

The Template-First Approach

Reports don't start from blank pages. They start from page templates — predefined page structures that the engine assembles based on the assessment's dimension count and theme.

The plan agent declares two values:

DimN=3
theme=Noir

The engine computes the page template list automatically:

cover-noir          → Cover page (Noir theme)
summary-3dim        → Summary page (radar chart for 3 dimensions)
detail-dim1         → Dimension 1 detail page
detail-dim2         → Dimension 2 detail page
detail-dim3         → Dimension 3 detail page
total-assessment    → Total score conclusion page

No AI involvement in this step. The engine reads the dimension count from the in-memory scale data and picks templates from a registry. This was a hard-won lesson — earlier versions let the AI choose template IDs, and it would invent non-existent templates or pick wrong page counts.

The Runtime Fallback

What happens when the plan agent forgets to declare dimension count? The engine recovers:

// In AssessAgent.skillGenerateStream()
if ("report".equals(skillName) && ObjectUtil.isEmpty(task.getPageTemplates())) {
    Factor _factor = session.getFlower().getModel().getFactor();
    if (_factor != null && !ObjectUtil.isEmpty(_factor.getScales())) {
        int _dimCount = _factor.getScales().size();
        List<String> _recovered = buildPageTemplates(_dimCount, task, planType);
        task.setPageTemplates(_recovered);
        FLog.w(TAG, "pageTemplates recovered from scale data, dimCount=" + _dimCount);
    }
}

By the time the report skill runs, the scale skill has already created dimensions in memory. The engine counts them and builds the template list. The AI's declaration is a hint, not a dependency.

The Widget Grid System

Each page is a 68×48 grid (0-indexed). Widgets are placed by coordinates:

assess report widget add \
  --page cover_1 \
  --type text \
  --x 2 --y 3 --w 44 --h 6 \
  --value "<h1>{{DisplayName}}'s Assessment Report</h1>"

Constraints:

x + w ≤ 48 (cannot exceed grid width)
y + h ≤ 68 (cannot exceed grid height)
No overlapping widgets on the same page

The grid system was chosen over free-form positioning because:

It's predictable — the AI can reason about layout mathematically
It's responsive — the same grid produces valid layouts at different PDF sizes
It prevents overlaps — a common bug with absolute positioning

BentoUI Style Parameters

Widgets support a constrained set of style parameters:

assess report widget update \
  --page detail_1 --id score_card \
  --backgroundColor "#1a1a2e" \
  --fontColor "#E2E8F0" \
  --roundCorner 16 \
  --enableBorder true \
  --borderColor "#33334c" \
  --borderSize 1 \
  --paddingSize 16 \
  --bold true \
  --alignX left

The parameter whitelist is strict. The AI can't invent --shadow or --gradient — they don't exist. This prevents the AI from generating CSS that the PDF renderer (iText) doesn't support.

The Variable System

Reports are personalized through template variables:

assess report widget update \
  --page summary_1 --id greeting \
  --value "<p>Hello, {{DisplayName}}!</p>"

Variables are wrapped in {{double curly braces}}. The engine replaces them with actual user data at render time:

Variable	Replaced With
`{{DisplayName}}`	User's name from the form
`{{DateTime}}`	Report generation timestamp
`{{DimensionName}}`	Current dimension's name
`{{DimensionScore}}`	User's score on current dimension
`{{DimensionTotal}}`	Maximum possible score for dimension
`{{ScaleScore}}`	Total score across all dimensions
`{{PersonalScore}}`	User's personal total
`{{TotalScore}}`	Maximum possible total
`{{ScoreRate}}`	Score percentage

The Bare Variable Bug

The most common report bug: variables without braces.

# Wrong — the engine treats "DisplayName" as literal text
--value "<p>Hello, DisplayName!</p>"

# The user sees "Hello, DisplayName!" instead of "Hello, John!"

This happens because variable names look like regular English words. The AI writes DisplayName when it means {{DisplayName}}. The bug is invisible during generation (the command succeeds) and only surfaces when a user reads their report.

The fix: a P0 validation rule that scans all --value and --logic parameters for bare variable names and rejects them. The SKILL.md includes a checklist of common mistakes:

❌ "Hello, DisplayName" → ✅ "Hello, {{DisplayName}}"
❌ "Score: DimensionScore/DimensionTotal" → ✅ "Score: {{DimensionScore}}/{{DimensionTotal}}"
❌ "<p>DateTime</p>" → ✅ "<p>{{DateTime}}</p>"

The Logic System: Score-Tiered Content

Different score tiers need different interpretations. A user with severe burnout needs different text than one with mild burnout. This is handled through --logic parameters:

assess report widget update \
  --page detail_1 --id burnout_interpretation \
  --type scale-dimension \
  --scaleId burnout \
  --enableOwn \
  --value "<p>Your burnout level: {{DimensionScore}}/{{DimensionTotal}}</p>" \
  --logic "19-999|<p>Your burnout is low. You're managing well — keep up the practices that work.</p>" \
  --logic "11-18|<p>You show moderate signs of burnout. Consider reviewing your workload and recovery routines.</p>" \
  --logic "5-10|<p>Your burnout level is high. This signals a need for active intervention — seek support.</p>"

How it works:

The engine evaluates the user's score against each --logic range
First match wins (so order matters)
The matched content replaces the widget's display
If no logic matches, --value is the fallback

The High-Score-First Rule

Logic ranges must be added from highest to lowest:

# Correct order: high → mid → low
--logic "19-999|High interpretation" \
--logic "11-18|Mid interpretation" \
--logic "5-10|Low interpretation"

Why? Because the engine uses first-match-wins evaluation. If the low range is first and the user scores 20, they'd match the low range (5-10 doesn't match 20, but if ranges overlap, the first one wins). Ordering high-to-low ensures the most specific high range is checked first.

The Symptom Scale Trap

For negative-direction dimensions (symptom scales, high = bad), the logic interpretation direction must flip:

High score → empathy + improvement suggestions
Low score → affirmation + maintenance advice

For positive-direction dimensions (ability scales, high = good):

High score → affirmation + advanced challenges
Low score → support + foundational steps

The SKILL.md reads the direction field from scale data and adjusts interpretation direction accordingly. The AI doesn't need to figure this out — the SKILL.md tells it: "if direction=negative for all dimensions, low total score = affirm good state, high total score = empathize + suggest improvement."

The PageTemplates Empty Report Problem

Sometimes the pageTemplates application fails silently — the templates are declared but not applied. The report skill runs and finds an empty report (no pages exist).

The SKILL.md handles this with a two-mode strategy:

Normal mode (pages exist):

# Only update widgets — pages are already created by templates
assess report widget update --page cover_1 --id title --value "..."

Empty report mode (no pages):

# Step 1: Create pages manually
assess report page update --page cover_1 --name "Cover" --backgroundColor "#1a1a2e"
# (response contains "⚠️ Page was auto-created" — confirms creation)

# Step 2: Add widgets (not update — they don't exist yet)
assess report widget add --page cover_1 --type text --x 2 --y 3 --w 44 --h 6 ...

The detection is simple: if the report-pages reference shows no page rows, switch to empty report mode.

The Contrast Problem

Dark-themed reports (Noir, Mystic, Classic) need dark page backgrounds with light text. But the AI would frequently create dark-background pages with dark text — invisible content.

The rule: fontColor and backgroundColor must be one dark, one light. Always.

Dark background (#000~#555 or rgba alpha < 0.3) → fontColor: #E2E8F0, #F1F5F9, #FFFFFF
Light background (#AAA~#FFF) → fontColor: #1A202C, #2D3748, #111827

The trap: rgba(255,255,255,0.06) — a semi-transparent white that looks dark visually but has "255" in the RGB values. The AI would see "white" and assign dark text. The rule now explicitly covers this: "rgba with alpha < 0.3 is visually dark, use light fontColor."

The Resource Honesty Principle

The SKILL.md has a P0 rule about fabricated resources:

--value/--content HTML must NOT contain fabricated image URLs, external resources, or base64 data. Only plain text + HTML + inline CSS + CSS gradients are allowed.

The AI would sometimes generate <img src="https://example.com/chart.png"> — a URL that doesn't exist. The PDF renderer would try to fetch it, fail, and produce a broken image icon in the report.

The only visual elements allowed are:

CSS gradients (background: linear-gradient(...))
Inline SVG (but see the SVG rules from the connect module post)
Text with styling

No external images. No base64 blobs. If the AI can't generate it with CSS, it doesn't go in the report.

Lessons Learned

Templates are engine-computed, not AI-chosen. The AI declares intent (dimension count, theme); the engine picks templates. This eliminated an entire class of bugs.
Always have a runtime fallback. If templates aren't applied, recover from in-memory scale data. Don't fail silently.
Bare variables are the #1 report bug. Validate every --value and --logic for {{}} wrapping before accepting the command.
Logic order matters. High-to-low, first-match-wins. Document this explicitly.
Contrast validation must handle edge cases. Semi-transparent backgrounds, named colors, and hex shorthand all need explicit rules.

Next: [Expert Module — Giving AI assistants personality and boundaries]

[5/10]Generating AI-Driven Cover Pages and Visual Styles That Don't Look Generic

Keo Fung | FormLM — Tue, 07 Jul 2026 08:47:28 +0000

Series: Building a Modular Assessment Engine (5/10)

The connect module configures what users actually see: the cover page, the form-filling experience, and the final page. It also drives the visual style — colors, backgrounds, layout. This is where "functional" meets "doesn't look like a government form from 2003."

Three Pages, Three Jobs

Every assessment app has three page types:

[Cover Page] → [Main Page (form)] → [Final Page]

Cover page: The hook. Why should the user spend 5 minutes on this?
Main page: The actual form. Can be one long page (form mode), one question per screen (field mode), or card-swipe style (card mode).
Final page: The payoff. Download a PDF report, chat with an AI expert, or a simple thank-you.

The Cover Page Conversion Formula

Most cover pages fail because they say "Welcome to our assessment." Nobody cares. The cover page needs to answer one question: why should I spend my time on this?

The SKILL.md enforces a four-element formula:

assess connect cover-page add --id cover_main \
  --name "Workplace Stress Assessment" \
  --description "<p>73% of high-pressure workers don't realize their stress exceeds healthy levels.</p>
    <p>This assessment covers Workload, Role Stress, and Social Support. 5 minutes. Personalized report.</p>" \
  --format rich-text \
  --enable-title-writer true \
  --enable-split-screen true

The four elements:

Hook sentence — a counter-intuitive fact or surprising number from the knowledge base (NOT "welcome")
Benefit statement — what the user gets out of it (one sentence)
Time estimate — "5 minutes" (honest, not "quick")
Dimension preview — 2-4 keywords showing what's covered

The Fabricated Statistics Problem

The hardest rule to enforce: statistics in the hook must come from the knowledge base, not the AI's imagination.

The AI would write things like "Studies show 87% of workers experience burnout." That number sounds credible. It's made up. On a public platform, fabricated statistics are a credibility disaster.

The fix: the SKILL.md explicitly states "statistics must come from knowledge base original text, AI fabrication forbidden. The --kbText contract from the form module ensures the source material is available.

The Main Page Format Decision

Three formats, each suited to different scenarios:

Format	UX	When to Use
`form`	All questions on one page	Surveys, data collection, short forms
`field`	One question per screen	Assessments, exams, consultations
`card`	Card carousel within a container	Medium-length assessments

The decision is driven by the plan type:

survey → form (mandatory)
assessment/consultation/exam → field or card
learn → field

Why does survey mandate form? Because surveys are often filled on desktop, and one-page-per-question for a 20-question survey feels like a dark pattern. Users want to see the full scope before committing.

Why does assessment prefer field? Because one-question-per-screen creates focus. The user isn't overwhelmed by seeing 15 Likert scales at once. It also enables progress indicators and per-question context.

The Style System

Visual style is applied through a separate AI call — style apply:

assess connect style apply \
  --theme Noir \
  --look "workplace stress assessment, psychological evaluation, dark professional, deep blue with silver accents" \
  --layout stack

This generates CSS that's applied to all pages. The --look parameter is natural language — the AI translates it into actual color values, background gradients, and typography.

Theme Presets

12 preset themes map to color palettes:

Light Themes	Dark Themes
Minimal (light purple-gray)	Earthy (deep forest green)
Fresh (blue-green)	Soft (deep rose)
Clean (green-white)	Vibrant (dark orange)
Warm (amber)	Noir (deep indigo)
Airy (sky blue)	Classic (deep blue)
Retro (warm rose)	Mystic (dark purple)

The AI picks a theme based on the assessment topic. Psychological assessments tend toward dark themes (Noir, Mystic). Health surveys lean light (Fresh, Clean). The --look parameter adds nuance — "warm and supportive" modifies how the theme is applied.

The `apply-all` Optimization

Initially, style apply was called once per page type (cover, main, final). Each call triggered a separate AI call to generate CSS. Three AI calls for styling alone.

The fix: style apply-all:

assess connect style apply-all \
  --theme Noir \
  --look "dark professional, deep blue with silver accents" \
  --layout stack

One AI call generates the style once, then applies it to all pages. This cut styling time from ~15 seconds to ~5 seconds.

The SVG Illustration System

The connect module supports optional SVG illustrations for field-level context. When the user asks for "scene illustrations," each assessment question gets a small SVG above it:

assess connect main-page set --field X4 \
  --description "<div><svg viewBox='0 0 280 64' width='100%' height='64'>
    <defs><linearGradient id='gd' x1='0' y1='0' x2='1' y2='0'>
      <stop offset='0%' stop-color='#818CF8' stop-opacity='0.3'/>
      <stop offset='100%' stop-color='#818CF8' stop-opacity='1'/>
    </linearGradient></defs>
    <!-- gauge, ticks, pointer -->
  </svg></div>"

Five standard illustration patterns cover most assessment question types:

Pattern	Visual	When
A. Layer deconstruction	Nested rounded boxes	Concept understanding
B. Path nodes	Bezier-connected circles	Process/methodology
C. Dual-scene contrast	Dashed divider, left dim/right bright	Comparison/contrast
D. Scale pointer	Gradient track + glowing dot	Frequency/degree scales
E. Scene narrative	Two figures + transformation arrow	Application/scenario

SVG Rules That Prevent Bugs

SVGs in this system have strict rules — not for aesthetics, but because they're later rendered to PDF by Batik, and Batik is picky:

Transparent background — no <rect> background. Batik renders it as opaque black in PDF.
fill='none' or low opacity — no large solid color blocks. They look terrible in print.
viewBox must be explicit — without it, Batik uses default dimensions and the SVG renders at wrong size in PDF.
<path> d attribute must start with M — Batik rejects paths that don't start with a move-to command.
Gradient IDs must be unique per page — duplicate IDs cause the first gradient to be used everywhere.
No <script>, <use>, or <image> — Batik doesn't execute scripts or fetch external resources.

These rules exist because each one was a bug report. The <path> starting with L instead of M? That crashed the PDF renderer for an entire week before I found it.

The Final Page: Where Conversion Happens

The final page is where the user gets their reward. Four formats:

Format	Content	When
`report-pdf`	Display + download PDF report	Assessment, exam, report
`expert`	Enter AI expert chat	Consultation
`rich-text`	Thank-you page	Survey, learn
`url`	Redirect to external link	Special cases

The final page must answer: "I just spent 5 minutes. What did I get?"

The SKILL.md enforces a three-element structure:

Congratulations — acknowledge completion
Value statement — "Your personalized report shows..."
Share prompt — "Found this useful? Share with a friend"

The share prompt matters more than you'd think. It's the viral coefficient. Apps without a share prompt have ~2% share rates. Apps with a natural share prompt hit ~8%.

The `--type` vs `--page-id` Confusion

One more CLI gotcha. The style set command can target pages by type or by ID:

# By type — works for cover/main/final
assess connect style set --type main --submit-label "Submit"

# By ID — needed for specific page overrides
assess connect style set --id cover_main --writer-speed 80

The rule: --type is for type-level settings (submit button text, main page config). --id is for page-specific overrides (typewriter speed on a specific cover page). Using --type cover when you meant --id cover_main silently applies to all cover pages, which is usually not what you want.

The exception: --submit-label is the only parameter allowed with --type main. Everything else requires --id.

Lessons Learned

The cover page is a conversion problem, not a design problem. Hook > benefit > time > preview. "Welcome" is not a hook.
Fabricated statistics are a credibility bomb. If the number isn't in the source material, it doesn't go in the cover page. Period.
SVG rules are PDF renderer rules. What looks fine in a browser can crash Batik. Define the constraints at generation time, not at render time.
Style generation should be one AI call, not N. apply-all isn't just an optimization — it ensures visual consistency across pages.
The final page is where virality lives. A good share prompt is worth more than a beautiful cover page.

Next: [Report Module — Page-templated PDF generation]

[4/10]Solving the Dimension Direction Problem: How Positive/Negative Scales Actually Work

Keo Fung | FormLM — Tue, 07 Jul 2026 02:20:54 +0000

Series: Building a Modular Assessment Engine (4/10)

The scale module computes dimension scores from form answers and assigns interpretation tiers. Sounds straightforward. It's not. The "direction" problem — whether high scores mean good or bad — caused more bugs than every other module combined.

The Data Structure

Three levels of hierarchy:

Factor (root)
  └── Scale (dimension)
       ├── id: "workload"
       ├── name: "Workload"
       ├── format: sum | avg | count
       ├── direction: positive | negative
       └── Data[] (score ranges)
            ├── 0-8: "Severe" → "Your workload is critically high..."
            ├── 9-14: "Moderate" → "Some signs of strain..."
            └── 15-999: "Mild" → "Your workload is manageable..."

format determines how scores are computed: sum (add all field scores), avg (average across fields), count (count specific option selections)
direction determines semantic meaning: positive (high = good, like "resilience") or negative (high = bad, like "burnout")
Data[] are the score ranges with labels and descriptions

The Direction Problem

Here's where it gets confusing. Consider two dimensions:

Burnout (negative direction, high = bad):

Score 5 (low) → Good state, low burnout
Score 25 (high) → Bad state, severe burnout

Resilience (positive direction, high = good):

Score 5 (low) → Bad state, low resilience
Score 25 (high) → Good state, high resilience

The question: when configuring score ranges, do you write them low-to-high or high-to-low? What does "low score" mean for each direction?

Attempt 1: Direction-Aware Configuration

Initially, the SKILL.md told the AI to configure ranges differently based on direction:

For positive dimensions: low score = worst, high score = best
For negative dimensions: low score = best, high score = worst

This was logical but confusing in practice. The AI would frequently mix up which direction meant what, especially in mixed-type assessments where some dimensions are positive and others are negative.

Result: roughly 30% of generated apps had at least one dimension with inverted ranges. Users with severe burnout would see "Your burnout is mild" because the ranges were flipped.

Attempt 2: Storage-Time Reversal

The solution that finally worked: unify the configuration convention and let the engine handle the reversal at storage time.

The rule is now dead simple for the AI:

Always configure ranges from lowest score (worst state) to highest score (best state).
The system automatically handles direction reversal internally.

# Burnout (negative direction) — ranges look the same as positive
assess scale add --id burnout --name "Burnout" \
  --format sum --direction negative

assess scale data add --scale burnout \
  --ranges "5-10:Severe:Burnout is high, seek support,11-18:Moderate:Some signs of strain,19-999:Mild:Burnout is low, keep it up"

Wait — "Severe" is at the low-score end? That doesn't make sense for burnout, where low scores mean you're fine.

Here's the trick: the system reverses the range labels when storing negative-direction dimensions. So the stored data becomes:

Stored (after reversal):
  5-10: Mild (low score = good for negative direction)
  11-18: Moderate
  19-999: Severe (high score = bad for negative direction)

The AI doesn't need to think about this. It writes ranges the same way for every dimension: low score = worst label, high score = best label. The engine flips it for negative dimensions.

Why This Works

One mental model. The AI always writes "low = worst, high = best." No conditional logic based on direction.
Direction is metadata, not configuration logic. --direction negative tells the engine "this is a symptom scale" — it's used for label reversal and report interpretation direction, not for range configuration.
The raw score always matches the stored ranges. After reversal, a user who scores 25 on burnout (high) correctly hits "Severe" because the stored ranges have "Severe" at the high end.

The `direction` Priority Rule

How does the AI decide if a dimension is positive or negative? The priority is:

Question wording (highest priority): "I feel exhausted" (symptom, high = worse) → negative. "I can cope with stress" (ability, high = better) → positive.
Plan declaration (secondary): Only when question wording is ambiguous.

This matters because the plan agent might declare a dimension as negative, but if the actual questions measure positive constructs ("I feel capable"), the direction should be positive. The SKILL.md explicitly states: when knowledge declaration and question semantics conflict, question semantics win.

The Ranges Continuity Bug

Score ranges must be continuous and non-overlapping:

✅ Correct:   3-6, 7-8, 9-999  (7 = 6+1, 9 = 8+1)
❌ Overlap:   3-6, 3-8, 9-999  (second range starts at 3, overlapping)
❌ Gap:       3-6, 9-999        (7-8 uncovered, users in this range get nothing)

The overlap bug was common. The AI would copy the first range's min as the second range's min instead of incrementing:

# Wrong — second range starts at 3 (copied from first range's min)
assess scale data add --scale workload \
  --ranges "3-6:Severe,3-8:Moderate,9-999:Mild"

# Correct — second range starts at 7 (previous max + 1)
assess scale data add --scale workload \
  --ranges "3-6:Severe,7-8:Moderate,9-999:Mild"

The engine now validates range continuity and rejects overlapping ranges with a clear error message.

The Unreachable Range Bug

Another classic: ranges based on theoretical scores instead of actual possible scores.

Knowledge says: "0-2 = Severe, 3-4 = Moderate, 5-6 = Mild"
But the form fields have min=1 (not 0), so the actual minimum score is 3
→ The "0-2: Severe" range is never reachable
→ Every user falls into "Moderate" or "Mild"
→ The "Severe" tier is dead code

The fix: before setting ranges, the scale skill must read the actual --min and --max values from form fields and compute the real score range:

// In the scale validation logic
int actualMin = 0;
int actualMax = 0;
for (Field f : associatedFields) {
    actualMin += f.getMinScore();
    actualMax += f.getMaxScore();
}
// Ranges must span [actualMin, actualMax]
// If actualMin = 3, ranges starting at 0 are unreachable

The SKILL.md now has a P0 rule:

ranges MUST be based on actual field scores. Read --options :score values from form-fields reference and compute the real min/max. NEVER use theoretical scores from knowledge.

The Sentinel Value

The highest range always uses 999 as its max:

5-10:Severe,11-18:Moderate,19-999:Mild

Why not use the actual maximum? Because floating-point rounding and edge cases. A user who scores 18.5 (from avg format) might not match 18 as a max boundary. 999 as a sentinel ensures the highest tier always catches everything above its minimum.

The engine treats 999 specially — it doesn't validate against the theoretical maximum, it just means "everything above this min."

The `count` Format Trap

Most dimensions use sum or avg. But count has a specific use case: counting how many times a specific option was selected.

# Count how many "Yes" answers in a checklist
assess scale add --id compliance --name "Compliance" \
  --format count --direction positive

# Each field's "Yes" option has score=1, "No" has score=0
# count format counts fields with score > 0

The trap: count doesn't sum scores. It counts non-zero fields. So if a field has --score 5, count treats it as 1 (non-zero), not 5. This is by design for binary checklists, but the AI would sometimes use count for regular scored questions, producing wrong totals.

The rule: count is for binary (yes/no) statistics only. For regular scoring, always use sum.

Lessons Learned

Unify the configuration convention. Don't make the AI think differently for positive vs negative. Let the engine handle the reversal.
Validate against actual data, not theoretical declarations. The plan agent might say "scores range 0-6" but the actual form fields produce 3-18. Always read from the source.
Range continuity is a validation problem, not an AI problem. Don't trust the AI to get min = previous_max + 1 right every time. Validate and reject.
Direction is metadata. It tells the engine how to interpret scores, not how to configure ranges. Keep it separate from the range configuration logic.

Next: [Connect Module — AI-driven cover pages and visual styles]

DEV Community: Keo Fung | FormLM

When Your AI Duplicates Every Field: A Story About Idempotency

What Happened

Why field_add Isn't Idempotent

The Fix: Find Before Add

Why Not Just Make field_add Idempotent?

The Idempotency Wrapper

The Deeper Lesson: AI Agents Need Idempotency Everywhere

The Cleanup

The Boolean Trap: When Your AI Literally Cannot Say "False"

The Setup

What Claude Did

The Root Cause

Why Claude Didn't Pass false

The Real Problem: Defaults That Bite

The Fix

The normBool Safety Net

The Pattern I Now Follow

MCP Tools, One Weekend: Stress-Testing an AI-Accessible Form Builder

The Task

Saturday: Building the Form

Tools used: app_create, field_schema, field_config, field_add (×11)

Tools used: field_list, field_move

Tools used: field_find

Sunday: Publishing and Cleanup

Tools used: share_publish, share_url, share_query

Tools used: share_unpublish, app_remove

What I Didn't Use

What Broke

The Scorecard

The find-then-set Pattern: How I Stopped My AI Agent From Breaking Fields

The Incident

Why This Happened

The Fix: find-then-set

The Full Pattern

When to Use update vs. set-property

The Bigger Lesson

I Let Claude Desktop Build My Entire Assessment Form. Here's What Happened.

The Setup

The Prompt

What Claude Did (Step by Step)

Step 1: Create the app

Step 2: Check available field types

Step 3: Add the exhaustion dimension (3 fields)

Step 4: Add cynicism and efficacy

Step 5: Publish

Where It Got Weird

What I Learned

[10/10]PDF Rendering War: SVG-to-PNG Conversion, Emoji Font Routing, and the iText NPE

Battle 1: The SVG NPE That Crashed Every Report

The Bug

The Root Cause

The Fix: SVG → PNG Conversion

The SvgToPngConverter

The viewBox Dimension Bug

Battle 2: Emoji Rendering in PDF

The Bug

The Root Cause

The Font Routing Problem

The Solution: Font Coverage Matrix

The setSplitCharacter Fix

Battle 3: Background Image SVG Compatibility

The Bug

The Root Cause

The Fix: Background SVG Cleaning

The Batik Namespace Requirement

The forPdf Context Flag

Lessons Learned

Series Conclusion

[9/10]SSE Reliability: Three Rounds of Fixing Event Loss in JAX-RS SseEventSink

The Setup

Round 1: The Missing await

The Bug

The Fix (Attempt 1)

Round 2: The Concurrent Write Crash

The Bug

The Fix (Attempt 2)

Round 3: The Virtual Thread Pinning

The Bug

The Final Fix: ReentrantLock + get(timeout)

Why `field_add` Isn't Idempotent

Why Not Just Make `field_add` Idempotent?

Why Claude Didn't Pass `false`

The `normBool` Safety Net

The `setSplitCharacter` Fix

Round 1: The Missing `await`

Why `get(10, SECONDS)` Instead of `join()`

Why Double-Check `hasEventSink()`

The `--enable` Flag

The `apply-all` Optimization

The `--type` vs `--page-id` Confusion

The `direction` Priority Rule