@telepath-computer/television 0.1.84 → 0.1.85
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/cli.cjs +83 -137
- package/dist/skills/{television/artifact-types/calendar.md → artifact-calendar/SKILL.md} +20 -12
- package/dist/skills/artifact-calendar/calendar.css +1 -0
- package/dist/skills/artifact-calendar/calendar.js +716 -0
- package/dist/skills/{television/html-house-style.md → artifact-calendar/house-style.md} +7 -7
- package/dist/skills/{television/artifact-types/table.md → artifact-table/SKILL.md} +4 -1
- package/dist/skills/artifact-table/house-style.md +67 -0
- package/dist/skills/television/SKILL.md +428 -12
- package/dist/web/assets/index-D3-COwxd.js +522 -0
- package/dist/web/index.html +1 -1
- package/package.json +1 -1
- package/dist/skills/television/.skill-manifest.json +0 -29
- package/dist/skills/television/artifact-workflow.md +0 -285
- package/dist/skills/television/cli-capabilities.md +0 -145
- package/dist/web/assets/index-BfzWRMnk.js +0 -522
|
@@ -1,7 +1,3 @@
|
|
|
1
|
-
---
|
|
2
|
-
description: House style and conventions for authoring HTML artifacts that render inside Television.
|
|
3
|
-
---
|
|
4
|
-
|
|
5
1
|
# Authoring artifacts
|
|
6
2
|
|
|
7
3
|
You're writing a single self-contained HTML artifact that will be rendered
|
|
@@ -55,9 +51,13 @@ Emit a complete HTML document, not a fragment:
|
|
|
55
51
|
|
|
56
52
|
## Conventions
|
|
57
53
|
|
|
58
|
-
- **Self-contained.**
|
|
59
|
-
|
|
60
|
-
|
|
54
|
+
- **Self-contained.** By default, emit one HTML file. If the active
|
|
55
|
+
kind skill ships local CSS or JS assets, copy or inline them from the
|
|
56
|
+
skill folder so the final artifact remains self-contained without any
|
|
57
|
+
`/skills/...` runtime dependency.
|
|
58
|
+
- **No arbitrary `<script>` tags.** Static HTML is the default. Only
|
|
59
|
+
include local, bundled scripts when the active kind skill explicitly
|
|
60
|
+
requires them.
|
|
61
61
|
- **No external network fetches.** No CDN links, no remote images, no
|
|
62
62
|
font URLs other than what `/canonical/v1/styles.css` already includes.
|
|
63
63
|
- **No inline `<style>` overrides for chrome-level concerns.** Small
|
|
@@ -1,9 +1,12 @@
|
|
|
1
1
|
---
|
|
2
|
-
|
|
2
|
+
name: artifact-table
|
|
3
|
+
description: Author dense Airtable-style HTML record tables using the shared Television house style.
|
|
3
4
|
---
|
|
4
5
|
|
|
5
6
|
# Authoring a record table
|
|
6
7
|
|
|
8
|
+
Before authoring the artifact, read `house-style.md` in this skill folder.
|
|
9
|
+
|
|
7
10
|
A dense, Airtable-style table of records. Lots of cells, mixed cell types,
|
|
8
11
|
structured rows. Should look crisp at a glance and read like real software,
|
|
9
12
|
not a styled spreadsheet.
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# Authoring artifacts
|
|
2
|
+
|
|
3
|
+
You're writing a single self-contained HTML artifact that will be rendered
|
|
4
|
+
inside a Television viewer (or downloaded for offline viewing later). This
|
|
5
|
+
skill documents the conventions you must follow.
|
|
6
|
+
|
|
7
|
+
## House style
|
|
8
|
+
|
|
9
|
+
Artifacts inherit a versioned, canonical stylesheet served by the
|
|
10
|
+
Television runtime. Include it in `<head>`:
|
|
11
|
+
|
|
12
|
+
```html
|
|
13
|
+
<link rel="stylesheet" href="/canonical/v1/styles.css">
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
That stylesheet provides:
|
|
17
|
+
|
|
18
|
+
- A CSS reset and font-face declarations (Hind variable font, loaded
|
|
19
|
+
automatically — no extra link tags needed).
|
|
20
|
+
- The full design-system token catalog as CSS custom properties:
|
|
21
|
+
typography (`--text-*`, `--font-*`, `--leading-*`), spacing
|
|
22
|
+
(`--space-*`), color (`--color-*`, `--neutral-*`), radii
|
|
23
|
+
(`--radius-*`), and surfaces. The runtime source of truth is
|
|
24
|
+
`packages/ui/styles/tokens.css`; the bundle inlines it.
|
|
25
|
+
- Bare-tag styling. `body`, `a`, `h1`–`h6`, `code`, `pre`, and similar
|
|
26
|
+
semantic elements have built-in styling — you do not need to add
|
|
27
|
+
classes to make them look right.
|
|
28
|
+
|
|
29
|
+
**Lean on semantic HTML and the bare-tag styling.** Reach for `<h1>`,
|
|
30
|
+
`<p>`, `<ul>`, `<code>`, etc. before inventing custom classes. Use tokens
|
|
31
|
+
(`var(--space-8)`, `var(--color-text-muted)`, etc.) for any custom CSS
|
|
32
|
+
you do write — never hardcoded pixel values or hex colors.
|
|
33
|
+
|
|
34
|
+
## Document shape
|
|
35
|
+
|
|
36
|
+
Emit a complete HTML document, not a fragment:
|
|
37
|
+
|
|
38
|
+
```html
|
|
39
|
+
<!doctype html>
|
|
40
|
+
<html lang="en">
|
|
41
|
+
<head>
|
|
42
|
+
<meta charset="utf-8">
|
|
43
|
+
<title>{{title}}</title>
|
|
44
|
+
<link rel="stylesheet" href="/canonical/v1/styles.css">
|
|
45
|
+
</head>
|
|
46
|
+
<body>
|
|
47
|
+
<!-- artifact content -->
|
|
48
|
+
</body>
|
|
49
|
+
</html>
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Conventions
|
|
53
|
+
|
|
54
|
+
- **Self-contained.** By default, emit one HTML file. If the active
|
|
55
|
+
kind skill ships local CSS or JS assets, copy or inline them from the
|
|
56
|
+
skill folder so the final artifact remains self-contained without any
|
|
57
|
+
`/skills/...` runtime dependency.
|
|
58
|
+
- **No arbitrary `<script>` tags.** Static HTML is the default. Only
|
|
59
|
+
include local, bundled scripts when the active kind skill explicitly
|
|
60
|
+
requires them.
|
|
61
|
+
- **No external network fetches.** No CDN links, no remote images, no
|
|
62
|
+
font URLs other than what `/canonical/v1/styles.css` already includes.
|
|
63
|
+
- **No inline `<style>` overrides for chrome-level concerns.** Small
|
|
64
|
+
layout-specific styles for the artifact's content are fine; redefining
|
|
65
|
+
brand colors or typography is not.
|
|
66
|
+
- **Use tokens, not hardcoded values.** `padding: var(--space-12)`, not
|
|
67
|
+
`padding: 12px`. `color: var(--color-text-muted)`, not `color: #999`.
|
|
@@ -1,14 +1,11 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: television
|
|
3
|
-
description: Mental model, when to use Television vs chat, and
|
|
4
|
-
version: 0.1.10
|
|
3
|
+
description: Mental model, when to use Television vs chat, and how Television's bundled skills are split. Read for screen and CLI work.
|
|
5
4
|
---
|
|
6
5
|
|
|
7
6
|
|
|
8
7
|
# Television
|
|
9
8
|
|
|
10
|
-
*Skill content version: 0.1.10*
|
|
11
|
-
|
|
12
9
|
Television is a persistent artifact screen for agents.
|
|
13
10
|
|
|
14
11
|
Load this skill when you need to create, update, inspect, attach, focus, or otherwise manage Television screens and artifacts.
|
|
@@ -79,17 +76,436 @@ Questions to keep straight:
|
|
|
79
76
|
|
|
80
77
|
Those questions interact, but they are not the same question.
|
|
81
78
|
|
|
82
|
-
##
|
|
79
|
+
## Related skills
|
|
83
80
|
|
|
84
|
-
|
|
81
|
+
Television guidance is split across bundled skills.
|
|
85
82
|
|
|
86
|
-
-
|
|
87
|
-
- For artifact
|
|
88
|
-
-
|
|
83
|
+
- Use this skill for screens, focus, artifact lifecycle decisions, and the `tv` CLI.
|
|
84
|
+
- For artifact authoring, install or inspect the bundled skills with `tv skills install` or `tv skills show`.
|
|
85
|
+
- 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.
|
|
89
86
|
|
|
90
87
|
`markdown editor UI recovery` remains out of scope for the current Television workflow.
|
|
91
88
|
|
|
92
|
-
## Known artifact-type docs
|
|
93
89
|
|
|
94
|
-
|
|
95
|
-
|
|
90
|
+
# TV CLI capabilities
|
|
91
|
+
|
|
92
|
+
Use this document when you need to reason about what the `tv` CLI can do, which command family fits the user's request, and how focus and screen placement should be decided.
|
|
93
|
+
|
|
94
|
+
## Agent recovery surfaces
|
|
95
|
+
|
|
96
|
+
The `television` skill is the primary guidance surface for Television screens, focus, and lifecycle work.
|
|
97
|
+
|
|
98
|
+
If the bundled skills are not installed yet, use:
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
tv skills show
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
That lists each bundled skill with its description and absolute path.
|
|
105
|
+
|
|
106
|
+
To inspect one bundled skill directly:
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
tv skills show television
|
|
110
|
+
tv skills show artifact-calendar
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
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.
|
|
114
|
+
|
|
115
|
+
## Command surface
|
|
116
|
+
|
|
117
|
+
The CLI is the source of truth for command syntax and per-command behavior. Run:
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
tv help
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
for the full command list. For details, flags, and behavioral nuance for a single command, run:
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
tv help <command>
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
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).
|
|
130
|
+
|
|
131
|
+
Commands group into four intents:
|
|
132
|
+
|
|
133
|
+
- **Screen commands** — create, inspect, remove, or switch screens (`create-screen`, `list-screens`, `get-screen`, `remove-screen`, `focus-screen`, `focus-status`).
|
|
134
|
+
- **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`).
|
|
135
|
+
- **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`).
|
|
136
|
+
- **Server and environment commands** — operate on the Television server itself (`serve`, `status`, `stop`, `storage-path`).
|
|
137
|
+
|
|
138
|
+
When the CLI rejects a command, follow the directive it prints rather than guessing flags.
|
|
139
|
+
|
|
140
|
+
## Read vs mutate
|
|
141
|
+
|
|
142
|
+
Read commands print JSON. Mutation and workflow commands print plain text.
|
|
143
|
+
|
|
144
|
+
Use read commands when you need authoritative state for planning or verification. Use mutation commands when you are intentionally changing Television state.
|
|
145
|
+
|
|
146
|
+
## Focus model
|
|
147
|
+
|
|
148
|
+
Television separates state changes from focus. Choosing where an artifact lives is one decision; choosing whether the user's attention moves there is a separate one.
|
|
149
|
+
|
|
150
|
+
- **screen focus** is persistent: which screen the user is currently looking at
|
|
151
|
+
- **artifact focus** is transient: clients may switch screens first, then scroll and highlight the artifact
|
|
152
|
+
|
|
153
|
+
There is a persisted focused screen.
|
|
154
|
+
There is not a persisted focused artifact.
|
|
155
|
+
|
|
156
|
+
Important consequence: creating or attaching something does not by itself answer whether the user should be taken to it now.
|
|
157
|
+
|
|
158
|
+
## Required explicit focus decisions
|
|
159
|
+
|
|
160
|
+
Create and attach commands require an explicit focus decision.
|
|
161
|
+
|
|
162
|
+
- `tv create-screen` requires exactly one of `--focus-screen` or `--no-focus`
|
|
163
|
+
- `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`
|
|
164
|
+
|
|
165
|
+
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.
|
|
166
|
+
|
|
167
|
+
## Choosing the focus directive
|
|
168
|
+
|
|
169
|
+
Think about the user's current attention stream before deciding. Use theory of mind: what are they probably attending to right now? Do they expect an immediate reveal, or would moving their view feel jarring? What will they likely want to do next?
|
|
170
|
+
|
|
171
|
+
Rules of thumb:
|
|
172
|
+
|
|
173
|
+
- **focus now** when seeing the result immediately is part of successfully answering the request
|
|
174
|
+
- **`--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
|
|
175
|
+
- **direct `focus-screen` / `focus-artifact` commands** when placement and attention movement should happen as separate steps
|
|
176
|
+
|
|
177
|
+
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.
|
|
178
|
+
|
|
179
|
+
## Listening for focus intent in the user's language
|
|
180
|
+
|
|
181
|
+
The user's phrasing is a strong cue — not a deterministic rule, but a real signal worth listening for.
|
|
182
|
+
|
|
183
|
+
Phrases that usually indicate the user wants attention moved (use a focus flag, or a direct `focus-screen` / `focus-artifact` command):
|
|
184
|
+
|
|
185
|
+
- "show me", "show me that", "let me see it", "let me review it"
|
|
186
|
+
- "switch to", "change to", "go to", "take me there", "open it"
|
|
187
|
+
- "put it on screen", "put it on my screen", "bring it up"
|
|
188
|
+
- references to the **active**, **current**, **showing**, or **visible** screen or artifact
|
|
189
|
+
|
|
190
|
+
Phrases that usually indicate the user wants the work to happen without disturbing their current view (use `--no-focus`):
|
|
191
|
+
|
|
192
|
+
- "in the background", "while I'm doing X", "while I work on Y go and do Z"
|
|
193
|
+
- "set this up", "prepare it", "wire it in", "get it ready"
|
|
194
|
+
- "don't interrupt me", "leave my screen alone", "don't switch"
|
|
195
|
+
|
|
196
|
+
These are illustrative, not exhaustive. When the language is ambiguous or unusual, reason about the user's attention stream instead of pattern-matching keywords.
|
|
197
|
+
|
|
198
|
+
## Screen placement
|
|
199
|
+
|
|
200
|
+
Artifact creation commands require `--screen` because new artifacts need immediate screen membership. Use `attach-artifact` and `detach-artifact` when the artifact already exists and you are changing where it appears.
|
|
201
|
+
|
|
202
|
+
Think carefully about whether the user means:
|
|
203
|
+
|
|
204
|
+
- create something new on a screen
|
|
205
|
+
- place an existing artifact on a screen
|
|
206
|
+
- stop showing an artifact on a screen
|
|
207
|
+
- globally delete an artifact everywhere
|
|
208
|
+
|
|
209
|
+
Those are different operations with different consequences. The per-command help text spells out which is which.
|
|
210
|
+
|
|
211
|
+
### Choosing the right screen
|
|
212
|
+
|
|
213
|
+
When deciding where an artifact should go:
|
|
214
|
+
|
|
215
|
+
- If the current screen is the right place and the user should see the result immediately, create or attach the artifact there with `--focus-artifact`.
|
|
216
|
+
- If the current screen is the right place but the work should appear without interrupting their reading flow, create or attach with `--no-focus`.
|
|
217
|
+
- If the work belongs on a different existing screen, place it there. Then decide whether to focus or merely tell the user where it is.
|
|
218
|
+
- Sometimes a new screen is the right call.
|
|
219
|
+
|
|
220
|
+
### When to create a new screen
|
|
221
|
+
|
|
222
|
+
Reach for `tv create-screen` when:
|
|
223
|
+
|
|
224
|
+
- the request is meaningfully separate from the current screen's purpose
|
|
225
|
+
- the result should become its own durable workspace the user can return to
|
|
226
|
+
- 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)
|
|
227
|
+
|
|
228
|
+
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.
|
|
229
|
+
|
|
230
|
+
|
|
231
|
+
# Artifact workflow
|
|
232
|
+
|
|
233
|
+
Read this document for Television artifact lifecycle work — creating, updating, committing, abandoning, attaching, detaching, deleting.
|
|
234
|
+
|
|
235
|
+
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.
|
|
236
|
+
|
|
237
|
+
If you are authoring an HTML artifact, use the matching `artifact-*` skill and read its `house-style.md` guidance when directed.
|
|
238
|
+
|
|
239
|
+
## Markdown or HTML
|
|
240
|
+
|
|
241
|
+
Once you have decided to make an artifact, choose the type:
|
|
242
|
+
|
|
243
|
+
- **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.
|
|
244
|
+
- **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.
|
|
245
|
+
|
|
246
|
+
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.
|
|
247
|
+
|
|
248
|
+
## Authoring quality
|
|
249
|
+
|
|
250
|
+
This applies to every artifact you author or maintain — internal, external, or URL.
|
|
251
|
+
|
|
252
|
+
Build artifacts that are durable, truthful, and maintainable by later agents.
|
|
253
|
+
|
|
254
|
+
Required standards:
|
|
255
|
+
|
|
256
|
+
- be faithful to source material
|
|
257
|
+
- do not invent missing facts to make the artifact look complete
|
|
258
|
+
- do not silently truncate a dataset and pretend it is comprehensive
|
|
259
|
+
- prefer truth over completeness when those goals conflict
|
|
260
|
+
- make limitations, sampling, gaps, and freshness visible when they matter
|
|
261
|
+
- keep the rendering aligned with the reasoning captured in the bundle files (for internal artifacts)
|
|
262
|
+
- keep the artifact maintainable by a future agent reading only the bundle (for internal artifacts)
|
|
263
|
+
|
|
264
|
+
Anti-patterns to avoid:
|
|
265
|
+
|
|
266
|
+
- cursory or low-effort data collection
|
|
267
|
+
- fake completeness — padding to look thorough
|
|
268
|
+
- brittle one-off hacks that a later agent cannot reproduce
|
|
269
|
+
- hidden dependencies that are not documented in the bundle
|
|
270
|
+
- unnecessary layout or styling churn during a simple data refresh
|
|
271
|
+
|
|
272
|
+
## Before creating artifacts
|
|
273
|
+
|
|
274
|
+
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.
|
|
275
|
+
|
|
276
|
+
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.
|
|
277
|
+
|
|
278
|
+
## In-flight narration style
|
|
279
|
+
|
|
280
|
+
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.
|
|
281
|
+
|
|
282
|
+
Required style:
|
|
283
|
+
|
|
284
|
+
- verbalize key actions and decisions as they happen
|
|
285
|
+
- keep updates short — a sentence per beat, not a paragraph
|
|
286
|
+
- prefer the user's framing over Television's internal machinery
|
|
287
|
+
- do not write reports, retrospective summaries, or chatty explanations while work is in progress
|
|
288
|
+
- do not use bullet lists unless the user explicitly asks for one
|
|
289
|
+
- optimize for speed and token efficiency
|
|
290
|
+
|
|
291
|
+
Good examples:
|
|
292
|
+
|
|
293
|
+
- "Starting the artifact now."
|
|
294
|
+
- "Reviewing the draft and source material."
|
|
295
|
+
- "Updating the HTML and moving through the artifact creation flow."
|
|
296
|
+
- "The artifact did not pass validation; fixing the draft notes and retrying."
|
|
297
|
+
- "Finalizing the artifact now."
|
|
298
|
+
- "Done."
|
|
299
|
+
|
|
300
|
+
Avoid:
|
|
301
|
+
|
|
302
|
+
- multi-paragraph progress reports
|
|
303
|
+
- long retrospective narration during execution
|
|
304
|
+
- verbose bullet lists for routine workflow steps
|
|
305
|
+
- workflow jargon ("calling commit-pending-artifact", "validator rejected memory.md") unless the user is debugging Television itself
|
|
306
|
+
|
|
307
|
+
## Internal bundle structure
|
|
308
|
+
|
|
309
|
+
Internal artifacts are Television-managed bundles. Every internal artifact bundle contains:
|
|
310
|
+
|
|
311
|
+
- `artifact.md`
|
|
312
|
+
- `data.json`
|
|
313
|
+
- `memory.md`
|
|
314
|
+
- `public/index.md` or `public/index.html`
|
|
315
|
+
|
|
316
|
+
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.
|
|
317
|
+
|
|
318
|
+
External artifacts and URL artifacts have no bundle and no pending lifecycle.
|
|
319
|
+
|
|
320
|
+
### `artifact.md`
|
|
321
|
+
|
|
322
|
+
`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.
|
|
323
|
+
|
|
324
|
+
Before commit, `artifact.md` must be non-empty and contain all of these exact headings:
|
|
325
|
+
|
|
326
|
+
```md
|
|
327
|
+
## User intent
|
|
328
|
+
## Purpose
|
|
329
|
+
## Data shape
|
|
330
|
+
## Data sources
|
|
331
|
+
## Rendering
|
|
332
|
+
## Update workflow
|
|
333
|
+
## Non-goals
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
Section guidance:
|
|
337
|
+
|
|
338
|
+
- `## User intent` — faithfully preserve what the user actually wants, including requests, constraints, corrections, complaints, and feedback when those matter. Use direct quotes when helpful.
|
|
339
|
+
- `## Purpose` — what the artifact is trying to achieve.
|
|
340
|
+
- `## Data shape` — the conceptual structure you used while authoring. For markdown artifacts this is often just `{}`.
|
|
341
|
+
- `## Data sources` — where the underlying facts came from and how they were obtained.
|
|
342
|
+
- `## Rendering` — how the public entry file should present the result.
|
|
343
|
+
- `## Update workflow` — how a future agent should refresh or modify it correctly.
|
|
344
|
+
- `## Non-goals` — important exclusions, especially when it would be easy to overbuild (e.g., "this is a static report, not a live dashboard").
|
|
345
|
+
|
|
346
|
+
### `data.json`
|
|
347
|
+
|
|
348
|
+
`data.json` is a thinking artifact, not a runtime payload.
|
|
349
|
+
|
|
350
|
+
Use it to clarify authoring structure when that helps you think, not to create an application state layer.
|
|
351
|
+
|
|
352
|
+
Hard rules:
|
|
353
|
+
|
|
354
|
+
- do not treat `data.json` as live runtime state
|
|
355
|
+
- do not build HTML/JS that depends on `data.json` as an application data source
|
|
356
|
+
- do not turn Television artifacts into runtime data-backed apps through `data.json`
|
|
357
|
+
- 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
|
|
358
|
+
|
|
359
|
+
For markdown artifacts, prefer to leave `data.json` as exactly:
|
|
360
|
+
|
|
361
|
+
```json
|
|
362
|
+
{}
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
For HTML artifacts, use `data.json` only when it materially helps your authoring process.
|
|
366
|
+
|
|
367
|
+
Validation requires that `data.json` exist and contain valid JSON.
|
|
368
|
+
|
|
369
|
+
### `memory.md`
|
|
370
|
+
|
|
371
|
+
`memory.md` is for maintenance-oriented notes to future agents.
|
|
372
|
+
|
|
373
|
+
Record decisions, limitations, source-retrieval notes, problems encountered, what changed, and anything that should be watched during future edits.
|
|
374
|
+
|
|
375
|
+
Required validation anchors:
|
|
376
|
+
|
|
377
|
+
- `memory.md` must contain `## Activity Log`
|
|
378
|
+
- it must contain at least one UTC timestamp in exact `YYYY-MM-DDTHH:MM:SSZ` format
|
|
379
|
+
- at least one timestamp must be fresh enough for commit validation (recent enough to prove this commit is current)
|
|
380
|
+
|
|
381
|
+
### Public entry file
|
|
382
|
+
|
|
383
|
+
This is what Television actually renders.
|
|
384
|
+
|
|
385
|
+
- markdown artifacts use `public/index.md`
|
|
386
|
+
- HTML artifacts use `public/index.html`
|
|
387
|
+
- the entry file must match the artifact type
|
|
388
|
+
- the entry file must be non-empty before commit
|
|
389
|
+
- HTML artifacts may include additional public assets under `public/`; keep paths relative
|
|
390
|
+
|
|
391
|
+
For HTML artifacts, also use the matching `artifact-*` skill and read its
|
|
392
|
+
`house-style.md` guidance.
|
|
393
|
+
|
|
394
|
+
## Workflows
|
|
395
|
+
|
|
396
|
+
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.
|
|
397
|
+
|
|
398
|
+
### Create a new internal artifact
|
|
399
|
+
|
|
400
|
+
1. Confirm internal is the right kind for this result (the result should be Television-owned and maintainable by future agents).
|
|
401
|
+
2. Tell the user what you are about to make before starting tool work.
|
|
402
|
+
3. Stage the pending bundle:
|
|
403
|
+
|
|
404
|
+
```bash
|
|
405
|
+
tv create-internal-artifact --screen "<screen-id>" --type text/markdown --title "Artifact title" --focus-artifact
|
|
406
|
+
```
|
|
407
|
+
|
|
408
|
+
Or, for HTML:
|
|
409
|
+
|
|
410
|
+
```bash
|
|
411
|
+
tv create-internal-artifact --screen "<screen-id>" --type text/html --title "Artifact title" --no-focus
|
|
412
|
+
```
|
|
413
|
+
|
|
414
|
+
`--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.)
|
|
415
|
+
|
|
416
|
+
4. Read the returned pending path. Edit files there.
|
|
417
|
+
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.
|
|
418
|
+
6. Fill out the remaining required `artifact.md` headings: `## Purpose`, `## Data shape`, `## Data sources`, `## Rendering`, `## Update workflow`, `## Non-goals`.
|
|
419
|
+
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.
|
|
420
|
+
8. Render `public/index.md` or `public/index.html`. The entry file must match the artifact type and must be non-empty.
|
|
421
|
+
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.
|
|
422
|
+
10. Commit:
|
|
423
|
+
|
|
424
|
+
```bash
|
|
425
|
+
tv commit-pending-artifact --id "<artifact-id>"
|
|
426
|
+
```
|
|
427
|
+
|
|
428
|
+
If the validator rejects the commit, read the directive, fix the bundle, and retry. Do not bypass validation by editing committed state directly.
|
|
429
|
+
|
|
430
|
+
### Update an internal artifact with fresh data
|
|
431
|
+
|
|
432
|
+
1. Stage the edit:
|
|
433
|
+
|
|
434
|
+
```bash
|
|
435
|
+
tv edit-internal-artifact --id "<artifact-id>"
|
|
436
|
+
```
|
|
437
|
+
|
|
438
|
+
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.
|
|
439
|
+
3. Refresh the underlying facts or source material.
|
|
440
|
+
4. Update `data.json` only if it improves the authoring model. For markdown artifacts, prefer to keep it as `{}`.
|
|
441
|
+
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."
|
|
442
|
+
6. Append a current UTC-timestamped entry to `## Activity Log` in `memory.md` describing what changed.
|
|
443
|
+
7. Commit:
|
|
444
|
+
|
|
445
|
+
```bash
|
|
446
|
+
tv commit-pending-artifact --id "<artifact-id>"
|
|
447
|
+
```
|
|
448
|
+
|
|
449
|
+
### Modify an internal artifact from user feedback
|
|
450
|
+
|
|
451
|
+
1. Stage the edit (`tv edit-internal-artifact --id "<artifact-id>"`).
|
|
452
|
+
2. Read `artifact.md`, `data.json`, and `memory.md`.
|
|
453
|
+
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.
|
|
454
|
+
4. Update `## Non-goals` if the user has ruled something out.
|
|
455
|
+
5. Adjust `data.json` only if the authoring model changed.
|
|
456
|
+
6. Adjust `public/index.md` or `public/index.html` as narrowly as the change requires.
|
|
457
|
+
7. Append an `## Activity Log` entry capturing the request, the decision, and the resulting change with a current timestamp.
|
|
458
|
+
8. Commit.
|
|
459
|
+
|
|
460
|
+
### Abandon pending work
|
|
461
|
+
|
|
462
|
+
If staged work should be discarded rather than committed:
|
|
463
|
+
|
|
464
|
+
```bash
|
|
465
|
+
tv abandon-pending-artifact --id "<artifact-id>"
|
|
466
|
+
```
|
|
467
|
+
|
|
468
|
+
For a pending create, the artifact never becomes live. For a pending edit, the previously committed version is kept unchanged.
|
|
469
|
+
|
|
470
|
+
### Create an external artifact
|
|
471
|
+
|
|
472
|
+
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.
|
|
473
|
+
|
|
474
|
+
```bash
|
|
475
|
+
tv create-external-artifact --screen "<screen-id>" --type text/markdown --title "Artifact title" --path /absolute/path/to/file.md --focus-artifact
|
|
476
|
+
```
|
|
477
|
+
|
|
478
|
+
Or:
|
|
479
|
+
|
|
480
|
+
```bash
|
|
481
|
+
tv create-external-artifact --screen "<screen-id>" --type text/html --title "Artifact title" --path /absolute/path/to/file.html --no-focus
|
|
482
|
+
```
|
|
483
|
+
|
|
484
|
+
Rules:
|
|
485
|
+
|
|
486
|
+
- `--path` must be absolute
|
|
487
|
+
- the file must already exist and be readable
|
|
488
|
+
- the extension must match `--type`
|
|
489
|
+
- there is no pending create / pending edit / commit / abandon flow
|
|
490
|
+
- `tv delete-artifact` only forgets the pointer; the underlying file is never deleted
|
|
491
|
+
|
|
492
|
+
### Create a URL artifact
|
|
493
|
+
|
|
494
|
+
URL artifacts embed a live `http(s)://` page. They commit immediately and have no pending lifecycle.
|
|
495
|
+
|
|
496
|
+
```bash
|
|
497
|
+
tv create-url-artifact --screen "<screen-id>" --title "Artifact title" --url https://example.com --focus-artifact
|
|
498
|
+
```
|
|
499
|
+
|
|
500
|
+
Or:
|
|
501
|
+
|
|
502
|
+
```bash
|
|
503
|
+
tv create-url-artifact --screen "<screen-id>" --title "Artifact title" --url https://example.com --no-focus
|
|
504
|
+
```
|
|
505
|
+
|
|
506
|
+
Rules:
|
|
507
|
+
|
|
508
|
+
- `--url` must be `http://` or `https://`
|
|
509
|
+
- the type is always `text/html` — do not pass `--type`
|
|
510
|
+
- in the desktop app the page renders in a sandboxed `<webview>`; in the browser it renders in an `<iframe>`
|
|
511
|
+
- 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
|