broader-vids 0.1.4 → 0.1.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,19 @@
1
+ {
2
+ "name": "broader-vids",
3
+ "description": "Broader Vids plugin for Claude Code",
4
+ "owner": {
5
+ "name": "Broader Vids contributors"
6
+ },
7
+ "plugins": [
8
+ {
9
+ "name": "broader-vids",
10
+ "source": {
11
+ "source": "npm",
12
+ "package": "broader-vids",
13
+ "version": "latest",
14
+ "registry": "https://registry.npmjs.org"
15
+ },
16
+ "description": "Curated YouTube and Bilibili recommendations with local evidence and feedback."
17
+ }
18
+ ]
19
+ }
@@ -0,0 +1,9 @@
1
+ {
2
+ "name": "broader-vids",
3
+ "version": "0.1.7",
4
+ "description": "Curated YouTube and Bilibili recommendations for Claude Code",
5
+ "author": {
6
+ "name": "Broader Vids contributors"
7
+ },
8
+ "license": "MIT"
9
+ }
package/README.md CHANGED
@@ -1,33 +1,31 @@
1
1
  # Broader Vids
2
2
 
3
- Broader Vids provides an alternative recommendation algorithm for YouTube and Bilibili.
4
- It combines your interests, exploration of unfamiliar topics, video quality, and feedback.
3
+ Broader Vids provides an alternative recommendation algorithm for YouTube and Bilibili. It combines your interests, exploration of unfamiliar topics, and video quality.
5
4
 
6
- **The plugin learns from your dashboard ratings and calibrates its internal scoring model weights to your preferences.**
7
- You can manually exclude creators and tags from future rounds.
8
- Each complete round recommends ten videos per selected platform.
5
+ **Your dashboard ratings calibrate the plugin’s internal scoring models to your preferences.**
6
+ You can exclude creators and tags from future rounds. Each complete round recommends ten videos per selected platform.
9
7
 
10
- The plugin runs locally through Codex CLI or Codex in the ChatGPT desktop app.
11
- Recommendations appear in chat. A local dashboard provides ratings, exclusions, and preferences.
8
+ The plugin runs locally through Codex CLI or Codex in the ChatGPT desktop app. Recommendations appear in chat. A local dashboard manages ratings, exclusions, and preferences. Claude Code packaging is experimental. Static package checks and launcher fixtures cover it. No Claude host acceptance test has been performed.
9
+
10
+ ## Requirements
11
+
12
+ Use Windows, PowerShell, Node.js 20 or later with npm, UV, and Codex CLI signed in with ChatGPT. Installation and recommendations require internet access.
12
13
 
13
14
  ## Install the plugin
14
15
 
15
- Requirements: Windows, PowerShell, Node.js 20 or later with npm, UV, and Codex CLI authenticated with ChatGPT.
16
- Installation and recommendations require internet access.
17
- Choose one installation method. Neither method requires a checkout, build, or local folder selection.
16
+ Choose one of these three remote installation routes. You do not need a repository checkout or a local build.
18
17
 
19
- ### From GitHub in the ChatGPT desktop app
18
+ ### ChatGPT desktop app
20
19
 
21
20
  1. Open the plugin marketplace controls in Codex.
22
- 2. Select **Add marketplace** and its repository or Git URL option.
21
+ 2. Select **Add marketplace** and choose its repository or Git URL option.
23
22
  3. Enter `https://github.com/antidemosthenes/broader-vids`.
24
- 4. Add or sync the marketplace.
25
- 5. Select **Broader Vids** and install it.
26
- 6. Start a new conversation.
23
+ 4. Add or sync the marketplace. Then install **Broader Vids**.
24
+ 5. Start a new conversation.
27
25
 
28
- The GitHub repository supplies the catalog. Its plugin entry downloads the complete package from npm.
26
+ The GitHub repository provides the catalog. The catalog downloads the plugin package from npm.
29
27
 
30
- ### From GitHub in Codex CLI
28
+ ### Codex CLI from GitHub
31
29
 
32
30
  Run these commands in PowerShell:
33
31
 
@@ -38,7 +36,7 @@ codex plugin add broader-vids@broader-vids
38
36
 
39
37
  Start a new conversation after installation.
40
38
 
41
- ### From npm
39
+ ### npm
42
40
 
43
41
  Run this command in PowerShell:
44
42
 
@@ -46,88 +44,47 @@ Run this command in PowerShell:
46
44
  npx --yes broader-vids@latest plugin install
47
45
  ```
48
46
 
49
- This command registers an npm-backed marketplace and installs the plugin through Codex.
50
- It installs the skills and dashboard, not only the terminal launcher.
51
- It does not require the GitHub catalog.
52
- Restart the desktop app or start a new Codex CLI conversation after installation.
47
+ This command registers an npm backed marketplace and installs the plugin skills and dashboard. Start a new conversation after installation.
53
48
 
54
- The app's Add marketplace field accepts repository URLs, not npm package names.
55
- Use the npm command above for that installation route.
56
- See the [official packaging guide](https://developers.openai.com/plugins/build/plugins) for supported plugin sources.
49
+ The desktop app accepts repository URLs in **Add marketplace**. Use the npm command for npm installation. See the [plugin packaging guide](https://developers.openai.com/plugins/build/plugins) for supported sources.
57
50
 
58
- ## Update the plugin
59
51
 
60
- For a GitHub installation, refresh its marketplace and install the current release:
52
+ ### Experimental Claude Code path
61
53
 
62
- ```powershell
63
- codex plugin marketplace upgrade broader-vids
64
- codex plugin add broader-vids@broader-vids
65
- ```
66
-
67
- For an npm installation, repeat the installation command:
54
+ Claude Code support is experimental. Static package checks and launcher fixtures cover it. No host acceptance test has been performed. These installation steps require a future npm release that contains the Claude files. See the [Claude Code installation notes](docs/REFERENCE.md#experimental-claude-code-installation).
68
55
 
69
- ```powershell
70
- npx --yes broader-vids@latest plugin install
71
- ```
72
-
73
- In the desktop app, refresh the marketplace and select the current Broader Vids release.
74
- If the app provides no update action, use the terminal commands for your installation method.
75
- Start a new conversation and run setup after an update.
76
- Setup installs the matching engine and preserves your saved profile.
77
- Finish active recommendations and close the dashboard before updating.
78
-
79
- ## Set up and request recommendations
56
+ ## Update the plugin
80
57
 
81
- Use this procedure for either platform or both:
58
+ Follow [Update an installed plugin](docs/REFERENCE.md#update-an-installed-plugin) for update steps.
82
59
 
83
- 1. Start a new conversation. Invoke the setup skill from the table below.
84
- 2. Choose YouTube, Bilibili, or both.
85
- 3. Choose calibrated starter preferences, enter your interests, or import a preference file.
86
- 4. Complete the dependency and access checks. Setup gives repair steps for required failures.
87
- 5. Invoke the recommendation skill. Review the links and summaries in chat.
88
- 6. Open the dashboard to mark watched videos and rate their topic, subject, depth, and quality.
89
- 7. Request another round when you want more recommendations.
60
+ ## Set up and use Broader Vids
90
61
 
91
- Existing profiles can keep their saved preferences during setup.
92
- Saving ratings updates the local preference and quality models.
93
- Their learned weights affect screening and final ranking in later rounds.
94
- Creator and tag exclusions apply to the next new round.
95
- The dashboard **Preferences** page lets you edit interests and import or export preferences and learned weights.
96
- Before a new round, incomplete feedback prompts you to open the dashboard or continue.
62
+ Start a new conversation and invoke the setup skill. Choose YouTube, Bilibili, or both. Then choose starter preferences, enter interests, or import a preference file. Setup checks dependencies and access. It gives repair steps when a required check fails.
97
63
 
98
- Both platforms support manual creator and tag exclusions.
99
- YouTube tag rules match available creator-supplied keyword tags, which differ from visible hashtags.
100
- Bilibili rules match its video tags.
101
- Search queries use English for YouTube and Simplified Chinese for Bilibili.
64
+ Invoke the recommendation skill to request a round. Review recommendations in chat. Open the dashboard to mark videos as watched and rate topic, subject, depth, and quality. Ratings update local preference and quality models. Their learned weights affect later rounds. Creator and tag exclusions apply to the next new round.
102
65
 
103
66
  | Action | Skill command | Purpose |
104
67
  | --- | --- | --- |
105
- | Setup | `$broader-vids-setup` | Choose platforms and preferences, install required tools, and check access. |
106
- | Recommendations | `$broader-vids` | Request a round for your saved platforms. |
107
- | Dashboard | `$broader-vids-dashboard` | Rate videos, manage exclusions, and edit preferences. |
108
- | Reset | `$broader-vids-reset` | Preview removal of preferences, weights, ratings, and histories while keeping tools and sign-in. |
109
- | Clean | `$broader-vids-clean` | Preview removal of all managed local data, including tools and sign-in. |
110
-
111
- Use the command names shown by your host's skill menu.
112
- Some hosts add the plugin namespace, such as `$broader-vids:broader-vids-dashboard`.
113
- You can also ask: “Use Broader Vids to recommend videos” or “Use Broader Vids to open my dashboard.”
68
+ | Setup | `$broader-vids-setup` | Choose platforms and preferences. Install tools and check access. |
69
+ | Recommendations | `$broader-vids` | Request videos for your saved platforms. |
70
+ | Dashboard | `$broader-vids-dashboard` | Rate videos. Manage exclusions and preferences. |
71
+ | Reset | `$broader-vids-reset` | Preview removal of preferences, weights, ratings, and histories. Keep tools and sign-in. |
72
+ | Clean | `$broader-vids-clean` | Preview removal of all managed data, including tools and sign-in. |
73
+
74
+ Use the skill commands shown in your host's skill menu. Some hosts add the plugin namespace, such as `$broader-vids:broader-vids-dashboard`. You can also ask Broader Vids to recommend videos or open the dashboard.
75
+
114
76
  Reset and Clean require confirmation. Neither action uninstalls the plugin.
115
77
 
116
78
  ## Bilibili access and exclusions
117
79
 
118
- Bilibili requires manual sign-in for full-video evidence.
119
- Setup opens a separate browser window.
120
- Keep that window open after sign-in and return to chat to report completion.
121
- The plugin verifies the session and closes the window.
122
- You can switch accounts later from the dashboard.
80
+ Bilibili needs manual sign-in for full video evidence. Setup opens a separate browser. Keep it open after sign-in, then report completion in chat. Broader Vids checks the session and closes the browser. You can switch accounts from the dashboard.
81
+
82
+ Broader Vids imports your account blacklist after sign-in checks and before new rounds. Imported creator exclusions combine with your manual exclusions. A failed sync keeps the last complete copy. Use **Sync blacklist** in the dashboard to retry.
83
+
84
+ ## Architecture and guides
123
85
 
124
- Bilibili imports your account blacklist after verified sign-in and before new rounds.
125
- Imported creator exclusions combine with your manual exclusions.
126
- A failed sync preserves the last complete copy.
127
- Use **Sync blacklist** in the dashboard to retry.
86
+ The Node launcher manages a versioned local Python engine, which stores profile data locally and serves the dashboard.
128
87
 
129
- See the [workflow](docs/WORKFLOW.md) for recommendation steps and the [scoring guide](docs/SCORING.md) for ranking and learning.
130
- The [reference](docs/REFERENCE.md) covers terminal commands, troubleshooting, local builds, and maintenance.
131
- The [architecture](docs/ARCHITECTURE.md) describes the launcher, engine, and local storage.
88
+ Read the [workflow](docs/WORKFLOW.md) for recommendation steps. Read the [scoring guide](docs/SCORING.md) for ranking and learning. The [reference](docs/REFERENCE.md) covers commands, troubleshooting, updates, and maintenance. The [architecture guide](docs/ARCHITECTURE.md) describes the launcher, engine, and local storage.
132
89
 
133
90
  License: [MIT](LICENSE).
@@ -91,16 +91,59 @@ function selectRoot(directory, env = process.env) {
91
91
  }
92
92
  }
93
93
 
94
+ function parseHost(args) {
95
+ let host = "codex";
96
+ let explicit = false;
97
+ const values = [];
98
+ for (let index = 0; index < args.length; index += 1) {
99
+ let selected;
100
+ if (args[index] === "--host") {
101
+ selected = args[++index];
102
+ if (!selected || selected.startsWith("--"))
103
+ throw new Error("--host requires codex or claude.");
104
+ } else if (args[index].startsWith("--host=")) {
105
+ selected = args[index].slice("--host=".length);
106
+ } else {
107
+ values.push(args[index]);
108
+ continue;
109
+ }
110
+ if (!["codex", "claude"].includes(selected))
111
+ throw new Error("--host must be codex or claude.");
112
+ if (explicit && host !== selected)
113
+ throw new Error("Use one host value per command.");
114
+ host = selected;
115
+ explicit = true;
116
+ }
117
+ return { args: values, host, explicit };
118
+ }
119
+
94
120
  function commandIndex(args) {
95
121
  let index = 0;
96
122
  while (index < args.length) {
97
123
  if (args[index] === "--data-dir") index += 2;
98
124
  else if (args[index].startsWith("--data-dir=")) index += 1;
125
+ else if (args[index] === "--host") index += 2;
126
+ else if (args[index].startsWith("--host=")) index += 1;
99
127
  else return index;
100
128
  }
101
129
  return -1;
102
130
  }
103
131
 
132
+ function validateSetupArguments(args, index) {
133
+ for (let item = index + 1; item < args.length; item += 1) {
134
+ const value = args[item];
135
+ if (value === "--asr" || value === "--evidence") continue;
136
+ if (value === "--data-dir") {
137
+ item += 1;
138
+ continue;
139
+ }
140
+ if (value.startsWith("--data-dir=")) continue;
141
+ throw new Error(
142
+ "Use setup with optional --evidence, --asr, and --data-dir PATH.",
143
+ );
144
+ }
145
+ }
146
+
104
147
  function invoke(command, args) {
105
148
  const result = spawnSync(command, args, {
106
149
  stdio: "inherit",
@@ -225,6 +268,9 @@ function recordRuntimeBuild(runtime, digest, packageRoot, groups) {
225
268
  }
226
269
 
227
270
  function main(args = process.argv.slice(2)) {
271
+ const selectedHost = parseHost(args);
272
+ args = selectedHost.args;
273
+ const host = selectedHost.host;
228
274
  const packageRoot = path.resolve(__dirname, "..");
229
275
  const manifest = JSON.parse(
230
276
  fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"),
@@ -236,21 +282,37 @@ function main(args = process.argv.slice(2)) {
236
282
  args.length === 2 &&
237
283
  ["--help", "-h"].includes(args[1])
238
284
  ) {
239
- console.log("Usage: broader-vids plugin install");
285
+ console.log(
286
+ "Usage: broader-vids plugin install [--host codex|claude] or broader-vids plugin update --host claude",
287
+ );
240
288
  return;
241
289
  }
242
- if (index !== 0 || args.length !== 2 || args[1] !== "install")
290
+ if (
291
+ index !== 0 ||
292
+ args.length !== 2 ||
293
+ !["install", "update"].includes(args[1])
294
+ )
243
295
  throw new Error(
244
- "Use broader-vids plugin install without profile arguments.",
296
+ "Use broader-vids plugin install, or plugin update --host claude, without profile arguments.",
245
297
  );
246
298
  const result = require("./plugin-install.cjs").installPlugin(
247
299
  manifest.version,
248
300
  invoke,
301
+ process.env,
302
+ host,
303
+ args[1],
249
304
  );
250
305
  console.log(JSON.stringify(result, null, 2));
251
- console.log(
252
- "Start a new Codex conversation and invoke the Broader Vids setup skill.",
253
- );
306
+ if (args[1] === "update")
307
+ console.log(
308
+ "Start a new Claude Code session and run setup to refresh the matching runtime.",
309
+ );
310
+ else
311
+ console.log(
312
+ host === "claude"
313
+ ? "Start a new Claude Code session and invoke the Broader Vids setup skill."
314
+ : "Start a new Codex conversation and invoke the Broader Vids setup skill.",
315
+ );
254
316
  return;
255
317
  }
256
318
  if (args[index] === "data") {
@@ -306,7 +368,8 @@ function main(args = process.argv.slice(2)) {
306
368
  if (result.status === "partial") process.exitCode = 2;
307
369
  return;
308
370
  }
309
- if (args[commandIndex(args)] === "setup") {
371
+ if (args[index] === "setup") {
372
+ validateSetupArguments(args, index);
310
373
  const sourceWheel = bundledWheel(packageRoot, manifest.version);
311
374
  const wheelRoot = path.dirname(sourceWheel);
312
375
  return withSetup(root, () => {
@@ -424,12 +487,17 @@ function main(args = process.argv.slice(2)) {
424
487
  error.data_directory = root;
425
488
  throw error;
426
489
  }
490
+ const engineArgs = [
491
+ ...args.slice(0, index),
492
+ ...(selectedHost.explicit ? ["--host", host] : []),
493
+ ...args.slice(index),
494
+ ];
427
495
  return invoke(executable, [
428
496
  "-m",
429
497
  "broader_vids",
430
498
  "--data-dir",
431
499
  root,
432
- ...args,
500
+ ...engineArgs,
433
501
  ]);
434
502
  });
435
503
  }
@@ -438,6 +506,7 @@ module.exports = {
438
506
  defaultRoot,
439
507
  dataRoot,
440
508
  commandIndex,
509
+ parseHost,
441
510
  cacheWheel,
442
511
  selectedRoot,
443
512
  selectRoot,
@@ -28,20 +28,36 @@ function resolveCodex(env = process.env, platform = process.platform) {
28
28
  );
29
29
  }
30
30
 
31
- function installPlugin(version, run, env = process.env) {
32
- const [command, prefix] = resolveCodex(env);
33
- const home = path.resolve(
34
- env.CODEX_HOME || path.join(os.homedir(), ".codex"),
31
+ function resolveClaude(env = process.env, platform = process.platform) {
32
+ if (platform !== "win32") return ["claude", []];
33
+ const directories = (env.PATH || env.Path || "").split(path.delimiter);
34
+ for (const directory of directories) {
35
+ const folder = directory.replace(/^"(.*)"$/, "$1");
36
+ if (!folder) continue;
37
+ const executable = path.join(folder, "claude.exe");
38
+ if (fs.existsSync(executable)) return [executable, []];
39
+ const script = path.join(
40
+ folder,
41
+ "node_modules",
42
+ "@anthropic-ai",
43
+ "claude-code",
44
+ "cli.js",
45
+ );
46
+ if (fs.existsSync(script)) return [process.execPath, [script]];
47
+ }
48
+ throw new Error(
49
+ "Install Claude Code CLI and add claude.exe to PATH before installing the plugin.",
35
50
  );
36
- const root = path.join(home, "broader-vids-npm");
37
- const directory = path.join(root, ".agents", "plugins");
38
- for (const folder of [root, path.join(root, ".agents"), directory]) {
51
+ }
52
+
53
+ function guardedDirectories(paths, message) {
54
+ for (const folder of paths) {
39
55
  fs.mkdirSync(folder, { recursive: true });
40
- if (fs.lstatSync(folder).isSymbolicLink())
41
- throw new Error(
42
- "The managed marketplace must not contain symbolic links.",
43
- );
56
+ if (fs.lstatSync(folder).isSymbolicLink()) throw new Error(message);
44
57
  }
58
+ }
59
+
60
+ function withMarketplaceLock(root, runInstall) {
45
61
  const lock = path.join(root, "install.lock");
46
62
  let handle;
47
63
  try {
@@ -53,11 +69,30 @@ function installPlugin(version, run, env = process.env) {
53
69
  );
54
70
  throw error;
55
71
  }
56
- const catalog = path.join(directory, "marketplace.json");
57
- const temporary = path.join(directory, `.${randomUUID()}.tmp`);
58
72
  try {
73
+ return runInstall();
74
+ } finally {
75
+ fs.closeSync(handle);
76
+ fs.unlinkSync(lock);
77
+ }
78
+ }
79
+
80
+ function installCodexPlugin(version, run, env) {
81
+ const [command, prefix] = resolveCodex(env);
82
+ const home = path.resolve(
83
+ env.CODEX_HOME || path.join(os.homedir(), ".codex"),
84
+ );
85
+ const root = path.join(home, "broader-vids-npm");
86
+ const directory = path.join(root, ".agents", "plugins");
87
+ guardedDirectories(
88
+ [root, path.join(root, ".agents"), directory],
89
+ "The managed marketplace must not contain symbolic links.",
90
+ );
91
+ return withMarketplaceLock(root, () => {
92
+ const catalog = path.join(directory, "marketplace.json");
59
93
  if (fs.existsSync(catalog) && fs.lstatSync(catalog).isSymbolicLink())
60
94
  throw new Error("The managed catalog must not be a symbolic link.");
95
+ const temporary = path.join(directory, `.${randomUUID()}.tmp`);
61
96
  const marketplace = {
62
97
  name: "broader-vids-npm",
63
98
  interface: { displayName: "Broader Vids (npm)" },
@@ -75,25 +110,124 @@ function installPlugin(version, run, env = process.env) {
75
110
  },
76
111
  ],
77
112
  };
78
- fs.writeFileSync(temporary, JSON.stringify(marketplace, null, 2) + "\n", {
79
- flag: "wx",
80
- mode: 0o600,
81
- });
82
- fs.renameSync(temporary, catalog);
83
- run(command, [...prefix, "plugin", "marketplace", "add", root]);
84
- run(command, [...prefix, "plugin", "add", "broader-vids@broader-vids-npm"]);
85
- return { status: "installed", marketplace: marketplace.name, version };
86
- } finally {
87
113
  try {
88
- fs.rmSync(temporary, { force: true });
114
+ fs.writeFileSync(temporary, JSON.stringify(marketplace, null, 2) + "\n", {
115
+ flag: "wx",
116
+ mode: 0o600,
117
+ });
118
+ fs.renameSync(temporary, catalog);
119
+ run(command, [...prefix, "plugin", "marketplace", "add", root]);
120
+ run(command, [
121
+ ...prefix,
122
+ "plugin",
123
+ "add",
124
+ "broader-vids@broader-vids-npm",
125
+ ]);
126
+ return { status: "installed", marketplace: marketplace.name, version };
89
127
  } finally {
90
- try {
91
- fs.closeSync(handle);
92
- } finally {
93
- fs.unlinkSync(lock);
128
+ fs.rmSync(temporary, { force: true });
129
+ }
130
+ });
131
+ }
132
+
133
+ function installClaudePlugin(version, run, env, operation = "install") {
134
+ const [command, prefix] = resolveClaude(env);
135
+ const home = path.resolve(
136
+ env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude"),
137
+ );
138
+ const root = path.join(home, "marketplaces", "broader-vids-npm");
139
+ const directory = path.join(root, ".claude-plugin");
140
+ const catalog = path.join(directory, "marketplace.json");
141
+ if (operation === "update" && !fs.existsSync(catalog))
142
+ throw new Error(
143
+ "The managed Claude marketplace is not installed. Run plugin install first.",
144
+ );
145
+ guardedDirectories(
146
+ [home, path.join(home, "marketplaces"), root, directory],
147
+ "The managed Claude marketplace must not contain symbolic links.",
148
+ );
149
+ return withMarketplaceLock(root, () => {
150
+ if (fs.existsSync(catalog) && fs.lstatSync(catalog).isSymbolicLink())
151
+ throw new Error(
152
+ "The managed Claude catalog must not be a symbolic link.",
153
+ );
154
+ const temporary = path.join(directory, `.${randomUUID()}.tmp`);
155
+ const marketplace = {
156
+ name: "broader-vids-npm",
157
+ description: "Broader Vids npm plugin catalog for Claude Code",
158
+ owner: { name: "Broader Vids contributors" },
159
+ plugins: [
160
+ {
161
+ name: "broader-vids",
162
+ source: {
163
+ source: "npm",
164
+ package: "broader-vids",
165
+ version,
166
+ registry: "https://registry.npmjs.org",
167
+ },
168
+ description:
169
+ "Curated YouTube and Bilibili recommendations with local evidence and feedback.",
170
+ },
171
+ ],
172
+ };
173
+ try {
174
+ fs.writeFileSync(temporary, JSON.stringify(marketplace, null, 2) + "\n", {
175
+ flag: "wx",
176
+ mode: 0o600,
177
+ });
178
+ fs.renameSync(temporary, catalog);
179
+ if (operation === "install") {
180
+ run(command, [...prefix, "plugin", "marketplace", "add", root]);
181
+ run(command, [
182
+ ...prefix,
183
+ "plugin",
184
+ "install",
185
+ "broader-vids@broader-vids-npm",
186
+ ]);
94
187
  }
188
+ run(command, [
189
+ ...prefix,
190
+ "plugin",
191
+ "marketplace",
192
+ "update",
193
+ marketplace.name,
194
+ ]);
195
+ run(command, [
196
+ ...prefix,
197
+ "plugin",
198
+ "update",
199
+ "broader-vids@broader-vids-npm",
200
+ "--scope",
201
+ "user",
202
+ ]);
203
+ return {
204
+ status: operation === "update" ? "updated" : "installed",
205
+ marketplace: marketplace.name,
206
+ version,
207
+ };
208
+ } finally {
209
+ fs.rmSync(temporary, { force: true });
95
210
  }
96
- }
211
+ });
212
+ }
213
+
214
+ function installPlugin(
215
+ version,
216
+ run,
217
+ env = process.env,
218
+ host = "codex",
219
+ operation = "install",
220
+ ) {
221
+ if (!["install", "update"].includes(operation))
222
+ throw new Error("Operation must be install or update.");
223
+ if (operation === "update" && host !== "claude")
224
+ throw new Error(
225
+ "Plugin update is supported only for Claude; use the Codex marketplace upgrade workflow.",
226
+ );
227
+ if (host === "codex") return installCodexPlugin(version, run, env);
228
+ if (host === "claude")
229
+ return installClaudePlugin(version, run, env, operation);
230
+ throw new Error("Host must be codex or claude.");
97
231
  }
98
232
 
99
- module.exports = { installPlugin, resolveCodex };
233
+ module.exports = { installPlugin, resolveCodex, resolveClaude };
@@ -1,7 +1,7 @@
1
1
  # Architecture
2
2
 
3
3
  Broader Vids has one Python engine.
4
- The terminal, Codex skill, and local dashboard use that engine.
4
+ The terminal, Codex skill, Claude Code skills, and local dashboard use that engine.
5
5
  The Node launcher installs and starts the engine.
6
6
  Per-profile locks coordinate launcher commands and setup.
7
7
  Ordinary commands can share the runtime. Setup requires exclusive access.
@@ -11,9 +11,15 @@ A stale or unreadable lock blocks later work until the operator checks for survi
11
11
  The launcher has no stale-lock repair command and does not implement recommendation logic.
12
12
 
13
13
  The GitHub marketplace and explicit npm installer both install the prepared npm plugin.
14
- The npm installer registers a small host catalog without GitHub access or profile access.
14
+ The npm installers register isolated host catalogs without GitHub access or profile access.
15
15
  Setup installs the bundled engine into external profile storage after plugin installation.
16
16
 
17
+ Host selection changes the model provider and worker interface. It does not change the engine.
18
+ Claude commands pass `--host claude` and explicit model and effort values.
19
+ Codex remains the default host.
20
+ Claude score reuse requires the same saved model and effort.
21
+ Codex retains its existing score-cache policy.
22
+ Both hosts can use the same profile through the same explicit `--data-dir` path.
17
23
  ## Project files
18
24
 
19
25
  ```text
@@ -68,6 +74,7 @@ broader-vids/
68
74
  asr-requirements.txt Locked transcription dependencies
69
75
  *.whl Generated engine package, excluded from Git
70
76
  scripts/
77
+ release.py Build, verify, and synchronize release artifacts
71
78
  release_ci.py Patch planning, publication checks, and GitHub assets
72
79
  versioning.py Validated release metadata synchronization
73
80
  test.py Isolated parallel regression runner
@@ -111,7 +118,9 @@ flowchart LR
111
118
  The web layer displays saved results and submits explicit user actions.
112
119
  It does not contain a separate scoring algorithm.
113
120
  The skill directs the host to call the engine.
114
- `worker_context.py` resolves the invoking thread's model and reasoning effort from local turn metadata.
121
+ `worker_context.py` resolves Codex model settings from local turn metadata.
122
+ Claude uses explicit model and effort settings. Its adapter lives in `claude_worker.py`.
123
+ Each round retains its saved host. Cancellation and deadlines stop owned worker processes.
115
124
  New runs save that pair and pass it to planning and assessment CLI workers.
116
125
  `recommendations/collection.py` continues candidate collection until 100 pass `screening.py` duration and raw engagement floors, or a saved limit stops collection.
117
126
  Screening policy 5 combines metadata screening with learned interest and balances query coverage across thirty-five content-assessment slots.
@@ -174,6 +183,7 @@ Refresh requests carry a read version and a mutation generation.
174
183
  Only one refresh group runs at a time.
175
184
  A refresh requested during an active read waits until that read finishes.
176
185
  Old video records stay in browser memory only while the server returns them, an earlier list uses them, or they have an unsaved rating draft.
186
+ The interface removes saved-status notes and inspector positions when their videos leave all retained lists and drafts.
177
187
  The interface rejects responses from before a newer mutation.
178
188
  It pauses background refresh while the tab is hidden or a write is active.
179
189
  Refresh preserves active controls and pane positions.
@@ -261,7 +271,8 @@ Preference transfer accepts format 4 with learning model version 8 and feature v
261
271
  Manual creator rules transfer separately from learning parameters and replace the manual lists transactionally on import.
262
272
  The export omits account-specific blacklist copies and sign-in data.
263
273
  It includes a bounded exploration summary with at most 1,024 nodes and aggregate counts and round ages.
264
- It excludes individual video history.
274
+ It includes watched video IDs without titles, ratings, or recommendation records.
275
+ Import adds their watched state without clearing local video states.
265
276
  It does not change SQLite schema 12.
266
277
  A completed `preference_import` job stores the imported parameter baseline and local feedback cutoff.
267
278
  Fitting combines that baseline with active ratings saved after the cutoff.
@@ -275,11 +286,11 @@ Input validation runs once per terminal or HTTP request.
275
286
  Failed imports remove unused recovery files.
276
287
  Import also removes obsolete model caches while preserving models referenced by recommendations or frozen evaluations.
277
288
  An uncertain commit retains its recovery file.
278
- Parameter-only recovery files reside in `backups/`.
289
+ Preference recovery files reside in `backups/` and include prior watched IDs and manual creator rules.
279
290
  The dashboard uses authenticated local POST operations for export, preview, and import.
280
291
  The transfer dialog preserves rating drafts and blocks stale polling responses during an operation.
281
292
 
282
- Evidence corrections add derived records.
293
+ Evidence corrections add derived records, including the current missing-caption deduction.
283
294
  They do not overwrite original scorecards or user ratings.
284
295
 
285
296
  The Preferences page uses `preferences.js` to coordinate `/api/interests` and the preference-transfer endpoints.
package/docs/REFERENCE.md CHANGED
@@ -807,6 +807,10 @@ Dashboard browser tests require Playwright and a supported local browser.
807
807
  Local Windows browser tests use installed Edge by default.
808
808
  CI installs the Playwright Chromium headless shell on both operating systems.
809
809
  Set `BROADER_VIDS_TEST_BROWSER=chromium` to use that browser locally.
810
+ Windows CI first installs the headless browser without changing system components.
811
+ If installation fails, it retries with the required system dependencies.
812
+ Linux CI installs those dependencies before tests.
813
+ Both paths retain browser validation and the full test suite.
810
814
  Linux tests use Playwright Chromium. Install its browser and system dependencies before running tests:
811
815
 
812
816
  ```bash
@@ -822,6 +826,27 @@ Dashboard tests check rating saves, drafts, duplicate feedback, dialogs, and pla
822
826
  Keep screenshots and other visual checks under the ignored `.cache/` directory.
823
827
  Browser tests reuse a browser process within each worker and create a fresh context for each test.
824
828
 
829
+ ## Experimental Claude Code installation
830
+
831
+ Claude Code support is experimental. Static package checks and launcher fixtures cover this path. No Claude CLI installation, skill loading, recommendation, or host acceptance test has been performed. This change does not publish an npm release. Use these commands after an npm release includes the Claude files.
832
+
833
+ Install from npm with the launcher:
834
+
835
+ ```powershell
836
+ npx --yes broader-vids@latest plugin install --host claude
837
+ ```
838
+
839
+ The launcher creates an isolated marketplace under `~/.claude/marketplaces/broader-vids-npm`, then calls Claude's native marketplace commands. It records the running npm package version in its catalog.
840
+
841
+ You can also install from the repository marketplace:
842
+
843
+ ```powershell
844
+ claude plugin marketplace add antidemosthenes/broader-vids
845
+ claude plugin install broader-vids@broader-vids
846
+ ```
847
+
848
+ The root Claude catalog tracks the npm `latest` release. See the [Claude Code plugin guide](https://code.claude.com/docs/en/plugins/create) for the host format. The installed skills route Claude to the host-specific instructions in [Claude host guide](../skills/claude-host.md).
849
+
825
850
  ## Remote plugin installation
826
851
 
827
852
  The [README](../README.md#install-the-plugin) gives GitHub and npm installation procedures.
@@ -956,6 +981,8 @@ An existing Git tag reserves its version, even when npm publication did not fini
956
981
  A different source receives a later version. A retry of the same source can reuse its tag.
957
982
  A higher version declared in the source acts as a minimum for the release version.
958
983
  The workflow synchronizes Node, Python, plugin, lock-file, and wheel-whitelist versions in a temporary release checkout.
984
+ Staging uses the version synchronizer's file list, including both host manifests.
985
+ Unstaged tracked changes stop the release before tag creation.
959
986
  It records the tested source commit in `package.json` under `broaderVidsRelease.sourceCommit`.
960
987
  It writes the version commit to main and creates its `vX.Y.Z` tag in one atomic push.
961
988
  The commit contains the tested functional source with synchronized release metadata.
@@ -980,6 +1007,8 @@ It retains workflow artifacts for seven days.
980
1007
  Retries resolve a tagged version commit back to its tested merge source.
981
1008
  They reuse a release when its recorded source commit matches that source.
982
1009
  An existing tag must have the expected parent and exact release tree.
1010
+ Rerunning publication cannot repair a tag with mismatched manifest versions.
1011
+ Keep that tag and merge a corrected main update to release a later version.
983
1012
  The bot version commit does not allocate a second version.
984
1013
  GitHub does not start another push workflow for a commit pushed with the workflow's `GITHUB_TOKEN`.
985
1014
  See [GitHub's trigger rules](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow).
@@ -1026,14 +1055,14 @@ The account settings and the first live OIDC publication require separate accept
1026
1055
  ### Update an installed plugin
1027
1056
 
1028
1057
  Finish active recommendations and stop the dashboard before updating.
1029
- For a GitHub installation:
1058
+ For a Codex GitHub installation:
1030
1059
 
1031
1060
  ```powershell
1032
1061
  codex plugin marketplace upgrade broader-vids
1033
1062
  codex plugin add broader-vids@broader-vids
1034
1063
  ```
1035
1064
 
1036
- For an npm installation:
1065
+ For a Codex npm installation:
1037
1066
 
1038
1067
  ```powershell
1039
1068
  npx --yes broader-vids@latest plugin install
@@ -1053,6 +1082,30 @@ Start a new conversation and run the setup skill after updating.
1053
1082
  Setup refreshes the matching runtime and preserves preferences, ratings, history, exclusions, and sign-in.
1054
1083
  An update does not run Reset or Clean.
1055
1084
 
1085
+ #### Update experimental Claude Code support
1086
+
1087
+ For the repository marketplace:
1088
+
1089
+ ```powershell
1090
+ claude plugin marketplace update broader-vids
1091
+ claude plugin update broader-vids@broader-vids --scope user
1092
+ ```
1093
+
1094
+ For the managed npm marketplace:
1095
+
1096
+ ```powershell
1097
+ npx --yes broader-vids@latest plugin update --host claude
1098
+ ```
1099
+
1100
+ The npm command updates the managed catalog's pinned version, refreshes the listing, and updates the installed user-scope plugin.
1101
+ Use `plugin install --host claude` for the first installation.
1102
+ Installation also synchronizes the plugin version after registration.
1103
+ A marketplace refresh alone does not update installed Claude plugins.
1104
+ Start a new Claude session and run `/broader-vids:broader-vids-setup` after an update.
1105
+ The new engine preserves the selected profile.
1106
+ These commands follow the [Claude plugin command reference](https://code.claude.com/docs/en/plugins/cli-reference).
1107
+ Actual Claude-host update behavior remains unverified in this project.
1108
+
1056
1109
  ### Repair the installed runtime
1057
1110
 
1058
1111
  From an unpacked package, install its external engine:
@@ -1080,6 +1133,7 @@ Its `installed` status does not mean onboarding is complete.
1080
1133
  Use the guided setup skill to configure interests, choose platforms, and check access.
1081
1134
  `setup --evidence` also installs browser and media tools.
1082
1135
  `setup --asr` includes those tools and transcription dependencies.
1136
+ Setup rejects unsupported options before it changes the profile or runtime.
1083
1137
  The receipt records `core`, `evidence`, and `asr` only when setup installed those groups, with each group's requirements-file digest.
1084
1138
  Setup requires Node.js 20 or later and UV.
1085
1139
  It does not use an npm postinstall script.
@@ -1218,7 +1272,14 @@ Continue only after you restore access.
1218
1272
  Browser sign-in is not imported automatically. Increasing the request cap does not repair an access challenge.
1219
1273
  They share one request counter and retain the existing access checks.
1220
1274
  Video downloads omit audio unless transcription requires it.
1221
- Exact or estimated selected-stream sizes support a check before transfer.
1275
+ The engine checks selected-stream sizes before transfer.
1276
+ It uses reported exact sizes, reported estimates, or duration multiplied by bitrate, in that order.
1277
+ Transcription downloads include both video and audio in this check.
1278
+ If the estimate exceeds the remaining allowance, the engine tries a smaller offered format within the existing resolution and audio rules.
1279
+ When partial media exists, continuation resolves saved format IDs against fresh metadata and checks their codecs and resolution.
1280
+ If the original selection is unavailable, the engine skips the candidate and removes its owned partial files.
1281
+ Cumulative download charges remain unchanged.
1282
+ Unknown sizes still use the transfer byte limit.
1222
1283
  Transfer checkpoints record observed bytes and bound unreported bytes after interruption.
1223
1284
  Reports identify conservative byte charges as upper bounds.
1224
1285
 
package/docs/SCORING.md CHANGED
@@ -4,6 +4,9 @@ Broader Vids learns conditional preferences from explicit feedback.
4
4
  It does not estimate an objective quality score for every video.
5
5
  Its conclusions apply to the retrieved videos and feature contexts that receive feedback.
6
6
 
7
+ Claude Code uses the same scoring formulas and thresholds as Codex.
8
+ The selected provider and model can change generated assessments.
9
+ No host selection changes the saved scoring formulas.
7
10
  ## Terms
8
11
 
9
12
  | Term | Meaning |
@@ -162,10 +165,10 @@ Search-domain labels describe retrieval context.
162
165
  They do not prove the video's semantic topic.
163
166
 
164
167
  New AI topic labels must be short subject names, with at most 120 characters and 12 words.
165
- The validator rejects obvious citations, instructions, control characters, and editing notes in labels.
166
- Invalid new output uses the existing bounded assessment fix workflow.
167
- Read operations omit unusable labels from older scorecards and annotations.
168
- They preserve raw evidence, numeric quality scores, saved ratings, and explicit user targets.
168
+ Fresh assessments and reads of saved scorecards omit unusable topic labels before validation.
169
+ The filter removes obvious citations, instructions, control characters, and editing notes from the label lists.
170
+ The engine retains the raw model response and preserves numeric quality scores, saved ratings, and explicit user targets.
171
+ Remaining schema or evidence errors use the existing bounded assessment fix workflow.
169
172
  This check detects common formatting errors. It does not prove that a topic correctly describes the video.
170
173
 
171
174
  Source links, repost declarations, `中配`, and YouDub disclosures inform originality assessment.
@@ -388,6 +391,7 @@ A new response type requires new holdout coverage.
388
391
  Training on released labels does not replace the earlier test result.
389
392
 
390
393
  Evidence maintenance adds derived feature records after source checks.
394
+ Corrections include the current missing-caption deduction, which replaces any earlier deduction.
391
395
  They preserve original ratings, scorecards, and captured features.
392
396
  Incomplete source metadata can pause quality fitting.
393
397
  Maintenance uses retained frames and captions without downloading replacement media.
package/docs/WORKFLOW.md CHANGED
@@ -4,9 +4,12 @@ Broader Vids finds videos, checks their content, and learns from explicit feedba
4
4
  This document explains the user workflow.
5
5
  See the [terminal reference](REFERENCE.md) for commands.
6
6
 
7
+ Codex remains the default host. Claude Code uses the same workflow and evidence rules.
8
+ Pass `--host claude` before an engine command and supply Claude's active model and effort explicitly.
9
+ Provider and model changes can change generated plans and assessments. They do not change collection or feedback gates.
7
10
  ## 1. Complete setup and check readiness
8
11
 
9
- Use the [README](../README.md#update-the-plugin) to update an installed plugin.
12
+ Use the [update procedure](REFERENCE.md#update-an-installed-plugin) to update an installed plugin.
10
13
  Finish active work before updating. Start a new conversation and run setup to prepare the matching engine.
11
14
  Setup preserves the existing profile unless you explicitly request Reset or Clean.
12
15
 
@@ -131,7 +134,7 @@ The two-platform command runs these paths with shared workers and an optional to
131
134
  ```mermaid
132
135
  flowchart TD
133
136
  S["Recommendation request"] --> T{"Onboarding complete?"}
134
- T -- No --> U["Introduce features; choose platforms; import preferences or enter interests"]
137
+ T -- No --> U["Introduce features; choose platforms; choose a starter, import preferences, or enter interests"]
135
138
  U --> V["Install required tools and check selected platform access"]
136
139
  V -- "Failure: repair and retry" --> V
137
140
  V --> W["Record setup completion"]
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "broader-vids",
3
- "version": "0.1.4",
4
- "description": "Codex skill and local YouTube/Bilibili recommendations with quality evidence and feedback",
3
+ "version": "0.1.7",
4
+ "description": "Codex and experimental Claude Code skills for local YouTube/Bilibili recommendations",
5
5
  "license": "MIT",
6
6
  "engines": {
7
7
  "node": ">=20"
@@ -11,7 +11,7 @@
11
11
  },
12
12
  "files": [
13
13
  "bin/",
14
- "python/broader_vids-0.1.4-*.whl",
14
+ "python/broader_vids-0.1.7-*.whl",
15
15
  "python/core-requirements.txt",
16
16
  "python/evidence-requirements.txt",
17
17
  "python/asr-requirements.txt",
@@ -22,7 +22,9 @@
22
22
  "docs/WORKFLOW.md",
23
23
  "docs/ARCHITECTURE.md",
24
24
  "docs/SCORING.md",
25
- "docs/REFERENCE.md"
25
+ "docs/REFERENCE.md",
26
+ ".claude-plugin/plugin.json",
27
+ ".claude-plugin/marketplace.json"
26
28
  ],
27
29
  "scripts": {
28
30
  "test": "node --test tests/launcher.test.cjs tests/profile-data.test.cjs",
@@ -46,6 +48,6 @@
46
48
  "tag": "latest"
47
49
  },
48
50
  "broaderVidsRelease": {
49
- "sourceCommit": "2954d5288aef941b7026a2358ce442d89fb31a06"
51
+ "sourceCommit": "61855b21530fa3ce0c35a7cd0afda7468e234f8a"
50
52
  }
51
53
  }
package/plugin.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
3
3
  "name": "broader-vids",
4
- "version": "0.1.4",
4
+ "version": "0.1.7",
5
5
  "description": "Curated YouTube and Bilibili recommendations with bounded quality evidence and local watched/feedback state.",
6
6
  "license": "MIT",
7
7
  "extensions": {
@@ -3,6 +3,8 @@ name: broader-vids
3
3
  description: Recommend YouTube and Bilibili videos with local evidence and feedback. Use for video discovery, recommendation rounds, video ratings, run recovery, and recommendation token reports.
4
4
  ---
5
5
 
6
+ > **Claude Code:** Read [the Claude host guide](../claude-host.md) and follow it instead of the Codex-specific instructions below.
7
+
6
8
  # Broader Vids
7
9
 
8
10
  Keep launcher commands internal.
@@ -3,6 +3,8 @@ name: broader-vids-clean
3
3
  description: Remove the complete Broader Vids data directory while retaining the installed plugin. Use only for full local-data removal, not routine media cleanup.
4
4
  ---
5
5
 
6
+ > **Claude Code:** Read [the Claude host guide](../claude-host.md) and follow it instead of the Codex-specific instructions below.
7
+
6
8
  # Clean Broader Vids data
7
9
 
8
10
  Keep launcher commands internal.
@@ -3,6 +3,8 @@ name: broader-vids-dashboard
3
3
  description: Open, inspect, or stop the Broader Vids local dashboard for recommendation feedback, optional calibration, token usage reports, and creator or tag exclusions. Use only for Broader Vids dashboard requests.
4
4
  ---
5
5
 
6
+ > **Claude Code:** Read [the Claude host guide](../claude-host.md) and follow it instead of the Codex-specific instructions below.
7
+
6
8
  # Broader Vids dashboard
7
9
 
8
10
  Keep launcher commands internal.
@@ -3,6 +3,8 @@ name: broader-vids-reset
3
3
  description: Reset Broader Vids preferences, learned weights, ratings, exclusions, and histories for a fresh start while retaining tools and Bilibili sign-in.
4
4
  ---
5
5
 
6
+ > **Claude Code:** Read [the Claude host guide](../claude-host.md) and follow it instead of the Codex-specific instructions below.
7
+
6
8
  # Reset Broader Vids
7
9
 
8
10
  Keep launcher commands internal.
@@ -3,6 +3,8 @@ name: broader-vids-setup
3
3
  description: Set up an installed Broader Vids plugin, its external Python runtime, local video interests, and platform access. Use for Broader Vids onboarding or installation repair, not general environment setup.
4
4
  ---
5
5
 
6
+ > **Claude Code:** Read [the Claude host guide](../claude-host.md) and follow it instead of the Codex-specific instructions below.
7
+
6
8
  # Set up Broader Vids
7
9
 
8
10
  ## Completion output
@@ -0,0 +1,46 @@
1
+ # Claude Code host guide
2
+
3
+ This guide is for Claude Code. Use it instead of the Codex-specific instructions in the five Broader Vids skill files.
4
+
5
+ ## Host and engine rules
6
+
7
+ - Keep the user's selected profile stable. Run `data show` and pass its absolute path with `--data-dir` on every engine command.
8
+ - Resolve the plugin root from the installed skill path. Run the Node launcher from that root.
9
+ - Put `--host claude` before each engine subcommand. For example, run `node <plugin-root>/bin/broader-vids.cjs --host claude recommend`.
10
+ - The Node launcher handles `data show`, `data use`, `data reset`, `reset`, and `clean`. It consumes `--host` for these commands.
11
+ - Run `setup --host claude --evidence` only to install or repair the runtime. The Node setup command does not complete onboarding.
12
+ - Use Claude's active model and effort only when Claude exposes both values in the current session. Otherwise ask the user once for both values and wait. Never infer either value from Codex, an old setting, or a default.
13
+ - Pass the verified values with `--model MODEL --effort EFFORT` for setup completion and recommendation commands. The engine can also read `BROADER_VIDS_CLAUDE_MODEL` and `BROADER_VIDS_CLAUDE_EFFORT` when the user explicitly sets both values.
14
+ - Keep launcher commands internal. Report results and repair steps in ordinary chat.
15
+
16
+ ## Setup
17
+
18
+ Use the setup skill's workflow as described here, with the engine's returned questions. Do not apply its Codex-specific host checks. Ask one question at a time. Do not invent interests, select a platform, or import a file without the user's answer.
19
+
20
+ Check Node.js, UV, Claude CLI, FFmpeg, yt-dlp, Pillow, and the selected platform access. Use the Node launcher setup command to install the runtime. Use `doctor` for diagnostics. Preserve a working profile during repair.
21
+
22
+ Use `onboarding questions`, `onboarding status`, `profile show`, and `onboarding configure` as required by the engine. Preview starter preferences or imports before applying them. Open Bilibili sign-in only when needed. Wait for the user to report sign-in completion, then check access.
23
+
24
+ Complete onboarding with `onboarding complete --format chat --model MODEL --effort EFFORT`. Include the exact active Claude model and effort. If the engine reports a required failure, repair it and repeat completion. Do not report success while an answer or required check is pending.
25
+
26
+ For a successful explicit setup request, return the full guide produced by `onboarding complete --format chat`. When setup interrupts a recommendation request, continue that request after setup succeeds.
27
+
28
+ ## Recommendations
29
+
30
+ Use the recommendation skill's engine workflow, evidence rules, saved profile, and feedback gate. Run one recommendation command with `--host claude`, the verified `--model` and `--effort`, and the requested platform options.
31
+
32
+ Do not bypass incomplete feedback without the user's explicit choice. Do not reduce requested platform coverage. Report incomplete results as partial and keep candidate failure details accurate. Continue a paused run only when the user asks.
33
+
34
+ ## Dashboard
35
+
36
+ Open the dashboard by running the engine's `dashboard` command with `--host claude`. Use the returned local URL. Do not start another server when one is already active. Stop only the verified Broader Vids dashboard for the selected profile.
37
+
38
+ The dashboard manages ratings, exclusions, interests, imports, and token reports. Do not create ratings or change preferences without the user's instruction. Dashboard access does not require a recommendation round.
39
+
40
+ ## Reset
41
+
42
+ Run `reset` without apply flags first. Show the exact profile path, removal summary, retained items, unknown files, and blockers. Apply Reset only when the user explicitly requests it for that previewed path. Stop the verified dashboard first. Pass the same `--data-dir` and exact confirmation path. Preserve unknown files and report partial failures.
43
+
44
+ ## Clean
45
+
46
+ Run `clean` without apply flags first. Show the exact profile path, removal summary, unknown files, and blockers. Apply Clean only when the user explicitly requests it for that previewed path. Stop the verified dashboard first. Pass the same `--data-dir` and exact confirmation path. Do not remove unknown files as a workaround. Report partial failures and offer setup if the user wants to use Broader Vids again.