diff --git a/dev/docs/README.md b/dev/docs/README.md
new file mode 100644
index 0000000..ce4622b
--- /dev/null
+++ b/dev/docs/README.md
@@ -0,0 +1 @@
+# Internal Development Docs
diff --git a/dev/docs/design/pins.md b/dev/docs/design/pins.md
new file mode 100644
index 0000000..1a823f6
--- /dev/null
+++ b/dev/docs/design/pins.md
@@ -0,0 +1,177 @@
+# Pin Scoping
+
+Element references via `data-volt-pin` require a scoping strategy to avoid name collisions and provide predictable access patterns.
+This document explores three approaches that were considered
+
+## Current Implementation: [data-volt] Root Scoping
+
+**How it works:**
+
+- Each `[data-volt]` root has its own pin registry
+- Pins are isolated to their scope
+- `$pins.name` accesses pins within the current root
+
+**Example:**
+
+```html
+
+
+
+
+
+
+
+
+
+```
+
+**Pros:**
+
+- Predictable: Each root is isolated
+- No name collision risk across roots
+- Aligns with current scope model (one scope per root)
+- Simple to implement and reason about
+
+**Cons:**
+
+- Can't share pins across roots (must use global state instead)
+- No sub-scoping within a root for component-like patterns
+
+**Use Cases:**
+
+- Simple applications with clear root boundaries
+- When each `[data-volt]` represents a distinct feature/component
+
+---
+
+## Alternative 1: Explicit Scope Boundaries (data-volt-scope)
+
+**How it works:**
+
+- Introduce `data-volt-scope` attribute to create nested scopes
+- Pins registered within a scope are isolated to that scope and its descendants
+- `$pins` searches up the scope chain
+
+**Example:**
+
+```html
+
+
+
+
+
+
+
+
+
+
+
+```
+
+**Pros:**
+
+- Fine-grained control over scope boundaries
+- Supports nested component patterns
+- Can isolate widgets within a larger root
+
+**Cons:**
+
+- More complex: requires scope hierarchy tracking
+- Additional attribute to learn
+- Lookup complexity (walking scope chain)
+- Breaks current 1:1 scope-to-root model
+
+**Use Cases:**
+
+- Large applications with reusable sub-components
+- When you need multiple isolated widgets within one root
+- Form libraries with nested fieldsets
+
+**Implementation Complexity:**
+
+- Requires scope hierarchy (parent references)
+- WeakMap must track scope chains
+- Pin lookup becomes recursive
+
+## Alternative 2: Global Document-Wide Registry
+
+**How it works:**
+
+- Single global pin registry for entire document
+- All pins accessible from any scope
+- Names must be unique across the entire page
+
+**Example:**
+
+```html
+
+
+
+
+
+
+
+
+```
+
+**Pros:**
+
+- Simplest to understand: flat namespace
+- Easy to share element references across roots
+- No scoping complexity
+
+**Cons:**
+
+- High risk of name collisions
+- No isolation between roots (breaks encapsulation)
+- Debugging becomes harder (where is this pin defined?)
+- Not composable (can't have two instances of same component)
+
+**Use Cases:**
+
+- Prototypes and simple pages
+- Single-page applications with unique IDs everywhere
+- When cross-root communication is primary goal
+
+**Implementation Complexity:**
+
+- Simple: single Map instead of per-scope maps
+- No WeakMap needed
+
+## Comparison Table
+
+| Aspect | Root Scoping (Current) | Explicit Scopes | Global |
+|--------|------------------------|-----------------|--------|
+| Isolation | Per root | Per scope boundary | None |
+| Name Collisions | Safe within root | Safe within scope | High risk |
+| Complexity | Low | Medium | Very Low |
+| Cross-root Access | Not supported | Not supported | Supported |
+| Nested Components | Not supported | Supported | Not needed |
+| Implementation | Simple | Complex | Trivial |
+| Composability | Good | Excellent | Poor |
+
+## Decision Rationale
+
+**Current implementation uses Root Scoping** for the following reasons:
+
+1. **Aligns with existing architecture**: VoltX already uses one scope per `[data-volt]` root
+2. **Simplicity**: No additional concepts or attributes to learn
+3. **Good enough**: Most use cases don't require nested scopes
+4. **Future extensibility**: Can add `data-volt-scope` later if needed (additive change)
+
+**When to reconsider:**
+
+- If users frequently request nested component isolation
+- If framework adds first-class component system
+- If cross-root pin access becomes a common need (could add `data-volt-pin-global`)
+
+## Migration Path
+
+If we later adopt Alternative 1 (Explicit Scopes):
+
+1. Keep current behavior as default
+2. Add `data-volt-scope` for opt-in nested scopes
+3. Update metadata to track parent scopes
+4. Modify `getPin()` to walk scope chain
+
+This would be backward compatible since existing code without `data-volt-scope` would continue to work.
diff --git a/docs/global-state.md b/docs/global-state.md
new file mode 100644
index 0000000..f19b711
--- /dev/null
+++ b/docs/global-state.md
@@ -0,0 +1,527 @@
+# Global State
+
+VoltX provides built-in global state management through special variables and the global store. These features enable sharing state across components, accessing metadata, and coordinating behavior without external dependencies.
+
+## Overview
+
+Every Volt scope automatically receives special variables (prefixed with `$`) that provide access to:
+
+- **Global Store** - Shared reactive state across all scopes
+- **Scope Metadata** - Information about the current reactive context
+- **Element References** - Access to pinned DOM elements
+- **Utility Functions** - Helper functions for common tasks
+
+## Special Variables
+
+### `$store`
+
+Access globally shared reactive state across all Volt roots.
+
+**Declarative API:**
+
+```html
+
+
+
+
+
+
+
+
+```
+
+**Programmatic API:**
+
+```typescript
+import { registerStore, getStore } from 'voltx.js';
+
+// Register store with signals or raw values
+registerStore({
+ theme: signal('dark'),
+ count: 0 // Auto-wrapped in signal
+});
+
+// Access store
+const store = getStore();
+store.set('count', 5);
+console.log(store.get('count')); // 5
+```
+
+**Methods:**
+
+- `$store.get(key)` - Get signal value
+- `$store.set(key, value)` - Update signal value
+- `$store.has(key)` - Check if key exists
+- `$store[key]` - Direct signal access
+
+### `$origin`
+
+Reference to the root element of the current reactive scope.
+
+```html
+
+
+
+
+```
+
+### `$scope`
+
+Direct access to the raw scope object containing all signals and context.
+
+```html
+
+
+
+
+```
+
+### `$pins`
+
+Access DOM elements registered with `data-volt-pin`.
+
+```html
+
+
+
+
+
+
+
+
+```
+
+**Notes:**
+
+- Pins are scoped to their root element
+- Each root maintains its own pin registry
+- Pins are accessible immediately after registration
+
+### `$pulse(callback)`
+
+Defers callback execution to the next microtask, ensuring DOM updates have completed.
+
+```html
+
+
+
+```
+
+**Use Cases:**
+
+- Run code after DOM updates
+- Coordinate async operations
+- Batch multiple updates
+
+### `$uid(prefix?)`
+
+Generates unique, deterministic IDs within the scope.
+
+```html
+
+
+
+
+
+
+
+
+
+
+```
+
+**Notes:**
+
+- IDs are unique within the scope
+- Counter increments on each call
+- Different scopes have independent counters
+
+### `$arc(eventName, detail?)`
+
+Dispatches a CustomEvent from the current element.
+
+```html
+
+
+
+```
+
+**Event Properties:**
+
+- `bubbles: true` - Event bubbles up the DOM
+- `composed: true` - Crosses shadow DOM boundaries
+- `cancelable: true` - Can be prevented
+- `detail` - Custom data payload
+
+### `$probe(expression, callback)`
+
+Observes a reactive expression and calls a callback when dependencies change.
+
+```html
+
+
+
+
+```
+
+**Parameters:**
+
+- `expression` (string) - Reactive expression to observe
+- `callback` (function) - Called with expression value on changes
+
+**Returns:**
+
+- Cleanup function to stop observing
+
+**Example:**
+
+```html
+
+
+
+
+
+
+
+```
+
+## `data-volt-init`
+
+Run initialization code once when an element is mounted.
+
+**Basic Usage:**
+
+```html
+
+
+
+
+
+```
+
+**Setting Up Observers:**
+
+```html
+
+
+
+
+
+
+```
+
+**Accessing Special Variables:**
+
+```html
+
+
+
+
+
+```
+
+## Global Store Patterns
+
+### Shared Application State
+
+```html
+
+
+
+
+