@phpsandbox/sdk 0.0.16 → 0.0.17

package/README.md

@@ -1,46 +1,6 @@
 # PHPSandbox SDK
 
-A comprehensive TypeScript SDK for interacting with cloud-based PHP development environments. The PHPSandbox SDK provides programmatic access to containerized PHP environments with full filesystem, terminal, and development tool integration.
-
-## Table of Contents
-
-- [PHPSandbox SDK](#phpsandbox-sdk)
-  - [Table of Contents](#table-of-contents)
-  - [Installation](#installation)
-  - [Quick Start](#quick-start)
-  - [Authentication](#authentication)
-  - [Core Concepts](#core-concepts)
-    - [Client](#client)
-    - [NotebookInstance](#notebookinstance)
-    - [Event-Driven Architecture](#event-driven-architecture)
-  - [API Reference](#api-reference)
-    - [Client](#client-1)
-      - [NotebookApi Methods](#notebookapi-methods)
-    - [NotebookInstance](#notebookinstance-1)
-    - [Filesystem](#filesystem)
-      - [File Search Example](#file-search-example)
-    - [Terminal](#terminal)
-      - [Terminal Usage Example](#terminal-usage-example)
-    - [Container](#container)
-    - [Language Server Protocol (LSP)](#language-server-protocol-lsp)
-    - [Composer](#composer)
-    - [Git](#git)
-    - [Laravel](#laravel)
-    - [REPL](#repl)
-    - [Shell](#shell)
-    - [Auth](#auth)
-    - [Logging](#logging)
-  - [Event System](#event-system)
-  - [Error Handling](#error-handling)
-    - [Common Error Types](#common-error-types)
-  - [Examples](#examples)
-    - [Complete Laravel Application Setup](#complete-laravel-application-setup)
-    - [File Processing Pipeline](#file-processing-pipeline)
-    - [Real-time Development Environment](#real-time-development-environment)
-  - [TypeScript Support](#typescript-support)
-    - [Generic Types](#generic-types)
-  - [Support and Contributing](#support-and-contributing)
-  - [License](#license)
+TypeScript SDK for working with PHPSandbox notebooks: create environments, edit files, run commands, and stream real-time events.
 
 ## Installation
 
@@ -48,691 +8,222 @@ A comprehensive TypeScript SDK for interacting with cloud-based PHP development
 npm install @phpsandbox/sdk
 ```
 
+Node.js `>=18` is required.
+
 ## Quick Start
 
-```typescript
+```ts
 import { PHPSandbox } from '@phpsandbox/sdk';
 
-// Create a client instance
-const client = new PHPSandbox('your-api-token');
-
-// Create and initialize a new notebook
-const notebook = await client.notebook.create('laravel');
+const token = process.env.PHPSANDBOX_TOKEN;
+if (!token) throw new Error('Missing PHPSANDBOX_TOKEN');
 
-// Access various services
-const files = notebook.file;
-const terminal = notebook.terminal;
-const container = notebook.container;
+const client = new PHPSandbox(token);
 
-// Write a PHP file
-await files.write('index.php', '<?php echo "Hello World!"; ?>');
+// create() initializes the notebook by default
+const notebook = await client.notebook.create('php');
 
-// Execute a command
-const process = await terminal.spawn('php', ['index.php']);
-process.output
-  .getReader()
-  .read()
-  .then(({ value }) => {
-    console.log(value); // "Hello World!"
-  });
-```
-
-## Authentication
+await notebook.file.write('index.php', '<?php echo "Hello from PHPSandbox";');
 
-The SDK requires an API token for authentication:
+const process = await notebook.terminal.spawn('php', ['index.php']);
 
-```typescript
-// Using environment variable (recommended)
-const client = new PHPSandbox(process.env.PHPSANDBOX_TOKEN);
+const reader = process.output.getReader();
+let output = '';
+try {
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    output += value;
+  }
+} finally {
+  reader.releaseLock();
+}
 
-// Or direct token
-const client = new PHPSandbox('your-token-here');
+await process.exit;
+console.log(output.trim());
 
-// Custom API URL (optional)
-const client = new PHPSandbox('token', 'https://api.phpsandbox.io/v1');
+// close websocket resources when done
+notebook.dispose();
 ```
 
-## Core Concepts
-
-### Client
+## Authentication
 
-The main entry point for the SDK. Handles authentication and provides access to notebook management.
+Use an API token:
 
-### NotebookInstance
+```ts
+import { PHPSandbox } from '@phpsandbox/sdk';
 
-Represents a containerized PHP environment with access to all development tools:
+const client = new PHPSandbox(process.env.PHPSANDBOX_TOKEN!);
+```
 
-- **Filesystem**: File operations, search, and monitoring
-- **Terminal**: Interactive terminal and process execution
-- **Container**: Environment management and monitoring
-- **LSP**: Language server integration for IDE features
-- **Development Tools**: Composer, Git, Laravel tooling, REPL
+Optional constructor args:
 
-### Event-Driven Architecture
+```ts
+new PHPSandbox('token', 'https://api.phpsandbox.io/v1', {
+  debug: false,
+  startClosed: true,
+});
+```
 
-The SDK uses WebSocket connections for real-time communication and events.
+## Notebook Lifecycle
 
-## API Reference
+```ts
+const client = new PHPSandbox(process.env.PHPSANDBOX_TOKEN!);
 
-### Client
+const created = await client.notebook.create('laravel');
+const opened = await client.notebook.open('notebook-id');
+await opened.ready();
 
-```typescript
-class PHPSandbox {
-  constructor(token: string, url?: string, options?: PHPSandboxClientOptions);
+const fetched = await client.notebook.get('notebook-id');
+await fetched.ready();
 
-  readonly notebook: NotebookApi;
-  readonly http: AxiosInstance;
-}
+const forked = await created.fork();
+await forked.delete();
 ```
 
-#### NotebookApi Methods
+Notes:
 
-```typescript
-// Create a new notebook from a template
-create(template: string, input?: Partial<CreateNotebookInput>, init?: boolean): Promise<NotebookInstance>
+- `create()` and `fork()` initialize automatically.
+- `open()` and `get()` return a notebook instance; call `await notebook.ready()` before using tools.
 
-// Get existing notebook by ID
-get(id: string): Promise<NotebookInstance>
+## Services At A Glance
 
-// Fork an existing notebook
-fork(id: string): Promise<NotebookInstance>
+Each `NotebookInstance` exposes service clients:
 
-// Open and initialize a notebook
-open(id: string): Promise<NotebookInstance>
+- `notebook.file` (`Filesystem`)
+- `notebook.terminal` (`Terminal`)
+- `notebook.container` (`Container`)
+- `notebook.shell` (`Shell`)
+- `notebook.composer` (`Composer`)
+- `notebook.git` (`Git`)
+- `notebook.lsp` (`Lsp`)
+- `notebook.repl` (`Repl`)
+- `notebook.laravel` (`Laravel`)
+- `notebook.auth` (`Auth`)
+- `notebook.log` (`Log`)
 
-// Create from existing data
-openFromData(data: NotebookData): Promise<NotebookInstance>
-```
+## Common Operations
 
-#### Create Notebook from GitHub Repository
-
-```typescript
-const notebook = await client.notebook.create(
-  'php',
-  {
-    title: 'Imported Repo',
-    import: {
-      provider: 'github',
-      repo: 'https://github.com/acme/private-repo.git',
-      branch: 'main',
-      auth: {
-        access_token: process.env.GITHUB_TOKEN!,
-      },
-    },
-  },
-  false
-);
-```
+### Files
 
-### NotebookInstance
-
-The core class providing access to all development environment features.
-
-```typescript
-class NotebookInstance {
-  // Core services
-  readonly file: Filesystem;
-  readonly terminal: Terminal;
-  readonly container: Container;
-  readonly lsp: Lsp;
-  readonly composer: Composer;
-  readonly git: Git;
-  readonly laravel: Laravel;
-  readonly repl: Repl;
-  readonly shell: Shell;
-  readonly auth: Auth;
-  readonly log: Log;
-
-  // Connection management
-  ready(): Promise<NotebookInitResult>;
-  connected(): Promise<NotebookInstance>;
-  reconnect(): void;
-  dispose(): void;
-
-  // Event handling
-  listen<T extends keyof Events>(event: T, handler: (data: Events[T]) => void): Disposable;
-  onDidConnect(handler: () => void): Disposable;
-  onDidDisconnect(handler: () => void): Disposable;
-
-  // Direct API calls
-  invoke<T extends keyof Invokable>(
-    action: T,
-    data?: Invokable[T]['args'],
-    options?: CallOption
-  ): Promise<Invokable[T]['response']>;
-}
-```
-
-### Filesystem
-
-Comprehensive file system operations with advanced search and monitoring capabilities.
-
-```typescript
-class Filesystem {
-  // File operations
-  readFile(path: string, lineRange?: { lineStart: number; lineEnd: number }): Promise<Uint8Array | ReadFileRangeResult>;
-  writeFile(path: string, contents: Uint8Array, options: FileWriteOptions): Promise<void>;
-  info(path: string): Promise<FileInfo>;
-  stat(path: string): Promise<Stats>;
-  exists(path: string): Promise<boolean>;
-
-  // Directory operations
-  createDirectory(path: string): Promise<void>;
-  readDirectory(path: string, include?: string[], exclude?: string[]): Promise<[string, FileType, number | null][]>;
-
-  // File management
-  copy(source: string, destination: string, options: FileOverwriteOptions): Promise<void>;
-  move(from: string, to: string): Promise<boolean>;
-  rename(from: string, to: string, options: FileOverwriteOptions): Promise<void>;
-  delete(path: string, options: FileDeleteOptions): Promise<void>;
-
-  // Search capabilities
-  find(query: string, options?: Partial<FileSearchOptions>): Promise<FileResult[]>;
-  search(
-    query: TextSearchQuery,
-    options?: Partial<TextSearchOptions>,
-    onMatch?: (result: TextSearchResult | false) => void
-  ): Promise<[boolean, TextSearchMatch[]]>;
-
-  // File monitoring
-  watch(path: string, options: WatchOptions, onDidChange: (e: FileChange) => void): FilesystemSubscription;
-
-  // Bulk operations
-  download(chunk?: (data: Uint8Array) => void, exclude?: string[]): Promise<Blob>;
-}
-```
+```ts
+await notebook.file.write('README.md', '# App');
 
-#### File Search Example
+const raw = await notebook.file.readFile('README.md');
+const text = new TextDecoder().decode(raw);
 
-```typescript
-// Find files by name
-const phpFiles = await notebook.file.find('*.php', {
-  includes: ['src/**'],
+const files = await notebook.file.find('*.php', {
+  includes: ['app/**'],
   excludes: ['vendor/**'],
-  useIgnoreFiles: true,
 });
 
-// Full-text search with context
 const [hasMore, matches] = await notebook.file.search(
-  { pattern: 'function.*authenticate', isRegExp: true },
-  { maxResults: 50, beforeContext: 2, afterContext: 2 }
+  { pattern: 'class\\s+User', isRegExp: true },
+  { maxResults: 20, includes: ['app/**'], excludes: ['vendor/**'] }
 );
 ```
 
 ### Terminal
 
-Interactive terminal with process execution and stream handling.
-
-```typescript
-class Terminal {
-  // Terminal management
-  create(input: TerminalCreateInput): Promise<Task>;
-  list(): Promise<Task[]>;
-  resize(id: string, size: [number, number]): Promise<boolean>;
-  input(id: string, input: string): Promise<void>;
-
-  // Process execution
-  spawn(command: string, args: string[], opts?: SpawnOptions): Promise<SandboxProcess & Task>;
-
-  // Event handling
-  onStarted(handler: (task: Task) => void): void;
-  onOutput(id: string, handler: (data: TerminalEvents['terminal.output']) => void): void;
-  listen<T extends keyof TerminalEvents>(event: T, handler: (data: TerminalEvents[T]) => void): Disposable;
-}
-```
-
-#### Terminal Usage Example
+```ts
+const task = await notebook.terminal.spawn('composer', ['--version']);
 
-```typescript
-// Spawn a process with I/O streams
-const process = await notebook.terminal.spawn('composer', ['install'], {
-  cwd: '/app',
-  env: { COMPOSER_NO_INTERACTION: '1' },
-});
-
-// Handle output stream
-const reader = process.output.getReader();
-while (true) {
-  const { done, value } = await reader.read();
-  if (done) break;
+task.output.getReader().read().then(({ value }) => {
   console.log(value);
-}
-
-// Wait for completion
-const exitCode = await process.exit;
-console.log(`Process exited with code: ${exitCode}`);
-```
-
-### Container
-
-Container lifecycle and resource management.
-
-```typescript
-class Container {
-  // Container control
-  start(): Promise<void>;
-  stop(): Promise<void>;
-  state(): Promise<{ state: NotebookState }>;
-
-  // Port management
-  openedPorts(): Promise<PortInfo[]>;
-  onPort(handler: (port: PortInfo, type: 'open' | 'close') => void): Disposable;
-
-  // Environment configuration
-  setPhp(version: string): Promise<{ version: string }>;
+});
 
-  // Resource monitoring
-  listen<T extends keyof ContainerEvents>(event: T, handler: (data: ContainerEvents[T]) => void): void;
-}
+const exitCode = await task.exit;
+console.log(exitCode);
 ```
 
-### Language Server Protocol (LSP)
-
-IDE-like features through Language Server Protocol integration.
-
-```typescript
-class Lsp {
-  // Connection management
-  connection(id: string): LspConnection;
-  start(id: string): Promise<void>;
-  close(id: string): Promise<void>;
-
-  // Communication
-  message(id: string, message: string): Promise<void>;
-
-  // Event handling
-  onResponse(id: string, cb: (data: string) => void): void;
-  onError(id: string, cb: (message: string) => void): void;
-  onClose(id: string, cb: (code: number, reason: string) => void): void;
-}
+### Shell
 
-class LspConnection {
-  send(content: string): Promise<void>;
-  onMessage(cb: (data: string) => void): void;
-  onError(cb: (message: string) => void): void;
-  onClose(cb: (code: number, reason: string) => void): void;
-  start(): Promise<void>;
-  dispose(): void;
-}
+```ts
+const result = await notebook.shell.exec('php -v');
+result.throw();
+console.log(result.output);
 ```
 
 ### Composer
 
-PHP dependency management integration.
-
-```typescript
-class Composer {
-  // Package management
-  install(packages?: string[]): Promise<void>;
-  update(packages?: string[]): Promise<void>;
-  remove(packages: string[]): Promise<void>;
+```ts
+await notebook.composer.install({ noInteraction: true });
+await notebook.composer.require({ packages: ['monolog/monolog'] });
 
-  // Project operations
-  init(options?: ComposerInitOptions): Promise<void>;
-  validate(): Promise<void>;
-
-  // Information
-  show(package?: string): Promise<object>;
-  outdated(): Promise<object>;
-
-  // Event handling
-  listen<T extends keyof ComposerEvents>(event: T, handler: (data: ComposerEvents[T]) => void): Disposable;
-}
+const installed = await notebook.composer.packages();
+console.log(installed.map((pkg) => pkg.name));
 ```
 
 ### Git
 
-Version control operations and repository management.
-
-```typescript
-class Git {
-  // Repository operations
-  init(): Promise<void>;
-  clone(url: string, directory?: string): Promise<void>;
-
-  // Branch management
-  branch(name?: string): Promise<string[] | void>;
-  checkout(branch: string): Promise<void>;
-
-  // Staging and commits
-  add(files: string[]): Promise<void>;
-  commit(message: string): Promise<void>;
-  push(remote?: string, branch?: string): Promise<void>;
-  pull(remote?: string, branch?: string): Promise<void>;
-
-  // Information
-  status(): Promise<GitStatus>;
-  log(options?: GitLogOptions): Promise<GitCommit[]>;
-  diff(options?: GitDiffOptions): Promise<string>;
-
-  // Event handling
-  listen<T extends keyof GitEvents>(event: T, handler: (data: GitEvents[T]) => void): Disposable;
-}
-```
-
-### Laravel
-
-Laravel-specific development tools and utilities.
-
-```typescript
-class Laravel {
-  // Artisan commands
-  artisan(command: string, args?: string[]): Promise<void>
-
-  // Code generation
-  make(type: string, name: string, options?: object): Promise<void>
-
-  // Database operations
-  migrate(options?: MigrateOptions): Promise<void>
-  seed(class?: string): Promise<void>
-
-  // Cache management
-  cache(action: 'clear' | 'config' | 'route' | 'view'): Promise<void>
-
-  // Event handling
-  listen<T extends keyof LaravelEvents>(event: T, handler: (data: LaravelEvents[T]) => void): Disposable
-}
-```
-
-### REPL
-
-Interactive PHP execution environment.
-
-```typescript
-class Repl {
-  // Code execution
-  execute(code: string): Promise<ReplResult>;
+```ts
+await notebook.git.checkpoint('Jane Doe <jane@example.com>', 'Initial checkpoint');
 
-  // Session management
-  reset(): Promise<void>;
-
-  // Variable inspection
-  variables(): Promise<object>;
-
-  // Event handling
-  listen<T extends keyof ReplEvents>(event: T, handler: (data: ReplEvents[T]) => void): Disposable;
-}
-```
-
-### Shell
-
-Shell command execution with customizable environments.
-
-```typescript
-class Shell {
-  // Command execution
-  execute(command: string, options?: ShellOptions): Promise<ShellResult>;
-
-  // Environment management
-  setEnv(variables: Record<string, string>): Promise<void>;
-  getEnv(): Promise<Record<string, string>>;
-
-  // Working directory
-  pwd(): Promise<string>;
-  cd(directory: string): Promise<void>;
-
-  // Event handling
-  listen<T extends keyof ShellEvents>(event: T, handler: (data: ShellEvents[T]) => void): Disposable;
-}
-```
-
-### Auth
-
-Authentication and authorization services.
-
-```typescript
-class Auth {
-  // Token management
-  login(credentials: LoginCredentials): Promise<AuthResult>;
-  logout(): Promise<void>;
-  refresh(): Promise<AuthResult>;
-
-  // User information
-  user(): Promise<User>;
-
-  // Permissions
-  can(permission: string): Promise<boolean>;
-}
-```
-
-### Logging
-
-Application logging and monitoring.
-
-```typescript
-class Log {
-  // Log levels
-  debug(message: string, context?: object): Promise<void>;
-  info(message: string, context?: object): Promise<void>;
-  warning(message: string, context?: object): Promise<void>;
-  error(message: string, context?: object): Promise<void>;
-
-  // Log retrieval
-  recent(limit?: number): Promise<LogEntry[]>;
-  search(query: string, options?: LogSearchOptions): Promise<LogEntry[]>;
+await notebook.git.sync(
+  'https://github.com/acme/my-repo.git',
+  'Jane Doe <jane@example.com>',
+  'main',
+  process.env.GITHUB_TOKEN,
+  'pull'
+);
 
-  // Event handling
-  listen<T extends keyof LogEvents>(event: T, handler: (data: LogEvents[T]) => void): Disposable;
-}
+const history = await notebook.git.log('main');
+console.log(history[0]);
 ```
 
-## Event System
-
-The SDK provides a comprehensive event system for real-time updates:
-
-```typescript
-// File system events
-notebook.file.watch('/app', { recursive: true }, (change) => {
-  console.log(`File ${change.path} was ${change.type}`);
-});
-
-// Terminal output
-notebook.terminal.onOutput('terminal-id', (data) => {
-  console.log(data.output);
-});
+### Events
 
-// Container stats
-notebook.container.listen('container.stats', (stats) => {
-  console.log(`CPU: ${stats.cpu.usage}/${stats.cpu.limit}`);
+```ts
+const disposeConnect = notebook.onDidConnect(() => {
+  console.log('connected');
 });
 
-// Connection events
-notebook.onDidConnect(() => {
-  console.log('Connected to notebook');
-});
+const disposeFs = notebook.file.watch(
+  '/app',
+  { recursive: true, excludes: ['vendor/**', 'node_modules/**'] },
+  (change) => {
+    console.log(change.type, change.path);
+  }
+);
 
-notebook.onDidDisconnect(() => {
-  console.log('Disconnected from notebook');
-});
+// later
+disposeConnect.dispose();
+disposeFs.dispose();
 ```
 
 ## Error Handling
 
-The SDK provides structured error handling with specific error types:
-
-```typescript
-import { FilesystemError, FilesystemErrorType, ErrorEvent } from '@phpsandbox/sdk';
+```ts
+import { ApiError, FilesystemError, FilesystemErrorType } from '@phpsandbox/sdk';
 
 try {
-  await notebook.file.readFile('/nonexistent.php');
+  await notebook.file.readFile('/does-not-exist.php');
 } catch (error) {
   if (error instanceof FilesystemError && error.name === FilesystemErrorType.FileNotFound) {
-    console.log('File not found');
-  } else if (error instanceof ErrorEvent) {
-    console.log(`Error ${error.code}: ${error.message}`);
+    console.error('Missing file');
+  } else if (error instanceof ApiError) {
+    console.error(error.status, error.body);
+  } else {
+    throw error;
   }
 }
 ```
 
-### Common Error Types
-
-- `FilesystemError`: File system operation errors
-- `RateLimitError`: API rate limiting
-- `NotebookInitError`: Notebook initialization failures
-- `ErrorEvent`: Base error class with error codes
+## Browser/CDN Usage
 
-## Examples
+See `docs/cdn-usage.md` for ESM and script-tag examples.
 
-### Complete Laravel Application Setup
+## More Docs
 
-```typescript
-import { PHPSandbox } from '@phpsandbox/sdk';
-
-async function setupLaravelApp() {
-  const client = new PHPSandbox(process.env.PHPSANDBOX_TOKEN);
-  const notebook = await client.notebook.create('laravel');
-
-  // Wait for container to be ready
-  await notebook.ready();
-
-  // Install additional dependencies
-  await notebook.composer.install(['laravel/sanctum', 'laravel/horizon']);
-
-  // Create a new controller
-  await notebook.laravel.make('controller', 'ApiController', { resource: true });
-
-  // Run migrations
-  await notebook.laravel.migrate();
-
-  // Set up Git repository
-  await notebook.git.init();
-  await notebook.git.add(['.']);
-  await notebook.git.commit('Initial commit');
-
-  // Start development server
-  const server = await notebook.terminal.spawn('php', ['artisan', 'serve', '--host=0.0.0.0']);
-
-  // Monitor for open ports
-  notebook.container.onPort((port, type) => {
-    if (type === 'open' && port.port === 8000) {
-      console.log(`Laravel server available at: ${port.url}`);
-    }
-  });
-
-  return notebook;
-}
-```
-
-### File Processing Pipeline
-
-```typescript
-async function processPhpFiles(notebook: NotebookInstance) {
-  // Find all PHP files
-  const phpFiles = await notebook.file.find('*.php', {
-    includes: ['app/**', 'src/**'],
-    excludes: ['vendor/**', 'node_modules/**'],
-  });
-
-  // Process each file
-  for (const file of phpFiles) {
-    const content = await notebook.file.readFile(file.path);
-
-    // Run PHP CS Fixer
-    await notebook.terminal.spawn('php-cs-fixer', ['fix', file.path]);
-
-    // Run static analysis
-    const analysis = await notebook.terminal.spawn('phpstan', ['analyse', file.path]);
-
-    // Wait for completion
-    await analysis.exit;
-  }
-
-  console.log(`Processed ${phpFiles.length} PHP files`);
-}
-```
-
-### Real-time Development Environment
-
-```typescript
-async function createDevelopmentEnvironment() {
-  const client = new PHPSandbox(process.env.PHPSANDBOX_TOKEN);
-  const notebook = await client.notebook.create('php');
-
-  // Set up file watching
-  notebook.file.watch('/app', { recursive: true }, (change) => {
-    console.log(`[${new Date().toISOString()}] ${change.path} ${change.type}`);
-
-    // Auto-reload on PHP file changes
-    if (change.path.endsWith('.php') && change.type === 'UPDATED') {
-      notebook.repl.execute(`include '${change.path}';`);
-    }
-  });
-
-  // Set up LSP for IDE features
-  const lspConnection = notebook.lsp.connection('php-lsp');
-  await lspConnection.start();
-
-  lspConnection.onMessage((message) => {
-    const data = JSON.parse(message);
-    if (data.method === 'textDocument/publishDiagnostics') {
-      console.log('Diagnostics:', data.params.diagnostics);
-    }
-  });
-
-  // Monitor container resources
-  notebook.container.listen('container.stats', (stats) => {
-    if (stats.memory.usage / stats.memory.limit > 0.8) {
-      console.warn('High memory usage detected');
-    }
-  });
-
-  return notebook;
-}
-```
-
-## TypeScript Support
-
-The SDK is built with TypeScript and provides comprehensive type definitions:
-
-```typescript
-import type {
-  NotebookInstance,
-  FileInfo,
-  Stats,
-  TextSearchQuery,
-  TerminalCreateInput,
-  ContainerStats,
-  Events,
-  FilesystemEvents,
-} from '@phpsandbox/sdk';
-
-// Type-safe event handling
-notebook.listen('fs.watch', (change: Events['fs.watch']) => {
-  // change is properly typed as FileChange
-  console.log(change.path, change.type);
-});
-
-// Type-safe API calls
-const stats: Stats = await notebook.file.stat('/app/composer.json');
-const info: FileInfo = await notebook.file.info('/app/index.php');
-```
-
-### Generic Types
-
-```typescript
-// Custom event handlers
-type CustomEventHandler<T extends keyof Events> = (data: Events[T]) => void;
-
-// Action types
-type FileSystemActions = FilesystemActions;
-type TerminalActions = TerminalActions;
-
-// Disposable pattern
-const disposable: Disposable = notebook.onDidConnect(() => {
-  console.log('Connected');
-});
-
-// Clean up when done
-disposable.dispose();
-```
+- Getting started walkthrough: `docs/getting-started.md`
+- API overview: `docs/api-summary.md`
+- Examples: `examples/README.md`
 
-## Support and Contributing
+## Support
 
-- **Documentation**: [https://docs.phpsandbox.io](https://docs.phpsandbox.io)
-- **API Reference**: [https://api.phpsandbox.io/docs](https://api.phpsandbox.io/docs)
-- **Issues**: [GitHub Issues](https://github.com/phpsandbox/sdk/issues)
-- **Examples**: [GitHub Examples](https://github.com/phpsandbox/examples)
+- Issues: https://github.com/phpsandbox/sdk/issues
+- Product docs: https://docs.phpsandbox.io
 
 ## License
 
-MIT License - see LICENSE file for details.
+MIT