docs: Mintlify nav and fixed flow visuals#1
Conversation
venkat1701
commented
May 13, 2026
venkat1701
commented
- Replace mint.json with consolidated docs.json to remove duplicate Documentation nav
- Add snippets/flow-visuals (vertical PipelineFlow, Tailwind styling, TokenRetryVisual)
- Humanize benchmarks, concepts, API overview, introduction, troubleshooting
- Fix authentication import path and add Mermaid + AuthSequence flow
- Update README navigation pointer to docs.json
- Replace mint.json with consolidated docs.json to remove duplicate Documentation nav - Add snippets/flow-visuals (vertical PipelineFlow, Tailwind styling, TokenRetryVisual) - Humanize benchmarks, concepts, API overview, introduction, troubleshooting - Fix authentication import path and add Mermaid + AuthSequence flow - Update README navigation pointer to docs.json Co-authored-by: Cursor <cursoragent@cursor.com>
venkat1701
changed the title
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
There was a problem hiding this comment.
Pull request overview
This PR modernizes the Mintlify documentation structure and refreshes much of the Tex docs copy, navigation, and visual explanations.
Changes:
- Replaces
mint.jsonwithdocs.jsonand updates README navigation guidance. - Adds reusable flow visuals and uses them in memory/auth docs.
- Rewrites quickstart, concepts, SDK/API references, recipes, migration, troubleshooting, and benchmark pages for clearer onboarding.
Reviewed changes
Copilot reviewed 39 out of 39 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
docs.json |
New consolidated Mintlify navigation/config. |
mint.json |
Removes legacy Mintlify config. |
README.md |
Points contributors to docs.json. |
snippets/flow-visuals.mdx |
Adds reusable flow/sequence visual components. |
introduction.mdx |
Reworks overview and doc entry points. |
quickstart.mdx |
Expands first-call walkthrough. |
authentication.mdx |
Adds auth flow diagram and refreshed auth guidance. |
benchmarks.mdx |
Humanizes benchmark methodology and claims. |
changelog.mdx |
Updates metadata copy/icon. |
troubleshooting.mdx |
Expands symptom/support guidance. |
concepts/memory-model.mdx |
Adds pipeline visuals and rewritten memory model explanation. |
concepts/retrieval.mdx |
Rewrites recall/ranking guidance. |
concepts/scopes.mdx |
Updates multi-tenancy/scoping copy. |
concepts/usage-billing.mdx |
Refreshes metering/quota guidance. |
sdk/installation.mdx |
Adds install CodeGroup and updated SDK setup copy. |
sdk/client.mdx |
Updates client metadata copy. |
sdk/conversations-remember.mdx |
Updates page metadata. |
sdk/recall.mdx |
Updates page metadata. |
sdk/usage.mdx |
Updates page metadata. |
sdk/errors.mdx |
Refreshes retry note wording. |
recipes/fastapi.mdx |
Rewrites FastAPI recipe with steps and production notes. |
recipes/langchain.mdx |
Reworks LangChain recipe structure. |
recipes/azure-openai-rag.mdx |
Rewrites Azure RAG walkthrough. |
recipes/slack-bot.mdx |
Reworks Slack bot recipe. |
recipes/streamlit.mdx |
Expands Streamlit recipe with staged walkthrough. |
recipes/multi-tenant-saas.mdx |
Reworks multi-tenant SaaS guidance. |
migration/from-redis.mdx |
Refreshes migration title/copy. |
migration/from-langchain-memory.mdx |
Refreshes migration metadata and tradeoffs copy. |
migration/from-supermemory.mdx |
Refreshes migration metadata. |
api-reference/overview.mdx |
Expands REST API overview. |
api-reference/account/me.mdx |
Updates metadata copy. |
api-reference/account/api-keys.mdx |
Updates metadata copy. |
api-reference/auth/signup.mdx |
Updates auth endpoint metadata. |
api-reference/auth/token-exchange.mdx |
Updates token exchange metadata. |
api-reference/auth/refresh.mdx |
Adds token retry visual and refreshed copy. |
api-reference/memory/ingest-memory.mdx |
Updates ingest endpoint metadata. |
api-reference/memory/recall.mdx |
Updates recall endpoint metadata. |
api-reference/usage/today.mdx |
Updates usage endpoint metadata. |
api-reference/usage/summary.mdx |
Updates monthly usage metadata. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| {"role": "user", "text": body.text, "timestamp": "2026-05-13T00:00:00Z"}, | ||
| {"role": "assistant", "text": answer, "timestamp": "2026-05-13T00:00:00Z"}, |
| @app.get("/healthz") | ||
| def healthz(tex: Tex = Depends(tex_client)): | ||
| try: | ||
| tex.usage.today() | ||
| return {"ok": True} | ||
| except Exception as e: | ||
| return {"ok": False, "error": str(e)}, 503 |
| <Step title="Collect the request id"> | ||
| Copy `e.request_id` from any SDK exception—UUID-shaped, safe to share. |
| `tex.recall(q, session_id, ...)` is your read path. | ||
| Stick with **`mode="active"`** for anything a person is staring at; switch to **`deep`** when you can spend more time or when **`active`** keeps coming back thin. **`top_k`** is your dial for context size—tight in chat, generous in digests—and it feeds straight into **`tokens_out`**. When **`confidence`** stays under about **0.3**, plan on skipping memory for that turn, widening the query, or trying **`deep`** once. | ||
|
|
||
| Python: `tex.recall(q, session_id, ...)`. HTTP: [recall](/api-reference/memory/recall). |
| { | ||
| id: "steady", | ||
| title: "SDK attaches Bearer access token", | ||
| detail: "Your business call runs (for example POST /recall) with Authorization: Bearer ….", |
There was a problem hiding this comment.
Review
Substantive work here, and the structural wins are real. I want most of this merged — the points below are about gaps that would matter if we shipped this as-is.
What's clearly better (keep)
mint.json→docs.jsonmigration. Current Mintlify schema, future-proof.- Sub-grouped sidebar (Concepts → Memory & retrieval / Tenancy & usage; Cookbook → Apps / Agents & channels / Production patterns). Easier to browse than the flat main.
snippets/flow-visuals.mdx— the<PipelineFlow>/<AuthSequence>/<TokenRetryVisual>components are purpose-built and brand-themed. Strict upgrade over generic Mermaid.- Quickstart-first ordering. Right call for a developer SDK — peer references (Stripe, Supabase, Clerk, our own Mintlify references) all do this.
- Frontmatter
icon:on every page — sidebar gets a real visual hierarchy. - Restrained tone on
/benchmarks— that page is the methodology page; humble there is the right register. Devs trust restrained, evidence-led claims more than bombast. - All SDK + REST API ref bodies preserved verbatim — every audited fact (
top_k=15/25,RecallEntity (id, label, score),timeline: Optional[str],RateLimitErrorretry semantics, org-scoped/me/api-keys,regex→pattern) is intact. No factual regressions in any of the SDK or API ref pages I checked. - No broken internal links. All 18
/-prefixed cross-references resolve. - No off-palette colors.
#F32C05/#FF5530/#C82200discipline preserved everywhere. - No orphaned files. Every
.mdxin the tree is in the nav; every nav entry has a backing file.
Gaps I'd close before merging
1. Accordion creep — 1 → 17 across the site
Net +16 AccordionGroups across this PR. Hidden content is friction; the surface ends up reading like a trailer pointing at where the info actually lives. Specifically:
introduction.mdx— 5 accordions in the "More" section (Latency / Isolation / Python vs HTTP / Quotas + bottom cards)quickstart.mdx— 3 accordions ("Load key from .env", "Call without SDK", "Reads")recipes/fastapi.mdx— 4 accordions for Prod tweakstroubleshooting.mdx— 4 accordions in "Extra"
A developer scanning a Production recipe wants every production pattern visible at once. A developer in panic mode on Troubleshooting wants every fix Cmd-F-searchable on one page, not behind chevrons. The earlier flatten pass deliberately removed these for that reason.
Suggest flattening all 16 into inline subheadings + bullets. README.md accordion can stay — that's setup steps for a different audience.
2. Trophy cards on the intro became travel brochures
Was:
#1. Beats EverMemOS (92.3%), MemMachine (91.7%), Zep (~85%), Mem0 (~66%).
Now:
Full-system benchmark; splits and baselines on /benchmarks.
The card descriptions are the only marketing surface inside the docs. A first-time visitor on introduction.mdx won't click through to the methodology page to verify the headline before deciding to scroll. Explicit competitor names + numbers do the proving in place.
The restrained tone is exactly right on /benchmarks (methodology). It's the wrong register on introduction.mdx (landing). Suggest restoring competitor-named framing in the two trophy <Card> blocks here.
3. Inline content moved to "See [X]" pointers
Pattern repeats across concepts and recipes: a paragraph mentions a topic and links out instead of demonstrating it. Same shape as the trophy-cards regression — the body becomes a referral, not a teach.
Pages where this is most visible:
concepts/memory-model.mdx—<PipelineFlow>is great, but the timing detail moves to an off-page referencequickstart.mdx— the "Reads" pointer table at the bottom is real estate that could host one inline tipconcepts/retrieval.mdx— mode descriptions point at the concept page instead of just showing latency/use-case inline
Suggest auditing every [X](/path) inside a body paragraph and asking would the reader benefit if the linked content were a 2-sentence inline excerpt instead? Almost always yes inside SDK/recipe context.
4. Snippet import path inconsistency
Three different relative styles for the same file:
api-reference/auth/refresh.mdx:8→"../../snippets/flow-visuals.mdx"authentication.mdx:7→"/snippets/flow-visuals.mdx"concepts/memory-model.mdx:7→"../snippets/flow-visuals.mdx"
All three work in Mintlify, but pick one. Root-absolute "/snippets/flow-visuals.mdx" is the canonical Mintlify pattern.
5. Page-title nit (small)
Overview — What is Tex? is the right title — pairs the structural cue (overview) with the implicit visitor question (what is it). Keep it. The default Introduction is generic.
- Updated language in authentication, benchmarks, and introduction for improved readability and precision. - Revised descriptions and details in API reference, including token management and memory ingestion/recall processes. - Streamlined troubleshooting guidance and symptom-response table for better user experience. - Adjusted formatting and structure in quickstart and changelog for enhanced scannability. - Ensured consistent terminology and phrasing throughout documentation to align with user feedback.
