@telepath-computer/television 0.1.97 → 0.1.99

package/dist/skills/television/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: television
-description: Mental model, when to use Television vs chat, and how Television's bundled skills are split. Read for screen and CLI work.
+description: Mental model, when to use Television vs chat, and how Television's bundled skills fit together. Read for screen, lifecycle, and CLI work.
 ---
 
 
@@ -44,23 +44,22 @@ That separation matters:
 
 ### Artifact kinds
 
-Three operational categories:
+Three artifact kinds:
 
-- **internal artifact** — Television-managed bundle content. Use when Television should own the result as a durable bundle that later agents can inspect and maintain.
-- **external artifact** — pointer to an existing absolute file on disk. Use when a real file already exists and Television should display it without taking ownership of that file.
-- **URL artifact** — pointer to an external `http(s)://` page. Use when the right answer is to show a live web page rather than Television-owned content or a local file.
+- **markdown** — pointer to an existing absolute markdown file on disk
+- **web-bundle** — Television-managed HTML bundle
+- **url** — pointer to an external `http(s)://` page
 
 ### Lifecycle states
 
-- **pending** — internal create/edit work has been staged but not committed yet
-- **committed** — the artifact is live
-- **trash** — live metadata and any committed internal bundle have been moved out of the active tree
+- **pending** — staged work not yet committed
+- **committed** — live and visible
+- **trash** — moved out of the live tree
 
 Important consequences:
 
-- only internal artifacts use pending create/edit/commit/abandon
-- external file artifacts are committed immediately
-- URL artifacts are committed immediately
+- only **web-bundle** artifacts can be pending
+- **markdown** and **url** artifacts are committed immediately
 - there is no restore-from-trash workflow in the current scope
 
 ### User-facing framing
@@ -81,8 +80,8 @@ Those questions interact, but they are not the same question.
 Television guidance is split across bundled skills.
 
 - Use this skill for screens, focus, artifact lifecycle decisions, and the `tv` CLI.
-- For artifact authoring, install or inspect the bundled skills with `tv skills install` or `tv skills show`.
-- Then let the matching `artifact-*` skill guide the output. Artifact skills can read `house-style.md` and any kind-specific assets from their own skill folder on demand.
+- Install the bundled Television skills into the agent harness skills folder with `tv skills install <path>` (for example `~/.openclaw/skills`, `~/.hermes/skills`, or `~/.agents/skills`) or use `tv skills install -i` before artifact authoring work.
+- For kind-specific HTML work, load the matching skill such as `television-calendar` or `television-table`.
 
 `markdown editor UI recovery` remains out of scope for the current Television workflow.
 
@@ -95,45 +94,34 @@ Use this document when you need to reason about what the `tv` CLI can do, which
 
 The `television` skill is the primary guidance surface for Television screens, focus, and lifecycle work.
 
-If the bundled skills are not installed yet, use:
+Install bundled Television skills with either:
 
 ```bash
-tv skills show
+tv skills install ~/.openclaw/skills
+tv skills install ~/.hermes/skills
+tv skills install ~/.agents/skills
+tv skills install -i
 ```
 
-That lists each bundled skill with its description and absolute path.
-
-To inspect one bundled skill directly:
-
-```bash
-tv skills show television
-tv skills show artifact-calendar
-```
-
-For artifact authoring, install all bundled skills with `tv skills install` or inspect the relevant `artifact-*` skill directly. `tv help` is normal CLI help plus routing pointers.
+`tv help` is normal CLI help plus routing pointers.
 
 ## Command surface
 
-The CLI is the source of truth for command syntax and per-command behavior. Run:
+Run:
 
 ```bash
 tv help
-```
-
-for the full command list. For details, flags, and behavioral nuance for a single command, run:
-
-```bash
 tv help <command>
 ```
 
-The help text is intentionally written to surface non-obvious semantics — idempotency, cascading effects, transient vs persistent state changes, JSON vs plain-text output, and so on. Read it before choosing a command, especially when two commands look superficially similar (detach vs delete, focus-screen vs focus-artifact, attach vs create).
+`tv help <command>` is the source of truth for per-command semantics that are not obvious from the name — idempotency, cascading effects, JSON vs plain-text output, and distinctions between superficially similar commands (detach vs delete, focus-screen vs focus-artifact, attach vs create). Read it before choosing a command when you are unsure.
 
 Commands group into four intents:
 
 - **Screen and display commands** — create, inspect, remove, or switch screens, or change the active display theme (`create-screen`, `list-screens`, `get-screen`, `remove-screen`, `focus-screen`, `focus-status`, `set-theme`).
-- **Artifact creation and lifecycle commands** — create or maintain artifact content (`create-internal-artifact`, `edit-internal-artifact`, `commit-pending-artifact`, `abandon-pending-artifact`, `create-external-artifact`, `create-url-artifact`).
+- **Artifact creation and lifecycle commands** — create or maintain artifact content (`create-web-bundle-artifact`, `edit-artifact`, `commit-artifact`, `abandon-artifact`, `create-markdown-artifact`, `create-url-artifact`).
 - **Artifact membership and removal commands** — place, unplace, inspect, retitle, or remove an existing artifact (`attach-artifact`, `detach-artifact`, `delete-artifact`, `get-artifact`, `list-artifacts`, `update-artifact`, `focus-artifact`).
-- **Server and environment commands** — operate on the Television server itself (`serve`, `status`, `stop`, `storage-path`).
+- **Server and environment commands** — operate on the Television server itself (`serve`, `status`, `stop`, `storage-path`, `skills install`).
 
 When the CLI rejects a command, follow the directive it prints rather than guessing flags.
 
@@ -160,7 +148,7 @@ Important consequence: creating or attaching something does not by itself answer
 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`
+- `tv create-web-bundle-artifact`, `tv create-markdown-artifact`, `tv create-url-artifact`, and `tv attach-artifact` require exactly one of `--focus-artifact` or `--no-focus`
 
 If you omit that decision, the CLI rejects the command. Dedicated `focus-screen` and `focus-artifact` commands can also move attention later as separate steps.
 
@@ -174,20 +162,20 @@ Rules of thumb:
 - **`--no-focus`** when the user is likely to want the result available without breaking their current flow, or when the work should run in the background
 - **direct `focus-screen` / `focus-artifact` commands** when placement and attention movement should happen as separate steps
 
-If you used `--no-focus`, explicitly tell the user what you did and where it went. Otherwise the Television display may not visibly change and the user may not know whether anything happened. Same applies if you placed something on a non-current screen without focusing it: name the screen. If you did move focus, say so, because that affects what the user will see next.
+When your action would not be visually obvious to the user — you used `--no-focus`, you placed something on a non-current screen, or you moved focus — tell them what you did, name the screen, and say what they should see. Otherwise the Television display may not change in a way they can interpret.
 
 ## Listening for focus intent in the user's language
 
 The user's phrasing is a strong cue — not a deterministic rule, but a real signal worth listening for.
 
-Phrases that usually indicate the user wants attention moved (use a focus flag, or a direct `focus-screen` / `focus-artifact` command):
+Phrases that usually indicate the user wants attention moved:
 
 - "show me", "show me that", "let me see it", "let me review it"
 - "switch to", "change to", "go to", "take me there", "open it"
 - "put it on screen", "put it on my screen", "bring it up"
 - references to the **active**, **current**, **showing**, or **visible** screen or artifact
 
-Phrases that usually indicate the user wants the work to happen without disturbing their current view (use `--no-focus`):
+Phrases that usually indicate the user wants the work to happen without disturbing their current view:
 
 - "in the background", "while I'm doing X", "while I work on Y go and do Z"
 - "set this up", "prepare it", "wire it in", "get it ready"
@@ -223,7 +211,7 @@ Reach for `tv create-screen` when:
 
 - the request is meaningfully separate from the current screen's purpose
 - the result should become its own durable workspace the user can return to
-- mixing it into the current screen would make the user's mental model worse (e.g., a research dossier vs a live dashboard, or two unrelated topics that should not share a strip)
+- mixing it into the current screen would make the user's mental model worse
 
 Default to placing things on an existing screen unless one of those conditions is true. Spawning a new screen for every request fragments the user's workspace; spawning none ever forces unrelated content together.
 
@@ -232,22 +220,38 @@ Default to placing things on an existing screen unless one of those conditions i
 
 Read this document for Television artifact lifecycle work — creating, updating, committing, abandoning, attaching, detaching, deleting.
 
-The earlier sections in this skill cover the artifact-vs-chat decision, the Television mental model, and the CLI focus model. This section covers everything else: which type to use, the staged lifecycle for internal artifacts, what each bundle file contains, validation rules, the quality bar, and the prescriptive recipes.
+If you need bundled Television authoring skills installed first, copy them into the agent harness skills folder with `tv skills install <path>` (for example `~/.openclaw/skills`, `~/.hermes/skills`, or `~/.agents/skills`) or use `tv skills install -i`.
 
-If you are authoring an HTML artifact, use the matching `artifact-*` skill and read its `house-style.md` guidance when directed.
+If you are authoring a specialized HTML artifact, read the matching kind skill after this one — for example `television-calendar` or `television-table`.
 
-## Markdown or HTML
+## Choosing the artifact kind
 
-Once you have decided to make an artifact, choose the type:
+Television has three artifact kinds. Pick the one that best fits the result:
 
-- **markdown** when the result is primarily textual and benefits from simple structured reading. Headings, lists, code blocks, links. Most research summaries, comparisons, and write-ups.
-- **HTML** when richer layout, stronger visual hierarchy, or more custom presentation will make the result substantially better. Dashboards, multi-column layouts, custom-styled cards, simple interactive widgets, anything where typographic prose is not the dominant mode.
+- **markdown** — the default. Create or use a markdown file in a sensible filesystem location, then point a markdown artifact at it. Television displays it; the file itself is the user's. This is right for almost all textual results: notes, reports, research summaries, comparisons, write-ups.
+- **web-bundle** — a Television-managed HTML bundle. Reach for this when the additional visual structure (rich layout, hierarchy, styled cards, custom widgets, dashboards) is doing real communicative work that markdown cannot. More work to author and maintain than markdown; only pays off when the structure earns its keep.
+- **url** — pointer to a live page (a remote site or a local web application). Use when the right answer is to embed an existing page rather than author Television-owned content.
 
-Default to markdown. HTML is more work to author, more work to maintain, and only pays off when the visual structure is doing real communicative work.
+If you are unsure between markdown and web-bundle, default to markdown. A markdown artifact can be rewritten as a web bundle later if the structure proves insufficient.
 
-## Authoring quality
+## Where the markdown file goes
+
+When you create a markdown artifact in response to a user request, you have to decide where the underlying file lives on disk. This decision is user-dependent — there is no Television-defined location, and no formula. The right path depends on the user's workspace conventions.
+
+Ask yourself:
+
+- If the user asked you to take a note, where would you put it?
+- If the user asked you to do web research and create a report, where would you put it?
+
+The point of those questions isn't to produce a single canonical answer. It's to direct you at the *class* of location (the user's notes folder, an agent workspace, the project root, a scratch directory) that fits the request and the user's working context.
+
+If you cannot infer a sensible location from context, ask the user rather than guess. A misplaced file is worse than a brief clarifying question.
+
+Consider including Television-indicating cues in the file name or path — a `television/` subdirectory, a filename marker, or similar — so the user and future agents can recognize that a given file was created by and for use in Television. A sensible default when no explicit user-supplied path is provided.
+
+Always tell the user where you put it. If the user can't see where the file landed, they may not know anything happened, or may not be able to find it later.
 
-This applies to every artifact you author or maintain — internal, external, or URL.
+## Authoring quality
 
 Build artifacts that are durable, truthful, and maintainable by later agents.
 
@@ -258,8 +262,7 @@ Required standards:
 - do not silently truncate a dataset and pretend it is comprehensive
 - prefer truth over completeness when those goals conflict
 - make limitations, sampling, gaps, and freshness visible when they matter
-- keep the rendering aligned with the reasoning captured in the bundle files (for internal artifacts)
-- keep the artifact maintainable by a future agent reading only the bundle (for internal artifacts)
+- avoid unnecessary layout or styling churn during simple refreshes
 
 Anti-patterns to avoid:
 
@@ -267,245 +270,259 @@ Anti-patterns to avoid:
 - fake completeness — padding to look thorough
 - brittle one-off hacks that a later agent cannot reproduce
 - hidden dependencies that are not documented in the bundle
-- unnecessary layout or styling churn during a simple data refresh
 
 ## Before creating artifacts
 
-Before starting artifact-creation tool work, briefly tell the user what you are about to make. Artifact creation can take noticeable time, and the user may not otherwise be able to tell what is happening during the agent loop.
-
-Also work expediently. Do not skip lifecycle or validation steps, but avoid unnecessary extra steps when building the artifact. There is real user wait time while artifact creation is in progress.
+Before starting artifact creation, briefly tell the user what you are about to make. Artifact creation can be time-consuming; the user should be kept informed. Think about how to work expediently and avoid unnecessary extra steps without compromising the outcome.
 
 ## In-flight narration style
 
-While a multi-step artifact workflow is running, narrate concisely so the user knows you are still working. Frame updates in their world and goals, not in CLI mechanics or workflow jargon.
+While a multi-step artifact workflow is running, narrate concisely so the user knows you are still working.
 
 Required style:
 
 - verbalize key actions and decisions as they happen
 - keep updates short — a sentence per beat, not a paragraph
 - prefer the user's framing over Television's internal machinery
-- do not write reports, retrospective summaries, or chatty explanations while work is in progress
-- do not use bullet 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 moving through the artifact creation flow."
-- "The artifact did not pass validation; fixing the draft notes and retrying."
+- "Updating the HTML and moving through the artifact flow."
 - "Finalizing the artifact now."
 - "Done."
 
 Avoid:
 
-- multi-paragraph progress reports
-- long retrospective narration during execution
-- verbose bullet lists for routine workflow steps
-- workflow jargon ("calling commit-pending-artifact", "validator rejected memory.md") unless the user is debugging Television itself
-
-## Internal bundle structure
+- multi-paragraph progress reports or long retrospective narration during execution
+- verbose bullet lists for routine workflow steps (use bullets only when the user explicitly asks)
+- workflow jargon ("calling commit-artifact", "promoting the pending bundle") unless the user is debugging Television itself
 
-Internal artifacts are Television-managed bundles. Every internal artifact bundle contains:
+## Web-bundle workflow
 
-- `artifact.md`
-- `data.json`
-- `memory.md`
-- `public/index.md` or `public/index.html`
+### Pending is the default
 
-Fresh pending bundles are intentionally minimal. Do not treat the scaffold as meaningfully authored content — the structure below describes what each file must contain before commit.
+The recommended workflow for new Television-owned web bundles is the pending workflow:
 
-External artifacts and URL artifacts have no bundle and no pending lifecycle.
-
-### `artifact.md`
-
-`artifact.md` is the contract for the artifact. It explains what the artifact is for, what 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
+```bash
+tv create-web-bundle-artifact --screen "<screen-id>" --title "Artifact title" --focus-artifact
 ```
 
-Section guidance:
+This creates a pending bundle under `.pending/<id>/`. Nothing is visible until commit.
 
-- `## User intent` — faithfully preserve what the user actually wants, including requests, constraints, corrections, complaints, and feedback when those matter. Use direct quotes when helpful.
-- `## Purpose` — what the artifact is trying to achieve.
-- `## Data shape` — the conceptual structure you used while authoring. For markdown artifacts this is often just `{}`.
-- `## Data sources` — where the underlying facts came from and how they were obtained.
-- `## Rendering` — how the public entry file should present the result.
-- `## Update workflow` — how a future agent should refresh or modify it correctly.
-- `## Non-goals` — important exclusions, especially when it would be easy to overbuild (e.g., "this is a static report, not a live dashboard").
+Inside the pending bundle you write:
 
-### `data.json`
+- `public/` — the public render directory; the entry file is `public/index.html`, and additional assets (CSS, images, fonts, helper JS) may live under `public/`. Keep asset paths relative to the bundle so they resolve under `<id>/public/` when served
+- `artifact.md` — bundle documentation for future agents (see below)
+- `memory.md` — maintenance log for future agents (see below)
+- a data-oriented supporting file when the artifact has non-trivial underlying data (see "Data before presentation")
 
-`data.json` is a thinking artifact, not a runtime payload.
+### Data before presentation
 
-Use it to clarify authoring structure when that helps you think, not to create an application state layer.
+Before authoring the final HTML, think through the underlying data in a pure-data way.
 
-Hard rules:
+Ask yourself:
 
-- do not treat `data.json` as live runtime state
-- do not build HTML/JS that depends on `data.json` as an application data source
-- do not turn Television artifacts into runtime data-backed apps through `data.json`
-- artifacts are static markdown or static HTML documents; HTML artifacts may include presentation-oriented JavaScript and assets under `public/`, but JS must not be driven by `data.json` as application state
+- what facts exist?
+- what structure do they have?
+- what is missing?
+- what separation between data and presentation would help the next agent?
 
-For markdown artifacts, prefer to leave `data.json` as exactly:
+Capture this reasoning in a supporting document inside the bundle — pick a file name and format that fits the data (a markdown table, a JSON snapshot, a YAML manifest, whatever expresses the data cleanly). Author this data-oriented asset **before** the presentation assets. The staged workflow (data first, then presentation) keeps the thinking discipline visible and gives the next agent a clear handle on what the rendering is built from.
 
-```json
-{}
-```
-
-For HTML artifacts, use `data.json` only when it materially helps your authoring process.
-
-Validation requires that `data.json` exist and contain valid JSON.
-
-### `memory.md`
-
-`memory.md` is for maintenance-oriented notes to future agents.
+### `artifact.md`
 
-Record decisions, limitations, source-retrieval notes, problems encountered, what changed, and anything that should be watched during future edits.
+`artifact.md` is the bundle's self-documentation for the next agent. Write it so that an agent reading only this file can pick up the artifact and continue work on it.
 
-Required validation anchors:
+Structure it with these sections:
 
-- `memory.md` must contain `## Activity Log`
-- it must contain at least one UTC timestamp in exact `YYYY-MM-DDTHH:MM:SSZ` format
-- at least one timestamp must be fresh enough for commit validation (recent enough to prove this commit is current)
+- **User intent** — what the user actually asked for, in their language. Use direct quotes where helpful, close paraphrase where clearer. Write this section *first*, before any other authoring work: it anchors the artifact in the user's actual ask and keeps you from retrofitting intent from memory after the fact.
+- **Purpose** — what the artifact is for and what success looks like.
+- **Data sources** — where the underlying facts came from and how they were obtained.
+- **Rendering** — how `public/index.html` should present the result, and why this presentation fits the data.
+- **Update workflow** — how a future agent should refresh or modify the artifact correctly.
+- **Non-goals** — important exclusions, especially when it would be easy to overbuild (e.g., "this is a static report, not a live dashboard").
 
-### Public entry file
+When the user's ask changes during a later edit, **revise** the User intent section to reflect what they want now — preserve the new language as direct quotes or close paraphrases. Old intent that no longer reflects the current ask should be revised, not just appended to. The goal is a faithful record of the *current* request, not a transcript of the conversation history.
 
-This is what Television actually renders.
+### `memory.md`
 
-- 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
-- HTML artifacts may include additional public assets under `public/`; keep paths relative
+`memory.md` is a maintenance log addressed to the next agent who will edit this artifact.
 
-For HTML artifacts, also use the matching `artifact-*` skill and read its
-`house-style.md` guidance.
+Record:
 
-## Workflows
+- decisions made during authoring and their reasons
+- limitations of the source material or rendering
+- problems encountered and how they were resolved
+- what changed in each edit pass
+- anything a future agent should watch for
 
-These recipes are prescriptive on purpose. The lifecycle steps and their order matter — `commit-pending-artifact` will refuse a bundle that has not satisfied the validation anchors above.
+A simple chronological structure works. When you commit a new edit, append an entry summarizing what changed and why.
 
-### Create a new internal artifact
+### Create a new web bundle
 
-1. Confirm internal is the right kind for this result (the result should be Television-owned and maintainable by future agents).
-2. Tell the user what you are about to make before starting tool work.
-3. Stage the pending bundle:
+1. Tell the user what you are about to make.
+2. Create the pending bundle:
 
    ```bash
-   tv create-internal-artifact --screen "<screen-id>" --type text/markdown --title "Artifact title" --focus-artifact
+   tv create-web-bundle-artifact --screen "<screen-id>" --title "Artifact title" --focus-artifact
    ```
 
-   Or, for HTML:
+3. Inside the pending bundle, write `artifact.md` — start with **User intent** before any other authoring work.
+4. Think through the underlying data and author the data-oriented supporting file (see "Data before presentation").
+5. Write `memory.md` with an initial entry describing this create pass.
+6. Author the presentation under `public/` — `public/index.html` plus any additional assets you need.
+7. Commit:
 
    ```bash
-   tv create-internal-artifact --screen "<screen-id>" --type text/html --title "Artifact title" --no-focus
+   tv commit-artifact --id "<artifact-id>"
    ```
 
-   `--screen` is required so the artifact has immediate screen membership. `--focus-artifact` or `--no-focus` is required so focus is an explicit choice. (See the CLI capabilities section earlier in this skill for how to make that choice.)
+   Commit is the pending → committed promotion.
 
-4. Read the returned pending path. Edit files there.
-5. Write `## User intent` in `artifact.md` **first**, before authoring anything else. Capture the user's language faithfully — direct quotes when helpful, close paraphrase when clearer. The rest of the bundle should serve that intent, so writing it first anchors the work and keeps you from retrofitting intent from memory after the fact.
-6. Fill out the remaining required `artifact.md` headings: `## Purpose`, `## Data shape`, `## Data sources`, `## Rendering`, `## Update workflow`, `## Non-goals`.
-7. Use `data.json` only as an authoring aid — not as runtime state. For markdown artifacts, leave it as `{}` unless there is a strong authoring reason not to.
-8. Render `public/index.md` or `public/index.html`. The entry file must match the artifact type and must be non-empty.
-9. Append a current UTC-timestamped entry under `## Activity Log` in `memory.md` (format: `YYYY-MM-DDTHH:MM:SSZ`). At least one timestamp must be fresh enough to satisfy commit validation.
-10. Commit:
+### Edit a committed web bundle
 
-    ```bash
-    tv commit-pending-artifact --id "<artifact-id>"
-    ```
+Use:
 
-    If the validator rejects the commit, read the directive, fix the bundle, and retry. Do not bypass validation by editing committed state directly.
+```bash
+tv edit-artifact --id "<artifact-id>"
+```
 
-### Update an internal artifact with fresh data
+This copies the committed bundle into `.pending/<id>/`. While the artifact is pending-edit, the viewer keeps showing the last committed content unchanged.
 
-1. Stage the edit:
+Before changing anything, read the existing `artifact.md` and `memory.md`. They tell you what the artifact is for, what shape it expects, and what prior agents decided.
 
-   ```bash
-   tv edit-internal-artifact --id "<artifact-id>"
-   ```
+When the user's ask has changed, revise **User intent** in `artifact.md` (and **Non-goals** if anything has been ruled out). Update the data-oriented supporting file only if the underlying data changed. Make the minimum rendering changes the new ask requires. Append a `memory.md` entry describing what changed and why.
 
-2. Read `artifact.md`, `data.json`, and `memory.md` before changing anything. They tell you what the artifact is, what shape it expects, and what prior agents decided.
-3. Refresh the underlying facts or source material.
-4. Update `data.json` only if it improves the authoring model. For markdown artifacts, prefer to keep it as `{}`.
-5. Make the minimum rendering changes needed to keep the artifact correct. Avoid layout or styling churn during a data-only refresh — that breaks the user's mental model of "same artifact, fresher data."
-6. Append a current UTC-timestamped entry to `## Activity Log` in `memory.md` describing what changed.
-7. Commit:
+When you are ready:
 
-   ```bash
-   tv commit-pending-artifact --id "<artifact-id>"
-   ```
+```bash
+tv commit-artifact --id "<artifact-id>"
+```
 
-### Modify an internal artifact from user feedback
+If you want to discard the staged edit instead:
 
-1. Stage the edit (`tv edit-internal-artifact --id "<artifact-id>"`).
-2. Read `artifact.md`, `data.json`, and `memory.md`.
-3. Update `## User intent` in `artifact.md` so it remains a faithful record of what the user actually wants now. Preserve the user's new language as direct quotes or close paraphrases. Old intent that no longer reflects the current ask should be revised, not just appended to.
-4. Update `## Non-goals` if the user has ruled something out.
-5. Adjust `data.json` only if the authoring model changed.
-6. Adjust `public/index.md` or `public/index.html` as narrowly as the change requires.
-7. Append an `## Activity Log` entry capturing the request, the decision, and the resulting change with a current timestamp.
-8. Commit.
+```bash
+tv abandon-artifact --id "<artifact-id>"
+```
 
-### Abandon pending work
+### Skip pending
 
-If staged work should be discarded rather than committed:
+If you do not want pending states for this artifact, create the committed bundle immediately:
 
 ```bash
-tv abandon-pending-artifact --id "<artifact-id>"
+tv create-web-bundle-artifact --screen "<screen-id>" --title "Artifact title" --skip-pending --no-focus
 ```
 
-For a pending create, the artifact never becomes live. For a pending edit, the previously committed version is kept unchanged.
+After that, write `artifact.md`, the data asset, `memory.md`, and the presentation under `public/` directly in the committed bundle. The content discipline is the same as the pending workflow; only the staging step is skipped.
 
-### Create an external artifact
+## Markdown artifacts
 
-External artifacts point at a file that already exists on disk. Television displays it and watches for changes, but does not own it — there is no bundle and no pending lifecycle.
+Markdown artifacts point at an existing absolute markdown file on disk. They are committed immediately and do not use pending.
 
 ```bash
-tv create-external-artifact --screen "<screen-id>" --type text/markdown --title "Artifact title" --path /absolute/path/to/file.md --focus-artifact
+tv create-markdown-artifact --screen "<screen-id>" --title "Artifact title" --path /absolute/path/to/file.md --focus-artifact
 ```
 
-Or:
+Rules:
+
+- `--path` must be absolute
+- the file must already exist and be readable
+- Television watches the file for changes but does not own or delete it
+
+## URL artifacts
+
+URL artifacts point at an external `http(s)://` page. They are committed immediately and do not use pending.
 
 ```bash
-tv create-external-artifact --screen "<screen-id>" --type text/html --title "Artifact title" --path /absolute/path/to/file.html --no-focus
+tv create-url-artifact --screen "<screen-id>" --title "Artifact title" --url https://example.com --no-focus
 ```
 
+Use this when the right answer is to embed a live page rather than author a Television-owned artifact.
+
 Rules:
 
-- `--path` must be absolute
-- the file must already exist and be readable
-- the extension must match `--type`
-- there is no pending create / pending edit / commit / abandon flow
-- `tv delete-artifact` only forgets the pointer; the underlying file is never deleted
+- `--url` must be `http://` or `https://`; other schemes (`file://`, `javascript:`, etc.) are rejected
+- in the desktop app the page renders in a sandboxed `<webview>`; in the browser it renders in an `<iframe>`
 
-### Create a URL artifact
+If the user reports that an embedded URL artifact is rendering blank, this is most likely the site refusing iframe embedding (typically via `X-Frame-Options` or a `frame-ancestors` CSP directive). Recovery: create a markdown or web-bundle artifact that just links to the page instead of embedding it.
 
-URL artifacts embed a live `http(s)://` page. They commit immediately and have no pending lifecycle.
+## Abandoning staged work
+
+If staged web-bundle work should be discarded rather than committed:
 
 ```bash
-tv create-url-artifact --screen "<screen-id>" --title "Artifact title" --url https://example.com --focus-artifact
+tv abandon-artifact --id "<artifact-id>"
 ```
 
-Or:
+For a pending create, the artifact never becomes live. For a pending edit, the previously committed version remains live.
 
-```bash
-tv create-url-artifact --screen "<screen-id>" --title "Artifact title" --url https://example.com --no-focus
+# Authoring artifacts
+
+You're writing a single self-contained HTML artifact that will be rendered
+inside a Television viewer (or downloaded for offline viewing later). This
+skill documents the conventions you must follow.
+
+## House style
+
+Artifacts inherit a versioned, canonical stylesheet served by the
+Television runtime. Include it in `<head>`:
+
+```html
+<link rel="stylesheet" href="/canonical/v1/styles.css">
 ```
 
-Rules:
+That stylesheet provides:
+
+- A CSS reset and font-face declarations (Hind variable font, loaded
+  automatically — no extra link tags needed).
+- The full design-system token catalog as CSS custom properties:
+  typography (`--text-*`, `--font-*`, `--leading-*`), spacing
+  (`--space-*`), color (`--color-*`, `--neutral-*`), radii
+  (`--radius-*`), and surfaces. The runtime source of truth is
+  `packages/ui/styles/tokens.css`; the bundle inlines it.
+- Bare-tag styling. `body`, `a`, `h1`–`h6`, `code`, `pre`, and similar
+  semantic elements have built-in styling — you do not need to add
+  classes to make them look right.
+
+**Lean on semantic HTML and the bare-tag styling.** Reach for `<h1>`,
+`<p>`, `<ul>`, `<code>`, etc. before inventing custom classes. Use tokens
+(`var(--space-8)`, `var(--color-text-muted)`, etc.) for any custom CSS
+you do write — never hardcoded pixel values or hex colors.
+
+## Document shape
+
+Emit a complete HTML document, not a fragment:
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <title>{{title}}</title>
+    <link rel="stylesheet" href="/canonical/v1/styles.css">
+  </head>
+  <body>
+    <!-- artifact content -->
+  </body>
+</html>
+```
 
-- `--url` must be `http://` or `https://`
-- the type is always `text/html` — do not pass `--type`
-- in the desktop app the page renders in a sandboxed `<webview>`; in the browser it renders in an `<iframe>`
-- some sites block embedding (X-Frame-Options, CSP); if the page may be one of those, prefer an internal artifact that links to the page
+## Conventions
+
+- **Self-contained.** By default, emit one HTML file. If the active
+  kind skill ships local CSS or JS assets, copy or inline them from the
+  skill folder so the final artifact remains self-contained without any
+  `/skills/...` runtime dependency.
+- **No arbitrary `<script>` tags.** Static HTML is the default. Only
+  include local, bundled scripts when the active kind skill explicitly
+  requires them.
+- **No external network fetches.** No CDN links, no remote images, no
+  font URLs other than what `/canonical/v1/styles.css` already includes.
+- **No inline `<style>` overrides for chrome-level concerns.** Small
+  layout-specific styles for the artifact's content are fine; redefining
+  brand colors or typography is not.
+- **Use tokens, not hardcoded values.** `padding: var(--space-12)`, not
+  `padding: 12px`. `color: var(--color-text-muted)`, not `color: #999`.