@schift-io/knowledge-scope 0.1.0 → 0.2.0

package/dist/types/state-contract.d.ts

@@ -47,6 +47,15 @@ export declare const StoredKnowledgeScopeSchema: z.ZodReadonly<z.ZodObject<{
             }, {
                 kind: "schift_search";
                 indexRef: string;
+            }>, z.ZodObject<{
+                kind: z.ZodLiteral<"local_documents">;
+                indexRef: z.ZodString;
+            }, "strict", z.ZodTypeAny, {
+                kind: "local_documents";
+                indexRef: string;
+            }, {
+                kind: "local_documents";
+                indexRef: string;
             }>, z.ZodObject<{
                 kind: z.ZodLiteral<"web_search">;
                 provider: z.ZodEnum<["customer", "schift"]>;
@@ -96,6 +105,9 @@ export declare const StoredKnowledgeScopeSchema: z.ZodReadonly<z.ZodObject<{
             }> | Readonly<{
                 kind: "schift_search";
                 indexRef: string;
+            }> | Readonly<{
+                kind: "local_documents";
+                indexRef: string;
             }> | Readonly<{
                 kind: "web_search";
                 provider: "customer" | "schift";
@@ -123,6 +135,9 @@ export declare const StoredKnowledgeScopeSchema: z.ZodReadonly<z.ZodObject<{
             }> | Readonly<{
                 kind: "schift_search";
                 indexRef: string;
+            }> | Readonly<{
+                kind: "local_documents";
+                indexRef: string;
             }> | Readonly<{
                 kind: "web_search";
                 provider: "customer" | "schift";
@@ -480,6 +495,9 @@ export declare const StoredKnowledgeScopeSchema: z.ZodReadonly<z.ZodObject<{
             }> | Readonly<{
                 kind: "schift_search";
                 indexRef: string;
+            }> | Readonly<{
+                kind: "local_documents";
+                indexRef: string;
             }> | Readonly<{
                 kind: "web_search";
                 provider: "customer" | "schift";
@@ -561,6 +579,9 @@ export declare const StoredKnowledgeScopeSchema: z.ZodReadonly<z.ZodObject<{
             }> | Readonly<{
                 kind: "schift_search";
                 indexRef: string;
+            }> | Readonly<{
+                kind: "local_documents";
+                indexRef: string;
             }> | Readonly<{
                 kind: "web_search";
                 provider: "customer" | "schift";
@@ -642,6 +663,9 @@ export declare const StoredKnowledgeScopeSchema: z.ZodReadonly<z.ZodObject<{
             }> | Readonly<{
                 kind: "schift_search";
                 indexRef: string;
+            }> | Readonly<{
+                kind: "local_documents";
+                indexRef: string;
             }> | Readonly<{
                 kind: "web_search";
                 provider: "customer" | "schift";
@@ -723,6 +747,9 @@ export declare const StoredKnowledgeScopeSchema: z.ZodReadonly<z.ZodObject<{
             }> | Readonly<{
                 kind: "schift_search";
                 indexRef: string;
+            }> | Readonly<{
+                kind: "local_documents";
+                indexRef: string;
             }> | Readonly<{
                 kind: "web_search";
                 provider: "customer" | "schift";
@@ -986,6 +1013,9 @@ export declare const StoredKnowledgeScopeSchema: z.ZodReadonly<z.ZodObject<{
             }> | Readonly<{
                 kind: "schift_search";
                 indexRef: string;
+            }> | Readonly<{
+                kind: "local_documents";
+                indexRef: string;
             }> | Readonly<{
                 kind: "web_search";
                 provider: "customer" | "schift";
@@ -1101,6 +1131,9 @@ export declare const StoredKnowledgeScopeSchema: z.ZodReadonly<z.ZodObject<{
             }> | Readonly<{
                 kind: "schift_search";
                 indexRef: string;
+            }> | Readonly<{
+                kind: "local_documents";
+                indexRef: string;
             }> | Readonly<{
                 kind: "web_search";
                 provider: "customer" | "schift";
@@ -1245,6 +1278,15 @@ export declare const KnowledgeScopeStateSchema: z.ZodReadonly<z.ZodObject<{
                 }, {
                     kind: "schift_search";
                     indexRef: string;
+                }>, z.ZodObject<{
+                    kind: z.ZodLiteral<"local_documents">;
+                    indexRef: z.ZodString;
+                }, "strict", z.ZodTypeAny, {
+                    kind: "local_documents";
+                    indexRef: string;
+                }, {
+                    kind: "local_documents";
+                    indexRef: string;
                 }>, z.ZodObject<{
                     kind: z.ZodLiteral<"web_search">;
                     provider: z.ZodEnum<["customer", "schift"]>;
@@ -1294,6 +1336,9 @@ export declare const KnowledgeScopeStateSchema: z.ZodReadonly<z.ZodObject<{
                 }> | Readonly<{
                     kind: "schift_search";
                     indexRef: string;
+                }> | Readonly<{
+                    kind: "local_documents";
+                    indexRef: string;
                 }> | Readonly<{
                     kind: "web_search";
                     provider: "customer" | "schift";
@@ -1321,6 +1366,9 @@ export declare const KnowledgeScopeStateSchema: z.ZodReadonly<z.ZodObject<{
                 }> | Readonly<{
                     kind: "schift_search";
                     indexRef: string;
+                }> | Readonly<{
+                    kind: "local_documents";
+                    indexRef: string;
                 }> | Readonly<{
                     kind: "web_search";
                     provider: "customer" | "schift";
@@ -1678,6 +1726,9 @@ export declare const KnowledgeScopeStateSchema: z.ZodReadonly<z.ZodObject<{
                 }> | Readonly<{
                     kind: "schift_search";
                     indexRef: string;
+                }> | Readonly<{
+                    kind: "local_documents";
+                    indexRef: string;
                 }> | Readonly<{
                     kind: "web_search";
                     provider: "customer" | "schift";
@@ -1759,6 +1810,9 @@ export declare const KnowledgeScopeStateSchema: z.ZodReadonly<z.ZodObject<{
                 }> | Readonly<{
                     kind: "schift_search";
                     indexRef: string;
+                }> | Readonly<{
+                    kind: "local_documents";
+                    indexRef: string;
                 }> | Readonly<{
                     kind: "web_search";
                     provider: "customer" | "schift";
@@ -1840,6 +1894,9 @@ export declare const KnowledgeScopeStateSchema: z.ZodReadonly<z.ZodObject<{
                 }> | Readonly<{
                     kind: "schift_search";
                     indexRef: string;
+                }> | Readonly<{
+                    kind: "local_documents";
+                    indexRef: string;
                 }> | Readonly<{
                     kind: "web_search";
                     provider: "customer" | "schift";
@@ -1921,6 +1978,9 @@ export declare const KnowledgeScopeStateSchema: z.ZodReadonly<z.ZodObject<{
                 }> | Readonly<{
                     kind: "schift_search";
                     indexRef: string;
+                }> | Readonly<{
+                    kind: "local_documents";
+                    indexRef: string;
                 }> | Readonly<{
                     kind: "web_search";
                     provider: "customer" | "schift";
@@ -2184,6 +2244,9 @@ export declare const KnowledgeScopeStateSchema: z.ZodReadonly<z.ZodObject<{
                 }> | Readonly<{
                     kind: "schift_search";
                     indexRef: string;
+                }> | Readonly<{
+                    kind: "local_documents";
+                    indexRef: string;
                 }> | Readonly<{
                     kind: "web_search";
                     provider: "customer" | "schift";
@@ -2299,6 +2362,9 @@ export declare const KnowledgeScopeStateSchema: z.ZodReadonly<z.ZodObject<{
                 }> | Readonly<{
                     kind: "schift_search";
                     indexRef: string;
+                }> | Readonly<{
+                    kind: "local_documents";
+                    indexRef: string;
                 }> | Readonly<{
                     kind: "web_search";
                     provider: "customer" | "schift";
@@ -2414,6 +2480,9 @@ export declare const KnowledgeScopeStateSchema: z.ZodReadonly<z.ZodObject<{
                 }> | Readonly<{
                     kind: "schift_search";
                     indexRef: string;
+                }> | Readonly<{
+                    kind: "local_documents";
+                    indexRef: string;
                 }> | Readonly<{
                     kind: "web_search";
                     provider: "customer" | "schift";
@@ -2529,6 +2598,9 @@ export declare const KnowledgeScopeStateSchema: z.ZodReadonly<z.ZodObject<{
                 }> | Readonly<{
                     kind: "schift_search";
                     indexRef: string;
+                }> | Readonly<{
+                    kind: "local_documents";
+                    indexRef: string;
                 }> | Readonly<{
                     kind: "web_search";
                     provider: "customer" | "schift";
@@ -2648,6 +2720,9 @@ export declare const KnowledgeScopeStateSchema: z.ZodReadonly<z.ZodObject<{
                 }> | Readonly<{
                     kind: "schift_search";
                     indexRef: string;
+                }> | Readonly<{
+                    kind: "local_documents";
+                    indexRef: string;
                 }> | Readonly<{
                     kind: "web_search";
                     provider: "customer" | "schift";
@@ -2767,6 +2842,9 @@ export declare const KnowledgeScopeStateSchema: z.ZodReadonly<z.ZodObject<{
                 }> | Readonly<{
                     kind: "schift_search";
                     indexRef: string;
+                }> | Readonly<{
+                    kind: "local_documents";
+                    indexRef: string;
                 }> | Readonly<{
                     kind: "web_search";
                     provider: "customer" | "schift";

package/docs/PILOT.md

@@ -1,8 +1,10 @@
 # Run a support-context pilot
 
-The pilot is for an AI application team, SI, or agency that already has support documents indexed
-in Schift Search. Its first task is to retrieve cited evidence for one support question and pass
-that evidence into its own application. Start with the [README quickstart](../README.md#quickstart).
+The pilot is for an AI application team, SI, or agency with approved support documents. Its first
+task is to retrieve cited evidence for one support question and pass that evidence into its own
+application. Start with the [local-file quickstart](../README.md#quickstart), which needs no account
+or model. Install `@schift-io/knowledge-scope@0.2.0` for this path; the older `0.1.0` requires the
+[hosted Search path](../README.md#hosted-search-advanced).
 
 Success means the customer can repeat that retrieval, inspect its sources, and refuse an answer
 when evidence is insufficient. Installing the package or passing synthetic tests does not establish
@@ -10,21 +12,29 @@ customer demand, live-provider compatibility, or better retrieval accuracy.
 
 ## Choose one question and one data boundary
 
-Ask the customer for a repeated support question whose approved answer is present in the indexed
-corpus. Record the expected document and passage before running retrieval. Select the authorized
-organization and bucket; confirm who may read that bucket.
+Ask the customer for a repeated support question whose approved answer is present in the documents.
+Record the expected document and passage before running retrieval. Obtain permission to copy those
+documents into local private state. Start with a small UTF-8 Markdown/text source and a new project
+directory. Do not publish source snapshots, generated local bindings, or installation state.
 
 The initial path is:
 
 ```text
-Existing indexed support documents
-  -> quickstart and local mount
+Approved Markdown/text documents
+  -> quickstart --source and private local snapshot
   -> retrieve and admit cited evidence
   -> customer's application
   -> customer verifies the cited passage
 ```
 
-The current Search adapter uses the mounted tenant and the Search API's organization/bucket ACL.
+Local retrieval is lexical and snapshot-based, not semantic search or continuous sync. Test both
+source-word queries and real user phrasing; a passage match alone does not establish relevance.
+Edit a source and confirm the old mount stays pinned; then create a new project/snapshot and
+verify the changed passage. Filesystem access protects local state, not a multi-user ACL service.
+An arbitrary local tenant label must not be presented as authentication or document authorization.
+
+For an existing hosted corpus, select the authorized organization and bucket and confirm who may
+read it. The Search adapter uses the mounted tenant and the Search API's organization/bucket ACL.
 It rejects narrower `namespace`, `subject`, and `session` requests before HTTP because the provider
 does not enforce those fields. An arbitrary tenant label is not a replacement for provider access
 control. Use an appropriately scoped bucket and installation when separate data access is required.
@@ -40,9 +50,9 @@ mounted policy and release their evidence only after combined admission succeeds
 
 1. Define the named operation and its input/result schemas. Identify its approved source and
    required evidence, including a stable record ID, revision, freshness, and citation.
-2. Supply an authorized executor through the injected records port, or configure an Open Connector
-   action in `core-dependencies/schift-connector`. The CLI does not create database connections or
-   accept raw SQL.
+2. Supply an authorized executor through the injected records port, or configure a read-only action
+   in a separately operated Open Connector service. Its implementation is not included in this
+   repository. The CLI does not create database connections or accept raw SQL.
 3. For Open Connector, allowlist the exact connector, account alias, and read-only action. If the
    operation needs filters or narrower Scope, provide a trusted input mapper that applies those
    restrictions in the provider-native input. Without it, the adapter rejects the request.
@@ -165,11 +175,14 @@ not evidence that more infrastructure will create demand.
 
 ## Evidence status
 
-Release-test observation (2026-09-22): one isolated full-suite run received a non-2xx response in
-the local Search fixture. Its status and listener identity were not captured. A later full run,
-330 repeated related tests, and 500 controlled same-port server replacements did not reproduce it.
-The fixture now asserts HTTP status and listener identity to make any recurrence diagnosable.
-The cause remains unconfirmed; no production change was made on the basis of this observation.
+Release-test observation (2026-09-22): the local Search HTTP fixture failed intermittently in
+isolated full-suite runs. Earlier related-test and same-port replacement probes did not reproduce
+the failure. During 0.2.0 release preparation, eight subsequent full-suite runs, including a
+sanitized environment and isolated release copy, passed; installed Node.js lifecycle checks also
+passed. The fixture now checks captured HTTP status and listener identity outside the adapter's
+error-catching boundary, so a future failure cannot hide the fixture assertion behind a generic
+provider error. The intermittent failure's cause remains unconfirmed. No production behavior,
+timeout, or retry policy was changed to make these tests pass.
 
 - [x] Local CE contract and adapter lifecycle have automated test coverage.
 - [x] An installable tarball and local fake-provider E2E path exist.

package/examples/local-documents/README.md

@@ -0,0 +1,48 @@
+# Retrieve a passage without an account
+
+Requires **0.2.0 or later** and Node.js 20 or later. This handbook is synthetic, not a customer
+dataset or an accuracy benchmark.
+
+From your application directory:
+
+```bash
+npm install @schift-io/knowledge-scope@0.2.0
+npx --no-install schift-ks quickstart ./handbook-project \
+  --source ./node_modules/@schift-io/knowledge-scope/examples/local-documents/support-handbook.md \
+  --query '환불 규정'
+```
+
+No cloud service, token, or model is called. A successful result contains a cited passage describing
+the 14-day refund window. The `schift://local-documents/...#Lx-Ly` citation identifies the source and
+line range; it is not a public web URL. Preserve its `installationId`, then ask another question:
+
+```bash
+npx --no-install schift-ks query '<installation-id>' --query '배송 기간'
+```
+
+The delivery passage says 3 to 5 business days. For an English query, use `Refund policy`.
+The local engine uses lexical matching, so these examples use wording present in the source.
+Do not interpret `ready` as a guarantee of semantic relevance or a correct final answer.
+
+## Pass evidence to your application
+
+Run the included SDK consumer with the default local tenant (`local-tenant`). If you supplied
+`--tenant`, use that returned tenant instead:
+
+```bash
+node node_modules/@schift-io/knowledge-scope/examples/consumer.mjs \
+  '<installation-id>' local-tenant '환불 규정' search
+```
+
+It loads the same local state, invokes the mounted `search` operation, prints evidence, and does
+not generate an answer. Only use `result.candidates` after `result.status === "ready"`; retain
+each citation. Handle `insufficient_evidence` by asking for more information or withholding the
+answer. The consumer exits with code 3 in that case.
+
+Replace `--source` with your own UTF-8 `.md` or `.txt` file or folder and choose a new destination
+directory. The private snapshot contains copied source text; do not share local state with the
+portable Pack. Refresh by creating a new snapshot/mount after source edits. There is no automatic
+sync, PDF/URL ingestion, or bundled MCP adapter.
+
+See the [main guide](../../README.md#quickstart) for setup and the
+[pilot guide](../../docs/PILOT.md) for real-data acceptance criteria.

package/examples/local-documents/support-handbook.md

@@ -0,0 +1,21 @@
+# Example Shop support handbook / 고객지원 안내
+
+Synthetic example only. These policies do not describe a real business.
+
+## 환불 규정 / Refund policy
+
+환불 규정: 구매 후 14일 이내에 사용하지 않은 상품의 환불을 요청할 수 있습니다.
+환불 신청에는 주문 번호가 필요합니다. 사용한 상품은 이 예제 정책에서 환불 대상이 아닙니다.
+Refund policy: unused products may be returned within 14 days of purchase.
+An order number is required. Used products are not eligible under this example policy.
+
+## 배송 기간 / Delivery time
+
+배송 기간: 주문 확인 후 영업일 기준 3일에서 5일이 걸립니다.
+Delivery time: orders arrive in 3 to 5 business days after confirmation.
+
+## 문의 / Contact
+
+담당자가 주문 번호를 확인한 후 개별 주문 문의에 응답합니다.
+A support representative checks the order number before responding about a specific order.
+This handbook contains no actual orders or customer records.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schift-io/knowledge-scope",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Portable Knowledge Scope authoring and local control plane.",
   "type": "module",
   "main": "./dist/index.js",
@@ -49,7 +49,7 @@
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/schift-io/schift.git",
+    "url": "git+https://github.com/schift-io/knowledge-scope.git",
     "directory": "packages/knowledge-scope-cli"
   },
   "publishConfig": {