herm-tui 1.9.0-dev.8 → 1.9.0

package/README.md

@@ -93,16 +93,61 @@ See [`.env.example`](./.env.example) for rarely-needed overrides.
 
 ### Share and install eikons
 
-- Press `M` from Gallery to enter the native Eikon Marketplace.
-- Search shared catalog entries, preview the selected eikon, install without
-  activating, then use it when ready.
-- Use `eikon.liftaris.dev` as a discovery mirror only; it previews catalog
-  entries and points back to Herm for native install/use.
-- Submit local non-bundled eikons with `u`; Herm shows the exact
-  preflight bundle before submission and blocks published marketplace installs
-  from duplicate submission.
-
-Herm owns native Marketplace behavior. The eikon repo owns the registry,
+Eikons are 48×24 terminal avatars. The shipped lifecycle is deterministic:
+discover, inspect, install, use, update, and remove.
+
+In Herm:
+
+- Open Eikon → Catalog, or run `/catalog`, to browse shared catalog
+  entries.
+- Preview rows before installing. Trust is shown as `Verified`, `Unverified`,
+  or `Mismatch` beside source and compatibility state.
+- Install adds the eikon to your local library without activating it.
+- Use selects an installed eikon as the active avatar.
+- Installing over the currently active eikon name also requires confirmation or
+  `--active-ok` because it replaces the active avatar's backing package.
+- Update or remove an active eikon only after confirming that the active
+  avatar's backing package will change or be cleared.
+
+From the shell:
+
+```bash
+herm eikon search [query] [--json]
+herm eikon browse [query] [--json]
+herm eikon inspect <name|url|dir> [--json]
+herm eikon install <name|url|dir> [--name N] [--no-source] [--active-ok] [--json]
+herm eikon list [--json]
+herm eikon use <name> [--json]
+herm eikon info <name> [--json]
+herm eikon update <name> [--active-ok] [--json]
+herm eikon remove <name> [--active-ok] [--json]
+herm eikon delist <name|id> [--json]
+```
+
+`install` never activates. `use` is the activation action. JSON output is
+available for automation with `--json`.
+
+Default Catalog installs fetch built package artifacts referenced by the
+catalog, not creator repositories. Direct GitHub installs are for sharing
+outside the default catalog and support both single-package repos and
+multi-eikon catalog repos addressed as `github.com/user/repo/eikon-name`.
+Private GitHub repos use normal git authentication.
+
+Creators can share Eikons through normal GitHub repositories. For official
+registry listing, press `u` in Studio or use Library's Share to catalog action
+after baking. Herm previews metadata, the prepared public bundle, and the GitHub
+PR target; with local `gh` auth it creates the PR, otherwise it shows manual PR
+steps with the prepared bundle path and compare URL. Direct-install repos can
+still be prepared with upstream `eikon pack`, `eikon index`, and
+`eikon manifest`.
+`eikon publish` remains the lower-level GitHub PR contribution helper for the
+configured/default catalog repo; it is not a hosted marketplace account, upload,
+dashboard, or moderation flow.
+
+Use `eikon.liftaris.dev` as a discovery gallery only; it previews catalog
+entries and gives copyable Herm install instructions.
+
+Herm owns native Catalog behavior. The eikon repo owns the registry,
 browser mirror, shared catalog/player exports, install resolver, and publish
 preflight. Herm imports public eikon package exports rather than browser mirror
 internals or unexported source paths.

package/assets/eikons/nous/manifest.json

@@ -0,0 +1,123 @@
+{
+  "kind": "eikon.package",
+  "schemaVersion": "1.0",
+  "id": "liftaris/nous",
+  "name": "nous",
+  "version": "1.0.0",
+  "display": {
+    "title": "nous",
+    "author": "kaio",
+    "glyph": "⬡"
+  },
+  "compatibility": {
+    "eikon": ">=1 <2"
+  },
+  "legacy": {
+    "sourceFormat": "pre-launch .eikon draft",
+    "migration": "converted",
+    "notes": [
+      "moved legacy metadata: author, created, source_url"
+    ]
+  },
+  "source": {
+    "base": "blobs/sha256/8c4dc411ca159253cc90fa31f5263799054592e6eaeb4e5c99881c8cac29e67b",
+    "states": {
+      "idle": {
+        "file": "blobs/sha256/481c010826d7cacb9c419455bd0f73d020f66492a1236b37e4e53353b7965902"
+      },
+      "listening": {
+        "file": "blobs/sha256/94f0f4f710c708f516128125142d5dce701f83558e9fad444c1bb376ee3c1fea"
+      },
+      "thinking": {
+        "file": "blobs/sha256/5ae0eb2e1889c72bed69144998acc6f80b9d11b67beffccd972842a9d6ed0f24"
+      },
+      "speaking": {
+        "file": "blobs/sha256/5c15fd3db3fba93b378eb5b23ab9ecf283e8fb5a08828f1393e91b323b65eab2"
+      },
+      "working": {
+        "file": "blobs/sha256/f63a864e84c4b4f672d6b02a4bcf610b2881fcf64166273b29a642fb76e00f09"
+      },
+      "error": {
+        "file": "blobs/sha256/5d1a1fa59ec9091d9c03d99728b15287ef58d397ea2c787a65c55519482683c8"
+      }
+    }
+  },
+  "entrypoints": {
+    "default": "nous.eikon"
+  },
+  "files": [
+    {
+      "path": "nous.eikon",
+      "role": "runtime",
+      "mediaType": "application/vnd.eikon.stream+jsonl",
+      "size": 139822,
+      "digest": "sha256:6a74e9ae20ecafe6cf268230272582ef618b31927cd13e11ce59ed8931413883",
+      "encoding": "gzip",
+      "decodedSize": 1401439,
+      "decodedDigest": "sha256:b2685743b05ddf201920b69db58640d4fab644e637fa7d313c6dfa215fa41fb7"
+    },
+    {
+      "path": "blobs/sha256/8c4dc411ca159253cc90fa31f5263799054592e6eaeb4e5c99881c8cac29e67b",
+      "role": "source.base",
+      "mediaType": "image/png",
+      "size": 98644,
+      "digest": "sha256:8c4dc411ca159253cc90fa31f5263799054592e6eaeb4e5c99881c8cac29e67b"
+    },
+    {
+      "path": "blobs/sha256/481c010826d7cacb9c419455bd0f73d020f66492a1236b37e4e53353b7965902",
+      "role": "source.clip",
+      "mediaType": "video/mp4",
+      "size": 105789,
+      "digest": "sha256:481c010826d7cacb9c419455bd0f73d020f66492a1236b37e4e53353b7965902",
+      "signal": "state.idle"
+    },
+    {
+      "path": "blobs/sha256/94f0f4f710c708f516128125142d5dce701f83558e9fad444c1bb376ee3c1fea",
+      "role": "source.clip",
+      "mediaType": "video/mp4",
+      "size": 275110,
+      "digest": "sha256:94f0f4f710c708f516128125142d5dce701f83558e9fad444c1bb376ee3c1fea",
+      "signal": "state.listening"
+    },
+    {
+      "path": "blobs/sha256/5ae0eb2e1889c72bed69144998acc6f80b9d11b67beffccd972842a9d6ed0f24",
+      "role": "source.clip",
+      "mediaType": "video/mp4",
+      "size": 174520,
+      "digest": "sha256:5ae0eb2e1889c72bed69144998acc6f80b9d11b67beffccd972842a9d6ed0f24",
+      "signal": "state.thinking"
+    },
+    {
+      "path": "blobs/sha256/5c15fd3db3fba93b378eb5b23ab9ecf283e8fb5a08828f1393e91b323b65eab2",
+      "role": "source.clip",
+      "mediaType": "video/mp4",
+      "size": 96790,
+      "digest": "sha256:5c15fd3db3fba93b378eb5b23ab9ecf283e8fb5a08828f1393e91b323b65eab2",
+      "signal": "state.speaking"
+    },
+    {
+      "path": "blobs/sha256/f63a864e84c4b4f672d6b02a4bcf610b2881fcf64166273b29a642fb76e00f09",
+      "role": "source.clip",
+      "mediaType": "video/mp4",
+      "size": 160072,
+      "digest": "sha256:f63a864e84c4b4f672d6b02a4bcf610b2881fcf64166273b29a642fb76e00f09",
+      "signal": "state.working"
+    },
+    {
+      "path": "blobs/sha256/5d1a1fa59ec9091d9c03d99728b15287ef58d397ea2c787a65c55519482683c8",
+      "role": "source.clip",
+      "mediaType": "video/mp4",
+      "size": 168804,
+      "digest": "sha256:5d1a1fa59ec9091d9c03d99728b15287ef58d397ea2c787a65c55519482683c8",
+      "signal": "state.error"
+    }
+  ],
+  "origin": {
+    "kind": "default-catalog",
+    "source": "https://eikon.liftaris.dev/packages/liftaris/nous/1.0.0.json",
+    "sourceKey": "registry:eikon.liftaris.dev:liftaris/nous@1.0.0",
+    "identityKey": "registry:eikon.liftaris.dev:liftaris/nous@1.0.0",
+    "packageUrl": "https://eikon.liftaris.dev/packages/liftaris/nous/1.0.0.json",
+    "trust": "verified"
+  }
+}

package/assets/plugins/eikon/__init__.py

@@ -1,17 +1,40 @@
-"""Eikon install plugin."""
+"""Eikon lifecycle plugin."""
 
 from __future__ import annotations
 
-from .schemas import EIKON_INSTALL_SCHEMA
-from .tools import _handle_eikon_install, check_herm_available
+from .schemas import (
+    EIKON_INSTALL_SCHEMA,
+    EIKON_LIST_SCHEMA,
+    EIKON_REMOVE_SCHEMA,
+    EIKON_SEARCH_SCHEMA,
+    EIKON_UPDATE_SCHEMA,
+    EIKON_USE_SCHEMA,
+)
+from .tools import (
+    _handle_eikon_install,
+    _handle_eikon_list,
+    _handle_eikon_remove,
+    _handle_eikon_search,
+    _handle_eikon_update,
+    _handle_eikon_use,
+    check_herm_available,
+)
 
 
 def register(ctx) -> None:
-    ctx.register_tool(
-        name="eikon_install",
-        toolset="eikon",
-        schema=EIKON_INSTALL_SCHEMA,
-        handler=_handle_eikon_install,
-        check_fn=check_herm_available,
-        emoji="⬡",
-    )
+    for name, schema, handler in [
+        ("eikon_install", EIKON_INSTALL_SCHEMA, _handle_eikon_install),
+        ("eikon_search", EIKON_SEARCH_SCHEMA, _handle_eikon_search),
+        ("eikon_list", EIKON_LIST_SCHEMA, _handle_eikon_list),
+        ("eikon_use", EIKON_USE_SCHEMA, _handle_eikon_use),
+        ("eikon_update", EIKON_UPDATE_SCHEMA, _handle_eikon_update),
+        ("eikon_remove", EIKON_REMOVE_SCHEMA, _handle_eikon_remove),
+    ]:
+        ctx.register_tool(
+            name=name,
+            toolset="eikon",
+            schema=schema,
+            handler=handler,
+            check_fn=check_herm_available,
+            emoji="⬡",
+        )

package/assets/plugins/eikon/plugin.yaml

@@ -1,7 +1,12 @@
 name: eikon
 version: 1.0.0
-description: "Herm eikon installer tool. Lets Hermes chat install terminal avatars through the existing `herm eikon install` CLI path."
+description: "Herm eikon lifecycle tools. Lets Hermes chat search, install, activate, update, and remove terminal avatars through the existing `herm eikon` CLI path."
 author: Liftaris
 kind: standalone
 provides_tools:
   - eikon_install
+  - eikon_search
+  - eikon_list
+  - eikon_use
+  - eikon_update
+  - eikon_remove

package/assets/plugins/eikon/schemas.py

@@ -7,7 +7,7 @@ EIKON_INSTALL_SCHEMA = {
     "description": (
         "Install a Herm eikon/avatar from the public catalog, a manifest URL, "
         "a git repository, or a local directory. Uses `herm eikon install`; "
-        "no separate eikon executable is required."
+        "set_active activates the installed avatar with `herm eikon use`."
     ),
     "parameters": {
         "type": "object",
@@ -32,10 +32,78 @@ EIKON_INSTALL_SCHEMA = {
             },
             "set_active": {
                 "type": "boolean",
-                "description": "Set the installed eikon as the active Herm avatar. Default true.",
+                "description": "Activate the installed eikon after install. Default true.",
                 "default": True,
             },
+            "active_ok": {
+                "type": "boolean",
+                "description": "Allow replacing the active eikon's backing package when installing over it.",
+                "default": False,
+            },
         },
         "required": ["source"],
     },
 }
+
+EIKON_SEARCH_SCHEMA = {
+    "name": "eikon_search",
+    "description": "Search the Herm eikon marketplace/catalog via `herm eikon search --json`.",
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "query": {"type": "string", "description": "Optional search query."},
+        },
+    },
+}
+
+EIKON_LIST_SCHEMA = {
+    "name": "eikon_list",
+    "description": "List installed Herm eikons via `herm eikon list --json`.",
+    "parameters": {"type": "object", "properties": {}},
+}
+
+EIKON_USE_SCHEMA = {
+    "name": "eikon_use",
+    "description": "Set an installed or bundled Herm eikon as active via `herm eikon use --json`.",
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "name": {"type": "string", "description": "Installed or bundled eikon name."},
+        },
+        "required": ["name"],
+    },
+}
+
+EIKON_UPDATE_SCHEMA = {
+    "name": "eikon_update",
+    "description": "Update an installed Herm eikon from its recorded source via `herm eikon update --json`.",
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "name": {"type": "string", "description": "Installed eikon name."},
+            "active_ok": {
+                "type": "boolean",
+                "description": "Allow updating the active avatar's backing package.",
+                "default": False,
+            },
+        },
+        "required": ["name"],
+    },
+}
+
+EIKON_REMOVE_SCHEMA = {
+    "name": "eikon_remove",
+    "description": "Remove an installed Herm eikon via `herm eikon remove --json`.",
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "name": {"type": "string", "description": "Installed eikon name."},
+            "active_ok": {
+                "type": "boolean",
+                "description": "Allow clearing the active avatar if this eikon is active.",
+                "default": False,
+            },
+        },
+        "required": ["name"],
+    },
+}

package/assets/plugins/eikon/tools.py

@@ -30,40 +30,96 @@ def check_herm_available() -> bool:
     return shutil.which(binary) is not None
 
 
-def _handle_eikon_install(args: dict[str, Any], **_: Any) -> str:
-    source = str(args.get("source") or "").strip()
-    if not source:
-        return _json({"ok": False, "error": "source is required"})
-
+def _run(parts: list[str], label: str, timeout: int = 120) -> dict[str, Any]:
     binary = _herm_bin()
     if not binary:
-        return _json({"ok": False, "error": "herm executable not found on PATH"})
-
-    cmd = [binary, "eikon", "install", source, "--json"]
-    name = str(args.get("name") or "").strip()
-    if name:
-        cmd.extend(["--name", name])
-    if args.get("media") is False or args.get("no_source") is True:
-        cmd.append("--no-source")
-    if args.get("set_active") is False:
-        cmd.append("--no-use")
+        return {"ok": False, "error": "herm executable not found on PATH"}
 
     try:
-        proc = subprocess.run(cmd, capture_output=True, text=True, timeout=120, check=False)
+        proc = subprocess.run([binary, *parts], capture_output=True, text=True, timeout=timeout, check=False)
     except FileNotFoundError:
-        return _json({"ok": False, "error": f"herm executable not found: {binary}"})
+        return {"ok": False, "error": f"herm executable not found: {binary}"}
     except subprocess.TimeoutExpired:
-        return _json({"ok": False, "error": "herm eikon install timed out"})
+        return {"ok": False, "error": f"herm eikon {label} timed out"}
 
     stdout = (proc.stdout or "").strip()
     stderr = (proc.stderr or "").strip()
     if proc.returncode != 0:
         detail = stderr or stdout or f"exit {proc.returncode}"
-        return _json({"ok": False, "error": f"herm eikon install failed: {detail}"})
+        return {"ok": False, "error": f"herm eikon {label} failed: {detail}"}
 
     line = next((ln for ln in reversed(stdout.splitlines()) if ln.strip()), "")
     try:
         payload = json.loads(line)
     except json.JSONDecodeError:
-        return _json({"ok": False, "error": "herm eikon install returned non-JSON output", "output": stdout})
-    return _json(payload)
+        return {"ok": False, "error": f"herm eikon {label} returned non-JSON output", "output": stdout}
+    if isinstance(payload, dict):
+        return payload
+    return {"ok": True, "result": payload}
+
+
+def _name(args: dict[str, Any]) -> str:
+    return str(args.get("name") or "").strip()
+
+
+def _handle_eikon_install(args: dict[str, Any], **_: Any) -> str:
+    source = str(args.get("source") or "").strip()
+    if not source:
+        return _json({"ok": False, "error": "source is required"})
+
+    cmd = ["eikon", "install", source, "--json"]
+    name = _name(args)
+    if name:
+        cmd.extend(["--name", name])
+    if args.get("media") is False or args.get("no_source") is True:
+        cmd.append("--no-source")
+    if args.get("active_ok") is True:
+        cmd.append("--active-ok")
+
+    payload = _run(cmd, "install")
+    if not payload.get("ok") or args.get("set_active") is False:
+        return _json(payload)
+
+    active = _run(["eikon", "use", str(payload.get("name") or source), "--json"], "use")
+    if not active.get("ok"):
+        return _json({"ok": False, "installed": payload, "error": f"installed but activation failed: {active.get('error', 'unknown error')}"})
+    return _json({**payload, "active": active.get("active")})
+
+
+def _handle_eikon_search(args: dict[str, Any], **_: Any) -> str:
+    query = str(args.get("query") or "").strip()
+    cmd = ["eikon", "search"]
+    if query:
+        cmd.append(query)
+    return _json(_run([*cmd, "--json"], "search"))
+
+
+def _handle_eikon_list(args: dict[str, Any], **_: Any) -> str:
+    return _json(_run(["eikon", "list", "--json"], "list"))
+
+
+def _handle_eikon_use(args: dict[str, Any], **_: Any) -> str:
+    name = _name(args)
+    if not name:
+        return _json({"ok": False, "error": "name is required"})
+    return _json(_run(["eikon", "use", name, "--json"], "use"))
+
+
+def _handle_eikon_update(args: dict[str, Any], **_: Any) -> str:
+    name = _name(args)
+    if not name:
+        return _json({"ok": False, "error": "name is required"})
+    cmd = ["eikon", "update", name, "--json"]
+    if args.get("active_ok") is True:
+        cmd.append("--active-ok")
+    return _json(_run(cmd, "update"))
+
+
+def _handle_eikon_remove(args: dict[str, Any], **_: Any) -> str:
+    name = _name(args)
+    if not name:
+        return _json({"ok": False, "error": "name is required"})
+    cmd = ["eikon", "remove", name, "--json"]
+    if args.get("active_ok") is True:
+        cmd.append("--active-ok")
+    return _json(_run(cmd, "remove"))

package/assets/skills/eikon/SKILL.md

@@ -1,15 +1,17 @@
 ---
 name: eikon
-description: Guide the user through making or editing a herm sidebar avatar (eikon) using herm's built-in Eikon Studio tab. The agent's role is advisory (what makes a good source, which knob to reach for); source generation is /eikon-create and all rasterize/bake happens in-app.
+description: Use when helping a user create, edit, install, activate, update, remove, or share a Herm eikon through the built-in Eikon tab or the `herm eikon` CLI.
+tags: [eikon, avatar, herm]
 related_skills: [eikon-create]
 ---
 
-# Building an eikon in herm
+# Building and managing eikons in Herm
 
-An eikon is a 48×24 monochrome text avatar. It lives on disk as:
+An eikon is a 48×24 monochrome text avatar. It lives in the active
+Hermes profile, normally:
 
     ~/.hermes/eikons/<name>/
-      <name>.eikon      packed NDJSON — written by Studio on Ctrl+S
+      <name>.eikon      packed NDJSON — written by Studio on Ctrl+S / Ctrl+U
       studio.json       Studio's workspace state
       source/           base.<ext>, <state>.<ext>
 
@@ -17,32 +19,99 @@ You do **not** write `.eikon` or `studio.json`. Studio does.
 
 ## Where the user does the work
 
-Herm's built-in **Eikon** tab (Studio / Gallery). Tell the user: "open
-the Eikon tab" or "Ctrl+K → Eikon". In Studio:
+Herm's built-in **Eikon** tab has **Library / Catalog / Studio**:
 
-- `eikon` row → pick / New…
-- `source` row → Local file… / Generate image… / Generate video…
+- **Library** — local and bundled eikons; use, edit, update, share, delete,
+  and New/install entry points.
+- **Catalog** — shared catalog; install runtime-only, install with source,
+  use installed eikons, download source, uninstall, or delist when eligible.
+- **Studio** — edit an existing local/source draft eikon and bake it.
+
+Tell the user: "open the Eikon tab"; `/library`, `/catalog`, and `/studio`
+jump directly to the Eikon sub-tabs. In Studio:
+
+- `eikon` row → pick an eikon, `+ New…`, or `+ Install…`
+- `source` row → local/downloaded source; Generate rows appear only when the
+  corresponding Hermes generation backend is configured
 - `input` section → contrast / invert / flip (pixel-domain, shared)
-- `<rasterizer>` section → symbols / fill / dither (glyph-domain)
-- Preview pane → wheel pans, Ctrl+wheel zooms, Shift+wheel pans X
-- **Ctrl+S** bakes all six states and sets it active
+- `<rasterizer>` section → rasterizer-specific glyph knobs, e.g. chafa
+  symbols/fill/dither or native symbols
+- Preview pane → wheel pans Y, Shift+wheel pans X, Ctrl+wheel zooms; drag the
+  pan bars to scrub pan
+- **Ctrl+S** bakes all six states without changing the active avatar
+- **Ctrl+U** bakes all six states and uses it as the active avatar
+- `u` in Studio opens the Submit eikon dialog; `s` in Library opens Share to
+  catalog for local unpublished eikons
 
 ## What makes a good source
 
-One line, once: **48×24, one color. Light subject on black, high
-contrast, strong silhouette.** Fine detail disappears; outline is
-everything.
+One line, once: **48×24, one color. Light subject on black, high contrast,
+strong silhouette.** Fine detail disappears; outline is everything.
 
 ## When to do what
 
 | user says | you do |
 |---|---|
 | "make me an eikon of X" | Load `eikon-create` and follow it. |
-| drops an image path | `cp` it to `~/.hermes/eikons/<name>/source/base.<ext>` → "Eikon tab, pick <name>". |
-| "edit my <name> eikon" | "Eikon tab → `eikon` row → <name>." |
+| drops an image path | Copy it to `${HERMES_HOME:-$HOME/.hermes}/eikons/<name>/source/base.<ext>` or use Library → New… → local file, then Studio → `eikon` row → `<name>`. |
+| "edit my <name> eikon" | "Eikon → Studio → `eikon` row → `<name>`." |
+| "install/shared catalog eikon" | "Eikon → Catalog" or `/catalog`. Choose Eikon only or Eikon + Source, then Use when ready. |
+| "install from GitHub / URL / dir" | "Studio → `eikon` row → `+ Install…`", "Library → New… → inspect/install", or `herm eikon install <name|url|dir>`. |
 | "too dark / washed out" | "invert toggle, then contrast slider — under `input`." |
-| "off-center / too small" | "Ctrl+wheel to zoom, wheel/drag to pan on the preview." |
-| "make it move" | `eikon-create` §5 (video), or Studio's `source` → Generate video…. |
+| "off-center / too small" | "Ctrl+wheel zooms; wheel/Shift+wheel pans; drag pan bars for precise pan." |
+| "make it move" | `eikon-create` §5 (video), or Studio's `source` row → Generate video… if available. |
+| "publish/share my eikon" | "After baking, press `u` in Studio or `s` in Library. Review metadata, bundle, and GitHub PR target before submitting." |
+| "remove from official catalog" | Use Catalog → Delist from Registry when eligible, or `herm eikon delist <name|id>`. |
+
+## Install and manage shared eikons
+
+For catalog eikons, use **Eikon → Catalog**. Rows show source,
+compatibility, trust (`Verified`, `Unverified`, or `Mismatch`), digest,
+and installed/active state. Catalog installs fetch built package artifacts;
+they do not clone creator repos.
+
+Default install is **Eikon only**: runtime package, no activation, no editable
+source. Choose **Eikon + Source**, or later **Download Source**, when the user
+wants to edit it in Studio.
+
+For direct sharing, use `github.com/user/repo/eikon-name` for a multi-eikon
+GitHub catalog repo, `github.com/user/repo` for a single-package repo, a git or
+HTTP URL, or a local package directory. Private GitHub repos use normal git
+authentication.
+
+The local lifecycle is explicit:
+
+```bash
+herm eikon search [query] [--json]
+herm eikon browse [query] [--json]
+herm eikon inspect <name|url|dir> [--json]
+herm eikon install <name|url|dir> [--name N] [--no-source] [--active-ok] [--json]
+herm eikon list [--json]
+herm eikon use <name> [--json]
+herm eikon info <name> [--json]
+herm eikon update <name> [--active-ok] [--json]
+herm eikon remove <name> [--active-ok] [--json]
+herm eikon delist <name|id> [--json]
+```
+
+`install` does not activate. If the installed name is currently active,
+installing replaces the active avatar's backing package and requires
+`--active-ok`. `use` activates. Updating or removing the active eikon also
+requires `--active-ok`.
+
+Creators share through normal GitHub repositories. For official registry
+listing, use `u` in Studio or Library → Share to catalog after baking: Herm
+runs registry preflight, asks for title/author/description/glyph, previews the
+public bundle, then creates a GitHub PR through local `gh` auth or gives manual
+PR instructions.
+Use upstream `eikon pack`, `eikon index`, and `eikon manifest` for
+direct-install repos. `eikon publish` is the lower-level GitHub PR contribution
+helper for the configured/default catalog repo, not a hosted account, upload,
+dashboard, or moderation flow.
+
+Browser catalog surfaces such as `eikon.liftaris.dev` are discovery-only: they
+preview catalog entries and give copyable `herm eikon install …` instructions.
+Do not imply a browser click installs, activates, authenticates, or mutates Herm.
 
 ## Quick poster
 
@@ -52,10 +121,14 @@ To show a candidate in chat without Studio:
 chafa --size=48x24 --symbols=braille --colors=none --format=symbols --stretch "<path>"
 ```
 
-Preview-only; Studio's output will differ (it tone-maps first).
+Preview-only; Studio's output will differ because it tone-maps first.
 
 ## Don'ts
 
 - Don't hand-write `.eikon` NDJSON.
 - Don't pick knob values for the user. Name the knob.
 - Don't repeat the 48×24 brief.
+- Don't say install activates. Install only writes the local package; Use
+  activates.
+- Don't describe hosted marketplace accounts, upload tokens, dashboards, or
+  browser-native install flows for the v1 registry.