{"owner":"elizaOS","repo":"eliza","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md","AGENTS.md"],"files":{"CLAUDE.md":"# elizaOS repository guide\n\nThis monorepo contains the elizaOS agent framework and the product stack built\non it: the core runtime, standalone agent host, Eliza application, CLI, cloud\nservices, native bridges, documentation, tests, and first-party plugins.\nBootable Linux and AOSP distributions are maintained separately in\n[`elizaOS/os`](https://github.com/elizaOS/os).\n\n## How repository instructions work\n\n- Read this guide before changing the repository.\n- Before working in a package or plugin, read the nearest `CLAUDE.md` and its\n  `README.md`. A local guide adds package-specific architecture, commands, and\n  validation requirements; repository-wide rules in this guide remain binding.\n- `CLAUDE.md` and `AGENTS.md` in the same directory must be byte-for-byte\n  identical. Author `CLAUDE.md`, copy the finished content to `AGENTS.md`, and\n  run `bun run check:agents-claude`.\n- The `AGENTS.md` files under\n  `packages/elizaos/src/migrate/__tests__/fixtures/` are migration inputs, not\n  repository instructions. They are intentionally unpaired and must change only\n  when the corresponding migration fixture changes.\n- Treat package manifests, exports, executable scripts, tests, and current\n  source as the factual authority. Documentation is a map, not evidence that a\n  feature still exists.\n\n## Naming\n\nWrite **elizaOS**, never `ElizaOS`. The npm scope is `@elizaos/*`. Use\n**Eliza agents** for agents built with the framework. The **Eliza Classic**\nplugin is the deliberate exception because it reimplements the 1966 chatbot.\n\n## Before editing\n\n1. Run `git status --short --branch`. This is a shared working tree and existing\n   changes belong to their authors; do not discard, rewrite, or stage unrelated\n   work.\n2. Identify the owning workspace and read its local guide, README, manifest,\n   exports, and relevant tests.\n3. Search for callers and contract tests before changing a public type, route,\n   event, environment variable, script, or package export.\n4. Use the narrowest relevant command while iterating, then run the required\n   package and repository gates before declaring the work complete.\n\n## Toolchain\n\n- **Runtime:** Bun `1.3.14` and Node `24.15.0` are pinned in `package.json`.\n  Use the pinned versions; do not silently substitute npm, pnpm, Yarn, or an\n  older Node runtime.\n- **Modules:** ESM only (`\"type\": \"module\"`). Do not introduce CommonJS.\n- **Workspace orchestration:** Turbo drives package `build`, `typecheck`,\n  `lint`, and test tasks. Workspace globs are defined in `package.json`.\n- **TypeScript:** the repository uses project references through root and\n  package `tsconfig` files.\n- **Formatting and linting:** Biome is pinned by the repository. Configuration\n  lives in `biome.json` and exclusions in `.biomeignore`.\n- **Tests:** Vitest is the primary runner; repository lanes are orchestrated by\n  `packages/scripts/run-all-tests.mjs`.\n\n## Root commands\n\n```bash\nbun install            # install workspaces, prepare submodules, apply patches, sync artifacts\nbun run install:light  # install without the large artifact sync\nbun run dev            # start the API and Eliza app development UI\nbun run start          # start the standalone agent host\nbun run build          # build the workspace through Turbo\nbun run verify         # parity, dependency, type, lint, and repository audit gates\nbun run lint           # workspace lint tasks\nbun run format         # workspace formatting tasks\nbun run typecheck      # workspace TypeScript checks\nbun run test           # repository unit and integration lane\nbun run test:server    # server package lane\nbun run test:client    # client package lane\nbun run test:e2e       # end-to-end lane\nbun run cloud:mock     # start the local cloud stack with mocks\nbun run clean          # remove generated build, cache, install, and local-state output\nbun run reset          # clean, reinstall, and rebuild\n```\n\nRun `bun run` with no arguments for the live script inventory. Scope a package\ncommand with `bun run --cwd <workspace> <script>`, for example:\n\n```bash\nbun run --cwd packages/core test\nbun run --cwd plugins/plugin-browser typecheck\n```\n\n### Shared app development server\n\nUse the normal `bun run dev` flow for a single checkout. Concurrent worktrees\nmust not all bind the default app port. From `packages/app` use:\n\n```bash\nbun run dev:shared   # start or reuse this worktree's deterministic Vite port\nbun run dev:status   # list registered shared servers\nbun run dev:rebuild  # request a full Vite reload for this worktree\n```\n\nReservations live in `~/.eliza/dev-server-registry.json` and may be redirected\nwith `ELIZA_DEV_SERVER_REGISTRY`. See\n[`packages/docs/development/shared-dev-server.md`](packages/docs/development/shared-dev-server.md).\n\n### Removed root command migrations\n\n| Removed command | Use instead |\n| --- | --- |\n| `bun run test:ci` | `bun run test` |\n| `bun run test:cloud:playwright` | `bun run --cwd packages/app test:e2e` |\n| `bun run test:ui:playwright` | `bun run --cwd packages/app test:e2e` |\n| `bun run test:lifeops` | `bun run test:plugin 'plugin-personal-assistant'` |\n| `bun run trajectory:inspect:test` | `bun test packages/scripts/__tests__/trajectory-validate.test.ts` |\n| `bun run audit:e2e-coverage:test` | `bun test packages/scripts/e2e-coverage/check-e2e-coverage.test.ts` |\n| `bun run test:browser-bridge` | `bun run --cwd packages/browser-extension test` |\n| `bun run test:browser-bridge:safari` | `bun run --cwd packages/browser-extension test:smoke:safari` |\n| `bun run voice:latency-report` | `bun run --cwd packages/app-core voice:latency-report` |\n| `bun run voice:interactive` | `bun run --cwd packages/app-core voice:interactive` |\n| `bun run voice:duet` | `bun run --cwd packages/app-core voice:duet` |\n| `bun run voice:create-profile` | `bun run --cwd packages/app-core voice:create-profile` |\n| `bun run smartglasses:hardware:doctor` | `bun run --cwd packages/examples/smartglasses hardware:doctor` |\n| `bun run smartglasses:hardware:status` | `bun run --cwd packages/examples/smartglasses hardware:status-latest` |\n| `bun run smartglasses:hardware:validate` | `bun run --cwd packages/examples/smartglasses hardware:validate-latest` |\n| `bun run smartglasses:hardware:prove` | `bun run --cwd packages/examples/smartglasses hardware:prove:bleak` |\n| `bun run smartglasses:hardware:prove:watch` | `bun run --cwd packages/examples/smartglasses hardware:prove:bleak:watch` |\n| `bun run smartglasses:hardware:prove:noble` | `bun run --cwd packages/examples/smartglasses hardware:prove:noble` |\n| `bun run smartglasses:hardware:prove:noble:watch` | `bun run --cwd packages/examples/smartglasses hardware:prove:noble:watch` |\n| `bun run smartglasses:dev:hardware` | `bun run --cwd packages/examples/smartglasses dev:hardware` |\n| `bun run smartglasses:dev:simulator` | `bun run --cwd packages/examples/smartglasses dev:simulator` |\n| `bun run smartglasses:simulator` | `bun run --cwd packages/examples/smartglasses simulator` |\n| `bun run smartglasses:smoke:simulator` | `bun run --cwd packages/examples/smartglasses smoke:simulator` |\n| `bun run test:ci:live` | `bun run test:live` |\n| `bun run test:lint` | retired with its aggregate tooling; no direct replacement |\n| `bun run test:lint:no-vi-mocks` | `bun run audit:test-integrity:no-vi-mocks` |\n| `bun run test:lint:lane-coverage` | retired with its tooling; no replacement |\n| `bun run test:lint:test-integrity` | retired with its tooling; no replacement |\n| `bun run test:lint:test-integrity:self-test` | retired with its tooling; no replacement |\n| `bun run verify:smartglasses-software` | `bun run audit:smartglasses-software` |\n| `bun run personality:judge` | `bun run bench:personality` |\n| `bun run personality:bench:calibrate` | `bun run bench:personality:calibrate` |\n| `bun run lint:all` | `bun run verify` |\n| `bun run build:typescript` | `node packages/scripts/run-turbo.mjs run build` |\n| `bun run audit:mvp-board` | `bun run mvp:closeout-audit` |\n| `bun run mvp:board-readiness` | `bun run mvp:closeout-audit` |\n| `bun run mvp:evidence-matrix` | `bun run mvp:closeout-audit` |\n\n## Repository map\n\n```text\npackages/\n  core/             @elizaos/core: AgentRuntime, contracts, message loop, memory, models\n  agent/            @elizaos/agent: standalone runtime assembly and HTTP backend\n  app-core/         shared application host, APIs, startup, build, and platform tooling\n  app/              Eliza web, desktop, and mobile UI application\n  auth/             shared account credentials, OAuth, subscription, and refresh logic\n  ui/               shared React primitives and product surfaces\n  elizaos/          the elizaos CLI and packaged project/plugin templates\n  prompts/          shared prompt templates across supported languages\n  shared/           cross-package utilities, contracts, and brand assets\n  logger/           structured logging package\n  vault/            secrets and configuration storage adapters\n  skills/           bundled runtime skills and loading utilities\n  registry/         first-party and community plugin registry data and validation\n  scenario-runner/  real-runtime scenario execution and report generation\n  test/             repository-wide scenarios and test corpus\n  evidence/         evidence manifest, bundle, verification, and ingestion foundation\n  docs/             documentation site source\n  homepage/         public Eliza product and download site\n  training/         Eliza-1 training, evaluation, conversion, and release tooling\n  cloud/            API, shared libraries, routing, SDK, infrastructure, tests, services\n  native/           native runtimes, third-party dependencies, and C/C++ plugins\n\nplugins/\n  plugin-<provider>/ model and inference providers\n  plugin-<channel>/  messaging and workspace connectors\n  plugin-native-*/   platform and device bridges\n  plugin-*/          domain capabilities, app views, storage, tools, and orchestration\n\nscripts/            repository-wide checks, CI helpers, evidence, security, and release tools\npatches/            dependency patches applied during installation\n```\n\nSome directories are organizational roots rather than npm workspaces. Use the\nnearest manifest and local guide instead of inferring ownership from directory\ndepth.\n\n## Runtime architecture\n\n- `@elizaos/core` owns `AgentRuntime`, the canonical public types, the plugin\n  contract, the message loop, model abstraction, memory/state primitives, and\n  framework services.\n- `@elizaos/agent` assembles a runnable backend around core. It owns the\n  standalone process, plugin loading policy, HTTP/WebSocket surfaces, and\n  host-level services.\n- `@elizaos/app-core` hosts Eliza application targets and their compatibility\n  APIs, startup flow, platform integration, and build orchestration.\n- `@elizaos/app` and `@elizaos/ui` render product state. Business values belong\n  in use-cases and DTOs, not recomputed in view or proxy layers.\n- A plugin normally exports a `Plugin` from `src/index.ts`. Plugins may\n  contribute actions, providers, evaluators, services, model handlers, routes,\n  events, tests, and app views.\n- The `elizaos` CLI is package-first. Its templates under\n  `packages/elizaos/templates/` are governed by their `SCAFFOLD.md` contracts.\n\nWhen code needs only the framework, depend on `@elizaos/core`. Do not depend on\nan application host to reach a core abstraction.\n\n## Engineering conventions\n\n- Use the structured logger in server/runtime code; never use `console` there.\n  Prefix human-readable messages with the owning class or subsystem and attach\n  structured context to errors.\n- Keep boundary types explicit. Validate untrusted input once, then use the\n  validated type. Avoid `any`, broad `unknown`, unchecked casts, and optional\n  chaining that hides a required collaborator.\n- DTO fields are required by default. If the producer failed to load a value,\n  represent that as an error or explicit unavailable state rather than a\n  healthy-looking zero, empty string, or empty collection.\n- Route, proxy, and compatibility layers translate protocols. Business\n  computation belongs in domain services or use-cases, and clients render the\n  resulting DTO.\n- Preserve public compatibility deliberately. Search exports, consumers,\n  templates, generated registry data, and contract tests before changing a\n  public surface.\n\n## Error policy: fail fast inside, handle at boundaries\n\nInner data paths throw typed errors. A designated process, transport, or UI\nboundary may translate the failure into a structured response or a visibly\ndistinct error/unavailable state. Do not catch and continue with fabricated\nsuccess.\n\nNew or rewritten domain failures use `ElizaError` from\n`packages/core/src/errors.ts` with an actionable `code`, relevant `context`, a\n`cause` when wrapping, and severity when appropriate. Diagnostic failures in\nproviders, services, background jobs, and event handlers call\n`runtime.reportError(scope, error, context?)`; the runtime logs them, emits\n`EventType.ERROR_REPORTED`, exposes them through `RECENT_ERRORS`, and supports\nowner escalation. Action/tool failures already return to the planner path.\n\nEvery retained catch must document one of these grep-able categories on the\nhandler with `// error-policy:J<N> <reason>`:\n\n- **J1 — boundary translation:** the outer process or transport boundary\n  returns a structured failure.\n- **J2 — context-adding rethrow:** wrap with a typed error and preserve `cause`.\n- **J3 — untrusted-input sanitizing:** parsing produces an explicit invalid\n  result, never a fake-valid default.\n- **J4 — user-facing degrade:** only an expected error shape becomes a visibly\n  distinct unavailable/error state.\n- **J5 — unhandled-rejection suppression:** the comment names where the same\n  rejection is observed.\n- **J6 — best-effort teardown:** teardown-only failure is logged at debug/warn.\n- **J7 — diagnostics must not kill the loop:** telemetry/trajectory failure is\n  warned and reported through `runtime.reportError`.\n\nEmpty catches, `.catch(() => {})`, log-and-continue data paths, default returns\nfrom catches, and `?? <literal>` used to disguise missing required data are not\nvalid recovery. In UI code, loading, designed-empty, and error are three\ndifferent states. The established examples are\n`packages/ui/src/components/pages/StreamView.tsx` and\n`packages/ui/src/state/usePluginsSkillsState.ts`.\n\n## File headers and comments\n\nEvery maintained source file begins with one prose `/** ... */` header after a\nshebang or third-party license block and before imports. The first sentence\nstates the file's system responsibility without repeating its filename. Add\nonly the context a reader cannot infer from the code: consumers, inputs,\ninvariants, protocol constraints, ownership boundaries, and non-obvious\nconsequences.\n\n- Tiny barrels and type files usually need one line; ordinary modules need two\n  to six; load-bearing modules may use two or three short paragraphs. Keep the\n  header under roughly 25 lines.\n- Test headers state the surface under test and whether the harness is real,\n  integration-backed, deterministic, or mocked.\n- Exported-symbol JSDoc serves callers. In-body `//` comments explain why a\n  design or ordering constraint exists.\n- Delete code narration, change history, migration stories, status notes,\n  commented-out code, and comments that merely restate the next statement.\n- Never edit generated files or third-party license text as part of comment\n  cleanup.\n\nUse these tone references:\n\n- `packages/agent/src/api/media-store.ts`\n- `packages/ui/src/components/RoleGate.tsx`\n- `packages/scripts/run-all-tests.mjs`\n- `.gitmodules`\n\nComment-only work must pass `bun run check:comment-only`, which verifies that\nthe code token stream is unchanged.\n\n## Cross-package invariants\n\n### Scheduling and personal-assistant domains\n\nThere is one clock and one scheduled-item architecture. Core `TaskService`\nowns when work runs. `@elizaos/plugin-scheduling` owns the storage-agnostic\n`ScheduledTask` state machine and runner. Personal-assistant and health domains\ncontribute structural records and registries; they do not create competing\nschedulers.\n\nBehavior must branch on typed fields such as `kind`, `trigger`, `shouldFire`,\n`completionCheck`, and `pipeline`, never on prose in `promptInstructions`.\nConnector delivery returns typed `DispatchResult`, not a boolean. Identity and\nrelationship changes go through the shared `EntityStore`, `RelationshipStore`,\nand merge engine. The authoritative implementation and contribution contracts\nare in:\n\n- `plugins/plugin-scheduling/README.md`\n- `plugins/plugin-personal-assistant/README.md`\n- `plugins/plugin-health/README.md`\n- `plugins/plugin-relationships/README.md`\n\n### Attachments and media\n\nAttachment bytes use the single content-addressed store in\n`packages/agent/src/api/media-store.ts`:\n`${STATE_DIR}/media/<sha256>.<ext>`, served from\n`/api/media/<sha256>.<ext>`. The SHA-256 URL is the canonical deduplicated\ncapability handle; `Media` in `packages/core/src/types/primitives.ts` is the\nin-message reference and may only be widened additively.\n\nDo not add a second file store, a storage selector, a `files` table, reference\ncounting, a second garbage collector, or a `fileId` field on `Media`. The\nexisting store uses `gcUnreferencedMedia` with a grace window. Server-side\nattachment fetches must pass through the SSRF guard in\n`packages/core/src/network` and `packages/core/src/media/fetch.ts`. The\npre-authenticated read route must not rewrite or rehost bytes; authenticated\nwrites may rehost. `ContentType` is frozen and append-only, so derive finer\nkinds from `mimeType` at read time.\n\n## Testing and verification\n\nRun focused checks while iterating, then expand in proportion to the affected\nsurface. At minimum, documentation changes must pass guide parity and link/path\nvalidation; code changes must pass the owning package's tests, typecheck, and\nlint plus the root `bun run verify` gate.\n\nTests must exercise the real contract being changed. Cover error, empty,\ninvalid-input, concurrency, authorization, and adversarial paths where they are\nmeaningful. A mock or stub standing in for the system under test is useful for\nunit coverage but is not end-to-end proof.\n\n### App visual review\n\nAny change in `packages/app`, or a shared UI change that reaches it, must run:\n\n```bash\nbun run --cwd packages/app audit:app\n```\n\nReview every affected desktop and mobile capture, including rest and hover\nstates. No touched view may retain a computed `needs-work` or `broken` verdict.\nRun at least five audit/inspection/iteration cycles for a meaningful redesign.\nOrange is the accent; do not introduce blue, and use darker orange—not black—\nfor an orange resting control's hover state. The full visual contract lives in\n`packages/app/CLAUDE.md`.\n\n## GitHub workflow and definition of done\n\nRead [`CONTRIBUTING.md`](CONTRIBUTING.md) before claiming coordinated work or\nopening a pull request. Issues define scoped acceptance criteria; GitHub\nProjects track live ownership and status; discussions coordinate across work;\nthe pull request carries the implementation and proof. Do not move a card to\n`Done` unless the board explicitly grants that authority.\n\n- Open an issue before a non-trivial change.\n- Use a `feat/`, `fix/`, `docs/`, or `chore/` branch and target `develop`.\n- Before opening or updating a PR, fetch and rebase on `origin/develop`, resolve\n  every conflict, run `bun install`, and run `bun run verify`.\n- Never push feature or fix work directly to `develop`.\n\nA reviewer must be able to verify the behavior without reading the code:\n\n1. Exercise the real path and inspect the result yourself. Green automation is\n   not a substitute for reviewing the generated artifact, pixels, audio, logs,\n   model trajectory, database row, scheduled item, or on-chain result.\n2. Use real integrations for end-to-end evidence. When agent behavior changes,\n   record live-model inputs and outputs; when a native/device/connector path\n   changes, run it on the real supported target.\n3. Leave no TODO, stub, fabricated success, or undocumented follow-up in the\n   delivered scope.\n\nFor frontend-testable work, include before/after full-page desktop and mobile\nscreenshots, an MP4 walkthrough, backend logs, frontend console/network logs,\nand any applicable live-model trajectories. Use `bun run test:matrix:review`\nfor the full evidence matrix, `bun run test:e2e:record:review` for scoped UI\nrecording, and the platform capture commands documented in `CONTRIBUTING.md` for\nnative targets. Build, install, and verify the current revision before capture;\ncapture tools do not prove that the installed application is current.\n\nEvidence belongs inline in the issue and PR, not committed to the repository.\nPrefer JPG screenshots, MP4 video, and collapsible log blocks. Mark a genuinely\ninapplicable evidence row `N/A` with a reason rather than leaving it blank.\n\n## Security and contribution references\n\nReport suspected vulnerabilities privately through\n[GitHub Security Advisories](https://github.com/elizaOS/eliza/security/advisories/new).\nDo not place exploit details, secrets, or embargoed dependency information in a\npublic issue, PR, log, or agent transcript. Product security documentation is\nin [`packages/docs/security.md`](packages/docs/security.md).\n\nThe repository is MIT licensed. Contribution workflow and evidence policy live\nin [`CONTRIBUTING.md`](CONTRIBUTING.md).\n","AGENTS.md":"# elizaOS repository guide\n\nThis monorepo contains the elizaOS agent framework and the product stack built\non it: the core runtime, standalone agent host, Eliza application, CLI, cloud\nservices, native bridges, documentation, tests, and first-party plugins.\nBootable Linux and AOSP distributions are maintained separately in\n[`elizaOS/os`](https://github.com/elizaOS/os).\n\n## How repository instructions work\n\n- Read this guide before changing the repository.\n- Before working in a package or plugin, read the nearest `CLAUDE.md` and its\n  `README.md`. A local guide adds package-specific architecture, commands, and\n  validation requirements; repository-wide rules in this guide remain binding.\n- `CLAUDE.md` and `AGENTS.md` in the same directory must be byte-for-byte\n  identical. Author `CLAUDE.md`, copy the finished content to `AGENTS.md`, and\n  run `bun run check:agents-claude`.\n- The `AGENTS.md` files under\n  `packages/elizaos/src/migrate/__tests__/fixtures/` are migration inputs, not\n  repository instructions. They are intentionally unpaired and must change only\n  when the corresponding migration fixture changes.\n- Treat package manifests, exports, executable scripts, tests, and current\n  source as the factual authority. Documentation is a map, not evidence that a\n  feature still exists.\n\n## Naming\n\nWrite **elizaOS**, never `ElizaOS`. The npm scope is `@elizaos/*`. Use\n**Eliza agents** for agents built with the framework. The **Eliza Classic**\nplugin is the deliberate exception because it reimplements the 1966 chatbot.\n\n## Before editing\n\n1. Run `git status --short --branch`. This is a shared working tree and existing\n   changes belong to their authors; do not discard, rewrite, or stage unrelated\n   work.\n2. Identify the owning workspace and read its local guide, README, manifest,\n   exports, and relevant tests.\n3. Search for callers and contract tests before changing a public type, route,\n   event, environment variable, script, or package export.\n4. Use the narrowest relevant command while iterating, then run the required\n   package and repository gates before declaring the work complete.\n\n## Toolchain\n\n- **Runtime:** Bun `1.3.14` and Node `24.15.0` are pinned in `package.json`.\n  Use the pinned versions; do not silently substitute npm, pnpm, Yarn, or an\n  older Node runtime.\n- **Modules:** ESM only (`\"type\": \"module\"`). Do not introduce CommonJS.\n- **Workspace orchestration:** Turbo drives package `build`, `typecheck`,\n  `lint`, and test tasks. Workspace globs are defined in `package.json`.\n- **TypeScript:** the repository uses project references through root and\n  package `tsconfig` files.\n- **Formatting and linting:** Biome is pinned by the repository. Configuration\n  lives in `biome.json` and exclusions in `.biomeignore`.\n- **Tests:** Vitest is the primary runner; repository lanes are orchestrated by\n  `packages/scripts/run-all-tests.mjs`.\n\n## Root commands\n\n```bash\nbun install            # install workspaces, prepare submodules, apply patches, sync artifacts\nbun run install:light  # install without the large artifact sync\nbun run dev            # start the API and Eliza app development UI\nbun run start          # start the standalone agent host\nbun run build          # build the workspace through Turbo\nbun run verify         # parity, dependency, type, lint, and repository audit gates\nbun run lint           # workspace lint tasks\nbun run format         # workspace formatting tasks\nbun run typecheck      # workspace TypeScript checks\nbun run test           # repository unit and integration lane\nbun run test:server    # server package lane\nbun run test:client    # client package lane\nbun run test:e2e       # end-to-end lane\nbun run cloud:mock     # start the local cloud stack with mocks\nbun run clean          # remove generated build, cache, install, and local-state output\nbun run reset          # clean, reinstall, and rebuild\n```\n\nRun `bun run` with no arguments for the live script inventory. Scope a package\ncommand with `bun run --cwd <workspace> <script>`, for example:\n\n```bash\nbun run --cwd packages/core test\nbun run --cwd plugins/plugin-browser typecheck\n```\n\n### Shared app development server\n\nUse the normal `bun run dev` flow for a single checkout. Concurrent worktrees\nmust not all bind the default app port. From `packages/app` use:\n\n```bash\nbun run dev:shared   # start or reuse this worktree's deterministic Vite port\nbun run dev:status   # list registered shared servers\nbun run dev:rebuild  # request a full Vite reload for this worktree\n```\n\nReservations live in `~/.eliza/dev-server-registry.json` and may be redirected\nwith `ELIZA_DEV_SERVER_REGISTRY`. See\n[`packages/docs/development/shared-dev-server.md`](packages/docs/development/shared-dev-server.md).\n\n### Removed root command migrations\n\n| Removed command | Use instead |\n| --- | --- |\n| `bun run test:ci` | `bun run test` |\n| `bun run test:cloud:playwright` | `bun run --cwd packages/app test:e2e` |\n| `bun run test:ui:playwright` | `bun run --cwd packages/app test:e2e` |\n| `bun run test:lifeops` | `bun run test:plugin 'plugin-personal-assistant'` |\n| `bun run trajectory:inspect:test` | `bun test packages/scripts/__tests__/trajectory-validate.test.ts` |\n| `bun run audit:e2e-coverage:test` | `bun test packages/scripts/e2e-coverage/check-e2e-coverage.test.ts` |\n| `bun run test:browser-bridge` | `bun run --cwd packages/browser-extension test` |\n| `bun run test:browser-bridge:safari` | `bun run --cwd packages/browser-extension test:smoke:safari` |\n| `bun run voice:latency-report` | `bun run --cwd packages/app-core voice:latency-report` |\n| `bun run voice:interactive` | `bun run --cwd packages/app-core voice:interactive` |\n| `bun run voice:duet` | `bun run --cwd packages/app-core voice:duet` |\n| `bun run voice:create-profile` | `bun run --cwd packages/app-core voice:create-profile` |\n| `bun run smartglasses:hardware:doctor` | `bun run --cwd packages/examples/smartglasses hardware:doctor` |\n| `bun run smartglasses:hardware:status` | `bun run --cwd packages/examples/smartglasses hardware:status-latest` |\n| `bun run smartglasses:hardware:validate` | `bun run --cwd packages/examples/smartglasses hardware:validate-latest` |\n| `bun run smartglasses:hardware:prove` | `bun run --cwd packages/examples/smartglasses hardware:prove:bleak` |\n| `bun run smartglasses:hardware:prove:watch` | `bun run --cwd packages/examples/smartglasses hardware:prove:bleak:watch` |\n| `bun run smartglasses:hardware:prove:noble` | `bun run --cwd packages/examples/smartglasses hardware:prove:noble` |\n| `bun run smartglasses:hardware:prove:noble:watch` | `bun run --cwd packages/examples/smartglasses hardware:prove:noble:watch` |\n| `bun run smartglasses:dev:hardware` | `bun run --cwd packages/examples/smartglasses dev:hardware` |\n| `bun run smartglasses:dev:simulator` | `bun run --cwd packages/examples/smartglasses dev:simulator` |\n| `bun run smartglasses:simulator` | `bun run --cwd packages/examples/smartglasses simulator` |\n| `bun run smartglasses:smoke:simulator` | `bun run --cwd packages/examples/smartglasses smoke:simulator` |\n| `bun run test:ci:live` | `bun run test:live` |\n| `bun run test:lint` | retired with its aggregate tooling; no direct replacement |\n| `bun run test:lint:no-vi-mocks` | `bun run audit:test-integrity:no-vi-mocks` |\n| `bun run test:lint:lane-coverage` | retired with its tooling; no replacement |\n| `bun run test:lint:test-integrity` | retired with its tooling; no replacement |\n| `bun run test:lint:test-integrity:self-test` | retired with its tooling; no replacement |\n| `bun run verify:smartglasses-software` | `bun run audit:smartglasses-software` |\n| `bun run personality:judge` | `bun run bench:personality` |\n| `bun run personality:bench:calibrate` | `bun run bench:personality:calibrate` |\n| `bun run lint:all` | `bun run verify` |\n| `bun run build:typescript` | `node packages/scripts/run-turbo.mjs run build` |\n| `bun run audit:mvp-board` | `bun run mvp:closeout-audit` |\n| `bun run mvp:board-readiness` | `bun run mvp:closeout-audit` |\n| `bun run mvp:evidence-matrix` | `bun run mvp:closeout-audit` |\n\n## Repository map\n\n```text\npackages/\n  core/             @elizaos/core: AgentRuntime, contracts, message loop, memory, models\n  agent/            @elizaos/agent: standalone runtime assembly and HTTP backend\n  app-core/         shared application host, APIs, startup, build, and platform tooling\n  app/              Eliza web, desktop, and mobile UI application\n  auth/             shared account credentials, OAuth, subscription, and refresh logic\n  ui/               shared React primitives and product surfaces\n  elizaos/          the elizaos CLI and packaged project/plugin templates\n  prompts/          shared prompt templates across supported languages\n  shared/           cross-package utilities, contracts, and brand assets\n  logger/           structured logging package\n  vault/            secrets and configuration storage adapters\n  skills/           bundled runtime skills and loading utilities\n  registry/         first-party and community plugin registry data and validation\n  scenario-runner/  real-runtime scenario execution and report generation\n  test/             repository-wide scenarios and test corpus\n  evidence/         evidence manifest, bundle, verification, and ingestion foundation\n  docs/             documentation site source\n  homepage/         public Eliza product and download site\n  training/         Eliza-1 training, evaluation, conversion, and release tooling\n  cloud/            API, shared libraries, routing, SDK, infrastructure, tests, services\n  native/           native runtimes, third-party dependencies, and C/C++ plugins\n\nplugins/\n  plugin-<provider>/ model and inference providers\n  plugin-<channel>/  messaging and workspace connectors\n  plugin-native-*/   platform and device bridges\n  plugin-*/          domain capabilities, app views, storage, tools, and orchestration\n\nscripts/            repository-wide checks, CI helpers, evidence, security, and release tools\npatches/            dependency patches applied during installation\n```\n\nSome directories are organizational roots rather than npm workspaces. Use the\nnearest manifest and local guide instead of inferring ownership from directory\ndepth.\n\n## Runtime architecture\n\n- `@elizaos/core` owns `AgentRuntime`, the canonical public types, the plugin\n  contract, the message loop, model abstraction, memory/state primitives, and\n  framework services.\n- `@elizaos/agent` assembles a runnable backend around core. It owns the\n  standalone process, plugin loading policy, HTTP/WebSocket surfaces, and\n  host-level services.\n- `@elizaos/app-core` hosts Eliza application targets and their compatibility\n  APIs, startup flow, platform integration, and build orchestration.\n- `@elizaos/app` and `@elizaos/ui` render product state. Business values belong\n  in use-cases and DTOs, not recomputed in view or proxy layers.\n- A plugin normally exports a `Plugin` from `src/index.ts`. Plugins may\n  contribute actions, providers, evaluators, services, model handlers, routes,\n  events, tests, and app views.\n- The `elizaos` CLI is package-first. Its templates under\n  `packages/elizaos/templates/` are governed by their `SCAFFOLD.md` contracts.\n\nWhen code needs only the framework, depend on `@elizaos/core`. Do not depend on\nan application host to reach a core abstraction.\n\n## Engineering conventions\n\n- Use the structured logger in server/runtime code; never use `console` there.\n  Prefix human-readable messages with the owning class or subsystem and attach\n  structured context to errors.\n- Keep boundary types explicit. Validate untrusted input once, then use the\n  validated type. Avoid `any`, broad `unknown`, unchecked casts, and optional\n  chaining that hides a required collaborator.\n- DTO fields are required by default. If the producer failed to load a value,\n  represent that as an error or explicit unavailable state rather than a\n  healthy-looking zero, empty string, or empty collection.\n- Route, proxy, and compatibility layers translate protocols. Business\n  computation belongs in domain services or use-cases, and clients render the\n  resulting DTO.\n- Preserve public compatibility deliberately. Search exports, consumers,\n  templates, generated registry data, and contract tests before changing a\n  public surface.\n\n## Error policy: fail fast inside, handle at boundaries\n\nInner data paths throw typed errors. A designated process, transport, or UI\nboundary may translate the failure into a structured response or a visibly\ndistinct error/unavailable state. Do not catch and continue with fabricated\nsuccess.\n\nNew or rewritten domain failures use `ElizaError` from\n`packages/core/src/errors.ts` with an actionable `code`, relevant `context`, a\n`cause` when wrapping, and severity when appropriate. Diagnostic failures in\nproviders, services, background jobs, and event handlers call\n`runtime.reportError(scope, error, context?)`; the runtime logs them, emits\n`EventType.ERROR_REPORTED`, exposes them through `RECENT_ERRORS`, and supports\nowner escalation. Action/tool failures already return to the planner path.\n\nEvery retained catch must document one of these grep-able categories on the\nhandler with `// error-policy:J<N> <reason>`:\n\n- **J1 — boundary translation:** the outer process or transport boundary\n  returns a structured failure.\n- **J2 — context-adding rethrow:** wrap with a typed error and preserve `cause`.\n- **J3 — untrusted-input sanitizing:** parsing produces an explicit invalid\n  result, never a fake-valid default.\n- **J4 — user-facing degrade:** only an expected error shape becomes a visibly\n  distinct unavailable/error state.\n- **J5 — unhandled-rejection suppression:** the comment names where the same\n  rejection is observed.\n- **J6 — best-effort teardown:** teardown-only failure is logged at debug/warn.\n- **J7 — diagnostics must not kill the loop:** telemetry/trajectory failure is\n  warned and reported through `runtime.reportError`.\n\nEmpty catches, `.catch(() => {})`, log-and-continue data paths, default returns\nfrom catches, and `?? <literal>` used to disguise missing required data are not\nvalid recovery. In UI code, loading, designed-empty, and error are three\ndifferent states. The established examples are\n`packages/ui/src/components/pages/StreamView.tsx` and\n`packages/ui/src/state/usePluginsSkillsState.ts`.\n\n## File headers and comments\n\nEvery maintained source file begins with one prose `/** ... */` header after a\nshebang or third-party license block and before imports. The first sentence\nstates the file's system responsibility without repeating its filename. Add\nonly the context a reader cannot infer from the code: consumers, inputs,\ninvariants, protocol constraints, ownership boundaries, and non-obvious\nconsequences.\n\n- Tiny barrels and type files usually need one line; ordinary modules need two\n  to six; load-bearing modules may use two or three short paragraphs. Keep the\n  header under roughly 25 lines.\n- Test headers state the surface under test and whether the harness is real,\n  integration-backed, deterministic, or mocked.\n- Exported-symbol JSDoc serves callers. In-body `//` comments explain why a\n  design or ordering constraint exists.\n- Delete code narration, change history, migration stories, status notes,\n  commented-out code, and comments that merely restate the next statement.\n- Never edit generated files or third-party license text as part of comment\n  cleanup.\n\nUse these tone references:\n\n- `packages/agent/src/api/media-store.ts`\n- `packages/ui/src/components/RoleGate.tsx`\n- `packages/scripts/run-all-tests.mjs`\n- `.gitmodules`\n\nComment-only work must pass `bun run check:comment-only`, which verifies that\nthe code token stream is unchanged.\n\n## Cross-package invariants\n\n### Scheduling and personal-assistant domains\n\nThere is one clock and one scheduled-item architecture. Core `TaskService`\nowns when work runs. `@elizaos/plugin-scheduling` owns the storage-agnostic\n`ScheduledTask` state machine and runner. Personal-assistant and health domains\ncontribute structural records and registries; they do not create competing\nschedulers.\n\nBehavior must branch on typed fields such as `kind`, `trigger`, `shouldFire`,\n`completionCheck`, and `pipeline`, never on prose in `promptInstructions`.\nConnector delivery returns typed `DispatchResult`, not a boolean. Identity and\nrelationship changes go through the shared `EntityStore`, `RelationshipStore`,\nand merge engine. The authoritative implementation and contribution contracts\nare in:\n\n- `plugins/plugin-scheduling/README.md`\n- `plugins/plugin-personal-assistant/README.md`\n- `plugins/plugin-health/README.md`\n- `plugins/plugin-relationships/README.md`\n\n### Attachments and media\n\nAttachment bytes use the single content-addressed store in\n`packages/agent/src/api/media-store.ts`:\n`${STATE_DIR}/media/<sha256>.<ext>`, served from\n`/api/media/<sha256>.<ext>`. The SHA-256 URL is the canonical deduplicated\ncapability handle; `Media` in `packages/core/src/types/primitives.ts` is the\nin-message reference and may only be widened additively.\n\nDo not add a second file store, a storage selector, a `files` table, reference\ncounting, a second garbage collector, or a `fileId` field on `Media`. The\nexisting store uses `gcUnreferencedMedia` with a grace window. Server-side\nattachment fetches must pass through the SSRF guard in\n`packages/core/src/network` and `packages/core/src/media/fetch.ts`. The\npre-authenticated read route must not rewrite or rehost bytes; authenticated\nwrites may rehost. `ContentType` is frozen and append-only, so derive finer\nkinds from `mimeType` at read time.\n\n## Testing and verification\n\nRun focused checks while iterating, then expand in proportion to the affected\nsurface. At minimum, documentation changes must pass guide parity and link/path\nvalidation; code changes must pass the owning package's tests, typecheck, and\nlint plus the root `bun run verify` gate.\n\nTests must exercise the real contract being changed. Cover error, empty,\ninvalid-input, concurrency, authorization, and adversarial paths where they are\nmeaningful. A mock or stub standing in for the system under test is useful for\nunit coverage but is not end-to-end proof.\n\n### App visual review\n\nAny change in `packages/app`, or a shared UI change that reaches it, must run:\n\n```bash\nbun run --cwd packages/app audit:app\n```\n\nReview every affected desktop and mobile capture, including rest and hover\nstates. No touched view may retain a computed `needs-work` or `broken` verdict.\nRun at least five audit/inspection/iteration cycles for a meaningful redesign.\nOrange is the accent; do not introduce blue, and use darker orange—not black—\nfor an orange resting control's hover state. The full visual contract lives in\n`packages/app/CLAUDE.md`.\n\n## GitHub workflow and definition of done\n\nRead [`CONTRIBUTING.md`](CONTRIBUTING.md) before claiming coordinated work or\nopening a pull request. Issues define scoped acceptance criteria; GitHub\nProjects track live ownership and status; discussions coordinate across work;\nthe pull request carries the implementation and proof. Do not move a card to\n`Done` unless the board explicitly grants that authority.\n\n- Open an issue before a non-trivial change.\n- Use a `feat/`, `fix/`, `docs/`, or `chore/` branch and target `develop`.\n- Before opening or updating a PR, fetch and rebase on `origin/develop`, resolve\n  every conflict, run `bun install`, and run `bun run verify`.\n- Never push feature or fix work directly to `develop`.\n\nA reviewer must be able to verify the behavior without reading the code:\n\n1. Exercise the real path and inspect the result yourself. Green automation is\n   not a substitute for reviewing the generated artifact, pixels, audio, logs,\n   model trajectory, database row, scheduled item, or on-chain result.\n2. Use real integrations for end-to-end evidence. When agent behavior changes,\n   record live-model inputs and outputs; when a native/device/connector path\n   changes, run it on the real supported target.\n3. Leave no TODO, stub, fabricated success, or undocumented follow-up in the\n   delivered scope.\n\nFor frontend-testable work, include before/after full-page desktop and mobile\nscreenshots, an MP4 walkthrough, backend logs, frontend console/network logs,\nand any applicable live-model trajectories. Use `bun run test:matrix:review`\nfor the full evidence matrix, `bun run test:e2e:record:review` for scoped UI\nrecording, and the platform capture commands documented in `CONTRIBUTING.md` for\nnative targets. Build, install, and verify the current revision before capture;\ncapture tools do not prove that the installed application is current.\n\nEvidence belongs inline in the issue and PR, not committed to the repository.\nPrefer JPG screenshots, MP4 video, and collapsible log blocks. Mark a genuinely\ninapplicable evidence row `N/A` with a reason rather than leaving it blank.\n\n## Security and contribution references\n\nReport suspected vulnerabilities privately through\n[GitHub Security Advisories](https://github.com/elizaOS/eliza/security/advisories/new).\nDo not place exploit details, secrets, or embargoed dependency information in a\npublic issue, PR, log, or agent transcript. Product security documentation is\nin [`packages/docs/security.md`](packages/docs/security.md).\n\nThe repository is MIT licensed. Contribution workflow and evidence policy live\nin [`CONTRIBUTING.md`](CONTRIBUTING.md).\n"}}