From 36be363c18c4c906440323d2929021437682260e Mon Sep 17 00:00:00 2001
From: Michael Bleigh <bleigh@google.com>
Date: Sun, 12 Oct 2025 15:24:31 -0700
Subject: [PATCH] chore: more guidance tweaks

---
 js/genkit/.guides/config.json | 10 +++++-----
 js/genkit/.guides/usage.md    | 21 +++++++++++++++++++--
 2 files changed, 24 insertions(+), 7 deletions(-)

diff --git a/js/genkit/.guides/config.json b/js/genkit/.guides/config.json
index 21d4b59a96..e18da19691 100644
--- a/js/genkit/.guides/config.json
+++ b/js/genkit/.guides/config.json
@@ -10,30 +10,30 @@
       "url": "https://genkit.dev/docs/models.md",
       "name": "generate-content",
       "title": "Generate Content",
-      "description": "how to generate content (text, structured data, images, videos) with Genkit."
+      "description": "read this before using Genkit to generate content (text, structured data, images, videos)"
     },
     {
       "url": "https://genkit.dev/docs/flows.md",
       "name": "flows",
       "title": "Using Flows to build GenAI Workflows",
-      "description": "how to construct strongly typed AI workflows with Genkit."
+      "description": "read this to understand Genkit flows. ALWAYS read before building new workflows with Genkit"
     },
     {
       "url": "https://genkit.dev/docs/tool-calling.md",
       "name": "tool-calling",
       "title": "Tool Calling",
-      "description": "an in-depth guide to providing tools/functions to Genkit for GenAI"
+      "description": "read to understand providing tools/function calling for Genkit"
     },
     {
       "url": "https://genkit.dev/docs/interrupts.md",
       "name": "tool-calling/interrupts",
       "title": "Interrupts (Tool Calling with Human-in-the-Loop)",
-      "description": "instructions on how to use interrupts to provide human-in-the-loop capabilities to Genkit agents"
+      "description": "read to understand how to provide human-in-the-loop and tool confirmation capabilities to Genkit agents"
     },
     {
       "url": "https://genkit.dev/docs/context.md",
       "name": "context",
-      "description": "how to pass context to tools and flows without exposing sensitive data to the LLM"
+      "description": "read to understand how to pass relevant context to tools and flows without exposing sensitive data to the LLM"
     }
   ]
 }
diff --git a/js/genkit/.guides/usage.md b/js/genkit/.guides/usage.md
index c30842b3a2..5ed7518797 100644
--- a/js/genkit/.guides/usage.md
+++ b/js/genkit/.guides/usage.md
@@ -1,7 +1,12 @@
 ## Basic Example
 
 ```ts
-import { ai, z } from "@/ai/genkit"; // or wherever genkit is initialized
+import { genkit, z } from "genkit";
+import { googleAI } from "@genkit-ai/google-genai"; // or other model plugin
+const ai = genkit({
+  plugins: [googleAI()],
+  model: googleAI.model('gemini-2.5-flash'),
+});
 
 const myTool = ai.defineTool({name, description, inputSchema: z.object(...)}, (input) => {...});
 
@@ -27,6 +32,15 @@ const {output} = await ai.generate({
 **IMPORTANT:** This app uses Genkit v1.19 which has changed significantly from pre-1.0 versions. Important changes include:
 
 ```ts
+// genkit is initialized into an instance
+import { genkit, z } from "genkit";
+const ai = genkit({plugins: [...]});
+
+// tools, flows, etc. are defined via method calls to the instance
+const someFlow = ai.defineFlow({...});
+const someTool = ai.defineTool({...});
+
+// methods are called on the initialized instance
 const response = await ai.generate(...);
 
 response.text // CORRECT 1.x syntax
@@ -36,14 +50,17 @@ response.output // CORRECT 1.x syntax
 response.output() // INCORRECT pre-1.0 syntax
 
 const {stream, response} = ai.generateStream(...); // IMPORTANT: no `await` needed
+
 for await (const chunk of stream) { } // CORRECT 1.x syntax
 for await (const chunk of stream()) { } // INCORRECT pre-1.0 syntax
+
 await response; // CORRECT 1.x syntax
 await response(); // INCORRECT pre-1.0 syntax
+
 await ai.generate({..., model: googleAI.model('gemini-2.5-flash')}); // CORRECT 1.x syntax
 await ai.generate({..., model: gemini15Pro}); // INCORRECT pre-1.0 syntax
 ```
 
 - Use `import {z} from "genkit"` when you need Zod to get an implementation consistent with Genkit.
 - When defining Zod schemas, ONLY use basic scalar, object, and array types. Use `.optional()` when needed and `.describe('...')` to add descriptions for output schemas.
-- Genkit has many capabilities, make sure to read docs when you need to use them.
+- Genkit has many capabilities, ALWAYS read docs when you need to use them.