memory-journal-mcp 7.7.0 → 8.0.0

package/skills/playwright-standard/SKILL.md

@@ -1,11 +1,10 @@
 ---
 name: playwright-standard
 description: |
-  Comprehensive, opinionated guidance for Playwright test development. Use when
-  writing E2E, API, component, or visual tests, debugging failures, implementing
-  Page Object Model, or configuring CI/CD. Includes "Golden Rules" for resilient
-  tests and provides on-demand reference for specialized scenarios (Electron,
-  WebSockets, mobile, security audits).
+  Comprehensive, opinionated guidance for Playwright test development. Use ONLY when
+  writing E2E, browser tests, UI tests, API, component, or visual tests, debugging failures, implementing
+  Page Object Model, or configuring CI/CD. For unit tests, use vitest-standard. Use Playwright solely for E2E, API, and component tests. NOT for unit testing (use Vitest).
+  If the user asks to "write tests" without specifying the type, you MUST ask "Unit, E2E, or both?" before proceeding.
 ---
 
 # Playwright Standard
@@ -20,7 +19,7 @@ This skill combines battle-tested coding standards with industrial-scale infrast
 4.  **Isolate every test** — Every test must run independently in any order (no shared state).
 5.  **Fixtures over globals** — Share state via `test.extend()`, not module-level variables.
 6.  **`baseURL` in config** — ZERO hardcoded URLs in test files.
-7.  **Auth: Reuse storage state** — Use `browserContext.storageState` to avoid UI login in every test.
+7.  **Auth: Reuse storage state** — Use `browserContext.storageState` to avoid UI login in every test. Store `storageState` files in `.gitignore`d paths (e.g., `playwright/.auth/`). Never commit auth state files to version control.
 8.  **Network: Mock third-party only** — Never mock your own app; mock external APIs, gateways, and emails.
 9.  **Traces: `'on-first-retry'`** — High-fidelity debugging without CI performance penalties.
 10. **One behavior per test** — Avoid "mega-tests": keep focus narrow and assertions meaningful.
@@ -29,11 +28,7 @@ This skill combines battle-tested coding standards with industrial-scale infrast
 
 ### Locators Priority
 
-1.  **Role**: `page.getByRole('button', { name: 'Submit' })`
-2.  **Label**: `page.getByLabel('User Name')`
-3.  **Placeholder**: `page.getByPlaceholder('Search...')`
-4.  **Text**: `page.getByText('Success')`
-5.  **TestID**: `page.getByTestId('submit-btn')` (Last resort)
+See **[locators.md](references/locators.md)** for the strict hierarchy of Playwright locator strategies (Role > Label > TestID).
 
 ### Synchronization
 

package/skills/playwright-standard/references/locators.md

@@ -0,0 +1,7 @@
+# Playwright Locators Priority
+
+1.  **Role**: `page.getByRole('button', { name: 'Submit' })`
+2.  **Label**: `page.getByLabel('User Name')`
+3.  **Placeholder**: `page.getByPlaceholder('Search...')`
+4.  **Text**: `page.getByText('Success')`
+5.  **TestID**: `page.getByTestId('submit-btn')` (Last resort)

package/skills/postgres/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: postgres
-description: Enterprise PostgreSQL production rules — advanced querying, indexing, JSONB data, and strict optimization patterns.
+description: |
+  Use when designing, querying, or managing a PostgreSQL database.
+  Enforces enterprise production rules for advanced querying, composite indexing, 
+  JSONB data handling, and strict optimization patterns (avoiding N+1).
+  Keywords: PostgreSQL query, JSONB, pg, pgvector, RLS, Postgres migration.
+  MUST-ASK: Require explicit database engine name before triggering. Never guess. Do NOT trigger for generic "set up a database" requests. NOT for SQLite or MySQL. NOT for ORM-managed migrations.
 ---
 
 # PostgreSQL Production Standards

package/skills/python/SKILL.md

@@ -5,7 +5,7 @@ description: |
   Use when writing Python code, configuring project structure, managing
   dependencies with uv, linting with ruff, adding type hints, writing pytest
   tests, or building FastAPI/Django/Flask applications. Triggers on "Python",
-  "FastAPI", "Django", "Flask", "pytest", "uv", "ruff", "pyproject.toml".
+  "FastAPI", "Django", "Flask", "pytest", "uv", "ruff", "pyproject.toml". Do NOT trigger for generic 'build a server' requests unless the platform/language is explicitly specified as Python (e.g. FastAPI, Django, Flask).
 ---
 
 # Python Engineering Standards
@@ -55,30 +55,7 @@ my-project/
 
 ### `pyproject.toml` Configuration (PEP 621)
 
-```toml
-[project]
-name = "my-package"
-version = "0.1.0"
-requires-python = ">=3.12"
-dependencies = [
-    "httpx>=0.27",
-    "pydantic>=2.0",
-]
-
-[project.optional-dependencies]
-dev = ["pytest>=8.0", "ruff>=0.8", "mypy>=1.13"]
-
-[tool.ruff]
-target-version = "py312"
-line-length = 88
-
-[tool.ruff.lint]
-select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
-
-[tool.pytest.ini_options]
-testpaths = ["tests"]
-pythonpath = ["src"]
-```
+See `references/config-templates.md` for the standard `pyproject.toml` template.
 
 ## 2. Type Hints (Mandatory)
 
@@ -124,23 +101,7 @@ ruff format .         # Format (replaces Black)
 
 ### Configuration in `pyproject.toml`
 
-```toml
-[tool.ruff]
-target-version = "py312"
-line-length = 88
-src = ["src", "tests"]
-
-[tool.ruff.lint]
-select = [
-    "E",    # pycodestyle errors
-    "F",    # pyflakes
-    "I",    # isort
-    "UP",   # pyupgrade
-    "B",    # bugbear
-    "SIM",  # simplify
-    "RUF",  # ruff-specific
-]
-```
+See `references/config-templates.md` for the standard Ruff configuration.
 
 - **NEVER** use `# noqa` to suppress linter errors unless the suppression is explicitly justified by a comment explaining _why_.
 - **NEVER** use `# type: ignore` — fix the type error or use a proper type guard.
@@ -208,36 +169,13 @@ uv run pytest -k "test_user"            # Run by pattern
 uv run pytest --cov=src --cov-report=term-missing  # Coverage
 ```
 
-## 6. Async & Concurrency
-
-- **Use `asyncio`** for I/O-bound concurrency (HTTP calls, DB queries)
-- **Use `async def` / `await`** — never mix sync and async code paths
-- **Use `asyncio.TaskGroup`** (Python 3.11+) for structured concurrency
-- **Use `httpx`** (async-native) instead of `requests` for HTTP clients
-
-```python
-async with asyncio.TaskGroup() as tg:
-    task1 = tg.create_task(fetch_user(user_id))
-    task2 = tg.create_task(fetch_orders(user_id))
-# Both tasks complete here — exceptions propagate cleanly
-```
-
-## 7. Data Validation: Pydantic v2
+## 6. Advanced Patterns & Security
 
-- **Use Pydantic models** at system boundaries (API requests, config files, DB results)
-- **Never trust external input** — validate with `model_validate()`, not dict access
-- **Use `Field()` validators** for constraints, not manual `if` checks
+For advanced guidance on `asyncio` concurrency, Pydantic v2 data validation, and Python security best practices, see the reference file:
 
-```python
-from pydantic import BaseModel, Field
-
-class CreateUserRequest(BaseModel):
-    name: str = Field(min_length=1, max_length=100)
-    email: str = Field(pattern=r"^[\w.-]+@[\w.-]+\.\w+$")
-    age: int = Field(ge=0, le=150)
-```
+**[Read: references/advanced-patterns.md](references/advanced-patterns.md)**
 
-## 8. Anti-Patterns (Never Do These)
+## 9. Anti-Patterns (Never Do These)
 
 | Anti-Pattern                         | Why It's Wrong                     | Do This Instead              |
 | ------------------------------------ | ---------------------------------- | ---------------------------- |
@@ -248,7 +186,7 @@ class CreateUserRequest(BaseModel):
 | `print()` for logging                | No levels, no rotation             | Use `logging` or `structlog` |
 | `== None` / `== True`                | Wrong semantics                    | `is None` / `is True`        |
 
-## 9. Web Frameworks Quick Reference
+## 10. Web Frameworks Quick Reference
 
 | Framework   | Best For                     | Key Pattern                                               |
 | ----------- | ---------------------------- | --------------------------------------------------------- |

package/skills/python/references/advanced-patterns.md

@@ -0,0 +1,37 @@
+# Advanced Python Patterns
+
+## Async & Concurrency
+
+- **Use `asyncio`** for I/O-bound concurrency (HTTP calls, DB queries)
+- **Use `async def` / `await`** — never mix sync and async code paths
+- **Use `asyncio.TaskGroup`** (Python 3.11+) for structured concurrency
+- **Use `httpx`** (async-native) instead of `requests` for HTTP clients
+
+```python
+async with asyncio.TaskGroup() as tg:
+    task1 = tg.create_task(fetch_user(user_id))
+    task2 = tg.create_task(fetch_orders(user_id))
+# Both tasks complete here — exceptions propagate cleanly
+```
+
+## Data Validation: Pydantic v2
+
+- **Use Pydantic models** at system boundaries (API requests, config files, DB results)
+- **Never trust external input** — validate with `model_validate()`, not dict access
+- **Use `Field()` validators** for constraints, not manual `if` checks
+
+```python
+from pydantic import BaseModel, Field
+
+class CreateUserRequest(BaseModel):
+    name: str = Field(min_length=1, max_length=100)
+    email: str = Field(pattern=r"^[\w.-]+@[\w.-]+\.\w+$")
+    age: int = Field(ge=0, le=150)
+```
+
+## Security & Safety
+
+- **SQL Injection**: Never use string interpolation for SQL queries. Use an ORM (SQLAlchemy, Django ORM) or parameterized queries (e.g., `cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))`).
+- **Secrets Management**: Never commit `.env` files or hardcode credentials. Use `python-decouple` or `os.environ` to read secrets from the environment.
+- **CSRF & Auth**: Always enable CSRF protection in web frameworks (e.g., `CsrfViewMiddleware` in Django).
+- **Input Validation**: Validate all untrusted input at the boundaries using Pydantic models.

package/skills/python/references/config-templates.md

@@ -0,0 +1,48 @@
+# Python Config Templates
+
+## `pyproject.toml` Configuration (PEP 621)
+
+```toml
+[project]
+name = "my-package"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "ruff>=0.8", "mypy>=1.13"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+```
+
+## Ruff Configuration in `pyproject.toml`
+
+```toml
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "F",    # pyflakes
+    "I",    # isort
+    "UP",   # pyupgrade
+    "B",    # bugbear
+    "SIM",  # simplify
+    "RUF",  # ruff-specific
+]
+```

package/skills/rag-pipelines/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: rag-pipelines
+description: |
+  Best practices for Retrieval-Augmented Generation (RAG) pipelines. Use when working with vector databases, embeddings, chunking strategies, semantic search, or hybrid search architectures.
+---
+
+# RAG Pipelines
+
+## Core Concepts
+
+- **Chunking**: Chunk by semantics or document structure, not just fixed lengths. Avoid naive character-based chunking. Use semantic chunking (splitting at sentence/paragraph boundaries) or structure-aware chunking (e.g., Markdown header splitting).
+- **Embeddings**: Select appropriate models (e.g. text-embedding-3-small).
+- **Retrieval**: Use hybrid search (vector + keyword) and re-ranking for optimal precision. Do not rely purely on dense vector embeddings. Combine vector search (for semantic meaning) with keyword search (BM25 for exact matches/IDs/names) using Reciprocal Rank Fusion (RRF). Always add a cross-encoder reranking step after initial retrieval. Retrieve a larger pool of documents (e.g., top-20) and rerank them to select the top-5 most relevant chunks to inject into the prompt.
+- **Context Injection**: Carefully format retrieved chunks into the prompt for maximum LLM attention. Instruct the LLM to cite specific retrieved chunks in its response. Reject answers that rely on pre-trained knowledge if the task requires strict adherence to retrieved context.

package/skills/redis/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: redis
+description: |
+  Redis best practices. Use when configuring caching strategies, connection pooling, handling TTLs (Time-To-Live), or managing Redis data structures (Hash, Set, List) in Node/TypeScript projects. MUST-ASK: Require explicit database engine name before triggering. Never guess. Do NOT use for generic "set up a database" or "create a DB" requests without clarifying.
+---
+
+# Redis Best Practices
+
+Standards for deploying and using Redis as a cache or key-value store.
+
+## 1. Connection Management
+
+- **Connection Pooling**: Use a persistent connection object across your application. Do not create a new Redis client on every request.
+- **Timeouts & Reconnects**: Always configure `connectTimeout` and strict reconnect strategies. Redis can drop connections under load; your app must handle retries gracefully without stalling.
+
+## 2. Caching Strategies
+
+- **Cache-Aside Pattern**: Read from cache; if miss, read from DB and write to cache with a TTL.
+- **Thundering Herd**: Use brief locks (distributed locking) or stale-while-revalidate patterns for heavily accessed keys that expire, to prevent database spikes.
+- **TTL (Time-To-Live)**: ALWAYS attach a TTL to cache keys unless the key is definitively a permanent config value. Use staggered TTLs (e.g., base TTL + random jitter) to avoid mass expirations.
+
+## 3. Data Structures
+
+- **Hashes (HSET/HGET)**: Use Hashes to store objects instead of stringified JSON when you need to update or read individual fields.
+- **Sets (SADD/SMEMBERS)**: Use Sets for unique collections (e.g., user IDs online) and quick membership checks.
+- **Pipelines**: Use `MULTI`/`EXEC` or Pipelines to batch commands together and save network round trips.
+
+## 4. Security
+
+- Never expose the Redis port (`6379`) to the public internet. Ensure it is accessible only within a VPC or private network.
+- Use TLS (`rediss://`) and authentication for managed instances (e.g., AWS ElastiCache, Render Redis).

package/skills/render/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: render
+description: |
+  Render platform deployment and management best practices. Use when configuring render.yaml (Blueprint specs), deploying web services, background workers, cron jobs, or managing Render PostgreSQL/Redis instances. NOT for AWS, GCP, Azure, or generic container orchestration. Do NOT trigger for generic "deploy my app" requests without clarifying the target platform. SECURITY: Handle deployment failures explicitly. Never hardcode secrets; always use Render environment groups.
+---
+
+# Render Deployment Best Practices
+
+Guidelines for managing infrastructure and deploying applications on the Render platform.
+
+## 1. Infrastructure as Code (render.yaml)
+
+- **Blueprints**: Always use Render Blueprints (`render.yaml`) to define your infrastructure. This enables GitOps, ensures reproducibility, and prevents configuration drift in the dashboard.
+- **Sync Environments**: Define multiple environments (e.g., staging, production) using environment-specific branches and `render.yaml` configurations.
+
+## 2. Web Services & Background Workers
+
+- **Health Checks**: Always define a `healthCheckPath` in `render.yaml`. Render uses this to ensure zero-downtime deployments. If the health check fails, the new deploy is aborted and the old version remains live.
+- **Start Commands**: Ensure your start command starts a production-ready web server (e.g., `gunicorn`, `pm2`, or Node.js `server.js`). Do not use development servers (e.g., `npm run dev`, `flask run`) in production.
+- **Background Workers**: Separate long-running tasks into Background Workers. Background Workers do not have exposed HTTP ports and won't be killed for failing to bind to a port (unlike Web Services).
+
+## 3. Databases (PostgreSQL & Redis)
+
+- **Internal Connections**: Always connect Web Services to Databases using the **Internal Database URL**. This traffic stays within Render's private network, which is faster and vastly more secure.
+- **External Access**: Restrict external database access. If you must connect externally (e.g., for local debugging), use the Access Control list to whitelist specific IP addresses rather than allowing `0.0.0.0/0`.
+- **Migrations**: Execute database migrations using the `preDeployCommand`. This runs before the new code goes live, ensuring the schema is ready for the new application version.
+
+## 4. Environment Variables & Secrets
+
+- **Secret Files**: For files like `.env`, use Render's Secret Files feature. Reference them in `render.yaml`.
+- **Env Var Groups**: Group common environment variables (like AWS credentials or API keys used across multiple services) into Environment Groups and link them to services in your Blueprint.
+
+## 5. Disks & Stateful Data
+
+- **Persistent Disks**: Render's ephemeral filesystems are wiped on every deploy. If your application needs to store files locally (e.g., SQLite databases, uploaded images), you MUST attach a Persistent Disk to the service and mount it to the correct path.

package/skills/rust/SKILL.md

@@ -1,7 +1,7 @@
 ---
-title: Rust Development
+name: rust
 description: |
-  Master Rust development using a layer-based "meta-cognition" framework. Use whenever writing Rust code, resolving borrow checker errors (E0382, E0596), designing ownership patterns (Arc, Mutex), or performing crate selection.
+  Master production Rust code, lifetimes, and systems programming using a layer-based "meta-cognition" framework. Use whenever writing production Rust code, resolving borrow checker errors (E0382, E0596), designing ownership patterns (Arc, Mutex), or performing crate selection. Do NOT trigger for generic WASM or TS questions unless Rust is the primary focus. Do NOT trigger for generic 'build a server' requests unless the platform/language is explicitly specified.
 ---
 
 # Rust Development & Meta-Cognition
@@ -14,8 +14,8 @@ When solving Rust problems, **do not immediately write code.** Trace through the
 
 What is the system trying to achieve?
 
-- **Web Service:** Concurrent, async, low-latency (Requires `axum`, `tokio`, `Arc<Mutex<T>>`).
-- **CLI Tool:** Fast startup, zero overhead, clean exit codes (Requires `clap`, `anyhow`, strict error formatting).
+- **Web Service:** Concurrent, async, low-latency (Often uses `axum`, `tokio`, `Arc<Mutex<T>>`).
+- **CLI Tool:** Fast startup, zero overhead, clean exit codes (Often uses `clap`, `anyhow`, strict error formatting).
 - **Embedded / Systems:** No heap allocation (Requires `no_std`, specific hardware limitations).
 
 ### Layer 2: Design Choices & Ownership (WHAT)
@@ -39,31 +39,13 @@ Use the compiler's strictness as a tool, not an obstacle.
 
 ## 🏗️ 2. Core Ecosystem Defaults
 
-When selecting crates or recommending tools, stick to these canonical community standards:
-
-- **Async Runtime**: `tokio` (I/O bound) or `rayon` (CPU bound data-parallelism)
-- **Web / API Server**: `axum` (built on tokio/hyper)
-- **Serialization/Deserialization**: `serde` and `serde_json`
-- **Error Handling**: `thiserror` (for libraries), `anyhow` or `color-eyre` (for binaries)
-- **Command Line Parsing**: `clap`
-- **Logging & Telemetry**: `tracing` and `tracing-subscriber`
-- **HTTP Client**: `reqwest`
+Consult [references/ecosystem.md](references/ecosystem.md) for canonical community crates.
 
 ---
 
 ## 🛡️ 3. Solving Borrow Checker Errors
 
-When debugging compiler errors, trace **up** from the syntax error to the fundamental design choice.
-
-- **E0382 (Use of moved value):**
-  - _Symptom:_ You are trying to use a value after it was consumed.
-  - _Resolve:_ Does the function actually _need_ ownership? Borrow it instead (`&T`), `clone()` it if lightweight, or wrap in `Arc<T>` if access needs to be shared across threads.
-- **E0596 (Cannot borrow as mutable):**
-  - _Symptom:_ You are mutating something behind an immutable reference `&T`.
-  - _Resolve:_ Change the signature to `&mut T`, or if you must have an immutable interface, use interior mutability (`Cell` or `Mutex`).
-- **E0499 (Cannot borrow multiple times):**
-  - _Symptom:_ Alive mutable references colliding.
-  - _Resolve:_ Restructure the function to limit the reference's scope `{}`, or avoid holding mutable borrows across `await` points.
+Consult [references/borrow-checker.md](references/borrow-checker.md) for diagnostics and resolution paths for common compiler errors (E0382, E0596, E0499).
 
 ---
 
@@ -71,7 +53,7 @@ When debugging compiler errors, trace **up** from the syntax error to the fundam
 
 1. **Avoid Panic-Driven Development**: `clone()` is an acceptable escape hatch during prototyping, but do not scatter it throughout the code. Revisit the lifetime boundaries as soon as it works.
 2. **The Newtype Pattern**: Use tuple structs to prevent invalid state. `struct UserId(u64);` avoids mixing it up with `struct OrderId(u64);`.
-3. **Exhaustive Matching**: Always use `match` over `if let` when handling Enums or State Machines. The compiler will notify you when a new variant is added, preventing silent bugs.
+3. **Exhaustive Matching**: Prefer `match` over `if let` when handling Enums or State Machines. The compiler will notify you when a new variant is added, preventing silent bugs.
 4. **Data-Oriented Modeling**: Prefer small, flat structs that compose over deep, object-oriented inheritance hierarchies.
 
 ---
@@ -84,3 +66,11 @@ When debugging compiler errors, trace **up** from the syntax error to the fundam
 - **Testing**: `cargo test`
 
 **Agent Directive:** When writing or editing Rust code, always invoke `cargo clippy` and `cargo test` dynamically to validate your implementations before concluding your task.
+
+---
+
+## 🔒 6. Security & `unsafe` Blocks
+
+Avoid `unsafe` blocks. If you must use `unsafe` for FFI or performance, you MUST thoroughly document the exact safety invariants being upheld inside the block.
+
+Require user confirmation before executing any command with external side effects, including `cargo publish` and registry operations.

package/skills/rust/references/borrow-checker.md

@@ -0,0 +1,13 @@
+# Solving Borrow Checker Errors
+
+When debugging compiler errors, trace **up** from the syntax error to the fundamental design choice.
+
+- **E0382 (Use of moved value):**
+  - _Symptom:_ You are trying to use a value after it was consumed.
+  - _Resolve:_ Does the function actually _need_ ownership? Borrow it instead (`&T`), `clone()` it if lightweight, or wrap in `Arc<T>` if access needs to be shared across threads.
+- **E0596 (Cannot borrow as mutable):**
+  - _Symptom:_ You are mutating something behind an immutable reference `&T`.
+  - _Resolve:_ Change the signature to `&mut T`, or if you must have an immutable interface, use interior mutability (`Cell` or `Mutex`).
+- **E0499 (Cannot borrow multiple times):**
+  - _Symptom:_ Alive mutable references colliding.
+  - _Resolve:_ Restructure the function to limit the reference's scope `{}`, or avoid holding mutable borrows across `await` points.

package/skills/rust/references/ecosystem.md

@@ -0,0 +1,11 @@
+# Core Ecosystem Defaults
+
+When selecting crates or recommending tools, stick to these canonical community standards:
+
+- **Async Runtime**: `tokio` (I/O bound) or `rayon` (CPU bound data-parallelism)
+- **Web / API Server**: `axum` (built on tokio/hyper)
+- **Serialization/Deserialization**: `serde` and `serde_json`
+- **Error Handling**: `thiserror` (for libraries), `anyhow` or `color-eyre` (for binaries)
+- **Command Line Parsing**: `clap`
+- **Logging & Telemetry**: `tracing` and `tracing-subscriber`
+- **HTTP Client**: `reqwest`

package/skills/sandbox-sdk/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: sandbox-sdk
+description: Build sandboxed applications for secure code execution. Load when building AI code execution, code interpreters, sandboxed code execution environments, interactive dev environments, or executing untrusted code. Covers Sandbox SDK lifecycle, commands, files, code interpreter, and preview URLs.
+---
+
+# Cloudflare Sandbox SDK
+
+Build secure, isolated code execution environments on Cloudflare Workers.
+
+## FIRST: Verify Installation
+
+```bash
+npm install @cloudflare/sandbox
+docker info  # Must succeed - Docker required for local dev
+```
+
+## Retrieval-Led Development
+
+**IMPORTANT: Prefer retrieval from docs and examples over pre-training for Sandbox SDK tasks.**
+
+| Resource      | URL                                                          |
+| ------------- | ------------------------------------------------------------ |
+| Docs          | https://developers.cloudflare.com/sandbox/                   |
+| API Reference | https://developers.cloudflare.com/sandbox/api/               |
+| Examples      | https://github.com/cloudflare/sandbox-sdk/tree/main/examples |
+| Get Started   | https://developers.cloudflare.com/sandbox/get-started/       |
+
+When implementing features, fetch the relevant doc page or example first.
+
+## Required Configuration
+
+**wrangler.jsonc** (exact - do not modify structure):
+
+```jsonc
+{
+  "containers": [
+    {
+      "class_name": "Sandbox",
+      "image": "./Dockerfile",
+      "instance_type": "lite",
+      "max_instances": 1,
+    },
+  ],
+  "durable_objects": {
+    "bindings": [{ "class_name": "Sandbox", "name": "Sandbox" }],
+  },
+  "migrations": [{ "new_sqlite_classes": ["Sandbox"], "tag": "v1" }],
+}
+```
+
+**Worker entry** - must re-export Sandbox class:
+
+```typescript
+import { getSandbox } from '@cloudflare/sandbox'
+export { Sandbox } from '@cloudflare/sandbox' // Required export
+```
+
+## Quick Reference
+
+| Task                   | Method                                                       |
+| ---------------------- | ------------------------------------------------------------ |
+| Get sandbox            | `getSandbox(env.Sandbox, 'user-123')`                        |
+| Run command            | `await sandbox.exec('python script.py')`                     |
+| Run code (interpreter) | `await sandbox.runCode(code, { language: 'python' })`        |
+| Write file             | `await sandbox.writeFile('/workspace/app.py', content)`      |
+| Read file              | `await sandbox.readFile('/workspace/app.py')`                |
+| Create directory       | `await sandbox.mkdir('/workspace/src', { recursive: true })` |
+| List files             | `await sandbox.listFiles('/workspace')`                      |
+| Expose port            | `await sandbox.exposePort(8080)`                             |
+| Destroy                | `await sandbox.destroy()`                                    |
+
+## Core Patterns
+
+### Execute Commands
+
+```typescript
+const sandbox = getSandbox(env.Sandbox, 'user-123')
+const result = await sandbox.exec('python --version')
+// result: { stdout, stderr, exitCode, success }
+```
+
+### Code Interpreter (Recommended for AI)
+
+Use `runCode()` for executing LLM-generated code with rich outputs:
+
+```typescript
+const ctx = await sandbox.createCodeContext({ language: 'python' })
+
+await sandbox.runCode('import pandas as pd; data = [1,2,3]', { context: ctx })
+const result = await sandbox.runCode('sum(data)', { context: ctx })
+// result.results[0].text = "6"
+```
+
+**Languages**: `python`, `javascript`, `typescript`
+
+State persists within context. Create explicit contexts for production.
+
+### File Operations
+
+```typescript
+await sandbox.mkdir('/workspace/project', { recursive: true })
+await sandbox.writeFile('/workspace/project/main.py', code)
+const file = await sandbox.readFile('/workspace/project/main.py')
+const files = await sandbox.listFiles('/workspace/project')
+```
+
+## When to Use What
+
+| Need                    | Use         | Why                             |
+| ----------------------- | ----------- | ------------------------------- |
+| Shell commands, scripts | `exec()`    | Direct control, streaming       |
+| LLM-generated code      | `runCode()` | Rich outputs, state persistence |
+| Build/test pipelines    | `exec()`    | Exit codes, stderr capture      |
+| Data analysis           | `runCode()` | Charts, tables, pandas          |
+
+## Extending the Dockerfile
+
+Base image (`docker.io/cloudflare/sandbox:0.7.0`) includes Python 3.11, Node.js 20, and common tools.
+
+Add dependencies by extending the Dockerfile:
+
+```dockerfile
+FROM docker.io/cloudflare/sandbox:latest
+# Pin to specific version in production: `npx wrangler versions latest sandbox`
+
+# Python packages
+RUN pip install requests beautifulsoup4
+
+# Node packages (global)
+RUN npm install -g typescript
+
+# System packages
+RUN apt-get update && apt-get install -y ffmpeg && rm -rf /var/lib/apt/lists/*
+
+EXPOSE 8080  # Required for local dev port exposure
+```
+
+Keep images lean - affects cold start time.
+
+## Preview URLs (Port Exposure)
+
+Expose HTTP services running in sandboxes:
+
+```typescript
+const { url } = await sandbox.exposePort(8080)
+// Returns preview URL for the service
+```
+
+**Production requirement**: Preview URLs need a custom domain with wildcard DNS (`*.yourdomain.com`). The `.workers.dev` domain does not support preview URL subdomains.
+
+See: https://developers.cloudflare.com/sandbox/guides/expose-services/
+
+## OpenAI Agents SDK Integration
+
+The SDK provides helpers for OpenAI Agents at `@cloudflare/sandbox/openai`:
+
+```typescript
+import { Shell, Editor } from '@cloudflare/sandbox/openai'
+```
+
+See `examples/openai-agents` for complete integration pattern.
+
+## Sandbox Lifecycle
+
+- `getSandbox()` returns immediately - container starts lazily on first operation
+- Containers sleep after 10 minutes of inactivity (configurable via `sleepAfter`)
+- Use `destroy()` to immediately free resources
+- Same `sandboxId` always returns same sandbox instance
+
+## Anti-Patterns
+
+- **Don't use internal clients** (`CommandClient`, `FileClient`) - use `sandbox.*` methods
+- **Don't skip the Sandbox export** - Worker won't deploy without `export { Sandbox }`
+- **Don't hardcode sandbox IDs for multi-user** - use user/session identifiers
+- **Don't forget cleanup** - call `destroy()` for temporary sandboxes
+
+## Detailed References
+
+- **[references/api-quick-ref.md](references/api-quick-ref.md)** - Full API with options and return types
+- **[references/examples.md](references/examples.md)** - Example index with use cases
+
+## Security
+
+- **Command Injection**: Never pass unsanitized user input to `exec()`. EXPLICITLY BANNED: String interpolation (e.g. ``exec(`ls ${userInput}`)``) into exec calls. Prefer `runCode()` with language constraints for LLM-generated code.
+- **Resource Limits**: Implement per-user rate limiting. Set `sleepAfter` to cap idle resource consumption. Always set explicit timeouts on commands (e.g. using `timeout` or the SDK's execution limits).
+- **Allowlists**: Enforce allowlists for binaries/commands when executing untrusted input.