face/README.md · Darwin

91 lines · markdown

# Darwin - The Face
 
The Awwwards-tier living-organism front door for Darwin, Zion's second brain. A single surface
that is *alive*: an R3F node-cluster creature made of real data sources, a three-pane query surface
(agent nervous system · ask + receipts · raw hits + inbox), and health-as-anatomy that withers
stale sources on screen.
 
Near-black `#050607` canvas, one bioluminescent teal accent `#16e0c8`, brutalist monolithic type
(Space Grotesk display / Inter UI / JetBrains Mono), easeOutExpo `cubic-bezier(0.16,1,0.3,1)`
motion dialect.
 
## Stack
 
Next.js 14 (App Router) · TypeScript · Tailwind · GSAP (ScrollTrigger) · @studio-freight/lenis ·
@react-three/fiber + drei · d3-force.
 
## Develop
 
The `/shared/projects` share is **noexec CIFS** - you cannot `npm install` or run there. Develop in
local ext4:
 
```bash
cd /var/tmp/darwin-dev/face
npm install        # one-time
npm run dev        # http://localhost:3000
```
 
`/shared/projects/darwin/face/` is a **mirror** (source tree only, no `node_modules`/`.next`). To
refresh it after editing in dev:
 
```bash
rsync -a --delete --exclude=node_modules --exclude=.next --exclude=.git \
  /var/tmp/darwin-dev/face/ /shared/projects/darwin/face/
```
 
## Build
 
```bash
cd /var/tmp/darwin-dev/face
npm run build      # validated green - 0 type errors, 0 lint errors
```
 
## What is mocked vs real
 
The Cortex gateway is **not deployed yet**. The app runs fully standalone against typed mocks in
`src/lib/mock-gateway.ts`, shaped EXACTLY per `cortex/CONTRACTS.md` §2:
 
| Surface | Source |
|---|---|
| `POST /ask` | mock (Hermes-status answer · 4 receipts · ranked hits · engine statuses · conflicts) |
| `GET /health` | mock (10 sources; `browser-history` is `down` @ `staleness_h 34.9` to demo the wither) |
| Agent nervous-system tree | mock event data (7 nodes, some active) |
| **Real Cortex** | activated automatically when `NEXT_PUBLIC_CORTEX_URL` is set |
 
When `NEXT_PUBLIC_CORTEX_URL` is set, the gateway client hits the real endpoint and falls back to
the mock on any error, so the surface never goes blank.
 
## Env vars
 
Copy `.env.local.example` → `.env.local`:
 
```
NEXT_PUBLIC_CORTEX_URL=http://REDACTED-IP:9890   # leave unset to use mocks
```
 
## Deploy to CT 252 (Darwin CT)
 
1. Add `output: 'standalone'` to `next.config.mjs`.
2. `npm run build` in `/var/tmp/darwin-dev/face`.
3. Copy `.next/standalone` + `.next/static` + `public` to CT 252.
4. Set `NEXT_PUBLIC_CORTEX_URL=http://REDACTED-IP:9890` in the CT 252 environment (the Cortex
   HTTP API per CONTRACTS.md runs on `:9890`).
5. `node server.js` (standalone entrypoint) behind the CT's reverse proxy.
6. Front it at `REDACTED-HOST` behind Authentik SSO per blueprint §10.
 
> Cutover is **gated on Zion's explicit go** (blueprint §7). Do not reallocate Odysseus/CT245
> resources until the new door is fully working including remote-control transport.
 
## Signature behaviors
 
- **Evolve-in:** on load all nodes spawn from origin → cluster positions over ~1.2s (expo-out).
- **Health-as-anatomy:** fresh sources glow bioluminescent teal; staleness greys then withers
  (shrinks + dims) the node; `down` sources render dead-grey. Driven live by `/health`.
- **Cursor attraction:** nodes within range drift toward the cursor (attention = selection
  pressure).
- **Focus → collapse:** focusing the ask field folds the organism inward toward center and swells
  the core glow - "the brain becomes a question."
- **Receipts:** every answer claim carries a clickable receipt chip (`[source] path · confidence%`)
  that expands to the snippet + last-seen timestamp. No claim without provenance.
 
All motion respects `prefers-reduced-motion` (GSAP/Lenis skipped, transitions no-op).

1	# Darwin - The Face
2
3	The Awwwards-tier living-organism front door for Darwin, Zion's second brain. A single surface
4	that is alive: an R3F node-cluster creature made of real data sources, a three-pane query surface
5	(agent nervous system · ask + receipts · raw hits + inbox), and health-as-anatomy that withers
6	stale sources on screen.
7
8	Near-black `#050607` canvas, one bioluminescent teal accent `#16e0c8`, brutalist monolithic type
9	(Space Grotesk display / Inter UI / JetBrains Mono), easeOutExpo `cubic-bezier(0.16,1,0.3,1)`
10	motion dialect.
11
12	## Stack
13
14	Next.js 14 (App Router) · TypeScript · Tailwind · GSAP (ScrollTrigger) · @studio-freight/lenis ·
15	@react-three/fiber + drei · d3-force.
16
17	## Develop
18
19	The `/shared/projects` share is noexec CIFS - you cannot `npm install` or run there. Develop in
20	local ext4:
21
22	```bash
23	cd /var/tmp/darwin-dev/face
24	npm install # one-time
25	npm run dev # http://localhost:3000
26	```
27
28	`/shared/projects/darwin/face/` is a mirror (source tree only, no `node_modules`/`.next`). To
29	refresh it after editing in dev:
30
31	```bash
32	rsync -a --delete --exclude=node_modules --exclude=.next --exclude=.git \
33	/var/tmp/darwin-dev/face/ /shared/projects/darwin/face/
34	```
35
36	## Build
37
38	```bash
39	cd /var/tmp/darwin-dev/face
40	npm run build # validated green - 0 type errors, 0 lint errors
41	```
42
43	## What is mocked vs real
44
45	The Cortex gateway is not deployed yet. The app runs fully standalone against typed mocks in
46	`src/lib/mock-gateway.ts`, shaped EXACTLY per `cortex/CONTRACTS.md` §2:
47
48	\| Surface \| Source \|
49	\|---\|---\|
50	\| `POST /ask` \| mock (Hermes-status answer · 4 receipts · ranked hits · engine statuses · conflicts) \|
51	\| `GET /health` \| mock (10 sources; `browser-history` is `down` @ `staleness_h 34.9` to demo the wither) \|
52	\| Agent nervous-system tree \| mock event data (7 nodes, some active) \|
53	\| Real Cortex \| activated automatically when `NEXT_PUBLIC_CORTEX_URL` is set \|
54
55	When `NEXT_PUBLIC_CORTEX_URL` is set, the gateway client hits the real endpoint and falls back to
56	the mock on any error, so the surface never goes blank.
57
58	## Env vars
59
60	Copy `.env.local.example` → `.env.local`:
61
62	```
63	NEXT_PUBLIC_CORTEX_URL=http://REDACTED-IP:9890 # leave unset to use mocks
64	```
65
66	## Deploy to CT 252 (Darwin CT)
67
68	1. Add `output: 'standalone'` to `next.config.mjs`.
69	2. `npm run build` in `/var/tmp/darwin-dev/face`.
70	3. Copy `.next/standalone` + `.next/static` + `public` to CT 252.
71	4. Set `NEXT_PUBLIC_CORTEX_URL=http://REDACTED-IP:9890` in the CT 252 environment (the Cortex
72	HTTP API per CONTRACTS.md runs on `:9890`).
73	5. `node server.js` (standalone entrypoint) behind the CT's reverse proxy.
74	6. Front it at `REDACTED-HOST` behind Authentik SSO per blueprint §10.
75
76	> Cutover is gated on Zion's explicit go (blueprint §7). Do not reallocate Odysseus/CT245
77	> resources until the new door is fully working including remote-control transport.
78
79	## Signature behaviors
80
81	- Evolve-in: on load all nodes spawn from origin → cluster positions over ~1.2s (expo-out).
82	- Health-as-anatomy: fresh sources glow bioluminescent teal; staleness greys then withers
83	(shrinks + dims) the node; `down` sources render dead-grey. Driven live by `/health`.
84	- Cursor attraction: nodes within range drift toward the cursor (attention = selection
85	pressure).
86	- Focus → collapse: focusing the ask field folds the organism inward toward center and swells
87	the core glow - "the brain becomes a question."
88	- Receipts: every answer claim carries a clickable receipt chip (`[source] path · confidence%`)
89	that expands to the snippet + last-seen timestamp. No claim without provenance.
90
91	All motion respects `prefers-reduced-motion` (GSAP/Lenis skipped, transitions no-op).