stylegallery 0.1.11 → 0.1.12

package/AGENTS.md

@@ -37,8 +37,8 @@ Before editing generated artifacts, validators, lifecycle state, or ownership po
 ## Agent Retrieval Route
 
 - When repository filesystem access is available, traverse the local Markdown corpus first: start at this file and `README.md`, follow the relevant task route or domain index, and read the selected source files directly.
-- When the relevant path is not yet clear, use `sg-material search --query "<narrow query>" --paths-only --limit <N>` to obtain a small deterministic set of repository-relative candidate paths, then continue by reading those files locally.
-- Use `sg-material context` as a fallback when repository files cannot be read directly or when a bounded, provenance-linked context package must be transferred to another process. Do not make context packaging the default local retrieval path.
+- When the relevant path is not yet clear, use `stylegallery search "<narrow query>" --paths-only --limit <N>` to obtain a small deterministic set of repository-relative candidate paths, then continue by reading those files locally.
+- Use `stylegallery read <id> --outline` and `--section <slug>` to read one part of a long document. Use `stylegallery context --query` as a fallback when repository files cannot be read directly or when a bounded, provenance-linked context package must be transferred to another process. Do not make context packaging the default local retrieval path.
 
 The remaining pattern, CSS, naming, token, checklist, and verification rules apply to the Layout domain. Non-Layout domain documents may discuss product-layer behavior, but they do not authorize decorative or motion properties in reusable Layout pattern CSS.
 

package/GOVERNANCE.md

@@ -24,7 +24,7 @@ Use this file before editing repository documentation. It names which file is au
 | Quality gates and evidence | `quality/**/*.md` | Manual | None | `stable` | Claim-boundary changes, evidence-family changes, or broken quality links. | `scripts/validate-okf.mjs`, `scripts/validate-links.mjs`, `scripts/validate-ia.mjs` | Quality owner |
 | Consumer reference contract | `consumer-reference/contract.md`, `consumer-reference/schema/item.schema.json` | Manual | None | `stable` contract with related fixtures | Handoff shape, path boundary, lifecycle, ownership, or dependency-direction changes. | `scripts/validate-consumer-reference.mjs`, `scripts/test-validate-consumer-reference.mjs` | Repository governance owner with Validation owner |
 | Agent-native knowledge interface v1 | `consumer-reference/agent-native/registry.json`, `consumer-reference/agent-native/schema/*.json`, `scripts/agent-native/{registry,identity,queries}.mjs`, `scripts/sg.mjs`, `scripts/sg-mcp.mjs` | Manual, with protocol projections derived from one operation registry | Frozen v1 CLI JSON, read-only MCP tools/resources, and compatibility projections | `experimental`, byte-compatible v1 interface | Identity grammar, canonical hashing, registry records, operation metadata, capability/effect semantics, receipt/conformance rules, or retrieval changes. | `bun run test:agent-native` | Repository governance owner with Validation owner |
-| Governed material interface v2 | `consumer-reference/agent-native/v2/admission-policy.json`, its closed schemas, and admitted tracked Markdown | `scripts/agent-native/v2/generate-material-registry.mjs` | `consumer-reference/agent-native/v2/material-registry.json`; separate `sg-material` CLI and material MCP | `experimental`, read-only and isolated from v1 | Admission roots/exclusions, source hash, identity, operation inventory, query/context bounds, package exposure, or source drift changes. | `bun run validate:material`, `bun run test:material`, generated drift | Repository governance owner with Validation owner |
+| Governed material interface v2 | `consumer-reference/agent-native/v2/admission-policy.json`, its closed schemas, and admitted tracked Markdown | `scripts/agent-native/v2/generate-material-registry.mjs` | `consumer-reference/agent-native/v2/material-registry.json`; `stylegallery search|read|context` and the main and material MCP servers | `experimental`, read-only and isolated from v1 | Admission roots/exclusions, source hash, identity, operation inventory, query/context bounds, package exposure, or source drift changes. | `bun run validate:material`, `bun run test:material`, generated drift | Repository governance owner with Validation owner |
 | Experimental protocol extensions | `scripts/agent-native/v2/experimental-extension-registry.mjs`, `scripts/agent-native/v2/extensions/*.mjs`, lifecycle extension records | Manual | A2A `1.0` and AG-UI `0.0.57` projections | `experimental`, retained pending owner review | Protocol version, caller inventory, forwarding, migration evidence, or disposition changes. | `scripts/agent-native/v2/test-agent-extension-boundary.mjs`, lifecycle suites | Repository governance owner with protocol and Validation owners |
 | Lifecycle dispositions and archives | `consumer-reference/policies/lifecycle-dispositions.json`, its five records, and `consumer-reference/schema/lifecycle-disposition.schema.json` | Manual, with immutable archive receipts | Retrieval metadata for historical sentinel/calibration and page evidence | `pending_owner` for three families; both extensions `retain` | Owner, deadline, caller status, archive object/ref, approval, transition, or post-deadline action changes. | `bun run validate:lifecycle-dispositions`, `bun run test:lifecycle-dispositions` | Repository governance owner with named family owner and Validation owner |
 | Portable token source | `consumer-reference/fixtures/token-portability/valid-reference.json`, `consumer-reference/schema/portable-tokens.schema.json` | `scripts/build-reference-artifacts.mjs` with Style Dictionary `5.5.0` | `consumer-reference/generated/tokens.css`, `consumer-reference/generated/manifest.json` | `stable` restricted adapter contract, `generated` output | Allowed token shape, adapter/version pin, source token count, warning, declaration, or content hash changes. | `scripts/validate-reference-artifacts.mjs`, `scripts/test-reference-adapters.mjs` | Repository governance owner with Validation owner |

package/README.md

@@ -18,7 +18,7 @@ The existing Layout corpus remains a gallery of minimal, portable CSS layout pat
 
 [Consumer Reference](consumer-reference/index.md) is shared non-domain infrastructure for optional consumer-owned reference handoffs. It carries schema, routing, provenance, and evidence metadata without owning profiles, visual values, components, or a seventh domain.
 
-[Agent-Native StyleGallery](consumer-reference/agent-native/README.md) documents the frozen v1 claim/evidence/governance interface. The `sg` CLI and main MCP server also expose [website compilation](scripts/compiler/README.md) through a separately installed compiler; isolated material v2 indexes admitted Markdown through `sg-material` and its read-only MCP. Lifecycle records own extension and archive dispositions. These interfaces do not create a seventh domain, replace the Markdown corpus, permit mutation of governed knowledge, or feed visual defaults back into Layout.
+[Agent-Native StyleGallery](consumer-reference/agent-native/README.md) documents the frozen v1 claim/evidence/governance interface. The `stylegallery` CLI and main MCP server also expose [website compilation](scripts/compiler/README.md) through a separately installed compiler; isolated material v2 indexes admitted Markdown, searched and read through `stylegallery search` / `stylegallery read` and the matching MCP tools. Lifecycle records own extension and archive dispositions. These interfaces do not create a seventh domain, replace the Markdown corpus, permit mutation of governed knowledge, or feed visual defaults back into Layout.
 
 ## Quick Start
 
@@ -32,7 +32,7 @@ Or install the CLI globally:
 
 ```sh
 npm install --global stylegallery
-sg discover --format json
+stylegallery discover --format json
 ```
 
 The npm package includes the pinned `@chenglou/pretext@0.0.8` browser text-layout engine. StyleGallery uses it as a measurement and verification dependency for text-fit QA; the Node CLI and MCP servers do not execute browser Canvas APIs.
@@ -40,23 +40,23 @@ The npm package includes the pinned `@chenglou/pretext@0.0.8` browser text-layou
 Common read-only commands:
 
 ```sh
-sg resolve sg:profile/editorial-reference-profile --format json
-sg claims sg:profile/editorial-reference-profile --format json
-sg context sg:profile/editorial-reference-profile --format json
-sg ops --format json
+stylegallery resolve sg:profile/editorial-reference-profile --format json
+stylegallery claims sg:profile/editorial-reference-profile --format json
+stylegallery context sg:profile/editorial-reference-profile --format json
+stylegallery ops --format json
 ```
 
 Check the gallery's own claims with the Registrar and the Conservator:
 
 ```sh
-sg registrar
-sg registrar --stale
-sg registrar --unverified
-sg conservator
-sg conservator --pattern sidebar,reel --controls
+stylegallery registrar
+stylegallery registrar --stale
+stylegallery registrar --unverified
+stylegallery conservator
+stylegallery conservator --pattern sidebar,reel --controls
 ```
 
-`sg registrar` checks every claim record in `quality/claim-records/` against the [claim template and machine-field rules](quality/claims.md). `--stale` lists records whose review date has passed, and `--unverified` lists records whose verdict is not fully automated. `sg conservator` renders every Layout pattern's documented CSS in Chromium at 320, 768, and 1440 CSS pixels and measures the spatial behavior the pattern doc claims. `--controls` also removes a declaration each pattern depends on and requires the matching measurement to fail. Playwright is installed with the package, but its browser is not. If Chromium is missing, the command reports `browser_missing`; run `npx playwright install chromium`, add `--install-browser`, or use an installed Chrome with `--channel chrome`.
+`stylegallery registrar` checks every claim record in `quality/claim-records/` against the [claim template and machine-field rules](quality/claims.md). `--stale` lists records whose review date has passed, and `--unverified` lists records whose verdict is not fully automated. `stylegallery conservator` renders every Layout pattern's documented CSS in Chromium at 320, 768, and 1440 CSS pixels and measures the spatial behavior the pattern doc claims. `--controls` also removes a declaration each pattern depends on and requires the matching measurement to fail. Playwright is installed with the package, but its browser is not. If Chromium is missing, the command reports `browser_missing`; run `npx playwright install chromium`, add `--install-browser`, or use an installed Chrome with `--channel chrome`.
 
 Every command writes JSON to stdout. Knowledge results retain their deterministic v1 payloads; `discover` and `ops` also report the local compiler installation. Invalid input returns an error object and a nonzero exit status. See [Agent-Native StyleGallery](consumer-reference/agent-native/README.md) for the frozen knowledge contract, StableRef and VersionID model, MCP resources, and trust boundaries.
 
@@ -64,24 +64,28 @@ Compile a website directly through SG after [installing the compiler](scripts/co
 
 ```sh
 export SG_COMPILER_ROOT=/absolute/path/to/site-compiler
-sg compile --url https://example.com --out ./captures/example
-sg timeline --url https://example.com --out ./captures/example --step 500
-sg workflow
+stylegallery compile --url https://example.com --out ./captures/example
+stylegallery timeline --url https://example.com --out ./captures/example --step 500
+stylegallery workflow
 ```
 
 `compile`, `timeline`, `transcribe`, `sale`, `gate`, and `build` are direct SG commands and MCP tool names. See [SG Website Compilation](scripts/compiler/README.md) for all commands, configuration, output ownership, and verification.
 
-Start with `sg 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.
+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.
 
-Material v2 searches the admitted Markdown corpus and returns JSON without an additional format flag:
+`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:
 
 ```sh
-npx --package stylegallery sg-material discover
-npx --package stylegallery sg-material search --query "sticky layout" --paths-only --limit 5
-npx --package stylegallery sg-material context --query "responsive sidebar" --budget-tokens 4096
+npx stylegallery search "sticky header"
+npx stylegallery search "헤더 고정" --query-en "sticky header"
+npx stylegallery search "sticky layout" --paths-only --limit 5
+npx stylegallery read sg:layout/sticky-header --outline
+npx stylegallery read sg:layout/sticky-header --section css
+npx stylegallery context --query "responsive sidebar" --budget-tokens 4096
+npx stylegallery --help
 ```
 
-With a global install, the same commands are available as `sg-material discover`, `sg-material search`, and `sg-material context`.
+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.
 
@@ -116,18 +120,7 @@ Example MCP client configuration:
 
 The main MCP server exposes governed read operations and compiler execution tools. Configure `SG_COMPILER_ROOT` in its environment to use the compiler. Execution tools declare file and network effects; the knowledge registry remains a read-only API. The frozen read-only server remains available as `bun run sg:mcp:v1`.
 
-The separate Material v2 MCP server is available as `stylegallery-material-mcp`. Attach it for Markdown retrieval and authoring work; the main server covers governed knowledge reads and compiler execution.
-
-```json
-{
-  "mcpServers": {
-    "stylegallery-material": {
-      "command": "npx",
-      "args": ["--yes", "--package", "stylegallery", "stylegallery-material-mcp"]
-    }
-  }
-}
-```
+The main server also exposes `search` and `read`, the same operations and JSON as the CLI commands, so one server covers Markdown retrieval. The former Material v2 server (`material-*` tools) still runs as `stylegallery-material-mcp` in 0.1.12 with a rename notice on stderr.
 
 ## 한국어 빠른 시작
 
@@ -141,10 +134,10 @@ npx stylegallery discover --format json
 
 ```sh
 npm install --global stylegallery
-sg discover --format json
+stylegallery discover --format json
 ```
 
-`discover`는 사용 가능한 인터페이스를 보여주고, `resolve`는 하나의 레코드를 조회하며, `claims`는 관련 주장과 근거를 분리해서 보여줍니다. `context`는 에이전트에 전달할 수 있는 제한된 컨텍스트 패키지를 만들고, `ops`는 지원하는 작업 목록을 반환합니다. 저장소를 직접 읽을 수 있는 에이전트는 `AGENTS.md`와 이 README의 작업 경로에서 시작해 로컬 Markdown을 따라가는 방식이 기본입니다. 경로가 불명확할 때만 `sg-material search --query "검색어" --paths-only --limit 5`로 후보 경로를 좁히고, `context`는 파일에 직접 접근할 수 없거나 제한된 패키지를 전달해야 할 때 사용합니다. 모든 결과는 자동화에 바로 사용할 수 있는 JSON입니다.
+`discover`는 사용 가능한 인터페이스를 보여주고, `resolve`는 하나의 레코드를 조회하며, `claims`는 관련 주장과 근거를 분리해서 보여줍니다. `context`는 에이전트에 전달할 수 있는 제한된 컨텍스트 패키지를 만들고, `ops`는 지원하는 작업 목록을 반환합니다. 저장소를 직접 읽을 수 있는 에이전트는 `AGENTS.md`와 이 README의 작업 경로에서 시작해 로컬 Markdown을 따라가는 방식이 기본입니다. 경로가 불명확할 때만 `stylegallery search "검색어" --paths-only --limit 5`로 후보 경로를 좁히고, `context`는 파일에 직접 접근할 수 없거나 제한된 패키지를 전달해야 할 때 사용합니다. 모든 결과는 자동화에 바로 사용할 수 있는 JSON입니다.
 
 CLI와 MCP의 상세 사용법은 [Agent-Native StyleGallery 가이드](consumer-reference/agent-native/README.md)를 참고하세요. 사람이 문서를 탐색하려면 아래의 도메인 표에서 목적에 맞는 진입점을 선택하면 됩니다.
 

package/consumer-reference/agent-native/README.md

@@ -6,7 +6,7 @@ description: Machine-facing identity, query, execution, protocol-projection, and
 
 # Agent-Native StyleGallery
 
-Primary role: frozen v1 knowledge interface guide. For the current `sg` CLI and main MCP server, including compiler execution, use [SG Website Compilation](../../scripts/compiler/README.md).
+Primary role: frozen v1 knowledge interface guide. For the current `stylegallery` CLI and main MCP server, including compiler execution, use [SG Website Compilation](../../scripts/compiler/README.md).
 
 Agent-Native StyleGallery lets a person, script, or agent inspect the governed StyleGallery knowledge graph without learning repository paths first. The Markdown corpus remains the human-readable source material; the agent-native layer gives its governed fixture records stable identities, closed schemas, deterministic operations, and protocol-specific projections.
 
@@ -58,13 +58,13 @@ All machine-mode results are deterministic JSON on stdout. A failed request retu
 
 ## Governed Material v2
 
-Material v2 is an isolated, read-only interface over admitted Markdown. Use `sg-material discover`, `search`, `get`, and `context`, or the equivalent `material-*` tools exposed by `stylegallery-material-mcp`. It does not merge material with v1 trust records or expand the admission policy.
+Material v2 is an isolated, read-only interface over admitted Markdown. Use `stylegallery search`, `stylegallery read`, and `stylegallery context --query`, or the `search` and `read` tools of `stylegallery-mcp`. It does not merge material with v1 trust records or expand the admission policy.
 
-Search keeps the fixed field weights `title: 16`, `path: 8`, and `body: 1`. For a multi-token query, each field contribution is multiplied by `ceil(material_count / max(1, token_document_frequency))` so a specific, uncommon term such as `sticky` is not outranked by a corpus-wide term such as `layout`. Results expose the document frequency and multiplier for every normalized query token; ties remain ordered by projected StableRef. `--paths-only` preserves the same ranking while returning repository-relative paths.
+`stylegallery search` (search v3, `scripts/agent-native/v2/material-search-v3.mjs`) ranks with BM25F (`k1` 1.2) over the fields title (weight 4), aliases (4), description (2.5), questions (2.5), path (2), headings (1.5), and body (1), each with its own length normalization. Terms are NFKC-lowercased Unicode words with English stopwords removed and light plural/-ing/-ed stemming. Hangul 2-grams are indexed only from Korean `aliases`, `questions`, and titles. `aliases` and `questions` are frontmatter JSON lists (`aliases: ["sticky top navigation", "헤더 고정"]`); add only names and questions the document's own sections answer. `query_en` adds an English rewrite of a non-English query. Ties order by readable id (`sg:<domain>/<slug>`, from the file name, or the path when names collide). `--paths-only` keeps the same ranking. The legacy `material-search` operation keeps its fixed `title: 16`, `path: 8`, `body: 1` weights with a rarity multiplier for the material v2 MCP. `node scripts/search-eval.mjs` scores both rankers on `eval/search/questions.json`.
 
 ```sh
-sg-material search --query "sticky layout" --paths-only --limit 5
-stylegallery-material search --query "design terminology source kinds" --paths-only --limit 5
+stylegallery search "sticky layout" --paths-only --limit 5
+stylegallery search "design terminology source kinds" --paths-only --limit 5
 ```
 
 ## MCP