@series-inc/stowkit-cli 0.6.19 → 0.6.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@series-inc/stowkit-cli",
-  "version": "0.6.19",
+  "version": "0.6.20",
   "type": "module",
   "bin": {
     "stowkit": "./dist/cli.js"
@@ -17,7 +17,7 @@
     "dev": "tsc --watch"
   },
   "dependencies": {
-    "@series-inc/stowkit-packer-gui": "^0.1.18",
+    "@series-inc/stowkit-packer-gui": "^0.1.19",
     "@series-inc/stowkit-editor": "^0.1.8",
     "draco3d": "^1.5.7",
     "fbx-parser": "^2.1.3",

package/skill.md

@@ -532,20 +532,86 @@ To refresh skill files without updating the CLI: `stowkit init --update`
 
 ## Asset Store
 
-StowKit includes a shared asset store for publishing, searching, and importing reusable asset packs across projects. Assets are stored in a public GCS bucket with a central `registry.json` manifest.
+StowKit includes a shared asset store for publishing, searching, and importing reusable asset packs across projects. Assets are stored in a GCS bucket with a central `registry.json` manifest.
 
-### Searching the store
+### Publishing to the store
+
+To publish a pack, you need an `assets-package.json` in the project root:
+
+```json
+{
+  "name": "my-pack",
+  "version": "1.0.0",
+  "author": "your-name",
+  "description": "A short description of what's in this pack",
+  "tags": ["environment", "fantasy", "low-poly"],
+  "bucket": "gs://venus-shared-assets-test"
+}
+```
+
+Then run `stowkit publish` from the packer GUI's Publish modal, or programmatically via the CLI server's `/api/publish` endpoint. The publish flow:
+
+1. Scans all assets in the `srcArtDir` and builds a dependency graph
+2. Uploads all source files to `packages/{name}/{version}/` in GCS
+3. Uploads per-asset thumbnails (captured in the packer GUI)
+4. Uploads a pack-level thumbnail if present (see below)
+5. Updates the central `registry.json` with the new version
+
+**Pack-level thumbnail:** Place a `thumbnail.webp`, `thumbnail.png`, or `thumbnail.jpg` in the project root directory. During publish, this file is uploaded alongside the package and displayed as the pack's cover image in the store. If no custom thumbnail is provided, the store shows a collage of individual asset thumbnails.
+
+**Version management:** Bump the `version` field in `assets-package.json` before each publish. Publishing the same version again requires `--force`.
+
+### Searching the store (CLI)
 
 ```bash
 stowkit store search coral                    # Find assets matching "coral"
+stowkit store search "boss, idle"             # AND search — both terms must match
 stowkit store search ocean --type texture     # Find textures tagged/named "ocean"
 stowkit store search staticMesh --json        # Machine-readable JSON output
 stowkit store list                            # List all published packages
-stowkit store info package_test               # Show all assets in a package
-stowkit store info package_test --json        # Full package details as JSON
+stowkit store info ninja-adventure            # Show all assets in a package
+stowkit store info ninja-adventure --json     # Full package details as JSON
 ```
 
-The `--json` flag outputs structured data with `stringId`, `type`, `packageName`, `version`, `file`, `size`, `tags`, `dependencies`, `thumbnail`, and `thumbnailUrl` for each asset. This is the recommended format for AI agents to consume.
+The `--json` flag outputs structured data for programmatic/AI consumption.
+
+### Search scoring algorithm
+
+Search uses a ranked scoring system with AND semantics. Each search term must independently clear a minimum threshold — weak matches alone won't surface results.
+
+**Scoring tiers (per term, highest match wins):**
+
+| Score | Match type | Example |
+|-------|-----------|---------|
+| 100 | Exact stringId match | "boss" matches asset "boss" |
+| 90 | Exact package name match | "ninja-adventure" matches the pack |
+| 80 | Exact asset tag match | "coral" matches tag "coral" |
+| 60 | Word match in stringId or tag | "boss" matches "actor/boss/idle" |
+| 50 | stringId starts with term | "act" matches "actor/boss/idle" |
+| 45-50 | Word match in package name/tag | "ninja" matches pack "ninja-adventure" |
+| 40 | Word prefix in stringId | "att" matches "attack" |
+| 25-35 | Substring/prefix matches | Various partial matches |
+| < 20 | File path, type, description | Below threshold — boost only |
+
+**Key behaviors:**
+- **AND semantics:** Multi-term queries (comma-separated) require ALL terms to match. "boss, idle" only returns assets matching both words.
+- **Minimum threshold (20):** Weak signals like file path matches or type name matches can't surface assets on their own. They only boost already-qualifying results.
+- **Tags score high:** Asset tags are curated metadata and rank just below exact name matches. If an asset has a tag that matches your query, it will surface prominently.
+- **Package metadata scoped:** When searching within a specific pack, package-level fields (name, description, tags) are excluded from scoring to prevent every asset from matching.
+
+**Word splitting:** StringIds and names are split on underscores, hyphens, dots, slashes, camelCase, and spaces. "NinjaBoss_Attack" becomes ["ninja", "boss", "attack"].
+
+### Searching in the Packer GUI
+
+The packer GUI has a **Store** button that opens a full-featured asset store browser:
+
+- **Global search:** Type a query without selecting a pack — shows matching **packs** (not individual assets), sorted by number of matches. Click a pack to browse its assets with the search term preserved.
+- **In-pack search:** Select a pack first, then search — shows individual assets within that pack, flat (no folder grouping), with AND scoring.
+- **Type filters:** Filter by asset type (texture, staticMesh, skinnedMesh, audio, materialSchema, animationClip) using toggle pills.
+- **Show All:** Checkbox to flatten the folder hierarchy and see all assets in the current pack at once. Combines with type filters.
+- **Folder browsing:** When not searching, navigate the pack's folder structure. Breadcrumbs below the filter bar show your current path.
+- **Thumbnail size:** Slider in the footer to adjust grid card size.
+- **Selection + dependencies:** Click assets to select them. Transitive dependencies are auto-resolved and shown with amber badges. The Import button downloads all selected assets and their deps into the project's `srcArtDir`.
 
 ### JSON search result format
 
@@ -561,6 +627,7 @@ The `--json` flag outputs structured data with `stringId`, `type`, `packageName`
     "tags": ["coral", "environment"],
     "dependencies": ["M_Sea_Floor"],
     "thumbnail": true,
+    "thumbnailFormat": "png",
     "thumbnailUrl": "https://storage.googleapis.com/venus-shared-assets-test/packages/ocean_pack/1.0.0/thumbnails/coral_1.png"
   }
 ]
@@ -572,16 +639,21 @@ Assets have dependency chains: meshes depend on materials, materials depend on t
 
 ### Importing from the store
 
-The packer GUI has a **Store** button to browse, search, and import assets. Selected assets and their transitive dependencies are downloaded directly into the project's `srcArtDir`.
+The packer GUI's Store modal handles importing. Selected assets and their transitive dependencies are downloaded directly into the project's `srcArtDir`. Already-imported assets are marked with a green "Imported" badge.
 
 ### Thumbnail URLs
 
-Published assets may have thumbnails at:
+Per-asset thumbnails (captured in the packer GUI during publish):
+```
+https://storage.googleapis.com/{bucket}/packages/{packageName}/{version}/thumbnails/{stringId}.{format}
+```
+
+Pack-level thumbnails (from project root `thumbnail.webp`):
 ```
-https://storage.googleapis.com/{bucket}/packages/{packageName}/{version}/thumbnails/{stringId}.png
+https://storage.googleapis.com/{bucket}/packages/{packageName}/{version}/thumbnail.webp
 ```
 
-Check the `thumbnail` boolean in search results to know if a thumbnail exists.
+Check the `thumbnail` boolean in search results to know if an asset has a thumbnail. Pack-level thumbnails are returned as `thumbnailUrl` in the package listing.
 
 ## Common Tasks for AI Agents
 
@@ -649,7 +721,11 @@ This is useful for verifying build output, checking which assets ended up in whi
 - **Set up with engine:** `stowkit init --with-engine` (installs `@series-inc/rundot-3d-engine` + `three`)
 - **Update CLI + skill files:** `stowkit update`
 - **Search the asset store:** `stowkit store search sword --json` (returns JSON array of matching assets with thumbnailUrls)
+- **AND search:** `stowkit store search "boss, idle" --json` (both terms must match)
 - **Find all meshes in the store:** `stowkit store search mesh --type staticMesh --json`
 - **List all published packages:** `stowkit store list --json`
 - **Get package details:** `stowkit store info ocean_pack --json`
-- **Show a thumbnail to the user:** Use the `thumbnailUrl` from search results — it's a public PNG URL
+- **Show a thumbnail to the user:** Use the `thumbnailUrl` from search results — it's a public URL
+- **Add a pack thumbnail:** Place `thumbnail.webp` (or `.png`/`.jpg`) in the project root before publishing
+- **Publish a pack:** Open the packer GUI (`stowkit packer`), click Publish, fill in version/description/tags, and publish
+- **Browse the store visually:** Open the packer GUI, click the Store button to browse, search, filter by type, and import assets