docs(cookbook): restructure the section and rework all 69 recipes to the working standard - #827
Merged
Conversation
FastNav swaps article, TOC, title, and sidebar on intercepted link clicks, but never the header tabs, so cross-tab jumps through the sidebar dropdown's Reference section (Docs to Cookbooks to SDK) kept the previous tab highlighted. Swap the header tablist from the fetched document alongside the other regions. Signed-off-by: khushalsonawat <khushalsonawat@gmail.com>
Landing pages for the two new cookbook sections. Each renders a card grid per sub-group covering all 57 recipes between them, and serves as the section's entry point in the sidebar switcher. Signed-off-by: khushalsonawat <khushalsonawat@gmail.com>
Replace the single flat Cookbooks group (with repeated product headings) with three switchable sections: Get Started, Use Cases, and Platform. Use Cases and Platform divide into collapsible sub-group folders (opt-in via a new NavItem.collapsible flag, so Docs/SDK sub-headings are untouched); Get Started keeps Production & CI/CD as a static section. All 70 recipes keep their existing routes. Sidebar dropdown changes: the hard-coded Docs/SDK phased-order branches become one per-tab config map, a group's dropdown link now resolves to its first linked page however deep (unlinked sub-headings no longer fall back to /docs), and the Reference entry for /docs/cookbook is renamed Guides to Cookbooks to match the tab. Signed-off-by: khushalsonawat <khushalsonawat@gmail.com>
The Colab and GitHub badges on 31 cookbooks linked notebooks on the cookbook/quickstart-notebooks and cookbook/falcon-ai-page feature branches, which die if those branches are pruned. The notebooks are on main as of future-agi/cookbooks#14, so point every badge at blob/main. Also fixes the one dead link: the golden-datasets page linked eval-datasets-from-traces.ipynb, which exists as golden-datasets-from-traces.ipynb. Signed-off-by: khushalsonawat <khushalsonawat@gmail.com>
The published system prompt was a plain helpful-assistant line that never reproduces the grounding failure the page teaches, so the low-adherence filter and insight steps had nothing to find. Restore the goodwill-override prompt the sandbox run actually used, add the span attributes that run set (GEN_AI_SPAN_KIND, INPUT_VALUE, OUTPUT_VALUE, and explicit SESSION_ID/USER_ID, which using_session/using_user do not apply to a manual span), pin the install versions, carry the full frontmatter, and extend troubleshooting to cover both gaps. Signed-off-by: khushalsonawat <khushalsonawat@gmail.com>
An external-link sweep of the cookbook corpus (217 unique URLs) found 16 genuinely dead links, all fixed here: - 10 absolute docs.futureagi.com links to long-moved pages, converted to their current relative routes so the link audit catches any future move - community.futureagi.com (NXDOMAIN, domain is gone) replaced with the GitHub repo - one cookbooks-repo tree link pointing at a path that never existed - 5 app.futureagi.com deep links using routes absent from the SPA router (settings/api_keys, workbench/all, projects/observe), pointed at the real routes Also worth knowing: app.futureagi.com serves HTTP 404 status for every SPA sub-route while returning the working app shell, so link checkers see dead links sitewide even where users do not. That is a hosting fallback misconfig, out of scope here. Signed-off-by: khushalsonawat <khushalsonawat@gmail.com>
Anchor links into docs pages never scrolled to their heading: the ClientRouter sets history.scrollRestoration to manual and swallows hash scrolling on both direct loads and client-side navigations (the same reason TableOfContents scrolls manually). FastNav now skips intercepting hash links and scrolls to the URL hash itself on every page load, using the TOC's 80px fixed-header offset, with one re-alignment after the transition settles. Separately, leaving an anchor-entered page kept the old scroll offset on the next page. The site's scroll-behavior: smooth CSS turns the two-arg scrollTo(0, 0) into an animation, which a pending transition cancels before it moves at all. The reset now uses behavior: 'instant' plus a guarded re-assert that only undoes an exact restoration of the departed page's offset. Signed-off-by: khushalsonawat <khushalsonawat@gmail.com>
The overview predated the sidebar restructure: seven stale headings, a hand-picked subset of recipes, and Card img props that Card.astro silently drops, rendering bare cards. The full listings now live on the Use Cases and Platform section pages, so the root page becomes a hub: Start Here (6 quickstarts), By Use Case (6 cards deep-linking the section anchors, with recipe counts), By Platform Feature (4). All hrefs and anchor ids verified against the rendered pages. Signed-off-by: khushalsonawat <khushalsonawat@gmail.com>
All 13 pages rewritten to the cookbook working standard: full frontmatter, TLDR, Package metadata table, Python 3.11 floor, stepped tutorials with expected-output beats, 5+ row troubleshooting tables, one forward link. Code verified against the SDK clones and, where one exists, the page's tested notebook; badge rows only where the notebook is real on future-agi/cookbooks main. Notebooks, real runs, and screenshots remain ticket work. Refs: TH-7586 Signed-off-by: khushalsonawat <khushalsonawat@gmail.com>
…ndard Six pages (observe-langgraph was already current). Same treatment as the rest of the corpus: standard shape, SDK-verified code, house voice, badge rows only for verified notebooks. Refs: TH-7587 Signed-off-by: khushalsonawat <khushalsonawat@gmail.com>
Five pages, three of them legacy rewrites. Retired the nonexistent ContextRetrieval template references in favor of real builtin evals, standard shape throughout, SDK-verified code. Refs: TH-7588 Signed-off-by: khushalsonawat <khushalsonawat@gmail.com>
Four pages. mongodb additionally gains the Atlas Vector Search index definition its code referenced but never defined, and the current vector (not knnVector) index type. Refs: TH-7597 Signed-off-by: khushalsonawat <khushalsonawat@gmail.com>
…tandard Four pages across the two small Use Cases sub-groups. The near-duplicate pairs (voice-simulation/simulate-sdk, text-to-sql-eval/text-to-sql) are both reworked but not consolidated; consolidation is the cleanup ticket. Refs: TH-7589 Signed-off-by: khushalsonawat <khushalsonawat@gmail.com>
…andard Refs: TH-7590 Signed-off-by: khushalsonawat <khushalsonawat@gmail.com>
…dard image-evaluation additionally drops the fabricated ImageInputOutput eval class the old page taught; the replacement step uses SyntheticImageEvaluator, verified by introspecting the published ai-evaluation wheel (the class, the evaluate() signature, and the 'image' input key). Refs: TH-7591 Signed-off-by: khushalsonawat <khushalsonawat@gmail.com>
Refs: TH-7592 Signed-off-by: khushalsonawat <khushalsonawat@gmail.com>
… standard Ten pages. dataset-annotation gets the standard shape only; its deprecated in-dataset-UI content is the cleanup ticket's rewrite. Refs: TH-7598 Signed-off-by: khushalsonawat <khushalsonawat@gmail.com>
…andard Ten pages, half legacy agent-opt content. basic-optimization gains a baseline scoring step (before/after was missing entirely), loses an untested runtime claim, and corrects the generated_output explanation to match BasicDataMapper's actual sentinel semantics in the agent-opt source. Refs: TH-7593 Signed-off-by: khushalsonawat <khushalsonawat@gmail.com>
khushalsonawat
changed the title
atharva-bhange
approved these changes
Aug 19, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Pull Request
Description
The whole cookbook section, rebuilt in one branch. Eighteen commits in four movements:
img=cards rendered blank; Card.astro has no such prop), and Use Cases / Platform get overview pages listing every recipebehavior: 'instant'so the site's smooth-scroll CSS can't cancel them mid-transition00-WORKING-STANDARD.md— full frontmatter, TLDR, Package metadata table, Python 3.11 floor, stepped tutorials, 5+ row troubleshooting tables, one forward link, house voice. Code verified against the five SDK clones and, for 27 pages, their tested notebooks; every page adversarially reviewed (3–17 findings each, all fixed). Plus 16 dead links repaired and all Colab/GitHub badges repointed from feature branches tomain(Publish quickstart and falcon-ai notebooks to main cookbooks#14)Notable correctness catches, recorded in their commit bodies: a fabricated
ImageInputOutputeval class replaced with the wheel-verifiedSyntheticImageEvaluator; mongodb's undefined Atlas vector index now has its JSON definition (and the currentvectortype, not legacyknnVector); basic-optimization gains the baseline scoring its before/after claim always lacked.Why
The standard was locked on 2026-08-17/18 while the corpus predated all of it: 32 fully legacy pages, one troubleshooting section in 70 pages, zero full frontmatter, 28 pages teaching Python 3.9, and code drifted far enough from the SDKs to teach APIs that never existed. The sidebar taxonomy was the authoring history, not anything a reader would look for.
What this deliberately does not do
dataset-annotationgets the standard shape only; its deprecated in-dataset-UI story is also TH-7594last-tested-dateanywhere (nothing was run end-to-end), badge rows only on the 27 pages whose notebook exists onmain, illustrative numbers labeled as suchHow to review
Per-batch commits map one-to-one to the Linear batch tickets (
Refs:in each body), so batch-by-batch review works. Live checks that matter: the switcher dropdown on /docs/cookbook (three sections + Reference), folder collapse in Use Cases/Platform, an anchor card from the hub landing on its heading, and a cross-tab jump via the Reference links updating the header highlight.Recording
None attached; verified live against the dev server: all 69 pages compile and serve 200,
audit-linksreports zero broken nav/content links, production build exits 0.Checklist
Related Issues
Refs: TH-7585 (parent), TH-7586–TH-7594, TH-7597, TH-7598, TH-7599