The TypeScript quickstart ONLY covers the Mastra framework path. If a developer uses Express, Fastify, Hono, or custom Node.js, there's no "raw OTLP + @arizeai/phoenix-otel" quickstart. The Python quickstart has auto_instrument=True for any framework, but TS has no equivalent generic path in the getting-started flow. The SDK reference page has the info — but it's not surfaced in the quickstart where devs land first.
Add a "Framework-agnostic" tab to the TS quickstart showing raw register() + manual span creation with @arizeai/phoenix-otel. Mirror the Python quickstart's framework-agnostic approach.
PROMPT.md is excellent for LLM call instrumentation — the routing table, phase 1/2 approach, and framework detection are well-designed. But it doesn't cover how to trace non-LLM operations: template selection, prompt assembly, data retrieval, custom business logic spans. Complex agents do far more than call LLMs — they orchestrate pipelines. I traced these exact patterns in my Phoenix Report (template selection → prompt assembly → provider dispatch) and this pattern isn't documented for agents to follow.
Add a "Custom spans for non-LLM operations" section to PROMPT.md showing how to create CHAIN, TOOL, and RETRIEVER spans for business logic. Include the withSpan() helper from @arizeai/phoenix-otel.
There's a "What is the difference between Phoenix and Arize" FAQ page, but no single "I'm running Phoenix locally, now I want to move to Arize AX" migration guide. The information exists across the self-hosting docs, AX quickstart, and the comparison page — but a developer doing the actual migration has to assemble it themselves. This is a critical conversion funnel gap: Phoenix OSS → paid AX customer.
Create a single "Graduate from Phoenix to Arize AX" page with: 1) What changes (endpoint, API key, features gained), 2) Code diff showing the 3-line change, 3) What you keep vs. what's new. Make it the obvious next step from every self-hosting page.
Node.js requires @opentelemetry/exporter-trace-otlp-proto instead of the default HTTP JSON exporter — otherwise you get HTTP 415 errors with zero explanation. The quickstart uses @arizeai/phoenix-otel which handles this internally, but if anyone follows the manual OTel setup path (common for existing apps with OTel already configured), this gotcha isn't documented until you hit the error. I discovered and documented this in my Phoenix Report.
Add a troubleshooting callout to the TS quickstart and the tracing FAQ: "Getting HTTP 415? You need the protobuf OTLP exporter (@opentelemetry/exporter-trace-otlp-proto), not the default HTTP JSON exporter."
ESM (ES Modules) vs. CommonJS compatibility is a well-known pain point in the Node.js OpenTelemetry ecosystem. I had to pin specific package versions to get ESM working with Phoenix. The docs don't mention ESM at all — not in the quickstart, not in the SDK reference, not in troubleshooting. Every modern Node.js project using "type": "module" in package.json will hit this.
Add an "ESM / CommonJS" section to the TS setup docs noting which packages need version pinning and what "type": "module" means for OTel initialization order.
The job posting says "make documentation work for coding agents as well as humans" and "real measurement of whether agents can complete tasks using docs alone." The px setup CLI's exit code 6 (configured but unverified) is a start. But there's no broader framework for measuring whether docs are agent-readable — no scoring, no automated testing, no benchmarks. This is the role's most novel requirement and the biggest whitespace.
Build an agent-readability scoring system for Arize docs. I've already built this: my Poly-Glot Markdown RAG/GEO scorer measures documentation quality for AI consumption on a 0–100 scale. Adapt this approach to score Arize docs for: frontmatter completeness, heading hierarchy, chunk boundaries, code sample correctness, and agent task-completion rate.
Of 20+ cookbooks listed in the Phoenix docs, only 2–3 are TypeScript. The vast majority are Python-only. Given the explosive growth of the TS/JS agent ecosystem — Mastra, Vercel AI SDK, LangChain.js, OpenAI Agents SDK (Node) — this is a significant coverage gap. Arize already supports these frameworks, but there's no cookbook showing a complete workflow.
Create TypeScript versions of the top 5 most-visited Python cookbooks. Prioritize: Agentic RAG Tracing, Structured Data Extraction, and the Iterative Eval & Experimentation workflow (which already has a TS version — good precedent to follow).