hyperview 0.3.1__tar.gz → 0.4.0__tar.gz

hyperview-0.4.0/.agents/skills/hyperview-cli/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: hyperview-cli
+description: Use HyperView's control-plane CLI for hyperview serve, dataset create, workspace create, embeddings compute, layouts compute, runtime jobs, ui layout set, ui selection set, ui panel add, extension add, tools run, native module panels, backend tools, and local HyperView plugin workflows.
+license: MIT
+compatibility: Requires Python 3.10+ and the hyperview CLI (`uv tool install hyperview`). Runtime-control commands require a running HyperView server.
+metadata:
+  homepage: https://github.com/Hyper3Labs/HyperView
+---
+
+# HyperView CLI
+
+Use the `hyperview` CLI as the primary agent interface to HyperView.
+
+## Install the Skill
+
+For users who installed HyperView from a package, install or refresh this agent skill with:
+
+```bash
+uv tool install --upgrade hyperview && hyperview skill install
+```
+
+Re-running `hyperview skill install` replaces old HyperView skill copies. By default this installs into detected agent locations plus the universal `~/.agents/skills/` fallback. Limit targets with repeated `--agent` flags such as `--agent claude-code`, `--agent github-copilot`, `--agent cursor`, or `--agent universal`; use `--all-known` when you explicitly want every known agent profile. Use `--scope project` to write project-local skills such as `.claude/skills/`, `.github/skills/`, `.cursor/skills/`, or `.agents/skills/` depending on the selected agent.
+
+## When to use it
+
+- Create or inspect a persisted dataset.
+- Create or inspect a workspace.
+- Set the single dataset attached to a workspace.
+- Start or control a running HyperView runtime.
+- Register a custom embedding provider.
+- Compute embeddings or layouts without restarting the UI.
+- Switch the active workspace, layout, or selection in a running session.
+- Add or remove agent-authored native module panels from local files.
+- Create, install, reload, or test a local plugin/extension with Python backend tools and a frontend panel.
+
+## Core workflow
+
+1. Create a workspace, usually with its dataset in the same command.
+2. Create the dataset if it does not exist yet.
+3. Start or target a running `hyperview serve` runtime.
+4. Register a provider if needed.
+5. Submit embedding or layout jobs through the runtime.
+6. Use `hyperview ui ...` commands to switch what the live UI shows.
+7. For plugins, create an extension folder and install it into the running workspace.
+
+## Current model
+
+- One dataset per workspace.
+- Datasets are created separately from workspaces.
+- The workspace owns the dataset selection.
+- `ui layout set` changes the active layout and the frontend opens the matching built-in scatter panel.
+- Runtime-added panels can be typed scatter instances bound to explicit layout keys, or native module panels loaded into the host React tree.
+- Runtime-added panels use the stable `HyperViewPanelSDK` surface on `window`.
+- Plugins are repo-local extension folders with `extension.toml`, optional Python tools, and optional native panel modules.
+- Plugin panels call backend tools through `HyperViewPanelSDK.hooks.useTool()` or `hyperview tools run`.
+- In practice, create datasets and workspaces before starting the runtime for that workspace. The current runtime loads workspace registry state on startup.
+
+Read [references/commands.md](references/commands.md) for command recipes covering datasets, workspaces, providers, embeddings, layouts, runtime UI state, selections, and jobs.
+Read [references/native-panels.md](references/native-panels.md) when the task involves authoring or registering a custom panel.
+Read [references/plugins.md](references/plugins.md) when the task involves backend-plus-frontend plugins/extensions.
+
+## Agent guidance
+
+- Prefer CLI commands over direct file edits when the goal is to operate a running HyperView session.
+- Treat dataset creation and workspace binding as separate steps when needed: `dataset create ...` creates persisted data, `workspace create --dataset ...` or `workspace set-dataset ...` binds it to a workspace.
+- Prefer `workspace create --dataset ...` over separate create and dataset-attach calls when setting up a new workspace.
+- For custom module panels, have the agent write panel modules outside the app source tree, for example under `agent-context/`, and then add them through `hyperview ui panel add --module-file ...`.
+- For side-by-side embedding comparisons, add typed scatter panels through `hyperview ui panel add --kind scatter --layout-key ... --reference-panel-id ... --direction right`.
+- For plugins, prefer `.hyperview/extensions/<plugin-name>/` in the project root. `hyperview serve` auto-discovers those folders and attaches them to the launched workspace, so they can live in version control with the dataset/project code.
+- Tools can write files under `ctx.extension_storage` and return `ctx.url_for(path)` for panel-renderable artifact URLs.
+- Keep plugins self-contained: `extension.toml`, `tools.py`, `panel.js` or `panel.jsx`, and any local assets in the same folder.
+- Prefer `--json` output when chaining commands or inspecting results programmatically.
+- Wait for embedding/layout jobs to finish before issuing layout-switch commands that depend on their results.
+- Use `hyperview jobs list` or `hyperview jobs inspect <job-id>` if a compute command is long-running or you started it with `--no-wait`.
+- For provider args, use repeated `--provider-arg key=value` flags.
+- Treat the workspace as the durable unit. Changing datasets means setting a new workspace dataset, not switching among many datasets inside one workspace.
+- Prefer native module panels over raw HTML. The panel system no longer relies on iframes.
+- The first `uv run hyperview ...` invocation in a session can take 30+ seconds (torch/datasets imports). Allow generous timeouts and avoid sending SIGINT.
+
+## Inspecting runtime state
+
+The runtime exposes JSON discovery endpoints alongside the CLI. Use them to obtain layout keys, sample IDs, and registered tools/panels for follow-up commands:
+
+- `GET /api/runtime?workspace_id=<ws>` &mdash; full snapshot. Read `workspace.ui.active_layout_key`, `workspace.ui.selected_ids`, `workspace.ui.custom_panels[*].data.module_src`, and registered `extensions`/`tools`.
+- `GET /api/embeddings?workspace_id=<ws>` &mdash; the active or default layout, including `layout_key`, `geometry`, and sample `ids`. Use the returned `layout_key` for `hyperview ui layout set --layout-key ...` and pick from `ids` for `hyperview ui selection set --ids ...`.
+- `GET /api/tools` &mdash; registered tool URIs (also returned by `hyperview tools list --json`).
+
+Layout keys encode geometry and dimension as a substring (e.g. `..._euclidean_umap__2d_...`, `..._hyperbolic_umap__3d_...`). Match on those substrings when filtering by geometry/dimension.

hyperview-0.4.0/.agents/skills/hyperview-cli/references/commands.md

@@ -0,0 +1,223 @@
+# Commands
+
+Use `--json` when chaining commands or inspecting results programmatically.
+
+## Skill Installer
+
+Install the packaged HyperView agent skill for detected agents plus the universal fallback:
+
+```bash
+hyperview skill install
+```
+
+Refresh installed copies after upgrading HyperView by running install again:
+
+```bash
+uv tool install --upgrade hyperview && hyperview skill install
+```
+
+Limit to specific agent targets:
+
+```bash
+hyperview skill install --agent claude-code --yes       # ~/.claude/skills/
+hyperview skill install --agent github-copilot --yes    # ~/.copilot/skills/
+hyperview skill install --agent cursor --yes            # ~/.cursor/skills/
+hyperview skill install --agent universal --yes         # ~/.agents/skills/
+```
+
+Install for every known profile explicitly:
+
+```bash
+hyperview skill install --all-known --yes
+```
+
+Install into a repo for project-shared discovery:
+
+```bash
+hyperview skill install --scope project --agent github-copilot --yes  # .github/skills/
+hyperview skill install --scope project --agent claude-code --yes     # .claude/skills/
+hyperview skill install --scope project --agent cursor --yes          # .cursor/skills/
+hyperview skill install --scope project --agent universal --yes       # .agents/skills/
+```
+
+Preview destinations without writing files:
+
+```bash
+hyperview skill install --dry-run --json
+```
+
+This is different from `hyperview extension add`, which installs a runtime plugin into a running HyperView workspace.
+
+## Datasets and Workspaces
+
+Create a persisted dataset from Hugging Face:
+
+```bash
+hyperview dataset create cifar10_demo \
+  --hf-dataset uoft-cs/cifar10 \
+  --split train \
+  --image-key img \
+  --label-key label
+```
+
+Create a persisted dataset from a local image directory:
+
+```bash
+hyperview dataset create local_assets_demo \
+  --images-dir assets
+```
+
+Create a workspace with its dataset in one step:
+
+```bash
+hyperview workspace create research \
+  --dataset cifar10_demo \
+  --activate
+```
+
+Change the dataset attached to a workspace:
+
+```bash
+hyperview workspace set-dataset research imagenette_clip_20260411
+```
+
+Start the runtime:
+
+```bash
+hyperview serve --workspace research --dataset cifar10_demo --no-browser
+```
+
+Check a running runtime:
+
+```bash
+hyperview status --json
+```
+
+## Providers, Embeddings, and Layouts
+
+Register a custom provider:
+
+```bash
+hyperview provider register my-provider \
+  --import-path my_pkg.provider:MyProvider
+```
+
+Compute checkpoint-backed embeddings and a layout:
+
+```bash
+hyperview embeddings compute \
+  --workspace research \
+  --dataset cifar10_demo \
+  --provider my-provider \
+  --model-id experiment-a \
+  --checkpoint /path/to/checkpoint.json \
+  --layout euclidean:2d
+```
+
+Add a new layout to an existing embedding space:
+
+```bash
+hyperview layouts compute \
+  --workspace research \
+  --dataset cifar10_demo \
+  --space-key <space-key> \
+  --layout euclidean:3d
+```
+
+Inspect long-running jobs:
+
+```bash
+hyperview jobs list --json
+hyperview jobs inspect <job-id> --json
+```
+
+## Runtime UI
+
+Discover an existing layout key and sample IDs before mutating runtime state:
+
+```bash
+curl --max-time 2 'http://127.0.0.1:6262/api/runtime?workspace_id=research' | jq '.workspace.ui'
+curl --max-time 2 'http://127.0.0.1:6262/api/embeddings?workspace_id=research' | jq '{layout_key, geometry, ids: (.ids[:3])}'
+```
+
+If no layout exists yet (`active_layout_key` is `null` and `/api/embeddings` returns nothing), create one with `hyperview embeddings compute ... --layout euclidean:2d` (creates embeddings + layout) or `hyperview layouts compute ... --space-key <space-key> --layout euclidean:2d` (adds a layout to an existing embedding space).
+
+Switch the live UI to a layout and selection:
+
+```bash
+hyperview ui layout set --workspace research --layout-key <layout-key>
+hyperview ui selection set --workspace research --ids sample-1,sample-8
+```
+
+`--layout-key` must be an existing layout (use the `layout_key` returned by `/api/embeddings`). When the chosen layout is Euclidean 3D, HyperView opens or focuses the Euclidean 3D scatter panel.
+
+Add a native panel from a local JavaScript module file:
+
+```bash
+hyperview ui panel add \
+  --workspace research \
+  --panel-id label-histogram \
+  --title "Label Histogram" \
+  --position right \
+  --module-file agent-context/panels/label-histogram/index.js
+```
+
+Add two runtime scatter panels bound to explicit layouts, side by side:
+
+```bash
+hyperview ui panel add \
+  --workspace research \
+  --panel-id uncha-poincare \
+  --title "UNCHA" \
+  --kind scatter \
+  --layout-key <uncha-poincare-layout-key> \
+  --position center
+
+hyperview ui panel add \
+  --workspace research \
+  --panel-id hycoclip-poincare \
+  --title "HyCoCLIP" \
+  --kind scatter \
+  --layout-key <hycoclip-poincare-layout-key> \
+  --position center \
+  --reference-panel-id uncha-poincare \
+  --direction right
+```
+
+Remove a runtime panel by id:
+
+```bash
+hyperview ui panel remove \
+  --workspace research \
+  --panel-id hycoclip-poincare
+```
+
+## Plugins and Tools
+
+Create backend-plus-frontend plugins under `.hyperview/extensions/<name>/` so they can be versioned with the project and auto-attached on `hyperview serve`. For a server that is already running, install one explicitly:
+
+```bash
+hyperview extension add .hyperview/extensions/selection-profile \
+  --workspace research \
+  --json
+```
+
+Inspect and run installed plugin tools:
+
+```bash
+hyperview extension list --json
+# => {"extensions":[{"name":"selection-profile","folder":"...","workspace_id":"research","panels":["selection-profile"],"tools":[{"uri":"selection_profile.summarize",...}]}]}
+
+hyperview tools list --json
+hyperview tools run selection_profile.summarize \
+  --workspace research \
+  --param 'sample_ids=["sample-1","sample-8"]' \
+  --json
+```
+
+`--param key=value` parses the value as JSON, then falls back to a raw string if JSON parsing fails. Use:
+
+- `--param 'top_k=5'` for numbers
+- `--param 'enabled=true'` for booleans
+- `--param 'name=foo'` for short strings (raw fallback) or `--param 'name="foo bar"'` for explicit JSON strings
+- `--param 'ids=["a","b"]'` or `--param 'opts={"k":1}'` for arrays/objects

hyperview-0.4.0/.agents/skills/hyperview-cli/references/native-panels.md

@@ -0,0 +1,138 @@
+# Native Panels
+
+Use this guide when writing a custom HyperView panel that should behave like a native built-in panel. If the panel also needs backend Python tools, use [plugins.md](plugins.md) instead.
+
+## Model
+
+HyperView no longer treats runtime-added panels as iframe HTML pages.
+
+Runtime panels are now native module panels:
+
+- the user writes a local JavaScript module file
+- the module is registered through the CLI with `hyperview ui panel add --module-file ...`
+- HyperView loads that module directly into the host React tree
+- the module can use the stable `window.HyperViewPanelSDK` surface
+
+Built-in panels and runtime panels now share the same host panel system.
+
+## Panel Module Contract
+
+A runtime panel module must export either:
+
+- a default React component
+- or a named export `Panel`
+
+The module runs in the browser and should use the SDK from `window.HyperViewPanelSDK`.
+
+Minimal example:
+
+```js
+const sdk = globalThis.HyperViewPanelSDK;
+const { React, components, hooks } = sdk;
+const { Panel, PanelToolbar } = components;
+const { usePanelRuntimeState } = hooks;
+
+export default function MyPanel() {
+  const { runtimeDatasetName } = usePanelRuntimeState();
+
+  return React.createElement(
+    Panel,
+    { className: "h-full" },
+    React.createElement(PanelToolbar, {
+      items: [{ id: "dataset", label: "Dataset", value: runtimeDatasetName || "unknown" }],
+    }),
+    React.createElement("div", { style: { padding: 12 } }, "Hello from a native panel")
+  );
+}
+```
+
+## Stable SDK Surface
+
+Current global SDK fields:
+
+- `React`
+- `components.Panel`
+- `components.PanelHeader`
+- `components.PanelTitle`
+- `components.PanelToolbar`
+- `components.PanelToolbarButton`
+- `components.PanelToolbarMenu`
+- `hooks.usePanelClient()`
+- `hooks.usePanelCommands()`
+- `hooks.usePanelDatasetInfo()`
+- `hooks.usePanelRuntimeState()`
+- `hooks.usePanelSamples()`
+- `hooks.usePanelSamplesView()`
+- `hooks.usePanelSelection()`
+- `hooks.usePanelUiState()`
+- `hooks.useTool(uri)`
+- `createClient(workspaceId)`
+
+Important distinction:
+
+- `usePanelSamplesView()` gives access to host-managed collection state and is the best hook for panels that should stay synchronized with the visible HyperView UI.
+- `usePanelClient()` or `createClient()` is the escape hatch for direct backend reads and control-plane calls.
+- `useTool(uri)` calls an installed backend tool registered by an extension and returns `{ loading, result, error, run, reset }`.
+
+### Hook return shapes
+
+Verified against the current `panel-sdk` surface:
+
+- `usePanelSelection()` → `{ selectedIds: string[], selectionSource: SelectionUpdateSource, setSelection(ids: string[], source?: SelectionUpdateSource): void, clearSelection(): void }`
+- `usePanelCommands()` → `{ setLabelFilter, setHoveredId, clearLassoSelection, clearSelection(): void, setSelection(ids: string[], source?: SelectionUpdateSource): void, focusPanel(panelId: string): boolean, closePanel(panelId: string): boolean }`
+- `usePanelRuntimeState()` → `{ activeWorkspaceId, runtimeDatasetName, activeLayoutKey, requestedLayoutKey, workspaces, customPanels }`
+- `usePanelUiState()` → `{ sampleGridSize, setSampleGridSize, scatterLabelOverlayMode, setScatterLabelOverlayMode }`
+- `usePanelDatasetInfo()` / `usePanelSamples()` / `usePanelSamplesView()` → host-managed dataset and view state
+- `useTool(uri)` → `{ loading: boolean, result: TResult | null, error: string | null, run(params?): Promise<TResult | null>, reset(): void }`
+- `usePanelClient()` → low-level client; pair with `createClient(workspaceId)` for direct API calls.
+
+To clear the current selection from a panel use `usePanelSelection().clearSelection()` or `usePanelCommands().setSelection([])`.
+
+## Placement
+
+Native runtime panels can be added in:
+
+- `right`
+- `bottom`
+- `center`
+
+Center placement lets a runtime panel behave like a normal center tab.
+
+## CLI Registration
+
+Register a panel module into a running workspace:
+
+```bash
+hyperview ui panel add \
+  --host 127.0.0.1 \
+  --port 6262 \
+  --workspace imagenette-cli-20260412 \
+  --panel-id native-label-histogram \
+  --title "Native Label Histogram" \
+  --position right \
+  --module-file agent-context/panels/native-label-histogram/index.js
+```
+
+## Verification
+
+After `hyperview ui panel add ...`:
+
+- `curl 'http://127.0.0.1:6262/api/runtime?workspace_id=<ws>'` should list the panel under `workspace.ui.custom_panels[*]` with `data.module_src` set to a `/api/panels/content/<ws>/<panel-id>/<file>` URL.
+- Fetching `data.module_src` should return `application/javascript` with your module body.
+- The panel should appear in the live UI in the requested `position` slot.
+
+## Good Practices
+
+- Prefer native module panels over HTML or iframe content.
+- Use `usePanelSamplesView()` for view-synchronized behavior.
+- Use `usePanelCommands()` for host interactions such as label filtering or selection changes.
+- Use `usePanelClient()` only for data that is not already available through the host state.
+- Keep the panel self-contained under `agent-context/panels/<panel-name>/`.
+- If the panel needs sibling assets, keep them next to the module and reference them with relative URLs.
+- Do not render a second title/header inside a normal Dockview runtime panel unless there is a strong reason. Dockview already provides the tab title. Built-in center and runtime panels should usually start with the standardized `PanelToolbar` row.
+
+## Current Limitation
+
+Runtime module panels should currently be authored as browser-loadable JavaScript modules.
+
+If an agent wants TypeScript or JSX ergonomics, it should bundle or transpile to JavaScript before registration.

hyperview-0.4.0/.agents/skills/hyperview-cli/references/plugins.md

@@ -0,0 +1,186 @@
+# Plugins
+
+Use this guide when creating a HyperView plugin that includes backend Python tools and a frontend panel.
+
+## Model
+
+A plugin is a local extension folder with an `extension.toml` manifest. One folder can register Python tools, native panel modules, or both.
+
+Preferred shape for agent-authored, project-versioned plugins:
+
+```text
+.hyperview/extensions/selection-profile/
+  extension.toml
+  tools.py
+  panel.jsx
+```
+
+Use `.hyperview/extensions/<name>/` by default. `hyperview serve` auto-discovers those folders from the project root, even when launched from a nested directory. Use `agent-context/extensions/<name>/` only for scratch or explicit local installs that should not attach automatically on launch.
+
+## Manifest
+
+Use a stable extension `name`. Tool-generated artifacts are served by extension name through `ctx.url_for(...)`, while panel modules are served by panel id.
+
+```toml
+name = "selection-profile"
+description = "Selection profile panel"
+
+[[tools]]
+file = "tools.py"
+
+[[panels]]
+id = "selection-profile"
+title = "Selection Profile"
+position = "right"
+file = "panel.jsx"
+```
+
+Valid panel positions are `right`, `bottom`, and `center`.
+
+## Backend Tools
+
+Tools are plain Python functions decorated with `@tool("namespace.name")`. The first argument is a `RunContext`.
+
+```python
+from __future__ import annotations
+
+from collections import Counter
+from typing import Any
+
+from hyperview.tools import RunContext, tool
+
+
+@tool("selection_profile.summarize")
+def summarize_selection(ctx: RunContext, *, sample_ids: list[str] | None = None) -> dict[str, Any]:
+    if ctx.dataset is None:
+        raise ValueError("No active dataset")
+
+    ids = sample_ids or ctx.workspace.ui.selected_ids
+    selected_samples = ctx.dataset.get_samples_by_ids(ids) if ids else []
+    label_counts = Counter(sample.label or "unlabeled" for sample in selected_samples)
+
+    return {
+        "dataset": ctx.dataset.name,
+        "selection_count": len(selected_samples),
+        "labels": [
+            {"label": label, "count": count}
+            for label, count in label_counts.most_common(8)
+        ],
+    }
+```
+
+Use `ctx.dataset` for active dataset reads, `ctx.workspace` for workspace UI state, `ctx.extension_storage` for per-plugin writable files, `ctx.url_for(path)` for renderable artifact URLs, and `ctx.submit_job(...)` for long-running work.
+
+### RunContext and Sample shapes
+
+- `ctx.dataset` &mdash; the active `Dataset`. Iterate samples with `for s in ctx.dataset.samples:` (returns `list[Sample]`). Look up by id with `ctx.dataset.get_samples_by_ids(ids)`.
+- `ctx.workspace.ui.selected_ids` &mdash; current selection (`list[str]`).
+- `ctx.extension_storage` &mdash; `pathlib.Path` to a writable per-plugin folder.
+- `ctx.url_for(path)` &mdash; returns a fetchable URL for a file under `extension_storage`.
+- `ctx.submit_job(...)` &mdash; schedule long-running work; returns a job handle.
+
+`Sample` (from `hyperview.core.sample`) exposes:
+
+- `sample.id: str`
+- `sample.label: str | None`
+- `sample.metadata: dict[str, Any]`
+
+## Frontend Panel
+
+Panel modules must be browser-loadable JavaScript modules. They export a default React component or named `Panel`, and use `globalThis.HyperViewPanelSDK` rather than importing from app internals.
+
+```js
+const sdk = globalThis.HyperViewPanelSDK;
+if (!sdk) throw new Error("HyperViewPanelSDK is not available on window.");
+
+const { React, components, hooks } = sdk;
+const { Panel, PanelToolbar, PanelToolbarButton } = components;
+const { usePanelSelection, useTool } = hooks;
+
+export default function SelectionProfilePanel() {
+  const { selectedIds } = usePanelSelection();
+  const profile = useTool("selection_profile.summarize");
+  const selectionKey = selectedIds.join("|");
+
+  React.useEffect(() => {
+    profile.run({ sample_ids: selectedIds });
+  }, [profile.run, selectionKey]);
+
+  const result = profile.result;
+
+  return React.createElement(
+    Panel,
+    { className: "h-full" },
+    React.createElement(PanelToolbar, {
+      items: [
+        { id: "selection", label: "Selection", value: String(selectedIds.length) },
+        { id: "status", label: "Status", value: profile.loading ? "running" : result ? "ready" : "idle" },
+      ],
+      actions: React.createElement(PanelToolbarButton, { onClick: () => profile.run({ sample_ids: selectedIds }) }, "Refresh"),
+    }),
+    React.createElement("pre", { style: { padding: 12, overflow: "auto" } }, JSON.stringify(result, null, 2))
+  );
+}
+```
+
+Available SDK hooks include `usePanelRuntimeState`, `usePanelDatasetInfo`, `usePanelSamplesView`, `usePanelSelection`, `usePanelCommands`, `usePanelUiState`, `usePanelClient`, and `useTool`.
+
+`useTool(uri)` returns `{ run, result, loading, error, reset }`. Call `run(params)` to invoke the tool; `result` holds the last successful return value, `loading` is true while a call is in flight, and `error` is the last failure message (or `null`). See [native-panels.md](native-panels.md#hook-return-shapes) for the full hook return shape table.
+
+## CLI Workflow
+
+Start a runtime for an existing workspace and dataset:
+
+```bash
+hyperview serve --workspace research --dataset cifar10_demo --no-browser
+```
+
+If the plugin already exists under `.hyperview/extensions/`, starting `hyperview serve` attaches it automatically. For a server that is already running, install or reload the plugin explicitly:
+
+```bash
+hyperview extension add .hyperview/extensions/selection-profile \
+  --workspace research \
+  --json
+```
+
+Inspect the result:
+
+```bash
+hyperview extension list --json
+hyperview tools list --json
+curl --max-time 2 'http://127.0.0.1:6262/api/runtime?workspace_id=research'
+```
+
+Run a tool directly:
+
+```bash
+hyperview tools run selection_profile.summarize \
+  --workspace research \
+  --param 'sample_ids=["sample-1","sample-8"]' \
+  --json
+```
+
+Reload after editing files:
+
+```bash
+hyperview extension reload selection-profile --json
+```
+
+## Verification
+
+A good plugin smoke test proves all of these paths:
+
+- `extension add` returns the plugin with expected tools and panels.
+- `GET /api/tools` (or `hyperview tools list --json`) includes the tool URI.
+- `hyperview tools run ...` returns data from the active dataset.
+- Tool-generated files under `ctx.extension_storage` are fetchable from URLs returned by `ctx.url_for(...)`.
+- `GET /api/runtime?workspace_id=<workspace>` includes the panel under `workspace.ui.custom_panels[*]` with `data.module_src` set to a `/api/panels/content/<workspace>/<panel-id>/<file>` URL.
+- Fetching `data.module_src` returns `application/javascript` with your module body.
+- In the browser, the panel imports successfully and a `useTool()` call returns a result.
+
+## Constraints
+
+- Treat plugins as trusted local code. Python tools are imported and executed in the HyperView runtime process.
+- Do not use bare npm imports in panel modules unless you bundle first.
+- Keep plugin source outside `frontend/src`; the runtime loads it from local files.
+- Keep plugin examples small and high-level. Avoid private HyperView APIs in user-facing examples.

{hyperview-0.3.1 → hyperview-0.4.0}/.gitignore

@@ -63,6 +63,7 @@ scripts_ignored/
 
 # AI Context (Agent files)
 .claude/
+agent-context/
 context/
 CLAUDE.md
 TASKS.md
@@ -74,12 +75,19 @@ AGENTS.md
 .github/hooks/
 .github/skills/
 .agents/
+!.agents/
+!.agents/skills/
+.agents/skills/*
+!.agents/skills/hyperview-cli/
+!.agents/skills/hyperview-cli/**
 .specstory/
 
 # Deployment repo (managed as a separate nested git repository)
 hyper-models/
 hyperview-spaces/
 eval/
+hyper-lrp/
 
 # Generated version file (hatch-vcs)
 src/hyperview/_version.py
+node_modules/