IntelIP · hudsonaikins · Jul 30, 2026 · Jul 30, 2026 · Jul 30, 2026
diff --git a/README.md b/README.md
@@ -4,13 +4,16 @@
 [![Python Versions](https://img.shields.io/pypi/pyversions/neural-sdk.svg)](https://pypi.org/project/neural-sdk/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Professional-grade SDK for algorithmic trading on prediction markets, built as the public surface of the Neural stack.
+Deterministic prediction-market kernel for portable contracts, normalization,
+replay, and paper-first integration beneath Vaticor.
 
 [Documentation](https://github.com/IntelIP/Neural/tree/main/docs) | [Examples](./examples) | [Contributing](./CONTRIBUTING.md)
 
-## Overview
+## Stable Kernel
 
-Neural SDK is the public Python control surface for market access, paper trading, provider discovery, and the CLI bridge consumed by the Neural TUI.
+The dependency-free stable surface lives at `neural.kernel`. Provider access,
+strategy analysis, deployment, sentiment, and FIX helpers remain experimental
+or deprecated compatibility modules.
 
 ## Install
 
@@ -28,6 +31,16 @@ pip install neural-sdk
 pip install "neural-sdk[trading]"
 ```
 
+Verify the stable installed surface without credentials or network access:
+
+```bash
+neural --json capabilities
+neural --json replay demo
+```
+
+See [Stable Kernel and Compatibility](./docs/architecture/stability.mdx) for
+the capability matrix, extras, and deprecation policy.
+
 ## CLI Bridge
 
 The base install ships a `neural` CLI intended to be the stable machine-readable bridge for the TypeScript Neural TUI.
@@ -41,6 +54,7 @@ neural --json providers list
 Current bridge commands:
 - `doctor`
 - `capabilities`
+- `replay demo`
 - `providers list`
 - `markets list`
 - `quote`

diff --git a/docs/architecture/meta.json b/docs/architecture/meta.json
@@ -1,4 +1,4 @@
 {
   "title": "Architecture",
-  "pages": ["start-here", "overview"]
+  "pages": ["start-here", "overview", "stability"]
 }
diff --git a/docs/architecture/stability.mdx b/docs/architecture/stability.mdx
@@ -0,0 +1,72 @@
+---
+title: Stable Kernel and Compatibility
+description: Neural's supported kernel surface, experimental modules, and deprecation policy
+---
+
+Neural is the deterministic Python kernel beneath Vaticor. The stable base
+does not authorize provider calls, live orders, deployment, or model-driven
+side effects.
+
+## Stable surface
+
+Import stable capabilities from `neural.kernel`:
+
+```python
+from neural.kernel import NormalizedMarket, ReplayEvent, replay
+```
+
+The stable surface contains:
+
+- normalized market, quote, order, position, capability, and policy types;
+- dependency-free deterministic replay with a canonical SHA-256 digest;
+- `neural doctor`, `neural capabilities`, and `neural replay demo`.
+
+Run the installed-wheel demo without credentials or network access:
+
+```bash
+neural --json replay demo
+```
+
+The result contains a digest, event count, market count, and final snapshot.
+The same fixture must produce the same result regardless of input order.
+
+## Capability matrix
+
+`neural --json capabilities` is the machine-readable source for the current
+matrix.
+
+| Capability | Status | Install path | Compatibility |
+| --- | --- | --- | --- |
+| Kernel normalization | Stable | base wheel | Public `neural.kernel` contract |
+| Kernel replay | Stable | base wheel | Deterministic output and digest |
+| CLI diagnostics | Stable | base wheel | JSON envelope retained |
+| Kalshi auth and collection | Experimental | `neural-sdk[trading]` | May change before 1.0 |
+| Paper and venue adapters | Experimental | `neural-sdk[trading]` | Paper-first; no live authority |
+| Strategy and backtesting | Experimental | `neural-sdk[analysis]` | May change before 1.0 |
+| Sentiment | Deprecated | `neural-sdk[sentiment]` | Compatibility only |
+| Generic deployment | Deprecated | `neural-sdk[deployment]` | Move runtime ownership to Vaticor |
+| FIX experiments | Deprecated | `neural-sdk[fix]` | Compatibility only |
+
+Existing imports remain available during the `0.4.x` compatibility window.
+New code should use `neural.kernel` for stable contracts.
+
+## Compatibility policy
+
+- Stable symbols retain compatible behavior within a minor release line.
+- Experimental symbols can change before `1.0`; changes require release notes.
+- Deprecated symbols remain through at least one later minor release and name
+  their replacement before removal.
+- Removal never silently enables a provider, credential, deployment, or live
+  execution path.
+- Model output remains untrusted. Schema or replay success cannot authorize an
+  external side effect.
+- Exact wheel compatibility requires the Neural commit, wheel digest, Python
+  version, and validator result. Local source-path imports are insufficient.
+
+## Legacy import path
+
+Existing `neural.exchanges`, `neural.trading`, `neural.analysis`,
+`neural.data_collection`, and `neural.deployment` imports are preserved for
+compatibility. Install the matching extra before using those surfaces. Moving
+to `neural.kernel` removes provider and optional-stack coupling from portable
+contract and replay code.
diff --git a/docs/getting-started.mdx b/docs/getting-started.mdx
@@ -1,6 +1,6 @@
 ---
 title: Getting Started
-description: Install, configure credentials, and ship your first Neural workflow
+description: Install the stable kernel and run a deterministic replay
 ---
 
 Follow these steps in order. Every command has a matching verification check so you know the environment is ready before moving on.
@@ -9,7 +9,7 @@ Follow these steps in order. Every command has a matching verification check so
 
 - Python 3.10 or newer
 - `pip` or `uv`
-- Kalshi API key ID and RSA private key (downloadable from the Kalshi console)
+- No credentials for the stable kernel path
 
 ## Step 1 – Install Neural
 
@@ -29,13 +29,22 @@ uv add "neural-sdk[trading]"
 
 **Verify:**
 
-```bash
-python - <<'PY'
-import neural
-print("Neural version:", neural.__version__)
-PY
+```console
+neural --json capabilities
+neural --json replay demo
 ```
 
+Both commands run without provider credentials or network access. The replay
+returns a deterministic digest and final market snapshot.
+
+See `architecture/stability` before importing experimental modules.
+
+## Experimental provider path
+
+Everything below this point uses experimental provider or analysis modules.
+It is not part of the stable base contract and does not grant live-execution
+authority.
+
 ## Step 2 – Configure credentials
 
 1. Place your keys in `secrets/` (keep the directory out of version control):
@@ -124,11 +133,11 @@ python examples/build_first_bot.py
 
 This script fetches live markets, applies a toy signal, and routes simulated orders through `PaperTradingClient`. Use it as a template before wiring in your own strategy.
 
-## Step 7 – Move into paper or live trading
+## Step 7 – Continue with paper execution
 
-1. Swap `TradingClient` in for live trading (credentials required).
-2. Keep `PaperTradingClient` for rehearsals and backtesting comparisons.
-3. Use `OrderManager` to keep strategy logic independent from the execution target.
+1. Keep `PaperTradingClient` for rehearsals and backtesting comparisons.
+2. Use `OrderManager` to keep strategy logic independent from the execution target.
+3. Treat any provider write or live order as a separate human-approved action.
 
 ## Step 8 – Run tests
 

diff --git a/docs/index.mdx b/docs/index.mdx
@@ -1,17 +1,20 @@
 ---
 title: 'Neural SDK'
-description: 'Build, test, and operate prediction-market systems with one Python SDK.'
+description: 'Use a deterministic prediction-market kernel beneath Vaticor.'
 ---
 
-Neural SDK is the public Python control surface for market data, strategy analysis,
-paper trading, provider discovery, and automation.
+Neural SDK supplies portable normalization, deterministic replay, and
+paper-first compatibility primitives beneath the Vaticor product.
 
 ## Choose your path
 
 <Cards>
   <Card title="Start with the architecture" href="/docs/architecture/start-here">
     Map data collection, analysis, and execution before writing code.
   </Card>
+  <Card title="Inspect the stable kernel" href="/docs/architecture/stability">
+    Review supported imports, experimental extras, and deprecation policy.
+  </Card>
   <Card title="Install the SDK" href="/docs/getting-started">
     Configure a local environment and run the first authenticated checks.
   </Card>
@@ -21,6 +24,6 @@ paper trading, provider discovery, and automation.
 </Cards>
 
 <Callout type="warn" title="Trading risk">
-  Neural is beta software. Prediction-market trading can lose money. Validate
-  strategies with deterministic tests and paper execution before using live funds.
+  Neural is beta software. Stable kernel output cannot authorize provider
+  calls, deployment, or live execution.
 </Callout>
diff --git a/neural/__init__.py b/neural/__init__.py
@@ -16,6 +16,7 @@
     "data_collection",
     "deployment",
     "exchanges",
+    "kernel",
     "trading",
 }
 
@@ -72,15 +73,14 @@ def __dir__() -> list[str]:
     return sorted(set(globals()) | _OPTIONAL_SUBMODULES)
 
 
-
 __all__ = [
     "__version__",
     "analysis",
     "auth",
     "data_collection",
     "deployment",
     "exchanges",
+    "kernel",
     "trading",
     "_warn_experimental",
 ]
-
diff --git a/neural/cli.py b/neural/cli.py
@@ -19,6 +19,7 @@
 CLI_COMMANDS = [
     "doctor",
     "capabilities",
+    "replay demo",
     "providers list",
     "markets list",
     "quote",
@@ -68,9 +69,18 @@ def _build_parser() -> argparse.ArgumentParser:
     )
     capabilities_parser.set_defaults(handler=_handle_capabilities, formatter=_format_capabilities)
 
+    replay_parser = subparsers.add_parser("replay", help="Run deterministic Neural kernel replays")
+    replay_subparsers = replay_parser.add_subparsers(dest="replay_command")
+    replay_demo_parser = replay_subparsers.add_parser(
+        "demo", help="Run the dependency-free deterministic fixture"
+    )
+    replay_demo_parser.set_defaults(handler=_handle_replay_demo)
+
     providers_parser = subparsers.add_parser("providers", help="Inspect deployment providers")
     providers_subparsers = providers_parser.add_subparsers(dest="providers_command")
-    providers_list_parser = providers_subparsers.add_parser("list", help="List discovered providers")
+    providers_list_parser = providers_subparsers.add_parser(
+        "list", help="List discovered providers"
+    )
     providers_list_parser.set_defaults(handler=_handle_providers_list, formatter=_format_providers)
 
     markets_parser = subparsers.add_parser("markets", help="Query Neural market data")
@@ -102,23 +112,31 @@ def _build_parser() -> argparse.ArgumentParser:
 
     deployments_parser = subparsers.add_parser("deployments", help="Inspect runtime deployments")
     deployments_parser.add_argument("--provider", default=os.getenv("NEURAL_DEPLOYMENT_PROVIDER"))
-    deployments_parser.add_argument("--workspace-name", default=os.getenv("NEURAL_DAYTONA_WORKSPACE"))
+    deployments_parser.add_argument(
+        "--workspace-name", default=os.getenv("NEURAL_DAYTONA_WORKSPACE")
+    )
     deployments_parser.add_argument("--runner-image", default=os.getenv("NEURAL_DAYTONA_IMAGE"))
     deployments_parser.add_argument("--project-name", default="neural")
     deployments_parser.add_argument("--environment", default="paper")
     deployments_parser.add_argument("--daytona-binary", default=os.getenv("NEURAL_DAYTONA_BINARY"))
     deployments_subparsers = deployments_parser.add_subparsers(dest="deployments_command")
 
     deployments_list_parser = deployments_subparsers.add_parser("list", help="List deployments")
-    deployments_list_parser.set_defaults(handler=_handle_deployments_list, formatter=_format_deployments)
+    deployments_list_parser.set_defaults(
+        handler=_handle_deployments_list, formatter=_format_deployments
+    )
 
-    deployments_status_parser = deployments_subparsers.add_parser("status", help="Get deployment status")
+    deployments_status_parser = deployments_subparsers.add_parser(
+        "status", help="Get deployment status"
+    )
     deployments_status_parser.add_argument("deployment_id")
     deployments_status_parser.set_defaults(
         handler=_handle_deployments_status, formatter=_format_deployment_status
     )
 
-    deployments_logs_parser = deployments_subparsers.add_parser("logs", help="Fetch deployment logs")
+    deployments_logs_parser = deployments_subparsers.add_parser(
+        "logs", help="Fetch deployment logs"
+    )
     deployments_logs_parser.add_argument("deployment_id")
     deployments_logs_parser.add_argument("--tail", type=int, default=50)
     deployments_logs_parser.set_defaults(
@@ -166,8 +184,15 @@ def _handle_doctor(_: argparse.Namespace) -> dict[str, Any]:
 
 
 def _handle_capabilities(_: argparse.Namespace) -> dict[str, Any]:
+    from neural.kernel import capability_matrix
+
     providers = _safe_list_providers()
     return {
+        "kernel": {
+            "stable": True,
+            "dependency_free": True,
+            "capabilities": capability_matrix(),
+        },
         "cli": {
             "commands": CLI_COMMANDS,
             "json_envelope": {
@@ -193,6 +218,12 @@ def _handle_capabilities(_: argparse.Namespace) -> dict[str, Any]:
     }
 
 
+def _handle_replay_demo(_: argparse.Namespace) -> dict[str, Any]:
+    from neural.kernel import run_demo_replay
+
+    return {"replay": run_demo_replay().as_dict()}
+
+
 def _handle_providers_list(_: argparse.Namespace) -> dict[str, Any]:
     providers = _safe_list_providers()
     return {"providers": providers, "count": len(providers)}
@@ -315,7 +346,11 @@ def _handle_deployments_logs(args: argparse.Namespace) -> dict[str, Any]:
 def _handle_deployments_stop(args: argparse.Namespace) -> dict[str, Any]:
     provider_name, provider = _build_provider(args)
     stopped = asyncio.run(provider.stop(args.deployment_id))
-    return {"provider": provider_name, "deployment_id": args.deployment_id, "stopped": bool(stopped)}
+    return {
+        "provider": provider_name,
+        "deployment_id": args.deployment_id,
+        "stopped": bool(stopped),
+    }
 
 
 def _build_provider(args: argparse.Namespace) -> tuple[str, Any]: