chore: improve Ory CLI usage in auth guide (#1918)

docs/getting-started/_common/ory-cli.mdx

@@ -1,24 +1,64 @@
-Ory CLI provides a convenient way to configure and manage projects. Additionally, the CLI contains Ory Proxy - a reverse proxy
-that rewrites cookies to match the domain your application is currently on.
+The Ory security model uses HTTP cookies to manage sessions, tokens, and cookies. Because of browser security measures like
+[CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS), Ory APIs must be exposed on the same domain as your application.
 
-Ory Proxy is a reverse proxy deployed in front of your application. The Proxy mirrors Ory endpoints on the same domain as the
-application you're running and rewrites cookies to match the domain your application is currently on.
+In the case of this example the application runs on your local machine. The cookie domain is `localhost`.
 
-As a result, the origin of the cookies is set correctly to the domain you run the app on instead of <br />
+:::info
 
-```
-<your-project-slug>.projects.oryapis.com
-```
+When developing locally, use either `localhost` or `127.0.0.1`, but not both. Although technically these mean the same thing,
+they're different cookie domains.
+
+Using both interchangeably in your code causes problems, as Ory APIs will not receive the cookies when they are set on a different
+domain.
+
+:::
 
-This behavior is necessary to avoid issues with the browser [CORS policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS).
+<p>
+  Ory CLI provides a convenient way to configure and manage projects. Additionally, the CLI provides Ory{" "}
+  {props.isTunnel ? "Tunnel" : "Proxy"} - a reverse proxy that rewrites cookies to match the domain your application is currently
+  on.
+</p>
 
-By using the Proxy, you can easily connect the application you're developing locally to Ory Network and consume the APIs without
-additional configuration or the self-hosting any Ory services.
+<p>
+  To make Ory APIs and your application available on the same domain, Ory {props.isTunnel ? "Tunnel" : "Proxy"} mirrors Ory
+  endpoints and rewrites cookies to match the domain correct domain.
+</p>
 
-[![Ory Proxy mirrors Ory's APIs](https://mermaid.ink/img/pako:eNptkMFKxEAMhl8l5GIXdm1BT3MQWlxEEBxWL8JchjbaYqcZMlO0bPfdna71sGBOP-H7EpIj1twQKvwQ61t4OpgBUlVZJfwVSDaw293ND_tXaGP0Ks97rm3fcojqtiiKGXT2LBNo4e9p8-vqs-I6EZYANkJ-zTLlM5T6cYGvwpLCBf3vgpvzgjJ741Gg9H41ykU4UPA8BJr1OuaiWeEWHYmzXZNOOy6IwdiSI4MqxcbKp0EznBI3-sZG2jddZEH1bvtAW7Rj5JdpqFFFGekPuu9sepNbqdMP2FdlPQ)](https://mermaid-js.github.io/mermaid-live-editor/edit#pako:eNptkMFKxEAMhl8l5GIXdm1BT3MQWlxEEBxWL8JchjbaYqcZMlO0bPfdna71sGBOP-H7EpIj1twQKvwQ61t4OpgBUlVZJfwVSDaw293ND_tXaGP0Ks97rm3fcojqtiiKGXT2LBNo4e9p8-vqs-I6EZYANkJ-zTLlM5T6cYGvwpLCBf3vgpvzgjJ741Gg9H41ykU4UPA8BJr1OuaiWeEWHYmzXZNOOy6IwdiSI4MqxcbKp0EznBI3-sZG2jddZEH1bvtAW7Rj5JdpqFFFGekPuu9sepNbqdMP2FdlPQ)
+As a result, the domain of the cookies is set correctly to the domain you run the app on instead of
+`<your-project-slug>.projects.oryapis.com`.
+
+<p>
+  By using the {props.isTunnel ? "Tunnel" : "Proxy"}, you can easily connect the application you're developing locally to Ory
+  Network and consume the APIs without additional configuration or the self-hosting any Ory services.
+</p>
+
+```mdx-code-block
+import Mermaid from "@site/src/theme/Mermaid"
+
+<Mermaid
+  chart={props.isTunnel ?
+`graph LR
+    B(Browser) -->|GET http://localhost:4000| T(Ory Tunnel)
+    T -->|Response| B
+    T <-->|mirrors| API(Ory's APIs)
+    B -->|GET http://localhost:3000| A(Your App)
+    A-->|Response|B
+` :
+`graph LR
+    B(Browser) -->|GET http://localhost:4000| P(Ory Proxy)
+    P <-->|mirrors at /.ory/| API(Ory's APIs)
+    P -->|GET http://localhost:3000| A(Your App)
+    A-->|Response|P
+    P-->|Response|B
+`}
+/>
+```
 
 :::tip
 
-To learn more about the Ory Proxy, read the [dedicated section of the Ory CLI documentation](../../guides/cli/proxy-and-tunnel).
+<p>
+  To learn more about the Ory {props.isTunnel ? "Tunnel" : "Proxy"}, read the [dedicated section of the Ory CLI
+  documentation](../../guides/cli/proxy-and-tunnel).
+</p>
 
 :::

docs/getting-started/integrate-auth/01_go.mdx

@@ -23,7 +23,7 @@ import { useLatestTag } from '@site/src/hooks'
 
 First, create a Go app. Run these commands:
 
-```shell-session
+```shell
 mkdir your-project
 cd your-project
 
@@ -43,7 +43,7 @@ Run this command to install the Ory SDK which allows you to interact with Ory AP
 
 Follow [this guide](../../guides/cli/01_installation.mdx) to install the Ory CLI on your machine.
 
-### Why do I Need the Ory CLI?
+### Why do I need the Ory CLI
 
 ```mdx-code-block
 import OryCLI from '../_common/ory-cli.mdx'
@@ -100,8 +100,8 @@ With all of the pieces in place, it's time to test your application. Follow thes
 
 1. Start your Go app:
 
-```shell-session
- go run .
+```shell
+go run .
 ```
 
 2. Export the SDK configuration URL for the desired Ory project. You can use the provided playground project for testing, or
@@ -119,9 +119,10 @@ import SdkEnvVar from '@site/src/components/SdkEnvVar'
 <SdkEnvVar />
 ```
 
-3. Run the Ory proxy to mirror the Ory API endpoints on your application's domain (`localhost`):
+3. Run the Ory proxy to mirror the Ory API endpoints on your application's domain (`localhost`). Upon first start, the Ory Proxy
+   will ask you to log into your Ory Console account.
 
-```shell-session
+```shell
 ory proxy http://localhost:3000
 ```
 

docs/getting-started/integrate-auth/05_php.mdx

@@ -20,7 +20,7 @@ import webm from '../_static/php/screencast.webm'
 
 First we create a new PHP project:
 
-```shell-session
+```shell
 mkdir your-project
 cd your-project
 touch index.php
@@ -30,19 +30,19 @@ touch index.php
 
 To interact with Ory's APIs we install the [Ory SDK](https://packagist.org/packages/ory/client):
 
-```shell-session
+```shell
 composer require ory/client
 ```
 
 To simplify URLs handling we install the [bramus/router](https://packagist.org/packages/bramus/router)
 
-```shell-session
+```shell
 composer require bramus/router
 ```
 
 To install Ory CLI follow [this guide](https://www.ory.sh/docs/guides/ory-cli-install-use)
 
-### Why do I Need the Ory CLI?
+### Why do I need the Ory CLI
 
 ```mdx-code-block
 import OryCLI from '../_common/ory-cli.mdx'
@@ -86,7 +86,7 @@ import appPHP from '!!raw-loader!../../../code-examples/protect-page-login/php/a
 
 Start your HTTP server and access the proxy URL
 
-```shell-session
+```shell
 php -S 127.0.0.1:3000
 ```
 
@@ -96,7 +96,10 @@ import SdkEnvVar from '@site/src/components/SdkEnvVar'
 <SdkEnvVar />
 ```
 
-```shell-session
+Next open a new terminal window and start the Ory Proxy. Upon first start, the Ory Proxy will ask you to log into your Ory Console
+account.
+
+```shell
 ory proxy http://localhost:3000
 ```
 

docs/getting-started/integrate-auth/10_expressjs.mdx

@@ -20,31 +20,23 @@ import webm from '../_static/expressjs/screencast.webm'
 
 First we create a new Express.js project:
 
-```shell-session
+```shell
 mkdir your-project
 cd your-project
 
 npx express-generator
 npm i
 ```
 
-## Install Ory SDK
-
-To interact with Ory's APIs we install the Ory SDK:
-
-```shell-session
-npm i --save @ory/client
-```
+## Install Ory SDK and CLI
 
-## Install Ory CLI
-
-The last step is setting up the Ory CLI.
+To interact with Ory's APIs we install the Ory SDK and CLI:
 
 ```shell
-npm i --save @ory/cli
+npm i --save @ory/client @ory/cli
 ```
 
-### Why do I Need the Ory CLI?
+### Why do I need the Ory CLI
 
 ```mdx-code-block
 import OryCLI from '../_common/ory-cli.mdx'
@@ -68,8 +60,8 @@ Now that the Ory CLI is installed, let's add it as a `npm run` script to our pro
   "dependencies": {
 ```
 
-This requires the express app (`npm run start`) to run on port 3000. The browser / user uses however the port 4000
-([http://localhost:4000](http://localhost:4000)) to access the app.
+This requires the express app (`npm run start`) to run on port 3000. However, the app has to be accessed through the port 4000
+([http://localhost:4000](http://localhost:4000)).
 
 ## Require login to access the home page
 
@@ -87,7 +79,7 @@ import CodeBlock from '@theme/CodeBlock'
 
 Great, that's it. Let's run your application. Start the Express.js server
 
-```shell-session
+```shell
 npm run start
 ```
 
@@ -99,9 +91,10 @@ import SdkEnvVar from '@site/src/components/SdkEnvVar'
 <SdkEnvVar />
 ```
 
-Next open a new terminal window and start the Ory Proxy:
+Next open a new terminal window and start the Ory Proxy. Upon first start, the Ory Proxy will ask you to log into your Ory Console
+account.
 
-```shell-session
+```shell
 npm run proxy
 ```
 
@@ -116,7 +109,7 @@ import ToProd from '../_common/going-to-prod.mdx'
 <ToProd />
 ```
 
-```js {2,4-7}
+```js
 var sdk = require("@ory/client")
 
 var ory = new sdk.FrontendApi(