@telepath-computer/television 0.1.75 → 0.1.77

package/dist/skills/television/SKILL.md

@@ -1,592 +1,24 @@
-# Television
-
-Television is a persistent artifact screen for agents. Use it when the user
-should be able to inspect, revisit, and refine a file-backed result instead of
-only reading a chat reply.
-
-If you lose context, run:
-
-```bash
-tv help
-```
-
-That command prints this full skill as one blob. There is no topic-scoped help
-in the current implementation.
-
-## Mental model
-
-- A **screen** is a named viewer surface with a layout.
-- An **artifact** is a file-backed result that can exist independently of any
-  screen. It can be unplaced, attached to one screen, or attached to multiple
-  screens.
-- **Screen membership** is separate from artifact identity: attaching/detaching
-  controls which screens show an artifact; deleting removes the artifact
-  globally. The CLI create commands require `--screen` so in-progress artifacts
-  are visible immediately.
-- An **internal artifact** is a Television-managed bundle. You create a pending
-  bundle, edit files in that bundle, then commit it.
-- An **external artifact** is a pointer to an existing absolute file on disk.
-  Television displays that file but does not own or delete it.
-- **Pending** means a create or edit is staged but not yet committed.
-- **Trash** means metadata and committed internal bundles moved out of the live
-  tree. There is no restore workflow in the current scope.
-
-The core workflow is:
-
-1. Decide whether the result should be internal or external.
-2. Decide whether the user should be taken to the new screen or artifact now, or whether the work should happen in the background.
-3. Create or stage the artifact with the CLI.
-4. For internal artifacts, edit files in the pending bundle.
-5. Commit when the validation rules are satisfied.
-
-## Focus model
-
-Television separates state changes from focus.
-
-There are two kinds of focus:
-
-- **Screen focus** is persistent. It decides which screen the TV is currently showing.
-- **Artifact focus** is transient. It may switch screens first, then scroll the artifact into view and briefly highlight it.
-
-Important consequence:
-
-- there is a persisted focused screen
-- there is **not** a persisted focused artifact
-
-State-change commands can optionally trigger focus, but they do not imply it.
-
-Agent-facing create and attach commands require an explicit focus decision:
-
-- `tv create-screen` requires exactly one of `--focus-screen` or `--no-focus`
-- `tv create-internal-artifact`, `tv create-external-artifact`, `tv create-url-artifact`, and `tv attach-artifact` require exactly one of `--focus-artifact` or `--no-focus`
-
-Use this decision rule:
-
-- use `--focus-screen` when the user likely wants to go to the new screen immediately
-- use `--focus-artifact` when the user likely wants to inspect the new artifact immediately
-- use `--no-focus` when the work should happen in the background while keeping the current screen and artifact context unchanged
-
-Heuristic examples:
-
-- use a focus flag for requests like "show me", "open it", "put it on screen", "take me there", or "let me review it"
-- treat user language like **active**, **current**, **showing**, **visible**, **switch to**, **change to**, **go to**, or **show me that** as focus intent for the relevant screen or artifact
-- requests like "switch to the other screen", "show me that artifact", or "change to that screen" should usually translate to `tv focus-screen` or `tv focus-artifact`
-- use `--no-focus` for requests like "set this up", "make it in the background", "prepare it", or "wire this in"
-- also use `--no-focus` when the user says things like "in the background", "while I do something else", "while I work on X", or otherwise signals that your work should proceed on a parallel thread decoupled from their main task
-
-Direct focus commands:
-
-- `tv focus-screen --id <screen-id>` sets persistent screen focus
-- `tv focus-artifact --id <artifact-id> [--screen <screen-id>]` sends a transient artifact-focus nudge
-- `tv focus-status` reports the current persistent screen focus and connected client count
-
-Important communication rule:
-
-- when you use `--no-focus`, explicitly say what you did in chat so the user knows the work happened even though Television did not visibly change
-
-If you forget these rules or the CLI rejects a command for missing focus intent, run `tv help` and reread this section before retrying.
-
-## User communication during multi-step workflows
-
-When you are doing a multi-step artifact workflow, keep the user informed as you
-progress.
-
-Required communication style:
-
-- verbalize key actions and decisions as they happen
-- keep the language concise
-- prefer short updates over long explanations
-- frame updates in the user's world and goals, not in the internal mechanics of the skill or CLI workflow
-- avoid technical workflow jargon unless the user explicitly asks for it
-- do not write reports, long paragraphs, or chatty summaries while the work is in progress
-- do not use lists unless the user explicitly asks for one
-- optimize for speed and token efficiency
-
-Good examples:
-
-- "Starting the artifact now."
-- "Reviewing the draft and source material."
-- "Updating the HTML and efficiently navigating the artifact creation flow."
-- "The artifact did not pass validation yet; fixing the draft notes and retrying."
-- "Finalizing the artifact now."
-- "Done."
-
-Bad examples:
-
-- multi-paragraph progress reports
-- long retrospective narration during execution
-- verbose bullet lists for routine workflow steps
-
-## Internal versus external
-
-Use an **internal artifact** when:
-
-- the artifact is purpose-built for Television
-- Television should own the bundle structure
-- future agents should be able to maintain the result by reading bundle files
-- you need a staged create or staged edit workflow
-
-Use an **external artifact** when:
-
-- a real file already exists on disk
-- the user wants Television to display that existing file
-- you do not need a Television-managed bundle
-
-Decision rule:
-
-- If the result should be maintained as a Television-owned long-lived artifact,
-  choose internal.
-- If the result is already a real file outside Television and should stay that
-  way, choose external.
-
-Supported artifact types:
-
-- `text/markdown`
-- `text/html`
-
-## Internal bundle files
-
-Every internal artifact bundle contains:
-
-- `artifact.md`
-- `data.json`
-- `memory.md`
-- `public/index.md` or `public/index.html`
-
-Fresh pending bundles are intentionally minimal:
-
-- `artifact.md` is blank
-- `memory.md` is blank
-- `public/index.md` or `public/index.html` is blank
-- `data.json` is exactly `{}`
-
-The scaffold is not commit-valid by itself. Learn the required structure from
-this skill, not from placeholder content in the scaffold.
-
-### `artifact.md`
-
-`artifact.md` is the contract for the artifact. It explains what the artifact
-is for, what conceptual material it is based on, how it should render, and how
-later agents should maintain it.
-
-Before commit, `artifact.md` must be non-empty and contain all of these exact
-headings:
-
-```md
-## User intent
-## Purpose
-## Data shape
-## Data sources
-## Rendering
-## Update workflow
-## Non-goals
-```
-
-What each section should capture:
-
-- `## 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
-- `## Purpose`: what the artifact is trying to achieve
-- `## Data shape`: the conceptual shape you reasoned about while authoring; for markdown artifacts this will often just be `{}`
-- `## Data sources`: where the underlying facts, notes, or source material came from and how they were obtained
-- `## Rendering`: how `public/index.md` or `public/index.html` should present it
-- `## Update workflow`: how future agents should refresh or modify it
-- `## Non-goals`: what is intentionally excluded, especially application-like runtime behavior
-
-### `data.json`
-
-`data.json` is a **thinking artifact**, not a runtime payload.
-
-Its purpose is to help the model separate:
-
-- reasoning / planning / authoring structure
-- from final presentation in `public/index.md` or `public/index.html`
-
-Use it to capture the pure conceptual shape of what you are about to render.
-This is an authoring aid for agents, not an application data layer.
-
-Hard rules:
-
-- **Do not treat `data.json` as live runtime state.**
-- **Do not write HTML/JS that loads, depends on, or synchronizes against `data.json`.**
-- **Do not build application-like data-driven artifacts.**
-- **We do not support runtime data-backed artifacts at this time.**
-- Artifacts are static markdown or static HTML documents.
-- HTML artifacts may include JavaScript and extra assets under `public/`, but
-  that JavaScript must stay presentation-oriented and self-contained, not
-  driven by `data.json` as an application state container.
-
-For `text/markdown` artifacts, leave `data.json` as exactly:
-
-```json
-{}
-```
-
-There is usually little value in separating content from presentation for
-markdown artifacts, so prefer `{}` unless there is a very strong authoring
-reason not to.
-
-For `text/html` artifacts, use `data.json` only when it helps you think clearly
-about the material before rendering. It may describe the conceptual structure
-of the artifact, but it must not become a runtime contract.
-
-Validation rule:
-
-- `data.json` must exist and contain valid JSON
-
-The current validator does not require the JSON value to be an object, but an
-object is the normal choice.
-
-### `memory.md`
-
-`memory.md` is the working scratchpad for later agents. Record decisions,
-limitations, data-retrieval notes, problems encountered, what changed, and what
-should be watched during future edits.
-
-Required validation anchors:
-
-- `memory.md` must contain `## Activity Log`
-- `memory.md` must contain at least one UTC timestamp in exact
-  `YYYY-MM-DDTHH:MM:SSZ` format
-- at least one timestamp must be from the last 30 minutes when you commit
-
-The minimum required heading is:
-
-```md
-## Activity Log
-```
-
-What to record beyond that is up to the artifact and the work performed.
+---
+name: television
+description: Television agent guidance and routing for screen and artifact workflows
+---
 
-### `public/index.md` and `public/index.html`
-
-This is the rendered entry file that Television serves.
-
-- Markdown artifacts use `public/index.md`
-- HTML artifacts use `public/index.html`
-- the entry file must match the artifact `type`
-- the entry file must be non-empty before commit
-
-For HTML artifacts:
-
-- `public/index.html` is a full HTML document, not a body fragment
-- additional public assets may live under `public/`
-- keep paths relative to `public/`
-
-## Quality bar
-
-Build artifacts that are durable, truthful, and maintainable by later agents.
-
-Required quality standards:
-
-- be faithful to source data
-- do not invent or hallucinate missing facts
-- do not silently truncate a dataset and pretend it is complete
-- prefer truth over completeness when those goals conflict
-- make limitations, sampling, missing data, and freshness visible
-- keep rendering aligned with the reasoning captured in `artifact.md`, `data.json`, and `memory.md`
-- keep `data.json` as an authoring/thinking artifact rather than a runtime dependency
-- keep the artifact maintainable by a future agent reading only the bundle files
-
-Anti-patterns:
-
-- cursory or low-effort data collection
-- fake data added to make the artifact look complete
-- brittle one-off hacks that a later agent cannot reproduce
-- hidden dependencies that are not documented in `artifact.md` or `memory.md`
-- layout churn during simple data refreshes when the data model did not change
-
-## HTML house style
-
-HTML artifacts should feel intentional and readable inside Television tiles.
-
-Television provides a full base stylesheet for HTML artifacts. Only add custom
-CSS when you need something not covered by the built-in styles. Prefer the base
-styles and theme tokens so artifacts stay visually coherent with the rest of
-Television.
-
-House-style guidance:
-
-- use semantic HTML first
-- keep the most important information near the top
-- design for small, medium, and large tile sizes
-- avoid horizontal overflow unless there is no reasonable alternative
-- make empty states and error states explicit
-- prefer the built-in HTML styling before inventing custom component chrome
-
-### Elements
-
-Standard elements already have sensible defaults, so you usually do not need to
-style from scratch:
-
-- headings (`h1`–`h6`) — sized and weighted
-- `p`, `ul`, `ol` — readable defaults
-- `code` and `pre` — monospace, muted background
-- `blockquote` — left border, muted text
-- `table`, `th`, `td` — bordered, striped headers
-- `button` — styled with border and hover state; use `size="sm"` or `size="md"` when appropriate
-- `hr` — subtle border
-- `a` — inherits color by default
-
-### `.prose` class
-
-Use a `.prose` wrapper for document-style HTML where readable vertical rhythm is
-appropriate. Do not rely on `.prose` for dashboards, tables, control surfaces,
-or dense custom layouts.
-
-```html
-<div class="prose">
-  <h1>Title</h1>
-  <p>Some content with proper spacing between elements.</p>
-  <ul>
-    <li>Item one</li>
-    <li>Item two</li>
-  </ul>
-</div>
-```
-
-### CSS variables
-
-Use the existing Television tokens when they are available in the runtime.
-These are the preferred way to stay aligned with the app theme.
-
-Colors:
-- `--color-bg` — page background
-- `--color-bg-muted` — subtle background
-- `--color-surface` — card or panel background
-- `--color-text` — primary text
-- `--color-text-muted` — secondary or label text
-- `--color-border` — border color
-
-Spacing:
-- `--space-4`
-- `--space-8`
-- `--space-12`
-- `--space-16`
-- `--space-24`
-- `--space-32`
-
-Fonts:
-- `--font-sans`
-- `--font-mono`
-
-Text sizes:
-- `--text-sm`
-- `--text-base`
-- `--text-lg`
-- `--text-xl`
-
-Radius:
-- `--radius-4`
-- `--radius-8`
-
-## Workflows
-
-### Create new internal artifact
-
-1. Decide that the result should be an internal artifact.
-2. Start the pending bundle:
-
-```bash
-tv create-internal-artifact --screen "<screen-id>" --type text/markdown --title "Artifact title" --focus-artifact
-```
-
-Or:
-
-```bash
-tv create-internal-artifact --screen "<screen-id>" --type text/html --title "Artifact title" --no-focus
-```
-
-`--screen` is required for internal artifact creation so the artifact has immediate screen membership. `--focus-artifact` or `--no-focus` is also required so you explicitly decide whether the user should be taken to it now.
-
-3. Read the returned pending path and edit files there.
-4. Write `artifact.md`.
-5. 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.
-6. Think through the artifact in a pure way and write `data.json` only as an authoring aid.
-7. For markdown artifacts, leave `data.json` as `{}` unless there is a compelling authoring reason not to.
-8. Render `public/index.md` or `public/index.html`.
-9. Append a current timestamped activity entry in `memory.md`.
-10. Commit:
-
-```bash
-tv commit-pending-artifact --id "<artifact-id>"
-```
-
-### Update internal artifact with fresh data
-
-1. Stage the edit:
-
-```bash
-tv edit-internal-artifact --id "<artifact-id>"
-```
-
-2. Read `artifact.md`, `data.json`, and `memory.md` before changing anything.
-3. Refresh the underlying facts or source material.
-4. Update `data.json` only if it helps clarify the authoring plan.
-5. For markdown artifacts, prefer to keep `data.json` as `{}`.
-6. Make the minimum rendering changes needed to keep the artifact correct.
-7. Record what changed in `memory.md`.
-8. Commit:
-
-```bash
-tv commit-pending-artifact --id "<artifact-id>"
-```
-
-Avoid unnecessary layout or styling churn during data-only refreshes.
-
-### Modify internal artifact from user feedback
-
-1. Stage the edit:
-
-```bash
-tv edit-internal-artifact --id "<artifact-id>"
-```
-
-2. Read `artifact.md`, `data.json`, and `memory.md`.
-3. Update `artifact.md` if the user intent or non-goals changed.
-4. 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.
-5. Update `data.json` only if it improves the authoring model of the artifact.
-6. For markdown artifacts, prefer to keep `data.json` as `{}`.
-7. Adjust `public/index.md` or `public/index.html` as narrowly as possible.
-8. Record the request, decision, and resulting change in `memory.md`.
-9. Commit:
-
-```bash
-tv commit-pending-artifact --id "<artifact-id>"
-```
-
-### Abandon pending work
-
-If the staged work should be discarded instead of committed:
-
-```bash
-tv abandon-pending-artifact --id "<artifact-id>"
-```
-
-### Create external artifact
-
-Use this when the file already exists on disk and Television should display it
-without owning a bundle:
-
-```bash
-tv create-external-artifact --screen "<screen-id>" --type text/markdown --title "Artifact title" --path /absolute/path/to/file.md --focus-artifact
-```
-
-Or:
-
-```bash
-tv create-external-artifact --screen "<screen-id>" --type text/html --title "Artifact title" --path /absolute/path/to/file.html --no-focus
-```
-
-`--screen` is required for CLI creation so the file has immediate screen membership. `--focus-artifact` or `--no-focus` is also required so you explicitly decide whether the user should be taken to it now.
-
-Rules:
-
-- `--path` must be absolute
-- the file must already exist and be readable
-- the extension must match `type`
-- external artifacts do not use pending create, pending edit, commit, or abandon
-
-### Create URL artifact
-
-Use this when the artifact should display a live web page (an internal docs
-page, a dashboard, a third-party site) rather than content Television owns or a
-file on disk:
-
-```bash
-tv create-url-artifact --screen "<screen-id>" --title "Artifact title" --url https://example.com --focus-artifact
-```
-
-Or:
-
-```bash
-tv create-url-artifact --screen "<screen-id>" --title "Artifact title" --url https://example.com --no-focus
-```
-
-`--screen` is required for CLI creation so the page has immediate screen membership. `--focus-artifact` or `--no-focus` is also required so you explicitly decide whether the user should be taken to it now.
-
-Rules:
-
-- `--url` must be `http://` or `https://`
-- the type is always `text/html` — do not pass `--type`
-- URL artifacts are committed immediately on creation; they have no pending create, pending edit, commit, or abandon lifecycle
-- in the desktop app the page renders in a sandboxed `<webview>`; in the browser it renders in an `<iframe>`
-
-## CLI reference
-
-Artifact commands:
-
-```bash
-tv create-internal-artifact --screen "<screen-id>" --type <text/markdown|text/html> --title "Artifact title" (--focus-artifact|--no-focus)
-tv create-external-artifact --screen "<screen-id>" --type <text/markdown|text/html> --title "Artifact title" --path /absolute/path (--focus-artifact|--no-focus)
-tv create-url-artifact --screen "<screen-id>" --title "Artifact title" --url https://example.com (--focus-artifact|--no-focus)
-tv edit-internal-artifact --id "<artifact-id>"
-tv commit-pending-artifact --id "<artifact-id>"
-tv abandon-pending-artifact --id "<artifact-id>"
-tv update-artifact --id "<artifact-id>" --title "New title"
-tv list-artifacts [--screen "<screen-id>"] [--unplaced]
-tv get-artifact --id "<artifact-id>"
-tv delete-artifact --id "<artifact-id>"
-```
-
-Screen commands:
-
-```bash
-tv create-screen --name "Screen name" (--focus-screen|--no-focus)
-tv list-screens
-tv get-screen --id "<screen-id>"
-tv remove-screen --id "<screen-id>"
-```
-
-Screen membership commands:
-
-```bash
-tv attach-artifact --id "<artifact-id>" --screen "<screen-id>" (--focus-artifact|--no-focus)
-tv detach-artifact --id "<artifact-id>" --screen "<screen-id>"
-```
-
-Focus commands:
+# Television
 
-```bash
-tv focus-status
-tv focus-screen --id "<screen-id>"
-tv focus-artifact --id "<artifact-id>" [--screen "<screen-id>"]
-```
+Television is a persistent artifact screen for agents.
 
-Server commands:
+Load this skill when you need to create, update, inspect, attach, focus, or otherwise manage Television screens and artifacts.
 
-```bash
-tv status
-tv storage-path
-tv serve
-tv stop
-```
+This skill is modular. Do not assume `SKILL.md` contains every rule you need.
 
-CLI behavior notes:
+Read `what-to-read.md` next to decide which companion docs apply.
 
-- `--screen` is required on CLI create commands so new artifacts get immediate screen membership; use `tv attach-artifact` and `tv detach-artifact` for later screen membership changes
-- `tv create-screen` requires exactly one of `--focus-screen` or `--no-focus`; `tv create-internal-artifact`, `tv create-external-artifact`, `tv create-url-artifact`, and `tv attach-artifact` require exactly one of `--focus-artifact` or `--no-focus`
-- workflow and mutation commands print plain text
-- read commands print JSON
-- `tv get-screen` includes artifact `kind` and `status`
-- `tv attach-artifact` appends a default-sized card to the right end of the strip; idempotent if the artifact is already on that screen
-- `tv detach-artifact` removes the card from a screen's layout; the artifact metadata is never touched, even on the last reference
-- `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)
-- `tv list-artifacts` accepts `--screen <id>` to filter by screen membership and `--unplaced` to surface artifacts attached to no screen
-- `tv update-artifact` changes title metadata only
-- `tv focus-screen` sets which screen the GUI is focused on; the change is persisted and broadcast to connected clients
-- `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)
-- `tv focus-status` prints the active screen ID and the count of connected GUI clients
-- when the CLI reports an error, follow the directive to run `tv help`
+## Core companion docs
 
-## Deferred or out of scope
+- `what-to-read.md`
+- `artifact-workflow.md`
+- `html-house-style.md`
 
-These are not part of the current implementation:
+## Known artifact-type docs
 
-- `tv help <topic>`
-- restore-from-trash
-- pending-listing commands
-- attestation or nonce commands
-- stale pending cleanup or stale trash cleanup
-- markdown editor UI recovery
-- client-side pending presentation work
-- multi-section help output
+- `artifact-types/table.md` — Table

package/dist/skills/television/artifact-workflow.md

@@ -0,0 +1,13 @@
+# Artifact workflow
+
+Read this document for Television artifact lifecycle work.
+
+It covers:
+
+- internal vs external artifacts
+- focus decisions
+- pending create/edit/commit/abandon flows
+- internal bundle files
+- validation anchors and commit expectations
+
+If you are authoring an HTML artifact, also read `html-house-style.md` and then check `artifact-types/` for any matching kind-specific doc.

package/dist/skills/television/what-to-read.md

@@ -0,0 +1,26 @@
+# What to read
+
+Use this routing guide to decide which Television companion docs apply.
+
+## Always
+
+- Read `SKILL.md` first.
+- If you are using the `tv` CLI, keep this routing guide in mind while choosing companion docs.
+
+## Artifact lifecycle work
+
+If you are creating, editing, committing, abandoning, deleting, attaching, detaching, or otherwise managing Television artifacts, read:
+
+- `artifact-workflow.md`
+
+## HTML artifact authoring
+
+If the artifact is `text/html`, read:
+
+- `html-house-style.md`
+
+HTML artifact work may also require a kind-specific doc under `artifact-types/`.
+
+## Known artifact-type docs
+
+- `artifact-types/table.md` — Table