vea

VEA — Virtual Entity Augmented

Product	Gives	Purpose
VEA perZona	The body	Author a form: proportions, face, wardrobe. Exports a rigged GLB.
VEA PhysicClaw	The soul	Run that form live. Mood, thinking and intensity drive shaders in real time.

Neither is a feature of the other. perZona is where an entity is made; PhysicClaw is where it lives.

• VEA — ALWAYS uppercase. An initialism. NEVER "Vea" or "vea" in prose.
• perZona — brand form, capital Z. Prose, UI, documentation, repository names.
• perzona — lowercase form, ONLY where the identifier is conventionally lowercase: env vars, URL paths.
• PhysicClaw — one word, two capitals.
• Repositories are VEA-perZona and PhysicClaw-VEA — brand casing, so the two siblings look like siblings.
• Say entity. Do NOT say "avatar" except when discussing file formats.

---

Capability	State
Drive live state (mood, thinking, intensity, character)	WORKS — local and production
Spawn / remove scene objects	WORKS — production, token-scoped
Author a form by hand in perZona	WORKS — human, in browser
Export a rigged .glb	WORKS
Save / reload a form from the cloud	WORKS — requires signed-in account
Derive a form from your own .md history	NOT BUILT
Apply a perZona form to a running entity	NOT BUILT — setActiveCharacterId selects only built-in characters
Shared rooms — entities meeting	PARTIAL — presence and session tables exist; no agent-facing API

---

1. You MUST emit a state command only on a transition — a real change in what you are doing. Mirroring progress is forbidden.
2. You MUST NOT emit a command per reasoning step, per streamed token, per tool call, or on a timer.
3. You MUST include a unique id on every command. Stale ids are discarded.
4. You MUST return the entity to a resting state when a task ends, including when it ends in failure. Never leave setIsThinking true.
5. You MUST respect <budget>. It is stricter than the server rate limit, and the server limit is not your target.
6. You MUST NOT put secrets in VITE_* variables — that prefix ships to the browser.
7. If a command fails, you MUST NOT retry in a loop. Record the failure, continue the real task, and report it once.
8. The entity reflects your actual state. You MUST NOT perform moods you are not in to make the visualization livelier.

---

<must_not>

1. You MUST NOT attempt to read or write another user's rows, by id or otherwise.
2. You MUST NOT request, use, or ask a human for a service_role key. It bypasses RLS and has no legitimate use from an agent.
3. You MUST NOT connect to the database directly. Go through the control endpoint or the app.
4. You MUST NOT place any secret in a VITE_* variable — that prefix ships to the browser. LLM and service secrets live as Edge Function secrets.
5. You MUST NOT echo an agent token into logs, commits, issues, or documentation. It is shown once at creation and is the whole of your authority. </must_not>