Ephemeral Engineering

ephemeral-eng — Input-to-Deliverable Engineering Tools

You are building a single self-contained HTML file that is simultaneously an engineering calculator and the final client deliverable. No build step, no dependencies, no server. The user opens it in a browser, types inputs on the left, and the paginated report on the right is what they print to PDF and issue.

Start from the template. Read template/ephemeral-template.html in this repo (or ask the user for their latest tool as a base). Never invent a new layout — consistency across tools is the product.

Non-negotiable safety rules

1. Every tool ships UNVERIFIED. Include the draft-watermark checkbox (default ON) and the footer note stating the tool must be verified per VERIFICATION.md before use. Never remove these; never default the watermark off.
2. Tell the user, every time, in your final message: the tool is unverified until they complete the VERIFICATION.md checklist, including a digit-for-digit hand-calc match.
3. Never fabricate code values. If you are not certain of a coefficient, table value, or code section (ASCE 7, NDS, ACI, AISC, ADM, IBC/FBC…), leave a clearly marked input for the engineer to enter it (enter from Table X) instead of hard-coding a guess. A blank the engineer must fill is safe; a wrong constant is not.
4. Decline scope creep. If asked for FEA, dynamic/seismic response, nonlinear or coupled-system analysis, say the framework is intentionally limited to simple, hand-verifiable checks and suggest validated commercial software.
5. When editing an existing tool, change only what was asked and list every functional change you made (the user will diff the file). Bump the version.

The five slots

The template marks five slots. Fill only these; leave framework chrome alone.

Report standards (the deliverable)

• US Letter pages: .report-page at 8.5×11in, page-break-after:always, branded footer on every page (footer(pg, of, d) helper), watermark via wm(d).
• A reviewer must be able to check the report without the tool. Show every input, every assumption (code edition, ASD/LRFD, load combos, what's excluded e.g. self-weight), and every calc step with substituted numbers: M = wL²/8 = 100 × 12²/8 = 1,800 lb·ft — never just the answer.
• Structure: (1) firm header + project block + design basis + inputs, (2) section properties → demands → checks as .calc-step blocks with .ref code citations → summary .calc-table with DCR + PASS/FAIL cells → conclusion box → signature block with stamp placeholder, (3+) appendix exhibits (drag-drop images) only if provided.
• All numbers through num(x, dp); all user text through esc(s). Never interpolate raw user input into HTML.

Engine conventions

• ASD vs LRFD/strength must be explicit in labels, basis paragraph, and comments. Never mix.
• Trap-check yourself before finishing: psf↔psi, plf↔lb/in, ft↔in (especially in L⁴ deflection terms), nominal vs actual dimensions, service vs strength wind pressures.
• Interpolations: clamp or warn outside table ranges — never extrapolate silently.
• validate() must catch: non-positive dimensions/loads/design values, and at least one absurdity check relevant to the domain (e.g. span-to-depth > 50).

Input JSON (state save/load) — mandatory framework chrome

Every tool keeps the template's JSON module (serializeInputs / exportJSON / importJSON + the "Save inputs / Load inputs" buttons). It exports every f_* input (and dropped images) to a portable file:

{
  "_meta": { "framework": "ephemeral-eng", "tool": "", "toolVersion": "V1.2",
             "saved": "ISO-8601", "source": "user" },
  "inputs": { "f_L": "12", "f_w": "100", "f_draft": true },
  "images": { "logoData": null, "imgData": null }
}

Why it matters: the calculator can be disposable because the project state is portable — archived with the job, re-loaded next revision, or moved into the next version of the tool.

AI pre-generation workflow: when a user gives you plan notes, an architect's email, or project docs and asks you to prep a calc, you may emit this JSON directly (keys = the tool's f_* ids) so they load it and review instead of typing. Rules:

1. You MUST set "_meta.source": "ai" — the tool then displays a persistent verify-every-value warning until the engineer edits the inputs. Never set "user" for machine-generated files.
2. Only fill values you can trace to the provided documents; leave unknown fields out (the tool keeps its defaults) rather than guessing.
3. List, in your reply, every value you filled and the document/line it came from.

Versioning & naming

File name: {ProjectNo_}ToolName_vX_Y.html (e.g. V26150_Footing_Check_v1_0.html). Version appears in ``, the panel version-badge, FIRM.toolVersion, and the report footer. Any functional change bumps the version; note what changed in a comment block at the top.

Workflow when a user requests a new tool

1. Interview briefly: what's being checked, governing code + edition, ASD or LRFD, inputs they want exposed vs fixed, deliverable type (calc report vs evaluation letter), branding (or reuse their existing tokens).
2. State your calculation plan in plain English first — formulas, code sections, assumptions — and get confirmation before writing code. This is where the engineer catches wrong physics cheaply.
3. Build from the template, filling the five slots.
4. Self-check: run the engine mentally (or with a script if you have code execution) on the default inputs and one boundary case; confirm units line by line.
5. Deliver with: (a) the file, (b) a list of every formula + code reference used, (c) explicit assumptions/exclusions, (d) the unverified-tool warning and a pointer to VERIFICATION.md.

Letter-generator variant

For evaluation/compliance letters (vs calc reports): first page is prose letterhead (addressee block, purpose & scope, numbered sections, conditions of acceptance, conclusion), calc detail moves to an "Exhibit — Calculations" appendix of .calc-step blocks, and exhibits get cover pages. Same slots, same rules.