{"templateId":"markdown","sharedDataIds":{},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Documentation Review: Developer Experience Analysis","siteUrl":"https://platform.papr.ai","description":"Papr Memory is an AI-native memory layer that lets developers add production-ready memory to their AI agents and apps with just a few lines of code."},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"documentation-review-developer-experience-analysis"},"children":["Documentation Review: Developer Experience Analysis"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"executive-summary"},"children":["Executive Summary"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Reviewed all changes from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apis/index.yaml"]}," update. Three major areas updated:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Session history order"]}," — Fixed newest-first behavior across all examples"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Memory lifecycle"]}," — Added async status, webhooks, holographic/graph-aware"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Graph-aware embeddings"]}," — New positioning guide with built-in schemas"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"whats-working-well-"},"children":["What's Working Well ✅"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"1.-graph-aware-embeddings-guide"},"children":["1. Graph-aware embeddings guide"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Clear concept"]},": \"reshapes vector space\" metaphor"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Concrete tables"]},": Three built-in schemas with all 14 dimensions"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["API mapping table"]},": Shows where each capability lives"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Decision criteria"]},": \"When to enable\" / \"When to skip\""]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"2.-session-history-fixes"},"children":["2. Session history fixes"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Consistent"]},": All Python/TypeScript examples now ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reversed()"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".reverse()"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Explicit callout"]},": States \"newest first\" upfront"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Complete coverage"]},": Fixed in messages-management, compression, context-handling, tutorials"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"3.-memory-lifecycle"},"children":["3. Memory lifecycle"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Clear table"]},": Poll vs webhook vs WebSocket"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Status states"]},": Listed all five states (queued → completed/failed)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Cross-references"]},": Points to document-processing for webhook patterns"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"critical-dx-issues-"},"children":["Critical DX Issues 🔴"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"issue-1-graph-aware-embeddings--dense-opening"},"children":["Issue 1: Graph-aware embeddings — Dense opening"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Problem:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"Graph-aware embeddings are a Papr embedding mode that reshapes the vector space \nso it behaves like a structured graph of meaning, not only a flat semantic similarity.\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["accurate but intimidating"]},". Developers scan the first paragraph to decide \"is this for me?\""]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Fix:"]}," ","Add a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["problem-first"]}," opening before the mechanism:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"# Graph-aware embeddings and domain schemas\n\n**The problem:** Standard vector search ranks by \"semantic closeness\" but can't tell if two results \nare close for the **same reason**. A code snippet about \"sorting arrays\" and \"sorting linked lists\" \nmight be semantically near but use different algorithms, data structures, and APIs.\n\n**Graph-aware embeddings** solve this by encoding **structured domain dimensions** alongside your \nbase vector—things like \"programming language,\" \"operation type,\" \"temporal context,\" or custom \nfields you define. Search can then filter and boost by **topical alignment**, **domain-specific \ncontext**, and other axes beyond flat similarity.\n\n**Implementation:** Uses Papr's holographic pipeline (`enable_holographic`, `holographic_config`, \n`/v1/holographic/*`). This guide covers **concepts and schemas**; API request/response shapes are \nin the [API reference](/apis/index.yaml).\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"issue-2-hz-vs-frequency--terminology-confusion"},"children":["Issue 2: Hz vs frequency — Terminology confusion"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Problem:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Built-in schema tables show: ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Hz"]}," (0.1, 0.5, 2.0, 4.0...)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Custom schema API uses: ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["frequency"]}]}," (with allowed values from spec)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Footnote says \"Table types describe dimension; API uses lowercase\" but doesn't clarify Hz mapping"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Fix:"]}," ","Add a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Hz explainer"]}," before custom schema section:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"## About frequency bands (Hz values)\n\nThe built-in schemas show **Hz** values (0.1, 0.5, 2.0, etc.) representing the 14 standard \n**brain-inspired frequency bands** in holographic encoding. When registering a custom schema, \nyour `frequency` field must use one of these allowed values (see `CustomFrequencyField` in the \nAPI reference for the exact enum).\n\n**Rule of thumb:** \n- Lower Hz (0.1–2.0) → Categorical/Enum dimensions (language, domain)\n- Mid Hz (4.0–14) → Descriptive/FreeText dimensions (intent, operation)\n- Higher Hz (18–70) → List/MultiValue dimensions (APIs, entities)\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"issue-3-missing-should-i-use-this-decision-tree"},"children":["Issue 3: Missing \"should I use this?\" decision tree"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Problem:"]}," ","The guide says \"when to enable\" but doesn't help developers ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["self-assess"]}," if their problem fits."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Fix:"]}," ","Add a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["decision flowchart"]}," before \"When to enable\":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"## Do you need graph-aware embeddings?\n\nFollow this decision tree:\n\n1. **Is your baseline search \"good enough\"?**  \n   → Yes: Skip graph-aware. Standard semantic + agentic graph is sufficient.  \n   → No: Continue ↓\n\n2. **Can you describe the quality gap in domain terms?**  \n   Examples: \"Returns Python when I need JavaScript,\" \"Mixes bug reports with feature requests\"  \n   → Yes: You have a domain mismatch → Continue ↓  \n   → No: Your problem might be query quality or data sparsity, not embeddings\n\n3. **Does a built-in schema match your domain?**  \n   - **cosqa** → Code search (snippet ↔ natural language)  \n   - **scifact** → Scientific claims ↔ evidence  \n   - **general** → Mixed content domains  \n   → Yes: Start with built-in → Measure → Tune  \n   → No: Continue ↓\n\n4. **Can you define 4-14 structured dimensions for your domain?**  \n   Examples: contract_type, jurisdiction, ticket_priority, user_intent  \n   → Yes: Register custom schema with Papr → Co-design recommended  \n   → No: Graph-aware mode requires a schema; revisit when you can articulate dimensions\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"issue-4-no-concrete-before/after-example"},"children":["Issue 4: No concrete before/after example"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Problem:"]}," ","No example showing ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["what difference it makes"]},". Developers need to see impact to justify complexity."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Fix:"]}," ","Add a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["comparison example"]}," after \"Why it matters\":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"## Example: Code search with vs without graph-aware\n\n**Query:** \"How do I sort a list in Python?\"\n\n### Standard semantic search (without graph-aware):\nReturns mixed results:\n1. Python `list.sort()` ✅\n2. JavaScript `array.sort()` ❌ (different language)\n3. Python sorting algorithms tutorial ⚠️ (conceptual, not code)\n4. SQL `ORDER BY` ❌ (different domain)\n\n### With graph-aware embeddings (cosqa schema):\nReturns filtered results aligned on **language=Python** and **primary_operation=sorting**:\n1. Python `list.sort()` ✅\n2. Python `sorted()` function ✅\n3. Python custom sort with `key=` ✅\n4. Python `heapq.nsmallest()` for partial sorts ✅\n\n**Why:** The schema encodes **programming_domain**, **language**, and **primary_operation** dimensions. \nH-COND scoring boosts results with high alignment on these fields.\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"medium-dx-issues-"},"children":["Medium DX Issues 🟡"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"issue-5-session-history--missing-why-reverse"},"children":["Issue 5: Session history — Missing \"why reverse\""]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Problem:"]}," ","Examples show ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reversed()"]}," but don't explain ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["when you need chronological vs newest-first display"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Fix:"]}," ","Add guidance in messages-management.md after the callout:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"**When to reverse:**\n- **Building LLM prompts**: Models expect chronological flow (oldest → newest)\n- **Timeline displays**: Users expect conversation order\n- **Transcript exports**: Standard format is oldest-first\n\n**When to keep as-is (newest-first):**\n- **Recent activity feeds**: \"What happened recently?\"\n- **Pagination UX**: Load latest messages first, older on scroll\n- **Admin dashboards**: Show most recent interactions\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"issue-6-memory-status--no-full-lifecycle-example"},"children":["Issue 6: Memory status — No full lifecycle example"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Problem:"]}," ","The table shows ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["what"]}," to use but not ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["how"]}," or ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["when"]}," in a real flow."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Fix:"]}," ","Add a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["complete example"]}," after the status table:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"### Full lifecycle example\n\n```python\n# 1. Create memory with webhook\nmemory = client.memory.add(\n    content=\"Q4 planning: Launch new API, hire 2 engineers, $200k budget\",\n    enable_holographic=True,\n    frequency_schema_id=\"general\",\n    webhook_url=\"https://api.myapp.com/papr-webhook\",\n    webhook_secret=\"my_webhook_secret_key\"\n)\n\nmemory_id = memory.memory_id\nprint(f\"Created: {memory_id}, initial status: quick_saved\")\n\n# 2. Poll status if you need it immediately (webhook takes ~seconds)\nimport time\nfor i in range(5):\n    status = client.memory.get_status(memory_id)\n    print(f\"Poll {i+1}: {status.status}\")\n    if status.status == \"completed\":\n        break\n    time.sleep(2)\n\n# 3. Webhook handler (receives POST when done)\n# POST https://api.myapp.com/papr-webhook\n# Headers: X-Webhook-Secret, X-Webhook-Signature (HMAC)\n# Body: {\"event\": \"memory.completed\", \"memory_id\": \"...\", \"status\": \"completed\", \"completed_at\": \"...\"}\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["When to use each:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Webhook"]},": Background processing, decoupled systems, batch workflows"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Polling"]},": Need result immediately in same request flow"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["WebSocket"]},": Real-time UI updates, progress bars, live dashboards"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"\n### Issue 7: Holographic terminology inconsistency\n\n**Problem:**\nWe use both \"holographic\" and \"graph-aware\" — relationship not always clear.\n\n**Fix:**\nAdd a **terminology box** at the top of graph-aware-embeddings.md:\n\n```markdown\n> **Terminology:** We call this **graph-aware embeddings** (concept) implemented via \n> **holographic** APIs (technology). When you see `enable_holographic` or \n> `holographic_config`, that's the implementation layer. When we discuss \"domain schemas\" \n> and \"structured dimensions,\" that's the conceptual layer this guide focuses on.\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"minor-dx-issues-"},"children":["Minor DX Issues 🟢"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"issue-8-custom-schema-example--no-response-handling"},"children":["Issue 8: Custom schema example — No response handling"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Problem:"]}," ","Shows the POST request but not what comes back or how to use the returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["schema_id"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Fix:"]}," ","Complete the example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"// Response\n{\n  \"status\": \"success\",\n  \"schema_id\": \"acme:legal_contracts:1.0.0\",\n  \"domain\": \"legal_contracts\",\n  \"num_frequencies\": 4\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Then show usage:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"# Use the returned schema_id when adding memories\nclient.memory.add(\n    content=\"Signed NDA with Acme Corp, jurisdiction: US, expires 2027-01-01\",\n    enable_holographic=True,\n    frequency_schema_id=\"acme:legal_contracts:1.0.0\"  # Use registered schema\n)\n\n# And in search\nresults = client.memory.search(\n    query=\"Find all active NDAs in US jurisdiction\",\n    holographic_config={\n        \"enabled\": True,\n        \"frequency_schema_id\": \"acme:legal_contracts:1.0.0\",\n        \"frequency_filters\": {\n            \"contract_type\": 0.9,  # Must be 90%+ aligned on contract type\n            \"jurisdiction\": 0.8    # Must be 80%+ aligned on jurisdiction\n        }\n    }\n)\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"issue-9-changelog--graph-aware-not-aligned-with-guide-title"},"children":["Issue 9: Changelog — \"Graph-aware\" not aligned with guide title"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Problem:"]}," ","Changelog says \"Graph-aware embeddings\" but then references holographic endpoints."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Fix:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"- **Graph-aware embeddings (holographic APIs)** — Documented as domain-tuned vector space \n  (built-in **cosqa**, **scifact**, **general**; custom schemas via `POST /v1/holographic/domains`). \n  Implementation uses `enable_holographic`, `holographic_config`, `/v1/holographic/*` endpoints. \n  See [Graph-aware embeddings guide](/guides/graph-aware-embeddings.md); API shapes in \n  [API reference](/apis/index.yaml).\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"issue-10-capability-matrix--no-quickstart-path-for-graph-aware"},"children":["Issue 10: Capability matrix — No quickstart path for graph-aware"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Problem:"]}," ","Matrix shows graph-aware row but no \"get started\" link like other capabilities have."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Fix:"]}," ","Add a \"Getting Started\" column or quick example in the key fields:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"| Domain-tuned (graph-aware) retrieval | ... | Start with `frequency_schema_id=\"general\"`, \nthen move to domain-specific (`cosqa`, `scifact`) or custom. See \n[Graph-aware guide](../guides/graph-aware-embeddings.md) for decision tree |\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"structural-recommendations-"},"children":["Structural Recommendations 📐"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"1.-add-graph-aware-quickstart-tutorial"},"children":["1. Add \"Graph-aware quickstart\" tutorial"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Problem:"]}," No 5-minute path to see it working."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Recommendation:"]}," ","Create ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tutorials/graph-aware-search.md"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["cosqa"]}," schema (code search)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Show baseline search returning mixed languages"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Enable holographic with cosqa"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Show filtered results"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Explain the difference"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"2.-cross-link-decision-flow"},"children":["2. Cross-link decision flow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Current:"]}," Graph-aware guide is standalone"," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Recommendation:"]}," Link from:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["guides/search-tuning.md"]}," → \"If baseline ranking isn't precise enough...\""]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["guides/retrieval.md"]}," → \"For domain-specific...\""]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["quickstart/index.md"]}," → \"Advanced: Domain-tuned search\""]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"3.-add-troubleshooting-section-to-graph-aware-guide"},"children":["3. Add troubleshooting section to graph-aware guide"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Common issues:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["\"Results didn't improve\" → Wrong schema / query still too broad"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["\"frequency_schema_id not found\" → Need to GET /v1/frequencies for valid ids"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["\"Slower than baseline\" → Some scoring methods are GPU-heavy (check docs)"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"validation-checklist-"},"children":["Validation Checklist ✓"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":true,"type":"checkbox","readOnly":true},"children":[]}," All code examples use correct API paths"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":true,"type":"checkbox","readOnly":true},"children":[]}," Request/response shapes match OpenAPI spec"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":true,"type":"checkbox","readOnly":true},"children":[]}," No broken internal links (validated with script)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":true,"type":"checkbox","readOnly":true},"children":[]}," Consistent terminology within each guide"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":true,"type":"checkbox","readOnly":true},"children":[]}," Changelog accurately describes changes"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":true,"type":"checkbox","readOnly":true},"children":[]}," Examples include error handling patterns"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"priority-improvements"},"children":["Priority Improvements"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"do-first-high-impact-low-effort"},"children":["Do First (High Impact, Low Effort):"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add problem-first opening to graph-aware guide"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add Hz explainer before custom schema section"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add terminology box clarifying holographic vs graph-aware"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add \"when to reverse\" guidance for session history"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Complete custom schema example with response + usage"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"do-next-high-impact-medium-effort"},"children":["Do Next (High Impact, Medium Effort):"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add decision tree flowchart to graph-aware guide"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add before/after comparison example"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add full lifecycle example to memory status section"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Cross-link graph-aware from search-tuning and retrieval"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"nice-to-have-medium-impact-higher-effort"},"children":["Nice to Have (Medium Impact, Higher Effort):"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create graph-aware quickstart tutorial"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add troubleshooting section"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add \"Getting Started\" column to capability matrix"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"final-assessment"},"children":["Final Assessment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Overall quality:"]}," B+ → A- (with recommended fixes)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Strengths:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Accurate and complete coverage of API changes"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Consistent terminology within each doc"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Good use of tables and structured information"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Examples match OpenAPI spec"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Opportunities:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Lead with problems, not mechanisms"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Show impact (before/after examples)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Reduce cognitive load at decision points"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Complete the \"getting started → production\" journey"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Developer journey gaps:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["\"Should I use graph-aware?\" → Needs decision tree"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["\"What will it do for me?\" → Needs comparison example"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["\"How do I get started?\" → Needs quickstart or inline example"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["\"Something's not working\" → Needs troubleshooting section"]}]}]},"headings":[{"value":"Documentation Review: Developer Experience Analysis","id":"documentation-review-developer-experience-analysis","depth":1},{"value":"Executive Summary","id":"executive-summary","depth":2},{"value":"What's Working Well ✅","id":"whats-working-well-","depth":2},{"value":"1. Graph-aware embeddings guide","id":"1.-graph-aware-embeddings-guide","depth":3},{"value":"2. Session history fixes","id":"2.-session-history-fixes","depth":3},{"value":"3. Memory lifecycle","id":"3.-memory-lifecycle","depth":3},{"value":"Critical DX Issues 🔴","id":"critical-dx-issues-","depth":2},{"value":"Issue 1: Graph-aware embeddings — Dense opening","id":"issue-1-graph-aware-embeddings--dense-opening","depth":3},{"value":"Issue 2: Hz vs frequency — Terminology confusion","id":"issue-2-hz-vs-frequency--terminology-confusion","depth":3},{"value":"Issue 3: Missing \"should I use this?\" decision tree","id":"issue-3-missing-should-i-use-this-decision-tree","depth":3},{"value":"Issue 4: No concrete before/after example","id":"issue-4-no-concrete-before/after-example","depth":3},{"value":"Medium DX Issues 🟡","id":"medium-dx-issues-","depth":2},{"value":"Issue 5: Session history — Missing \"why reverse\"","id":"issue-5-session-history--missing-why-reverse","depth":3},{"value":"Issue 6: Memory status — No full lifecycle example","id":"issue-6-memory-status--no-full-lifecycle-example","depth":3},{"value":"Minor DX Issues 🟢","id":"minor-dx-issues-","depth":2},{"value":"Issue 8: Custom schema example — No response handling","id":"issue-8-custom-schema-example--no-response-handling","depth":3},{"value":"Issue 9: Changelog — \"Graph-aware\" not aligned with guide title","id":"issue-9-changelog--graph-aware-not-aligned-with-guide-title","depth":3},{"value":"Issue 10: Capability matrix — No quickstart path for graph-aware","id":"issue-10-capability-matrix--no-quickstart-path-for-graph-aware","depth":3},{"value":"Structural Recommendations 📐","id":"structural-recommendations-","depth":2},{"value":"1. Add \"Graph-aware quickstart\" tutorial","id":"1.-add-graph-aware-quickstart-tutorial","depth":3},{"value":"2. Cross-link decision flow","id":"2.-cross-link-decision-flow","depth":3},{"value":"3. Add troubleshooting section to graph-aware guide","id":"3.-add-troubleshooting-section-to-graph-aware-guide","depth":3},{"value":"Validation Checklist ✓","id":"validation-checklist-","depth":2},{"value":"Priority Improvements","id":"priority-improvements","depth":2},{"value":"Do First (High Impact, Low Effort):","id":"do-first-high-impact-low-effort","depth":3},{"value":"Do Next (High Impact, Medium Effort):","id":"do-next-high-impact-medium-effort","depth":3},{"value":"Nice to Have (Medium Impact, Higher Effort):","id":"nice-to-have-medium-impact-higher-effort","depth":3},{"value":"Final Assessment","id":"final-assessment","depth":2}],"frontmatter":{"seo":{"title":"Documentation Review: Developer Experience Analysis"}},"lastModified":"2026-04-22T01:40:48.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/internal/planning/dx-review-spec-changes","userData":{"isAuthenticated":false,"teams":["anonymous"]}}