Analysis templates: dynamic top-down codebook

backend/api/analysis_routes.py

@@ -148,6 +148,9 @@ async def _analyze_from_text(
     store = get_persona_store()
     effective_analysis_attributes = await store.get_setting("analysis_attributes")
     effective_analysis_system_prompt = await store.get_setting("analysis_system_prompt")
+    template_id = await store.get_setting("top_down_codebook_template_id")
+    template_id_str = template_id.strip() if isinstance(template_id, str) else ""
+    template_record = await store.get_analysis_template(template_id_str, include_deleted=False) if template_id_str else None
     resources = await run_resource_agent_analysis(
         transcript=transcript,
         llm_backend=settings.llm.backend,
@@ -156,6 +159,9 @@ async def _analyze_from_text(
         settings=settings,
         analysis_attributes=effective_analysis_attributes,
         analysis_system_prompt=effective_analysis_system_prompt if isinstance(effective_analysis_system_prompt, str) else None,
+        top_down_template_id=template_record.template_id if template_record else template_id_str,
+        top_down_template_version_id=template_record.current_version_id if template_record else "",
+        top_down_template_categories=template_record.categories if template_record else [],
     )
 
     persisted = False
@@ -178,6 +184,9 @@ async def _analyze_from_text(
             "analysis": {
                 "analysis_system_prompt": effective_analysis_system_prompt if isinstance(effective_analysis_system_prompt, str) else None,
                 "analysis_attributes": effective_analysis_attributes,
+                "top_down_codebook_template_id": template_record.template_id if template_record else template_id_str,
+                "top_down_codebook_template_version_id": template_record.current_version_id if template_record else "",
+                "top_down_codebook_template_snapshot": template_record.categories if template_record else [],
             },
         }
         record = RunRecord(

backend/api/analysis_template_routes.py

@@ -0,0 +1,178 @@
+"""Top-down codebook analysis templates (CRUD)."""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, List, Optional
+from uuid import uuid4
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field
+
+from .storage_service import get_persona_store
+
+router = APIRouter(prefix="", tags=["analysis-templates"])
+
+
+def _slugify(value: str) -> str:
+    normalized = re.sub(r"[^a-zA-Z0-9]+", "_", (value or "").strip().lower()).strip("_")
+    normalized = re.sub(r"_+", "_", normalized)
+    return normalized
+
+
+def _normalize_categories(payload: Any) -> List[Dict[str, str]]:
+    if not isinstance(payload, list):
+        return []
+    out: List[Dict[str, str]] = []
+    used: set = set()
+    for item in payload:
+        if not isinstance(item, dict):
+            continue
+        label = item.get("label")
+        if not isinstance(label, str) or not label.strip():
+            continue
+        cid = item.get("category_id")
+        cid_str = cid.strip() if isinstance(cid, str) else ""
+        if not cid_str:
+            cid_str = _slugify(label)
+        if not cid_str:
+            cid_str = f"cat_{uuid4().hex[:8]}"
+        # Ensure unique within this template version.
+        base = cid_str
+        n = 2
+        while cid_str in used:
+            cid_str = f"{base}_{n}"
+            n += 1
+        used.add(cid_str)
+        out.append({"category_id": cid_str, "label": label.strip()})
+    return out
+
+
+class AnalysisTemplateSummaryResponse(BaseModel):
+    template_id: str
+    name: str
+    is_default: bool = False
+
+
+class AnalysisTemplateDetailResponse(BaseModel):
+    template_id: str
+    name: str
+    is_default: bool = False
+    version_id: str
+    categories: List[Dict[str, str]] = Field(default_factory=list)
+
+
+class CreateAnalysisTemplateRequest(BaseModel):
+    name: str = Field(..., description="Display name (set on create; not editable)")
+    clone_from_template_id: Optional[str] = Field(default=None)
+
+
+class UpdateAnalysisTemplateRequest(BaseModel):
+    categories: List[Dict[str, str]] = Field(default_factory=list)
+
+
+@router.get("/analysis-templates", response_model=List[AnalysisTemplateSummaryResponse])
+async def list_templates() -> List[AnalysisTemplateSummaryResponse]:
+    store = get_persona_store()
+    rows = await store.list_analysis_template_summaries(include_deleted=False)
+    return [
+        AnalysisTemplateSummaryResponse(
+            template_id=row.template_id,
+            name=row.name,
+            is_default=row.is_default,
+        )
+        for row in rows
+    ]
+
+
+@router.get("/analysis-templates/{template_id}", response_model=AnalysisTemplateDetailResponse)
+async def get_template(template_id: str) -> AnalysisTemplateDetailResponse:
+    store = get_persona_store()
+    record = await store.get_analysis_template(template_id, include_deleted=False)
+    if not record:
+        raise HTTPException(status_code=404, detail="Template not found")
+    return AnalysisTemplateDetailResponse(
+        template_id=record.template_id,
+        name=record.name,
+        is_default=record.is_default,
+        version_id=record.current_version_id,
+        categories=record.categories,
+    )
+
+
+@router.post("/analysis-templates", response_model=AnalysisTemplateDetailResponse)
+async def create_template(payload: CreateAnalysisTemplateRequest) -> AnalysisTemplateDetailResponse:
+    name = (payload.name or "").strip()
+    if not name:
+        raise HTTPException(status_code=400, detail="name is required")
+
+    store = get_persona_store()
+    categories: List[Dict[str, str]] = []
+    if payload.clone_from_template_id:
+        src = await store.get_analysis_template(payload.clone_from_template_id, include_deleted=False)
+        if not src:
+            raise HTTPException(status_code=404, detail="clone_from_template_id not found")
+        categories = src.categories
+    if not categories:
+        categories = [{"category_id": "category_1", "label": "New category"}]
+
+    template_id, version_id = await store.create_analysis_template(
+        name=name,
+        categories=_normalize_categories(categories),
+        is_default=False,
+    )
+    record = await store.get_analysis_template(template_id, include_deleted=False)
+    if not record:
+        raise HTTPException(status_code=500, detail="Failed to create template")
+    return AnalysisTemplateDetailResponse(
+        template_id=record.template_id,
+        name=record.name,
+        is_default=record.is_default,
+        version_id=record.current_version_id,
+        categories=record.categories,
+    )
+
+
+@router.put("/analysis-templates/{template_id}", response_model=AnalysisTemplateDetailResponse)
+async def update_template(template_id: str, payload: UpdateAnalysisTemplateRequest) -> AnalysisTemplateDetailResponse:
+    store = get_persona_store()
+    record = await store.get_analysis_template(template_id, include_deleted=True)
+    if not record:
+        raise HTTPException(status_code=404, detail="Template not found")
+    if record.is_default:
+        raise HTTPException(status_code=403, detail="default template is immutable")
+
+    categories = _normalize_categories(payload.categories)
+    if not categories:
+        raise HTTPException(status_code=400, detail="categories are required")
+
+    try:
+        await store.update_analysis_template(template_id=template_id, categories=categories)
+    except PermissionError as e:
+        raise HTTPException(status_code=403, detail=str(e))
+    except ValueError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+
+    updated = await store.get_analysis_template(template_id, include_deleted=False)
+    if not updated:
+        raise HTTPException(status_code=404, detail="Template not found")
+    return AnalysisTemplateDetailResponse(
+        template_id=updated.template_id,
+        name=updated.name,
+        is_default=updated.is_default,
+        version_id=updated.current_version_id,
+        categories=updated.categories,
+    )
+
+
+@router.delete("/analysis-templates/{template_id}")
+async def delete_template(template_id: str) -> Dict[str, Any]:
+    store = get_persona_store()
+    try:
+        await store.soft_delete_analysis_template(template_id)
+    except PermissionError as e:
+        raise HTTPException(status_code=403, detail=str(e))
+    except ValueError:
+        raise HTTPException(status_code=404, detail="Template not found")
+    return {"ok": True}
+

backend/api/conversation_service.py

@@ -97,6 +97,9 @@ async def run_resource_agent_analysis(
     settings: AppSettings,
     analysis_attributes: Optional[List[str]] = None,
     analysis_system_prompt: Optional[str] = None,
+    top_down_template_id: Optional[str] = None,
+    top_down_template_version_id: Optional[str] = None,
+    top_down_template_categories: Optional[List[Dict[str, str]]] = None,
 ) -> Dict[str, Any]:
     """Run the resource agent analysis on an in-memory transcript and return parsed JSON.
 
@@ -121,8 +124,8 @@ async def run_resource_agent_analysis(
         **llm_params,
     )
 
-    schema_version = "7"
-    analysis_prompt_version = "v2"
+    schema_version = "8"
+    analysis_prompt_version = "v3"
 
     evidence_catalog: Dict[str, Dict[str, Any]] = {}
     for message in transcript:
@@ -147,6 +150,17 @@ async def run_resource_agent_analysis(
         )
     system_prompt = (base + "\n\n" + compile_analysis_rules_block(analysis_attributes)).strip()
 
+    template_categories = top_down_template_categories or []
+    template_categories = [
+        {"category_id": str(c.get("category_id") or "").strip(), "label": str(c.get("label") or "").strip()}
+        for c in template_categories
+        if isinstance(c, dict)
+        and isinstance(c.get("category_id"), str)
+        and str(c.get("category_id") or "").strip()
+        and isinstance(c.get("label"), str)
+        and str(c.get("label") or "").strip()
+    ]
+
     evidence_catalog_json = json.dumps(evidence_catalog, ensure_ascii=False)
     user_prompt = (
         "Evidence catalog (JSON object mapping evidence_id -> sentence):\n"
@@ -189,15 +203,37 @@ async def run_resource_agent_analysis(
         "      \"confidence\": number  // 0..1\n"
         "    }\n"
         "  }\n"
-        "  \"top_down_codes\": {\n"
-        "    \"symptoms_concerns\": [ {\"code\": string, \"summary\": string, \"evidence\": [ {\"evidence_id\": string} ], \"confidence\": number  // 0..1 } ],\n"
-        "    \"daily_management\": [ {\"code\": string, \"summary\": string, \"evidence\": [ {\"evidence_id\": string} ], \"confidence\": number  // 0..1 } ],\n"
-        "    \"barriers_constraints\": [ {\"code\": string, \"summary\": string, \"evidence\": [ {\"evidence_id\": string} ], \"confidence\": number  // 0..1 } ],\n"
-        "    \"support_resources\": [ {\"code\": string, \"summary\": string, \"evidence\": [ {\"evidence_id\": string} ], \"confidence\": number  // 0..1 } ]\n"
+        "  \"top_down_codebook\": {\n"
+        "    \"template_id\": string,\n"
+        "    \"template_version_id\": string,\n"
+        "    \"categories\": [\n"
+        "      {\n"
+        "        \"category_id\": string,\n"
+        "        \"label\": string,\n"
+        "        \"items\": [ {\"code\": string, \"summary\": string, \"evidence\": [ {\"evidence_id\": string} ], \"confidence\": number  // 0..1 } ]\n"
+        "      }\n"
+        "    ]\n"
         "  }\n"
         "}\n"
     )
 
+    if template_categories:
+        template_json = json.dumps(
+            {
+                "template_id": top_down_template_id or "",
+                "template_version_id": top_down_template_version_id or "",
+                "categories": template_categories,
+            },
+            ensure_ascii=False,
+        )
+        user_prompt = (
+            user_prompt
+            + "\n\nTop-down codebook template (JSON):\n"
+            + template_json
+            + "\n\nFor top-down coding, you MUST populate top_down_codebook.categories in the same order as the template. "
+            "Use the exact category_id and label from the template. If no evidence supports a category, return an empty items array.\n"
+        )
+
     try:
         raw = await client.generate(prompt=user_prompt, system_prompt=system_prompt, temperature=0.2)
         parsed = json.loads(raw)
@@ -217,17 +253,49 @@ async def run_resource_agent_analysis(
                 if normalized is not None:
                     box["confidence"] = normalized
 
-        top_down_codes = parsed.get("top_down_codes") or {}
-        for key in ("symptoms_concerns", "daily_management", "barriers_constraints", "support_resources"):
-            items = top_down_codes.get(key) or []
-            if not isinstance(items, list):
-                continue
-            for item in items:
-                if not isinstance(item, dict):
-                    continue
-                normalized = _normalize_confidence(item.get("confidence"))
-                if normalized is not None:
-                    item["confidence"] = normalized
+        td_book = parsed.get("top_down_codebook")
+        if not isinstance(td_book, dict):
+            td_book = None
+
+        # Compatibility shim: if the model returns the legacy dict-shaped top_down_codes,
+        # map it into the new array-based top_down_codebook using the template order when available.
+        if td_book is None:
+            legacy = parsed.get("top_down_codes")
+            if isinstance(legacy, dict):
+                cats: List[Dict[str, Any]] = []
+                if template_categories:
+                    for cat in template_categories:
+                        cid = cat.get("category_id")
+                        label = cat.get("label")
+                        arr = legacy.get(cid) or []
+                        cats.append({"category_id": cid, "label": label, "items": arr if isinstance(arr, list) else []})
+                else:
+                    for key, arr in legacy.items():
+                        if not isinstance(key, str):
+                            continue
+                        cats.append({"category_id": key, "label": key, "items": arr if isinstance(arr, list) else []})
+                td_book = {
+                    "template_id": top_down_template_id or "",
+                    "template_version_id": top_down_template_version_id or "",
+                    "categories": cats,
+                }
+                parsed["top_down_codebook"] = td_book
+
+        if isinstance(td_book, dict):
+            categories = td_book.get("categories") or []
+            if isinstance(categories, list):
+                for cat in categories:
+                    if not isinstance(cat, dict):
+                        continue
+                    items = cat.get("items") or []
+                    if not isinstance(items, list):
+                        continue
+                    for item in items:
+                        if not isinstance(item, dict):
+                            continue
+                        normalized = _normalize_confidence(item.get("confidence"))
+                        if normalized is not None:
+                            item["confidence"] = normalized
 
         return parsed
     finally:
@@ -265,6 +333,9 @@ class ConversationInfo:
     patient_system_prompt: str = ""
     analysis_system_prompt: str = ""
     analysis_attributes: List[str] = field(default_factory=list)
+    top_down_template_id: str = ""
+    top_down_template_version_id: str = ""
+    top_down_template_categories: List[Dict[str, str]] = field(default_factory=list)
     patient_attributes: List[str] = field(default_factory=list)
     surveyor_attributes: List[str] = field(default_factory=list)
     surveyor_question_bank: Optional[str] = None
@@ -287,6 +358,9 @@ class HumanChatInfo:
     patient_system_prompt: str = ""
     analysis_system_prompt: str = ""
     analysis_attributes: List[str] = field(default_factory=list)
+    top_down_template_id: str = ""
+    top_down_template_version_id: str = ""
+    top_down_template_categories: List[Dict[str, str]] = field(default_factory=list)
     patient_attributes: List[str] = field(default_factory=list)
     surveyor_attributes: List[str] = field(default_factory=list)
     surveyor_question_bank: Optional[str] = None
@@ -343,6 +417,19 @@ class ConversationService:
             return []
         return [s.strip() for s in attrs if isinstance(s, str) and s.strip()]
 
+    async def _resolve_top_down_template(self) -> Dict[str, Any]:
+        store = get_persona_store()
+        template_id = await store.get_setting("top_down_codebook_template_id")
+        template_id_str = template_id.strip() if isinstance(template_id, str) else ""
+        record = await store.get_analysis_template(template_id_str, include_deleted=False) if template_id_str else None
+        if record:
+            return {
+                "template_id": record.template_id,
+                "template_version_id": record.current_version_id,
+                "categories": record.categories,
+            }
+        return {"template_id": template_id_str, "template_version_id": "", "categories": []}
+
     async def start_human_chat(
         self,
         conversation_id: str,
@@ -385,6 +472,7 @@ class ConversationService:
         resolved_patient_prompt = pp if isinstance(pp, str) and pp.strip() else DEFAULT_PATIENT_SYSTEM_PROMPT
         resolved_analysis_prompt = asp if isinstance(asp, str) and asp.strip() else ""
         resolved_analysis_attrs = [s.strip() for s in ap if isinstance(ap, str) and s.strip()] if isinstance(ap, list) else []
+        template = await self._resolve_top_down_template()
 
         chat_info = HumanChatInfo(
             conversation_id=conversation_id,
@@ -397,6 +485,9 @@ class ConversationService:
             patient_system_prompt=resolved_patient_prompt,
             analysis_system_prompt=resolved_analysis_prompt,
             analysis_attributes=resolved_analysis_attrs,
+            top_down_template_id=str(template.get("template_id") or ""),
+            top_down_template_version_id=str(template.get("template_version_id") or ""),
+            top_down_template_categories=list(template.get("categories") or []),
             patient_attributes=self._persona_attributes(patient_persona),
             surveyor_attributes=self._persona_attributes(surveyor_persona),
             surveyor_question_bank=self._persona_question_bank(surveyor_persona),
@@ -747,6 +838,7 @@ class ConversationService:
             resolved_patient_prompt = pp if isinstance(pp, str) and pp.strip() else DEFAULT_PATIENT_SYSTEM_PROMPT
             resolved_analysis_prompt = asp if isinstance(asp, str) and asp.strip() else ""
             resolved_analysis_attrs = [s.strip() for s in ap if isinstance(ap, str) and s.strip()] if isinstance(ap, list) else []
+            template = await self._resolve_top_down_template()
 
             # Create conversation info
             conv_info = ConversationInfo(
@@ -760,6 +852,9 @@ class ConversationService:
                 patient_system_prompt=resolved_patient_prompt,
                 analysis_system_prompt=resolved_analysis_prompt,
                 analysis_attributes=resolved_analysis_attrs,
+                top_down_template_id=str(template.get("template_id") or ""),
+                top_down_template_version_id=str(template.get("template_version_id") or ""),
+                top_down_template_categories=list(template.get("categories") or []),
                 patient_attributes=self._persona_attributes(patient_persona),
                 surveyor_attributes=self._persona_attributes(surveyor_persona),
                 surveyor_question_bank=self._persona_question_bank(surveyor_persona),
@@ -1027,6 +1122,9 @@ class ConversationService:
                 settings=self.settings,
                 analysis_attributes=getattr(conv_info, "analysis_attributes", None),
                 analysis_system_prompt=getattr(conv_info, "analysis_system_prompt", None),
+                top_down_template_id=getattr(conv_info, "top_down_template_id", None),
+                top_down_template_version_id=getattr(conv_info, "top_down_template_version_id", None),
+                top_down_template_categories=getattr(conv_info, "top_down_template_categories", None),
             )
 
             persisted = False
@@ -1076,6 +1174,9 @@ class ConversationService:
                     "analysis": {
                         "analysis_system_prompt": getattr(conv_info, "analysis_system_prompt", None),
                         "analysis_attributes": getattr(conv_info, "analysis_attributes", None),
+                        "top_down_codebook_template_id": getattr(conv_info, "top_down_template_id", None),
+                        "top_down_codebook_template_version_id": getattr(conv_info, "top_down_template_version_id", None),
+                        "top_down_codebook_template_snapshot": getattr(conv_info, "top_down_template_categories", None),
                     },
                 }
 

backend/api/export_routes.py

@@ -162,9 +162,13 @@ def _export_xlsx_bytes(payload: ExportRequest) -> bytes:
             )
 
     ws_td = add_sheet("TopDownCodes", ["category", "index", "code", "summary", "confidence", "evidence_ids"])
-    top_down = payload.resources.get("top_down_codes") or {}
-    if isinstance(top_down, dict):
-        for category, arr in top_down.items():
+    td_book = payload.resources.get("top_down_codebook")
+    if isinstance(td_book, dict) and isinstance(td_book.get("categories"), list):
+        for cat in td_book.get("categories") or []:
+            if not isinstance(cat, dict):
+                continue
+            label = cat.get("label") or cat.get("category_id") or "Category"
+            arr = cat.get("items") or []
             if not isinstance(arr, list):
                 continue
             for idx, item in enumerate(arr):
@@ -173,7 +177,7 @@ def _export_xlsx_bytes(payload: ExportRequest) -> bytes:
                 evidence_ids = _extract_evidence_ids(item.get("evidence"))
                 ws_td.append(
                     [
-                        str(category),
+                        str(label),
                         idx,
                         item.get("code", "") or "",
                         item.get("summary", "") or "",
@@ -181,6 +185,26 @@ def _export_xlsx_bytes(payload: ExportRequest) -> bytes:
                         _safe_join(evidence_ids),
                     ]
                 )
+    else:
+        top_down = payload.resources.get("top_down_codes") or {}
+        if isinstance(top_down, dict):
+            for category, arr in top_down.items():
+                if not isinstance(arr, list):
+                    continue
+                for idx, item in enumerate(arr):
+                    if not isinstance(item, dict):
+                        continue
+                    evidence_ids = _extract_evidence_ids(item.get("evidence"))
+                    ws_td.append(
+                        [
+                            str(category),
+                            idx,
+                            item.get("code", "") or "",
+                            item.get("summary", "") or "",
+                            item.get("confidence", ""),
+                            _safe_join(evidence_ids),
+                        ]
+                    )
 
     for ws in wb.worksheets:
         for row in ws.iter_rows(min_row=2):

backend/api/main.py

@@ -32,6 +32,7 @@ from .conversation_routes import router as conversation_router  # noqa: E402
 from .persona_routes import router as persona_router  # noqa: E402
 from .export_routes import router as export_router  # noqa: E402
 from .analysis_routes import router as analysis_router  # noqa: E402
+from .analysis_template_routes import router as analysis_template_router  # noqa: E402
 from .run_routes import router as run_router  # noqa: E402
 from .run_export_routes import router as run_export_router  # noqa: E402
 from .conversation_service import initialize_conversation_service  # noqa: E402
@@ -70,6 +71,7 @@ app.include_router(conversation_router)
 app.include_router(persona_router)
 app.include_router(export_router)
 app.include_router(analysis_router)
+app.include_router(analysis_template_router)
 app.include_router(run_router)
 app.include_router(run_export_router)
 

backend/api/persona_routes.py

@@ -52,6 +52,7 @@ class SettingsResponse(BaseModel):
     patient_system_prompt: str
     analysis_system_prompt: str
     analysis_attributes: List[str]
+    top_down_codebook_template_id: str
 
 
 class UpdateSettingsRequest(BaseModel):
@@ -59,6 +60,7 @@ class UpdateSettingsRequest(BaseModel):
     patient_system_prompt: Optional[str] = None
     analysis_system_prompt: Optional[str] = None
     analysis_attributes: Optional[List[str]] = None
+    top_down_codebook_template_id: Optional[str] = None
 
 
 @router.get("/settings/defaults")
@@ -68,6 +70,7 @@ async def get_settings_defaults() -> SettingsResponse:
         patient_system_prompt=DEFAULT_PATIENT_SYSTEM_PROMPT,
         analysis_system_prompt=DEFAULT_ANALYSIS_SYSTEM_PROMPT,
         analysis_attributes=list(DEFAULT_ANALYSIS_ATTRIBUTES),
+        top_down_codebook_template_id="top_down_v1",
     )
 
 
@@ -244,11 +247,13 @@ async def get_settings() -> SettingsResponse:
     pp = await store.get_setting("patient_system_prompt")
     asp = await store.get_setting("analysis_system_prompt")
     ap = await store.get_setting("analysis_attributes")
+    td = await store.get_setting("top_down_codebook_template_id")
     return SettingsResponse(
         surveyor_system_prompt=sp if isinstance(sp, str) else "",
         patient_system_prompt=pp if isinstance(pp, str) else "",
         analysis_system_prompt=asp if isinstance(asp, str) else "",
         analysis_attributes=[s for s in ap if isinstance(ap, str)] if isinstance(ap, list) else [],
+        top_down_codebook_template_id=td if isinstance(td, str) else "",
     )
 
 
@@ -266,4 +271,6 @@ async def update_settings(payload: UpdateSettingsRequest) -> SettingsResponse:
             "analysis_attributes",
             [s.strip() for s in (payload.analysis_attributes or []) if isinstance(s, str) and s.strip()],
         )
+    if payload.top_down_codebook_template_id is not None:
+        await store.upsert_setting("top_down_codebook_template_id", str(payload.top_down_codebook_template_id))
     return await get_settings()

backend/core/analysis_knobs.py

@@ -11,7 +11,7 @@ DEFAULT_ANALYSIS_ATTRIBUTES: List[str] = [
     "For care experience: do not duplicate the same evidence_id across positive/negative/mixed/neutral. If a sentence supports both positive and negative interpretations, put it in care_experience.mixed.",
     "confidence must be a number between 0 and 1.",
     "For health_situations: include a short code label (1-3 words) in addition to the longer summary.",
-    "For top_down_codes categories: include a short code label (1-3 words) and cite evidence.",
+    "For top_down_codebook categories: include a short code label (1-3 words) and cite evidence.",
     "Prefer fewer, higher-confidence items.",
 ]
 

backend/core/default_analysis_templates.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from typing import Dict, List
+
+
+DEFAULT_TOP_DOWN_CODEBOOK_TEMPLATE: Dict[str, object] = {
+    "template_id": "top_down_v1",
+    "name": "Default top-down codebook (v1)",
+    "categories": [
+        {"category_id": "symptoms_concerns", "label": "Symptoms/concerns"},
+        {"category_id": "daily_management", "label": "Daily management"},
+        {"category_id": "barriers_constraints", "label": "Barriers/constraints"},
+        {"category_id": "support_resources", "label": "Support/resources"},
+    ],
+}
+
+
+def default_top_down_categories() -> List[Dict[str, str]]:
+    cats = DEFAULT_TOP_DOWN_CODEBOOK_TEMPLATE.get("categories")  # type: ignore[assignment]
+    if isinstance(cats, list):
+        return [c for c in cats if isinstance(c, dict)]  # type: ignore[return-value]
+    return []
+

backend/core/persona_seed.py

@@ -5,6 +5,7 @@ from typing import Any, Dict, List
 from backend.core.default_personas import DEFAULT_PATIENT_PERSONAS, DEFAULT_SURVEYOR_PERSONAS
 from backend.core.universal_prompts import DEFAULT_PATIENT_SYSTEM_PROMPT, DEFAULT_SURVEYOR_SYSTEM_PROMPT, DEFAULT_ANALYSIS_SYSTEM_PROMPT
 from backend.core.analysis_knobs import DEFAULT_ANALYSIS_ATTRIBUTES
+from backend.core.default_analysis_templates import DEFAULT_TOP_DOWN_CODEBOOK_TEMPLATE, default_top_down_categories
 from backend.storage.sqlite_persona_store import SQLitePersonaStore
 
 
@@ -26,6 +27,23 @@ async def seed_defaults_overwrite(*, store: SQLitePersonaStore) -> None:
     if not (isinstance(existing_analysis_prompt, str) and existing_analysis_prompt.strip()):
         await store.upsert_setting("analysis_system_prompt", DEFAULT_ANALYSIS_SYSTEM_PROMPT)
 
+    # Top-down codebook template: seed a default and set the active template if missing.
+    template_id = str(DEFAULT_TOP_DOWN_CODEBOOK_TEMPLATE.get("template_id") or "top_down_v1")
+    template_name = str(DEFAULT_TOP_DOWN_CODEBOOK_TEMPLATE.get("name") or "Default top-down codebook (v1)")
+    try:
+        await store.upsert_default_analysis_template(
+            template_id=template_id,
+            name=template_name,
+            categories=default_top_down_categories(),
+        )
+    except Exception:
+        # Best-effort seeding; do not block startup.
+        pass
+
+    active_template = await store.get_setting("top_down_codebook_template_id")
+    if not (isinstance(active_template, str) and active_template.strip()):
+        await store.upsert_setting("top_down_codebook_template_id", template_id)
+
     # Personas (overwrite by writing a new version each startup)
     for p in (DEFAULT_SURVEYOR_PERSONAS + DEFAULT_PATIENT_PERSONAS):
         await store.upsert_default_persona(

backend/storage/__init__.py

@@ -1,4 +1,11 @@
-from .models import RunRecord, RunSummary, PersonaRecord, PersonaSummary
+from .models import (
+    RunRecord,
+    RunSummary,
+    PersonaRecord,
+    PersonaSummary,
+    AnalysisTemplateRecord,
+    AnalysisTemplateSummary,
+)
 from .sqlite_persona_store import SQLitePersonaStore
 from .sqlite_run_store import SQLiteRunStore
 
@@ -7,6 +14,8 @@ __all__ = [
     "RunSummary",
     "PersonaRecord",
     "PersonaSummary",
+    "AnalysisTemplateRecord",
+    "AnalysisTemplateSummary",
     "SQLiteRunStore",
     "SQLitePersonaStore",
 ]

backend/storage/models.py

@@ -52,3 +52,23 @@ class PersonaRecord:
     updated_at: str
     attributes: List[str]
     question_bank_items: List[str]
+
+
+@dataclass(frozen=True)
+class AnalysisTemplateSummary:
+    template_id: str
+    name: str
+    is_default: bool = False
+    is_deleted: bool = False
+
+
+@dataclass(frozen=True)
+class AnalysisTemplateRecord:
+    template_id: str
+    name: str
+    is_default: bool
+    is_deleted: bool
+    current_version_id: str
+    created_at: str
+    updated_at: str
+    categories: List[Dict[str, str]]

backend/storage/sqlite_persona_store.py

@@ -9,7 +9,7 @@ from uuid import uuid4
 
 import aiosqlite
 
-from .models import PersonaRecord, PersonaSummary
+from .models import PersonaRecord, PersonaSummary, AnalysisTemplateRecord, AnalysisTemplateSummary
 
 
 def _now_iso() -> str:
@@ -26,6 +26,23 @@ def _clean_str_list(value: Any) -> List[str]:
     return out
 
 
+def _clean_category_list(value: Any) -> List[Dict[str, str]]:
+    if not isinstance(value, list):
+        return []
+    out: List[Dict[str, str]] = []
+    for item in value:
+        if not isinstance(item, dict):
+            continue
+        cid = item.get("category_id")
+        label = item.get("label")
+        if not (isinstance(cid, str) and cid.strip()):
+            continue
+        if not (isinstance(label, str) and label.strip()):
+            continue
+        out.append({"category_id": cid.strip(), "label": label.strip()})
+    return out
+
+
 class SQLitePersonaStore:
     def __init__(self, db_path: str):
         self.db_path = str(db_path)
@@ -76,6 +93,323 @@ class SQLitePersonaStore:
                 );
                 """
             )
+
+            await db.execute(
+                """
+                CREATE TABLE IF NOT EXISTS analysis_templates (
+                    template_id TEXT PRIMARY KEY,
+                    name TEXT NOT NULL,
+                    is_default INTEGER NOT NULL DEFAULT 0,
+                    is_deleted INTEGER NOT NULL DEFAULT 0,
+                    current_version_id TEXT NOT NULL,
+                    created_at TEXT NOT NULL,
+                    updated_at TEXT NOT NULL
+                );
+                """
+            )
+            await db.execute("CREATE INDEX IF NOT EXISTS analysis_templates_is_default ON analysis_templates(is_default);")
+            await db.execute(
+                """
+                CREATE TABLE IF NOT EXISTS analysis_template_versions (
+                    template_id TEXT NOT NULL,
+                    version_id TEXT NOT NULL,
+                    created_at TEXT NOT NULL,
+                    content_json TEXT NOT NULL,
+                    PRIMARY KEY (template_id, version_id),
+                    FOREIGN KEY (template_id) REFERENCES analysis_templates(template_id) ON DELETE CASCADE
+                );
+                """
+            )
+            await db.commit()
+
+    async def list_analysis_template_summaries(
+        self,
+        *,
+        include_deleted: bool = False,
+    ) -> List[AnalysisTemplateSummary]:
+        async with aiosqlite.connect(self.db_path) as db:
+            await db.execute("PRAGMA foreign_keys=ON;")
+            where: List[str] = []
+            args: List[Any] = []
+            if not include_deleted:
+                where.append("is_deleted = 0")
+            clause = ("WHERE " + " AND ".join(where)) if where else ""
+            cur = await db.execute(
+                f"""
+                SELECT template_id, name, is_default, is_deleted
+                FROM analysis_templates
+                {clause}
+                ORDER BY is_default DESC, name ASC;
+                """,
+                tuple(args),
+            )
+            rows = await cur.fetchall()
+        return [
+            AnalysisTemplateSummary(
+                template_id=row[0],
+                name=row[1],
+                is_default=bool(row[2]),
+                is_deleted=bool(row[3]),
+            )
+            for row in rows
+        ]
+
+    async def list_analysis_template_records(
+        self,
+        *,
+        include_deleted: bool = False,
+    ) -> List[AnalysisTemplateRecord]:
+        async with aiosqlite.connect(self.db_path) as db:
+            await db.execute("PRAGMA foreign_keys=ON;")
+            where: List[str] = []
+            args: List[Any] = []
+            if not include_deleted:
+                where.append("t.is_deleted = 0")
+            clause = ("WHERE " + " AND ".join(where)) if where else ""
+            cur = await db.execute(
+                f"""
+                SELECT
+                    t.template_id, t.name, t.is_default, t.is_deleted,
+                    t.current_version_id, t.created_at, t.updated_at,
+                    v.content_json
+                FROM analysis_templates t
+                JOIN analysis_template_versions v
+                  ON v.template_id = t.template_id AND v.version_id = t.current_version_id
+                {clause}
+                ORDER BY t.is_default DESC, t.name ASC;
+                """,
+                tuple(args),
+            )
+            rows = await cur.fetchall()
+
+        out: List[AnalysisTemplateRecord] = []
+        for row in rows:
+            content: Dict[str, Any] = {}
+            if isinstance(row[7], str):
+                try:
+                    content = json.loads(row[7]) or {}
+                except Exception:
+                    content = {}
+            out.append(
+                AnalysisTemplateRecord(
+                    template_id=row[0],
+                    name=row[1],
+                    is_default=bool(row[2]),
+                    is_deleted=bool(row[3]),
+                    current_version_id=row[4],
+                    created_at=row[5],
+                    updated_at=row[6],
+                    categories=_clean_category_list(content.get("categories")),
+                )
+            )
+        return out
+
+    async def get_analysis_template(
+        self,
+        template_id: str,
+        *,
+        include_deleted: bool = False,
+    ) -> Optional[AnalysisTemplateRecord]:
+        if not isinstance(template_id, str) or not template_id.strip():
+            return None
+        async with aiosqlite.connect(self.db_path) as db:
+            await db.execute("PRAGMA foreign_keys=ON;")
+            cur = await db.execute(
+                """
+                SELECT template_id, name, is_default, is_deleted, current_version_id, created_at, updated_at
+                FROM analysis_templates
+                WHERE template_id = ?;
+                """,
+                (template_id,),
+            )
+            row = await cur.fetchone()
+            if not row:
+                return None
+            if bool(row[3]) and not include_deleted:
+                return None
+
+            cur2 = await db.execute(
+                """
+                SELECT content_json
+                FROM analysis_template_versions
+                WHERE template_id = ? AND version_id = ?;
+                """,
+                (row[0], row[4]),
+            )
+            vrow = await cur2.fetchone()
+            content: Dict[str, Any] = {}
+            if vrow and isinstance(vrow[0], str):
+                try:
+                    content = json.loads(vrow[0]) or {}
+                except Exception:
+                    content = {}
+
+        return AnalysisTemplateRecord(
+            template_id=row[0],
+            name=row[1],
+            is_default=bool(row[2]),
+            is_deleted=bool(row[3]),
+            current_version_id=row[4],
+            created_at=row[5],
+            updated_at=row[6],
+            categories=_clean_category_list(content.get("categories")),
+        )
+
+    async def upsert_default_analysis_template(
+        self,
+        *,
+        template_id: str,
+        name: str,
+        categories: List[Dict[str, str]],
+    ) -> Tuple[str, str]:
+        if not isinstance(template_id, str) or not template_id.strip():
+            raise ValueError("template_id is required")
+        if not isinstance(name, str) or not name.strip():
+            raise ValueError("name is required")
+        cleaned_categories = _clean_category_list(categories)
+        if not cleaned_categories:
+            raise ValueError("categories are required")
+
+        now = _now_iso()
+        version_id = str(uuid4())
+        content_json = json.dumps({"categories": cleaned_categories}, ensure_ascii=False)
+
+        async with aiosqlite.connect(self.db_path) as db:
+            await db.execute("PRAGMA foreign_keys=ON;")
+            cur = await db.execute(
+                "SELECT current_version_id FROM analysis_templates WHERE template_id = ?;",
+                (template_id,),
+            )
+            existing = await cur.fetchone()
+
+            if existing:
+                # Do not overwrite existing defaults; keep the DB canonical once created.
+                return template_id, str(existing[0])
+
+            await db.execute(
+                """
+                INSERT INTO analysis_template_versions (template_id, version_id, created_at, content_json)
+                VALUES (?, ?, ?, ?);
+                """,
+                (template_id, version_id, now, content_json),
+            )
+            await db.execute(
+                """
+                INSERT INTO analysis_templates (template_id, name, is_default, is_deleted, current_version_id, created_at, updated_at)
+                VALUES (?, ?, 1, 0, ?, ?, ?);
+                """,
+                (template_id, name.strip(), version_id, now, now),
+            )
+            await db.commit()
+        return template_id, version_id
+
+    async def create_analysis_template(
+        self,
+        *,
+        name: str,
+        categories: List[Dict[str, str]],
+        is_default: bool = False,
+    ) -> Tuple[str, str]:
+        if not isinstance(name, str) or not name.strip():
+            raise ValueError("name is required")
+        cleaned_categories = _clean_category_list(categories)
+        if not cleaned_categories:
+            raise ValueError("categories are required")
+
+        now = _now_iso()
+        template_id = str(uuid4())
+        version_id = str(uuid4())
+        content_json = json.dumps({"categories": cleaned_categories}, ensure_ascii=False)
+
+        async with aiosqlite.connect(self.db_path) as db:
+            await db.execute("PRAGMA foreign_keys=ON;")
+            await db.execute(
+                """
+                INSERT INTO analysis_template_versions (template_id, version_id, created_at, content_json)
+                VALUES (?, ?, ?, ?);
+                """,
+                (template_id, version_id, now, content_json),
+            )
+            await db.execute(
+                """
+                INSERT INTO analysis_templates (template_id, name, is_default, is_deleted, current_version_id, created_at, updated_at)
+                VALUES (?, ?, ?, 0, ?, ?, ?);
+                """,
+                (template_id, name.strip(), 1 if is_default else 0, version_id, now, now),
+            )
+            await db.commit()
+        return template_id, version_id
+
+    async def update_analysis_template(
+        self,
+        *,
+        template_id: str,
+        categories: List[Dict[str, str]],
+    ) -> str:
+        if not isinstance(template_id, str) or not template_id.strip():
+            raise ValueError("template_id is required")
+        cleaned_categories = _clean_category_list(categories)
+        if not cleaned_categories:
+            raise ValueError("categories are required")
+
+        now = _now_iso()
+        version_id = str(uuid4())
+        content_json = json.dumps({"categories": cleaned_categories}, ensure_ascii=False)
+
+        async with aiosqlite.connect(self.db_path) as db:
+            await db.execute("PRAGMA foreign_keys=ON;")
+            cur = await db.execute(
+                "SELECT is_default, is_deleted FROM analysis_templates WHERE template_id = ?;",
+                (template_id,),
+            )
+            row = await cur.fetchone()
+            if not row:
+                raise ValueError("template not found")
+            if bool(row[1]):
+                raise ValueError("template not found")
+            if bool(row[0]):
+                raise PermissionError("default template is immutable")
+
+            await db.execute(
+                """
+                INSERT INTO analysis_template_versions (template_id, version_id, created_at, content_json)
+                VALUES (?, ?, ?, ?);
+                """,
+                (template_id, version_id, now, content_json),
+            )
+            await db.execute(
+                """
+                UPDATE analysis_templates
+                SET current_version_id = ?, updated_at = ?
+                WHERE template_id = ?;
+                """,
+                (version_id, now, template_id),
+            )
+            await db.commit()
+        return version_id
+
+    async def soft_delete_analysis_template(self, template_id: str) -> None:
+        if not isinstance(template_id, str) or not template_id.strip():
+            raise ValueError("template_id is required")
+        now = _now_iso()
+        async with aiosqlite.connect(self.db_path) as db:
+            await db.execute("PRAGMA foreign_keys=ON;")
+            cur = await db.execute(
+                "SELECT is_default, is_deleted FROM analysis_templates WHERE template_id = ?;",
+                (template_id,),
+            )
+            row = await cur.fetchone()
+            if not row:
+                raise ValueError("template not found")
+            if bool(row[1]):
+                raise ValueError("template not found")
+            if bool(row[0]):
+                raise PermissionError("default template is immutable")
+
+            await db.execute(
+                "UPDATE analysis_templates SET is_deleted = 1, updated_at = ? WHERE template_id = ?;",
+                (now, template_id),
+            )
             await db.commit()
 
     async def upsert_setting(self, key: str, value: Any) -> None:

frontend/pages/config_view.py

@@ -15,7 +15,7 @@ def get_config_view_js() -> str:
 	                "For care experience: do not duplicate the same evidence_id across positive/negative/mixed/neutral. If a sentence supports both positive and negative interpretations, put it in care_experience.mixed.",
 	                "confidence must be a number between 0 and 1.",
 	                "For health_situations: include a short code label (1-3 words) in addition to the longer summary.",
-	                "For top_down_codes categories: include a short code label (1-3 words) and cite evidence.",
+	                "For top_down_codebook categories: include a short code label (1-3 words) and cite evidence.",
 	                "Prefer fewer, higher-confidence items.",
 	            ];
 
@@ -86,6 +86,10 @@ Requirements:
 		            const [analysisSystemPrompt, setAnalysisSystemPrompt] = React.useState(() => {
 		                return '';
 		            });
+		            const [analysisTemplates, setAnalysisTemplates] = React.useState([]);
+		            const [selectedTemplateId, setSelectedTemplateId] = React.useState('');
+		            const [selectedTemplateDetail, setSelectedTemplateDetail] = React.useState(null);
+		            const [selectedTemplateCategories, setSelectedTemplateCategories] = React.useState([]);
 		            const [savedAt, setSavedAt] = React.useState(existing?.saved_at || null);
 		            const [saveFlash, setSaveFlash] = React.useState(false);
 		            const applySurveyorDefaults = () => {
@@ -116,6 +120,61 @@ Requirements:
 		                    .catch(() => setAnalysisSystemPrompt(DEFAULT_ANALYSIS_SYSTEM_PROMPT));
 		            };
 
+		            const refreshAnalysisTemplates = () => {
+		                return authedFetch('/api/analysis-templates')
+		                    .then(r => r.json())
+		                    .then(rows => {
+		                        const list = Array.isArray(rows) ? rows : [];
+		                        setAnalysisTemplates(list);
+		                        return list;
+		                    })
+		                    .catch(() => null);
+		            };
+
+		            const addTemplateCategory = () => setSelectedTemplateCategories((prev) => ([...(prev || []), { category_id: '', label: '' }]));
+		            const updateTemplateCategoryLabel = (idx, label) => setSelectedTemplateCategories((prev) => (prev || []).map((c, i) => (i === idx ? Object.assign({}, c, { label }) : c)));
+		            const removeTemplateCategory = (idx) => setSelectedTemplateCategories((prev) => (prev || []).filter((_, i) => i !== idx));
+		            const moveTemplateCategory = (idx, dir) => {
+		                setSelectedTemplateCategories((prev) => {
+		                    const arr = [...(prev || [])];
+		                    const next = idx + dir;
+		                    if (idx < 0 || idx >= arr.length) return arr;
+		                    if (next < 0 || next >= arr.length) return arr;
+		                    const tmp = arr[idx];
+		                    arr[idx] = arr[next];
+		                    arr[next] = tmp;
+		                    return arr;
+		                });
+		            };
+
+		            const createAnalysisTemplate = async (cloneFromId) => {
+		                const suggested = cloneFromId ? 'Copy of codebook' : '';
+		                const name = window.prompt('New codebook template name', suggested) || '';
+		                if (!name.trim()) return null;
+		                const res = await authedFetch('/api/analysis-templates', {
+		                    method: 'POST',
+		                    headers: { 'Content-Type': 'application/json' },
+		                    body: JSON.stringify({
+		                        name: name.trim(),
+		                        clone_from_template_id: cloneFromId || undefined,
+		                    })
+		                });
+		                if (!res.ok) return null;
+		                const data = await res.json();
+		                await refreshAnalysisTemplates();
+		                return data?.template_id || null;
+		            };
+
+		            const deleteAnalysisTemplate = async (templateId) => {
+		                if (!templateId) return false;
+		                const ok = window.confirm('Delete this codebook template? This cannot be undone.');
+		                if (!ok) return false;
+		                const res = await authedFetch(`/api/analysis-templates/${templateId}`, { method: 'DELETE' });
+		                if (!res.ok) return false;
+		                await refreshAnalysisTemplates();
+		                return true;
+		            };
+
 	            React.useEffect(() => {
 	                if (activePane === 'surveyors') {
 	                    setSurveyorPromptUnlocked(false);
@@ -128,6 +187,10 @@ Requirements:
 	                }
 	            }, [activePane]);
 
+	            React.useEffect(() => {
+	                refreshAnalysisTemplates();
+	            }, []);
+
 		            const refreshPersonas = () => {
 		                return authedFetch('/api/personas')
 		                    .then(r => r.json())
@@ -201,12 +264,36 @@ Requirements:
 	                        if (typeof data?.surveyor_system_prompt === 'string') setSurveyorSystemPrompt(data.surveyor_system_prompt);
 	                        if (typeof data?.patient_system_prompt === 'string') setPatientSystemPrompt(data.patient_system_prompt);
 	                        if (typeof data?.analysis_system_prompt === 'string') setAnalysisSystemPrompt(data.analysis_system_prompt);
+	                        if (typeof data?.top_down_codebook_template_id === 'string') setSelectedTemplateId(data.top_down_codebook_template_id);
 	                        const attrs = Array.isArray(data?.analysis_attributes) ? data.analysis_attributes : [];
 	                        setAnalysisAttributeItems(attrs.map((x) => (typeof x === 'string' ? x.trim() : '')).filter((x) => x.length > 0));
 	                    })
 	                    .catch(() => {});
 	            }, []);
 
+	            React.useEffect(() => {
+	                const tid = (selectedTemplateId || '').trim();
+	                if (!tid) {
+	                    setSelectedTemplateDetail(null);
+	                    setSelectedTemplateCategories([]);
+	                    return;
+	                }
+	                authedFetch(`/api/analysis-templates/${tid}`)
+	                    .then(r => r.json())
+	                    .then(t => {
+	                        setSelectedTemplateDetail(t || null);
+	                        const cats = Array.isArray(t?.categories) ? t.categories : [];
+	                        setSelectedTemplateCategories(cats.map((c) => ({
+	                            category_id: (c && typeof c.category_id === 'string') ? c.category_id : '',
+	                            label: (c && typeof c.label === 'string') ? c.label : '',
+	                        })));
+	                    })
+	                    .catch(() => {
+	                        setSelectedTemplateDetail(null);
+	                        setSelectedTemplateCategories([]);
+	                    });
+	            }, [selectedTemplateId]);
+
 	            React.useEffect(() => {
 	                authedFetch(`/api/personas/${selectedSurveyorId}`)
 	                    .then(r => r.json())
@@ -256,6 +343,7 @@ Requirements:
 		                    surveyor_system_prompt: (surveyorSystemPrompt || '').trim(),
 		                    patient_system_prompt: (patientSystemPrompt || '').trim(),
 		                    analysis_system_prompt: (analysisSystemPrompt || '').trim(),
+		                    top_down_codebook_template_id: (selectedTemplateId || '').trim(),
 		                    analysis_attributes: (analysisAttributeItems || []).map((x) => (typeof x === 'string' ? x.trim() : '')).filter((x) => x.length > 0),
 		                };
 
@@ -285,6 +373,18 @@ Requirements:
 		                            })
 		                        }).catch(() => null)
 		                        : Promise.resolve(null),
+		                    (activePane === 'analysis' && selectedTemplateDetail && selectedTemplateDetail.is_default === false)
+		                        ? authedFetch(`/api/analysis-templates/${selectedTemplateId}`, {
+		                            method: 'PUT',
+		                            headers: { 'Content-Type': 'application/json' },
+		                            body: JSON.stringify({
+		                                categories: (selectedTemplateCategories || []).map((c) => ({
+		                                    category_id: (c && typeof c.category_id === 'string') ? c.category_id : '',
+		                                    label: (c && typeof c.label === 'string') ? c.label.trim() : '',
+		                                })).filter((c) => c.label && c.label.length > 0),
+		                            })
+		                        }).catch(() => null)
+		                        : Promise.resolve(null),
 		                ]).then(() => {
 		                    setSavedAt(cfg.saved_at);
 		                    setSaveFlash(true);
@@ -738,6 +838,132 @@ Requirements:
                                 </div>
                             </div>
 
+                            <div className="grid grid-cols-2 gap-6">
+                                <div>
+                                    <div className="flex items-center justify-between gap-3 mb-2">
+                                        <label className="block text-sm font-semibold text-slate-700">Top-down codebook template (applies to analyses)</label>
+                                    </div>
+                                    <div className="flex items-center gap-2 flex-wrap">
+                                        <select
+                                            className="w-full md:w-1/2 border border-slate-300 rounded-lg px-3 py-2 text-sm bg-white"
+                                            value={selectedTemplateId || ''}
+                                            onChange={(e) => setSelectedTemplateId(e.target.value)}
+                                        >
+                                            {(analysisTemplates.length ? analysisTemplates : [{template_id: 'top_down_v1', name: 'Default top-down codebook (v1)', is_default: true}]).map(t => (
+                                                <option key={t.template_id} value={t.template_id}>{t.name}</option>
+                                            ))}
+                                        </select>
+                                        <button
+                                            type="button"
+                                            onClick={async () => {
+                                                const id = await createAnalysisTemplate(null);
+                                                if (id) setSelectedTemplateId(id);
+                                            }}
+                                            className="bg-slate-100 hover:bg-slate-200 text-slate-800 px-3 py-2 rounded-lg text-sm font-semibold transition-all border border-slate-300"
+                                        >
+                                            + New
+                                        </button>
+                                        <button
+                                            type="button"
+                                            onClick={async () => {
+                                                const id = await createAnalysisTemplate(selectedTemplateId);
+                                                if (id) setSelectedTemplateId(id);
+                                            }}
+                                            className="bg-slate-100 hover:bg-slate-200 text-slate-800 px-3 py-2 rounded-lg text-sm font-semibold transition-all border border-slate-300"
+                                        >
+                                            Duplicate
+                                        </button>
+                                        <button
+                                            type="button"
+                                            disabled={!(selectedTemplateDetail && selectedTemplateDetail.is_default === false)}
+                                            onClick={async () => {
+                                                const ok = await deleteAnalysisTemplate(selectedTemplateId);
+                                                if (ok) {
+                                                    const list = await refreshAnalysisTemplates();
+                                                    const fallback = (list && list[0] && list[0].template_id) ? list[0].template_id : 'top_down_v1';
+                                                    setSelectedTemplateId(fallback);
+                                                }
+                                            }}
+                                            className="bg-white hover:bg-red-50 text-red-700 px-3 py-2 rounded-lg text-sm font-semibold transition-all border border-red-200 disabled:opacity-50 disabled:hover:bg-white"
+                                        >
+                                            Delete
+                                        </button>
+                                    </div>
+                                    {selectedTemplateDetail?.is_default !== false && (
+                                        <div className="mt-2 bg-amber-50 border border-amber-200 rounded-lg px-3 py-2 text-sm text-slate-800 w-fit">
+                                            Note: This is a default template that can't be edited. Create a new template to edit.
+                                        </div>
+                                    )}
+                                </div>
+                                <div />
+                            </div>
+
+                            <div className="grid grid-cols-2 gap-6">
+                                <div>
+                                    <div className="flex items-center justify-between gap-3 mb-2">
+                                        <label className="block text-sm font-semibold text-slate-700">
+                                            Codebook categories {selectedTemplateDetail?.is_default === false ? '' : '(read-only)'}
+                                        </label>
+                                    </div>
+                                    <div className="space-y-2">
+                                        {(selectedTemplateCategories || []).length === 0 ? (
+                                            <div className="text-sm text-slate-500">No categories.</div>
+                                        ) : (
+                                            (selectedTemplateCategories || []).map((cat, idx) => (
+                                                <div key={idx} className="flex items-start gap-2">
+                                                    <div className="mt-2 text-xs font-mono text-slate-500 w-10 shrink-0">{String(idx + 1).padStart(2, '0')}</div>
+                                                    <input
+                                                        className={`flex-1 border border-slate-300 rounded-lg px-3 py-2 text-sm ${selectedTemplateDetail?.is_default === false ? 'bg-white' : 'bg-slate-50 text-slate-600'}`}
+                                                        value={(cat && typeof cat.label === 'string') ? cat.label : ''}
+                                                        onChange={(e) => updateTemplateCategoryLabel(idx, e.target.value)}
+                                                        disabled={!(selectedTemplateDetail?.is_default === false)}
+                                                        placeholder="Category label..."
+                                                    />
+                                                    {selectedTemplateDetail?.is_default === false && (
+                                                        <>
+                                                            <button
+                                                                type="button"
+                                                                onClick={() => moveTemplateCategory(idx, -1)}
+                                                                className="text-slate-600 hover:text-slate-900 px-2 py-2 text-sm"
+                                                                title="Move up"
+                                                            >
+                                                                ↑
+                                                            </button>
+                                                            <button
+                                                                type="button"
+                                                                onClick={() => moveTemplateCategory(idx, 1)}
+                                                                className="text-slate-600 hover:text-slate-900 px-2 py-2 text-sm"
+                                                                title="Move down"
+                                                            >
+                                                                ↓
+                                                            </button>
+                                                            <button
+                                                                type="button"
+                                                                onClick={() => removeTemplateCategory(idx)}
+                                                                className="text-slate-600 hover:text-red-600 px-2 py-2 text-sm"
+                                                                title="Remove category"
+                                                            >
+                                                                ✕
+                                                            </button>
+                                                        </>
+                                                    )}
+                                                </div>
+                                            ))
+                                        )}
+                                        {selectedTemplateDetail?.is_default === false && (
+                                            <button
+                                                type="button"
+                                                onClick={addTemplateCategory}
+                                                className="bg-slate-100 hover:bg-slate-200 text-slate-800 px-3 py-2 rounded-lg text-sm font-semibold transition-all border border-slate-300"
+                                            >
+                                                + Add category
+                                            </button>
+                                        )}
+                                    </div>
+                                </div>
+                                <div />
+                            </div>
+
                             <div className="grid grid-cols-2 gap-6">
                                 <div>
                                     <div className="flex items-center justify-between gap-3 mb-2">

frontend/pages/shared_views.py

@@ -463,20 +463,53 @@ def get_shared_views_js() -> str:
                             <div className="space-y-3">
                                 <div className="text-lg font-extrabold text-slate-900 mb-2">Top-down codebook categories</div>
                                 {(() => {
-                                    const td = activeResources?.top_down_codes || {};
-                                    const order = [
-                                        { key: 'symptoms_concerns', label: 'Symptoms/concerns', empty: 'No symptoms/concerns excerpts detected.' },
-                                        { key: 'daily_management', label: 'Daily management', empty: 'No daily management excerpts detected.' },
-                                        { key: 'barriers_constraints', label: 'Barriers/constraints', empty: 'No barriers/constraints excerpts detected.' },
-                                        { key: 'support_resources', label: 'Support/resources', empty: 'No support/resources excerpts detected.' }
-                                    ];
+                                    const tdBook = activeResources?.top_down_codebook || null;
+                                    const legacy = activeResources?.top_down_codes || {};
+
+                                    const legacyLabels = {
+                                        symptoms_concerns: 'Symptoms/concerns',
+                                        daily_management: 'Daily management',
+                                        barriers_constraints: 'Barriers/constraints',
+                                        support_resources: 'Support/resources'
+                                    };
+                                    const legacyOrder = ['symptoms_concerns', 'daily_management', 'barriers_constraints', 'support_resources'];
+
+                                    const categories = (() => {
+                                        if (tdBook && Array.isArray(tdBook.categories)) {
+                                            return tdBook.categories
+                                                .filter((c) => c && typeof c === 'object')
+                                                .map((c) => ({
+                                                    category_id: String(c.category_id || ''),
+                                                    label: String(c.label || c.category_id || 'Category'),
+                                                    items: Array.isArray(c.items) ? c.items : []
+                                                }));
+                                        }
+
+                                        const out = [];
+                                        if (legacy && typeof legacy === 'object') {
+                                            const seen = new Set();
+                                            legacyOrder.forEach((key) => {
+                                                if (Array.isArray(legacy[key])) {
+                                                    seen.add(key);
+                                                    out.push({ category_id: key, label: legacyLabels[key] || key, items: legacy[key] });
+                                                }
+                                            });
+                                            Object.keys(legacy).forEach((key) => {
+                                                if (seen.has(key)) return;
+                                                if (Array.isArray(legacy[key])) out.push({ category_id: key, label: key, items: legacy[key] });
+                                            });
+                                        }
+                                        return out;
+                                    })();
 
                                     return (
                                         <div className="space-y-3">
-                                            {order.map(({ key, label, empty }) => {
-                                                const arr = td[key] || [];
+                                            {categories.map((cat) => {
+                                                const arr = Array.isArray(cat.items) ? cat.items : [];
+                                                const label = cat.label || 'Category';
+                                                const empty = `No ${String(label).toLowerCase()} excerpts detected.`;
                                                 return (
-                                                    <div key={key} className="bg-slate-50 border border-slate-200 rounded-lg p-3">
+                                                    <div key={cat.category_id || label} className="bg-slate-50 border border-slate-200 rounded-lg p-3">
                                                         <div className="font-extrabold text-slate-900">Code: {label}</div>
                                                         {arr.length === 0 ? (
                                                             <div className="text-sm text-slate-600 mt-2">{empty}</div>