docs: add comprehensive JSDoc and Mintlify documentation

docs/api-reference/classes/droid.mdx

@@ -0,0 +1,205 @@
+---
+title: Droid
+description: Main entry point for the Droid SDK
+---
+
+# Droid
+
+The `Droid` class is the main entry point for the SDK. It provides methods for executing prompts and managing conversation threads.
+
+## Import
+
+```typescript
+import { Droid, MODELS } from '@activade/droid-sdk';
+```
+
+## Constructor
+
+```typescript
+new Droid(config?: DroidConfig)
+```
+
+Creates a new Droid instance with the specified configuration.
+
+### Parameters
+
+<ParamField path="config" type="DroidConfig" optional>
+  Configuration options for the Droid instance.
+
+  <Expandable title="DroidConfig properties">
+    <ParamField path="cwd" type="string" optional default="process.cwd()">
+      Working directory for CLI operations.
+    </ParamField>
+    <ParamField path="model" type="ModelId | string" optional>
+      AI model to use for generation.
+    </ParamField>
+    <ParamField path="autonomyLevel" type="AutonomyLevel" optional default="'default'">
+      Level of autonomous decision-making: `'default'`, `'low'`, `'medium'`, or `'high'`.
+    </ParamField>
+    <ParamField path="reasoningEffort" type="ReasoningEffort" optional>
+      Reasoning intensity: `'off'`, `'none'`, `'low'`, `'medium'`, or `'high'`.
+    </ParamField>
+    <ParamField path="droidPath" type="string" optional default="'droid'">
+      Path to the Droid CLI binary.
+    </ParamField>
+    <ParamField path="timeout" type="number" optional default="600000">
+      Maximum execution time in milliseconds.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+### Example
+
+```typescript
+const droid = new Droid({
+  model: MODELS.CLAUDE_SONNET,
+  autonomyLevel: 'high',
+  reasoningEffort: 'medium',
+  cwd: '/path/to/project',
+  timeout: 300000
+});
+```
+
+## Properties
+
+### config
+
+```typescript
+get config(): Readonly<DroidConfig>
+```
+
+Returns the current configuration as a readonly object.
+
+```typescript
+const droid = new Droid({ model: MODELS.CLAUDE_SONNET });
+console.log(droid.config.model); // 'claude-sonnet-4-5-20250929'
+```
+
+## Methods
+
+### startThread()
+
+```typescript
+startThread(options?: ThreadOptions): Thread
+```
+
+Creates a new conversation thread for multi-turn interactions.
+
+<ParamField path="options" type="ThreadOptions" optional>
+  Thread-specific configuration that overrides instance defaults.
+</ParamField>
+
+**Returns:** A new `Thread` instance.
+
+```typescript
+const thread = droid.startThread({
+  autonomyLevel: 'high',
+  enabledTools: ['file_read', 'file_write']
+});
+
+await thread.run('Create a REST API');
+await thread.run('Add authentication');
+
+console.log('Session ID:', thread.id);
+```
+
+### resumeThread()
+
+```typescript
+resumeThread(sessionId: string, options?: ThreadOptions): Thread
+```
+
+Resumes a previously created conversation thread.
+
+<ParamField path="sessionId" type="string" required>
+  The unique session identifier from a previous thread.
+</ParamField>
+<ParamField path="options" type="ThreadOptions" optional>
+  Thread-specific configuration overrides.
+</ParamField>
+
+**Returns:** A `Thread` instance connected to the existing session.
+
+```typescript
+const thread = droid.resumeThread('session_abc123...');
+await thread.run('What did we work on last time?');
+```
+
+### exec()
+
+```typescript
+exec(prompt: string, options?: ExecOptions): Promise<TurnResult>
+```
+
+Executes a single prompt without maintaining conversation state.
+
+<ParamField path="prompt" type="string" required>
+  The natural language prompt to execute.
+</ParamField>
+<ParamField path="options" type="ExecOptions" optional>
+  Execution options including model, output schema, etc.
+</ParamField>
+
+**Returns:** A promise resolving to the execution result.
+
+**Throws:**
+- `ExecutionError` - If the CLI execution fails
+- `TimeoutError` - If the operation exceeds the configured timeout
+- `CliNotFoundError` - If the Droid CLI is not installed
+
+```typescript
+const result = await droid.exec('Generate a UUID');
+console.log(result.finalResponse);
+```
+
+### listTools()
+
+```typescript
+listTools(model?: string): Promise<string[]>
+```
+
+Lists all available tools for the configured or specified model.
+
+<ParamField path="model" type="string" optional>
+  Model ID to query tools for (defaults to instance model).
+</ParamField>
+
+**Returns:** A promise resolving to an array of tool names.
+
+```typescript
+const tools = await droid.listTools();
+console.log('Available tools:', tools);
+// ['file_read', 'file_write', 'shell_exec', ...]
+```
+
+## Full Example
+
+```typescript
+import { Droid, MODELS } from '@activade/droid-sdk';
+import { z } from 'zod';
+
+const droid = new Droid({
+  model: MODELS.CLAUDE_SONNET,
+  autonomyLevel: 'high',
+  cwd: './my-project'
+});
+
+// One-shot execution
+const result = await droid.exec('Create a hello world function');
+console.log(result.finalResponse);
+
+// Multi-turn conversation
+const thread = droid.startThread();
+await thread.run('Create a React component');
+await thread.run('Add unit tests for it');
+
+// Structured output
+const schema = z.object({
+  name: z.string(),
+  version: z.string()
+});
+
+const pkgResult = await droid.exec('Get package info as JSON');
+const pkg = pkgResult.parse(schema);
+console.log(pkg.name, pkg.version);
+```