feat: OpenTelemetry LGTM observability, dev tooling, and memoir UX fixes (#31)

* add staging ios app build script

* feat(api): add OpenTelemetry LGTM stack for local observability

Wire OTel traces, metrics, and logs through a collector to Tempo,
Prometheus, and Loki, with custom LLM instrumentation, dev compose overlay,
Grafana provisioning, env templates, and development.sh auto-start.

Co-authored-by: Cursor <cursoragent@cursor.com>

* feat: expand observability, harden dev tooling, and fix expo staging UX

Add business and LLM Prometheus metrics with Grafana dashboards, alerting,
and a metrics verification script. Wire telemetry through adapters and core
LLM paths, and document the local LGTM workflow.

Fix development.sh for macOS bash 3.2, open Grafana and eval-web in Chrome,
and repair eval-web auto-open (unbound EVAL_WEB_BROWSER_SCHEDULED). Merge
internal-eval into the main dev script with improved compose handling.

Require EXPO_PUBLIC_* at build time, improve iOS HTTP ATS for staging IPs,
show memoir empty state instead of load errors when no chapters exist, and
add jest env setup plus chapter list response normalization.

Co-authored-by: Cursor <cursoragent@cursor.com>

* chore: enable Grafana Assistant Cursor plugin

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: memoir empty state and repair withdrawn 0020_chapters_book_id stamp

Show empty memoir UI when the chapter list succeeds with no items; treat auth/404 as non-fatal. Extend alembic revision repair so local dev DBs stamped with the removed 0020_chapters_book_id migration can roll back and upgrade to 0019.

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Kevin <kevin@brighteng.org>
Co-authored-by: Cursor <cursoragent@cursor.com>

api/app/features/memoir/story_pipeline_sync.py

@@ -27,6 +27,7 @@ from app.agents.memoir.story_route_agent import (
     StoryRouteAgent,
     default_append_target_story_id,
 )
+from app.core.business_telemetry import business_span
 from app.agents.stage_constants import (
     CATEGORY_TO_CHAT_STAGE,
     CHAPTER_CATEGORIES,
@@ -996,6 +997,46 @@ def run_story_pipeline_for_category_batch(
 
     返回 :class:`StoryPipelineResult`。低置信路由会被延迟而不创建 Story/Chapter。
     """
+    with business_span(
+        "memoir.story_pipeline.batch",
+        chapter_category=chapter_category,
+        segment_count=len(category_segments),
+    ):
+        return _run_story_pipeline_batch_inner(
+            session,
+            user_id=user_id,
+            chapter_category=chapter_category,
+            category_segments=category_segments,
+            state=state,
+            user_profile=user_profile,
+            user_birth_year=user_birth_year,
+            llm=llm,
+            background_voice=background_voice,
+            occupation=occupation,
+            memoir_correlation_id=memoir_correlation_id,
+            llm_fast=llm_fast,
+            memory_evidence=memory_evidence,
+            language=language,
+        )
+
+
+def _run_story_pipeline_batch_inner(
+    session: Session,
+    *,
+    user_id: str,
+    chapter_category: str,
+    category_segments: list,
+    state: MemoirStateSchema,
+    user_profile: str,
+    user_birth_year: int | None,
+    llm: Any,
+    background_voice: str = "default",
+    occupation: str = "",
+    memoir_correlation_id: str | None = None,
+    llm_fast: Any | None = None,
+    memory_evidence: dict | None = None,
+    language: str = "zh",
+) -> StoryPipelineResult:
     pipeline_phase_timings: dict[str, float] = {}
     narrative_agent = NarrativeAgent()
     route_agent = StoryRouteAgent()
@@ -1013,9 +1054,10 @@ def run_story_pipeline_for_category_batch(
         top_k = int(settings.evidence_top_k_large_batch)
 
     def _oral_job() -> tuple[str, float]:
-        t_oral = time.perf_counter()
-        out = normalize_oral_for_memoir(combined_text, llm=llm)
-        return out, time.perf_counter() - t_oral
+        with business_span("memoir.story_pipeline.oral_normalize"):
+            t_oral = time.perf_counter()
+            out = normalize_oral_for_memoir(combined_text, llm=llm)
+            return out, time.perf_counter() - t_oral
 
     _t_parallel = time.perf_counter()
     with ThreadPoolExecutor(max_workers=1) as pool:
@@ -1045,7 +1087,8 @@ def run_story_pipeline_for_category_batch(
         top_k,
     )
 
-    evidence_text = format_evidence_chunks_for_prompt(evidence)
+    with business_span("memoir.story_pipeline.evidence_prep", chapter_category=chapter_category):
+        evidence_text = format_evidence_chunks_for_prompt(evidence)
     ct_raw = (combined_text or "").strip()
     om_norm = (oral_for_memoir or "").strip()
     if ct_raw != om_norm:
@@ -1099,35 +1142,36 @@ def run_story_pipeline_for_category_batch(
     calculated_order_index = STAGE_TO_ORDER.get(chapter_category, 999)
 
     _t0 = time.perf_counter()
-    use_batch_plan = (
-        llm_route
-        and len(category_segments) >= 2
-        and len(category_segments) <= PLAN_BATCH_MAX_SEGMENTS
-    )
-    plan: StoryBatchPlan | None = None
-    if use_batch_plan:
-        segs = _route_segment_texts(category_segments)
-        plan = route_agent.plan_batch(
-            chapter_category=chapter_category,
-            chapter_title=title,
-            segments=segs,
-            candidate_stories=candidates,
-            llm=llm_route,
-            valid_story_ids=valid_ids,
-            story_meta=story_meta,
+    with business_span("memoir.story_pipeline.route", chapter_category=chapter_category):
+        use_batch_plan = (
+            llm_route
+            and len(category_segments) >= 2
+            and len(category_segments) <= PLAN_BATCH_MAX_SEGMENTS
         )
+        plan: StoryBatchPlan | None = None
+        if use_batch_plan:
+            segs = _route_segment_texts(category_segments)
+            plan = route_agent.plan_batch(
+                chapter_category=chapter_category,
+                chapter_title=title,
+                segments=segs,
+                candidate_stories=candidates,
+                llm=llm_route,
+                valid_story_ids=valid_ids,
+                story_meta=story_meta,
+            )
 
-    single_route: Any = None
-    if plan is None:
-        single_route = route_agent.decide(
-            chapter_category=chapter_category,
-            chapter_title=title,
-            batch_transcript=route_transcript,
-            candidate_stories=candidates,
-            llm=llm_route,
-            valid_story_ids=valid_ids,
-            story_meta=story_meta,
-        )
+        single_route: Any = None
+        if plan is None:
+            single_route = route_agent.decide(
+                chapter_category=chapter_category,
+                chapter_title=title,
+                batch_transcript=route_transcript,
+                candidate_stories=candidates,
+                llm=llm_route,
+                valid_story_ids=valid_ids,
+                story_meta=story_meta,
+            )
     pipeline_phase_timings["route"] = time.perf_counter() - _t0
 
     if (
@@ -1166,89 +1210,91 @@ def run_story_pipeline_for_category_batch(
     )
 
     _t0 = time.perf_counter()
-    if plan is not None:
-        dispatch_ids = _run_batch_plan_writes(
-            session,
-            plan=plan,
-            category_segments=category_segments,
-            chapter=chapter,
-            chapter_category=chapter_category,
-            evidence_text=evidence_text,
-            evidence=evidence,
-            evidence_top_k=top_k,
-            slot_snippets=slot_snippets,
-            user_id=user_id,
-            user_profile=user_profile,
-            user_birth_year=user_birth_year,
-            llm=llm,
-            narrative_agent=narrative_agent,
-            candidate_stories=candidates,
-            story_meta=story_meta,
-            background_voice=background_voice,
-            occupation=occupation,
-            memoir_correlation_id=memoir_correlation_id,
-            fidelity_llm=llm_fidelity,
-            language=language,
-        )
-    else:
-        route = single_route
-        decision_source = (
-            route.reason
-            if route.reason in FALLBACK_NEW_STORY_REASONS
-            else ("fallback_no_llm" if not llm_route else "single_decide")
-        )
-        target_story_id, existing_for_narrative, decision_source = (
-            _resolve_append_target(
+    with business_span("memoir.story_pipeline.narrative_writes", chapter_category=chapter_category):
+        if plan is not None:
+            dispatch_ids = _run_batch_plan_writes(
                 session,
-                route_decision=route.decision,
-                route_target_story_id=route.target_story_id,
-                user_id=user_id,
+                plan=plan,
+                category_segments=category_segments,
+                chapter=chapter,
                 chapter_category=chapter_category,
-                oral_norm=om_norm,
+                evidence_text=evidence_text,
+                evidence=evidence,
+                evidence_top_k=top_k,
+                slot_snippets=slot_snippets,
+                user_id=user_id,
+                user_profile=user_profile,
+                user_birth_year=user_birth_year,
+                llm=llm,
+                narrative_agent=narrative_agent,
                 candidate_stories=candidates,
                 story_meta=story_meta,
-                decision_source=decision_source,
+                background_voice=background_voice,
+                occupation=occupation,
                 memoir_correlation_id=memoir_correlation_id,
+                fidelity_llm=llm_fidelity,
+                language=language,
+            )
+        else:
+            route = single_route
+            decision_source = (
+                route.reason
+                if route.reason in FALLBACK_NEW_STORY_REASONS
+                else ("fallback_no_llm" if not llm_route else "single_decide")
+            )
+            target_story_id, existing_for_narrative, decision_source = (
+                _resolve_append_target(
+                    session,
+                    route_decision=route.decision,
+                    route_target_story_id=route.target_story_id,
+                    user_id=user_id,
+                    chapter_category=chapter_category,
+                    oral_norm=om_norm,
+                    candidate_stories=candidates,
+                    story_meta=story_meta,
+                    decision_source=decision_source,
+                    memoir_correlation_id=memoir_correlation_id,
+                )
             )
-        )
 
-        sid, _ = _execute_narrative_unit(
-            session,
-            oral_text=oral_for_memoir,
-            evidence_text=evidence_text,
-            evidence=evidence,
-            evidence_top_k=top_k,
-            chapter=chapter,
-            chapter_category=chapter_category,
-            slot_snippets=slot_snippets,
-            user_id=user_id,
-            user_profile=user_profile,
-            user_birth_year=user_birth_year,
-            llm=llm,
-            narrative_agent=narrative_agent,
-            target_story_id=target_story_id,
-            existing_for_narrative=existing_for_narrative,
-            decision_source=decision_source,
-            route_decision=route.decision,
-            route_type="single",
-            segment_ids=[str(s.id) for s in category_segments],
-            category_segments=category_segments,
-            background_voice=background_voice,
-            occupation=occupation,
-            memoir_correlation_id=memoir_correlation_id,
-            fidelity_llm=llm_fidelity,
-            language=language,
-        )
-        if sid:
-            dispatch_ids.add(sid)
+            sid, _ = _execute_narrative_unit(
+                session,
+                oral_text=oral_for_memoir,
+                evidence_text=evidence_text,
+                evidence=evidence,
+                evidence_top_k=top_k,
+                chapter=chapter,
+                chapter_category=chapter_category,
+                slot_snippets=slot_snippets,
+                user_id=user_id,
+                user_profile=user_profile,
+                user_birth_year=user_birth_year,
+                llm=llm,
+                narrative_agent=narrative_agent,
+                target_story_id=target_story_id,
+                existing_for_narrative=existing_for_narrative,
+                decision_source=decision_source,
+                route_decision=route.decision,
+                route_type="single",
+                segment_ids=[str(s.id) for s in category_segments],
+                category_segments=category_segments,
+                background_voice=background_voice,
+                occupation=occupation,
+                memoir_correlation_id=memoir_correlation_id,
+                fidelity_llm=llm_fidelity,
+                language=language,
+            )
+            if sid:
+                dispatch_ids.add(sid)
 
     pipeline_phase_timings["narrative_writes"] = time.perf_counter() - _t0
 
     _t0 = time.perf_counter()
-    reorder_chapter_story_links_by_life_order_sync(session, str(chapter.id))
-    mark_chapter_dirty_sync(session, str(chapter.id))
-    session.flush()
-    refresh_chapter_evidence_snapshot_with_retry_sync(session, str(chapter.id))
+    with business_span("memoir.story_pipeline.finalize", chapter_category=chapter_category):
+        reorder_chapter_story_links_by_life_order_sync(session, str(chapter.id))
+        mark_chapter_dirty_sync(session, str(chapter.id))
+        session.flush()
+        refresh_chapter_evidence_snapshot_with_retry_sync(session, str(chapter.id))
     pipeline_phase_timings["finalize"] = time.perf_counter() - _t0
 
     image_settings = MemoirImageSettings.from_env()