Kelly Portrait Retouch

Turn portraits into natural, reviewable candidates. Keep the original image and facial identity intact. Use the App as the review surface and the trusted CLI as the image-processing boundary.

Required Skills

1. Read and follow $kelly-app-skill-creator for the operator workflow, responsive UI, product onboarding, and visual acceptance contract.
2. Read and follow $busabase-app-creator for Busabase resource modeling, AirApp runtime limits, security, validation, synchronization, and deployment.
3. Use $kelly-app-skill-creator-tests for repository-level conformance, persistence, OSS Busabase, OAuth, and AirApp parity checks.

The approved product blueprint is product-overlay.md.

Defaults

• Use the natural preset at strength 35 unless the user asks otherwise.
• Create a new sibling file ending in _retouched; never overwrite by default.
• Strip EXIF/GPS metadata by default. Preserve metadata only when explicitly requested.
• Preserve face shape, age, skin tone, moles, freckles, scars, and other identity cues unless the user names a specific reversible edit.
• Do not whiten skin, enlarge eyes, shrink a face, or change body shape by implication. Ask before structural or identity-changing edits.
• Treat portraits as sensitive biometric data. Do not upload them to an external model unless the user explicitly approves that route.

Local CLI

Install once from the skill directory:

pnpm install --frozen-lockfile

Create one natural candidate:

node scripts/retouch.mjs portrait.jpg --preset natural --strength 35

Create a candidate and a side-by-side proof:

node scripts/retouch.mjs portrait.jpg --output exports/portrait-natural.jpg --compare exports/portrait-proof.jpg

Create a reusable processing summary, inspect the dry-run sync plan, then write the candidate through the trusted Busabase boundary:

node scripts/retouch.mjs portrait.jpg --compare exports/portrait-proof.jpg --summary exports/portrait-summary.json
node scripts/sync-candidate.mjs exports/portrait-summary.json
node scripts/sync-candidate.mjs exports/portrait-summary.json --apply

Use --face x,y,width,height when automatic face detection is unavailable or needs correction. Coordinates are image pixels after orientation is applied. Run node scripts/retouch.mjs --help for every option.

The CLI uses macOS Vision for face rectangles when available, then applies a subtle masked texture blend with Sharp. On other platforms it performs only whole-frame tone/detail polish unless --face is supplied. It never changes facial geometry.

Workflow

1. Inspect the source image at full resolution. Note blur, compression, clipping, mixed lighting, and whether the requested result is realistic.
2. Confirm any ambiguous identity-changing request. For ordinary “美颜”, use the natural defaults without asking.
3. Run the CLI and keep its JSON summary. Generate a comparison image when the user needs to judge strength.
4. Inspect the candidate at face scale and full-frame scale. Reject waxy skin, halos, flattened detail, color shifts, or softened eyes/hair.
5. Present the candidate and comparison for review. Iterate by reducing strength before adding more processing.
6. When Busabase is available, run the sync command as a trusted Agent. It uploads source/output/comparison files through Busabase Assets and upserts the jobs and candidates Bases with stable idempotency keys. Base rows store asset IDs, not image bytes or expiring URLs.
7. Export or replace only after the user names the approved candidate. Publishing remains outside this skill.

Presets

• natural: restrained tone lift and face-local texture softening; default.
• fresh: slightly brighter and more saturated for casual/social portraits.
• studio: neutral color, restrained contrast, and crisper detail for headshots.

Read retouch-policy.md before fulfilling a structural edit, processing a minor's portrait, or using an external image model.

App Contract

The canonical App source is in content/kelly-portrait-retouch-app/. It provides a quiet list/detail review desk with hash routes, before/after inspection, strength and preset metadata, approve/change/block decisions, bilingual chrome, phone navigation, and Help & Settings. ?demo=queue opens deterministic read-only data.

Busabase resources:

• Folder kelly-portrait-retouch owns the workflow.
• Base jobs stores one row per local processing request and its lifecycle.
• Base candidates stores candidate provenance, checks, and human verdicts.
• Base settings stores non-secret defaults and onboarding state.
• Busabase Assets stores source, candidate, and comparison files; Base records keep their stable asset IDs.

The browser never receives filesystem access, API keys, or Vault values. The trusted Agent runs the CLI and performs content-addressed asset upload plus idempotent record writes. The App only reads approved state and records human decisions through stale-version-protected ChangeRequests. Runtime readiness and product onboarding are separate; incomplete onboarding suppresses workflow rows.

Validation

Run:

pnpm test
pnpm --dir content/kelly-portrait-retouch-app check
node scripts/retouch.mjs --help
node scripts/sync-candidate.mjs --help