What changed​

• docs-site/scripts/generate-activity-calendar.mjs generates static activity data from changelog markdown and committed Git stats.
• docs-site/src/components/ActivityCalendar renders the calendar, activity markers, day details, month navigation, and click-to-filter behavior.
• docs-site/src/theme/BlogListPage adds the tracker above /blog entries and filters visible changelog posts when a day is selected.
• docs-site/package.json runs activity generation before docs start and build commands, while docs-site/docusaurus.config.ts shows all posts on the blog index so filtering works across the full changelog.
• The calendar detail panel now uses container-aware layout rules to prevent hover flicker and to stack cleanly on narrower blog columns.
• css/app.css gives the Prompt list a thin neutral scrollbar, stable gutter, and removes the older duplicate prompt-list style block.

User impact​

• Developers can scan changelog and code activity by date from /blog.
• Hovering a day previews the related changelogs, commits, file count, and line activity.
• Clicking a day filters the changelog list to that date, and clearing the filter restores the full list.
• The Prompt list scrollbar feels quieter and no longer shows chunky browser scrollbar buttons.

Verification​

Checked locally with:

cd docs-site
pnpm activity:generate
pnpm typecheck
pnpm build

Browser checks confirmed the calendar renders on /blog, June 17 and June 18 filter to the expected changelog posts, hover previews no longer flicker, and desktop, tablet, and mobile widths have no horizontal overflow.

What changed​

• index.html removes the .brain-badge overlay from the brain stage and updates the initial status text with N 0, A 0, and SIG 0.
• css/app.css removes the desktop and mobile badge styles plus the live-dot styling that only existed for that overlay.
• src/brain-ui.ts no longer caches or updates #brainTelemetry, and the removed buildTelemetryLine() helper is gone.
• src/scene.ts adds neuron and axon totals to the status bar. The full status uses NEURONS and AXONS; the compact status uses N and A to keep the line readable on narrow canvases.

User impact​

• The brain canvas is visually cleaner and focuses on the 3D brain plus the existing affect label.
• Duplicate telemetry is gone. Neuron and axon counts now live with the rest of the stage readout in the bottom status bar.
• The right-panel telemetry tiles are unchanged, so dashboard metrics remain in the same place.

Verification​

Checked locally with:

pnpm typecheck
pnpm test
pnpm exec vite build

The built app was served locally and checked at desktop and mobile widths. The checks confirmed the badge DOM is gone, #brainTelemetry no longer exists, the affect overlay remains, the status bar includes neuron, axon, and signal counts, the right-panel metrics remain populated, and the WebGL canvas renders with visible pixel variation.

What changed​

• docs-site/src/css/custom.css removes hero gradients, normalizes hero title spacing, and simplifies the eyebrow badge.
• docs-site/src/pages/index.module.css tightens homepage feature cards with an 8px radius, quieter hover states, and more compact spacing.
• docs-site/docusaurus.config.ts keeps local Docusaurus search, adds page indexing, expands result limits and context, and excludes navbar, footer, breadcrumbs, pagination, table of contents, and doc footer chrome from the index.
• docs-site/package.json adds preview:search for the production-search workflow: build the docs site, then serve the generated static output.
• Current docs, versioned docs, and blog posts replace long dash separators with cleaner punctuation or explicit wording.

User impact​

• The docs homepage has a flat visual style with no gradient coloring.
• Search validation is less confusing: pnpm start remains for live editing, while pnpm serve or pnpm preview:search validates the generated search index.
• Searching for terms such as tele in the built site returns real local results instead of the build-index warning.
• The visible docs copy no longer uses em dash or en dash separators.

Verification​

Checked locally with:

cd docs-site
pnpm typecheck
pnpm build
rg -n '\x{2014}|\x{2013}' docs-site/docs docs-site/versioned_docs docs-site/blog docs-site/src/pages docs-site/docusaurus.config.ts
rg -n 'linear-gradient|radial-gradient' docs-site/src

The built site was served at http://127.0.0.1:3001/. Browser checks confirmed the homepage hero has no background image, the mobile layout fits at 390px, and searching for tele returns Telemetry results without the build-index warning.

What changed​

• src/affect/* adds the affect engine: shared types, the emotion palette, the deterministic local classifier, text hashing, affect-to-region mapping, and the browser client for saving affect annotations.
• src/brain-ui.ts classifies user input immediately, classifies assistant output after streaming, renders message affect chips, updates the new Affective Field, and triggers emotion-colored neural pulses. Chat error states can also become assistant_error affect events when the failed span is available.
• index.html adds the Affective Field readout inside the Chat tile and the canvas-stage affect overlay.
• css/app.css styles the Affective Field, message chips, stage overlay, and responsive narrow-panel behavior.
• rust/brain_sim/src/lib.rs extends the WASM signal pool with per-signal RGB color buffers. Stimuli can now pass a hex color, and signals propagate that color through neuron firing.
• src/brain.ts binds the WASM particle color buffer to a Three.js color geometry attribute so simultaneous signals can render different emotion colors in the same canvas.
• supabase/functions/chat-affect/index.ts adds an authenticated Edge Function that writes affective_state span annotations. It always stores the local CODE classifier output and can also store an LLM-refined annotation through 9Router.
• supabase/functions/run-chat/index.ts now includes trace_id, span_id, otel_trace_id, and otel_span_id on streaming error payloads when the error span was persisted successfully.

Affect model​

The local classifier scores:

• anger
• fear
• sadness
• joy
• disgust
• surprise
• curiosity
• calm
• distress
• neutral

Profanity is context-aware. For example, "fuck yeah" routes toward high-arousal joy, while directed hostile profanity routes toward anger, distress, and higher toxicity. The UI can look dramatic, but docs and metadata call the output synthetic affect telemetry.

Persistence​

chat-affect writes to existing span_annotations rather than adding a new table:

• name = "affective_state"
• annotator_kind = "CODE" for local analysis
• annotator_kind = "LLM" for optional refinement
• identifier = chat-turn:<turn_id>:phase:<phase>:source:<source>

Metadata stores score vectors, region mix, color palette, classifier version, selected chat model, affect model, phase, and text hash. Raw message text is not duplicated in affect metadata.

Verification​

Checked locally with:

pnpm run typecheck
pnpm test
pnpm build
pnpm --dir docs-site build

A browser smoke check opened Chat at http://127.0.0.1:9001/, verified the Affective Field on desktop and narrow viewports, confirmed no Chat overflow, and confirmed the WebGL brain canvas screenshot was nonblank.

What changed​

• src/ui/keyboard-shortcuts.ts adds a shared registry for visible keyboard commands and a guard that decides whether global scene shortcuts should run.
• src/events.ts now scopes the visualizer shortcuts so Space, A, and S only affect the 3D scene when focus is outside inputs, buttons, chat, search, Settings, diagnostics, prompt playground, and lil-gui controls.
• index.html adds a Keyboard Shortcuts & Commands card to Settings and changes the initial clip preview from a fake 0:06 duration to an explicit empty state.
• src/ui/workbench.ts renders the Settings command list from the shortcut registry so the visible docs match the active runtime behavior.
• src/ui/media-duration.ts centralizes duration labels: no stimulus shows :, images show Still, videos show their metadata duration, and unknown loaded media shows Loaded.
• src/brain-ui.ts now resets cleared media to an empty state, waits for video metadata before showing a duration badge, and removes the clip-thumb badge when no stimulus is loaded.
• css/app.css adds the empty clip thumbnail style and responsive Settings shortcut rows with compact kbd chips, scope labels, and wrapped descriptions.
• src/__tests__/keyboard-shortcuts.test.ts and src/__tests__/media-duration.test.ts cover the shortcut guard and duration label behavior.

User impact​

• Pressing A, S, or Space while typing in Chat or interacting with Settings no longer toggles visualizer helpers by accident.
• Settings now lists the app's current global and contextual commands, including Search, Diagnostics, Chat send, model picker navigation, and the Floor Platform visualizer command.
• Fresh app load and cleared clips show Duration : and a muted No clip thumbnail instead of 0:06.
• Uploaded images show Still instead of a fake video duration; uploaded videos show their real metadata duration once available.

Verification​

Checked locally with:

pnpm typecheck
pnpm exec vitest run src/__tests__/keyboard-shortcuts.test.ts src/__tests__/media-duration.test.ts
pnpm build

The browser smoke test opened http://localhost:9001/, confirmed the empty clip state, confirmed the Settings list rendered nine command rows, and verified A, S, and Space type normally inside the Chat input.

What changed​

• index.html replaced the native #brainModelSelect with an app-owned model picker: #brainModelTrigger, #brainModelMenu, #brainModelSearch, and #brainModelList. It also added the data-view="observability" right-panel view and the new #observabilitySlot mount target.
• src/brain-ui.ts now renders the model list as a custom listbox while keeping the existing chatModels, selectedChatModel, and exepert.brainChat.model.v1 persistence flow. The menu supports provider grouping, search, variant badges, Escape, ArrowUp/ArrowDown, Enter, outside-click dismissal, and disabled state while streaming.
• src/ui/observability.ts now prefers #observabilitySlot, falls back to the old #obsSlot only for older shells, and uses exepert.obsCollapsed.v2 so the activity-page panel defaults to expanded.
• css/app.css adds the dark model popover, selected/active row states, responsive badge behavior, Observability workbench view rules, and the wider Trace Ingestion page layout.

User impact​

• Opening the Chat model picker no longer shows a white operating-system dropdown in the dark UI.
• Codex and Claude models from 9Router are searchable and grouped by provider.
• Chat keeps its full vertical space because Trace Ingestion is no longer mounted under the chat tile.
• The Observability activity icon now opens a focused Trace Ingestion page with the existing import, sample, trace viewer, live, project, Supabase status, and summary controls.

Verification​

Checked locally with:

pnpm typecheck
pnpm build

The browser smoke test confirmed that the menu listed 25 models, filtering worked for Claude models, keyboard selection worked, a chat request used the selected cx/gpt-5.4 model, and #obs-panel mounted inside #observabilitySlot rather than the Chat area.

What changed​

• Added scripts/vercel-build.sh as the Vercel build command. It prepares Rust, installs the wasm32-unknown-unknown target and wasm-pack, runs the Vite production build, builds docs-site/, and merges the rendered docs into dist/.
• Added scripts/copy-docs-build.mjs to copy docs-site/build into dist/ while skipping the docs site's root index.html. The app stays mounted at /, and Docusaurus pages are available under routes like /docs/getting-started/introduction/.
• Replaced hardcoded localhost:3000 documentation links with environment-aware links. Local app origins use http://localhost:3000; production uses the app's deployed origin unless VITE_DOCS_URL is explicitly set.
• Added EXEPERT favicon assets for the app and docs site: public/favicon.png, public/favicon-32.png, public/favicon-192.png, public/apple-touch-icon.png, and docs-site/static/img/favicon.png.

Deployment note​

Set Vercel's Build Command to:

bash scripts/vercel-build.sh

Leave the Output Directory as dist. Do not set VITE_DOCS_URL for the normal Vercel deployment unless the docs are intentionally hosted somewhere else.

Decluttered chat header​

The chat tile header (.brain-chat-header) previously showed a "Neural Brain" title plus a live-telemetry status pill (pulse dot + "Live telemetry" / "Waiting for signal"). Both were removed; the header now holds only the close (×) button, right-aligned.

• index.html: dropped .brain-chat-title and .brain-chat-status-inline (which contained #brainChatStatus). The dialog now names itself with aria-label="Neural Brain chat" instead of the dangling aria-labelledby="brainChatTitle" (no such element ever existed).
• src/brain-ui.ts: removed brainChatStatus from the cached-element list and the per-tick els.brainChatStatus.textContent = … write, so nothing references the deleted node.
• css/app.css: .brain-chat-header is now justify-content: flex-end; removed the unused .brain-chat-title, .brain-chat-status-inline, .pulse-dot, and @keyframes pulseDot rules.

Collapsible Trace Ingestion tile​

The observability panel (#obs-panel) gained a chevron toggle in its header (#obsCollapse) that collapses the tile to just its header, hiding .obs-body. Because the slot is flex: 0 0 auto and #leftChat is flex: 1, collapsing the panel hands that vertical space straight to the chat.

• Defaults to collapsed so the chat gets maximum real estate out of the box.
• The choice is persisted across reloads in localStorage under exepert.obsCollapsed, wrapped in try/catch for private-mode / SSR safety.
• aria-expanded + aria-controls="obsBody" keep the toggle accessible; the chevron rotates 180° when expanded.

Help link now opens the rendered guide​

The panel's ? help link pointed at Plans/guide-trace-ingestion.md, which Vite resolved to a raw, unrendered .md file on the app origin (a blank page). It now opens the rendered Docusaurus guide page at /docs/guides/trace-ingestion.

On local app origins, docs links default to http://localhost:3000, which matches the separate Docusaurus dev server. In production, leave VITE_DOCS_URL unset: the Vercel build bundles the rendered docs into the app's dist/ folder, so the link resolves on the deployed app origin under /docs.

See the UI guide for the chat tile contract and the trace-ingestion tile notes.

Symptom​

With the Chat tab active, the DOM collapsed into the chat header:

• div.brain-chat-header > div#brainMessages: message column ~30px wide instead of full width.
• div.brain-chat-header > div.brain-chat-input: input overflowing the panel (333px wide inside a 329px panel).

#leftChat is a flex-direction: column tile and its five regions are meant to be direct siblings. Because they were nested inside the header row instead, they inherited display: flex; align-items: center and collapsed.

Root cause​

index.html had a duplicated opening <div class="brain-chat-header"> tag with only one matching </div>:

<div class="brain-chat-header">
  <div class="brain-chat-header">
  <strong class="brain-chat-title">Neural Brain</strong>
  …status · close…
</div>
<!-- chat-context, brainMessages, quick-prompts, brain-chat-input
     were now all trapped INSIDE the header -->

The unbalanced tag pushed .chat-context, #brainMessages, .quick-prompts, and .brain-chat-input inside the header, so the column layout never applied.

Fix​

Removed the duplicate opening tag so the header self-closes and the five regions are siblings again:

<div class="brain-chat-header">
  <strong class="brain-chat-title">Neural Brain</strong>
  <span class="brain-chat-status-inline">…</span>
  <button class="brain-chat-close" id="closeBrainChat">&times;</button>
</div>
<div class="chat-context">…</div>
<div class="brain-chat-messages" id="brainMessages">…</div>
<div class="quick-prompts">…</div>
<div class="brain-chat-input">…</div>

No CSS changed: the stylesheet (.brain-chat-messages { flex: 1 }, the column container, the input row) was already correct. See the UI guide for the sibling contract that this tile depends on.

What's documented​

This first pass covers the project as it actually runs today:

• Getting started: prerequisites (Node, pnpm, Rust + wasm-pack), installation, the dev loop on port 9001, and production builds.
• Architecture: the two-layer design where a Rust World compiled to WebAssembly owns the state and the Three.js front end reads it through zero-copy buffers.
• Simulation core: neuron/axon generation, the struct-of-arrays signal pool, the four cortical regions, stimulus injection, and the telemetry contract.
• Frontend modules, the diagnostics logger, a UI guide, and development notes (testing, CI, the legacy reference pages).

A note on the rendering path​

EXEPERT currently renders with a classic WebGL2 WebGLRenderer and GLSL ShaderMaterial shaders, driven by a CPU simulation step (step_cpu). Earlier design docs in the Plans/ folder describe a WebGPU + TSL compute path that was built and then reverted. The documentation describes the shipped code; treat those plans as history.

Browse the Introduction to get started.