How to Build a Premium 3D Website with Hermes Agent

Set up this project to generate images through the Higgsfield API with the Soul 2 model.

Read the official SDK documentation at https://docs.higgsfield.ai/docs/how-to/sdk and
the model reference at
https://open.higgsfield.ai/models/higgsfield-ai/soul/v2/standard/api-reference before
implementing.

1. The website itself stays plain HTML, CSS and JavaScript with no build step. Put the
   generation tooling in its own folder, tools/higgsfield/, as a small Node project with
   ES modules: install @higgsfield/client and dotenv there, and nothing in the website
   folder.
2. Give me a safe way to add my key without it ever passing through this chat. Create
   tools/higgsfield/set-key.mjs and an npm script "set-key" that, run in my own
   terminal, asks "Paste your Higgsfield API key (KEY_ID:KEY_SECRET):" with the typed
   input hidden, ignores control characters that pasting can add, checks it has the
   KEY_ID:KEY_SECRET shape (exactly one colon, no spaces, text on both sides), writes it
   as HF_CREDENTIALS=... to tools/higgsfield/.env.local with file permissions 600
   (readable only by me), and replies only "Key saved" without echoing any part of it.
   Add .env.local and node_modules to .gitignore, and add a .env.example with an empty
   HF_CREDENTIALS= line. Then stop and tell me, in plain steps: get an API key at
   https://open.higgsfield.ai (sign in, open API keys, create one, copy the key id and
   secret), open a terminal in the project, run "cd tools/higgsfield && npm run
   set-key", wait until the question appears (anything pasted before it shows on
   screen), paste the key, press Enter, and tell you when it says "Key saved". Do not
   run set-key yourself, because anything typed into a command you run passes through
   this chat. Never ask me to paste the key into chat, and never read, print, log or
   commit it or the .env.local file; to check it exists, only test for the file and the
   HF_CREDENTIALS name. The key is used only by the Node tool, never by the website or
   the browser.
3. Create tools/higgsfield/generate.mjs. First load .env.local with dotenv using {
   quiet: true } (dotenv never overrides a variable that is already set). Then import {
   config, higgsfield } from "@higgsfield/client/v2" and call config({ credentials:
   process.env.HF_CREDENTIALS, maxPollTime: 600000, maxRetries: 0 }): the SDK's default
   of 5 minutes gives up on slow jobs that are already paid for, and its default retries
   silently resubmit a failed request up to 3 times, which can pay for the same image
   twice. Use higgsfield.subscribe("higgsfield-ai/soul/v2/standard", { input: { ... },
   withPolling: true }). With this v2 client, subscribe returns the raw API response:
   check its status ("completed", "failed" or "nsfw", which means moderated and
   refunded) and read the image from images[0].url; the isCompleted and jobs[0] shape
   shown in the SDK README does not apply. Download the image to a file. Take the
   prompt, aspect ratio and output path as arguments so the next prompts can reuse the
   script. Treat failed, moderated or errored requests as failures and never claim
   success for them. Never print or log a caught error object, because SDK errors carry
   the request including the Authorization header with the key; print only the error's
   name, status and message. If submitting a request answers with a 5xx error, wait a
   minute and try again. If a 5xx comes while you wait for a request that was already
   accepted, keep its request id and check that request's status again instead of
   submitting a new one, which would be paid again.
4. Run one test image: the prompt "a red apple on a white table, plain photograph",
   aspect_ratio "1:1", resolution "720p", batch_size 1 and enhance_prompt false. This is
   a billable request of a fraction of a cent; save it in tools/higgsfield/test-output/.
   Verify it completes, the file exists, and show me the image. "720p" comes back at
   about 1536 pixels on a side; that is expected. Do not claim the setup works unless
   you ran it successfully; if execution is blocked, report the blocker.

You are working on my Linux server and I am sitting at a different computer, so before
anything else we need a door: one place where I hand you files and one address where I
watch what you build. Build both now, in the project, with Python's standard library
only, no framework, no extra packages.

Write tools/preview/server.py and run it on port 8901. It does two jobs:
- It serves the website folder at / , so the site we are about to build is live at that
  port from the first prompt to the last. Until the site exists, / answers with a plain
  "nothing built yet" page rather than a stack trace.
- GET /upload serves a small self-contained upload page, inline CSS and JavaScript, no
  CDN and no libraries, but make it pleasant rather than a bare form: a large
  drag-and-drop area that highlights on hover and also opens a file picker when clicked,
  the name and size of each file as it goes up, a clear tick when it lands, and a short
  line saying where the file was saved.
- POST /api/upload takes the file from that page as JSON {name, data}, where data is the
  data URL a FileReader produces, and saves it into the project's reference folder
  keeping the original filename.

SECURITY, NON-NEGOTIABLE: bind to 127.0.0.1 only, never 0.0.0.0. Do not open a port in
the firewall, do not put nginx or any other reverse proxy in front of it, and do not
expose it to the internet. This page writes files into the project and has no login, so
the SSH tunnel is the only door and my key is the lock. Accept only image files (.png,
.jpg, .jpeg, .webp), reject anything over 25 megabytes, and reject any filename
containing a slash or two dots, so nothing can be written outside the reference folder.

One trap that makes the upload look broken while it is working: a screenshot is a few
megabytes, so read the whole request body up to its Content-Length before you answer,
and set Content-Length on your own response. A handler that saves the file and closes
the socket early reports failure in the browser although the file landed, which is the
worst kind of bug, because both halves are half right.

Start it so it survives a reboot and restarts if it dies: a user systemd service if this
machine has one, otherwise nohup with a line in crontab @reboot. If the port is already
taken, say so loudly and stop rather than picking another one silently, because every
later prompt refers to this port. Check it yourself with curl on the server before you
tell me anything.

Then teach me the door. Print the exact tunnel command for THIS machine with my real
username and this server's real address filled in, the actual values, which you look up
yourself, never a placeholder: the shape is

ssh -N -L 8901:127.0.0.1:8901 <username>@<server-address>

and tell me to run it in a terminal on my own computer and leave it open. Then give me
the two addresses I will use for the rest of the project: http://localhost:8901/upload
to hand you files, and http://localhost:8901/ to watch the site.

Then STOP and wait. I will open the upload page and drop in one screenshot of the
finished website, which is the reference image for the next prompt. When it lands, tell
me the filename you received and where you saved it, and wait for my next prompt. Do not
build anything else yet.