Document ForkCell runtime fork

Author: Ambient Code Bot

FORKCELL.md

@@ -0,0 +1,47 @@
+# ForkCell Runtime Fork
+
+This repository is BeforeWire's pinned OpenShell runtime fork for ForkCell.
+
+ForkCell is the control plane for governed agent execution cells: checkpoint,
+governed run, receipt, then accept, restore, or fork. OpenShell remains the
+runtime enforcement layer for sandbox lifecycle, filesystem/process policy,
+egress/L7 policy, credentials, and OCSF/log events.
+
+## Pinned Runtime
+
+- Branch: `forkcell-workspace-substrate`
+- Runtime tag: recorded in `beforewire/forkcell/patches/openshell.lock`
+- Runtime commit: recorded in `beforewire/forkcell/patches/openshell.lock`
+- ForkCell repo: `https://github.com/beforewire/forkcell`
+- Upstream base: `f23c2c8e84193beac5c35af8cd80276b60b8dbd4`
+
+## Patch Scope
+
+The ForkCell patch adds a typed Docker workspace substrate contract:
+
+- accepts `docker.workspace` config with `type: forkcell_overlay`;
+- mounts a named workspace backing volume at a private runtime path;
+- passes workspace substrate metadata to the supervisor;
+- prepares/chowns overlay runtime directories before privilege drop;
+- keeps OpenShell policy, egress, credential, and OCSF paths unchanged.
+
+## Non-goals
+
+- This fork does not replace upstream OpenShell.
+- This fork does not add business-semantic policy evaluation.
+- This fork does not claim full sandbox lifecycle latency is `0ms`.
+- This fork only enables ForkCell's fast workspace restore substrate.
+
+## Validation
+
+ForkCell's public-preview docs report:
+
+- native overlay `restore_sync_ms`: `0ms` for validated profiles;
+- correctness matrix: `7/7` cases passed;
+- policy smoke: deny host, allow GET, and L7 deny passed;
+- README-path tiny demo: checkpoint mark `0ms`, restore duration `0ms`,
+  total restore path `783ms` including OpenShell sandbox lifecycle and log
+  collection.
+
+See `beforewire/forkcell` for the user-facing README, receipts, and preview
+testing plan.

README.md

@@ -1,5 +1,11 @@
 # NVIDIA OpenShell
 
+> **BeforeWire ForkCell runtime fork.** This branch is pinned by
+> `beforewire/forkcell` and carries a narrow workspace-substrate patch for
+> ForkCell's fast checkpoint/restore path. For the ForkCell-specific scope,
+> pinned commit, and non-goals, see [`FORKCELL.md`](FORKCELL.md). For general
+> OpenShell usage, prefer the upstream NVIDIA project and release channels.
+
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue)](https://github.com/NVIDIA/OpenShell/blob/main/LICENSE)
 [![PyPI](https://img.shields.io/badge/PyPI-openshell-orange?logo=pypi)](https://pypi.org/project/openshell/)
 [![Security Policy](https://img.shields.io/badge/Security-Report%20a%20Vulnerability-red)](SECURITY.md)