@telepath-computer/television 0.1.47 → 0.1.48

package/dist/cli.cjs

@@ -33753,12 +33753,15 @@ var ServerEventMessageEvent = defineEvent();
 var LayoutMutationEvent = defineEvent();
 var LayoutScrollEvent = defineEvent();
 var ArtifactCreatedEvent = defineEvent();
+var ArtifactAttachedEvent = defineEvent();
 var ArtifactUpdatedEvent = defineEvent();
 var ArtifactRemovedEvent = defineEvent();
 var ArtifactContentChangedEvent = defineEvent();
 var ScreenCreatedEvent = defineEvent();
 var ScreenUpdatedEvent = defineEvent();
 var ScreenRemovedEvent = defineEvent();
+var ViewerActiveScreenChangedEvent = defineEvent();
+var ViewerFocusEvent = defineEvent();
 
 // ../shared/src/errors.ts
 function defineError(name) {
@@ -33775,6 +33778,7 @@ var RequestError = defineError("RequestError");
 var ValidationError = defineError("ValidationError");
 var NotFoundError = defineError("NotFoundError");
 var InvalidRequestError = defineError("InvalidRequestError");
+var ConflictError = defineError("ConflictError");
 
 // ../shared/src/acp-types.ts
 function isACPBridgeClientMessage(value) {
@@ -33950,21 +33954,36 @@ var ScreenClient = class {
 };
 var ArtifactClient = class {
   #http;
-  #screens;
-  constructor(http2, screens) {
+  constructor(http2) {
     this.#http = http2;
-    this.#screens = screens;
   }
-  async create(input) {
-    const screenID = await this.#resolveScreenID(input.screenID);
+  /**
+   * Create an artifact, optionally attaching it to a screen in one round
+   * trip. When `screenID` is supplied the response carries an `attached`
+   * field with the resulting cardID.
+   */
+  create(input) {
+    const body = {
+      type: input.type,
+      title: input.title
+    };
+    if (input.externalFilePath !== void 0) body.externalFilePath = input.externalFilePath;
+    if (input.screenID !== void 0) body.screenID = input.screenID;
+    return this.#http.requestJSON("POST", "/artifacts", body);
+  }
+  /**
+   * List artifacts. With no filter, returns every artifact known to the
+   * server. `screenID` filters to a single screen's members; `unplaced`
+   * returns only artifacts attached to no screen.
+   */
+  list(input = {}) {
+    const params = new URLSearchParams();
+    if (input.screenID !== void 0) params.set("screenID", input.screenID);
+    if (input.unplaced) params.set("unplaced", "true");
+    const query = params.toString();
     return this.#http.requestJSON(
-      "POST",
-      `/screens/${encodeURIComponent(screenID)}/artifact`,
-      {
-        type: input.type,
-        title: input.title,
-        externalFilePath: input.externalFilePath
-      }
+      "GET",
+      query ? `/artifacts?${query}` : "/artifacts"
     );
   }
   get(input) {
@@ -33997,12 +34016,37 @@ var ArtifactClient = class {
   abandonPending(input) {
     return this.#http.requestVoid("POST", `/artifacts/${encodeURIComponent(input.artifactID)}/abandon`);
   }
-  remove(input) {
+  /**
+   * Attach an existing artifact to a screen. Idempotent — if already
+   * attached, the existing card is returned and no event fires.
+   */
+  attach(input) {
+    return this.#http.requestJSON(
+      "POST",
+      `/screens/${encodeURIComponent(input.screenID)}/artifacts/${encodeURIComponent(input.artifactID)}`
+    );
+  }
+  /**
+   * Detach an artifact from a single screen. Layout-only; the artifact
+   * itself is never trashed by this call. Use `delete()` to remove the
+   * artifact globally.
+   */
+  detach(input) {
     return this.#http.requestJSON(
       "DELETE",
       `/screens/${encodeURIComponent(input.screenID)}/artifacts/${encodeURIComponent(input.artifactID)}`
     );
   }
+  /**
+   * Globally delete an artifact: strip every referencing card from every
+   * screen and trash/forget/discard the on-disk state.
+   */
+  delete(input) {
+    return this.#http.requestJSON(
+      "DELETE",
+      `/artifacts/${encodeURIComponent(input.artifactID)}`
+    );
+  }
   getContent(input) {
     return this.#http.requestText("GET", `/artifacts/${encodeURIComponent(input.artifactID)}/content`);
   }
@@ -34013,18 +34057,27 @@ var ArtifactClient = class {
       input.content
     );
   }
-  async #resolveScreenID(screenID) {
-    if (screenID !== void 0) {
-      return screenID;
-    }
-    const { screens } = await this.#screens.list();
-    if (screens.length === 1) {
-      return screens[0].id;
-    }
-    throw this.#http.createError(
-      `screenID is required when multiple screens exist. Available screens: ${formatScreenChoices(screens)}`
+};
+var ViewerClient = class {
+  #http;
+  constructor(http2) {
+    this.#http = http2;
+  }
+  state() {
+    return this.#http.requestJSON("GET", "/viewer/state");
+  }
+  setActive(input) {
+    return this.#http.requestJSON(
+      "PUT",
+      "/viewer/active-screen",
+      { screenID: input.screenID }
     );
   }
+  focus(input) {
+    const body = { artifactID: input.artifactID };
+    if (input.screenID !== void 0) body.screenID = input.screenID;
+    return this.#http.requestJSON("POST", "/viewer/focus", body);
+  }
 };
 var ViewClient = class {
   #http;
@@ -34039,12 +34092,14 @@ var ViewClient = class {
 var TelevisionClient = class {
   screens;
   artifacts;
+  viewer;
   views;
   #http;
   constructor(serverURL, options = {}) {
     this.#http = new HttpRequester(serverURL, options);
     this.screens = new ScreenClient(this.#http);
-    this.artifacts = new ArtifactClient(this.#http, this.screens);
+    this.artifacts = new ArtifactClient(this.#http);
+    this.viewer = new ViewerClient(this.#http);
     this.views = new ViewClient(this.#http);
   }
   health() {
@@ -47984,14 +48039,24 @@ var createArtifactSchema = external_exports.object({
   title: external_exports.string(),
   externalFilePath: external_exports.string().optional()
 }).strict();
+var createArtifactBodySchema = createArtifactSchema.extend({
+  screenID: external_exports.string().optional()
+}).strict();
 var patchArtifactSchema = external_exports.object({
   title: external_exports.string().optional()
 }).refine((value) => value.title !== void 0, { message: "title is required" });
+var setActiveScreenSchema = external_exports.object({ screenID: external_exports.string() }).strict();
+var focusSchema = external_exports.object({
+  artifactID: external_exports.string(),
+  screenID: external_exports.string().optional()
+}).strict();
+var HTTP_OK2 = 200;
 var HTTP_CREATED = 201;
 var HTTP_NO_CONTENT = 204;
 var HTTP_BAD_REQUEST = 400;
 var HTTP_FORBIDDEN = 403;
 var HTTP_NOT_FOUND = 404;
+var HTTP_CONFLICT = 409;
 var CORS_HEADERS = {
   "Access-Control-Allow-Origin": "*",
   "Access-Control-Allow-Methods": "GET, POST, PUT, PATCH, DELETE, OPTIONS",
@@ -48018,19 +48083,29 @@ function handleStoreError(res, error48, fallback) {
     sendError(res, HTTP_BAD_REQUEST, error48.message);
     return;
   }
+  if (error48 instanceof ConflictError) {
+    sendError(res, HTTP_CONFLICT, error48.message);
+    return;
+  }
   throw error48 instanceof Error ? error48 : new Error(fallback);
 }
 function registerRoutes(app, store, options) {
+  const getConnectedClientCount = options.getConnectedClientCount ?? (() => 0);
   const auth = options.requireAuth ? [options.requireAuth] : [];
   app.use("/screens", applyCorsMiddleware);
   app.use("/artifacts", applyCorsMiddleware);
   app.use("/views", applyCorsMiddleware);
+  app.use("/viewer", applyCorsMiddleware);
   app.options("/screens", (_req, res) => res.status(HTTP_NO_CONTENT).end());
   app.options("/screens/:id", (_req, res) => res.status(HTTP_NO_CONTENT).end());
   app.options("/screens/:id/artifact", (_req, res) => res.status(HTTP_NO_CONTENT).end());
   app.options("/screens/:screenID/artifacts/:artifactID", (_req, res) => res.status(HTTP_NO_CONTENT).end());
+  app.options("/artifacts", (_req, res) => res.status(HTTP_NO_CONTENT).end());
   app.options("/artifacts/:id/*", (_req, res) => res.status(HTTP_NO_CONTENT).end());
   app.options("/artifacts/:id", (_req, res) => res.status(HTTP_NO_CONTENT).end());
+  app.options("/viewer/state", (_req, res) => res.status(HTTP_NO_CONTENT).end());
+  app.options("/viewer/active-screen", (_req, res) => res.status(HTTP_NO_CONTENT).end());
+  app.options("/viewer/focus", (_req, res) => res.status(HTTP_NO_CONTENT).end());
   app.options("/views", (_req, res) => res.status(HTTP_NO_CONTENT).end());
   app.options("/views/:id", (_req, res) => res.status(HTTP_NO_CONTENT).end());
   app.options("/views/:id/*", (_req, res) => res.status(HTTP_NO_CONTENT).end());
@@ -48091,6 +48166,21 @@ function registerRoutes(app, store, options) {
       handleStoreError(res, error48, "Failed to update screen");
     }
   });
+  app.delete(
+    "/screens/:screenID/artifacts/:artifactID",
+    ...auth,
+    (req, res) => {
+      try {
+        const result = store.detachArtifact({
+          screenID: req.params.screenID,
+          artifactID: req.params.artifactID
+        });
+        res.json(result);
+      } catch (error48) {
+        handleStoreError(res, error48, "Failed to detach artifact");
+      }
+    }
+  );
   app.post("/screens/:id/artifact", ...auth, (req, res) => {
     const parsed = createArtifactSchema.safeParse(req.body);
     if (!parsed.success) {
@@ -48106,27 +48196,96 @@ function registerRoutes(app, store, options) {
       });
       res.status(HTTP_CREATED).json({
         artifact,
-        // Internal artifacts return the pending bundle path so the caller can
-        // write files into it before commit. External artifacts don't have a
-        // pending bundle.
         ...artifact.externalFilePath ? {} : { pendingPath: getArtifactPendingBundlePath(store.storagePath, artifact.id) }
       });
     } catch (error48) {
       handleStoreError(res, error48, "Failed to create artifact");
     }
   });
-  app.delete(
+  app.get("/artifacts", ...auth, (req, res) => {
+    const rawScreenID = req.query.screenID;
+    const rawUnplaced = req.query.unplaced;
+    const screenIDFilter = typeof rawScreenID === "string" ? rawScreenID : void 0;
+    const unplacedOnly = rawUnplaced === "true" || rawUnplaced === "1";
+    if (screenIDFilter !== void 0 && unplacedOnly) {
+      sendError(res, HTTP_BAD_REQUEST, "screenID and unplaced are mutually exclusive");
+      return;
+    }
+    if (screenIDFilter !== void 0) {
+      const snapshot = store.getScreen(screenIDFilter);
+      if (!snapshot) {
+        sendError(res, HTTP_NOT_FOUND, `Screen not found: ${screenIDFilter}`);
+        return;
+      }
+      res.json({ artifacts: snapshot.artifacts });
+      return;
+    }
+    const all = store.listArtifacts();
+    if (!unplacedOnly) {
+      res.json({ artifacts: all });
+      return;
+    }
+    const placed = /* @__PURE__ */ new Set();
+    for (const screen of store.listScreens()) {
+      for (const id of getScreenArtifactIDs(screen)) {
+        placed.add(id);
+      }
+    }
+    const unplaced = all.filter((artifact) => !placed.has(artifact.id));
+    res.json({ artifacts: unplaced });
+  });
+  app.post("/artifacts", ...auth, (req, res) => {
+    const parsed = createArtifactBodySchema.safeParse(req.body);
+    if (!parsed.success) {
+      sendError(res, HTTP_BAD_REQUEST, parsed.error.issues[0]?.message ?? "Invalid request body");
+      return;
+    }
+    if (parsed.data.screenID !== void 0 && !store.getScreen(parsed.data.screenID)) {
+      sendError(res, HTTP_NOT_FOUND, `Screen not found: ${parsed.data.screenID}`);
+      return;
+    }
+    try {
+      const artifact = store.createArtifact({
+        type: parsed.data.type,
+        title: parsed.data.title,
+        externalFilePath: parsed.data.externalFilePath
+      });
+      const body = { artifact };
+      if (!artifact.externalFilePath) {
+        body.pendingPath = getArtifactPendingBundlePath(store.storagePath, artifact.id);
+      }
+      if (parsed.data.screenID !== void 0) {
+        const attachResult = store.attachArtifact({
+          screenID: parsed.data.screenID,
+          artifactID: artifact.id
+        });
+        body.attached = { screenID: attachResult.screenID, cardID: attachResult.cardID };
+      }
+      res.status(HTTP_CREATED).json(body);
+    } catch (error48) {
+      handleStoreError(res, error48, "Failed to create artifact");
+    }
+  });
+  app.delete("/artifacts/:id", ...auth, (req, res) => {
+    try {
+      const result = store.deleteArtifact(req.params.id);
+      res.json(result);
+    } catch (error48) {
+      handleStoreError(res, error48, "Failed to delete artifact");
+    }
+  });
+  app.post(
     "/screens/:screenID/artifacts/:artifactID",
     ...auth,
     (req, res) => {
       try {
-        const result = store.removeArtifactFromScreen(
-          req.params.artifactID,
-          req.params.screenID
-        );
+        const result = store.attachArtifact({
+          screenID: req.params.screenID,
+          artifactID: req.params.artifactID
+        });
         res.json(result);
       } catch (error48) {
-        handleStoreError(res, error48, "Failed to remove artifact");
+        handleStoreError(res, error48, "Failed to attach artifact");
       }
     }
   );
@@ -48238,6 +48397,41 @@ function registerRoutes(app, store, options) {
   app.put("/artifacts/:id/content/*", ...auth, (_req, res) => {
     sendError(res, HTTP_FORBIDDEN, "Only the primary content file is HTTP-writable");
   });
+  app.get("/viewer/state", ...auth, (_req, res) => {
+    res.json({
+      activeScreenID: store.getActiveScreenID(),
+      connectedClients: getConnectedClientCount()
+    });
+  });
+  app.put("/viewer/active-screen", ...auth, (req, res) => {
+    const parsed = setActiveScreenSchema.safeParse(req.body);
+    if (!parsed.success) {
+      sendError(res, HTTP_BAD_REQUEST, parsed.error.issues[0]?.message ?? "Invalid request body");
+      return;
+    }
+    try {
+      store.setActiveScreen(parsed.data.screenID);
+      res.status(HTTP_OK2).json({ activeScreenID: parsed.data.screenID });
+    } catch (error48) {
+      handleStoreError(res, error48, "Failed to set active screen");
+    }
+  });
+  app.post("/viewer/focus", ...auth, (req, res) => {
+    const parsed = focusSchema.safeParse(req.body);
+    if (!parsed.success) {
+      sendError(res, HTTP_BAD_REQUEST, parsed.error.issues[0]?.message ?? "Invalid request body");
+      return;
+    }
+    try {
+      const result = store.focus({
+        artifactID: parsed.data.artifactID,
+        ...parsed.data.screenID !== void 0 ? { screenID: parsed.data.screenID } : {}
+      });
+      res.status(HTTP_OK2).json(result);
+    } catch (error48) {
+      handleStoreError(res, error48, "Failed to focus artifact");
+    }
+  });
   const viewStaticHandlers = /* @__PURE__ */ new Map();
   const getViewStaticHandler = (id, viewDir) => {
     let handler = viewStaticHandlers.get(id);
@@ -48368,6 +48562,16 @@ var EventStreamServer = class extends withDisposable(class {
     });
     this.subscribeStore();
   }
+  /** Number of currently-open `/events` sockets. */
+  getConnectedClientCount() {
+    let count = 0;
+    for (const socket of this.wsServer.clients) {
+      if (socket.readyState === import_websocket.default.OPEN) {
+        count++;
+      }
+    }
+    return count;
+  }
   handleUpgrade(request, socket, head) {
     this.wsServer.handleUpgrade(request, socket, head, (ws) => {
       this.wsServer.emit("connection", ws, request);
@@ -48390,7 +48594,10 @@ var EventStreamServer = class extends withDisposable(class {
   }
   subscribeStore() {
     const onArtifactCreated = (event) => {
-      this.broadcast({ type: "artifact-created", screenID: event.screenID, artifact: event.artifact });
+      this.broadcast({ type: "artifact-created", artifact: event.artifact });
+    };
+    const onArtifactAttached = (event) => {
+      this.broadcast({ type: "artifact-attached", screenID: event.screenID, cardID: event.cardID, artifact: event.artifact });
     };
     const onArtifactUpdated = (event) => {
       this.broadcast({ type: "artifact-updated", artifact: event.artifact });
@@ -48410,21 +48617,33 @@ var EventStreamServer = class extends withDisposable(class {
     const onScreenRemoved = (event) => {
       this.broadcast({ type: "screen-removed", screenID: event.screenID });
     };
+    const onViewerActiveScreenChanged = (event) => {
+      this.broadcast({ type: "viewer-active-screen-changed", screenID: event.screenID });
+    };
+    const onViewerFocus = (event) => {
+      this.broadcast({ type: "viewer-focus", screenID: event.screenID, artifactID: event.artifactID });
+    };
     this.store.addEventListener("artifact-created", onArtifactCreated);
+    this.store.addEventListener("artifact-attached", onArtifactAttached);
     this.store.addEventListener("artifact-updated", onArtifactUpdated);
     this.store.addEventListener("artifact-removed", onArtifactRemoved);
     this.store.addEventListener("artifact-content-changed", onArtifactContentChanged);
     this.store.addEventListener("screen-created", onScreenCreated);
     this.store.addEventListener("screen-updated", onScreenUpdated);
     this.store.addEventListener("screen-removed", onScreenRemoved);
+    this.store.addEventListener("viewer-active-screen-changed", onViewerActiveScreenChanged);
+    this.store.addEventListener("viewer-focus", onViewerFocus);
     this.unsubscribe.push(
       () => this.store.removeEventListener("artifact-created", onArtifactCreated),
+      () => this.store.removeEventListener("artifact-attached", onArtifactAttached),
       () => this.store.removeEventListener("artifact-updated", onArtifactUpdated),
       () => this.store.removeEventListener("artifact-removed", onArtifactRemoved),
       () => this.store.removeEventListener("artifact-content-changed", onArtifactContentChanged),
       () => this.store.removeEventListener("screen-created", onScreenCreated),
       () => this.store.removeEventListener("screen-updated", onScreenUpdated),
-      () => this.store.removeEventListener("screen-removed", onScreenRemoved)
+      () => this.store.removeEventListener("screen-removed", onScreenRemoved),
+      () => this.store.removeEventListener("viewer-active-screen-changed", onViewerActiveScreenChanged),
+      () => this.store.removeEventListener("viewer-focus", onViewerFocus)
     );
   }
   broadcast(event) {
@@ -48707,13 +48926,14 @@ var Server = class {
       res.json({ status: "ok" });
     });
     this.app.use(import_express2.default.json());
+    this.events = new EventStreamServer({ store: this.store, publicServer: this.publicServer });
     registerRoutes(this.app, this.store, {
-      requireAuth: this.publicServer ? null : this.requireAuthorization
+      requireAuth: this.publicServer ? null : this.requireAuthorization,
+      getConnectedClientCount: () => this.events.getConnectedClientCount()
     });
     if (options.staticDir) {
       this.app.use(import_express2.default.static(options.staticDir));
     }
-    this.events = new EventStreamServer({ store: this.store, publicServer: this.publicServer });
     this.acp = new ACPServer({ authToken: this.store.authToken, publicServer: this.publicServer });
     this.httpServer.on("upgrade", (request, socket, head) => {
       const parsed = new URL(request.url ?? "/", this.baseURL);
@@ -48805,6 +49025,7 @@ var ServerStore = class extends EventTarget {
   storagePath;
   authToken;
   screens = /* @__PURE__ */ new Map();
+  activeScreenID = null;
   _artifacts = /* @__PURE__ */ new Map();
   contentWatchers = /* @__PURE__ */ new Map();
   contentWatchDebounceTimers = /* @__PURE__ */ new Map();
@@ -48820,6 +49041,7 @@ var ServerStore = class extends EventTarget {
     this.views = this.scanViewRegistry();
     this.authToken = this.loadOrCreateAuthToken();
     this.load();
+    this.loadViewerState();
     this.startContentWatchersForLoadedArtifacts();
     if (this.screens.size === 0) {
       this.createDefaultScreen();
@@ -48940,8 +49162,15 @@ var ServerStore = class extends EventTarget {
   listArtifacts() {
     return [...this._artifacts.values()];
   }
+  /**
+   * Create a new artifact. When `screenID` is supplied, the artifact is also
+   * attached to that screen as a convenience: a card is appended to the strip
+   * end and an `artifact-attached` event follows the `artifact-created` event.
+   * When `screenID` is omitted, the artifact is created standalone — no screen
+   * mutation, no `artifact-attached` event.
+   */
   createArtifact(input) {
-    const screen = this.requireScreen(input.screenID);
+    const screen = input.screenID !== void 0 ? this.requireScreen(input.screenID) : null;
     const artifact = createArtifact({
       type: input.type,
       title: input.title,
@@ -48956,14 +49185,19 @@ var ServerStore = class extends EventTarget {
     if (artifact.status === "committed") {
       this.startWatchingArtifactContent(artifact.id);
     }
-    screen.layout = [...screen.layout, createCardNode(artifact.id)];
-    this.persistScreen(screen);
-    this.dispatchEvent(
-      new ArtifactCreatedEvent("artifact-created", {
-        screenID: screen.id,
-        artifact
-      })
-    );
+    this.dispatchEvent(new ArtifactCreatedEvent("artifact-created", { artifact }));
+    if (screen) {
+      const card = createCardNode(artifact.id);
+      screen.layout = [...screen.layout, card];
+      this.persistScreen(screen);
+      this.dispatchEvent(
+        new ArtifactAttachedEvent("artifact-attached", {
+          screenID: screen.id,
+          cardID: card.id,
+          artifact
+        })
+      );
+    }
     return artifact;
   }
   updateArtifact(input) {
@@ -49049,18 +49283,93 @@ var ServerStore = class extends EventTarget {
     this.dispatchEvent(new ArtifactUpdatedEvent("artifact-updated", { artifact }));
   }
   /**
-   * Remove an artifact reference from a single screen.
+   * Attach an existing artifact to a screen by appending a default-sized
+   * card to the right end of the strip. Idempotent: if the artifact is
+   * already on the screen, returns the existing card and emits no event.
    *
-   * - If other screens still reference the artifact, only the screen
-   *   layout is stripped; no disk content is touched. Result: `unlinked`.
-   * - If this was the last reference, the artifact cascades through the
-   *   same trash/discard rules as before (committed → trashed, pending-create
-   *   → discarded, external → metadata-only trashed). Result mirrors the
-   *   committed/external/pending-create variant.
+   * Throws `NotFoundError` when the screen or artifact does not exist.
+   */
+  attachArtifact(input) {
+    const screen = this.requireScreen(input.screenID);
+    const artifact = this._artifacts.get(input.artifactID);
+    if (!artifact) {
+      throw new NotFoundError(`Artifact not found: ${input.artifactID}`, {
+        entityType: "artifact",
+        entityID: input.artifactID
+      });
+    }
+    const existingCardID = findCardIDForArtifact(screen.layout, input.artifactID);
+    if (existingCardID !== null) {
+      return { screenID: screen.id, cardID: existingCardID, artifact };
+    }
+    const card = createCardNode(input.artifactID);
+    screen.layout = [...screen.layout, card];
+    this.persistScreen(screen);
+    this.dispatchEvent(
+      new ArtifactAttachedEvent("artifact-attached", {
+        screenID: screen.id,
+        cardID: card.id,
+        artifact
+      })
+    );
+    return { screenID: screen.id, cardID: card.id, artifact };
+  }
+  /**
+   * Detach an artifact reference from a single screen. Layout-only — the
+   * artifact metadata, bundle, and pending state are never touched, even
+   * when this is the last screen referencing it. Use `deleteArtifact` to
+   * actually remove an artifact.
    *
    * Throws `NotFoundError` when the screen does not exist, the artifact
    * does not exist, or the artifact is not a member of the screen.
    */
+  detachArtifact(input) {
+    const screen = this.requireScreen(input.screenID);
+    const artifact = this._artifacts.get(input.artifactID);
+    if (!artifact) {
+      throw new NotFoundError(`Artifact not found: ${input.artifactID}`, {
+        entityType: "artifact",
+        entityID: input.artifactID
+      });
+    }
+    if (!layoutContainsArtifactID(screen.layout, input.artifactID)) {
+      throw new NotFoundError(
+        `Artifact ${input.artifactID} is not a member of screen ${input.screenID}`,
+        { entityType: "artifact", entityID: input.artifactID }
+      );
+    }
+    screen.layout = removeArtifactFromLayout(screen.layout, input.artifactID);
+    this.persistScreen(screen);
+    this.dispatchEvent(
+      new ArtifactRemovedEvent("artifact-removed", {
+        artifactID: input.artifactID,
+        screenID: input.screenID
+      })
+    );
+    return { screenID: input.screenID, artifactID: input.artifactID };
+  }
+  /**
+   * Globally remove an artifact: strip every referencing card from every
+   * screen (firing one `artifact-removed` per affected screen), then trash
+   * the bundle (committed internal), forget the pointer (external), or
+   * discard live state (pending-create internal).
+   *
+   * Throws `NotFoundError` when the artifact does not exist.
+   */
+  deleteArtifact(artifactID) {
+    const artifact = this._artifacts.get(artifactID);
+    if (!artifact) {
+      throw new NotFoundError(`Artifact not found: ${artifactID}`, { entityType: "artifact", entityID: artifactID });
+    }
+    return this.cascadeArtifactRemoval(artifactID);
+  }
+  /**
+   * Internal helper used by `removeScreen` to cascade per-artifact
+   * cleanup with the same legacy-shaped result so existing screen-removal
+   * tests continue to pin the user-visible "delete a screen, lose its
+   * orphaned artifacts" behavior. New callers should use `detachArtifact`
+   * or `deleteArtifact` directly.
+   */
   removeArtifactFromScreen(artifactID, screenID) {
     const screen = this.requireScreen(screenID);
     const artifact = this._artifacts.get(artifactID);
@@ -49075,11 +49384,7 @@ var ServerStore = class extends EventTarget {
     }
     const referencingScreenIDs = this.collectReferencingScreenIDs(artifactID);
     if (referencingScreenIDs.some((id) => id !== screenID)) {
-      screen.layout = removeArtifactFromLayout(screen.layout, artifactID);
-      this.persistScreen(screen);
-      this.dispatchEvent(
-        new ArtifactRemovedEvent("artifact-removed", { artifactID, screenID })
-      );
+      this.detachArtifact({ screenID, artifactID });
       return { outcome: "unlinked", artifactID };
     }
     return this.cascadeArtifactRemoval(artifactID);
@@ -49103,6 +49408,79 @@ var ServerStore = class extends EventTarget {
     this.dispatchEvent(new ScreenUpdatedEvent("screen-updated", { screen }));
     return screen;
   }
+  /**
+   * The screen that Television's GUI is currently focused on, or `null` if
+   * no client has set one. Drift-tolerant: if the persisted ID points at a
+   * screen that no longer exists, returns `null` rather than the stale ID.
+   */
+  getActiveScreenID() {
+    if (this.activeScreenID && !this.screens.has(this.activeScreenID)) {
+      return null;
+    }
+    return this.activeScreenID;
+  }
+  setActiveScreen(screenID) {
+    this.requireScreen(screenID);
+    if (this.activeScreenID === screenID) {
+      return;
+    }
+    this.activeScreenID = screenID;
+    this.persistViewerState();
+    this.dispatchEvent(
+      new ViewerActiveScreenChangedEvent("viewer-active-screen-changed", { screenID })
+    );
+  }
+  /**
+   * Resolve a target screen for `artifactID` (preferring an explicit
+   * `screenID`, then the current active screen, then any screen referencing
+   * the artifact), flip the active screen if necessary, then broadcast a
+   * `viewer-focus` event for clients to scroll-and-highlight.
+   *
+   * Throws `NotFoundError` for missing artifact or unknown explicit screen,
+   * `InvalidRequestError` if the artifact is not attached to an explicitly
+   * named screen, and `ConflictError` if no `screenID` was supplied and the
+   * artifact is attached to no screens.
+   */
+  focus(input) {
+    const artifact = this._artifacts.get(input.artifactID);
+    if (!artifact) {
+      throw new NotFoundError(`Artifact not found: ${input.artifactID}`, {
+        entityType: "artifact",
+        entityID: input.artifactID
+      });
+    }
+    let target;
+    if (input.screenID !== void 0) {
+      const screen = this.requireScreen(input.screenID);
+      if (!layoutContainsArtifactID(screen.layout, input.artifactID)) {
+        throw new InvalidRequestError(
+          `Artifact ${input.artifactID} is not attached to screen ${input.screenID}`
+        );
+      }
+      target = screen.id;
+    } else {
+      const active = this.getActiveScreenID();
+      const activeScreen = active ? this.screens.get(active) : void 0;
+      if (activeScreen && layoutContainsArtifactID(activeScreen.layout, input.artifactID)) {
+        target = activeScreen.id;
+      } else {
+        const referencing = this.collectReferencingScreenIDs(input.artifactID);
+        if (referencing.length === 0) {
+          throw new ConflictError(
+            `Artifact ${input.artifactID} is not attached to any screen; cannot focus`
+          );
+        }
+        target = referencing[0];
+      }
+    }
+    if (this.activeScreenID !== target) {
+      this.setActiveScreen(target);
+    }
+    this.dispatchEvent(
+      new ViewerFocusEvent("viewer-focus", { screenID: target, artifactID: input.artifactID })
+    );
+    return { screenID: target, artifactID: input.artifactID };
+  }
   removeScreen(screenID) {
     const screen = this.requireScreen(screenID);
     const snapshot = { ...screen, layout: structuredClone(screen.layout) };
@@ -49387,6 +49765,35 @@ var ServerStore = class extends EventTarget {
     registry2.sort((a, b) => a.id.localeCompare(b.id));
     return registry2;
   }
+  loadViewerState() {
+    if (!(0, import_node_fs3.existsSync)(this.viewerStatePath)) {
+      return;
+    }
+    let raw;
+    try {
+      raw = (0, import_node_fs3.readFileSync)(this.viewerStatePath, "utf8");
+    } catch {
+      return;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return;
+    }
+    if (parsed && typeof parsed === "object" && "activeScreenID" in parsed && (typeof parsed.activeScreenID === "string" || parsed.activeScreenID === null)) {
+      this.activeScreenID = parsed.activeScreenID;
+    }
+  }
+  persistViewerState() {
+    (0, import_node_fs3.writeFileSync)(
+      this.viewerStatePath,
+      JSON.stringify({ activeScreenID: this.activeScreenID }, null, JSON_INDENT_SPACES)
+    );
+  }
+  get viewerStatePath() {
+    return import_node_path6.default.join(this.storagePath, "viewer.json");
+  }
   loadOrCreateAuthToken() {
     if ((0, import_node_fs3.existsSync)(this.tokenPath)) {
       return (0, import_node_fs3.readFileSync)(this.tokenPath, "utf8").trim();
@@ -49551,6 +49958,30 @@ Review docs/storage.md for the current schema, and either update the file to mat
     return import_node_path6.default.join(this.storagePath, "token");
   }
 };
+function findCardIDForArtifact(layout, artifactID) {
+  for (const node of layout) {
+    const id = findCardIDInNode(node, artifactID);
+    if (id !== null) return id;
+  }
+  return null;
+}
+function findCardIDInNode(node, artifactID) {
+  switch (node.type) {
+    case "card":
+      return node.artifactID === artifactID ? node.id : null;
+    case "row":
+      for (const child of node.children) {
+        if (child.artifactID === artifactID) return child.id;
+      }
+      return null;
+    case "stack":
+      for (const child of node.children) {
+        const id = findCardIDInNode(child, artifactID);
+        if (id !== null) return id;
+      }
+      return null;
+  }
+}
 
 // src/index.ts
 var import_meta = {};
@@ -49579,8 +50010,8 @@ function getDevPackageDir() {
   return import_node_path7.default.resolve(import_node_path7.default.dirname((0, import_node_url.fileURLToPath)(import_meta.url)), "..");
 }
 function readCLIVersion() {
-  if ("0.1.47".length > 0) {
-    return "0.1.47";
+  if ("0.1.48".length > 0) {
+    return "0.1.48";
   }
   const devPackageJsonPath = import_node_path7.default.join(getDevPackageDir(), "package.json");
   if (!(0, import_node_fs4.existsSync)(devPackageJsonPath)) {
@@ -49589,8 +50020,8 @@ function readCLIVersion() {
   return JSON.parse((0, import_node_fs4.readFileSync)(devPackageJsonPath, "utf8")).version;
 }
 function readWorkflowHelpText() {
-  if ('# Television\n\nTelevision is a persistent artifact screen for agents. Use it when the user\nshould be able to inspect, revisit, and refine a file-backed result instead of\nonly reading a chat reply.\n\nIf you lose context, run:\n\n```bash\ntv help\n```\n\nThat command prints this full skill as one blob. There is no topic-scoped help\nin the current implementation.\n\n## Mental model\n\n- A **screen** is the screen and layout container.\n- An **artifact** is one displayed result on that screen.\n- An **internal artifact** is a Television-managed bundle. You create a pending\n  bundle, edit files in that bundle, then commit it.\n- An **external artifact** is a pointer to an existing absolute file on disk.\n  Television displays that file but does not own or delete it.\n- **Pending** means a create or edit is staged but not yet committed.\n- **Trash** means metadata and committed internal bundles moved out of the live\n  tree. There is no restore workflow in the current scope.\n\nThe core workflow is:\n\n1. Decide whether the result should be internal or external.\n2. Create or stage the artifact with the CLI.\n3. For internal artifacts, edit files in the pending bundle.\n4. Commit when the validation rules are satisfied.\n\n## User communication during multi-step workflows\n\nWhen you are doing a multi-step artifact workflow, keep the user informed as you\nprogress.\n\nRequired communication style:\n\n- verbalize key actions and decisions as they happen\n- keep the language concise\n- prefer short updates over long explanations\n- frame updates in the user\'s world and goals, not in the internal mechanics of the skill or CLI workflow\n- avoid technical workflow jargon unless the user explicitly asks for it\n- do not write reports, long paragraphs, or chatty summaries while the work is in progress\n- do not use lists unless the user explicitly asks for one\n- optimize for speed and token efficiency\n\nGood examples:\n\n- "Starting the artifact now."\n- "Reviewing the draft and source material."\n- "Updating the HTML and efficiently navigating the artifact creation flow."\n- "The artifact did not pass validation yet; fixing the draft notes and retrying."\n- "Finalizing the artifact now."\n- "Done."\n\nBad examples:\n\n- multi-paragraph progress reports\n- long retrospective narration during execution\n- verbose bullet lists for routine workflow steps\n\n## Internal versus external\n\nUse an **internal artifact** when:\n\n- the artifact is purpose-built for Television\n- Television should own the bundle structure\n- future agents should be able to maintain the result by reading bundle files\n- you need a staged create or staged edit workflow\n\nUse an **external artifact** when:\n\n- a real file already exists on disk\n- the user wants Television to display that existing file\n- you do not need a Television-managed bundle\n\nDecision rule:\n\n- If the result should be maintained as a Television-owned long-lived artifact,\n  choose internal.\n- If the result is already a real file outside Television and should stay that\n  way, choose external.\n\nSupported artifact types:\n\n- `text/markdown`\n- `text/html`\n\n## Internal bundle files\n\nEvery internal artifact bundle contains:\n\n- `artifact.md`\n- `data.json`\n- `memory.md`\n- `public/index.md` or `public/index.html`\n\nFresh pending bundles are intentionally minimal:\n\n- `artifact.md` is blank\n- `memory.md` is blank\n- `public/index.md` or `public/index.html` is blank\n- `data.json` is exactly `{}`\n\nThe scaffold is not commit-valid by itself. Learn the required structure from\nthis skill, not from placeholder content in the scaffold.\n\n### `artifact.md`\n\n`artifact.md` is the contract for the artifact. It explains what the artifact\nis for, what conceptual material it is based on, how it should render, and how\nlater agents should maintain it.\n\nBefore commit, `artifact.md` must be non-empty and contain all of these exact\nheadings:\n\n```md\n## User intent\n## Purpose\n## Data shape\n## Data sources\n## Rendering\n## Update workflow\n## Non-goals\n```\n\nWhat each section should capture:\n\n- `## User intent`: faithful restatement or quotation of what the user actually said they wanted; this is critical and should preserve the user\'s language as closely as practical, including requests, feedback, complaints, constraints, and guidance\n- `## Purpose`: what the artifact is trying to achieve\n- `## Data shape`: the conceptual shape you reasoned about while authoring; for markdown artifacts this will often just be `{}`\n- `## Data sources`: where the underlying facts, notes, or source material came from and how they were obtained\n- `## Rendering`: how `public/index.md` or `public/index.html` should present it\n- `## Update workflow`: how future agents should refresh or modify it\n- `## Non-goals`: what is intentionally excluded, especially application-like runtime behavior\n\n### `data.json`\n\n`data.json` is a **thinking artifact**, not a runtime payload.\n\nIts purpose is to help the model separate:\n\n- reasoning / planning / authoring structure\n- from final presentation in `public/index.md` or `public/index.html`\n\nUse it to capture the pure conceptual shape of what you are about to render.\nThis is an authoring aid for agents, not an application data layer.\n\nHard rules:\n\n- **Do not treat `data.json` as live runtime state.**\n- **Do not write HTML/JS that loads, depends on, or synchronizes against `data.json`.**\n- **Do not build application-like data-driven artifacts.**\n- **We do not support runtime data-backed artifacts at this time.**\n- Artifacts are static markdown or static HTML documents.\n- HTML artifacts may include JavaScript and extra assets under `public/`, but\n  that JavaScript must stay presentation-oriented and self-contained, not\n  driven by `data.json` as an application state container.\n\nFor `text/markdown` artifacts, leave `data.json` as exactly:\n\n```json\n{}\n```\n\nThere is usually little value in separating content from presentation for\nmarkdown artifacts, so prefer `{}` unless there is a very strong authoring\nreason not to.\n\nFor `text/html` artifacts, use `data.json` only when it helps you think clearly\nabout the material before rendering. It may describe the conceptual structure\nof the artifact, but it must not become a runtime contract.\n\nValidation rule:\n\n- `data.json` must exist and contain valid JSON\n\nThe current validator does not require the JSON value to be an object, but an\nobject is the normal choice.\n\n### `memory.md`\n\n`memory.md` is the working scratchpad for later agents. Record decisions,\nlimitations, data-retrieval notes, problems encountered, what changed, and what\nshould be watched during future edits.\n\nRequired validation anchors:\n\n- `memory.md` must contain `## Activity Log`\n- `memory.md` must contain at least one UTC timestamp in exact\n  `YYYY-MM-DDTHH:MM:SSZ` format\n- at least one timestamp must be from the last 30 minutes when you commit\n\nThe minimum required heading is:\n\n```md\n## Activity Log\n```\n\nWhat to record beyond that is up to the artifact and the work performed.\n\n### `public/index.md` and `public/index.html`\n\nThis is the rendered entry file that Television serves.\n\n- Markdown artifacts use `public/index.md`\n- HTML artifacts use `public/index.html`\n- the entry file must match the artifact `type`\n- the entry file must be non-empty before commit\n\nFor HTML artifacts:\n\n- `public/index.html` is a full HTML document, not a body fragment\n- additional public assets may live under `public/`\n- keep paths relative to `public/`\n\n## Quality bar\n\nBuild artifacts that are durable, truthful, and maintainable by later agents.\n\nRequired quality standards:\n\n- be faithful to source data\n- do not invent or hallucinate missing facts\n- do not silently truncate a dataset and pretend it is complete\n- prefer truth over completeness when those goals conflict\n- make limitations, sampling, missing data, and freshness visible\n- keep rendering aligned with the reasoning captured in `artifact.md`, `data.json`, and `memory.md`\n- keep `data.json` as an authoring/thinking artifact rather than a runtime dependency\n- keep the artifact maintainable by a future agent reading only the bundle files\n\nAnti-patterns:\n\n- cursory or low-effort data collection\n- fake data added to make the artifact look complete\n- brittle one-off hacks that a later agent cannot reproduce\n- hidden dependencies that are not documented in `artifact.md` or `memory.md`\n- layout churn during simple data refreshes when the data model did not change\n\n## HTML house style\n\nHTML artifacts should feel intentional and readable inside Television tiles.\n\nTelevision provides a full base stylesheet for HTML artifacts. Only add custom\nCSS when you need something not covered by the built-in styles. Prefer the base\nstyles and theme tokens so artifacts stay visually coherent with the rest of\nTelevision.\n\nHouse-style guidance:\n\n- use semantic HTML first\n- keep the most important information near the top\n- design for small, medium, and large tile sizes\n- avoid horizontal overflow unless there is no reasonable alternative\n- make empty states and error states explicit\n- prefer the built-in HTML styling before inventing custom component chrome\n\n### Elements\n\nStandard elements already have sensible defaults, so you usually do not need to\nstyle from scratch:\n\n- headings (`h1`\u2013`h6`) \u2014 sized and weighted\n- `p`, `ul`, `ol` \u2014 readable defaults\n- `code` and `pre` \u2014 monospace, muted background\n- `blockquote` \u2014 left border, muted text\n- `table`, `th`, `td` \u2014 bordered, striped headers\n- `button` \u2014 styled with border and hover state; use `size="sm"` or `size="md"` when appropriate\n- `hr` \u2014 subtle border\n- `a` \u2014 inherits color by default\n\n### `.prose` class\n\nUse a `.prose` wrapper for document-style HTML where readable vertical rhythm is\nappropriate. Do not rely on `.prose` for dashboards, tables, control surfaces,\nor dense custom layouts.\n\n```html\n<div class="prose">\n  <h1>Title</h1>\n  <p>Some content with proper spacing between elements.</p>\n  <ul>\n    <li>Item one</li>\n    <li>Item two</li>\n  </ul>\n</div>\n```\n\n### CSS variables\n\nUse the existing Television tokens when they are available in the runtime.\nThese are the preferred way to stay aligned with the app theme.\n\nColors:\n- `--color-bg` \u2014 page background\n- `--color-bg-muted` \u2014 subtle background\n- `--color-surface` \u2014 card or panel background\n- `--color-text` \u2014 primary text\n- `--color-text-muted` \u2014 secondary or label text\n- `--color-border` \u2014 border color\n\nSpacing:\n- `--space-4`\n- `--space-8`\n- `--space-12`\n- `--space-16`\n- `--space-24`\n- `--space-32`\n\nFonts:\n- `--font-sans`\n- `--font-mono`\n\nText sizes:\n- `--text-sm`\n- `--text-base`\n- `--text-lg`\n- `--text-xl`\n\nRadius:\n- `--radius-4`\n- `--radius-8`\n\n## Workflows\n\n### Create new internal artifact\n\n1. Decide that the result should be an internal artifact.\n2. Start the pending bundle:\n\n```bash\ntv create-internal-artifact --screen "<screen-id>" --type text/markdown --title "Artifact title"\n```\n\nOr:\n\n```bash\ntv create-internal-artifact --screen "<screen-id>" --type text/html --title "Artifact title"\n```\n\n3. Read the returned pending path and edit files there.\n4. Write `artifact.md`.\n5. In `artifact.md`, capture the user\'s language faithfully in `## User intent` before doing the rest of the authoring work. Use direct quotes when helpful, or a close paraphrase when that is clearer, but keep it representative of what the user actually said they wanted.\n6. Think through the artifact in a pure way and write `data.json` only as an authoring aid.\n7. For markdown artifacts, leave `data.json` as `{}` unless there is a compelling authoring reason not to.\n8. Render `public/index.md` or `public/index.html`.\n9. Append a current timestamped activity entry in `memory.md`.\n10. Commit:\n\n```bash\ntv commit-pending-artifact --id "<artifact-id>"\n```\n\n### Update internal artifact with fresh data\n\n1. Stage the edit:\n\n```bash\ntv edit-internal-artifact --id "<artifact-id>"\n```\n\n2. Read `artifact.md`, `data.json`, and `memory.md` before changing anything.\n3. Refresh the underlying facts or source material.\n4. Update `data.json` only if it helps clarify the authoring plan.\n5. For markdown artifacts, prefer to keep `data.json` as `{}`.\n6. Make the minimum rendering changes needed to keep the artifact correct.\n7. Record what changed in `memory.md`.\n8. Commit:\n\n```bash\ntv commit-pending-artifact --id "<artifact-id>"\n```\n\nAvoid unnecessary layout or styling churn during data-only refreshes.\n\n### Modify internal artifact from user feedback\n\n1. Stage the edit:\n\n```bash\ntv edit-internal-artifact --id "<artifact-id>"\n```\n\n2. Read `artifact.md`, `data.json`, and `memory.md`.\n3. Update `artifact.md` if the user intent or non-goals changed.\n4. When the user has added feedback, complaints, corrections, or new guidance, update `## User intent` so it remains a faithful record of what the user actually wants now. Preserve the user\'s language as closely as practical, using direct quotes or close paraphrases.\n5. Update `data.json` only if it improves the authoring model of the artifact.\n6. For markdown artifacts, prefer to keep `data.json` as `{}`.\n7. Adjust `public/index.md` or `public/index.html` as narrowly as possible.\n8. Record the request, decision, and resulting change in `memory.md`.\n9. Commit:\n\n```bash\ntv commit-pending-artifact --id "<artifact-id>"\n```\n\n### Abandon pending work\n\nIf the staged work should be discarded instead of committed:\n\n```bash\ntv abandon-pending-artifact --id "<artifact-id>"\n```\n\n### Create external artifact\n\nUse this when the file already exists on disk and Television should display it\nwithout owning a bundle:\n\n```bash\ntv create-external-artifact --screen "<screen-id>" --type text/markdown --title "Artifact title" --path /absolute/path/to/file.md\n```\n\nOr:\n\n```bash\ntv create-external-artifact --screen "<screen-id>" --type text/html --title "Artifact title" --path /absolute/path/to/file.html\n```\n\nRules:\n\n- `--path` must be absolute\n- the file must already exist and be readable\n- the extension must match `type`\n- external artifacts do not use pending create, pending edit, commit, or abandon\n\n## CLI reference\n\nWorkflow commands:\n\n```bash\ntv create-internal-artifact --screen "<screen-id>" --type <text/markdown|text/html> --title "Artifact title"\ntv edit-internal-artifact --id "<artifact-id>"\ntv commit-pending-artifact --id "<artifact-id>"\ntv abandon-pending-artifact --id "<artifact-id>"\ntv create-external-artifact --screen "<screen-id>" --type <text/markdown|text/html> --title "Artifact title" --path /absolute/path\ntv update-artifact --id "<artifact-id>" --title "New title"\ntv remove-artifact --id "<artifact-id>" --screen "<screen-id>"\ntv remove-screen --id "<screen-id>"\n```\n\nRead and server commands:\n\n```bash\ntv list-screens\ntv get-screen --id "<screen-id>"\ntv create-screen --name "Screen name"\ntv storage-path\ntv status\ntv serve\ntv stop\n```\n\nCLI behavior notes:\n\n- workflow and mutation commands print plain text\n- read commands print JSON\n- `tv get-screen` includes artifact `kind` and `status`\n- `tv remove-artifact` removes the artifact reference from the named screen; if another screen still references it, the artifact is unlinked and kept alive; otherwise it cascades to trash/discard\n- `tv update-artifact` changes title metadata only\n- when the CLI reports an error, follow the directive to run `tv help`\n\n## Deferred or out of scope\n\nThese are not part of the current implementation:\n\n- `tv help <topic>`\n- restore-from-trash\n- pending-listing commands\n- attestation or nonce commands\n- stale pending cleanup or stale trash cleanup\n- markdown editor UI recovery\n- client-side pending presentation work\n- multi-section help output'.length > 0) {
-    return '# Television\n\nTelevision is a persistent artifact screen for agents. Use it when the user\nshould be able to inspect, revisit, and refine a file-backed result instead of\nonly reading a chat reply.\n\nIf you lose context, run:\n\n```bash\ntv help\n```\n\nThat command prints this full skill as one blob. There is no topic-scoped help\nin the current implementation.\n\n## Mental model\n\n- A **screen** is the screen and layout container.\n- An **artifact** is one displayed result on that screen.\n- An **internal artifact** is a Television-managed bundle. You create a pending\n  bundle, edit files in that bundle, then commit it.\n- An **external artifact** is a pointer to an existing absolute file on disk.\n  Television displays that file but does not own or delete it.\n- **Pending** means a create or edit is staged but not yet committed.\n- **Trash** means metadata and committed internal bundles moved out of the live\n  tree. There is no restore workflow in the current scope.\n\nThe core workflow is:\n\n1. Decide whether the result should be internal or external.\n2. Create or stage the artifact with the CLI.\n3. For internal artifacts, edit files in the pending bundle.\n4. Commit when the validation rules are satisfied.\n\n## User communication during multi-step workflows\n\nWhen you are doing a multi-step artifact workflow, keep the user informed as you\nprogress.\n\nRequired communication style:\n\n- verbalize key actions and decisions as they happen\n- keep the language concise\n- prefer short updates over long explanations\n- frame updates in the user\'s world and goals, not in the internal mechanics of the skill or CLI workflow\n- avoid technical workflow jargon unless the user explicitly asks for it\n- do not write reports, long paragraphs, or chatty summaries while the work is in progress\n- do not use lists unless the user explicitly asks for one\n- optimize for speed and token efficiency\n\nGood examples:\n\n- "Starting the artifact now."\n- "Reviewing the draft and source material."\n- "Updating the HTML and efficiently navigating the artifact creation flow."\n- "The artifact did not pass validation yet; fixing the draft notes and retrying."\n- "Finalizing the artifact now."\n- "Done."\n\nBad examples:\n\n- multi-paragraph progress reports\n- long retrospective narration during execution\n- verbose bullet lists for routine workflow steps\n\n## Internal versus external\n\nUse an **internal artifact** when:\n\n- the artifact is purpose-built for Television\n- Television should own the bundle structure\n- future agents should be able to maintain the result by reading bundle files\n- you need a staged create or staged edit workflow\n\nUse an **external artifact** when:\n\n- a real file already exists on disk\n- the user wants Television to display that existing file\n- you do not need a Television-managed bundle\n\nDecision rule:\n\n- If the result should be maintained as a Television-owned long-lived artifact,\n  choose internal.\n- If the result is already a real file outside Television and should stay that\n  way, choose external.\n\nSupported artifact types:\n\n- `text/markdown`\n- `text/html`\n\n## Internal bundle files\n\nEvery internal artifact bundle contains:\n\n- `artifact.md`\n- `data.json`\n- `memory.md`\n- `public/index.md` or `public/index.html`\n\nFresh pending bundles are intentionally minimal:\n\n- `artifact.md` is blank\n- `memory.md` is blank\n- `public/index.md` or `public/index.html` is blank\n- `data.json` is exactly `{}`\n\nThe scaffold is not commit-valid by itself. Learn the required structure from\nthis skill, not from placeholder content in the scaffold.\n\n### `artifact.md`\n\n`artifact.md` is the contract for the artifact. It explains what the artifact\nis for, what conceptual material it is based on, how it should render, and how\nlater agents should maintain it.\n\nBefore commit, `artifact.md` must be non-empty and contain all of these exact\nheadings:\n\n```md\n## User intent\n## Purpose\n## Data shape\n## Data sources\n## Rendering\n## Update workflow\n## Non-goals\n```\n\nWhat each section should capture:\n\n- `## User intent`: faithful restatement or quotation of what the user actually said they wanted; this is critical and should preserve the user\'s language as closely as practical, including requests, feedback, complaints, constraints, and guidance\n- `## Purpose`: what the artifact is trying to achieve\n- `## Data shape`: the conceptual shape you reasoned about while authoring; for markdown artifacts this will often just be `{}`\n- `## Data sources`: where the underlying facts, notes, or source material came from and how they were obtained\n- `## Rendering`: how `public/index.md` or `public/index.html` should present it\n- `## Update workflow`: how future agents should refresh or modify it\n- `## Non-goals`: what is intentionally excluded, especially application-like runtime behavior\n\n### `data.json`\n\n`data.json` is a **thinking artifact**, not a runtime payload.\n\nIts purpose is to help the model separate:\n\n- reasoning / planning / authoring structure\n- from final presentation in `public/index.md` or `public/index.html`\n\nUse it to capture the pure conceptual shape of what you are about to render.\nThis is an authoring aid for agents, not an application data layer.\n\nHard rules:\n\n- **Do not treat `data.json` as live runtime state.**\n- **Do not write HTML/JS that loads, depends on, or synchronizes against `data.json`.**\n- **Do not build application-like data-driven artifacts.**\n- **We do not support runtime data-backed artifacts at this time.**\n- Artifacts are static markdown or static HTML documents.\n- HTML artifacts may include JavaScript and extra assets under `public/`, but\n  that JavaScript must stay presentation-oriented and self-contained, not\n  driven by `data.json` as an application state container.\n\nFor `text/markdown` artifacts, leave `data.json` as exactly:\n\n```json\n{}\n```\n\nThere is usually little value in separating content from presentation for\nmarkdown artifacts, so prefer `{}` unless there is a very strong authoring\nreason not to.\n\nFor `text/html` artifacts, use `data.json` only when it helps you think clearly\nabout the material before rendering. It may describe the conceptual structure\nof the artifact, but it must not become a runtime contract.\n\nValidation rule:\n\n- `data.json` must exist and contain valid JSON\n\nThe current validator does not require the JSON value to be an object, but an\nobject is the normal choice.\n\n### `memory.md`\n\n`memory.md` is the working scratchpad for later agents. Record decisions,\nlimitations, data-retrieval notes, problems encountered, what changed, and what\nshould be watched during future edits.\n\nRequired validation anchors:\n\n- `memory.md` must contain `## Activity Log`\n- `memory.md` must contain at least one UTC timestamp in exact\n  `YYYY-MM-DDTHH:MM:SSZ` format\n- at least one timestamp must be from the last 30 minutes when you commit\n\nThe minimum required heading is:\n\n```md\n## Activity Log\n```\n\nWhat to record beyond that is up to the artifact and the work performed.\n\n### `public/index.md` and `public/index.html`\n\nThis is the rendered entry file that Television serves.\n\n- Markdown artifacts use `public/index.md`\n- HTML artifacts use `public/index.html`\n- the entry file must match the artifact `type`\n- the entry file must be non-empty before commit\n\nFor HTML artifacts:\n\n- `public/index.html` is a full HTML document, not a body fragment\n- additional public assets may live under `public/`\n- keep paths relative to `public/`\n\n## Quality bar\n\nBuild artifacts that are durable, truthful, and maintainable by later agents.\n\nRequired quality standards:\n\n- be faithful to source data\n- do not invent or hallucinate missing facts\n- do not silently truncate a dataset and pretend it is complete\n- prefer truth over completeness when those goals conflict\n- make limitations, sampling, missing data, and freshness visible\n- keep rendering aligned with the reasoning captured in `artifact.md`, `data.json`, and `memory.md`\n- keep `data.json` as an authoring/thinking artifact rather than a runtime dependency\n- keep the artifact maintainable by a future agent reading only the bundle files\n\nAnti-patterns:\n\n- cursory or low-effort data collection\n- fake data added to make the artifact look complete\n- brittle one-off hacks that a later agent cannot reproduce\n- hidden dependencies that are not documented in `artifact.md` or `memory.md`\n- layout churn during simple data refreshes when the data model did not change\n\n## HTML house style\n\nHTML artifacts should feel intentional and readable inside Television tiles.\n\nTelevision provides a full base stylesheet for HTML artifacts. Only add custom\nCSS when you need something not covered by the built-in styles. Prefer the base\nstyles and theme tokens so artifacts stay visually coherent with the rest of\nTelevision.\n\nHouse-style guidance:\n\n- use semantic HTML first\n- keep the most important information near the top\n- design for small, medium, and large tile sizes\n- avoid horizontal overflow unless there is no reasonable alternative\n- make empty states and error states explicit\n- prefer the built-in HTML styling before inventing custom component chrome\n\n### Elements\n\nStandard elements already have sensible defaults, so you usually do not need to\nstyle from scratch:\n\n- headings (`h1`\u2013`h6`) \u2014 sized and weighted\n- `p`, `ul`, `ol` \u2014 readable defaults\n- `code` and `pre` \u2014 monospace, muted background\n- `blockquote` \u2014 left border, muted text\n- `table`, `th`, `td` \u2014 bordered, striped headers\n- `button` \u2014 styled with border and hover state; use `size="sm"` or `size="md"` when appropriate\n- `hr` \u2014 subtle border\n- `a` \u2014 inherits color by default\n\n### `.prose` class\n\nUse a `.prose` wrapper for document-style HTML where readable vertical rhythm is\nappropriate. Do not rely on `.prose` for dashboards, tables, control surfaces,\nor dense custom layouts.\n\n```html\n<div class="prose">\n  <h1>Title</h1>\n  <p>Some content with proper spacing between elements.</p>\n  <ul>\n    <li>Item one</li>\n    <li>Item two</li>\n  </ul>\n</div>\n```\n\n### CSS variables\n\nUse the existing Television tokens when they are available in the runtime.\nThese are the preferred way to stay aligned with the app theme.\n\nColors:\n- `--color-bg` \u2014 page background\n- `--color-bg-muted` \u2014 subtle background\n- `--color-surface` \u2014 card or panel background\n- `--color-text` \u2014 primary text\n- `--color-text-muted` \u2014 secondary or label text\n- `--color-border` \u2014 border color\n\nSpacing:\n- `--space-4`\n- `--space-8`\n- `--space-12`\n- `--space-16`\n- `--space-24`\n- `--space-32`\n\nFonts:\n- `--font-sans`\n- `--font-mono`\n\nText sizes:\n- `--text-sm`\n- `--text-base`\n- `--text-lg`\n- `--text-xl`\n\nRadius:\n- `--radius-4`\n- `--radius-8`\n\n## Workflows\n\n### Create new internal artifact\n\n1. Decide that the result should be an internal artifact.\n2. Start the pending bundle:\n\n```bash\ntv create-internal-artifact --screen "<screen-id>" --type text/markdown --title "Artifact title"\n```\n\nOr:\n\n```bash\ntv create-internal-artifact --screen "<screen-id>" --type text/html --title "Artifact title"\n```\n\n3. Read the returned pending path and edit files there.\n4. Write `artifact.md`.\n5. In `artifact.md`, capture the user\'s language faithfully in `## User intent` before doing the rest of the authoring work. Use direct quotes when helpful, or a close paraphrase when that is clearer, but keep it representative of what the user actually said they wanted.\n6. Think through the artifact in a pure way and write `data.json` only as an authoring aid.\n7. For markdown artifacts, leave `data.json` as `{}` unless there is a compelling authoring reason not to.\n8. Render `public/index.md` or `public/index.html`.\n9. Append a current timestamped activity entry in `memory.md`.\n10. Commit:\n\n```bash\ntv commit-pending-artifact --id "<artifact-id>"\n```\n\n### Update internal artifact with fresh data\n\n1. Stage the edit:\n\n```bash\ntv edit-internal-artifact --id "<artifact-id>"\n```\n\n2. Read `artifact.md`, `data.json`, and `memory.md` before changing anything.\n3. Refresh the underlying facts or source material.\n4. Update `data.json` only if it helps clarify the authoring plan.\n5. For markdown artifacts, prefer to keep `data.json` as `{}`.\n6. Make the minimum rendering changes needed to keep the artifact correct.\n7. Record what changed in `memory.md`.\n8. Commit:\n\n```bash\ntv commit-pending-artifact --id "<artifact-id>"\n```\n\nAvoid unnecessary layout or styling churn during data-only refreshes.\n\n### Modify internal artifact from user feedback\n\n1. Stage the edit:\n\n```bash\ntv edit-internal-artifact --id "<artifact-id>"\n```\n\n2. Read `artifact.md`, `data.json`, and `memory.md`.\n3. Update `artifact.md` if the user intent or non-goals changed.\n4. When the user has added feedback, complaints, corrections, or new guidance, update `## User intent` so it remains a faithful record of what the user actually wants now. Preserve the user\'s language as closely as practical, using direct quotes or close paraphrases.\n5. Update `data.json` only if it improves the authoring model of the artifact.\n6. For markdown artifacts, prefer to keep `data.json` as `{}`.\n7. Adjust `public/index.md` or `public/index.html` as narrowly as possible.\n8. Record the request, decision, and resulting change in `memory.md`.\n9. Commit:\n\n```bash\ntv commit-pending-artifact --id "<artifact-id>"\n```\n\n### Abandon pending work\n\nIf the staged work should be discarded instead of committed:\n\n```bash\ntv abandon-pending-artifact --id "<artifact-id>"\n```\n\n### Create external artifact\n\nUse this when the file already exists on disk and Television should display it\nwithout owning a bundle:\n\n```bash\ntv create-external-artifact --screen "<screen-id>" --type text/markdown --title "Artifact title" --path /absolute/path/to/file.md\n```\n\nOr:\n\n```bash\ntv create-external-artifact --screen "<screen-id>" --type text/html --title "Artifact title" --path /absolute/path/to/file.html\n```\n\nRules:\n\n- `--path` must be absolute\n- the file must already exist and be readable\n- the extension must match `type`\n- external artifacts do not use pending create, pending edit, commit, or abandon\n\n## CLI reference\n\nWorkflow commands:\n\n```bash\ntv create-internal-artifact --screen "<screen-id>" --type <text/markdown|text/html> --title "Artifact title"\ntv edit-internal-artifact --id "<artifact-id>"\ntv commit-pending-artifact --id "<artifact-id>"\ntv abandon-pending-artifact --id "<artifact-id>"\ntv create-external-artifact --screen "<screen-id>" --type <text/markdown|text/html> --title "Artifact title" --path /absolute/path\ntv update-artifact --id "<artifact-id>" --title "New title"\ntv remove-artifact --id "<artifact-id>" --screen "<screen-id>"\ntv remove-screen --id "<screen-id>"\n```\n\nRead and server commands:\n\n```bash\ntv list-screens\ntv get-screen --id "<screen-id>"\ntv create-screen --name "Screen name"\ntv storage-path\ntv status\ntv serve\ntv stop\n```\n\nCLI behavior notes:\n\n- workflow and mutation commands print plain text\n- read commands print JSON\n- `tv get-screen` includes artifact `kind` and `status`\n- `tv remove-artifact` removes the artifact reference from the named screen; if another screen still references it, the artifact is unlinked and kept alive; otherwise it cascades to trash/discard\n- `tv update-artifact` changes title metadata only\n- when the CLI reports an error, follow the directive to run `tv help`\n\n## Deferred or out of scope\n\nThese are not part of the current implementation:\n\n- `tv help <topic>`\n- restore-from-trash\n- pending-listing commands\n- attestation or nonce commands\n- stale pending cleanup or stale trash cleanup\n- markdown editor UI recovery\n- client-side pending presentation work\n- multi-section help output';
+  if ('# Television\n\nTelevision is a persistent artifact screen for agents. Use it when the user\nshould be able to inspect, revisit, and refine a file-backed result instead of\nonly reading a chat reply.\n\nIf you lose context, run:\n\n```bash\ntv help\n```\n\nThat command prints this full skill as one blob. There is no topic-scoped help\nin the current implementation.\n\n## Mental model\n\n- A **screen** is a named viewer surface with a layout.\n- An **artifact** is a file-backed result that can exist independently of any\n  screen. It can be unplaced, attached to one screen, or attached to multiple\n  screens.\n- **Screen membership** is separate from artifact identity: attaching/detaching\n  controls which screens show an artifact; deleting removes the artifact\n  globally. The CLI create commands require `--screen` so in-progress artifacts\n  are visible immediately.\n- An **internal artifact** is a Television-managed bundle. You create a pending\n  bundle, edit files in that bundle, then commit it.\n- An **external artifact** is a pointer to an existing absolute file on disk.\n  Television displays that file but does not own or delete it.\n- **Pending** means a create or edit is staged but not yet committed.\n- **Trash** means metadata and committed internal bundles moved out of the live\n  tree. There is no restore workflow in the current scope.\n\nThe core workflow is:\n\n1. Decide whether the result should be internal or external.\n2. Create or stage the artifact with the CLI.\n3. For internal artifacts, edit files in the pending bundle.\n4. Commit when the validation rules are satisfied.\n\n## User communication during multi-step workflows\n\nWhen you are doing a multi-step artifact workflow, keep the user informed as you\nprogress.\n\nRequired communication style:\n\n- verbalize key actions and decisions as they happen\n- keep the language concise\n- prefer short updates over long explanations\n- frame updates in the user\'s world and goals, not in the internal mechanics of the skill or CLI workflow\n- avoid technical workflow jargon unless the user explicitly asks for it\n- do not write reports, long paragraphs, or chatty summaries while the work is in progress\n- do not use lists unless the user explicitly asks for one\n- optimize for speed and token efficiency\n\nGood examples:\n\n- "Starting the artifact now."\n- "Reviewing the draft and source material."\n- "Updating the HTML and efficiently navigating the artifact creation flow."\n- "The artifact did not pass validation yet; fixing the draft notes and retrying."\n- "Finalizing the artifact now."\n- "Done."\n\nBad examples:\n\n- multi-paragraph progress reports\n- long retrospective narration during execution\n- verbose bullet lists for routine workflow steps\n\n## Internal versus external\n\nUse an **internal artifact** when:\n\n- the artifact is purpose-built for Television\n- Television should own the bundle structure\n- future agents should be able to maintain the result by reading bundle files\n- you need a staged create or staged edit workflow\n\nUse an **external artifact** when:\n\n- a real file already exists on disk\n- the user wants Television to display that existing file\n- you do not need a Television-managed bundle\n\nDecision rule:\n\n- If the result should be maintained as a Television-owned long-lived artifact,\n  choose internal.\n- If the result is already a real file outside Television and should stay that\n  way, choose external.\n\nSupported artifact types:\n\n- `text/markdown`\n- `text/html`\n\n## Internal bundle files\n\nEvery internal artifact bundle contains:\n\n- `artifact.md`\n- `data.json`\n- `memory.md`\n- `public/index.md` or `public/index.html`\n\nFresh pending bundles are intentionally minimal:\n\n- `artifact.md` is blank\n- `memory.md` is blank\n- `public/index.md` or `public/index.html` is blank\n- `data.json` is exactly `{}`\n\nThe scaffold is not commit-valid by itself. Learn the required structure from\nthis skill, not from placeholder content in the scaffold.\n\n### `artifact.md`\n\n`artifact.md` is the contract for the artifact. It explains what the artifact\nis for, what conceptual material it is based on, how it should render, and how\nlater agents should maintain it.\n\nBefore commit, `artifact.md` must be non-empty and contain all of these exact\nheadings:\n\n```md\n## User intent\n## Purpose\n## Data shape\n## Data sources\n## Rendering\n## Update workflow\n## Non-goals\n```\n\nWhat each section should capture:\n\n- `## User intent`: faithful restatement or quotation of what the user actually said they wanted; this is critical and should preserve the user\'s language as closely as practical, including requests, feedback, complaints, constraints, and guidance\n- `## Purpose`: what the artifact is trying to achieve\n- `## Data shape`: the conceptual shape you reasoned about while authoring; for markdown artifacts this will often just be `{}`\n- `## Data sources`: where the underlying facts, notes, or source material came from and how they were obtained\n- `## Rendering`: how `public/index.md` or `public/index.html` should present it\n- `## Update workflow`: how future agents should refresh or modify it\n- `## Non-goals`: what is intentionally excluded, especially application-like runtime behavior\n\n### `data.json`\n\n`data.json` is a **thinking artifact**, not a runtime payload.\n\nIts purpose is to help the model separate:\n\n- reasoning / planning / authoring structure\n- from final presentation in `public/index.md` or `public/index.html`\n\nUse it to capture the pure conceptual shape of what you are about to render.\nThis is an authoring aid for agents, not an application data layer.\n\nHard rules:\n\n- **Do not treat `data.json` as live runtime state.**\n- **Do not write HTML/JS that loads, depends on, or synchronizes against `data.json`.**\n- **Do not build application-like data-driven artifacts.**\n- **We do not support runtime data-backed artifacts at this time.**\n- Artifacts are static markdown or static HTML documents.\n- HTML artifacts may include JavaScript and extra assets under `public/`, but\n  that JavaScript must stay presentation-oriented and self-contained, not\n  driven by `data.json` as an application state container.\n\nFor `text/markdown` artifacts, leave `data.json` as exactly:\n\n```json\n{}\n```\n\nThere is usually little value in separating content from presentation for\nmarkdown artifacts, so prefer `{}` unless there is a very strong authoring\nreason not to.\n\nFor `text/html` artifacts, use `data.json` only when it helps you think clearly\nabout the material before rendering. It may describe the conceptual structure\nof the artifact, but it must not become a runtime contract.\n\nValidation rule:\n\n- `data.json` must exist and contain valid JSON\n\nThe current validator does not require the JSON value to be an object, but an\nobject is the normal choice.\n\n### `memory.md`\n\n`memory.md` is the working scratchpad for later agents. Record decisions,\nlimitations, data-retrieval notes, problems encountered, what changed, and what\nshould be watched during future edits.\n\nRequired validation anchors:\n\n- `memory.md` must contain `## Activity Log`\n- `memory.md` must contain at least one UTC timestamp in exact\n  `YYYY-MM-DDTHH:MM:SSZ` format\n- at least one timestamp must be from the last 30 minutes when you commit\n\nThe minimum required heading is:\n\n```md\n## Activity Log\n```\n\nWhat to record beyond that is up to the artifact and the work performed.\n\n### `public/index.md` and `public/index.html`\n\nThis is the rendered entry file that Television serves.\n\n- Markdown artifacts use `public/index.md`\n- HTML artifacts use `public/index.html`\n- the entry file must match the artifact `type`\n- the entry file must be non-empty before commit\n\nFor HTML artifacts:\n\n- `public/index.html` is a full HTML document, not a body fragment\n- additional public assets may live under `public/`\n- keep paths relative to `public/`\n\n## Quality bar\n\nBuild artifacts that are durable, truthful, and maintainable by later agents.\n\nRequired quality standards:\n\n- be faithful to source data\n- do not invent or hallucinate missing facts\n- do not silently truncate a dataset and pretend it is complete\n- prefer truth over completeness when those goals conflict\n- make limitations, sampling, missing data, and freshness visible\n- keep rendering aligned with the reasoning captured in `artifact.md`, `data.json`, and `memory.md`\n- keep `data.json` as an authoring/thinking artifact rather than a runtime dependency\n- keep the artifact maintainable by a future agent reading only the bundle files\n\nAnti-patterns:\n\n- cursory or low-effort data collection\n- fake data added to make the artifact look complete\n- brittle one-off hacks that a later agent cannot reproduce\n- hidden dependencies that are not documented in `artifact.md` or `memory.md`\n- layout churn during simple data refreshes when the data model did not change\n\n## HTML house style\n\nHTML artifacts should feel intentional and readable inside Television tiles.\n\nTelevision provides a full base stylesheet for HTML artifacts. Only add custom\nCSS when you need something not covered by the built-in styles. Prefer the base\nstyles and theme tokens so artifacts stay visually coherent with the rest of\nTelevision.\n\nHouse-style guidance:\n\n- use semantic HTML first\n- keep the most important information near the top\n- design for small, medium, and large tile sizes\n- avoid horizontal overflow unless there is no reasonable alternative\n- make empty states and error states explicit\n- prefer the built-in HTML styling before inventing custom component chrome\n\n### Elements\n\nStandard elements already have sensible defaults, so you usually do not need to\nstyle from scratch:\n\n- headings (`h1`\u2013`h6`) \u2014 sized and weighted\n- `p`, `ul`, `ol` \u2014 readable defaults\n- `code` and `pre` \u2014 monospace, muted background\n- `blockquote` \u2014 left border, muted text\n- `table`, `th`, `td` \u2014 bordered, striped headers\n- `button` \u2014 styled with border and hover state; use `size="sm"` or `size="md"` when appropriate\n- `hr` \u2014 subtle border\n- `a` \u2014 inherits color by default\n\n### `.prose` class\n\nUse a `.prose` wrapper for document-style HTML where readable vertical rhythm is\nappropriate. Do not rely on `.prose` for dashboards, tables, control surfaces,\nor dense custom layouts.\n\n```html\n<div class="prose">\n  <h1>Title</h1>\n  <p>Some content with proper spacing between elements.</p>\n  <ul>\n    <li>Item one</li>\n    <li>Item two</li>\n  </ul>\n</div>\n```\n\n### CSS variables\n\nUse the existing Television tokens when they are available in the runtime.\nThese are the preferred way to stay aligned with the app theme.\n\nColors:\n- `--color-bg` \u2014 page background\n- `--color-bg-muted` \u2014 subtle background\n- `--color-surface` \u2014 card or panel background\n- `--color-text` \u2014 primary text\n- `--color-text-muted` \u2014 secondary or label text\n- `--color-border` \u2014 border color\n\nSpacing:\n- `--space-4`\n- `--space-8`\n- `--space-12`\n- `--space-16`\n- `--space-24`\n- `--space-32`\n\nFonts:\n- `--font-sans`\n- `--font-mono`\n\nText sizes:\n- `--text-sm`\n- `--text-base`\n- `--text-lg`\n- `--text-xl`\n\nRadius:\n- `--radius-4`\n- `--radius-8`\n\n## Workflows\n\n### Create new internal artifact\n\n1. Decide that the result should be an internal artifact.\n2. Start the pending bundle:\n\n```bash\ntv create-internal-artifact --screen "<screen-id>" --type text/markdown --title "Artifact title"\n```\n\nOr:\n\n```bash\ntv create-internal-artifact --screen "<screen-id>" --type text/html --title "Artifact title"\n```\n\n`--screen` is required for internal artifact creation so the user can see the in-progress artifact immediately.\n\n3. Read the returned pending path and edit files there.\n4. Write `artifact.md`.\n5. In `artifact.md`, capture the user\'s language faithfully in `## User intent` before doing the rest of the authoring work. Use direct quotes when helpful, or a close paraphrase when that is clearer, but keep it representative of what the user actually said they wanted.\n6. Think through the artifact in a pure way and write `data.json` only as an authoring aid.\n7. For markdown artifacts, leave `data.json` as `{}` unless there is a compelling authoring reason not to.\n8. Render `public/index.md` or `public/index.html`.\n9. Append a current timestamped activity entry in `memory.md`.\n10. Commit:\n\n```bash\ntv commit-pending-artifact --id "<artifact-id>"\n```\n\n### Update internal artifact with fresh data\n\n1. Stage the edit:\n\n```bash\ntv edit-internal-artifact --id "<artifact-id>"\n```\n\n2. Read `artifact.md`, `data.json`, and `memory.md` before changing anything.\n3. Refresh the underlying facts or source material.\n4. Update `data.json` only if it helps clarify the authoring plan.\n5. For markdown artifacts, prefer to keep `data.json` as `{}`.\n6. Make the minimum rendering changes needed to keep the artifact correct.\n7. Record what changed in `memory.md`.\n8. Commit:\n\n```bash\ntv commit-pending-artifact --id "<artifact-id>"\n```\n\nAvoid unnecessary layout or styling churn during data-only refreshes.\n\n### Modify internal artifact from user feedback\n\n1. Stage the edit:\n\n```bash\ntv edit-internal-artifact --id "<artifact-id>"\n```\n\n2. Read `artifact.md`, `data.json`, and `memory.md`.\n3. Update `artifact.md` if the user intent or non-goals changed.\n4. When the user has added feedback, complaints, corrections, or new guidance, update `## User intent` so it remains a faithful record of what the user actually wants now. Preserve the user\'s language as closely as practical, using direct quotes or close paraphrases.\n5. Update `data.json` only if it improves the authoring model of the artifact.\n6. For markdown artifacts, prefer to keep `data.json` as `{}`.\n7. Adjust `public/index.md` or `public/index.html` as narrowly as possible.\n8. Record the request, decision, and resulting change in `memory.md`.\n9. Commit:\n\n```bash\ntv commit-pending-artifact --id "<artifact-id>"\n```\n\n### Abandon pending work\n\nIf the staged work should be discarded instead of committed:\n\n```bash\ntv abandon-pending-artifact --id "<artifact-id>"\n```\n\n### Create external artifact\n\nUse this when the file already exists on disk and Television should display it\nwithout owning a bundle:\n\n```bash\ntv create-external-artifact --screen "<screen-id>" --type text/markdown --title "Artifact title" --path /absolute/path/to/file.md\n```\n\nOr:\n\n```bash\ntv create-external-artifact --screen "<screen-id>" --type text/html --title "Artifact title" --path /absolute/path/to/file.html\n```\n\n`--screen` is required for CLI creation so the file appears on a visible screen immediately.\n\nRules:\n\n- `--path` must be absolute\n- the file must already exist and be readable\n- the extension must match `type`\n- external artifacts do not use pending create, pending edit, commit, or abandon\n\n## CLI reference\n\nArtifact commands:\n\n```bash\ntv create-internal-artifact --screen "<screen-id>" --type <text/markdown|text/html> --title "Artifact title"\ntv create-external-artifact --screen "<screen-id>" --type <text/markdown|text/html> --title "Artifact title" --path /absolute/path\ntv edit-internal-artifact --id "<artifact-id>"\ntv commit-pending-artifact --id "<artifact-id>"\ntv abandon-pending-artifact --id "<artifact-id>"\ntv update-artifact --id "<artifact-id>" --title "New title"\ntv list-artifacts [--screen "<screen-id>"] [--unplaced]\ntv get-artifact --id "<artifact-id>"\ntv delete-artifact --id "<artifact-id>"\n```\n\nScreen commands:\n\n```bash\ntv create-screen --name "Screen name"\ntv list-screens\ntv get-screen --id "<screen-id>"\ntv remove-screen --id "<screen-id>"\n```\n\nScreen membership commands:\n\n```bash\ntv attach-artifact --id "<artifact-id>" --screen "<screen-id>"\ntv detach-artifact --id "<artifact-id>" --screen "<screen-id>"\n```\n\nViewer commands:\n\n```bash\ntv viewer-status\ntv set-active-screen --id "<screen-id>"\ntv focus-artifact --id "<artifact-id>" [--screen "<screen-id>"]\n```\n\nServer commands:\n\n```bash\ntv status\ntv storage-path\ntv serve\ntv stop\n```\n\nCLI behavior notes:\n\n- `--screen` is required on CLI create commands so new artifacts are visible immediately; use `tv attach-artifact` and `tv detach-artifact` for later screen membership changes\n- workflow and mutation commands print plain text\n- read commands print JSON\n- `tv get-screen` includes artifact `kind` and `status`\n- `tv attach-artifact` appends a default-sized card to the right end of the strip; idempotent if the artifact is already on that screen\n- `tv detach-artifact` removes the card from a screen\'s layout; the artifact metadata is never touched, even on the last reference\n- `tv delete-artifact` is the way to globally remove an artifact (detaches from every screen, then trashes the bundle / forgets the external pointer / discards pending-create)\n- `tv list-artifacts` accepts `--screen <id>` to filter by screen membership and `--unplaced` to surface artifacts attached to no screen\n- `tv update-artifact` changes title metadata only\n- `tv set-active-screen` sets which screen the GUI is focused on; the change is persisted and broadcast to connected clients\n- `tv focus-artifact` is a transient nudge: clients switch screens if needed, scroll the artifact\'s card into view, and play a brief highlight animation; pass `--screen <id>` to pin which screen, otherwise the server picks one (preferring the active screen when the artifact is there)\n- `tv viewer-status` prints the active screen ID and the count of connected GUI clients\n- when the CLI reports an error, follow the directive to run `tv help`\n\n## Deferred or out of scope\n\nThese are not part of the current implementation:\n\n- `tv help <topic>`\n- restore-from-trash\n- pending-listing commands\n- attestation or nonce commands\n- stale pending cleanup or stale trash cleanup\n- markdown editor UI recovery\n- client-side pending presentation work\n- multi-section help output'.length > 0) {
+    return '# Television\n\nTelevision is a persistent artifact screen for agents. Use it when the user\nshould be able to inspect, revisit, and refine a file-backed result instead of\nonly reading a chat reply.\n\nIf you lose context, run:\n\n```bash\ntv help\n```\n\nThat command prints this full skill as one blob. There is no topic-scoped help\nin the current implementation.\n\n## Mental model\n\n- A **screen** is a named viewer surface with a layout.\n- An **artifact** is a file-backed result that can exist independently of any\n  screen. It can be unplaced, attached to one screen, or attached to multiple\n  screens.\n- **Screen membership** is separate from artifact identity: attaching/detaching\n  controls which screens show an artifact; deleting removes the artifact\n  globally. The CLI create commands require `--screen` so in-progress artifacts\n  are visible immediately.\n- An **internal artifact** is a Television-managed bundle. You create a pending\n  bundle, edit files in that bundle, then commit it.\n- An **external artifact** is a pointer to an existing absolute file on disk.\n  Television displays that file but does not own or delete it.\n- **Pending** means a create or edit is staged but not yet committed.\n- **Trash** means metadata and committed internal bundles moved out of the live\n  tree. There is no restore workflow in the current scope.\n\nThe core workflow is:\n\n1. Decide whether the result should be internal or external.\n2. Create or stage the artifact with the CLI.\n3. For internal artifacts, edit files in the pending bundle.\n4. Commit when the validation rules are satisfied.\n\n## User communication during multi-step workflows\n\nWhen you are doing a multi-step artifact workflow, keep the user informed as you\nprogress.\n\nRequired communication style:\n\n- verbalize key actions and decisions as they happen\n- keep the language concise\n- prefer short updates over long explanations\n- frame updates in the user\'s world and goals, not in the internal mechanics of the skill or CLI workflow\n- avoid technical workflow jargon unless the user explicitly asks for it\n- do not write reports, long paragraphs, or chatty summaries while the work is in progress\n- do not use lists unless the user explicitly asks for one\n- optimize for speed and token efficiency\n\nGood examples:\n\n- "Starting the artifact now."\n- "Reviewing the draft and source material."\n- "Updating the HTML and efficiently navigating the artifact creation flow."\n- "The artifact did not pass validation yet; fixing the draft notes and retrying."\n- "Finalizing the artifact now."\n- "Done."\n\nBad examples:\n\n- multi-paragraph progress reports\n- long retrospective narration during execution\n- verbose bullet lists for routine workflow steps\n\n## Internal versus external\n\nUse an **internal artifact** when:\n\n- the artifact is purpose-built for Television\n- Television should own the bundle structure\n- future agents should be able to maintain the result by reading bundle files\n- you need a staged create or staged edit workflow\n\nUse an **external artifact** when:\n\n- a real file already exists on disk\n- the user wants Television to display that existing file\n- you do not need a Television-managed bundle\n\nDecision rule:\n\n- If the result should be maintained as a Television-owned long-lived artifact,\n  choose internal.\n- If the result is already a real file outside Television and should stay that\n  way, choose external.\n\nSupported artifact types:\n\n- `text/markdown`\n- `text/html`\n\n## Internal bundle files\n\nEvery internal artifact bundle contains:\n\n- `artifact.md`\n- `data.json`\n- `memory.md`\n- `public/index.md` or `public/index.html`\n\nFresh pending bundles are intentionally minimal:\n\n- `artifact.md` is blank\n- `memory.md` is blank\n- `public/index.md` or `public/index.html` is blank\n- `data.json` is exactly `{}`\n\nThe scaffold is not commit-valid by itself. Learn the required structure from\nthis skill, not from placeholder content in the scaffold.\n\n### `artifact.md`\n\n`artifact.md` is the contract for the artifact. It explains what the artifact\nis for, what conceptual material it is based on, how it should render, and how\nlater agents should maintain it.\n\nBefore commit, `artifact.md` must be non-empty and contain all of these exact\nheadings:\n\n```md\n## User intent\n## Purpose\n## Data shape\n## Data sources\n## Rendering\n## Update workflow\n## Non-goals\n```\n\nWhat each section should capture:\n\n- `## User intent`: faithful restatement or quotation of what the user actually said they wanted; this is critical and should preserve the user\'s language as closely as practical, including requests, feedback, complaints, constraints, and guidance\n- `## Purpose`: what the artifact is trying to achieve\n- `## Data shape`: the conceptual shape you reasoned about while authoring; for markdown artifacts this will often just be `{}`\n- `## Data sources`: where the underlying facts, notes, or source material came from and how they were obtained\n- `## Rendering`: how `public/index.md` or `public/index.html` should present it\n- `## Update workflow`: how future agents should refresh or modify it\n- `## Non-goals`: what is intentionally excluded, especially application-like runtime behavior\n\n### `data.json`\n\n`data.json` is a **thinking artifact**, not a runtime payload.\n\nIts purpose is to help the model separate:\n\n- reasoning / planning / authoring structure\n- from final presentation in `public/index.md` or `public/index.html`\n\nUse it to capture the pure conceptual shape of what you are about to render.\nThis is an authoring aid for agents, not an application data layer.\n\nHard rules:\n\n- **Do not treat `data.json` as live runtime state.**\n- **Do not write HTML/JS that loads, depends on, or synchronizes against `data.json`.**\n- **Do not build application-like data-driven artifacts.**\n- **We do not support runtime data-backed artifacts at this time.**\n- Artifacts are static markdown or static HTML documents.\n- HTML artifacts may include JavaScript and extra assets under `public/`, but\n  that JavaScript must stay presentation-oriented and self-contained, not\n  driven by `data.json` as an application state container.\n\nFor `text/markdown` artifacts, leave `data.json` as exactly:\n\n```json\n{}\n```\n\nThere is usually little value in separating content from presentation for\nmarkdown artifacts, so prefer `{}` unless there is a very strong authoring\nreason not to.\n\nFor `text/html` artifacts, use `data.json` only when it helps you think clearly\nabout the material before rendering. It may describe the conceptual structure\nof the artifact, but it must not become a runtime contract.\n\nValidation rule:\n\n- `data.json` must exist and contain valid JSON\n\nThe current validator does not require the JSON value to be an object, but an\nobject is the normal choice.\n\n### `memory.md`\n\n`memory.md` is the working scratchpad for later agents. Record decisions,\nlimitations, data-retrieval notes, problems encountered, what changed, and what\nshould be watched during future edits.\n\nRequired validation anchors:\n\n- `memory.md` must contain `## Activity Log`\n- `memory.md` must contain at least one UTC timestamp in exact\n  `YYYY-MM-DDTHH:MM:SSZ` format\n- at least one timestamp must be from the last 30 minutes when you commit\n\nThe minimum required heading is:\n\n```md\n## Activity Log\n```\n\nWhat to record beyond that is up to the artifact and the work performed.\n\n### `public/index.md` and `public/index.html`\n\nThis is the rendered entry file that Television serves.\n\n- Markdown artifacts use `public/index.md`\n- HTML artifacts use `public/index.html`\n- the entry file must match the artifact `type`\n- the entry file must be non-empty before commit\n\nFor HTML artifacts:\n\n- `public/index.html` is a full HTML document, not a body fragment\n- additional public assets may live under `public/`\n- keep paths relative to `public/`\n\n## Quality bar\n\nBuild artifacts that are durable, truthful, and maintainable by later agents.\n\nRequired quality standards:\n\n- be faithful to source data\n- do not invent or hallucinate missing facts\n- do not silently truncate a dataset and pretend it is complete\n- prefer truth over completeness when those goals conflict\n- make limitations, sampling, missing data, and freshness visible\n- keep rendering aligned with the reasoning captured in `artifact.md`, `data.json`, and `memory.md`\n- keep `data.json` as an authoring/thinking artifact rather than a runtime dependency\n- keep the artifact maintainable by a future agent reading only the bundle files\n\nAnti-patterns:\n\n- cursory or low-effort data collection\n- fake data added to make the artifact look complete\n- brittle one-off hacks that a later agent cannot reproduce\n- hidden dependencies that are not documented in `artifact.md` or `memory.md`\n- layout churn during simple data refreshes when the data model did not change\n\n## HTML house style\n\nHTML artifacts should feel intentional and readable inside Television tiles.\n\nTelevision provides a full base stylesheet for HTML artifacts. Only add custom\nCSS when you need something not covered by the built-in styles. Prefer the base\nstyles and theme tokens so artifacts stay visually coherent with the rest of\nTelevision.\n\nHouse-style guidance:\n\n- use semantic HTML first\n- keep the most important information near the top\n- design for small, medium, and large tile sizes\n- avoid horizontal overflow unless there is no reasonable alternative\n- make empty states and error states explicit\n- prefer the built-in HTML styling before inventing custom component chrome\n\n### Elements\n\nStandard elements already have sensible defaults, so you usually do not need to\nstyle from scratch:\n\n- headings (`h1`\u2013`h6`) \u2014 sized and weighted\n- `p`, `ul`, `ol` \u2014 readable defaults\n- `code` and `pre` \u2014 monospace, muted background\n- `blockquote` \u2014 left border, muted text\n- `table`, `th`, `td` \u2014 bordered, striped headers\n- `button` \u2014 styled with border and hover state; use `size="sm"` or `size="md"` when appropriate\n- `hr` \u2014 subtle border\n- `a` \u2014 inherits color by default\n\n### `.prose` class\n\nUse a `.prose` wrapper for document-style HTML where readable vertical rhythm is\nappropriate. Do not rely on `.prose` for dashboards, tables, control surfaces,\nor dense custom layouts.\n\n```html\n<div class="prose">\n  <h1>Title</h1>\n  <p>Some content with proper spacing between elements.</p>\n  <ul>\n    <li>Item one</li>\n    <li>Item two</li>\n  </ul>\n</div>\n```\n\n### CSS variables\n\nUse the existing Television tokens when they are available in the runtime.\nThese are the preferred way to stay aligned with the app theme.\n\nColors:\n- `--color-bg` \u2014 page background\n- `--color-bg-muted` \u2014 subtle background\n- `--color-surface` \u2014 card or panel background\n- `--color-text` \u2014 primary text\n- `--color-text-muted` \u2014 secondary or label text\n- `--color-border` \u2014 border color\n\nSpacing:\n- `--space-4`\n- `--space-8`\n- `--space-12`\n- `--space-16`\n- `--space-24`\n- `--space-32`\n\nFonts:\n- `--font-sans`\n- `--font-mono`\n\nText sizes:\n- `--text-sm`\n- `--text-base`\n- `--text-lg`\n- `--text-xl`\n\nRadius:\n- `--radius-4`\n- `--radius-8`\n\n## Workflows\n\n### Create new internal artifact\n\n1. Decide that the result should be an internal artifact.\n2. Start the pending bundle:\n\n```bash\ntv create-internal-artifact --screen "<screen-id>" --type text/markdown --title "Artifact title"\n```\n\nOr:\n\n```bash\ntv create-internal-artifact --screen "<screen-id>" --type text/html --title "Artifact title"\n```\n\n`--screen` is required for internal artifact creation so the user can see the in-progress artifact immediately.\n\n3. Read the returned pending path and edit files there.\n4. Write `artifact.md`.\n5. In `artifact.md`, capture the user\'s language faithfully in `## User intent` before doing the rest of the authoring work. Use direct quotes when helpful, or a close paraphrase when that is clearer, but keep it representative of what the user actually said they wanted.\n6. Think through the artifact in a pure way and write `data.json` only as an authoring aid.\n7. For markdown artifacts, leave `data.json` as `{}` unless there is a compelling authoring reason not to.\n8. Render `public/index.md` or `public/index.html`.\n9. Append a current timestamped activity entry in `memory.md`.\n10. Commit:\n\n```bash\ntv commit-pending-artifact --id "<artifact-id>"\n```\n\n### Update internal artifact with fresh data\n\n1. Stage the edit:\n\n```bash\ntv edit-internal-artifact --id "<artifact-id>"\n```\n\n2. Read `artifact.md`, `data.json`, and `memory.md` before changing anything.\n3. Refresh the underlying facts or source material.\n4. Update `data.json` only if it helps clarify the authoring plan.\n5. For markdown artifacts, prefer to keep `data.json` as `{}`.\n6. Make the minimum rendering changes needed to keep the artifact correct.\n7. Record what changed in `memory.md`.\n8. Commit:\n\n```bash\ntv commit-pending-artifact --id "<artifact-id>"\n```\n\nAvoid unnecessary layout or styling churn during data-only refreshes.\n\n### Modify internal artifact from user feedback\n\n1. Stage the edit:\n\n```bash\ntv edit-internal-artifact --id "<artifact-id>"\n```\n\n2. Read `artifact.md`, `data.json`, and `memory.md`.\n3. Update `artifact.md` if the user intent or non-goals changed.\n4. When the user has added feedback, complaints, corrections, or new guidance, update `## User intent` so it remains a faithful record of what the user actually wants now. Preserve the user\'s language as closely as practical, using direct quotes or close paraphrases.\n5. Update `data.json` only if it improves the authoring model of the artifact.\n6. For markdown artifacts, prefer to keep `data.json` as `{}`.\n7. Adjust `public/index.md` or `public/index.html` as narrowly as possible.\n8. Record the request, decision, and resulting change in `memory.md`.\n9. Commit:\n\n```bash\ntv commit-pending-artifact --id "<artifact-id>"\n```\n\n### Abandon pending work\n\nIf the staged work should be discarded instead of committed:\n\n```bash\ntv abandon-pending-artifact --id "<artifact-id>"\n```\n\n### Create external artifact\n\nUse this when the file already exists on disk and Television should display it\nwithout owning a bundle:\n\n```bash\ntv create-external-artifact --screen "<screen-id>" --type text/markdown --title "Artifact title" --path /absolute/path/to/file.md\n```\n\nOr:\n\n```bash\ntv create-external-artifact --screen "<screen-id>" --type text/html --title "Artifact title" --path /absolute/path/to/file.html\n```\n\n`--screen` is required for CLI creation so the file appears on a visible screen immediately.\n\nRules:\n\n- `--path` must be absolute\n- the file must already exist and be readable\n- the extension must match `type`\n- external artifacts do not use pending create, pending edit, commit, or abandon\n\n## CLI reference\n\nArtifact commands:\n\n```bash\ntv create-internal-artifact --screen "<screen-id>" --type <text/markdown|text/html> --title "Artifact title"\ntv create-external-artifact --screen "<screen-id>" --type <text/markdown|text/html> --title "Artifact title" --path /absolute/path\ntv edit-internal-artifact --id "<artifact-id>"\ntv commit-pending-artifact --id "<artifact-id>"\ntv abandon-pending-artifact --id "<artifact-id>"\ntv update-artifact --id "<artifact-id>" --title "New title"\ntv list-artifacts [--screen "<screen-id>"] [--unplaced]\ntv get-artifact --id "<artifact-id>"\ntv delete-artifact --id "<artifact-id>"\n```\n\nScreen commands:\n\n```bash\ntv create-screen --name "Screen name"\ntv list-screens\ntv get-screen --id "<screen-id>"\ntv remove-screen --id "<screen-id>"\n```\n\nScreen membership commands:\n\n```bash\ntv attach-artifact --id "<artifact-id>" --screen "<screen-id>"\ntv detach-artifact --id "<artifact-id>" --screen "<screen-id>"\n```\n\nViewer commands:\n\n```bash\ntv viewer-status\ntv set-active-screen --id "<screen-id>"\ntv focus-artifact --id "<artifact-id>" [--screen "<screen-id>"]\n```\n\nServer commands:\n\n```bash\ntv status\ntv storage-path\ntv serve\ntv stop\n```\n\nCLI behavior notes:\n\n- `--screen` is required on CLI create commands so new artifacts are visible immediately; use `tv attach-artifact` and `tv detach-artifact` for later screen membership changes\n- workflow and mutation commands print plain text\n- read commands print JSON\n- `tv get-screen` includes artifact `kind` and `status`\n- `tv attach-artifact` appends a default-sized card to the right end of the strip; idempotent if the artifact is already on that screen\n- `tv detach-artifact` removes the card from a screen\'s layout; the artifact metadata is never touched, even on the last reference\n- `tv delete-artifact` is the way to globally remove an artifact (detaches from every screen, then trashes the bundle / forgets the external pointer / discards pending-create)\n- `tv list-artifacts` accepts `--screen <id>` to filter by screen membership and `--unplaced` to surface artifacts attached to no screen\n- `tv update-artifact` changes title metadata only\n- `tv set-active-screen` sets which screen the GUI is focused on; the change is persisted and broadcast to connected clients\n- `tv focus-artifact` is a transient nudge: clients switch screens if needed, scroll the artifact\'s card into view, and play a brief highlight animation; pass `--screen <id>` to pin which screen, otherwise the server picks one (preferring the active screen when the artifact is there)\n- `tv viewer-status` prints the active screen ID and the count of connected GUI clients\n- when the CLI reports an error, follow the directive to run `tv help`\n\n## Deferred or out of scope\n\nThese are not part of the current implementation:\n\n- `tv help <topic>`\n- restore-from-trash\n- pending-listing commands\n- attestation or nonce commands\n- stale pending cleanup or stale trash cleanup\n- markdown editor UI recovery\n- client-side pending presentation work\n- multi-section help output';
   }
   const devSkillPath = import_node_path7.default.join(getDevPackageDir(), "skill/SKILL.md");
   if (!(0, import_node_fs4.existsSync)(devSkillPath)) {
@@ -49667,31 +50098,7 @@ function validateExternalArtifactPath(inputPath) {
   }
   return inputPath;
 }
-function formatArtifactRemovalResult(result, context) {
-  if (context.kind === "top-level") {
-    const sID = context.screenID;
-    if (result.outcome === "unlinked") {
-      return [`Artifact ${result.artifactID} unlinked from screen ${sID} (still referenced elsewhere).`];
-    }
-    if (result.outcome === "discarded") {
-      return [
-        `Pending-create artifact ${result.artifactID} unlinked from screen ${sID} and discarded.`,
-        "No trash paths were written because no committed artifact existed yet."
-      ];
-    }
-    if ("bundlePath" in result) {
-      return [
-        `Internal artifact ${result.artifactID} unlinked from screen ${sID}; last reference, moved to trash:`,
-        `  metadata: ${result.metadataPath}`,
-        `  bundle:   ${result.bundlePath}`
-      ];
-    }
-    return [
-      `External artifact ${result.artifactID} unlinked from screen ${sID}; last reference, moved to trash:`,
-      `  metadata: ${result.metadataPath}`,
-      `  external file ${result.externalFilePath} not touched.`
-    ];
-  }
+function formatArtifactRemovalResult(result) {
   if (result.outcome === "unlinked") {
     return [`  ${result.artifactID}: unlinked (still referenced elsewhere)`];
   }
@@ -49711,6 +50118,26 @@ function formatArtifactRemovalResult(result, context) {
     `    external file ${result.externalFilePath} not touched.`
   ];
 }
+function formatDeleteArtifactResult(result) {
+  if (result.outcome === "discarded") {
+    return [
+      `Pending-create artifact ${result.artifactID} discarded.`,
+      "No trash paths were written because no committed artifact existed yet."
+    ];
+  }
+  if ("bundlePath" in result) {
+    return [
+      `Internal artifact ${result.artifactID} moved to trash:`,
+      `  metadata: ${result.metadataPath}`,
+      `  bundle:   ${result.bundlePath}`
+    ];
+  }
+  return [
+    `External artifact ${result.artifactID} moved to trash:`,
+    `  metadata: ${result.metadataPath}`,
+    `  external file ${result.externalFilePath} not touched.`
+  ];
+}
 function formatScreenRemovalResult(result) {
   const header = [
     `Screen ${result.screenID} moved to trash:`,
@@ -49722,7 +50149,7 @@ function formatScreenRemovalResult(result) {
   }
   header.push(`${result.artifactResults.length} referenced artifact(s):`);
   for (const artifactResult of result.artifactResults) {
-    header.push(...formatArtifactRemovalResult(artifactResult, { kind: "cascade" }));
+    header.push(...formatArtifactRemovalResult(artifactResult));
   }
   return header;
 }
@@ -49924,13 +50351,50 @@ If you wish to display temporary content to the user, use an internal artifact i
     await client.artifacts.update({ artifactID: opts.id, title: opts.title });
     writeLine(env.stdout, `Artifact ${opts.id} updated.`);
   });
-  program2.command("remove-artifact").description("Remove an artifact reference from a screen").requiredOption("--id <id>", "Artifact ID").requiredOption("--screen <id>", "Screen ID").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).action(async (opts) => {
+  const detachAction = async (opts) => {
     const client = createAuthenticatedClient(opts.server);
-    const result = await client.artifacts.remove({ artifactID: opts.id, screenID: opts.screen });
-    for (const line of formatArtifactRemovalResult(result, { kind: "top-level", screenID: opts.screen })) {
+    const result = await client.artifacts.detach({
+      artifactID: opts.id,
+      screenID: opts.screen
+    });
+    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("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("--server <url>", "Server URL", DEFAULT_SERVER_URL).action(async (opts) => {
+    const client = createAuthenticatedClient(opts.server);
+    const result = await client.artifacts.attach({
+      artifactID: opts.id,
+      screenID: opts.screen
+    });
+    writeLine(
+      env.stdout,
+      `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) => {
+    const client = createAuthenticatedClient(opts.server);
+    const result = await client.artifacts.delete({ artifactID: opts.id });
+    for (const line of formatDeleteArtifactResult(result)) {
       writeLine(env.stdout, line);
     }
   });
+  program2.command("get-artifact").description("Fetch an artifact's metadata as JSON").requiredOption("--id <id>", "Artifact ID").option("--server <url>", "Server URL", DEFAULT_SERVER_URL).action(async (opts) => {
+    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) => {
+    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("--server <url>", "Server URL", DEFAULT_SERVER_URL).action(async (opts) => {
     const client = createAuthenticatedClient(opts.server);
     const { screen } = await client.screens.create({ name: opts.name });
@@ -49951,6 +50415,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.get({ screenID: opts.id }));
   });
+  program2.command("viewer-status").description("Print viewer state: active screen ID and connected client count").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("set-active-screen").description("Set the screen Television's GUI is focused on; broadcast to connected clients").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, `Active screen set to ${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) => {
+    const client = createAuthenticatedClient(opts.server);
+    const { connectedClients } = await client.viewer.state();
+    if (connectedClients === 0) {
+      env.stderr.write(
+        "Warning: no Television clients are connected; the focus event will be broadcast to nobody.\n"
+      );
+    }
+    const focusInput = { artifactID: opts.id };
+    if (opts.screen !== void 0) focusInput.screenID = opts.screen;
+    const result = await client.viewer.focus(focusInput);
+    writeLine(env.stdout, `Focused artifact ${result.artifactID} on screen ${result.screenID}.`);
+  });
   program2.command("stop").description("Stop the Television system service").action(async () => {
     const daemon = env.createDaemon();
     await daemon.uninstall();
@@ -49979,7 +50465,7 @@ If you wish to display temporary content to the user, use an internal artifact i
 function listVisibleCLICommandNames() {
   const sink = { write: () => true };
   const program2 = createProgram(createEnvironment({ stdout: sink, stderr: sink }));
-  return program2.commands.map((command) => command.name());
+  return program2.commands.filter((command) => !command._hidden).map((command) => command.name());
 }
 async function runCLI(argv, environment = {}) {
   const env = createEnvironment(environment);