Improve Documentation Linking and Navigation

cli/installation.mdx → api-reference/permissions-and-authorization.mdx

@@ -1,5 +1,5 @@
 ---
-title: Permissions-and-authorization
+title: Permissions and Authorization
 createdAt: Tue Jan 14 2025 02:09:39 GMT+0000 (Coordinated Universal Time)
 updatedAt: Tue Apr 29 2025 16:45:10 GMT+0000 (Coordinated Universal Time)
 ---
@@ -68,9 +68,9 @@ The following json would create a user that has access to the specified categori
 ```text Text
 {
     "api": {
-        "misc": {}, 
-        "user_read":{}, 
-        "instance_read": {}, 
+        "misc": {},
+        "user_read":{},
+        "instance_read": {},
         "instance_write": {},
 		"billing_read": {},
 		"billing_write": {}
@@ -83,9 +83,9 @@ The following json would create restricted access to only the presented categori
 ```text Text
 {
     "api": {
-        "misc": {}, 
-        "user_read":{}, 
-        "instance_read": {}, 
+        "misc": {},
+        "user_read":{},
+        "instance_read": {},
         "instance_write": {}
     }
 }
@@ -105,9 +105,9 @@ The following permissions would allow a user to read the instance logs of instan
 ```text Text
 {
     "api": {
-        "misc": {}, 
-        "user_read":{}, 
-        "instance_read": {}, 
+        "misc": {},
+        "user_read":{},
+        "instance_read": {},
         "instance_write": {},
         "billing_read": {
             "api.instance.request_logs": {
@@ -284,5 +284,4 @@ The following permissions would allow a user to read the instance logs of instan
 - [Update Team Role](https://docs.vast.ai/api-reference/team/update-team-role)
 - [Delete Team Role](https://docs.vast.ai/api-reference/team/destroy-team-role)
 - [Invite Team Member](https://docs.vast.ai/api-reference/team/invite-team-member)
-- [Delete Team Member](https://docs.vast.ai/api-reference/team/remove-team-member)
-
+- [Delete Team Member](https://docs.vast.ai/api-reference/team/remove-team-member)

cli/get-started.mdx

@@ -40,7 +40,7 @@ updatedAt: "Thu Apr 24 2025 19:41:24 GMT+0000 (Coordinated Universal Time)"
   })
 }} />
 
-We provide a python CLI (open-source) for a convenient interface to the rest API.  You can use the --explain option with any CLI command and it will print out the underlying API calls.
+We provide a python CLI (open-source) for managing Vast.ai resources from the command line.  You can use the --explain option with any CLI command to see the underlying API calls if needed.
 
 ## PyPI Install
 
@@ -72,7 +72,7 @@ where the `xxxx...` is a unique api-key (a long hexadecimal number).
 Note that if the script is named "vast" in this command on the website and your installed script is named "vast.py" you will need to change the name of the script in the command you run.
 The `set api-key` command saves your api-key in a hidden file in your home directory.
 Do not share your api-keys with anyone as they authenticate commands from your account.
-Your default main key allows full access to all commands without limitations, but you can use the CLI to create additional keys with [fine-grained access restrictions](/cli/installation).
+Your default main key allows full access to all commands without limitations. To create restricted keys, use the `create api-key` command (see [CLI commands](/cli/commands#create-api-key)) with the permission JSON structure described in the [permissions documentation](/api-reference/permissions-and-authorization).
 
 ## Usage
 
@@ -82,7 +82,7 @@ For the most up to date help, use 'vast.py --help'. You can then get a list of t
 vastai --help
 ```
 
-To see how the API works you can use it to find machines for rent.
+Here's how to search for available machines to rent:
 
 ```text Text
 vastai search offers --help

docs.json

@@ -304,7 +304,6 @@
             "icon": "terminal",
             "pages": [
               "cli/get-started",
-              "cli/installation",
               "cli/commands"
             ]
           }
@@ -317,7 +316,8 @@
             "group": "API Reference",
             "icon": "webhook",
             "pages": [
-              "api-reference/introduction"
+              "api-reference/introduction",
+              "api-reference/permissions-and-authorization"
             ]
           },
           {
@@ -385,10 +385,6 @@
       "source": "/api-reference/overview-and-quickstart",
       "destination": "/cli/get-started"
     },
-    {
-      "source": "/api-reference/permissions-and-authorization",
-      "destination": "/cli/installation"
-    },
     {
       "source": "/index",
       "destination": "/documentation/get-started"

documentation/get-started/index.mdx

@@ -32,17 +32,54 @@ description: "Step-by-step Vast.ai developer documentation with examples, guides
 
 [Vast.ai](https://www.vast.ai) is a marketplace for affordable GPU cloud computing. We make it easy for anyone to:
 
-- Spin up GPU instances in seconds at competitive [prices](https://vast.ai/pricing).
+- Spin up GPU instances in seconds at competitive [prices](/documentation/instances/pricing).
 - Scale across thousands of GPUs from [Secure Cloud datacenters](https://cloud.vast.ai/create/?instanceDiskSizeMin=16&instanceDurationMin=259200&instanceType=onDemand&isAvxSupported=false&isHostSecure=true&isMachineIpStatic=false&isOfferAvailable=true&isOfferCompatible=true&isOfferVerified=true&isQueryInverted=false&machineReliabilityMin=0.9&sorts=score-desc) or community providers.
-- Launch [prebuilt](https://cloud.vast.ai/templates/) or [custom templates](/documentation/templates/creating-templates) with one click.
+- Launch [prebuilt](/documentation/templates/introduction) or [custom templates](/documentation/templates/creating-templates) with one click.
 
 ## How It Works
 
-Vast.ai connects compute providers — from hobbyists to Tier-4 datacenters — with users who need GPUs. Our search engine lets you filter by GPU type, RAM, CPU, bandwidth, and more, while providers retain full control over pricing and contracts.
+Vast.ai connects compute providers — from hobbyists to Tier-4 datacenters — with users who need GPUs. Our [search engine](/documentation/instances/choosing/find-and-rent) lets you filter by GPU type, RAM, CPU, bandwidth, and more, while providers retain full control over [pricing](/documentation/instances/pricing) and [contracts](/documentation/instances/choosing/instance-types).
 
-## Getting started
+## Get Started
+
+<Card title="Quickstart Guide" href="/documentation/get-started/quickstart" icon="rocket">
+  Launch your first GPU instance in minutes with our step-by-step guide
+</Card>
+
+## GPU Instances
+
+<CardGroup cols={2}>
+  <Card title="Overview" href="/documentation/instances/overview" icon="server">
+    Learn about GPU instances, containers, and compute options
+  </Card>
+  <Card title="Pricing" href="/documentation/instances/pricing" icon="tag">
+    Understand marketplace pricing and cost optimization strategies
+  </Card>
+  <Card title="Find & Rent" href="/documentation/instances/choosing/find-and-rent" icon="search">
+    Search and rent the perfect GPU for your workload
+  </Card>
+  <Card title="Connect" href="/documentation/instances/connect/overview" icon="plug">
+    Access instances via SSH, Jupyter, or web portal
+  </Card>
+</CardGroup>
+
+## Common Tasks
+
+<CardGroup cols={2}>
+  <Card title="Templates Guide" href="/documentation/templates/introduction" icon="layer-group">
+    Learn about pre-built environments and customization
+  </Card>
+  <Card title="Data Movement" href="/documentation/instances/storage/data-movement" icon="arrows">
+    Transfer files to and from your instances
+  </Card>
+  <Card title="Reserved Instances" href="/documentation/instances/choosing/reserved-instances" icon="calendar">
+    Save up to 50% with long-term commitments
+  </Card>
+  <Card title="Manage Instances" href="/documentation/instances/manage-instances" icon="server">
+    Start, stop, and monitor your GPU rentals
+  </Card>
+</CardGroup>
 
-Ready to get started? Follow our [Quick Start Guide](/documentation/get-started/quickstart) to launch your first instance.
 
 ## Mission
 
@@ -52,4 +89,6 @@ Vast.ai's mission is to align and democratize AI. Machine learning is progressin
 
 - **Support Chat** → Available 24/7 in the bottom-right corner of our [console](https://cloud.vast.ai).
 - **Email** → [[email protected]](mailto:[email protected])
+- **Discord** → Join our [community](https://discord.gg/vast) for help and discussions.
+- **Documentation** → Browse our [instances guide](/documentation/instances/overview), [templates documentation](/documentation/templates/introduction), or [troubleshooting tips](/documentation/reference/troubleshooting).
 

documentation/get-started/quickstart.mdx

@@ -75,7 +75,8 @@ This Quickstart will guide you through setting up your Vast.ai account and runni
 
 - Create an account on [vast.ai.](https://cloud.vast.ai/)
 - Verify your email address.
-- Go to [**Billing**](https://cloud.vast.ai/billing/) → **Add Credit** and top up using credit card, Coinbase, or Crypto.com.
+- Go to [**Billing**](/documentation/reference/billing) → **Add Credit** and top up using [credit card, Coinbase, or Crypto.com](/documentation/reference/billing#payment-methods).
+- Learn about [auto-billing](/documentation/reference/billing#auto-debit) to avoid interruptions.
 
 
   ![Billing](/images/guides-overview-quick-start.webp)
@@ -85,16 +86,16 @@ This Quickstart will guide you through setting up your Vast.ai account and runni
   ![](/images/guides-overview-quick-start-2.webp)
 
 <Note>
-  Before you can **rent a machine&#x20;**&#x6F;r **create a team**, you must verify your email address. After signing up, check your inbox (and spam folder) for the verification email  and click the link inside. You can resend the verification email anytime from **Settings → Resend Verification Email.**
+  Before you can **rent a machine** or **create a team**, you must [verify your email address](/documentation/reference/account-settings#email-verification). After signing up, check your inbox (and spam folder) for the verification email and click the link inside. You can resend the verification email anytime from [**Settings**](/documentation/reference/account-settings) → Resend Verification Email. Learn more about [teams](/documentation/teams/teams-overview) and [instance management](/documentation/instances/manage-instances).
 </Note>
 
 ### &#x32;**. Prepare to Connect**
 
-- **For SSH access**: generate an [SSH key pair](/documentation/instances/sshscp) and upload your **public key** in [Keys page](https://cloud.vast.ai/manage-keys/).
+- **For SSH access**: generate an [SSH key pair](/documentation/instances/connect/ssh#generating-ssh-keys) following our [complete SSH guide](/documentation/instances/connect/ssh) and upload your **public key** in [Keys page](https://cloud.vast.ai/manage-keys/) or via [account settings](/documentation/reference/keys).
 
 
   ![Keys](/images/guides-overview-quick-start-3.webp)
-- **For Jupyter access**: download and install the provided [TSL certificate](/documentation/instances/jupyter#1SmCz) (needed for secure browser access).
+- **For Jupyter access**: download and install the provided [TSL certificate](/documentation/instances/connect/jupyter#certificate-installation) following our [Jupyter setup guide](/documentation/instances/connect/jupyter) (needed for secure browser access).
 
 <Note>
   If you don’t install the provided browser certificate:&#x20;
@@ -105,19 +106,19 @@ This Quickstart will guide you through setting up your Vast.ai account and runni
   Installing the certificate once removes the warning permanently.
 </Note>
 
-  ### &#x33;**. Pick a&#x20;**[**Template**](/documentation/instances/templates)**&#x20;& Find a Machine**
+  ### 3. Pick a [**Template**](/documentation/templates/introduction) & Find a Machine
 
-  - Browse [**Templates**](https://cloud.vast.ai/templates/) for pre-built setups (e.g., [PyTorch](/pytorch), TensorFlow, ComfyUI).
-- Go to [**Search**](https://cloud.vast.ai/create/) and filter by GPU type, count, RAM, CPU, network speed, and price.
-- **Disk Space is Permanent.&#x20;**&#x54;he disk size you choose when creating an instance cannot be changed later. If you run out of space, you’ll need to create a new instance with a larger disk. Tip: Allocate a bit more than you think you need to avoid interruptions.
-- Click **Rent** when you find a match.
-- Wait for the instance to start—cached images launch quickly, fresh pulls may take 10–60 minutes.
-- Click **Open** button to access your instance.
+  - Browse [**Templates**](https://cloud.vast.ai/templates/) for pre-built setups (e.g., [PyTorch](/pytorch), TensorFlow, ComfyUI) or [create custom templates](/documentation/templates/creating-templates).
+- Go to [**Search**](https://cloud.vast.ai/create/) and filter by GPU type, count, RAM, CPU, network speed, and price. Learn about [search filters](/documentation/instances/choosing/overview#search-filters) and [instance types](/documentation/instances/choosing/instance-types).
+- **Disk Space is Permanent.** The disk size you choose when creating an instance cannot be changed later. If you run out of space, you'll need to create a new instance with a larger disk. Learn about [storage types](/documentation/instances/storage/types) and [volumes](/documentation/instances/storage/volumes). Tip: Allocate a bit more than you think you need to avoid interruptions.
+- Click **Rent** when you find a match. Consider [reserved instances](/documentation/instances/choosing/reserved-instances) for 50% savings on long-term projects.
+- Wait for the instance to start—cached images launch quickly, fresh pulls may take 10–60 minutes. Check [instance status](/documentation/instances/manage-instances#status) for progress.
+- Click **Open** button to access your instance via your chosen [connection method](/documentation/instances/connect/overview).
 
-### **4.&#x20;**[**Manage or End Your Instance**](/documentation/instances/managing-instances)
+### **4. [Manage or End Your Instance](/documentation/instances/manage-instances)**
 
-- Use **Stop** to pause GPU billing (storage still accrues charges).
-- Use **Delete** when finished to stop *all* charges.
+- Use **Stop** to pause GPU billing ([storage still accrues charges](/documentation/instances/storage/types#costs)). Learn about the [instance lifecycle](/documentation/instances/manage-instances#lifecycle).
+- Use **Delete** when finished to stop *all* charges. See [data movement](/documentation/instances/storage/data-movement) if you need to save data first.
 
 ![Manage or End Your Instance](/images/guides-overview-quick-start-4.webp)
 
@@ -129,8 +130,22 @@ The minimum deposit amount on Vast.ai is $5.
 
 ### What happens when my balance runs out? Can I avoid interruptions?
 
-When your balance reaches zero, your running instances will automatically stop. To avoid this, you can enable **auto-billing&#x20;**&#x6F;n the Billing page. Set an auto-charge threshold higher than your average daily spend, so your card is automatically charged when your balance falls below that amount. We also recommend setting a **low-balance email alert&#x20;**&#x61;t a slightly lower threshold to notify you if the auto-charge fails for any reason.&#x20;
+When your balance reaches zero, your running instances will automatically stop. To avoid this, you can enable [**auto-billing**](/documentation/reference/billing#auto-debit) on the [Billing page](/documentation/reference/billing). Set an auto-charge threshold higher than your average daily spend, so your card is automatically charged when your balance falls below that amount. We also recommend setting a [**low-balance email alert**](/documentation/reference/account-settings#notifications) at a slightly lower threshold to notify you if the auto-charge fails for any reason. Learn more about [billing management](/documentation/reference/billing) and [cost optimization](/documentation/instances/pricing).
 
 ### How can I customize a template?
 
-You can create a new template from scratch, or you can edit an existing template. You can find a guide [here](/documentation/instances/templates#LrOME).&#x20;
+You can create a new template from scratch, or you can edit an existing template. You can find a guide [here](/documentation/templates/creating-templates). See also [template settings](/documentation/templates/template-settings) and [advanced setup](/documentation/templates/advanced-setup) for more customization options. Learn about [managing templates](/documentation/templates/managing-templates) for organizing your template library.
+
+## Next Steps
+
+<CardGroup cols={3}>
+  <Card title="Instances Overview" href="/documentation/instances/overview" icon="server">
+    Complete guide to GPU instances, types, and management
+  </Card>
+  <Card title="Instance Pricing" href="/documentation/instances/pricing" icon="dollar-sign">
+    Marketplace pricing, instance types, and saving strategies
+  </Card>
+  <Card title="Templates Introduction" href="/documentation/templates/introduction" icon="layer-group">
+    Pre-built environments, customization, and Docker setup
+  </Card>
+</CardGroup>

documentation/instances/choosing/overview.mdx

@@ -42,10 +42,20 @@ For the fastest path to a running instance:
 
 ## What's in This Section
 
-- **[Instance Types](/documentation/instances/choosing/instance-types)** - Understand on-demand vs interruptible vs reserved options
-- **[Choosing a Template](/documentation/instances/choosing/templates)** - Understanding and selecting templates
-- **[Finding & Renting](/documentation/instances/choosing/find-and-rent)** - Search, filter, configure, and rent
-- **[Reserved Instances](/documentation/instances/choosing/reserved-instances)** - Save up to 50% with prepayment
+<CardGroup cols={2}>
+  <Card title="Instance Types" href="/documentation/instances/choosing/instance-types" icon="layer-group">
+    Understand on-demand vs interruptible vs reserved options
+  </Card>
+  <Card title="Choosing a Template" href="/documentation/instances/choosing/templates" icon="cube">
+    Understanding and selecting templates for your needs
+  </Card>
+  <Card title="Finding & Renting" href="/documentation/instances/choosing/find-and-rent" icon="search">
+    Search, filter, configure, and rent GPU instances
+  </Card>
+  <Card title="Reserved Instances" href="/documentation/instances/choosing/reserved-instances" icon="badge-dollar">
+    Save up to 50% with prepayment options
+  </Card>
+</CardGroup>
 
 ## Common Questions
 

documentation/instances/connect/overview.mdx

@@ -3,7 +3,31 @@ title: Overview
 description: Learn about Vast.ai connection methods—SSH, Jupyter, and Entrypoint—and how each controls instance access and workflow.
 ---
 
-We currently support 3 launch modes: entrypoint, ssh, and jupyter.
+Choose how to access your GPU instances based on your workflow needs.
+
+## Connection Methods
+
+<CardGroup cols={2}>
+  <Card title="SSH Access" href="/documentation/instances/connect/ssh" icon="terminal">
+    Terminal access with port forwarding and VS Code support
+  </Card>
+  <Card title="Jupyter Lab" href="/documentation/instances/connect/jupyter" icon="notebook">
+    Web-based notebooks for interactive development
+  </Card>
+</CardGroup>
+
+**Note:** For automated execution without interactive access, see [Entrypoint](#entrypoint) below.
+
+## Additional Options
+
+<CardGroup cols={2}>
+  <Card title="Instance Portal" href="/documentation/instances/connect/instance-portal" icon="browser">
+    Web access to any application via secure tunnels
+  </Card>
+  <Card title="Port Networking" href="/documentation/instances/connect/networking" icon="network-wired">
+    Configure exposed ports and bandwidth settings
+  </Card>
+</CardGroup>
 
 ## Entrypoint