docs: Restructure docs around AI tools/cli to make them more discoverable

apps/typegpu-docs/astro.config.mjs

@@ -294,6 +294,11 @@ export default defineConfig({
         {
           label: 'Tooling',
           items: stripFalsy([
+            {
+              label: 'TypeGPU CLI',
+              slug: 'tooling/typegpu-cli',
+              badge: { text: 'new' },
+            },
             {
               label: 'Build Plugin',
               slug: 'tooling/unplugin-typegpu',
@@ -304,7 +309,12 @@ export default defineConfig({
               badge: { text: 'new' },
             },
             {
-              label: 'Generator CLI',
+              label: 'AI Tools',
+              slug: 'tooling/ai-tools',
+              badge: { text: 'new' },
+            },
+            {
+              label: 'WGSL to TypeGPU',
               slug: 'tooling/tgpu-gen',
             },
           ]),

apps/typegpu-docs/src/content/docs/getting-started.mdx

@@ -11,6 +11,8 @@ All you need to get started in most cases, is to just run the following command:
 npx typegpu@latest
 ```
 
+For more installation options and existing-project setup, see the [TypeGPU CLI](/TypeGPU/tooling/typegpu-cli) guide.
+
 It allows you to:
 - Select from a range of **templates** in various frameworks
 - Pick and choose from our wide variety of **ecosystem packages**
@@ -98,10 +100,10 @@ function foo() {
 We provide a [lint plugin](/TypeGPU/tooling/eslint-plugin-typegpu) that helps with writing 'use gpu' functions.
 :::
 
-### AI Tools
+:::tip
+If you use AI coding agents, see [AI Tools](/TypeGPU/tooling/ai-tools) for the official TypeGPU Skill and runtime inspector MCP.
+:::
 
-To install the official TypeGPU Skill, head to the [Software Mansion Skills repository](https://github.com/software-mansion-labs/skills) and select the TypeGPU skill during the setup process.
-You can also use the experimental [TypeGPU MCP](https://www.npmjs.com/package/typegpu-runtime-inspector-mcp) to make it easier for agents to catch runtime errors and inspect the generated WGSL code along with other useful runtime information.
 ### Troubleshooting
 
 <details>

apps/typegpu-docs/src/content/docs/tooling/ai-tools.mdx

@@ -0,0 +1,26 @@
+---
+title: AI Tools
+description: A guide to using TypeGPU resources with AI coding agents.
+---
+
+TypeGPU provides optional tools for AI coding agents working with TypeGPU projects.
+They help agents find TypeGPU-specific guidance and inspect generated shader code while debugging.
+
+## TypeGPU Skill
+
+The official TypeGPU Skill gives agents guidance for TypeGPU schemas, functions, shaders, buffers, textures, pipelines, and common error patterns.
+
+To install it, use the [Software Mansion Skills repository](https://github.com/software-mansion-labs/skills) and select the TypeGPU skill during the setup process.
+
+:::tip
+The TypeGPU project starter can install the skill for you. Run `npx typegpu@latest` and enable AI skills when prompted.
+For a non-interactive setup, run `npx typegpu@latest my-app --yes --agent-skills`.
+For an existing project, run `npx typegpu@latest --enhance --yes --agent-skills`.
+:::
+
+## TypeGPU MCP
+
+The experimental [TypeGPU Runtime Inspector MCP](https://www.npmjs.com/package/typegpu-runtime-inspector-mcp) exposes runtime inspection data to agent tools.
+It helps agents catch runtime errors and inspect generated WGSL code alongside other useful TypeGPU runtime information.
+
+Use it when your agent environment supports MCP servers and you want runtime feedback while iterating on TypeGPU programs.

apps/typegpu-docs/src/content/docs/tooling/tgpu-gen.mdx

@@ -1,15 +1,15 @@
 ---
-title: Generator CLI
-description: A guide on how to use the TypeGPU Generator CLI
+title: WGSL to TypeGPU
+description: Convert existing WGSL shader files into TypeGPU definitions with tgpu-gen.
 ---
 
 import { FileTree } from '@astrojs/starlight/components';
 import FileDiff from '../../../components/FileDiff.astro';
 
-TypeGPU Generator (tgpu-gen) is a CLI companion tool that transforms WGSL code files into
+`tgpu-gen` is a WGSL migration tool that transforms WGSL code files into
 matching TypeGPU definitions. It can be used for integrating TypeGPU into established WebGPU projects, or automating the migration process.
 
-- ✨ Generate TypeGPU definitions from WGSL shaders
+- ✨ Convert WGSL shaders into TypeGPU definitions
 - 👀 Continuously watch for changes in WGSL files and update the generated definitions
 - 🌲 Specify input and output using glob patterns
 - 🎯 Choose the output extension and CJS or ESM format
@@ -179,7 +179,7 @@ import { Tabs, TabItem } from '@astrojs/starlight/components';
 If we wanted to leverage TypeGPU's type-safe features with these shaders, we could
 manually create the necessary definitions. However, maintaining these handcrafted
 definitions in sync with the shaders can be both tedious and prone to errors.
-Fortunately, we don't have to do that; we can use the TypeGPU Generator CLI to automatically generate the required TypeScript definitions for us.
+Fortunately, we don't have to do that; we can use `tgpu-gen` to automatically generate the required TypeScript definitions for us.
 
 Assuming that we are inside the project directory (computeBoids folder), we can run the following command to generate the TypeScript definitions for the shaders:
 
@@ -272,7 +272,7 @@ For specific usage details, check out the following Usage section.
 
 ## Usage
 
-This section will cover the most common use cases of the TypeGPU Generator CLI and provide short examples.
+This section covers the most common `tgpu-gen` use cases and provides short examples.
 
 ### Generate TypeGPU definitions for WGSL shader files
 
@@ -304,7 +304,7 @@ The quotes are not necessary if the path does not contain spaces. However, using
 If you are using glob patterns, quotes are required to prevent the shell from expanding them.
 :::
 
-TypeGPU Generator CLI supports glob patterns for specifying input paths.
+`tgpu-gen` supports glob patterns for specifying input paths.
 The following command will generate TypeGPU definitions for all WGSL files inside a given directory:
 
 ```bash
@@ -526,7 +526,7 @@ This will overwrite the existing TypeScript files with the new TypeGPU definitio
 
 ### Watch mode
 
-TypeGPU Generator CLI supports a watch mode that continuously monitors the input files for changes and updates the generated definitions.
+`tgpu-gen` supports a watch mode that continuously monitors the input files for changes and updates the generated definitions.
 To enable the watch mode, use the `--watch` (or `-w`) option:
 
 ```bash
@@ -539,7 +539,7 @@ By default, the watch mode will overwrite the existing files when changes are de
 You can also use the `--keep` and `--overwrite` options in the watch mode. They will only affect the initial generation.
 
 
-## Getting help with the Generator CLI
+## Getting help with tgpu-gen
 
 To get a quick overview of the generator, its arguments and options, run:
 

apps/typegpu-docs/src/content/docs/tooling/typegpu-cli.mdx

@@ -0,0 +1,127 @@
+---
+title: TypeGPU CLI
+description: Create a TypeGPU project or add TypeGPU to an existing project with npx typegpu@latest.
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+The TypeGPU CLI is the project starter for TypeGPU.
+Use it to scaffold a new TypeGPU project or enhance an existing project with TypeGPU dependencies and setup.
+
+## Creating a project
+
+Run the CLI in the directory where you want to create your project:
+
+<Tabs syncKey="package-manager">
+  <TabItem label="npm" icon="seti:npm">
+    ```sh frame=none
+    npx typegpu@latest
+    ```
+  </TabItem>
+  <TabItem label="pnpm" icon="pnpm">
+    ```sh frame=none
+    pnpm dlx typegpu@latest
+    ```
+  </TabItem>
+  <TabItem label="yarn" icon="seti:yarn">
+    ```sh frame=none
+    yarn dlx typegpu@latest
+    ```
+  </TabItem>
+  <TabItem label="bun" icon="bun">
+    ```sh frame=none
+    bunx typegpu@latest
+    ```
+  </TabItem>
+</Tabs>
+
+The CLI lets you choose a project name and one of the available templates:
+
+- Vite
+- Vite + React
+- Expo React Native
+- ... and more
+
+It can also install dependencies and download the official TypeGPU AI skill during setup.
+
+### Non-interactive creation
+
+Use `--yes` to skip prompts and use defaults:
+
+```sh
+npx typegpu@latest my-app --yes
+```
+
+You can still select the important setup choices explicitly:
+
+```sh
+npx typegpu@latest my-app --yes --template vite-react --packages @typegpu/sdf --packages @typegpu/noise
+```
+
+`--yes` skips dependency installation.
+Use `--agent-skills` when you want the TypeGPU AI skill installed during project creation:
+
+```sh
+npx typegpu@latest my-app --yes --agent-skills
+```
+
+## Enhancing an existing project
+
+Run the CLI with `--enhance` from the root of an existing project:
+
+<Tabs syncKey="package-manager">
+  <TabItem label="npm" icon="seti:npm">
+    ```sh frame=none
+    npx typegpu@latest --enhance
+    ```
+  </TabItem>
+  <TabItem label="pnpm" icon="pnpm">
+    ```sh frame=none
+    pnpm dlx typegpu@latest --enhance
+    ```
+  </TabItem>
+  <TabItem label="yarn" icon="seti:yarn">
+    ```sh frame=none
+    yarn dlx typegpu@latest --enhance
+    ```
+  </TabItem>
+  <TabItem label="bun" icon="bun">
+    ```sh frame=none
+    bunx typegpu@latest --enhance
+    ```
+  </TabItem>
+</Tabs>
+
+### Non-interactive enhancement
+
+Use `--recommended` with `--yes` to apply the standard Vite-oriented TypeGPU setup without prompts:
+
+```sh
+npx typegpu@latest --enhance --yes --recommended
+```
+
+You can also add ecosystem packages or the TypeGPU AI skill in the same pass:
+
+```sh
+npx typegpu@latest --enhance --yes --recommended --packages @typegpu/sdf --agent-skills
+```
+
+If the CLI cannot detect a package manager, pass `--package-manager npm`, `pnpm`, `yarn`, or `bun`.
+
+:::caution
+Back up your project before running the enhance flow.
+The CLI does not provide an automatic rollback.
+:::
+
+## Options
+
+- `-y`, `--yes`: skip prompts and use defaults.
+- `--template <name>`: choose `vite-simple`, `vite-complex`, `vite-react`, or `expo-simple`.
+- `--packages <name>`: add a TypeGPU ecosystem package. Repeat the flag to add more.
+- `--agent-skills`: download the official TypeGPU AI skill.
+- `--package-manager <pm>`: choose the package manager for dependency and skill commands.
+- `--recommended`: use the recommended enhance setup.
+
+## Related tools
+
+If you want to convert existing WGSL shader files into TypeGPU definitions, use [tgpu-gen](/TypeGPU/tooling/tgpu-gen) instead.