vikhyat · Aug 3, 2026 · Aug 3, 2026 · Aug 3, 2026 · Aug 3, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -6,21 +6,21 @@ The site is a Docusaurus 3 project. Keep docs-focused updates in `docs/`, groupe
 
 ## Build, Test, and Development Commands
 
-- `yarn install`: install Node dependencies; rerun when packages change.
-- `yarn start`: launch the dev server with hot reload on <http://localhost:3000/>.
-- `yarn build`: produce the production bundle in `build/`; run before merging structural or styling changes.
-- `yarn serve`: preview the latest `build/` output locally.
-- `yarn typecheck`: run the TypeScript compiler against MDX/TS sources to catch broken imports or props.
-- `yarn deploy`: publish the generated site to GitHub Pages; ensure `docusaurus.config.ts` URLs are correct first.
+- `npm ci`: install the exact dependencies in `package-lock.json`.
+- `npm start`: launch the dev server with hot reload on <http://localhost:3005/>.
+- `npm run build`: produce the production bundle in `build/`; run before merging structural or styling changes.
+- `npm run serve`: preview the latest `build/` output locally.
+- `npm run typecheck`: run the TypeScript compiler against MDX/TS sources to catch broken imports or props.
+- `npm run deploy`: publish the generated site to GitHub Pages; ensure `docusaurus.config.ts` URLs are correct first.
 
 ## Coding Style & Naming Conventions
 
 Use TypeScript and React 19 idioms: functional components, hooks, and PascalCase filenames in `src/components/`. Keep MDX headings sentence-cased and include concise intro paragraphs for placement in search. Favor 2-space indentation (default Prettier formatting) and wrap lines around 100 characters for readability. Import paths should be relative to the file unless a Docusaurus alias already exists. When adding CSS, extend selectors under `:root` tokens instead of overriding colors inline.
 
 ## Testing Guidelines
 
-Run `yarn typecheck` before every PR and ensure `yarn build` completes cleanly; both catch most configuration regressions. For new or reorganized docs, confirm sidebar ordering locally and click through new links in `yarn start`. If you embed live code blocks, preview them in both light and dark mode. When adding interactive React components, prefer colocated unit tests beneath the component (e.g., `Example.test.tsx`) and ensure they execute via `yarn typecheck` or in a dedicated script before merging.
+Run `npm run typecheck` before every PR and ensure `npm run build` completes cleanly; both catch most configuration regressions. For new or reorganized docs, confirm sidebar ordering locally and click through new links in `npm start`. If you embed live code blocks, preview them in both light and dark mode. When adding interactive React components, prefer colocated unit tests beneath the component (e.g., `Example.test.tsx`) and ensure they execute via `npm run typecheck` or in a dedicated script before merging.
 
 ## Commit & Pull Request Guidelines
 
-Follow the existing history: short, imperative summaries (e.g., “add quickstart note”). Reference related issues in the body when applicable and note any screenshot-worthy visual changes. Each PR description should list: purpose, key file touchpoints, validation steps (`yarn typecheck`, `yarn build`), and deployment impact. Request review from a docs maintainer when navigation or config files change, and include before/after screenshots for styling tweaks.
+Follow the existing history: short, imperative summaries (e.g., “add quickstart note”). Reference related issues in the body when applicable and note any screenshot-worthy visual changes. Each PR description should list: purpose, key file touchpoints, validation steps (`npm run typecheck`, `npm run build`), and deployment impact. Request review from a docs maintainer when navigation or config files change, and include before/after screenshots for styling tweaks.
diff --git a/README.md b/README.md
@@ -1,98 +1,23 @@
-# Website
+# Moondream Docs
 
-This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+Source for [docs.moondream.ai](https://docs.moondream.ai), built with
+[Docusaurus](https://docusaurus.io/).
 
-## Installation
+## Local development
 
 ```bash
-yarn
+npm ci
+npm start
 ```
 
-## Local Development
+The development server runs at `http://localhost:3005`.
 
-```bash
-yarn start
-```
-
-This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
-
-## Build
-
-```bash
-yarn build
-```
-
-This command generates static content into the `build` directory and can be served using any static contents hosting service.
-
-## Deployment
-
-Using SSH:
-
-```bash
-USE_SSH=true yarn deploy
-```
-
-Not using SSH:
+## Validation
 
 ```bash
-GIT_USER=<Your GitHub username> yarn deploy
+npm run typecheck
+npm run build
 ```
 
-If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
-
-## Modifying the content
-To add a doc, simply create a .md file inside the docs folder and add the content you want. It will automatically be compiled and added to the website.
-
-To add a category/folder, it's the same process. Create the folder inside docs and it will add it automatically.
-
-For code documentation, here is an example of adding code to the markdown:
-
-# Code Block Examples
-
-### Code Tabs
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
-<Tabs>
-  <TabItem value="js" label="JavaScript" default>
-
-  ```javascript
-  const greeting = "Hello, World!";
-  console.log(greeting);
-  ```
-
-  </TabItem>
-  <TabItem value="py" label="Python">
-
-  ```python
-  greeting = "Hello, World!"
-  print(greeting)
-  ```
-
-  </TabItem>
-  <TabItem value="java" label="Java">
-
-  ```java
-  public class HelloWorld {
-      public static void main(String[] args) {
-          System.out.println("Hello, World!");
-      }
-  }
-  ```
-
-  </TabItem>
-</Tabs>
-
-### Standard
-
-```python
-greeting = "Hello, World!"
-print(greeting)
-```
-
-### Modifying aesthetics
-In order to change the look of the website, you can adjust the themes inside docusaurus.config.ts or you can modify CSS inside custom.css. Docusaurus uses custom flags that can be identified from the inspect menu, in order to properly change the colors. 
-
-### Modifying the URL
-If you change the URL of the site, make sure to update docusaurus.config.ts (both url and BaseURL) to match it. It needs to be the correct URL in order to build properly.
+Merges to `main` deploy through the GitHub Pages workflow in
+[`.github/workflows/deploy.yml`](.github/workflows/deploy.yml).
diff --git a/docs/batch.md b/docs/batch.md
@@ -58,23 +58,23 @@ import TabItem from '@theme/TabItem';
 INIT=$(curl -s -X POST "https://api.moondream.ai/v1/batch?action=mpu-create" \
   -H "X-Moondream-Auth: YOUR_API_KEY")
 
-FILE_ID=$(echo $INIT | jq -r '.fileId')
-UPLOAD_ID=$(echo $INIT | jq -r '.uploadId')
+FILE_ID=$(echo "$INIT" | jq -r '.fileId')
+UPLOAD_ID=$(echo "$INIT" | jq -r '.uploadId')
 
 # Step 2: Split file into 50MB chunks and upload each part
 CHUNK_SIZE=$((50 * 1024 * 1024))
-split -b $CHUNK_SIZE batch_input.jsonl chunk_
+split -b "$CHUNK_SIZE" batch_input.jsonl chunk_
 
 PARTS="[]"
 PART_NUM=1
 for CHUNK in chunk_*; do
   PART=$(curl -s -X PUT "https://api.moondream.ai/v1/batch/$FILE_ID?action=mpu-uploadpart&uploadId=$UPLOAD_ID&partNumber=$PART_NUM" \
     -H "X-Moondream-Auth: YOUR_API_KEY" \
     -H "Content-Type: application/octet-stream" \
-    --data-binary @$CHUNK)
-  ETAG=$(echo $PART | jq -r '.etag')
-  PARTS=$(echo $PARTS | jq ". + [{\"partNumber\": $PART_NUM, \"etag\": \"$ETAG\"}]")
-  rm $CHUNK
+    --data-binary "@$CHUNK")
+  ETAG=$(echo "$PART" | jq -r '.etag')
+  PARTS=$(echo "$PARTS" | jq ". + [{\"partNumber\": $PART_NUM, \"etag\": \"$ETAG\"}]")
+  rm -- "$CHUNK"
   PART_NUM=$((PART_NUM + 1))
 done
 
@@ -84,7 +84,7 @@ BATCH=$(curl -s -X POST "https://api.moondream.ai/v1/batch/$FILE_ID?action=mpu-c
   -H "Content-Type: application/json" \
   -d "{\"parts\": $PARTS, \"model\": \"moondream3.1-9B-A2B\"}")
 
-BATCH_ID=$(echo $BATCH | jq -r '.id')
+BATCH_ID=$(echo "$BATCH" | jq -r '.id')
 echo "Batch submitted: $BATCH_ID"
 ```
 

diff --git a/docs/finetuning/python-sdk.mdx b/docs/finetuning/python-sdk.mdx
@@ -85,15 +85,15 @@ Returns a dict:
 
 ```python
 {
-    "request": { ... },      # Pass back to train_step unchanged
+    "request": {"...": "..."},  # Pass back to train_step unchanged
     "rollouts": [
         {
             "skill": "query",
             "output": {"answer": "red"},
-            ...                # Opaque training metadata
+            "...": "...",          # Opaque training metadata
         }
     ],
-    "rewards": [0.8, ...]    # Present if ground_truth was provided, otherwise null
+    "rewards": [0.8],             # Present only with ground_truth
 }
 ```
 
@@ -240,7 +240,7 @@ ft.train_step([{
 Point targets can also use bounding boxes:
 
 ```python
-"target": {"boxes": [{"x_min": 0.45, "y_min": 0.22, "x_max": 0.58, "y_max": 0.39}]}
+target = {"boxes": [{"x_min": 0.45, "y_min": 0.22, "x_max": 0.58, "y_max": 0.39}]}
 ```
 
 **Detect:**

diff --git a/docs/overview.md b/docs/overview.md
@@ -6,9 +6,11 @@ title: "Overview"
 
 # Overview
 
-Moondream is an open-source family of Vision Language Models (VLMs) built for powerful, efficient visual reasoning. Our newest release, Moondream 3 Preview, is a mixture-of-experts model with grounded visual reasoning, a 32k context window, and native support for multiple vision skills—like pointing, counting, and object detection—all designed with a deployment-friendly ethos.
+Moondream is an open-weight family of Vision Language Models (VLMs) built for powerful, efficient visual reasoning. The Moondream 3 family uses a mixture-of-experts architecture with grounded visual reasoning, a 32k context window, and native support for multiple vision skills—like pointing, counting, and object detection—all designed with a deployment-friendly ethos.
 
-Moondream 3 Preview is now the default model for our cloud API and local processing with [Photon](/running-locally) – [get started here](./quickstart).
+Moondream 3 Preview remains the default for local inference with
+[Photon](/running-locally). For hosted inference, choose a model through the
+[Cloud API quickstart](./quickstart).
 
 ### Key stats
 
@@ -23,10 +25,13 @@ Moondream has built-in vision-specific skills that make it easy to generate spec
 - Pointing and Counting
 - Visual Question Answering
 - Captioning
+- Image Segmentation
 
 ### Performance Benchmarks
 
-Here are some early benchmark results. We show it alongside some top frontier models for comparison. Moondream also produces answers in fraction of the time of these bigger models. We'll publish more complete results later and include inference times to make this clearer.
+Selected benchmark results are shown alongside larger frontier models for
+comparison. Moondream is designed to produce strong results with substantially
+lower inference cost.
 
 | Task | Moondream 3 Preview | GPT 5 | Gemini 2.5-Flash | Claude 4 Sonnet |
 |------|---------------------|-------|------------------|-----------------|

diff --git a/docs/pricing.md b/docs/pricing.md
@@ -44,4 +44,4 @@ Create an account and launch requests immediately (no sales conversations requir
 
 ## Enterprise plan
 
-Need a higher-volume contract, on-prem deployment, or tailored consulting support? Our enterprise plan covers bespoke requirements with dedicated technical guidance. Contact sales at [sales@moondream.ai](mailto:sales@moondream.ai) or [schedule a call](https://cal.com/moondream-sales) to scope a solution with our team.
+Need a higher-volume contract, on-prem deployment, or tailored consulting support? Our enterprise plan covers bespoke requirements with dedicated technical guidance. Contact sales at [sales@moondream.ai](mailto:sales@moondream.ai) or [schedule a call](https://cal.com/moondream) to scope a solution with our team.
diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -3,7 +3,7 @@ sidebar_position: 2
 title: "Getting Started"
 ---
 
-Moondream is a powerful, fast, and efficient vision AI model. It can answer questions, detect objects, count and point, caption, perform OCR, and more.  Grab an API key at the [Moondream Cloud Console](https://moondream.ai/c/cloud/api-keys) and try it out!
+Moondream is a powerful, fast, and efficient vision AI model. It can answer questions, detect objects, count and point, caption, perform OCR, and more. Grab an API key at the [Moondream Cloud Console](https://moondream.ai/c/cloud/api-keys) and try it out.
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
@@ -347,5 +347,5 @@ Want to run Moondream on your own hardware instead of using the Cloud API? Check
 ## Next Steps
 
 - **Try it live**: Use our [interactive playground](https://moondream.ai/c/playground) to test without coding
-- **Deep dive**: Explore detailed documentation for each skill - [Query](/skills/query), [Detect](/skills/detect), [Point](/skills/point), [Caption](/skills/caption)
+- **Deep dive**: Explore detailed documentation for each skill: [Query](/skills/query), [Detect](/skills/detect), [Point](/skills/point), [Caption](/skills/caption), [Segment](/skills/segment)
 - **More capabilities**: Check out all [Moondream Skills](/skills/)
diff --git a/docs/rate-limits.md b/docs/rate-limits.md
@@ -10,5 +10,4 @@ import RateLimitsTable from '@site/src/components/RateLimitsTable';
 
 ## Need Higher Limits?
 
-We can accommodate much higher rate limits for production workloads and enterprise use cases. Contact sales at [sales@moondream.ai](mailto:sales@moondream.ai) or [schedule a call](https://cal.com/moondream-sales) to discuss your requirements.
-
+We can accommodate much higher rate limits for production workloads and enterprise use cases. Contact sales at [sales@moondream.ai](mailto:sales@moondream.ai) or [schedule a call](https://cal.com/moondream) to discuss your requirements.
diff --git a/docs/reasoning.md b/docs/reasoning.md
@@ -22,7 +22,9 @@ Enable Moondream's reasoning capabilities to improve result quality for complex
 - **High accuracy requirements**: When you need the most accurate possible answer
 
 ### Trade-offs
-- **Speed**: Reasoning adds minor latency to requests (typically 10-20% longer)
+- **Speed and output length**: Reasoning generates an explicit analysis before
+  the answer, so it can materially increase latency and generated tokens. Measure
+  it with prompts representative of your workload.
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
@@ -48,6 +50,7 @@ image = Image.open("path/to/image.jpg")
 
 # Query with reasoning enabled
 result = model.query(image, "What is in this image?", reasoning=True)
+print(result["reasoning"])
 print(result["answer"])
 ```
 
@@ -72,6 +75,7 @@ const result = await model.query({
   question: 'What is in this image?',
   reasoning: true
 });
+console.log(result.reasoning);
 console.log(result.answer);
 ```
Original file line number	Diff line number	Diff line change
Expand Up		@@ -44,4 +44,4 @@ Create an account and launch requests immediately (no sales conversations requir

		## Enterprise plan

		Need a higher-volume contract, on-prem deployment, or tailored consulting support? Our enterprise plan covers bespoke requirements with dedicated technical guidance. Contact sales at [sales@moondream.ai](mailto:sales@moondream.ai) or [schedule a call](https://cal.com/moondream-sales) to scope a solution with our team.
		Need a higher-volume contract, on-prem deployment, or tailored consulting support? Our enterprise plan covers bespoke requirements with dedicated technical guidance. Contact sales at [sales@moondream.ai](mailto:sales@moondream.ai) or [schedule a call](https://cal.com/moondream) to scope a solution with our team.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -10,5 +10,4 @@ import RateLimitsTable from '@site/src/components/RateLimitsTable';

		## Need Higher Limits?

		We can accommodate much higher rate limits for production workloads and enterprise use cases. Contact sales at [sales@moondream.ai](mailto:sales@moondream.ai) or [schedule a call](https://cal.com/moondream-sales) to discuss your requirements.

		We can accommodate much higher rate limits for production workloads and enterprise use cases. Contact sales at [sales@moondream.ai](mailto:sales@moondream.ai) or [schedule a call](https://cal.com/moondream) to discuss your requirements.