doc: add Modus / Run Locally

.trunk/trunk.yaml

@@ -18,7 +18,7 @@ runtimes:
 
 lint:
   enabled:
-    - renovate@39.164.1
+    - renovate@39.166.1
     - [email protected]
     - [email protected]
     - [email protected]
@@ -31,7 +31,7 @@ lint:
           - "@mintlify/[email protected]"
     - [email protected]
     - [email protected]
-    - [email protected].5
+    - [email protected].6
     - [email protected]
   ignore:
     - linters: [ALL]

mint.json

@@ -130,7 +130,8 @@
         "modus/search",
         "modus/api-generation",
         "modus/authentication",
-        "modus/error-handling"
+        "modus/error-handling",
+        "modus/run-locally"
       ]
     },
     {

modus/app-manifest.mdx

@@ -121,7 +121,7 @@ If your connection requires authentication, you can include _placeholders_ in
 connection properties which resolve to their respective secrets at runtime.
 
 When developing locally,
-[set secrets using environment variables](#working-locally-with-secrets).
+[set secrets using environment variables](/modus/run-locally#environment-secrets).
 
 When deployed on Hypermode, set the actual secrets via the Hypermode Console,
 where they're securely stored until needed.
@@ -419,48 +419,10 @@ For example, if using Neon, refer to the
 
 </ResponseField>
 
-### Working locally with secrets
-
-When you run your app locally using `modus dev`, the runtime replaces the
-placeholders of the manifest with values from environment variables defined in
-your operating system or in `.env` files.
-
-The environment variables keys must be upper case and follow the naming
-convention:
-
-`MODUS_<CONNECTION NAME>_<PLACEHOLDER>`
-
-For example, with the following manifest:
-
-```json modus.json
-{
-  "connections": {
-    "openai": {
-      "type": "http",
-      "baseUrl": "https://api.openai.com/",
-      "headers": {
-        "Authorization": "Bearer {{API_KEY}}"
-      }
-    }
-  }
-}
-```
-
-The Modus runtime substitutes `{{API_KEY}}` with the value of the environment
-variable `MODUS_OPENAI_API_KEY`
-
-An easy way to define the environment variables when working locally is to use
-the file `.env.dev.local` located in your app folder.
-
-For the previous manifest, we can set the key in the .env.dev.local file as
-follow:
-
-```text .env.dev.local
-MODUS_OPENAI_API_KEY="your openai key"
-```
-
-You should exclude `.env` files from source control. Projects created with
-`modus new` exclude these files automatically when creating your project.
+<Tip>
+  See [Running locally with secrets](/modus/run-locally#environment-secrets) for
+  more details on how to set secrets for local development.
+</Tip>
 
 ## Models
 

modus/run-locally.mdx

@@ -0,0 +1,109 @@
+---
+title: Run Locally
+description: "Test your Modus app and iterate quickly"
+"og:title": "Run Locally - Modus"
+---
+
+Modus provides a local development environment that makes it easy to build and
+test your app, with local access to models.
+
+## Launching your app in development mode
+
+To run your app, from the project root, run:
+
+```bash
+modus dev
+```
+
+The `modus dev` command compiles your app code, starts a local server, and
+provides a URL to access your app's API. It also enables fast refresh, which
+automatically recompiles and reloads any changed functions while preserving app
+state during development.
+
+Once your app is running, you can access the graphical interface for your API at
+the URL located in your terminal.
+
+```bash
+View endpoint: http://localhost:8686/explorer
+```
+
+The API Explorer interface allows you to interact with your app's API and test
+your functions.
+
+<img
+  className="block"
+  src="../images/api-explorer.png"
+  alt="API Graphical Interface."
+/>
+
+## Environment secrets
+
+When you run your app locally using `modus dev`, the runtime replaces the
+placeholders of the manifest with values from environment variables defined in
+your operating system or in `.env` files.
+
+The environment variables keys must be upper case and follow the naming
+convention:
+
+`MODUS_<CONNECTION NAME>_<PLACEHOLDER>`
+
+For example, with the following manifest:
+
+```json modus.json
+{
+  "connections": {
+    "openai": {
+      "type": "http",
+      "baseUrl": "https://api.openai.com/",
+      "headers": {
+        "Authorization": "Bearer {{API_KEY}}"
+      }
+    }
+  }
+}
+```
+
+The Modus runtime substitutes `{{API_KEY}}` with the value of the environment
+variable `MODUS_OPENAI_API_KEY`
+
+An easy way to define the environment variables when working locally is to use
+the file `.env.dev.local` located in your app folder.
+
+For the previous manifest, we can set the key in the .env.dev.local file as
+follow:
+
+```text .env.dev.local
+MODUS_OPENAI_API_KEY="your openai key"
+```
+
+<Warning>
+  You should exclude `.env` files from source control. Projects created with
+  `modus new` exclude these files automatically when creating your project.
+</Warning>
+
+## Using Hypermode-hosted models
+
+To use Hypermode-hosted models in your local environment, first install the Hyp
+CLI:
+
+```bash
+npm install -g @hypermode/hyp-cli
+```
+
+Then log in to your Hypermode account:
+
+```bash
+hyp login
+```
+
+After logging in, your app automatically connects to Hypermode-hosted models
+when running locally. For more information on the models available to use, see
+[hosted shared models](/hosted-models#shared-models).
+
+## Working with Collections
+
+Collections requires a PostgreSQL instance for local development. While
+Hypermode manages this database in production, you'll need to set up PostgreSQL
+locally when developing outside the Hypermode platform. For detailed setup
+instructions, see
+[Develop locally with Collections](/modus/search#develop-locally-with-collections).

styles/config/vocabularies/general/accept.txt

@@ -68,6 +68,7 @@ NPM|npm
 NQuads|nquads
 PostgreSQL|postgresql
 PUT
+recompiles
 repo
 RDF
 REST|[Rr]est