From 13448966f5b8cd97a8582b1b5b22b9691bf6f291 Mon Sep 17 00:00:00 2001
From: akshitkrnagpal <akshitkrnagpal@gmail.com>
Date: Fri, 22 May 2026 14:04:17 +0400
Subject: [PATCH] Document documents search input shape

---
 .changeset/clear-search-docs.md         |  5 +++++
 README.md                               | 13 +++++++++++++
 packages/cli/src/operation-docs.test.ts |  2 +-
 packages/cli/src/operation-docs.ts      |  6 +++---
 4 files changed, 22 insertions(+), 4 deletions(-)
 create mode 100644 .changeset/clear-search-docs.md

diff --git a/.changeset/clear-search-docs.md b/.changeset/clear-search-docs.md
new file mode 100644
index 0000000..a509312
--- /dev/null
+++ b/.changeset/clear-search-docs.md
@@ -0,0 +1,5 @@
+---
+"@typesensekit/cli": patch
+---
+
+Document the `documents.search` input shape with the required top-level `params` wrapper.
diff --git a/README.md b/README.md
index c3fcae4..f0e61d3 100644
--- a/README.md
+++ b/README.md
@@ -42,6 +42,19 @@ List every supported operation:
 tsk operations
 ```
 
+Inspect an operation's input shape before running it:
+
+```sh
+tsk documents.search --schema
+tsk documents.search --examples
+```
+
+Search parameters are passed inside the top-level `params` object:
+
+```sh
+tsk documents.search --input '{"collection":"production__products","params":{"q":"*","query_by":"q"}}' --json
+```
+
 ## MCP Server
 
 Run the MCP stdio server directly:
diff --git a/packages/cli/src/operation-docs.test.ts b/packages/cli/src/operation-docs.test.ts
index d776393..6471898 100644
--- a/packages/cli/src/operation-docs.test.ts
+++ b/packages/cli/src/operation-docs.test.ts
@@ -38,7 +38,7 @@ describe("operation docs", () => {
 
   it("renders command-specific examples for common operations", () => {
     expect(renderOperationExamples("documents.search")).toContain(
-      `tsk documents.search --input '{"collection":"products","params":{"q":"chair","query_by":"title,description"}}' --json`,
+      `tsk documents.search --input '{"collection":"production__products","params":{"q":"*","query_by":"q"}}' --json`,
     );
     expect(renderOperationExamples("presets.create")).toContain(
       `tsk presets.create --input '{"name":"Semantic","value":{"query_by":"title_embedding"}}' --json`,
diff --git a/packages/cli/src/operation-docs.ts b/packages/cli/src/operation-docs.ts
index 97b22ca..a192bf6 100644
--- a/packages/cli/src/operation-docs.ts
+++ b/packages/cli/src/operation-docs.ts
@@ -64,10 +64,10 @@ const EXAMPLES: Record<string, JsonValue[]> = {
   ],
   "documents.search": [
     {
-      collection: "products",
+      collection: "production__products",
       params: {
-        q: "chair",
-        query_by: "title,description",
+        q: "*",
+        query_by: "q",
       },
     },
   ],