@aryasaatvik/motel 0.3.0

package/AGENTS.md

@@ -0,0 +1,180 @@
+# AGENTS.md
+
+## Commands
+- Install deps: `bun install`
+- Run the TUI: `bun run dev` or `bun run start` (auto-ensures a managed
+  OTLP daemon is running in the background so traces ingest while the TUI
+  is up)
+- Start the background daemon only: `bun run daemon` (same as `motel start`)
+- Stop the managed daemon: `bun run stop`
+- Daemon status JSON: `bun run status`
+- Restart the managed daemon only: `bun run restart`
+- Run the local server in the foreground (no daemon, no TUI): `bun run server`
+- Run tests: `bun run test`
+- Query services via CLI: `motel services`
+- Query traces via CLI: `motel traces <service> [limit]`
+- Query a span via CLI: `motel span <span-id>`
+- Query spans for one trace: `motel trace-spans <trace-id>`
+- Search spans via CLI: `motel search-spans [service] [operation] [parent=<operation>] [attr.key=value ...]`
+- Search traces via CLI: `motel search-traces [service] [operation] [attr.key=value ...]`
+- Query trace stats via CLI: `motel trace-stats <groupBy> <agg> [service] [attr.key=value ...]`
+- Query logs via CLI: `motel logs <service>`
+- Search logs via CLI: `motel search-logs [service] [body] [attr.key=value ...]`
+- Query log stats via CLI: `motel log-stats <groupBy> [service] [attr.key=value ...]`
+- Query logs for one trace: `motel trace-logs <trace-id>`
+- Query logs for one span: `motel span-logs <span-id>`
+- Query facets via CLI: `motel facets <traces|logs> <field>`
+- Print Effect setup instructions: `bun run instructions`
+- Build the web UI: `bun run web:build`
+- Dev the web UI (with hot reload): `bun run web:dev`
+- Typecheck: `bun run typecheck`
+- Effect LSP diagnostics over the whole project: `bunx effect-language-service diagnostics --project tsconfig.json --format text`
+- Effect LSP interactive setup wizard: `bunx effect-language-service setup`
+
+## Release Strategy
+- npm package: `@aryasaatvik/motel`
+- Releases are run from an attended local session with Tegami; GitHub Actions only validates pull requests.
+- Tags are versioned as `vX.Y.Z` (`git tag --sort=-version:refname` shows `v0.2.4`, `v0.2.3`, ...)
+- Add user-facing release notes under `.tegami/` and commit them with the implementation they describe.
+- `bun run version:packages` consumes pending entries, updates the package version and changelog, writes the publish lock, and opens or updates `tegami/version-packages` against `dev`.
+- After the version pull request is merged, run `bun run release` from a clean, current `dev` branch with npm and GitHub CLI authentication.
+- The release command runs typechecks, Effect diagnostics, tests, and package validation before Tegami publishes npm, pushes the matching `v<version>` tag, and creates the GitHub Release.
+- See `docs/release.md` for the attended release and verification procedure.
+- Publishing does not install or restart the machine-global Motel service; that cutover is a separate operation.
+
+## Effect LSP
+The repo is wired up with `@effect/language-service` as a `tsconfig.json` `plugins` entry. Editors that pick up the TypeScript workspace plugin (Zed, VSCode, Cursor, NVim via vtsls) will surface Effect-specific diagnostics, quick fixes, and refactors inline. In Zed this requires selecting the workspace TypeScript version — it does so automatically when `node_modules/typescript` is present.
+
+## Verification
+- The built-in verification step is `bun run typecheck`.
+- For runtime verification, start the TUI or server once, then query `http://127.0.0.1:27686/api/services`, `http://127.0.0.1:27686/api/spans/<span-id>`, `http://127.0.0.1:27686/openapi.json`, and `motel logs motel-otel-tui`.
+- For span-centric debugging, use `http://127.0.0.1:27686/api/spans/search?...`, `http://127.0.0.1:27686/api/spans/<span-id>/logs`, and `http://127.0.0.1:27686/api/traces/<trace-id>/spans`.
+
+## API Notes
+- List and search endpoints return a `meta` object with `limit`, `lookback`, `returned`, `truncated`, and `nextCursor`.
+- `/api/traces` and `/api/traces/search` return summaries by default. Use `/api/traces/<trace-id>` for the full trace tree.
+- `/api/logs` and `/api/logs/search` support `severity` (e.g. `?severity=ERROR`), case-insensitive body search, and `attrContains.<key>=<substring>` for substring search inside attribute values.
+- `/api/spans/search` supports `traceId` to scope to one trace, `attr.<key>=<value>` for exact match, and `attrContains.<key>=<substring>` for case-insensitive substring search inside attribute values.
+- `/api/ai/calls` searches AI SDK calls (streamText, generateText, etc.) with first-class filters for `model`, `provider`, `sessionId`, `functionId`, `operation`, `status`, `text` (cross-field search), and returns compact summaries with previews and token usage.
+- `/api/ai/calls/<span-id>` returns the full detail of a single AI call including complete prompt messages, response text, tool calls, timing, and correlated logs.
+- `/api/ai/stats` aggregates AI call statistics by `provider`, `model`, `functionId`, `sessionId`, or `status` with aggregations: `count`, `avg_duration`, `p95_duration`, `total_input_tokens`, `total_output_tokens`.
+- `/api/facets?type=traces&field=attribute_keys&service=<svc>` lists span-attribute keys for a service, ranked by discriminating power (keys with many distinct values first). Pair with `field=attribute_values&key=<key>` to list values for a specific key. Used by the TUI `f` attribute filter.
+- `/api/docs` lists available documentation; `/api/docs/debug` and `/api/docs/effect` return the full skill content.
+
+## Architecture
+- `src/index.tsx` creates the OpenTUI renderer and mounts the app.
+- `src/App.tsx` composes the top-level screen: header, footer, and the
+  drill-in workspace. Heavy logic is delegated to the modules below.
+- `src/ui/app/useTraceScreenData.ts` owns the atoms and data-loading
+  effects for traces, logs, services, and cache warming.
+- `src/ui/app/useAppLayout.ts` is the single source for layout math
+  (pane widths, body lines, viewport rows, drill-in level).
+- `src/ui/app/TraceWorkspace.tsx` renders the drill-in state machine:
+  L0 (trace list), L1 (waterfall), L2 (span detail), plus the service
+  logs side mode. When drilled in the list is hidden entirely and the
+  detail pane(s) expand to fill.
+- `src/ui/app/TraceListPane.tsx` hosts the trace list: header + optional
+  filter bar + virtual-windowed body (no opentui scrollbox — that had a
+  race with Yoga layout timing).
+- `src/ui/TraceList.tsx` exports `TraceListHeader` (the `TRACES 100 · ...`
+  strip) and `TraceListBody` (virtual-windowed rows with mouse-wheel
+  scrolling). The body owns its own scrollOffset state, preserves the
+  selected row's visual position across auto-refresh shifts, and snaps
+  the window to follow selection that moves off-screen.
+- `src/ui/Waterfall.tsx` renders the waterfall timeline with a
+  virtualised scroll viewport; `src/ui/waterfallNav.ts` is the pure
+  collapse/expand/walk resolver (unit-tested).
+- `src/ui/TraceDetailsPane.tsx` is the L1 body: header + waterfall.
+- `src/ui/SpanDetailPane.tsx` is the L2 body; renders
+  `src/ui/SpanDetail.tsx` below a header that owns the span identity.
+- `src/ui/useKeyboardNav.ts` centralises the keyboard handlers and
+  cross-pane navigation state transitions.
+- `src/motel.ts` composes and runs the public Effect command tree; `src/cli.ts` exports typed telemetry query leaves and handlers.
+- `src/runtime.ts` wires the Effect beta runtime and OTEL trace + log exporters.
+- `src/localServer.ts` starts the local Bun OTLP/query server.
+- `src/httpApi.ts` defines the typed Effect HttpApi surface and OpenAPI spec for the local server.
+- `src/httpListPolicy.ts` owns pure HTTP list/search parameter decoding, bounds, cursors, and pagination metadata shaping.
+- `src/server.ts` runs the local server without the TUI.
+- `src/instructions.ts` contains the copied setup instructions for other Effect apps.
+- `src/services/TelemetryStore.ts` persists traces and logs in SQLite and exposes indexed queries through writer and read-only service identifiers.
+- `src/services/TelemetryQuery.ts` proxies read-only store calls to `src/services/telemetryQueryWorker.ts`, keeping synchronous Bun SQLite queries off the HTTP event loop.
+- `src/config.ts` is the source of truth for ports and env-driven OTEL settings.
+- `web/` is a Vite + React SPA for the browser-based UI (Tailwind CSS, `@effect/atom-react`, `AtomHttpApi`).
+- `web/src/api.ts` creates the typed `AtomHttpApi.Service` client from `src/httpApi.ts`.
+- `web/src/pages/` contains route pages: TracesPage, TraceDetailPage, LogsPage, AiCallsPage.
+- `web/src/components/` contains Waterfall and SpanDetail components.
+- The server in `src/localServer.ts` serves `web/dist/` as static files with SPA fallback for non-API routes.
+
+## Tests
+- `bun run test` runs the suite. Three kinds of tests live in the repo:
+  - `src/telemetry.test.ts` exercises the SQLite TelemetryStore with
+    OTLP payloads end-to-end.
+  - `src/ui/waterfallNav.test.ts` unit-tests the pure collapse/expand
+    resolver (no UI).
+  - `src/ui/*.repro.test.ts` drive the real TUI under `tuistory` to
+    reproduce regressions, using deterministic traces seeded into SQLite
+    by child processes. They become no-op passes when `tuistory` is absent.
+
+## Effect Observability Guidance
+- Inspect the target repo’s existing Effect runtime and observability wiring before adding anything new.
+- Prefer the repo’s existing Effect-native observability APIs if available.
+- If `effect/unstable/observability` is already the best fit, prefer it over adding `@effect/opentelemetry`.
+- Only add new OpenTelemetry SDK packages when the repo already uses them or they are clearly required.
+- Merge telemetry into the main runtime once, not per-feature.
+- Prefer structured log annotations so fields like `sessionID`, `modelID`, `providerID`, and `tool` are queryable.
+
+## Local OTEL Ports
+- Local API / UI base: `http://127.0.0.1:27686`
+- OTLP HTTP traces: `http://127.0.0.1:27686/v1/traces`
+- OTLP HTTP logs: `http://127.0.0.1:27686/v1/logs`
+- Health: `http://127.0.0.1:27686/api/health`
+
+## Env Vars
+- `MOTEL_OTEL_ENABLED`: defaults to `false` (set to `true` to emit self-traces for debugging motel itself)
+- `MOTEL_OTEL_SERVICE_NAME`: defaults to `motel-otel-tui`
+- `MOTEL_OTEL_BASE_URL`: defaults to `http://127.0.0.1:27686`
+- `MOTEL_OTEL_HOST`: defaults to `127.0.0.1`
+- `MOTEL_OTEL_PORT`: defaults to `27686`
+- `MOTEL_OTEL_EXPORTER_URL`: defaults to `http://127.0.0.1:27686/v1/traces`
+- `MOTEL_OTEL_LOGS_EXPORTER_URL`: defaults to `http://127.0.0.1:27686/v1/logs`
+- `MOTEL_OTEL_QUERY_URL`: defaults to `http://127.0.0.1:27686`
+- `MOTEL_OTEL_DB_PATH`: defaults to `${XDG_STATE_HOME:-~/.local/state}/motel/telemetry.sqlite` (one shared DB per machine; daemon log + lock + instance registry live in the same directory)
+- `MOTEL_RUNTIME_DIR`: overrides the daemon log, lock, and instance-registry directory (primarily for isolated tests and custom managed instances)
+- `MOTEL_OTEL_TRACE_LOOKBACK_MINUTES`: defaults to `1440` (24h)
+- `MOTEL_OTEL_TRACE_LIMIT`: defaults to `100`
+- `MOTEL_OTEL_LOG_LIMIT`: defaults to `80`
+- `MOTEL_OTEL_RETENTION_HOURS`: defaults to `168` (7d)
+- `MOTEL_OTEL_MAX_DB_SIZE_MB`: defaults to `1024` (size-based retention cap)
+- `MOTEL_OTEL_RETENTION_TRACE_BATCH`: defaults to `100` completed traces per cleanup pass
+- `MOTEL_OTEL_RETENTION_LOG_BATCH`: defaults to `5000` logs per cleanup pass
+- `MOTEL_OTEL_RETENTION_INTERVAL_SECONDS`: defaults to `10`
+
+## TUI Keys
+- `?`: toggle shortcut help
+- `j` / `k` or `up` / `down`: move trace or span selection
+- `h` / `left`: collapse current span, or step to parent
+- `l` / `right`: expand current span, or step to first child
+- `ctrl-n` / `ctrl-p`: switch traces while staying in the details area
+- `gg` / `home`: jump to the first trace or span
+- `G` / `end`: jump to the last trace or span
+- `ctrl-u` / `pageup`: page up
+- `ctrl-d` / `pagedown`: page down
+- `enter`: drill in one level (list → waterfall → span detail)
+- `esc`: back out one level
+- `tab`: toggle service logs view
+- `[` / `]`: switch services
+- `s`: cycle sort mode (recent → slowest → errors)
+- `t`: cycle theme (motel-default → tokyo-night → catppuccin)
+- `/`: enter filter mode.
+  - **In the trace list (L0)** the input matches against the root operation name. Composable modifiers:
+    - `:error` — restrict to traces with at least one failed span (client-side)
+    - `:ai <query>` — FTS5-backed search against LLM prompt/response/tool content (`AI_FTS_KEYS`) across every span in the trace. Tokens are prefix-matched and implicitly AND'd. Debounced 250ms.
+    - Modifiers compose: `/ :ai rate limit :error`
+  - **In the waterfall (L1/L2)** the input runs a client-side substring match against each span's operation name and tag values. Non-matching spans are dimmed; the filter bar shows the live match count. `enter` commits (dim persists while you navigate); `esc` clears.
+- `f`: open attribute filter picker (browse span-attribute keys → values for the current service; `backspace` walks back to keys; `esc` in the trace list clears the active filter)
+- `a`: pause or resume auto-refresh
+- `r`: refresh now
+- `c`: copy setup instructions for another Effect app
+- `o`: open selected trace in the browser
+- `y`: copy selected trace or span id
+- `q`: quit

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kit Langton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,137 @@
+# motel
+
+A local OpenTelemetry ingest + TUI viewer for development, backed by
+SQLite. Point your app's OTLP/HTTP exporters at the local motel server
+and debug with real runtime evidence — from a terminal, the built-in web
+UI, or directly from an AI coding agent.
+
+## For agents: install the motel-debug skill
+
+`motel` ships a companion skill that teaches Claude Code, OpenCode,
+Cursor, Codex, and 40+ other agents how to debug with runtime evidence
+by querying motel's local OTLP store. Install it once and any future
+agent session in the project will know how to use it.
+
+```bash
+# Project-local (adds to .claude/skills, .agents/skills, etc.)
+npx skills add aryasaatvik/motel --skill motel-debug
+
+# Or globally, for every project
+npx skills add aryasaatvik/motel --skill motel-debug -g
+```
+
+See the full skill at [`skills/motel-debug/SKILL.md`](skills/motel-debug/SKILL.md).
+
+## For humans: install and run the TUI
+
+motel is distributed on npm as `@aryasaatvik/motel`. The binary is a Bun
+script, so Bun must be on your `PATH` at runtime:
+
+```bash
+# one-off (no install)
+bunx @aryasaatvik/motel
+
+# or install globally
+bun add -g @aryasaatvik/motel
+motel
+
+# npm also works (Bun still required to run it)
+npm install -g @aryasaatvik/motel
+```
+
+Don't have Bun?
+
+```bash
+curl -fsSL https://bun.sh/install | bash
+```
+
+`motel` starts the local OTLP ingest server on
+`http://127.0.0.1:27686` and launches the TUI. Press `?` once inside for
+the keyboard cheat sheet, or `c` to copy paste-ready setup instructions
+for any Effect/OTEL app you want to trace.
+
+Requirements: [Bun](https://bun.sh/) v1.1 or newer.
+
+### macOS service from the maintained checkout
+
+The per-user LaunchAgent intentionally runs
+`~/.bun/bin/bun ~/.bun/bin/motel server`. For a maintained-checkout
+installation, prepare and link the merged `dev` checkout before installing
+the service:
+
+```bash
+bun install --frozen-lockfile
+bun run web:build
+bun link
+motel service install
+```
+
+This service path does not discover npm-global or arbitrary `PATH`
+executables. `motel service install` verifies both stable Bun bin paths before
+writing or loading the LaunchAgent. Re-running it leaves an equivalent loaded
+service unchanged and loads an equivalent definition that is currently
+unloaded.
+
+## How your app connects
+
+Once motel is running, point your app's OTLP/HTTP exporters at these
+local endpoints:
+
+```
+http://127.0.0.1:27686/v1/traces
+http://127.0.0.1:27686/v1/logs
+```
+
+Motel keeps everything in a machine-global local SQLite database at
+`${XDG_STATE_HOME:-~/.local/state}/motel/telemetry.sqlite`. One managed
+daemon is shared across local projects. No Docker, no cloud account.
+
+The store retains seven days of telemetry by default and targets a 1 GB
+active-data ceiling using bounded background batches. Recent data is preserved while
+the oldest completed traces and logs are removed first. Configure the policy
+with `MOTEL_OTEL_RETENTION_HOURS`, `MOTEL_OTEL_MAX_DB_SIZE_MB`,
+`MOTEL_OTEL_RETENTION_TRACE_BATCH`, `MOTEL_OTEL_RETENTION_LOG_BATCH`, and
+`MOTEL_OTEL_RETENTION_INTERVAL_SECONDS`. Existing databases created without
+incremental auto-vacuum are never silently rewritten at startup; deleted pages
+are reused, but shrinking such a historical file requires an explicit offline
+SQLite `VACUUM` chosen by the user.
+
+## How agents connect
+
+Agents with the `motel-debug` skill installed will automatically use
+motel's HTTP API. The full OpenAPI spec is at
+`http://127.0.0.1:27686/openapi.json` — the key endpoints are:
+
+```
+GET /api/health                              liveness check
+GET /api/services                            services reporting telemetry
+GET /api/traces?service=<service>            recent traces for a service
+GET /api/traces/<trace-id>                   full trace tree
+GET /api/spans/<span-id>                     single span + logs
+GET /api/logs?service=<service>              recent logs
+GET /api/traces/search?...                   structured trace search
+GET /api/logs/search?...                     structured log search
+GET /api/ai/calls                            AI SDK call inspector
+```
+
+## TUI keys
+
+- `?` — keyboard cheat sheet
+- `j` / `k` or `↑` / `↓` — move selection
+- `enter` / `esc` — drill in / back out (trace → waterfall → span detail)
+- `[` / `]` — switch service
+- `tab` — toggle service logs
+- `/` — filter traces
+- `s` — cycle sort (recent → slowest → errors)
+- `t` — cycle theme
+- `c` — copy paste-ready setup instructions for another app
+- `o` — open selected trace in the browser
+- `q` — quit
+
+## Privacy note
+
+motel is a local development tool, but your app can emit sensitive
+telemetry. Correlated logs may include secrets, tokens, or PII if your
+app logs them; AI call traces may include full prompt content and
+response text. Treat the local SQLite store as sensitive development
+data when pointing motel at real workloads.

package/package.json

@@ -0,0 +1,119 @@
+{
+  "name": "@aryasaatvik/motel",
+  "version": "0.3.0",
+  "description": "A local OpenTelemetry ingest + TUI viewer for development, backed by SQLite.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Kit Langton",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aryasaatvik/motel.git"
+  },
+  "homepage": "https://github.com/aryasaatvik/motel#readme",
+  "bugs": {
+    "url": "https://github.com/aryasaatvik/motel/issues"
+  },
+  "keywords": [
+    "opentelemetry",
+    "otel",
+    "tracing",
+    "observability",
+    "tui",
+    "sqlite",
+    "effect",
+    "opentui"
+  ],
+  "workspaces": [
+    "web"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "overrides": {
+    "@grpc/grpc-js": "1.14.4",
+    "protobufjs": "7.6.4",
+    "shell-quote": "1.9.0",
+    "ws": "8.21.0"
+  },
+  "files": [
+    "src",
+    "web/dist",
+    "skills/motel-debug/SKILL.md",
+    "skills/motel-debug/references/effect.md",
+    "LICENSE",
+    "README.md",
+    "AGENTS.md"
+  ],
+  "bin": {
+    "motel": "src/motel.ts",
+    "motel-mcp": "src/mcp.ts"
+  },
+  "scripts": {
+    "clear-motel-debug": "bun run skills/motel-debug/scripts/clear-motel-debug.ts",
+    "dev": "MOTEL_OTEL_ENABLED=true bun run src/motel.ts tui",
+    "start": "bun run src/motel.ts tui",
+    "daemon": "bun run src/motel.ts daemon",
+    "status": "bun run src/motel.ts status",
+    "stop": "bun run src/motel.ts stop",
+    "restart": "bun run src/motel.ts restart",
+    "server": "bun run src/motel.ts server",
+    "mcp": "bun run src/mcp.ts",
+    "test": "bun test",
+    "cli": "bun run src/motel.ts",
+    "instructions": "bun run src/motel.ts instructions",
+    "services": "bun run src/motel.ts services",
+    "logs": "bun run src/motel.ts logs",
+    "trace-logs": "bun run src/motel.ts trace-logs",
+    "span-logs": "bun run src/motel.ts span-logs",
+    "span": "bun run src/motel.ts span",
+    "trace-spans": "bun run src/motel.ts trace-spans",
+    "search-spans": "bun run src/motel.ts search-spans",
+    "trace-stats": "bun run src/motel.ts trace-stats",
+    "log-stats": "bun run src/motel.ts log-stats",
+    "web:dev": "bun run --cwd web dev",
+    "web:build": "bun run --cwd web build",
+    "story:chat": "bun run src/storybook/aiChatStory.tsx",
+    "bench:motel-cold-start": "bun run scripts/bench-motel-cold-start.ts",
+    "bench:ingest-logs": "bun run scripts/bench-ingest-logs.ts",
+    "bench:ingest-traces": "bun run scripts/bench-ingest-traces.ts",
+    "bench:search-spans": "bun run scripts/bench-search-spans.ts",
+    "tegami": "bun scripts/tegami.mts",
+    "version:packages": "bun run tegami version",
+    "release:check": "bun run typecheck && bun run web:typecheck && bunx effect-language-service diagnostics --project tsconfig.json --format text && bun run test && bun run release:validate",
+    "release": "bun run release:check && bun run tegami publish",
+    "release:validate": "bun run scripts/validate-release.ts",
+    "typecheck": "tsc --noEmit",
+    "web:typecheck": "tsc --noEmit -p web/tsconfig.json",
+    "prepublishOnly": "bun run web:build"
+  },
+  "devDependencies": {
+    "@effect/language-service": "0.87.1",
+    "@types/bun": "^1.3.14",
+    "@types/react": "^19.2.17",
+    "tegami": "1.2.6",
+    "typescript": "^6.0.3"
+  },
+  "dependencies": {
+    "@effect/atom-react": "4.0.0-beta.101",
+    "@effect/opentelemetry": "4.0.0-beta.101",
+    "@effect/platform-bun": "4.0.0-beta.101",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.219.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.219.0",
+    "@opentelemetry/otlp-transformer": "0.214.0",
+    "@opentelemetry/sdk-logs": "^0.219.0",
+    "@opentelemetry/sdk-node": "^0.219.0",
+    "@opentelemetry/sdk-trace-base": "^2.8.0",
+    "@opentelemetry/sdk-trace-node": "^2.8.0",
+    "@opentui/core": "0.4.2",
+    "@opentui/react": "0.4.2",
+    "effect": "4.0.0-beta.101",
+    "protobufjs": "7.6.4",
+    "react": "^19.2.7",
+    "scheduler": "^0.27.0"
+  }
+}

package/skills/motel-debug/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: motel-debug
+description: Debug applications with motel, a local OpenTelemetry ingest and query server. Use when the user wants runtime-evidence debugging with traces or logs, wants temporary debug instrumentation that can be removed later, or needs a repo wired to send OTLP/HTTP telemetry to a local motel server. If the target repo uses Effect or @effect/*, also read references/effect.md.
+---
+
+# Motel Debug
+
+You are in **debug mode**. Debug with runtime evidence, not guesswork.
+
+Agents guess based on code alone. You need actual runtime data. Motel is the local OpenTelemetry server that collects traces and logs — use it as your evidence loop.
+
+Default local server details:
+
+- Base URL: `http://127.0.0.1:27686`
+- OTLP traces: `POST /v1/traces`
+- OTLP logs: `POST /v1/logs`
+- Query API: `GET /api/*`
+- OpenAPI: `GET /openapi.json`
+- Header: `Content-Type: application/json`
+- Auth: none by default
+
+If the user provides a different motel URL, use that instead of the default.
+
+## Workflow
+
+### 1. Verify motel is running — and start it if not
+
+Check `GET /api/health`. If it returns 200, continue.
+
+If it fails (connection refused, timeout, non-200), motel isn't running.
+Start it as a background daemon — **do not** launch the TUI, which is
+interactive and will block your shell:
+
+```bash
+motel start
+```
+
+`motel start` ensures the machine-global managed daemon is running, writes
+runtime files under `${XDG_STATE_HOME:-~/.local/state}/motel/`, and returns a
+JSON status blob. It is idempotent and shared across local projects. If motel isn't on `PATH`, fall
+back to `bunx @aryasaatvik/motel start`.
+
+After starting, re-check `GET /api/health` (may take 1–2s to become
+ready). If it still fails, read `${XDG_STATE_HOME:-~/.local/state}/motel/daemon.log` for the error
+and surface it to the user.
+
+Other lifecycle commands, for reference:
+
+```bash
+motel status   # JSON status (running? pid? originating workdir?)
+motel stop     # stop the shared managed daemon for all local projects
+```
+
+Discover reporting services with `GET /api/services` when needed.
+
+### 2. Generate hypotheses
+
+Before touching any code, generate **3-5 specific hypotheses** about why the bug occurs. Be precise — "the cache key doesn't include the user ID" is better than "something is wrong with caching."
+
+### 3. Instrument with tagged debug blocks
+
+Add the minimum instrumentation needed to confirm or reject **all** hypotheses in parallel. Every debug block must:
+
+- Be wrapped in `#region motel debug` / `#endregion motel debug` markers
+- Include a `debug.hypothesis` attribute linking it to a specific hypothesis
+- Use whatever tracing/logging mechanism the codebase already has (spans, structured logs, annotations — not raw `fetch` calls)
+
+Tag every piece of debug instrumentation with structured attributes so you can query it later. Reuse these keys:
+
+| Key | Purpose |
+|-----|---------|
+| `debug.session` | Groups all instrumentation for this debug session |
+| `debug.hypothesis` | Links to a specific hypothesis (e.g. `"cache-miss"`, `"A"`) |
+| `debug.step` | Position in the flow (e.g. `"entry"`, `"before-write"`, `"after-read"`) |
+| `debug.label` | Human-readable description of what this point captures |
+
+Choose log placements based on your hypotheses:
+
+- Function entry with parameters
+- Function exit with return values
+- Values before and after critical operations
+- Branch execution paths (which if/else ran)
+- State mutations and intermediate values
+- Suspected error or edge-case values
+
+Guidelines:
+
+- At least 1 instrumentation point is required; never skip instrumentation
+- Do not exceed 10 — if you think you need more, narrow your hypotheses
+- Typical range is 2-6
+
+### 4. Reproduce the issue
+
+- If a failing test exists, run it directly
+- If reproduction is straightforward (CLI command, curl, simple script), write and run it yourself
+- Otherwise, ask the user to reproduce — provide clear numbered steps and remind them to restart if needed
+- Once a reproduction pathway is established, reuse it for all subsequent iterations
+
+### 5. Analyze evidence
+
+Query motel for the debug instrumentation:
+
+```bash
+curl "http://127.0.0.1:27686/api/spans/search?service=<service>&attr.debug.hypothesis=<id>"
+curl "http://127.0.0.1:27686/api/logs/search?service=<service>&attr.debug.session=<session>"
+curl "http://127.0.0.1:27686/api/traces/search?service=<service>&attr.debug.hypothesis=<id>"
+```
+
+For each hypothesis, evaluate: **CONFIRMED**, **REJECTED**, or **INCONCLUSIVE** — cite specific spans, logs, or attribute values as evidence.
+
+### 6. Fix only with evidence
+
+Do **not** fix without runtime evidence. When you fix:
+
+- Keep all debug instrumentation in place — do not remove it yet
+- Make the fix as small and targeted as possible
+- Reuse existing architecture and patterns; do not overengineer
+
+### 7. Verify the fix
+
+Reproduce the issue again with instrumentation still active. Compare before/after evidence:
+
+- Cite specific log lines or span attributes that prove the fix works
+- If the fix failed: **revert code changes from rejected hypotheses** (do not let speculative fixes accumulate), generate new hypotheses from different subsystems, add more instrumentation, and iterate
+- Iteration is expected. Taking longer with more data yields better fixes.
+
+### 8. Clean up
+
+Only after the fix is verified **and** the user confirms there are no remaining issues:
+
+- Run the cleanup script or remove blocks manually (see Cleanup section below)
+- Run `git diff` to confirm only the intentional fix remains
+
+## Instrumentation Rules
+
+Wrap every temporary debug block in these exact markers:
+
+```ts
+// #region motel debug
+// temporary debug instrumentation
+// #endregion motel debug
+```
+
+Use whatever the codebase already provides for tracing and logging. The markers are language-comment wrappers — adapt the comment syntax for non-JS/TS files (e.g. `# #region motel debug` for Python).
+
+**Do not:**
+- Log secrets, tokens, passwords, or raw PII
+- Remove instrumentation before post-fix verification succeeds
+- Use `setTimeout`, `sleep`, or artificial delays as a "fix"
+- Let code changes from rejected hypotheses accumulate — revert them
+
+## Query Patterns
+
+Two filter prefixes for attribute search:
+
+| Prefix | Match type | Example |
+|--------|-----------|---------|
+| `attr.<key>=<value>` | Exact match | `attr.debug.hypothesis=cache-miss` |
+| `attrContains.<key>=<substring>` | Case-insensitive substring | `attrContains.ai.prompt.messages=hello world` |
+
+```bash
+curl http://127.0.0.1:27686/api/health
+curl http://127.0.0.1:27686/api/services
+
+# Trace search
+curl "http://127.0.0.1:27686/api/traces/search?service=<service>&operation=<text>&attr.debug.session=<session>"
+
+# Span search (supports traceId to scope to one trace)
+curl "http://127.0.0.1:27686/api/spans/search?service=<service>&traceId=<trace-id>&attr.debug.hypothesis=<id>"
+curl "http://127.0.0.1:27686/api/spans/search?service=<service>&attrContains.ai.prompt.messages=<phrase>"
+
+# Log search (supports severity filter, case-insensitive body search)
+curl "http://127.0.0.1:27686/api/logs/search?service=<service>&severity=ERROR&body=<text>"
+curl "http://127.0.0.1:27686/api/logs/search?service=<service>&attrContains.debug.label=<substring>"
+
+# AI call search (compact summaries with previews)
+curl "http://127.0.0.1:27686/api/ai/calls?model=gpt-5.4&sessionId=<session>"
+curl "http://127.0.0.1:27686/api/ai/calls?text=<phrase>&status=error"
+
+# AI call detail (full prompt/response payloads)
+curl "http://127.0.0.1:27686/api/ai/calls/<span-id>"
+
+# AI stats
+curl "http://127.0.0.1:27686/api/ai/stats?groupBy=model&agg=total_input_tokens"
+
+curl http://127.0.0.1:27686/openapi.json
+```
+
+List and search responses include `meta.nextCursor` when more data is available.
+
+Motel gives you trace-correlated data — you can see which span a debug log belongs to, the parent operation, timing, and the full trace tree. Use `GET /api/traces/<trace-id>/spans` and `GET /api/spans/<span-id>/logs` to navigate the correlation.
+
+For AI/LLM calls, use `/api/ai/calls` for compact searchable summaries (with prompt/response previews and token usage), and `/api/ai/calls/<span-id>` for full payloads.
+
+## Effect
+
+If the target repo uses Effect, read `references/effect.md` before changing runtime wiring or adding instrumentation.
+
+## Cleanup
+
+Use the bundled script at `scripts/clear-motel-debug.ts` when you want deterministic cleanup. It removes every block between `#region motel debug` and `#endregion motel debug` in JS/TS files and fails on unmatched markers.
+
+If you cannot run the script, delete every marked block manually and then grep for `#region motel debug` to confirm none remain.