diff --git a/.github/instructions/memory.instructions.md b/.github/instructions/memory.instructions.md
new file mode 100644
index 0000000..a64190d
--- /dev/null
+++ b/.github/instructions/memory.instructions.md
@@ -0,0 +1,41 @@
+---
+description: Session handoff for webware-theme — theme resolver state, spec-kit location, and where the decision log and standing rules live, as of 2026-10-01.
+applyTo: '**/*'
+---
+
+# Webware Theme Memory
+
+Tagline: Theme resolution by lookup, not by path stacking. The resolver is built; the asset helper, the
+default theme and the template port are open. Everything needed to continue is in `specs/001-theme-resolution/`.
+
+## Start here
+
+1. `specs/001-theme-resolution/decisions.md` — current state, the owner's standing rules, the decision log
+   (D-001 onwards) with statuses, next actions, gotchas. **Read it first.**
+2. `specs/001-theme-resolution/tasks.md` — what is done and what is left; the next free task ID is stated at
+   the top.
+3. `spec.md` (requirements), `plan.md` (design, with a built-versus-planned table), `data-model.md`
+   (configuration shape), `research.md` (measurements), `quickstart.md`.
+
+Spec-kit, `.specify/` and `specs/` are tracked in this repository on purpose; do not propose removing them.
+
+## What exists
+
+- `Webware\Theme\Resolver\ThemeResolver` (final, `ResolverInterface`): `maps[active][name] ?? maps['default'][name]
+  ?? false`, no filesystem call. `ThemeResolverFactory` reads `theme.themes` and `theme.active`.
+  `AggregateResolverFactory` attaches theme at 100, `TemplateMapResolver` at 50, the namespaced path stack at 1.
+  `ConfigProvider` must be merged after `Mezzio\LaminasView\ConfigProvider`.
+- The asset helper key is `view_helper_config.asset.resource_map` (not `view_manager.asset`).
+- Assets are served from `/theme/<theme>/{css,js,img,fonts}`, never from a bare `/<theme>/` (`.htaccess` would let a
+  directory shadow a route).
+
+## Rules that bite
+
+- Every change goes through a pull request; never push to `1.0.x`. Releases and tags belong to the owner.
+- Never delete, rename or move a file without approval. Never edit the IMS repository (read-only).
+- Named arguments always; never change form field names.
+- Never run application code while a debug session may be attached (`ss -ltnp | grep -E ':(9000|9003)'`).
+- Check Mago gates by exit code, not by the last line of output.
+- Commits: `git commit -s` as `Joey Smith <jsmith@webinertia.net>`; merge commits by default.
+
+The full list is `decisions.md` section 2 and `vendor/webware/webware-tools/agent-working-agreements.md`.
diff --git a/README.md b/README.md
index 20d3d28..4d56e1c 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,8 @@
 # webware/webware-theme
 
-Theme support for Webware applications: a theme is a directory under a component's
-`templates/`, resolved by name through laminas-view, with per-template fallback to the
-`default` theme that every component ships.
+Theme support for Webware applications. A theme is a set of template and asset overrides; the active theme
+is consulted first and `default` answers for everything it does not override. Template lookups are a
+single array read, with no filesystem walk.
 
 [![PHP Version](https://img.shields.io/packagist/php-v/webware/webware-theme)](https://packagist.org/packages/webware/webware-theme)
 [![Latest Version](https://img.shields.io/packagist/v/webware/webware-theme)](https://packagist.org/packages/webware/webware-theme)
@@ -11,45 +11,64 @@ Theme support for Webware applications: a theme is a directory under a component
 [![codecov](https://codecov.io/gh/webinertia/webware-theme/graph/badge.svg)](https://codecov.io/gh/webinertia/webware-theme)
 [![Mutation testing badge](https://img.shields.io/endpoint?style=flat&url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2Fwebinertia%2Fwebware-theme%2F1.0.x)](https://dashboard.stryker-mutator.io/reports/github.com/webinertia/webware-theme/1.0.x)
 
-## The convention
+## Quickstart
 
-A theme is a directory named for the theme, directly inside a module's `templates/` directory, holding one
-subdirectory per template namespace:
+1. Install it and register the provider **after** `Mezzio\LaminasView\ConfigProvider`:
 
-```
-src/App/templates/
-├── default/                  # every module that ships templates ships this one
-│   ├── app/home-page.phtml          -> app::home-page.phtml
-│   ├── layout/default.phtml         -> layout::default
-│   └── admin/dashboard.phtml        -> admin::dashboard.phtml   (a vendor template, overridden here)
-└── acme/                     # a theme, same layout of files
-    └── layout/default.phtml         -> layout::default
+```bash
+composer require webware/webware-theme
 ```
 
-Addresses stay mezzio's namespaced ones — `<namespace>::<name>` — and the theme selects the first
-directory segment, so it is never part of the address and a component's references to its own templates
-survive a theme change. Resolution consults the paths a namespace is served from, the active theme's
-directory before `default`, and falls back **per template**, so a theme that overrides one layout leaves
-every other template coming from `default`. A module overrides another module's template by placing that
-namespace under its own theme directory — which is how an application restyles a vendor template without
-touching the package that ships it.
-
-That is the whole mechanism: a redesign is a directory of templates plus the assets that go with it, not
-a fork of every package. Templates resolve from `templates/`; assets are served from `public/theme/<theme>/`
-(a theme's `templates/` directory is never a served location); nothing is compiled, published or watched.
+```php
+Mezzio\LaminasView\ConfigProvider::class,
+Webware\Theme\ConfigProvider::class,
+```
 
-## Installation
+2. Describe a theme in any autoloaded config file, for example `config/autoload/theme.acme.global.php`:
 
-```bash
-composer require webware/webware-theme
+```php
+use Webware\Theme\ConfigProvider;
+
+return [
+    ConfigProvider::THEME => [
+        ConfigProvider::ACTIVE => 'acme',
+        ConfigProvider::THEMES => [
+            'acme' => [
+                // only the addresses this theme overrides
+                'layout::default' => __DIR__ . '/../../templates/acme/layout/default.phtml',
+            ],
+        ],
+        ConfigProvider::ASSETS => [
+            'acme' => ['theme.css' => 'css/acme.css'],
+        ],
+    ],
+];
 ```
 
-Register the `ConfigProvider` in your Mezzio application config aggregator:
+3. Put the asset file at `public/theme/acme/css/acme.css`, and use it in a template:
 
 ```php
-Webware\Theme\ConfigProvider::class,
+<link rel="stylesheet" href="<?= $this->asset('theme.css') ?>">
 ```
 
+`layout::default` now comes from the `acme` theme and every other address from `default`;
+`asset('theme.css')` returns `/theme/acme/css/acme.css`, and a name `acme` does not define falls back to the
+`default` theme's file. Anything not listed in a theme falls back to `default` per address and per name.
+Addresses stay mezzio's namespaced ones (`<namespace>::<name>`) and never contain a theme name, so a
+component's references to its own templates survive a theme change.
+
+## Documentation
+
+| Document | Contents |
+|---|---|
+| [Installation](docs/v1/installation.md) | Requirements, provider order, what the provider registers |
+| [Configuration](docs/v1/configuration.md) | The `theme.active`, `theme.themes` and `theme.assets` keys and their rules |
+| [Template resolution](docs/v1/template-resolution.md) | How `ThemeResolver` answers, and the resolver order |
+| [Assets](docs/v1/assets.md) | The theme-aware `asset()` helper, URL layout, theme-name rules |
+
+Not built yet: publishing assets into `public/`, the command that creates and switches themes, and the
+admin widget. They are specified in `specs/001-theme-resolution/`.
+
 ## Design
 
 The design and its measurements live with the component, in `specs/001-theme-resolution/`:
diff --git a/composer.json b/composer.json
index 6d875cd..a136e80 100644
--- a/composer.json
+++ b/composer.json
@@ -23,6 +23,7 @@
     "require": {
         "php": "~8.4.1 || ~8.5.0",
         "laminas/laminas-view": "^3.0",
+        "mezzio/mezzio-laminasviewrenderer": "^3.0",
         "psr/container": "^2.0"
     },
     "require-dev": {
diff --git a/composer.lock b/composer.lock
index 4aa7fe9..4f7920d 100644
--- a/composer.lock
+++ b/composer.lock
@@ -4,7 +4,7 @@
         "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
         "This file is @generated automatically"
     ],
-    "content-hash": "82485d307068fd00125d2028195b3b95",
+    "content-hash": "e8e4c3632803b8156ef05080cf22b040",
     "packages": [
         {
             "name": "brick/varexporter",
@@ -55,6 +55,62 @@
             ],
             "time": "2025-02-20T17:42:39+00:00"
         },
+        {
+            "name": "fig/http-message-util",
+            "version": "1.1.5",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/php-fig/http-message-util.git",
+                "reference": "9d94dc0154230ac39e5bf89398b324a86f63f765"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/php-fig/http-message-util/zipball/9d94dc0154230ac39e5bf89398b324a86f63f765",
+                "reference": "9d94dc0154230ac39e5bf89398b324a86f63f765",
+                "shasum": ""
+            },
+            "require": {
+                "php": "^5.3 || ^7.0 || ^8.0"
+            },
+            "suggest": {
+                "psr/http-message": "The package containing the PSR-7 interfaces"
+            },
+            "type": "library",
+            "extra": {
+                "branch-alias": {
+                    "dev-master": "1.1.x-dev"
+                }
+            },
+            "autoload": {
+                "psr-4": {
+                    "Fig\\Http\\Message\\": "src/"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "PHP-FIG",
+                    "homepage": "https://www.php-fig.org/"
+                }
+            ],
+            "description": "Utility classes and constants for use with PSR-7 (psr/http-message)",
+            "keywords": [
+                "http",
+                "http-message",
+                "psr",
+                "psr-7",
+                "request",
+                "response"
+            ],
+            "support": {
+                "issues": "https://github.com/php-fig/http-message-util/issues",
+                "source": "https://github.com/php-fig/http-message-util/tree/1.1.5"
+            },
+            "time": "2020-11-24T22:02:12+00:00"
+        },
         {
             "name": "laminas/laminas-escaper",
             "version": "2.18.0",
@@ -396,6 +452,302 @@
             ],
             "time": "2026-06-02T22:39:05+00:00"
         },
+        {
+            "name": "mezzio/mezzio-helpers",
+            "version": "5.20.0",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/mezzio/mezzio-helpers.git",
+                "reference": "a26ba04bd449d5cdb5ad38b17ce672365dbc9d90"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/mezzio/mezzio-helpers/zipball/a26ba04bd449d5cdb5ad38b17ce672365dbc9d90",
+                "reference": "a26ba04bd449d5cdb5ad38b17ce672365dbc9d90",
+                "shasum": ""
+            },
+            "require": {
+                "mezzio/mezzio-router": "^3.18 || ^4.0",
+                "php": "~8.2.0 || ~8.3.0 || ~8.4.0 || ~8.5.0",
+                "psr/container": "^1.0 || ^2.0",
+                "psr/http-message": "^1.0.1 || ^2.0.0",
+                "psr/http-server-middleware": "^1.0"
+            },
+            "conflict": {
+                "amphp/amp": "<2.6.4",
+                "amphp/dns": "<2.1.2",
+                "amphp/socket": "<2.3.1",
+                "zendframework/zend-expressive-helpers": "*"
+            },
+            "require-dev": {
+                "ext-json": "*",
+                "laminas/laminas-coding-standard": "~3.1.0",
+                "laminas/laminas-diactoros": "^3.6",
+                "phpunit/phpunit": "^11.5.42",
+                "psalm/plugin-phpunit": "^0.19.5",
+                "vimeo/psalm": "^6.13.1"
+            },
+            "suggest": {
+                "ext-json": "If you wish to use the JsonStrategy with BodyParamsMiddleware"
+            },
+            "type": "library",
+            "extra": {
+                "laminas": {
+                    "config-provider": "Mezzio\\Helper\\ConfigProvider"
+                }
+            },
+            "autoload": {
+                "psr-4": {
+                    "Mezzio\\Helper\\": "src/"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "BSD-3-Clause"
+            ],
+            "description": "Helper/Utility classes for Mezzio",
+            "homepage": "https://mezzio.dev",
+            "keywords": [
+                "http",
+                "laminas",
+                "mezzio",
+                "middleware",
+                "psr",
+                "psr-7"
+            ],
+            "support": {
+                "chat": "https://laminas.dev/chat",
+                "docs": "https://docs.mezzio.dev/mezzio/features/helpers/intro/",
+                "forum": "https://discourse.laminas.dev",
+                "issues": "https://github.com/mezzio/mezzio-helpers/issues",
+                "rss": "https://github.com/mezzio/mezzio-helpers/releases.atom",
+                "source": "https://github.com/mezzio/mezzio-helpers"
+            },
+            "funding": [
+                {
+                    "url": "https://funding.communitybridge.org/projects/laminas-project",
+                    "type": "community_bridge"
+                }
+            ],
+            "time": "2025-10-11T08:40:34+00:00"
+        },
+        {
+            "name": "mezzio/mezzio-laminasviewrenderer",
+            "version": "3.0.0",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/mezzio/mezzio-laminasviewrenderer.git",
+                "reference": "ac78584ea1c417f4f4289616add5ca8d96c78f62"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/mezzio/mezzio-laminasviewrenderer/zipball/ac78584ea1c417f4f4289616add5ca8d96c78f62",
+                "reference": "ac78584ea1c417f4f4289616add5ca8d96c78f62",
+                "shasum": ""
+            },
+            "require": {
+                "laminas/laminas-servicemanager": "^4.4.0",
+                "laminas/laminas-view": "^3.0.1",
+                "mezzio/mezzio-helpers": "^5.15.0",
+                "mezzio/mezzio-router": "^3.16.1 || ^4.0.0",
+                "mezzio/mezzio-template": "^3.0",
+                "php": "~8.2.0 || ~8.3.0 || ~8.4.0 || ~8.5.0",
+                "psr/container": "^1.0 || ^2.0",
+                "psr/http-message": "^1.0.1 || ^2.0.0"
+            },
+            "require-dev": {
+                "laminas/laminas-coding-standard": "^3.1.0",
+                "mezzio/mezzio-fastroute": "^3.14",
+                "phpunit/phpunit": "^11.5.44",
+                "psalm/plugin-phpunit": "^0.19.5",
+                "vimeo/psalm": "^6.13.1"
+            },
+            "type": "library",
+            "extra": {
+                "laminas": {
+                    "config-provider": "Mezzio\\LaminasView\\ConfigProvider"
+                }
+            },
+            "autoload": {
+                "psr-4": {
+                    "Mezzio\\LaminasView\\": "src/"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "BSD-3-Clause"
+            ],
+            "description": "laminas-view PhpRenderer integration for Mezzio",
+            "homepage": "https://mezzio.dev",
+            "keywords": [
+                "http",
+                "laminas",
+                "mezzio",
+                "middleware",
+                "psr",
+                "psr-7"
+            ],
+            "support": {
+                "chat": "https://laminas.dev/chat",
+                "docs": "https://docs.mezzio.dev/mezzio/features/template/laminas-view/",
+                "forum": "https://discourse.laminas.dev",
+                "issues": "https://github.com/mezzio/mezzio-laminasviewrenderer/issues",
+                "rss": "https://github.com/mezzio/mezzio-laminasviewrenderer/releases.atom",
+                "source": "https://github.com/mezzio/mezzio-laminasviewrenderer"
+            },
+            "funding": [
+                {
+                    "url": "https://funding.communitybridge.org/projects/laminas-project",
+                    "type": "community_bridge"
+                }
+            ],
+            "time": "2025-11-26T16:34:39+00:00"
+        },
+        {
+            "name": "mezzio/mezzio-router",
+            "version": "4.2.0",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/mezzio/mezzio-router.git",
+                "reference": "e7a6505d7e460ce30c4135e146241d7d24d81c27"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/mezzio/mezzio-router/zipball/e7a6505d7e460ce30c4135e146241d7d24d81c27",
+                "reference": "e7a6505d7e460ce30c4135e146241d7d24d81c27",
+                "shasum": ""
+            },
+            "require": {
+                "fig/http-message-util": "^1.1.5",
+                "php": "~8.2.0 || ~8.3.0 || ~8.4.0 || ~8.5.0",
+                "psr/container": "^1.1.2 || ^2.0",
+                "psr/http-factory": "^1.0.2",
+                "psr/http-message": "^1.0.1 || ^2.0.0",
+                "psr/http-server-middleware": "^1.0.2",
+                "webmozart/assert": "^1.11.0 || ^2.1.1"
+            },
+            "conflict": {
+                "mezzio/mezzio": "<3.5",
+                "zendframework/zend-expressive-router": "*"
+            },
+            "require-dev": {
+                "laminas/laminas-coding-standard": "~3.1.0",
+                "laminas/laminas-diactoros": "^3.6.0",
+                "laminas/laminas-servicemanager": "^4.4.0",
+                "laminas/laminas-stratigility": "^4.2.0",
+                "phpunit/phpunit": "^11.5.42",
+                "psalm/plugin-phpunit": "^0.19.5",
+                "vimeo/psalm": "^6.13.1"
+            },
+            "suggest": {
+                "mezzio/mezzio-fastroute": "^3.0 to use the FastRoute routing adapter",
+                "mezzio/mezzio-laminasrouter": "^3.0 to use the laminas-router routing adapter"
+            },
+            "type": "library",
+            "extra": {
+                "laminas": {
+                    "config-provider": "Mezzio\\Router\\ConfigProvider"
+                }
+            },
+            "autoload": {
+                "psr-4": {
+                    "Mezzio\\Router\\": "src/"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "BSD-3-Clause"
+            ],
+            "description": "Router subcomponent for Mezzio",
+            "homepage": "https://mezzio.dev",
+            "keywords": [
+                "http",
+                "laminas",
+                "mezzio",
+                "middleware",
+                "psr",
+                "psr-7"
+            ],
+            "support": {
+                "chat": "https://laminas.dev/chat",
+                "docs": "https://docs.mezzio.dev/mezzio/features/router/intro/",
+                "forum": "https://discourse.laminas.dev",
+                "issues": "https://github.com/mezzio/mezzio-router/issues",
+                "rss": "https://github.com/mezzio/mezzio-router/releases.atom",
+                "source": "https://github.com/mezzio/mezzio-router"
+            },
+            "funding": [
+                {
+                    "url": "https://funding.communitybridge.org/projects/laminas-project",
+                    "type": "community_bridge"
+                }
+            ],
+            "time": "2026-01-09T11:44:24+00:00"
+        },
+        {
+            "name": "mezzio/mezzio-template",
+            "version": "3.0.0",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/mezzio/mezzio-template.git",
+                "reference": "49a797e19b167b208327854c81eb079937f0b161"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/mezzio/mezzio-template/zipball/49a797e19b167b208327854c81eb079937f0b161",
+                "reference": "49a797e19b167b208327854c81eb079937f0b161",
+                "shasum": ""
+            },
+            "require": {
+                "php": "~8.2.0 || ~8.3.0 || ~8.4.0 || ~8.5.0"
+            },
+            "conflict": {
+                "zendframework/zend-expressive-template": "*"
+            },
+            "require-dev": {
+                "laminas/laminas-coding-standard": "~3.1.0",
+                "phpunit/phpunit": "^11.5.42",
+                "psalm/plugin-phpunit": "^0.19.5",
+                "vimeo/psalm": "^6.13.1"
+            },
+            "suggest": {
+                "mezzio/mezzio-laminasviewrenderer": "^2.0 to use the laminas-view PhpRenderer template renderer",
+                "mezzio/mezzio-platesrenderer": "^2.0 to use the Plates template renderer",
+                "mezzio/mezzio-twigrenderer": "^2.0 to use the Twig template renderer"
+            },
+            "type": "library",
+            "autoload": {
+                "psr-4": {
+                    "Mezzio\\Template\\": "src/"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "BSD-3-Clause"
+            ],
+            "description": "Template subcomponent for Mezzio",
+            "homepage": "https://mezzio.dev",
+            "keywords": [
+                "laminas",
+                "mezzio",
+                "template"
+            ],
+            "support": {
+                "chat": "https://laminas.dev/chat",
+                "docs": "https://docs.mezzio.dev/mezzio/features/template/intro/",
+                "forum": "https://discourse.laminas.dev",
+                "issues": "https://github.com/mezzio/mezzio-template/issues",
+                "rss": "https://github.com/mezzio/mezzio-template/releases.atom",
+                "source": "https://github.com/mezzio/mezzio-template"
+            },
+            "funding": [
+                {
+                    "url": "https://funding.communitybridge.org/projects/laminas-project",
+                    "type": "community_bridge"
+                }
+            ],
+            "time": "2025-10-11T09:18:27+00:00"
+        },
         {
             "name": "nikic/php-parser",
             "version": "v5.9.0",
@@ -505,6 +857,293 @@
                 "source": "https://github.com/php-fig/container/tree/2.0.2"
             },
             "time": "2021-11-05T16:47:00+00:00"
+        },
+        {
+            "name": "psr/http-factory",
+            "version": "1.1.0",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/php-fig/http-factory.git",
+                "reference": "2b4765fddfe3b508ac62f829e852b1501d3f6e8a"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/php-fig/http-factory/zipball/2b4765fddfe3b508ac62f829e852b1501d3f6e8a",
+                "reference": "2b4765fddfe3b508ac62f829e852b1501d3f6e8a",
+                "shasum": ""
+            },
+            "require": {
+                "php": ">=7.1",
+                "psr/http-message": "^1.0 || ^2.0"
+            },
+            "type": "library",
+            "extra": {
+                "branch-alias": {
+                    "dev-master": "1.0.x-dev"
+                }
+            },
+            "autoload": {
+                "psr-4": {
+                    "Psr\\Http\\Message\\": "src/"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "PHP-FIG",
+                    "homepage": "https://www.php-fig.org/"
+                }
+            ],
+            "description": "PSR-17: Common interfaces for PSR-7 HTTP message factories",
+            "keywords": [
+                "factory",
+                "http",
+                "message",
+                "psr",
+                "psr-17",
+                "psr-7",
+                "request",
+                "response"
+            ],
+            "support": {
+                "source": "https://github.com/php-fig/http-factory"
+            },
+            "time": "2024-04-15T12:06:14+00:00"
+        },
+        {
+            "name": "psr/http-message",
+            "version": "2.0",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/php-fig/http-message.git",
+                "reference": "402d35bcb92c70c026d1a6a9883f06b2ead23d71"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/php-fig/http-message/zipball/402d35bcb92c70c026d1a6a9883f06b2ead23d71",
+                "reference": "402d35bcb92c70c026d1a6a9883f06b2ead23d71",
+                "shasum": ""
+            },
+            "require": {
+                "php": "^7.2 || ^8.0"
+            },
+            "type": "library",
+            "extra": {
+                "branch-alias": {
+                    "dev-master": "2.0.x-dev"
+                }
+            },
+            "autoload": {
+                "psr-4": {
+                    "Psr\\Http\\Message\\": "src/"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "PHP-FIG",
+                    "homepage": "https://www.php-fig.org/"
+                }
+            ],
+            "description": "Common interface for HTTP messages",
+            "homepage": "https://github.com/php-fig/http-message",
+            "keywords": [
+                "http",
+                "http-message",
+                "psr",
+                "psr-7",
+                "request",
+                "response"
+            ],
+            "support": {
+                "source": "https://github.com/php-fig/http-message/tree/2.0"
+            },
+            "time": "2023-04-04T09:54:51+00:00"
+        },
+        {
+            "name": "psr/http-server-handler",
+            "version": "1.0.2",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/php-fig/http-server-handler.git",
+                "reference": "84c4fb66179be4caaf8e97bd239203245302e7d4"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/php-fig/http-server-handler/zipball/84c4fb66179be4caaf8e97bd239203245302e7d4",
+                "reference": "84c4fb66179be4caaf8e97bd239203245302e7d4",
+                "shasum": ""
+            },
+            "require": {
+                "php": ">=7.0",
+                "psr/http-message": "^1.0 || ^2.0"
+            },
+            "type": "library",
+            "extra": {
+                "branch-alias": {
+                    "dev-master": "1.0.x-dev"
+                }
+            },
+            "autoload": {
+                "psr-4": {
+                    "Psr\\Http\\Server\\": "src/"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "PHP-FIG",
+                    "homepage": "https://www.php-fig.org/"
+                }
+            ],
+            "description": "Common interface for HTTP server-side request handler",
+            "keywords": [
+                "handler",
+                "http",
+                "http-interop",
+                "psr",
+                "psr-15",
+                "psr-7",
+                "request",
+                "response",
+                "server"
+            ],
+            "support": {
+                "source": "https://github.com/php-fig/http-server-handler/tree/1.0.2"
+            },
+            "time": "2023-04-10T20:06:20+00:00"
+        },
+        {
+            "name": "psr/http-server-middleware",
+            "version": "1.0.2",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/php-fig/http-server-middleware.git",
+                "reference": "c1481f747daaa6a0782775cd6a8c26a1bf4a3829"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/php-fig/http-server-middleware/zipball/c1481f747daaa6a0782775cd6a8c26a1bf4a3829",
+                "reference": "c1481f747daaa6a0782775cd6a8c26a1bf4a3829",
+                "shasum": ""
+            },
+            "require": {
+                "php": ">=7.0",
+                "psr/http-message": "^1.0 || ^2.0",
+                "psr/http-server-handler": "^1.0"
+            },
+            "type": "library",
+            "extra": {
+                "branch-alias": {
+                    "dev-master": "1.0.x-dev"
+                }
+            },
+            "autoload": {
+                "psr-4": {
+                    "Psr\\Http\\Server\\": "src/"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "PHP-FIG",
+                    "homepage": "https://www.php-fig.org/"
+                }
+            ],
+            "description": "Common interface for HTTP server-side middleware",
+            "keywords": [
+                "http",
+                "http-interop",
+                "middleware",
+                "psr",
+                "psr-15",
+                "psr-7",
+                "request",
+                "response"
+            ],
+            "support": {
+                "issues": "https://github.com/php-fig/http-server-middleware/issues",
+                "source": "https://github.com/php-fig/http-server-middleware/tree/1.0.2"
+            },
+            "time": "2023-04-11T06:14:47+00:00"
+        },
+        {
+            "name": "webmozart/assert",
+            "version": "2.4.1",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/webmozarts/assert.git",
+                "reference": "2ccb7c2e821038c03a3e6e1700c570c158c55f70"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/webmozarts/assert/zipball/2ccb7c2e821038c03a3e6e1700c570c158c55f70",
+                "reference": "2ccb7c2e821038c03a3e6e1700c570c158c55f70",
+                "shasum": ""
+            },
+            "require": {
+                "ext-ctype": "*",
+                "ext-date": "*",
+                "ext-filter": "*",
+                "php": "^8.2"
+            },
+            "suggest": {
+                "ext-intl": "",
+                "ext-simplexml": "",
+                "ext-spl": ""
+            },
+            "type": "library",
+            "extra": {
+                "psalm": {
+                    "pluginClass": "Webmozart\\Assert\\PsalmPlugin"
+                },
+                "branch-alias": {
+                    "dev-master": "2.0-dev",
+                    "dev-feature/2-0": "2.0-dev"
+                }
+            },
+            "autoload": {
+                "psr-4": {
+                    "Webmozart\\Assert\\": "src/"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "Bernhard Schussek",
+                    "email": "bschussek@gmail.com"
+                },
+                {
+                    "name": "Woody Gilk",
+                    "email": "woody.gilk@gmail.com"
+                }
+            ],
+            "description": "Assertions to validate method input/output with nice error messages.",
+            "keywords": [
+                "assert",
+                "check",
+                "validate"
+            ],
+            "support": {
+                "issues": "https://github.com/webmozarts/assert/issues",
+                "source": "https://github.com/webmozarts/assert/tree/2.4.1"
+            },
+            "time": "2026-06-15T15:31:57+00:00"
         }
     ],
     "packages-dev": [
@@ -9617,72 +10256,6 @@
             ],
             "time": "2025-12-08T11:19:18+00:00"
         },
-        {
-            "name": "webmozart/assert",
-            "version": "2.4.1",
-            "source": {
-                "type": "git",
-                "url": "https://github.com/webmozarts/assert.git",
-                "reference": "2ccb7c2e821038c03a3e6e1700c570c158c55f70"
-            },
-            "dist": {
-                "type": "zip",
-                "url": "https://api.github.com/repos/webmozarts/assert/zipball/2ccb7c2e821038c03a3e6e1700c570c158c55f70",
-                "reference": "2ccb7c2e821038c03a3e6e1700c570c158c55f70",
-                "shasum": ""
-            },
-            "require": {
-                "ext-ctype": "*",
-                "ext-date": "*",
-                "ext-filter": "*",
-                "php": "^8.2"
-            },
-            "suggest": {
-                "ext-intl": "",
-                "ext-simplexml": "",
-                "ext-spl": ""
-            },
-            "type": "library",
-            "extra": {
-                "psalm": {
-                    "pluginClass": "Webmozart\\Assert\\PsalmPlugin"
-                },
-                "branch-alias": {
-                    "dev-master": "2.0-dev",
-                    "dev-feature/2-0": "2.0-dev"
-                }
-            },
-            "autoload": {
-                "psr-4": {
-                    "Webmozart\\Assert\\": "src/"
-                }
-            },
-            "notification-url": "https://packagist.org/downloads/",
-            "license": [
-                "MIT"
-            ],
-            "authors": [
-                {
-                    "name": "Bernhard Schussek",
-                    "email": "bschussek@gmail.com"
-                },
-                {
-                    "name": "Woody Gilk",
-                    "email": "woody.gilk@gmail.com"
-                }
-            ],
-            "description": "Assertions to validate method input/output with nice error messages.",
-            "keywords": [
-                "assert",
-                "check",
-                "validate"
-            ],
-            "support": {
-                "issues": "https://github.com/webmozarts/assert/issues",
-                "source": "https://github.com/webmozarts/assert/tree/2.4.1"
-            },
-            "time": "2026-06-15T15:31:57+00:00"
-        },
         {
             "name": "webmozart/glob",
             "version": "4.7.0",
diff --git a/docs/v1/assets.md b/docs/v1/assets.md
new file mode 100644
index 0000000..ceb9187
--- /dev/null
+++ b/docs/v1/assets.md
@@ -0,0 +1,50 @@
+# Assets
+
+laminas-view's `asset()` helper maps a fixed name to a URL and throws on a name it does not know. It is
+`final readonly` and has no idea of a theme, so this package replaces its **factory**, not the helper.
+`Webware\Theme\View\Helper\Container\AssetFactory` is registered under `view_helpers.factories` and
+returns the stock `Laminas\View\Helper\Asset`.
+
+```php
+<link rel="stylesheet" href="<?= $this->asset('theme.css') ?>">
+```
+
+## How the map is built
+
+1. Start from `view_helper_config.asset.resource_map`, so an application's existing entries keep working.
+2. Apply `theme.assets.default`, then `theme.assets.<active>` over it.
+3. For each value:
+   - starting with `https://`, `http://` or `//`: used unchanged;
+   - anything else: `/theme/<theme>/<value>`, with leading slashes on the value removed.
+
+The `<theme>` in the URL is the theme that **defined** the value, so a name the active theme does not
+define still points at the `default` theme's file. Fallback is per name.
+
+## Where the files go
+
+```
+public/theme/<theme>/css/...
+public/theme/<theme>/js/...
+public/theme/<theme>/img/...
+public/theme/<theme>/fonts/...
+```
+
+The prefix `/theme/` is deliberate: the web server serves existing files and directories before it routes,
+so a directory named after a theme at the web root could shadow a route of the same name.
+
+A component's own assets are planned per theme under `public/theme/<theme>/component/<component>/`
+(decision D-011). Publishing files into `public/` is the composer plugin installer's job
+(`webinertia/project-tracking#6`) and is not part of this package; until it exists, place the files by
+hand.
+
+## Theme names
+
+A theme name that becomes part of a URL must be a single path segment: it matches
+`^[A-Za-z0-9][A-Za-z0-9_-]*$`. Anything else, for example `..`, `a/b` or `.hidden`, makes the helper's
+factory throw `Webware\Theme\Exception\InvalidThemeNameException`. Both the `default` theme and the active
+theme are checked.
+
+## Unknown names
+
+The stock helper throws `Laminas\View\Exception\InvalidArgumentException` for a name no theme defines.
+That is intended: an asset a template asks for must exist.
diff --git a/docs/v1/configuration.md b/docs/v1/configuration.md
new file mode 100644
index 0000000..51e9561
--- /dev/null
+++ b/docs/v1/configuration.md
@@ -0,0 +1,46 @@
+# Configuration
+
+Everything sits under one key. The keys have constants on `Webware\Theme\ConfigProvider`.
+
+```php
+use Webware\Theme\ConfigProvider;
+
+return [
+    ConfigProvider::THEME => [                 // 'theme'
+        ConfigProvider::ACTIVE => 'acme',      // 'active'  the theme to use; absent or empty means 'default'
+        ConfigProvider::THEMES => [            // 'themes'  template overrides per theme
+            'acme' => [
+                'layout::default'      => __DIR__ . '/../../templates/acme/layout/default.phtml',
+                'app::home-page.phtml' => __DIR__ . '/../../templates/acme/app/home-page.phtml',
+            ],
+        ],
+        ConfigProvider::ASSETS => [            // 'assets'  asset values per theme
+            'default' => ['theme.css' => 'css/theme.css'],
+            'acme'    => ['theme.css' => 'css/acme.css'],
+        ],
+    ],
+];
+```
+
+| Key | Type | Meaning |
+|---|---|---|
+| `theme.active` | non-empty string | The active theme. A missing or empty value means `default`. |
+| `theme.themes.<theme>.<address>` | absolute path | A template address the theme overrides. |
+| `theme.assets.<theme>.<name>` | string | An asset value: a path relative to the theme's directory, or an absolute URL. |
+
+## Rules
+
+- Addresses are mezzio's namespaced ones (`namespace::name`) and never contain a theme name.
+- Anything a theme does not list falls back to the `default` theme, address by address (templates) and
+  name by name (assets).
+- A path in `theme.themes` is trusted: it is used as written and not checked on disk.
+- Configuration merges with the usual config aggregator rules: string keys are later-wins, so an
+  application's autoload file overrides a package's defaults.
+- The active theme is read once, when the factories run. Changing it means clearing the aggregated config
+  cache.
+
+## Where the keys are planned to live
+
+Per the decisions log (`specs/001-theme-resolution/decisions.md`, D-012 and D-020): a future command will write
+each theme's `theme.themes` map to `config/autoload/theme.{theme-name}.global.php` and `theme.active` to
+`config/autoload/theme.settings.global.php`. Until then, write them by hand in any autoload file.
diff --git a/docs/v1/installation.md b/docs/v1/installation.md
new file mode 100644
index 0000000..6b10f45
--- /dev/null
+++ b/docs/v1/installation.md
@@ -0,0 +1,37 @@
+# Installation
+
+```bash
+composer require webware/webware-theme
+```
+
+Requires PHP `~8.4.1 || ~8.5.0`, `laminas/laminas-view` and `mezzio/mezzio-laminasviewrenderer`.
+
+## Register the config provider
+
+`Webware\Theme\ConfigProvider` is declared under `extra.laminas.config-provider`, so a config aggregator
+that reads composer's providers picks it up. If you list providers by hand, put it
+**after** `Mezzio\LaminasView\ConfigProvider`:
+
+```php
+$aggregator = new ConfigAggregator([
+    Mezzio\LaminasView\ConfigProvider::class,
+    Webware\Theme\ConfigProvider::class, // must come after
+    // ...
+]);
+```
+
+Both providers define `Laminas\View\Resolver\AggregateResolver`, and the later one wins. This package's
+factory attaches the theme resolver ahead of mezzio's own, which is the whole point of the package.
+
+## What the provider registers
+
+| Where | Entry |
+|---|---|
+| `dependencies.factories` | `ThemeResolver` and `AggregateResolver` (replacing mezzio's factory) |
+| `view_helpers.factories` | `Laminas\View\Helper\Asset` built by `AssetFactory` |
+
+## Not part of this package yet
+
+Installing a theme's assets into `public/`, and the command and admin widget that create and switch
+themes, are specified in `specs/001-theme-resolution/` (tasks T032 to T034 and T065 to T068) and are not
+built.
diff --git a/docs/v1/template-resolution.md b/docs/v1/template-resolution.md
new file mode 100644
index 0000000..49c73ac
--- /dev/null
+++ b/docs/v1/template-resolution.md
@@ -0,0 +1,37 @@
+# Template resolution
+
+`Webware\Theme\Resolver\ThemeResolver` is a `Laminas\View\Resolver\ResolverInterface`. It does one array
+lookup and never touches the filesystem:
+
+```
+maps[active][address]  ??  maps['default'][address]  ??  false
+```
+
+Returning `false` lets the aggregate resolver continue to the next resolver.
+
+## Order
+
+`AggregateResolverFactory` builds the aggregate with the resolvers mezzio would have had, and attaches the
+theme resolver in front:
+
+| Priority | Resolver |
+|---|---|
+| 100 | `ThemeResolver` |
+| 50 | `Laminas\View\Resolver\TemplateMapResolver` (`templates.map`) |
+| 1 | `Mezzio\LaminasView\NamespacedPathStackResolver` (`templates.paths`) |
+
+So a theme override wins, a component's own `templates.map` entry comes next, and its path stack is the
+last resort. A component therefore keeps working with no theme configuration at all.
+
+## Writing a theme
+
+1. Put the theme's templates anywhere; the convention is `templates/<theme>/<namespace>/<name>.phtml`.
+2. List each overridden address in `theme.themes.<theme>` (see [configuration](configuration.md)).
+3. Set `theme.active`.
+
+Only the addresses you list change. For the rest, `default` is used.
+
+## What it is not
+
+- It does not stack directories or scan for files, so a missing file is not detected at resolution time.
+- It does not select a theme per request. The active theme is configuration.
diff --git a/specs/001-theme-resolution/data-model.md b/specs/001-theme-resolution/data-model.md
index d4da691..d7fa5a2 100644
--- a/specs/001-theme-resolution/data-model.md
+++ b/specs/001-theme-resolution/data-model.md
@@ -13,7 +13,7 @@ Identity is the directory name. There is no registry and no per-theme metadata f
 | Field | Type | Rules |
 |---|---|---|
 | `name` | `non-empty-string` | A single path segment: no directory separators, no `..`, not empty. It is used as a directory name under `templates/`, so anything else is a path-escape (T002) |
-| `root` | `non-empty-string` | Absolute path to the theme's directory in one module: `<module>/templates/<name>`. A theme usually has one root per module that ships or overrides templates |
+| `root` | — | **Superseded (D-006):** there is no root field. A theme is a key in `theme.themes` (template overrides) and in `theme.assets` (asset values) |
 
 `default` is the reserved name: every module that ships templates ships `default`, and it is the fallback
 consulted after the active theme. It cannot collide with mezzio's internal unnamespaced bucket, which is
@@ -52,7 +52,7 @@ within each module the active theme's directory before `default` — and address
 Per-template fallback falls out of the ordering: a template the active theme does not ship resolves from
 `default`, and the framework's own resolvers take anything not theme-owned at all.
 
-Two things are decisions rather than open code:
+Both questions below are **settled** (D-002, D-003). The list is kept so the alternatives stay on record:
 
 - **Module order** for a namespace served by more than one module — presumably the application's own
   module first.
@@ -73,7 +73,7 @@ Two things are decisions rather than open code:
   point today; the key of a path list is the namespace, and its integer-keyed lists append in provider
   order, so the first-registered path wins a same-named file.
 
-## Theme root
+## Theme root *(superseded, D-006; kept for history)*
 
 A directory a theme resolves against in one module, plus where it came from.
 
@@ -96,16 +96,17 @@ by controlling provider order.
 ```
 theme
 ├── active            # the theme name; absent means `default`
-├── roots             # list<ThemeRoot>, ordered
-└── templates         # map<template name, path> contributed by the active theme
-view_manager
-└── asset               # laminas-view's own key, published by components
-    └── resource_map    # map<asset name, url|path>; themes re-value, never introduce
+├── themes            # map<theme, map<address, absolute path>>: overrides only (BUILT)
+└── assets            # map<theme, map<asset name, relative path | absolute URL>> (PLANNED, T042)
+view_helper_config
+└── asset               # laminas-view's own key; its stock AssetFactory reads it (D-009)
+    └── resource_map    # flat map<asset name, url>; the theme-aware factory builds it at runtime (D-008)
 ```
 
 Merge behaviour this shape depends on, measured in `ConfigAggregator::mergeArray()`: string keys replace
-with later-wins (so `templates` and `resource_map` overrides are automatic), while integer keys append
-(so a `roots` list accumulates in provider order and cannot be reordered by a later provider).
+with later-wins (so `themes` and `assets` overrides are automatic), while integer keys append
+(so an integer-keyed list accumulates in provider order and cannot be reordered by a later provider,
+which is why this shape has none).
 
 ## Resolver
 
@@ -136,10 +137,17 @@ lazy resolution — which makes `webware/webware-console` a dependency of this p
 
 ## Asset name
 
-Asset files live under `public/` — `/public/theme/<theme>/…` — and **never** inside a theme's `templates/`
-root, which is not a served location. The exact path shape and filenames are still to be settled.
+Asset files live under `public/` and **never** inside a theme's `templates/` root, which is not a served
+location. The layout is settled (D-007):
+
+```
+public/theme/<theme>/{css,js,img,fonts}/...                  URL /theme/<theme>/...                   theme assets
+public/theme/<theme>/component/<component>/...               URL /theme/<theme>/component/<component>/...   component assets, per theme (D-011)
+```
+
+One directory name per kind: `img`, not `images`. A theme name is a single path segment.
 
 | Field | Type | Rules |
 |---|---|---|
 | `name` | `non-empty-string` | Defined by a component; a fixed vocabulary. The `Asset` helper throws on anything unknown |
-| `value` | `non-empty-string` | A URL or a base-path-relative path. A theme overrides the value, including a CDN URL for a framework stylesheet |
+| `value` | `non-empty-string` | A path relative to the defining theme's directory (`css/theme.css`) or an absolute URL. A theme overrides the value, including with a CDN URL for a framework stylesheet |
diff --git a/specs/001-theme-resolution/decisions.md b/specs/001-theme-resolution/decisions.md
new file mode 100644
index 0000000..046d328
--- /dev/null
+++ b/specs/001-theme-resolution/decisions.md
@@ -0,0 +1,113 @@
+# Decisions and Handoff: Theme Resolution
+
+**Feature**: `specs/001-theme-resolution/` · **Last updated**: 2026-10-01 · **Branch**: `prototype/resolver`
+
+This file is the single place to start. Read it first, then `tasks.md` (what is left), then `spec.md`
+(what must be true). Every decision has an ID so a later session can cite it, and a status so it is
+clear what is settled and what still needs the owner (Joey Smith). When a decision changes, edit its
+row and add a dated line; never delete a row.
+
+## 1. Where things stand
+
+| Area | State |
+|---|---|
+| `ThemeResolver`, `ThemeResolverFactory`, `AggregateResolverFactory`, `ConfigProvider` | Built on `prototype/resolver` (commit `d1c05dc`). 7 unit tests, 5 integration tests. Mago `format`, `lint`, `analyze`, `guard` clean. Not merged: there is no PR for this branch yet. |
+| Theme-aware `asset()` helper | Built on `feat/asset-helper` (stacked on `prototype/resolver`, Phase 10 T042–T046, T048; T047 docs open). `ConfigProvider` now has the key constants and registers `AssetFactory` under `view_helpers.factories`. |
+| Asset publishing (installer) | Not built. Requirements live in `webinertia/project-tracking#6` (the Webware component installer RFC). |
+| Default theme visuals | Mockup open as `webinertia/default-theme#1` (CSS tokens plus `mockup/index.html`). |
+| Port of webware-acl, webware-admin, webware-usermanager templates to a neutral `default` theme | Started: usermanager PR #69 open, acl moved on an uncommitted branch. See `tasks.md` Phase 12. |
+| `ims` theme (the IMS originals, verbatim) | Partly present in `webinertia/webware` (`src/App/templates/ims/`, mapped in `config/autoload/theme.global.php`). Admin pages not yet copied. |
+
+Open pull requests that this work depends on (checked 2026-10-01): `webware-htmx#22` (merge state was
+`UNKNOWN`, re-check; it edits the same `ConfigProvider` that `webware-htmx#23` changed),
+`webware-usermanager#69`, `webware#7`, `default-theme#1`.
+
+## 2. Standing rules (the owner's, apply to every task)
+
+1. **Every change lands through a pull request.** Never push to `1.0.x` or any default branch. This
+   branch (`prototype/resolver`) is a work branch, not a release line.
+2. **Never delete, rename or move a file without the owner's explicit approval.** `git mv` of templates
+   into `templates/default/<namespace>/` has been approved for the theme port; nothing else has.
+3. **Releases and tags belong to the owner.** Never create, move or delete a tag; never run
+   `gh release`. If a change needs a release, say so loudly and stop.
+4. **Commits are signed off** (`git commit -s`) as `Joey Smith <jsmith@webinertia.net>`. Never override
+   the author or committer identity, never derive one from the OS username.
+5. **Merge commits are the default.** Squash only for a stated, compelling reason, said before merging.
+6. **The IMS repository (`~/github.com/tyrsson/inventory-management-system`) is read-only.** No edits,
+   no branch switches. IMS code is never lost, and never lives in a webware component: it belongs in the
+   `ims` theme or in IMS components.
+7. **Never change form field names** in templates.
+8. **Named arguments everywhere** in PHP (the `literal-named-argument` lint fails the gate).
+9. **Do not run application code while a debug session may be attached.** Check
+   `ss -ltnp | grep -E ':(9000|9003)'` first. Static tools (`mago`) and reading files are always safe.
+10. **Do not probe Packagist.** Use `git ls-remote --tags` and `gh release list`.
+11. **Do exactly the scope asked.** Anything else you notice gets one line at most. See
+    `vendor/webware/webware-tools/agent-working-agreements.md`.
+12. Gates before every commit: `mago fmt`, then `mago lint`, `mago analyze`, `mago guard` by **exit
+    code** (never read only the last line of output: an `INFO` line can hide a warning, and a warning
+    fails CI), then `composer test`, `composer test-integration`. MSI floors are 95/95 in
+    `webware-ci.json`. CI for `webinertia/webware` is switched off, so run everything locally there.
+
+## 3. Decision log
+
+Status values: **Settled** (built or confirmed by the owner), **Accepted** (proposed and not
+contradicted; confirm if you disagree), **Proposed** (needs the owner), **Open** (undecided),
+**Superseded**.
+
+| ID | Date | Decision | Status | Evidence / why |
+|---|---|---|---|---|
+| D-001 | 2026-09-29 | Theme resolution is a `Laminas\View\Resolver\ResolverInterface` registered in the aggregate. The renderer is not modified. | Settled | `research.md`, "Why not the renderer". The renderer approach paid a stat per path on every lookup. |
+| D-002 | 2026-09-29 | The construction is **theme-keyed maps**: `theme.themes[<theme>][<address>] => absolute path`, with the active theme injected and `default` as the per-address fallback. `namespace-keyed paths` and `merge-last theme map` were **not** prototyped. | Settled | Built in `ThemeResolver`; the active theme is a lookup-time fact, no filesystem call. Revisit the other two only if a requirement the map cannot meet appears. |
+| D-003 | 2026-09-29 | `ThemeResolver` only answers addresses a theme map lists. Everything else falls through the aggregate to `TemplateMapResolver` then `NamespacedPathStackResolver`. A component's own **default** theme is therefore served by the component publishing `templates/default/<namespace>/` under that namespace in `templates.paths`, not by a `theme.themes.default` entry. Priorities: theme 100, map 50, path stack 1. | Settled | `AggregateResolverFactory`; the app's `theme.global.php` lists only the `ims` overrides. |
+| D-004 | 2026-09-29 | `ConfigProvider` for this package must be merged **after** `Mezzio\LaminasView\ConfigProvider`: both own `AggregateResolver::class` and the later provider wins. | Settled | Docblock in `src/ConfigProvider.php`. The guarantee is a requirement on the installer (`project-tracking#6`). |
+| D-005 | 2026-10-01 | **Dropped.** No `Theme` / `ThemeInterface` objects (T001, T002). Keep it minimal: add **constants for the known config keys** (`theme`, `active`, `themes`, `assets`) and validate a theme name as a single path segment where it is used (the asset factory, T043). | Settled | Owner, 2026-10-01: "If we do not need them lets keep it minimal and just add const for the known config keys." Prototype works without them. Tasks T062, T063. |
+| D-006 | 2026-10-01 | `theme.roots` and PSR-4 root derivation (FR-011, T014) are **superseded** by `theme.themes` maps declared in configuration. | Superseded | The earlier docs described a `roots` list; the code never had one. |
+| D-007 | 2026-10-01 | Theme assets are served from `public/theme/<theme>/{css,js,img,fonts}/`, URL `/theme/<theme>/…`. One name per kind: `img` (not `images`). | Accepted | Proposed 2026-10-01 and the owner proceeded on it. Reasons: the `.htaccess` serves existing files and directories before routing, so a bare `/<theme>/` directory at the web root would shadow a route of the same name (`/admin`, `/user`); one prefix for cache headers; keeps `public/` tidy. |
+| D-008 | 2026-10-01 | The theme-aware asset helper **overrides the factory** for `Laminas\View\Helper\Asset` and returns a stock `Asset` built from a merged map. No subclass (the class is `final readonly`). Config: `theme.assets.<theme>.<name> => 'css/theme.css'` (relative to the theme's directory) or an absolute URL. The factory prefixes `/theme/<theme>/` using the theme that **defined** the name, so fallback active → `default` is per name. Absolute URLs (`https://`, `//`) pass through unchanged. Unknown names still throw (stock behaviour; fail loudly). The helper is shared; the active theme is configuration, not per request. | Accepted | `laminas-view/src/Helper/Service/AssetFactory.php` builds `new Asset($resourceMap)` once from `view_helper_config.asset.resource_map`. |
+| D-009 | 2026-10-01 | The laminas-view config key is **`view_helper_config.asset.resource_map`**, not `view_manager.asset.resource_map` as earlier docs said. | Settled | Measured in `AssetFactory` (`assertArray('view_helper_config', …)`, `assertArray('asset', …)`, `assertArray('resource_map', …)`). |
+| D-010 | 2026-10-01 | Component behaviour JavaScript ships with the **component** (webware-acl for the ACL page), never with a theme. A theme ships CSS that styles the component's neutral hooks. | Accepted | The ACL page's behaviour is about 400 lines of the IMS app's `public/assets/js/app.js` (from line 301, "ACL Wizard controller"), selecting by `ims-acl-*` ids and classes and building markup strings that contain them. It cannot live in a theme. |
+| D-011 | 2026-10-01 | Component assets are stored **per theme**, so each theme can publish its own version of a component's assets: `public/theme/<theme>/component/<component>/…`, URL `/theme/<theme>/component/<component>/…`. There is no theme-neutral `public/component/` directory. The component ships a default set (its `default` theme); another theme may supply its own, and the per-name fallback to `default` (D-008) applies. | Settled (path shape is my reading of the owner's answer; correct it if you meant otherwise) | Owner, 2026-10-01: "it would be better if those were stored per theme so each theme could publish their own." Supersedes the earlier proposal of `public/component/<component>/`. Task T064. |
+| D-012 | 2026-10-01 | **Installing is the composer plugin installer's job** (publishes theme and component assets from `vendor/` into `public/theme/<theme>/`; requirements in `project-tracking#6`). **A command** in the Webware CLI provides: creating a new theme based on `default`, registering it, and switching the active theme. **An admin widget** lets an administrator pick the active theme from the installed themes. So `webware-theme` is not the installer; whether the command lives in this package (needs `webware/webware-console`, `Console\` guard rule: a `final` `*Command` with `#[AsCommand]`, factory in `Console\Container\`) or elsewhere, and where the widget lives (webware-admin `WidgetInterface`), is for the plan. | Settled (split of responsibilities); placement of the command and widget open | Owner, 2026-10-01. Tasks T032–T034 are re-scoped; T065–T068 added. The widget needs a list of installed themes and a persisted active theme, neither of which exists (see Next actions). |
+| D-013 | 2026-10-01 | `ims-*` classes in the three components' templates are **styling and behaviour hooks whose CSS and JS live in the IMS app**, not IMS content. In the `default` theme they become neutral hooks: `ims-acl-X` → `acl-X`, `ims-widget-X` → `widget-X`, `ims-badge-xs` → `badge-xs`, `ims-rules-panel-` → `acl-rules-panel-`. `ims-col-*` (usermanager list) must **not** become `col-*`, which collides with Bootstrap's grid; use `list-col-*`. The rename changes markup and JS together or the page breaks. | Accepted | 84 rules in IMS `public/assets/css/custom.css`; the ACL templates have no inline script that selects by these names. |
+| D-014 | 2026-10-01 | The verbatim IMS originals of every ported template go into the `ims` theme in `webinertia/webware` (`src/App/templates/ims/<namespace>/`, mapped in `theme.global.php`), and the IMS CSS/JS go with that theme. | Accepted | The owner: "all of the ims specific stuff will get ported verbatim into the ims-theme". |
+| D-015 | 2026-10-01 | The shipped `default` theme is **stock Bootstrap 5.3.8 markup**, dark by default, with a Light/Dark control that persists in `localStorage` under `webware-theme`. No build step. Two logo colours: `#7e5ae0` is `primary`, `#05a578` is `secondary`. Component tokens are restated in `default-theme/css/theme.css` because Bootstrap's compiled components hard-code their blue. | Settled | `default-theme#1`. WCAG AA checked: white on purple 4.74:1, black on green 6.66:1, dark-mode purple text tint 6.50:1. |
+| D-016 | 2026-10-01 | Mapping green to `secondary` makes `.btn-secondary`, `.text-bg-secondary` and `.alert-secondary` green rather than neutral grey. Bootstrap's own `success` (`#198754`) sits close to the brand green. HTTP-method and privilege colours in the ACL page stay on Bootstrap's semantic success/warning/danger/info, not the brand colours. | Accepted | Called out in `default-theme#1`; not contradicted. |
+| D-017 | 2026-10-01 | `ThemeResolver` trusts a map entry and does not stat the file (T008). A missing file surfaces as the renderer's own error. | Settled | The resolver does no filesystem call by design (FR-005). |
+| D-018 | 2026-10-01 | The home page (`app::home-page`) is to be a CMS-style landing page loading content blocks from installed components through a PSR-14 collect event, mirroring `webware-admin` (`DashboardMiddleware` dispatches `RegisterWidgetEvent`, listeners add `WidgetInterface`, `AclWidgetFilterIterator` filters by role). The contract is **not** admin's `WidgetInterface`: it needs a `region`. Where the contract lives is **a new component** (owner, 2026-10-01: "Will be provided by a new component. Im still deciding on a few things there before that work will start."). | Settled (location); details open, work not started | Do not start it until the owner says so. Also unchecked: how `AclWidgetFilterIterator` resolves an anonymous user (`DashboardMiddleware` passes it `null`). |
+| D-019 | 2026-10-01 | Home-page work is **out of this feature's scope** except for the `default` theme templates that render it. | Accepted | Keeps `webware-theme` about resolution and assets. |
+| D-020 | 2026-10-01 | **Creating a theme (the command, D-012) copies the `default` theme's primary files under the given name**: in 1.0 only the layout, body and home-page templates and the main CSS file. It then **registers configuration**: a template map (`theme.themes.<name>`) covering **only the copied templates**, and **sets the new theme as active** (`theme.active`). | Settled (behaviour and storage: the command writes an autoloaded config file named `theme.{theme-name}.global.php`, owner 2026-10-01) | Owner, 2026-10-01: "A copy of the default files will be created and named as the provided name. I think in 1.0 we will just copy the primary templates. Layout, body, home-page and main css file. Configuration will also need to be registered and a template map covering just the copied templates etc and it will set the newly created theme as active." Everything not copied falls back to `default` per address (D-002), so the copy stays small. Tasks T065, T066. |
+
+## 4. Next actions, in order
+
+1. Open a PR for `prototype/resolver` (docs and prototype) so the work is reviewable. Do not merge
+   without the owner.
+2. Build the asset helper (Phase 10, T042–T048). It unblocks everything that serves CSS or JS.
+3. Land `default-theme#1` and `webware-usermanager#69` (owner review), then continue Phase 12 with the
+   ACL templates: finish the rename (D-013) and extract the ACL JavaScript into webware-acl (D-010).
+4. The owner's four answers are recorded (D-005, D-011, D-012, D-018). D-018 is **a new component, not yet
+   named or specified; the owner is still deciding details, so do not start it**. The theme-selection
+   command and widget (D-012) need a persisted active theme; settled 2026-10-01: the command writes an
+   **autoloaded config file** named `theme.{theme-name}.global.php` (owner: "The filename will be
+   theme.{theme-name}.global.php"). The
+   **admin widget never creates a theme**: it only switches between already installed themes.
+   **`theme.active` lives in `theme.settings.global.php`**, a settings file for themes that can hold
+   other theme settings later (owner, 2026-10-01). Autoload files merge in glob order and the later
+   file wins a shared key, so a per-theme file must not set `active`: otherwise every non-active
+   theme's file would need editing on a switch. The command (creating) and the widget (switching)
+   both write `theme.active` in `theme.settings.global.php`; a per-theme file holds only that theme's
+   `theme.themes.<name>` map (and its assets).
+
+## 5. Gotchas that cost time already
+
+- `mago lint` and `mago analyze` output ends with an `INFO` line; checking only the last line hid a
+  failing `literal-named-argument` warning once. Check exit codes.
+- `#[CoversClass]` cannot target a trait or a class outside `src` (PHPUnit warns, and Infection then
+  refuses to start). Use `#[CoversTrait]` for traits and omit `#[UsesClass]` for vendor classes.
+- A public method gains a `PublicVisibility` mutant in Infection. Only a test that calls it directly
+  kills it.
+- File-creation tools can write asynchronously. Wait and check the file size before running `mago fmt`.
+- Bash history expansion breaks `feat!:` in double quotes. Use `set +H` and single quotes.
+- The browser tool cannot open `file://` paths outside a trusted folder. Serve a directory with
+  `python3 -m http.server <port> --bind 127.0.0.1` on a port that is not 8080 (the owner's) and stop it
+  afterwards.
+- The webinertia clones are not kept in sync. `git fetch` and compare before trusting a clone.
diff --git a/specs/001-theme-resolution/plan.md b/specs/001-theme-resolution/plan.md
index 79e166f..eb6b1ad 100644
--- a/specs/001-theme-resolution/plan.md
+++ b/specs/001-theme-resolution/plan.md
@@ -1,19 +1,33 @@
 # Implementation Plan: Theme Resolution for Webware Packages
 
-**Feature**: `specs/001-theme-resolution/spec.md` · **Branch**: `001-theme-resolution` · **Date**: 2026-09-29
+**Feature**: `specs/001-theme-resolution/spec.md` · **Branch**: `prototype/resolver` · **Date**: 2026-09-29 · **Revised**: 2026-10-01
+
+> **Read `decisions.md` first.** It holds the current state, the standing rules and the decision log
+> (D-001…). Where this plan and a decision disagree, the decision is newer.
+
+## Implementation status (2026-10-01)
+
+| Piece | State |
+|---|---|
+| `ThemeResolver`, `ThemeResolverFactory`, `AggregateResolverFactory`, `ConfigProvider` wiring | **Built** (`d1c05dc`); 7 unit + 5 integration tests; Mago clean |
+| `Theme` / `ThemeInterface`, PSR-4 root derivation, `theme.roots` | **Not built and superseded or open** (D-005, D-006) |
+| Theme-aware `asset()` helper (`AssetFactory`) | Not built; `tasks.md` Phase 10 |
+| Asset publishing / installer | Not built; requirements in `project-tracking#6` (D-012) |
+| Default theme assets and the port of the three components' templates | Open; `tasks.md` Phases 11 and 12 |
 
 ## Summary
 
-Ship `webware/webware-theme`: a theme contract, a resolver that assembles the per-namespace paths a
-template is served from (active theme before `default`) with per-template fallback, and the convention
-that a theme is a directory of namespace directories under a module's `templates/`.
-Packages contribute roots and asset names through their `ConfigProvider`; applications (and client
-modules) contribute theirs as configuration, with module roots derivable from registered PSR-4
-namespaces. No middleware, no build step, no database.
+Ship `webware/webware-theme`: a resolver that answers an address from theme-keyed maps
+(`theme.themes[<theme>][<address>]`, active theme injected, `default` as the per-address fallback), a
+theme-aware `asset()` helper, and the convention that a component's own default theme is its
+`templates/default/<namespace>/` published under its namespace. Packages contribute their default
+templates through their `ConfigProvider`; applications contribute theme maps and asset values as
+configuration. No middleware, no build step, no database.
 
 One consumer change is a **prerequisite**, because a resolver can only resolve a name it is given: the
 package that layers the body and layout (webware-htmx) must name each with one configuration value
-(Phase 6, T019–T021 of `tasks.md`, and the required subset of webinertia/webware-htmx#21). Everything else
+(Phase 6, T039–T041 of `tasks.md`, and the required subset of webinertia/webware-htmx#21; the work is
+PR `webinertia/webware-htmx#22`). Everything else
 in that RFC is enabled by this feature's convention but not required by it.
 
 ## Technical Context
@@ -48,7 +62,10 @@ All measured in `webinertia/webware` against the installed `laminas/laminas-view
 | `AggregateResolver::resolve()` `continue`s on `false`, returns the first hit | `laminas-view/src/Resolver/AggregateResolver.php` | Per-template fallback is free between resolvers — the hook the design uses |
 | No `ResolveCache` anywhere in `laminas-view` 3.x `src` | grep, 2026-09-29 | Nothing memoizes resolution; the resolver memoizes its own results |
 | `ConfigAggregator::mergeArray()`: `is_int($key)` appends; string keys replace and recurse | `laminas-config-aggregator/src/ConfigAggregator.php` | Maps are the override channel (later wins); path lists give the first-registered provider priority |
-| `Laminas\View\Helper\Asset::__invoke()` throws on an unknown name; `resource_map` is string-keyed | `laminas-view/src/Helper/Asset.php` | Asset names are a fixed vocabulary; themes re-value names and cannot invent them (FR-009) |
+| `Laminas\View\Helper\Asset::__invoke()` throws on an unknown name; the class is `final readonly` and is built once by `AssetFactory` from `view_helper_config.asset.resource_map` (not `view_manager.asset`, as earlier drafts said) | `laminas-view/src/Helper/Asset.php`, `Helper/Service/AssetFactory.php`; re-measured 2026-10-01 | Asset names are a fixed vocabulary (FR-009). Theme awareness is a factory override that builds a merged map (D-008), not a subclass |
+| `webware/public/.htaccess` serves any existing file, link or **directory** before routing | `webware/public/.htaccess` | A bare `/<theme>/` directory at the web root would shadow a route of that name; assets live under `/theme/<theme>/` (D-007) |
+| The ACL page's behaviour is ~400 lines of the IMS app's `public/assets/js/app.js` (from line 301), selecting by `ims-acl-*` ids and classes and building markup strings with them; its styling is 84 rules in `public/assets/css/custom.css`; the component templates contain no script that selects by those names | IMS repo, read-only; 2026-10-01 | A neutral rename must move markup, script and CSS together; the script ships with the component (D-010, D-013) |
+| `webware/vendor/webware/webware-theme` is a symlink to the sibling clone and the app's `composer.lock` pins it as a path dist at the prototype commit | `webware/composer.lock`; 2026-10-01 | The app works only where that clone is on `prototype/resolver`; the resolver must reach `1.0.x` by PR |
 | `LaminasRendererFactory` reads five keys for layout/body (`templates.layout`, `templates.body`, `templates.default_layout`, `templates.default_body`, `view_manager.default_layout`); first non-empty is the layout, last is the body | `webware-htmx/src/View/LaminasRendererFactory.php` | FR-012 collapses this to two theme-resolved names |
 | `webware-htmx/templates/body/default.phtml` is the IMS shell and calls `$this->imsMessenger()`, a helper defined nowhere in the app repo or in `webware/vendor` | measured 2026-09-29 | US3 exists: the shell moves to `ims`, `default` becomes helper-clean (FR-013) |
 
@@ -66,6 +83,7 @@ and the package's own coverage metadata requirements.
 
 ```
 specs/001-theme-resolution/
+├── decisions.md     # START HERE: state, standing rules, decision log, next actions
 ├── spec.md          # this feature's requirements
 ├── plan.md          # this file
 ├── tasks.md         # dependency-ordered task list
@@ -74,20 +92,21 @@ specs/001-theme-resolution/
 └── quickstart.md    # using a theme from both sides: theme author and package author
 ```
 
-Note: `.specify/` and `/specs/` are ignored by this repository's `.gitignore` (inherited from
-`repo-template`), so these documents are local unless that is revisited.
+Note: `.specify/` and `/specs/` are **tracked** in this repository (`tasks.md` T026); only the vendored
+preset under `.specify/presets/` is ignored.
 
 ### Source Code (repository root)
 
 ```
 src/
-├── ConfigProvider.php              # wiring entry point; already present, currently empty
-├── ThemeInterface.php              # a theme: name + root + optional overrides
-├── Theme.php                       # value object implementation (final readonly)
+├── ConfigProvider.php              # BUILT: registers the resolver and the aggregate factories
+├── ThemeInterface.php              # NOT BUILT, open decision D-005
+├── Theme.php                       # NOT BUILT, open decision D-005 (the name check is still needed by T043)
 ├── Resolver/
-│   ├── ThemeResolver.php           # per-namespace paths, active theme before default, memoized
-│   └── Container/ThemeResolverFactory.php
-├── Installer/
+│   ├── ThemeResolver.php           # BUILT: theme-keyed map lookup, active theme then default
+│   └── Container/ThemeResolverFactory.php   # BUILT (and AggregateResolverFactory.php beside it)
+├── View/Helper/Container/AssetFactory.php   # PLANNED (T043): theme-aware asset() factory (D-008)
+├── Installer/                      # OPEN (D-012): may live in the Webware installer instead
 │   ├── ThemeInstaller.php          # creates and manages a theme's assets under public/theme/<theme>/
 │   └── Container/ThemeInstallerFactory.php
 ├── Console/                        # only if the installer is a command here (T034)
@@ -113,6 +132,8 @@ installed asset set look like?".
 
 | Deviation | Why | What it costs |
 |---|---|---|
-| Resolution consults theme-aware paths or maps rather than the framework's `templates.paths` in provider order | FR-005 (no filesystem walk per lookup) plus the measured asymmetry: integer-keyed path lists append, so the first-registered provider wins a same-named file and a theme could not win | Either construction must be built at boot (a scan or a manifest), so a theme that changes on disk needs it rebuilt — unless the maps are keyed by theme, which makes the active theme a lookup instead of a build-time fact. Prototyped in Phase 2b |
+| Resolution consults theme-keyed maps rather than the framework's `templates.paths` in provider order | FR-005 (no filesystem walk per lookup) plus the measured asymmetry: integer-keyed path lists append, so the first-registered provider wins a same-named file and a theme could not win | The active theme is a lookup-time fact, no build or scan. The cost: every overridden address must be listed in config (D-002 settled this after the prototype) |
+| The asset helper is made theme-aware by replacing its factory, not by subclassing | `Asset` is `final readonly` and built once from a flat map (D-008) | The factory must be registered after `Mezzio\LaminasView\ConfigProvider` and the active theme is fixed per process (no per-request themes) |
+| A component's behaviour JavaScript ships with the component, not the theme (D-010) | The ACL page's script selects by the markup's hooks and builds markup strings with them | Components need an asset publishing path (D-011, D-012) the app does not have yet |
 | The resolver is a `ResolverInterface` instead of a renderer modification | The previous iteration modified the renderer and pushed paths onto its stack; keeping resolution out of the renderer keeps `webware-htmx` free to own body/layout layering | Resolution and rendering are configured in two places, and their interaction needs an integration test |
 | Theme identity is the directory name, not a registry entry | It is the convention that makes a redesign a directory of files, and it keeps the whole thing configuration-only (FR-006) | Two packages cannot ship different themes under the same name, and there is no per-theme metadata beyond the directory |
diff --git a/specs/001-theme-resolution/quickstart.md b/specs/001-theme-resolution/quickstart.md
index 9d1180c..35d0927 100644
--- a/specs/001-theme-resolution/quickstart.md
+++ b/specs/001-theme-resolution/quickstart.md
@@ -4,9 +4,9 @@
 
 ## For a designer or developer refreshing a client's site
 
-A theme is a directory under a module's `templates/`, holding one subdirectory per template namespace,
-plus the assets the installer puts under `public/theme/<theme>/`. Nothing is compiled, published or
-registered.
+A theme is a key in the `theme.themes` configuration: a map from template address to the file that
+replaces it. Its assets are files under `public/theme/<theme>/`. Nothing is compiled or scanned; a
+template path in the map is used as written and is not checked on disk (D-017).
 
 ```
 src/App/templates/
@@ -26,13 +26,12 @@ segment and is never part of the address. Templates and assets live in different
 served differently — `templates/` is never a served location, so nothing under it can be requested by a
 browser.
 
-1. Create the theme directory beside the module's `default` and copy into it only what the redesign
-   changes, keeping each template under its namespace. Anything you do not copy continues to come from
-   `default`.
-2. Its assets are the installer's job, not yours: run the theme installer and they appear under
-   `public/theme/<theme>/` (exact path shape and filenames still to be settled), with their **names**
-   pointed at them in the resource map — the names are the ones the components already use; you are
-   changing values, not inventing names.
+1. Put the theme's templates in a directory of your choosing (the layout above is the convention) and
+   list each address the theme overrides in `theme.themes.<name>`. Anything not listed continues to
+   come from `default`, address by address.
+2. Its assets go under `public/theme/<theme>/{css,js,img,fonts}/`, and their **names** are pointed at
+   them in `theme.assets.<theme>` (planned, T042; the asset helper does not read it yet) — the names
+   are the ones the components already use; you are changing values, not inventing names.
 3. Activate it:
 
 ```php
@@ -40,8 +39,11 @@ browser.
 return [
     'theme' => [
         'active' => 'acme',
-        'roots'  => [
-            ['component' => 'app', 'path' => __DIR__ . '/../../templates/acme'],
+        'themes' => [
+            'acme' => [
+                'app::home-page.phtml' => __DIR__ . '/../../src/App/templates/acme/app/home-page.phtml',
+                'layout::default'      => __DIR__ . '/../../src/App/templates/acme/layout/default.phtml',
+            ],
         ],
     ],
 ];
diff --git a/specs/001-theme-resolution/research.md b/specs/001-theme-resolution/research.md
index d5bdaa9..919607f 100644
--- a/specs/001-theme-resolution/research.md
+++ b/specs/001-theme-resolution/research.md
@@ -63,7 +63,8 @@ provider order is not relied upon as an override mechanism.
 
 ## Asset names are a vocabulary, not a fallback chain
 
-`Laminas\View\Helper\Asset` is a `final readonly` lookup over `view_manager.asset.resource_map` and
+`Laminas\View\Helper\Asset` is a `final readonly` lookup over `view_helper_config.asset.resource_map`
+(earlier drafts said `view_manager.asset`, which is wrong; D-009) and
 **throws** `InvalidArgumentException` on a name that is not present. Templates fall through; assets do
 not. So a theme re-values names that components define, and cannot introduce or rename them.
 
@@ -106,11 +107,56 @@ with Tailwind bridges later via asset helpers. Consequences that shaped the desi
 - Per-package defaults plus per-theme overrides mean an application must be able to have *two* sets of
   markup on disk at once, which is why the default theme is a directory rather than a fallback file.
 
-## Open items
-
-- Cross-module order for a shared namespace is assumed (the application's own module first), not yet
-  exercised against a real second module.
-- Whether a theme root that must be enumerated on disk is scanned at map-build time or declared in a
-  manifest is a planning decision (T008 in `tasks.md`).
-- The `ims` theme extraction has not been attempted in the application, so SC-005 (byte-identical
-  markup) is untested.
+## Decisions taken after the prototype (2026-10-01)
+
+Measured or settled once the resolver existed; the IDs point into `decisions.md`.
+
+- **Asset layout `/theme/<theme>/{css,js,img,fonts}` (D-007).** `public/.htaccess` serves an existing
+  file, link or directory before it rewrites to `index.php`. A theme directory at the web root would
+  therefore shadow a route of the same name, and `/admin` or `/user` are routes. One fixed prefix also
+  gives the web server a single place for cache headers.
+- **The helper is a factory override (D-008).** `AssetFactory::__invoke()` reads
+  `view_helper_config.asset.resource_map` and returns `new Asset($map)`; the class has no setter and no
+  theme concept. Replacing the factory and handing it a merged map keeps the stock helper, its
+  `InvalidArgumentException` on unknown names, and its caller-facing API.
+- **Component JavaScript cannot live in a theme (D-010).** The ACL page's behaviour is the "ACL Wizard
+  controller" in the IMS app's `public/assets/js/app.js`: lines 301 to 704 of a 704-line file. It selects
+  by `ims-acl-*` ids and classes (`#ims-acl-route-search`, `.ims-acl-route-entry`,
+  `.ims-acl-grant-card`, `#ims-acl-wiz-next`, `#ims-acl-rule-offcanvas`), reads `data-acl-filter`,
+  `data-wizard-action`, `data-rules-panel` and `data-acl-step-grant`, and builds markup strings that
+  contain `ims-acl-*` classes. The component templates have no inline script that selects by those
+  names (checked with `querySelector`, `classList`, `closest` and `getElementById`).
+- **The styling is 84 rules in IMS `public/assets/css/custom.css`** (739 lines) for the `ims-acl-*`,
+  `ims-widget-*`, `ims-badge-*`, `ims-col-*` and `ims-rules-*` families. Several hard-code Bootstrap's
+  RGB values (the method pills use Bootstrap's success green and blue). They become palette tokens in
+  the default theme; the HTTP-method and privilege colours stay semantic (D-016).
+- **Name collision (D-013).** Stripping `ims-` from `ims-col-name` and friends in the usermanager list
+  would produce `col-name`, which collides with Bootstrap's `.col-*` grid classes. Use `list-col-*`.
+- **Counts in the three components' templates.** webware-acl: 8 templates, `ims-` hooks concentrated in
+  `admin-acl.phtml` (about 37) and `partials/protect-route-wizard.phtml` (about 30), plus 6 in
+  `admin-widget.phtml`. webware-admin: 1 template, none. webware-usermanager: 8 templates, five hooks
+  each in `admin-widget.phtml` and `list-users.phtml`; the auth pages are already neutral (PR #69).
+- **The IMS home page is not worth porting.** `ims/app/home-page.phtml` is the Mezzio skeleton welcome
+  page (Pico-style `article` and `grid` markup, Font Awesome icons). The part of IMS worth porting is the
+  shell, `ims/body/default.phtml` (156 lines): navbar, the `main`/`admin`/`user` navigation containers
+  and the messenger.
+- **The home page's intended model** is webware-admin's: `DashboardMiddleware` dispatches a mutable
+  `RegisterWidgetEvent`, listeners add `WidgetInterface` objects (`title`, `resourceId`, `privilege`,
+  `template`, `order`), `AclWidgetFilterIterator` filters them by the user's roles, the handler renders
+  `admin::dashboard`, which loops `$this->partial($widget->template, $widget)`. A public page needs a
+  `region` the admin widget does not have (D-018).
+- **The default theme's colours (D-015).** Decoded from the org avatar: purple `#7e5ae0`, green
+  `#05a578`. Contrast: white on purple 4.74:1; purple text on Bootstrap's dark body 3.25:1 (so dark-mode
+  text uses `#b29cec` at 6.50:1 and dark-mode outline buttons `#987be6` at 4.63:1); white on green
+  3.15:1 (so green buttons use black text at 6.66:1 and light-mode green text `#048460` at 4.69:1).
+  Bootstrap 5.3.8 compiled components hard-code their blue, so tokens are restated per component in
+  `default-theme/css/theme.css`.
+
+## Open items (revised 2026-10-01)
+
+- Cross-module order for a shared namespace is **resolved** (D-002): theme maps are config and the
+  config merge decides, later wins.
+- Map entries are trusted and not stat-checked (**decided**, D-017; this was T008).
+- The `ims` theme extraction is **partly done** in `webinertia/webware` (layout, body, home page, error
+  pages and the four user pages are in `src/App/templates/ims/`); the admin pages are not, so SC-005
+  (byte-identical markup) is untested for them (T058).
diff --git a/specs/001-theme-resolution/spec.md b/specs/001-theme-resolution/spec.md
index d8b23a7..846170e 100644
--- a/specs/001-theme-resolution/spec.md
+++ b/specs/001-theme-resolution/spec.md
@@ -4,7 +4,10 @@
 
 **Created**: 2026-09-29
 
-**Status**: Draft
+**Status**: In progress. The resolver is built as a prototype (see `decisions.md` section 1); the
+theme-aware asset helper, asset publishing, the default theme's assets and the port of the base
+templates are open (`tasks.md` Phases 10 to 13). Requirements below carry a note where a decision
+changed them; the reasons are in `decisions.md`.
 
 **Input**: User description: "I want to simply build a resolver which will simplify, I hope, also
 supporting the custom template layer for htmx. The benefit is that laminas already provides and will
@@ -29,8 +32,11 @@ every layer.
 
 **In scope:** theme resolution for laminas-view; the directory and naming convention; the default
 theme shipped by packages; the active-theme selection and its configuration; asset name resolution
-through laminas-view's asset helpers; the webware-htmx body/layout layer expressed as ordinary theme
-templates; the extraction of the IMS application's current shell into an `ims` theme.
+through laminas-view's asset helpers, made theme-aware; where theme and component assets are served
+from; the visual baseline of the `default` theme; the port of the base templates of webware-acl,
+webware-admin and webware-usermanager to a neutral `default` theme; the webware-htmx body/layout layer
+expressed as ordinary theme templates; the extraction of the IMS application's current shell and admin
+pages, verbatim, into an `ims` theme.
 
 **Out of scope (explicit):**
 
@@ -43,7 +49,13 @@ templates; the extraction of the IMS application's current shell into an `ims` t
   direction, is expected to be a theme that overrides markup plus an asset-helper entry rather than a
   pipeline.
 - Per-request theme switching. The active theme is a configuration value; nothing in this spec
-  requires resolving a theme from a session, a store, or a request.
+  requires resolving a theme from a session, a store, or a request. (The Light/Dark colour mode is a
+  client-side `data-bs-theme` toggle, not a theme switch.)
+- The home-page content-block contract (a PSR-14 collect event modelled on webware-admin's dashboard
+  widgets). This feature only supplies the `default` theme templates that render it. See `decisions.md`
+  D-018 and D-019.
+- The installer itself. Its requirements live in `webinertia/project-tracking#6`; this spec states only
+  what it must produce (FR-015).
 
 ## User Scenarios & Testing *(mandatory)*
 
@@ -115,6 +127,46 @@ error; then activate `ims` and confirm the IMS shell renders with its own helper
 
 ---
 
+### User Story 4 - The default theme looks like Webware, not like a framework skeleton (Priority: P2)
+
+A person installs the packages and opens the admin pages. They see stock Bootstrap markup in a dark
+theme built from the two logo colours of the webinertia org, with a Light option, and nothing that
+mentions IMS or a store.
+
+**Why this priority:** a default theme nobody wants to keep makes every install a redesign.
+
+**Independent Test:** with no theme configured, load the ACL overview, the user list and the dashboard
+in a browser, in dark and in light.
+
+**Acceptance Scenarios:**
+
+1. **Given** a first visit, **When** a page renders, **Then** it is dark and the Dark option is the
+   pressed one.
+2. **Given** the Light option is chosen, **When** the page is reloaded, **Then** it is still light.
+3. **Given** any rendered `default` page, **When** its markup is searched, **Then** it contains no
+   `ims-` class or id and no IMS branding.
+
+---
+
+### User Story 5 - The IMS application keeps its look, verbatim (Priority: P3)
+
+The IMS application's admin pages move into the `ims` theme exactly as they were, with their own CSS
+and JavaScript, while the packages move to the neutral `default` theme.
+
+**Why this priority:** it is what lets the components lose the IMS coupling without losing any IMS code.
+
+**Independent Test:** activate `ims` and compare the rendered ACL, user and dashboard markup with what
+the IMS application renders today.
+
+**Acceptance Scenarios:**
+
+1. **Given** `theme.active` is `ims`, **When** the ACL overview renders, **Then** the markup is the
+   original markup and the original script works against it.
+2. **Given** `theme.active` is `default`, **When** the same page renders, **Then** the neutral hooks
+   are present and the component's own script works against them.
+
+---
+
 ### Edge Cases
 
 - The active theme directory does not exist at all — the application still renders from `default`
@@ -123,6 +175,10 @@ error; then activate `ims` and confirm the IMS shell renders with its own helper
   is the same failure an unknown template name has always produced.
 - A theme's configured asset name is not present in the resource map. The asset helper throws on an
   unknown name, so asset names are a vocabulary: themes re-value names, they do not invent them.
+- A theme re-values only some asset names. The rest resolve from `default`, per name, and the URL points
+  at the theme that defined the name.
+- A theme name that is not a single path segment (`a/b`, `..`, empty) is rejected before it is used to
+  build a path or a URL.
 - The active theme is changed in configuration but the aggregated config is cached — a cached
   configuration must be cleared for the switch to take effect, and this must be documented.
 - Two components ship the same template name and different themes are active — resolution must be
@@ -143,8 +199,10 @@ agreements, the four Mago gates, and the MSI floors in `webware-ci.json`.
 - **FR-002**: Templates MUST keep mezzio's namespaced addressing — `<namespace>::<name>`, e.g.
   `app::home-page.phtml`, `layout::default`, `admin::dashboard.phtml`. The theme is never part of the
   address; it selects the first directory segment under `templates/`.
-- **FR-003**: Resolution for a namespace MUST consult the paths that namespace is served from, module by
-  module, and within each module the active theme's directory before `default`.
+- **FR-003** *(revised 2026-10-01, D-002/D-003)*: Resolution MUST consult the active theme's template
+  map before anything else, then the framework's own map and path-stack resolvers. A component's
+  `default` theme is served by the component publishing `templates/default/<namespace>/` under its
+  namespace; the theme map carries only overrides.
 - **FR-004**: Fallback MUST be per template, not per theme: a template the active theme does not ship
   resolves from `default` in the same namespace, and a template no module ships falls through to the
   framework's own resolvers.
@@ -158,13 +216,17 @@ agreements, the four Mago gates, and the MSI floors in `webware-ci.json`.
 - **FR-007**: Every module that ships layouts or templates MUST ship a `default` theme.
 - **FR-008**: The active theme MUST be selectable by a configuration value alone. A module that ships no
   directory for the active theme contributes only its `default`.
-- **FR-009**: Assets MUST be resolved through laminas-view's asset helpers, with theme values
-  overriding entries in the resource map. No request-time asset middleware. Asset files MUST live under
-  `public/` (`/public/theme/<theme>/…`) and never inside a theme's `templates/` root, which is not a
-  served location.
+- **FR-009** *(revised 2026-10-01, D-007 to D-009)*: Assets MUST be resolved through laminas-view's
+  `asset()` helper, made theme-aware by overriding that helper's **factory** (the class is
+  `final readonly`). Values live under `theme.assets.<theme>.<name>`; the laminas-view key the stock
+  factory reads is `view_helper_config.asset.resource_map`. No request-time asset middleware. Asset
+  files MUST live under `public/theme/<theme>/{css,js,img,fonts}/` (URL `/theme/<theme>/…`) and never
+  inside a theme's `templates/` root, which is not a served location.
+- **FR-009a**: The theme-aware helper MUST resolve a name from the active theme, fall back to `default`
+  per name, pass absolute URLs through unchanged, and still throw on a name no theme defines.
 - **FR-010**: A theme MUST work without a build step. Markup and assets are the deliverables.
-- **FR-011**: Module roots MAY be derived from the PSR-4 namespaces registered for that module (its
-  namespace root's sibling `templates/`), with package roots declared by their own `ConfigProvider`.
+- **FR-011** *(superseded 2026-10-01, D-006)*: Module roots derived from PSR-4 namespaces. Replaced by
+  theme maps declared in configuration (`theme.themes`); there is no `roots` list.
 - **FR-012**: The body and the layout MUST each be named by **one** configuration value, and that value
   MUST be a theme-resolvable template name (`body`, `layout`) rather than a path the owning package
   publishes as a map entry. This is what lets a theme point at a body template at all, so the collapse of
@@ -179,14 +241,33 @@ agreements, the four Mago gates, and the MSI floors in `webware-ci.json`.
 - **FR-015**: Creating and managing a theme's asset files MUST be the theme installer's responsibility
   rather than a manual task. Running the installer is what puts a theme's assets under
   `public/theme/<theme>/`; a developer never creates them by hand, and the components' `default` themes
-  need no manual asset step.
+  need no manual asset step. A component's assets (for example the ACL page JavaScript) are stored
+  per theme, under `public/theme/<theme>/component/<component>/`, so each theme can publish its own
+  (D-011). Publishing symlinks in
+  development, copies in production, is idempotent, and removes what a package no longer ships. The
+  installer's own requirements are tracked in `webinertia/project-tracking#6` (D-012). Installing is the
+  composer plugin installer's job; creating, registering and switching themes is a command, and choosing
+  one is an admin widget (D-012, tasks T065–T068).
+- **FR-016**: The shipped `default` theme MUST use stock Bootstrap 5.3 markup and spacing, be dark by
+  default with a Light/Dark control that persists the choice, and need no build step (D-015).
+- **FR-017**: The two colours of the webinertia logo MUST be the theme's `primary` (`#7e5ae0`) and
+  `secondary` (`#05a578`) in both colour modes. Text and control colours MUST meet WCAG AA (4.5:1) in
+  both modes; where a brand colour does not, a tint or shade is used for that role only (D-015, D-016).
+- **FR-018**: A component's templates MUST live under `templates/default/<namespace>/` and publish that
+  path under their namespace. In the `default` theme they MUST NOT carry `ims-` classes, ids or
+  branding; styling hooks use neutral prefixes (D-013).
+- **FR-019**: A component's behaviour JavaScript MUST ship with the component, select only by the
+  neutral hooks, and never be part of a theme (D-010). A theme supplies CSS for those hooks.
+- **FR-020**: Every template ported to the `default` theme MUST also exist, verbatim, in the `ims` theme
+  of `webinertia/webware`, with its CSS and JavaScript, so no IMS code is lost and none lives in a
+  component (D-014).
 
 ### Key Entities
 
 - **Theme**: a name plus the root it resolves from. Configuration-driven; identity is the directory
   name.
-- **Theme root**: the directory a theme resolves against in one module — `<module>/templates/<theme>/` —
-  contributed by a package's `ConfigProvider` or derived from a module's registered namespace.
+- **Theme root** *(superseded, D-006)*: there is no theme root entity. A theme is a key in
+  `theme.themes` (address to path) and, for assets, a key in `theme.assets`.
 - **Resolver**: the component that turns a namespaced address (`<namespace>::<name>`) into a path, using
   the paths that namespace is served from, with the active theme's directory before `default`.
 - **Asset name**: a fixed vocabulary entry in the resource map that a theme may re-value.
@@ -214,9 +295,8 @@ agreements, the four Mago gates, and the MSI floors in `webware-ci.json`.
   concern rather than for a service inside it.
 - The runtime dependency is `laminas/laminas-view` alone. `mezzio/mezzio-laminasviewrenderer` and
   `webware/webware-htmx` stay consumers, not dependencies.
-- Which module's path is consulted first when more than one module serves the same namespace is a
-  decision to confirm (presumably the application's own module first), since it decides which of two
-  same-named templates wins.
+- Which module's path is consulted first is **no longer a question** (D-002): themes are address maps
+  merged by the config aggregator, so the later provider wins and `theme.themes` entries override.
 - The default theme's directory name is `default`, which cannot collide with mezzio's internal
   unnamespaced bucket (`__DEFAULT__`, a private constant, unreachable as a template namespace).
 - Configuration merging decides override precedence: integer-keyed lists append (first-registered
@@ -224,5 +304,6 @@ agreements, the four Mago gates, and the MSI floors in `webware-ci.json`.
   therefore the override channel unless provider order is deliberately controlled.
 - `laminas-view` 3.x ships no resolver cache, so anything that touches the filesystem at resolve time
   pays per lookup; this is why FR-005 exists.
-- `.specify/` and `/specs/` are ignored by this repository's `.gitignore` (inherited from the template),
-  so these documents are local until that is revisited.
+- `.specify/` and `/specs/` are **tracked** in this repository on purpose (`tasks.md` T026); only the
+  vendored preset copy under `.specify/presets/` is ignored. An earlier version of this note said the
+  opposite and was wrong.
diff --git a/specs/001-theme-resolution/tasks.md b/specs/001-theme-resolution/tasks.md
index a2448cf..ce9fb4f 100644
--- a/specs/001-theme-resolution/tasks.md
+++ b/specs/001-theme-resolution/tasks.md
@@ -4,6 +4,11 @@
 
 **Feature**: `001-theme-resolution` · **Package**: `webware/webware-theme` · **Namespace**: `Webware\Theme`
 
+**Status key** (updated 2026-10-01 against commit `d1c05dc` on `prototype/resolver`): `[X]` is done or
+**Superseded** (a decision replaced it; do not build it), `[ ]` is open. A bold note after the ID says why.
+The decisions behind every note are in `decisions.md` (IDs `D-001`…); read it first, including its
+standing rules. Task IDs are never reused: the next free ID is **T070**.
+
 Notes that apply to every task: `mago fmt` before any commit; all four gates clean
 (`format --check`, `lint`, `analyze`, `guard`); every test class carries `#[CoversClass]` and
 `#[CoversMethod]` with the matching imports (`requireCoverageMetadata="true`); MSI gates are 95/95 from
@@ -11,31 +16,31 @@ Notes that apply to every task: `mago fmt` before any commit; all four gates cle
 
 ## Phase 1 — Theme contract
 
-- [ ] T001 Define `ThemeInterface` in `src/ThemeInterface.php`: the name, the root it resolves from,
+- [X] T001 **Dropped (D-005).** No `ThemeInterface`; config key constants instead (T062). Original text: define `ThemeInterface` in `src/ThemeInterface.php`: the name, the root it resolves from,
       and nothing else. A theme is a directory; identity is its name (`@api`, since consumers
       reference it)
-- [ ] T002 Implement `Theme` in `src/Theme.php` as a `final readonly` value object with a
+- [X] T002 **Dropped (D-005).** The single-segment name check moves to T043 / T063. Original text: implement `Theme` in `src/Theme.php` as a `final readonly` value object with a
       `fromArray`-style named constructor; validate the name as a single path segment (no separators,
       no `..`) so a configuration value can never escape its root
-- [ ] T003 Define the theme root contract: how a package declares `templates/<theme>` as a root, as a
+- [X] T003 **Superseded (D-006, D-003).** Define the theme root contract: how a package declares `templates/<theme>` as a root, as a
       docblock `@type` alias in `ConfigProvider` in the house style (`@type`, not `@phpstan-type`)
 
 ## Phase 2 — Resolver
 
-- [ ] T004 Implement `Resolver\ThemeResolver` in `src/Resolver/ThemeResolver.php`, implementing
+- [X] T004 **Built** (`ThemeResolver`, 7 unit tests). Implement `Resolver\ThemeResolver` in `src/Resolver/ThemeResolver.php`, implementing
       `Laminas\View\Resolver\ResolverInterface`. It MUST return `false` — never throw — for a name it
       cannot resolve, so `AggregateResolver` continues to the next resolver
-- [ ] T005 Build, per namespace, the paths that namespace is served from — module by module, and within
+- [X] T005 **Superseded (D-002, D-003).** Build, per namespace, the paths that namespace is served from — module by module, and within
       each module the active theme's directory before `default` — so fallback is per template and not per
       theme (FR-004)
-- [ ] T006 Resolve from a map built once, not by walking directories per lookup (FR-005): build the
+- [X] T006 **Done by D-002:** the maps are config arrays, the lookup is an array access, nothing to memoize. Resolve from a map built once, not by walking directories per lookup (FR-005): build the
       map when the resolver is constructed, and memoize resolved names in the instance
-- [ ] T007 Build the map without touching the filesystem where the configuration already names the
+- [X] T007 **Superseded (D-002):** the resolver never touches the filesystem; maps are declared in config. Build the map without touching the filesystem where the configuration already names the
       templates; where a root must be enumerated, scan it once at build time
-- [ ] T008 Decide and document the behaviour when a map entry points at a file that does not exist:
+- [X] T008 **Decided (D-017):** trust the entry, no stat-check. Decide and document the behaviour when a map entry points at a file that does not exist:
       either trust the entry (a build-time artefact) or stat-check it and fall through. Record the
       choice and its cost in `plan.md` Complexity Tracking
-- [ ] T009 Register the resolver in `src/Resolver/Container/ThemeResolverFactory.php` and wire it to
+- [X] T009 **Built** (`ThemeResolverFactory`, `AggregateResolverFactory`: theme 100, map 50, path stack 1). Register the resolver in `src/Resolver/Container/ThemeResolverFactory.php` and wire it to
       the aggregate ahead of the map/path resolvers, so an active theme wins over package defaults
 
 ## Phase 2b — Prototype the construction before committing to it
@@ -44,44 +49,44 @@ Next free IDs, following the convention above. Both shapes hang off two measured
 address the renderer asks for (`app::home-page`), and the resolver gets a factory, so the active theme can
 be injected from configuration.
 
-- [ ] T035 Prototype **namespace-keyed paths** (mezzio's `templates.paths`, the active theme's directory
+- [ ] T035 **Not run** (D-002); revisit only if a requirement the map cannot meet appears. Prototype **namespace-keyed paths** (mezzio's `templates.paths`, the active theme's directory
       prepended per namespace). Measure the lookup cost with a theme installed, and confirm the ordering
       hazard: integer-keyed lists append in provider order, so the first-registered path wins a
       same-named file, which is the opposite of what a theme needs
-- [ ] T036 Prototype **theme-keyed maps** (`[theme][address] => path` for every theme at once, active
+- [X] T036 **Built and chosen (D-002).** Prototype **theme-keyed maps** (`[theme][address] => path` for every theme at once, active
       theme injected into the resolver, `default` as the per-address fallback). Confirm the active theme
       becomes a lookup-time fact, and measure what building the maps costs (directory scan or manifest)
-- [ ] T037 Prototype **merge-last theme map**: a theme ships its overrides as an address-keyed map, and a
+- [ ] T037 **Not run** (D-002). Prototype **merge-last theme map**: a theme ships its overrides as an address-keyed map, and a
       provider or post-processor registered last merges it over the rest, so the theme wins by the same
       rule that makes `templates.map` an override channel today — and every address the theme does not
       list keeps its earlier entry, which is per-address fallback for free. Runtime stays a plain
       `TemplateMapResolver`: no custom resolver, no stats. Confirm what the rebuild costs at config time
       and whether the config cache absorbs it
-- [ ] T038 Write down which won and why (build-time theme vs lookup-time theme is the real fork), then
+- [X] T038 **Recorded in `decisions.md` D-002.** Write down which won and why (build-time theme vs lookup-time theme is the real fork), then
       fold it into the resolver tasks above rather than leaving two constructions in the code
 
 ## Phase 3 — Configuration
 
-- [ ] T010 Define the configuration shape (active theme + roots + per-component roots) as a docblock
+- [X] T010 **Built** (`@type ThemeConfig`: `active`, `themes`; the `roots` list is gone, D-006). Define the configuration shape (active theme + roots + per-component roots) as a docblock
       `@type` alias, with `ConfigProvider` publishing the package's own defaults
-- [ ] T011 Read configuration only — no container bootstrapping at render time, no database access,
+- [X] T011 **Built.** Read configuration only — no container bootstrapping at render time, no database access,
       at boot or at render (FR-006)
-- [ ] T012 Select the active theme from configuration alone (FR-008) and default to `default` when
+- [X] T012 **Built** (`theme.active` absent or empty means `default`; test `defaultsToTheDefaultThemeWhenNoneIsConfigured`). Select the active theme from configuration alone (FR-008) and default to `default` when
       nothing is configured, so an application with no theme configuration renders (US1 scenario 3)
-- [ ] T013 Document that a cached aggregated config must be cleared for a theme switch to take effect
+- [ ] T013 **Open.** Document that a cached aggregated config must be cleared for a theme switch to take effect
       (edge case in `spec.md`)
-- [ ] T014 Derive roots for application and client modules from their registered PSR-4 namespaces,
+- [X] T014 **Superseded (D-006).** Derive roots for application and client modules from their registered PSR-4 namespaces,
       taking the namespace root's sibling `templates/` directory; skip `autoload-dev` prefixes and
       handle a prefix that maps to more than one directory (FR-011)
 
 ## Phase 4 — Asset names
 
-- [ ] T015 Define the resource-map contribution: the package and every component publish
-      `view_manager.asset.resource_map` entries; a theme re-values names and never introduces them
+- [X] T015 **Superseded by Phase 10 (T042–T048), D-007…D-009.** Define the resource-map contribution: the package and every component publish
+      `view_helper_config.asset.resource_map` entries; a theme re-values names and never introduces them
       (FR-009, and the `Asset` helper throws on an unknown name). Settle the exact asset path shape and
       filenames under `public/theme/<theme>/` while doing so — assets are served from there, never from
       a theme's `templates/` root
-- [ ] T016 Contribute the default theme's entries from `ConfigProvider` so that an application with no
+- [X] T016 **Superseded by Phase 10 (T042–T048).** Contribute the default theme's entries from `ConfigProvider` so that an application with no
       theme configuration resolves every asset name the shipped templates use
 
 ## Phase 4b — Theme installer (FR-015)
@@ -89,15 +94,15 @@ be injected from configuration.
 Task IDs are assigned in the order they were added, so this phase carries the next free numbers rather
 than displacing the ones below it.
 
-- [ ] T032 Implement the theme installer: given a theme, materialise its assets under
+- [ ] T032 **Re-scoped (D-012): installing belongs to the composer plugin installer** (`project-tracking#6`), not this package. Original text: implement the theme installer: given a theme, materialise its assets under
       `public/theme/<theme>/` from the theme's own source. Nothing here is a build step — it is the one
       place that writes into a served location
-- [ ] T033 Decide and record how far "manage" goes: create only, update when the theme's assets change,
+- [ ] T033 **Open; requirements are now in `project-tracking#6`** (symlink in dev, copy in prod, idempotent, removes what a package stopped shipping). Decide and record how far "manage" goes: create only, update when the theme's assets change,
       and what happens on uninstall. Whichever way it goes, the installer owns it rather than leaving
       stale files in `public/`
-- [ ] T034 Decide whether the installer is a console command in this package (registered under
+- [ ] T034 **Re-scoped (D-012).** The *installer* is the composer plugin. The console command is for creating a theme from `default`, registering it and switching the active theme (T065–T067). Whether that command lives in this package (registered under
       `Webware\Console\ConsoleInterface::class`, which makes `webware/webware-console` a dependency, as
-      it is for webware-migration) or an application-level command. Record the choice in `plan.md`
+      it is for webware-migration) or elsewhere is still to record in `plan.md`. Original text: decide whether the installer is a console command in this package (registered under
 
 ## Phase 5 — The convention in the packages
 
@@ -107,19 +112,19 @@ than displacing the ones below it.
 - [ ] T018 Confirm the convention against a package with existing templates (webware-navigation,
       webware-htmx) and record any divergence rather than moving files in a package outside this
       feature's scope
-- [ ] T019 Settle the cross-module question the convention leaves open: when more than one module serves
+- [X] T019 **Resolved by design (D-002, D-006):** maps are config, so precedence is the config merge (later wins), not a module order. Settle the cross-module question the convention leaves open: when more than one module serves
       the same namespace, which module's path is consulted first (record it in `plan.md`)
 
 ## Phase 6 — The htmx configuration prerequisite (FR-012)
 
-- [ ] T019 Make webware-htmx read **one key per value** for the body and the layout, whose values are
+- [ ] T039 **In progress: `webinertia/webware-htmx#22` is open** (merge state was `UNKNOWN` on 2026-10-01, re-check). Make webware-htmx read **one key per value** for the body and the layout, whose values are
       theme-resolvable template names, replacing the five-key lookup and the package-published
       `templates.map['body::default']` entry. This is the only part of webinertia/webware-htmx#21 this
       feature needs: without it a theme has no name to resolve for the body
-- [ ] T020 Integration-test that the body name resolves **through the resolver** rather than through a map
+- [ ] T040 **Open.** Integration-test that the body name resolves **through the resolver** rather than through a map
       entry the package publishes itself, and that a theme overriding only the layout still gets the
       default body
-- [ ] T021 Keep webware-htmx free of a dependency on this package: it reads the configured name and hands
+- [ ] T041 **Open.** Keep webware-htmx free of a dependency on this package: it reads the configured name and hands
       it to the aggregate resolver, whichever package supplies it
 
 ## Phase 7 — Consumer-side work, deliberately not in this list
@@ -135,23 +140,136 @@ Everything else in webinertia/webware-htmx#21 is work the convention *enables* b
 
 ## Phase 8 — Tests
 
-- [ ] T022 Unit: `test/unit/Resolver/ThemeResolverTest.php` — a theme hit, a per-template fallback to
+- [ ] T022 **Partly met:** theme hit, per-address fallback and unknown-returns-`false` are tested; name validation (separators) is not, and belongs to T043. Unit: `test/unit/Resolver/ThemeResolverTest.php` — a theme hit, a per-template fallback to
       `default`, an unknown name returning `false`, and name validation rejecting separators
-- [ ] T023 Unit: the per-namespace ordering, including the case where two modules serve the same
+- [ ] T023 **Superseded in intent by D-002** (there is no per-namespace ordering to test); re-scope to "two themes each carry the same address" if a test is wanted. Unit: the per-namespace ordering, including the case where two modules serve the same
       namespace and ship the same template name
-- [ ] T024 Integration: real template files across two roots, proving fallback and that resolution
+- [ ] T024 **Partly met:** `ThemeResolutionTest` (3 tests) uses real files under `test/integration/TestAssets/themes/` for hit, fallback and the theme beating Mezzio's map; the "does not scan per lookup" claim is not asserted. Integration: real template files across two roots, proving fallback and that resolution
       does not scan per lookup
-- [ ] T025 Keep `test/integration/ConfigProviderWiringTest.php` green: it asserts
+- [X] T025 **Built** (`ConfigProviderWiringTest`, green). Keep `test/integration/ConfigProviderWiringTest.php` green: it asserts
       `extra.laminas.config-provider` agrees with the namespace
 
 ## Phase 9 — Spec-kit tracking
 
-- [ ] T026 Keep `.specify/` and `/specs/` tracked in this repository (deliberate divergence from the
+- [X] T026 **Done** (specs and `.specify` are tracked on this branch). Keep `.specify/` and `/specs/` tracked in this repository (deliberate divergence from the
       preset's alignment tasks, which add both to `.gitignore`): this component's development is
       spec-driven, so the scaffolding and the specs live and evolve with it
-- [ ] T027 Keep the vendored preset copy (`.specify/presets/`) local via `.specify/.gitignore`; it is
+- [X] T027 **Done** (`.specify/.gitignore` ignores `presets/`). Keep the vendored preset copy (`.specify/presets/`) local via `.specify/.gitignore`; it is
       released content shipped in `webware/webware-tools/presets/`
 
+## Phase 10 — Theme-aware asset helper (FR-009, FR-009a; D-007, D-008, D-009)
+
+Why: laminas-view's `Asset` helper is `final readonly` and is built once from
+`view_helper_config.asset.resource_map`, with no idea of a theme. The fix is a factory, not a subclass.
+
+- [X] T042 **Done:** the shape is `assets?` in the existing `@type ThemeConfig`, not a separate alias. Define the asset configuration shape as an `@type ThemeAssetsConfig` in `ConfigProvider`:
+      `theme.assets.<theme>.<name> => value`, where `value` is a path relative to that theme's directory
+      (`css/theme.css`) or an absolute URL (`https://`, `//`). Names are a fixed vocabulary defined by the
+      components; a theme re-values them
+- [X] T043 **Done.** Also adds `Webware\Theme\ConfigPath` (nested-array reader) and `Exception\InvalidThemeNameException`; entries already under `view_helper_config.asset.resource_map` are kept as the base; only the `default` and the active theme names are validated (`^[A-Za-z0-9][A-Za-z0-9_-]*$`). Implement `Webware\Theme\View\Helper\Container\AssetFactory` (`final`, returns a stock
+      `Laminas\View\Helper\Asset`). Merge `default` first, then the active theme over it. A relative value
+      becomes `/theme/<theme>/<value>` using the theme that **defined** the name, so fallback is per name;
+      absolute URLs pass through unchanged. Validate every theme name as a single path segment (no `/`,
+      `\`, `..`, empty) and throw a package exception otherwise. Never throw for an unknown name here: the
+      stock `Asset` does that at call time, which is wanted
+- [X] T044 **Done:** `view_helpers.factories` (verified against `laminas-view`'s `ConfigProvider`, which has `view_helpers` as the top-level plugin-manager key). Register it for `Laminas\View\Helper\Asset::class` in the **view helper** factories, not the
+      container's `dependencies`. Verify the exact config key in `laminas-view/src/ConfigProvider.php`
+      before writing it (`view_helper_config` holds helper options; the plugin-manager key is a different
+      one). Merge order matters: this provider must come after `Mezzio\LaminasView\ConfigProvider`
+      (D-004, `project-tracking#6`)
+- [X] T045 **Done:** `test/unit/View/Helper/Container/AssetFactoryTest.php`. Unit tests for the factory: active theme wins; per-name fallback to `default`; absolute URL
+      unchanged; unknown name throws from the helper; a traversal theme name is rejected; an empty config
+      yields a helper whose every call throws
+- [X] T046 **Done:** `test/integration/AssetHelperTest.php`. Integration test through a real `HelperPluginManager` (or the `ServiceManager` the other
+      integration tests use) that `asset('theme.css')` returns `/theme/default/css/theme.css`, then the
+      active theme's value after switching `theme.active`
+- [ ] T047 Document in `quickstart.md` how a theme author adds an asset and where the file goes
+      (`public/theme/<theme>/…`, published by the installer, never hand-written)
+- [X] T048 **Done earlier** (`data-model.md`, `research.md` carry `view_helper_config.asset.resource_map`). Record the final key paths in `data-model.md` and `research.md` (they currently describe
+      `view_manager.asset.resource_map`, which is wrong, D-009)
+
+## Phase 11 — The default theme's assets (repository `webinertia/default-theme`; D-015, D-016)
+
+- [ ] T049 Land `webinertia/default-theme#1` (the Bootstrap 5.3.8 token overrides in `css/theme.css` and
+      `mockup/index.html`). Owner review; do not merge without them
+- [ ] T050 Decide how the default theme is packaged so the installer can publish it to
+      `public/theme/default/{css,js,img,fonts}/` (composer package name and layout). Record it in
+      `decisions.md`
+- [ ] T051 Extend the mockup with the shell: navbar with the three navigation areas (`main`, `admin`,
+      `user`), footer, toast container for the messenger, and the Light/Dark control. Check each page in
+      both modes
+- [ ] T052 Port the CSS the three components need (the `ims-acl-*`, `ims-widget-*`, `ims-badge-*` and
+      `ims-col-*` rules, 84 in IMS `public/assets/css/custom.css`) into `default-theme/css/` with the
+      neutral class names from D-013 and the palette tokens. Keep HTTP-method and privilege colours on
+      Bootstrap's semantic colours (D-016); replace hard-coded Bootstrap RGB values with tokens
+- [ ] T053 CMS-style landing page layout mockup for `app::home-page` (hero plus regions). Blocked on the
+      contract location, D-018
+
+## Phase 12 — Port the base templates to a neutral `default` theme (FR-018 to FR-020; D-010, D-013, D-014)
+
+Scope: webware-acl, webware-admin, webware-usermanager. Everything IMS-specific is copied **verbatim**
+into the `ims` theme first; the `default` copy then loses the `ims-` coupling. No IMS code is lost and
+none lives in a component (standing rule 6).
+
+- [ ] T054 webware-usermanager: land PR #69 (auth pages already neutral and under
+      `templates/default/user/`), then replace the remaining `ims-widget-*` and `ims-col-*` hooks in
+      `admin-widget.phtml` and `list-users.phtml` (five each). Use `list-col-*`, never `col-*` (D-013)
+- [ ] T055 webware-acl: move `templates/acl` to `templates/default/acl`, update
+      `ConfigProvider::getTemplates()` and its test. **Started on branch `feat/default-theme-templates`
+      in the local clone, uncommitted as of 2026-10-01: check `git status` before redoing it.** Then
+      rename the hooks per D-013 in `admin-acl.phtml` (about 37 occurrences), `admin-widget.phtml` and
+      `partials/protect-route-wizard.phtml` (about 30). Change ids, classes, `data-*` references and
+      the markup strings built in JavaScript together
+- [ ] T056 webware-acl: extract the ACL page controller (IMS `public/assets/js/app.js` lines 301 to 704,
+      "ACL Wizard controller") into webware-acl as plain JavaScript with neutral selectors and no build
+      step, shipped as a **component** asset (D-010), and register its asset name. Needs Phase 10 and a
+      served location (D-011, D-012)
+- [ ] T057 webware-admin: move `templates/admin` to `templates/default/admin` and update the template
+      path and its test (the dashboard is 14 lines and already free of `ims` markup)
+- [ ] T058 `webinertia/webware`: copy the verbatim originals (from each component's git history or the IMS
+      repository) into `src/App/templates/ims/<namespace>/` and map them in the `ims` block of
+      `config/autoload/theme.global.php`. Include the IMS CSS and JS with that theme
+- [ ] T059 Verify in a browser with the `default` theme active, dark and light: the ACL overview, roles,
+      resources, the user list and the dashboard render with the palette, and the ACL search, filters,
+      rules offcanvas and protect-route wizard work. Needs an admin user in the app database
+
+## Phase 13 — Cross-repository dependencies
+
+- [ ] T060 `project-tracking#6` (the installer RFC) carries the asset-publishing requirements (added
+      2026-10-01). Until an installer exists, publish assets with a documented one-off command and remove
+      it when #6 lands; nobody hand-creates files under `public/theme/`
+- [ ] T061 Decide where the home-page block contract lives (D-018), then write its spec and plan in that
+      repository. This feature only needs the `default` theme templates that render it (D-019)
+
+## Phase 14 — Owner decisions of 2026-10-01 (D-005, D-011, D-012)
+
+- [X] T062 **Done:** `ConfigProvider::THEME`, `ACTIVE`, `THEMES`, `ASSETS`, used by both factories. Add constants for the known config keys in `ConfigProvider` (`THEME = 'theme'`, `ACTIVE`,
+      `THEMES`, `ASSETS`) and use them in `ThemeResolverFactory` and the tests instead of the string
+      literals (D-005). No new classes
+- [X] T063 **Done** in `AssetFactory` (the one place a name becomes a path today); the command (T066) must reuse the same rule. Validate a theme name as a single path segment (no separators, no `..`) at the one place it
+      becomes a path, the asset factory (T043); test it. Do not add a value object (D-005)
+- [ ] T064 Component assets are per theme (D-011): in T042–T043 the asset values for a component live
+      under `theme.assets.<theme>` and resolve to `/theme/<theme>/component/<component>/…`; document the
+      layout in `data-model.md` (it currently shows the superseded `public/component/` path) and
+      `quickstart.md`
+- [ ] T065 Specify (in `spec.md`) the theme-management command (D-012, D-020): given a name, copy the
+      `default` theme's layout, body and home-page templates and main CSS file into a new theme of that
+      name; register a `theme.themes.<name>` map covering only the copied templates in the autoloaded
+      file `theme.{theme-name}.global.php`; set `theme.active` to it in `theme.settings.global.php`
+      (owner, 2026-10-01: that file holds `active` and any later theme settings, so a per-theme file
+      never sets `active`). Also switch the active theme to an existing one, writing the same key
+- [ ] T066 Implement the command(s) from T065, following the `Console\` guard rule, once T065 is
+      agreed and webware-console placement is recorded (T034). The copy must not overwrite an existing
+      theme, and the name is validated as a single path segment (T063)
+- [ ] T067 Tests for T066 to the 100% line and MSI floors
+- [ ] T068 Admin widget to choose the active theme from the installed themes (D-012), using
+      webware-admin's `WidgetInterface`. It **only switches** between already installed themes and never
+      creates one (owner, 2026-10-01); the switch changes `theme.active` in `theme.settings.global.php`. Depends
+      on T065 (installed-theme list and persistence) and
+      belongs in the repository the owner chooses. Not started
+- [X] T069 Done 2026-10-01 for the layout line; the Theme/roots wording is already marked superseded. Update `data-model.md`: replace the `public/component/` layout with the per-theme one (see
+      T064) and drop the superseded Theme/roots wording now that D-005 is settled
+
 ## Verification
 
 - [ ] T028 `mago format --check && mago lint && mago analyze && mago guard` — all four clean
diff --git a/src/ConfigPath.php b/src/ConfigPath.php
new file mode 100644
index 0000000..4aa5e5c
--- /dev/null
+++ b/src/ConfigPath.php
@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Webware Theme package.
+ *
+ * Copyright (c) 2026 Joey Smith <jsmith@webinertia.net>
+ * and contributors.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Webware\Theme;
+
+use function is_array;
+
+/**
+ * Reads a nested array out of merged configuration, treating anything that is not an array as absent.
+ *
+ * @internal
+ */
+final class ConfigPath
+{
+    /**
+     * @return array<array-key, mixed>
+     */
+    public static function array(mixed $source, string ...$keys): array
+    {
+        foreach ($keys as $key) {
+            /** @var mixed $source */
+            $source = is_array($source) ? $source[$key] ?? null : null;
+        }
+
+        return is_array($source) ? $source : [];
+    }
+}
diff --git a/src/ConfigProvider.php b/src/ConfigProvider.php
index c017ccc..d97e13c 100644
--- a/src/ConfigProvider.php
+++ b/src/ConfigProvider.php
@@ -14,29 +14,72 @@
 
 namespace Webware\Theme;
 
+use Laminas\View\Helper\Asset;
+use Laminas\View\Resolver\AggregateResolver;
+use Webware\Theme\Resolver\Container\AggregateResolverFactory;
+use Webware\Theme\Resolver\Container\ThemeResolverFactory;
+use Webware\Theme\Resolver\ThemeResolver;
+use Webware\Theme\View\Helper\Container\AssetFactory;
+
 /**
  * Wiring entry point for the package.
  *
- * Declared under `extra.laminas.config-provider` in composer.json, so a consumer's
- * config aggregator merges this without any further registration.
+ * Declared under `extra.laminas.config-provider` in composer.json, so a consumer's config aggregator
+ * merges this without any further registration.
+ *
+ * Merge this provider **after** `Mezzio\LaminasView\ConfigProvider`: both own
+ * `AggregateResolver::class`, the later provider wins, and the theme being consulted first is the
+ * whole point of the package.
  *
+ * @type ThemeConfig array{
+ *     active?: non-empty-string,
+ *     themes?: array<non-empty-string, array<non-empty-string, non-empty-string>>,
+ *     assets?: array<non-empty-string, array<non-empty-string, non-empty-string>>,
+ * }
+ * @type DependenciesConfig array{
+ *     factories: array<class-string, class-string>,
+ * }
+ * @type ProviderConfig array{
+ *     dependencies: DependenciesConfig,
+ *     view_helpers: array{factories: array<class-string, class-string>},
+ * }
  * @internal
  */
 final class ConfigProvider
 {
-    /** @return array<string, mixed> */
+    /** The top-level configuration key every theme setting sits under. */
+    final public const string THEME = 'theme';
+
+    /** The name of the active theme, under {@see self::THEME}. */
+    final public const string ACTIVE = 'active';
+
+    /** Template overrides per theme, under {@see self::THEME}. */
+    final public const string THEMES = 'themes';
+
+    /** Asset values per theme, under {@see self::THEME}. */
+    final public const string ASSETS = 'assets';
+
+    /** @return DependenciesConfig */
     public function getDependencies(): array
     {
         return [
-            'factories' => [],
+            'factories' => [
+                ThemeResolver::class     => ThemeResolverFactory::class,
+                AggregateResolver::class => AggregateResolverFactory::class,
+            ],
         ];
     }
 
-    /** @return array<string, mixed> */
+    /** @return ProviderConfig */
     public function __invoke(): array
     {
         return [
             'dependencies' => $this->getDependencies(),
+            'view_helpers' => [
+                'factories' => [
+                    Asset::class => AssetFactory::class,
+                ],
+            ],
         ];
     }
 }
diff --git a/src/Exception/InvalidThemeNameException.php b/src/Exception/InvalidThemeNameException.php
new file mode 100644
index 0000000..ae9d73a
--- /dev/null
+++ b/src/Exception/InvalidThemeNameException.php
@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Webware Theme package.
+ *
+ * Copyright (c) 2026 Joey Smith <jsmith@webinertia.net>
+ * and contributors.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Webware\Theme\Exception;
+
+use InvalidArgumentException;
+
+/**
+ * A theme name that is not a single path segment, so it could not be used to build a safe URL.
+ *
+ * @internal
+ */
+final class InvalidThemeNameException extends InvalidArgumentException {}
diff --git a/src/Resolver/Container/AggregateResolverFactory.php b/src/Resolver/Container/AggregateResolverFactory.php
new file mode 100644
index 0000000..698825c
--- /dev/null
+++ b/src/Resolver/Container/AggregateResolverFactory.php
@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Webware Theme package.
+ *
+ * Copyright (c) 2026 Joey Smith <jsmith@webinertia.net>
+ * and contributors.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Webware\Theme\Resolver\Container;
+
+use Laminas\View\Resolver\AggregateResolver;
+use Laminas\View\Resolver\ResolverInterface;
+use Laminas\View\Resolver\TemplateMapResolver;
+use Mezzio\LaminasView\NamespacedPathStackResolver;
+use Psr\Container\ContainerExceptionInterface;
+use Psr\Container\ContainerInterface;
+use Psr\Container\NotFoundExceptionInterface;
+use Webware\Theme\Resolver\ThemeResolver;
+
+/**
+ * Composes the resolver aggregate with the theme consulted first, then mezzio's map, then its path
+ * stack.
+ *
+ * mezzio's own factory attaches the map and the path stack at equal priority, which leaves their
+ * relative order to the queue. Here the order is stated outright, which is what makes an address the
+ * active theme carries win and every other address resolve exactly as it did before this package was
+ * installed.
+ *
+ * Registering this factory replaces `Mezzio\LaminasView\TemplateResolverFactory` through the
+ * `AggregateResolver::class` service key, so the theme package's provider must be merged after
+ * mezzio's.
+ *
+ * @internal
+ */
+final class AggregateResolverFactory
+{
+    /**
+     * @throws ContainerExceptionInterface
+     * @throws NotFoundExceptionInterface
+     */
+    public function __invoke(ContainerInterface $container): ResolverInterface
+    {
+        $aggregate = new AggregateResolver();
+
+        $aggregate->attach($container->get(ThemeResolver::class), 100);
+        $aggregate->attach($container->get(TemplateMapResolver::class), 50);
+        $aggregate->attach($container->get(NamespacedPathStackResolver::class), 1);
+
+        return $aggregate;
+    }
+}
diff --git a/src/Resolver/Container/ThemeResolverFactory.php b/src/Resolver/Container/ThemeResolverFactory.php
new file mode 100644
index 0000000..2af2088
--- /dev/null
+++ b/src/Resolver/Container/ThemeResolverFactory.php
@@ -0,0 +1,69 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Webware Theme package.
+ *
+ * Copyright (c) 2026 Joey Smith <jsmith@webinertia.net>
+ * and contributors.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Webware\Theme\Resolver\Container;
+
+use Psr\Container\ContainerExceptionInterface;
+use Psr\Container\ContainerInterface;
+use Psr\Container\NotFoundExceptionInterface;
+use Webware\Theme\ConfigProvider;
+use Webware\Theme\Resolver\ThemeResolver;
+
+use function is_array;
+use function is_string;
+
+/**
+ * Builds the theme resolver from the merged `theme` configuration.
+ *
+ * This is where the active theme enters: the resolver is not told which theme to use at call time, so
+ * the configuration is read once, here, and the resolver holds the answer.
+ *
+ * @import-type ThemeConfig from ConfigProvider
+ * @internal
+ */
+final class ThemeResolverFactory
+{
+    /**
+     * @throws ContainerExceptionInterface
+     * @throws NotFoundExceptionInterface
+     */
+    public function __invoke(ContainerInterface $container): ThemeResolver
+    {
+        /** @var mixed $raw */
+        $raw = $container->has('config') ? $container->get('config') : [];
+
+        /** @var array<string, mixed> $config */
+        $config = is_array($raw) ? $raw : [];
+
+        /** @var mixed $theme */
+        $theme = $config[ConfigProvider::THEME] ?? [];
+
+        /** @var ThemeConfig $theme */
+        $theme = is_array($theme) ? $theme : [];
+
+        /** @var mixed $maps */
+        $maps = $theme[ConfigProvider::THEMES] ?? [];
+
+        /** @var array<non-empty-string, array<non-empty-string, non-empty-string>> $maps */
+        $maps = is_array($maps) ? $maps : [];
+
+        /** @var mixed $active */
+        $active = $theme[ConfigProvider::ACTIVE] ?? null;
+
+        return new ThemeResolver(
+            $maps,
+            is_string($active) && '' !== $active ? $active : ThemeResolver::DEFAULT_THEME,
+        );
+    }
+}
diff --git a/src/Resolver/ThemeResolver.php b/src/Resolver/ThemeResolver.php
new file mode 100644
index 0000000..75ec31d
--- /dev/null
+++ b/src/Resolver/ThemeResolver.php
@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Webware Theme package.
+ *
+ * Copyright (c) 2026 Joey Smith <jsmith@webinertia.net>
+ * and contributors.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Webware\Theme\Resolver;
+
+use Laminas\View\Resolver\ResolverInterface;
+use Override;
+
+/**
+ * Resolves a namespaced template address against the active theme's map.
+ *
+ * The name handed in is the address the renderer asks for — `app::home-page`, `layout::default`,
+ * `admin::dashboard` — and a map is keyed by exactly that, so a hit is an `isset` and nothing
+ * touches the filesystem. An address the active theme does not carry falls back to the `default`
+ * theme's entry for the same address, and a name neither theme carries returns `false` so the
+ * aggregate resolver continues to the next resolver.
+ *
+ * @internal
+ */
+final class ThemeResolver implements ResolverInterface
+{
+    /**
+     * The theme every other theme falls back to. Module directories are named for their theme, so
+     * this is also the directory name a module ships when it ships one theme.
+     */
+    final public const string DEFAULT_THEME = 'default';
+
+    /**
+     * @param array<non-empty-string, array<non-empty-string, non-empty-string>> $maps
+     *        theme name => template address => absolute path
+     * @param non-empty-string $active
+     */
+    public function __construct(
+        private readonly array $maps,
+        private readonly string $active = self::DEFAULT_THEME,
+    ) {}
+
+    #[Override]
+    public function resolve(string $name): string|false
+    {
+        return (
+            $this->maps[$this->active][$name]
+                ?? $this->maps[self::DEFAULT_THEME][$name]
+                ?? false
+        );
+    }
+}
diff --git a/src/View/Helper/Container/AssetFactory.php b/src/View/Helper/Container/AssetFactory.php
new file mode 100644
index 0000000..61f15d9
--- /dev/null
+++ b/src/View/Helper/Container/AssetFactory.php
@@ -0,0 +1,107 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Webware Theme package.
+ *
+ * Copyright (c) 2026 Joey Smith <jsmith@webinertia.net>
+ * and contributors.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Webware\Theme\View\Helper\Container;
+
+use Laminas\View\Helper\Asset;
+use Psr\Container\ContainerExceptionInterface;
+use Psr\Container\ContainerInterface;
+use Psr\Container\NotFoundExceptionInterface;
+use Webware\Theme\ConfigPath;
+use Webware\Theme\ConfigProvider;
+use Webware\Theme\Exception\InvalidThemeNameException;
+use Webware\Theme\Resolver\ThemeResolver;
+
+use function is_string;
+use function ltrim;
+use function preg_match;
+use function sprintf;
+use function str_starts_with;
+
+/**
+ * Builds laminas-view's stock `Asset` helper from a map the active theme has been merged into.
+ *
+ * `Asset` is `final readonly` and knows nothing about themes, so the theme is applied here, once: the
+ * `default` theme's values first, the active theme's over them. A relative value becomes
+ * `/theme/<theme>/<value>` using the theme that defined the name, so the fallback is per asset name.
+ * Entries already under laminas-view's own `view_helper_config.asset.resource_map` are the base, so an
+ * application's existing map keeps working.
+ *
+ * @internal
+ */
+final class AssetFactory
+{
+    private const string URL_PREFIX = '/theme/';
+
+    /** @throws InvalidThemeNameException */
+    private static function assertSegment(string $name): void
+    {
+        if (1 !== preg_match('/^[A-Za-z0-9][A-Za-z0-9_-]*$/', $name)) {
+            throw new InvalidThemeNameException(sprintf(
+                'The theme name "%s" is not a single path segment.',
+                $name,
+            ));
+        }
+    }
+
+    private static function url(string $theme, string $value): string
+    {
+        return match (true) {
+            str_starts_with($value, 'https://'),
+            str_starts_with($value, 'http://'),
+            str_starts_with($value, '//'),
+                => $value,
+            default                                                                                                => self::URL_PREFIX
+                . $theme
+                . '/'
+                . ltrim($value, characters: '/'),
+        };
+    }
+
+    /**
+     * @throws ContainerExceptionInterface
+     * @throws NotFoundExceptionInterface
+     * @throws InvalidThemeNameException
+     */
+    public function __invoke(ContainerInterface $container): Asset
+    {
+        /** @var mixed $config */
+        $config = $container->has('config') ? $container->get('config') : [];
+        $theme  = ConfigPath::array($config, ConfigProvider::THEME);
+        $assets = ConfigPath::array($theme, ConfigProvider::ASSETS);
+
+        /** @var mixed $active */
+        $active = $theme[ConfigProvider::ACTIVE] ?? null;
+        $active = is_string($active) && '' !== $active ? $active : ThemeResolver::DEFAULT_THEME;
+
+        $map = ConfigPath::array($config, 'view_helper_config', 'asset', 'resource_map');
+
+        foreach ([ThemeResolver::DEFAULT_THEME, $active] as $name) {
+            self::assertSegment(name: $name);
+
+            /** @var array<string, string> $values */
+            $values = ConfigPath::array($assets, $name);
+
+            foreach ($values as $asset => $value) {
+                $map[$asset] = self::url(
+                    theme: $name,
+                    value: $value,
+                );
+            }
+        }
+
+        /** @var array<non-empty-string, non-empty-string> $map */
+        return new Asset($map);
+    }
+}
diff --git a/test/integration/AssetHelperTest.php b/test/integration/AssetHelperTest.php
new file mode 100644
index 0000000..59f2984
--- /dev/null
+++ b/test/integration/AssetHelperTest.php
@@ -0,0 +1,67 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Webware Theme package.
+ *
+ * Copyright (c) 2026 Joey Smith <jsmith@webinertia.net>
+ * and contributors.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace WebwareTestIntegration\Theme;
+
+use Laminas\ServiceManager\ServiceManager;
+use Laminas\View\Helper\Asset;
+use Laminas\View\HelperPluginManager;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\CoversMethod;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+use Webware\Theme\ConfigProvider;
+use Webware\Theme\View\Helper\Container\AssetFactory;
+
+/**
+ * The asset helper is resolved the way a view does, through the real plugin manager configured by this
+ * package's own provider, and switching the active theme changes what a name resolves to.
+ */
+#[CoversClass(AssetFactory::class)]
+#[CoversMethod(AssetFactory::class, '__invoke')]
+final class AssetHelperTest extends TestCase
+{
+    #[Test]
+    public function switchingTheActiveThemeChangesTheValue(): void
+    {
+        static::assertSame('/theme/acme/css/acme.css', $this->helper('acme')('theme.css'));
+    }
+
+    #[Test]
+    public function theDefaultThemeServesTheDefaultValue(): void
+    {
+        static::assertSame('/theme/default/css/theme.css', $this->helper('default')('theme.css'));
+    }
+
+    private function helper(string $active): Asset
+    {
+        $container = new ServiceManager();
+        $container->setService('config', [
+            ConfigProvider::THEME => [
+                ConfigProvider::ACTIVE => $active,
+                ConfigProvider::ASSETS => [
+                    'default' => ['theme.css' => 'css/theme.css'],
+                    'acme'    => ['theme.css' => 'css/acme.css'],
+                ],
+            ],
+        ]);
+
+        $plugins = new HelperPluginManager($container, new ConfigProvider()->__invoke()['view_helpers']);
+
+        $asset = $plugins->get('asset');
+        static::assertInstanceOf(Asset::class, $asset);
+
+        return $asset;
+    }
+}
diff --git a/test/integration/TestAssets/themes/acme/app/home-page.phtml b/test/integration/TestAssets/themes/acme/app/home-page.phtml
new file mode 100644
index 0000000..cf27f63
--- /dev/null
+++ b/test/integration/TestAssets/themes/acme/app/home-page.phtml
@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Webware Theme package.
+ *
+ * Copyright (c) 2026 Joey Smith <jsmith@webinertia.net>
+ * and contributors.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+?>
+<!-- acme theme: app/home-page -->
diff --git a/test/integration/TestAssets/themes/acme/layout/default.phtml b/test/integration/TestAssets/themes/acme/layout/default.phtml
new file mode 100644
index 0000000..afce5fd
--- /dev/null
+++ b/test/integration/TestAssets/themes/acme/layout/default.phtml
@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Webware Theme package.
+ *
+ * Copyright (c) 2026 Joey Smith <jsmith@webinertia.net>
+ * and contributors.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+?>
+<!-- acme theme: layout/default -->
diff --git a/test/integration/TestAssets/themes/default/app/home-page.phtml b/test/integration/TestAssets/themes/default/app/home-page.phtml
new file mode 100644
index 0000000..1762926
--- /dev/null
+++ b/test/integration/TestAssets/themes/default/app/home-page.phtml
@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Webware Theme package.
+ *
+ * Copyright (c) 2026 Joey Smith <jsmith@webinertia.net>
+ * and contributors.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+?>
+<!-- default theme: app/home-page -->
diff --git a/test/integration/TestAssets/themes/default/layout/default.phtml b/test/integration/TestAssets/themes/default/layout/default.phtml
new file mode 100644
index 0000000..68ebcaa
--- /dev/null
+++ b/test/integration/TestAssets/themes/default/layout/default.phtml
@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Webware Theme package.
+ *
+ * Copyright (c) 2026 Joey Smith <jsmith@webinertia.net>
+ * and contributors.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+?>
+<!-- default theme: layout/default -->
diff --git a/test/integration/ThemeResolutionTest.php b/test/integration/ThemeResolutionTest.php
new file mode 100644
index 0000000..1c9e195
--- /dev/null
+++ b/test/integration/ThemeResolutionTest.php
@@ -0,0 +1,114 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Webware Theme package.
+ *
+ * Copyright (c) 2026 Joey Smith <jsmith@webinertia.net>
+ * and contributors.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace WebwareTestIntegration\Theme;
+
+use Laminas\View\Resolver\AggregateResolver;
+use Laminas\View\Resolver\TemplateMapResolver;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\CoversMethod;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+use Webware\Theme\Resolver\ThemeResolver;
+
+use function is_file;
+
+/**
+ * Exercises resolution against real files: the active theme wins an address it carries, an address
+ * it does not carry comes from `default`, and both hold when the theme resolver sits in a real
+ * aggregate ahead of mezzio's map.
+ */
+#[CoversClass(ThemeResolver::class)]
+#[CoversMethod(ThemeResolver::class, 'resolve')]
+final class ThemeResolutionTest extends TestCase
+{
+    private const ASSETS = __DIR__ . '/TestAssets/themes';
+
+    #[Test]
+    public function anAddressTheThemeDoesNotCarryStillResolvesThroughTheMap(): void
+    {
+        $mezzio = new TemplateMapResolver([
+            'admin::dashboard' => self::ASSETS . '/default/app/home-page.phtml',
+        ]);
+
+        $aggregate = new AggregateResolver();
+        $aggregate->attach(new ThemeResolver($this->maps(), 'acme'), 100);
+        $aggregate->attach($mezzio, 50);
+
+        static::assertSame(
+            self::ASSETS . '/default/app/home-page.phtml',
+            $aggregate->resolve('admin::dashboard'),
+        );
+    }
+
+    #[Test]
+    public function fallsBackToTheDefaultThemesFileForAnAddressTheActiveThemeLacks(): void
+    {
+        $maps = $this->maps();
+        unset($maps['acme']['layout::default']);
+
+        $resolver = new ThemeResolver($maps, 'acme');
+
+        $path = $resolver->resolve('layout::default');
+
+        static::assertSame(self::ASSETS . '/default/layout/default.phtml', $path);
+        static::assertIsString($path);
+        static::assertTrue(is_file($path));
+    }
+
+    #[Test]
+    public function resolvesTheActiveThemesFileFromDisk(): void
+    {
+        $resolver = new ThemeResolver($this->maps(), 'acme');
+
+        $path = $resolver->resolve('app::home-page');
+
+        static::assertIsString($path);
+        static::assertSame(self::ASSETS . '/acme/app/home-page.phtml', $path);
+        static::assertTrue(is_file($path));
+    }
+
+    #[Test]
+    public function theThemeWinsAnAddressMezziosMapAlsoCarries(): void
+    {
+        // The same address, published by the module the old way, through mezzio's own map.
+        $mezzio = new TemplateMapResolver([
+            'app::home-page' => self::ASSETS . '/default/app/home-page.phtml',
+        ]);
+
+        $aggregate = new AggregateResolver();
+        $aggregate->attach(new ThemeResolver($this->maps(), 'acme'), 100);
+        $aggregate->attach($mezzio, 50);
+
+        static::assertSame(
+            self::ASSETS . '/acme/app/home-page.phtml',
+            $aggregate->resolve('app::home-page'),
+        );
+    }
+
+    /** @return array<string, array<string, string>> */
+    private function maps(): array
+    {
+        return [
+            'default' => [
+                'app::home-page'  => self::ASSETS . '/default/app/home-page.phtml',
+                'layout::default' => self::ASSETS . '/default/layout/default.phtml',
+            ],
+            'acme'    => [
+                'app::home-page'  => self::ASSETS . '/acme/app/home-page.phtml',
+                'layout::default' => self::ASSETS . '/acme/layout/default.phtml',
+            ],
+        ];
+    }
+}
diff --git a/test/unit/ConfigPathTest.php b/test/unit/ConfigPathTest.php
new file mode 100644
index 0000000..d4bd094
--- /dev/null
+++ b/test/unit/ConfigPathTest.php
@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Webware Theme package.
+ *
+ * Copyright (c) 2026 Joey Smith <jsmith@webinertia.net>
+ * and contributors.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace WebwareTest\Theme;
+
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\CoversMethod;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+use Webware\Theme\ConfigPath;
+
+#[CoversClass(ConfigPath::class)]
+#[CoversMethod(ConfigPath::class, 'array')]
+final class ConfigPathTest extends TestCase
+{
+    #[Test]
+    public function aMissingKeyIsAnEmptyArray(): void
+    {
+        static::assertSame([], ConfigPath::array(['a' => []], 'a', 'missing'));
+    }
+
+    #[Test]
+    public function aNonArrayAnywhereOnThePathIsAnEmptyArray(): void
+    {
+        static::assertSame([], ConfigPath::array(['a' => 'x'], 'a', 'b'));
+        static::assertSame([], ConfigPath::array('not an array', 'a'));
+        static::assertSame([], ConfigPath::array(['a' => 'x'], 'a'));
+    }
+
+    #[Test]
+    public function returnsTheNestedArrayAtThePath(): void
+    {
+        $config = ['a' => ['b' => ['c' => 1]]];
+
+        static::assertSame(['c' => 1], ConfigPath::array($config, 'a', 'b'));
+    }
+
+    #[Test]
+    public function withNoKeysTheSourceArrayIsReturned(): void
+    {
+        static::assertSame(['a' => 1], ConfigPath::array(['a' => 1]));
+    }
+}
diff --git a/test/unit/ConfigProviderTest.php b/test/unit/ConfigProviderTest.php
index a7a456d..6a5ee2f 100644
--- a/test/unit/ConfigProviderTest.php
+++ b/test/unit/ConfigProviderTest.php
@@ -14,11 +14,17 @@
 
 namespace WebwareTest\Theme;
 
+use Laminas\View\Helper\Asset;
+use Laminas\View\Resolver\AggregateResolver;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\CoversMethod;
 use PHPUnit\Framework\Attributes\Test;
 use PHPUnit\Framework\TestCase;
 use Webware\Theme\ConfigProvider;
+use Webware\Theme\Resolver\Container\AggregateResolverFactory;
+use Webware\Theme\Resolver\Container\ThemeResolverFactory;
+use Webware\Theme\Resolver\ThemeResolver;
+use Webware\Theme\View\Helper\Container\AssetFactory;
 
 #[CoversClass(ConfigProvider::class)]
 #[CoversMethod(ConfigProvider::class, '__invoke')]
@@ -26,20 +32,35 @@
 final class ConfigProviderTest extends TestCase
 {
     #[Test]
-    public function getDependenciesIsAnEmptyFactoryMap(): void
+    public function getDependenciesProvidesTheResolverAndTheAggregateFactories(): void
     {
-        self::assertSame(['factories' => []], new ConfigProvider()->getDependencies());
+        $expected = [
+            'factories' => [
+                ThemeResolver::class     => ThemeResolverFactory::class,
+                AggregateResolver::class => AggregateResolverFactory::class,
+            ],
+        ];
+
+        static::assertSame($expected, new ConfigProvider()->getDependencies());
     }
 
     #[Test]
-    public function providesAnEmptyDependencyFactoryMap(): void
+    public function providesTheResolverAndTheAggregateFactories(): void
     {
         $expected = [
             'dependencies' => [
-                'factories' => [],
+                'factories' => [
+                    ThemeResolver::class     => ThemeResolverFactory::class,
+                    AggregateResolver::class => AggregateResolverFactory::class,
+                ],
+            ],
+            'view_helpers' => [
+                'factories' => [
+                    Asset::class => AssetFactory::class,
+                ],
             ],
         ];
 
-        self::assertSame($expected, new ConfigProvider()->__invoke());
+        static::assertSame($expected, new ConfigProvider()->__invoke());
     }
 }
diff --git a/test/unit/Resolver/ThemeResolverTest.php b/test/unit/Resolver/ThemeResolverTest.php
new file mode 100644
index 0000000..cfb873c
--- /dev/null
+++ b/test/unit/Resolver/ThemeResolverTest.php
@@ -0,0 +1,97 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Webware Theme package.
+ *
+ * Copyright (c) 2026 Joey Smith <jsmith@webinertia.net>
+ * and contributors.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace WebwareTest\Theme\Resolver;
+
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\CoversMethod;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+use Webware\Theme\Resolver\ThemeResolver;
+
+#[CoversClass(ThemeResolver::class)]
+#[CoversMethod(ThemeResolver::class, 'resolve')]
+final class ThemeResolverTest extends TestCase
+{
+    /** @var array<string, array<string, string>> */
+    private const MAPS = [
+        'default' => [
+            'app::home-page'  => '/app/templates/default/app/home-page.phtml',
+            'layout::default' => '/app/templates/default/layout/default.phtml',
+        ],
+        'acme'    => [
+            'app::home-page' => '/app/templates/acme/app/home-page.phtml',
+        ],
+    ];
+
+    #[Test]
+    public function defaultsToTheDefaultThemeWhenNoneIsConfigured(): void
+    {
+        $resolver = new ThemeResolver(self::MAPS);
+
+        static::assertSame(
+            '/app/templates/default/app/home-page.phtml',
+            $resolver->resolve('app::home-page'),
+        );
+    }
+
+    #[Test]
+    public function fallsBackToDefaultForAnAddressTheActiveThemeDoesNotCarry(): void
+    {
+        $resolver = new ThemeResolver(self::MAPS, 'acme');
+
+        static::assertSame(
+            '/app/templates/default/layout/default.phtml',
+            $resolver->resolve('layout::default'),
+        );
+    }
+
+    #[Test]
+    public function fallsBackToDefaultWhenTheActiveThemeHasNoMapAtAll(): void
+    {
+        $resolver = new ThemeResolver(self::MAPS, 'a-theme-nobody-shipped');
+
+        static::assertSame(
+            '/app/templates/default/app/home-page.phtml',
+            $resolver->resolve('app::home-page'),
+        );
+    }
+
+    #[Test]
+    public function resolvesAnAddressTheActiveThemeCarries(): void
+    {
+        $resolver = new ThemeResolver(self::MAPS, 'acme');
+
+        static::assertSame(
+            '/app/templates/acme/app/home-page.phtml',
+            $resolver->resolve('app::home-page'),
+        );
+    }
+
+    #[Test]
+    public function returnsFalseForAnAddressNoThemeCarries(): void
+    {
+        $resolver = new ThemeResolver(self::MAPS, 'acme');
+
+        static::assertFalse($resolver->resolve('admin::dashboard'));
+    }
+
+    #[Test]
+    public function returnsFalseWhenNoMapsAreConfigured(): void
+    {
+        $resolver = new ThemeResolver([]);
+
+        static::assertFalse($resolver->resolve('app::home-page'));
+    }
+}
diff --git a/test/unit/View/Helper/Container/AssetFactoryTest.php b/test/unit/View/Helper/Container/AssetFactoryTest.php
new file mode 100644
index 0000000..8ff7b64
--- /dev/null
+++ b/test/unit/View/Helper/Container/AssetFactoryTest.php
@@ -0,0 +1,194 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Webware Theme package.
+ *
+ * Copyright (c) 2026 Joey Smith <jsmith@webinertia.net>
+ * and contributors.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace WebwareTest\Theme\View\Helper\Container;
+
+use Laminas\View\Exception\InvalidArgumentException;
+use Laminas\View\Helper\Asset;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\CoversMethod;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+use Psr\Container\ContainerInterface;
+use Webware\Theme\Exception\InvalidThemeNameException;
+use Webware\Theme\View\Helper\Container\AssetFactory;
+
+#[CoversClass(AssetFactory::class)]
+#[CoversMethod(AssetFactory::class, '__invoke')]
+final class AssetFactoryTest extends TestCase
+{
+    /** @return iterable<string, array{string, string}> */
+    public static function absoluteUrls(): iterable
+    {
+        yield 'https' => ['bootstrap', 'https://cdn.example.com/bootstrap.css'];
+        yield 'http' => ['insecure', 'http://cdn.example.com/y.js'];
+        yield 'protocol relative' => ['protocol', '//cdn.example.com/x.js'];
+    }
+
+    /** @return iterable<string, array{string}> */
+    public static function badThemeNames(): iterable
+    {
+        yield 'traversal' => ['..'];
+        yield 'nested' => ['a/b'];
+        yield 'backslash' => ['a\\b'];
+        yield 'leading dot' => ['.hidden'];
+        yield 'space' => ['a b'];
+    }
+
+    #[Test]
+    public function aLeadingSlashOnARelativeValueDoesNotEscapeTheThemeDirectory(): void
+    {
+        $asset = $this->build($this->config('default'));
+
+        static::assertSame('/theme/default/css/leading.css', $asset('leading'));
+    }
+
+    #[Test]
+    #[DataProvider('absoluteUrls')]
+    public function anAbsoluteUrlPassesThroughUnchanged(string $name, string $expected): void
+    {
+        $asset = $this->build($this->config('acme'));
+
+        static::assertSame($expected, $asset($name));
+    }
+
+    #[Test]
+    public function aNameTheActiveThemeLacksFallsBackToDefaultByName(): void
+    {
+        $asset = $this->build($this->config('acme'));
+
+        static::assertSame('/theme/default/js/app.js', $asset('app.js'));
+    }
+
+    #[Test]
+    public function anEmptyActiveNameMeansDefault(): void
+    {
+        $asset = $this->build($this->config(''));
+
+        static::assertSame('/theme/default/css/theme.css', $asset('theme.css'));
+    }
+
+    #[Test]
+    public function anUnknownNameThrowsFromTheHelper(): void
+    {
+        $asset = $this->build($this->config('acme'));
+
+        $this->expectException(InvalidArgumentException::class);
+
+        $asset('missing.css');
+    }
+
+    #[Test]
+    #[DataProvider('badThemeNames')]
+    public function aThemeNameThatIsNotASingleSegmentIsRejected(string $name): void
+    {
+        $this->expectException(InvalidThemeNameException::class);
+
+        $this->build($this->config($name));
+    }
+
+    #[Test]
+    public function entriesUnderLaminasViewsOwnKeyAreKept(): void
+    {
+        $config                       = $this->config('acme');
+        $config['view_helper_config'] = ['asset' => ['resource_map' => ['legacy.css' => '/legacy.css']]];
+
+        $asset = $this->build($config);
+
+        static::assertSame('/legacy.css', $asset('legacy.css'));
+    }
+
+    #[Test]
+    public function malformedAssetEntriesYieldAnEmptyMap(): void
+    {
+        $asset = $this->build([
+            'theme'              => ['assets' => 'x'],
+            'view_helper_config' => ['asset' => 'y'],
+        ]);
+
+        $this->expectException(InvalidArgumentException::class);
+
+        $asset('theme.css');
+    }
+
+    #[Test]
+    public function malformedThemeConfigurationYieldsAnEmptyMap(): void
+    {
+        $asset = $this->build(['theme' => 'x', 'view_helper_config' => 'y']);
+
+        $this->expectException(InvalidArgumentException::class);
+
+        $asset('theme.css');
+    }
+
+    #[Test]
+    public function theActiveThemeWinsANameItDefines(): void
+    {
+        $asset = $this->build($this->config('acme'));
+
+        static::assertSame('/theme/acme/css/acme.css', $asset('theme.css'));
+    }
+
+    #[Test]
+    public function theDefaultThemeValuesAreServedFromItsOwnDirectory(): void
+    {
+        $asset = $this->build($this->config('default'));
+
+        static::assertSame('/theme/default/css/theme.css', $asset('theme.css'));
+    }
+
+    #[Test]
+    public function withoutConfigurationEveryNameThrowsFromTheHelper(): void
+    {
+        $asset = $this->build([], hasConfig: false);
+
+        $this->expectException(InvalidArgumentException::class);
+
+        $asset('theme.css');
+    }
+
+    /** @param array<string, mixed> $config */
+    private function build(array $config, bool $hasConfig = true): Asset
+    {
+        $container = $this->createStub(ContainerInterface::class);
+        $container->method('has')->willReturn($hasConfig);
+        $container->method('get')->willReturn($config);
+
+        return new AssetFactory()->__invoke($container);
+    }
+
+    /** @return array<string, mixed> */
+    private function config(string $active): array
+    {
+        return [
+            'theme' => [
+                'active' => $active,
+                'assets' => [
+                    'default' => [
+                        'theme.css' => 'css/theme.css',
+                        'app.js'    => 'js/app.js',
+                        'bootstrap' => 'https://cdn.example.com/bootstrap.css',
+                        'protocol'  => '//cdn.example.com/x.js',
+                        'insecure'  => 'http://cdn.example.com/y.js',
+                        'leading'   => '/css/leading.css',
+                    ],
+                    'acme'    => [
+                        'theme.css' => 'css/acme.css',
+                    ],
+                ],
+            ],
+        ];
+    }
+}