From 5f804adfa5c5f0b6068116e5b525aa2201f7d1e6 Mon Sep 17 00:00:00 2001
From: Ben Follington <5009316+bfollington@users.noreply.github.com>
Date: Tue, 2 Dec 2025 10:40:10 +1000
Subject: [PATCH] Add documentation for `ct-cell-context` usage

---
 docs/common/CELL_CONTEXT.md                   | 41 +++++++++++++++++++
 .../ct-cell-context/ct-cell-context.ts        |  2 +-
 2 files changed, 42 insertions(+), 1 deletion(-)
 create mode 100644 docs/common/CELL_CONTEXT.md

diff --git a/docs/common/CELL_CONTEXT.md b/docs/common/CELL_CONTEXT.md
new file mode 100644
index 0000000000..0ea450d31d
--- /dev/null
+++ b/docs/common/CELL_CONTEXT.md
@@ -0,0 +1,41 @@
+`<ct-cell-context>` designates a region of the page as pertaining to a particular cell. This creates a tree of cells annotating the entire interaction—like an accessibility tree, but for data. Currently used for debugging and inspection; future features will build on this structure.
+
+# Automatic Injection
+
+Every `[UI]` render is automatically wrapped in `ct-cell-context`. You get top-level charm debugging for free without any code changes.
+
+# When to Use Manually
+
+Add `ct-cell-context` sparingly—typically 1-2 per pattern at most. Use it for values that are:
+
+- Important but otherwise difficult to access
+- Intermediate calculations or API responses
+- Values you'd otherwise debug with `console.log`
+
+This is better than adding a `derive` with `console.log` because inspection is conditional—users can watch and unwatch values on demand rather than flooding the console.
+
+```tsx
+<ct-cell-context $cell={result} label="Calculation Result">
+  <div>{result.value}</div>
+</ct-cell-context>
+```
+
+# API
+
+- `$cell` - The Cell to associate with this region
+- `label` - Human-readable name shown in the toolbar (optional)
+- `inline` - Display as inline-block instead of block (optional)
+
+# Debugging
+
+Hold **Alt** and hover over a cell context region to see the debugging toolbar:
+
+- **val** - Log the cell value to console and set `globalThis.$cell` to the cell, making it accessible via the console for inspection (similar to Chrome's `$0` for elements)
+- **id** - Log the cell's full address
+- **watch/unwatch** - Subscribe to value changes; updates appear in the debugger's Watch List
+
+# When NOT to Use
+
+- Don't wrap every cell—reserve for important values
+- Don't use for trivial or obviously-accessible values
+- If a value is already easy to inspect via the UI, you probably don't need this
diff --git a/packages/ui/src/v2/components/ct-cell-context/ct-cell-context.ts b/packages/ui/src/v2/components/ct-cell-context/ct-cell-context.ts
index 83b97f800b..c01a536583 100644
--- a/packages/ui/src/v2/components/ct-cell-context/ct-cell-context.ts
+++ b/packages/ui/src/v2/components/ct-cell-context/ct-cell-context.ts
@@ -31,7 +31,7 @@ export class CTCellContext extends BaseElement {
       }
 
       :host([inline]) {
-        display: inline;
+        display: inline-block;
       }
 
       .container {