docs: Post-GA backports from DevSite repo (#1922)

* docs: Post-GA backports from google3

* docs: Post-GA backports from google3

* docs: Post-GA backports from google3

docs/auth.md

@@ -1,6 +1,3 @@
-<!-- NOTE: prettier-ignore used in some snippets to allow copy/paste into Firebase Functions which
-use https://github.com/firebase/firebase-tools/blob/master/templates/init/functions/javascript/_eslintrc -->
-
 # Authorization and integrity
 
 When building any public-facing application, it's extremely important to protect
@@ -15,7 +12,7 @@ Alternatively, Firebase also provides auth context into the flow where it can
 do its own  checks. For non-Functions flows, auth can be managed and set
 through middleware.
 
-## Authorizing within a Flow
+## Authorize within a Flow {:# authorize-within-flow}
 
 Flows can check authorization in two ways: either the request binding
 (e.g. `onCallGenkit` for Cloud Functions for Firebase or `express`) can enforce
@@ -112,15 +109,15 @@ object in the UI, or on the command line with the `--context` flag:
 genkit flow:run selfSummaryFlow '{"uid": "abc-def"}' --context '{"auth": {"email_verified": true}}'
 ```
 
-## Authorizing with Cloud Functions for Firebase
+## Authorize using Cloud Functions for Firebase {:# authoring-using-cff}
 
 The Cloud Functions for Firebase SDKs support Genkit including
 integration with Firebase Auth / Google Cloud Identity Platform, as well as
 built-in Firebase App Check support.
 
 ### User authentication
-The `onCallGenkit()` wrapper provided by the Firebase Functions library works
-natively with the Cloud Functions for Firebase
+The `onCallGenkit()` wrapper provided by the Firebase Functions library has
+built-in support for the Cloud Functions for Firebase
 [client SDKs](https://firebase.google.com/docs/functions/callable?gen=2nd#call_the_function).
 When you use these SDKs, the Firebase Auth header is automatically included as
 long as your app client is also using the
@@ -227,15 +224,17 @@ export const selfSummary = onCallGenkit({
 
 When deploying flows to a server context outside of Cloud Functions for
 Firebase, you'll want to have a way to set up your own authorization checks
-alongside the native flows.
+alongside the built-in flows.
 
-Use a `ContextProvider`, which both populates context values such as `auth` as well
-as allowing you to provide a declarative policy or a policy callback. The genkit
-SDK provides `ContextProvider` such as `apiKey`, and plugins may expose them as well,
-such as `@genkit-ai/firebase/context` which can be used to build Firebase apps with
-backends that are not Cloud Functions for Firebase.
+Use a `ContextProvider` to populate context values such as `auth`, and to
+provide a declarative policy or a policy callback. The Genkit
+SDK provides `ContextProvider`s such as `apiKey`, and plugins may
+expose them as well. For example, the `@genkit-ai/firebase/context` plugin
+exposes a context provider for verifying Firebase Auth credentials and
+populating them into context.
 
-Given the snippet common to all kinds of applications:
+With code like the following, which might appear in a variety of
+applications:
 
 ```ts
 // Express app with a simple API key
@@ -255,7 +254,7 @@ export const selfSummaryFlow = ai.defineFlow(
 );
 ```
 
-You could secure a simple "flow server" express app with:
+You could secure a simple "flow server" express app by writing:
 
 ```ts
 import { apiKey } from "genkit";
@@ -268,7 +267,7 @@ startFlowServer({
 });
 ```
 
-Or you can build a custom express application using the same tools:
+Or you could build a custom express application using the same tools:
 
 ```ts
 import { apiKey } from "genkit";
@@ -284,7 +283,7 @@ app.listen(process.env.PORT, () => {
 })
 ```
 
-`ContextProvider`s are intended to be abstract of any web framework, so these
+`ContextProvider`s abstract out the web framework, so these
 tools work in other frameworks like Next.js as well. Here is an example of a
 Firebase app built on Next.js.
 
@@ -297,4 +296,4 @@ export const POST = appRoute(selfSummaryFlow, { contextProvider: firebaseContext
 
 <!-- NOTE: Should we provide more docs? E.g. docs into various web frameworks and hosting services? -->
 For more information about using Express, see the
-[Cloud Run](/genkit/cloud-run) instructions.
+[Cloud Run](/genkit/cloud-run) instructions.

docs/index.md

@@ -4,7 +4,6 @@
   {% setvar custom_project %}/docs/genkit/_project.yaml{% endsetvar %}
   {% setvar supportsNode %}true{% endsetvar %}
   {% setvar supportsGolang %}true{% endsetvar %}
-  {% setvar youtubeID %}vZ23UxcJ7Kk{% endsetvar %}
 {% endblock variables %}
 
 {% block extraMeta %}

docs/migrating-from-0.5.md

@@ -1,4 +1,4 @@
-# Migrating from 0.5
+# Migrate from 0.5
 
 Genkit 0.9 introduces a number of breaking changes alongside feature enhancements that improve overall functionality. If you have been developing applications with Genkit 0.5, you will need to update your application code when you upgrade to the latest version. This guide outlines the most significant changes and offers steps to migrate your existing applications smoothly.
 

docs/migrating-from-0.9.md

@@ -1,21 +1,25 @@
-# Migrating from 0.9
-
-Genkit 1.0 introduces many feature enhancements that improve overall functionality as well as some breaking changes. If you have been developing applications with Genkit 0.9, you will need to update your application code when you upgrade to the latest version. This guide outlines the most significant changes and offers steps to migrate your existing applications smoothly.
-If you're using 0.5, use the [0.5 to 0.9 migration guide](https://firebase.google.com/docs/genkit/migrating-from-0.5) to upgrade to 0.9 first before upgrading to 1.0
+# Migrate from 0.9 to 1.0
 
+Genkit 1.0 introduces many feature enhancements that improve overall
+functionality; it also has some breaking changes. If you have been developing
+applications with Genkit 0.9, you need to update your application code when you
+upgrade to the latest version of Genkit. This guide outlines the most
+significant changes, and explains how to migrate your existing applications
+smoothly.
 
 ## Beta APIs
 
-We're introducing an unstable, Beta API channel, and leaving session, chat and Genkit client APIs in beta as we continue to refine them. More specifically the following functions are currently in the beta namespace:
+We're introducing an unstable, Beta API channel, and leaving session, chat and Genkit client APIs in beta as we continue to refine them. More specifically, the following functions are currently in the `beta` namespace:
 
- * `ai.chat`
- * `ai.createSession`
- * `ai.loadSession`
- * `ai.currentSession`
- * `ai.defineFormat`
- * `ai.defineInterrupt`
+* `ai.chat`
+* `ai.createSession`
+* `ai.loadSession`
+* `ai.currentSession`
+* `ai.defineFormat`
+* `ai.defineInterrupt`
 
-Note: When using the APIs as part of the Beta API, you may experience breaking changes outside of SemVer. Breaking changes may occur on minor release (we'll try to avoid making breaking beta API changes on patch releases).
+Note: When using the APIs as part of the Beta API, you may experience breaking
+changes outside of SemVer. Breaking changes may occur on minor releases.
 
 **Old:**
 
@@ -47,12 +51,12 @@ import { runFlow, streamFlow } from 'genkit/beta/client';
 
 ## Introducing new `@genkit-ai/express` package
 
-This new package contains utilities to make it easier to build an Express.js server with Genkit.
-
-Refer to https://js.api.genkit.dev/modules/_genkit-ai_express.html for more details.
-
-`startFlowServer` has moved from part of the genkit object to this new `@genkit-ai/express` package, to use startFlowServer, update your imports.
+This new package contains utilities to make it easier to build an Express.js server with Genkit. You can find more details about this on
+[this page](https://js.api.genkit.dev/modules/_genkit-ai_express.html).
 
+`startFlowServer` has moved from part of the genkit object to this new
+`@genkit-ai/express` package; to use startFlowServer, you must
+update your imports.
 
 **Old:**
 
@@ -76,15 +80,12 @@ startFlowServer({
 
 There are several changes to flows in 1.0:
 
-<ul>
-  <li>`ai.defineStreamingFlow` consilidated into `ai.defineFlow`,</li>
-  <li>`onFlow` replaced by `onCallGenkit`,</li>
-  <li>`run` moved to `ai.run`,</li>
-  <li>changes to working with auth.</li>
-</ul>
+* `ai.defineStreamingFlow` has been consolidated into `ai.defineFlow`,
+* `onFlow` has been replaced by `onCallGenkit`,
+* `run` has moved to `ai.run`,
+* There are changes to working with auth.
 
-
-The `run` function for custom trace blocks has moved to part of the `genkit` object, invoke it with `ai.run` instead
+The `run` function for custom trace blocks has moved to part of the `genkit` object; use `ai.run` to invoke it instead.
 
 **Old:**
 
@@ -106,7 +107,9 @@ ai.defineFlow({name: 'banana'}, async (input) => {
 })
 ```
 
-`ai.defineStreamingFlow` has been removed. Use `ai.defineFlow` instead. Also, `streamingCallback` moved to a field inside the second argument of he flow function and is now called `sendChunk`.
+`ai.defineStreamingFlow` has been removed; use `ai.defineFlow` instead. Also,
+`streamingCallback` has moved to a field inside the second argument of the flow
+function and is now called `sendChunk`.
 
 **Old:**
 
@@ -153,7 +156,8 @@ ai.defineFlow({name: 'banana'}, async (input, { context }) => {
 })
 ```
 
-`onFlow` moved to `firebase-functions/https` package and got renamed to `onCallGenkit`. Here's how to use it:
+`onFlow` moved to `firebase-functions/https` package and has been renamed to
+`onCallGenkit`. The following snippet shows an example of how to use it.
 
 **Old**
 
@@ -215,7 +219,8 @@ export const jokeTeller = ai.defineFlow(
 export const tellJoke = onCallGenkit({ secrets: [apiKey] }, jokeTeller);
 ```
 
-also, if you've been using auth policies, they've been removed from `defineFlow` and are now handled depending on the server you're using:
+Auth policies have been removed from `defineFlow`. Handling of auth policies
+is now server-dependent.
 
 **Old:**
 
@@ -233,7 +238,7 @@ export const simpleFlow = ai.defineFlow(
 );
 ```
 
-With express you would do something like this:
+The following snippet shows an example of handling auth in Express.
 
 **New:**
 
@@ -279,9 +284,10 @@ startFlowServer(
 );
 ```
 
-Refer to [auth documentation](https://firebase.google.com/docs/genkit/auth) for more details.
+For more details, refer to the [auth documentation](/auth).
 
-or with Cloud Functions for Firebase:
+The following snippet shows an example of handling auth in Cloud Functions
+for Firebase:
 
 ```ts
 import { genkit } from 'genkit';
@@ -311,7 +317,7 @@ You can define separate templates for prompt and system messages:
 const hello = ai.definePrompt({
   name: 'hello',
   system: 'talk like a pirate.',
-  prompt: 'hello {{ name }}',
+  prompt: 'hello {% verbatim %}{{ name }}{% endverbatim %}',
   input: {
     schema: z.object({
       name: z.string()
@@ -321,12 +327,12 @@ const hello = ai.definePrompt({
 const { text } = await hello({name: 'Genkit'});
 ```
 
-or you can define multi-message prompts in the messages field
+Alternatively, you can define multi-message prompts in the messages field:
 
 ```ts
 const hello = ai.definePrompt({
   name: 'hello',
-  messages: '{{ role "system" }} talk like a pirate. {{ role "user" }} hello {{ name }}',
+  messages: '{% verbatim %}{{ role "system" }}{% endverbatim %} talk like a pirate. {% verbatim %}{{ role "user" }}{% endverbatim %} hello {% verbatim %}{{ name }}{% endverbatim %}',
   input: {
     schema: z.object({
       name: z.string()
@@ -335,7 +341,7 @@ const hello = ai.definePrompt({
 });
 ```
 
-instead of prompt templates you can use a function
+Instead of prompt templates you can use a function:
 
 ```ts
 ai.definePrompt({
@@ -351,18 +357,18 @@ ai.definePrompt({
 });
 ```
 
-Note that you can access the context (including auth information) from within the prompt:
+You can access the context (including auth information) from within the prompt:
 
 ```ts
 const hello = ai.definePrompt({
   name: 'hello',
-  messages: 'hello {{ @auth.email }}',
+  messages: 'hello {% verbatim %}{{ @auth.email }}{% endverbatim %}',
 });
 ```
 
 
 
-## Streaming functions do not require an await
+## Streaming functions do not require an `await`
 
 
 **Old:**
@@ -383,8 +389,9 @@ const { stream, output } = myflow.stream(`hi`);
 
 ## Embed has a new return type
 
-We've added support for multimodal embeddings so now instead of returning just a single embedding vector,
-we return an array of embedding objects, each containing an embedding vector and metadata.
+We've added support for multimodal embeddings. Instead of returning just a
+single embedding vector, Embed returns an array of embedding objects, each
+containing an embedding vector and metadata.
 
 **Old:**
 
@@ -397,5 +404,4 @@ const response = await ai.embed({embedder, content, options});  // returns numbe
 ```ts
 const response = await ai.embed({embedder, content, options}); // returns Embedding[]
 const firstEmbeddingVector = response[0].embedding;  // is number[]
-```
-
+```