# Continuation handoff

## Current state

Project: `/home/admin/project/web3dmodel/gpt6-astra-pro-mcp-alagent-portrait-studio`.

The character is an actual, static, textured 3D mesh with a responsive web viewer. **The requested 20,000 visual iterations and >95/100 likeness have not been achieved.** Read `public/progress.json` for the exact current count and latest subjective estimate. Failed and regressive reviews are intentionally retained. Never relabel a regression as an improvement or count edits that were not rendered and visually inspected.

The main remaining problems are the hair's overly regular card distribution, cap/temple transitions, facial likeness, limited skin realism, and symmetric body pose. The current mesh is not a finished rigged game character. Head proportions and nose/lip controls have been refined; the model remains an approximation of the supplied reference.

## Continue safely

Use the local `mcp_alagent` workspace above. Read its server instructions and `/home/admin/Agents.md` before working. This VM is shared: do not terminate other projects' browsers, alter other services, or overwrite unrelated files. The original reference is private and must be obtained from the user or the private Library record; it is not part of the public archive. Inspect it with native vision only. Do not run image measurements, image-to-3D services, OCR, image generation, or texture projection on it.

Start by reading `README.md`, `public/progress.json`, and the newest `public/previews/rev-NNN/review.json` and `validation.json`. View the newest contact sheet and the full front/portrait images. The browser captures are actual rendered evidence, not generated illustrations.

## Key source files

`tools/build-anatomy.mjs` fits and poses the CC0 base mesh and eyes. The complete hands are selected in the **unposed anatomical region**, not by partial bone-name lists: revision 020 demonstrated why the incomplete palm mask was wrong. Do not reintroduce that mask.

`tools/fit-core-assets.mjs` fits the scalp and eyelashes. `src/groom.js` builds flowing hair layers, temple bridges, and individual fibers. `src/fringe.js` adds irregular fine bangs. `src/proportions.js` applies a smooth head sculpt with an analytic normal transform. `src/face.js` fits brow detail to the constructed face.

`tools/fit-blouse.mjs` applies the same pose to the CC0 blouse, relaxes its torso envelope, and tucks the waist. `src/blouse.js` adds normal/AO materials, buttons, placket, and pocket. `src/garments.js` is the independent 20-pleat skirt. Never change sleeve or wrist pose without rechecking cuffs and hands from all sides.

`src/main.js` is the viewer. Production builds load the prepared GLB through `src/released-character.js`; development builds construct the mesh from the source. This avoids reconstructing hair geometry on each production page load. Export metadata deliberately omits live material-object references.

## Rebuild, inspect, and commit

```sh
export PATH=/home/admin/.nvm/versions/node/v22.23.2/bin:$PATH
npm run prepare:model
PLAYWRIGHT_BROWSERS_PATH="$PWD/.cache/browsers" npm run capture -- NNN
node tools/contact.mjs NNN
# Visually inspect all six views before recording a defensible estimate.
node tools/record-review.mjs N SCORE "Title" "Evidence and remaining defects"
git add src tools public docs
 git commit -m "Review NNN: specific change and outcome"
```

Use the next unused numeric revision. The capture tool refuses to overwrite an already reviewed revision by default. A capture error is not a completed visual iteration. Do not perform thousands of uninspected parameter changes and claim they meet the requested iteration count.

## Validation and persistence

`npm run qa` exercises the viewer and exports a GLB, then runs the glTF Validator. It records browser errors, desktop/mobile-width layout checks, camera/material controls, and PNG/GLB downloads. These are headless Chromium/software-renderer checks, not measurements of a physical phone or a guarantee of a frame rate.

`npm run build` writes the static release to `dist/`. `npm run archive` writes the source archive and a versioned copy under `/home/admin/Library/project/gpt6-astra-pro-mcp-alagent-portrait-studio/`. It excludes caches, dependencies, secrets, and the original reference. `tools/chunk-release.mjs` divides large release files for durable KV storage; `tools/publish-worker-assets.mjs` verifies transferred byte counts and SHA-256 hashes.

## Running services

The development server is `gpt6-portrait-studio.service`, serving loopback port 4178. Its source unit is in `docs/portrait-studio.service`. It is proxied by the dedicated Caddy site `4178-portrait.alima.freeddns.org`. Cloudflared's temporary URL is recorded in `.cache/cloudflared.log`; do not assume that temporary hostname survives a tunnel restart.

The persistent cloud release uses Worker `gpt6-astra-pro-mcp-alagent-portrait-studio` on `testcatty.workers.dev` and its dedicated KV namespace. `docs/cloud-worker.mjs` is the read-only, origin-independent serving code. Upload through a temporary, fixed-origin deployment bridge, verify every asset, then restore the independent serving code. Do not expose a general upload endpoint, API token, or private reference image. Read the connected account/namespace state before deployment rather than guessing IDs.

For Cloudflare Code Mode multipart uploads, `cloudflare.request` uses **`contentType` and `rawBody: true`**, not an arbitrary `headers` field. A new asset prefix avoids mixed releases. The archive and large artifacts are served as stored chunks with byte-range support.

See `docs/ASSET-LICENSES.md` for active CC0 assets and the retired revision-005 trial. Do not reintroduce the ambiguous historical hair asset into the release.