added the cli-client skill

.github/copilot-instructions.md

@@ -2,7 +2,7 @@
 
 This repository is resource-first.
 
-- Canonical skill guidance lives in `docs/skills/<skill-id>/SKILL.md`.
+- Canonical skill guidance lives in `src/personal_mcp/docs/skills/<skill-id>/SKILL.md`.
 - Skills are exposed through FastMCP's native `skill://` resource family.
 - Prompts are exposed through native MCP prompt operations (`prompts/list`, `prompts/get`).
 - General documentation pages are exposed through `resource://docs/{path*}`.

.github/instructions/authoring.instructions.md

@@ -1,19 +1,19 @@
 ---
 name: Authoring Content
-description: "Use when editing Markdown under docs/. Routes authors to the canonical docs ownership, layout, and symlink guidance."
-applyTo: 'docs/**/*.md'
+description: "Use when editing Markdown under src/personal_mcp/docs/. Routes authors to the canonical docs ownership and layout guidance."
+applyTo: 'src/personal_mcp/docs/**/*.md'
 ---
 
-For edits under `docs/`, use the [Authoring Guide](../../docs/authoring.md) as the entry point for content placement and contracts.
+For edits under `src/personal_mcp/docs/`, use the [Authoring Guide](../../src/personal_mcp/docs/authoring.md) as the entry point for content placement and contracts.
 
-For source-tree ownership, symlink, packaging, or runtime questions, follow [Source Tree Ownership](../../docs/authoring.md). Treat that section as authoritative instead of restating its guidance here.
+For source-tree ownership, packaging, or runtime questions, follow [Source Tree Ownership](../../src/personal_mcp/docs/authoring.md). Treat that section as authoritative instead of restating its guidance here.
 
 
 Primary references:
-- [Skill contract](../../docs/contracts/skill_contract.md)
-- [Prompt contract](../../docs/contracts/prompt.md)
-- [Frontmatter contract](../../docs/contracts/frontmatter.md)
-- [URI contract](../../docs/contracts/uris.md)
+- [Skill contract](../../src/personal_mcp/docs/contracts/skill_contract.md)
+- [Prompt contract](../../src/personal_mcp/docs/contracts/prompt.md)
+- [Frontmatter contract](../../src/personal_mcp/docs/contracts/frontmatter.md)
+- [URI contract](../../src/personal_mcp/docs/contracts/uris.md)
 - `skill://zensical-docs/SKILL.md`
 
 Inspect `skill://zensical-docs/_manifest` only when a supporting documentation reference is needed.

.github/instructions/pytesting.instructions.md

@@ -21,4 +21,4 @@ Execution pattern:
 
 If task intent is ambiguous, ask one clarifying question before editing.
 
-Be sure to also refer to the [testing page](../../docs/testing.md) page for design detail
+Be sure to also refer to the [testing page](../../src/personal_mcp/docs/testing.md) for design detail.

.github/prompts/pytest-fill-scaffold.prompt.md

@@ -26,11 +26,11 @@ Use this prompt after test scaffolding exists and method names/docstrings are al
 
 Load these in order and use only what matches the task:
 
-1. Core defaults: [pytest scaffolding skill](../../docs/skills/pytesting/SKILL.md)
-2. Naming/hierarchy preservation: [naming and organization](../../docs/skills/pytesting/references/naming-and-organization.md)
-3. Baseline pytest fixtures/markers: [pytest docs notes](../../docs/skills/pytesting/references/pytest-docs.md)
-4. FastAPI-specific behavior (only when needed): [fastapi testing](../../docs/skills/pytesting/references/fastapi-testing.md)
-5. SQLAlchemy-specific behavior (only when needed): [sqlalchemy testing](../../docs/skills/pytesting/references/sqlalchemy-testing.md)
+1. Core defaults: [pytest scaffolding skill](../../src/personal_mcp/docs/skills/pytesting/SKILL.md)
+2. Naming/hierarchy preservation: [naming and organization](../../src/personal_mcp/docs/skills/pytesting/references/naming-and-organization.md)
+3. Baseline pytest fixtures/markers: [pytest docs notes](../../src/personal_mcp/docs/skills/pytesting/references/pytest-docs.md)
+4. FastAPI-specific behavior (only when needed): [fastapi testing](../../src/personal_mcp/docs/skills/pytesting/references/fastapi-testing.md)
+5. SQLAlchemy-specific behavior (only when needed): [sqlalchemy testing](../../src/personal_mcp/docs/skills/pytesting/references/sqlalchemy-testing.md)
 
 ## Workflow
 

.github/prompts/pytest-scaffold.prompt.md

@@ -24,8 +24,8 @@ Use this prompt to do in one run what we have been doing manually in chat:
 
 ## Repository Rules To Apply
 
-- Use [pytest scaffolding skill](../../docs/skills/pytesting/SKILL.md) for strategy and defaults.
-- Use [naming and organization reference](../../docs/skills/pytesting/references/naming-and-organization.md) before finalizing hierarchy.
+- Use [pytest scaffolding skill](../../src/personal_mcp/docs/skills/pytesting/SKILL.md) for strategy and defaults.
+- Use [naming and organization reference](../../src/personal_mcp/docs/skills/pytesting/references/naming-and-organization.md) before finalizing hierarchy.
 - Use `uv run pytest --collect-only -q` as structural validation.
 - Default to a source-mirror style adapted to this repository:
   - map selected modules to `tests/` with concise path segments when requested

pyproject.toml

@@ -31,6 +31,7 @@ dev = [
     "ty>=0.0.51",
 ]
 test = [
+    "asgi-lifespan>=2.1.0",
     "httpx2>=2.9.1",
     "pytest>=9.1.1",
     "pytest-asyncio>=1.4.0",

src/personal_mcp/app.py

@@ -8,6 +8,7 @@ from fastapi import Response
 from fastapi import status
 from fastapi.responses import RedirectResponse
 from fastapi.staticfiles import StaticFiles
+from fastmcp.utilities.lifespan import combine_lifespans
 
 from .config import Settings
 from .config import get_settings
@@ -17,7 +18,9 @@ from .mcp import create_mcp
 def create_app(settings: Settings | None = None) -> FastAPI:
     runtime_settings = settings if settings is not None else get_settings()
     docs_route = runtime_settings.mounts.docs.rstrip("/") or "/docs"
+    mcp_route = runtime_settings.mounts.mcp.rstrip("/") or "/mcp"
     mcp_app = create_mcp().http_app(
+        path=mcp_route,
         json_response=True,
         stateless_http=True,
         transport="http",
@@ -27,7 +30,7 @@ def create_app(settings: Settings | None = None) -> FastAPI:
         docs_url=None,
         redoc_url=None,
         openapi_url=None,
-        lifespan=app_lifespan,
+        lifespan=combine_lifespans(app_lifespan, mcp_app.lifespan),
     )
     app.state.settings = runtime_settings
 
@@ -44,7 +47,7 @@ def create_app(settings: Settings | None = None) -> FastAPI:
         include_in_schema=False,
     )
 
-    app.mount(runtime_settings.mounts.mcp, mcp_app, name="mcp")
+    app.router.routes.extend(mcp_app.routes)
     return app
 
 

src/personal_mcp/docs/architecture.md

@@ -4,102 +4,40 @@ icon: lucide/library
 
 # Architecture
 
-## Overview
+Personal MCP is a small publishing service. Markdown is written once and made available in two ways:
 
-The application combines a FastMCP server with a pre-built Zensical documentation site. Markdown under `docs/` is the single authored content tree, while native FastMCP providers own skill and prompt discovery.
+1. as an MCP server for AI clients
+2. as a documentation website for people
 
-The runtime has four content paths:
-
-1. `SkillsDirectoryProvider` publishes native `skill://` resources from packaged skill directories.
-2. A custom prompt provider loads declarative prompt definitions from packaged Markdown.
-3. The general docs registry publishes non-skill Markdown through `resource://docs/{path*}`.
-4. FastAPI serves the pre-built `site/` directory.
-
-There is no custom skill catalog, prompt catalog, or per-prompt Python module.
-
-## Source Ownership
-
-### Skills
-
-Each skill owns one directory:
-
-1. `docs/skills/<skill-id>/SKILL.md`
-2. `docs/skills/<skill-id>/<supporting-path>`
-
-`SkillsDirectoryProvider` publishes:
-
-1. `skill://<name>/SKILL.md`
-2. `skill://<name>/_manifest`
-3. `skill://<name>/{path*}`
-
-The provider parses standard skill frontmatter and generates the manifest. The general docs registry excludes `skills/**`, so only the native provider owns this namespace.
-
-### Prompts
-
-Each prompt has one source: `docs/prompts/<prompt-id>/PROMPT.md`. Its nested `prompt` frontmatter owns runtime metadata and argument declarations, while its body owns canonical prose.
-
-The custom provider reads packaged Markdown with `importlib.resources`, validates metadata and exact placeholder-to-argument equality, and creates native FastMCP prompt objects. It rescans on each list and get request, so an editable deployment observes file additions, edits, and deletions without a restart.
-
-FastMCP exposes prompts through native `prompts/list` and `prompts/get` operations.
-
-### General Docs
-
-The docs registry indexes packaged Markdown for `resource://docs/{path*}`. It rejects `skills/**` because skills are provider-owned. Prompt Markdown can remain visible as general documentation, but prompt invocation is owned by the native prompt provider.
-
-## Runtime Composition
+## How It Fits Together
 
 ```mermaid
-flowchart TD
-    A[Packaged Skill Directories] --> B[SkillsDirectoryProvider]
-    C[Packaged Prompt Markdown] --> D[Markdown Prompt Provider]
-    F[General Markdown] --> G[Docs Registry]
-    B --> H[FastMCP Server]
-    D --> H
-    G --> H
-    H --> K[MCP Transport]
-    L[Zensical Site Output] --> M[FastAPI Static Mount]
-    K --> M
+flowchart LR
+    A[Markdown in src/personal_mcp/docs] --> B[MCP resources and prompts]
+    A --> C[Documentation website]
+    B --> D[AI clients]
+    C --> E[Human readers]
 ```
 
-Server construction is lazy with respect to package import. Each application process creates its providers and docs snapshot when the server factory runs. Skills use startup discovery, while prompts are reloaded when a client lists or gets prompts.
+The running application has two routes:
 
-## Packaging
+- `/mcp` is the MCP endpoint.
+- `/docs/` is the pre-built documentation site.
 
-The repository root `docs/` directory is the only authored Markdown source. `src/personal_mcp/docs` is a relative symlink used by source checkouts and editable installs. Hatchling follows it and stores regular files beneath `personal_mcp/docs/` in the wheel.
+The root URL redirects to the website.
 
-Runtime reads are package-relative:
+## Content Types
 
-1. Prompt content and general docs use `importlib.resources` and `Traversable` APIs.
-2. `SkillsDirectoryProvider` receives the packaged `personal_mcp/docs/skills` filesystem path.
-3. No runtime content lookup depends on the current working directory.
+The server publishes three kinds of Markdown content:
 
-## Public Contracts
+- **Skills** are reusable guidance that clients read as `skill://` resources.
+- **Prompts** are parameterized workflows that clients invoke as MCP prompts.
+- **Documentation** is available to clients through `resource://docs/...` and to people on the website.
 
-The machine-facing surfaces are:
+FastMCP provides the MCP behavior. FastAPI hosts that server beside the static site, and Zensical builds the site from the same Markdown files.
 
-1. Native skill resources under `skill://<name>/...`.
-2. Native MCP prompt list and get operations.
-3. `resource://docs/{path*}` for general Markdown.
+## Source Of Truth
 
-Canonical contracts are documented in:
+All authored content lives under `src/personal_mcp/docs/`. The generated `src/personal_mcp/site/` directory is build output and should not be edited by hand.
 
-1. [Prompt Contract](./contracts/prompt.md)
-2. [Skill Contract](./contracts/skill_contract.md)
-3. [Frontmatter Contract](./contracts/frontmatter.md)
-4. [URI Contract](./contracts/uris.md)
-
-Only these canonical provider and protocol surfaces are registered.
-
-## Static Documentation
-
-Zensical builds `docs/` into `site/` before deployment. FastAPI mounts that immutable output in the same process that hosts FastMCP. Generated `site/` files are deployment assets and are never an authored source.
-
-## Validation
-
-Changes are accepted only after:
-
-1. focused provider and protocol tests
-2. Ruff and ty checks
-3. a Zensical build
-4. the full pytest suite
-5. an installed-wheel smoke test when packaging or provider paths change
+For exact file formats and URI rules, see the [content contracts](./contracts/index.md). For everyday changes, start with the [Authoring Guide](./authoring.md).

src/personal_mcp/docs/authoring.md

@@ -4,128 +4,68 @@ icon: lucide/pencil
 
 # Authoring Guide
 
-This page defines the practical workflow for maintaining skills, prompts, and project documentation while keeping root `docs/` as the only authored source.
-
-Primary references:
-
-1. [Skill Contract](./contracts/skill_contract.md)
-2. [Prompt Contract](./contracts/prompt.md)
-3. [Frontmatter Contract](./contracts/frontmatter.md)
-4. [URI Contract](./contracts/uris.md)
-5. [Zensical documentation skill](./skills/zensical-docs/SKILL.md)
+All authored content lives under `src/personal_mcp/docs/`. The same files feed the MCP server and the documentation website.
 
 ## Source Tree Ownership
 
-Edit content only under root `docs/`. The `src/personal_mcp/docs` path is a relative symlink for editable installs; do not author through a copied package tree.
-
-Hatchling's normal package traversal follows `src/personal_mcp/docs` during wheel builds and archives the linked targets as regular files under `personal_mcp/docs/`. Do not add a `force-include` entry for root `docs/`; it duplicates those wheel paths. The installed package therefore gives `SkillsDirectoryProvider` a regular filesystem directory while Zensical builds the human site directly from root `docs/`.
-
-Generated `site/` content is a build artifact and must not be edited by hand.
-
-## Content Layout
-
 ```text
-docs/
-    *.md
-    contracts/
+src/personal_mcp/docs/
+    *.md                         # General documentation
     prompts/<prompt-id>/
-        PROMPT.md
-        references/
+        PROMPT.md                # One MCP prompt
     skills/<skill-name>/
-        SKILL.md
-        references/
+        SKILL.md                 # Main skill guidance
+        references/              # Optional supporting material
 ```
 
-Keep skill and prompt files inside their owning directories. Relative links may cross sections, but content ownership should remain clear.
+Do not edit `src/personal_mcp/site/` by hand. It is generated by Zensical.
+
+## Documentation Pages
+
+Add general documentation as Markdown under `src/personal_mcp/docs/`. Use relative links between pages. Top-level pages need an `icon` in their frontmatter, and navigation changes belong in `zensical.toml`.
 
 ## Skill Authoring
 
-A skill is discovered when a direct child of `docs/skills/` contains `SKILL.md`.
-
-Required frontmatter:
+Skills follow the [Agent Skills specification](https://agentskills.io/specification). Each skill is a directory containing a required `SKILL.md` file with YAML frontmatter and Markdown instructions:
 
 ```yaml
 ---
 name: <skill-name>
-description: <what the skill does and when to use it>
+description: <what this skill covers and when to use it>
 ---
 ```
 
-Rules:
+The specification requires:
 
-1. Use lowercase kebab-case for the directory and `name`.
-2. Keep `name` exactly equal to the directory name.
-3. Write a specific description because clients use it for discovery.
-4. Do not add `x-personal-mcp`, versions, tags, capabilities, or reference mappings.
-5. Put supporting material anywhere beneath the skill directory, normally under `references/`.
-6. Link supporting files from `SKILL.md` so humans and agents understand when to load them.
+1. `name` must match the directory name, contain 1-64 lowercase letters, numbers, or hyphens, and have no leading, trailing, or consecutive hyphens.
+2. `description` must contain 1-1024 characters and explain both what the skill does and when an agent should use it.
+3. The body of `SKILL.md` must contain the instructions an agent needs after selecting the skill.
 
-FastMCP recursively scans every skill file and generates `skill://<name>/_manifest`. Supporting-resource identity is the real relative path, not a synthetic reference id.
+This repository adds two narrower conventions: names start with a letter, and frontmatter contains only the required `name` and `description`. The specification also defines optional `license`, `compatibility`, `metadata`, and experimental `allowed-tools` fields, but they are not part of this repository's current [Skill Contract](./contracts/skill_contract.md).
 
-Recommended sequence:
+Write skills for progressive disclosure. Keep discovery information in the frontmatter, the main workflow in `SKILL.md`, and detailed material in focused files under `references/`. Link to supporting files with paths relative to the skill root, and avoid chains of references that require an agent to open several files before finding the useful content.
 
-1. Draft or revise `SKILL.md` routing guidance.
-2. Add focused supporting files.
-3. Verify relative links.
-4. Run the provider tests and docs build.
-5. Restart running servers because production uses `reload=False`.
+The Agent Skills specification also permits `scripts/`, `assets/`, and other supporting directories. This project is primarily a guidance library, so prefer `references/` unless the skill genuinely needs executable or static resources.
+
+[FastMCP's Skills Provider](https://gofastmcp.com/servers/providers/skills) publishes each compliant directory as MCP resources, including the main file, a generated manifest, and any supporting files. The specification's [`skills-ref` validator](https://github.com/agentskills/agentskills/tree/main/skills-ref) can validate an individual skill before the repository-wide checks run.
 
 ## Prompt Authoring
 
-A prompt is one self-describing `docs/prompts/<prompt-id>/PROMPT.md` file:
+A prompt is one `PROMPT.md` file under `src/personal_mcp/docs/prompts/<prompt-id>/`. Its `prompt` frontmatter describes the workflow and arguments; its Markdown body contains the instructions.
 
-1. Create a lowercase kebab-case directory beneath `docs/prompts/`.
-2. Add a nested `prompt` frontmatter mapping with version, description, tags, and ordered arguments.
-3. Give every argument a description and explicit required flag.
-4. Add `choices` only when a string argument accepts a fixed set of values.
-5. Use each argument exactly once or more as a `{{argument_name}}` placeholder in the body.
-6. Do not add a Python component, name field, metadata sidecar, or central catalog entry.
+Use each declared argument as a `{{placeholder}}` in the body. The server validates prompt metadata and placeholders when the prompt is discovered.
 
-The custom provider rescans prompt documents during every native list and get request. Changes in an editable checkout are therefore visible on the next request without a process restart. Invalid metadata or placeholder drift fails that request with a configuration error.
+The [Prompt Contract](./contracts/prompt.md) and [Frontmatter Contract](./contracts/frontmatter.md) contain the exact schema.
 
-## Frontmatter Safety
-
-1. Quote scalar values containing `:`.
-2. Quote values with reserved YAML characters such as `#`, `{}`, `[]`, or leading `*`.
-3. Use block scalars for punctuation-heavy multiline text.
-4. Keep fields within the applicable skill or documentation contract.
-
-## Writing Quality
-
-1. Prefer focused sections and descriptive headings.
-2. Link feature-level claims to authoritative sources.
-3. Use relative links for internal pages.
-4. Keep code examples minimal and actionable.
-5. Avoid bare URLs in prose.
-6. Load only supporting material relevant to the immediate task.
-
-## Copilot Routing
-
-Active instructions should point directly to native main resources:
-
-1. `skill://zensical-docs/SKILL.md`
-2. `skill://pytesting/SKILL.md`
-3. `skill://vscode-configuration/SKILL.md`
-
-When deeper guidance is needed, read the selected skill's `_manifest` and fetch supporting files by their listed path.
-
-## Validation Checklist
+## Validate Changes
 
 ```bash
-uv run pytest tests/skills/test_provider.py tests/web/test_mcp_skills.py -q
 uv run zensical build
 uv run ruff check .
 uv run ty check
 uv run pytest
 ```
 
-For packaging changes, also build and inspect an installed wheel so provider path resolution is verified outside the editable checkout.
+Restart a running server after changing content so every surface reads the latest package data.
 
-## Navigation
-
-When adding or moving pages:
-
-1. update `zensical.toml`
-2. keep top-level page icons in frontmatter
-3. rebuild the site
-4. verify internal links and navigation labels
+For detailed rules, see the [content contracts](./contracts/index.md). For writing and site features, use the [Zensical documentation skill](./skills/zensical-docs/SKILL.md).

src/personal_mcp/docs/contracts/frontmatter.md

@@ -69,4 +69,4 @@ Prompt validation is provider- and renderer-oriented. Every list or get request
 1. Skills remain directly portable to tools that understand standard Agent Skills directories.
 2. Native skill discovery has no parallel catalog metadata source.
 3. Prompts use FastMCP's native component metadata and protocol surface without a parallel catalog or Python component file.
-4. All authored content remains under `docs/`.
+4. All authored content remains under `src/personal_mcp/docs/`.

src/personal_mcp/docs/contracts/index.md

@@ -21,13 +21,13 @@ This page defines the authored content contract for the docs-first MCP architect
 
 ## Canonical Source Of Truth
 
-1. All authored Markdown lives under `docs/`.
+1. All authored Markdown lives under `src/personal_mcp/docs/`.
 2. MCP resources and static docs are two distribution surfaces of the same authored files.
-3. No parallel authored markdown is allowed in `src/` or other package-only paths.
+3. No parallel authored Markdown is allowed in a root `docs/` directory or another source tree.
 
 ## Canonical Content Shape
 
-Authored content is organized under `docs/`:
+Authored content is organized under `src/personal_mcp/docs/`:
 
 ```mermaid
 ---
@@ -41,7 +41,7 @@ config:
             lineColor: '#FFFFFF'
 ---
 treeView-beta
-  "docs/"
+  "src/personal_mcp/docs/"
     "*.md (top-level docs pages)"
     "contracts/"
       "prompt.md"
@@ -59,9 +59,9 @@ treeView-beta
 
 ## File Placement And Ownership Boundaries
 
-1. Top-level project docs stay in `docs/*.md`.
-2. Skill docs stay in `docs/skills/<skill-id>/...`.
-3. Prompt docs stay in `docs/prompts/<prompt-id>/...`.
+1. Top-level project docs stay in `src/personal_mcp/docs/*.md`.
+2. Skill docs stay in `src/personal_mcp/docs/skills/<skill-id>/...`.
+3. Prompt docs stay in `src/personal_mcp/docs/prompts/<prompt-id>/...`.
 4. A skill or prompt may link across sections, but must not store content in another artifact's directory.
 5. Server and runtime code may index and serve docs, but must not be the source of authored markdown.
 
@@ -74,7 +74,7 @@ treeView-beta
 
 This contract guarantees:
 
-1. One authored source tree in `docs/` for both website and MCP.
+1. One authored source tree in `src/personal_mcp/docs/` for both website and MCP.
 2. Skill and prompt artifacts remain path-stable within their own sections.
 3. Cross-surface publishing remains deterministic because authored content paths are canonical.
 

src/personal_mcp/docs/contracts/prompt.md

@@ -22,7 +22,7 @@ config:
             lineColor: '#FFFFFF'
 ---
 treeView-beta
-    "docs/prompts/"
+        "src/personal_mcp/docs/prompts/"
       "<prompt-id>/"
         "PROMPT.md"
     "src/personal_mcp/prompts/"
@@ -45,7 +45,7 @@ Rules:
 1. Each `PROMPT.md` owns both its runtime metadata and prose.
 2. Python owns only generic parsing, validation, rendering, and provider behavior.
 3. There is no central prompt catalog, generated signature, or metadata sidecar.
-4. The provider scans direct children of packaged `docs/prompts/` on each list or get request.
+4. The provider scans direct children of packaged `personal_mcp/docs/prompts/` on each list or get request.
 5. Additions, edits, and deletions become visible on the next request without restarting the server.
 6. Reload is pull-based; the provider does not watch files or emit proactive change notifications.
 

src/personal_mcp/docs/contracts/skill_contract.md

@@ -8,7 +8,7 @@ This page defines the canonical contract for skills in the docs-first MCP archit
 
 ## Canonical Skill Shape
 
-Each skill is one directory under `docs/skills/`:
+Each skill is one directory under `src/personal_mcp/docs/skills/`:
 
 ```mermaid
 ---
@@ -22,7 +22,7 @@ config:
 						lineColor: '#FFFFFF'
 ---
 treeView-beta
-	"docs/"
+	"src/personal_mcp/docs/"
 		"... (other docs)"
 		"skills/"
 			"<skill-id>/"
@@ -70,7 +70,7 @@ Invalid examples:
 
 ## Provider Publication
 
-[`SkillsDirectoryProvider`](https://gofastmcp.com/servers/providers/skills) scans `docs/skills/` with `supporting_files="template"` and publishes:
+[`SkillsDirectoryProvider`](https://gofastmcp.com/servers/providers/skills) scans packaged `personal_mcp/docs/skills/` with `supporting_files="template"` and publishes:
 
 1. `skill://<skill-id>/SKILL.md`
 2. `skill://<skill-id>/_manifest`

src/personal_mcp/docs/contracts/uris.md

@@ -46,7 +46,7 @@ FastMCP confines reads to the selected skill directory. Absolute paths, traversa
 
 ## General Docs URI
 
-General authored documentation is exposed through `resource://docs/{path*}`. The wildcard accepts normalized relative POSIX Markdown paths beneath `docs/`, excludes the provider-owned `skills/` subtree, and rejects absolute paths, traversal segments, backslashes, and non-Markdown targets.
+General authored documentation is exposed through `resource://docs/{path*}`. The wildcard accepts normalized relative POSIX Markdown paths beneath packaged `personal_mcp/docs/`, excludes the provider-owned `skills/` subtree, and rejects absolute paths, traversal segments, backslashes, and non-Markdown targets.
 
 Prompts are MCP prompt components rather than resources. Clients discover them with the protocol `prompts/list` operation and render them with `prompts/get`.
 

src/personal_mcp/docs/copilot.md

@@ -2,129 +2,56 @@
 icon: lucide/bot
 ---
 
-# Copilot MCP Mechanics
+# Using With GitHub Copilot
 
-## Purpose
+Once Personal MCP is configured as a VS Code MCP server, Copilot can use its resources, prompts, and read-only tools.
 
-This page explains how GitHub Copilot in VS Code consumes native skill resources and prompts from `personal-mcp`.
+For general connection details, see [Using Personal MCP](./usage.md). For VS Code setup options, see [Add and manage MCP servers](https://code.visualstudio.com/docs/agent-customization/mcp-servers).
 
-## Capability Lanes
+## Skills And Documentation
 
-Copilot interacts with MCP servers through independently exposed lanes:
+Use **MCP: Browse Resources** to inspect the server's resources. Skills appear as `skill://<name>/SKILL.md`; general pages appear under `resource://docs/...`.
 
-1. tools invoked during execution
-2. resources attached as read-only context
-3. server-provided prompts
+For a task that needs guidance:
 
-This server publishes skills as native `skill://` resources, general docs as `resource://docs/{path*}` resources, and workflows as native MCP prompt objects. It intentionally publishes no compatibility tools that mirror resources or prompts.
+1. choose the skill whose description best matches the task
+2. read its main `SKILL.md`
+3. read `_manifest` only when supporting material is needed
+4. attach or read only the relevant supporting files
 
-## VS Code Feature Coverage
+When the current chat surface supports MCP resource attachments, the same resources are available from **Add Context**.
 
-The server uses every FastMCP feature that applies to its read-only guidance workload:
+## Prompts
 
-| Feature | Usage |
-| --- | --- |
-| Server identity | The initialize response includes a stable name, usage instructions, and a self-contained icon for VS Code's MCP server UI. |
-| Tools | No tools are published for this documentation-only server surface. Resource and prompt operations stay on native MCP capabilities. |
-| Resources | Documentation and skills use native resources and wildcard resource templates with explicit Markdown MIME types. |
-| Prompts | Declarative workflows use native prompt objects with descriptions, display titles, typed arguments, and slash-command access. |
-| Argument completion | Prompt arguments with authored `choices` are returned through `completion/complete` as the user types. |
+Personal MCP prompts appear as `/<server>.<prompt>` chat commands. Select a command and fill in its arguments to start the workflow. Arguments with a fixed list of choices offer completion as you type.
 
-[FastMCP server identity](https://gofastmcp.com/servers/server), [component icons](https://gofastmcp.com/servers/icons), [tool metadata](https://gofastmcp.com/servers/tools), and [argument completion](https://gofastmcp.com/servers/completions) define the implementation details. [VS Code's MCP documentation](https://code.visualstudio.com/docs/agent-customization/mcp-servers) describes how tools, resources, prompts, and MCP Apps appear in the client.
+## Automatic Use
 
-The following capabilities are conditional rather than useful by default:
+Copilot can use four fallback tools when the chat surface does not expose resources or prompts directly:
 
-1. MCP Apps require an interactive tool result such as a form or visualization; this server returns guidance and structured resource data only.
-2. Sampling is appropriate only when server-side work must ask VS Code to run an LLM. The current server retrieves authored content and does not generate it.
-3. Elicitation is appropriate only when a running operation needs additional user input. Prompt arguments already collect all required input before execution.
-4. Progress, client logging, and background tasks require long-running operations. Current reads and prompt rendering are bounded local operations.
-5. Client roots matter only when server behavior depends on client filesystem roots. This server reads packaged content and never traverses a client workspace.
-6. `website_url` requires a canonical public deployment URL. None is configured, so the server does not advertise a guessed address.
+- `list_resources` and `read_resource`
+- `list_prompts` and `get_prompt`
 
-Add one of these capabilities when a concrete workflow needs it, then cover its negotiated capability and protocol response in the HTTP MCP smoke tests. See the [FastMCP Apps overview](https://gofastmcp.com/apps/overview), [sampling](https://gofastmcp.com/servers/sampling), [elicitation](https://gofastmcp.com/servers/elicitation), [progress reporting](https://gofastmcp.com/servers/progress), and [MCP context](https://gofastmcp.com/servers/context) for the activation criteria.
-
-## Native Skill Resources
-
-For every skill, Copilot can discover:
-
-1. `skill://<name>/SKILL.md`
-2. `skill://<name>/_manifest`
-3. `skill://<name>/{path*}` supporting-file template
-
-The main resource description comes from `SKILL.md`. The manifest discloses supporting paths, sizes, and SHA256 hashes. Native resources remain the only skill content and discovery contract; the tools search or delegate to that same resource surface rather than maintaining a parallel catalog.
-
-## Resource Picker Availability
-
-`MCP Resources...` in Add Context requires both:
-
-1. a connected server advertising resource capability
-2. a chat surface that exposes MCP resource attachment
-
-A successful `resources/list` response does not guarantee the picker appears in every session type. Use `MCP: Browse Resources` to distinguish server availability from chat UI availability.
-
-## Recommended Workflow
-
-For autonomous agents:
-
-1. browse native resources and compare skill descriptions
-2. read one relevant `skill://<name>/SKILL.md`
-3. read `_manifest` only if supporting detail may be needed
-4. read only selected supporting files
-
-For manual context attachment, browse the server's resources and attach the same bounded set of files.
-
-## Prompt Examples
-
-Resource attachment:
+These tools access the same content as the native features. A repository instruction can guide Copilot toward the intended order:
 
 ```text
-Use the attached personal-mcp skill as guidance, then reconcile it with the repository before proposing changes.
-```
-
-Direct loading:
-
-```text
-Read skill://async-fastapi-sqlmodel/SKILL.md and apply only the sections relevant to this repository.
-```
-
-Supporting material:
-
-```text
-Read skill://pytesting/_manifest, select the one reference relevant to async test lifecycle, and use that file with the main skill instructions.
-```
-
-## Repository Instruction Pattern
-
-A repo-level instruction should name the native retrieval order and context budget:
-
-```md
 When a task matches a personal-mcp skill:
-
-1. Prefer an already attached native skill resource.
-2. Otherwise browse MCP resources and select one `skill://<name>/SKILL.md` by description.
-3. Read the selected skill and read `_manifest` only when supporting material is needed.
-4. Load at most two candidate main files and only the relevant supporting paths.
-5. Reconcile guidance with the current repository before editing.
+1. Prefer an attached skill resource, or browse resources and choose one by description.
+2. Read its main file and load supporting material only when needed.
+3. Reconcile the guidance with the current repository before editing.
 ```
 
-Instructions steer behavior but do not force VS Code to attach resources automatically.
-
-## Prompt Objects
-
-Prompts remain separate from skills. When the client supports MCP prompt APIs, use prompt listing and `get_prompt` for parameterized workflows. Each authored `PROMPT.md` is the complete source of truth for its metadata, arguments, and prose; changes are loaded on the next prompt request.
+Instructions guide resource use but do not force VS Code to attach resources automatically.
 
 ## Troubleshooting
 
 1. Use `MCP: List Servers` to confirm the server is enabled.
-2. Use `MCP: Browse Resources` to confirm native skill resources exist.
-3. Confirm `Add Context > MCP Resources` lists server resources in the active chat surface.
-4. Restart the MCP server after changing skill files because production uses `reload=False`.
-5. Reload the VS Code window if the server is healthy but the resource or tool picker remains stale.
+2. Use `MCP: Browse Resources` to confirm resources are available.
+3. Restart the MCP server after changing its content.
+4. Reload the VS Code window if the server is healthy but the resource or tool list remains stale.
 
 ## Further Reading
 
-1. [FastMCP Skills Provider](https://gofastmcp.com/servers/providers/skills)
-2. [Add and manage MCP servers](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
-3. [MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration)
-4. [Manage context for AI](https://code.visualstudio.com/docs/chat/copilot-chat-context)
-5. [Skill Usage Mechanics](./usage.md)
+1. [VS Code MCP configuration](https://code.visualstudio.com/docs/agents/reference/mcp-configuration)
+2. [Managing context in VS Code](https://code.visualstudio.com/docs/chat/copilot-chat-context)
+3. [Using Personal MCP](./usage.md)

src/personal_mcp/docs/index.md

@@ -4,45 +4,46 @@ icon: lucide/rocket
 
 # Personal MCP
 
-This project is a document library of software patterns, best practices, and structured references to external documentation. The same markdown files are published through two equivalent surfaces, so human-readable docs and MCP resources stay aligned.
+Personal MCP is a library of software development guidance for people and AI assistants. Content is written once in Markdown and published as both a documentation website and an MCP server.
 
-## MCP Server
+## What It Provides
 
-An [MCP server](https://modelcontextprotocol.io/docs/getting-started/intro) at `/mcp` provides context for AI systems. The markdown files are exposed as [resources](https://modelcontextprotocol.io/docs/learn/server-concepts#resources) and are structured to be easily consumed by [MCP clients](https://modelcontextprotocol.io/docs/learn/client-concepts), such as VS Code.
+- **Skills** provide focused guidance for development tasks.
+- **Prompts** provide reusable workflows with named inputs.
+- **Documentation** makes the same material easy to browse and maintain.
 
-## Docs
+The HTTP service exposes the [MCP](https://modelcontextprotocol.io/docs/getting-started/intro) endpoint at `/mcp` and the website at `/docs/`.
 
-A website at `/docs` for humans to read and review.
+## Quick Start
 
-## Quick start
-
-Install dependencies first:
+Install dependencies, build the website, and start the server:
 
 ```bash
 uv sync
+uv run zensical build
+uv run personal-mcp --host 127.0.0.1 --port 8765
 ```
 
-Run the app locally with the static docs rebuilt first, using [Uvicorn factory mode](https://www.uvicorn.org/settings/#application):
+Then open `http://127.0.0.1:8765/docs/` or connect an MCP client to `http://127.0.0.1:8765/mcp`.
+
+The MCP server can also run over standard input and output:
 
 ```bash
-uv run zensical build && uv run uvicorn personal_mcp.web.app:create_app --factory --host 127.0.0.1 --port 8765
+uv run mcp-stdio
 ```
 
-Build and run the Docker image with the same exposed port:
+For Docker:
 
 ```bash
-docker build -t personal-mcp . && docker run --rm -p 8765:8765 personal-mcp
+docker compose up --build
 ```
 
-When the server is running, the health check is available at `/healthz` and the generated docs are available at `/docs/`.
+## Read Next
 
-## Architecture
-
-- [Resource-First Pattern Module Architecture](./architecture.md)
-- [Contracts](./contracts/index.md)
-- [Content Contract](./contracts/index.md#content-contract)
-- [Frontmatter Contract](./contracts/frontmatter.md)
-- [URI Contract](./contracts/uris.md)
-- [Static Docs Hosting Pattern](./mcp_layout.md)
-- [Skill Usage Mechanics](./usage.md)
-- [Copilot MCP Mechanics](./copilot.md)
+- [Using Personal MCP](./usage.md)
+- [Authoring Guide](./authoring.md)
+- [Architecture](./architecture.md)
+- [Running the Server](./mcp_layout.md)
+- [Testing](./testing.md)
+- [Security](./securing.md)
+- [Content Contracts](./contracts/index.md)

src/personal_mcp/docs/mcp_layout.md

@@ -2,94 +2,43 @@
 icon: lucide/server
 ---
 
-# Runtime And Static Docs Layout
+# Running The Server
 
-## Purpose
+Personal MCP can run as an HTTP service or as a local stdio process.
 
-The project serves native MCP content and a pre-built documentation site from one FastAPI process. Markdown is authored once under `docs/`; runtime providers and Zensical consume that same packaged tree for different purposes.
+## Local HTTP Server
 
-## Repository Layout
+Build the website before starting the application:
 
-```mermaid
----
-config:
-    treeView:
-        rowIndent: 32
-        lineThickness: 2
----
-treeView-beta
-   "project-root"
-      "docs"
-         "prompts/<prompt-id>/PROMPT.md"
-         "skills/<skill-id>/SKILL.md"
-         "skills/<skill-id>/<supporting-files>"
-         "<general-pages>.md"
-      "site"
-         "static build output"
-      "src/personal_mcp"
-         "mcp.py"
-         "prompts/content.py"
-         "prompts/models.py"
-         "prompts/provider.py"
-         "registry/"
-         "skills/provider.py"
-         "web/"
+```bash
+uv sync
+uv run zensical build
+uv run personal-mcp --host 127.0.0.1 --port 8765
 ```
 
-Ownership rules:
+The server then provides:
 
-1. `docs/skills/` is owned exclusively by `SkillsDirectoryProvider` at runtime.
-2. Each file under `docs/prompts/` owns its prompt metadata, argument schema, and prose.
-3. The docs registry owns only general Markdown resources and explicitly excludes skills.
-4. `site/` is generated output.
-5. The deleted custom `catalog/` package is not part of the runtime.
+- `http://127.0.0.1:8765/docs/` for the website
+- `http://127.0.0.1:8765/mcp` for MCP clients
 
-## Runtime Composition
+The host, port, log level, debug mode, and reload behavior can be set with command-line options or `PERSONAL_MCP_` environment variables.
 
-```mermaid
-flowchart TD
-   A[Packaged Skills] --> B[SkillsDirectoryProvider]
-   C[Packaged Prompt Markdown] --> D[Markdown Prompt Provider]
-   E[Packaged Markdown] --> F[Docs Registry]
-   B --> G[FastMCP]
-   D --> G
-   F --> G
-   G --> H[MCP Transport]
-   H --> K[FastAPI Application]
-   L[Pre-built site] --> M[Static /docs Mount]
-   K --> M
+## Local Stdio Server
+
+For clients that manage the server process themselves:
+
+```bash
+uv run mcp-stdio
 ```
 
-Runtime guarantees:
+This mode provides MCP only; it does not host the website.
 
-1. Providers are installed before serving requests.
-2. Prompt discovery rescans authored files on each list and get request.
-3. Duplicate components fail according to FastMCP's configured duplicate policy.
-4. Skills and prompts use native FastMCP component surfaces.
-5. General docs path parsing rejects traversal, backslashes, non-Markdown paths, and the skill namespace.
+## Docker
 
-## Build And Publish Flow
+The included Compose configuration builds the website into the image and publishes the service on port `8765`:
 
-1. Author prompt definitions and prose under `docs/prompts/`.
-2. Run `uv run zensical build` to produce `site/`.
-3. Build the wheel, which packages the authored docs under `personal_mcp/docs/`.
-4. Start the app and serve MCP plus the static site.
+```bash
+docker compose up --build
+```
 
-No runtime Markdown-to-HTML conversion occurs.
-
-## Machine-Facing Mapping
-
-1. `docs/skills/<skill-id>/SKILL.md` maps to `skill://<skill-id>/SKILL.md`.
-2. Skill supporting files map to `skill://<skill-id>/<path>`.
-3. Declarative prompt documents map to native MCP prompt names.
-4. General `docs/<path>.md` maps to `resource://docs/{path*}`.
-
-The server publishes no tool projections of resources or prompts.
-
-## Public Surface Policy
-
-Canonical provider and protocol surfaces are the only public interfaces.
-
-## Static Mount Expectations
-
-The FastAPI app mounts the Zensical output, serves index and asset files, and returns a clear unavailable response when the static output is absent. The site directory is immutable for a given build and remains separate from packaged authored Markdown.
+For a remote deployment, place the service behind a reverse proxy and review the [security guidance](./securing.md).

src/personal_mcp/docs/securing.md

@@ -2,138 +2,41 @@
 icon: lucide/shield-check
 ---
 
-# Securing Remote Access
+# Security
 
-## Context
+## Public By Design
 
-This project exposes two related surfaces from the same runtime:
+The application does not implement authentication. Its current purpose is to publish read-only guidance, so everything exposed through the server must be safe to make public.
 
-1. a static documentation site under `/docs`
-2. a Streamable HTTP MCP endpoint under `/mcp`
+This includes:
 
-The same Markdown content backs both surfaces. For the current project shape, the MCP server is resource-first and primarily exposes public skill and documentation text. It is not intended to expose secrets, private data, shell access, filesystem access, or tools with side effects.
+- the website under `/docs/`
+- resources and prompts under `/mcp`
+- the four read-only fallback tools
 
-The expected deployment path is:
+Do not add secrets, private notes, credentials, or sensitive environment details to the authored content.
+
+## Remote Deployment
+
+Place the service behind a reverse proxy or tunnel rather than exposing the container directly. The edge can provide TLS, rate limiting, access logs, and optional authentication without adding those concerns to this small application.
+
+A simple deployment is:
 
 ```text
-Public internet
-	-> Cloudflare Tunnel
-	-> Caddy
-	-> personal-mcp container
+Internet -> reverse proxy or tunnel -> personal-mcp
 ```
 
-## Decision
+The website and MCP endpoint can remain public while they contain only public, read-only content. Use edge authentication if access should be limited.
 
-For the current use case, heavy application-level authentication is not required.
+## When Authentication Becomes Required
 
-The recommended posture is:
-
-1. Keep the service behind Cloudflare Tunnel and Caddy.
-2. Do not expose the container port directly to the public internet.
-3. Treat everything exposed through MCP as publishable public documentation.
-4. Add stronger authentication only if the MCP surface later includes sensitive content or tools with meaningful side effects.
-
-This keeps the deployment simple while preserving a clear upgrade path.
-
-## Tradeoffs
-
-### Leaving `/mcp` Public
-
-This is acceptable if `/mcp` exposes only the same public Markdown already available through `/docs`.
-
-Benefits:
-
-1. lowest operational friction
-2. fewer compatibility issues with MCP clients
-3. no need to implement OAuth, mTLS, JWT validation, or custom auth middleware
-4. consistent with the project assumption that documentation content is public
-
-Risks:
-
-1. random scraping, probing, or fuzzing of a machine endpoint
-2. possible bandwidth or CPU nuisance traffic
-3. accidental future exposure if new tools or private resources are added
-4. less control over who can use the MCP endpoint
-
-### Protecting `/mcp` With Cloudflare Access
-
-Cloudflare Access can add a lightweight gate using GitHub, Google, one-time PIN, or service tokens.
-
-Benefits:
-
-1. reduces random internet traffic
-2. requires little app code
-3. works well for a small trusted team
-4. provides logs and centralized access control
-
-Costs:
-
-1. browser-based login may not work with all MCP clients
-2. non-browser MCP clients may need Cloudflare Access service tokens
-3. adds operational configuration for a low-sensitivity endpoint
-
-### Using mTLS
-
-mTLS is useful when both client and server environments are tightly controlled.
-
-Benefits:
-
-1. strong client identity
-2. good fit for service-to-service or private infrastructure
-3. can be used between Cloudflare, Caddy, and the backend if desired
-
-Costs:
-
-1. harder certificate provisioning and rotation
-2. weaker compatibility with normal MCP clients
-3. unnecessary for public documentation-only content
-
-For this project, mTLS is not the primary recommendation.
-
-## Practical Recommendation
-
-Use a simple public-docs posture unless the endpoint changes.
-
-Recommended current setup:
-
-```text
-/docs  public
-/mcp   public or lightly protected
-```
-
-If `/mcp` remains public, add only basic operational safeguards:
-
-1. keep Cloudflare Tunnel and Caddy in front
-2. avoid publishing `8765` directly
-3. enable Cloudflare or Caddy rate limiting if traffic becomes noisy
-4. monitor logs for unusual request volume
-5. document that MCP resources must remain safe to publish
-
-A slightly stricter setup is also reasonable:
-
-```text
-/docs  public
-/mcp   Cloudflare Access or service token
-```
-
-This is the best option if the team wants to reduce drive-by MCP traffic without adding auth code to the application.
-
-## Upgrade Trigger
-
-Add real authentication before introducing any MCP capability that can:
+Protect `/mcp` before adding any capability that can:
 
 1. read non-public files
-2. access private notes or credentials
-3. call upstream APIs
+2. access private data or credentials
+3. call authenticated services
 4. mutate data
 5. run commands
-6. expose environment details
-7. perform expensive computation
+6. perform expensive work
 
-At that point, prefer edge-level authentication first, such as Cloudflare Access, and consider proper OAuth 2.1 resource-server behavior only if broad public MCP client interoperability becomes a goal.
-
-## Security Invariant
-
-Everything exposed by the MCP server must be safe to publish publicly.
-
-If that invariant stops being true, `/mcp` should be protected before the new capability is deployed.
+At that point, choose authentication based on the clients that need to connect. Edge authentication is the simplest option for a small trusted audience; standards-based MCP authorization is more appropriate when broad client interoperability is required.

src/personal_mcp/docs/skills/cli-client/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: cli-client
+description: 'Design, implement, review, or refine Python command-line clients for remote APIs. Use for command structure, automation-friendly input and output, configuration, authentication, HTTP transport, pagination, retries, errors and exit codes, state-changing operations, packaging, or CLI testing.'
+---
+
+# Python API CLI Clients
+
+Use this skill as a conceptual reference for command-line applications that operate remote services. Preserve established project conventions, but make the command surface predictable for people, scripts, CI jobs, and shell composition.
+
+## Design Priorities
+
+A good API CLI should be:
+
+- **Task-oriented:** commands reflect user goals rather than HTTP endpoints or internal service classes.
+- **Predictable:** names, flags, defaults, output, errors, and exit statuses behave consistently.
+- **Composable:** successful data goes to stdout, diagnostics go to stderr, and machine-readable output is stable.
+- **Safe:** destructive operations are explicit, retries respect operation semantics, and secrets never enter output or logs.
+- **Layered:** command parsing, application behavior, API resources, transport, authentication, and persistence have distinct owners.
+- **Inspectable:** users can discover commands and effective configuration without reading source code.
+
+Use the [Command Line Interface Guidelines](https://clig.dev/) as the general human-interface baseline. Prefer the target project's established command framework and HTTP library over introducing replacements without a concrete need.
+
+## Command Model
+
+Design the command tree around a small, consistent grammar:
+
+```text
+mycli <resource> <action> [arguments] [options]
+mycli projects list --owner alice
+mycli projects get PROJECT_ID
+mycli projects create --name NAME
+mycli projects delete PROJECT_ID
+```
+
+- Use nouns for resource groups and familiar verbs for actions.
+- Keep equivalent operations parallel across resources: `list`, `get`, `create`, `update`, and `delete` should not change meaning by command group.
+- Prefer explicit positional arguments for primary identities and named options for modifiers.
+- Reserve global options for behavior that applies consistently across commands, such as profile, endpoint, output format, verbosity, and non-interactive mode.
+- Give every command useful `--help` output with a one-line purpose, argument meaning, defaults, and behavior-changing caveats.
+- Avoid mirroring every server endpoint. Combine low-level calls when one user task requires them, and omit endpoints that do not form a coherent CLI operation.
+
+Do not make users memorize hidden context. When a command depends on an active account, project, region, or profile, make that context discoverable and overridable.
+
+## Responsibility Boundaries
+
+Keep the command layer thin and dependencies directional:
+
+```text
+entry point and bootstrap
+└── command groups
+    └── application services
+        └── API client and resources
+            └── authenticated HTTP transport
+                └── HTTP library
+
+configuration ───────────────┘
+credentials ──> authentication
+renderers <──── command results
+```
+
+| Layer | Owns | Avoid |
+| --- | --- | --- |
+| Entry point | Dependency construction, top-level exception mapping, process exit | Business logic and API calls |
+| Command | Parsing, prompts, presentation, command-specific orchestration | Raw HTTP details and credential refresh |
+| Application service | Multi-request use cases and domain decisions | Terminal formatting |
+| API resource | Endpoint paths, request parameters, and response models | CLI prompts and global process state |
+| Transport | Base URL, headers, serialization, timeouts, retries, and response decoding | Resource-specific business rules |
+| Authentication | Credential acquisition, storage, and renewal | API resource behavior |
+| Renderer | Human and machine-readable output | Network calls and state mutation |
+
+Keep framework objects at the command boundary. Core operations should accept ordinary typed values and return structured results so they can be tested without invoking a subprocess.
+
+## Input And Interaction
+
+- Accept flags for every value that automation may need to provide. Prompts are an interactive convenience, not the only input path.
+- Prompt only when stdin and stderr are attached to a terminal and the user has not selected non-interactive mode.
+- In non-interactive mode, fail quickly with a specific missing-input error instead of waiting for input.
+- Read large request bodies from a file or stdin; avoid forcing structured documents into shell-escaped arguments.
+- Distinguish an omitted option from an explicit empty value when the API supports partial updates.
+- Validate syntax locally, but let the service remain authoritative for remote identities, permissions, and business rules.
+- Support `--` before pass-through values or positional arguments that can begin with a hyphen.
+
+For destructive or difficult-to-reverse operations, state the target precisely and require confirmation in interactive sessions. Provide an explicit option such as `--yes` for automation; never silently infer consent merely because input is non-interactive.
+
+## Output Contract
+
+Treat output as a public interface.
+
+- Write requested results to stdout and diagnostics, progress, warnings, and errors to stderr.
+- Make the default human output concise and scannable. Do not print the same result as both prose and a table.
+- Provide one stable machine-readable format, usually `--output json` or `--json`, for commands whose results are useful in automation.
+- Serialize machine output from typed result models rather than scraping human-formatted strings.
+- Keep machine-readable stdout clean: no progress bars, update notices, color codes, or explanatory prefixes.
+- Disable color and animated progress when the output stream is not a terminal or when the user requests it.
+- Use a pager only for interactive human output, and provide a consistent way to disable it.
+- Document whether list commands emit one aggregate value or a stream of records; do not switch shapes based on result count.
+
+When adding fields, preserve existing machine-readable fields where practical. Treat renaming, removing, or changing the type of a field as a compatibility decision.
+
+## Configuration Model
+
+Use one documented precedence order:
+
+```text
+command-line option > environment variable > selected profile/config file > built-in default
+```
+
+- Resolve configuration once near startup and pass a validated settings object inward.
+- Keep endpoint, profile, timeout, output mode, and similar behavior visible through a config or diagnostics command.
+- Show provenance when troubleshooting precedence, but redact secret values.
+- Store configuration in platform-appropriate user directories rather than the current working directory unless project-local configuration is intentional.
+- Keep credentials behind a separate storage abstraction. A convenient config file is not automatically an acceptable secret store.
+- Validate incompatible options together and report the conflict in the user's vocabulary.
+
+## HTTP And API Behavior
+
+Centralize remote-call behavior in the transport or API client:
+
+- Set explicit connect, read, write, and pool timeouts appropriate to the service.
+- Send a useful user agent containing the CLI name and version.
+- Map service errors into a small application error taxonomy before they reach commands.
+- Retry only transient failures, honor `Retry-After`, cap attempts and elapsed time, and add jitter where concurrent clients may synchronize.
+- Automatically retry state-changing requests only when they are demonstrably replay-safe, such as through an idempotency key accepted by the service.
+- Preserve server request or correlation IDs in verbose diagnostics without exposing sensitive response data.
+- Keep pagination in the API layer. Let commands choose whether to fetch one page, stream pages, or collect all results based on output and memory requirements.
+- Make cancellation responsive between requests and during long-running operations.
+
+Do not leak raw HTTP-library exceptions as the normal user interface. Preserve the original exception as the cause for debugging while presenting a stable CLI-level error.
+
+## Authentication
+
+Choose authentication from the service contract and execution context. Keep credential acquisition and renewal out of command handlers and API resources.
+
+For OAuth-protected APIs, load [OAuth 2.0 for installed CLI clients](./references/oauth.md). It covers public clients, Authorization Code with PKCE, loopback callbacks, device authorization, Authlib and HTTPX2 boundaries, protected token storage, synchronized refresh, scopes, discovery, and bounded authentication retries.
+
+For API keys or static tokens:
+
+- Accept them through an explicit credential provider such as an OS credential store, environment variable, or CI secret integration.
+- Define precedence when more than one provider is configured.
+- Never place credentials in command arguments by default because process listings and shell history may expose them.
+- Redact credentials and credential-like headers from errors, debug logs, traces, and support bundles.
+
+For unattended workloads, use a service identity and grant intended for machines. Do not reuse a person's interactive credentials as automation identity.
+
+## Errors And Exit Status
+
+Keep a small documented taxonomy and map it once at the entry point:
+
+| Category | User-facing behavior | Exit-status requirement |
+| --- | --- | --- |
+| Usage or validation | Explain the invalid input and show the nearest help hint | Stable nonzero status distinct from remote failure |
+| Authentication | Explain whether login or credential repair is required | Stable nonzero status |
+| Authorization | Identify the denied operation without claiming credentials are expired | Stable nonzero status |
+| Not found or conflict | Name the target and preserve actionable server context | Stable nonzero status if scripts branch on it |
+| Rate limit or transient service failure | Explain retryability and any known retry time | Stable nonzero status |
+| Unexpected failure | Concise message plus opt-in diagnostic detail | Generic nonzero status |
+
+- Return zero only when the requested operation completed according to its contract.
+- Do not require scripts to parse prose to distinguish common failure categories.
+- Keep normal errors concise. Put tracebacks, request details, and internal context behind an explicit debug or verbose mode.
+- Handle interruption without a traceback by default and use the platform's conventional interrupted-process status.
+- Preserve partial-success information for batch operations and define whether partial success is a failing exit status.
+
+## State-Changing Operations
+
+- Display or return the identity of the affected resource.
+- Support a dry-run or plan mode when the service can accurately predict a consequential change.
+- Use idempotency keys for retried creates or actions when the API supports them.
+- Do not claim rollback if the remote API cannot provide it.
+- For batch changes, define ordering, concurrency limits, stop/continue behavior, and partial-failure reporting.
+- Keep local caches disposable unless their contents are explicitly part of the user contract.
+
+## Concurrency And Async Boundaries
+
+Use concurrency only where it improves a measured workflow such as independent page or resource retrieval. Bound concurrent requests to respect service and local limits.
+
+Choose one owner for the event loop. Command handlers may call an async application boundary, but lower layers should not invoke nested event-loop runners. Keep synchronous and asynchronous APIs separate or adapt them in one explicit place.
+
+## Suggested Package Shape
+
+Adapt this shape to the project's size and existing conventions:
+
+```text
+src/mycli/
+├── __main__.py
+├── cli.py
+├── config.py
+├── errors.py
+├── output.py
+├── api/
+│   ├── client.py
+│   ├── transport.py
+│   └── resources/
+└── auth/
+```
+
+Small clients can combine modules while preserving the conceptual boundaries. Split code when a boundary has distinct dependencies, state, tests, or change cadence, not merely to reproduce the example tree.
+
+## Design Sequence
+
+1. Inventory the user tasks, execution environments, API capabilities, and existing project conventions.
+2. Define the command grammar, required inputs, destructive-operation policy, output modes, and exit-status contract before wiring endpoints.
+3. Define typed configuration and its precedence, including credential providers and active context.
+4. Establish API resource, transport, authentication, and error boundaries.
+5. Implement one vertical command path through parsing, service behavior, transport, rendering, and error mapping.
+6. Verify the path both in-process and as an installed subprocess before repeating the pattern.
+7. Add concurrency, retries, caching, rich presentation, and convenience prompts only where requirements justify them.
+
+## Testing Strategy
+
+- Unit-test command-independent services, API resources, renderers, configuration resolution, and error mapping directly.
+- Test command invocation with isolated environment variables, config directories, stdin, stdout, and stderr.
+- Assert exit status, stdout, and stderr independently.
+- Cover human and machine-readable output, including empty and multi-page results.
+- Use a mock transport for timeouts, malformed responses, pagination, rate limits, transient retries, and permanent failures.
+- Verify interactive confirmation and non-interactive refusal for destructive operations.
+- Test redaction with realistic secret shapes in headers, URLs, response bodies, and nested exceptions.
+- Add live-service tests only for behavior a local fake cannot represent, using isolated accounts and CI-managed credentials.
+- Build and install the distribution in a clean environment to verify the console entry point and runtime dependencies.
+
+## Reference Map
+
+| Topic | Load when | Reference |
+| --- | --- | --- |
+| Python library selection | Choosing or comparing a parser framework, terminal output, TUI, configuration, HTTP, authentication, testing, or packaging stack | [Python CLI library selection](./references/library-selection.md) |
+| OAuth for installed applications | The API uses OAuth, OIDC discovery, refresh tokens, loopback callbacks, or device authorization | [OAuth 2.0 for installed CLI clients](./references/oauth.md) |
+
+## Completion Checks
+
+1. Commands model recognizable user tasks with consistent names and options.
+2. Interactive conveniences have explicit non-interactive equivalents.
+3. Stdout, stderr, machine output, and exit statuses form a stable automation contract.
+4. Configuration has one visible precedence order and credentials use an appropriate protected source.
+5. Commands do not own raw HTTP, authentication lifecycle, or terminal-independent business logic.
+6. Timeouts, retries, pagination, cancellation, and state-changing request safety are explicit.
+7. Errors are actionable, categorized, redacted, and mapped at one process boundary.
+8. Destructive and batch operations define confirmation, idempotency, and partial-failure behavior.
+9. Tests exercise installed command behavior as well as isolated application and transport logic.
+10. Help text and diagnostics let users discover the command surface and effective non-secret configuration.

src/personal_mcp/docs/skills/cli-client/references/library-selection.md

@@ -0,0 +1,175 @@
+# Python CLI Library Selection
+
+Use this reference when choosing libraries for a new Python CLI or deciding whether an existing stack still fits. Choose each layer independently: a command parser, terminal renderer, terminal UI, settings model, HTTP client, authentication implementation, test runner, and package manager solve different problems.
+
+## Default Stack
+
+For a new typed application CLI, start with:
+
+| Concern | Default | Why |
+| --- | --- | --- |
+| Command parsing | [Cyclopts](https://cyclopts.readthedocs.io/en/latest/) | Type-driven commands, rich type support, docstring-derived help, validation, command groups, configuration sources, and testing helpers |
+| Human terminal output | [Rich](https://rich.readthedocs.io/en/stable/) | Tables, progress, status, syntax, terminal detection, and separate output consoles |
+| Settings and data validation | [Pydantic](https://docs.pydantic.dev/latest/) and [Pydantic Settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) | Typed models and explicit environment, dotenv, secret, and custom settings sources |
+| HTTP | [HTTPX2](https://pydantic.dev/docs/httpx2/) | Actively maintained synchronous and asynchronous APIs, explicit clients, timeouts, streaming, and testable transports |
+| OAuth | [Authlib 1.8+](https://pypi.org/project/Authlib/) | OAuth implementation integrated with HTTPX2; use the [OAuth reference](./oauth.md) for architecture and security requirements |
+| Tests | [pytest](https://docs.pytest.org/en/stable/) | Fixtures, parametrization, output capture, monkeypatching, and a broad plugin ecosystem |
+| Project and environment | [uv](https://docs.astral.sh/uv/) | Project dependencies, lockfiles, environments, scripts, builds, and tool execution |
+
+Add [Textual](https://textual.textualize.io/) only when the product needs a persistent, event-driven terminal interface. It complements a command parser; it does not replace the scriptable command surface.
+
+This is a starting point, not a mandate. Preserve a sound existing stack unless a requirement exposes a concrete limitation.
+
+## Choose The Command Framework
+
+### Use Cyclopts by default for a new typed application CLI
+
+[Cyclopts](https://cyclopts.readthedocs.io/en/latest/) derives commands and parameters from Python function signatures and supports built-in and user-defined types, including unions, literals, dataclasses, Pydantic models, and attrs classes. It can derive help from docstrings and provides converters, validators, nested commands, lazy loading, configuration sources, documentation integration, and testing guidance.
+
+Choose Cyclopts when:
+
+- Modern type annotations should be the primary command schema.
+- Commands accept structured dataclasses or validation models.
+- Rich unions, literals, nested structures, or reusable parameter groups matter.
+- The project values concise declarations and generated documentation.
+- A newer and smaller ecosystem is an acceptable tradeoff.
+
+Before committing, prototype the hardest command signature, help page, validation error, completion behavior, and test invocation. Do not evaluate a framework only on a one-command example.
+
+### Use Typer for the mainstream type-driven choice
+
+[Typer](https://typer.tiangolo.com/) also derives CLI arguments and options from Python type hints and provides automatic help, shell completion, nested command groups, Rich-formatted output, packaging guidance, and test helpers. It is a strong choice when contributor familiarity, established examples, and ecosystem recognition matter more than Cyclopts' broader type model.
+
+Since Typer 0.26.0, [Typer vendors Click](https://typer.tiangolo.com/#click-code) rather than depending on the external Click package. Do not assume an arbitrary Click extension or subclass will integrate with modern Typer; verify that requirement against the installed Typer release.
+
+Choose Typer when:
+
+- The team already knows Typer or follows the FastAPI ecosystem.
+- The command types fit Typer's supported parameter model.
+- A familiar, established type-driven framework lowers contributor cost.
+- Existing Typer conventions or integrations outweigh framework-switching benefits.
+
+### Use Click when explicit control is the requirement
+
+[Click](https://click.palletsprojects.com/en/stable/) models commands, groups, contexts, parameters, types, and invocation explicitly. It supports arbitrary command nesting, lazy subcommand loading, custom parameter types, extension APIs, testing utilities, and a mature plugin ecosystem.
+
+Choose Click when:
+
+- The CLI is itself a framework or plugin host.
+- Commands must be discovered or loaded lazily.
+- Parsing, context propagation, invocation, or help behavior needs unusual customization.
+- Existing Click extensions are a hard dependency.
+- Explicit declarations are preferable to inference from application types.
+
+Do not choose Click merely because it is mature. For ordinary application commands, the extra parser-level detail may duplicate function types, defaults, validation, and documentation.
+
+### Use argparse when dependency constraints dominate
+
+[`argparse`](https://docs.python.org/3/library/argparse.html) is the standard-library parser and supports subcommands, generated help, custom actions and types, argument files, and parser-level error handling. Python 3.14 added colored help and `suggest_on_error`, making its default experience more capable than older comparisons imply.
+
+Choose argparse when:
+
+- The tool must remain standard-library-only.
+- It is a small utility with a stable and modest command surface.
+- Conservative deployment environments value availability over declaration ergonomics.
+- Adding a runtime dependency has a real operational cost.
+
+For a substantial typed application, account for the duplication between parser declarations and the application's function signatures, models, defaults, validation, and help text.
+
+### Use Fire for exposure, not deliberate public design
+
+[Python Fire](https://github.com/google/python-fire) generates a CLI from functions, classes, modules, mappings, and other Python objects. This is useful for developer tools, debugging, exploration, and rapidly exposing an internal Python API.
+
+Avoid Fire as the default for a stable public CLI. Exposing the Python object model couples command names, arguments, and behavior to implementation details instead of treating the CLI as a deliberately designed compatibility surface.
+
+## Framework Decision Table
+
+| Primary requirement | Choose | Main tradeoff |
+| --- | --- | --- |
+| New, typed application with rich parameter models | Cyclopts | Smaller ecosystem and less accumulated operational history |
+| Type-driven CLI with maximum contributor familiarity | Typer | Verify complex typing and Click-extension assumptions |
+| Plugin framework or unusual parser behavior | Click | More explicit declarations and parser-specific code |
+| Standard-library-only or tiny utility | argparse | Imperative setup and duplicated schema information |
+| Rapid internal exposure of Python objects | Fire | Python implementation becomes the CLI contract |
+
+When Cyclopts and Typer both fit, build the same representative vertical slice in each. Include the most complex parameter model, nested command registration, configuration injection, help output, validation failure, shell completion, and command test. Select from that evidence rather than syntax preference.
+
+## Keep Complementary Libraries In Their Layer
+
+### Rich is presentation, not parsing
+
+Use [Rich](https://rich.readthedocs.io/en/stable/) behind a renderer abstraction for human-readable tables, progress, status displays, syntax, and styled errors. Keep structured output on a separate serialization path so `--output json` never contains decoration, progress, or terminal control codes.
+
+Typer includes Rich as a dependency and uses it for formatted errors. Cyclopts can also produce Rich-oriented help and errors. This does not remove the need for an application-owned output boundary.
+
+### Textual is an optional interactive mode
+
+Use [Textual](https://textual.textualize.io/) when users need a persistent screen, navigation, reactive widgets, keyboard actions, or live dashboards. Keep ordinary parser commands for automation and direct operations:
+
+```text
+mycli projects list       -> scriptable command
+mycli interactive         -> Textual application
+             both -> application services -> API client
+```
+
+The command and TUI adapters should call the same application services. Do not embed API and domain behavior separately in Textual event handlers.
+
+## Supporting Stack Decisions
+
+### Configuration and models
+
+Use dataclasses when configuration is small, already parsed, and needs no source orchestration. Use [Pydantic](https://docs.pydantic.dev/latest/) for structured request, response, configuration, or command models that benefit from validation and serialization. Use [Pydantic Settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) when environment variables, dotenv files, secret files, or custom settings sources participate in explicit precedence.
+
+Do not pass framework parameter objects into application services. Convert parser output into ordinary typed values or application models at the command boundary.
+
+### HTTP
+
+Use [HTTPX2](https://pydantic.dev/docs/httpx2/) for new API clients. It is the actively developed continuation of HTTPX and supports synchronous and asynchronous clients, explicit timeouts, streaming, custom authentication, and mock transports. [Authlib 1.8+](https://pypi.org/project/Authlib/) integrates with HTTPX2 directly. Reuse a client with explicit timeouts rather than calling top-level request functions throughout resource methods.
+
+Preserve [HTTPX](https://www.python-httpx.org/) in a sound existing client until its dependencies, type checks, and transport tests are ready to migrate. Do not use HTTPX2's process-wide import alias from reusable library code, and do not keep HTTPX and HTTPX2 as permanent parallel transports without a concrete compatibility requirement.
+
+Use [aiohttp](https://docs.aiohttp.org/en/stable/) when the project already standardizes on its async client, depends on its streaming or WebSocket behavior, or has measured requirements that justify a different transport. Do not introduce both HTTPX2 and aiohttp without a clear ownership boundary.
+
+### Authentication
+
+Use [Authlib 1.8+](https://pypi.org/project/Authlib/) for OAuth protocol behavior rather than implementing grants, PKCE, token parsing, and refresh directly. Keep it behind an authentication abstraction. For OAuth-enabled installed applications, follow [OAuth 2.0 for installed CLI clients](./oauth.md).
+
+Use [keyring](https://keyring.readthedocs.io/en/latest/) to access operating-system credential stores when the deployment environment provides one. Treat headless secret storage as an explicit deployment decision rather than silently falling back to plaintext configuration.
+
+### Testing and packaging
+
+Use [pytest](https://docs.pytest.org/en/stable/) for application and command tests. Combine framework-level invocation helpers with subprocess tests of the installed console entry point; a runner helper alone does not verify packaging or startup behavior.
+
+Use [uv](https://docs.astral.sh/uv/) for dependency management, lockfiles, isolated tool execution, and project commands when the repository adopts uv. Declare the CLI through a `[project.scripts]` entry point in [`pyproject.toml`](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#creating-and-packaging-command-line-tools) so installation, tests, and users invoke the same bootstrap path.
+
+## Architecture Rule
+
+Do not couple application behavior to the chosen CLI framework:
+
+```text
+Cyclopts / Typer / Click / argparse
+                 |
+                 v
+        thin command adapters
+                 |
+                 v
+       application services
+                 |
+                 v
+            API client
+```
+
+Command functions should parse or receive values, call an application service, and hand the result to a renderer. Keep API calls, authentication, retries, and domain decisions outside parser decorators and callbacks. This makes framework-specific tests small and keeps a future parser migration bounded.
+
+## Selection Checklist
+
+1. Identify the minimum supported Python version and dependency constraints.
+2. Model the hardest real command, not the smallest demonstration command.
+3. Decide whether type annotations or explicit parser objects should own the command schema.
+4. Check complex types, nested commands, lazy loading, plugins, completion, help, validation, and test support against actual requirements.
+5. Separate parsing from Rich presentation and optional Textual interaction.
+6. Select configuration, HTTP, authentication, testing, and packaging libraries independently.
+7. Prototype ambiguous framework choices with the same vertical slice.
+8. Pin compatible versions and verify behavior against installed-library documentation before implementation.
+9. Keep application services free of CLI-framework types.
+10. Preserve stable stdout, stderr, and exit-status contracts regardless of library defaults.

src/personal_mcp/docs/skills/cli-client/references/oauth.md

@@ -0,0 +1,513 @@
+# OAuth 2.0 For Installed CLI Clients
+
+Use this reference when a Python CLI calls an OAuth-protected API. Keep authentication, token lifecycle, HTTP transport, and API resources as separate ownership boundaries.
+
+## Recommended Default
+
+For an interactive installed CLI, use:
+
+> Public client + Authorization Code + PKCE using `S256` + loopback callback + Authlib 1.8+ + HTTPX2 + protected credential store + centralized token refresh + minimum scopes.
+
+Follow the current [OAuth 2.0 Security Best Current Practice](https://www.rfc-editor.org/rfc/rfc9700) and the [OAuth 2.0 guidance for native applications](https://www.rfc-editor.org/rfc/rfc8252). Do not use the implicit grant, Resource Owner Password Credentials grant, or an embedded client secret.
+
+## Responsibility Boundaries
+
+Keep dependencies pointed inward toward authentication and transport primitives:
+
+```text
+CLI commands
+├── login/logout/status -> OAuthManager -> authorization server
+└── API commands -> ApiClient/resources -> OAuthTransport
+                                           └── TokenManager
+                                               ├── TokenStore
+                                               └── OAuth client / HTTP transport
+```
+
+| Component | Owns | Must not own |
+| --- | --- | --- |
+| `OAuthManager` | Interactive login, callback validation, token exchange, logout | API resource methods |
+| `TokenStore` | Loading, atomically saving, and deleting sensitive token state | Refresh policy or HTTP requests |
+| `TokenManager` | Expiry checks, refresh synchronization, and valid access-token retrieval | CLI presentation or resource URLs |
+| `OAuthTransport` | Bearer-token injection and one bounded authentication retry | Interactive login UX |
+| `ApiClient` and resources | API operations, request models, and response models | OAuth grants, refresh tokens, or credential storage |
+
+Keep [Authlib's HTTPX2 OAuth client](https://github.com/authlib/authlib/blob/v1.8.0/authlib/integrations/httpx_client/oauth2_client.py) behind the authentication boundary. API resources should request an authenticated transport or call `TokenManager.get_valid_access_token()`; they should not depend directly on Authlib.
+
+## Library Selection
+
+Use one library per responsibility and keep each one behind an application-owned interface:
+
+| Concern | Default for new code | Use something else when |
+| --- | --- | --- |
+| OAuth protocol | [Authlib 1.8+](https://pypi.org/project/Authlib/) | A provider supplies an official, maintained SDK that correctly implements its non-standard behavior |
+| API and OAuth HTTP | [HTTPX2 2.x](https://pydantic.dev/docs/httpx2/) | Preserve HTTPX in an existing stable client until its dependencies and test doubles are ready to migrate |
+| Desktop credential storage | [keyring](https://keyring.readthedocs.io/en/latest/) | The target platforms are explicitly supported by a reviewed native alternative, or the deployment already owns a managed vault |
+| Async coordination | [`asyncio`](https://docs.python.org/3/library/asyncio-sync.html) for an asyncio-only CLI | The application already standardizes on [AnyIO](https://anyio.readthedocs.io/en/stable/) or supports multiple async backends |
+| Tests | [pytest](https://docs.pytest.org/en/stable/) and [`httpx2.MockTransport`](https://pydantic.dev/docs/httpx2/advanced/transports/#mock-transports) | The repository has an established equivalent |
+
+[HTTPX2](https://pypi.org/project/httpx2/) is the actively developed continuation of HTTPX under Pydantic stewardship. It keeps the familiar client, request, response, authentication, and mock-transport APIs while using the `httpx2` import. Authlib 1.8 moved its HTTP client integration to HTTPX2, so new OAuth clients can use one HTTP implementation:
+
+```bash
+uv add "Authlib>=1.8" "httpx2>=2" keyring
+```
+
+Do not call [`httpx2.alias_httpx()`](https://pydantic.dev/docs/httpx2/api/api/#httpx2.alias_httpx) from reusable library code. It changes imports process-wide and exists as a temporary application-level migration aid. If an existing dependency still requires `httpx`, keep both clients behind local abstractions and remove HTTPX only after dependency and transport tests pass.
+
+## Configuration And Secret State
+
+Separate public OAuth configuration from sensitive OAuth state.
+
+Public configuration may contain:
+
+- Client ID for the registered public client.
+- Issuer, authorization endpoint, token endpoint, and optional revocation or device-authorization endpoint.
+- Exact registered redirect URI rules.
+- Required scopes and, when supported, resource or audience indicators.
+
+Sensitive state includes:
+
+- Access tokens.
+- Refresh tokens.
+- Token expiry and related token response fields when they reveal account or authorization state.
+
+Represent the complete token response and store it through a narrow abstraction. A `TypedDict` documents the common fields without discarding provider-specific fields from the runtime dictionary:
+
+```python
+from typing import Protocol, Required, TypedDict
+
+
+class OAuthToken(TypedDict, total=False):
+    access_token: Required[str]
+    refresh_token: str
+    token_type: str
+    expires_at: float
+    expires_in: int
+    scope: str
+
+
+class TokenStore(Protocol):
+    async def load(self) -> OAuthToken | None: ...
+    async def save(self, token: OAuthToken) -> None: ...
+    async def delete(self) -> None: ...
+```
+
+For a desktop CLI, [keyring](https://keyring.readthedocs.io/en/latest/) remains the conservative default because it selects macOS Keychain, Windows Credential Locker, Secret Service, or KWallet as available. Its API is synchronous, so move calls off the event-loop thread. Store one JSON document per account so access-token and refresh-token rotation is replaced as one logical update:
+
+```python
+import json
+from typing import cast
+
+import anyio
+import keyring
+from keyring.backend import KeyringBackend
+from keyring.errors import KeyringError
+
+
+class CredentialStoreError(RuntimeError):
+    pass
+
+
+class KeyringTokenStore:
+    def __init__(
+        self,
+        service: str,
+        account: str,
+        backend: KeyringBackend | None = None,
+    ) -> None:
+        self._service = service
+        self._account = account
+        self._backend = backend or keyring.get_keyring()
+        if self._backend.priority <= 0:
+            raise CredentialStoreError("No protected credential store is available")
+
+    async def load(self) -> OAuthToken | None:
+        try:
+            raw = await anyio.to_thread.run_sync(
+                self._backend.get_password, self._service, self._account
+            )
+        except KeyringError as error:
+            raise CredentialStoreError("Could not read OAuth credentials") from error
+        if raw is None:
+            return None
+        try:
+            value = json.loads(raw)
+        except json.JSONDecodeError as error:
+            raise CredentialStoreError("Stored OAuth credentials are invalid") from error
+        if not isinstance(value, dict) or not isinstance(value.get("access_token"), str):
+            raise CredentialStoreError("Stored OAuth credentials are invalid")
+        return cast("OAuthToken", value)
+
+    async def save(self, token: OAuthToken) -> None:
+        encoded = json.dumps(token, separators=(",", ":"))
+        try:
+            await anyio.to_thread.run_sync(
+                self._backend.set_password,
+                self._service,
+                self._account,
+                encoded,
+            )
+        except KeyringError as error:
+            raise CredentialStoreError("Could not save OAuth credentials") from error
+
+    async def delete(self) -> None:
+        if await self.load() is None:
+            return
+        try:
+            await anyio.to_thread.run_sync(
+                self._backend.delete_password, self._service, self._account
+            )
+        except KeyringError as error:
+            raise CredentialStoreError("Could not delete OAuth credentials") from error
+```
+
+Fail closed when no recommended backend is available. Do not install [`keyrings.alt`](https://pypi.org/project/keyrings.alt/) as an automatic fallback; it intentionally includes possibly insecure backends.
+
+### Storage Alternatives
+
+- Consider [`rust-native-keyring`](https://pypi.org/project/rust-native-keyring/) when native compiled wheels, the Rust [keyring ecosystem](https://github.com/open-source-cooperative/keyring-rs), and its richer credential-store selection fit the supported platforms. Its Python package is still `0.x`, so pin it, verify wheel availability, and test lock/unlock and deletion behavior on every target OS before preferring it over `keyring`.
+- Consider the official [1Password Python SDK](https://www.1password.dev/sdks/) when users already rely on 1Password and desktop authorization prompts, auditing, or shared vault policy are product requirements. It is asynchronous and supports desktop-app authorization, but its SDK is also still version `0`; it is not a transparent local-keyring replacement.
+- Use a managed service such as [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/retrieving-secrets-python-sdk.html), [Azure Key Vault](https://learn.microsoft.com/en-us/azure/key-vault/secrets/quick-create-python), [Google Secret Manager](https://docs.cloud.google.com/secret-manager/docs/reference/libraries), or [HashiCorp Vault](https://developer.hashicorp.com/vault/docs/get-started/developer-qs) for unattended or centrally governed deployments. Authenticate with workload identity or another deployment-owned mechanism; do not solve storage by introducing a second long-lived bootstrap secret.
+
+For a headless environment without a credential service, require an explicit storage backend appropriate to its threat model; do not silently fall back to plaintext config. Never emit tokens through logs, telemetry, exceptions, shell output, or status commands.
+
+## Interactive Authorization
+
+Use Authorization Code with PKCE for browser-based login:
+
+1. Generate a cryptographically random `state` and a fresh PKCE `code_verifier` for every attempt.
+2. Derive the `S256` code challenge and construct the authorization URL with the exact requested redirect URI and minimum scopes.
+3. Bind a temporary listener to `127.0.0.1` on an ephemeral port. Do not expose it on all interfaces.
+4. Open the system browser and wait for one callback with a short timeout and cancellation path.
+5. Reject OAuth errors, a missing code, or any callback whose `state` does not exactly match.
+6. Exchange the code using the original verifier and redirect URI.
+7. Persist the complete returned token state atomically, then stop the listener immediately.
+8. Return a minimal success page and CLI message without displaying credentials.
+
+Treat the CLI as a public client. A secret distributed inside source, a package, a binary, or an environment-independent configuration file cannot authenticate installed copies of the CLI.
+
+The following manager shows the Authlib-owned part of a loopback flow. A separate callback receiver should bind `127.0.0.1`, accept one request, enforce a timeout and maximum request size, then pass the complete callback URL to `finish()`:
+
+```python
+import secrets
+from dataclasses import dataclass
+from urllib.parse import parse_qs, urlsplit
+
+from authlib.integrations.httpx_client import AsyncOAuth2Client
+
+
+@dataclass(frozen=True, slots=True)
+class OAuthConfig:
+    client_id: str
+    authorization_endpoint: str
+    token_endpoint: str
+    redirect_uri: str
+    scopes: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class PendingAuthorization:
+    url: str
+    state: str
+    code_verifier: str
+
+
+class OAuthManager:
+    def __init__(self, config: OAuthConfig, store: TokenStore) -> None:
+        self._config = config
+        self._store = store
+        self._client = AsyncOAuth2Client(
+            client_id=config.client_id,
+            redirect_uri=config.redirect_uri,
+            scope=" ".join(config.scopes),
+            code_challenge_method="S256",
+            token_endpoint_auth_method="none",
+        )
+
+    def begin(self) -> PendingAuthorization:
+        verifier = secrets.token_urlsafe(64)
+        url, state = self._client.create_authorization_url(
+            self._config.authorization_endpoint,
+            code_verifier=verifier,
+        )
+        return PendingAuthorization(url=url, state=state, code_verifier=verifier)
+
+    async def finish(
+        self, callback_url: str, pending: PendingAuthorization
+    ) -> OAuthToken:
+        callback = urlsplit(callback_url)
+        expected = urlsplit(self._config.redirect_uri)
+        callback_target = (callback.scheme, callback.hostname, callback.port, callback.path)
+        expected_target = (expected.scheme, expected.hostname, expected.port, expected.path)
+        if callback_target != expected_target:
+            raise AuthenticationError("OAuth callback used an unexpected redirect URI")
+
+        query = parse_qs(callback.query)
+        if query.get("state") != [pending.state]:
+            raise AuthenticationError("OAuth callback state did not match")
+        if "error" in query:
+            raise AuthenticationError("Authorization server rejected login")
+        code = query.get("code", [None])[0]
+        if code is None:
+            raise AuthenticationError("OAuth callback did not contain a code")
+
+        result = await self._client.fetch_token(
+            self._config.token_endpoint,
+            code=code,
+            code_verifier=pending.code_verifier,
+        )
+        token = cast("OAuthToken", dict(result))
+        await self._store.save(token)
+        return token
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+```
+
+Do not persist `PendingAuthorization`: `state` and `code_verifier` are short-lived, single-attempt values. Define `AuthenticationError` in the application's stable error taxonomy and keep callback query values out of its message.
+
+If a browser or loopback listener is impractical and the provider exposes it, use the standardized [Device Authorization Grant](https://www.rfc-editor.org/rfc/rfc8628). Respect the server-provided polling interval, `slow_down`, expiration, and cancellation behavior. Do not invent a device flow against a provider that does not advertise or document one.
+
+## Authorization Server Metadata
+
+Prefer [OAuth 2.0 Authorization Server Metadata](https://www.rfc-editor.org/rfc/rfc8414) or OpenID Connect discovery when the provider supports it. Validate that discovered metadata belongs to the configured issuer and require HTTPS for non-loopback endpoints.
+
+Use explicit endpoints when discovery is unavailable or when a controlled deployment intentionally pins them. Do not mix endpoints discovered from one issuer with configuration from another.
+
+## Token Lifecycle
+
+Centralize expiry and refresh decisions in `TokenManager`:
+
+```text
+load token
+├── missing -> authentication required
+├── valid beyond refresh leeway -> return access token
+└── expired or near expiry
+    └── acquire refresh lock
+        ├── reload token
+        ├── return it if another task refreshed it
+        └── refresh, atomically persist the full response, and return it
+```
+
+Use a small expiry leeway, commonly 60 seconds, to avoid starting a request with a token that expires in transit. For a single-process async CLI, an `asyncio.Lock` is sufficient for in-process refresh coordination. If multiple processes can share one token store, add storage-level coordination or optimistic versioning; an in-process lock cannot prevent cross-process races.
+
+Preserve a refresh token when the server omits it from a refresh response, but replace it whenever rotation returns a new one. Save the newly returned token as one atomic state update so an older writer cannot restore a superseded refresh token.
+
+Classify missing, expired-without-refresh, rejected-refresh, and revoked credentials as authentication failures with a clear path to log in again. Do not turn refresh failures into anonymous API calls.
+
+A small refresher adapter and token manager keep Authlib details out of storage and API resources:
+
+```python
+import asyncio
+import time
+from collections.abc import Callable
+
+
+class AuthenticationError(RuntimeError):
+    pass
+
+
+class AuthlibTokenRefresher:
+    def __init__(self, config: OAuthConfig) -> None:
+        self._config = config
+
+    async def refresh(self, token: OAuthToken) -> OAuthToken:
+        refresh_token = token.get("refresh_token")
+        if refresh_token is None:
+            raise AuthenticationError("Login is required")
+        async with AsyncOAuth2Client(
+            client_id=self._config.client_id,
+            token=dict(token),
+            token_endpoint_auth_method="none",
+        ) as client:
+            result = await client.refresh_token(
+                self._config.token_endpoint,
+                refresh_token=refresh_token,
+            )
+        refreshed = cast("OAuthToken", dict(result))
+        refreshed.setdefault("refresh_token", refresh_token)
+        return refreshed
+
+
+class TokenManager:
+    def __init__(
+        self,
+        store: TokenStore,
+        refresher: AuthlibTokenRefresher,
+        *,
+        refresh_leeway: float = 60.0,
+        clock: Callable[[], float] = time.time,
+    ) -> None:
+        self._store = store
+        self._refresher = refresher
+        self._refresh_leeway = refresh_leeway
+        self._clock = clock
+        self._lock = asyncio.Lock()
+
+    def _is_usable(self, token: OAuthToken) -> bool:
+        expires_at = token.get("expires_at")
+        return expires_at is None or expires_at > self._clock() + self._refresh_leeway
+
+    async def get_valid_access_token(self, *, force_refresh: bool = False) -> str:
+        token = await self._store.load()
+        if token is None:
+            raise AuthenticationError("Login is required")
+        if not force_refresh and self._is_usable(token):
+            return token["access_token"]
+
+        async with self._lock:
+            token = await self._store.load()
+            if token is None:
+                raise AuthenticationError("Login is required")
+            if not force_refresh and self._is_usable(token):
+                return token["access_token"]
+            refreshed = await self._refresher.refresh(token)
+            await self._store.save(refreshed)
+            return refreshed["access_token"]
+```
+
+This lock covers one process. Replace or augment it with storage-level compare-and-swap or an inter-process lock when several processes share the same credential entry.
+
+## Authenticated HTTP Transport
+
+The transport should:
+
+1. Obtain a valid access token before sending a protected request.
+2. Inject the authorization header without exposing the token to API resource code.
+3. Apply the project's normal timeout, TLS, proxy, retry, and error-mapping policy.
+4. Optionally react to one `401` by forcing one synchronized refresh and replaying the request once.
+5. Raise an authentication error if the replay is still unauthorized.
+
+Do not refresh blindly on every `401`; unauthorized responses can indicate revocation, malformed credentials, the wrong audience, or another authentication failure. Never create an unbounded refresh or request loop. Replay only requests whose body can be safely regenerated, and do not treat `403` as an expiry signal.
+
+[HTTPX2 custom authentication](https://pydantic.dev/docs/httpx2/advanced/authentication/#custom-authentication-schemes) is a compact way to apply the token manager to every API request. This example retries one bodyless, read-only request after a synchronized refresh and leaves all other `401` responses untouched:
+
+```python
+import httpx2
+
+
+class OAuthAuth(httpx2.Auth):
+    requires_response_body = True
+
+    def __init__(self, tokens: TokenManager) -> None:
+        self._tokens = tokens
+
+    def sync_auth_flow(self, request: httpx2.Request):
+        raise RuntimeError("OAuthAuth requires httpx2.AsyncClient")
+        yield request
+
+    async def async_auth_flow(self, request: httpx2.Request):
+        access_token = await self._tokens.get_valid_access_token()
+        request.headers["Authorization"] = f"Bearer {access_token}"
+        response = yield request
+
+        if response.status_code != 401 or request.method not in {"GET", "HEAD", "OPTIONS"}:
+            return
+        access_token = await self._tokens.get_valid_access_token(force_refresh=True)
+        request.headers["Authorization"] = f"Bearer {access_token}"
+        yield request
+
+
+class ApiClient:
+    def __init__(self, base_url: str, tokens: TokenManager) -> None:
+        self._http = httpx2.AsyncClient(
+            base_url=base_url,
+            auth=OAuthAuth(tokens),
+            timeout=httpx2.Timeout(20.0, connect=5.0),
+        )
+
+    async def get_project(self, project_id: str) -> dict[str, object]:
+        response = await self._http.get(f"/projects/{project_id}")
+        response.raise_for_status()
+        value = response.json()
+        if not isinstance(value, dict):
+            raise ValueError("Expected an object response")
+        return value
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+```
+
+For streaming requests, uploads, or state-changing methods, omit automatic replay unless the API supplies an idempotency mechanism and the request body can be rebuilt. Map the final HTTPX2 response or exception into application errors before it reaches a CLI command.
+
+## Scopes And Token Restrictions
+
+- Request only scopes needed by the CLI's supported operations.
+- Keep scopes explicit in configuration and stable in tests.
+- Request offline access or equivalent provider-specific scope only when refresh tokens are needed.
+- Use audience or resource restrictions when supported.
+- Detect when stored authorization lacks scopes required by a command and direct the user through deliberate reauthorization rather than quietly broadening every login.
+
+## CLI Surface
+
+Expose a small authentication surface consistent with the existing command framework:
+
+```text
+mycli login
+mycli logout
+mycli auth status
+```
+
+`login` starts interactive authorization and reports only progress and outcome. `logout` deletes local token state and uses the provider's revocation endpoint when supported; explain if remote revocation fails after local deletion. `auth status` may show account identity, granted scopes, issuer, and expiry, but never a token or authorization code.
+
+A manual `auth refresh` command is optional and primarily diagnostic. Normal API commands should not require users to manage refresh timing.
+
+## Suggested Package Shape
+
+Adapt names to the existing project rather than forcing this exact tree:
+
+```text
+src/mycli/
+├── cli.py
+├── errors.py
+├── api/
+│   ├── client.py
+│   ├── transport.py
+│   └── resources/
+└── auth/
+    ├── config.py
+    ├── manager.py
+    ├── token.py
+    └── store.py
+```
+
+Keep token models independent from provider client objects so storage, tests, and API code do not inherit Authlib's internal representation as a public application contract.
+
+## Branching Guidance
+
+- If the provider supports loopback redirects: use Authorization Code with PKCE and an ephemeral `127.0.0.1` listener.
+- If the execution environment cannot open a browser or accept a loopback callback: use Device Authorization Grant only when the provider supports it.
+- If the API is called by unattended automation rather than a person: use the provider's machine-to-machine grant and credential mechanism; do not reuse an interactive user's refresh token as service identity.
+- If the provider supports discovery: derive endpoints from validated issuer metadata; otherwise pin explicit HTTPS endpoints.
+- If requests are concurrent in one process: serialize refresh with a lock and re-read state after acquisition.
+- If token state is shared across processes: use inter-process coordination and atomic persistence.
+- If an existing CLI already has HTTP and configuration abstractions: integrate at those boundaries instead of replacing the command framework or resource layer.
+
+## Tests And Verification
+
+Test protocol behavior without depending on a live identity provider:
+
+- Login creates fresh state and verifier values and uses `S256`.
+- Callback handling accepts the expected state and rejects missing, mismatched, duplicate, timed-out, and OAuth-error callbacks.
+- The listener binds only to loopback and always shuts down.
+- Token exchange uses the same redirect URI and verifier as authorization.
+- Valid tokens bypass refresh; near-expiry tokens refresh once.
+- Concurrent requests cause one refresh and all callers observe the persisted replacement token.
+- Refresh-token rotation cannot be overwritten by stale state.
+- A `401` causes at most one eligible replay; a second `401` fails.
+- Status and error output remain useful without revealing token values.
+- Logout clears local state and handles optional remote revocation explicitly.
+
+Use deterministic clocks, fake token stores, and [`httpx2.MockTransport`](https://pydantic.dev/docs/httpx2/advanced/transports/#mock-transports) for unit tests. Add a provider integration test only when the project has suitable isolated credentials and CI secret handling.
+
+## Completion Checks
+
+1. The CLI is registered and implemented as a public client without an embedded secret.
+2. Interactive login uses Authorization Code with PKCE `S256`, fresh state, exact redirect validation, and a bounded loopback listener.
+3. Device authorization is conditional on provider support and follows server polling instructions.
+4. Token storage is replaceable, protected, atomic, and absent from logs and normal output.
+5. One component owns expiry, synchronized refresh, and refresh-token rotation.
+6. API resources remain independent of OAuth protocol and storage details.
+7. Scopes and audience are minimal and explicit.
+8. Authentication retries are bounded and replay only eligible requests.
+9. Login, logout, status, refresh, concurrency, callback rejection, and redaction paths have focused verification.
+10. Provider-specific behavior and installed dependency versions are checked against current primary documentation.

src/personal_mcp/docs/skills/nicegui/SKILL.md

@@ -1,163 +1,73 @@
 ---
 name: nicegui
-description: 'Reference hub for NiceGUI and FastAPI application structure, typed configuration, ASGI and Uvicorn startup, UI composition, styling, bindable state, interactions, troubleshooting, testing, and source documentation. Use when planning, implementing, reviewing, deploying, or debugging NiceGUI applications; load only the references relevant to the task.'
+description: 'Build, review, debug, configure, deploy, and package NiceGUI applications. Use for FastAPI or Uvicorn integration, ui.run settings, native mode, Docker or executable deployment, app factories and lifespan, thin pages and reusable component factories, bindable dataclass handles, ui.refreshable methods, ui.* components, Quasar props/events/slots, Tailwind layout, colors, bindings, editable ui.table cells, uploads/forms/live updates, or version-specific source research.'
 ---
 
-# NiceGUI Reference
+# NiceGUI Application Guide
 
-Use this skill as a progressive reference for NiceGUI applications built with FastAPI. Start with the routing map, load only the material needed for the current question, and reconcile it with the target project's NiceGUI version and established conventions.
+Use this skill to choose the smallest supporting reference for a NiceGUI task. The pages cover different ownership boundaries; do not load the whole reference set.
 
-## When to Use
+## Workflow
 
-- Planning or reviewing NiceGUI application structure and FastAPI composition.
-- Building or refactoring pages, components, layouts, and static assets.
-- Creating editable tables with Python-authoritative state, validation, and persistence.
-- Modeling UI state with bindings or bindable dataclasses.
-- Implementing forms, uploads, refreshes, live updates, or background work.
-- Diagnosing UI state, concurrency, navigation, or asset problems.
-- Verifying framework behavior against primary documentation.
+1. Inspect the target project's pinned NiceGUI version, entry point, and existing page/component patterns.
+2. Match the request to one row in the routing table and load that primary reference.
+3. Load the optional companion only when the task crosses the boundary named in the last column.
+4. Prefer NiceGUI's typed constructor, binding, or helper API; descend to Quasar props, events, slots, or methods only when the wrapper does not expose the required behavior.
+5. Validate the changed behavior with a focused test. For visual work, also check the supported mobile, landscape desktop, and portrait desktop viewports.
 
-## How to Use This Skill
+## Task Routing
 
-1. Classify the request using the discovery map below.
-2. Load the smallest relevant reference, or at most two references for a mixed concern.
-3. Inspect the target repository before applying guidance; preserve its sound local patterns.
-4. Check the pinned NiceGUI and integration versions before relying on version-specific APIs.
-5. Validate the changed behavior with focused tests and, for UI work, relevant viewport checks.
+| Task or symptom | Load first | Add only when |
+| --- | --- | --- |
+| Choose package boundaries, dependency direction, thin page composition, reusable component factories, returned dataclass component handles, page registration, health routes, or optional subsystem placement | [application architecture](./references/architecture.md) | Add [binding dataclasses](./references/binding-dataclasses.md) for the component handle's binding graph or [FastAPI and Uvicorn startup](./references/fastapi-uvicorn-startup.md) for concrete ASGI ownership. |
+| Decide between `ui.run()` and `ui.run_with()`, compose a parent FastAPI app, define lifespan ordering, build an app factory, configure typed settings, expose a project script, or handle reload/workers | [FastAPI and Uvicorn startup](./references/fastapi-uvicorn-startup.md) | Add [configuration and deployment](./references/configuration-and-deployment.md) for concrete `ui.run` options, hosting, native mode, or packaging. |
+| Configure `ui.run`, consume `app.urls`, select NiceGUI environment variables, run behind Docker or a reverse proxy, enable HTTPS, build a native app, package with PyInstaller or Nuitka, or evaluate NiceGUI On Air | [configuration and deployment](./references/configuration-and-deployment.md) | Add [FastAPI and Uvicorn startup](./references/fastapi-uvicorn-startup.md) when a parent ASGI app, app factory, lifespan, reload, or workers own part of startup. |
+| Choose a `ui.*` constructor, binding, Quasar prop, event, slot, or frontend method; diagnose model events, event payloads, scoped-slot props, detached popups, `ui.select`, or `ui.icon` | [component mechanics](./references/component-mechanics.md) | Add [source documentation](./references/source-documentation.md) when the installed wrapper or bundled Quasar version must be verified. |
+| Build page shells, rows, columns, grids, widths, overflow, responsive reflow, typography, font loading, static assets, or deliberate scaling | [page structure, typography, and scaling](./references/styling-and-customization.md) | Add [component mechanics](./references/component-mechanics.md) when layout depends on a Quasar prop, slot, popup, or generated component structure. |
+| Configure `app.colors()`, `ui.colors()`, semantic or fixed Quasar colors, custom color names, component color values, CSS color variables, or `ui.dark_mode()` | [NiceGUI and Quasar color theming](./references/colors-and-quasar-theming.md) | Add [page structure, typography, and scaling](./references/styling-and-customization.md) only when the task also changes physical layout or CSS loading. |
+| Model typed page or component state with `binding.bindable_dataclass`, return a bound component handle, understand propagation and transform direction, bind nested values, avoid active-link polling, or design projection/persistence rollback | [binding dataclasses](./references/binding-dataclasses.md) | Add [application architecture](./references/architecture.md) for the render-factory and thin-page boundary or [component mechanics](./references/component-mechanics.md) for browser-originated proposals. |
+| Customize `ui.table` or QTable columns, formatting, classes, props, responsive density, toolbar controls, visible columns, empty states, named slots, or frontend methods | [table customization](./references/table-customization.md) | Add [editable tables](./references/tables.md) only when cells also accept server-authoritative edits. |
+| Make `ui.table` cells editable with stable row keys, dataframe projections, row-scoped dataclasses, validation, touched rows, selection-preserving refresh, or `QPopupEdit` | [editable tables](./references/tables.md) | Follow its links to binding or component mechanics only when changing the underlying projection or event bridge. |
+| Implement uploads, form submission, SSE versus WebSockets, background jobs, duplicate-submit guards, or `@ui.refreshable` and `@ui.refreshable_method` component regions | [interaction patterns](./references/interaction-patterns.md) | Add [application architecture](./references/architecture.md) for the reusable component contract or [binding dataclasses](./references/binding-dataclasses.md) when state propagation itself is the problem. |
+| Build or explain URL-backed tabs, persistent tab panels, `ui.sub_pages` route adapters, browser-history synchronization, or parameterized routes that share one tab | [URL-backed tabs with sub pages](./references/tabbed-subpages.md) | Add [binding dataclasses](./references/binding-dataclasses.md) only when the route-backed state grows beyond the single field shown in the example. |
+| Investigate upload errors, async UI races, stale assets, navigation/state drift, or perform a compact production-readiness review | [troubleshooting and quality gates](./references/troubleshooting-and-quality-gates.md) | Follow the symptom to one detailed reference above. |
+| Verify a framework claim against primary NiceGUI, FastAPI, Uvicorn, Tailwind, Quasar, SQLAlchemy, Pydantic, or LangGraph documentation | [source documentation](./references/source-documentation.md) | Use a task page first when implementation guidance, not source lookup, is needed. |
 
-## Progressive Discovery Map
+## Boundary Rules
 
-### Application Architecture
+- Use [application architecture](./references/architecture.md) for module ownership, not for page geometry or low-level component behavior.
+- Use [FastAPI and Uvicorn startup](./references/fastapi-uvicorn-startup.md) to decide which process owns startup; use [configuration and deployment](./references/configuration-and-deployment.md) after that decision for runtime, native, hosting, and packaging settings.
+- Keep page functions thin: compose page shells and returned component handles there; keep each component's element tree, bindings, callbacks, and bounded refreshes in its render factory or component object.
+- Use [page structure, typography, and scaling](./references/styling-and-customization.md) for physical layout. Use [component mechanics](./references/component-mechanics.md) for the behavior crossing NiceGUI, Quasar, Vue, and browser boundaries.
+- Start read-only table presentation and QTable control work in [table customization](./references/table-customization.md); keep editable state and validation in [editable tables](./references/tables.md).
+- Use [binding dataclasses](./references/binding-dataclasses.md) for the binding graph and Python model projections. Use [interaction patterns](./references/interaction-patterns.md) for user workflows such as upload, submit, refresh, streaming, and background work.
+- Start editable-table work in [editable tables](./references/tables.md). It already identifies the exact binding and event sections needed by that pattern.
+- Treat [source documentation](./references/source-documentation.md) as a source index, not as an implementation workflow.
 
-Load [application architecture](./references/architecture.md) for:
+## Runnable Examples
 
-- FastAPI app factories and lifespan ownership
-- package boundaries and dependency direction
-- page registration and health routes
-- optional persistence, LangGraph, or mounted documentation
-- async responsiveness and baseline tests
+Load an example only when its exact mechanic matches the task:
 
-### FastAPI And Uvicorn Startup
+- [binding transforms](./examples/data_binding.py): `bindable_dataclass`, `ui.date`, and typed `forward`/`backward` conversion.
+- [select events](./examples/select_events.py): `on_change`, generic Quasar events, `update:model-value`, browser-to-Python payload forwarding, and programmatic value changes.
+- [table customization](./examples/table_customization.py): raw-value sorting with cosmetic prefix, suffix, and datetime formatting; dynamic classes; QTable props; toolbar and cell slots; filtering; visible columns; and empty states.
+- [editable table](./examples/editable_table.py): dataframe-to-row state, named QTable cell slots, controlled editors, dialog-based whole-row save/cancel edits, Python validation, touched rows, and canonical row refresh.
+- [tabbed sub-pages](./examples/tab_spa.py): a persistent shell with URL-backed tabs, tab panels, browser-history navigation, and retained state for a parameterized report route. See the [reference explanation](./references/tabbed-subpages.md) for the ownership model and behavioral boundaries.
 
-Load [FastAPI and Uvicorn startup](./references/fastapi-uvicorn-startup.md) for:
-
-- choosing between `ui.run()` and `ui.run_with()`
-- understanding the parent FastAPI app and NiceGUI's internal app
-- composing ASGI lifespan and mounted routes
-- loading one typed settings snapshot for server and application configuration
-- serving an app instance or factory with Uvicorn
-- exposing programmatic startup through `[project.scripts]`
-- reload, worker, and process-local state constraints
-
-### Styling And Customization
-
-Load [styling and customization](./references/styling-and-customization.md) for:
-
-- app-wide and page-level color themes, dark mode, and semantic CSS tokens
-- Tailwind and Quasar utility classes
-- scoped CSS properties and stable application classes
-- responsive page composition and static asset loading
-- cosmetic treatment of controls, surfaces, typography, and visual states
-- visual validation at supported viewport sizes
-
-### Component Mechanics
-
-Load [component mechanics](./references/component-mechanics.md) for:
-
-- the NiceGUI Python wrapper, element bridge, Quasar component, and Vue runtime boundaries
-- deciding between constructors, bindings, Quasar props, events, slots, and frontend methods
-- server-client state and event flow
-- detached content and external icon assets
-- source research against the installed NiceGUI and bundled Quasar versions
-- `ui.select` and `ui.icon` mechanics and caveats
-- scoped component slots and their interaction contracts
-
-### Editable Tables
-
-Load [editable tables](./references/tables.md) for:
-
-- Python-authoritative editable `ui.table` state
-- rendering dataframe records into row-scoped bindable dataclasses
-- stable row identity across sorting, filtering, and pagination
-- NiceGUI editors in Quasar `body-cell-*` scoped slots
-- validation, persistence, rejection, and canonical row refresh
-- the full `body` slot required when escalating to `QPopupEdit`
-
-### Bindable State
-
-Load [bindable dataclasses](./references/binding-dataclasses.md) for:
-
-- typed local UI state
-- propagation and refresh behavior
-- nested structures and strict bindings
-- mutable defaults, performance, and version notes
-
-### Interaction Patterns
-
-Load [interaction patterns](./references/interaction-patterns.md) for:
-
-- uploads and form submission
-- explicit refreshes
-- server-sent events and WebSockets
-- background work and duplicate-submission guards
-
-### Troubleshooting And Quality
-
-Load [troubleshooting and quality gates](./references/troubleshooting-and-quality-gates.md) for:
-
-- upload failures and UI race conditions
-- stale assets and navigation drift
-- responsiveness, accessibility, reliability, and maintainability checks
-
-### Primary Sources
-
-Load [source documentation](./references/source-documentation.md) when:
-
-- behavior is version-sensitive or uncertain
-- an integration recommendation needs verification
-- upstream NiceGUI, FastAPI, Tailwind, Quasar, SQLAlchemy, Pydantic, or LangGraph documentation is required
-
-## Common Discovery Paths
-
-### New Application Or Architecture Review
-
-1. Load [application architecture](./references/architecture.md).
-2. Add [FastAPI and Uvicorn startup](./references/fastapi-uvicorn-startup.md) when FastAPI owns the application or startup must be exposed as a project command.
-3. Add [styling and customization](./references/styling-and-customization.md) only when page layout or visual customization is in scope.
-
-### Page Or Component Work
-
-1. Load [application architecture](./references/architecture.md) for page and component ownership decisions.
-2. Load [styling and customization](./references/styling-and-customization.md) for themes, layout, responsive presentation, utility classes, or CSS.
-3. Load [component mechanics](./references/component-mechanics.md) when behavior must be mapped across NiceGUI, Quasar, and Vue, or when detached content and component-specific behavior are involved.
-4. Load [editable tables](./references/tables.md) when table cells accept user changes or `QPopupEdit` is being considered.
-5. Add [interaction patterns](./references/interaction-patterns.md) or [bindable dataclasses](./references/binding-dataclasses.md) according to the page behavior.
-
-### Debugging Or Production Review
-
-1. Start with [troubleshooting and quality gates](./references/troubleshooting-and-quality-gates.md).
-2. Follow the symptom to one detailed reference.
-3. Confirm uncertain behavior in [source documentation](./references/source-documentation.md).
-
-## General Defaults
+## Defaults That Span References
 
 - Keep composition, transport, services, pages, and components directionally separated.
+- Prefer reusable render functions that return typed component handles; use bindable dataclass fields for the state intentionally exposed to composition code.
 - Keep business logic out of UI components and event handlers.
 - Avoid blocking I/O and CPU-heavy work in the UI event loop.
-- Prefer event-driven updates and explicit refreshes over unrelated polling.
-- Discover component capabilities through NiceGUI docs and constructors, then the wrapped Quasar API.
-- Keep editable table records authoritative in Python; send stable row keys with edit proposals and reassert canonical rows after validation.
-- Research the current NiceGUI and Quasar source documentation before generating component-specific code or CSS.
-- Prefer constructor arguments and native Quasar features through NiceGUI; use Tailwind for structure and scoped static CSS for stable fine tuning.
+- Prefer event-driven updates and explicit refreshes to unrelated polling.
+- Keep browser-originated values as proposals; validate and normalize them in Python before mutating authoritative state.
+- Prefer NiceGUI context managers and `ui.*` elements over raw Vue templates. Keep application logic and authoritative state in Python; use minimal browser expressions only for scoped-slot values or client-only behavior, following [Python-owned slot composition](./references/component-mechanics.md#prefer-python-owned-composition).
+- For each presentation requirement, check the component's typed Python arguments and helpers before using `.props(...)` or `.classes(...)`. Create an application class and add CSS only when no Python API, documented component prop or slot, or existing utility class can express the requirement.
+- Use NiceGUI context managers for element structure and Tailwind for generic layout, spacing, responsive behavior, and typography. Keep Quasar classes for semantic palette roles or component-specific geometry, and use Quasar props for component behavior and density; see [combining Tailwind with Quasar utilities](./references/styling-and-customization.md#combine-tailwind-with-quasar-utilities-deliberately).
 - Provide loading, success, and failure states for user-triggered work.
-- Treat version-specific guidance as a prompt to verify the project's dependency version.
+- Verify component-specific behavior against the installed NiceGUI version and its bundled Quasar version.
 
-## Reference Use Contract
+## Completion Check
 
-When applying this skill:
-
-- return only guidance relevant to the current task
-- distinguish repository facts from reference recommendations
-- cite the appropriate source reference for framework-level claims
-- state assumptions when application requirements are missing
-- report the focused checks used to validate implementation changes
+Before finishing, distinguish target-repository facts from reference recommendations, cite the supporting page used for framework-specific claims, state unresolved assumptions, and report the focused behavior and viewport checks performed.

src/personal_mcp/docs/skills/nicegui/examples/data_binding.py

@@ -0,0 +1,30 @@
+from dataclasses import field
+from datetime import date
+
+from nicegui import binding
+from nicegui import ui
+
+
+@binding.bindable_dataclass
+class ReportFilters:
+    start_on: date = field(default_factory=date.today)
+    page_size: int = 25
+
+
+filters = ReportFilters()
+
+ui.date().bind_value(
+    filters,
+    "start_on",
+    forward=date.fromisoformat,  # control str -> model date
+    backward=date.isoformat,  # model date -> control str
+)
+
+ui.label().bind_text_from(
+    filters,
+    "start_on",
+    backward=lambda value: f"Starting {value:%d %B %Y}",
+)
+
+if __name__ in {"__main__", "__mp_main__"}:
+    ui.run(port=8888, reload=True)

src/personal_mcp/docs/skills/nicegui/examples/editable_table.py

@@ -3,37 +3,125 @@
 # dependencies = [
 #   "nicegui==3.16.0",
 #   "pandas",
+#   "pydantic>=2",
 # ]
 # ///
 
+from collections.abc import Callable
 from dataclasses import dataclass
+from dataclasses import field
 
 import pandas as pd
 from nicegui import binding
 from nicegui import events
 from nicegui import ui
+from pydantic import BaseModel
+from pydantic import ValidationError
+from pydantic import field_validator
 
 STATUS_OPTIONS = ["draft", "active", "archived"]
 EDITABLE_FIELDS = ("name", "quantity", "status")
-TableValue = str | int
-TableRow = dict[str, TableValue]
+
+type TableValue = str | int
+type TableRow = dict[str, TableValue]
 
 
-@binding.bindable_dataclass(bindable_fields=EDITABLE_FIELDS)
+class RowEditDraft(BaseModel):
+    name: str
+    quantity: int
+    status: str
+
+    @field_validator("name")
+    @classmethod
+    def validate_name(cls, value: str) -> str:
+        if not (name := value.strip()):
+            raise ValueError("Name is required")
+        return name
+
+    @field_validator("quantity", mode="before")
+    @classmethod
+    def validate_quantity(cls, value: object) -> int:
+        if isinstance(value, bool) or value is None:
+            raise TypeError("Quantity must be an integer")
+        if not isinstance(value, (int, float, str)):
+            raise TypeError("Quantity must be an integer")
+        if isinstance(value, float) and not value.is_integer():
+            raise ValueError("Quantity must be an integer")
+        try:
+            quantity = int(value)
+        except (TypeError, ValueError, OverflowError) as error:
+            raise ValueError("Quantity must be an integer") from error
+        if not 0 <= quantity <= 1_000:
+            raise ValueError("Quantity must be between 0 and 1000")
+        return quantity
+
+    @field_validator("status")
+    @classmethod
+    def validate_status(cls, value: str) -> str:
+        if value not in STATUS_OPTIONS:
+            raise ValueError("Unknown status")
+        return value
+
+
+@dataclass(slots=True)
+class RowEditorDialog:
+    open_for_row_id: Callable[[int], None]
+
+
+def _validation_message(error: ValidationError) -> str:
+    return str(error.errors()[0]["msg"])
+
+
+@binding.bindable_dataclass
 class EditableRow:
     id: int
     name: str
     quantity: int
     status: str
+    table_row: TableRow = field(init=False, repr=False)
+    touched: bool = False
+
+    def __post_init__(self) -> None:
+        self.table_row = {
+            "id": self.id,
+            "name": self.name,
+            "quantity": self.quantity,
+            "status": self.status,
+        }
+        for field_name in EDITABLE_FIELDS:
+            binding.bind_to(
+                self,
+                field_name,
+                self.table_row,
+                field_name,
+                other_strict=True,
+            )
+
+    def to_draft(self) -> RowEditDraft:
+        return RowEditDraft(name=self.name, quantity=self.quantity, status=self.status)
+
+    def validate_update(self, updates: dict[str, object]) -> RowEditDraft:
+        base_values = self.to_draft().model_dump()
+        return RowEditDraft.model_validate({**base_values, **updates})
+
+    def apply_draft(self, draft: RowEditDraft) -> None:
+        self.name = draft.name
+        self.quantity = draft.quantity
+        self.status = draft.status
 
 
 @dataclass(slots=True)
 class EditableTableState:
     rows_by_id: dict[int, EditableRow]
-    table_rows_by_id: dict[int, TableRow]
+
+    def row(self, row_id: int) -> EditableRow | None:
+        return self.rows_by_id.get(row_id)
 
     def table_rows(self) -> list[TableRow]:
-        return list(self.table_rows_by_id.values())
+        return [row.table_row for row in self.rows_by_id.values()]
+
+    def touched_rows(self) -> list[EditableRow]:
+        return [row for row in self.rows_by_id.values() if row.touched]
 
 
 def dataframe_to_state(dataframe: pd.DataFrame) -> EditableTableState:
@@ -45,72 +133,81 @@ def dataframe_to_state(dataframe: pd.DataFrame) -> EditableTableState:
         raise ValueError("The id column must contain unique row keys")
 
     rows_by_id: dict[int, EditableRow] = {}
-    table_rows_by_id: dict[int, TableRow] = {}
     for record in dataframe.to_dict(orient="records"):
-        row_state = EditableRow(
+        row = EditableRow(
             id=int(record["id"]),
             name=str(record["name"]),
             quantity=int(record["quantity"]),
             status=str(record["status"]),
         )
-        if row_state.status not in STATUS_OPTIONS:
-            raise ValueError(f"Unknown status {row_state.status!r}")
-        if row_state.id in rows_by_id:
+        if row.status not in STATUS_OPTIONS:
+            raise ValueError(f"Unknown status {row.status!r}")
+        if row.id in rows_by_id:
             raise ValueError("Row keys must remain unique after normalization")
+        rows_by_id[row.id] = row
 
-        table_row: TableRow = {
-            "id": row_state.id,
-            "name": row_state.name,
-            "quantity": row_state.quantity,
-            "status": row_state.status,
-        }
-        for field_name in EDITABLE_FIELDS:
-            binding.bind_to(
-                row_state,
-                field_name,
-                table_row,
-                field_name,
-                other_strict=True,
-            )
-        rows_by_id[row_state.id] = row_state
-        table_rows_by_id[row_state.id] = table_row
-
-    return EditableTableState(rows_by_id, table_rows_by_id)
+    return EditableTableState(rows_by_id)
 
 
-def normalize_edit(field: str, raw_value: object) -> TableValue:
-    match field:
-        case "name":
-            if not isinstance(raw_value, str) or not (name := raw_value.strip()):
-                raise ValueError("Name is required")
-            return name
-        case "quantity":
-            if isinstance(raw_value, bool) or not isinstance(raw_value, (int, float, str)):
-                raise TypeError("Quantity must be an integer")
-            if isinstance(raw_value, float) and not raw_value.is_integer():
-                raise ValueError("Quantity must be an integer")
-            try:
-                quantity = int(raw_value)
-            except (ValueError, OverflowError) as error:
-                raise ValueError("Quantity must be an integer") from error
-            if not 0 <= quantity <= 1_000:
-                raise ValueError("Quantity must be between 0 and 1000")
-            return quantity
-        case "status":
-            if not isinstance(raw_value, str) or raw_value not in STATUS_OPTIONS:
-                raise ValueError("Unknown status")
-            return raw_value
-        case _:
-            raise ValueError(f"Field {field!r} is not editable")
+def render_row_editor_dialog(
+    state: EditableTableState,
+    refresh_table: Callable[[], None],
+) -> RowEditorDialog:
+    selected_row_id: int | None = None
 
+    with ui.dialog() as edit_dialog, ui.card().classes("w-96"):
+        dialog_heading = ui.label("Edit row")
+        draft_name = ui.input("Name")
+        draft_quantity = ui.number("Quantity", min=0, max=1_000, precision=0)
+        draft_status = ui.select(STATUS_OPTIONS, label="Status")
+        with ui.row().classes("w-full justify-end"):
+            ui.button("Cancel", on_click=edit_dialog.close).props("flat")
 
-def save_row(dataframe: pd.DataFrame, row_state: EditableRow) -> None:
-    matching_rows = dataframe["id"].eq(row_state.id)
-    if int(matching_rows.sum()) != 1:
-        raise ValueError("This row no longer exists")
-    dataframe.loc[matching_rows, "name"] = row_state.name
-    dataframe.loc[matching_rows, "quantity"] = row_state.quantity
-    dataframe.loc[matching_rows, "status"] = row_state.status
+            def save_dialog_edit() -> None:
+                nonlocal selected_row_id
+                try:
+                    if selected_row_id is None:
+                        raise ValueError("Select a row before saving")
+
+                    row_state = state.row(selected_row_id)
+                    if row_state is None:
+                        raise ValueError("This row no longer exists")
+
+                    draft = row_state.validate_update(
+                        {
+                            "name": draft_name.value,
+                            "quantity": draft_quantity.value,
+                            "status": draft_status.value,
+                        },
+                    )
+                    row_state.apply_draft(draft)
+                    row_state.touched = True
+                    edit_dialog.close()
+                except ValidationError as error:
+                    ui.notify(_validation_message(error), type="negative")
+                except ValueError as error:
+                    ui.notify(str(error), type="negative")
+                finally:
+                    refresh_table()
+
+            ui.button("Save", icon="save", on_click=save_dialog_edit)
+
+    def open_for_row_id(row_id: int) -> None:
+        nonlocal selected_row_id
+        row_state = state.row(row_id)
+        if row_state is None:
+            ui.notify("This row no longer exists", type="negative")
+            return
+
+        selected_row_id = row_id
+        draft = row_state.to_draft()
+        dialog_heading.set_text(f"Edit row {row_id}")
+        draft_name.set_value(draft.name)
+        draft_quantity.set_value(draft.quantity)
+        draft_status.set_value(draft.status)
+        edit_dialog.open()
+
+    return RowEditorDialog(open_for_row_id=open_for_row_id)
 
 
 def render_table(dataframe: pd.DataFrame) -> EditableTableState:
@@ -119,58 +216,106 @@ def render_table(dataframe: pd.DataFrame) -> EditableTableState:
         {"name": "name", "label": "Name", "field": "name", "align": "left"},
         {"name": "quantity", "label": "Quantity", "field": "quantity", "align": "right"},
         {"name": "status", "label": "Status", "field": "status", "align": "left"},
+        {"name": "actions", "label": "Actions", "field": "id", "align": "center"},
     ]
     table = ui.table(
         columns=columns,
         rows=state.table_rows(),
         row_key="id",
         selection="multiple",
-    ).classes("w-full")
+        pagination=10,
+    ).classes("w-120")
 
-    def apply_edit(event: events.GenericEventArguments) -> None:
+    def refresh_table() -> None:
+        table.update_rows(state.table_rows(), clear_selection=False)
+
+    def apply_inline_edit(event: events.GenericEventArguments) -> None:
         try:
             raw_row_id, raw_field, raw_value = event.args
             row_id = int(raw_row_id)
             field_name = str(raw_field)
-            row_state = state.rows_by_id.get(row_id)
+            if field_name not in EDITABLE_FIELDS:
+                raise ValueError(f"Field {field_name!r} is not editable")
+
+            row_state = state.row(row_id)
             if row_state is None:
                 raise ValueError("This row no longer exists")
 
-            normalized_value = normalize_edit(field_name, raw_value)
-            previous_value = getattr(row_state, field_name)
-            setattr(row_state, field_name, normalized_value)
-            try:
-                save_row(dataframe, row_state)
-            except Exception:
-                setattr(row_state, field_name, previous_value)
-                raise
+            draft = row_state.validate_update({field_name: raw_value})
+            row_state.apply_draft(draft)
+            row_state.touched = True
+        except ValidationError as error:
+            ui.notify(_validation_message(error), type="negative")
         except (TypeError, ValueError) as error:
             ui.notify(str(error), type="negative")
         finally:
-            table.update_rows(state.table_rows(), clear_selection=False)
+            refresh_table()
 
+    def show_changes() -> None:
+        changed_rows = state.touched_rows()
+        if not changed_rows:
+            ui.notify("No rows changed")
+            return
+        for row in changed_rows:
+            ui.notify(f"Changed row: {row.id}: {row.name}, quantity {row.quantity}, status {row.status}")
+
+    row_editor = render_row_editor_dialog(state, refresh_table)
+
+    _add_slots(
+        table,
+        apply_inline_edit,
+        row_editor.open_for_row_id,
+    )
+
+    with ui.row().classes("w-120 justify-end"):
+        ui.button("Show changes", icon="edit_note", on_click=show_changes)
+
+    return state
+
+
+def open_dialog_for_row(open_editor: Callable[[int], None], event: events.GenericEventArguments) -> None:
+    try:
+        row_id = int(event.args)
+        open_editor(row_id)
+    except (TypeError, ValueError):
+        ui.notify("Invalid row key", type="negative")
+
+
+def _add_slots(
+    table: ui.table,
+    apply_inline_edit: Callable[[events.GenericEventArguments], None],
+    open_editor: Callable[[int], None],
+):
     with table.add_slot("body-cell-name"), table.cell("name"):
-        ui.input().props(':model-value="props.value" dense borderless debounce=400').on(
-            "update:model-value",
-            handler=apply_edit,
+        name_input = ui.input().props(remove="value")
+        name_input.props(':value="props.value" dense borderless debounce=400').on(
+            "update:value",
+            handler=apply_inline_edit,
             js_handler="(value) => emit(props.row.id, props.col.name, value)",
         )
 
     with table.add_slot("body-cell-quantity"), table.cell("quantity"):
         ui.number(min=0, max=1_000).props(':model-value="props.value" dense borderless debounce=400').on(
             "update:model-value",
-            handler=apply_edit,
+            handler=apply_inline_edit,
             js_handler="(value) => emit(props.row.id, props.col.name, value)",
         )
 
     with table.add_slot("body-cell-status"), table.cell("status"):
         ui.select(STATUS_OPTIONS).props(':model-value="props.value" dense borderless options-dense').on(
             "update:model-value",
-            handler=apply_edit,
-            js_handler="(value) => emit(props.row.id, props.col.name, value)",
+            handler=apply_inline_edit,
+            js_handler="(option) => emit(props.row.id, props.col.name, option.label)",
         )
 
-    return state
+    with table.add_slot("body-cell-actions"), table.cell("actions"):
+        edit_button = ui.button(icon="edit")
+        edit_button.props('flat round dense color=primary aria-label="Edit row"')
+        edit_button.tooltip("Edit this row").on(
+            "click",
+            handler=lambda event: open_dialog_for_row(open_editor, event),
+            js_handler="() => emit(props.row.id)",
+        )
 
 
 if __name__ in {"__main__", "__mp_main__"}:
@@ -178,6 +323,14 @@ if __name__ in {"__main__", "__mp_main__"}:
         [
             {"id": 101, "name": "Desk", "quantity": 4, "status": "active"},
             {"id": 102, "name": "Lamp", "quantity": 12, "status": "draft"},
+            {"id": 103, "name": "Chair", "quantity": 8, "status": "active"},
+            {"id": 104, "name": "Shelf", "quantity": 3, "status": "draft"},
+            {"id": 105, "name": "Monitor", "quantity": 15, "status": "active"},
+            {"id": 106, "name": "Keyboard", "quantity": 20, "status": "active"},
+            {"id": 107, "name": "Mouse", "quantity": 24, "status": "active"},
+            {"id": 108, "name": "Dock", "quantity": 6, "status": "archived"},
+            {"id": 109, "name": "Cable", "quantity": 40, "status": "draft"},
+            {"id": 110, "name": "Stand", "quantity": 10, "status": "active"},
         ]
     )
     table_state = render_table(items)

src/personal_mcp/docs/skills/nicegui/examples/select_events.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# dependencies = [
+#   "nicegui==3.16.0",
+# ]
+# ///
+
+from datetime import UTC
+from datetime import datetime
+
+from nicegui import events
+from nicegui import ui
+
+OPTIONS = {
+    "python": "Python",
+    "typescript": "TypeScript",
+    "rust": "Rust",
+}
+
+
+with ui.card().classes("w-140 max-w-full"):
+    ui.label("Select event mechanics").classes("text-xl font-semibold")
+    event_log = ui.log(max_lines=12).classes("w-full h-64")
+
+    def record(event_name: str, payload: object) -> None:
+        timestamp = datetime.now(UTC).astimezone().strftime("%H:%M:%S")
+        event_log.push(f"{timestamp}  {event_name}: {payload!r}")
+
+    def handle_change(event: events.ValueChangeEventArguments) -> None:
+        record("on_change event.value", event.value)
+
+    def handle_model_update(event: events.GenericEventArguments) -> None:
+        record("js_handler -> handler event.args", event.args)
+
+    language = (
+        ui.select(
+            options=OPTIONS,
+            value="python",
+            label="Language",
+            on_change=handle_change,
+            with_input=True,
+            clearable=True,
+        )
+        .props("outlined options-dense")
+        .classes("w-full text-h6")
+    )
+
+    language.on("popup-show", lambda: record("popup-show", None), args=[])
+    language.on("popup-hide", lambda: record("popup-hide", None), args=[])
+
+    # This only fires when the value is changed from the browser side (not from the button)
+    language.on(
+        "update:model-value",
+        handler=handle_model_update,
+        js_handler="(...args) => emit(...args)",
+    )
+
+    with ui.row().classes("w-full justify-end"):
+        ui.button("Set Rust", on_click=lambda: language.set_value("rust"))
+        ui.button("Clear log", on_click=event_log.clear).props("flat")
+
+
+if __name__ in {"__main__", "__mp_main__"}:
+    ui.run(port=8888, reload=True)

src/personal_mcp/docs/skills/nicegui/examples/tab_spa.py

@@ -0,0 +1,210 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# dependencies = [
+#   "nicegui==3.16.0",
+# ]
+# ///
+
+"""Demonstrate URL-backed tabs with persistent parameterized-route state."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from urllib.parse import urlsplit
+
+from nicegui import binding
+from nicegui import events
+from nicegui import ui
+from nicegui.elements.tabs import Tab
+from nicegui.elements.tabs import TabPanel
+
+type PageBuilder = Callable[..., None]
+
+DEFAULT_REPORT_PATH = "/reports/a"
+REPORTS_TAB = "reports"
+TAB_ROUTES = frozenset({"/", "/projects", "/settings"})
+
+
+def page_heading(title: str, description: str) -> None:
+    """Render a shared heading for sub-page content."""
+    with ui.column().classes("w-full gap-1"):
+        ui.label(title).classes("text-3xl font-semibold text-stone-900")
+        ui.label(description).classes("text-base text-stone-600")
+
+
+def overview_page() -> None:
+    """Render the overview sub-page."""
+    with ui.column().classes("w-full max-w-6xl mx-auto gap-6 px-4 py-8"):
+        page_heading("Overview", "A quick read on the workspace today.")
+
+        metrics = (
+            ("Active projects", "8", "folder_open", "primary"),
+            ("Tasks completed", "24", "task_alt", "positive"),
+            ("Needs attention", "3", "error_outline", "warning"),
+        )
+        with ui.grid().classes("w-full grid-cols-1 gap-4 md:grid-cols-3"):
+            for label, value, icon, color in metrics:
+                with ui.card().classes("w-full p-5 gap-3"):
+                    with ui.row().classes("w-full items-center justify-between"):
+                        ui.label(label).classes("text-sm font-medium text-stone-600")
+                        ui.icon(icon, color=color).classes("text-2xl")
+                    ui.label(value).classes("text-3xl font-semibold text-stone-900")
+
+
+def projects_page() -> None:
+    """Render the projects sub-page."""
+    with ui.column().classes("w-full max-w-6xl mx-auto gap-6 px-4 py-8"):
+        page_heading("Projects", "Each route builds its own content inside the shared shell.")
+
+        with ui.list().props("bordered separator").classes("w-full bg-white rounded"):
+            for name, status, color in (
+                ("Client portal", "On track", "positive"),
+                ("Mobile refresh", "In review", "primary"),
+                ("Data migration", "Blocked", "negative"),
+            ):
+                with ui.item():
+                    with ui.item_section().props("avatar"):
+                        ui.icon("folder", color=color)
+                    with ui.item_section():
+                        ui.item_label(name)
+                        ui.item_label(status).props("caption")
+                    with ui.item_section().props("side"):
+                        ui.badge(status, color=color)
+
+
+def report_page(state: NavigationState) -> None:
+    """Render report content bound to the active route parameter."""
+    with ui.column().classes("w-full max-w-6xl mx-auto gap-6 px-4 py-8"):
+        with ui.column().classes("w-full gap-1"):
+            ui.label().bind_text_from(
+                state,
+                "active_report_path",
+                backward=lambda path: f"Report {report_id_from_path(path).upper()}",
+            ).classes("text-3xl font-semibold text-stone-900")
+            ui.label("The report ID is injected from the URL path.").classes("text-base text-stone-600")
+
+        with ui.card().classes("w-full max-w-2xl p-5 gap-4"):
+            ui.label("Parameterized route").classes("text-xl font-semibold text-stone-900")
+            ui.label().bind_text_from(
+                state,
+                "active_report_path",
+                backward=lambda path: f"Loaded {path}",
+            ).classes("text-stone-600")
+            with ui.row().classes("gap-2"):
+                ui.button("Report A", on_click=lambda: ui.navigate.to("/reports/a")).props("outline")
+                ui.button("Report B", on_click=lambda: ui.navigate.to("/reports/b")).props("outline")
+
+
+def settings_page() -> None:
+    """Render the settings sub-page."""
+    with ui.column().classes("w-full max-w-6xl mx-auto gap-6 px-4 py-8"):
+        page_heading("Settings", "Controls here are recreated when this sub-page is opened.")
+
+        with ui.card().classes("w-full max-w-2xl p-5 gap-4"):
+            ui.label("Notifications").classes("text-xl font-semibold text-stone-900")
+            ui.switch("Weekly summary", value=True)
+            ui.switch("Project status changes", value=True)
+            ui.switch("Product announcements", value=False)
+
+
+def normalize_route(path: str) -> str:
+    """Extract and normalize the path portion of a route."""
+    return urlsplit(path).path.rstrip("/") or "/"
+
+
+def tab_name_for_route(route: str) -> str:
+    """Return the tab name associated with a concrete route."""
+    if route.startswith("/reports/"):
+        return REPORTS_TAB
+    return route if route in TAB_ROUTES else "/"
+
+
+@binding.bindable_dataclass
+class NavigationState:
+    """Store client-local navigation state for parameterized tabs."""
+
+    active_report_path: str = DEFAULT_REPORT_PATH
+
+
+type TabHandler = events.ValueChangeEventArguments[str | Tab | TabPanel | None]
+
+
+def report_id_from_path(path: str) -> str:
+    """Extract the report ID from a normalized report route."""
+    return path.rsplit("/", maxsplit=1)[-1]
+
+
+def create_tabs(state: NavigationState, initial_route: str) -> ui.tabs:
+    """Create route-aware tabs and retain the last selected report."""
+
+    def navigate(event: TabHandler) -> None:
+        """Navigate to the route represented by the selected tab."""
+        match event.value:
+            case str(tabname):
+                destination = state.active_report_path if tabname == REPORTS_TAB else tabname
+                ui.navigate.to(destination)
+            case _:
+                return
+
+    with ui.column().classes("mx-auto"), ui.tabs() as tabs:
+        ui.tab("/", label="Overview", icon="space_dashboard")
+        ui.tab("/projects", label="Projects", icon="folder_open")
+        ui.tab(REPORTS_TAB, label="Reports", icon="summarize")
+        ui.tab("/settings", label="Settings", icon="settings")
+
+    tabs.set_value(tab_name_for_route(initial_route))
+    tabs.on_value_change(navigate)
+
+    return tabs
+
+
+def render_tab_panels(tabs: ui.tabs, state: NavigationState, active_tab: str) -> None:
+    """Render all tabbed page content inside a tab panels container."""
+    with ui.tab_panels(tabs, value=active_tab, animated=True).classes("w-full"):
+        with ui.tab_panel("/"):
+            overview_page()
+        with ui.tab_panel("/projects"):
+            projects_page()
+        with ui.tab_panel(REPORTS_TAB):
+            report_page(state)
+        with ui.tab_panel("/settings"):
+            settings_page()
+
+
+def root() -> None:
+    """Build the persistent application shell and sub-page container."""
+    initial_route = normalize_route(ui.context.client.sub_pages_router.current_path)
+    state = NavigationState()
+    if tab_name_for_route(initial_route) == REPORTS_TAB:
+        state.active_report_path = initial_route
+
+    with ui.header(elevated=True).classes("py-0 items-center"):
+        tabs = create_tabs(state, initial_route)
+        ui.button(icon="settings").classes("text-white").props("round flat").tooltip("Settings")
+
+    render_tab_panels(tabs, state, tab_name_for_route(initial_route))
+
+    def route_overview() -> None:
+        tabs.set_value("/")
+
+    def route_projects() -> None:
+        tabs.set_value("/projects")
+
+    def route_reports(report_id: str) -> None:
+        state.active_report_path = f"/reports/{report_id}"
+        tabs.set_value(REPORTS_TAB)
+
+    def route_settings() -> None:
+        tabs.set_value("/settings")
+
+    routes: dict[str, PageBuilder] = {
+        "/": route_overview,
+        "/projects": route_projects,
+        "/reports/{report_id}": route_reports,
+        "/settings": route_settings,
+    }
+    ui.sub_pages(routes).classes("hidden")
+
+
+if __name__ in {"__main__", "__mp_main__"}:
+    ui.run(root, title="Northstar", port=8888, reload=True)

src/personal_mcp/docs/skills/nicegui/examples/table_customization.py

@@ -0,0 +1,253 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# dependencies = [
+#   "nicegui==3.16.0",
+# ]
+# ///
+
+from nicegui import events
+from nicegui import ui
+
+type TableValue = str | int | float
+type TableRow = dict[str, TableValue]
+
+STATUS_COLORS = {
+    "Ready": "positive",
+    "Low": "warning",
+    "Backorder": "negative",
+}
+
+COLUMNS = [
+    {
+        "name": "actions",
+        "label": "Actions",
+        "required": True,
+        "align": "center",
+    },
+    {
+        "name": "name",
+        "label": "Product",
+        "field": "name",
+        "required": True,
+        "sortable": True,
+        "align": "left",
+        "headerClasses": "bg-grey-2 text-grey-9 font-bold",
+        "classes": "font-medium",
+        "headerStyle": "width: 40%; min-width: 12rem",
+        "style": "width: 40%; min-width: 12rem",
+    },
+    {
+        "name": "category",
+        "label": "Category",
+        "field": "category",
+        "sortable": True,
+        "align": "left",
+        "headerStyle": "width: 9rem",
+        "style": "width: 9rem",
+    },
+    {
+        "name": "stock",
+        "label": "In stock",
+        "field": "stock",
+        "sortable": True,
+        "align": "right",
+        "headerStyle": "width: 7rem",
+        "style": "width: 7rem",
+        ":classes": "row => row.stock < 10 ? 'text-negative font-bold' : ''",
+        ":format": "value => value == null ? '' : `${value} units`",
+    },
+    {
+        "name": "price",
+        "label": "Unit price",
+        "field": "price",
+        "sortable": True,
+        "align": "right",
+        "headerStyle": "width: 8rem",
+        "style": "width: 8rem",
+        ":format": "value => value == null ? '' : `$${value.toFixed(2)}`",
+    },
+    {
+        "name": "status",
+        "label": "Status",
+        "field": "status",
+        "sortable": True,
+        "align": "center",
+        "headerStyle": "width: 8rem",
+        "style": "width: 8rem",
+        "colorByValue": STATUS_COLORS,
+    },
+    {
+        "name": "updated_at",
+        "label": "Updated",
+        "field": "updated_at",
+        "sortable": True,
+        "align": "left",
+        "headerStyle": "width: 13rem",
+        "style": "width: 13rem",
+        ":sort": "(left, right) => Date.parse(left) - Date.parse(right)",
+        ":format": """(() => {
+            const formatter = new Intl.DateTimeFormat('en-US', {
+                dateStyle: 'medium',
+                timeStyle: 'short',
+                timeZone: 'UTC',
+            });
+            return value => {
+                if (!value) return '';
+                const timestamp = Date.parse(value);
+                return Number.isNaN(timestamp) ? 'Invalid date' : formatter.format(timestamp);
+            };
+        })()""",
+    },
+]
+
+ROWS: list[TableRow] = [
+    {
+        "id": 101,
+        "name": "Desk lamp",
+        "category": "Lighting",
+        "stock": 7,
+        "price": 42.5,
+        "status": "Low",
+        "updated_at": "2026-08-31T16:20:00Z",
+    },
+    {
+        "id": 102,
+        "name": "Task chair",
+        "category": "Seating",
+        "stock": 18,
+        "price": 289.0,
+        "status": "Ready",
+        "updated_at": "2026-09-01T08:45:00Z",
+    },
+    {
+        "id": 103,
+        "name": "Monitor arm",
+        "category": "Hardware",
+        "stock": 0,
+        "price": 119.95,
+        "status": "Backorder",
+        "updated_at": "2026-08-29T11:05:00Z",
+    },
+    {
+        "id": 104,
+        "name": "Cable tray",
+        "category": "Hardware",
+        "stock": 34,
+        "price": 31.25,
+        "status": "Ready",
+        "updated_at": "2026-09-01T14:30:00Z",
+    },
+    {
+        "id": 105,
+        "name": "Side table",
+        "category": "Furniture",
+        "stock": 9,
+        "price": 164.5,
+        "status": "Low",
+        "updated_at": "2026-08-30T19:15:00Z",
+    },
+    {
+        "id": 106,
+        "name": "Floor light",
+        "category": "Lighting",
+        "stock": 15,
+        "price": 98.0,
+        "status": "Ready",
+        "updated_at": "2026-09-01T10:10:00Z",
+    },
+]
+
+
+def render_table() -> ui.table:
+    table = ui.table(
+        columns=COLUMNS,
+        column_defaults={"headerClasses": "text-grey-8"},
+        rows=ROWS,
+        row_key="id",
+        pagination={
+            "sortBy": "stock",
+            "descending": True,
+            "rowsPerPage": 5,
+        },
+    ).classes("w-full max-w-5xl")
+
+    (
+        table.props(
+            # Surface and cell layout.
+            "flat bordered separator=horizontal wrap-cells"
+        )
+        .props(
+            # Local sorting and page-size choices; zero means "all rows".
+            'binary-state-sort :rows-per-page-options="[5, 10, 0]"'
+        )
+        .props(
+            # Compact cells only below Quasar's medium breakpoint.
+            ':dense="Quasar.Screen.lt.md"'
+        )
+        .props(
+            # Distinguish an empty dataset from a filter with no matches.
+            'no-data-label="No inventory items" no-results-label="No matching inventory items"'
+        )
+    )
+
+    with table.add_slot("top-left"), ui.row(align_items="center").classes("gap-2"):
+        ui.icon("inventory_2", size="sm", color="primary")
+        ui.label("Inventory").classes("text-xl font-medium")
+        ui.badge(str(len(ROWS)), color="grey-3", text_color="grey-9")
+
+    with table.add_slot("top-right"):
+        ui.input(placeholder="Search inventory").props("dense outlined clearable debounce=250").bind_value_to(
+            table,
+            "filter",
+        )
+
+    with table.add_slot("body-cell-status"), table.cell("status"):
+        ui.badge(outline=True).props(':label="props.value" :color="props.col.colorByValue[props.value] ?? \'grey\'"')
+
+    def open_product(event: events.GenericEventArguments) -> None:
+        product = next((row for row in table.rows if row[table.row_key] == event.args), None)
+        if product is None:
+            ui.notify("Product no longer exists", type="negative")
+            return
+        ui.notify(f"Opening {product['name']}")
+
+    with (
+        table.add_slot("body-cell-actions"),
+        table.cell("actions"),
+        ui.button(icon="open_in_new")
+        .props("round flat size='sm'")
+        .on(
+            "click.stop",
+            handler=open_product,
+            js_handler="() => emit(props.key)",
+        ),
+    ):
+        ui.tooltip("Open product")
+
+    with table.add_slot("no-data"), ui.row(align_items="center").classes("w-full justify-center gap-2 p-6 text-grey-7"):
+        ui.icon("inventory_2", size="2em").props(":name=\"props.filter ? 'filter_alt_off' : 'inventory_2'\"")
+        ui.element("span").props(':textContent="props.message"')
+
+    optional_columns = [column for column in table.columns if not column.get("required")]
+
+    def set_visible_columns(names: list[str]) -> None:
+        table.props["visible-columns"] = names
+        table.update()
+
+    ui.select(
+        {column["name"]: column["label"] for column in optional_columns},
+        value=[column["name"] for column in optional_columns],
+        label="Visible columns",
+        multiple=True,
+        clearable=True,
+        on_change=lambda event: set_visible_columns(event.value),
+    ).props("outlined dense options-dense").classes("w-64")
+
+    return table
+
+
+if __name__ in {"__main__", "__mp_main__"}:
+    with ui.column(align_items="center").classes("w-full gap-4 p-4"):
+        render_table()
+
+    ui.run(port=8888, reload=True)

src/personal_mcp/docs/skills/nicegui/references/architecture.md

@@ -70,12 +70,104 @@ Avoid imports from services back into API or UI modules.
 
 ## Page And Component Ownership
 
-Page modules compose routes from presentation components and service calls. They should not own domain rules, persistence, or long-running synchronous work.
+Page modules should be a thin route-level composition layer. A page resolves route inputs and page-scoped dependencies, establishes the page shell, composes reusable components, and wires only the interactions that cross component boundaries. It should not contain a component's internal element tree, field bindings, refresh logic, domain rules, persistence, or long-running synchronous work.
 
-Extract a presentation pattern to `ui/components/` when it appears on two or more pages or owns a meaningful interaction boundary. Keep one-off route composition in the page module. Reusable components should accept data and event callbacks instead of importing page state or business services implicitly.
+Extract a presentation pattern to `ui/components/` when it appears on two or more pages or owns a meaningful state or interaction boundary. Reusable components should accept initial data, use-case functions, and event callbacks explicitly instead of importing page state or business services implicitly.
 
 For page composition, responsive layout, Quasar props, and CSS customization, load [styling and customization](./styling-and-customization.md).
 
+## Reusable Component Contract
+
+In this architecture, a "component" is an application-level composition pattern, not necessarily a custom Vue component or a subclass of NiceGUI `Element`. Its usual shape is:
+
+1. A typed dataclass represents the component's public handle and local UI state.
+2. A render or factory function creates one component instance, builds its element subtree, and binds elements to that instance.
+3. The function returns the instance so its caller can read or change intentional state, invoke public actions, or coordinate it with another component.
+4. Internal elements, event handlers, validation feedback, and refreshable regions remain private to the component unless an imperative element handle is intentionally part of its API.
+
+Use [`binding.bindable_dataclass`](./binding-dataclasses.md) for fields that drive or receive element properties. Plain `@dataclass` is sufficient when the returned object only groups element handles or callbacks and does not need immediate field propagation. Use `bindable_fields` when the dataclass also stores injected dependencies or other fields that should not participate in NiceGUI's binding graph.
+
+```python
+from collections.abc import Awaitable, Callable
+from dataclasses import field
+
+from nicegui import binding, ui
+
+
+Search = Callable[[str], Awaitable[list[str]]]
+
+
+@binding.bindable_dataclass(bindable_fields={"query", "busy", "items"})
+class SearchPanel:
+   search: Search = field(repr=False)
+   query: str = ""
+   busy: bool = False
+   items: list[str] = field(default_factory=list)
+
+   @ui.refreshable_method
+   def render_results(self) -> None:
+      if not self.items:
+         ui.label("No results")
+      for item in self.items:
+         ui.label(item)
+
+   async def submit(self) -> None:
+      if self.busy:
+         return
+      self.busy = True
+      try:
+         self.items = await self.search(self.query)
+         await self.render_results.refresh()
+      finally:
+         self.busy = False
+
+
+def render_search_panel(search: Search) -> SearchPanel:
+   panel = SearchPanel(search=search)
+   with ui.column().classes("w-full gap-3"):
+      ui.input("Search").bind_value(panel, "query")
+      ui.button("Search", on_click=panel.submit).bind_enabled_from(
+         panel,
+         "busy",
+         backward=lambda busy: not busy,
+      )
+      ui.label().bind_text_from(
+         panel,
+         "items",
+         backward=lambda items: f"{len(items)} results",
+      )
+      panel.render_results()
+   return panel
+```
+
+The returned dataclass is the component API. Its bindable fields synchronize stable element properties, while `render_results()` owns a bounded region whose child structure changes with `items`. The injected `search` callable preserves dependency direction: the component can invoke a use case without locating a service globally.
+
+[`@ui.refreshable_method`](https://nicegui.io/documentation/refreshable) is the instance-oriented refresh surface for this pattern. NiceGUI records refresh targets by method instance, allowing each page-created component object to refresh independently. Detailed target, argument, async, and lifecycle behavior is documented under [refreshable component regions](./interaction-patterns.md#refreshable-component-regions).
+
+### Thin Page Example
+
+```python
+from nicegui import ui
+
+from app.services.catalog import search_catalog
+from app.ui.components.search_panel import render_search_panel
+
+
+@ui.page("/catalog")
+def catalog_page() -> None:
+   with ui.column().classes("mx-auto w-full max-w-5xl gap-6"):
+      ui.label("Catalog").classes("text-2xl font-semibold")
+      render_search_panel(search_catalog)
+```
+
+The page owns the route and composition. The component owns its controls, binding graph, feedback state, and structural refresh. The service owns search rules and data access. If two component handles must coordinate, keep the page wiring declarative, such as subscribing one component's public event to another component's public refresh action; move orchestration with domain meaning into a service.
+
+### Component Lifetime
+
+Create component state during each page build unless sharing is deliberate. A module-global component dataclass can leak UI state across clients, and a module-global `@ui.refreshable` function can refresh every recorded target. Do not retain returned handles beyond their owning client without an explicit cleanup and stale-client policy.
+
+Bindings to elements are removed with NiceGUI's element lifecycle. Refreshing a region deletes and recreates the elements inside that region, so external code should retain the component handle rather than private child element references. Component-owned subscriptions, timers, and background tasks must follow the client deletion rules in [interaction mechanics](./interaction-patterns.md#page-and-client-lifetime).
+
 ## Optional Persistence
 
 Use only when the product requires durable data.

src/personal_mcp/docs/skills/nicegui/references/binding-dataclasses.md

@@ -1,16 +1,20 @@
-# Binding Dataclasses Deep Dive
+# Binding Dataclasses
 
-Use this reference to model NiceGUI state with bindable dataclasses and avoid common propagation and performance pitfalls.
+Use this reference to understand how NiceGUI creates binding links, detects changes, propagates values, and applies `forward` and `backward` transforms.
+
+The implementation details and signatures below are verified against NiceGUI `3.16.0`. Check the target project's pinned version before copying version-sensitive behavior.
 
 ## Primary Sources
 
-- NiceGUI binding docs: [binding properties](https://www.nicegui.io/documentation/section_binding_properties)
-- Python dataclass docs: [dataclasses module](https://docs.python.org/3/library/dataclasses.html)
-- Data class design rationale: [PEP 557](https://peps.python.org/pep-0557/)
+- [NiceGUI binding documentation](https://www.nicegui.io/documentation/section_binding_properties): public binding behavior and examples
+- [NiceGUI `binding.py` at `v3.16.0`](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/binding.py): binding graph, propagation, active links, strict checks, and `bindable_dataclass`
+- [NiceGUI `ValueElement` at `v3.16.0`](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/elements/mixins/value_element.py): `bind_value*` signatures and transform direction
+- [Python dataclasses](https://docs.python.org/3/library/dataclasses.html): generated methods, fields, defaults, and mutable-value rules
+- [PEP 557](https://peps.python.org/pep-0557/): dataclass design rationale
 
-## Bindable Dataclass Behavior
+## What `bindable_dataclass` Changes
 
-`@binding.bindable_dataclass` extends standard dataclasses by turning fields into bindable properties, allowing UI bindings to propagate when a field is assigned.
+`@binding.bindable_dataclass` first applies Python's `@dataclass`, then replaces each selected field on the resulting class with a NiceGUI `BindableProperty` descriptor. The descriptor stores the field value privately and intercepts later assignment.
 
 ```python
 from nicegui import binding, ui
@@ -26,24 +30,205 @@ profile = Profile()
 
 ui.input("Name").bind_value(profile, "name")
 ui.number("Age", min=0).bind_value(profile, "age")
-ui.label().bind_text_from(profile, "name", backward=lambda name: f"User: {name}")
+ui.label().bind_text_from(
+    profile,
+    "name",
+    backward=lambda name: f"User: {name}",
+)
 ```
 
-## Propagation And Performance
+Assigning a different value to `profile.name` invokes the descriptor immediately. It records the new value, propagates it through the binding graph, and then runs any descriptor change handler. Assigning an equal value returns without propagation.
 
-NiceGUI distinguishes between two link types:
+By default every dataclass field is bindable. Pass `bindable_fields` to limit descriptor conversion:
 
-- Bindable properties propagate efficiently when values are assigned.
-- Active links are checked in a refresh loop.
+```python
+@binding.bindable_dataclass(bindable_fields={"query", "page_size"})
+class SearchState:
+    query: str = ""
+    page_size: int = 25
+    request_count: int = 0
+```
 
-Prefer bindable dataclasses for frequently updated form state. Keep binding transforms pure and inexpensive. If an application has many active links, tune `binding_refresh_interval` in `ui.run(...)` only after measuring the impact.
+A bound field omitted from `bindable_fields` still works, but NiceGUI must treat it as an active link and poll it for changes.
+
+## Bindable Dataclasses As Component Handles
+
+A reusable NiceGUI component can expose a bindable dataclass as its typed public handle. The component's render function creates the dataclass instance, builds the element subtree, establishes bindings against that instance, and returns it to the page. This keeps the page at the composition level while the component owns its field wiring and internal elements. See the complete [reusable component contract](./architecture.md#reusable-component-contract).
+
+Choose binding direction according to what the public field represents:
+
+| Component field | Typical element relationship | Binding surface |
+| --- | --- | --- |
+| editable value such as `query` | control and component share the value | `element.bind_value(handle, "query")` |
+| rendered status such as `busy` or `count` | component state drives text, visibility, or enabled state | `bind_*_from` with a pure transform when needed |
+| browser proposal requiring validation | event handler validates before assignment | explicit callback, then assign the accepted bindable field |
+| collection controlling child count or layout | component state is read while rebuilding a bounded subtree | `@ui.refreshable_method`, not a binding to the child list itself |
+| injected service or callback | component implementation dependency | ordinary dataclass field omitted from `bindable_fields` |
+
+The returned handle should expose intentional component state and actions, not every child element. Bindable fields are effective for stable element properties because assignments propagate immediately. They do not create or delete elements when collection structure changes; a component-owned refreshable method should rebuild that region after the authoritative field is replaced. The target and instance behavior is defined under [refreshable component regions](./interaction-patterns.md#refreshable-component-regions).
+
+Create one handle during each page build unless shared state is deliberate. A module-global bindable component model propagates across clients that bind to it, just as a module-level refreshable function can own targets from multiple clients.
+
+## Binding Graph And Propagation
+
+NiceGUI stores bindings as directed edges from one object attribute to another. A two-way binding is two one-way edges with transforms in opposite directions.
+
+When an edge is registered, NiceGUI propagates its source immediately. For a two-way binding, it registers and runs the `backward` edge first, then registers the `forward` edge. The model value therefore wins initial synchronization and seeds the control.
+
+After registration, propagation follows these rules:
+
+1. A `BindableProperty` assignment starts propagation immediately when `old_value != new_value`.
+2. NiceGUI walks outgoing edges depth first.
+3. Each object-and-attribute node is visited at most once during that propagation pass, preventing a two-way cycle from running forever.
+4. Each edge transforms the source value, compares it with the target, and only assigns and continues when the values differ.
+
+Since NiceGUI `2.16.0`, this depth-first walk updates each affected node once per pass. Transform functions must not depend on call count or traversal order.
+
+## Authoritative Models And Projections
+
+A bindable dataclass can own canonical page state while plain dictionaries or component properties act as serializable projections. Use a one-way binding from each model field to its projection when browser rendering requires a different container shape:
+
+```python
+from nicegui import binding
+
+
+projection = {"name": profile.name}
+binding.bind_to(
+    profile,
+    "name",
+    projection,
+    "name",
+    other_strict=True,
+)
+```
+
+Assigning `profile.name` then propagates immediately to `projection["name"]`. The projection is transport state, not a second business model; application code should locate and mutate the owning dataclass rather than treating browser-visible dictionaries as authoritative. This distinction is especially useful when one client-side scoped template renders many records and therefore cannot bind to one fixed Python object. The [editable-table pattern](./tables.md) applies it to one row dataclass and one QTable payload per stable row identity.
+
+Browser-originated values still require Python validation before model assignment. Keep editable fields explicit, normalize into domain types, verify permissions and record existence, and only then assign the bindable field. For the client event path that carries such proposals, see [server-authoritative edit proposals](./component-mechanics.md#server-authoritative-edit-proposals).
+
+### Persistence And Rollback
+
+Treat a dataframe, service, or repository as the persistence boundary around the canonical bindable model:
+
+1. validate and normalize the proposed value
+2. remember the previous model value
+3. assign the normalized value so bound projections update
+4. persist the model through the owning adapter, service, or repository
+5. if persistence fails, restore the previous model value before reporting or re-raising the error
+6. refresh the affected component from the resulting projection on both acceptance and rejection
+
+For asynchronous persistence, await the transaction and refresh only after it commits or rolls back. Catch expected validation, conflict, and persistence exceptions separately so the interface can report actionable failures without hiding programming errors. Component-specific refresh APIs and identity rules remain the responsibility of the consuming pattern; for QTable, see [persistence and row refresh](./tables.md#persistence-and-row-refresh).
+
+## Bindable Properties Versus Active Links
+
+| Source | Change detection | Update timing |
+| --- | --- | --- |
+| NiceGUI element property or `BindableProperty` field | descriptor intercepts assignment | immediate |
+| ordinary object attribute or mapping entry | refresh loop compares source and target | next refresh step |
+| tuple path such as `("address", "city")` | the full path is not a single bindable descriptor key | refresh loop unless the owning leaf object is bound directly |
+
+The active-link refresh interval defaults to `0.1` seconds and is configured with `binding_refresh_interval` in `ui.run(...)`. Every refresh applies the transform and compares the result, so polling large collections or running expensive transforms can block the event loop. Tune the interval only after measuring; first reduce active links and transform cost.
+
+## Transform Direction
+
+The names `forward` and `backward` are relative to the element on which `bind_value*` is called:
+
+| API | Source to target | Transform |
+| --- | --- | --- |
+| `element.bind_value_to(model, "field")` | element to model | `forward` |
+| `element.bind_value_from(model, "field")` | model to element | `backward` |
+| `element.bind_value(model, "field")` | both directions | both; `backward` runs first initially |
+
+Each transform adapts the source value before NiceGUI assigns it to the target. The examples below convert between control values and native Python types only to make the two directions easy to observe; they do not prescribe a state-modeling approach.
+
+Keep both functions pure, fast, and valid for every value the source can emit. NiceGUI does not turn transform exceptions into validation messages.
+
+## Example: Observe Both Directions
+
+This example uses [`datetime.date`](https://docs.python.org/3/library/datetime.html#date-objects) and `int` conversions to expose the mechanics. Their different representations make it clear which transform runs as a value crosses each binding edge.
+
+```python
+from dataclasses import field
+from datetime import date
+
+from nicegui import binding, ui
+
+
+@binding.bindable_dataclass
+class ReportFilters:
+    start_on: date = field(default_factory=date.today)
+    page_size: int = 25
+
+
+filters = ReportFilters()
+
+ui.date().bind_value(
+    filters,
+    "start_on",
+    forward=date.fromisoformat,  # control str -> model date
+    backward=date.isoformat,  # model date -> control str
+)
+
+ui.select(
+    options={"10": "10 rows", "25": "25 rows", "50": "50 rows"},
+    label="Page size",
+).bind_value(
+    filters,
+    "page_size",
+    forward=int,  # control str -> model int
+    backward=str,  # model int -> control str
+)
+
+ui.label().bind_text_from(
+    filters,
+    "start_on",
+    backward=lambda value: f"Starting {value:%d %B %Y}",
+)
+```
+
+At binding time, NiceGUI runs `backward` from the model to each control. Later control changes run `forward` toward the model. Assigning a new model value runs `backward` again.
+
+## Example: Follow A Constrained Value
+
+A select and an [`Enum`](https://docs.python.org/3/library/enum.html) provide a second visible representation change. Because the select only emits known values, this example keeps attention on propagation rather than parse failures.
+
+```python
+from enum import Enum
+
+from nicegui import binding, ui
+
+
+class SortOrder(Enum):
+    NEWEST = "newest"
+    OLDEST = "oldest"
+
+
+@binding.bindable_dataclass
+class ResultsState:
+    sort_order: SortOrder = SortOrder.NEWEST
+
+
+state = ResultsState()
+
+ui.select(
+    options={"newest": "Newest first", "oldest": "Oldest first"},
+    label="Sort order",
+).bind_value(
+    state,
+    "sort_order",
+    forward=SortOrder,  # control str -> model SortOrder
+    backward=lambda value: value.value,  # model SortOrder -> control str
+)
+```
+
+The concrete types are incidental. The same graph mechanics apply whenever `forward` and `backward` map two representations.
 
 ## Dataclass Modeling Rules
 
-- Use `field(default_factory=...)` for mutable defaults.
-- Avoid `frozen=True` for models edited by UI controls.
-- Use `slots=True` only after confirming compatibility with inheritance and extension needs.
-- Keep UI-editable fields explicit and typed.
+- Use `field(default_factory=...)` for mutable defaults and time-dependent defaults.
+- NiceGUI `3.16.0` rejects `frozen=True` and `slots=True` in `bindable_dataclass`; both conflict with its descriptor storage model.
+- Keep UI-editable fields explicit and typed. Dataclass annotations describe intent but do not enforce runtime types; the control or transform must produce the right type.
+- Replace collections instead of mutating them in place.
 
 ```python
 from dataclasses import field
@@ -55,28 +240,36 @@ from nicegui import binding
 class Filters:
     query: str = ""
     tags: list[str] = field(default_factory=list)
+
+
+filters = Filters()
+filters.tags = [*filters.tags, "python"]  # unequal assignment propagates
 ```
 
+Calling `filters.tags.append("python")` bypasses the descriptor. Mutating first and then assigning an equal copy also does not propagate because `BindableProperty` compares with `!=` and returns when values are equal.
+
 ## Nested Structures
 
-NiceGUI supports tuple paths for nested data structures.
+Tuple paths support nested mappings and object attributes:
 
 ```python
-from nicegui import ui
-
 data = {"user": {"name": "Ada"}}
 
 ui.input("Name").bind_value(data, ("user", "name"))
 ui.label().bind_text_from(data, ("user", "name"))
 ```
 
-Keep nested dataclass updates explicit and predictable at the field level.
+A tuple path is checked as an active link. When a nested object is itself a bindable dataclass, bind its owning object directly to preserve immediate descriptor-driven propagation:
 
-## Strictness And Refactor Safety
+```python
+ui.input("City").bind_value(profile.address, "city")
+```
 
-- Object attributes are checked by default.
-- Dictionary keys are not checked by default.
-- Use `strict=True` when missing dictionary keys should produce warnings.
+If `profile.address` is replaced later, rebuild that direct binding or bind through the root tuple path and accept active-link polling.
+
+## Strictness And Missing Paths
+
+NiceGUI `3.16.0` checks object attributes by default and does not check mapping keys by default. A failed strict check raises `AttributeError` or `KeyError` while the binding is being created.
 
 ```python
 from nicegui import app, ui
@@ -84,17 +277,23 @@ from nicegui import app, ui
 ui.input().bind_value(app.storage.user, "display_name", strict=True)
 ```
 
+Use `strict=False` for an intentionally lazy object attribute and `strict=True` when a mapping key must already exist. On assignment, NiceGUI can create missing intermediate dictionaries, but it cannot create missing intermediate object attributes.
+
 ## Common Pitfalls
 
-- In-place mutation may not produce immediate UI synchronization. Assign the updated value back to the bound field.
-- Heavy binding transforms can degrade refresh performance. Move expensive work to event handlers or services.
-- State shared across unrelated pages or users can leak data. Scope models to the appropriate page, client, or user context.
+- Do not put logging, I/O, model mutation, notifications, or other side effects in transforms. Propagation order and call count are implementation details.
+- Do not use a transform as the validation boundary for free-form text. A raised parser exception interrupts propagation.
+- Do not mutate a bound collection in place. Construct and assign a different value.
+- Do not assume a nested tuple path gets the same immediate behavior as binding directly to a bindable leaf object.
+- Scope bindable models to the appropriate page, client, or user. A module-global model shares state across users.
+- Remove bindings with NiceGUI's public element lifecycle rather than retaining discarded elements or models indefinitely.
 
 ## Version Checks
 
-- `bindable_dataclass` was added in NiceGUI 2.11.0.
-- Depth-first binding propagation was documented in NiceGUI 2.16.0.
-- Binding `strict` behavior was documented in NiceGUI 3.0.0.
-- Tuple paths for nested properties were documented in NiceGUI 3.10.0.
+- `bindable_dataclass` was added in NiceGUI `2.11.0`.
+- Depth-first binding propagation changed in NiceGUI `2.16.0`.
+- Binding strictness controls were added in NiceGUI `3.0.0`.
+- Tuple paths for nested properties were added in NiceGUI `3.10.0`.
+- NiceGUI `3.16.0` supports `bindable_fields` and rejects `slots=True` and `frozen=True`.
 
-Verify these behaviors against the NiceGUI version pinned by the target project.
+Verify the installed NiceGUI source and documentation when any of these mechanics affect application correctness.

src/personal_mcp/docs/skills/nicegui/references/colors-and-quasar-theming.md

@@ -0,0 +1,189 @@
+# NiceGUI And Quasar Color Theming
+
+This reference describes how NiceGUI's Python color APIs map onto Quasar's browser-side color system. It distinguishes theme configuration from individual element colors, fixed palette colors from runtime brand roles, and palette values from dark-mode state.
+
+The primary public references are [NiceGUI styling and appearance](https://nicegui.io/documentation/section_styling_appearance), [NiceGUI color theming](https://nicegui.io/documentation/colors), and the [Quasar color palette](https://quasar.dev/style/color-palette).
+
+## Boundary At A Glance
+
+NiceGUI does not define an independent component theme engine. It configures and consumes the Quasar color system while adding Python-facing scope, value classification, and CSS cascade behavior.
+
+| Surface | NiceGUI owns | Quasar or the browser owns |
+| --- | --- | --- |
+| `app.colors(...)` | application-wide Python configuration and custom-name registration | initial Quasar brand configuration and the resulting `--q-*` values on each page |
+| `ui.colors(...)` | a page-level element and precedence over `app.colors()` | runtime `--q-*` properties on `document.body` plus custom `text-*` and `bg-*` classes |
+| component `color=` and `text_color=` arguments | classification of supported values as Quasar, Tailwind, or CSS colors on color-aware wrappers | rendering through a Quasar prop, a utility class, or an inline CSS declaration |
+| `.props("color=...")` | transport of the prop to the frontend component | interpretation of the value by that Quasar component |
+| `.classes("text-primary bg-positive")` | attachment of class names and NiceGUI's CSS layer arrangement | Quasar's semantic utility classes and their `--q-*` variable references |
+| `ui.dark_mode(...)` | Python control and binding with `True`, `False`, or automatic `None` state | Quasar dark-mode state, `body--light` or `body--dark`, and dark-aware components |
+
+The central handoff is a CSS custom property. NiceGUI supplies a value such as `#176b5b`; Quasar components and helpers consume `var(--q-primary)`.
+
+## Quasar Color Namespaces
+
+Quasar exposes two materially different kinds of color name. Only one kind is changed by NiceGUI's theme APIs.
+
+### Runtime Brand Roles
+
+Quasar's semantic brand roles are backed by root or body-level CSS custom properties. Components and semantic utility classes follow these values at runtime. NiceGUI exposes the eight Quasar brand roles and the separate dark-page surface through `app.colors()` and `ui.colors()`.
+
+| NiceGUI argument | CSS custom property | NiceGUI default | Intended meaning |
+| --- | --- | --- | --- |
+| `primary` | `--q-primary` | `#5898d4` | main action and brand emphasis |
+| `secondary` | `--q-secondary` | `#26a69a` | secondary brand emphasis |
+| `accent` | `--q-accent` | `#9c27b0` | accent emphasis |
+| `dark` | `--q-dark` | `#1d1d1d` | dark component surface |
+| `dark_page` | `--q-dark-page` | `#121212` | dark page background |
+| `positive` | `--q-positive` | `#21ba45` | success state |
+| `negative` | `--q-negative` | `#c10015` | error or destructive state |
+| `info` | `--q-info` | `#31ccec` | informational state |
+| `warning` | `--q-warning` | `#f2c037` | warning state |
+
+For example, `color="primary"`, `.props("color=primary")`, `text-primary`, and `bg-primary` all reach Quasar's semantic primary role. Changing that role changes every consumer of `--q-primary`; it does not rewrite fixed palette colors.
+
+```python
+from nicegui import app, ui
+
+app.colors(
+    primary="#176b5b",
+    secondary="#52645f",
+    accent="#c05a32",
+    positive="#2e7d32",
+    negative="#b3261e",
+    info="#276b8e",
+    warning="#a86600",
+    dark="#202523",
+    dark_page="#151917",
+)
+
+ui.button("Save")
+ui.label("Saved").classes("text-positive")
+```
+
+The current NiceGUI client implementation writes page-level values to `document.body` in [`colors.js`](https://github.com/zauberzeug/nicegui/blob/main/nicegui/elements/colors.js). Quasar's semantic helpers reference those properties, as described under [dynamic brand colors](https://quasar.dev/style/color-palette#dynamic-change-of-brand-colors-dynamic-theme-colors).
+
+### Fixed Palette Colors
+
+Names such as `red-5`, `teal-10`, and `blue-grey-2` belong to Quasar's compiled [color list](https://quasar.dev/style/color-palette#color-list). Their `text-*` and `bg-*` classes contain fixed color values rather than references to the semantic brand variables.
+
+Consequently:
+
+- `ui.colors(primary="#0057b8")` changes `primary`, `text-primary`, and `bg-primary` consumers.
+- It does not change `blue`, `blue-6`, `text-blue-6`, or `bg-blue-6`.
+- A fixed palette color can be assigned to a component, for example `ui.button("Open", color="teal-7")`, without adding it to the application theme.
+
+The fixed palette is a Quasar facility bundled into NiceGUI. It is not generated by `app.colors()` or `ui.colors()`.
+
+### Custom Semantic Names
+
+Extra keyword arguments create application-specific names:
+
+```python
+from nicegui import app, ui
+
+app.colors(brand="#176b5b", review_required="#a86600")
+
+ui.button("Continue", color="brand")
+ui.label("Review required").classes("text-review-required")
+```
+
+NiceGUI normalizes underscores in Python keyword names to hyphens in browser color names. For each custom name, the client-side [`applyColors`](https://github.com/zauberzeug/nicegui/blob/main/nicegui/static/nicegui.js) helper creates:
+
+- a `--q-<name>` property on `document.body`
+- a `.text-<name>` class that reads that property
+- a `.bg-<name>` class that reads that property
+
+This automates the custom-class pattern shown in Quasar's [adding your own colors](https://quasar.dev/style/color-palette#adding-your-own-colors) reference. NiceGUI also registers the name in its Python-side Quasar color set so color-aware wrappers pass the value as a Quasar color prop. The name must therefore be declared with `app.colors()` or `ui.colors()` before a NiceGUI component first uses it; this ordering requirement is part of the [NiceGUI custom colors contract](https://nicegui.io/documentation/colors#custom_colors).
+
+## Scope And Precedence
+
+The effective palette has three levels:
+
+| Level | Scope | Effect |
+| --- | --- | --- |
+| bundled Quasar values | every page | fallback values supplied by Quasar's CSS |
+| `app.colors(...)` | all NiceGUI pages | populates NiceGUI's Quasar brand configuration before each client app starts |
+| `ui.colors(...)` | current page | writes the core and custom properties on that page's `document.body` and takes precedence over app-wide values |
+
+`app.colors()` is configuration, not a rendered UI element. NiceGUI stores its values in the application's Quasar configuration; see the current [`App.colors` implementation](https://github.com/zauberzeug/nicegui/blob/main/nicegui/app/app.py).
+
+`ui.colors()` is rendered into a specific page. Its DOM placement in a row, card, or other container does not scope the palette to that subtree because its client component writes to `document.body`. A page with two calls therefore has one effective page palette, with the last mounted call determining the core values. Subtree-specific theming requires application CSS variables or directly scoped `--q-*` overrides, not nested `ui.colors()` elements.
+
+The `ui.colors()` initializer supplies all nine core values. A call such as `ui.colors(primary="#555")` is therefore a complete core-palette assignment: unspecified roles resolve to NiceGUI's defaults rather than acting as a one-property patch over `app.colors()`. Pages that must retain customized app-wide secondary, status, or dark values should pass those values explicitly in the page override.
+
+`app.colors()` was added in NiceGUI 3.6.0, while custom colors were added to `ui.colors()` in 2.2.0. Applications pinned to earlier NiceGUI releases need version-matched behavior from the [NiceGUI colors reference](https://nicegui.io/documentation/colors).
+
+## Element Color Values
+
+On elements implemented with NiceGUI's color mixins, a `color`, `text_color`, or corresponding setter value is classified in this order by [`color_elements.py`](https://github.com/zauberzeug/nicegui/blob/main/nicegui/elements/mixins/color_elements.py):
+
+| Input kind | Example | NiceGUI output | Theme response |
+| --- | --- | --- | --- |
+| Quasar semantic, fixed, or registered custom name | `primary`, `red-5`, `brand` | Quasar component color prop | semantic and custom names follow `--q-*`; fixed names do not |
+| recognized Tailwind color | `red-500` | `bg-red-500` or `text-red-500` class | independent of the Quasar palette |
+| other CSS color value | `#ff0000`, `rgb(255 0 0)`, `rebeccapurple` | inline `background-color` or `color` | independent of the Quasar palette |
+| `None` | `None` | removes the managed color | falls back to component and cascade defaults |
+
+This classification is a NiceGUI convenience, not a general Quasar rule. Passing `.props("color=#ff0000")` bypasses NiceGUI's color mixin and asks the Quasar component to interpret `#ff0000` as its `color` prop. Likewise, components that expose a raw Quasar color prop without using the mixin may accept only the values documented by that component. The specific NiceGUI constructor documentation remains authoritative for each element.
+
+Quasar and Tailwind color classes share the same HTML class list but not the same namespace conventions. `text-red-5` is a Quasar fixed-palette helper; `text-red-500` is a Tailwind-compatible utility. Semantic names such as `text-primary` are Quasar helpers.
+
+## Palette Values And Dark Mode Are Separate
+
+The `dark` and `dark_page` arguments define colors; they do not enable dark mode. Mode state is controlled by [`ui.dark_mode()`](https://nicegui.io/documentation/dark_mode), the `dark` argument of `ui.run()`, or a page decorator. `ui.dark_mode()` takes precedence for its page and maps `None` to Quasar's automatic system-preference mode.
+
+When dark mode is active, Quasar:
+
+- applies `body--dark` instead of `body--light`
+- uses the dark page background and dark-aware component behavior
+- automatically enables the dark state of Quasar components that support a `dark` prop
+
+These behaviors are defined by [Quasar dark mode](https://quasar.dev/style/dark-mode). Application-owned surfaces can key off the same body class and reuse Quasar variables:
+
+```css
+:root {
+    --app-surface: #ffffff;
+    --app-text: #202623;
+}
+
+.body--dark {
+    --app-surface: var(--q-dark);
+    --app-text: #eef3f0;
+}
+```
+
+Changing `--q-dark` while the page remains in light mode changes consumers of the `dark` role but does not add `body--dark`. Enabling dark mode without designing application-specific text, border, and surface tokens does not automatically recolor arbitrary custom CSS.
+
+## CSS Classes And Cascade
+
+NiceGUI ships Quasar's color helpers, so `.classes("text-primary")` and `.classes("bg-warning")` can be attached directly to NiceGUI elements. Quasar defines these helpers with `!important`.
+
+NiceGUI changes the cascade arrangement around the bundled Quasar CSS. Its [CSS layer reference](https://nicegui.io/documentation/section_styling_appearance#css_layers) explains how Quasar rules are split into layers so important Tailwind utilities or application rules in suitable layers can override them. This is a NiceGUI integration detail; the class names and color semantics still come from Quasar.
+
+Direct CSS can consume the same semantic properties without a Quasar class:
+
+```css
+.app-focus-ring {
+    outline: 2px solid var(--q-primary);
+}
+```
+
+Such CSS follows runtime palette changes because it reads the same property. A literal declaration such as `outline-color: #176b5b` does not.
+
+## Source Index
+
+!!! info "Primary sources"
+    - [NiceGUI styling and appearance](https://nicegui.io/documentation/section_styling_appearance)
+    - [NiceGUI color theming](https://nicegui.io/documentation/colors)
+    - [NiceGUI dark mode](https://nicegui.io/documentation/dark_mode)
+    - [Quasar color palette](https://quasar.dev/style/color-palette)
+    - [Quasar dark mode](https://quasar.dev/style/dark-mode)
+    - [Quasar theme builder](https://quasar.dev/style/theme-builder)
+
+!!! info "Implementation references"
+    - [NiceGUI app-wide color configuration](https://github.com/zauberzeug/nicegui/blob/main/nicegui/app/app.py)
+    - [NiceGUI page color element](https://github.com/zauberzeug/nicegui/blob/main/nicegui/elements/colors.py)
+    - [NiceGUI page color client component](https://github.com/zauberzeug/nicegui/blob/main/nicegui/elements/colors.js)
+    - [NiceGUI custom color CSS generation](https://github.com/zauberzeug/nicegui/blob/main/nicegui/static/nicegui.js)
+    - [NiceGUI element color classification](https://github.com/zauberzeug/nicegui/blob/main/nicegui/elements/mixins/color_elements.py)
+    - [NiceGUI color behavior tests](https://github.com/zauberzeug/nicegui/blob/main/tests/test_colors.py)

src/personal_mcp/docs/skills/nicegui/references/component-mechanics.md

@@ -1,6 +1,247 @@
 # NiceGUI Component Mechanics
 
-Use this reference to understand how customization crosses the NiceGUI Python wrapper, Quasar component, Vue runtime, and browser DOM. It owns constructor behavior, prop translation, events, bindings, slots, frontend methods, detached content, and component-specific caveats. For themes, utility classes, CSS properties, responsive page composition, and other cosmetic work, load [visual styling and CSS](./styling-and-customization.md).
+NiceGUI components are Python objects that describe browser UI elements. A component constructor creates an element, constructor arguments configure its common behavior, and methods on the returned object expose styling, events, bindings, slots, and client-side capabilities.
+
+This reference begins with those everyday component APIs, then describes the NiceGUI, Quasar, Vue, and browser layers beneath them. Page structure, typography, responsive composition, and scaling are covered separately in [styling and customization](./styling-and-customization.md).
+
+## Basic Components
+
+Components are created from the `ui` namespace. Layout components are context managers, so nested Python blocks describe the element hierarchy:
+
+```python
+from nicegui import ui
+
+with ui.column().classes("gap-3"):
+    name = ui.input("Name", placeholder="Ada")
+    role = ui.select(
+        options={"admin": "Administrator", "reader": "Reader"},
+        value="reader",
+        label="Role",
+    ).props("outlined dense")
+    ui.button("Save", on_click=lambda: ui.notify(f"Saved {name.value}"))
+```
+
+The [NiceGUI component documentation](https://nicegui.io/documentation) is the index of available `ui.*` constructors. Each component page documents its Python parameters, values, callbacks, methods, and examples. The implementation for each wrapper is available in the [NiceGUI element source tree](https://github.com/zauberzeug/nicegui/tree/main/nicegui/elements).
+
+## Common Component Mechanics
+
+Most NiceGUI elements inherit a common set of mechanics from `Element`; individual wrappers add component-specific properties and methods.
+
+| Surface | What it represents | Source of supported values |
+| --- | --- | --- |
+| Constructor arguments | NiceGUI's typed, Python-facing API for initial content, values, callbacks, validation, and common behavior | the component's page in the [NiceGUI component documentation](https://nicegui.io/documentation) and its wrapper in the [NiceGUI element source tree](https://github.com/zauberzeug/nicegui/tree/main/nicegui/elements) |
+| Properties such as `.value` and `.options` | Python-side component state maintained by a particular wrapper | the component documentation and wrapper source; these properties are not universal `Element` APIs |
+| Wrapper methods such as `set_options()` | NiceGUI state transitions that normalize Python data and schedule a client update | the component documentation and wrapper source |
+| `.props(...)` | Quasar component props, Vue bindings, or HTML attributes serialized onto the frontend element | the API section of the wrapped component in the [Quasar component documentation](https://quasar.dev/vue-components); [NiceGUI element customization](https://nicegui.io/documentation/element) defines the bridge syntax |
+| `.classes(...)` | CSS class names attached to the element | [Tailwind's utility documentation](https://tailwindcss.com/docs) for Tailwind classes; Quasar's [breakpoint](https://quasar.dev/style/breakpoints), [spacing](https://quasar.dev/style/spacing), [visibility](https://quasar.dev/style/visibility), and [helper-class](https://quasar.dev/style/other-helper-classes) references for Quasar classes; or the application's own stylesheets for custom classes |
+| `.style(...)` | Inline CSS declarations attached to the element | the [MDN CSS reference](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference) |
+| Constructor callbacks and `.on(...)` | NiceGUI callbacks and forwarded browser or Quasar events | the component's NiceGUI page first, then the Events section of its Quasar API; [NiceGUI generic events](https://nicegui.io/documentation/generic_events) documents `.on(...)` |
+| `on_*` methods | Named event conveniences implemented by a specific NiceGUI wrapper, such as `on_value_change` | the component documentation and wrapper source; there is no universal list that applies to every component |
+| `bind_*` methods | synchronization between element properties and Python model properties | [NiceGUI binding documentation](https://nicegui.io/documentation/section_binding_properties) and the wrapper's documented bindable properties |
+| `add_slot(...)` | content inserted into a Quasar or Vue named slot | the Slots and Scoped Slots sections of the wrapped component's Quasar API |
+| `run_method(...)` | invocation of a public method on the client component | the Methods section of the wrapped component's Quasar API |
+
+### Options And Values
+
+`options` is component state rather than a universal styling mechanism. Components such as `ui.select`, `ui.radio`, `ui.toggle`, and `ui.table` define their own accepted option shapes and value semantics. For example, NiceGUI's [`ui.select` documentation](https://nicegui.io/documentation/select) describes list and dictionary options, while the [`Select` wrapper source](https://github.com/zauberzeug/nicegui/blob/main/nicegui/elements/select.py) shows how those Python values are normalized for Quasar.
+
+Reading `element.options` accesses the wrapper's current Python-side options. Assigning or mutating options only changes browser state when the wrapper detects or sends an update. Component helpers such as `set_options()` encode that synchronization behavior and therefore belong to the wrapper's API rather than to Quasar's raw `options` prop.
+
+### Props
+
+`.props()` writes props onto the frontend component:
+
+```python
+ui.button("Archive").props("outline color=negative")
+ui.select(["A", "B"]).props("dense options-dense")
+```
+
+For NiceGUI elements backed by Quasar, supported names and values come from the wrapped Quasar component's API. For example, the full [`QSelect` API](https://quasar.dev/vue-components/select#qselect-api) lists `dense`, `options-dense`, `popup-content-class`, events, slots, and methods. NiceGUI may already expose some of those features as typed constructor arguments or wrapper methods; the NiceGUI component page and source describe that higher-level behavior.
+
+#### Property-String Format
+
+NiceGUI's `.props()` string is parsed on the Python side by the tagged [`Props.parse()` implementation](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/props.py). It accepts whitespace-delimited tokens in these forms:
+
+| Form | Python-side result | Frontend meaning |
+| --- | --- | --- |
+| `dense` | `{"dense": True}` | a true boolean prop |
+| `label=Chair` | `{"label": "Chair"}` | a static string prop |
+| `offset=[8, 8]` | `{"offset": [8, 8]}` | a Python literal serialized as a value |
+| `:label=someExpression` | `{":label": "someExpression"}` | a JavaScript expression evaluated in the browser |
+
+Quoted strings and bracketed or braced literals are parsed with Python's `ast.literal_eval`; unquoted values remain strings. Quote an expression when it contains whitespace or characters outside NiceGUI's unquoted-value grammar, or assign it through `element.props[":name"]` to avoid the string parser. Regular HTML attributes can pass through the same mechanism where the rendered element supports them. The [NiceGUI element documentation](https://nicegui.io/documentation/element) defines the public bridge syntax.
+
+#### Dynamic Props And Vue Bindings
+
+The leading colon borrows Vue's [`v-bind` shorthand](https://vuejs.org/api/built-in-directives.html#v-bind), but NiceGUI elements are created with Vue's `h()` render function rather than compiled from a template. NiceGUI's tagged [`renderRecursively()` implementation](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/static/nicegui.js) removes the colon, evaluates the value as JavaScript, and passes the result in the vnode's props object. For example:
+
+```python
+ui.badge().props(':color="window.innerWidth < 600 ? \'primary\' : \'grey\'"')
+```
+
+corresponds conceptually to this Vue template:
+
+```vue
+<q-badge :color="window.innerWidth < 600 ? 'primary' : 'grey'" />
+```
+
+The right-hand side is JavaScript, not Python. It may read browser globals, call functions, or construct arrays and objects, provided the receiving HTML element or Vue component accepts the resulting property. Inside a scoped slot, NiceGUI additionally makes that slot's current scope object available under the name `props`; outside a scoped slot, that name has no slot object to reference.
+
+There is one important render-function distinction. Vue template syntax allows argument-less `v-bind="object"` to spread every key in an object. A literal `.props("v-bind=someObject")` token is not compiled as a directive by NiceGUI's render-function path and does not spread the object. Use a raw `add_slot(..., template=...)` Vue template when a slot contract requires whole-object binding, or bind the documented fields individually. Vue's [render-function reference](https://vuejs.org/guide/extras/render-function.html#creating-vnodes) defines the equivalent programmatic form as passing or spreading those keys in the object supplied to `h()`.
+
+#### Controlled Values And Model Events
+
+Vue component `v-model` expands to a value prop plus an update listener. For the common `modelValue` contract, that means `modelValue` and `update:modelValue`, as defined by the [Vue component `v-model` guide](https://vuejs.org/guide/components/v-model.html) and its tagged [compiler transform](https://github.com/vuejs/core/blob/v3.5.22/packages/compiler-core/src/transforms/vModel.ts).
+
+NiceGUI can express a deliberately one-way controlled value with a dynamic prop and handle the corresponding proposal separately. For example, `ui.number` follows QInput's common `modelValue` contract:
+
+```python
+number_editor = ui.number()
+number_editor.props(':model-value="props.value"').on(
+    "update:model-value",
+    handler=apply_proposal,
+    js_handler="(value) => emit(value)",
+)
+```
+
+This pattern is useful inside a scoped slot or whenever Python must authorize a change before reasserting component state. The dynamic prop displays the current client-side projection; the listener sends an edit proposal to Python instead of assigning into the source object in JavaScript. Use an ordinary NiceGUI value binding when the wrapper's two-way value model already matches the requirement.
+
+##### `ui.input` Wrapper Exception
+
+In NiceGUI `3.16.0`, `ui.input` is a NiceGUI client wrapper around QInput rather than a direct QInput element. The tagged [`input.js` component](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/elements/input.js) defines its controlled prop and event as `value` and `update:value`, not `model-value` and `update:model-value`. It also adds a static empty `value` prop. Remove that prop before adding a row-scoped dynamic value:
+
+```python
+name_input = ui.input().props(remove="value")
+name_input.props(':value="props.value"').on(
+    "update:value",
+    handler=apply_proposal,
+    js_handler="(value) => emit(value)",
+)
+```
+
+Using `:model-value="props.value"` leaves this wrapper's own `value` unchanged, so repeated text inputs in a scoped table slot render blank. `ui.number` is a direct QInput specialization and therefore uses `model-value` and `update:model-value` as shown above. Check each NiceGUI wrapper's `VALUE_PROP` and client component before assuming the underlying Quasar model contract is exposed unchanged.
+
+An `update:model-value` listener receives the component's emitted model value, whose shape is component-specific. A custom listener also bypasses normalization that a wrapper's built-in value handler may perform. For example, the Quasar input beneath `ui.number` can emit numeric text, so the Python proposal handler must perform authoritative numeric conversion.
+
+NiceGUI serializes `ui.select` options into QSelect objects shaped like `{value: index, label: option_label}` and normally maps the selected object back to the corresponding Python option. A custom `js_handler` receives that object before NiceGUI's Python-side conversion. When list values and labels are intentionally identical, forward `option.label`; otherwise emit the index and resolve it against the authoritative Python options rather than trusting a browser-supplied label.
+
+### Classes And Styles
+
+`.classes()` adds class names to the rendered element:
+
+```python
+ui.label("Account").classes("text-lg font-semibold text-slate-800")
+ui.row().classes("w-full items-center gap-4")
+```
+
+NiceGUI includes Tailwind-compatible utility styling, so names such as `flex`, `gap-4`, `w-full`, and `text-slate-800` are defined by Tailwind. The complete categorized list is the [Tailwind CSS documentation](https://tailwindcss.com/docs); its [utility-class guide](https://tailwindcss.com/docs/styling-with-utility-classes) explains variants, responsive prefixes, and arbitrary values. NiceGUI can alternatively run with a selected UnoCSS preset, whose compatibility limits are documented under [NiceGUI's UnoCSS engine](https://nicegui.io/documentation/section_styling_appearance#unocss_engine).
+
+Quasar publishes its classes by category rather than through a single style index. The [breakpoint reference](https://quasar.dev/style/breakpoints) defines viewport thresholds, the [spacing reference](https://quasar.dev/style/spacing) lists the `q-p*` and `q-m*` permutations, the [visibility reference](https://quasar.dev/style/visibility) covers responsive and platform visibility, and the [other helper classes reference](https://quasar.dev/style/other-helper-classes) covers pointer, scrolling, sizing, rotation, and border helpers. Application-defined class names are supported when their CSS is loaded with `ui.add_css`, static assets, or page head content. `.style()` accepts CSS declarations directly, separated by semicolons.
+
+### Events And `on_*` Methods
+
+Callbacks supplied by a constructor are NiceGUI's documented event surface:
+
+```python
+ui.input("Search", on_change=lambda event: print(event.value))
+ui.button("Refresh", on_click=lambda: print("refresh"))
+```
+
+Some wrappers also expose named registration methods such as `on_value_change`. Their availability and event argument type are component-specific and are documented on the NiceGUI component page or in its wrapper source.
+
+`.on()` is the generic event bridge for events without a dedicated Python convenience API:
+
+```python
+field = ui.select(["A", "B"])
+field.on("popup-show", lambda: print("opened"))
+```
+
+For Quasar-backed elements, the component API's Events section is the authoritative list of emitted event names and payloads. Native browser events are documented in the [MDN event reference](https://developer.mozilla.org/en-US/docs/Web/Events). NiceGUI's [generic event documentation](https://nicegui.io/documentation/generic_events) defines the public `.on()` API.
+
+#### Mapping Quasar Event Names
+
+Quasar documents each component event under its **Events** API entry. Use the documented kebab-case name with `.on()`. NiceGUI's tagged [`event_type_to_camel_case()` helper](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/helpers/strings.py) converts the event name before the first modifier dot to the camelCase form emitted by the component; its frontend renderer then creates Vue's `onXxx` listener prop. These forms therefore map to the same event path:
+
+| Quasar API name | NiceGUI registration | Vue runtime listener |
+| --- | --- | --- |
+| `popup-show` | `.on("popup-show", ...)` | `onPopupShow` |
+| `input-value` | `.on("input-value", ...)` | `onInputValue` |
+| `update:model-value` | `.on("update:model-value", ...)` | `onUpdate:modelValue` |
+
+Vue component events are notifications emitted by the direct component; unlike DOM events, they do not bubble through component ancestors. Prefer a NiceGUI constructor callback, binding, or named wrapper method when one already owns the same behavior. In particular, use `on_change` or a value binding instead of registering another `update:model-value` listener unless the lower-level model event is specifically required.
+
+#### Reading Event Payloads
+
+The Quasar event's documented `params` define the positional arguments received by the listener. NiceGUI serializes those arguments and exposes them as `GenericEventArguments.args` in Python. If exactly one argument is emitted, NiceGUI presents that value directly; multiple emitted arguments remain a list in their documented order.
+
+For example, the version-matched [`QSelect` event API](https://github.com/quasarframework/quasar/blob/quasar-v2.18.5/ui/src/components/select/QSelect.json) defines `add` as one details object containing `index` and `value`:
+
+```python
+def handle_add(event) -> None:
+    print(event.args["index"], event.args["value"])
+
+item_select.on("add", handle_add, args=["index", "value"])
+```
+
+The `args` parameter controls transport, not Quasar's event signature:
+
+| `args` value | Data sent to Python |
+| --- | --- |
+| `None` | all JSON-serializable attributes of every emitted argument |
+| `[]` | no event arguments |
+| `["index", "value"]` | only those attributes from a one-object event argument |
+| `[[], ["name"], None]` | for a three-argument event: none from the first, `name` from the second, and all of the third |
+
+Primitive values and arrays are forwarded as values rather than filtered by attribute name. Browser objects, DOM nodes, component references, functions, and cyclic structures are not meaningful server payloads; select the small serializable subset the Python handler actually needs.
+
+#### Transforming Events In The Browser
+
+`js_handler` receives the original Quasar or browser event arguments in the browser. Calling NiceGUI's injected `emit(...)` forwards only the transformed arguments to the Python `handler`:
+
+```python
+item_select.on(
+    "add",
+    handler=lambda event: print(event.args),
+    js_handler="(details) => emit({index: details.index, value: details.value})",
+)
+```
+
+Omit the Python handler for a client-only action, or omit `js_handler` to use NiceGUI's default `(...args) => emit(...args)` forwarding behavior. Since NiceGUI `2.18.0`, both can be supplied together. A `js_handler` may also decide not to call `emit`, in which case no Python callback runs for that occurrence.
+
+Events that pass imperative JavaScript callbacks require special care. For example, QSelect's `filter` event emits an input string plus `doneFn` and `abortFn` functions. Those functions cannot be serialized for later use by Python. Use NiceGUI's wrapper-supported filtering API, or consume such callbacks synchronously in browser-side JavaScript; do not treat them as ordinary server payloads.
+
+#### Server-Authoritative Edit Proposals
+
+Treat values received from the browser as proposals, even when Quasar validation or input constraints have already run. Attach the listener to the component that emits the event, use `js_handler` to send only the identity and serializable values Python needs, and validate the field allowlist, types, ranges, permissions, record existence, and persistence constraints in Python. The browser may keep temporary editor state, but it is not the source of truth.
+
+Choose when proposals cross the client-server boundary according to the interaction:
+
+- Use `update:model-value` for discrete editors such as selects, switches, and checkboxes.
+- For text and numeric inputs accepted during typing, use the component's documented `debounce` prop to avoid a server round trip for every keystroke.
+- For an explicit save/cancel workflow, keep a local draft in a dialog or popup and emit one proposal on save.
+- During asynchronous persistence, disable the editor or expose a busy state. Add an entity version or another optimistic-concurrency check when multiple clients can edit the same record.
+
+After validation, pass accepted values to the authoritative model and persistence boundary. See [bindable dataclasses](./binding-dataclasses.md#authoritative-models-and-projections) for projection, rollback, and refresh mechanics, and [editable tables](./tables.md) for the QTable-specific form of this pattern.
+
+#### Modifiers And High-Frequency Events
+
+Dot suffixes use Vue's [event and key modifier rules](https://vuejs.org/guide/essentials/event-handling.html#event-modifiers):
+
+```python
+field.on("keydown.enter", submit)
+field.on("click.stop", handle_click)
+viewport.on("scroll.passive", handle_scroll, throttle=0.1)
+```
+
+NiceGUI separates listener options such as `capture`, `once`, and `passive`, event modifiers such as `stop`, `prevent`, and `self`, and key filters such as `enter`. The tagged [`EventListener.to_dict()` implementation](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/event_listener.py) performs that classification before the frontend applies Vue's `withModifiers()` and `withKeys()` helpers. `throttle`, `leading_events`, and `trailing_events` regulate messages sent to Python; they do not throttle a client-only `js_handler` that never calls `emit`.
+
+### Custom Vue Components
+
+When NiceGUI's wrappers and the documented Quasar extension points cannot express a component, subclass `ui.element` and pair it with a Vue component. Start from NiceGUI's [custom Vue component example](https://github.com/zauberzeug/nicegui/tree/main/examples/custom_vue_component), keeping Python responsible for the server-facing state and event contract.
+
+For a component with npm dependencies, bundle the frontend module and pass its ESM module name and bundled file path through the `esm` parameter on the Python element subclass. NiceGUI adds that module to the page import map. The [signature pad example](https://github.com/zauberzeug/nicegui/tree/main/examples/signature_pad) and [node module integration example](https://github.com/zauberzeug/nicegui/tree/main/examples/node_module_integration) demonstrate the package and bundling boundary.
+
+Treat the generated JavaScript and CSS as package data in executable builds. PyInstaller or Nuitka configuration must include those assets, and the packaged artifact must be checked for successful module loading rather than only for process startup. Do not introduce a custom Vue component merely to avoid a supported NiceGUI constructor, Quasar prop, event, slot, or public method.
 
 ## Framework Boundary Model
 
@@ -15,9 +256,7 @@ A NiceGUI component is not a Python-rendered HTML fragment. Customization passes
 
 Treat the generated DOM beneath a Quasar component as private implementation detail. Work through the highest owning layer that expresses the requirement.
 
-## How The APIs Map
-
-Use this map after confirming the exact API against the installed NiceGUI and bundled Quasar versions:
+## API Mapping Across Layers
 
 | Requirement | NiceGUI surface | Underlying mechanic |
 | --- | --- | --- |
@@ -28,7 +267,7 @@ Use this map after confirming the exact API against the installed NiceGUI and bu
 | Imperative frontend action | a NiceGUI helper or `run_method(...)` | NiceGUI invokes a public method on the client component |
 | Page placement or appearance | `.classes(...)`, `.style(...)`, or an application stylesheet | CSS applies to the rendered element; detached content needs its own class hook |
 
-Do not copy a Vue template into Python. Translate each part according to its owner: constructor data stays in Python, Quasar props go through `.props()`, emitted events go through callbacks or `.on()`, and named Vue slots go through NiceGUI's slot API.
+Constructor data remains in Python, Quasar props cross through `.props()`, emitted events cross through callbacks or `.on()`, and named Vue slots cross through NiceGUI's slot API. A Vue example in the Quasar documentation therefore maps to several distinct NiceGUI surfaces rather than to one copied template.
 
 ## State And Event Flow
 
@@ -40,48 +279,28 @@ Server-driven changes and user-driven changes cross a client-server boundary:
 4. NiceGUI forwards registered events to Python handlers.
 5. Python mutations return through bindings, wrapper helpers, or an explicit `update()`.
 
-Use wrapper helpers and bindings when available because they preserve NiceGUI's value model. Directly changing a Python collection or constructing a raw JavaScript object does not imply that the client receives the change.
+Wrapper helpers and bindings preserve NiceGUI's value model and schedule the corresponding client update. Directly changing a plain Python collection or constructing a raw JavaScript object does not itself imply that the client receives the change.
 
 ## Detached Content And Assets
 
-Some Quasar components render menus, dialogs, tooltips, and similar content outside the field or trigger's DOM subtree. A descendant CSS selector beneath the Python-created element will not reach that content. Use the component's documented popup or content class prop, then style that application-owned class separately.
+Some Quasar components render menus, dialogs, tooltips, and similar content outside the field or trigger's DOM subtree. A descendant CSS selector beneath the Python-created element will not reach that content. Component APIs expose props such as `popup-content-class` for assigning a separate class hook to detached content.
 
 Icons and other externally defined visuals add another boundary: a valid Quasar icon name identifies an asset but does not load its font or stylesheet. Confirm both the naming convention and the application-level asset registration.
 
-## Component Customization Workflow
+## Versioned Sources
 
-Research the target component before generating code or CSS. Do not rely on a remembered NiceGUI or Quasar API, and do not mix source versions.
+The exact public surface depends on both the installed NiceGUI version and the Quasar version bundled with it. NiceGUI's tagged `package.json` records that pairing. The component details below describe NiceGUI `3.16.0` with Quasar `2.18.5`, as declared by [NiceGUI `v3.16.0` frontend dependencies](https://github.com/zauberzeug/nicegui/blob/v3.16.0/package.json).
 
-### Establish The Version Pair
+Four source levels answer different questions:
 
-1. Read the target project's lockfile or installed package metadata to identify its exact NiceGUI version.
-2. Open `package.json` at that NiceGUI tag and read the exact `quasar` dependency version.
-3. Use the NiceGUI tag for both NiceGUI sources and the matching `quasar-v<version>` tag for both Quasar sources.
+| Source | Information it defines |
+| --- | --- |
+| NiceGUI component documentation | documented Python constructors, callbacks, methods, and examples |
+| NiceGUI wrapper source at the installed tag | normalization, validation, stored properties, bindings, updates, and the wrapped frontend component |
+| Quasar component API at the bundled tag | accepted props, emitted events, named slots, public methods, accessibility behavior, and warnings |
+| Quasar component source at the bundled tag | detailed runtime behavior behind that public API |
 
-The curated component sections below use NiceGUI `3.16.0` and Quasar `2.18.5`. The pairing comes from [NiceGUI `v3.16.0` frontend dependencies](https://github.com/zauberzeug/nicegui/blob/v3.16.0/package.json). Repeat the version check when the target application uses another NiceGUI release. Never infer compatibility from Quasar's latest release or use NiceGUI `main` with Quasar `dev`.
-
-### Research Four Sources
-
-Review these sources in order for the selected version pair:
-
-1. **NiceGUI documentation:** identify the supported Python API and documented examples for the component.
-2. **NiceGUI source code:** inspect constructor normalization, validation, props, bindings, events, helpers, and the wrapped frontend component.
-3. **Quasar documentation:** identify the wrapped component's public props, slots, events, methods, accessibility behavior, and documented warnings.
-4. **Quasar source code:** verify how those public APIs behave, especially popup mounting, model translation, event flow, rendering, and public methods.
-
-Use current upstream sources only when the target version is unavailable, and state that fallback explicitly. If the installed package differs from its tag, follow the installed implementation and record the difference.
-
-### Apply The Findings
-
-For every component section:
-
-1. Link the four version-matched sources under **Research Sources**.
-2. Summarize which layer owns the behavior under **Ownership Result**.
-3. Order the supported customization surfaces from highest-level NiceGUI API to lower-level Quasar or CSS mechanisms.
-4. Include an example only after the owning APIs are established.
-5. Curate a short caveat list from the four sources. Keep only constraints that change implementation, security, accessibility, performance, or testing decisions.
-
-If the requirement is purely visual after this ownership check, continue in [visual styling and CSS](./styling-and-customization.md).
+Links to `main`, `dev`, or the latest hosted documentation can describe a newer API than the installed package. Tagged NiceGUI and matching `quasar-v<version>` links provide the version-specific definition.
 
 ## Using Slots In NiceGUI
 
@@ -91,9 +310,17 @@ NiceGUI creates a default slot for every element. Entering an element as a conte
 
 These mechanics are defined by the tagged [`Element.add_slot()` implementation](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/element.py), the [`Slot` context manager](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/slot.py), and NiceGUI's [context-managed scoped-slot examples](https://github.com/zauberzeug/nicegui/blob/v3.16.0/website/documentation/content/table_documentation.py).
 
-### Prefer Context-Managed NiceGUI Elements
+### Prefer Python-Owned Composition
 
-Build slot content with ordinary NiceGUI elements by default:
+Use NiceGUI context managers and `ui.*` elements for slot structure whenever they can represent the required element tree. Keep values, mappings, validation, permissions, event handling, and authoritative state transitions in Python. This preserves element identity, typed wrapper APIs, lifecycle cleanup, test visibility, and the normal NiceGUI update path.
+
+Use the narrowest browser-side expression for state that exists only while Quasar renders a scoped slot. A dynamic prop such as `:label="props.value"` may project that value into a NiceGUI element without moving the surrounding structure or business rules into JavaScript. When Python needs a browser-owned value, emit the smallest serializable proposal to a Python handler and validate it there.
+
+Escalate to `add_slot(name, template)` only when the slot contract requires client-side structure that context-managed NiceGUI elements cannot preserve, such as a browser-side `v-for`, a variable number of sibling roots, or Vue's object form of `v-bind` for a Quasar interaction bundle. Keep raw templates small, use documented scoped props, and do not duplicate authoritative application logic in JavaScript.
+
+### Context-Managed NiceGUI Elements
+
+Ordinary NiceGUI elements can populate slot content:
 
 ```python
 name_input = ui.input("Name")
@@ -102,46 +329,94 @@ with name_input.add_slot("prepend"):
     ui.icon("person")
 ```
 
-Use nested context managers to express the component hierarchy. This preserves NiceGUI element identity, event registration, updates, deletion, and test visibility. Pass a raw Vue template to `add_slot(name, template)` only when the slot requires client-side structure that ordinary NiceGUI elements cannot express cleanly, such as a `v-for` that creates a variable number of sibling elements.
+Nested context managers express the component hierarchy while preserving NiceGUI element identity, event registration, updates, deletion, and test visibility.
 
-### Use Scoped Props On The Client
+### Scoped Props On The Client
 
-A scoped slot receives a `props` object from its owning Vue component. Since NiceGUI `3.5.0`, NiceGUI elements inside a scoped-slot context can reference that object in dynamic `.props()` expressions and JavaScript event handlers:
+A scoped slot is a function whose argument is supplied by the component that renders the slot. Vue calls that argument the slot props; `props` is only NiceGUI's chosen local name for it. Since NiceGUI `3.5.0`, context-managed NiceGUI elements inside a scoped slot receive the current slot-props object as their frontend render context.
 
-- use `.props(":label=props.value")` or another component-supported prop to display a scoped value
-- use `.props("v-bind=props.itemProps")` when the slot provides a bundle of required attributes and handlers
-- use `.on(..., js_handler="... emit(...)", handler=...)` to transform and send serializable scoped values to Python
+The general `.props()` grammar and dynamic binding path are described under [Props](#props). In this context, the current scope object can be referenced by dynamic properties and JavaScript event handlers. For example:
+
+```python
+ui.badge().props(
+    ':label=props.label :color="props.selected ? \'primary\' : \'grey\'"'
+)
+```
+
+corresponds conceptually to this Vue template:
+
+```vue
+<q-badge :label="props.label" :color="props.selected ? 'primary' : 'grey'" />
+```
+
+Static `.props()` values do not have access to the slot scope. Only colon-prefixed expressions and NiceGUI JavaScript event handlers are evaluated with `props` in scope.
+
+#### Which `props.*` Names Exist
+
+There is no global catalog of `props.*` attributes. The owner of each named slot chooses the keys it passes when invoking that slot, so the available names can differ between components and between slots on the same component. Find them in this order:
+
+1. Open the wrapped component's version-matched Quasar API and inspect the **Slots** entry for the exact named slot.
+2. Use the slot's `scope` table as the public contract, including each value's type and whether it is data, state, or a callable.
+3. Inspect the version-matched Quasar source only when the API does not explain a bundle's contents or runtime behavior.
+
+For example, the [`QSelect` `option` slot API at Quasar `2.18.5`](https://github.com/quasarframework/quasar/blob/quasar-v2.18.5/ui/src/components/select/QSelect.json) exposes:
+
+| Expression | Meaning |
+| --- | --- |
+| `props.index` | index in the options array |
+| `props.opt` | original option from the `options` prop |
+| `props.label` | label after `option-label` processing |
+| `props.html` | whether the option content is marked as HTML |
+| `props.selected` | whether this option is selected |
+| `props.focused` | whether this option is the focused menu option |
+| `props.toggleOption` | function that adds or removes an option from the model |
+| `props.setOptionIndex` | function that changes the focused option index |
+| `props.itemProps` | object of computed props and listeners intended for the root `QItem` |
+
+The tagged [`QSelect` implementation](https://github.com/quasarframework/quasar/blob/quasar-v2.18.5/ui/src/components/select/QSelect.js) constructs `itemProps` with values such as `clickable`, `active`, `activeClass`, `manualFocus`, `focused`, `disable`, `tabindex`, `dense`, `dark`, `role`, `aria-selected`, `id`, `onClick`, and, when applicable, `onMousemove`. It is a behavior and accessibility bundle, not the original option object. Other QSelect slots expose different scopes: `no-option` only documents `inputValue`, while `selected-item` documents selection-oriented keys such as `index`, `opt`, `removeAtIndex`, `toggleOption`, and `tabindex`. A QTable body-cell slot's `props.value` is valid because QTable supplies `value`; that name should not be assumed in a QSelect option slot.
+
+#### Sending Scoped Values To Python
+
+NiceGUI also places the current slot object in scope while evaluating a `js_handler`. Use the event bridge's `emit(...)` function to select or transform JSON-serializable values before the Python callback runs:
+
+```python
+ui.button("Inspect").on(
+    "click",
+    handler=lambda event: print(event.args),
+    js_handler="() => emit({index: props.index, label: props.label})",
+)
+```
 
 Scoped props exist only in the browser render context. They are not Python variables and cannot be read by a Python callback until a JavaScript handler emits the required values. Treat `innerHTML`, `v-html`, and raw template interpolation as untrusted HTML unless the source is explicitly sanitized.
 
-### Preserve The Slot Contract
+### Slot Contracts
 
-Replacing default slot content also replaces the wrapped component's default rendering. Preserve any documented slot-prop bundle that carries behavior. For example, a `QSelect` option slot must bind `props.itemProps` to its root item; otherwise the custom row can lose click selection, disabled state, focus, active state, and keyboard navigation. Keep one root element per virtual-scroll item unless the component documents how to mark additional siblings.
+Replacing default slot content also replaces the wrapped component's default rendering. Documented slot-prop bundles can carry behavior as well as data. For example, a `QSelect` option slot binds `props.itemProps` to its root item; without that binding, the custom row can lose click selection, disabled state, focus, active state, and keyboard navigation. Quasar's virtual-scroll contract expects one root element per item unless additional siblings carry its documented marker class.
 
 ## `ui.select`
 
-### Research Sources
+### Versioned Source Definitions
 
 - **NiceGUI documentation:** [`ui.select` documentation source at `v3.16.0`](https://github.com/zauberzeug/nicegui/blob/v3.16.0/website/documentation/content/select_documentation.py)
 - **NiceGUI source code:** [`Select` implementation at `v3.16.0`](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/elements/select.py)
 - **Quasar documentation:** [`QSelect` documentation source at `2.18.5`](https://github.com/quasarframework/quasar/blob/quasar-v2.18.5/docs/src/pages/vue-components/select.md)
 - **Quasar source code:** [`QSelect` implementation at `2.18.5`](https://github.com/quasarframework/quasar/blob/quasar-v2.18.5/ui/src/components/select/QSelect.js)
 
-### Ownership Result
+### Layer Ownership
 
 NiceGUI's `Select` wraps Quasar `QSelect` but owns important Python-side behavior. Its constructor handles options, labels, values, change callbacks, input filtering, new-value modes, multiple selection, clearing, validation, and key generation. Use those constructor parameters before adding equivalent Quasar props manually.
 
-### Customization Order
+### Exposed Surfaces
 
-1. Use `options`, `label`, `value`, `on_change`, `with_input`, `new_value_mode`, `multiple`, `clearable`, `validation`, and `key_generator` through the NiceGUI constructor.
-2. Use `.props()` for additional documented `QSelect` behavior such as field design, chips, option density, popup classes, popup positioning, or menu/dialog behavior.
-3. Use `.classes()` and Tailwind for the field's structural width and placement.
-4. Use named slots for prepend, append, loading, no-option, selected, or option content when props are insufficient.
-5. Preserve the documented scoped-slot props when replacing option content so Quasar retains selection and keyboard behavior.
+- The NiceGUI constructor exposes `options`, `label`, `value`, `on_change`, `with_input`, `new_value_mode`, `multiple`, `clearable`, `validation`, and `key_generator`.
+- `.props()` carries additional documented `QSelect` behavior such as field design, chips, option density, popup classes, popup positioning, and menu/dialog behavior.
+- `.classes()` attaches structural width, placement, and other CSS utilities to the field element.
+- Named slots provide prepend, append, loading, no-option, selected, and option content.
+- Scoped-slot props retain Quasar's selection and keyboard behavior when option content is replaced.
 
 ### Example: Custom Menu Options With A Scoped Slot
 
-`QSelect` supplies each option as `props.opt` and its interaction contract as `props.itemProps`. NiceGUI elements can consume both inside the slot context without a raw Vue template:
+`QSelect` supplies each option as `props.opt`, its processed label as `props.label`, and its interaction contract as `props.itemProps`. Because the complete interaction bundle needs Vue's object form of `v-bind`, use a raw slot template for the root item:
 
 ```python
 from nicegui import ui
@@ -157,17 +432,24 @@ item_select = ui.select(
 with item_select.add_slot("prepend"):
     ui.icon("search")
 
-with item_select.add_slot("option"):
-    with ui.item().props("v-bind=props.itemProps"):
-        with ui.item_section().props("avatar"):
-            ui.icon("inventory_2")
-        with ui.item_section():
-            ui.badge().props(":label=props.opt.label outline color=primary")
+item_select.add_slot(
+    "option",
+    r"""
+    <q-item v-bind="props.itemProps">
+        <q-item-section avatar>
+            <q-icon name="inventory_2" />
+        </q-item-section>
+        <q-item-section>
+            <q-badge :label="props.label" outline color="primary" />
+        </q-item-section>
+    </q-item>
+    """,
+)
 ```
 
-The `prepend` slot adds content around the field. The scoped `option` slot replaces every menu row with context-managed NiceGUI elements; the badge reads the browser-side option label through a dynamic Quasar prop. Keep `v-bind=props.itemProps` on the root `ui.item()` so the custom rendering retains the option's interaction and accessibility wiring.
+The `prepend` slot uses context-managed NiceGUI elements because it needs no scoped object spread. The raw `option` template is compiled by Vue, so `v-bind="props.itemProps"` forwards every computed property and listener to `QItem`; the badge reads the processed browser-side label. Keep that binding on the root item so the custom rendering retains the option's interaction and accessibility wiring.
 
-### Curated Caveats
+### Behavioral Caveats
 
 These caveats are distilled from the four version-matched sources above:
 
@@ -177,34 +459,34 @@ These caveats are distilled from the four version-matched sources above:
 - A multiple select has a list value. NiceGUI normalizes a non-list initial value, but application state should still use the intended list shape.
 - `map-options` has a Quasar performance cost. Do not add it to NiceGUI's mapped options without confirming that the wrapper's value translation requires it.
 - `display-value-html` and `options-html` can create cross-site scripting risk. When using `selected`, `selected-item`, or `option` slots, the application owns sanitization.
-- A custom `option` slot must bind `props.itemProps` to its root `ui.item()` so click, focus, active, disabled, and keyboard behavior remain connected.
+- A custom `option` slot must bind `props.itemProps` to its root `QItem` so click, focus, active, disabled, and keyboard behavior remain connected.
 - Custom option slots use virtual scrolling. When one option renders multiple sibling elements, Quasar requires `q-virtual-scroll--with-prev` on every additional sibling.
 - Buttons placed in `before`, `after`, `prepend`, or `append` field slots do not propagate clicks to the parent. A submit button in one of those slots needs its own submit handler.
 - `QSelect` renders its popup outside the field. Style it through `popup-content-class`; do not assume a descendant selector beneath the field will reach it.
 - Quasar switches between menu and dialog popup behavior by platform. Verify forced `behavior=menu` carefully on iOS when input filtering is enabled.
 
-Use `.on()` or `run_method()` only after confirming the event or method in the installed Quasar API. Prefer NiceGUI's `on_change`, `set_options()`, value bindings, and `is_showing_popup` when they cover the behavior.
+`.on()` and `run_method()` address events and methods defined by the installed Quasar API. NiceGUI's `on_change`, `set_options()`, value bindings, and `is_showing_popup` provide wrapper-managed equivalents for their respective behaviors.
 
 ## `ui.icon`
 
-### Research Sources
+### Versioned Source Definitions
 
 - **NiceGUI documentation:** [`ui.icon` documentation source at `v3.16.0`](https://github.com/zauberzeug/nicegui/blob/v3.16.0/website/documentation/content/icon_documentation.py)
 - **NiceGUI source code:** [`Icon` implementation at `v3.16.0`](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/elements/icon.py)
 - **Quasar documentation:** [`QIcon` documentation source at `2.18.5`](https://github.com/quasarframework/quasar/blob/quasar-v2.18.5/docs/src/pages/vue-components/icon.md)
 - **Quasar source code:** [`QIcon` implementation at `2.18.5`](https://github.com/quasarframework/quasar/blob/quasar-v2.18.5/ui/src/components/icon/QIcon.js)
 
-### Ownership Result
+### Layer Ownership
 
 NiceGUI's `Icon` is a thin `QIcon` wrapper. Its constructor exposes `name`, `size`, and `color`; the source forwards these to a `q-icon` element. Use Quasar's icon naming and asset rules for anything beyond those parameters.
 
-### Customization Order
+### Exposed Surfaces
 
-1. Choose an icon family that is actually loaded by the application.
-2. Pass the documented icon name, size, and color to `ui.icon()`.
-3. Use `.props()` for supported `QIcon` props such as `left`, `right`, or a custom render tag.
-4. Use `.classes()` for structural placement and an application class for stable visual variants.
-5. Use a static stylesheet for Material Symbol axes, state variants, custom webfonts, or repeated effects.
+- The application-loaded icon family determines which icon names can render.
+- `ui.icon()` accepts the documented icon name, size, and color.
+- `.props()` carries supported `QIcon` props such as `left`, `right`, and a custom render tag.
+- `.classes()` controls structural placement and can attach application-defined visual variants.
+- Static stylesheets define Material Symbol axes, state variants, custom webfonts, and repeated effects.
 
 ### Example
 
@@ -232,7 +514,7 @@ ui.icon(
 }
 ```
 
-### Curated Caveats
+### Behavioral Caveats
 
 These caveats are distilled from the four version-matched sources above:
 
@@ -245,15 +527,17 @@ These caveats are distilled from the four version-matched sources above:
 - `QIcon` renders with `aria-hidden="true"`. For an action, use a semantic control such as `ui.button(icon=..., on_click=...)` and put the accessible name on that control; a tooltip is supplementary.
 - Prefer `ui.icon(...).tooltip(...)` over manually constructing tooltip slot markup when NiceGUI's method covers the visual hint.
 
-## Completion Check
+## Related Reference Index
 
-Before accepting a special-component customization:
-
-1. Record the target NiceGUI version and its declared Quasar version.
-2. Link the version-matched NiceGUI documentation and source code.
-3. Link the version-matched Quasar documentation and source code.
-4. Identify constructor arguments, Quasar props, slots, Tailwind classes, and stylesheet rules separately.
-5. Confirm detached popup or external asset behavior where applicable.
-6. Keep the caveat list traceable to the four researched sources.
-7. Test keyboard interaction, focus, labels, and tooltips.
-8. Test the supported mobile, landscape desktop, and portrait desktop viewports.
+- [NiceGUI component documentation](https://nicegui.io/documentation): Python constructors, callbacks, bindings, and wrapper methods
+- [NiceGUI `Element` documentation](https://nicegui.io/documentation/element): common props, classes, styles, hierarchy, updates, and client methods
+- [NiceGUI generic events](https://nicegui.io/documentation/generic_events): `.on()`, event arguments, JavaScript handlers, and throttling
+- [NiceGUI binding documentation](https://nicegui.io/documentation/section_binding_properties): one-way and two-way Python property binding
+- [Quasar component documentation](https://quasar.dev/vue-components): per-component props, events, slots, and methods
+- [Quasar breakpoints](https://quasar.dev/style/breakpoints): viewport names and pixel thresholds
+- [Quasar spacing classes](https://quasar.dev/style/spacing): padding and margin class syntax and permutations
+- [Quasar visibility classes](https://quasar.dev/style/visibility): responsive, platform, orientation, and print visibility
+- [Quasar helper classes](https://quasar.dev/style/other-helper-classes): pointer, scrolling, sizing, rotation, and border helpers
+- [Tailwind CSS documentation](https://tailwindcss.com/docs): complete utility-class categories and variant syntax
+- [MDN CSS reference](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference): CSS properties accepted by `.style()` and application stylesheets
+- [MDN event reference](https://developer.mozilla.org/en-US/docs/Web/Events): native browser event names and behavior

src/personal_mcp/docs/skills/nicegui/references/configuration-and-deployment.md

@@ -0,0 +1,194 @@
+# NiceGUI Configuration And Deployment
+
+Use this reference when a NiceGUI task concerns `ui.run(...)` settings, runtime URLs, native windows, environment variables, server hosting, executable packaging, or NiceGUI On Air. For startup ownership, app factories, `ui.run_with(...)`, lifespan, reload, and workers, load [FastAPI and Uvicorn startup](./fastapi-uvicorn-startup.md).
+
+The public surfaces below follow NiceGUI's current [configuration and deployment documentation](https://nicegui.io/documentation/section_configuration_deployment). Inspect the target project's pinned NiceGUI version before relying on a recently added option or native-mode behavior.
+
+## Configure The Owning Runtime
+
+Choose the process owner before setting runtime options:
+
+| Deployment shape | Owning surface | Where configuration belongs |
+| --- | --- | --- |
+| NiceGUI is the application and starts its server | `ui.run(...)` | NiceGUI arguments plus additional Uvicorn keyword arguments |
+| A parent FastAPI app owns startup | `ui.run_with(parent_app, ...)` and the external ASGI server | NiceGUI composition options in `ui.run_with`; socket, TLS, reload, and worker options in Uvicorn or the process manager |
+| Desktop application | `ui.run(native=True, ...)` | NiceGUI runtime options and `app.native` configuration |
+| Packaged browser or desktop executable | `ui.run(reload=False, ...)` | import-safe page registration, packaging flags, and multiprocessing setup |
+
+Do not split ownership by calling `ui.run()` and a separate server launcher for the same app. The exact composition patterns and worker constraints are in [FastAPI and Uvicorn startup](./fastapi-uvicorn-startup.md).
+
+## Select `ui.run` Options Deliberately
+
+[`ui.run(...)`](https://nicegui.io/documentation/run) accepts several groups of settings:
+
+| Concern | Representative options | Decision rule |
+| --- | --- | --- |
+| route and metadata | `root`, `title`, `viewport`, `favicon`, `language`, `dark`, `markdown` | Use a root callable or decorated pages; override metadata per page when it is route-specific. |
+| network and launch | `host`, `port`, `show`, `on_air` | Bind and expose only the interfaces required by the deployment; treat On Air as a separate remote-access choice. |
+| client recovery | `reconnect_timeout`, `message_history_length` | Tune together from observed disconnect duration and replay volume; replay is not durable job delivery. |
+| binding work | `binding_refresh_interval` | Reduce active links before lowering the interval; use `None` only when no polling-based links need updates. |
+| static delivery | `cache_control_directives`, `gzip_middleware_factory` | Preserve deliberate cache lifetimes and compression behavior; disabling gzip or changing immutable caching is an operational decision. |
+| development | `reload`, `uvicorn_reload_dirs`, `uvicorn_reload_includes`, `uvicorn_reload_excludes`, `uvicorn_logging_level` | Keep reload local to development and restart fully when changing options that the reloader process owns. |
+| frontend runtime | `tailwind`, `unocss`, `prod_js` | Verify class compatibility before switching CSS engines; use production Vue and Quasar assets in deployed apps. |
+| API visibility | `fastapi_docs`, `endpoint_documentation` | Expose only the OpenAPI surfaces the application intends to publish. |
+| browser storage | `storage_secret`, `session_middleware_kwargs` | A secret is required for `ui.storage.user` and `ui.storage.browser`; load it from a secret source and configure cookie policy for the deployment. |
+| native window | `native`, `window_size`, `fullscreen`, `frameless` | Use only for a desktop app with a supported browser engine. |
+
+Additional keyword arguments are forwarded to `uvicorn.run`. Most `ui.run` option changes require stopping and fully restarting the process; do not assume development auto-reload applies them.
+
+## Read Runtime URLs After Binding
+
+[`app.urls`](https://nicegui.io/documentation/section_configuration_deployment#urls) contains the URLs on which the running app is available. The server has not bound its sockets during `app.on_startup`, so the collection is not available there. Read it in a page function or subscribe to `app.urls.on_change` when another application component needs the final addresses.
+
+```python
+from nicegui import app, ui
+
+
+@ui.page('/')
+def home() -> None:
+    for url in app.urls:
+        ui.link(url, target=url)
+
+
+ui.run()
+```
+
+Do not derive a public URL solely from the listening host and port when a reverse proxy, container port mapping, or tunnel owns the external address.
+
+## Configure Environment-Controlled Facilities
+
+NiceGUI recognizes these framework environment variables:
+
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `MATPLOTLIB` | enabled | Set to `false` to skip the potentially costly Matplotlib import; `ui.pyplot` and `ui.line_plot` then remain unavailable. |
+| `NICEGUI_STORAGE_PATH` | `.nicegui` in the working directory | Changes the local storage-file directory. |
+| `NICEGUI_REDIS_URL` | no Redis backend | Selects Redis for shared persistent storage. |
+| `NICEGUI_REDIS_KEY_PREFIX` | `nicegui:` | Namespaces NiceGUI keys in Redis. |
+| `MARKDOWN_CONTENT_CACHE_SIZE` | `1000` | Bounds cached Markdown snippets. |
+| `RST_CONTENT_CACHE_SIZE` | `1000` | Bounds cached reStructuredText snippets. |
+
+Treat these as process-start configuration. For application-owned host, port, credentials, feature flags, and service settings, use one validated settings model rather than scattering direct environment reads. When multiple processes or executables share local storage, do not let them independently rewrite the same files; give each instance a distinct `NICEGUI_STORAGE_PATH` or configure Redis where state must be shared.
+
+## Deploy A Browser-Hosted App
+
+Run the production entry point under a service manager or container restart policy. NiceGUI's [multi-architecture Docker image](https://hub.docker.com/r/zauberzeug/nicegui) runs an application mounted at `/app`; its default internal port is `8080`, so publish that port explicitly. The image supports non-root execution through `PUID` and `PGID` and passes process signals through to the app.
+
+```bash
+docker run --detach --restart always \
+    --publish 80:8080 \
+    --env PUID="$(id -u)" \
+    --env PGID="$(id -g)" \
+    --volume "$PWD:/app" \
+    zauberzeug/nicegui:latest
+```
+
+For HTTPS, either pass Uvicorn's `ssl_certfile` and `ssl_keyfile` options to `ui.run(...)` or terminate TLS at a reverse proxy such as NGINX or Traefik. A reverse-proxy deployment must preserve NiceGUI's HTTP and Socket.IO traffic, forwarding scheme and host information, route prefixes, timeouts, and upload limits consistently. Verify the rendered page, static assets, websocket connection, reconnect behavior, and upload path through the public URL rather than only against the container port.
+
+Use one worker by default. NiceGUI clients, element trees, tasks, and ordinary Python state are process-local; a multi-worker deployment needs compatible session affinity and externalized shared state. See [FastAPI and Uvicorn startup](./fastapi-uvicorn-startup.md#development-reload) before adding workers or combining them with reload.
+
+## Build A Native Desktop App
+
+[`ui.run(native=True)`](https://nicegui.io/documentation/section_configuration_deployment#native-mode) launches a pywebview window. `window_size`, `fullscreen`, and `frameless` cover common presentation settings. Configure lower-level pywebview behavior before startup through:
+
+- `app.native.window_args` for `webview.create_window` arguments
+- `app.native.start_args` for `webview.start` arguments
+- `app.native.settings` for pywebview settings
+- `app.native.main_window` for asynchronous access to the running window
+
+Values in `window_args` and `start_args` take precedence over overlapping `ui.run` arguments. The browser engine must support ES modules and import maps; use Chrome 89 or newer, a current WebKitGTK or Qt backend on Linux, and the EdgeChromium prerequisites used by pywebview on Windows. A local Windows `favicon` used as the native icon must be an `.ico` file.
+
+Native mode chooses an available port automatically when `port` is omitted. Browser mode defaults to `8080`; use `native.find_open_port()` explicitly when multiple browser-mode executable instances must coexist.
+
+### Native Events And Process Placement
+
+Register sync or async handlers with `app.native.on(...)`. Supported lifecycle and window events are `shown`, `loaded`, `minimized`, `maximized`, `restored`, `resized`, `moved`, `closed`, and `drop`. Resized and moved events expose dimensions or coordinates in `event.args`; drop events expose filesystem paths under `event.args['files']`.
+
+The native UI runs in a separate process. Define `app.native.window_args`, `start_args`, `settings`, and event registrations outside the `if __name__ == '__main__':` guard so the child process sees them.
+
+```python
+from nicegui import app, ui
+
+app.native.window_args['resizable'] = False
+app.native.on('drop', lambda event: print(event.args['files']))
+
+if __name__ == '__main__':
+    ui.run(native=True, reload=False)
+```
+
+Native storage follows the same scopes as browser mode. Multiple executable instances started from one working directory can collide on the default `.nicegui` files; isolate `NICEGUI_STORAGE_PATH` per instance or use Redis for intentionally shared state.
+
+## Package An Executable
+
+Both `nicegui-pack`/PyInstaller and Nuitka require an import-safe application:
+
+1. Disable auto-reload with `ui.run(reload=False, ...)`.
+2. Supply a `root` page callable to `ui.run` or register at least one `@ui.page`.
+3. Decide whether the executable opens a browser or uses `native=True`.
+4. Use an available port when simultaneous instances are valid.
+5. Exercise the built artifact on every target operating system; a successful build on the development host does not establish runtime compatibility.
+
+With [`nicegui-pack`](https://nicegui.io/documentation/section_configuration_deployment#package-for-installation), `--onefile` is convenient but starts more slowly because PyInstaller extracts it on each run. A directory build starts faster and can be archived for distribution. Use `--windowed` only with `native=True`; a browser-mode application without a console has no normal Ctrl-C exit surface.
+
+Nuitka must include both NiceGUI modules and package data because NiceGUI uses lazy imports and ships frontend assets:
+
+```bash
+python -m nuitka \
+    --onefile \
+    --include-package=nicegui \
+    --include-package-data=nicegui \
+    main.py
+```
+
+Add equivalent package and package-data flags for optional libraries that ship templates or frontend assets. Prefer `--standalone` when startup speed matters more than producing one file.
+
+### Multiprocessing In Packaged Native Apps
+
+Packaged native apps must call [`multiprocessing.freeze_support()`](https://docs.python.org/3/library/multiprocessing.html#multiprocessing.freeze_support) as the first statement inside the main guard to prevent recursive process creation. Keep native settings outside the guard so the spawned native process applies them.
+
+```python
+from multiprocessing import freeze_support
+
+from nicegui import app, ui
+
+app.native.window_args['transparent'] = True
+
+
+def root() -> None:
+    ui.label('Packaged app')
+
+
+if __name__ == '__main__':
+    freeze_support()
+    ui.run(root, native=True, reload=False)
+```
+
+## Use On Air Only For Deliberate Remote Access
+
+[`ui.run(on_air=True)`](https://nicegui.io/documentation/section_configuration_deployment#nicegui-on-air) creates a temporary public URL, currently valid for one hour. A private device token can select a stable organization/device URL. Treat that token as a secret, and do not log or commit it.
+
+NiceGUI On Air is a tech preview, not a substitute for selecting an authentication, authorization, availability, and data-governance model. Before exposing an application, review what data and actions become reachable, add application authentication where needed, and verify the service's current operational and privacy terms. Use ordinary hosted deployment when the application requires controlled networking, durable availability, or organization-owned TLS and access policy.
+
+## Deployment Verification
+
+Validate the built deployment through its real entry point and public boundary:
+
+- process starts with reload disabled and shuts down cleanly under the service manager or container runtime
+- health route, root page, static assets, Socket.IO connection, and reconnect flow work through the proxy or published port
+- `app.urls` is consumed only after server binding and is not mistaken for canonical proxy configuration
+- storage survives and isolates users, tabs, workers, and executable instances as designed
+- TLS, forwarded headers, cookie flags, upload limits, cache policy, and logs match the public deployment
+- a native build opens, handles window events, closes cleanly, and can run alongside another instance when supported
+- packaged artifacts include NiceGUI and optional-library data files and are tested on each target platform
+- normal background tasks cancel on shutdown, while only explicitly bounded finalization work uses `@background_tasks.await_on_shutdown`; see [interaction mechanics](./interaction-patterns.md#execution-contexts)
+
+## Sources
+
+!!! info "Primary sources"
+    - [NiceGUI configuration and deployment](https://nicegui.io/documentation/section_configuration_deployment)
+    - [`ui.run` arguments](https://nicegui.io/documentation/run)
+    - [NiceGUI Docker example](https://github.com/zauberzeug/nicegui/tree/main/examples/docker_image)
+    - [NiceGUI NGINX HTTPS example](https://github.com/zauberzeug/nicegui/blob/main/examples/nginx_https/nginx.conf)
+    - [NiceGUI FastAPI example](https://github.com/zauberzeug/nicegui/tree/main/examples/fastapi)
+    - [pywebview API](https://pywebview.flowrl.com/api)
+    - [Uvicorn settings](https://www.uvicorn.org/settings/)

src/personal_mcp/docs/skills/nicegui/references/fastapi-uvicorn-startup.md

@@ -57,6 +57,8 @@ ui.run()
 
 In this mode, NiceGUI configures and starts its own [Uvicorn-derived server](https://github.com/zauberzeug/nicegui/blob/main/nicegui/server.py). Do not also call `uvicorn.run()`.
 
+For `ui.run` arguments, runtime URL discovery, native mode, environment variables, hosted deployment, and executable packaging, use [configuration and deployment](./configuration-and-deployment.md).
+
 ### Let FastAPI Own The Application
 
 Use `ui.run_with()` when an existing FastAPI application owns middleware, API routers, OpenAPI configuration, lifespan resources, or deployment startup. The [official NiceGUI FastAPI example](https://github.com/zauberzeug/nicegui/blob/main/examples/fastapi/main.py) follows this model.

src/personal_mcp/docs/skills/nicegui/references/interaction-patterns.md

@@ -1,110 +1,306 @@
-# Interaction Patterns Reference
+# NiceGUI Interaction Mechanics
 
-## Reactive State
+Use this reference for user-driven and live application behavior: page and client lifetime, value validation, form submission, uploads, explicit refreshes, timers, application events, background execution, and server-pushed updates. Component-specific event names, scoped event payloads, and Quasar model contracts are covered in [component mechanics](./component-mechanics.md). Binding graph behavior and typed projections are covered in [binding dataclasses](./binding-dataclasses.md).
 
-Use bindable dataclasses for local page state.
+The NiceGUI implementation details below are verified against NiceGUI `3.16.0`. FastAPI's native `EventSourceResponse` and `ServerSentEvent` APIs require FastAPI `0.135.0` or later. Check the target application's pinned versions before depending on those surfaces.
+
+## Interaction Boundary Map
+
+| Boundary | Owns | Does not own |
+| --- | --- | --- |
+| NiceGUI element | browser-facing value, enabled state, validation display, and registered UI callbacks | domain authorization, durable persistence, or cross-worker coordination |
+| Page `Client` | one page visit's elements, UI context, socket connection, outbox, and client-scoped storage | durable user identity or shared application state |
+| Page state | current filters, drafts, selections, busy flags, and serializable projections | database transactions or durable job state |
+| Service or repository | domain validation, authorization, transactions, idempotency, and persistence | direct creation or mutation of NiceGUI elements |
+| NiceGUI task utility | scheduling work in the event loop, a thread, or a process | durable delivery after process failure |
+| FastAPI route | HTTP, SSE, or custom WebSocket protocol and authentication boundary | automatic synchronization with NiceGUI elements |
+
+NiceGUI already uses a Socket.IO connection to carry element events and server updates for each client. Ordinary page interactions should use component callbacks, bindings, `Event`, and element updates rather than introducing a second transport.
+
+## Page And Client Lifetime
+
+A [`@ui.page`](https://nicegui.io/documentation/page) builder creates a private `Client` and element tree for each page visit. During initial page construction, Python can create elements before the browser socket exists. Code that requires JavaScript, tab storage, or post-response work must first await `ui.context.client.connected()`.
+
+The tagged [`page` implementation](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/page.py) distinguishes two phases:
+
+1. Before connection, the page builder must produce the initial response within `response_timeout`, which defaults to three seconds.
+2. Once `connected()` is awaited, NiceGUI can send the initial HTML immediately and let the remaining async builder continue with a live client.
+
+Long service calls should not delay initial page construction. Render a stable loading state, await the connection where necessary, then perform the asynchronous work and update or refresh the bounded result region.
+
+### Disconnect, Reconnect, And Delete
+
+The tagged [`Client` implementation](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/client.py) treats a transient socket disconnect differently from client deletion:
+
+- `on_disconnect` runs whenever the socket disconnects, including interruptions followed by reconnection.
+- NiceGUI keeps the client alive for the page's `reconnect_timeout`.
+- A successful handshake within that window cancels pending deletion.
+- `on_delete` runs only when the client is actually removed after the reconnect window or explicit cleanup.
+- Deletion removes the client's elements and bindings and stops its outbox.
+
+Use `on_disconnect` for connection telemetry and reversible transport state. Use `on_delete` to release resources owned by the page visit. Do not close a page-owned resource on every disconnect if it must survive a short reconnect.
+
+NiceGUI's tagged [`Outbox`](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/outbox.py) retains recent messages according to `message_history_length` and the reconnect window. A reconnecting client supplies its next expected message ID; NiceGUI replays retained messages or reloads the page when the required history is unavailable. Message replay is transport recovery, not a durable event log or a substitute for idempotent service operations.
+
+### State Scope
+
+[`app.storage`](https://nicegui.io/documentation/storage) offers scopes with different navigation and process lifetimes:
+
+| Scope | Shared with | Survives page navigation or reload | Persistence notes |
+| --- | --- | --- | --- |
+| `client` | current page visit only | no | server memory; appropriate for short-lived page resources |
+| `tab` | current browser tab | yes | server memory by default; requires an established connection |
+| `user` | tabs carrying the same signed session ID | yes | server-side persistent dictionary; requires `storage_secret` |
+| `browser` | tabs sharing the session cookie | yes | cookie payload; writable only before the response is built; prefer `user` for most data |
+| `general` | all users in the process or configured backend | yes | shared persistent dictionary; not a per-user boundary |
+
+The tagged [`storage` implementation](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/storage.py) stores general and user data in local JSON files by default or Redis when configured. Tab storage is process memory unless Redis is configured. Multiple workers therefore require an explicitly shared backend for state that must cross processes.
+
+## Values, Validation, And Submission
+
+NiceGUI value elements mirror browser changes into Python and then invoke `on_change` or `on_value_change` handlers. For text input, [`ui.input`](https://nicegui.io/documentation/input) sends `on_change` on each value change unless a Quasar `debounce` prop delays the model update. Use an enter, blur, or explicit submit event when every keystroke should not trigger application work.
+
+The tagged [`ValidationElement`](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/elements/mixins/validation_element.py) implements NiceGUI's Python validation:
+
+- a callable returns an error string or `None`
+- a dictionary maps error strings to predicates and stops at the first failed predicate
+- automatic validation runs after each handled value change unless `without_auto_validation()` is set
+- `validate()` updates the element's `error` and `error-message` props
+- asynchronous validation runs as a background task; `validate(return_result=True)` is not supported for an async validator
+
+NiceGUI validation is suitable for field feedback, but a submit operation still needs service-level validation and authorization. Browser values, client-side Quasar rules, file metadata, and hidden or disabled controls are not trust boundaries.
+
+NiceGUI does not require a transport-level HTML form for ordinary page submission: current element values already exist in Python. A submit handler can validate relevant fields, construct an immutable command or DTO, call the service boundary, and update the page from the accepted result. Clear draft state only after persistence succeeds.
 
 ```python
-from dataclasses import field
-from nicegui import binding, ui
+async def submit() -> None:
+    if not all(field.validate() for field in (name, email)):
+        return
 
-@binding.bindable_dataclass
-class PageState:
-    selected_id: int | None = None
-    items: list = field(default_factory=list)
-
-state = PageState()
-ui.label().bind_text_from(state, "selected_id")
-```
-
-## File Upload Pattern
-
-- Validate extension and size before storing.
-- Delegate storage to a service method.
-- Notify success and failure explicitly.
-
-```python
-async def handle_upload(e: ui.events.UploadEventArguments):
+    submit_button.disable()
     try:
-        if e.size > 10 * 1024 * 1024:
-            raise ValueError("File too large")
-        if not e.name.endswith(".pdf"):
-            raise ValueError("Only PDF allowed")
-        await file_service.store(e.content.read(), e.name)
-        ui.notify(f"Uploaded: {e.name}", type="positive")
-    except ValueError as err:
-        ui.notify(str(err), type="negative")
-
-ui.upload(on_upload=handle_upload, auto_upload=True)
+        user = await user_service.create(name=name.value, email=email.value)
+        ui.notify(f"Created {user.display_name}", type="positive")
+        name.set_value("")
+        email.set_value("")
+    except DuplicateEmailError:
+        email.error = "This email is already registered"
+    finally:
+        submit_button.enable()
 ```
 
-## Form Submission Pattern
+For asynchronous field validators, await the validator at the service boundary or maintain an explicit validation state; do not use the synchronous return value of `validate()` as proof that asynchronous validation completed.
 
-- Bind UI inputs to dataclass fields.
-- Perform validation in the service layer.
-- Clear form state on success.
+## Upload Mechanics
+
+[`ui.upload`](https://nicegui.io/documentation/upload) wraps Quasar's `QUploader`. The tagged [`Upload` wrapper](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/elements/upload.py) registers a POST route scoped to the current client and element. Its event order is:
+
+1. `on_rejected` during browser-side file selection for Quasar restrictions.
+2. `on_begin_upload` when the client starts a request.
+3. `on_upload` once for each server-received file.
+4. `on_multi_upload` after all files in that request have been converted.
+
+`max_file_size`, `max_total_size`, `max_files`, and an `accept` prop improve client feedback, but NiceGUI's [security guidance](https://nicegui.io/documentation/section_security#examples_are_starting_points) identifies those restrictions as browser-side checks. Revalidate size, media type, content signature, filename policy, authorization, and storage quota on the server before persisting or parsing data.
+
+In NiceGUI 3.16, `event.file` is a [`FileUpload`](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/elements/upload_files.py):
+
+| Surface | Behavior |
+| --- | --- |
+| `name` | basename sanitized by NiceGUI; still untrusted display metadata |
+| `content_type` | request-provided media type; not content verification |
+| `size()` | synchronous byte count |
+| `read()`, `text()`, `json()` | asynchronous full-content reads |
+| `iterate(chunk_size=...)` | asynchronous chunks for bounded-memory processing |
+| `save(path)` | asynchronous save to an application-selected path |
+
+NiceGUI reads the incoming Starlette upload and keeps it in memory up to `MultiPartParser.spool_max_size`; larger files spill to a temporary file. This spool threshold controls memory versus disk, not the allowed upload size. Raising it increases per-upload memory pressure and should not be used as a validation mechanism.
 
 ```python
-@binding.bindable_dataclass
-class FormData:
-    name: str = ""
-    email: str = ""
+from nicegui import events, ui
 
-data = FormData()
-ui.input("Name").bind_value(data, "name")
-ui.input("Email").bind_value(data, "email")
 
-async def on_submit():
+async def handle_upload(event: events.UploadEventArguments) -> None:
+    file = event.file
+    if file.size() > 10 * 1024 * 1024:
+        ui.notify("File exceeds 10 MB", type="negative")
+        return
+    if file.content_type != "application/pdf":
+        ui.notify("Only PDF files are accepted", type="negative")
+        return
+
     try:
-        await user_service.create_user(name=data.name, email=data.email)
-        ui.notify("User created", type="positive")
-        data.name = data.email = ""
-    except ValueError as err:
-        ui.notify(str(err), type="negative")
+        await file_service.store(chunks=file.iterate(), original_name=file.name)
+    except StorageQuotaError:
+        ui.notify("Storage quota exceeded", type="negative")
+    else:
+        ui.notify(f"Uploaded {file.name}", type="positive")
 
-ui.button("Submit").on_click(on_submit)
+
+uploader = ui.upload(
+    on_upload=handle_upload,
+    on_rejected=lambda: ui.notify("File rejected", type="negative"),
+    max_file_size=10 * 1024 * 1024,
+    auto_upload=True,
+).props("accept=application/pdf")
 ```
 
-## Real-Time Updates Decision
+Generate the durable storage name independently from `file.name`, keep user-uploaded active content off the application origin, and apply content-specific scanning before downstream parsers consume the file. Call `uploader.reset()` when the product should clear QUploader's client-side queue after a completed or abandoned operation.
 
-Use SSE for one-way status streaming.
-Use WebSocket for bidirectional messaging.
+## Refreshable Component Regions
 
-SSE endpoint example:
+The reusable [component factory pattern](./architecture.md#reusable-component-contract) combines stable bindable fields with bounded structural refreshes. Use bindings and setters while an existing element can represent the change; use a refreshable region when the number, type, order, or nesting of child elements must be rebuilt.
 
-```python
-@app.get("/events/status")
-async def status_stream():
-    async def gen():
-        while True:
-            yield f"data: {await get_status()}\\n\\n"
-            await asyncio.sleep(1)
-    return StreamingResponse(gen(), media_type="text/event-stream")
-```
+Use the narrowest update mechanism that represents the change:
 
-## Background Work Pattern
+| Change | Appropriate surface |
+| --- | --- |
+| one wrapper property | setter, binding, or property assignment supported by that wrapper |
+| mutated option or row collection | wrapper helper or explicit `element.update()` |
+| a bounded subtree whose structure changed | `@ui.refreshable` or `@ui.refreshable_method` |
+| navigation to a different page | `ui.navigate` or `ui.sub_pages` |
 
-- Start long jobs in FastAPI background tasks.
-- Expose status via endpoint or streaming channel.
-- Guard buttons against duplicate submissions during in-flight tasks.
+The tagged [`refreshable` implementation](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/functions/refreshable.py) records every invocation as a target containing a `RefreshableContainer`, the function arguments, and the associated object instance when applicable. The initial call both renders the region and registers that target. Calling `refresh()` before the decorated function or method has rendered does nothing because no target exists yet.
 
-## Explicit Refresh Pattern
+For each matching target, `refresh()` clears the container, updates its remembered arguments, and invokes the function again inside that same container. It recreates the subtree rather than diffing children. Bindings and event handlers owned by deleted elements follow normal element cleanup; a retained reference to a former child does not become the new child. Expose component state and public actions through the returned component handle instead of leaking refresh-owned element references.
 
-Use @ui.refreshable and call refresh intentionally instead of polling unrelated state.
+### Function And Method Scope
 
-```python
-@ui.refreshable
-async def item_list():
-    items = await service.list()
-    for item in items:
-        ui.label(item.name)
+Choose the decorator according to state ownership:
 
-ui.button("Refresh").on_click(lambda: item_list.refresh())
-```
+| Form | Target identity | Appropriate scope |
+| --- | --- | --- |
+| module-level `@ui.refreshable` | every surviving call target of that decorated function | deliberate multicast or shared rendering |
+| page-local `@ui.refreshable` | calls recorded by the function created during that page build | one page client |
+| page-created `ui.refreshable(function)` | calls recorded by that decorated wrapper | one page client or component factory call |
+| `@ui.refreshable_method` | targets whose recorded instance equals the accessed object | reusable component instances with independent state |
 
-## Links
+A module-level refreshable called by multiple clients has multiple targets, so one refresh can update every surviving target. The official [global and local scope examples](https://nicegui.io/documentation/refreshable#global_scope) demonstrate this distinction. For reusable components returned as dataclass handles, prefer a page-created instance with `@ui.refreshable_method`; NiceGUI's tagged [multi-instance tests](https://github.com/zauberzeug/nicegui/blob/v3.16.0/tests/test_refreshable.py) verify that refreshing one instance selects its own targets.
 
-!!! info "Primary sources"
-    - [NiceGUI action events](https://nicegui.io/documentation/section_action_events)
-    - [FastAPI server-sent events](https://fastapi.tiangolo.com/advanced/server-sent-events/)
-    - [FastAPI WebSockets](https://fastapi.tiangolo.com/advanced/websockets/)
+Calling the same refreshable function more than once creates more than one target. For `@ui.refreshable_method`, every call made on the same instance belongs to that instance, so `instance.region.refresh()` refreshes all surviving targets for that method and instance. Use separate methods or separate component instances when independently refreshing two regions is required.
+
+### Arguments And Return Behavior
+
+Targets remember their initial positional and keyword arguments:
+
+- no refresh arguments reuse all remembered values
+- non-empty positional refresh arguments replace the remembered positional tuple
+- keyword refresh arguments update the remembered keyword dictionary
+- arguments must remain consistently positional or keyword; supplying the same parameter through both paths raises `TypeError`
+- the initial call and each refresh return the decorated function's normal result; the `refresh()` wrapper itself exposes NiceGUI's awaitable response behavior
+
+Parameters should describe render input, not hide durable state. On a reusable component, fields on the returned dataclass usually provide a clearer interface than repeatedly replacing a long refresh argument list.
+
+### Async Refresh
+
+An async refreshable's initial invocation returns its coroutine and should be awaited when page construction depends on its output. For subsequent refreshes:
+
+- `await region.refresh()` waits for all matching async refreshes to finish
+- calling `region.refresh()` without awaiting schedules the async work in the background
+- awaiting is appropriate when a button must remain disabled until rendering completes
+- each refresh clears the old target before the new async render finishes, so provide a stable outer loading surface when an empty interval would be disruptive
+
+Multiple matching targets are refreshed together; awaiting waits for all async results through `asyncio.gather`. That coordinates completion but does not serialize competing refresh calls. Apply the generation, lock, or coalescing policy described under [concurrency and feedback state](#concurrency-and-feedback-state) when two operations can refresh the same target concurrently.
+
+### Target And Local-State Lifetime
+
+Before every invocation or refresh, NiceGUI prunes targets whose container was deleted. Clearing an ancestor, navigating away, deleting the client, or replacing an outer refreshable region can therefore remove an inner target. A later call to the inner region's `refresh()` cannot recreate a pruned outer placement; the owning outer render must invoke it again.
+
+`ui.state()` stores values in a list owned by one refreshable target and identifies each value by call order. Its setter automatically refreshes the associated instance target. Conditional or reordered `ui.state()` calls can associate stored values with a different logical variable, so keep their call order stable.
+
+For reusable application components, a bindable dataclass is usually the clearer state owner: fields have explicit names, can bind directly to stable elements, and remain available to the page through the returned handle. Reserve `ui.state()` for small render-local values that do not need a typed component API, cross-component coordination, service persistence, or independent tests.
+
+## Timers And Application Events
+
+[`ui.timer`](https://nicegui.io/documentation/timer) is client-scoped. Its tagged [element implementation](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/elements/timer.py) waits for the client connection and cancels the current invocation when the element is deleted. `app.timer` is application-scoped and has no UI context of its own.
+
+The tagged base [`Timer`](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/timer.py) awaits each callback before scheduling the remainder of the interval, so one timer does not overlap its own invocations. A callback that takes longer than the interval causes the next iteration to begin without an additional delay. `deactivate()` pauses future invocations, while `cancel(with_current_invocation=True)` also cancels the current callback task and cannot be reversed.
+
+Use timers for truly periodic observation, not to compensate for a missing event or explicit refresh. Polling intervals must account for query cost, number of connected clients, and process-local duplication under multiple workers.
+
+[`Event`](https://nicegui.io/documentation/event) decouples long-lived Python producers from UI subscribers:
+
+- `emit()` invokes subscribers without waiting for async callbacks to complete
+- `call()` awaits all subscribers and propagates their failures to the caller
+- `emitted(timeout=...)` waits for the next emission
+- subscriptions created in a UI context are automatically removed when that client is deleted unless configured otherwise
+
+The automatic unsubscribe behavior in the tagged [`Event` implementation](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/event.py) makes an application event suitable for connecting longer-lived models to page-local UI without retaining deleted clients. It remains process-local; use a broker or shared service for cross-worker fan-out.
+
+## Execution Contexts
+
+Choose an execution surface by workload and lifetime:
+
+| Surface | Execution | Suitable for | Important constraint |
+| --- | --- | --- | --- |
+| async UI handler | event loop | non-blocking clients and short orchestration | blocking calls freeze all clients on that loop |
+| `run.io_bound()` | shared thread pool | blocking file, HTTP, or SDK calls | cancellation does not necessarily stop the underlying thread operation |
+| `run.cpu_bound()` | process pool | CPU-heavy pure computation | callable, arguments, result, and failures cross a pickle boundary |
+| `background_tasks.create()` | event-loop task | detached async work owned by this process | canceled during shutdown unless tagged with `await_on_shutdown` |
+| FastAPI `BackgroundTasks` | after an HTTP response | small route-triggered work | still belongs to the web process; not a durable queue |
+| external worker or job queue | separate process or service | durable, retryable, resource-heavy jobs | requires explicit status, cancellation, and result contracts |
+
+The tagged [`run` implementation](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/run.py) uses a thread pool for `io_bound` and a process pool for `cpu_bound`. For CPU work, prefer a module-level function with simple serializable arguments and return data rather than UI objects or closures. NiceGUI 3.16 inherits the platform multiprocessing start method unless `run.process_pool_start_method` is set before startup; `spawn` avoids unsafe fork behavior in a threaded process but does not inherit module state.
+
+The tagged [`background_tasks` implementation](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/background_tasks.py) keeps strong references to running tasks, forwards unhandled exceptions to global exception handlers, and cancels ordinary tasks during shutdown. `create_lazy()` coalesces repeated work by name into the current run plus only the latest waiting coroutine; it is useful for refresh-style invalidation, not for work where every event must be processed.
+
+Decorate a coroutine with `@background_tasks.await_on_shutdown` only when process shutdown must wait for that bounded task to finish, such as flushing a small already-accepted result. The decorator prevents NiceGUI's normal shutdown cancellation; it does not make the work durable after a crash, container kill, or host failure. Keep unbounded work and retryable jobs in an external worker rather than delaying application termination indefinitely.
+
+## Live Update Transports
+
+| Requirement | Default surface |
+| --- | --- |
+| update the initiating NiceGUI page | mutate elements or bound page state in its client context |
+| notify all local clients of a page | iterate `app.clients(path)` and enter each `with client:` context |
+| connect a long-lived Python producer to page subscribers | NiceGUI `Event` with page-local subscriptions |
+| one-way HTTP event stream for an external/browser consumer | FastAPI SSE endpoint |
+| custom bidirectional protocol independent of NiceGUI elements | FastAPI WebSocket endpoint |
+| cross-worker or cross-instance broadcast | external broker plus a subscriber in each process |
+
+FastAPI's [SSE support](https://fastapi.tiangolo.com/tutorial/server-sent-events/) uses a yielding route with `response_class=EventSourceResponse`. `ServerSentEvent` adds `event`, `id`, `retry`, and comment fields; event IDs support application-defined resume behavior through `Last-Event-ID`. FastAPI supplies keep-alive comments and headers that discourage proxy buffering and caching. The stream producer still owns authorization, disconnect-aware resource cleanup, replay semantics, and bounded buffering.
+
+FastAPI [WebSockets](https://fastapi.tiangolo.com/advanced/websockets/) support text, bytes, and JSON in both directions. Catch `WebSocketDisconnect`, remove the connection from any local registry, and remember that an in-memory connection manager reaches only clients attached to the same process.
+
+Do not use SSE or a custom WebSocket merely to update NiceGUI elements. Those transports do not automatically establish the target NiceGUI client context or synchronize its element tree.
+
+## Concurrency And Feedback State
+
+Disabling the initiating control communicates that work is active, but it is not a server-side concurrency guarantee. Also guard the handler or service with one of these policies:
+
+- reject a second request while the operation is in flight
+- coalesce duplicate refresh requests and keep only the latest invalidation
+- serialize operations with a lock scoped to the affected entity or user
+- make the service operation idempotent and return the existing result
+
+For search, filtering, and other replaceable reads, an older request can complete after a newer request. Associate each request with a monotonically increasing generation or cancel the previous task, and only publish a result that still matches the current generation. Cancellation must still restore enabled/loading state in `finally`.
+
+Every user-triggered asynchronous operation should expose a bounded state model such as `idle`, `running`, `succeeded`, `failed`, or `canceled`. Keep the error message near the action, preserve user input after expected failure, and do not convert unexpected programming errors into a generic success-like state.
+
+## Source Index
+
+!!! info "NiceGUI public documentation"
+    - [Pages and client connection](https://nicegui.io/documentation/page)
+    - [Action, events, execution, and error handling](https://nicegui.io/documentation/section_action_events)
+    - [Input and validation](https://nicegui.io/documentation/input)
+    - [Upload](https://nicegui.io/documentation/upload)
+    - [Refreshable UI](https://nicegui.io/documentation/refreshable)
+    - [Timer](https://nicegui.io/documentation/timer)
+    - [Application events](https://nicegui.io/documentation/event)
+    - [Storage scopes](https://nicegui.io/documentation/storage)
+
+!!! info "NiceGUI `3.16.0` implementation"
+    - [Page builder and response phases](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/page.py)
+    - [Client lifecycle](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/client.py)
+    - [Outbox and reconnect replay](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/outbox.py)
+    - [Validation elements](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/elements/mixins/validation_element.py)
+    - [Upload wrapper](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/elements/upload.py)
+    - [Uploaded-file storage and access](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/elements/upload_files.py)
+    - [Refreshable targets and local state](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/functions/refreshable.py)
+    - [Timer scheduling](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/timer.py)
+    - [Application event dispatch](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/event.py)
+    - [Thread and process execution](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/run.py)
+    - [Background-task lifecycle](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/background_tasks.py)
+
+!!! info "FastAPI transports and tasks"
+    - [Server-sent events](https://fastapi.tiangolo.com/tutorial/server-sent-events/)
+    - [WebSockets](https://fastapi.tiangolo.com/advanced/websockets/)
+    - [Response background tasks](https://fastapi.tiangolo.com/tutorial/background-tasks/)

src/personal_mcp/docs/skills/nicegui/references/source-documentation.md

@@ -9,11 +9,16 @@ Use these links to verify framework-specific behavior before relying on version-
     - [Element styling, props, and events](https://nicegui.io/documentation/element)
     - [NiceGUI element source](https://github.com/zauberzeug/nicegui/tree/main/nicegui/elements)
     - [Pages, routing, and FastAPI integration](https://www.nicegui.io/documentation/section_pages_routing)
+    - [Configuration, native mode, hosting, and packaging](https://nicegui.io/documentation/section_configuration_deployment)
+    - [`ui.run` arguments](https://nicegui.io/documentation/run)
     - [`ui.run_with` implementation](https://github.com/zauberzeug/nicegui/blob/main/nicegui/ui_run_with.py)
     - [FastAPI integration example](https://github.com/zauberzeug/nicegui/blob/main/examples/fastapi/main.py)
     - [Binding properties and bindable dataclasses](https://www.nicegui.io/documentation/section_binding_properties)
     - [Action events](https://www.nicegui.io/documentation/section_action_events)
     - [Security best practices](https://www.nicegui.io/documentation/section_security)
+    - [Machine-readable sitewide documentation index](https://nicegui.io/static/sitewide_index.json)
+    - [Machine-readable documentation search index](https://nicegui.io/static/search_index.json)
+    - [Machine-readable examples index](https://nicegui.io/static/examples_index.json)
 
 ## FastAPI
 

src/personal_mcp/docs/skills/nicegui/references/styling-and-customization.md

@@ -1,172 +1,71 @@
-# NiceGUI Visual Styling And CSS
+# NiceGUI Page Structure, Typography, And Scaling
 
-Use this reference for cosmetic and presentational work: themes, color roles, utility classes, CSS properties, responsive layout, and static assets. For the mechanics of how a NiceGUI Python element maps to a Quasar Vue component, including props, events, slots, methods, teleported content, and wrapper-owned state, load [component mechanics](./component-mechanics.md).
+Use this reference for the physical structure of a NiceGUI page: container geometry, Tailwind layout classes, spacing, overflow, responsive reflow, font loading, typography, and scale. Prefer NiceGUI's Python mechanics or Tailwind classes wherever they can express the requirement; custom CSS is the fallback, not a parallel styling path. For the mechanics of how a NiceGUI Python element maps to a Quasar Vue component, including props, events, slots, methods, teleported content, and wrapper-owned state, load [component mechanics](./component-mechanics.md).
 
 For package boundaries, dependency direction, and page or component ownership, load [application architecture](./architecture.md).
 
-## Visual Styling Boundary
+## Page Structure Boundary
 
-This page owns how an element looks and fits into a page after the correct component and behavior have been chosen. Typical concerns include:
+This page owns how elements occupy and share space after the correct components and behavior have been chosen. Typical concerns include:
 
-- application color roles and light or dark presentation
-- width, height, spacing, alignment, wrapping, and overflow
-- typography, borders, shadows, focus treatments, and state colors
+- page shells, content-width constraints, columns, rows, and grid tracks
+- width, height, spacing, alignment, wrapping, overflow, and scroll ownership
+- font resources, font families, type sizes, weights, line height, and line length
 - responsive page composition and stable control dimensions
-- reusable application classes, CSS custom properties, and static assets
+- rem-based sizing, browser text enlargement, and explicit element scaling
+- exceptional CSS that cannot be expressed through Python mechanics or Tailwind classes
 
 The companion [component mechanics](./component-mechanics.md) reference owns how behavior crosses framework boundaries. Use it when the question is whether a value belongs in a constructor, Quasar prop, Vue event, slot, method, binding, or teleported popup.
 
-## Visual Styling Workflow
+## Precedence: Python, Then Tailwind, Then CSS
 
-Escalate only as far as the visual requirement needs:
+Apply this order to every structural requirement:
 
-1. Use a NiceGUI constructor argument when it directly expresses appearance, such as an icon, color, or size.
-2. Use documented Quasar appearance props through `.props(...)` for component variants such as `outlined`, `rounded`, or `dense`.
-3. Use Tailwind classes for page structure and common visual utilities.
-4. Use Quasar utility classes for Quasar spacing, typography, semantic colors, visibility, and positioning.
-5. Use `.style(...)` for a calculated runtime value or a short-lived visual probe.
-6. Move stable or repeated declarations into a scoped static stylesheet under an application-owned class.
+1. Use NiceGUI's Python composition and component APIs: containers such as `ui.row`, `ui.column`, and `ui.grid`, constructor arguments, documented properties, slots, and wrapper methods.
+2. Add Tailwind classes through `.classes(...)` for width, tracks, spacing, alignment, wrapping, overflow, responsive changes, typography, and other physical presentation.
+3. Use Quasar props or helper classes when the requirement belongs specifically to a Quasar component and NiceGUI exposes that boundary.
+4. Use `.style(...)` only for a calculated runtime value that cannot be represented by the available APIs or utility classes.
+5. Add scoped static CSS only when all preceding layers cannot express the requirement without relying on unsupported component internals.
 
-Stop when the required presentation is achieved. If a proposed rule needs selectors such as `.q-field__control`, changes a popup's mounting or positioning behavior, or depends on generated Vue markup, resolve the component mechanics first instead of compensating with CSS.
+Do not create a stylesheet merely to rename or group utilities that fit cleanly in `.classes(...)`. Reuse a Python component or helper when a class sequence repeats. Before adding CSS, identify the unsupported requirement it solves; if the rule needs selectors such as `.q-field__control`, changes popup positioning, or depends on generated Vue markup, resolve the component mechanics first instead of compensating with CSS.
 
 ```python
-ui.select(
-    options=items,
-    label="Item",
-).props(
-    "outlined popup-content-class=app-item-menu"
-).classes(
-    "app-item-select w-full md:max-w-md"
+(
+    ui.select(options=items, label="Item")
+    .props("outlined")
+    .classes("w-full md:max-w-md rounded")
 )
 ```
 
-```css
-.app-item-select {
-    border-radius: 0.25rem;
-}
+## Physical Layout Model
 
-.app-item-menu {
-    max-height: min(24rem, 60dvh);
-}
-```
+Four layout decisions control most NiceGUI page structure:
 
-## Application Themes With NiceGUI And Quasar
+| Decision | Typical declarations | Failure when omitted |
+| --- | --- | --- |
+| outer constraint | `w-full`, `max-w-*`, `mx-auto`, `px-*` | content touches viewport edges or becomes unreadably wide |
+| track sizing | `flex-1`, `shrink-0`, `grid-cols-*`, `minmax(0, 1fr)` | sidebars collapse or content forces tracks wider than the viewport |
+| intrinsic minimums | `min-w-0`, `min-h-0` | flexible children refuse to shrink and create page-level overflow |
+| overflow owner | `overflow-auto`, `overflow-x-auto`, `overflow-hidden` | multiple nested scrollers or clipped interactive content |
 
-Treat a theme as three related layers with different owners:
-
-1. Configure Quasar's named color roles through NiceGUI.
-2. Let Quasar own light, dark, and automatic mode state.
-3. Define application semantic tokens for surfaces and content not covered by Quasar components.
-
-Do not implement a parallel theme switch by replacing Quasar classes or directly restyling each component. NiceGUI's color APIs set the supported Quasar `--q-*` custom properties, so Quasar components, `color=` arguments, and classes such as `text-primary` and `bg-positive` stay aligned.
-
-### Set The App-Wide Palette Once
-
-Use [`app.colors()`](https://nicegui.io/documentation/colors#app-wide-colors) in the composition layer for the default palette. Prefer Quasar's semantic roles over shade names: `primary`, `secondary`, `accent`, `positive`, `negative`, `info`, and `warning`. The `dark` and `dark_page` arguments configure dark surface colors; they do not enable dark mode.
-
-```python
-from nicegui import app, ui
-
-app.colors(
-    primary="#176b5b",
-    secondary="#52645f",
-    accent="#c05a32",
-    dark="#202523",
-    dark_page="#151917",
-    positive="#2e7d32",
-    negative="#b3261e",
-    info="#276b8e",
-    warning="#a86600",
-    brand="#176b5b",
-)
-
-
-@ui.page("/")
-def index() -> None:
-    ui.button("Save")
-    ui.label("Current workspace").classes("text-brand")
-
-
-ui.run()
-```
-
-Custom names such as `brand` become Quasar color names and can be used through `color="brand"`, `text-brand`, or `bg-brand`. Register them before any component uses them. `app.colors()` was added in NiceGUI 3.6.0; for an older pinned version, centralize the same `ui.colors(...)` call in a shared page shell.
-
-Use [`ui.colors()`](https://nicegui.io/documentation/colors) only when one page intentionally overrides the app palette. It is page-scoped and takes precedence over `app.colors()`:
-
-```python
-@ui.page("/operations")
-def operations_page() -> None:
-    ui.colors(primary="#8f3d2c")
-    ui.button("Operations action")
-```
-
-Avoid scattering `ui.colors()` calls among reusable components. A component should consume semantic roles from its owning page rather than silently changing the palette for the whole page.
-
-### Let Quasar Control Light And Dark Mode
-
-Use [`ui.dark_mode()`](https://nicegui.io/documentation/dark_mode) for page mode. Its value is tri-state: `True` enables dark mode, `False` disables it, and `None` follows the client's `prefers-color-scheme` setting. It overrides the `dark` default supplied to `ui.run()` or `@ui.page` for that page.
-
-```python
-dark_mode = ui.dark_mode(None)
-
-with ui.button_group():
-    ui.button("System", on_click=dark_mode.auto)
-    ui.button("Light", on_click=dark_mode.disable)
-    ui.button("Dark", on_click=dark_mode.enable)
-```
-
-Quasar applies `body--light` or `body--dark`, updates its dark-aware components, and tracks system changes while mode is automatic. Use the NiceGUI element instead of invoking Quasar's JavaScript Dark plugin directly. Persist an explicit user preference separately when it must survive navigation or a new browser session.
-
-### Add Semantic Tokens For Application Surfaces
-
-Quasar's brand roles cover framework components, not every application-specific surface. Define a small set of semantic CSS variables in the static stylesheet and change their values under Quasar's documented `.body--dark` class:
-
-```css
-:root {
-    --app-page: #f6f8f7;
-    --app-surface: #ffffff;
-    --app-text: #202623;
-    --app-border: #cbd4d0;
-}
-
-.body--dark {
-    --app-page: var(--q-dark-page);
-    --app-surface: var(--q-dark);
-    --app-text: #eef3f0;
-    --app-border: #46504b;
-}
-
-body {
-    background: var(--app-page);
-    color: var(--app-text);
-}
-
-.app-panel {
-    background: var(--app-surface);
-    border: 1px solid var(--app-border);
-}
-```
-
-Name tokens by purpose, such as `--app-surface` or `--app-muted-text`, rather than by a fixed color such as `--app-gray-100`. Reuse `--q-primary` and the other Quasar variables when the meaning matches. Check text, icon, border, focus, hover, disabled, positive, warning, and negative contrast in both modes; a palette is not complete merely because the page background changes.
+NiceGUI rows and columns provide component structure, while their `.classes(...)` values define the physical constraints. Prefer explicit Tailwind `p-*` and `gap-*` classes for local container spacing. NiceGUI's `--nicegui-default-padding` and `--nicegui-default-gap` variables, both `1rem` by default, are CSS-level exceptions for changing the framework-wide baseline rather than one container.
 
 ## Structural Styling With Tailwind
 
-Use standard [Tailwind utility classes](https://tailwindcss.com/docs/utility-first) for page and component structure:
+NiceGUI's `.classes()` method attaches Tailwind-compatible classes directly to the rendered element. The structural categories used most often are:
 
-- display, flex, and grid behavior
-- width, height, and maximum-width constraints
-- spacing, gaps, padding, and alignment
-- wrapping, overflow, and responsive variants
-- typography and common visual utilities when they fully express the design
+| Concern | Representative classes |
+| --- | --- |
+| display and tracks | `flex`, `grid`, `grid-cols-1`, `md:grid-cols-2` |
+| growth and shrinkage | `flex-1`, `grow`, `shrink-0`, `basis-*` |
+| dimensions | `w-full`, `h-full`, `min-w-0`, `max-w-6xl`, `size-10` |
+| spacing | `gap-4`, `px-4`, `py-6`, `mx-auto`, `space-y-3` |
+| alignment | `items-start`, `items-center`, `justify-between`, `self-stretch` |
+| wrapping and overflow | `flex-wrap`, `whitespace-nowrap`, `overflow-auto`, `truncate` |
+| positioning | `relative`, `absolute`, `sticky`, `inset-*`, `z-*` |
+| responsive changes | `md:flex-row`, `lg:grid-cols-3`, `xl:max-w-7xl` |
 
-Build the outer layout before fine-tuning individual controls:
-
-1. Define the page shell and width constraints.
-2. Establish responsive rows, columns, gaps, and wrapping.
-3. Add semantic sections and repeated visual patterns.
-4. Configure component appearance and behavior with constructor arguments and Quasar props.
-5. Add stable application classes for any remaining stylesheet rules.
+The [Tailwind width](https://tailwindcss.com/docs/width) and [maximum-width](https://tailwindcss.com/docs/max-width) references distinguish fixed spacing-scale widths, fractions, viewport units, and container-scale constraints. A centered shell normally combines its responsibilities explicitly:
 
 ```python
 with ui.column().classes("w-full max-w-6xl mx-auto gap-6 px-4"):
@@ -177,60 +76,126 @@ with ui.column().classes("w-full max-w-6xl mx-auto gap-6 px-4"):
         item_grid().classes("w-full flex-1 min-w-0")
 ```
 
-Use stable width, minimum-width, and flex constraints so labels, icons, validation messages, and loaded content do not shift the surrounding layout.
+`w-full` fills available inline space, `max-w-6xl` caps line and panel length, `mx-auto` centers the shell, and `px-4` retains edge space below the cap. Inside the row, `shrink-0` protects the sidebar and `min-w-0` allows the flexible content track to become narrower than its intrinsic content.
+
+Tailwind's [responsive variants](https://tailwindcss.com/docs/responsive-design) are mobile-first. Unprefixed classes apply at every size; `md:*` and larger prefixes apply from their minimum width upward. In NiceGUI's default Tailwind setup, verify available classes against the framework version bundled by the installed NiceGUI release. Optional [UnoCSS presets](https://nicegui.io/documentation/section_styling_appearance#unocss_engine) are intentionally not fully compatible with Tailwind, and Tailwind CSS layers are one documented difference.
 
 ### Combine Tailwind With Quasar Utilities Deliberately
 
-NiceGUI's `.classes()` accepts both Tailwind utilities and the CSS helpers bundled with Quasar. Keep Tailwind as the default for application layout and responsive structure, but use Quasar utilities when they express a Quasar-owned or framework-semantic concern more directly:
+NiceGUI's `.classes()` accepts both Tailwind utilities and CSS helpers bundled with Quasar. Assign each concern to one system:
+
+| Concern | Default owner | Examples |
+| --- | --- | --- |
+| Python element structure | NiceGUI | `ui.row`, `ui.column`, `ui.grid`, slot context managers |
+| Generic geometry and responsive layout | Tailwind | `w-full`, `items-center`, `justify-center`, `gap-2`, `p-6`, `flex-wrap` |
+| Generic application typography | Tailwind | `text-xl`, `font-medium`, `leading-6`, `truncate` |
+| Theme-aware semantic color | Quasar | `text-primary`, `bg-positive`, `text-grey-7` |
+| Component behavior and density | Quasar props | `dense`, `outlined`, `round`, `separator=horizontal` |
+| Component-specific geometry | Quasar helper classes | `q-table--col-auto-width`, `absolute-top-right` |
+
+Prefer the Tailwind spelling when both systems express ordinary application layout or typography. For example, use `w-full` instead of `full-width`, `items-center justify-center` instead of `flex-center`, `gap-2` instead of `q-gutter-sm`, `p-4` instead of `q-pa-md`, and `text-xl font-medium` instead of `text-h6 text-weight-medium`. This keeps spacing, breakpoints, and type choices in one vocabulary.
+
+Quasar helpers remain useful when a value intentionally follows Quasar's component conventions:
 
 - [`q-m*` and `q-p*` spacing classes](https://quasar.dev/style/spacing) when spacing should follow Quasar's component scale
 - [typography helpers](https://quasar.dev/style/typography), such as `text-h6`, `text-subtitle2`, and `text-weight-medium`, for text that should follow Quasar's type system
-- [color palette classes](https://quasar.dev/style/color-palette), such as `text-primary`, `bg-positive`, and `text-negative`, so semantic colors track the palette configured by `app.colors()` or `ui.colors()`
 - [visibility helpers](https://quasar.dev/style/visibility), such as `gt-sm` and `lt-md`, when visibility should use Quasar's configured breakpoints
 - [positioning helpers](https://quasar.dev/style/positioning), such as `absolute-top-right`, when positioning content relative to a Quasar component
+- [size and overflow helpers](https://quasar.dev/style/other-helper-classes), such as `fit`, `full-width`, and `overflow-auto`, when matching Quasar layout behavior
 
-Mix the two systems by concern, not by writing competing declarations for the same CSS property. For example, `w-full q-pa-md text-primary` uses Tailwind for width and Quasar for component-scale padding and semantic color. Do not combine `p-4` with `q-pa-md`, or Tailwind and Quasar visibility helpers, on the same element; their cascade order can make the result version-dependent and difficult to review.
+Do not assign the same property through both systems on one element. For example, `w-full q-pa-md` deliberately uses Tailwind for width and Quasar for component-scale padding; adding `p-4` would create competing padding declarations. The same rule applies to Tailwind and Quasar visibility helpers or to Tailwind font sizes and Quasar heading classes.
 
 ```python
 with ui.card().classes("w-full max-w-2xl q-pa-md"):
-    ui.label("Inventory summary").classes("text-h6 text-primary")
-    ui.label("Review required").classes("text-negative text-weight-medium")
+    ui.label("Inventory summary").classes("text-h6")
+    ui.label("12 locations").classes("text-subtitle2 text-weight-medium")
 ```
 
-Quasar utilities are global classes, so they need no Vue-specific translation before being passed to `.classes()`. Confirm the available helpers and breakpoints against the Quasar version bundled by the installed NiceGUI release.
+Tailwind and Quasar do not share breakpoint thresholds. Tailwind's defaults begin `sm` at `40rem` and `md` at `48rem`; Quasar defines `sm` from `600px` and `md` from `1024px`. Keep one breakpoint system responsible for a given layout transition, and confirm the bundled framework versions before relying on exact thresholds.
 
-## Fine Tuning With Static Stylesheets
+## CSS As A Last Resort
 
-Move stable fine tuning into a static stylesheet after the structure and native component configuration are correct. Static stylesheets provide reusable selectors, media queries, pseudo-classes, CSS variables, and a clear cascade that inline declarations cannot provide.
-
-Attach an application-owned class with `.classes()` or a Quasar popup prop, then scope stylesheet rules beneath it:
+Do not move stable geometry into a stylesheet simply because a Tailwind class string is long. Tailwind arbitrary values can express constraints such as `minmax(...)`, `min(...)`, aspect ratios, and dynamic viewport units while keeping the rule visible beside the Python structure that owns it.
 
 ```python
-ui.select(...).props("popup-content-class=app-item-menu").classes(
-    "app-item-select w-full md:max-w-md"
-)
+with ui.element("main").classes(
+    "grid min-h-0 "
+    "grid-cols-[minmax(14rem,20rem)_minmax(0,1fr)]"
+):
+    sidebar()
+    workspace().classes("min-w-0")
+
+ui.select(...).props(
+    'outlined popup-content-class="max-h-[min(24rem,60dvh)] overflow-y-auto"'
+).classes("w-full md:max-w-md")
 ```
 
-```css
-.app-item-select {
-    --app-field-accent: #176b5b;
-}
+Use `.style()` only when a value is calculated at runtime and no class or component property can represent it. Keep the override on the narrowest element and do not promote it to a shared stylesheet unless it becomes a genuine cross-component rule.
 
-.app-item-select:focus-within {
-    filter: drop-shadow(0 0 0.25rem rgb(23 107 91 / 20%));
-}
-
-.app-item-menu {
-    max-height: min(24rem, 60dvh);
-}
-```
-
-Use `.style()` when a value is calculated at runtime or while testing a local hypothesis. Once a declaration becomes stable or repeated, move it to the stylesheet and keep only the application class in Python.
+Static CSS remains appropriate for browser-level facilities such as `@font-face`, selectors or pseudo-elements with no available utility, and integration with markup that cannot receive classes. Attach an application-owned class through `.classes()` or a documented Quasar prop, then scope the exceptional rule beneath that class.
 
 Avoid overriding Quasar internals such as `.q-field__label`, `.q-field__native`, `.q-field__control`, and `.q-field__input` unless the public props, slots, and application-level selectors cannot express the requirement.
 
 Quasar coordinates field height, padding, labels, values, icons, and floating-label transforms. Changing only one internal part tends to cause clipping or overlap.
 
+## Fonts And Typography
+
+Typography affects physical layout because font metrics determine line breaks, control height, baseline alignment, and the intrinsic width of labels. Treat font loading and the type scale as structural dependencies rather than late decoration.
+
+### Font Families And Loading
+
+Tailwind provides `font-sans`, `font-serif`, and `font-mono`, and supports custom family utilities as documented by [Tailwind font family](https://tailwindcss.com/docs/font-family). Quasar's [typography reference](https://quasar.dev/style/typography) documents its embedded Roboto default and its heading, weight, alignment, wrapping, and case helpers.
+
+For an application-owned typeface, `@font-face` is one of the browser-level cases that warrants CSS. Mount the font with other static assets and declare it once in the shared stylesheet. [MDN `@font-face`](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face) recommends WOFF2 for modern web delivery; `font-display: swap` keeps text available while the resource loads.
+
+```css
+@font-face {
+    font-family: "App Sans";
+    src: url("/static/fonts/app-sans.woff2") format("woff2");
+    font-display: swap;
+    font-style: normal;
+    font-weight: 400 700;
+}
+
+.app-shell {
+    font-family: "App Sans", sans-serif;
+}
+```
+
+Include the real weight range supplied by the font file. Requesting an unavailable weight makes the browser synthesize it and can alter text width. Keep a fallback family so failed or delayed font requests do not leave text unavailable.
+
+### Type Size And Line Height
+
+Tailwind's [font-size utilities](https://tailwindcss.com/docs/font-size) pair named rem-based sizes such as `text-sm`, `text-base`, and `text-xl` with default line heights. Combined forms such as `text-sm/6` set size and line height together. Separate `leading-*`, `font-*`, and text-alignment utilities refine those dimensions.
+
+```python
+with ui.column().classes("w-full max-w-[65ch] gap-3"):
+    ui.label("Inventory summary").classes("text-2xl/8 font-semibold")
+    ui.label("Counts by location and storage area").classes("text-base/7")
+```
+
+Prefer a small named hierarchy over unrelated one-off sizes. Use `rem`-based utilities so browser font preferences and page zoom remain meaningful, and use a character-based maximum width such as `max-w-[65ch]` for long prose. Avoid viewport-width font sizing: text should reflow at narrow widths rather than shrink to preserve one line.
+
+`em` dimensions inherit and can compound through nested elements; `rem` dimensions refer to the root element and avoid that compounding. The [MDN font-size reference](https://developer.mozilla.org/en-US/docs/Web/CSS/font-size) describes both behaviors and recommends relative sizing for accessibility.
+
+## Scaling Boundaries
+
+The word "scale" can refer to different browser mechanics. They are not interchangeable:
+
+| Mechanism | Participates in layout | Appropriate use |
+| --- | --- | --- |
+| responsive classes and reflow | yes | normal page adaptation across available widths |
+| relative font and spacing units | yes | coherent type and spacing changes that respect browser settings |
+| browser zoom | yes, at the document level | user-controlled magnification that the page must tolerate |
+| CSS `zoom` | yes | exceptional magnification of a bounded region |
+| `transform: scale(...)` | no | transient visual emphasis or a deliberately overlaid preview |
+
+Responsive reflow through Python composition and Tailwind classes is the default for page structure. A narrower page should stack tracks, wrap controls, and retain readable text rather than shrink the entire interface.
+
+[CSS `zoom`](https://developer.mozilla.org/en-US/docs/Web/CSS/zoom) changes the size used by layout, so surrounding content is recalculated. [`transform: scale()`](https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/scale) changes only painting; neighboring elements retain the unscaled geometry, and enlarged content can overlap or overflow its box. Treat both as exceptional effects after responsive widths, gaps, and breakpoints have been exhausted.
+
+Stable fixed-format regions such as boards, diagrams, and previews need an explicit box before their contents scale. Combine `aspect-ratio`, a bounded inline size, and local overflow rules so transformed content cannot resize surrounding controls. Scaling animations should respect `prefers-reduced-motion`.
+
 ## Responsive Layout
 
 Support these layouts only:
@@ -239,7 +204,7 @@ Support these layouts only:
 - landscape desktop: $1920 \times 1080$ with side-by-side panels where they improve scanning
 - portrait desktop: $1080 \times 1920$ with stacked panels or a narrow fixed sidebar
 
-Build the mobile layout first, then add one desktop breakpoint when a row or grid needs more space. Prefer flex wrapping and fluid grids before adding another breakpoint. Use Tailwind classes for page layout and Quasar props for component behavior.
+Build the mobile layout first, then add one desktop breakpoint when a row or grid needs more space. Unprefixed Tailwind classes define the mobile baseline; breakpoint-prefixed classes alter it at larger widths. Prefer flex wrapping and fluid grids before adding another breakpoint. Use Tailwind classes for page layout and Quasar props for component density and behavior.
 
 ```python
 with ui.row().classes("w-full flex-wrap gap-4 lg:flex-nowrap items-start"):
@@ -249,12 +214,15 @@ with ui.row().classes("w-full flex-wrap gap-4 lg:flex-nowrap items-start"):
 
 Use `min-w-0` for flexible children, `flex-wrap` for toolbars, and `max-w-* mx-auto` to keep portrait layouts readable. Do not add device-specific component trees, container queries, or custom breakpoints unless a supported layout demonstrates a concrete failure.
 
-## Loading Stylesheets And Static Assets
+Height needs an explicit ownership chain. `h-full` only resolves when the containing block has a definite height; viewport-bound workspaces usually need a defined outer height and `min-h-0` on nested flex or grid tracks before an inner `overflow-auto` region can scroll. Prefer dynamic viewport units such as `dvh` for browser UI that changes the visible mobile viewport.
 
-- Mount and link static stylesheets once from the composition layer rather than injecting CSS from individual pages.
-- Keep custom CSS tokenized with variables and scoped to application classes.
+## Loading Exceptional CSS And Static Assets
+
+- Keep ordinary layout and typography in Python mechanics and Tailwind classes rather than creating a stylesheet.
+- When exceptional CSS is required, mount and link it once from the composition layer rather than injecting it from individual pages.
+- Keep custom dimensions and font families in named variables or application classes.
 - Avoid broad rules against Quasar internals.
-- Mount referenced assets in the composition layer.
+- Mount referenced stylesheets, fonts, and other assets in the composition layer.
 - Verify mount paths, reverse-proxy rewrites, and cache behavior.
 
 ```python
@@ -283,23 +251,29 @@ Check each completed page at these three viewports:
 2. Landscape desktop at $1920 \times 1080$.
 3. Portrait desktop at $1080 \times 1920$.
 
-Confirm that page sections do not overlap, toolbars wrap on mobile, desktop panels use the available space without becoming excessively wide, and dialogs remain visible and scroll to their final field.
+Confirm that page sections do not overlap, toolbars wrap on mobile, desktop panels use the available space without becoming excessively wide, and dialogs remain visible and scroll to their final field. Repeat the checks with browser zoom or text enlargement, a delayed font request, long labels, validation messages, and loaded content. Watch for unexpected page-level horizontal scrolling, nested scroll regions, clipped focus outlines, and layout shifts when the webfont replaces its fallback.
 
 ## Sources
 
 !!! info "Primary sources"
     - [NiceGUI element styling and props](https://nicegui.io/documentation/element)
     - [NiceGUI binding properties](https://nicegui.io/documentation/section_binding_properties)
-    - [NiceGUI color theming](https://nicegui.io/documentation/colors)
-    - [NiceGUI dark mode](https://nicegui.io/documentation/dark_mode)
+    - [NiceGUI styling and appearance](https://nicegui.io/documentation/section_styling_appearance)
     - [Quasar components](https://quasar.dev/vue-components)
     - [Quasar spacing classes](https://quasar.dev/style/spacing)
     - [Quasar typography helpers](https://quasar.dev/style/typography)
+    - [Quasar breakpoints](https://quasar.dev/style/breakpoints)
     - [Quasar visibility helpers](https://quasar.dev/style/visibility)
     - [Quasar positioning helpers](https://quasar.dev/style/positioning)
-    - [Quasar color palette and runtime brand variables](https://quasar.dev/style/color-palette)
-    - [Quasar dark mode](https://quasar.dev/style/dark-mode)
+    - [Quasar size and overflow helpers](https://quasar.dev/style/other-helper-classes)
     - [Quasar field](https://quasar.dev/vue-components/field/)
     - [Quasar select](https://quasar.dev/vue-components/select/)
+    - [Tailwind width utilities](https://tailwindcss.com/docs/width)
+    - [Tailwind maximum-width utilities](https://tailwindcss.com/docs/max-width)
+    - [Tailwind font-family utilities](https://tailwindcss.com/docs/font-family)
+    - [Tailwind font-size utilities](https://tailwindcss.com/docs/font-size)
     - [Tailwind responsive design](https://tailwindcss.com/docs/responsive-design)
-    - [MDN `zoom`](https://developer.mozilla.org/en-US/docs/Web/CSS/zoom)
+    - [MDN `@font-face`](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face)
+    - [MDN `font-size`](https://developer.mozilla.org/en-US/docs/Web/CSS/font-size)
+    - [MDN `zoom`](https://developer.mozilla.org/en-US/docs/Web/CSS/zoom)
+    - [MDN `scale()`](https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/scale)

src/personal_mcp/docs/skills/nicegui/references/tabbed-subpages.md

@@ -0,0 +1,101 @@
+# URL-Backed Tabs with Sub Pages
+
+The [`tab_spa.py` example](../examples/tab_spa.py) combines [NiceGUI tabs](https://nicegui.io/documentation/tabs) with [sub-page routing](https://nicegui.io/documentation/sub_pages). It keeps one application shell and one set of tab panels mounted while the browser URL identifies the active view.
+
+The example targets NiceGUI `3.16.0`. In this design, tabs are the visible navigation and content mechanism; `ui.sub_pages` is a URL-matching adapter whose route builders update the tab state instead of rendering route content inside the router.
+
+## Responsibility Map
+
+| Surface | Responsibility |
+| --- | --- |
+| `root()` | Creates one client-local shell, reads the initial URL, and connects the tabs, panels, and router. |
+| `ui.tabs` | Holds the selected tab name and emits user selection changes. |
+| `ui.tab_panels` | Displays the panel whose name matches the selected tab. |
+| `ui.sub_pages` | Matches URL paths, extracts route parameters, and invokes the corresponding route callback without a full page reload. |
+| `NavigationState` | Retains the concrete report path represented by the shared `reports` tab. |
+| `ui.navigate.to()` | Changes the browser location so the sub-pages router can resolve the destination. |
+
+The separation matters because a tab name is not always a URL. Static tabs use their route as their name, but every `/reports/{report_id}` URL maps to the single `reports` tab and panel.
+
+## Route and Panel Mapping
+
+| Browser path | Tab value | Panel value | Route callback effect |
+| --- | --- | --- | --- |
+| `/` | `/` | `/` | Selects the overview panel. |
+| `/projects` | `/projects` | `/projects` | Selects the projects panel. |
+| `/reports/a` | `reports` | `reports` | Stores `/reports/a` and selects the reports panel. |
+| `/reports/b` | `reports` | `reports` | Stores `/reports/b` and selects the reports panel. |
+| `/settings` | `/settings` | `/settings` | Selects the settings panel. |
+
+`tab_name_for_route()` is the translation boundary. It preserves static route names, collapses concrete report routes to `reports`, and returns `/` for other paths.
+
+## Initial Page Construction
+
+`root()` reads `ui.context.client.sub_pages_router.current_path` before creating the navigation controls. `normalize_route()` removes query strings, fragments, and trailing slashes so `/projects/` and `/projects` select the same tab.
+
+For a direct request to `/reports/b`, the initial route produces two values:
+
+- `active_report_path` becomes `/reports/b`.
+- the selected tab and panel become `reports`.
+
+The initial `tabs.set_value(...)` call occurs before `tabs.on_value_change(navigate)` is registered. Initial selection therefore establishes the shell state without treating page construction as a user navigation. Passing the same initial tab value to `ui.tab_panels` aligns the content container with the tabs from the first render.
+
+All panel builders run during shell construction. Switching tabs changes the selected panel; it does not rerun `overview_page()`, `projects_page()`, `report_page()`, or `settings_page()`. Their element state remains client-local for the lifetime of that shell.
+
+## Tab-Originated Navigation
+
+The tab change handler receives the selected tab name. Static tab names are already destinations. The reports tab resolves through `state.active_report_path`, which supplies the last concrete report URL:
+
+```python
+destination = state.active_report_path if tabname == REPORTS_TAB else tabname
+ui.navigate.to(destination)
+```
+
+[`ui.navigate.to()`](https://nicegui.io/documentation/navigate) performs the route transition. The sub-pages router then matches the new location and invokes a callback that selects the corresponding tab. Because the panel container is associated with `tabs`, the visible panel follows that selected value.
+
+## URL-Originated Navigation
+
+The route callbacks contain no page markup. They translate router matches back into the visible state:
+
+```python
+def route_reports(report_id: str) -> None:
+    state.active_report_path = f"/reports/{report_id}"
+    tabs.set_value(REPORTS_TAB)
+```
+
+This direction handles direct links and browser back or forward navigation. A URL such as `/reports/b` supplies `report_id="b"`; the callback reconstructs the normalized concrete path, updates report-bound labels through `NavigationState`, and selects the shared reports panel.
+
+The router element is hidden because it is not the content container in this example:
+
+```python
+ui.sub_pages(routes).classes("hidden")
+```
+
+Normally, `ui.sub_pages` clears and rebuilds its own children when a route changes. Here its builders only mutate state outside that container, so hiding the empty routing element does not hide the tab-panel content.
+
+## Parameterized Report State
+
+`NavigationState.active_report_path` separates tab identity from route identity. The reports tab always has the stable value `reports`, while the state records `/reports/a`, `/reports/b`, or another matched report route.
+
+This provides two forms of continuity:
+
+- A direct report URL selects the correct tab and report during initial construction.
+- Leaving the reports tab and selecting it again during the same client lifetime returns to the last visited report.
+
+The state is page-local, not durable storage. Reloading a non-report URL creates a new `NavigationState` and restores `DEFAULT_REPORT_PATH`. Shareable report identity remains durable because report pages encode it in the URL.
+
+## Behavioral Boundaries
+
+- `TAB_ROUTES` contains concrete routes whose path and tab identity are the same. Parameterized route families require a stable synthetic tab name such as `reports`.
+- `normalize_route()` intentionally ignores query parameters and fragments for tab selection. Route callbacks would need matching parameters if those values affected panel state.
+- The hidden router also hides its built-in 404 output. As written, an unmatched path selects the overview panel through `tab_name_for_route()` while the router's not-found content remains invisible.
+- Panels are mounted together, so expensive panel construction still occurs during the initial shell build. Lazy or route-specific construction requires a different content ownership model.
+- The pattern preserves the shell only for navigation handled by the current `ui.sub_pages` router. A full reload creates a new client and rebuilds all page-local state.
+
+## Source Index
+
+!!! info "NiceGUI sources"
+    - [Sub pages and URL parameters](https://nicegui.io/documentation/sub_pages)
+    - [Tabs, tab names, and tab panels](https://nicegui.io/documentation/tabs)
+    - [Navigation and browser history](https://nicegui.io/documentation/navigate)
+    - [NiceGUI `3.16.0` sub-pages implementation](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/elements/sub_pages.py)

src/personal_mcp/docs/skills/nicegui/references/table-customization.md

@@ -0,0 +1,412 @@
+# Table Customization
+
+Use this reference when a [`ui.table`](https://nicegui.io/documentation/table) needs presentation, controls, responsive behavior, or custom cell content while retaining [Quasar QTable](https://quasar.dev/vue-components/table) sorting, filtering, pagination, and selection behavior. Use [editable tables](./tables.md) instead when browser-originated cell values must be validated and committed by Python.
+
+## Version Baseline
+
+This reference and its runnable example were verified against this bundled stack:
+
+| Layer | Version | Evidence |
+| --- | --- | --- |
+| NiceGUI | `3.16.0` | [Tagged `Table` source](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/elements/table.py) |
+| Quasar | `2.18.5` | [NiceGUI frontend dependencies](https://github.com/zauberzeug/nicegui/blob/v3.16.0/package.json) |
+| Vue | `3.5.22` | [NiceGUI frontend dependencies](https://github.com/zauberzeug/nicegui/blob/v3.16.0/package.json) |
+
+Recheck the tagged NiceGUI sources and bundled dependencies for another release. The current Quasar documentation may describe features added after NiceGUI's bundled Quasar version.
+
+## Choose The Narrowest Layer
+
+Apply customization at the highest-level API that expresses it:
+
+1. Use `ui.table(...)` for rows, columns, defaults, stable row identity, title, selection, and pagination.
+2. Use column definitions for alignment, sorting, formatting, cell classes, header classes, and width hints.
+3. Use `.props(...)` for QTable behavior that the NiceGUI constructor does not expose, such as `dense`, `separator`, `wrap-cells`, `rows-per-page-options`, and empty-state labels.
+4. Use named slots for custom toolbar content, one special header or cell, loading, no-data content, or pagination controls.
+5. Use a full `header`, `body`, or `item` slot only when the whole generated structure must change.
+6. Add narrowly scoped CSS for behavior that neither component API covers, such as sticky columns.
+
+NiceGUI's tagged [table client wrapper](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/elements/table.js) passes props to QTable and forwards every supplied slot with its scoped properties. This makes QTable's API the source of truth below the NiceGUI wrapper, but it does not make every current QTable feature compatible with the bundled `2.18.5` release.
+
+## Columns Before Slots
+
+A QTable column is both a data projection and a presentation contract. Keep its `name` unique because sorting and `body-cell-[name]` slot selection use it. `field` identifies or computes the raw cell value; it does not need to match the column name.
+
+```python
+columns = [
+    {
+        "name": "available",
+        "label": "In stock",
+        "field": "stock",
+        "sortable": True,
+        "align": "right",
+    },
+]
+
+table = ui.table(
+    rows=rows,
+    columns=columns,
+    column_defaults={"headerClasses": "text-grey-8"},
+    row_key="id",
+)
+```
+
+Use plain keys such as `classes`, `style`, `headerClasses`, and `headerStyle` for static values. NiceGUI's client-side dynamic-property conversion recognizes colon-prefixed keys such as `:field`, `:format`, `:sort`, `:classes`, and `:style` as JavaScript expressions. Keep row data JSON-serializable; format display values in a column or slot rather than putting component objects in rows.
+
+### Raw Values And Cosmetic Display Formatting
+
+Use the column's `format(value, row)` function when only the displayed cell text should change. QTable's tagged [`getCellValue`](https://github.com/quasarframework/quasar/blob/quasar-v2.18.5/ui/src/components/table/QTable.js) resolves `field` first and then passes that raw value through `format`. The formatted result is used by the default cell renderer and exposed to `body-cell-*` slots as `props.value`.
+
+Keep the layers distinct:
+
+| Layer | Owns | Effect |
+| --- | --- | --- |
+| row value | canonical JSON-serializable data sent by Python | remains available as `props.row.<field>` |
+| `field` | raw value extraction or derivation | supplies sorting and the input to `format` |
+| `format` | cosmetic text projection | changes default rendering, `props.value`, and local default-filter matching |
+| `body-cell-*` slot | component structure around the value | use for badges, icons, links, controls, or multiple elements |
+
+Formatting does not mutate `table.rows` or the row object. QTable's tagged [sorting implementation](https://github.com/quasarframework/quasar/blob/quasar-v2.18.5/ui/src/components/table/table-sort.js) compares raw `field` values, while its tagged [default filter](https://github.com/quasarframework/quasar/blob/quasar-v2.18.5/ui/src/components/table/table-filter.js) searches the formatted values returned by `getCellValue`. This is usually desirable: numbers sort numerically while users can search what they see.
+
+#### Prefix And Suffix Text
+
+Use a null-safe `:format` expression for simple prefix or suffix text:
+
+```python
+columns = [
+    {
+        "name": "price",
+        "label": "Unit price",
+        "field": "price",
+        "sortable": True,
+        ":format": "value => value == null ? '' : `$${value.toFixed(2)}`",
+    },
+    {
+        "name": "stock",
+        "label": "In stock",
+        "field": "stock",
+        "sortable": True,
+        ":format": "value => value == null ? '' : `${value} units`",
+    },
+]
+```
+
+The underlying values stay numeric, so sorting remains numeric. Check `value == null` rather than `if (!value)` when zero is valid; `0` must render as `$0.00` or `0 units`, not as an empty cell. Use a named cell slot instead when the prefix or suffix needs separate styling, an icon, a tooltip, or accessible text that differs from the visible text.
+
+#### Datetime Text
+
+Send datetimes as ISO 8601 strings with an explicit offset. Python's [`datetime.isoformat()`](https://docs.python.org/3/library/datetime.html#datetime.datetime.isoformat) includes an offset for aware values, and [`astimezone()`](https://docs.python.org/3/library/datetime.html#datetime.datetime.astimezone) preserves the represented instant while converting zones:
+
+```python
+from datetime import UTC, datetime
+
+updated_at = datetime.now(UTC)
+row = {"updated_at": updated_at.astimezone(UTC).isoformat()}
+```
+
+Avoid locale-formatted strings and naive datetime strings as transport values. JavaScript guarantees support for its standard ISO date-time format, but [date-time strings without an offset](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse) are interpreted in the browser's local timezone when they contain both a date and time. An explicit `Z` or `+00:00` identifies the instant unambiguously.
+
+For repeated cells, construct one [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) and return a formatter closure. NiceGUI evaluates the colon-prefixed expression into the column function, so the formatter is reused instead of performing locale-data lookup for every cell:
+
+```python
+columns = [
+    {
+        "name": "updated_at",
+        "label": "Updated",
+        "field": "updated_at",
+        "sortable": True,
+        ":sort": "(left, right) => Date.parse(left) - Date.parse(right)",
+        ":format": """(() => {
+            const formatter = new Intl.DateTimeFormat('en-US', {
+                dateStyle: 'medium',
+                timeStyle: 'short',
+                timeZone: 'UTC',
+            });
+            return value => {
+                if (!value) return '';
+                const timestamp = Date.parse(value);
+                return Number.isNaN(timestamp) ? 'Invalid date' : formatter.format(timestamp);
+            };
+        })()""",
+    },
+]
+```
+
+Choose locale and timezone deliberately:
+
+- Use a fixed locale such as `en-US` when the product requires one stable language convention; use `undefined` to follow the browser's locale.
+- Set `timeZone` to `UTC` or an IANA zone such as `America/New_York` for deterministic product behavior; omit it only when each viewer should see browser-local time.
+- Keep invalid-value handling explicit. `Date.parse()` returns `NaN` for an invalid value, while passing an invalid date directly to the formatter can throw.
+
+Sorting still receives the raw ISO value from `field`; it never compares the formatted label. The explicit `:sort` function above converts those raw strings to epoch milliseconds, so values with different offsets are ordered by instant while cells keep their localized display text. Validate datetime strings before sending them because an invalid value makes `Date.parse()` return `NaN`. For a simpler data contract, send epoch milliseconds as the field value and format that number directly.
+
+Lexicographic sorting without a custom `sort` function is chronological only when every ISO string uses the same fixed-width representation and offset, as in normalized UTC values. Local filtering is intentionally different: it matches the formatted text, so searches follow the chosen locale and timezone rather than the raw ISO string.
+
+### Cell Classes And Styles
+
+Quasar's tagged [`table-column-selection.js`](https://github.com/quasarframework/quasar/blob/quasar-v2.18.5/ui/src/components/table/table-column-selection.js), [`QTh.js`](https://github.com/quasarframework/quasar/blob/quasar-v2.18.5/ui/src/components/table/QTh.js), and [`QTd.js`](https://github.com/quasarframework/quasar/blob/quasar-v2.18.5/ui/src/components/table/QTd.js) establish the exact targets:
+
+| Column key | Applied to | Static or dynamic | Typical uses |
+| --- | --- | --- | --- |
+| `headerClasses` | The generated `<th>` for this column | Static string | Header color, weight, whitespace, sticky positioning, utility-based width |
+| `classes` | Every generated `<td>` in this column | String or function of `row` | Body typography, whitespace, conditional color, utility-based width |
+| `headerStyle` | Inline `style` on the generated `<th>` | Static string | Header-specific dimensions or positioning |
+| `style` | Inline `style` on every generated `<td>` | String or function of `row` | Body dimensions, overflow, or row-dependent presentation |
+
+`align` is separate: Quasar prepends `text-left`, `text-right`, or `text-center` to both header and body classes. It also appends header state classes such as `sortable`, `sorted`, and `sort-desc`. Supplying `classes` or `headerClasses` does not remove those generated classes.
+
+These fields interact through normal CSS rules:
+
+- On the same cell, inline `style` normally wins over a conflicting class declaration. A class rule containing `!important` can beat a normal inline declaration; avoid building a width policy around that exception.
+- The order of class names in the `class` attribute does not decide precedence. CSS origin, importance, cascade layer, selector specificity, and stylesheet source order do.
+- `headerClasses` never flows into body cells, and `classes` never flows into the header. The same separation applies to `headerStyle` and `style`.
+- `column_defaults` is merged as `{**defaults, **column}`. A column-level value replaces the complete default value for that key; class strings are not concatenated. Include shared classes again in an overriding column value when they must be retained.
+- A named `header-cell-*` or `body-cell-*` slot replaces QTable's default cell renderer. Use `table.header(column_name)` or `table.cell(column_name)` so Quasar reapplies the computed column classes and styles to the resulting `QTh` or `QTd`.
+
+Prefer classes for reusable visual policy and static utility classes. Prefer `headerStyle` and `style` for one-off values, especially dimensions that do not have a clear project utility. Use `:classes` or `:style` only when the value genuinely depends on the browser-side row; otherwise a static value is easier to inspect and override.
+
+### Column Width Model
+
+QTable renders a native table with `width: 100%`, `max-width: 100%`, and, by default, the browser's [`table-layout: auto`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/table-layout) algorithm. One column is a shared track: its header and all body cells receive the same final used width even though each cell can contribute a different width constraint.
+
+This has several consequences:
+
+1. A `width` in `headerStyle` and a different `width` in `style` do not override each other because they are declarations on different elements. The browser considers both, along with every cell's min-content and max-content size, and computes one column width.
+2. Under automatic layout, `width` is a strong sizing input, not a guaranteed cap. Long unbreakable content, cell padding, other columns, and the table's available width can make the column wider.
+3. `min-width` supplies a floor. `max-width` alone is not a dependable truncation mechanism for an automatic table because intrinsic content still participates in track sizing.
+4. QTable is `nowrap` by default through `q-table--no-wrap`. The `wrap-cells` prop removes that rule, allowing ordinary wrapping and reducing columns toward their min-content widths. For IDs or URLs, add [`overflow-wrap: anywhere`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/overflow-wrap) to create breaks inside otherwise unbreakable strings.
+5. Cell padding contributes to the track width. QTable uses `16px` horizontal padding per side normally and `8px` in dense mode, with larger edge padding retained for the first and last columns.
+
+Use the following mechanisms in order:
+
+| Goal | Recommended mechanism |
+| --- | --- |
+| Let content choose sensible widths | Leave `style` and `headerStyle` unset; keep automatic layout |
+| Keep a column from becoming too narrow | Put the same absolute `min-width` in `style` and `headerStyle` |
+| Give columns proportional targets | Put matching percentage `width` values in `style` and `headerStyle`; treat them as targets under automatic layout |
+| Keep utility or action cells compact | Use `auto-width` on `table.header(...)` and `table.cell(...)` in slots, or Quasar's `q-table--col-auto-width` class on both header and body; it sets `width: 1px` and content supplies the floor |
+| Allow readable narrow layouts | Enable `wrap-cells`, set a practical `min-width` for key columns, and let QTable's middle container scroll horizontally when the total minimum exceeds the viewport |
+| Guarantee a column allocation | Use fixed table layout, an explicit table width, matching first-row/header widths, and an explicit overflow policy |
+| Truncate text | Use a fixed/constrained track plus a block wrapper with Tailwind's `truncate` utility; [`text-overflow`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/text-overflow) does not create overflow by itself |
+
+For ordinary data tables, automatic layout plus a few minimum or target widths is the idiomatic default. Apply matching values to `headerStyle` and `style`: one declaration is often enough to influence the shared track, but matching declarations make intent explicit, survive empty datasets, and keep custom header/body renderers consistent.
+
+Use fixed layout only when predictable allocation matters more than content-driven sizing. QTable's `table-style` prop styles the scrolling wrapper `<div>`, not the nested native `<table>`, so it cannot set `table-layout`. This nested element cannot receive a utility class through NiceGUI or QTable's public API, making one application class and one scoped CSS rule necessary. Keep truncation on a Python-created wrapper with Tailwind's `truncate` utility:
+
+```python
+ui.add_css("""
+.inventory-table .q-table {
+    table-layout: fixed;
+}
+""")
+
+table = ui.table(rows=rows, columns=columns).classes("inventory-table w-full")
+
+with table.add_slot("body-cell-name"), table.cell("name"):
+    ui.element("span").props(':textContent="props.value"').classes("block truncate")
+```
+
+With fixed layout, the table must have a non-automatic width; QTable already gives its native table `width: 100%`, while `w-full` constrains the NiceGUI element. The first row's explicit widths determine tracks without a `<colgroup>`; later body content does not resize them and therefore needs wrapping, clipping, or scrolling. A full custom header changes that first-row contract, so retest every column after introducing one.
+
+Column visibility has two useful patterns:
+
+- Mark identity or action columns `required` when they must remain visible.
+- For a Python-owned column picker, assign the selected column names to `table.props["visible-columns"]`, then call `table.update()`. QTable automatically includes columns marked `required`. Assign the Python list directly to the prop rather than interpolating it into a JavaScript expression.
+
+## QTable Props
+
+Pass static QTable props as whitespace-delimited tokens. Prefix a prop with `:` only when its value is a JavaScript expression:
+
+```python
+table.props(
+    'flat bordered separator=horizontal wrap-cells '
+    ':dense="Quasar.Screen.lt.md" '
+    ':rows-per-page-options="[5, 10, 0]"'
+)
+```
+
+Use static props for fixed component policy and dynamic props for small browser-owned presentation decisions such as responsive density. Keep authoritative business state and permission decisions in Python.
+
+Useful QTable presentation props include:
+
+| Need | Props |
+| --- | --- |
+| Surface | `flat`, `bordered`, `square`, `dark`, `color` |
+| Cell layout | `dense`, `separator`, `wrap-cells` |
+| Layers | `hide-header`, `hide-bottom`, `hide-pagination`, `hide-no-data` |
+| Labels | `no-data-label`, `no-results-label`, `loading-label`, `rows-per-page-label` |
+| Paging and sorting | `rows-per-page-options`, `binary-state-sort`, `column-sort-order` |
+| Large local datasets | `virtual-scroll`, `virtual-scroll-item-size`, `virtual-scroll-sticky-size-start` |
+
+Virtual scrolling needs a bounded height and accurate row-size assumptions. If a full `body` slot renders multiple `QTr` elements for one data row, follow Quasar's `q-virtual-scroll--with-prev` and unique-key requirements. Do not enable virtual scrolling as a default for a small table.
+
+## Named Slots
+
+Prefer the smallest QTable slot that owns the customization:
+
+| Slot | Use |
+| --- | --- |
+| `top-left`, `top-right` | Title, filters, column controls, export |
+| `header-cell-[name]` | One custom header while preserving other generated headers |
+| `body-cell-[name]` | One custom cell type while preserving generated rows and other cells |
+| `no-data`, `loading` | Empty, filtered-empty, and busy states |
+| `pagination` | Custom page controls |
+| `footer` | A real table footer such as totals |
+
+Since NiceGUI `3.5.0`, a scoped slot can contain NiceGUI elements. Follow the [Python-owned slot composition](./component-mechanics.md#prefer-python-owned-composition) rule: use context managers and NiceGUI elements for structure, keep application logic in Python, and reserve dynamic props for scoped values that exist only in the browser. Wrap body-cell content in `table.cell(column_name)` so QTable retains the column's alignment and cell semantics:
+
+```python
+STATUS_COLORS = {
+    "Ready": "positive",
+    "Low": "warning",
+    "Backorder": "negative",
+}
+
+columns = [
+    {
+        "name": "status",
+        "label": "Status",
+        "field": "status",
+        "colorByValue": STATUS_COLORS,
+    },
+]
+
+with table.add_slot("body-cell-status"), table.cell("status"):
+    ui.badge().props(
+        ':label="props.value" '
+        ':color="props.col.colorByValue[props.value] ?? \'grey\'"'
+    )
+```
+
+Inside table slots, `props.value` is the parsed and formatted cell value, `props.row` is the row object, and `props.col` is the column definition. Custom JSON-serializable column keys such as `colorByValue` therefore provide a clean bridge from Python-owned display policy to a reused browser-side slot. Use Quasar color names in the mapping when the component's `color` prop should follow the active theme, and include a fallback for unexpected values.
+
+A slot template is reused for every matching row, so `props.value`, `props.row`, and `props.col` are JavaScript expressions, not Python variables. Keep authorization and business-state decisions out of this mapping; it is client-visible presentation metadata.
+
+### Add A Button To A Cell
+
+Add an action column to the table's column definitions, then target it with the corresponding `body-cell-[name]` slot. Use a NiceGUI `ui.button` rather than writing a raw QBtn template, and wrap it in `table.cell(column_name)` so QTable preserves the cell's alignment, classes, styles, and table semantics.
+
+The slot's `props.key` is the primitive identity derived from the table's `row_key`. Forward that key to Python instead of sending the full browser-side row object. Resolve the current authoritative row again in the handler because the record may have changed or disappeared since the table was rendered:
+
+```python
+from nicegui import events
+from nicegui import ui
+
+columns = [
+    {"name": "actions", "label": "Actions", "required": True, "align": "center"},
+    {"name": "name", "label": "Product", "field": "name", "align": "left"},
+]
+rows = [
+    {"id": 101, "name": "Desk lamp"},
+    {"id": 102, "name": "Task chair"},
+]
+
+table = ui.table(rows=rows, columns=columns, row_key="id")
+
+def open_product(event: events.GenericEventArguments) -> None:
+    product = next((row for row in table.rows if row[table.row_key] == event.args), None)
+    if product is None:
+        ui.notify("Product no longer exists", type="negative")
+        return
+    ui.notify(f"Opening {product['name']}")
+
+with (
+    table.add_slot("body-cell-actions"),
+    table.cell("actions"),
+    ui.button(icon="open_in_new")
+    .props("round flat size='sm'")
+    .on(
+        "click.stop",
+        handler=open_product,
+        js_handler="() => emit(props.key)",
+    ),
+):
+    ui.tooltip("Open product")
+```
+
+The compact icon-only button uses QBtn's `round`, `flat`, and `size` props to avoid a visually heavy filled action in every row. Nest `ui.tooltip` inside the button so each row's cloned QTooltip uses its own parent as the target. Do not call `action_button.tooltip(...)` in a reused scoped slot: NiceGUI implements that convenience method with an element-ID target, and every clone would resolve to the first button. The `.on(...)` bridge is necessary here because `props.key` exists only in the reused browser-side slot scope; a normal Python `on_click` callback cannot capture a different row for each rendered instance. The `click.stop` modifier prevents the button click from also reaching a row-click handler. Treat the key as untrusted input and repeat authorization, existence, and state checks before performing the real action.
+
+Replacing the full `body` or `header` slot also replaces behavior QTable would otherwise generate. Render `QTr` plus `QTd` or `QTh`, pass the scoped props through, preserve unique row keys, and retest sorting, selection, focus, and responsive behavior. In particular, QTable row-click events are not emitted when a full `body`, `row`, or `item` slot owns the structure.
+
+## Toolbar Search
+
+NiceGUI controls can live in QTable toolbar slots. Bind an input's value one way to the table's `filter` property for a small, local dataset:
+
+```python
+with table.add_slot("top-right"):
+    ui.input(placeholder="Search inventory").props(
+        "dense outlined clearable debounce=250"
+    ).bind_value_to(table, "filter")
+```
+
+The path from keystroke to displayed rows is:
+
+1. `debounce=250` waits until input has been idle for 250 milliseconds, reducing value-change traffic while the user types.
+2. `bind_value_to(table, "filter")` immediately initializes `table.filter` from the input and then propagates later input values in that direction only.
+3. For local rows, QTable lowercases the search term and each computed cell value. A row remains when at least one column value contains the term as a substring.
+4. QTable filters first, sorts the matching rows, resets pagination to page 1 when the filter changes, and then slices the current page.
+5. When no row matches, the `no-data` slot receives the configured `no-results-label` as `message` and a truthy `filter`; when the underlying row list is empty without a filter, it receives `no-data-label` and a falsy `filter`.
+
+The default matcher uses each column's resolved `field` and then its `format` function. In this example, searches can therefore match displayed values such as `Hardware`, `Backorder`, or `$31.25`; the row ID is not searchable because it has no column. QTable passes its computed columns to the matcher, so a column excluded with the `visible-columns` prop is not searched. Hiding a column with CSS classes would leave it in the search set and should not be used as a substitute for the component prop.
+
+This is client-side filtering over rows already sent to the browser. Do not load a large dataset merely to search it locally. When pagination contains `rowsNumber`, QTable switches to server-side mode, stops applying its local matcher, and emits a `request` carrying the filter and pagination state; validate the term and query the authoritative data source in that handler. Add explicit backend search semantics for field scope, tokenization, locale, and ranking instead of assuming they match QTable's substring behavior.
+
+When Python needs the browser's current result set, prefer `await table.get_filtered_sorted_rows()` for all matches before pagination or `await table.get_computed_rows()` for the current page. These helpers require a connected client and should not replace backend filtering for server-owned data.
+
+Prefer typed table helpers over raw frontend calls. Use `table.run_method(...)` only for QTable methods without a NiceGUI helper, such as `scrollTo`, `sort`, or `firstPage`, and verify the method in the bundled QTable API first.
+
+## Runnable Example
+
+The complete example combines raw-value sorting with cosmetic prefix, suffix, and datetime formatting; column defaults; responsive QTable props; filtering; column visibility; a toolbar; custom status and action cells; and a filtered-empty state. It is available as [`table_customization.py`](../examples/table_customization.py) and as `skill://nicegui/examples/table_customization.py`.
+
+```python title="table_customization.py"
+--8<-- "docs/skills/nicegui/examples/table_customization.py"
+```
+
+Run it from the repository root:
+
+```bash
+uv run src/personal_mcp/docs/skills/nicegui/examples/table_customization.py
+```
+
+Verify that stock and price sort by their numeric row values while displaying suffix and prefix text. Verify that updated timestamps sort chronologically by their raw ISO values while displaying localized UTC text. Confirm that searches are case-insensitive, match formatted values across columns, reset to the first page, and change the empty-state message when no rows match. Confirm that optional columns can be hidden and restored, the status cell retains its alignment and badge styling, and each action button reports the product from its own row. Hover action buttons in multiple rows and confirm that each one independently shows exactly one `Open product` tooltip. Resize the browser across mobile, landscape desktop, and portrait desktop widths; the toolbar must remain usable and the table must scroll without overlapping controls.
+
+## Escalation Boundaries
+
+- For editable cells, stable row identity, proposal validation, and canonical refresh, use [editable tables](./tables.md).
+- For generic scoped-slot values, event forwarding, and model events, use [component mechanics](./component-mechanics.md).
+- For page width, overflow, typography, and static CSS loading, use [page structure, typography, and scaling](./styling-and-customization.md).
+- For theme colors and dark mode, use [NiceGUI and Quasar color theming](./colors-and-quasar-theming.md).
+
+## Source Index
+
+!!! info "Primary documentation"
+    - [NiceGUI table documentation](https://nicegui.io/documentation/table)
+    - [Quasar QTable documentation](https://quasar.dev/vue-components/table)
+    - [Python aware and naive datetimes](https://docs.python.org/3/library/datetime.html#aware-and-naive-objects)
+    - [JavaScript `Date.parse()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse)
+    - [JavaScript `Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat)
+    - [CSS table layout algorithm](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/table-layout)
+    - [CSS width sizing](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/width)
+
+!!! info "NiceGUI `3.16.0` implementation"
+    - [`Table` Python source](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/elements/table.py)
+    - [Table client wrapper](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/elements/table.js)
+    - [Frontend dependency manifest](https://github.com/zauberzeug/nicegui/blob/v3.16.0/package.json)
+
+!!! info "Bundled Quasar `2.18.5` implementation"
+    - [QTable API definition](https://github.com/quasarframework/quasar/blob/quasar-v2.18.5/ui/src/components/table/QTable.json)
+    - [QTable implementation](https://github.com/quasarframework/quasar/blob/quasar-v2.18.5/ui/src/components/table/QTable.js)
+    - [QTable column computation](https://github.com/quasarframework/quasar/blob/quasar-v2.18.5/ui/src/components/table/table-column-selection.js)
+    - [QTable styles](https://github.com/quasarframework/quasar/blob/quasar-v2.18.5/ui/src/components/table/QTable.sass)
+
+## Completion Check
+
+Before accepting a customized table:
+
+1. Verify the target NiceGUI release and its bundled Quasar version.
+2. Set a primitive, immutable, unique `row_key` before using selection or row-scoped actions.
+3. Use constructor arguments and column definitions before QTable props or slots.
+4. Keep sortable values canonical and serializable; use `format` only for cosmetic text and `sort` only when raw values need a custom comparator.
+5. Choose the narrowest named slot and preserve QTable cell or header semantics.
+6. Recheck sorting, filtering, pagination, selection, and empty states after customization.
+7. Check mobile, landscape desktop, and portrait desktop layouts; verify the toolbar remains usable and wide tables scroll without overlapping controls.

src/personal_mcp/docs/skills/nicegui/references/tables.md

@@ -14,35 +14,38 @@ This reference was verified against the latest released NiceGUI stack at the tim
 
 Recheck the dependency manifest and tagged sources when the target application uses another NiceGUI release. Do not infer the Quasar or Vue version from their latest independent releases; use the versions bundled by NiceGUI.
 
-## Ownership Model
+## Table Ownership Model
 
-Treat an edit as a proposal, not a browser-side state mutation:
+This pattern combines [server-authoritative component events](./component-mechanics.md#server-authoritative-edit-proposals) with [bindable model projections](./binding-dataclasses.md#authoritative-models-and-projections):
 
 1. A render function converts dataframe records into row-scoped [bindable dataclasses](./binding-dataclasses.md).
-2. Each editable dataclass field is bound to the corresponding serializable QTable row field.
+2. Each bindable row owns its serializable QTable projection and whether an accepted edit has touched it.
 3. A NiceGUI editor displays that projection through `props.value` in a QTable scoped slot.
 4. The editor emits stable row identity, the field name, and the proposed value.
-5. Python locates the row dataclass, validates and assigns the value, persists the row to the dataframe or repository, and sends the resulting projection back with `table.update_rows(...)`.
+5. Python locates the row, validates and assigns the value, marks it as touched, and sends the resulting projection back with `table.update_rows(...)`.
 
 ```mermaid
 flowchart LR
-    A[Dataframe or repository] -->|render| B[Bindable row dataclasses]
-    B -->|field bindings| C[QTable row payloads]
-    C -->|props.value| D[NiceGUI editor]
-    D -->|row key, field, proposed value| E[Python handler]
-    E --> F{validate}
-    F -->|accept| B
-    B -->|persist| A
-    F -->|reject| G[notify]
+    A[Dataframe or repository] -->|render| B[EditableTableState]
+    B --> C[Bindable row: fields, payload, touched]
+    C -->|field bindings| D[QTable row payloads]
+    D -->|props.value| E[NiceGUI editor]
+    E -->|row key, field, proposed value| F[Python handler]
+    F --> G{validate}
+    G -->|accept and mark touched| C
+    C -->|persist touched rows later| A
+    G -->|reject| H[notify]
 ```
 
-The bindable dataclasses are the canonical page state in Python. The dataframe is the load and persistence boundary in this example; a production application can replace it with a service or repository. The browser may hold temporary editor state, but it is never the source of truth. Do not mutate `props.row` and mistake Vue reactivity for persistence. Do not use a visual row index as identity: sorting, filtering, and pagination can all change it. Set `row_key` to an immutable, unique field and send that value with every edit proposal.
+Do not use a visual row index as identity: sorting, filtering, and pagination can all change it. Set `row_key` to an immutable, unique field and send that value with every edit proposal. Do not mutate `props.row`; locate the row model by its stable key and let Python update the bound QTable projection.
 
 ## Recommended Cell-Slot Pattern
 
 [NiceGUI `ui.table`](https://nicegui.io/documentation/table) supports NiceGUI elements in scoped slots since `3.5.0`. The tagged [`Table.cell` implementation](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/elements/table.py) creates the corresponding Quasar `QTd`, while the tagged [table client component](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/elements/table.js) forwards QTable's scoped slot props.
 
-The following example uses a render function to transform a dataframe into an `EditableTableState`. That state owns one `EditableRow` per stable identifier and one serializable QTable payload per row. NiceGUI's `binding.bind_to` links each bindable dataclass field to its corresponding payload field, so assigning `row_state.name`, `row_state.quantity`, or `row_state.status` updates the Python-side table projection immediately.
+The following example uses a render function to transform a dataframe into an `EditableTableState`. Its `rows_by_id` container owns one `EditableRow` per stable identifier. Each row keeps its serializable QTable payload and touched flag with the editable fields, while the container provides identity lookup and ordered projections. The detailed `binding.bind_to` propagation behavior is covered by [bindable dataclasses](./binding-dataclasses.md#authoritative-models-and-projections).
+
+`state.touched_rows()` returns touched `EditableRow` instances that remain in `rows_by_id`, in table order. The example marks a row after an edit validates and leaves persistence to the caller, which can persist the returned dataclasses in one batch. Its **Show changes** button uses the same method to report each changed row's current ID, name, quantity, and status. Removing or replacing a row in the container automatically excludes the former object.
 
 A QTable scoped slot is one client-side template reused for every matching cell. It cannot use `bind_value(row_state, "name")` because there is no single Python `row_state` for that template. Instead, the slot reads the bound payload through `props.value` and sends the stable key back to Python, where the handler selects and assigns the corresponding dataclass.
 
@@ -52,35 +55,13 @@ The complete runnable source is available as [`editable_table.py`](../examples/e
 --8<-- "docs/skills/nicegui/examples/editable_table.py"
 ```
 
-This uses the same transformed-event path documented by [NiceGUI's table selection example](https://nicegui.io/documentation/table): `.on("update:model-value", ...)` attaches directly to the editor, and `js_handler` emits only the serializable values Python needs. Vue component events [do not bubble](https://vuejs.org/guide/components/events.html), so listening on the table or cell instead of the editor will not capture the editor's model update.
+The editor path uses the transformed-event pattern from [controlled values and model events](./component-mechanics.md#controlled-values-and-model-events). Attach the listener directly to each cell editor because Vue component events do not bubble from the editor to the cell or table. Read the QTable cell value from `props.value`, emit `props.row.<row_key>`, `props.col.name`, and the proposed value, then resolve the row in Python. NiceGUI's text-input wrapper uses `value` and `update:value`, while the number and select editors use `model-value` and `update:model-value`. Remove the text input's static `value` prop before adding its scoped `:value` binding. The select editor emits a NiceGUI-normalized option object, so this example forwards `option.label`, which is also the canonical value in `STATUS_OPTIONS`.
 
-The `update:model-value` callback receives the emitted model value itself. Forward it with `(value) => emit(..., value)`; do not read `value.value`. For `ui.number`, the underlying Quasar input emits numeric text and NiceGUI normally performs the float conversion in its built-in value handler. Because this custom handler forwards the event, `normalize_edit` accepts numeric strings and performs the authoritative integer conversion in Python.
+When a row needs an explicit save/cancel workflow, add an actions cell (for example `body-cell-actions`) that emits only the immutable row key and opens one reusable `ui.dialog`. Keep dialog controls as local draft state rather than binding directly to the authoritative row model. On **Save**, re-resolve the row by key, validate and normalize every proposed field in Python (for example with a small Pydantic draft model), and then commit all assignments together so partial validation failure cannot leave mixed old/new values. On **Cancel** or dialog dismiss, close the dialog without mutating authoritative state. This keeps the table in named cell slots and avoids the full-row templating boundary required by `QPopupEdit`.
 
-The `:model-value="props.value"` prop is deliberately one-way at the client boundary. In Vue, component `v-model` expands to a `modelValue` prop plus an `update:modelValue` listener, as shown in the [Vue component `v-model` guide](https://vuejs.org/guide/components/v-model.html) and its tagged [compiler transform](https://github.com/vuejs/core/blob/v3.5.22/packages/compiler-core/src/transforms/vModel.ts). Here the update listener sends an intent to Python rather than assigning into `props.row`; Python assignment to the selected bindable dataclass then updates the corresponding table-row payload.
+## Persistence And Row Refresh
 
-## Commit Policy
-
-Choose when edits cross the client-server boundary according to the editor:
-
-- Use `update:model-value` for discrete editors such as `ui.select`, switches, and checkboxes.
-- For text and numeric inputs, use Quasar's documented `debounce` prop when accepting edits during typing. A trailing delay avoids one server round trip per keystroke.
-- When the user must explicitly save or cancel a multi-field draft, keep the draft in a dialog or popup and emit one proposal on save. Python must still validate and reassert the canonical row.
-- For asynchronous persistence, disable or mark the affected editor busy while saving. Add an entity version or other optimistic concurrency check when multiple clients can edit the same record.
-
-Do not rely on browser validation alone. Quasar editor constraints improve feedback, but the event payload is still untrusted input. The Python handler must enforce the editable-field allowlist, types, ranges, permissions, record existence, and persistence constraints.
-
-## Persistence And Refresh
-
-Keep `table.rows` as a projection, not the business model. The row-scoped bindable dataclasses are the page model, and the dataframe or repository is its persistence boundary. On acceptance:
-
-1. validate and coerce into domain types
-2. assign the normalized value to the matching bindable dataclass field
-3. persist that dataclass through the dataframe adapter, service, or repository
-4. call `table.update_rows(state.table_rows(), clear_selection=False)`
-
-On validation rejection, leave the dataclass unchanged. On persistence failure, restore its previous value before re-raising or reporting the error. Perform step 4 in either case so the field binding and canonical Python state overwrite any temporary editor display. Preserve selection only when the selected row identities remain valid; otherwise use the default `clear_selection=True`.
-
-For database-backed applications, make the handler `async`, await the service transaction, and refresh only after it commits. Catch the application's expected validation, conflict, and persistence exceptions separately so the user receives actionable feedback without hiding programming errors.
+Keep `table.rows` as the serializable projection described in [bindable dataclasses](./binding-dataclasses.md#persistence-and-rollback), not the business model. After every accepted or rejected proposal, call `table.update_rows(state.table_rows(), clear_selection=False)` so the canonical projection replaces any temporary editor display. Preserve selection only while the selected row identities remain valid; otherwise use the default `clear_selection=True`.
 
 ## QTable And QPopupEdit Escalation
 
@@ -92,7 +73,7 @@ That restriction changes the implementation boundary: a full `body` slot must re
 
 1. confirm an ordinary NiceGUI editor or dialog cannot meet the interaction requirement
 2. copy the row structure from the matching Quasar `2.18.5` QTable documentation, not another version
-3. keep popup draft state local rather than assigning into `props.row`
+3. keep popup draft state local rather than assigning into `props.row`, following the [explicit save/cancel proposal pattern](./component-mechanics.md#server-authoritative-edit-proposals)
 4. emit the stable row key, field, and saved proposal to Python
 5. validate, persist, and replace the table rows from Python exactly as in the cell-slot pattern
 6. test keyboard focus, save, cancel, validation failure, sorting, filtering, pagination, and selection
@@ -117,15 +98,6 @@ Replacing the full row template has a larger maintenance and accessibility surfa
 - [`QPopupEdit` source](https://github.com/quasarframework/quasar/blob/quasar-v2.18.5/ui/src/components/popup-edit/QPopupEdit.js)
 - [`QPopupEdit` API definition](https://github.com/quasarframework/quasar/blob/quasar-v2.18.5/ui/src/components/popup-edit/QPopupEdit.json)
 
-### Vue `3.5.22`
-
-- [Component `v-model`](https://vuejs.org/guide/components/v-model.html)
-- [Component events](https://vuejs.org/guide/components/events.html)
-- [Scoped slots](https://vuejs.org/guide/components/slots.html#scoped-slots)
-- [`v-model` compiler transform](https://github.com/vuejs/core/blob/v3.5.22/packages/compiler-core/src/transforms/vModel.ts)
-- [Component event runtime](https://github.com/vuejs/core/blob/v3.5.22/packages/runtime-core/src/componentEmits.ts)
-- [Native `v-model` directives](https://github.com/vuejs/core/blob/v3.5.22/packages/runtime-dom/src/directives/vModel.ts)
-
 ## Completion Check
 
 Before accepting an editable table:
@@ -133,12 +105,12 @@ Before accepting an editable table:
 1. Pin the NiceGUI release and verify its bundled Quasar and Vue versions.
 2. Use an immutable, unique `row_key`; never persist by view index.
 3. Transform dataframe records into row-scoped bindable dataclasses during rendering.
-4. Bind each editable dataclass field to its corresponding serializable QTable row field.
+4. Keep each dataclass, serializable QTable row, and touched flag together on one bindable row.
 5. Display the projected value from QTable scoped props; do not bind one shared slot template to one Python row object.
-6. Attach the event listener directly to the editor and emit only row identity, field, and proposed value.
-7. Validate field access, types, ranges, permissions, and record existence in Python.
-8. Assign the dataclass field, persist through the owning adapter or service, and roll back that assignment on failure.
+6. Apply the [controlled-value event proposal](./component-mechanics.md#controlled-values-and-model-events) directly to each editor and emit only row identity, field, and proposed value.
+7. Validate and normalize proposals in Python before assigning them.
+8. Mark accepted rows as touched and derive touched dataclasses from the rows still held by the container.
 9. Reassert canonical rows after accepted and rejected proposals.
 10. Test editing after sort, filter, pagination, and selection changes.
-11. Test stale rows, invalid input, persistence failure, and concurrent edits.
+11. Test stale rows, invalid input, persistence failure, concurrent edits, and removal of touched bindings.
 12. Use a full `body` slot for `QPopupEdit`, never a `body-cell-*` slot.

src/personal_mcp/docs/skills/nicegui/references/troubleshooting-and-quality-gates.md

@@ -1,39 +1,276 @@
-# Troubleshooting and Quality Gates
+# NiceGUI Troubleshooting And Quality Evidence
 
-## Troubleshooting
+Use this reference to identify the layer that owns a NiceGUI failure and the evidence needed to distinguish similar symptoms. It covers behavior verified against NiceGUI `3.16.0`; browser, Quasar, Vue, FastAPI, Socket.IO, Uvicorn, and proxy behavior must also be checked against the versions deployed by the target application.
 
-### Upload Errors
+The companion [interaction mechanics](./interaction-patterns.md) page defines normal lifecycle, validation, upload, refresh, timer, task, and transport behavior. [Component mechanics](./component-mechanics.md) covers Quasar props, events, slots, wrapper models, and frontend payload mapping. [FastAPI and Uvicorn startup](./fastapi-uvicorn-startup.md) covers import identity, workers, reload, and deployment topology.
 
-- Validate extension and size before storage.
-- Catch expected exceptions and return negative notifications.
-- Log unexpected exceptions with request context.
+## Diagnostic Index
 
-### UI Race Conditions
+| Symptom | Likely owner | Discriminating evidence |
+| --- | --- | --- |
+| upload rejected before handler runs | Quasar `QUploader` or browser selection rules | `on_rejected` fires; no upload POST reaches the server |
+| upload request returns `400` or `413` | proxy, ASGI multipart parsing, NiceGUI upload route, or application validation | HTTP status and response body from the upload request; proxy and server logs |
+| page shows a response-timeout error | async page construction before client connection | warning naming `response_timeout`; page builder timing and `connected()` boundary |
+| update appears only after reload | wrong client context, unobserved plain mutation, or missing explicit update | target `Client`, element deletion state, outbox traffic, and wrapper update call |
+| update reaches one tab but not another | private page element tree or process-local fan-out | client IDs, page paths, worker identity, and `app.clients(path)` iteration |
+| updates disappear after a brief network interruption | client deleted after reconnect timeout or outbox replay unavailable | disconnect/delete timestamps, reconnect timeout, next message ID, and reload log |
+| old query result replaces a newer one | concurrent async completion race | request generation, start/end timestamps, query identity, and publish order |
+| all clients pause during one action | blocking work on the event loop | event-loop lag and stack or profile showing synchronous I/O or CPU work |
+| callback runs repeatedly after navigation | duplicate timer, event subscription, or lifecycle registration | registration count, client IDs, delete handlers, and task names |
+| user state leaks across tabs or users | incorrect storage scope or module-level mutable state | storage scope, session ID, tab ID, process ID, and object identity |
+| URL changes but content or state does not | History API used without a route/content transition | `pushState`/`replaceState` call versus `ui.navigate.to` or sub-page routing |
+| changed CSS or image remains stale | static cache lifetime or proxy/browser cache | response URL, `Cache-Control`, cache source in developer tools, and content version |
+| exception is logged but no page feedback appears | exception occurred outside an active UI slot or after the client was deleted | exception handler invoked, current client/slot, task owner, and element state |
 
-- Disable triggering controls during async work.
-- Remove duplicate timers and listeners targeting the same state.
-- Ensure service call ordering is deterministic before render updates.
+Start with the smallest boundary that can explain the symptom. Browser developer tools establish whether an event, upload, static request, or socket message crossed the network. Server logs establish whether the page, client, handler, task, or service received it. Durable data inspection establishes whether the accepted operation committed independently of the UI.
 
-### Asset Caching
+## Upload Failures
 
-- Confirm static mount and proxy rewrite correctness.
-- Add cache-busting query strings for changed assets.
-- Avoid per-page CSS injection.
+[`ui.upload`](https://nicegui.io/documentation/upload) is a Quasar uploader backed by an element-specific NiceGUI POST route. The tagged [`Upload` implementation](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/elements/upload.py) resolves the `client_id` and element ID from the route before converting each Starlette upload to `event.file`.
 
-### Navigation and State Drift
+### Rejected Before Transfer
 
-- Avoid global mutable UI state.
-- Keep state request-scoped or service-managed.
-- Rehydrate page data during route load.
+`max_file_size`, `max_total_size`, `max_files`, and the Quasar `accept` prop operate in the browser. A rejection at this stage calls `on_rejected`; it does not prove that the server would reject an equivalent direct request. An unexpected rejection commonly comes from MIME patterns, file-count state retained in the uploader queue, or size units that differ from the intended policy.
 
-## Production Readiness Gate
+Useful evidence includes the selected file's browser-reported type and size, current queue contents, configured Quasar props, and whether `on_begin_upload` or a network request occurs. Reset the uploader queue only when clearing previous selections is the intended product behavior.
 
-Pass all checks before shipping:
+### Transfer Or Multipart Failure
 
-- Structure: one-way dependencies between pages, components, and services.
-- Responsiveness: UI validated at both small and large viewport widths.
-- Accessibility: labels and actions are clear and readable.
-- Reliability: validation and exception paths surface user feedback.
-- Maintainability: repeated UI patterns are extracted; business logic remains in services.
+If the POST begins but the upload handler does not run, inspect the HTTP status before changing page code:
 
-If any check fails, return to the workflow step that owns that concern.
+| Response | Common boundary |
+| --- | --- |
+| `404` | stale or deleted element/client route, incorrect proxy prefix, or navigation during transfer |
+| `400` | malformed multipart body, missing `client_id`, missing element ID, or no matching uploader element |
+| `413` | reverse-proxy or ASGI request-size limit |
+| `422` | route or dependency validation outside the normal NiceGUI upload route |
+| `5xx` | multipart conversion, temporary storage, application handler, or downstream service failure |
+
+The tagged [`FileUpload` conversion](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/elements/upload_files.py) keeps small uploads in memory and spills larger ones to a temporary file after Starlette's `MultiPartParser.spool_max_size`. This is a buffering threshold, not an acceptance limit. Concurrency multiplies memory and temporary-disk pressure, so record file size, concurrent upload count, process memory, temporary filesystem capacity, and proxy limits together.
+
+### Accepted But Unsafe Or Corrupt
+
+`file.name` is reduced to its basename by NiceGUI, and `file.content_type` comes from the request. Neither establishes safe content. Server-side acceptance should record the authoritative byte size and verify content signature, parser behavior, quota, authorization, and application-selected destination. Use an independently generated storage key and keep active user content off the main application origin.
+
+When downstream parsing fails, distinguish transport completion from domain acceptance. A successful upload POST can still produce a rejected document. Preserve an operation ID or storage record so logs and user feedback identify the same attempt without logging file content or sensitive form fields.
+
+## Initial Page Response Failures
+
+The tagged [`page` wrapper](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/page.py) gives async page construction `response_timeout` seconds, three by default, to finish or signal that it is waiting for the client connection. If neither happens, NiceGUI cancels the page task, deletes that client, logs a warning, and serves a terminal `500` page through a fresh client.
+
+Increasing `response_timeout` can be appropriate for bounded, unavoidable initial construction, but it does not make long I/O responsive. The relevant timing split is:
+
+- code before `await ui.context.client.connected()` delays the initial HTTP response
+- code after that await runs with a connected browser and can progressively update the page
+- synchronous blocking work in either phase can still stall the event loop
+
+Capture elapsed time around dependencies, database calls, remote clients, serialization, and component construction. A timeout with low service latency may indicate a page builder waiting on a condition that itself requires the browser connection.
+
+Synchronous page-builder exceptions and async exceptions raised before the response is built can render an `app.on_page_exception` page. That handler is synchronous in NiceGUI 3.16. A returned FastAPI `Response` bypasses normal page rendering. Do not assume a global `app.on_exception` handler can reconstruct a failed initial element tree.
+
+## Connection, Reconnect, And Deleted Clients
+
+The tagged [`Client` lifecycle](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/client.py) separates a socket disconnect from deletion. On disconnect, NiceGUI invokes disconnect handlers and waits for `reconnect_timeout`; a successful handshake cancels deletion. If no connection returns, NiceGUI closes tab storage as needed, invokes delete handlers, removes elements and bindings, stops the outbox, and removes the client from `Client.instances`.
+
+### Stale Client Writes
+
+Holding an element, slot, timer, or client in a long-lived object can outlive the page that created it. Writes after deletion trigger NiceGUI's deleted-client warning and cannot produce a valid browser update. Before publishing detached work, retain the intended client deliberately and check `client.is_deleted` or membership in the current client set. A durable job result should be written to durable state even when its original page no longer exists; a later page load can rehydrate it.
+
+Do not treat `on_disconnect` as final resource disposal. It also runs for reconnectable interruptions. Page-owned cleanup belongs in `on_delete`; transport telemetry and reversible status belong in `on_disconnect` and `on_connect`.
+
+### Reconnect Replay And Reload
+
+The tagged [`Outbox`](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/outbox.py) retains recent element updates and messages. During handshake, the browser provides the next message ID it expects. NiceGUI rewinds retained history and replays from that ID. If the ID is no longer available because of age or `message_history_length`, NiceGUI reloads the page.
+
+This mechanism explains several superficially similar outcomes:
+
+| Outcome | Interpretation |
+| --- | --- |
+| short interruption, state continues | client survived and required messages remained in history |
+| interruption followed by reload | rewind target was unavailable or browser initiated a reload |
+| interruption followed by fresh page state | original client was deleted and route rebuilt a new element tree |
+| durable operation duplicated after reconnect | application command lacked idempotency; outbox replay is not a transaction protocol |
+
+Correlate client ID, document or tab identity, message IDs, disconnect duration, reconnect timeout, and process ID. A load-balanced multi-worker deployment also needs compatible session affinity and shared application state; an in-memory client exists only in the worker that created it.
+
+## Missing Or Misrouted Updates
+
+Each page client owns a private element tree. Mutating an element affects that element's client; mutating a plain list or model that has no active binding does not enqueue a browser update by itself. Check these in the owning layer:
+
+- the element has not been deleted or replaced by a refresh
+- the handler runs in the intended client's slot context
+- the wrapper property is bindable or followed by its documented helper or `update()`
+- the refreshable target belongs to the intended client
+- application-wide producers iterate the intended `app.clients(path)` and enter each client context
+- process-local events are not assumed to reach clients connected to another worker
+
+A module-level `@ui.refreshable` can accumulate targets from several clients. Its tagged [`refresh()` implementation](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/functions/refreshable.py) clears and rebuilds every matching surviving target. Unexpected cross-client refresh therefore indicates target scope, not shared DOM. Unexpectedly missing refresh often indicates that the target container was deleted or the code refreshed a different decorated instance.
+
+## Async Races And Duplicate Actions
+
+NiceGUI event handlers that return awaitables are scheduled as background tasks. Disabling a button reduces normal repeated clicks but does not serialize direct requests, reconnect replays, keyboard submission, another control, or another client.
+
+### Completion-Order Races
+
+For replaceable reads such as search, an older request can finish after a newer request and overwrite its result. Record a generation or request key when work starts and compare it immediately before publishing. Cancellation can reduce wasted work but is not sufficient when the underlying thread, remote service, or database operation cannot be canceled.
+
+For writes, define the service-level policy explicitly: lock, optimistic entity version, idempotency key, conflict response, or accepted duplicate semantics. UI busy state is feedback, not concurrency control.
+
+### Refresh Races
+
+Each refreshable invocation owns a target container. Refresh clears that target before recreating children; concurrent refreshes can therefore interleave service reads and rendering. Await a refresh when the triggering action depends on completion, serialize refreshes for one target, or use a latest-generation policy for replaceable data. Keep long-lived loading and error indicators outside the cleared target if they must remain stable.
+
+### Observable Evidence
+
+For an asynchronous interaction, logs are most useful when they contain operation ID, client ID, user or tenant identifier where safe, entity ID, request generation, start and finish time, outcome, and exception type. Avoid recording secrets, raw uploaded content, session cookies, or full form payloads.
+
+## Blocking Work And Event-Loop Lag
+
+An `async def` callback does not make synchronous work non-blocking. CPU-heavy loops, synchronous HTTP clients, filesystem calls, image or document parsers, and blocking database drivers executed on the event loop delay socket heartbeats, all clients' event handlers, timers, page responses, and outbox delivery.
+
+Use the execution boundary defined in [interaction mechanics](./interaction-patterns.md#execution-contexts): non-blocking async APIs in the event loop, `run.io_bound()` for blocking I/O, `run.cpu_bound()` for serializable CPU work, or an external worker for durable jobs. A thread keeps the loop responsive but does not remove memory, timeout, thread-safety, or cancellation constraints. A process pool adds serialization and process-start constraints.
+
+Evidence for event-loop blocking includes simultaneous latency across unrelated clients, delayed timers or Socket.IO heartbeats, event-loop lag metrics, and a stack or profile inside synchronous work. A single slow awaited network request that yields control does not by itself block other clients.
+
+## Timer, Listener, And Task Duplication
+
+Repeated callbacks usually originate at registration, not dispatch. Common ownership mistakes include:
+
+- creating `ui.timer` repeatedly during a refresh while retaining the old timer outside the cleared container
+- registering an application timer or lifecycle handler during a per-client page build
+- subscribing a long-lived `Event` outside a UI context without later unsubscribing
+- starting a new consumer task on every reconnect instead of once at application startup
+- reloading a development process while an external scheduler still targets both old and new instances
+
+In NiceGUI 3.16, a page-scoped `ui.timer` waits for its client connection and is canceled when its element is deleted. An `app.timer` is process-scoped. An `Event` subscription made inside a UI context is automatically removed on client deletion by default; one made outside UI context has no automatic client owner. Application lifecycle handlers and external broker consumers need an application-level owner and shutdown path.
+
+Record timer or task name, registration site, process ID, client ID when applicable, activation state, and cancellation reason. Count registrations directly rather than inferring duplication from repeated business effects, which could also come from retries or multiple workers.
+
+## Storage And Navigation Drift
+
+State drift often comes from assigning data to a scope with the wrong lifetime:
+
+| Unexpected behavior | Scope to inspect |
+| --- | --- |
+| state disappears on reload or route navigation | `app.storage.client` or page-local Python object |
+| state unexpectedly follows another tab | `app.storage.user`, `browser`, or module-global state |
+| state is missing immediately after page construction | `app.storage.tab` accessed before `client.connected()` |
+| state differs between workers | local file storage, in-memory tab state, or module-global state |
+| browser storage mutation raises or is ignored | `app.storage.browser` changed after response construction |
+
+The tagged [`storage` implementation](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/storage.py) persists `user` and `general` scopes locally by default or in Redis when configured. Tab storage is in-memory unless Redis is configured. The signed browser cookie identifies a user storage record; storage scope is not authorization, and persisted identifiers must still be checked against the authenticated principal and tenant.
+
+[`ui.navigate.to`](https://nicegui.io/documentation/navigate) opens a route, client element anchor, or external URL. With `ui.sub_pages`, a relative same-app route can be handled within the current client. `ui.navigate.history.push()` and `.replace()` only change browser history state and the visible URL; they do not invoke a page builder or rehydrate content. A URL/content mismatch after `pushState` is therefore expected unless application code also owns the content transition.
+
+A full navigation or reload creates a new page client, so page-local objects and client storage are not durable navigation state. Encode shareable state in route or query parameters, place tab- or user-lifetime state in the matching storage scope, and reload authoritative data from services rather than retaining element instances globally.
+
+## Static Assets, Media, And Cache Boundaries
+
+The tagged [`Client.build_response()`](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/client.py) marks NiceGUI page and Markdown responses `Cache-Control: no-store`. A proxy that caches page HTML against that header can serve stale client IDs, initial state, or user-specific content and is misconfigured.
+
+Static files intentionally use a different policy. In NiceGUI 3.16:
+
+- `app.add_static_files()` and `app.add_static_file()` default to `Cache-Control: public, max-age=3600`
+- `max_cache_age=0` requests immediate revalidation behavior but does not create a private authorization boundary
+- media routes support byte-range streaming and should be used for seekable audio or video
+- static and media directory helpers explicitly expose their contents without per-file application authorization
+- `single_use=True` removes a route after the first handled request in one process; it is not a secure, distributed, or retry-safe download grant
+
+The implementation is defined by [`app.add_static_*` and `app.add_media_*`](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/app/app.py) and [`CacheControlledStaticFiles`](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/staticfiles.py).
+
+For stale assets, inspect the actual response in browser developer tools: final URL after proxy rewriting, status, `Cache-Control`, `ETag` or modification metadata, service-worker involvement, and whether the response came from memory, disk, intermediary, or origin. Prefer content-versioned URLs for immutable assets. Query-string cache busting works only when every cache key includes the query and the origin serves the updated bytes.
+
+Security-sensitive files belong behind an authenticated FastAPI route or object-store authorization mechanism with private cache policy. A hard-to-guess static URL is not access control, and public cache headers can retain content beyond logout or permission changes.
+
+## Exception Surfaces
+
+NiceGUI exceptions have different user-feedback capabilities according to where they occur:
+
+| Failure surface | Handler path | UI context available |
+| --- | --- | --- |
+| page builder before response | `app.on_page_exception`, FastAPI handlers, then global exception handlers | fresh error-page client for synchronous page handler |
+| UI event or awaited callback in an element slot | client in-page exception handlers plus global handlers | originating slot while client remains alive |
+| timer or NiceGUI background task | global handler; in-page handler only when task retained an active slot context | depends on captured context and client lifetime |
+| `Event.emit()` subscriber | exception forwarded to global handling | subscriber's captured slot when available |
+| `Event.call()` subscriber | exception propagates to caller | caller decides feedback and transaction behavior |
+| FastAPI route outside NiceGUI page UI | FastAPI exception handling | no implicit NiceGUI element context |
+
+The tagged [`app.handle_exception()`](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/app/app.py) first invokes a client's in-page exception handling when a client and slot are active, then invokes global exception handlers. Unexpected exceptions should retain a traceback and correlation ID in server logs. User feedback should be specific for expected domain failures and generic for unexpected failures, without exposing internals.
+
+An exception notification is not recovery by itself. Restore busy state in `finally`, preserve user input after a recoverable failure, reconcile uncertain write outcomes from the authoritative store, and stop publishing to deleted clients.
+
+## Security-Sensitive Boundaries
+
+The following client-visible mechanisms improve usability but do not enforce policy:
+
+- disabled or hidden controls
+- Quasar input rules and upload restrictions
+- route names, element IDs, client IDs, or unguessable-looking static paths
+- values retained in page, tab, browser, or user storage
+- custom JavaScript validation or transformed event payloads
+
+Authorization, tenant boundaries, accepted fields, type and range checks, optimistic concurrency, upload inspection, and durable write constraints belong on the server. For every mutation, identify the authenticated principal independently of browser-submitted ownership fields.
+
+Do not interpolate untrusted values into raw `ui.html`, Vue templates, JavaScript, or style content. Use wrapper text/value APIs and structured serialization. Review proxy trust, forwarded-prefix configuration, cookies, origin exposure, and WebSocket policy as deployment inputs rather than component styling concerns.
+
+## Quality Evidence Matrix
+
+A quality gate is satisfied by observable evidence, not by the presence of a pattern in source code.
+
+| Concern | Required evidence |
+| --- | --- |
+| startup and import identity | application starts through the production entry point; reload and worker behavior match deployment; no duplicate module import paths |
+| initial page response | representative pages stay within their response budget or intentionally cross `client.connected()` before long work |
+| interaction correctness | primary actions, keyboard submission, validation failure, retry, duplicate action, and cancellation produce deterministic state |
+| client lifecycle | disconnect/reconnect within the configured window preserves valid behavior; deletion releases page-owned resources |
+| concurrency | stale reads cannot overwrite newer intent; writes have a documented conflict or idempotency policy |
+| blocking behavior | concurrent-client check shows one slow action does not stall unrelated page events; profiles contain no unexpected event-loop blocking |
+| storage isolation | reload, navigation, second-tab, second-user, process-restart, and multi-worker checks match each selected storage scope |
+| uploads | browser rejection, direct server-side rejection, oversized request, invalid content, storage failure, and successful streaming path are distinguished |
+| exception behavior | expected domain failures remain actionable; unexpected failures log tracebacks and correlation IDs; controls recover from busy state |
+| cache behavior | page responses are `no-store`; public assets use deliberate versioning and lifetime; protected content is not exposed through public static routes |
+| responsive layout | narrow mobile, intermediate, and wide desktop viewports show no clipping, overlap, inaccessible popup content, or layout shift from dynamic labels |
+| accessibility | keyboard order, focus return, accessible names, validation association, contrast, reduced-motion behavior, and dialog/menu escape behavior are verified |
+| observability | logs identify operation, client/process, route or entity, timing, and outcome without secrets or sensitive payloads |
+| shutdown | timers, consumers, process/thread work, persistent storage, and external clients have deliberate cancellation or close behavior |
+
+## Testing Surfaces
+
+NiceGUI's [pytest integration](https://nicegui.io/documentation/section_testing) provides two complementary fixtures:
+
+- `User` simulates interactions in Python and is the fast default for page content, component values, clicks, typing, event dispatch, navigation, and service-backed acceptance behavior.
+- `Screen` drives a real headless browser and is reserved for behavior that depends on browser layout, JavaScript, actual uploads/downloads, focus, WebSockets, rendering, or client-side Quasar behavior.
+
+Use lower-level tests for services, validation, authorization, idempotency, storage adapters, and task logic without constructing UI. Use `User` tests for application interaction contracts. Use a small set of `Screen` tests for the browser boundary, and supplement responsive or visual claims with screenshots and computed layout checks at explicit viewport sizes.
+
+Tests should control async completion by observable state, events, or bounded timeouts rather than arbitrary sleeps. Reconnect, multi-tab, multi-user, and multi-worker behavior need dedicated environments because a single simulated client cannot establish those isolation claims.
+
+## Source Index
+
+!!! info "NiceGUI public documentation"
+	- [Pages, response timeout, connection, and multicasting](https://nicegui.io/documentation/page)
+	- [Error handling and execution](https://nicegui.io/documentation/section_action_events)
+	- [Uploads](https://nicegui.io/documentation/upload)
+	- [Storage](https://nicegui.io/documentation/storage)
+	- [Navigation](https://nicegui.io/documentation/navigate)
+	- [Testing](https://nicegui.io/documentation/section_testing)
+	- [Security guidance](https://nicegui.io/documentation/section_security)
+
+!!! info "NiceGUI `3.16.0` implementation"
+	- [Page response lifecycle](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/page.py)
+	- [Client connection and deletion](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/client.py)
+	- [Outbox replay](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/outbox.py)
+	- [Upload route](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/elements/upload.py)
+	- [Uploaded-file buffering](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/elements/upload_files.py)
+	- [Refreshable targets](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/functions/refreshable.py)
+	- [Timers](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/timer.py)
+	- [Storage scopes](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/storage.py)
+	- [Navigation](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/functions/navigate.py)
+	- [Exception and static/media handling](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/app/app.py)
+	- [Static cache headers](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/staticfiles.py)
+
+!!! info "Related platform references"
+	- [FastAPI WebSockets](https://fastapi.tiangolo.com/advanced/websockets/)
+	- [FastAPI server-sent events](https://fastapi.tiangolo.com/tutorial/server-sent-events/)
+	- [Starlette static files](https://www.starlette.io/staticfiles/)
+	- [Uvicorn deployment](https://www.uvicorn.org/deployment/)

src/personal_mcp/docs/testing.md

@@ -4,96 +4,44 @@ icon: lucide/flask-conical
 
 # Testing
 
-This page describes the current test layout and execution model for this repository.
-
-Primary guidance sources:
-- [Pytest scaffolding skill](./skills/pytesting/SKILL.md)
-- [Pytest docs reference](./skills/pytesting/references/pytest-docs.md)
-- [FastAPI + uv + Docker skill](./skills/fastapi-uv-docker/SKILL.md)
-
-## Goals
-
-1. Keep local feedback fast with deterministic tests.
-2. Mirror source modules with focused test groups.
-3. Keep endpoint and MCP surface checks explicit.
-4. Make marker usage strict and intentional.
+The test suite checks that the same public MCP behavior works over HTTP and stdio.
 
 ## Current Test Layout
 
-Current tree:
-
 ```text
 tests/
-    __init__.py
     conftest.py
-    registry/
-        test_read.py
-        ingest/
-            test_current_docs.py
-            test_document.py
-        models/
-            test_document_validation.py
-    prompts/
-        test_content_renderer.py
-        test_filesystem_provider.py
-    skills/
-        test_provider.py
-    web/
-        conftest.py
-        test_endpoint_connections.py
-        test_mcp_prompts.py
-        test_mcp_skills.py
+    server_contract.py
+    test_http.py
+    test_stdio.py
 ```
 
-Source-to-test alignment today:
-- `src/personal_mcp/registry/ingest/` -> `tests/registry/ingest/`
-- `src/personal_mcp/registry/models/` -> `tests/registry/models/`
-- `src/personal_mcp/prompts/` -> `tests/prompts/`
-- `src/personal_mcp/skills/provider.py` -> `tests/skills/test_provider.py`
-- `src/personal_mcp/web/` and MCP HTTP surface -> `tests/web/`
+`server_contract.py` contains the shared expectations. Both transport tests verify the resources, prompts, fallback tools, and representative reads against that contract.
 
-## Markers And Strictness
+## Run Tests
 
-Configured markers in `pyproject.toml`:
-- `unit`: fast deterministic tests with no external dependencies
-- `integration`: framework or component integration tests
-- `smoke`: thin critical-path checks
-
-Pytest runs with `--strict-markers`, so any unregistered marker fails the test run.
-
-## Fixture Layering
-
-Fixture placement follows test scope:
-1. `tests/conftest.py` for cross-suite defaults.
-2. `tests/web/conftest.py` for web and endpoint client setup.
-
-Prefer adding fixtures at the narrowest scope that serves more than one test.
-
-## Command Baseline
-
-Canonical invocation:
+Run the full suite with:
 
 ```bash
 uv run pytest
 ```
 
-Useful filtered runs:
+Run one transport while working on a focused change:
 
 ```bash
-uv run pytest --collect-only -q
-uv run pytest -m unit -q
-uv run pytest -m integration -q
-uv run pytest -m smoke -q
+uv run pytest tests/test_http.py -q
+uv run pytest tests/test_stdio.py -q
 ```
 
-## Adding New Tests
+The repository uses strict pytest markers. Register any new marker in `pyproject.toml` before using it.
 
-When adding coverage:
-1. Place tests under the nearest existing module subtree (`prompts/`, `registry/`, `skills/`, or `web/`).
-2. Mirror the source path where practical.
-3. Reuse existing `conftest.py` files before adding new fixture layers.
-4. Add markers only when they convey execution intent, and register new markers in `pyproject.toml` first.
+## Full Validation
 
-This keeps the suite aligned with the current architecture while preserving a fast local test loop.
+```bash
+uv run zensical build
+uv run ruff check .
+uv run ty check
+uv run pytest
+```
 
-Prefer durable boundaries over implementation details: provider discovery, prompt rendering, traversal rejection, protocol behavior, and installed-package path resolution. Do not test deleted catalog projections, Pydantic immutability internals, or helper delegation.
+See the [Pytesting skill](./skills/pytesting/SKILL.md) when adding or restructuring tests.

src/personal_mcp/docs/usage.md

@@ -2,105 +2,59 @@
 icon: lucide/workflow
 ---
 
-# Skill Usage Mechanics
+# Using Personal MCP
 
-## Purpose
+Personal MCP gives clients access to skills, prompts, and general documentation. Use the smallest piece of content that matches the task instead of loading the whole library.
 
-This page describes how clients discover and load `personal-mcp` skills published by the [FastMCP Skills Provider](https://gofastmcp.com/servers/providers/skills).
+## Connect
 
-Skills are MCP resources. The client remains responsible for selecting guidance, loading only useful supporting material, and applying it to the current workspace.
-
-## Published Skill Surface
-
-Each directory beneath `docs/skills/` publishes:
-
-1. `skill://<name>/SKILL.md` for primary instructions
-2. `skill://<name>/_manifest` for file discovery and integrity metadata
-3. `skill://<name>/{path*}` for supporting files
-
-The server uses `supporting_files="template"`. Main files and manifests appear in `resources/list`; supporting files stay behind per-skill wildcard templates so the resource list remains compact.
-
-The manifest contains every skill-relative path, byte size, and SHA256 hash. References do not have synthetic ids or a separate catalog record.
-
-Prompts are available through native MCP prompt discovery and rendering.
-
-## Discovery Workflow
-
-Use this bounded sequence:
-
-1. List resources or call FastMCP `list_skills()`.
-2. Compare skill names and descriptions.
-3. Read one selected `skill://<name>/SKILL.md`.
-4. Read `skill://<name>/_manifest` only when supporting material may be useful.
-5. Fetch the minimum supporting paths needed for the task.
-6. Reconcile the guidance with the actual repository code before making changes.
-
-Do not load every skill or every supporting file up front.
-
-## FastMCP Client Utilities
-
-FastMCP provides native utilities in `fastmcp.utilities.skills`:
-
-1. `list_skills(client)` discovers main skill resources.
-2. `get_skill_manifest(client, name)` parses a generated manifest.
-3. `download_skill(client, name, target_dir)` downloads one skill.
-4. `sync_skills(client, target_dir)` downloads all advertised skills.
-
-These utilities operate directly on the native `skill://` contract and require no repository-specific adapter.
-
-## Copilot Invocation
-
-In VS Code, skills can arrive through:
-
-1. explicit attachment from `Add Context > MCP Resources` or `MCP: Browse Resources`
-2. direct resource reads on selected `skill://<name>/SKILL.md` entries
-3. a slash-command prompt that names a specific native skill URI
-
-Instructions can steer retrieval, but they do not guarantee automatic resource attachment in every chat surface. Use `MCP: Browse Resources` to confirm server-side availability, then attach only the minimum skill resources needed for the current task.
-
-A reliable prompt is:
+The HTTP endpoint is `/mcp`. For a local server on port `8765`, connect to:
 
 ```text
-Browse MCP resources, select the best matching skill://.../SKILL.md entry by description, inspect its _manifest only if supporting detail is needed, and reconcile the guidance with this workspace.
+http://127.0.0.1:8765/mcp
 ```
 
-## Thin Shim Pattern
+Clients that launch servers as subprocesses can use:
 
-Consumer repositories can bind file scopes to native skill resources with short `.github/instructions/*.instructions.md` files.
-
-| `applyTo` scope | Companion docs | Primary skill resource |
-| --- | --- | --- |
-| `**/*.md` | [Authoring Guide](./authoring.md) | `skill://zensical-docs/SKILL.md` |
-| `tests/**` | [Testing](./testing.md) | `skill://pytesting/SKILL.md` |
-| `.vscode/**` | [VS Code Configuration](./skills/vscode-configuration/SKILL.md) | `skill://vscode-configuration/SKILL.md` |
-
-Minimal shape:
-
-```md
----
-name: <scope name>
-description: Route <path scope> edits to a personal-mcp skill.
-applyTo: '<glob>'
----
-
-Load `skill://<skill-name>/SKILL.md` first. Read `_manifest` and supporting files only when the task needs deeper detail. Apply the guidance to the current repository rather than treating it as generated output.
+```bash
+uv run mcp-stdio
 ```
 
-## Failure Recovery
+## Use A Skill
 
-When no skill is an obvious match:
+Skills are MCP resources. A client should:
 
-1. compare the available main-resource descriptions again
-2. select at most two candidates
-3. read their main files, not all supporting files
-4. ask one clarifying question if the choice remains ambiguous
+1. browse the available `skill://<name>/SKILL.md` resources
+2. choose one by its name and description
+3. read the main `SKILL.md`
+4. read its `_manifest` only when extra reference material is needed
+5. load only the relevant supporting files
 
-When a supporting path fails, refresh `_manifest`; file paths are the public supporting-resource identifiers.
+The guidance should then be checked against the code and conventions in the current workspace.
 
-## Runtime Checklist
+## Use A Prompt
 
-1. Confirm MCP connectivity.
-2. Confirm at least one `skill://<name>/SKILL.md` resource is listed.
-3. Read its `_manifest` and verify `SKILL.md` appears with a SHA256 hash.
-4. Read one supporting file through its manifest path.
-5. Keep loaded context bounded to the selected skill and relevant files.
+Prompts are reusable workflows with named arguments. Browse the server's prompts, select one by its description, and supply the requested values when invoking it.
+
+In VS Code, MCP prompts appear as chat slash commands. Resources can be opened from **MCP: Browse Resources** and attached as context when the active chat surface supports it.
+
+## Tool Fallbacks
+
+Some clients can call tools but cannot browse MCP resources or prompts directly. For those clients, the server exposes four read-only tools:
+
+- `list_resources`
+- `read_resource`
+- `list_prompts`
+- `get_prompt`
+
+They provide access to the same underlying content. Clients with native resource and prompt support should use those native features.
+
+## Example Request
+
+```text
+Browse the available Personal MCP skills, choose the best match for this task,
+read its main SKILL.md, and load supporting files only if they are needed.
+Apply the guidance to this repository rather than treating it as generated output.
+```
+
+For the exact resource and prompt formats, see the [content contracts](./contracts/index.md).

src/personal_mcp/mcp.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
 from fastmcp import FastMCP
+from fastmcp.server.transforms import PromptsAsTools
+from fastmcp.server.transforms import ResourcesAsTools
 from mcp_types import Icon
 
 from .prompts.provider import prompt_lifespan
@@ -10,8 +12,9 @@ from .skills import skill_lifespan
 
 _SERVER_INSTRUCTIONS = """Personal development guidance exposed as native MCP resources and prompts.
 
-Use prompts for parameterized workflows. For task-specific guidance, browse native skill resources,
-select one skill://<name>/SKILL.md resource, and read its manifest only when supporting detail is needed.
+Use prompts for parameterized workflows; tool-only agents can discover and render them with
+list_prompts and get_prompt. For task-specific guidance, browse native skill resources, select one
+skill://<name>/SKILL.md resource, and read its manifest only when supporting detail is needed.
 """
 _SERVER_ICON = Icon(
     src=(
@@ -59,6 +62,10 @@ def create_mcp() -> FastMCP:
     def docs_markdown(path: str) -> dict[str, str]:
         return read_docs_markdown_path(registry, path)
 
+    # Bridges tool-only clients that cannot browse native resources or prompts directly.
+    mcp.add_transform(ResourcesAsTools(mcp))
+    mcp.add_transform(PromptsAsTools(mcp))
+
     return mcp
 
 

tests/conftest.py

@@ -0,0 +1,18 @@
+from collections.abc import AsyncIterator
+
+import pytest
+from asgi_lifespan import LifespanManager
+from fastmcp.utilities.tests import ASGIServer
+
+from personal_mcp.app import create_app
+
+
+@pytest.fixture
+async def http_server() -> AsyncIterator[ASGIServer]:
+    app = create_app()
+    async with LifespanManager(app):
+        yield ASGIServer(
+            url="http://127.0.0.1/mcp",
+            app=app,
+            transport_type="http",
+        )

tests/server_contract.py

@@ -0,0 +1,34 @@
+from fastmcp import Client
+from mcp_types import TextContent
+from mcp_types import TextResourceContents
+
+
+async def assert_server_contract(client: Client) -> None:
+    resources = {str(resource.uri) for resource in await client.list_resources()}
+    templates = {str(template.uri_template) for template in await client.list_resource_templates()}
+    prompts = {prompt.name for prompt in await client.list_prompts()}
+    tools = {tool.name for tool in await client.list_tools()}
+
+    assert tools == {"get_prompt", "list_prompts", "list_resources", "read_resource"}
+    assert "skill://pytesting/SKILL.md" in resources
+    assert "resource://docs/{path*}" in templates
+    assert "skill://pytesting/{path*}" in templates
+    assert "pytest-fill-scaffold" in prompts
+
+    skill_content = await client.read_resource("skill://pytesting/SKILL.md")
+    docs_content = await client.read_resource("resource://docs/index.md")
+
+    assert isinstance(skill_content[0], TextResourceContents)
+    assert "# Pytesting" in skill_content[0].text
+    assert isinstance(docs_content[0], TextResourceContents)
+    assert '"format": "markdown"' in docs_content[0].text
+
+    listed = await client.call_tool("list_resources")
+    listed_content = listed.content[0]
+    assert isinstance(listed_content, TextContent)
+    assert "skill://pytesting/SKILL.md" in listed_content.text
+
+    read = await client.call_tool("read_resource", {"uri": "skill://pytesting/SKILL.md"})
+    read_content = read.content[0]
+    assert isinstance(read_content, TextContent)
+    assert "# Pytesting" in read_content.text

tests/test_http.py

@@ -0,0 +1,9 @@
+import pytest
+from fastmcp.utilities.tests import ASGIServer
+from server_contract import assert_server_contract
+
+
+@pytest.mark.integration
+async def test_fastapi_server(http_server: ASGIServer) -> None:
+    async with http_server.client() as client:
+        await assert_server_contract(client)

tests/test_stdio.py

@@ -0,0 +1,20 @@
+import sys
+from pathlib import Path
+
+import pytest
+from fastmcp import Client
+from fastmcp.client.transports import StdioTransport
+from server_contract import assert_server_contract
+
+
+@pytest.mark.integration
+async def test_stdio_server() -> None:
+    transport = StdioTransport(
+        command=sys.executable,
+        args=["-m", "personal_mcp.mcp"],
+        cwd=str(Path(__file__).parent.parent),
+        keep_alive=False,
+    )
+
+    async with Client(transport) as client:
+        await assert_server_contract(client)

uv.lock

@@ -52,6 +52,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/da/35/f2287558c17e29fafc8ef3daf819bb9834061cfa43bff8014f7df7f63bdc/anyio-4.14.2-py3-none-any.whl", hash = "sha256:9f505dda5ac9f0c8309b5e8bd445a8c2bf7246f3ce950121e45ea15bc41d1494", size = 125813, upload-time = "2026-07-12T20:29:05.763Z" },
 ]
 
+[[package]]
+name = "asgi-lifespan"
+version = "2.1.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "sniffio" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/6a/da/e7908b54e0f8043725a990bf625f2041ecf6bfe8eb7b19407f1c00b630f7/asgi-lifespan-2.1.0.tar.gz", hash = "sha256:5e2effaf0bfe39829cf2d64e7ecc47c7d86d676a6599f7afba378c31f5e3a308", size = 15627, upload-time = "2023-03-28T17:35:49.126Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/2f/f5/c36551e93acba41a59939ae6a0fb77ddb3f2e8e8caa716410c65f7341f72/asgi_lifespan-2.1.0-py3-none-any.whl", hash = "sha256:ed840706680e28428c01e14afb3875d7d76d3206f3d5b2f2294e059b5c23804f", size = 10895, upload-time = "2023-03-28T17:35:47.772Z" },
+]
+
 [[package]]
 name = "asttokens"
 version = "3.0.2"
@@ -1126,6 +1138,7 @@ dev = [
     { name = "ty" },
 ]
 test = [
+    { name = "asgi-lifespan" },
     { name = "httpx2" },
     { name = "pytest" },
     { name = "pytest-asyncio" },
@@ -1152,6 +1165,7 @@ dev = [
     { name = "ty", specifier = ">=0.0.51" },
 ]
 test = [
+    { name = "asgi-lifespan", specifier = ">=2.1.0" },
     { name = "httpx2", specifier = ">=2.9.1" },
     { name = "pytest", specifier = ">=9.1.1" },
     { name = "pytest-asyncio", specifier = ">=1.4.0" },
@@ -1781,6 +1795,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/b7/46/f5af3402b579fd5e11573ce652019a67074317e18c1935cc0b4ba9b35552/secretstorage-3.5.0-py3-none-any.whl", hash = "sha256:0ce65888c0725fcb2c5bc0fdb8e5438eece02c523557ea40ce0703c266248137", size = 15554, upload-time = "2025-11-23T19:02:51.545Z" },
 ]
 
+[[package]]
+name = "sniffio"
+version = "1.3.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/a2/87/a6771e1546d97e7e041b6ae58d80074f81b7d5121207425c964ddf5cfdbd/sniffio-1.3.1.tar.gz", hash = "sha256:f4324edc670a0f49750a81b895f35c3adb843cca46f0530f79fc1babb23789dc", size = 20372, upload-time = "2024-02-25T23:20:04.057Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e9/44/75a9c9421471a6c4805dbf2356f7c181a29c1879239abab1ea2cc8f38b40/sniffio-1.3.1-py3-none-any.whl", hash = "sha256:2f6da418d1f1e0fddd844478f41680e794e6051915791a034ff65e5f100525a2", size = 10235, upload-time = "2024-02-25T23:20:01.196Z" },
+]
+
 [[package]]
 name = "sse-starlette"
 version = "3.4.8"

zensical.toml

@@ -11,7 +11,7 @@
 # The site_name is shown in the page header and the browser window title
 #
 # Read more: https://zensical.org/docs/setup/basics/#site_name
-site_name = "Documentation"
+site_name = "Personal MCP"
 
 site_dir = "src/personal_mcp/site"
 docs_dir = "src/personal_mcp/docs"
@@ -20,12 +20,12 @@ docs_dir = "src/personal_mcp/docs"
 # meaningful description of the site content for use by search engines.
 #
 # Read more: https://zensical.org/docs/setup/basics/#site_description
-site_description = "A new project generated from the default template project."
+site_description = "Software development guidance published as MCP resources, prompts, and human-readable documentation."
 
 # The site_author attribute. This is used in the HTML head element.
 #
 # Read more: https://zensical.org/docs/setup/basics/#site_author
-site_author = "<your name here>"
+site_author = "Personal MCP"
 
 # The site_url is the canonical URL for your site. When building online
 # documentation you should set this.
@@ -47,115 +47,6 @@ Copyright &copy; 2026 The authors
 # can be defined using TOML syntax.
 #
 # Read more: https://zensical.org/docs/setup/navigation/
-# nav = [
-#   { "Home" = "index.md" },
-#   { "Guide" = [
-#     { "Arch" = "architecture.md" },
-#     { "Contracts" = [
-#       { "Overview" = "contracts/index.md" },
-#       { "Prompt" = "contracts/prompt.md" },
-#       { "Skill" = "contracts/skill_contract.md" },
-#       { "Frontmatter" = "contracts/frontmatter.md" },
-#       { "URIs" = "contracts/uris.md" },
-#     ] },
-#     { "MCP" = "mcp_layout.md" },
-#     { "Copilot" = "copilot.md" },
-#     { "Usage" = "usage.md" },
-#     { "Authoring" = "authoring.md" },
-#     { "Future Work" = "future_work.md" },
-#     { "Testing" = "testing.md" },
-#     { "Security" = "securing.md" },
-#   ] },
-#   { "Prompts" = [
-#     { "Authoring" = "prompts/authoring/PROMPT.md" },
-#     { "JSFiddle Page Layout" = "prompts/jsfiddle-page-layout/PROMPT.md" },
-#     { "NiceGUI Component Extraction" = "prompts/nicegui-component-extraction/PROMPT.md" },
-#     { "Pytest Fill Scaffold" = "prompts/pytest-fill-scaffold/PROMPT.md" },
-#     { "Pytest Scaffold" = "prompts/pytest-scaffold/PROMPT.md" },
-#     { "Greenfield Architecture" = "prompts/greenfield-architecture/PROMPT.md" },
-#     { "MCP Consumer Repo Shim" = "prompts/mcp-consumer-repo-shim/PROMPT.md" },
-#   ] },
-#   { "Skills" = [
-#     { "Copilot" = [
-#       { "Overview" = "skills/copilot-customization/SKILL.md" },
-#       { "VS Code" = "skills/copilot-customization/references/vscode-customization.md" },
-#     ] },
-#     { "VS Code Config" = [
-#       { "Overview" = "skills/vscode-configuration/SKILL.md" },
-#       { "Debug Launch" = "skills/vscode-configuration/references/debug-launch-configurations.md" },
-#       { "FastAPI Debug" = "skills/vscode-configuration/references/fastapi-debugpy-launch.md" },
-#       { "Tasks" = "skills/vscode-configuration/references/tasks-json-configuration.md" },
-#     ] },
-#     { "FastAPI UV" = [
-#       { "Overview" = "skills/fastapi-uv-docker/SKILL.md" },
-#       { "Best" = "skills/fastapi-uv-docker/references/fastapi-best-practices.md" },
-#       { "Layout" = "skills/fastapi-uv-docker/references/uv-project-layout.md" },
-#       { "Uvicorn" = "skills/fastapi-uv-docker/references/uvicorn-settings.md" },
-#       { "Docker" = "skills/fastapi-uv-docker/references/docker-cloud-native.md" },
-#     ] },
-#     { "Async SQLA" = [
-#       { "Overview" = "skills/async-fastapi-sqlmodel/SKILL.md" },
-#       { "Engine" = "skills/async-fastapi-sqlmodel/references/engine.md" },
-#       { "Session" = "skills/async-fastapi-sqlmodel/references/session.md" },
-#       { "FastAPI" = "skills/async-fastapi-sqlmodel/references/fastapi.md" },
-#       { "Tx" = "skills/async-fastapi-sqlmodel/references/transactions.md" },
-#       { "SQLModel" = "skills/async-fastapi-sqlmodel/references/sqlmodel.md" },
-#       { "CRUD" = "skills/async-fastapi-sqlmodel/references/crud.md" },
-#       { "Testing" = "skills/async-fastapi-sqlmodel/references/testing.md" },
-#       { "IO" = "skills/async-fastapi-sqlmodel/references/implicit_io.md" },
-#       { "Obs" = "skills/async-fastapi-sqlmodel/references/observability.md" },
-#       { "Template" = "skills/async-fastapi-sqlmodel/references/template.md" },
-#     ] },
-#     { "NiceGUI" = [
-#       { "Overview" = "skills/nicegui/SKILL.md" },
-#       { "App Architecture" = "skills/nicegui/references/architecture.md" },
-#       { "Startup" = "skills/nicegui/references/fastapi-uvicorn-startup.md" },
-#       { "Visual Styling" = "skills/nicegui/references/styling-and-customization.md" },
-#       { "Component Mechanics" = "skills/nicegui/references/component-mechanics.md" },
-#       { "Tables" = "skills/nicegui/references/tables.md" },
-#       { "Binding" = "skills/nicegui/references/binding-dataclasses.md" },
-#       { "Flows" = "skills/nicegui/references/interaction-patterns.md" },
-#       { "Quality" = "skills/nicegui/references/troubleshooting-and-quality-gates.md" },
-#       { "Sources" = "skills/nicegui/references/source-documentation.md" },
-#     ] },
-#     { "Pytest" = [
-#       { "Overview" = "skills/pytesting/SKILL.md" },
-#       { "Docs" = "skills/pytesting/references/pytest-docs.md" },
-#       { "AsyncIO" = "skills/pytesting/references/asyncio-testing.md" },
-#     ] },
-#     { "MCP Details" = [
-#       { "Overview" = "skills/mcp-details/SKILL.md" },
-#       { "Protocol" = "skills/mcp-details/references/mcp-protocol-and-spec.md" },
-#       { "SDKs and FastMCP" = "skills/mcp-details/references/sdk-and-fastmcp.md" },
-#       { "Ecosystem" = "skills/mcp-details/references/ecosystem-and-tooling.md" },
-#     ] },
-#     { "Logging" = [
-#       { "Overview" = "skills/python-logging/SKILL.md" },
-#       { "Docs" = "skills/python-logging/references/python-logging-docs.md" },
-#       { "JSON File" = "skills/python-logging/references/json-file-logging.md" },
-#       { "Network" = "skills/python-logging/references/network-logging-minimal-example.md" },
-#       { "HTTPX" = "skills/python-logging/references/httpx-logging-handler-example.md" },
-#     ] },
-#     { "Pydantic Settings" = [
-#       { "Overview" = "skills/pydantic-settings/SKILL.md" },
-#       { "Source Docs" = "skills/pydantic-settings/references/source-documentation.md" },
-#       { "Workflow" = "skills/pydantic-settings/references/implementation-workflow.md" },
-#     ] },
-#     { "Ruff" = [
-#       { "Overview" = "skills/ruff-linting-formating/SKILL.md" },
-#       { "Docs" = "skills/ruff-linting-formating/references/ruff-docs.md" },
-#       { "Integrations" = "skills/ruff-linting-formating/references/ruff-integrations.md" },
-#     ] },
-#     { "Zensical" = [
-#       { "Overview" = "skills/zensical-docs/SKILL.md" },
-#       { "Features" = "skills/zensical-docs/references/zensical-features.md" },
-#       { "Theme" = "skills/zensical-docs/references/theme-customization-and-icons.md" },
-#       { "Quality" = "skills/zensical-docs/references/documentation-quality.md" },
-#       { "IA" = "skills/zensical-docs/references/discoverability-and-ia.md" },
-#       { "API Docs" = "skills/zensical-docs/references/code-heavy-docs-and-mkdocstrings.md" },
-#     ] },
-#   ] },
-# ]
 
 # With the "extra_css" option you can add your own CSS styling to customize
 # your Zensical project according to your needs. You can add any number of