feishin Documentation

Technical Documentation: jeffvli/feishin

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

Feishin

Rewrite of Sonixd.

Features Copy Chapter

• MPV player backend
• Web player backend
• Modern UI
• Scrobble playback to your server
• Smart playlist editor (Navidrome)
• Synchronized and unsynchronized lyrics support
• Request a feature or view taskboard

Screenshots Copy Chapter

Getting Started Copy Chapter

Desktop (recommended) Copy Section

Download the latest desktop client. The desktop client is the recommended way to use Feishin. It supports both the MPV and web player backends, as well as includes built-in fetching for lyrics.

macOS Notes

If you're using a device running macOS 12 (Monterey) or higher, check here for instructions on how to remove the app from quarantine.

For media keys to work, you will be prompted to allow Feishin to be a Trusted Accessibility Client. After allowing, you will need to restart Feishin for the privacy settings to take effect.

Linux Notes

Feishin is available in Flathub.

Alternatively, you can install it as an Appimage. We provide a small install script to download the latest .AppImage, make it executable, and also download the icons required by Desktop Environments. Finally, it generates a .desktop file to add Feishin to your Application Launcher.

Simply run the installer like this:

dir=/your/application/directory
curl 'https://raw.githubusercontent.com/jeffvli/feishin/refs/heads/development/install-feishin-appimage' | sh -s -- "$dir"

The script also has an option to add launch arguments to run Feishin in native Wayland mode. Note that this is experimental in Electron and therefore not officially supported. If you want to use it, run this instead:

dir=/your/application/directory
curl 'https://raw.githubusercontent.com/jeffvli/feishin/refs/heads/development/install-feishin-appimage' | sh -s -- "$dir" wayland-native

It also provides a simple uninstall routine, removing the downloaded files:

dir=/your/application/directory
curl 'https://raw.githubusercontent.com/jeffvli/feishin/refs/heads/development/install-feishin-appimage' | sh -s -- "$dir" remove

The entry should show up in your Application Launcher immediately. If it does not, simply log out, wait 10 seconds, and log back in. Your Desktop Environment may alternatively provide a way to reload entries.

Web and Docker Copy Section

Visit https://feishin.vercel.app to use the hosted web version of Feishin. The web client only supports the web player backend.

Feishin is also available as a Docker image. The images are hosted via ghcr.io and are available to view here. You can run the container using the following commands:

# Run the latest version
docker run --name feishin -p 9180:9180 ghcr.io/jeffvli/feishin:latest

# Build the image locally
docker build -t feishin .
docker run --name feishin -p 9180:9180 feishin

Docker Compose

To install via Docker Compose, use the following snippet. This also works on Portainer.

services:
    feishin:
        container_name: feishin
        image: 'ghcr.io/jeffvli/feishin:latest'
        restart: unless-stopped
        environment:
            - SERVER_NAME=jellyfin # pre-defined server name
            - SERVER_LOCK=true # When true AND name/type/url are set, only username/password can be toggled
            - SERVER_TYPE=jellyfin # the allowed types are: jellyfin, navidrome, subsonic. These values are case insensitive
            - SERVER_URL= # http://address:port or https://address:port
            - REMOTE_URL= # http://address or https://address
            - LEGACY_AUTHENTICATION=false # When SERVER_LOCK is true, sets the legacy (plaintext) authentication flag for Subsonic/OpenSubsonic servers
            - ANALYTICS_DISABLED=true # Set to true to disable Umami analytics tracking
        ports:
            - 9180:9180
            # Alternatively, to restrict to only localhost, - 127.0.0.1:9180:8190

Configuration Copy Section

1. Upon startup you will be greeted with a prompt to select the path to your MPV binary. If you do not have MPV installed, you can download it here or install it using any package manager supported by your OS. After inputting the path, restart the app.

2. After restarting the app, you will be prompted to select a server. Click the Open menu button and select Manage servers. Click the Add server button in the popup and fill out all applicable details. You will need to enter the full URL to your server, including the protocol and port if applicable (e.g. https://navidrome.my-server.com or http://192.168.0.1:4533).

• Navidrome - For the best experience, select "Save password" when creating the server and configure the SessionTimeout setting in your Navidrome config to a larger value (e.g. 72h).
  • Linux users - The default password store uses libsecret. kwallet4/5/6 are also supported, but must be explicitly set in Settings > Window > Passwords/secret store.

3. Optional - If you want to host Feishin on a subpath (not /), then pass in the following environment variable: PUBLIC_PATH=PATH. For example, to host on /feishin, pass in PUBLIC_PATH=/feishin.

4. Optional - To hard code the server url, pass the following environment variables: SERVER_NAME, SERVER_TYPE (one of jellyfin or navidrome or subsonic), SERVER_URL. To prevent users from changing these settings, pass SERVER_LOCK=true. This can only be set if all three of the previous values are set. When SERVER_LOCK=true, you can also set LEGACY_AUTHENTICATION=true or LEGACY_AUTHENTICATION=false to configure the legacy authentication flag for the server (only applicable for Subsonic/OpenSubsonic servers).

5. Optional - If your server uses a separate public-facing URL than what integrating applications use internally to communicate with your server, such as a separate Navidrome ShareURL, set REMOTE_URL to said public-facing URL.

6. Optional - To disable Umami analytics tracking in the Docker/web version, set the environment variable ANALYTICS_DISABLED=true. When enabled, the analytics script will not be loaded and all tracking will be disabled.

7. Optional - App settings (theme, language, sidebar options, etc.) can be overridden with environment variables on first run. The variables use the FS_ prefix (e.g. FS_GENERAL_THEME=defaultDark, FS_GENERAL_LANGUAGE=de). See the settings environment variable documentation for the full list.

FAQ Copy Chapter

MPV is either not working or is rapidly switching between pause/play states Copy Section

First thing to do is check that your MPV binary path is correct. Navigate to the settings page and re-set the path and restart the app. If your issue still isn't resolved, try reinstalling MPV. Known working versions include v0.35.x and v0.36.x. v0.34.x is a known broken version.

What music servers does Feishin support? Copy Section

Feishin supports any music server that implements a Navidrome, Jellyfin, or OpenSubsonic compatible API.

• Navidrome

• Jellyfin

• OpenSubsonic compatible servers, such as...

  • Airsonic-Advanced
  • Ampache
  • Astiga
  • Funkwhale
  • Gonic
  • LMS
  • Nextcloud Music
  • Supysonic
  • Qm-Music
  • More (?)

• Plex

  • Feishin fork by lux032 - Plex is not natively supported. Use the fork by lux032 to use Plex with Feishin.

I have the issue "The SUID sandbox helper binary was found, but is not configured correctly" on Linux Copy Section

This happens when you have user (unprivileged) namespaces disabled (sysctl kernel.unprivileged_userns_clone returns 0). You can fix this by either enabling unprivileged namespaces, or by making the chrome-sandbox Setuid.

chmod 4755 chrome-sandbox
sudo chown root:root chrome-sandbox

Ubuntu 24.04 specifically introduced breaking changes that affect how namespaces work. Please see https://discourse.ubuntu.com/t/ubuntu-24-04-lts-noble-numbat-release-notes/39890#:~:text=security%20improvements%20 for possible fixes.

How can I add custom themes? Copy Section

On the desktop app, you can add custom themes by dropping JSON files into the Themes folder (Settings → General → Theme → Open Folder). See the custom themes documentation for the file format and examples.

Development Copy Chapter

Built and tested using Node v23.11.0.

This project is built off of electron-vite

• pnpm run dev - Start the development server
• pnpm run dev:watch - Start the development server in watch mode (for main / preload HMR)
• pnpm run start - Starts the app in production preview mode
• pnpm run build - Builds the app for desktop
• pnpm run build:electron - Build the electron app (main, preload, and renderer)
• pnpm run build:remote - Build the remote app (remote)
• pnpm run build:web - Build the standalone web app (renderer)
• pnpm run package - Package the project
• pnpm run package:dev - Package the project for development locally
• pnpm run package:linux - Package the project for Linux locally
• pnpm run package:mac - Package the project for Mac locally
• pnpm run package:win - Package the project for Windows locally
• pnpm run publish:linux - Publish the project for Linux
• pnpm run publish:linux:beta - Publish the project for Linux (beta channel)
• pnpm run publish:linux-arm64 - Publish the project for Linux ARM64
• pnpm run publish:linux-arm64:beta - Publish the project for Linux ARM64 (beta channel)
• pnpm run publish:mac - Publish the project for Mac
• pnpm run publish:mac:beta - Publish the project for Mac (beta channel)
• pnpm run publish:win - Publish the project for Windows
• pnpm run publish:win:beta - Publish the project for Windows (beta channel)
• pnpm run typecheck - Type check the project
• pnpm run typecheck:node - Type check the project with tsconfig.node.json
• pnpm run typecheck:web - Type check the project with tsconfig.web.json
• pnpm run lint - Lint the project
• pnpm run lint:fix - Lint the project and fix linting errors
• pnpm run i18next - Generate i18n files

Translation Copy Chapter

This project uses Weblate for translations. If you would like to contribute, please visit the link and submit a translation.

License Copy Chapter

GNU General Public License v3.0 ©

Overview (`.agents/skills/caveman-commit/README.md`) Copy Section

caveman-commit

Terse Conventional Commits. Why over what.

What it does Copy Chapter

Generates commit messages in Conventional Commits format. Subject ≤50 chars, hard cap 72. Imperative mood. Body only when the why is non-obvious or there are breaking changes. No AI attribution, no "this commit does X", no emoji unless the project uses them. Body always required for breaking changes, security fixes, data migrations, and reverts — future debuggers need the context.

Outputs only the message. Does not stage, commit, or amend.

How to invoke Copy Chapter

/caveman-commit

Also triggers on phrases like "write a commit", "commit message", "generate commit".

Example output Copy Chapter

Diff: new endpoint for user profile.

feat(api): add GET /users/:id/profile

Mobile client needs profile data without the full user payload
to reduce LTE bandwidth on cold-launch screens.

Closes #128

Diff: breaking API rename.

feat(api)!: rename /v1/orders to /v1/checkout

BREAKING CHANGE: clients on /v1/orders must migrate to /v1/checkout
before 2026-06-01. Old route returns 410 after that date.

See also Copy Chapter

• SKILL.md — full LLM-facing instructions
• Caveman README — repo overview

Overview (`.agents/skills/caveman-review/README.md`) Copy Section

caveman-review

One-line PR comments. Location, problem, fix. No throat-clearing.

What it does Copy Chapter

Generates code review comments in L<line>: <severity> . <fix>. format. One line per finding. Severity emoji: 🔴 bug, 🟡 risk, 🔵 nit, ❓ question. Drops "I noticed that...", hedging, and restating what the diff already shows. Keeps exact line numbers, backticked symbols, and concrete fixes.

Auto-clarity: drops terse mode for CVE-class security findings, architectural disagreements, and onboarding contexts where the author needs the why. Resumes terse for the rest.

Output only — does not approve, request changes, or run linters.

How to invoke Copy Chapter

/caveman-review

Also triggers on "review this PR", "code review", "review the diff".

Example output Copy Chapter

L42: 🔴 bug: user can be null after .find(). Add guard before .email.
L88-140: 🔵 nit: 50-line fn does 4 things. Extract validate/normalize/persist.
L23: 🟡 risk: no retry on 429. Wrap in withBackoff(3).
L107: ❓ q: why drop the cache here? Reads on next request will miss.

See also Copy Chapter

• SKILL.md — full LLM-facing instructions
• Caveman README — repo overview

Overview (`.claude/skills/caveman-commit/README.md`) Copy Section

caveman-commit

Terse Conventional Commits. Why over what.

What it does Copy Chapter

Generates commit messages in Conventional Commits format. Subject ≤50 chars, hard cap 72. Imperative mood. Body only when the why is non-obvious or there are breaking changes. No AI attribution, no "this commit does X", no emoji unless the project uses them. Body always required for breaking changes, security fixes, data migrations, and reverts — future debuggers need the context.

Outputs only the message. Does not stage, commit, or amend.

How to invoke Copy Chapter

/caveman-commit

Also triggers on phrases like "write a commit", "commit message", "generate commit".

Example output Copy Chapter

Diff: new endpoint for user profile.

feat(api): add GET /users/:id/profile

Mobile client needs profile data without the full user payload
to reduce LTE bandwidth on cold-launch screens.

Closes #128

Diff: breaking API rename.

feat(api)!: rename /v1/orders to /v1/checkout

BREAKING CHANGE: clients on /v1/orders must migrate to /v1/checkout
before 2026-06-01. Old route returns 410 after that date.

See also Copy Chapter

• SKILL.md — full LLM-facing instructions
• Caveman README — repo overview

Overview (`.claude/skills/caveman-review/README.md`) Copy Section

caveman-review

One-line PR comments. Location, problem, fix. No throat-clearing.

What it does Copy Chapter

Generates code review comments in L<line>: <severity> . <fix>. format. One line per finding. Severity emoji: 🔴 bug, 🟡 risk, 🔵 nit, ❓ question. Drops "I noticed that...", hedging, and restating what the diff already shows. Keeps exact line numbers, backticked symbols, and concrete fixes.

Auto-clarity: drops terse mode for CVE-class security findings, architectural disagreements, and onboarding contexts where the author needs the why. Resumes terse for the rest.

Output only — does not approve, request changes, or run linters.

How to invoke Copy Chapter

/caveman-review

Also triggers on "review this PR", "code review", "review the diff".

Example output Copy Chapter

L42: 🔴 bug: user can be null after .find(). Add guard before .email.
L88-140: 🔵 nit: 50-line fn does 4 things. Extract validate/normalize/persist.
L23: 🟡 risk: no retry on 429. Wrap in withBackoff(3).
L107: ❓ q: why drop the cache here? Reads on next request will miss.

See also Copy Chapter

• SKILL.md — full LLM-facing instructions
• Caveman README — repo overview

CUSTOM THEMES (`docs/CUSTOM_THEMES.md`) Copy Section

Custom Themes

Custom themes let you add your own light and dark themes to the desktop app without rebuilding Feishin. Drop JSON theme files into the Themes folder; Feishin watches that folder and reloads themes when files change.

Custom themes are Electron / desktop only. They are not available in the web or Docker builds.

Getting started Copy Chapter

1. Open Settings → General → Theme.
2. Under Custom Themes, click Open Folder to reveal the Themes directory.
3. Add a .json file (for example my-theme.json).
4. Select the theme from the Theme dropdown (it appears under Dark or Light based on mode).

You can also click Reload in Settings if a change was not picked up automatically.

Themes folder location Copy Section

In development builds the folder name is under feishin-dev instead of feishin.

Theme files must be .json files in the root of the Themes folder (not nested in subfolders). Linked stylesheets may live next to them or in subfolders, as long as they stay inside Themes.

Theme file format Copy Chapter

Each theme is a single JSON object.

{
  "mode": "dark",
  "extends": "defaultDark",
  "colors": {
    "primary": "rgb(53, 116, 252)",
    "background": "rgb(12, 12, 12)",
    "foreground": "rgb(225, 225, 225)"
  },
  "app": {
    "scrollbar-size": "9px"
  },
  "mantineOverride": {
    "primaryShade": {
      "dark": 6
    }
  },
  "stylesheets": ["my-theme.css"]
}

Identity Copy Section

Use a unique filename. The id is what appears in settings and what you use when another theme extends this one.

Fields Copy Section

Unspecified color and app values fall back to Feishin’s default theme (and then to anything provided by extends).

Colors Copy Chapter

Supported colors keys:

Values must be valid CSS colors recognized by Feishin’s color validator (for example rgb(...), rgba(...), #rrggbb, #rgb). Named CSS colors like red are rejected. Invalid entries are ignored and listed under Custom Themes warnings in Settings.

App variables Copy Chapter

Supported app keys (CSS values as strings):

Extending themes Copy Chapter

Use extends to start from a built-in or another custom theme and only override what you need.

{
  "mode": "dark",
  "extends": "nord",
  "colors": {
    "primary": "#88c0d0"
  }
}

Rules:

• Custom theme fields always win over the theme they extend.
• Custom → custom chains are flattened when loading (depth limit of 10; cycles are ignored).
• If extends is a built-in id, merging with that built-in’s defaults happens in the renderer.
• If extends is omitted, the theme still merges onto Feishin’s shared default palette.

Built-in theme ids Copy Section

Use these as extends values (same ids as in Settings):

ayuDark, ayuLight, catppuccinLatte, catppuccinMocha, defaultDark, defaultLight, dracula, everforestDark, everforestLight, githubDark, githubLight, glassyDark, gruvboxDark, gruvboxLight, highContrastDark, highContrastLight, materialDark, materialLight, monokai, nightOwl, nord, oneDark, rosePine, rosePineDawn, rosePineMoon, shadesOfPurple, solarizedDark, solarizedLight, tokyoNight, vscodeDarkPlus, vscodeLightPlus, zenburn

Linked stylesheets Copy Chapter

For larger visual overrides (glass effects, layout tweaks, etc.), point stylesheets at CSS files inside the Themes folder:

{
  "mode": "dark",
  "extends": "defaultDark",
  "stylesheets": ["overrides/my-theme.css"]
}

Themes/
  my-theme.json
  overrides/
    my-theme.css

Notes:

• Feishin watches JSON theme files for automatic reload. After editing only a CSS file, click Reload in Settings (or touch/save the .json file) so stylesheets are re-read.
• Empty or unreadable stylesheet paths are skipped with a console warning.

Examples Copy Chapter

Minimal accent-only dark theme Copy Section

accent-blue.json:

{
  "mode": "dark",
  "extends": "defaultDark",
  "colors": {
    "primary": "rgb(80, 160, 255)"
  }
}

Full light palette Copy Section

paper-light.json:

{
  "mode": "light",
  "colors": {
    "background": "rgb(250, 249, 246)",
    "background-alternate": "rgb(242, 240, 235)",
    "surface": "rgb(255, 255, 255)",
    "surface-foreground": "rgb(40, 40, 40)",
    "foreground": "rgb(30, 30, 30)",
    "foreground-muted": "rgb(110, 110, 110)",
    "primary": "rgb(180, 83, 9)",
    "black": "rgb(0, 0, 0)",
    "white": "rgb(255, 255, 255)",
    "state-error": "rgb(185, 28, 28)",
    "state-info": "rgb(37, 99, 235)",
    "state-success": "rgb(22, 163, 74)",
    "state-warning": "rgb(217, 119, 6)"
  },
  "app": {
    "overlay-header": "linear-gradient(rgb(250 249 246 / 50%) 0%, rgb(250 249 246 / 80%))",
    "scrollbar-handle-background": "rgba(120, 120, 120, 30%)"
  },
  "mantineOverride": {
    "primaryShade": {
      "light": 5
    }
  }
}

Theme that extends another custom theme Copy Section

nord-soft.json:

{
  "mode": "dark",
  "extends": "nord",
  "colors": {
    "background": "rgb(36, 41, 51)",
    "surface": "rgb(46, 52, 64)"
  }
}

Troubleshooting Copy Chapter

Broken themes still appear in Settings with their error message so you can fix them without digging through logs.

ENV SETTINGS (`docs/ENV_SETTINGS.md`) Copy Section

Environment variables for settings (web / Docker)

These variables override app settings on first run when no persisted settings exist. They are injected via settings.js (from settings.js.template) and only apply to the web build.

Format: All values are strings; booleans use true/false, numbers are numeric strings. Leave unset or empty to use the default.

General Copy Chapter

Playback Copy Chapter

Discord Copy Chapter

Lyrics Copy Chapter

Lyrics display Copy Chapter

Applies to the default lyrics display profile (lyricsDisplay.default).

Auto DJ Copy Chapter

CSS Copy Chapter

Font Copy Chapter

Agents Api (`docs/agents/api.md`) Copy Section

API

Server library data layer (Jellyfin / Navidrome / Subsonic). Read when adding or changing fetches, mutations, normalize, or query keys.

Layers Copy Chapter

React Query client: src/renderer/lib/react-query.ts.

Add a query Copy Chapter

1. Prefer extending the matching src/renderer/features/<feature>/api/*-api.ts (or add one beside siblings).
2. Call api.controller.<method>(…) — do not invent one-off axios/fetch in UI.
3. Keys from queryKeys — keep serverId first; invalidate the same keys from mutations.
4. UI uses useQuery(<feature>Queries.…) like nearby features.

import { api } from '/@/renderer/api';
import { queryKeys } from '/@/renderer/api/query-keys';

Normalize / new endpoint Copy Chapter

• Wire through the per-backend controller, not the feature component.
• Parse/validate with shared types; map with jfNormalize / ndNormalize / ssNormalize in src/shared/api/....
• Keep domain types stable for features; backend quirks stay in normalize/controller.

Upstream OpenAPI (last resort) Copy Chapter

Do not fetch these for ordinary API work. Prefer in-repo controllers, src/shared/api/*-types.ts, normalize, and existing call sites.

Fetch only when an endpoint, field, or auth detail is missing or contradictory in-repo and you cannot finish without the vendor contract:

When you must open one: pull only the path/operation/schema (or Go handler file) you need, not the whole spec or folder into context. Then encode the result in our types/normalize/controller — do not leave features depending on the remote source.

Don’t Copy Chapter

• Bypass api.controller from feature UI.
• Put Jellyfin/Navidrome/Subsonic response shapes in React components — normalize first.
• Hand-roll query key arrays when query-keys.ts already has a factory.
• Open upstream OpenAPI “just in case” or to explore — in-repo code first.

Agents Architecture (`docs/agents/architecture.md`) Copy Section

Architecture

Process and build boundaries. Read when work crosses main / preload / renderer / remote / web, or touches window.api / IPC.

Layout Copy Chapter

Builds Copy Chapter

Desktop-only surfaces (custom themes, mpv, MPRIS, many window.api.* modules) must gate on isElectron() and null-check window.api. See docs/CUSTOM_THEMES.md for themes.

Aliases Copy Chapter

Import boundaries (culture — not ESLint) Copy Chapter

• main → /@/main, /@/shared only.
• preload → preload + shared (plus the existing relative main env exception).
• shared → no /@/renderer, /@/main, /@/remote, /@/preload.
• renderer → /@/renderer, /@/shared, /@/i18n — not /@/main.
• remote → /@/remote, /@/shared; may reuse selected /@/renderer utilities (theme, logger) — do not grow that into a full renderer dependency.

Electron capabilities from the UI: window.api.* (typed in src/preload/index.d.ts), never direct main imports.

Related Copy Chapter

• UI / CSS / i18n patterns: docs/agents/frontend.md
• Server library API: docs/agents/api.md
• Logging: docs/agents/logging.md

Agents Commits (`docs/agents/commits.md`) Copy Section

Commits

Conventional Commits for history that can feed release notes and scoped changelogs. Enforced by commitlint (commitlint.config.mjs) and the Test workflow.

Automatic Weblate translation commits (subject Translated using Weblate) are skipped via the config's ignores list, since they do not follow the conventional format.

Format Copy Chapter

type(scope): subject

[optional body]

[optional footer]

Examples:

• feat(player): add MPV reload control
• fix(window): restore minimized window
• chore(deps): bump electron
• feat!: drop legacy auth path or footer BREAKING CHANGE: …

Types Copy Chapter

Use the conventional set (from @commitlint/config-conventional):

feat · fix · perf · refactor · docs · style · test · build · ci · chore · revert

Prefer feat / fix / perf for user-facing notes; keep chore/build/ci out of highlight sections when generating notes.

Scopes Copy Chapter

Scope = product area a release-note reader cares about — not Electron process (main / preload) and not “settings” (scope the feature the setting belongs to).

Scope is optional. When present, it must be one of (see commitlint.config.mjs — source of truth):

Product Copy Section

Meta Copy Section

Add a new scope in commitlint.config.mjs first, then document it here.

Subject Copy Chapter

• Imperative, present tense (“add”, not “added”)
• No trailing period
• Do not put agent attribution in the message (see AGENTS.md)

Local check Copy Chapter

pnpm exec commitlint --last
# or
echo "feat(player): your subject" | pnpm exec commitlint

CI runs commitlint over the PR or push range (see .github/workflows/test.yml).

Agents Domain (`docs/agents/domain.md`) Copy Section

Domain Docs

How the engineering skills should consume this repo's domain documentation when exploring the codebase.

Before exploring, read these Copy Chapter

• CONTEXT.md at the repo root, or
• CONTEXT-MAP.md at the repo root if it exists — it points at one CONTEXT.md per context. Read each one relevant to the topic.
• docs/adr/ — read ADRs that touch the area you're about to work in. In multi-context repos, also check src/<context>/docs/adr/ for context-scoped decisions.

If any of these files don't exist, proceed silently. Don't flag their absence; don't suggest creating them upfront. The /domain-modeling skill (reached via /grill-with-docs and /improve-codebase-architecture) creates them lazily when terms or decisions actually get resolved.

File structure Copy Chapter

Single-context repo (most repos):

/
├── CONTEXT.md
├── docs/adr/
│   ├── 0001-event-sourced-orders.md
│   └── 0002-postgres-for-write-model.md
└── src/

Multi-context repo (presence of CONTEXT-MAP.md at the root):

/
├── CONTEXT-MAP.md
├── docs/adr/                          ← system-wide decisions
└── src/
    ├── ordering/
    │   ├── CONTEXT.md
    │   └── docs/adr/                  ← context-specific decisions
    └── billing/
        ├── CONTEXT.md
        └── docs/adr/

Use the glossary's vocabulary Copy Chapter

When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in CONTEXT.md. Don't drift to synonyms the glossary explicitly avoids.

If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for /domain-modeling).

Flag ADR conflicts Copy Chapter

If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:

Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…

Agents Frontend (`docs/agents/frontend.md`) Copy Section

Frontend

Conventions for UI in the renderer: imports, composition, CSS Modules, theme tokens, i18n, icons, toasts, modals, Zustand state.

Imports Copy Chapter

Deep imports only — no component barrels. Example: /@/shared/components/button/button.

Mantine: feature UI imports wrappers under /@/shared/components and /@/shared/hooks, not @mantine/core. Open docs/agents/mantine.md only when debugging those wrappers or adding a new one.

Exception: @mantine/modals (openModal, openContextModal, closeModal, …) is the usual imperative API in features — match nearby callers.

Composition ladder Copy Chapter

1. Shared wrapper — /@/shared/components/... (design-system primitive).
2. Feature-shared — src/renderer/features/shared/components/ (domain chrome reused across features).
3. Feature-local — src/renderer/features/<feature>/components/ (one feature only).

Layout primitives: Box, Flex, Stack, Group, Grid from /@/shared/components/.... Prefer them over one-off layout divs when composing screens.

Put a new primitive in shared only when it is generic design-system; otherwise keep it feature-local or feature-shared.

CSS Modules Copy Chapter

• Co-locate component-name.module.css next to component-name.tsx (kebab folder + file names).
• Class names in CSS are kebab-case; Vite maps them to camelCase on styles (.player-button → styles.playerButton).
• Compose classes with clsx. On Mantine wrappers, pass module classes through the Styles API (classNames={{ root: styles.root, ... }}).
• Colors, spacing, chrome: prefer var(--theme-…) / var(--theme-colors-…) over raw hex or --mantine-* so custom themes keep working.
• PostCSS: @mixin light-root / dark-root where light/dark splits belong; lighten / darken / alpha are allowed by stylelint.

Global CSS is rare (src/shared/styles/global.css and third-party/theme overrides) — don’t add feature styles there.

Theme tokens Copy Chapter

User-loadable desktop theme JSON (colors / app / mantineOverride / stylesheets): docs/CUSTOM_THEMES.md — only when changing that surface.

i18n, icons, toasts, modals Copy Chapter

• Copy: useTranslation / t; keys in src/i18n/locales/en.json (common.*, form.*, error.*, page.*, entity.*, …). Add keys next to existing namespaces.
• Icons: `` from /@/shared/components/icon/icon. New glyphs go on the AppIcon map there — don’t import react-icons / Lucide directly in features.
• Toasts: toast.success|error|info|warn({ message, title? }) from /@/shared/components/toast/toast.
• Modals: open/close via @mantine/modals; render with shared Modal / ModalButton / provider patterns already in tree. Controlled visibility often uses /@/shared/hooks/use-disclosure.

State (Zustand) Copy Chapter

Patterns to match nearby stores:

• Prefer createWithEqualityFn from zustand/traditional.
• Persisted app stores often use persist + immer (+ devtools / subscribeWithSelector when siblings do).
• Multi-field reads: useShallow or the store’s exported selector hooks; see src/renderer/lib/zustand.ts (createSelectors) where used.
• Don’t duplicate player/auth/settings into a new global store — extend the existing one or keep a feature-local store.

Agents Issue Tracker (`docs/agents/issue-tracker.md`) Copy Section

Issue tracker: Local Markdown

Issues and specs for this repo live as markdown files in .scratch/.

Conventions Copy Chapter

• One feature per directory: .scratch/<feature-slug>/
• The spec is .scratch/<feature-slug>/spec.md
• Implementation issues are one file per ticket at .scratch/<feature-slug>/issues/<NN>-<slug>.md, numbered from 01 — never a single combined tickets file
• Triage state is recorded as a Status: line near the top of each issue file (see triage-labels.md for the role strings)
• Comments and conversation history append to the bottom of the file under a ## Comments heading

When a skill says "publish to the issue tracker" Copy Chapter

Create a new file under .scratch/<feature-slug>/ (creating the directory if needed).

When a skill says "fetch the relevant ticket" Copy Chapter

Read the file at the referenced path. The user will normally pass the path or the issue number directly.

Wayfinding operations Copy Chapter

Used by /wayfinder. The map is a file with one child file per ticket.

• Map: .scratch/<effort>/map.md — the Notes / Decisions-so-far / Fog body.
• Child ticket: .scratch/<effort>/issues/NN-<slug>.md, numbered from 01, with the question in the body. A Type: line records the ticket type (research/prototype/grilling/task); a Status: line records claimed/resolved.
• Blocking: a Blocked by: NN, NN line near the top. A ticket is unblocked when every file it lists is resolved.
• Frontier: scan .scratch/<effort>/issues/ for files that are open, unblocked, and unclaimed; first by number wins.
• Claim: set Status: claimed and save before any work.
• Resolve: append the answer under an ## Answer heading, set Status: resolved, then append a context pointer (gist + link) to the map's Decisions-so-far in map.md.

Agents Logging (`docs/agents/logging.md`) Copy Section

Logging

Use the process logger for diagnosable failures and meaningful state transitions. Skip noise (render churn, routine success paths, prop dumps).

Which logger Copy Chapter

Do not use bare console.* for new logging in app code — the loggers format, debounce (renderer), forward to electron-log / files, and respect the configured level.

When to log Copy Chapter

Add a log when the code path is hard to reconstruct from the UI alone:

• Failures and catch blocks that would otherwise vanish (error / warn)
• Engine / connection / auth / playback transitions that change behavior (info or debug)
• Fallback paths (e.g. playback engine fell back to web) (warn / info)

Skip: hot loops, every React render, expected empty states, data the user already sees as a toast unless the log adds process-side detail.

Levels Copy Chapter

Configured threshold is debug | info (LogLevel in /@/shared/logger/types). Message severity is debug | info | warn | error.

Message shape Copy Chapter

• First arg: short human message string.
• Optional second arg (renderer): structured meta object — prefer { error, … } over string-concatenating errors.
• No secrets: passwords, tokens, full auth headers, or anything sanitize-for-diagnostics would strip from exports. Main diagnostic packaging uses /@/shared/utils/sanitize-for-diagnostics — keep ad-hoc logs equally clean.

Agents Mantine (`docs/agents/mantine.md`) Copy Section

Mantine

Feishin wraps the Mantine components and hooks it uses under src/shared/components/ and src/shared/hooks/. Feature code imports those wrappers (/@/shared/...), not @mantine/*.

Default (most UI work) Copy Chapter

1. Import from /@/shared/components/... and /@/shared/hooks/....
2. Match callers and props already in use — the wrapper is the API.
3. Do not fetch Mantine LLM docs, MCP, or upstream skills.

@mantine/* belongs only inside the wrapper modules (and a few shared theme/type utilities).

When to open upstream docs Copy Chapter

Reach for live Mantine docs only if you are:

• Debugging a wrapper — behavior/bug lives in src/shared/components/* or src/shared/hooks/* (or adjacent shared Mantine adapters), or
• Adding a new wrapped component or hook — introducing a new /@/shared/... re-export that did not exist.

Then:

1. Confirm Mantine v9 in package.json.
2. Prefer Mantine MCP if configured (search_docs, get_item_doc, get_item_props); else https://mantine.dev/llms.txt → the linked per-page .md for that item only.
3. Do not vendor llms-full.txt.

Skill branches (new wrappers only) Copy Chapter

Install from mantinedev/skills only when scaffolding a matching new wrapper:

Repo theme notes Copy Chapter

User-loadable desktop theme JSON and mantineOverride: docs/CUSTOM_THEMES.md — only when changing that behavior or theme-object shape.

Agents Triage Labels (`docs/agents/triage-labels.md`) Copy Section

Triage Labels

The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.

When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.

Edit the right-hand column to match whatever vocabulary you actually use.

--- METRICS ---

• Files Extracted: 16
• Estimated Token Budget: ~15346 tokens
• Canonical Reference: https://codewiki.google/github.com/jeffvli/feishin