feat: Add a quickstart tutorial, update existing documentation content, and modify VitePress configuration and logo.

Author: aminembarki

.vitepress/config.ts

@@ -135,9 +135,10 @@ export default defineConfig({
 
     sidebar: [
       {
-        text: 'Introduction',
+        text: 'Getting Started',
         items: [
           { text: 'Overview', link: '/docs/' },
+          { text: 'Quick Start Tutorial', link: '/docs/quickstart-tutorial' },
           { text: 'Apify SDK Environment', link: '/docs/apify-sdk-environment' },
         ],
       },

src/docs/api.md

@@ -17,6 +17,8 @@ curl -H "Authorization: Bearer YOUR_TOKEN" \
   https://your-server.com/v2/datasets
 ```
 
+All resource endpoints are user-scoped — authenticated users can only access their own resources.
+
 ---
 
 ## Datasets
@@ -42,6 +44,15 @@ curl -X POST \
   https://your-server.com/v2/datasets/{id}/items
 ```
 
+### Retrieve Items
+
+Supports pagination with `offset` and `limit` query parameters (max limit: 1000).
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  "https://your-server.com/v2/datasets/{id}/items?offset=0&limit=100"
+```
+
 ---
 
 ## Key-Value Stores
@@ -53,6 +64,7 @@ Store arbitrary data by key.
 | `GET`    | `/v2/key-value-stores`                    | List all stores    |
 | `POST`   | `/v2/key-value-stores`                    | Create a new store |
 | `GET`    | `/v2/key-value-stores/{id}`               | Get store details  |
+| `DELETE` | `/v2/key-value-stores/{id}`               | Delete a store     |
 | `PUT`    | `/v2/key-value-stores/{id}/records/{key}` | Set a record       |
 | `GET`    | `/v2/key-value-stores/{id}/records/{key}` | Get a record       |
 | `DELETE` | `/v2/key-value-stores/{id}/records/{key}` | Delete a record    |
@@ -68,19 +80,33 @@ Store arbitrary data by key.
 
 Manage URLs to crawl with automatic deduplication.
 
-| Method   | Endpoint                                            | Description             |
-| -------- | --------------------------------------------------- | ----------------------- |
-| `GET`    | `/v2/request-queues`                                | List all queues         |
-| `POST`   | `/v2/request-queues`                                | Create a new queue      |
-| `POST`   | `/v2/request-queues/{id}/requests`                  | Add requests to queue   |
-| `POST`   | `/v2/request-queues/{id}/head/lock`                 | Lock and fetch requests |
-| `DELETE` | `/v2/request-queues/{id}/requests/{requestId}/lock` | Release a lock          |
-| `PUT`    | `/v2/request-queues/{id}/requests/{requestId}`      | Update request status   |
+| Method   | Endpoint                                            | Description              |
+| -------- | --------------------------------------------------- | ------------------------ |
+| `GET`    | `/v2/request-queues`                                | List all queues          |
+| `POST`   | `/v2/request-queues`                                | Create a new queue       |
+| `GET`    | `/v2/request-queues/{id}`                           | Get queue details        |
+| `DELETE` | `/v2/request-queues/{id}`                           | Delete a queue           |
+| `GET`    | `/v2/request-queues/{id}/head`                      | Get next pending requests |
+| `POST`   | `/v2/request-queues/{id}/head/lock`                 | Lock and fetch requests  |
+| `POST`   | `/v2/request-queues/{id}/requests`                  | Add request to queue     |
+| `POST`   | `/v2/request-queues/{id}/requests/batch`            | Batch add requests       |
+| `GET`    | `/v2/request-queues/{id}/requests/{requestId}`      | Get request details      |
+| `PUT`    | `/v2/request-queues/{id}/requests/{requestId}`      | Update request status    |
+| `PUT`    | `/v2/request-queues/{id}/requests/{requestId}/lock` | Prolong request lock     |
+| `DELETE` | `/v2/request-queues/{id}/requests/{requestId}/lock` | Release a lock           |
 
 ### Deduplication
 
 Requests are deduplicated by `uniqueKey`. Adding a request with an existing `uniqueKey` is a no-op.
 
+### Locking
+
+The lock endpoint (`POST .../head/lock`) supports distributed crawling. Parameters:
+
+- `lockSecs` — Lock duration in seconds (max 86400)
+- `limit` — Number of requests to fetch (max 1000)
+- `clientKey` — Unique identifier for the crawling client
+
 ---
 
 ## Actors
@@ -96,18 +122,31 @@ Manage Actor definitions.
 | `DELETE` | `/v2/acts/{id}`      | Delete an Actor   |
 | `POST`   | `/v2/acts/{id}/runs` | Start a new run   |
 
+### Input Validation
+
+Actor create/update bodies are validated with the following constraints:
+
+- `name` — 1-100 chars, alphanumeric with dots, dashes, underscores
+- `timeout` — Max 86400 seconds (24h)
+- `memory` — Max 16384 MB (16 GB)
+
 ---
 
 ## Runs
 
 Monitor Actor executions.
 
-| Method | Endpoint                    | Description           |
-| ------ | --------------------------- | --------------------- |
-| `GET`  | `/v2/actor-runs`            | List all runs         |
-| `GET`  | `/v2/actor-runs/{id}`       | Get run status        |
-| `POST` | `/v2/actor-runs/{id}/abort` | Abort a running Actor |
-| `GET`  | `/v2/actor-runs/{id}/log`   | Get run logs          |
+| Method | Endpoint                                                  | Description                     |
+| ------ | --------------------------------------------------------- | ------------------------------- |
+| `GET`  | `/v2/actor-runs`                                          | List all runs                   |
+| `GET`  | `/v2/actor-runs/{id}`                                     | Get run status                  |
+| `PUT`  | `/v2/actor-runs/{id}`                                     | Update run status               |
+| `POST` | `/v2/actor-runs/{id}/abort`                               | Abort a running Actor           |
+| `POST` | `/v2/actor-runs/{id}/resurrect`                           | Resurrect a failed run          |
+| `GET`  | `/v2/actor-runs/{id}/logs`                                | Get run logs                    |
+| `POST` | `/v2/actor-runs/{id}/logs`                                | Append log entry                |
+| `GET`  | `/v2/actor-runs/{id}/dataset/items`                       | Get run's dataset items         |
+| `GET`  | `/v2/actor-runs/{id}/key-value-store/records/{key}`       | Get run's KV store record       |
 
 ### Run Status Values
 
@@ -136,6 +175,22 @@ All successful responses wrap data in a `data` field:
 }
 ```
 
+### Validation Errors
+
+Invalid request bodies return a 400 with Zod validation details:
+
+```json
+{
+  "error": {
+    "type": "validation_error",
+    "message": "Validation failed",
+    "details": [
+      { "path": ["name"], "message": "String must contain at least 1 character(s)" }
+    ]
+  }
+}
+```
+
 ### Error Responses
 
 ```json
@@ -151,6 +206,6 @@ All successful responses wrap data in a `data` field:
 | --------- | ------------------------------ |
 | `400`     | Bad request / validation error |
 | `401`     | Authentication required        |
-| `403`     | Permission denied              |
 | `404`     | Resource not found             |
+| `409`     | Conflict (e.g., locked request)|
 | `500`     | Internal server error          |

src/docs/apify-sdk-environment.md

@@ -60,10 +60,10 @@ npm start
 
 ```bash
 # Login to your server
-crawlee-cloud login --server https://your-server.com
+crc login --url https://your-server.com
 
 # Push your Actor
-crawlee-cloud push my-actor
+crc push my-actor
 ```
 
 ---

src/docs/cli.md

@@ -105,10 +105,29 @@ crawlee-cloud status abc123 --watch --interval 5
 Authenticate with your Crawlee Cloud server.
 
 ```bash
-crawlee-cloud login --url https://your-server.com
+crawlee-cloud login [options]
 ```
 
-You'll be prompted to enter your API token. Credentials are stored in `~/.crawlee-cloud/config.json`.
+**Options:**
+
+| Flag           | Description     |
+| -------------- | --------------- |
+| `--url, -u`    | API base URL    |
+| `--token, -t`  | API token       |
+
+Without flags, you'll be prompted interactively. The token is validated against the server before saving.
+
+**Examples:**
+
+```bash
+# Interactive login (prompts for URL and token)
+crawlee-cloud login
+
+# Non-interactive
+crawlee-cloud login --url https://your-server.com --token your-api-token
+```
+
+Credentials are stored in `~/.crawlee-cloud/config.json`.
 
 ---
 
@@ -124,48 +143,49 @@ crawlee-cloud push [actor-name]
 
 | Flag            | Description               |
 | --------------- | ------------------------- |
-| `--version, -v` | Version tag for the build |
-| `--no-build`    | Skip local build step     |
+| `--tag, -t`  | Docker image tag for the build |
+| `--no-build` | Skip local build step          |
 
 **Example:**
 
 ```bash
 cd my-actor
-crawlee-cloud push my-scraper --version 1.0.0
+crawlee-cloud push my-scraper --tag 1.0.0
 ```
 
 ---
 
 ### `run`
 
-Execute an Actor on the server.
+Run an Actor locally with local file storage.
 
 ```bash
-crawlee-cloud run <actor-name> [options]
+crawlee-cloud run [options]
 ```
 
 **Options:**
 
-| Flag           | Description              |
-| -------------- | ------------------------ |
-| `--input, -i`  | JSON input for the Actor |
-| `--input-file` | Path to JSON input file  |
-| `--wait, -w`   | Wait for completion      |
-| `--timeout`    | Max wait time (seconds)  |
+| Flag          | Description                         |
+| ------------- | ----------------------------------- |
+| `--input, -i` | JSON input or path to JSON file    |
+| `--no-purge`  | Do not purge storage before run     |
 
 **Examples:**
 
 ```bash
-# Run with inline input
-crawlee-cloud run my-scraper --input '{"url": "https://example.com"}'
+# Run in current directory
+cd my-actor
+crawlee-cloud run
 
-# Run with input file
-crawlee-cloud run my-scraper --input-file ./input.json
+# Run with input
+crawlee-cloud run --input '{"url": "https://example.com"}'
 
-# Run and wait for completion
-crawlee-cloud run my-scraper --wait --timeout 300
+# Keep previous storage data
+crawlee-cloud run --no-purge
 ```
 
+Local storage is created in `./storage/` with datasets, key-value stores, and request queues.
+
 ---
 
 ### `logs`
@@ -193,28 +213,70 @@ crawlee-cloud logs abc123 --follow
 
 ### `call`
 
-Make direct API requests.
+Call a remote Actor on the platform and optionally wait for results.
 
 ```bash
-crawlee-cloud call <method> <path> [options]
+crawlee-cloud call <actor> [options]
 ```
 
 **Options:**
 
-| Flag         | Description         |
-| ------------ | ------------------- |
-| `--data, -d` | Request body (JSON) |
+| Flag              | Description                                    |
+| ----------------- | ---------------------------------------------- |
+| `--input, -i`     | Input JSON or path to JSON file                |
+| `--env, -e`       | Environment variable KEY=VALUE (repeatable)    |
+| `--wait, -w`      | Wait for run to finish                         |
+| `--timeout, -t`   | Timeout in seconds (default: 3600)             |
+| `--memory, -m`    | Memory in MB (default: 1024)                   |
 
 **Examples:**
 
 ```bash
-# List datasets
-crawlee-cloud call GET /v2/datasets
+# Call an Actor
+crawlee-cloud call my-scraper --input '{"url": "https://example.com"}'
+
+# Call and wait for results
+crawlee-cloud call my-scraper --wait --input '{"url": "https://example.com"}'
+
+# Call with environment variables (use -e multiple times)
+crc call my-actor -e KEY1=val1 -e KEY2=val2
+```
+
+> **Tip:** The `-e` flag can be repeated to pass multiple environment variables in a single call.
+
+---
+
+## Getting Your API Token
+
+You need an API token to authenticate with Crawlee Cloud. There are two ways to get one:
+
+### Via the Dashboard
+
+1. Login to the dashboard at `http://localhost:3001`
+2. Go to **Settings → API Keys**
+3. Create a new API key
+
+### Via the API
+
+First, obtain a JWT token by logging in:
+
+```bash
+curl -X POST http://localhost:3000/v2/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"admin@crawlee.cloud","password":"your-password"}'
+```
 
-# Create a dataset
-crawlee-cloud call POST /v2/datasets --data '{"name": "my-data"}'
+Then create an API key using the JWT token:
+
+```bash
+curl -X POST http://localhost:3000/v2/auth/api-keys \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"my-key"}'
 ```
 
+Use the resulting API key as your token when running `crawlee-cloud login`.
+
 ---
 
 ## Configuration
@@ -223,7 +285,7 @@ Configuration is stored in `~/.crawlee-cloud/config.json`:
 
 ```json
 {
-  "server": "https://your-server.com",
+  "apiBaseUrl": "https://your-server.com",
   "token": "your-api-token"
 }
 ```