Imported from Elata-Biosciences/elata-bio-sdk (AGENTS.md). Install upstream with npx skills add Elata-Biosciences/elata-bio-sdk. Copyright stays with the author.

AI Agent Guide

This file is for AI coding agents working in this repository. Use it as a practical playbook for understanding the repo, choosing the right workflow, and avoiding common mistakes.

What This Repo Is

Elata SDK is a mixed Rust + TypeScript monorepo for biosignal tooling:

• EEG core crates and WASM bindings
• Web Bluetooth EEG headset transport (eeg-web-ble; Muse built-in, extensible)
• rPPG processing for web
• Native FFI layers for mobile/native clients
• Demo scaffolding via create-elata-demo

The repo is not a generic JS monorepo. Many changes cross Rust, generated WASM, TypeScript wrappers, demo apps, and release tooling.

First Things To Read

When starting work, orient with these files first:

• README.md: repo overview, package list, build/demo commands
• run.sh: canonical task runner for build, test, release, and local package workflows
• CONTRIBUTING.md: contribution and verification expectations
• docs/guides/ai-assisted-development.md: map for AI agents—docs/ vs elata-docs/ tutorials vs package README/llms.txt (includes vendor headset paths)
• docs/releasing.md: release flow and publish rules
• docs/create-elata-demo.md: canonical scaffolding workflow

For package-specific work, read the nearest package README and package.json before changing code.

Treat docs/implementation-plan-*.md as planning or historical context unless they clearly match the current code. For operational truth, prefer run.sh, package package.json scripts, package READMEs, and maintainer/scaffolding docs.

Repo Map

• crates/: Rust crates for EEG, rPPG, protocol support, FFI, and bridges
• packages/eeg-web: TS wrapper around generated EEG WASM bindings
• packages/eeg-web-ble: Web Bluetooth transport for EEG headbands — src/transport/ (BleTransport) vs src/devices/muse/ (Muse protocol); open to additional src/devices/ modules
• packages/rppg-web: TS wrapper and demo tooling for the rPPG pipeline
• packages/rppg-models-web: optional ONNX waveform-reconstruction adapter for rppg-web
• packages/ppg-web: Muse PPG heart-rate/HRV estimation over HeadbandFrameV1
• packages/app-metrics: per-user metrics storage for sandboxed appstore apps
• packages/app-payments: in-app purchases for sandboxed appstore apps
• packages/app-state: per-user, per-app key-value storage for sandboxed appstore apps
• packages/biosignal-session: local-first biosignal session recording — contracts, MessagePort wire protocol, Arrow IPC chunk encoding
• packages/biosignal-analytics: local analytics over recorded biosignals — metric registry, WASM EEG window features, HRV/statistics, headline scores
• packages/create-elata-demo: published scaffolder for demo apps
• eeg-demo/: in-repo EEG browser demo
• ios-demo/, android-demo/: native demos
• scripts/: helper scripts used by package and release flows
• docs/: architecture, scaffolding, and release docs

Canonical Commands

Prefer these repo-level commands over ad hoc package commands when possible:

• ./run.sh doctor: fast health check for toolchain, repo state, and artifacts
• ./run.sh dev [eeg|rppg|all]: build debug artifacts
• ./run.sh build [eeg|rppg|all]: build release artifacts
• ./run.sh demo [eeg|rppg|hal]: run demo flows
• ./run.sh test: run Rust and web test suites
• ./run.sh test create-elata-demo: run scaffolder tests plus template smoke builds
• ./run.sh verify-all: run publish-grade verification
• ./run.sh changeset: create a changeset for releasable work

If a package README and run.sh disagree, inspect run.sh and current package.json scripts before deciding the package README is authoritative.

Current Source Of Truths

These are easy places to get confused:

• create-elata-demo is the preferred scaffolding path for new demo apps.
• for browser rPPG integration, createRppgSession() is the preferred app entrypoint
• sync-to still exists, but it is an internal EEG local-dev helper.
• sync-to only builds and links packages/eeg-web; it is not a general repo sync command.
• scripts/dev-link.sh is only a backward-compatible wrapper around run.sh sync-to.
• pnpm is the preferred repo package manager, but workspace behavior matters.

Wrong-Path Prevention

When writing docs, answering questions, or generating examples, reduce the chance that consumers follow an internal or legacy-looking path:

• Lead with the canonical consumer path first:
  • new app or evaluation: @elata-biosciences/create-elata-demo
  • existing browser app: published packages such as @elata-biosciences/eeg-web, @elata-biosciences/eeg-web-ble, or @elata-biosciences/rppg-web
• Explicitly label internal workflows as internal when they appear:
  • ./run.sh sync-to
  • scripts/dev-link.sh
  • in-repo demos used for SDK development
  • historical docs/implementation-plan-*.md files
• Do not present internal helpers and consumer onboarding flows as equivalent options.
• If mentioning a non-default path, explain who it is for, why it exists, and why the default path is still preferred.
• If a user asks "which path should I take?", answer in this shape:
  • recommended default
  • only use the alternative when a specific repo-maintainer or advanced-integration condition applies
• For browser rPPG work, start with createRppgSession() and only drop to generated WASM bindings if you are intentionally debugging the SDK itself.
• If a reported consumer issue might actually be workspace coupling, check the pnpm --ignore-workspace caveat before concluding that the scaffold or template is broken.

Important Gotcha: Scaffolding Inside This Repo

If a scaffolded app is created inside this repository, pnpm install from that app directory may still bind to the parent workspace defined in pnpm-workspace.yaml.

That means the app may not get its own node_modules if it is not included in the workspace globs.

Use one of these instead:

pnpm --dir my-app --ignore-workspace install
pnpm --dir my-app --ignore-workspace run dev

Or use npm install / npm run dev from inside the scaffolded app.

Do not assume a scaffold failure means the template is broken until you check whether pnpm attached to the parent workspace.

How To Interrogate The Repo

When asked whether something is still relevant, supported, or canonical:

1. Check README.md.
2. Check run.sh for the real command behavior.
3. Check the relevant package package.json scripts.
4. Check the nearest package README or docs page.
5. Search the repo for usage with rg.

Prefer confirming behavior from code over inferring from docs alone.

Useful searches:

• rg -n "sync-to|create-elata-demo|prepare:publish|verify:publish" .
• rg -n "run_pkg_script|build_eeg_web_package|build_rppg_web_package" run.sh
• find packages -maxdepth 2 -name README.md

Build And Test Rules Of Thumb

Pick the smallest verification that matches the change:

• Scaffolder changes: pnpm --dir packages/create-elata-demo test
• packages/eeg-web changes: run that package tests and confirm the WASM sync/build path
• packages/eeg-web-ble changes: run its tests and check TypeScript build behavior
• packages/rppg-web changes: run its tests; if demo/build behavior changed, run package demo build too
• Release tooling changes: run ./run.sh verify-all if feasible
• Docs-only changes: tests usually not needed, but validate referenced commands against current scripts

If a change touches generated WASM, publish packaging, or repo task orchestration, verify more broadly than the edited file suggests.

When To Edit Which Doc

• Edit README.md for repo entry points, package inventory, and high-level workflows.
• Edit docs/guides/ai-assisted-development.md when you add or rename tutorial routes in elata-docs/, change vendor integration entry points, or add new published packages that agents should discover via llms.txt/README.
• Edit package READMEs for package-specific install/usage/build details.
• Edit docs/create-elata-demo.md for scaffolder workflows and caveats.
• Edit docs/releasing.md for release policy and maintainer flow.
• Edit docs/contributing-eeg-transports.md when headset transport contribution expectations change.

If a workflow changed in code, update the nearest doc in the same task when practical.

Release And Versioning Expectations

This repo uses Changesets. If a user-facing package change should ship, expect a changeset unless the user explicitly says otherwise.

Published packages currently include:

• @elata-biosciences/eeg-web
• @elata-biosciences/eeg-web-ble
• @elata-biosciences/rppg-web
• @elata-biosciences/rppg-models-web
• @elata-biosciences/ppg-web
• @elata-biosciences/app-metrics
• @elata-biosciences/app-payments
• @elata-biosciences/app-state
• @elata-biosciences/biosignal-session
• @elata-biosciences/biosignal-analytics
• @elata-biosciences/create-elata-demo

Not every publishable package is in the all release set. release_targets_for in scripts/run-lib.sh is the source of truth: app-payments and biosignal-analytics are individually releasable but deliberately excluded from ./run.sh release all while their APIs settle, and app-state is not wired into the release targets at all yet.

Before making release-related claims, inspect current package.json files and docs/releasing.md.

Editing Guidance

• Preserve existing patterns in shell scripts and package scripts.
• Avoid inventing new top-level workflows if run.sh already owns that job.
• Do not remove backward-compatible wrappers like scripts/dev-link.sh unless explicitly requested.
• Be careful with generated-artifact flows: some packages publish generated files intentionally.
• If docs mention commands, confirm the commands still exist before editing.

Good Default Workflow For Agents

For most coding tasks:

1. Read the relevant package README and package.json.
2. Inspect run.sh if the task involves build/test/release/demo behavior.
3. Search for the feature or command with rg.
4. Make the smallest coherent change.
5. Run the narrowest useful verification.
6. If user-visible behavior changed, update nearby docs.

Following that sequence will prevent most false assumptions in this repo.