What Deep Whale actually is
Deep Whale is a skin and asset pack for the DSH Web GUI, not a code plugin that adds behaviour to the harness. The README calls it an independent distribution repository for a whale-girl themed skin series: it changes how the interface looks — palettes, character artwork, decorative layers and sidebar treatment — and does not advertise new agent capabilities, tools, or services.
That framing decides how you should read everything below. Installing Deep Whale is closer to installing a theme than to installing a feature, and the way it is packaged says so.
Three packages, and the one that is not a skin
The repository does not ship one package. Each of the following is a separate subdirectory, installed independently and named as its own package:
maid-atelier—@dsh-external/dsh-client-ui-skin-maid-atelier, described as a deep-sea maid atelier: twin-maid backgrounds, deep-blue lace interface, chibi sidebar.orca-link—@dsh-external/dsh-client-ui-skin-orca-link, described as an orca link: pearl-white mechanical cabin, orca-girl character, electric-blue link signals.skin-manager—@dsh-external/dsh-client-ui-skin-deep-whale-manager, a generic skin discovery, switching and per-skin configuration panel.
The README is explicit that skin-manager is not a skin. It is the control surface, and the README recommends keeping it installed, because switching and mutual exclusion both depend on it. The two skins are maid-atelier and orca-link; those are the two that compete with each other, and only those two.
Read this before installing: skins are enabled by default, and the rows go in two files
This is the operational trap the README flags as required reading. Skin on/off state is controlled by disabled rows in the Cordis patch layer. If a skin has no disabled row in the patch, that skin is enabled by default. So a single installed skin works out of the box — and two installed skins that have never been toggled will run at the same time.
The README is specific about the damage: the decorative layers stack, the sidebar and settings area get scrambled, and the typical symptoms are that the settings button disappears, sidebar width and layout break, and the interface is visibly muddled. The stock interface is fine. Enabling both skins is not a cosmetic preference; it is a broken UI state.
Installation therefore needs an exclusion row. One of the two skins must carry disabled: true; the README states that the two skins may leave at most one false. The manager provides the backstop: on the first restart after a one-line install it merges the profile and home states, detects that both skins are effectively enabled, and automatically rolls back atomically to the official default while writing the exclusion rows. A pre-existing legitimate choice of zero or one enabled skin is not rewritten, so there is no stacking window on a fresh install and no need to prepare the rows by hand first.
If you add the exclusion rows yourself, or repair them later, this is what you are editing. The manager writes into both patch layers — ~/.dsh/profiles/web/cordis.patch.yml and the home-level ~/.dsh/cordis.patch.yml, where the home layer takes precedence. The README says both are mandatory and that hand-written edits must be appended to both.
The rows look like an id plus a disabled boolean, for example an entry for the maid-atelier wiring id set to false and the orca-link entry set to true. The README states that non-skin YAML is preserved rather than the whole patch file being overwritten, and warns that replacing the default template’s single [] line with a list is required — leaving comments, [] and other entries together produces invalid YAML, the config parse fails, and the server keeps running on the last usable config until you fix it and refresh.
Requirements and restart behaviour
- pnpm ≥ 9 is required. The subdirectory
#path:spec syntax starts at pnpm 9; the README says pnpm 8 reads apath:spec as a commit reference and errors out. - The packages install directly as GitHub dependencies as
#path:subdirectories. The README says no clone is needed, and that a local clone directory can be substituted for local development or weak networks — but GitHub and local-link installs target the same package names, so mixing them means the last install wins. - A restart is needed for the first install and whenever you add or remove a package. Toggling a skin does not need a restart: switching hot-reloads, via the manager’s “switch” action under Settings → Skin Management, followed by a page refresh.
- The staging script that sets the target skin before install is optional; skipping it is safe because the manager falls back to the official default on first start.
- The README’s verification path is to list the three
@dsh-external/*dependencies in the profile and then check the dumped config, and — after a cold start — to confirm in the browser console that the start page actually references the manager and the enabled skin’sclient.js. It notes that a config entry alone does not prove the browser package registered.
Known limits and failure modes
The README documents its troubleshooting rather than promising smoothness. A misspelled GitHub spec, no network, or a bare directory name used as a local spec all surface as a 404-style fetch error. Relative paths resolve against the directory you invoke the command from, not the skin repository, and a bare directory name is treated as an npm registry package name and fails — ./maid-atelier, ../dsh-deep-whale/maid-atelier or an absolute path is required. On Windows, a # that is not quoted is cut off as a comment.
Two things the README does not state, so do not assume them: it gives no supported DSH version range and no release-notes or compatibility policy for harness upgrades, and it describes no telemetry behaviour either way. The skins touch interface chrome, which is exactly the surface that upstream UI changes break, so treat any harness upgrade as something to verify visually rather than to trust.
Licensing: MIT code, non-commercial artwork
The split matters and is easy to get wrong. The repository’s own code is MIT. The artwork is not. Every artwork asset in both skins — including images the README describes as AI-generated or processed — is licensed CC BY-NC-SA 4.0, and commercial use is prohibited. The README states that images remain outside the MIT grant even when embedded in source, CSS or build output, so shipping the built result is not a way around the artwork terms. Attribution chains live in each skin’s own NOTICE file, with the license text in LICENSE-ARTWORK. The README also credits the character artwork to named original creators, asks that problems be filed as issues rather than sent to them, and notes that the skin scaffolding comes from a separate project while this repository distributes finished skins only.
When to use it — and when not to
Use it if you want the DSH Web GUI to look like this specific series and you accept that you are installing decoration, not capability. Use the manager, and enable exactly one skin.
Do not stack this repository’s packages on top of @linxin666/dsh-web-all (DSH Web). The README is direct on this point: in a DSH Web environment, install the maid-atelier and orca-link adaptations from that bundle’s own skin centre instead, and do not add this repository’s standalone packages into the same profile, because the component and style contracts differ and the interface may display incorrectly. Skip this pack if you need the artwork commercially, if you cannot upgrade pnpm, or if you would rather not maintain patch-file rows — and note that the pack only decides how the interface looks, so nothing here is required for the harness to work.
FAQ
Can I enable both skins at once?
No. With no disabled row a skin is enabled by default, so installing both without toggling leaves both running, and the README reports a broken interface: the settings button disappears and the sidebar width and layout break. The manager detects that on the first restart and atomically rolls back to the official default, writing the exclusion rows it needs — and a pre-existing legitimate choice of zero or one enabled skin is left untouched.
Can I use the artwork in a commercial project?
No. The repository’s code is MIT, but all artwork in both skins — including AI-generated and processed images — is CC BY-NC-SA 4.0 with commercial use prohibited, and the README says images stay outside the MIT grant even when embedded in source, CSS or build output. Attribution is in each skin’s NOTICE file.
Does it patch or modify DSH itself?
It does not modify DSH’s source. It writes disabled rows into the Cordis patch layer in both the web profile and the home directory, preserving non-skin YAML, and the manager exposes the switch under Settings → Skin Management.
Do I need to restart after enabling a skin?
Not for the toggle itself. A restart is needed for the first install and whenever a package is added or removed; after that, switching skins hot-reloads and only needs a page refresh.
Is it safe to install alongside DSH Web?
Not as standalone packages. If @linxin666/dsh-web-all is installed, the README says to use that bundle’s skin centre for its maid-atelier and orca-link adaptations instead of stacking this repository’s packages into the same profile.