@gmickel/gno 1.23.0 → 1.24.0

package/README.md

@@ -50,8 +50,10 @@ Use it when:
 # Install
 bun install -g @gmickel/gno
 
-# Add a few collections
-gno init ~/notes --name notes
+# Prove the first folder immediately; semantic work continues independently
+gno setup ~/notes --name notes
+
+# Add more collections with the granular commands
 gno collection add ~/work/docs --name work-docs --pattern "**/*.{md,pdf,docx}"
 gno collection add ~/work/gno/src --name gno-code --pattern "**/*.{ts,tsx,js,jsx}"
 
@@ -60,7 +62,7 @@ gno context add "notes:" "Personal notes, journal entries, and long-form ideas"
 gno context add "work-docs:" "Architecture docs, runbooks, RFCs, meeting notes"
 gno context add "gno-code:" "Source code for the GNO application"
 
-# Index + embed
+# Sync the additional collections, then embed when you want semantic retrieval
 gno update --yes
 gno embed
 
@@ -105,7 +107,7 @@ gno daemon --detach  # headless continuous indexing (background; --status / --st
 
 <!-- public-truth:current-version -->
 
-> Current release: **v1.23.0** — see [CHANGELOG.md](./CHANGELOG.md)
+> Current release: **v1.24.0** — see [CHANGELOG.md](./CHANGELOG.md)
 
 <!-- /public-truth -->
 
@@ -218,8 +220,7 @@ gno query "ECONNREFUSED 127.0.0.1:5432" --thorough
 ## Quick Start
 
 ```bash
-gno init ~/notes --name notes    # Point at your docs
-gno index                        # Build search index
+gno setup ~/notes --name notes   # Build BM25 and prove an exact local result
 gno daemon --detach              # Keep index fresh in the background (macOS/Linux)
 gno query "auth best practices"  # Hybrid search
 gno ask "summarize the API" --answer  # AI answer with citations
@@ -254,14 +255,19 @@ brew install sqlite3
 Verify the local installation and corpus-derived lexical retrieval:
 
 ```bash
-gno doctor
-gno status --json
+gno setup ~/notes --name notes
 ```
 
-`gno status` is passive with respect to models and connectors and exits 0 even
-when its structured activation state is degraded. `gno doctor` exits 2 when any
-configured folder fails the lexical proof; semantic models may still be pending
-without blocking BM25 search.
+`gno setup` returns only after BM25 finds an exact `gno://` result from the
+folder. It is safe to rerun: the same canonical folder and collection are
+reused. Semantic indexing is a separate one-shot process; `--no-semantic`
+records an explicit skip. Add repeatable `--connector <id>` flags only when you
+also want supported agent integrations installed and checked. Setup is direct
+and standalone—it never attaches to `serve`, `daemon`, Web, or MCP.
+
+Use `gno status --json` for passive state and `gno doctor` for diagnostics.
+Semantic pending and connector follow-up never invalidate proven lexical
+search.
 
 <!-- public-truth:supported-platforms -->
 

package/assets/skill/SKILL.md

@@ -30,12 +30,19 @@ network boundaries.
 ## Quick Start
 
 ```bash
-gno init                              # Initialize in current directory
-gno collection add ~/docs --name docs # Add folder to index
-gno index                             # Build index (ingest + embed)
+gno setup ~/docs --name docs          # Index + prove exact BM25; semantic continues
 gno search "your query"               # BM25 keyword search
 ```
 
+`gno setup` is the default activation path. It is idempotent, returns only
+after exact lexical proof, and runs directly without resident/Web/MCP
+attachment. Use `--no-semantic` to start no worker and record skipped state.
+Use repeatable `--connector` with `claude-code-skill`,
+`claude-desktop-mcp`, `cursor-mcp`, `codex-skill`, `opencode-skill`,
+`openclaw-skill`, or `hermes-skill`. Connector skips/failures can return
+`completed_with_actions` without invalidating lexical success. Skill targets
+are installed but report `target_runtime_unverifiable`.
+
 ## Recipe Router
 
 Use these recipe files when the task is more than a one-off lookup. Read only
@@ -63,22 +70,22 @@ Recipe rules:
 
 ## Command Overview
 
-| Category     | Commands                                                                | Description                                                              |
-| ------------ | ----------------------------------------------------------------------- | ------------------------------------------------------------------------ |
-| **Search**   | `search`, `vsearch`, `query`, `ask`                                     | Find documents by keywords, meaning, or get AI answers                   |
-| **Links**    | `links`, `backlinks`, `similar`, `graph`, `graph query`                 | Navigate document relationships and typed connections                    |
-| **Retrieve** | `get`, `multi-get`, `ls`                                                | Fetch document content by URI or ID                                      |
-| **Index**    | `init`, `collection add/list/remove`, `index`, `update`, `embed`        | Set up and maintain document index                                       |
-| **Tags**     | `tags`, `tags add`, `tags rm`                                           | Organize and filter documents                                            |
-| **Context**  | `context add/list/rm/check/build/verify/watch/watches/reverify/unwatch` | Configure guidance or compile, verify, and watch saved evidence Capsules |
-| **Changes**  | `changes`, `diff`, `impact`                                             | Inspect bounded metadata history and dependency impact                   |
-| **Traces**   | `trace list/show/label/export/replay/delete/purge`                      | Manage and replay private retrieval receipts                             |
-| **Models**   | `models list/use/pull/clear/path`                                       | Manage local AI models                                                   |
-| **Serve**    | `serve`, `daemon`                                                       | One resident Web/headless gateway and watcher                            |
-| **Publish**  | `publish export`                                                        | Export gno.sh publish artifacts                                          |
-| **MCP**      | `mcp`, `mcp install/uninstall/status`                                   | AI assistant integration                                                 |
-| **Skill**    | `skill install/uninstall/show/paths`                                    | Install skill for AI agents                                              |
-| **Admin**    | `status`, `doctor`, `cleanup`, `reset`, `vec`, `completion`             | Maintenance and diagnostics                                              |
+| Category     | Commands                                                                  | Description                                                              |
+| ------------ | ------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| **Search**   | `search`, `vsearch`, `query`, `ask`                                       | Find documents by keywords, meaning, or get AI answers                   |
+| **Links**    | `links`, `backlinks`, `similar`, `graph`, `graph query`                   | Navigate document relationships and typed connections                    |
+| **Retrieve** | `get`, `multi-get`, `ls`                                                  | Fetch document content by URI or ID                                      |
+| **Index**    | `setup`, `init`, `collection add/list/remove`, `index`, `update`, `embed` | Prove first retrieval, then maintain the document index                  |
+| **Tags**     | `tags`, `tags add`, `tags rm`                                             | Organize and filter documents                                            |
+| **Context**  | `context add/list/rm/check/build/verify/watch/watches/reverify/unwatch`   | Configure guidance or compile, verify, and watch saved evidence Capsules |
+| **Changes**  | `changes`, `diff`, `impact`                                               | Inspect bounded metadata history and dependency impact                   |
+| **Traces**   | `trace list/show/label/export/replay/delete/purge`                        | Manage and replay private retrieval receipts                             |
+| **Models**   | `models list/use/pull/clear/path`                                         | Manage local AI models                                                   |
+| **Serve**    | `serve`, `daemon`                                                         | One resident Web/headless gateway and watcher                            |
+| **Publish**  | `publish export`                                                          | Export gno.sh publish artifacts                                          |
+| **MCP**      | `mcp`, `mcp install/uninstall/status`                                     | AI assistant integration                                                 |
+| **Skill**    | `skill install/uninstall/show/paths`                                      | Install skill for AI agents                                              |
+| **Admin**    | `status`, `doctor`, `cleanup`, `reset`, `vec`, `completion`               | Maintenance and diagnostics                                              |
 
 ## Search Modes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",

package/spec/cli.md

@@ -64,6 +64,7 @@ equivalent files fail closed as ambiguous.
 | ------------------ | ------ | ------- | ----- | ---- | ----- | -------- |
 | status             | yes    | no      | no    | yes  | no    | terminal |
 | init               | no     | no      | no    | no   | no    | terminal |
+| setup              | yes    | no      | no    | no   | no    | terminal |
 | collection add     | no     | no      | no    | no   | no    | terminal |
 | collection list    | yes    | no      | no    | yes  | no    | terminal |
 | collection remove  | no     | no      | no    | no   | no    | terminal |
@@ -353,6 +354,96 @@ projected wiki/markdown edges and surface in graph traversal/diagnose metadata.
 
 ---
 
+### gno setup
+
+Add or reuse one folder collection, build its lexical index, and prove a real
+corpus-derived retrieval before reporting success. Semantic indexing is handed
+to one standalone background worker and never delays lexical success.
+
+**Synopsis:**
+
+```bash
+gno setup <folder> [-n|--name <name>] [--exclude <pattern>]...
+  [--authorize-secret-risk] [--connector <id>]...
+  [--no-semantic] [--json]
+```
+
+**Options:**
+
+| Option                    | Type       | Default       | Description                                                                  |
+| ------------------------- | ---------- | ------------- | ---------------------------------------------------------------------------- |
+| `-n, --name <name>`       | string     | dirname       | Requested collection name; exact-root reruns reuse the configured collection |
+| `--exclude <pattern>`     | repeatable | core defaults | One literal exclusion per occurrence; never CSV                              |
+| `--authorize-secret-risk` | boolean    | false         | Explicitly authorize likely credentials, private keys, or env files          |
+| `--connector <id>`        | repeatable | none          | Install or reuse and verify one supported connector after lexical proof      |
+| `--no-semantic`           | boolean    | false         | Prove lexical retrieval but record semantic work as skipped                  |
+| `--json`                  | boolean    | false         | Emit one closed setup result object                                          |
+
+Omitting `--exclude` preserves the core create defaults or the filters already
+configured for an exact-root rerun. An empty occurrence is invalid. Global
+`--yes` accepts safe defaults only; it never authorizes secret risk. Only an
+interactive terminal may ask one default-No question after the lexical core
+returns `secret_risk`. JSON, `--yes`, non-TTY, decline, and EOF fail closed.
+
+The command bootstraps missing config/data/database state without adding the
+folder through `init`, then runs the folder setup transaction. Success requires
+a completed `FolderSetupReceipt@1.0`, `activation.ready=true`, and a non-empty
+exact `activation.evidence.resultUri`. Terminal stage progress uses stderr;
+`--quiet` suppresses progress but not the final result. JSON writes exactly one
+canonical result to stdout on both success and domain failure, with no progress.
+
+After lexical proof, the command records one private atomic
+`setup-semantic@1.0` receipt per canonical index/folder and starts one detached,
+collection-scoped Bun worker. A matching live worker is reused; a dead worker is
+replaced; and a live worker with an older identity remains authoritative until
+it exits so its completion receipt cannot be stranded. A later setup rerun may
+then schedule the new identity. The worker uses the normal model
+download/offline policy, records `completed` only when embedding and vector
+synchronization finish without errors, and exits. Spawn, download, partial
+embedding, and vector-sync failures retain an exact foreground
+`gno ... embed <collection>` remediation and never change proven lexical exit 0.
+Direct setup never contacts a resident, MCP, or Web runtime.
+
+`--connector` is explicit and repeatable; omission performs no connector
+inspection, installation, or verification. Supported IDs are
+`claude-code-skill`, `claude-desktop-mcp`, `cursor-mcp`, `codex-skill`,
+`opencode-skill`, `openclaw-skill`, and `hermes-skill`. Exact duplicates dedupe
+in first-seen order. Unknown IDs fail before setup side effects.
+Any connector-mode JSON invocation emits `setup-activation-result@1.0`.
+Argument or lexical failure uses outer `status: failed`, nests the unchanged
+failed setup result, and keeps `connectors: []`; it retains the original setup
+exit code and performs no connector action.
+
+After proven lexical success and after the lexical store closes, the direct CLI
+opens a new standalone store for connector composition. Missing targets use the
+existing read-only installer; existing entries are reused without overwrite.
+Malformed or unreadable entries are preserved. MCP targets run the shipped
+bounded read-only activation smoke. Skill targets install but return
+`skipped/target_runtime_unverifiable` because they expose no safe runtime hook.
+Connector failures or skips do not roll back lexical success: the command exits
+0 with `completed_with_actions` and bounded per-target remediation. No raw child
+output or client config path is serialized. Reruns delegate passed-receipt reuse
+and recoverable retry to the shipped activation verifier; setup introduces no
+second connector fingerprint or cache.
+
+**Structured schemas:**
+
+- [`setup-command-result@1.0`](./output-schemas/setup-command-result.schema.json)
+- [`setup-activation-result@1.0`](./output-schemas/setup-activation-result.schema.json)
+- [`setup-semantic@1.0`](./output-schemas/setup-semantic-receipt.schema.json)
+- [`FolderSetupReceipt@1.0`](./output-schemas/setup-receipt.schema.json)
+
+**Exit Codes:**
+
+- 0: Lexical setup completed with a real exact result URI; semantic state may
+  be scheduled, running, pending, completed, or skipped; requested connector
+  actions may require bounded follow-up
+- 1: Invalid/safe-input rejection, collection/filter/index disagreement,
+  secret-risk refusal, or declined confirmation
+- 2: Config, receipt, IO, store, indexing, proof, or internal invariant failure
+
+---
+
 ### gno collection add
 
 Add a new collection to the index.