feat(docs): TS build setup guide + auto-import DX across all pages

Add dedicated TypeScript Build Setup guide covering aster-gen CLI,
npm scripts, Vite/Webpack plugins, type mapping, branded numerics,
and runtime fallback. All TS code examples simplified: bare decorators
(@rpc(), @ServerStream(), etc.), no manual registerGenerated() import,
no generated wiring — just `npx aster-gen` then AsterServer.start()
auto-imports aster-rpc.generated.js.

- New page: guides/typescript-build-setup.mdx (added to sidebar)
- quickstart/python.mdx: TS producer uses auto-import, node not bun
- quickstart/mission-control.mdx: all 5 chapter TS blocks cleaned up,
  Bun.spawn replaced with node:child_process for cross-runtime compat
- bindings/javascript/index.mdx: bare @rpc() + auto-import example
- bindings/javascript/server.mdx: decorator docs stripped of
  request/response, link to build setup
- guides/define-a-service.mdx: build step note after TS tab

Author: emrul

docs/bindings/javascript/index.mdx

@@ -39,7 +39,7 @@ A producer hosts a service over QUIC; a consumer connects by address.
 
 ```typescript
 // service.ts
-import { Service, Rpc, AsterServer, AsterClientWrapper } from '@aster-rpc/aster';
+import { Service, Rpc, AsterServer } from '@aster-rpc/aster';
 
 class HelloRequest {
   name = "";
@@ -53,14 +53,16 @@ class HelloResponse {
 
 @Service({ name: "Hello", version: 1 })
 export class HelloService {
-  @Rpc({ request: HelloRequest, response: HelloResponse })
+  @Rpc()
   async sayHello(req: HelloRequest): Promise<HelloResponse> {
     return new HelloResponse({ message: `Hello, ${req.name}!` });
   }
 }
 
-// Producer
-const server = new AsterServer({ services: [new HelloService()] });
+// Producer (run `npx aster-gen` first)
+const server = new AsterServer({
+  services: [new HelloService()],
+});
 await server.start();
 console.log("Producer ready at:", server.address);
 await server.serve();

docs/bindings/javascript/server.mdx

@@ -89,36 +89,30 @@ class EchoService { ... }
 ### @Rpc
 
 ```typescript
-@Rpc({ request: EchoRequest, response: EchoResponse, timeout: 30, idempotent: true })
+@Rpc({ timeout: 30, idempotent: true })
 async echo(req: EchoRequest): Promise<EchoResponse> { ... }
 ```
 
-> **Note:** TypeScript erases generic type parameters at runtime, so the
-> contract publisher and the `gen-client` codegen pipeline cannot discover
-> the request and response shapes from the method signature alone. Pass
-> the constructors explicitly via `request:` and `response:` so the
-> published manifest carries the wire tag and field list -- this is
-> required for cross-language consumers (Python, Go, Java) to talk to
-> the service.
+The `aster-gen` build step reads request/response types from the AST, so you don't need to pass them in the decorator. Optional keys: `timeout`, `idempotent`, `requires`, `serialization`. See [TypeScript Build Setup](/docs/guides/typescript-build-setup).
 
 ### @ServerStream
 
 ```typescript
-@ServerStream({ request: WatchRequest, response: ItemUpdate })
+@ServerStream()
 async *watchItems(req: WatchRequest): AsyncGenerator<ItemUpdate> { ... }
 ```
 
 ### @ClientStream
 
 ```typescript
-@ClientStream({ request: Item, response: BatchResult })
+@ClientStream()
 async uploadBatch(requests: AsyncIterable<Item>): Promise<BatchResult> { ... }
 ```
 
 ### @BidiStream
 
 ```typescript
-@BidiStream({ request: Message, response: Message })
+@BidiStream()
 async *chat(requests: AsyncIterable<Message>): AsyncGenerator<Message> { ... }
 ```
 

docs/guides/define-a-service.mdx

@@ -163,7 +163,7 @@ class TaskService {
 }
 ```
 
-`@Rpc()` accepts optional `{ timeout, idempotent, requires }` options.
+`@Rpc()` accepts optional `{ timeout, idempotent, requires }` options. The scanner reads request/response types from the AST — run `npx aster-gen` before starting your server. See [TypeScript Build Setup](/docs/guides/typescript-build-setup).
 
   </TabItem>
 </LanguageTabs>

docs/guides/typescript-build-setup.mdx

@@ -0,0 +1,180 @@
+---
+id: typescript-build-setup
+title: TypeScript Build Setup
+slug: /guides/typescript-build-setup
+---
+
+TypeScript erases type information at runtime. Aster's `aster-gen` scanner
+reads your source at build time via the TypeScript compiler API, discovers
+all `@Service`, `@WireType`, `@Rpc`, `@ServerStream`, `@ClientStream`, and
+`@BidiStream` decorated classes, and emits `aster-rpc.generated.ts` with
+the metadata the runtime needs — field shapes, wire type mappings, method
+signatures, and contract identity hashes.
+
+This replaces the need to pass `{ request, response }` to every decorator.
+You write clean decorators; the scanner extracts types from the AST.
+
+## Install
+
+```bash
+npm install @aster-rpc/aster
+```
+
+`aster-gen` ships as the `aster-gen` bin inside `@aster-rpc/aster` — no
+extra package needed. TypeScript is a peer dependency (bring your own
+version).
+
+## Run the scanner
+
+```bash
+# defaults: reads ./tsconfig.json, writes ./aster-rpc.generated.ts
+npx aster-gen
+
+# custom paths
+npx aster-gen -p tsconfig.app.json -o build/aster-rpc.generated.ts
+```
+
+Or add it to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "build": "aster-gen && tsc"
+  }
+}
+```
+
+Re-run after adding or changing wire types, RPC methods, or decorator
+options. The generated file is deterministic — same input always produces
+the same output.
+
+## Use in your app
+
+`AsterServer.start()` auto-imports `aster-rpc.generated.js` from the
+working directory — no manual import or wiring needed:
+
+```typescript
+import { AsterServer } from '@aster-rpc/aster';
+import { MyService } from './services.js';
+
+const server = new AsterServer({
+  services: [new MyService()],
+});
+await server.start();
+await server.serve();
+```
+
+If the generated file is missing, the runtime falls back to reflection
+and logs a warning.
+
+## What gets generated
+
+The output `aster-rpc.generated.ts` contains two exports:
+
+- **`WIRE_TYPES`** — ordered array of wire type descriptors (tag, fields,
+  nested type refs, field name sets) in dependency order.
+- **`SERVICES`** — array of service descriptors with method signatures,
+  RPC patterns, pre-derived manifest fields, and BLAKE3 type hashes for
+  cross-language contract identity.
+
+The file is `// @ts-nocheck` and auto-formatted. Commit it or gitignore
+it — either works. Committing makes the example runnable without a build
+step; gitignoring keeps diffs clean.
+
+## Bundler plugins
+
+For projects using a bundler, plugins run `aster-gen` automatically on
+build and during hot reload. When using a bundler plugin, pass the
+`generated` option explicitly since dynamic import won't resolve at
+bundle time:
+
+### Vite
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { asterGen } from '@aster-rpc/aster/vite-plugin';
+
+export default defineConfig({
+  plugins: [
+    asterGen({
+      project: 'tsconfig.json',
+      out: 'aster-rpc.generated.ts',
+    }),
+  ],
+});
+```
+
+The plugin runs on `buildStart` and watches for changes to decorated
+source files during dev.
+
+### Webpack
+
+```typescript
+// webpack.config.ts
+import { AsterGenPlugin } from '@aster-rpc/aster/webpack-plugin';
+
+export default {
+  plugins: [
+    new AsterGenPlugin({
+      project: 'tsconfig.json',
+      out: 'aster-rpc.generated.ts',
+    }),
+  ],
+};
+```
+
+The plugin hooks into `beforeCompile` and re-scans when source files
+change.
+
+## Type mapping
+
+The scanner maps TypeScript types to wire types per the Aster spec:
+
+| TypeScript | Wire type |
+|------------|-----------|
+| `string` | `string` |
+| `boolean` | `bool` |
+| `number` | `float64` |
+| `bigint` | `int64` |
+| `Date` | `timestamp` |
+| `Uint8Array` | `binary` |
+| `T[]` / `Array<T>` | `list<T>` |
+| `Set<T>` | `set<T>` |
+| `Map<K, V>` | `map<K, V>` |
+| `T \| null` / `T \| undefined` | `nullable<T>` |
+| Class with `@WireType` | `ref` (by tag) |
+
+### Branded numeric types
+
+Plain `number` maps to `float64`. For narrower types (int32, uint16, etc.),
+use branded types:
+
+```typescript
+import { i32, u64, f32 } from '@aster-rpc/aster';
+
+@WireType("myapp/Metrics")
+class Metrics {
+  count: i32 = 0;       // → int32
+  total_bytes: u64 = 0n; // → uint64
+  avg_latency: f32 = 0;  // → float32
+}
+```
+
+The scanner detects branded types via their phantom property and maps them
+to the correct wire primitive.
+
+## Runtime fallback
+
+If `aster-rpc.generated.js` is not found (e.g. during rapid prototyping),
+the runtime falls back to reflection: instantiating each wire type class
+and inspecting `Object.keys()`. This works for simple cases but has
+limitations:
+
+- Empty arrays don't reveal their element type.
+- Optional/nullable nested types aren't recursed.
+- Non-default-constructible classes can't be introspected.
+- Contract identity hashes are zeroed (cross-language calls won't match).
+
+A console warning fires once per class on the fallback path. For
+production use, always run `aster-gen`.

docs/quickstart/mission-control.mdx

@@ -53,7 +53,8 @@ class MissionControl {
 ```
 
 ```bash
-bun run control.ts             # that's the server
+npx aster-gen                  # generate type metadata (one-time build step)
+node control.ts                # that's the server
 aster shell aster1Qm...       # that's the client — tab completion, typed responses
 ```
 
@@ -221,7 +222,9 @@ aster shell aster1Qm...
 
 ```typescript
 // control.ts
-import { AsterServer, Service, Rpc, WireType } from '@aster-rpc/aster';
+import {
+    AsterServer, Service, Rpc, WireType,
+} from '@aster-rpc/aster';
 
 @WireType("mission/StatusRequest")
 class StatusRequest {
@@ -260,8 +263,11 @@ main();
 ```
 
 ```bash
+# Generate type metadata (run once, re-run after changing types/methods)
+npx aster-gen
+
 # Start the control plane
-bun run control.ts
+node control.ts
 # → aster1Qmxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 #   ^^^^^^^ this is your control plane's public-key address — copy it for the next step
 ```
@@ -528,10 +534,11 @@ async function main() {
 main();
 ```
 
-**Restart the service.** Stop the previous run with `Ctrl+C`, then start the new version:
+**Restart the service.** Stop the previous run with `Ctrl+C`, re-run the scanner and start the new version:
 
 ```bash
-bun run control.ts
+npx aster-gen
+node control.ts
 # → aster1Qmxxxxxxxx... ← this is a NEW address; the old one is gone
 ```
 
@@ -948,7 +955,7 @@ import {
 } from '@aster-rpc/aster';
 ```
 
-**Restart `control.ts`** (`Ctrl+C` then `bun run control.ts`) and copy the new address.
+**Re-run `npx aster-gen`** (to pick up the new method), then restart `control.ts` (`Ctrl+C` then `node control.ts`) and copy the new address.
 
 Save this as `metrics.ts` in a **second terminal** to push 10,000 metric points:
 
@@ -1166,14 +1173,20 @@ class AgentSession {
 
     @BidiStream()
     async *runCommand(commands: AsyncIterable<Command>): AsyncGenerator<CommandResult> {
+        const { execFile } = await import('node:child_process');
+        const { promisify } = await import('node:util');
+        const exec = promisify(execFile);
         for await (const cmd of commands) {
-            const proc = Bun.spawn(["sh", "-c", cmd.command], {
-                stdout: "pipe", stderr: "pipe",
-            });
-            const stdout = await new Response(proc.stdout).text();
-            const stderr = await new Response(proc.stderr).text();
-            const exit_code = await proc.exited;
-            yield new CommandResult({ stdout, stderr, exit_code });
+            try {
+                const { stdout, stderr } = await exec("sh", ["-c", cmd.command]);
+                yield new CommandResult({ stdout, stderr, exit_code: 0 });
+            } catch (e: any) {
+                yield new CommandResult({
+                    stdout: e.stdout ?? "",
+                    stderr: e.stderr ?? e.message,
+                    exit_code: e.code ?? 1,
+                });
+            }
         }
     }
 }

docs/quickstart/python.mdx

@@ -119,7 +119,9 @@ export class HelloService {
 }
 ```
 
-Two decorators: `@Service` (marks the class as an Aster service), `@Rpc` (marks a method as a callable endpoint). No schema files, no code generation, no base classes. Wire tags are auto-derived from the class names; for production cross-language services you'll add explicit `@WireType("ns/Type")` decorators -- see [Defining Services and Types](/docs/guides/services).
+Two decorators: `@Service` (marks the class as an Aster service), `@Rpc` (marks a method as a callable endpoint). No schema files, no base classes. Wire tags are auto-derived from the class names; for production cross-language services you'll add explicit `@WireType("ns/Type")` decorators -- see [Defining Services and Types](/docs/guides/services).
+
+Before running, generate type metadata with `npx aster-gen` — this reads your TypeScript source and emits `aster-rpc.generated.ts`, which `AsterServer` auto-imports on startup. See [TypeScript Build Setup](/docs/guides/typescript-build-setup) for details and bundler plugin options.
 
 </TabItem>
 </LanguageTabs>
@@ -155,7 +157,11 @@ python producer.py
 </TabItem>
 <TabItem value="typescript" label="TypeScript">
 
-Create `producer.ts`:
+Generate type metadata, then create `producer.ts`:
+
+```bash
+npx aster-gen
+```
 
 ```typescript
 import { AsterServer } from '@aster-rpc/aster';
@@ -170,7 +176,7 @@ await server.serve();
 ```
 
 ```bash
-bun run producer.ts
+node producer.ts
 ```
 
 </TabItem>
@@ -251,12 +257,12 @@ Run it, passing the producer's address:
 
 ```bash
 # macOS / Linux
-ASTER_ENDPOINT_ADDR=<paste from producer output> bun run consumer.ts
+ASTER_ENDPOINT_ADDR=<paste from producer output> node consumer.ts
 ```
 
 ```powershell
 # Windows (PowerShell)
-$env:ASTER_ENDPOINT_ADDR="<paste from producer output>"; bun run consumer.ts
+$env:ASTER_ENDPOINT_ADDR="<paste from producer output>"; node consumer.ts
 ```
 
 </TabItem>