@telepath-computer/television 1.4.7 → 1.4.9

package/dist/skills/television/SKILL.md

@@ -49,7 +49,7 @@ That relationship matters:
 
 ### Onboarding channels
 
-Fresh installations receive a small set of bundled onboarding channels, each installed exactly once per storage directory. After installation they are ordinary channels: rename, edit, or delete them like any other, and Television never re-creates or overwrites what changed. You can tell one apart from a user-created channel by the `onboarding` marker containing its stable channel slug — visible in `tv list-channels` / `tv get-channel` output; user-created channels have no such field. Marked channels appear as ordinary unpinned channels and receive no special browser promotion. The marker changes nothing about how you manage the channel.
+Fresh installations receive a small set of bundled onboarding channels, each installed exactly once per Television home. After installation they are ordinary channels: rename, edit, or delete them like any other, and Television never re-creates or overwrites what changed. You can tell one apart from a user-created channel by the `onboarding` marker containing its stable channel slug — visible in `tv list-channels` / `tv get-channel` output; user-created channels have no such field. Marked channels appear as ordinary unpinned channels and receive no special browser promotion. The marker changes nothing about how you manage the channel.
 
 ### Artifact shapes
 
@@ -90,7 +90,7 @@ Read the entire document before acting. If your web fetch tool returned a summar
 
 Television collects anonymous, content-free telemetry by default to understand early usage and improve the product. Telemetry records predefined usage events and content-free classifications; it does not record artifact paths or URLs, artifact titles, channel names, theme names, file contents, or user-authored text.
 
-If the user wants to opt out, you turn telemetry off for them by running `tv telemetry disable` against the running server (`tv telemetry enable` turns it back on); `tv status` reports the current telemetry state. The command needs a live server. Television also honors the standard `DO_NOT_TRACK` environment variable when it is set, but `tv telemetry disable` is the intended way to opt out. Install- and upgrade-time telemetry duties — the disclosure to give the user and the `--installed-by-agent` flag — are covered in the admin guide (see the Administration section above).
+If the user wants to opt out, you turn telemetry off for them by running `tv telemetry disable` against the running server (`tv telemetry enable` turns it back on); `tv status` reports the current telemetry state. The command needs a live server. Television also honors the standard `DO_NOT_TRACK` environment variable when it is set, but `tv telemetry disable` is the intended way to opt out. Install- and upgrade-time telemetry duties — the disclosure to give the user and the server's `installedByAgent` setting — are covered in the admin guide (see the Administration section above).
 
 ## Related skills
 
@@ -138,15 +138,17 @@ Commands group into four intents:
 - **Channel and display commands** — create, inspect, rename, remove, or switch channels, or change the active display theme (`create-channel`, `list-channels`, `get-channel`, `update-channel`, `remove-channel`, `focus-channel`, `focus-status`, `set-theme`).
 - **Artifact creation commands** — register path or URL artifacts (`create-path-artifact`, `create-url-artifact`).
 - **Artifact management commands** — inspect, retitle, repoint, focus, list, or delete existing artifacts (`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`, `telemetry`, `skills install`).
+- **Server and environment commands** — operate on the Television server and its home (`serve`, `status`, `stop`, `config`, `themes-path`, `telemetry`, `skills install`).
 
 When the CLI rejects a command, follow the directive it prints rather than guessing flags.
 
 ### Server operation notes
 
-`tv status` reports server health and, when supported, system service status. Workflow commands connect to `localhost:<port>` only; use `--port`, `TELEVISION_PORT`, or the default `32848` rather than `--server`. When targeting non-default storage, pass `--storage-path` or set `TELEVISION_STORAGE_PATH` so the CLI reads the matching token from `<storagePath>/state/token`.
+Each `tv` command works with one Television home, the directory that holds an installation's config file, token, channels, artifacts, themes, and logs. A command uses the home given with `--home <path>`, otherwise the path written in `~/.tv-home`, otherwise `~/.television`. `--home` applies only to the command that receives it, so when you work with a home other than the default, pass the same `--home` to every command. The server and commands share the settings in the home's optional `config.json`; `tv config show` prints the selected home and its effective settings.
 
-Starting, installing, upgrading, or reconfiguring the server — `tv serve` flags, listeners, auth and tokens, ports, the persistent daemon (`--persist`), stopping and uninstalling (`tv stop`) — is administrator work covered by the deployed admin guide, not this skill. Before doing any of it, fetch the full raw guide as described in the Administration section of this skill; do not work from the command names alone or from a summary.
+`tv status` reports the selected home, server health, and, when supported, system service status. Commands that contact the server connect to `localhost` on the config file's port, with the token from `<home>/state/token`; there is no `--server` option. They take `--port <number>` only when the config file sets port `0`, and then require it, using the port from the server's startup URL. `tv themes-path` prints the home's themes directory.
+
+Starting, installing, upgrading, or reconfiguring the server — `tv serve`, `tv config set`, listeners, auth and tokens, ports, the persistent service (`--persist`), stopping and uninstalling (`tv stop`) — is administrator work covered by the deployed admin guide, not this skill. Before doing any of it, fetch the full raw guide as described in the Administration section of this skill; do not work from the command names alone or from a summary.
 
 ## Read vs mutate
 
@@ -276,13 +278,13 @@ If you are unsure between HTML and markdown, default to HTML.
 
 Television registers pointers — the file lifecycle is yours, not Television's. Deleting an artifact removes the registry record, not the underlying file or folder, regardless of where it lives.
 
-**Default for HTML (single file or directory): `~/.television/artifacts/`.** HTML artifacts are pure presentation — Television is where they live and get used, so the default folder is the right home. Put them there unless the user has told you otherwise. Create the directory if it does not exist.
+**Default for HTML (single file or directory): `<home>/artifacts/`**, the `artifacts` folder in the Television home your `tv` commands use. `tv config show` prints that home as `home`. HTML artifacts are pure presentation — Television is where they live and get used, so the default folder is the right place. Put them there unless the user has told you otherwise. Create the directory if it does not exist.
 
-**Markdown is different.** A markdown artifact is usually a user-owned document — a note, draft, write-up — that has a life outside Television. Putting one in `~/.television/artifacts/` is suspect: the user will likely want it alongside their other documents. For markdown, co-locate with the project, repo, notes folder, or workspace where a new document of that kind would naturally belong if the user had asked for one outside Television. If no such home is obvious from context, ask the user where it should go rather than dropping it in the default folder.
+**Markdown is different.** A markdown artifact is usually a user-owned document — a note, draft, write-up — that has a life outside Television. Putting one in `<home>/artifacts/` is suspect: the user will likely want it alongside their other documents. For markdown, co-locate with the project, repo, notes folder, or workspace where a new document of that kind would naturally belong if the user had asked for one outside Television. If no such place is obvious from context, ask the user where it should go rather than dropping it in the default folder.
 
 For HTML, put the file somewhere else only when the user has explicitly directed you to — either in this request, or via a durable instruction (project `AGENTS.md`/`CLAUDE.md`, a standing preference, an earlier "from now on…" in this session). Examples of explicit direction: "save it in the repo", "put it in my notes folder", "drop it in the agent workspace".
 
-Do not co-locate HTML artifacts with project files, repo trees, notes folders, or agent workspaces on your own initiative — even when it seems natural. The default for HTML is `~/.television/artifacts/`.
+Do not co-locate HTML artifacts with project files, repo trees, notes folders, or agent workspaces on your own initiative — even when it seems natural. The default for HTML is `<home>/artifacts/`.
 
 ### File and folder naming
 

package/dist/skills/television/theming.md

@@ -4,10 +4,10 @@ Read this document when creating, revising, or bringing an installed Television
 
 ## Theme package and authoring record
 
-Run `tv storage-path` to find the active storage directory. Author one folder directly beneath its `themes` directory:
+Run `tv themes-path` to find the themes directory; it prints `{"themesPath":"<path>"}`. Author one folder directly inside that directory:
 
 ```text
-<storagePath>/themes/<theme-id>/
+<themesPath>/<theme-id>/
   manifest.json      required runtime metadata
   theme.css          required entry stylesheet
   main.js                    optional main-document entry
@@ -1124,7 +1124,7 @@ The first two forms report the opening selection when it was available. The thir
 ## Authoring workflow
 
 1. Gather the user's visual intent, references, palette and typography direction, and the application or artifact surfaces that matter.
-2. Run `tv storage-path` to locate the themes directory and `tv status` to establish the target app version.
+2. Run `tv themes-path` to locate the themes directory and `tv status` to establish the target app version. When the installation is not in the default home, give these and every later `tv` command the same `--home`. A user who keeps the default home elsewhere writes its path into `~/.tv-home`, and then commands need no `--home`.
 3. Choose an exact theme ID, inspect the target path, and apply the existing-folder safeguards above before writing.
 4. Choose the least invasive visual surface, then write the manifest with its required `colorScheme`, entry stylesheet, README, any justified JavaScript entries, and relative assets as one package. Add purpose comments to narrow selector rules.
 5. Activate the package with `tv set-theme <theme-id>`. Correct any manifest error the command reports.
@@ -1137,4 +1137,4 @@ Visual verification can include screenshots when the environment can render both
 
 ## Clouds as a worked example
 
-The installed Clouds package at `<storagePath>/themes/clouds/` is a locally available structural example of package shape, relative assets, application-only scoping, and purpose-specific shell rules. Its version may meet or exceed Television's minimum, and its files may contain user edits, so read it as a local example rather than a pristine template. Use the vocabulary and reference in this document as the authority when adapting the example.
+The installed Clouds package at `<themesPath>/clouds/` is a locally available structural example of package shape, relative assets, application-only scoping, and purpose-specific shell rules. Its version may meet or exceed Television's minimum, and its files may contain user edits, so read it as a local example rather than a pristine template. Use the vocabulary and reference in this document as the authority when adapting the example.