docs updates

Author: Yasser Toruno

README.md

@@ -52,7 +52,7 @@ The only runtime dependency is Django. `dj-control-room` is optional and only ne
 
 ### Panel tools
 
-`PanelConfig` accepts an optional `tools` list of `PanelTool` instances. Each tool carries a name, a scope (reusing the same permission system as views), a human-readable description, a JSON Schema for its inputs, and a handler callable. When installed panels expose tools, the `dj-control-room` hub aggregates them across all panels, filters by the current user's permissions at request time, and dispatches calls through a unified endpoint — suitable for AI agent integrations and an in-admin chat experience with no per-panel HTTP wiring required.
+`PanelConfig` accepts an optional `tools` list of `PanelTool` instances. Each tool carries a name, a scope (reusing the same permission system as views), a human-readable description, a JSON Schema for its inputs, and a handler callable. When installed panels expose tools, the `dj-control-room` hub aggregates them across all panels, filters by the current user's permissions at request time, and dispatches calls through a unified endpoint, suitable for AI agent integrations and an in-admin chat experience with no per-panel HTTP wiring required.
 
 ## Screenshots
 
@@ -177,7 +177,7 @@ DJ_MY_PANEL_SETTINGS = {
 }
 ```
 
-`themes/unfold.css` remaps DCR's accent/surface/border/muted tokens to [django-unfold](https://github.com/unfoldadmin/django-unfold)'s own CSS variables (`--color-primary-*`, `--color-base-*`, `--color-font-*`), so panels match the host site's configured brand color. `themes/jazzmin.css` does the same for [django-jazzmin](https://github.com/farridav/django-jazzmin), mapping onto Bootstrap 5's `--bs-primary`, `--bs-body-*`, and `--bs-border-color` variables so panels track whichever Bootswatch theme Jazzmin is configured with. See the [configuration docs](https://django-control-room.github.io/dj-control-room-base/configuration/#theme-adapters) for details.
+`themes/unfold.css` matches panels to your [django-unfold](https://github.com/unfoldadmin/django-unfold) brand color, and `themes/jazzmin.css` does the same for [django-jazzmin](https://github.com/farridav/django-jazzmin), tracking whichever Bootswatch theme it's configured with. See the [configuration docs](https://django-control-room.github.io/dj-control-room-base/configuration/#theme-adapters) for details, or [Theme Adapters](https://django-control-room.github.io/dj-control-room-base/themes/) for a visual gallery.
 
 ### Permission settings
 

docs/building-panels.md

@@ -201,13 +201,13 @@ The base template automatically handles `dj_cr_load_default_css` and `dj_cr_extr
 
 Panel tools are optional, structured callables that the `dj-control-room` hub can aggregate across all installed panels and expose through a unified API. They are designed to power AI agent integrations (where an LLM calls tools on your behalf) and an in-admin chat experience, but they are generic enough to be used in any context that needs a structured, permission-aware callable.
 
-Tools reuse the same scope-based permission system as views — no separate permission wiring is needed.
+Tools reuse the same scope-based permission system as views, so no separate permission wiring is needed.
 
 ### Tool primitives
 
 All four are importable from `dj_control_room_base.core.panel_tool`:
 
-**`PanelTool`** — the tool definition. You'll rarely construct this directly (see `ToolRegistry` below), but it's what ends up on `PanelConfig.tools`:
+**`PanelTool`** - the tool definition. You'll rarely construct this directly (see `ToolRegistry` below), but it's what ends up on `PanelConfig.tools`:
 
 | Field | Type | Description |
 |---|---|---|
@@ -217,27 +217,27 @@ All four are importable from `dj_control_room_base.core.panel_tool`:
 | `input_schema` | `dict` | [JSON Schema](https://json-schema.org) object describing the tool's input arguments. Tools that take no arguments should use `{"type": "object", "properties": {}}`. |
 | `handler` | `Callable` | A function that receives a `PanelToolContext` and returns a `PanelToolResult`. |
 
-**`PanelToolContext`** — passed to the handler at call time:
+**`PanelToolContext`** - passed to the handler at call time:
 
 | Field | Type | Description |
 |---|---|---|
 | `user` | `Any` | The Django `User` object of the caller. |
 | `inputs` | `dict` | The validated input arguments for this call, matching the tool's `input_schema`. |
 | `config` | `Any` | The panel's `PanelConfig` instance, injected by the hub dispatcher. |
 
-**`PanelToolResult`** — returned by the handler:
+**`PanelToolResult`** - returned by the handler:
 
 | Field | Type | Description |
 |---|---|---|
 | `success` | `bool` | Whether the tool call succeeded. |
 | `message` | `str` | A short human-readable summary of the outcome. |
 | `data` | `dict` | The structured result payload. Defaults to `{}`. |
 
-**`ToolRegistry`** — collects `PanelTool`s via a `@registry.register(...)` decorator, so each tool's metadata lives directly above the handler it describes instead of in a separate list you have to keep in sync. This is the recommended way to define tools (see below).
+**`ToolRegistry`** - collects `PanelTool`s via a `@registry.register(...)` decorator, so each tool's metadata lives directly above the handler it describes instead of in a separate list you have to keep in sync. This is the recommended way to define tools (see below).
 
 ### Defining tools
 
-Keep handlers in a dedicated `tools.py` module. Use local imports inside handlers for anything that touches Django models — this keeps the module safe to import at any point in the Django startup sequence.
+Keep handlers in a dedicated `tools.py` module. Use local imports inside handlers for anything that touches Django models, which keeps the module safe to import at any point in the Django startup sequence.
 
 Instantiate one `ToolRegistry` per `tools.py` module and decorate each handler with `@registry.register(...)`:
 
@@ -265,7 +265,7 @@ registry = ToolRegistry()
     },
 )
 def handle_get_item(ctx: PanelToolContext) -> PanelToolResult:
-    from .models import Item  # local import — safe at any startup stage
+    from .models import Item  # local import - safe at any startup stage
 
     key = ctx.inputs["key"]
     try:
@@ -296,7 +296,7 @@ def handle_list_items(ctx: PanelToolContext) -> PanelToolResult:
     )
 ```
 
-The decorator only records metadata as a side effect — it returns the handler unchanged, so `handle_get_item` and `handle_list_items` remain plain, directly callable functions (e.g. in tests, just call `handle_get_item(ctx)`).
+The decorator only records metadata as a side effect: it returns the handler unchanged, so `handle_get_item` and `handle_list_items` remain plain, directly callable functions (e.g. in tests, just call `handle_get_item(ctx)`).
 
 ### Registering tools on `PanelConfig`
 
@@ -320,7 +320,7 @@ Panel authors do not need to write any URL configuration for tools as this will
 
 #### Building the list manually
 
-`ToolRegistry` is a convenience, not a requirement — `PanelConfig(tools=...)` just needs a `list[PanelTool]`. If you'd rather construct `PanelTool` instances directly (e.g. building the list programmatically from some other source), that still works:
+`ToolRegistry` is a convenience, not a requirement - `PanelConfig(tools=...)` just needs a `list[PanelTool]`. If you'd rather construct `PanelTool` instances directly (e.g. building the list programmatically from some other source), that still works:
 
 ```python
 from dj_control_room_base.core.panel_tool import PanelTool
@@ -399,7 +399,7 @@ That is the full wiring. One `PanelConfig` declaration in `conf.py` gives all vi
 |---|---|---|
 | `get_url_name()` | `"index"` | URL name for the panel's main view. The hub resolves `reverse(f"{app_name}:{get_url_name()}")`. |
 | `get_config()` | `None` | Return the panel's `PanelConfig` instance. Override using a local import (see above). |
-| `validate()` | — | Assert all required attributes are set. Convenience method for tests; the registry runs its own validation at autodiscovery time. |
+| `validate()` | n/a | Assert all required attributes are set. Convenience method for tests; the registry runs its own validation at autodiscovery time. |
 
 ---
 
@@ -433,7 +433,7 @@ Returns `True` if the request's user may access the panel or a specific scope. T
 
 ### `panel_config._check_permission(user, scope=None)`
 
-Returns `True` if `user` may access the panel or a specific scope. Operates on a user object directly so it can be called outside of a request context — for example in tool dispatch, management commands, or background tasks.
+Returns `True` if `user` may access the panel or a specific scope. Operates on a user object directly so it can be called outside of a request context, for example in tool dispatch, management commands, or background tasks.
 
 ### `@panel_config.permission_required(scope=None)`
 

docs/configuration.md

@@ -101,11 +101,7 @@ Currently available:
 | `themes/unfold.css` | Projects using [django-unfold](https://github.com/unfoldadmin/django-unfold) as their admin skin. |
 | `themes/jazzmin.css` | Projects using [django-jazzmin](https://github.com/farridav/django-jazzmin) as their admin skin. |
 
-`themes/unfold.css` remaps a handful of `--dcr-*` tokens (accent color, surfaces, borders, muted text) to Unfold's own `--color-primary-*` / `--color-base-*` / `--color-font-*` CSS variables, so panels pick up the host site's configured brand color instead of DCR's classic-admin blue. It only touches tokens - never `dcr-*` component rules - and every override falls back to DCR's own default if the Unfold variable isn't present, so it's safe to load even if Unfold changes its internals in a future release. Semantic status colors (success/warning/danger/info) are left alone, since Unfold doesn't expose those as configurable brand colors.
-
-`themes/jazzmin.css` follows the same approach for Jazzmin's Bootstrap 5 foundation, remapping the same set of tokens to `--bs-body-color`, `--bs-border-color`, `--bs-secondary-color`, `--bs-tertiary-bg`, `--bs-primary`, and `--bs-primary-bg-subtle` - so panels track whatever Bootswatch theme is configured via `JAZZMIN_UI_TWEAKS["theme"]` instead of hardcoding one palette. Same fallback safety and same scope (tokens only, no `dcr-*` component rules, semantic status colors untouched).
-
-Both adapters rely on `design-system.css` already recognizing the host skin's dark-mode signal so the *default* DCR palette (not just the adapter's own overrides) switches correctly: Unfold toggles a plain `dark` class on `<html>`, while Jazzmin (via Bootstrap 5) sets `data-bs-theme="dark"` on `<html>`. Both are handled automatically - no extra configuration needed beyond loading the adapter's stylesheet.
+`themes/unfold.css` maps DCR's tokens onto [django-unfold](https://github.com/unfoldadmin/django-unfold)'s own CSS variables, so panels automatically pick up the host site's configured brand color. `themes/jazzmin.css` does the same for [django-jazzmin](https://github.com/farridav/django-jazzmin), tracking whichever Bootswatch theme (light or dark) is configured via `JAZZMIN_UI_TWEAKS["theme"]`. Both only touch tokens, never `dcr-*` component rules, and dark mode is handled automatically - no extra configuration needed beyond loading the stylesheet.
 
 Because this is opt-in per panel rather than hub-wide, each panel you want themed needs its own `EXTRA_CSS` entry for now.
 

docs/index.md

@@ -41,7 +41,7 @@ Panels register themselves with Control Room via a `pyproject.toml` entry point
 
 ### Panel tools
 
-`PanelConfig` accepts an optional `tools` list of `PanelTool` instances. Each tool declares a name, a scope (reusing the same permission system as views), a description, a JSON Schema for its inputs, and a handler callable. When a panel exposes tools, the `dj-control-room` hub aggregates them into a central registry, filters by user permissions, and dispatches calls through a unified endpoint — enabling AI agent integrations and an in-admin chat experience without any per-panel HTTP wiring. See [Building Panels — Panel Tools](building-panels.md#panel-tools) for the full guide.
+`PanelConfig` accepts an optional `tools` list of `PanelTool` instances. Each tool declares a name, a scope (reusing the same permission system as views), a description, a JSON Schema for its inputs, and a handler callable. When a panel exposes tools, the `dj-control-room` hub aggregates them into a central registry, filters by user permissions, and dispatches calls through a unified endpoint, enabling AI agent integrations and an in-admin chat experience without any per-panel HTTP wiring. See [Building Panels - Panel Tools](building-panels.md#panel-tools) for the full guide.
 
 ---
 

docs/themes.md

@@ -30,7 +30,7 @@ DJ_MY_PANEL_SETTINGS = {
 
 ## django-jazzmin
 
-[`django-jazzmin`](https://github.com/farridav/django-jazzmin) is built on Bootstrap 5 and ships as a set of [Bootswatch](https://bootswatch.com/) skins, selected via `JAZZMIN_UI_TWEAKS["theme"]`. `themes/jazzmin.css` maps the same DCR tokens onto Bootstrap's `--bs-*` variables (`--bs-primary`, `--bs-body-*`, `--bs-border-color`, `--bs-secondary-color`, ...), with per-theme accent and dark-mode fallbacks sourced from each Bootswatch palette - so panels track whichever theme is active without any extra configuration.
+[`django-jazzmin`](https://github.com/farridav/django-jazzmin) is built on Bootstrap 5 and ships as a set of [Bootswatch](https://bootswatch.com/) skins, selected via `JAZZMIN_UI_TWEAKS["theme"]`. `themes/jazzmin.css` maps DCR's tokens onto Bootstrap's own CSS variables, so panels track whichever theme is active, including Jazzmin's dark skins, without any extra configuration.
 
 ```python
 DJ_MY_PANEL_SETTINGS = {
@@ -46,10 +46,10 @@ All of Jazzmin's built-in Bootswatch themes are covered, each with its own accen
 |---|---|
 | `cerulean`, `cosmo`, `flatly`, `journal`, `litera`, `lumen`, `lux`, `materia`, `minty`, `pulse`, `sandstone`, `simplex`, `sketchy`, `spacelab`, `united`, `yeti` | `cyborg`, `darkly`, `slate`, `solar`, `superhero` |
 
-Dark themes are detected via the `body.theme-<name>` class Jazzmin applies (not `data-bs-theme`, which Jazzmin doesn't document or set) - see [`ui_customisation`](https://django-jazzmin.readthedocs.io/ui_customisation/) for the full list Jazzmin ships.
+See [`ui_customisation`](https://django-jazzmin.readthedocs.io/ui_customisation/) for the full list of themes Jazzmin ships.
 
 ---
 
 ## Build your own
 
-Both adapters follow the same recipe: remap `--dcr-*` tokens to the host skin's variables, fall back to DCR's own defaults when a variable is missing, and leave semantic status colors (success/warning/danger/info) untouched since most skins don't expose those as configurable brand colors. This works well for any Tailwind CSS or Bootstrap admin skin that exposes its palette as CSS custom properties - use `unfold.css` or `jazzmin.css` as a starting point.
+Both adapters follow the same recipe: remap `--dcr-*` tokens to the host skin's own variables, with sensible fallbacks. This works well for any Tailwind CSS or Bootstrap admin skin that exposes its palette as CSS custom properties - use `unfold.css` or `jazzmin.css` as a starting point.