mirror of https://github.com/ksyasuda/SubMiner.git synced 2026-05-29 12:55:16 -07:00

Files

T

docs: reconcile docs-site with current config schema and defaults

- sidebar: migrate flat props to css object (font-family, color, bg, custom vars)
- frequencyDictionary.topX default: 1000 → 10000
- text-shadow default: updated to outline-style multi-shadow
- anki: reset ai model/prompt, imageMaxWidth/Height, animatedMaxHeight to 0; isLapis defaults
- troubleshooting: log default warn (not info), css["font-size"] usage
- shortcuts: add W markWatchedKey; clarify keybindings vs built-in overlay actions
- websocket: clarify all services off by default, fix enabled semantics
- usage: --anilist → --anilist-setup
- AGENTS.md: add Docs Upkeep trigger map, clarify CLAUDE.md symlink, expand PR notes

2026-05-28 19:21:58 -07:00

4.5 KiB

Raw Blame History

AGENTS.MD

Internal Docs

Start here, then leave this file.

Internal system of record: docs/README.md
Architecture map: docs/architecture/README.md
Workflow map: docs/workflow/README.md
Verification lanes: docs/workflow/verification.md
Knowledge-base rules: docs/knowledge-base/README.md
Release guide: docs/RELEASING.md

docs-site/ is user-facing. Do not treat it as the canonical internal source of truth.

CLAUDE.md is a symlink to this file — there is one project instruction file, not two.

Quick Start

Init workspace: git submodule update --init --recursive
Install deps: make deps or bun install plus (cd vendor/texthooker-ui && bun install --frozen-lockfile)
Fast dev loop: make dev-watch
Full local run: bun run dev
Verbose Electron debug: electron . --start --dev --log-level debug

Build / Test

Runtime/package manager: Bun (packageManager: bun@1.3.5)
Default handoff gate: bun run typecheck bun run test:fast bun run test:env bun run build bun run test:smoke:dist
If docs-site/ changed, also run: bun run docs:test bun run docs:build
Prefer make pretty and bun run format:check:src

Change-Specific Checks

Config/schema/defaults: bun run test:config; if template/defaults changed, bun run generate:config-example
Launcher/plugin: bun run test:launcher or bun run test:env
Runtime-compat / dist-sensitive: bun run test:runtime:compat
Docs-only: bun run docs:test, then bun run docs:build

Docs Upkeep

Docs ship with the change, not after. If a change alters behavior, defaults, flags, shortcuts, ports, or APIs, update the matching docs in the same PR. Touching code without reconciling its docs is an incomplete change.
Source of truth for config defaults is the generated config.example.jsonc. Never write a default value into prose you didn't read from it — and don't restate the same default across multiple docs; cite/link to one place so there's a single thing to update.
Trigger map (touch left → update right):
- src/config/definitions/** (schema/defaults/template) → bun run generate:config-example, then reconcile docs-site/configuration.md + any feature doc that cites that default
- shortcuts/keybindings (shortcuts.*, keybindings, stats.*Key, subtitleSidebar.toggleKey, controller bindings) → docs-site/shortcuts.md
- CLI flags/subcommands (src/cli/args.ts, launcher/**) → docs-site/usage.md + relevant integration doc
- feature behavior (anki / jellyfin / jimaku / anilist / youtube / immersion / stats / websocket / sidebar / character-dictionary / annotations) → matching docs-site/<feature>.md
- architecture / IPC / workflow / internal process → internal docs/ (system of record)
- feature set / requirements / install flow → README.md
Removing or renaming a config key: grep docs-site/ and docs/ for the old key and any value it documented; legacy/hidden keys (LEGACY_HIDDEN_CONFIG_PATHS) should not appear in user docs as current settings.
Verify after doc edits: bun run verify:config-example (if config touched), bun run docs:test, bun run docs:build.

Sensitive Files

Launcher source of truth: launcher/*.ts
Generated launcher artifact: dist/launcher/subminer; never hand-edit it
Repo-root ./subminer is stale; do not revive it
bun run build rebuilds bundled Yomitan from vendor/subminer-yomitan
Do not change signing/packaging identifiers unless the task explicitly requires it

Release / PR Notes

User-visible PRs need one fragment in changes/*.md — format and rules in changes/README.md (type + area keys required; apply the skip-changelog label to opt out)
User-visible docs changes get a type: docs fragment
CI enforces bun run changelog:lint and bun run changelog:pr-check
PR review helpers:
- gh pr view --json number,title,url --jq '"PR #\\(.number): \\(.title)\\n\\(.url)"'
- gh api repos/:owner/:repo/pulls/<num>/comments --paginate

Runtime Notes

Use Codex background for long jobs; tmux only when persistence/interaction is required
CI red: gh run list/view, rerun, fix, repeat until green
TypeScript: keep files small; follow existing patterns
Only Swift is the scripts/get-mpv-window-macos.swift helper (macOS mpv window detection); validate via bun test scripts/get-mpv-window-macos.test.ts

4.5 KiB Raw Blame History