Merge origin/main into feat/humanized-figure

Resolve comment-only conflicts in mannequin.ts: keep the rewritten
figure doc comments and adopt main's no-em-dash comment style.

Author: a-baran-orhan

README.md

@@ -1,21 +1,22 @@
 <h1 align="center">◆ Posecode</h1>
 
 <p align="center"><b>Kinematic motion as text.</b> Mermaid gave LLMs a way to draw diagrams.<br/>
-Posecode gives them a way to <i>show movement</i> — exercises, physiotherapy, posture —<br/>
+Posecode gives them a way to <i>show movement</i>: exercises, physiotherapy, posture,<br/>
 as a tiny human-readable language that renders to an animated 3D figure in the browser.</p>
 
 <p align="center">
   <a href="https://posecode.org/play"><b>▶ Live playground</b></a> ·
-  <a href="spec/SPEC.md">Language spec</a> ·
+  <a href="https://posecode.org/moves/">Movement library</a> ·
+  <a href="https://posecode.org/spec.html">Language spec</a> ·
   <a href="spec/examples">Examples</a> ·
   <a href="packages/posecode-mcp">MCP server</a>
 </p>
 
 <table align="center">
   <tr>
-    <td align="center"><img src="docs/media/deadlift.gif" width="230" alt="Deadlift rendered from .posecode text"/><br/><sub><code>pelvis: hinge</code> — deadlift</sub></td>
-    <td align="center"><img src="docs/media/squat.gif" width="230" alt="Body-weight squat rendered from .posecode text"/><br/><sub><code>knees: flex 95</code> — squat</sub></td>
-    <td align="center"><img src="docs/media/lateral-raise.gif" width="230" alt="Lateral raise rendered from .posecode text"/><br/><sub><code>shoulders: abduct 90</code> — lateral raise</sub></td>
+    <td align="center"><img src="docs/media/deadlift.gif" width="230" alt="Deadlift rendered from .posecode text"/><br/><sub><code>pelvis: hinge</code>, deadlift</sub></td>
+    <td align="center"><img src="docs/media/squat.gif" width="230" alt="Body-weight squat rendered from .posecode text"/><br/><sub><code>knees: flex 95</code>, squat</sub></td>
+    <td align="center"><img src="docs/media/lateral-raise.gif" width="230" alt="Lateral raise rendered from .posecode text"/><br/><sub><code>shoulders: abduct 90</code>, lateral raise</sub></td>
   </tr>
 </table>
 
@@ -25,13 +26,13 @@ as a tiny human-readable language that renders to an animated 3D figure in the b
 
 Ask an LLM to explain a push-up and it can only give you prose or a flat image.
 The model *knows* the biomechanics ("elbows flex, shoulders abduct on the
-descent") — it just has no syntax to express it that a renderer can read.
+descent"), it just has no syntax to express it that a renderer can read.
 Diffusion-based text-to-motion models exist, but they're heavy, expensive, and
 give you no fine control over the anatomical phases.
 
 Posecode takes the opposite, lightweight approach (see [the research](#background)):
 
-- The LLM writes a small **`.posecode`** document — semantic phases, not 3D matrices.
+- The LLM writes a small **`.posecode`** document: semantic phases, not 3D matrices.
 - A **client-side** parser + Three.js renderer animates it. Generation is a
   fraction of a cent of text; rendering runs at 60fps on a phone.
 - Every angle is **hard-clamped to a healthy range of motion**, so a model
@@ -70,17 +71,17 @@ npm run eval     # fidelity scorecard: geometric invariants over every example
 
 In the playground: pick an example, watch it animate, edit the text live, and
 hit **Copy LLM prompt** to get a system prompt that teaches ChatGPT/Claude to
-write Posecode for you — or wire up the [MCP server](packages/posecode-mcp) so
+write Posecode for you, or wire up the [MCP server](packages/posecode-mcp) so
 your agent authors, validates, and renders movements natively.
 
 ## How Posecode stays honest
 
 Two safety layers ship with the language:
 
-- **ROM clamping** — every angle is hard-clamped to healthy range-of-motion
+- **ROM clamping**: every angle is hard-clamped to healthy range-of-motion
   tables before rendering; a hallucinated `knee: flex 200` renders at its
   ceiling with a warning, never an impossible joint.
-- **Fidelity evals** — [`posecode-eval`](packages/posecode-eval) re-runs the
+- **Fidelity evals**: [`posecode-eval`](packages/posecode-eval) re-runs the
   real parser → FK → ground-lock pipeline headlessly and scores geometric
   invariants ("a deadlift pitches the torso ≥ 50° with vertical shins"). Every
   example must pass every invariant in CI.
@@ -92,11 +93,11 @@ Two safety layers ship with the language:
 | [`posecode-parser`](packages/posecode-parser) | `.posecode` text → validated, ROM-clamped IR. Pure TypeScript, framework-agnostic. |
 | [`posecode-render`](packages/posecode-render) | IR → animated low-poly mannequin (Three.js), forward kinematics + ground-lock CCD IK. |
 | [`posecode-share`](packages/posecode-share) | Encode a `.posecode` doc to a URL-safe token so a movement travels as a link. Pure, dependency-free. |
-| [`posecode-mcp`](packages/posecode-mcp) | MCP server: lets an LLM agent author, ROM-validate, and get a render link for a movement — natively. |
+| [`posecode-mcp`](packages/posecode-mcp) | MCP server: lets an LLM agent author, ROM-validate, and get a render link for a movement, natively. |
 | [`posecode-eval`](packages/posecode-eval) | Fidelity harness: headless kinematic probing + biomechanical invariant scoring. |
 | [`playground`](playground) | Live editor + 3D viewport + warnings + the LLM prompt + shareable links. |
 
-The protocol and both libraries are **MIT-licensed** — the open core. See
+The protocol and both libraries are **MIT-licensed**: the open core. See
 [`spec/SPEC.md`](spec/SPEC.md) for the full language and
 [`spec/llm-authoring.md`](spec/llm-authoring.md) for the authoring prompt.
 For where Posecode spreads fastest and the per-domain go-to-market plan, see

ROADMAP.md

@@ -1,59 +1,59 @@
-# Posecode — domains & roadmap
+# Posecode: domains & roadmap
 
 Posecode's vision is broad: **describe any single-person movement as text and render it
 safely in 3D.** The *protocol* is general; the *current renderer* is deliberately
 scoped (one figure, forward kinematics, ground-locked hands/feet, no props). This
 doc maps the domains Posecode can serve, what already works, and what each remaining
-domain needs — so contributions land where they unlock the most.
+domain needs, so contributions land where they unlock the most.
 
 ## Where Posecode fits
 
 | Domain | Example uses | Status |
 | --- | --- | --- |
-| **Physiotherapy / rehab** | Range-of-motion demos, home-exercise programs, post-op protocols, cervical/shoulder mobility | ✅ Strong fit today — the ROM safety clamp is a clinical feature. Many moves render now; equipment (bands, balls) is future. |
+| **Physiotherapy / rehab** | Range-of-motion demos, home-exercise programs, post-op protocols, cervical/shoulder mobility | ✅ Strong fit today: the ROM safety clamp is a clinical feature. Many moves render now; equipment (bands, balls) is future. |
 | **Ergonomics / desk & posture** | Posture resets, seated/standing stretch breaks, "do this every hour" prompts | ✅ Works today for standing variants; true *seated* needs a chair prop (below). |
 | **Yoga & mobility** | Standing poses (chair, side bend, twist), flows, mobility drills | ✅ Standing poses work; floor/inversion/lying poses need lying base poses + a mat. |
-| **Movement education / anatomy** | Demonstrate joint actions ("what is shoulder abduction?"), biomechanics teaching | ✅ Excellent fit — single-joint demos are exactly what the rig does. |
+| **Movement education / anatomy** | Demonstrate joint actions ("what is shoulder abduction?"), biomechanics teaching | ✅ Excellent fit: single-joint demos are exactly what the rig does. |
 | **Fitness / strength** | Body-weight and free-form movement coaching | ✅ Core today (squat, curl, raise). Barbell/dumbbell/machine work needs props + grip. |
-| **Functional / elderly care** | Sit-to-stand, balance, gentle ROM, fall-prevention drills | 🟡 Partial — sit-to-stand works; reaching/balance need reach-IK + props. |
-| **Sports technique** | Golf swing, tennis serve, throwing, kicking | 🟡 Partial — needs trunk rotation fidelity, weight shift, and implements (club/racket/ball). |
+| **Functional / elderly care** | Sit-to-stand, balance, gentle ROM, fall-prevention drills | 🟡 Partial: sit-to-stand works; reaching/balance need reach-IK + props. |
+| **Sports technique** | Golf swing, tennis serve, throwing, kicking | 🟡 Partial: needs trunk rotation fidelity, weight shift, and implements (club/racket/ball). |
 | **Dance / choreography** | Notating sequences, port de bras, phrases that turn & travel | ✅ Phrases, port de bras, pirouettes, and traveling combos (box-step, grapevine, chassé) work via `turn`/`travel`; partner work is future. |
 | **Martial arts** | Stances, strikes, basic forms | 🟡 Stances/strikes partly work; contact and weapons are future. |
-| **Sign language / gesture** | Finger-spelling, signs, expressive gesture | 🟡 Partial — single-DOF finger curls render visibly (fist, pinch, wave, rough finger-spelling); exact sign language needs multi-joint fingers + wrist orientation. |
+| **Sign language / gesture** | Finger-spelling, signs, expressive gesture | 🟡 Partial: single-DOF finger curls render visibly (fist, pinch, wave, rough finger-spelling); exact sign language needs multi-joint fingers + wrist orientation. |
 
 ## Engine capabilities that widen the scope
 
 These are the unlocks, roughly in order of leverage:
 
-1. ~~**Hip / waist hinge primitive**~~ — ✅ **shipped (v0.1).** `pelvis: hinge <deg>`
+1. ~~**Hip / waist hinge primitive**~~: ✅ **shipped (v0.1).** `pelvis: hinge <deg>`
    tips the torso forward over the hips while the legs stay planted (the renderer
    counter-rotates the hips). Powers `deadlift`, `bent-over-row`, `good-morning`,
    and `bow`. Next: hinge with a loaded-bar prop.
-2. ~~**Reach-IK (reach a world target)**~~ — ✅ **shipped, now ROM-constrained.**
+2. ~~**Reach-IK (reach a world target)**~~: ✅ **shipped, now ROM-constrained.**
    `reach: <effector> <target>` drives a hand/foot to a body landmark, the
    `floor`, or a prop anchor via CCD. Powers `touch-toes`, `cross-body-reach`,
    `seated-forward-fold`, and prop grips. The solve clamps every chain joint
-   into its Range-of-Motion box each iteration — solved angles obey the same
-   hard limits as authored ones — and `hands` / `feet` reach or pin both sides
+   into its Range-of-Motion box each iteration; solved angles obey the same
+   hard limits as authored ones, and `hands` / `feet` reach or pin both sides
    in one line. Next: two-bone analytic solve for straighter elbows/knees.
-3. ~~**Scene props with contact anchors**~~ — ✅ **shipped (starter set).** `prop
+3. ~~**Scene props with contact anchors**~~: ✅ **shipped (starter set).** `prop
    chair|wall|bar` adds a scene object with named anchors (`seat`, `wall`, `bar`).
    Powers `sit-to-stand`, `box-squat`, `wall-sit`, `dead-hang`, `hanging-knee-raise`.
    Next: more props (bench, rings, bands), load cues, anchor-aware ground-lock.
-4. ~~**Lying & seated base poses**~~ — ✅ **shipped.** `supine | prone | seated`
+4. ~~**Lying & seated base poses**~~: ✅ **shipped.** `supine | prone | seated`
    start poses (grounded by a bounding-box drop). Powers `glute-bridge`,
    `dead-bug`, `cobra`, `seated-forward-fold`. Next: quadruped + chair-seated.
-5. ~~**Hand / finger articulation**~~ — ✅ **shipped (single-DOF).** Per-finger
+5. ~~**Hand / finger articulation**~~: ✅ **shipped (single-DOF).** Per-finger
    curl bones + `fingers` group. Powers `make-a-fist`, `pinch-grip`, `hand-wave`,
    `finger-spell-demo`. Next: multi-joint fingers for accurate sign language.
-6. ~~**Spatial choreography (turn & travel)**~~ — ✅ **shipped.** `turn: <deg>`
+6. ~~**Spatial choreography (turn & travel)**~~: ✅ **shipped.** `turn: <deg>`
    rotates the figure's facing and `travel: <x> <z>` moves it across the floor,
    both absolute + carried across phases and returning home on the loop wrap.
    Powers `pirouette`, `box-step`, `grapevine`, `waltz-box`, `chasse`,
-   `walk-cycle`, `quarter-turns` — pirouettes, traveling combos, and gait.
+   `walk-cycle`, `quarter-turns`: pirouettes, traveling combos, and gait.
    Standing poses only. Next: footstep-locked travel (true gait), motion
    aliveness (velocity-continuous flow + weight shift).
-7. **Two-person + collision** — partner stretches, assisted rehab, contact sports
+7. **Two-person + collision**: partner stretches, assisted rehab, contact sports
    (still deferred in the spec).
 
 ## Prop / equipment library (future)
@@ -72,17 +72,17 @@ Each prop is a small scene object + an anchor type; movements then reference it
 | **Resistance band** | Band pull-aparts, banded rehab, mobility with tension |
 | **Dumbbell / barbell / kettlebell** | Loaded strength patterns (needs grip + load cues) |
 | **Ball (stability / medicine)** | Core work, balance, throws |
-| **Parallettes / dip station** | ✅ Dip bars shipped (`prop dip-bars` — triceps dips). Still future: L-sits, push-up variations at height |
+| **Parallettes / dip station** | ✅ Dip bars shipped (`prop dip-bars`, triceps dips). Still future: L-sits, push-up variations at height |
 | **Foam roller** | Self-myofascial release, mobility drills |
 
 ## Current limitations (honest)
 
 - One figure only; partner work and collision are still deferred.
-- A **starter** prop set (chair / wall / bar / box / dip bars) — no bench,
+- A **starter** prop set (chair / wall / bar / box / dip bars): no bench,
   rings, bands, or loaded implements yet, and props sit at fixed default
   placements.
 - Props are visual + reach anchors (no physical sit/lean solve).
-- Fingers are **single-DOF** curls — good for grip and rough gesture, not exact
+- Fingers are **single-DOF** curls, good for grip and rough gesture, not exact
   sign language. The head has no facial articulation.
 
 > Range-of-motion values are general literature data, not medical advice.

VERCEL_AGENTS.md

@@ -1,4 +1,4 @@
-# Vercel Plugin — AI Agent Instructions
+# Vercel Plugin: AI Agent Instructions
 
 > Drop this file into any GitHub repo. AI coding agents (Claude Code, Codex, Cursor, Copilot, Grok Build) will pick it up automatically.
 
@@ -22,25 +22,25 @@ Requires Node.js 18+ and Bun. After install, session context is injected automat
 
 ## Key skills (invoke on demand)
 
-- `nextjs` — App Router, Server Components, Server Actions, rendering strategies
-- `ai-sdk` — AI SDK v6: streaming, tool calling, agents, MCP, embeddings
-- `ai-gateway` — Unified API to 100+ models with failover and cost tracking
-- `vercel-functions` — Serverless, Edge, Fluid Compute, streaming, Cron Jobs
-- `vercel-storage` — Blob, Edge Config, Neon Postgres, Upstash Redis
-- `deployments-cicd` — Deploy, promote, rollback, `--prebuilt`, CI config
-- `env-vars` — `.env` files, `vercel env`, OIDC tokens
-- `routing-middleware` — Rewrites, redirects, personalization (Node.js/Edge/Bun)
-- `runtime-cache` — Per-region KV cache with tag-based invalidation
-- `shadcn` — shadcn/ui CLI, components, theming, Tailwind integration
-- `workflow` — Durable execution, DurableAgent, steps, pause/resume
-- `vercel-sandbox` — Ephemeral VMs for running untrusted/AI-generated code
-- `verification` — Browser, API, data, and response flow verification
+- `nextjs`: App Router, Server Components, Server Actions, rendering strategies
+- `ai-sdk`: AI SDK v6: streaming, tool calling, agents, MCP, embeddings
+- `ai-gateway`: Unified API to 100+ models with failover and cost tracking
+- `vercel-functions`: Serverless, Edge, Fluid Compute, streaming, Cron Jobs
+- `vercel-storage`: Blob, Edge Config, Neon Postgres, Upstash Redis
+- `deployments-cicd`: Deploy, promote, rollback, `--prebuilt`, CI config
+- `env-vars`: `.env` files, `vercel env`, OIDC tokens
+- `routing-middleware`: Rewrites, redirects, personalization (Node.js/Edge/Bun)
+- `runtime-cache`: Per-region KV cache with tag-based invalidation
+- `shadcn`: shadcn/ui CLI, components, theming, Tailwind integration
+- `workflow`: Durable execution, DurableAgent, steps, pause/resume
+- `vercel-sandbox`: Ephemeral VMs for running untrusted/AI-generated code
+- `verification`: Browser, API, data, and response flow verification
 
 ## Specialist agents
 
-- `deployment-expert` — CI/CD, deploy strategies, environment variables, rollbacks
-- `performance-optimizer` — Core Web Vitals, caching, rendering, asset optimization
-- `ai-architect` — AI app design, model selection, streaming, MCP integration
+- `deployment-expert`: CI/CD, deploy strategies, environment variables, rollbacks
+- `performance-optimizer`: Core Web Vitals, caching, rendering, asset optimization
+- `ai-architect`: AI app design, model selection, streaming, MCP integration
 
 ## Platform defaults to assume
 

docs/brand/README.md

@@ -0,0 +1,38 @@
+# Posecode brand kit
+
+The Posecode logo is a **kinematic figure in an open, energetic pose**: bones as
+strokes, joints connected, the same rig the app animates. It hints at the
+project (human movement) while staying friendly and legible down to 16px. It is
+the exact mark used in the site's nav, favicon, and app icon: one logo,
+everywhere, no separate "tiled" variant.
+
+## Palette
+
+| Token | Hex | Use |
+| --- | --- | --- |
+| Lime | `#c6f24a` | The figure / accent |
+| Ink | `#0a0d12` | Dark background |
+
+Type: **Hanken Grotesk** (wordmark), **JetBrains Mono** (code).
+
+## Files
+
+| File | What it is |
+| --- | --- |
+| `posecode-mark.svg` | The logo, `currentColor` so it inherits the surrounding text color. Source of truth for inline use. |
+| `posecode-icon-512.png` | The logo as a flat-lime PNG on a transparent background. Use for READMEs, avatars, anywhere. |
+| `posecode-social.png` | 1280×640 GitHub social preview (logo + wordmark + tagline). |
+
+The live favicon (`playground/public/favicon.svg`, plus `favicon-16/32/48/192/512.png`)
+and the iOS icon (`playground/public/apple-touch-icon.png`) use this same figure.
+The SVG favicon adapts to the tab color (lime on dark UI, ink on light) so it
+stays legible without a background tile.
+
+## Using them on GitHub
+
+- **Repo social preview:** Settings → General → Social preview → upload
+  `posecode-social.png`.
+- **Org / project avatar:** upload `posecode-icon-512.png`. (It's transparent, so
+  on a light avatar background the lime figure will read light; if you want more
+  contrast there, place it on an `#0a0d12` square first.)
+- **README / inline:** reference `posecode-icon-512.png` or `posecode-mark.svg`.