stylegallery 0.1.14 → 0.1.16

package/README.md

@@ -73,7 +73,7 @@ stylegallery workflow
 
 Start with `stylegallery workflow` to select the stages for reconstruction, adaptation, or sale-package production. For a faithful clone, use available original media and fill document gaps by inspecting the source. The automatic `build` command is a sale-edition preview with restricted source access; it is not the general clone builder.
 
-`search` ranks the admitted Markdown corpus offline (BM25F over title, aliases, description, questions, path, headings, and body) and returns JSON (schema 3.0) without a format flag. Each result carries a readable id such as `sg:layout/sticky-header`, a verbatim snippet, and the next `read` command:
+`search` ranks the admitted Markdown corpus and returns JSON (schema 3.0) without a format flag. The default `hybrid` mode fuses BM25F (over title, aliases, description, questions, path, headings, and body) with the similarity of a small English embedding model, so everyday wording such as "sidebar layout that collapses on mobile" finds documents that use different words; `--mode lexical` ranks with BM25F alone. The result's `mode` field says which ranking ran. Each result carries a readable id such as `sg:layout/sticky-header`, a verbatim snippet, and the next `read` command:
 
 ```sh
 npx stylegallery search "sticky header"
@@ -85,21 +85,28 @@ npx stylegallery context --query "responsive sidebar" --budget-tokens 4096
 npx stylegallery --help
 ```
 
+Search modes and the embedding model:
+
+- The model ([bge-small-en-v1.5](https://huggingface.co/Xenova/bge-small-en-v1.5), quantized ONNX, 34 MB) is not part of the npm package. The first hybrid search downloads it into `~/.cache/stylegallery/models/` (or `$STYLEGALLERY_CACHE_DIR`, or `$XDG_CACHE_HOME/stylegallery`) from a pinned revision and checks its SHA-256; later searches run offline. Document vectors are precomputed and shipped with the package.
+- It runs with `onnxruntime-web` (WebAssembly), an optional dependency. When that dependency is missing, the download fails or is disabled with `STYLEGALLERY_OFFLINE=1`, or the query is Korean without `--query-en`, search falls back to BM25F, sets `mode` to `lexical` with a `mode_reason`, and the CLI prints one warning to stderr. Results are then identical to `--mode lexical`.
+- Ranking is deterministic: the same query and corpus give the same order. On an Apple M4 a CLI search takes about 0.4 s in hybrid mode (about 0.15 s lexical), most of it process and model start; inside the running MCP server a query takes about 0.1 s, of which ranking is about 25 ms.
+- Maintainers regenerate the vectors with `bun run generate:search-embeddings` after editing documents; CI fails when they are stale.
+
 Agents asking in another language should pass `--query-en` (MCP: `query_en`) with an English rewrite; Korean words match only documents that declare Korean `aliases`. The old `sg` alias is gone (it collided with ast-grep); `sg-material`, `stylegallery-material`, and `stylegallery-material-mcp` still work in 0.1.12 with a rename notice and are removed in the next release.
 
 For a coding agent with repository filesystem access, local guided traversal is the default: read `AGENTS.md` and this README, follow the narrowest relevant task route or domain index, and inspect the selected Markdown files directly. Use `search --paths-only` only when the path is unclear; it returns a deterministic `paths` array of repository-relative candidates without full result metadata. Reserve `context` for environments that cannot read repository files or for transferring a bounded, provenance-linked package.
 
 ### Connect your agent
 
-Installing the package does not make Claude Code or Codex use it. Run `setup` once to copy the `stylegallery-search` skill into each agent's user skill folder and register the `stylegallery-mcp` server:
+Installing the package does not make Claude Code, Codex, or OmO use it. Run `setup` once to copy the `stylegallery-search` skill into each agent's user skill folder and register the `stylegallery-mcp` server:
 
 ```sh
 npm install --global stylegallery
 stylegallery setup --dry-run   # show the planned changes
-stylegallery setup             # Claude Code and Codex, whichever is installed
+stylegallery setup             # Claude Code, Codex, and OmO, whichever is installed
 ```
 
-Claude Code gets `~/.claude/skills/stylegallery-search/SKILL.md` and a user-scope `mcpServers.stylegallery` entry in `~/.claude.json`; Codex gets `~/.agents/skills/stylegallery-search/SKILL.md` and `[mcp_servers.stylegallery]` in `~/.codex/config.toml` (or `$CODEX_HOME/config.toml`). The server runs as `npx -y --package stylegallery stylegallery-mcp`, so it works however the package was installed. Rerunning changes nothing, every modified config file is backed up first as `<file>.bak-stylegallery-<timestamp>`, other settings are preserved, and an existing entry with the same name but different settings is left alone unless you pass `--force`. Use `--agent claude|codex|all`, `--only skill|mcp`, and `--uninstall` to narrow or undo it, then check with `claude mcp list` or `codex mcp list`.
+Claude Code gets `~/.claude/skills/stylegallery-search/SKILL.md` and a user-scope `mcpServers.stylegallery` entry in `~/.claude.json`; Codex gets `~/.agents/skills/stylegallery-search/SKILL.md` and `[mcp_servers.stylegallery]` in `~/.codex/config.toml` (or `$CODEX_HOME/config.toml`); OmO shares the `~/.agents/skills` copy with Codex (written once, and kept on `--uninstall --agent omo` while Codex is still detected, and vice versa) and gets `mcpServers.stylegallery` in `~/.omo/agent/mcp.json` (or `$OMO_CODING_AGENT_DIR/mcp.json`). The server runs as `npx -y --package stylegallery stylegallery-mcp`, so it works however the package was installed. Rerunning changes nothing, every modified config file is backed up first as `<file>.bak-stylegallery-<timestamp>`, other settings are preserved, and an existing entry with the same name but different settings is left alone unless you pass `--force`. Use `--agent claude|codex|omo|all`, `--only skill|mcp`, and `--uninstall` to narrow or undo it, then check with `claude mcp list` or `codex mcp list`.
 
 ### CLI reference
 
@@ -117,7 +124,7 @@ Find and read documents (offline, deterministic):
 
 | Command | Options | Purpose |
 | --- | --- | --- |
-| `search <query...>` | `--limit <n>` (1-50, default 5), `--paths-only`, `--detailed`, `--query-en <text>` | Rank the Markdown corpus; JSON schema 3.0 with id, snippet, and next `read` command |
+| `search <query...>` | `--limit <n>` (1-50, default 5), `--paths-only`, `--detailed`, `--query-en <text>`, `--mode <hybrid\|lexical>` (default `hybrid`) | Rank the Markdown corpus; JSON schema 3.0 with id, snippet, and next `read` command |
 | `read <id\|path>` | `--outline`, `--section <slug>` | Read one document by id (`sg:layout/sticky-header`), repository path, or StableRef |
 | `context --query <text>` | `--budget-tokens <n>` (256-32768, default 8192) | Build a bounded, provenance-linked context package |
 
@@ -138,7 +145,7 @@ Connect your agents:
 
 | Command | Options | Purpose |
 | --- | --- | --- |
-| `setup` | `--agent <claude\|codex\|all>`, `--only <skill\|mcp>`, `--dry-run`, `--uninstall`, `--force` | Install the search skill and register `stylegallery-mcp` for Claude Code and Codex ([Connect your agent](#connect-your-agent)) |
+| `setup` | `--agent <claude\|codex\|omo\|all>`, `--only <skill\|mcp>`, `--dry-run`, `--uninstall`, `--force` | Install the search skill and register `stylegallery-mcp` for Claude Code, Codex, and OmO ([Connect your agent](#connect-your-agent)) |
 
 Site compilation (requires `SG_COMPILER_ROOT`): `compile`, `timeline`, `transcribe`, `sale`, `gate`, `build`, `shots`, `probe`, `workflow`. Start with `stylegallery workflow`.
 
@@ -192,7 +199,7 @@ npm install --global stylegallery
 stylegallery discover --format json
 ```
 
-설치만으로는 Claude Code나 Codex가 StyleGallery를 쓰지 않습니다. 한 번 `stylegallery setup`을 실행하면 `stylegallery-search` 스킬을 각 에이전트의 사용자 스킬 폴더에 복사하고 `stylegallery-mcp` 서버를 등록합니다. `--dry-run`으로 바뀔 내용만 먼저 볼 수 있고, `--agent claude|codex|all`, `--only skill|mcp`, `--uninstall`, `--force`를 지원합니다. 다시 실행해도 결과는 같고, 수정하는 설정 파일은 먼저 `.bak-stylegallery-<시각>`으로 백업하며, 같은 이름의 다른 설정은 `--force` 없이는 건드리지 않습니다. 등록 확인은 `claude mcp list` 또는 `codex mcp list`로 합니다.
+설치만으로는 Claude Code, Codex, OmO가 StyleGallery를 쓰지 않습니다. 한 번 `stylegallery setup`을 실행하면 `stylegallery-search` 스킬을 각 에이전트의 사용자 스킬 폴더에 복사하고 `stylegallery-mcp` 서버를 등록합니다. `--dry-run`으로 바뀔 내용만 먼저 볼 수 있고, `--agent claude|codex|omo|all`, `--only skill|mcp`, `--uninstall`, `--force`를 지원합니다. 다시 실행해도 결과는 같고, 수정하는 설정 파일은 먼저 `.bak-stylegallery-<시각>`으로 백업하며, 같은 이름의 다른 설정은 `--force` 없이는 건드리지 않습니다. OmO는 Codex와 같은 `~/.agents/skills` 스킬을 쓰고 MCP는 `~/.omo/agent/mcp.json`(또는 `$OMO_CODING_AGENT_DIR/mcp.json`)에 등록합니다. 공유 스킬은 다른 에이전트가 아직 설치돼 있으면 `--uninstall` 때 남깁니다. 등록 확인은 `claude mcp list` 또는 `codex mcp list`로 하고, OmO는 다시 시작하면 반영됩니다.
 
 ```sh
 stylegallery setup --dry-run
@@ -338,7 +345,7 @@ Pattern verification covers the relevant viewport, container, content, direction
 
 The npm package is published from GitHub Actions through [npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers). The repository stores no npm token, and nothing is published from a local machine.
 
-1. Open a pull request that bumps `version` in `package.json`, adds the `log.md` entry, and refreshes the material registry and lifecycle hashes that the version change touches. Merge it after CI passes.
+1. Open a pull request that bumps `version` in `package.json`, adds the `log.md` entry, and refreshes the search embeddings (`bun run generate:search-embeddings`, since `log.md` is embedded), the material registry, and the lifecycle hashes that the version change touches. Merge it after CI passes.
 2. Create a GitHub Release from `main` whose tag is `v` plus the new version, for example `v0.1.11`.
 3. Publishing the release runs [`.github/workflows/publish.yml`](.github/workflows/publish.yml). The workflow checks that the tag matches `package.json`, runs the governance, lifecycle, reference-artifact, material, and Registrar checks, and runs `npm publish` with a short-lived OIDC credential. npm attaches provenance automatically.