@telepath-computer/television 0.1.81 → 0.1.82

package/dist/cli.cjs

@@ -50093,7 +50093,7 @@ function findCardIDInNode(node, artifactID) {
 var import_meta = {};
 var DAEMON_NAME = "com.television.server";
 var MAX_PORT = 65535;
-var HELP_POINTER = "Load/read the installed `television` skill. Start with `what-to-read.md`. If the skill is not installed, you can use `tv skills install` (interactive, not agent-friendly) or `tv skills show` (agent-friendly, prints bundled skill files directly). If this is artifact lifecycle work, read `artifact-workflow.md`. If this is HTML artifact work, also read `html-house-style.md` and the relevant `artifact-types/*.md` companion doc.";
+var HELP_POINTER = "Load/read the installed `television` skill. Start with `SKILL.md` for the mental model and the artifact-vs-chat decision. If the skill is not installed, you can use `tv skills install` (interactive, not agent-friendly) or `tv skills show` (agent-friendly, prints bundled skill files directly). For CLI commands, focus, and screen placement, read `cli-capabilities.md`. For artifact lifecycle work, read `artifact-workflow.md`. For HTML artifact work, also read `html-house-style.md` and the relevant `artifact-types/*.md` companion doc.";
 var CLIDirectiveError = class extends Error {
   name = "CLIDirectiveError";
 };
@@ -50123,8 +50123,8 @@ function resolveVercelSkillsInstallerBin() {
   return localRequire.resolve("skills/bin/cli.mjs");
 }
 function readCLIVersion() {
-  if ("0.1.81".length > 0) {
-    return "0.1.81";
+  if ("0.1.82".length > 0) {
+    return "0.1.82";
   }
   const devPackageJsonPath = import_node_path7.default.join(getDevPackageDir(), "package.json");
   if (!(0, import_node_fs4.existsSync)(devPackageJsonPath)) {
@@ -50151,7 +50151,8 @@ function buildAgentHelpNote() {
     "",
     "Agent workflow note:",
     "  Load/read the installed `television` skill before Television work.",
-    "  Then read `what-to-read.md` to choose the right companion docs.",
+    "  `SKILL.md` carries the mental model and the artifact-vs-chat decision.",
+    "  `cli-capabilities.md` covers commands, focus, and screen placement.",
     "  For artifact lifecycle work, read `artifact-workflow.md`.",
     "  For HTML artifacts, also read `html-house-style.md`.",
     "  Known artifact-type docs:",
@@ -50175,6 +50176,28 @@ function buildArtifactWorkflowHelpNote(includeHTMLNote) {
 function getBundledTelevisionSkillRoot(bundledTelevisionSkillsCollectionRoot) {
   return import_node_path7.default.join(bundledTelevisionSkillsCollectionRoot, "television");
 }
+function readSkillManifest(skillRoot) {
+  const empty = { version: void 0, descriptions: /* @__PURE__ */ new Map() };
+  const manifestPath = import_node_path7.default.join(skillRoot, ".skill-manifest.json");
+  if (!(0, import_node_fs4.existsSync)(manifestPath)) return empty;
+  try {
+    const raw = (0, import_node_fs4.readFileSync)(manifestPath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null) return empty;
+    const root = parsed;
+    const version2 = typeof root.version === "string" ? root.version : void 0;
+    const files = Array.isArray(root.files) ? root.files : [];
+    const entries = [];
+    for (const entry of files) {
+      if (typeof entry === "object" && entry !== null && typeof entry.path === "string" && typeof entry.description === "string") {
+        entries.push([entry.path, entry.description]);
+      }
+    }
+    return { version: version2, descriptions: new Map(entries) };
+  } catch {
+    return empty;
+  }
+}
 function listSkillFiles(skillRoot, prefix = "") {
   const entries = (0, import_node_fs4.readdirSync)(skillRoot, { withFileTypes: true }).filter((entry) => !entry.name.startsWith(".")).sort((a, b) => a.name.localeCompare(b.name));
   const files = [];
@@ -50505,7 +50528,9 @@ function createProgram(env, argv = []) {
       });
     });
   });
-  program2.command("create-internal-artifact").description("Create a pending internal Television-managed artifact bundle").requiredOption("--screen <id>", "Target screen ID").requiredOption("--type <type>", `Artifact type (${ARTIFACT_TYPES.join(" or ")})`).requiredOption("--title <title>", "Artifact title").option("--focus-artifact", "Focus the new artifact after creation").option("--no-focus", "Create the artifact in the background without changing focus").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).addHelpText("after", buildArtifactWorkflowHelpNote(true)).action(async (opts) => {
+  program2.command("create-internal-artifact").description(
+    "Stage a pending internal artifact bundle that Television owns and renders. Internal artifacts use a staged lifecycle: this command creates the pending bundle on disk, you edit its files (artifact.md, data.json, memory.md, public/index.{md,html}), and you finish with `tv commit-pending-artifact` or discard with `tv abandon-pending-artifact`. The artifact has immediate membership on --screen so the user can see in-progress state. Pick --focus-artifact when the user should be taken to it now, or --no-focus to work in the background."
+  ).requiredOption("--screen <id>", "Target screen ID").requiredOption("--type <type>", `Artifact type (${ARTIFACT_TYPES.join(" or ")})`).requiredOption("--title <title>", "Artifact title").option("--focus-artifact", "Focus the new artifact after creation").option("--no-focus", "Create the artifact in the background without changing focus").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).addHelpText("after", buildArtifactWorkflowHelpNote(true)).action(async (opts) => {
     const shouldFocus = resolveFocusDirective(argv, "create-internal-artifact", "--focus-artifact");
     if (!isArtifactType(opts.type)) {
       throw createDirectiveError(
@@ -50528,24 +50553,32 @@ function createProgram(env, argv = []) {
     writeLine(env.stdout, `Edit files in ${result.pendingPath}, then commit with:`);
     writeLine(env.stdout, `  tv commit-pending-artifact --id ${result.artifact.id}`);
   });
-  program2.command("edit-internal-artifact").description("Stage a pending edit for an internal artifact").requiredOption("--id <id>", "Artifact ID").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).addHelpText("after", buildArtifactWorkflowHelpNote(true)).action(async (opts) => {
+  program2.command("edit-internal-artifact").description(
+    "Stage a pending edit against an existing internal artifact. The bundle becomes editable on disk; the live committed version stays in place until you finish. Read artifact.md, data.json, and memory.md before changing anything so you preserve user intent and prior decisions. Finish with `tv commit-pending-artifact`, or discard with `tv abandon-pending-artifact`."
+  ).requiredOption("--id <id>", "Artifact ID").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).addHelpText("after", buildArtifactWorkflowHelpNote(true)).action(async (opts) => {
     const client = createAuthenticatedClient(opts.server);
     const result = await client.artifacts.edit({ artifactID: opts.id });
     writeLine(env.stdout, `Pending edit for artifact ${result.artifact.id} staged.`);
     writeLine(env.stdout, `Edit files in ${result.pendingPath}, then commit with:`);
     writeLine(env.stdout, `  tv commit-pending-artifact --id ${result.artifact.id}`);
   });
-  program2.command("commit-pending-artifact").description("Validate and commit a pending internal artifact bundle").requiredOption("--id <id>", "Artifact ID").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).addHelpText("after", buildArtifactWorkflowHelpNote(true)).action(async (opts) => {
+  program2.command("commit-pending-artifact").description(
+    "Validate the pending bundle and, if valid, commit it as the live artifact. Validation enforces required structure: artifact.md must contain all required headings (## User intent, ## Purpose, ## Data shape, ## Data sources, ## Rendering, ## Update workflow, ## Non-goals); data.json must be valid JSON; memory.md must contain ## Activity Log and a fresh UTC timestamp (YYYY-MM-DDTHH:MM:SSZ); public/index.{md,html} must be non-empty and match the artifact type. The CLI prints a directive when validation fails \u2014 fix the bundle and retry."
+  ).requiredOption("--id <id>", "Artifact ID").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).addHelpText("after", buildArtifactWorkflowHelpNote(true)).action(async (opts) => {
     const client = createAuthenticatedClient(opts.server);
     const { artifact } = await client.artifacts.commitPending({ artifactID: opts.id });
     writeLine(env.stdout, `Artifact ${artifact.id} committed.`);
   });
-  program2.command("abandon-pending-artifact").description("Discard a pending internal artifact create or edit").requiredOption("--id <id>", "Artifact ID").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).addHelpText("after", buildArtifactWorkflowHelpNote(false)).action(async (opts) => {
+  program2.command("abandon-pending-artifact").description(
+    "Discard pending work without committing. For a pending create, the artifact never becomes live and the bundle is removed. For a pending edit, the live committed version is kept unchanged. Use this when the staged work should not ship."
+  ).requiredOption("--id <id>", "Artifact ID").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).addHelpText("after", buildArtifactWorkflowHelpNote(false)).action(async (opts) => {
     const client = createAuthenticatedClient(opts.server);
     await client.artifacts.abandonPending({ artifactID: opts.id });
     writeLine(env.stdout, `Pending operation on artifact ${opts.id} abandoned.`);
   });
-  program2.command("create-external-artifact").description("Create an external artifact that points at an existing file").requiredOption("--screen <id>", "Target screen ID").requiredOption("--type <type>", `Artifact type (${ARTIFACT_TYPES.join(" or ")})`).requiredOption("--title <title>", "Artifact title").requiredOption("--path <path>", "Absolute path to an existing content file").option("--focus-artifact", "Focus the new artifact after creation").option("--no-focus", "Create the artifact in the background without changing focus").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).addHelpText("after", buildArtifactWorkflowHelpNote(true)).action(async (opts) => {
+  program2.command("create-external-artifact").description(
+    "Create an artifact that points at an existing file on disk. Television displays the file and watches it for changes, but does not own it: there is no bundle, no pending lifecycle, and `tv delete-artifact` only forgets the pointer \u2014 it never deletes the underlying file. --path must be absolute, the file must already exist and be readable, and its extension must match --type. Use this when the file already exists outside Television; use create-internal-artifact when Television should own a maintainable bundle."
+  ).requiredOption("--screen <id>", "Target screen ID").requiredOption("--type <type>", `Artifact type (${ARTIFACT_TYPES.join(" or ")})`).requiredOption("--title <title>", "Artifact title").requiredOption("--path <path>", "Absolute path to an existing content file").option("--focus-artifact", "Focus the new artifact after creation").option("--no-focus", "Create the artifact in the background without changing focus").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).addHelpText("after", buildArtifactWorkflowHelpNote(true)).action(async (opts) => {
     const shouldFocus = resolveFocusDirective(argv, "create-external-artifact", "--focus-artifact");
     if (!isArtifactType(opts.type)) {
       throw createDirectiveError(
@@ -50573,7 +50606,9 @@ If you wish to display temporary content to the user, use an internal artifact i
     writeLine(env.stdout, `External artifact ${artifact.id} created.`);
     writeLine(env.stdout, `Television will display content from ${externalPath} and watch it for changes.`);
   });
-  program2.command("create-url-artifact").description("Create a URL-backed artifact that embeds an external page").requiredOption("--screen <id>", "Target screen ID").requiredOption("--title <title>", "Artifact title").requiredOption("--url <url>", "http(s) URL of the page to embed").option("--focus-artifact", "Focus the new artifact after creation").option("--no-focus", "Create the artifact in the background without changing focus").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).addHelpText("after", buildArtifactWorkflowHelpNote(true)).action(async (opts) => {
+  program2.command("create-url-artifact").description(
+    "Create an artifact that embeds a live http(s) page. Type is always text/html \u2014 do not pass --type. URL artifacts commit immediately and have no pending lifecycle. The page renders in a sandboxed <webview> in the desktop app and an <iframe> in the browser; some sites block embedding via X-Frame-Options or CSP, in which case the page may show as blank. Use this for live dashboards, docs, or third-party pages; use create-internal-artifact when the content should be Television-owned and durable."
+  ).requiredOption("--screen <id>", "Target screen ID").requiredOption("--title <title>", "Artifact title").requiredOption("--url <url>", "http(s) URL of the page to embed").option("--focus-artifact", "Focus the new artifact after creation").option("--no-focus", "Create the artifact in the background without changing focus").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).addHelpText("after", buildArtifactWorkflowHelpNote(true)).action(async (opts) => {
     const shouldFocus = resolveFocusDirective(argv, "create-url-artifact", "--focus-artifact");
     const client = createAuthenticatedClient(opts.server);
     const { artifact } = await client.artifacts.create({
@@ -50591,7 +50626,9 @@ If you wish to display temporary content to the user, use an internal artifact i
   program2.command("storage-path").description("Print the Television storage path").action(() => {
     writeJSON(env.stdout, { storagePath: getTelevisionStoragePath() });
   });
-  program2.command("update-artifact").description("Update artifact metadata in place (artifact ID and type stay the same)").requiredOption("--id <id>", "Artifact ID").requiredOption("--title <title>", "New title").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).action(async (opts) => {
+  program2.command("update-artifact").description(
+    "Update artifact metadata in place. Currently only --title is changeable; ID and type are immutable. This does not modify bundle content \u2014 for content changes on internal artifacts, use `tv edit-internal-artifact` and the pending-edit lifecycle."
+  ).requiredOption("--id <id>", "Artifact ID").requiredOption("--title <title>", "New title").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).action(async (opts) => {
     const client = createAuthenticatedClient(opts.server);
     await client.artifacts.update({ artifactID: opts.id, title: opts.title });
     writeLine(env.stdout, `Artifact ${opts.id} updated.`);
@@ -50604,14 +50641,18 @@ If you wish to display temporary content to the user, use an internal artifact i
     });
     writeLine(env.stdout, `Artifact ${result.artifactID} detached from screen ${result.screenID}.`);
   };
-  program2.command("detach-artifact").description("Remove an artifact card from a screen's layout (artifact metadata is preserved)").requiredOption("--id <id>", "Artifact ID").requiredOption("--screen <id>", "Screen ID").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).action(detachAction);
+  program2.command("detach-artifact").description(
+    "Remove the artifact's card from one screen's layout. The artifact itself is never touched: its metadata, its bundle (if internal), and its pointer (if external/url) all stay intact. Detaching the last screen reference does NOT delete the artifact \u2014 it just leaves it unplaced. Use `tv delete-artifact` when the user wants global removal, and `tv list-artifacts --unplaced` to find unplaced artifacts."
+  ).requiredOption("--id <id>", "Artifact ID").requiredOption("--screen <id>", "Screen ID").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).action(detachAction);
   program2.command("remove-artifact", { hidden: true }).description("Deprecated alias for detach-artifact").requiredOption("--id <id>", "Artifact ID").requiredOption("--screen <id>", "Screen ID").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).action(async (opts) => {
     env.stderr.write(
       "Deprecated: 'tv remove-artifact' has been renamed to 'tv detach-artifact'. Note: detach no longer trashes the artifact even on the last reference; use 'tv delete-artifact' to remove an artifact globally.\n"
     );
     await detachAction(opts);
   });
-  program2.command("attach-artifact").description("Attach an existing artifact to a screen by appending a card to the strip end").requiredOption("--id <id>", "Artifact ID").requiredOption("--screen <id>", "Screen ID").option("--focus-artifact", "Focus the artifact after attaching it").option("--no-focus", "Attach the artifact in the background without changing focus").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).action(async (opts) => {
+  program2.command("attach-artifact").description(
+    "Attach an existing artifact to a screen by appending a default-sized card to the right end of the screen's strip. Idempotent: attaching an artifact that is already on this screen is a no-op (existing card position is preserved). An artifact may belong to multiple screens simultaneously; attach does not move it, it adds another reference. Pick --focus-artifact when the user should be taken to the new card now, or --no-focus to attach in the background."
+  ).requiredOption("--id <id>", "Artifact ID").requiredOption("--screen <id>", "Screen ID").option("--focus-artifact", "Focus the artifact after attaching it").option("--no-focus", "Attach the artifact in the background without changing focus").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).action(async (opts) => {
     const shouldFocus = resolveFocusDirective(argv, "attach-artifact", "--focus-artifact");
     const client = createAuthenticatedClient(opts.server);
     const result = await client.artifacts.attach({
@@ -50626,7 +50667,9 @@ If you wish to display temporary content to the user, use an internal artifact i
       `Artifact ${result.artifact.id} attached to screen ${result.screenID} as card ${result.cardID}.`
     );
   });
-  program2.command("delete-artifact").description("Globally delete an artifact: detach from every screen, trash the bundle / forget the pointer").requiredOption("--id <id>", "Artifact ID").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).action(async (opts) => {
+  program2.command("delete-artifact").description(
+    "Globally remove an artifact. Detaches it from every screen it appears on, then: trashes the bundle (internal), forgets the pointer (external \u2014 the underlying file is untouched), drops the URL reference (URL), or discards pending-create work. This is the only path to global removal \u2014 `tv detach-artifact` only removes one screen-level card and leaves the artifact otherwise intact. There is no restore-from-trash workflow; treat delete as terminal."
+  ).requiredOption("--id <id>", "Artifact ID").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).action(async (opts) => {
     const client = createAuthenticatedClient(opts.server);
     const result = await client.artifacts.delete({ artifactID: opts.id });
     for (const line of formatDeleteArtifactResult(result)) {
@@ -50637,14 +50680,18 @@ If you wish to display temporary content to the user, use an internal artifact i
     const client = createAuthenticatedClient(opts.server);
     writeJSON(env.stdout, await client.artifacts.get({ artifactID: opts.id }));
   });
-  program2.command("list-artifacts").description("List artifacts. With no filter, every artifact is returned").option("--screen <id>", "Filter to artifacts attached to this screen").option("--unplaced", "Only return artifacts attached to no screen").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).action(async (opts) => {
+  program2.command("list-artifacts").description(
+    "List artifacts as JSON. With no filter, every artifact is returned. --screen <id> filters to artifacts attached to that screen. --unplaced returns only artifacts attached to no screen (use this to find orphans left after detaches). The two filters are mutually exclusive in practice."
+  ).option("--screen <id>", "Filter to artifacts attached to this screen").option("--unplaced", "Only return artifacts attached to no screen").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).action(async (opts) => {
     const client = createAuthenticatedClient(opts.server);
     const filter = {};
     if (opts.screen !== void 0) filter.screenID = opts.screen;
     if (opts.unplaced) filter.unplaced = true;
     writeJSON(env.stdout, await client.artifacts.list(filter));
   });
-  program2.command("create-screen").description("Create a new screen").requiredOption("--name <name>", "Screen name").option("--focus-screen", "Focus the new screen after creating it").option("--no-focus", "Create the screen in the background without changing focus").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).action(async (opts) => {
+  program2.command("create-screen").description(
+    "Create a new screen. Pick --focus-screen when the user should be taken to the new screen immediately (creating a workspace they're about to use), or --no-focus to create it in the background without disturbing their current view. A new screen starts empty; attach existing artifacts with `tv attach-artifact` or create new ones with the create-*-artifact commands using --screen."
+  ).requiredOption("--name <name>", "Screen name").option("--focus-screen", "Focus the new screen after creating it").option("--no-focus", "Create the screen in the background without changing focus").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).action(async (opts) => {
     const shouldFocus = resolveFocusDirective(argv, "create-screen", "--focus-screen");
     const client = createAuthenticatedClient(opts.server);
     const { screen } = await client.screens.create({ name: opts.name });
@@ -50653,7 +50700,9 @@ If you wish to display temporary content to the user, use an internal artifact i
     }
     writeLine(env.stdout, `Screen created: ${screen.id} (${screen.name})`);
   });
-  program2.command("remove-screen").description("Move a screen to trash and cascade artifact removals").requiredOption("--id <id>", "Screen ID").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).action(async (opts) => {
+  program2.command("remove-screen").description(
+    "Move a screen to trash. Cascades to its artifacts: each artifact is detached from this screen, and any artifact that loses its last screen reference as a result is left unplaced (not deleted). Use `tv list-artifacts --unplaced` afterward if you need to find or clean up orphans, and `tv delete-artifact` to remove them globally."
+  ).requiredOption("--id <id>", "Screen ID").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).action(async (opts) => {
     const client = createAuthenticatedClient(opts.server);
     const result = await client.screens.remove({ screenID: opts.id });
     for (const line of formatScreenRemovalResult(result)) {
@@ -50664,20 +50713,28 @@ If you wish to display temporary content to the user, use an internal artifact i
     const client = createAuthenticatedClient(opts.server);
     writeJSON(env.stdout, await client.screens.list());
   });
-  program2.command("get-screen").description("Get a screen and its artifacts").option("--id <id>", "Screen ID (auto-selects if only one exists)").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).action(async (opts) => {
+  program2.command("get-screen").description(
+    "Get a screen and its artifacts as JSON. Includes each artifact's kind (internal/external/url) and status (pending/committed) so you can plan follow-up actions without a second call. With no --id, auto-selects when exactly one screen exists; otherwise --id is required."
+  ).option("--id <id>", "Screen ID (auto-selects if only one exists)").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).action(async (opts) => {
     const client = createAuthenticatedClient(opts.server);
     writeJSON(env.stdout, await client.screens.get({ screenID: opts.id }));
   });
-  program2.command("focus-status").description("Print focus state: active screen ID and connected client count").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).action(async (opts) => {
+  program2.command("focus-status").description(
+    "Print focus state as JSON: the active (persistently focused) screen ID and the count of currently connected GUI clients. Useful for verifying that an upcoming focus event will actually be visible to anyone \u2014 if connectedClients is 0, focus-screen and focus-artifact are no-ops from the user's perspective."
+  ).option("--server <url>", "Server URL", DEFAULT_SERVER_URL).action(async (opts) => {
     const client = createAuthenticatedClient(opts.server);
     writeJSON(env.stdout, await client.viewer.state());
   });
-  program2.command("focus-screen").description("Focus a screen persistently; broadcast to connected clients").requiredOption("--id <id>", "Screen ID").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).action(async (opts) => {
+  program2.command("focus-screen").description(
+    "Set persistent screen focus. The change is broadcast to every connected GUI client and survives reconnects. This is the right command when the user wants to switch to a different screen and stay there. For just nudging attention to a specific artifact (which may live on the current screen), prefer `tv focus-artifact`."
+  ).requiredOption("--id <id>", "Screen ID").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).action(async (opts) => {
     const client = createAuthenticatedClient(opts.server);
     await client.viewer.setActive({ screenID: opts.id });
     writeLine(env.stdout, `Focused screen ${opts.id}.`);
   });
-  program2.command("focus-artifact").description("Nudge connected clients to scroll an artifact into view and play a brief highlight").requiredOption("--id <id>", "Artifact ID").option("--screen <id>", "Screen ID (optional; server picks a screen the artifact is on)").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).action(async (opts) => {
+  program2.command("focus-artifact").description(
+    "Send a transient focus nudge for a specific artifact. Connected clients switch to the artifact's screen if they're not already on it, scroll the artifact's card into view, and play a brief highlight animation. This is NOT persisted as state \u2014 there is no concept of a 'focused artifact' that survives reconnects (the focused screen is persistent, but artifact focus is a one-shot event). Pass --screen <id> to pin which screen the nudge targets, otherwise the server picks one (preferring the active screen when the artifact is there)."
+  ).requiredOption("--id <id>", "Artifact ID").option("--screen <id>", "Screen ID (optional; server picks a screen the artifact is on)").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).action(async (opts) => {
     const client = createAuthenticatedClient(opts.server);
     const { connectedClients } = await client.viewer.state();
     if (connectedClients === 0) {
@@ -50720,9 +50777,20 @@ If you wish to display temporary content to the user, use an internal artifact i
       throw new Error(`Could not resolve the bundled television skill root at ${skillRoot}.`);
     }
     if (relativePath === void 0) {
+      const manifest = readSkillManifest(skillRoot);
+      if (manifest.version !== void 0) {
+        writeLine(env.stdout, `Television skill content version: ${manifest.version}`);
+        writeLine(env.stdout, "");
+      }
+      writeLine(env.stdout, "Relative paths inside the bundled `television` skill:");
+      writeLine(env.stdout, "");
       for (const file2 of listSkillFiles(skillRoot)) {
-        writeLine(env.stdout, file2);
+        const description = manifest.descriptions.get(file2);
+        writeLine(env.stdout, description ? `${file2} \u2014 ${description}` : file2);
       }
+      writeLine(env.stdout, "");
+      writeLine(env.stdout, `Television skill root: ${skillRoot}`);
+      writeLine(env.stdout, "To read one file directly: tv skills show <relative-path>");
       return;
     }
     const filepath = resolveSkillFilePath(skillRoot, relativePath);

package/dist/skills/television/.skill-manifest.json

@@ -0,0 +1,29 @@
+{
+  "version": "0.1.10",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "description": "Mental model, when to use Television vs chat, and routing to companion docs. Always read first."
+    },
+    {
+      "path": "cli-capabilities.md",
+      "description": "The `tv` CLI command surface plus the complete focus story — model, required decisions, theory of mind, phrase cues, screen placement, and the `--no-focus` communication rule."
+    },
+    {
+      "path": "artifact-workflow.md",
+      "description": "Artifact lifecycle work — markdown vs HTML, prescriptive recipes for create/update/modify/abandon/external/url, internal bundle structure and validation, in-flight narration style, and the quality bar."
+    },
+    {
+      "path": "html-house-style.md",
+      "description": "House style and conventions for authoring HTML artifacts that render inside Television."
+    },
+    {
+      "path": "artifact-types/calendar.md",
+      "description": "Authoring conventions for the calendar artifact kind."
+    },
+    {
+      "path": "artifact-types/table.md",
+      "description": "Authoring conventions for the record-table artifact kind: dense, Airtable-style tables of records."
+    }
+  ]
+}

package/dist/skills/television/SKILL.md

@@ -1,23 +1,93 @@
 ---
 name: television
-description: Television agent guidance and routing for screen and artifact workflows
+description: Mental model, when to use Television vs chat, and routing to companion docs. Always read first.
+version: 0.1.10
 ---
 
+
 # Television
 
+*Skill content version: 0.1.10*
+
 Television is a persistent artifact screen for agents.
 
 Load this skill when you need to create, update, inspect, attach, focus, or otherwise manage Television screens and artifacts.
 
-This skill is modular. Do not assume `SKILL.md` contains every rule you need.
+## When to use Television
+
+Prefer Television when it is a better presentation surface than chat. When a response would otherwise be long, structured, visual, research-heavy, or significantly clearer as markdown, HTML, or a table, prefer creating a Television artifact as the primary response instead of delivering the full result in chat.
+
+The chat sidebar is good for short, conversational replies. It is bad for results the user will want to scan, compare, revisit, or treat as a working surface. Long structured output crammed into chat is harder to read and easy to lose.
+
+Use judgment. Do not create an artifact for every response, but do prefer one when:
+
+- the result is lengthy text or deep analysis
+- the result is a table or other structured comparison
+- the result is research output the user will likely revisit
+- the result benefits from richer HTML layout, hierarchy, or widgets
+- the user is likely to keep referring back to the result while continuing the conversation
+
+Ground this decision in the user's likely experience. Ask yourself what will be easier for them to read, compare, revisit, or act on next.
+
+When the artifact is the real answer, keep the final chat reply short. Tell the user what you created, what they will see, and where to find it rather than duplicating the full content in chat.
+
+## Mental model
+
+### Core entities
+
+- A **screen** is a named viewer surface with a layout.
+- An **artifact** is a result that can be shown on a screen.
+- Screen membership and artifact identity are separate.
+
+That separation matters:
+
+- attaching or detaching changes where an artifact appears
+- deleting an artifact removes it globally
+- an artifact may be attached to one screen, multiple screens, or no screens
+
+### Artifact kinds
+
+Three operational categories:
+
+- **internal artifact** — Television-managed bundle content. Use when Television should own the result as a durable bundle that later agents can inspect and maintain.
+- **external artifact** — pointer to an existing absolute file on disk. Use when a real file already exists and Television should display it without taking ownership of that file.
+- **URL artifact** — pointer to an external `http(s)://` page. Use when the right answer is to show a live web page rather than Television-owned content or a local file.
+
+### Lifecycle states
+
+- **pending** — internal create/edit work has been staged but not committed yet
+- **committed** — the artifact is live
+- **trash** — live metadata and any committed internal bundle have been moved out of the active tree
+
+Important consequences:
+
+- only internal artifacts use pending create/edit/commit/abandon
+- external file artifacts are committed immediately
+- URL artifacts are committed immediately
+- there is no restore-from-trash workflow in the current scope
+
+### User-facing framing
+
+Think in terms of what the user believes exists and where they expect to find it.
+
+Questions to keep straight:
+
+- should this result become a durable Television-owned artifact?
+- should it instead stay an external file or URL pointer?
+- should it appear on the current screen, another existing screen, or a new screen?
+- should the user see it immediately, or should it be prepared without moving their attention yet?
+
+Those questions interact, but they are not the same question.
+
+## Where to read next
 
-Read `what-to-read.md` next to decide which companion docs apply.
+This skill is modular. SKILL.md does not contain every rule.
 
-## Core companion docs
+- For the `tv` CLI command surface, the focus model, and screen-placement guidance, read `cli-capabilities.md`.
+- For artifact lifecycle work — creating, updating, committing, abandoning, attaching, detaching, deleting — read `artifact-workflow.md`. That doc covers internal bundle structure and validation as well, since most artifact authoring is internal.
+- For HTML artifacts, also read `html-house-style.md` and any matching `artifact-types/*.md` companion doc.
 
-- `what-to-read.md`
-- `artifact-workflow.md`
-- `html-house-style.md`
+`markdown editor UI recovery` remains out of scope for the current Television workflow.
 
 ## Known artifact-type docs
 

package/dist/skills/television/artifact-types/calendar.md

@@ -1,3 +1,7 @@
+---
+description: Authoring conventions for the calendar artifact kind.
+---
+
 # Authoring a calendar week
 
 A working-week calendar with a generated header strip, all-day band, time axis,

package/dist/skills/television/artifact-types/table.md

@@ -1,3 +1,7 @@
+---
+description: Authoring conventions for the record-table artifact kind: dense, Airtable-style tables of records.
+---
+
 # Authoring a record table
 
 A dense, Airtable-style table of records. Lots of cells, mixed cell types,