@gmickel/gno 2.12.2 → 2.14.0

package/README.md

@@ -139,7 +139,7 @@ See the [guide](docs/COMPILED-CONTEXT.md).
 
 <!-- public-truth:current-version -->
 
-> Current source version: **v2.12.2**. See [CHANGELOG.md](./CHANGELOG.md).
+> Current source version: **v2.14.0**. See [CHANGELOG.md](./CHANGELOG.md).
 
 <!-- /public-truth -->
 

package/assets/skill/SKILL.md

@@ -84,7 +84,7 @@ Recipe rules:
 | ------------ | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
 | **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                                      |
+| **Retrieve** | `get`, `multi-get`, `ls`, `ls --filter`                                                                    | Fetch document content by URI or ID; list documents by typed metadata    |
 | **Index**    | `setup`, `profile check/show/diff/apply`, `init`, `collection add/list/remove`, `index`, `update`, `embed` | Reproduce profile intent, prove retrieval, then maintain the 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 |
@@ -154,13 +154,15 @@ machines are slower.
 exact identifier/quote/error you already have verbatim → `gno search` (a
 question, or a name or topic taken from it, is not exact text). No good results: run balanced
 `gno query`, then rephrase, then `--thorough`. An expected document still
-missing: `gno query diagnose` before falling back to grep.
+missing: `gno query diagnose` before falling back to grep. When the user
+explicitly asks for a semantic, vector or meaning-only search (their documents
+use different wording), use `gno vsearch` instead.
 
 ## Common Flags (search/vsearch/query/ask)
 
 ```
 -n <num>              Max results (default: 5)
--c, --collection      Filter to collection
+-c, --collection      Filter to collection (repeat for several; search/vsearch/query)
 --tags-any <t1,t2>    Has ANY of these tags
 --tags-all <t1,t2>    Has ALL of these tags
 --since <date>        Modified after date (ISO: 2026-03-01)
@@ -345,7 +347,10 @@ confirmation and invalidates active sessions, streams, and queued work.
 
 Bearer authentication, MCP write enablement, and collection policy are
 independent gates. `EGRESS_DENIED` is not permission to retry through another
-surface. Audit output is local and content-free via
+surface. The one exception is reason `COLLECTION_LIMIT_EXCEEDED`: the call
+covered more than 64 collections (128 for lineage), so retry it scoped to the
+collections the task needs (`collection`/`collections`, `-c`). It is not an
+outage; never restart, raise a limit or relax policy for it. Audit output is local and content-free via
 `gno egress-audit list|show|status`; deletion/purge must be explicit. A local
 policy change cannot retract data already uploaded—tell the user to remove it
 at the remote service. For gno.sh, supported private links can be revoked or
@@ -371,6 +376,29 @@ never from code spans, code blocks, or non-Markdown files.
 Report `truncation.snapshotTruncated` as "totals cover the bounded snapshot,
 not the whole index".
 
+A collection can opt into three report-only link rules with an `audit` block in
+its config: `linkCollections` (other collections it may link to; its own is
+always allowed), `externalUrls: report`, and `paths` (globs every document path
+must match). Their findings are `warning`s: `links.collection-policy`,
+`links.external-url` and `links.path-layout`. Report them as structure and
+publishing hygiene, not access control: `links.external-url` only reports a
+URL written in a note; it sends and blocks nothing, so the remedy is editing
+the note or setting `externalUrls: ignore`, never a collection policy change.
+Show which URLs were found with
+`gno audit links --json | jq -r '.findings[] | select(.ruleId == "links.external-url") | "\(.subject) \(.location) \(.evidence[0].summary)"'`.
+Never add an `audit` block on your own initiative. When the user asks for a
+rule, there is no CLI flag: always write out the exact `audit` block for that
+collection's entry in the config file, then run the check. For "published may
+link only to reference":
+
+```bash
+gno doctor   # prints "Config loaded: <path>"
+# In <path>, under the `published` collection entry, add:
+#   audit:
+#     linkCollections: [reference]
+gno audit links -c published --json
+```
+
 Treat exit `4` as a complete report with findings. Exit `5` or report status
 `partial`/`changed_during_audit` means evidence is unavailable, inconclusive,
 cancelled, truncated, or repeatedly changed—never healthy. Preserve stable
@@ -753,7 +781,10 @@ fields must be indexed from nested YAML `gno.metadata`; arbitrary frontmatter
 keys are not automatically custom fields. Run `gno metadata --collection <c>`
 (MCP `gno_list_metadata`) first to see which keys, types and values exist.
 CLI retrieval accepts `--filter` JSON; MCP/SDK/REST accept the same `filter`
-object:
+object. To enumerate documents by metadata with no search term (every
+`status: draft` note), use `gno ls [<collection>] --filter '<json>'`, not a
+search with a placeholder query; `--json` returns `{documents, meta}`, so read
+`.documents[]` and `meta.total`:
 
 ```json
 {

package/assets/skill/cli-reference.md

@@ -151,6 +151,19 @@ gno index [options]
 | `--models-pull`       | Download models if missing |
 | `--git-pull`          | Git pull before indexing   |
 
+### gno convert
+
+Print the Markdown GNO would index for one file. Needs no config or index and
+writes nothing.
+
+```bash
+gno convert <file> [--json]
+```
+
+`--json` adds `title`, `converter`, `mirrorHash` and `warnings`. Mail archives,
+calendars and other multi-record formats are refused (`MULTI_DOCUMENT`); index
+them in a collection instead.
+
 ### gno embed
 
 Generate embeddings only.
@@ -393,16 +406,16 @@ BM25 keyword search.
 gno search <query> [options]
 ```
 
-| Option             | Default | Description                      |
-| ------------------ | ------- | -------------------------------- |
-| `-n`               | 5       | Max results                      |
-| `--min-score`      | 0       | Minimum score (0-1)              |
-| `-c, --collection` | all     | Filter to collection             |
-| `--tags-any`       | -       | Filter: has ANY tag (comma-sep)  |
-| `--tags-all`       | -       | Filter: has ALL tags (comma-sep) |
-| `--full`           | false   | Full content (not snippets)      |
-| `--line-numbers`   | false   | Include line numbers             |
-| `--lang`           | auto    | Language filter                  |
+| Option             | Default | Description                                            |
+| ------------------ | ------- | ------------------------------------------------------ |
+| `-n`               | 5       | Max results                                            |
+| `--min-score`      | 0       | Minimum score (0-1)                                    |
+| `-c, --collection` | all     | Filter to collection; repeat (`-c a -c b`) for several |
+| `--tags-any`       | -       | Filter: has ANY tag (comma-sep)                        |
+| `--tags-all`       | -       | Filter: has ALL tags (comma-sep)                       |
+| `--full`           | false   | Full content (not snippets)                            |
+| `--line-numbers`   | false   | Include line numbers                                   |
+| `--lang`           | auto    | Language filter                                        |
 
 Output formats: `--json`, `--files`, `--csv`, `--md`, `--xml`
 
@@ -497,9 +510,14 @@ gno multi-get <pattern> [--max-bytes <n>] [--line-numbers]
 List documents.
 
 ```bash
-gno ls [<scope>] [--json|--files|--md]
+gno ls [<scope>] [--filter <json>] [-n <num>] [--offset <num>] [--json|--files|--md]
 ```
 
+- `<scope>`: collection name or `gno://collection/prefix`
+- `--filter <json>`: list only documents whose typed metadata (`gno.metadata`) matches; same predicate syntax and semantics as `gno search --filter`. Applies before pagination
+- `--json` returns `{documents: [{docid, uri, title, source}], meta: {total, returned, offset}}`; `meta.total` counts all matches
+- With `--filter`, `meta.warnings` (`METADATA_COVERAGE_INCOMPLETE`) appears when documents with invalid or pending metadata were skipped; other formats print it on stderr
+
 ## Context Management
 
 ### gno context add
@@ -640,6 +658,9 @@ gno egress-audit purge
 Denied egress is terminal for that route; do not retry through another network
 surface. Relaxing policy requires the current revision; tightening to
 `local_only` does not. Audit receipts are local and content-free.
+`COLLECTION_LIMIT_EXCEEDED` is the one denial to retry: the request covered more
+than 64 collections (128 for lineage), so name only the collections it needs
+(`-c <name>`).
 Deletion/purge must remain explicit.
 
 ## Note Linking
@@ -836,6 +857,36 @@ gno models path [--json]
 
 ## Maintenance
 
+### gno audit
+
+Read-only workspace integrity report. Exit 4 = complete with findings, 5 =
+partial/inconclusive.
+
+```bash
+gno audit [links|provenance|freshness|all] [-c <collection>] [--json]
+gno audit links -c published --json
+```
+
+Opt-in, report-only collection rules come from an `audit` block on a
+collection in the config file (`gno doctor` shows its path); there are no CLI
+flags for them:
+
+```yaml
+collections:
+  - name: published
+    path: ~/notes/published
+    audit:
+      linkCollections: [reference] # other collections it may link to
+      externalUrls: report # report | ignore (default ignore)
+      paths: ["20??/**/*.md"] # globs every document path must match
+```
+
+| Rule id                   | Reports                                                                                                                    |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `links.collection-policy` | A link into a collection `linkCollections` does not list                                                                   |
+| `links.external-url`      | A URL written in a document (outside frontmatter, code, comments), or `unchecked` when the text is unavailable. Not egress |
+| `links.path-layout`       | A document whose path matches none of the `paths` globs                                                                    |
+
 ### gno peek
 
 Cheap counts, backlog, recent files, and serve liveness. Same `peek@1.0`

package/assets/skill/examples.md

@@ -183,6 +183,17 @@ gno ls work
 gno ls --json
 ```
 
+### List by metadata
+
+```bash
+# Every draft note in work (no search term needed)
+gno ls work --filter '{"op":"eq","key":"status","value":"draft"}'
+
+# URIs of every note whose project list contains atlas
+gno ls work --filter '{"op":"in","key":"project","values":["atlas"]}' -n 1000 --json \
+  | jq -r '.documents[].uri'
+```
+
 ## Search & Retrieve Full Content
 
 ### Pipeline: Search then get
@@ -204,10 +215,10 @@ gno search "error handling" --json | jq -r '.results[].uri' | xargs gno multi-ge
 
 ```bash
 # Get URIs of matches
-gno search "api endpoint" --json | jq '.[] | .uri'
+gno search "api endpoint" --json | jq '.results[] | .uri'
 
 # Get snippets
-gno search "config" --json | jq '.[] | {uri, snippet}'
+gno search "config" --json | jq '.results[] | {uri, snippet}'
 ```
 
 ### Check index health
@@ -224,10 +235,10 @@ gno doctor --json
 
 ```bash
 # Export all document IDs
-gno ls --json | jq -r '.[].docid' > doc-ids.txt
+gno ls --json -n 10000 | jq -r '.documents[].docid' > doc-ids.txt
 
 # Search and process results
-gno search "error" --json | jq -r '.[] | .uri' | while read uri; do
+gno search "error" --json | jq -r '.results[] | .uri' | while read uri; do
   echo "Processing: $uri"
   gno get "$uri" > "output/$(basename $uri)"
 done
@@ -235,6 +246,21 @@ done
 
 ## Maintenance
 
+### Check a published collection's links
+
+Let `published` link only to itself and `reference`: add this to the
+`published` collection in the config file (`gno doctor` shows its path).
+
+```yaml
+audit:
+  linkCollections: [reference]
+```
+
+```bash
+gno audit links -c published --json \
+  | jq -r '.findings[] | select(.ruleId == "links.collection-policy") | "\(.subject) \(.location): \(.message)"'
+```
+
 ### Update index after changes
 
 ```bash

package/assets/skill/mcp-reference.md

@@ -93,6 +93,14 @@ gno serve --status --json
 gno daemon --status --json
 ```
 
+Each HTTP request is checked against the egress policy of the collections it
+covers: the ones it names, or every configured collection when it names none.
+One check covers at most 64 collections (128 for a policy lineage; 64 names for
+`gno_egress_check`). A 403 whose reason is `COLLECTION_LIMIT_EXCEEDED` means the
+call covered too many collections: retry with `collection` or `collections` set
+to just the ones the task needs. It is not an outage, so do not restart the
+server, raise a limit, change policy, or retry through another surface.
+
 ## Retrieval Order
 
 `gno mcp --tool-profile core` (or `gateway.toolProfile: core` for the resident
@@ -114,6 +122,8 @@ abstains unless every substantive claim is supported. This is a support
 classification against the retained Capsule, not a guarantee that the corpus
 is complete or its sources are true. Bounded graph expansion is on by default;
 set `graph: false` or `noGraph: true` only for an explicit BM25/vector-only path.
+To search several collections, pass `collections: ["a", "b"]` to `gno_query`,
+`gno_search` or `gno_vsearch` instead of `collection` (not both).
 Check `gno_peek` first for counts, backlog, serve liveness, or recent files.
 Use `gno_status` for activation, onboarding, or heavy health (missing vectors,
 stale embeddings). Use `gno_query_diagnose` when a known target document
@@ -251,6 +261,12 @@ before calling.
   `not_found`, so do not blindly resend an uncertain old write as new.
 - Errors arrive as tool text `CODE: message` with `structuredContent.error`.
 
+## Audits
+
+`gno_audit` returns the same report as `gno audit`. Collection `audit` config
+adds `links.collection-policy`, `links.external-url` and `links.path-layout`
+findings with no new tool inputs; they report structure, not egress.
+
 ## Uninstall
 
 ```bash

package/browser-extension/artifacts/gno-browser-clipper-v2.14.0.zip.sha256

@@ -0,0 +1 @@
+aca4d00878cb85d4f57181425caf0bb2175ecec0a5bc4ea437e994b8fd42c9cc  gno-browser-clipper-v2.14.0.zip

package/browser-extension/dist/manifest.json

@@ -21,5 +21,5 @@
   "content_security_policy": {
     "extension_pages": "script-src 'self'; object-src 'none'; connect-src http://127.0.0.1:*"
   },
-  "version": "2.12.2"
+  "version": "2.14.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "2.12.2",
+  "version": "2.14.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

@@ -91,6 +91,7 @@ equivalent files fail closed as ambiguous.
 | sessions           | yes    | no      | no    | no   | no    | terminal |
 | get                | yes    | no      | no    | yes  | no    | terminal |
 | multi-get          | yes    | yes     | no    | yes  | no    | terminal |
+| convert            | yes    | no      | no    | no   | no    | Markdown |
 | ls                 | yes    | yes     | no    | yes  | no    | terminal |
 | daemon             | yes¹   | no      | no    | no   | no    | terminal |
 | context add        | no     | no      | no    | no   | no    | terminal |
@@ -190,7 +191,11 @@ through a resumable operation. It can initialize a missing user config. Omitted
 collection-scoped contexts, and content-type rules remain untouched; stale
 same-path collections are reported as skipped and retained. A stale same-name
 collection root is repaired in place without deleting its collection or index
-identity. Apply also updates a timestamp-free `projectProfileBindings` record
+identity. A re-applied collection keeps every setting the profile does not
+own (for example `egressPolicy`, `egressPolicyRevision`, `sourceAvailability`,
+`workspaceRoot`, `memoryManaged`, `audit` and `updateCmd`). When a repaired root
+falls outside an explicit `workspaceRoot`, apply fails with
+`WORKSPACE_ROOT_CONFLICT` (exit 1) before any config write. Apply also updates a timestamp-free `projectProfileBindings` record
 in the local user config with the canonical absolute profile path, profile
 fingerprint, and projected collection. The public `profile_binding` resource
 receipt identifies only the collection and never exposes that local path.
@@ -892,6 +897,12 @@ List all configured collections.
 gno collection list [--json|--md]
 ```
 
+Each JSON item is the configured collection plus `effectiveWorkspaceRoot` and
+`workspaceSource`. A collection with an `audit` block lists it unchanged
+(`linkCollections`, `externalUrls`, `paths`); see
+[gno audit](#gno-audit). Schema:
+[`collection-list@1.0`](./output-schemas/collection-list.schema.json).
+
 ---
 
 ### gno collection clear-embeddings
@@ -1045,6 +1056,32 @@ target missing from the listing stays unresolved; an unreadable folder or the
 file bound makes the listing incomplete, which the `links.outside-index` rule
 message states once.
 
+**Opt-in collection rules.** A collection's optional `audit` config object
+adds three report-only `links` rules. Each is emitted only when an audited
+collection (the `--collection` filter, else every collection) configures it,
+so without `audit` the rule list, findings, fingerprints and exit codes are
+unchanged. The config fingerprint includes a collection's `audit` object only
+when present on an audited collection.
+
+| Rule id                   | Enabled by                   | Reports                                                                                              |
+| ------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `links.collection-policy` | `audit.linkCollections`      | A link that resolves into a collection the list does not name                                        |
+| `links.external-url`      | `audit.externalUrls: report` | An external URL written in a document, or a document whose indexed text is unavailable (`unchecked`) |
+| `links.path-layout`       | `audit.paths`                | A document whose collection-relative path matches none of the globs                                  |
+
+Findings are `warning`s with location evidence: `collection-policy` (detail
+`sourceCollection`, `targetCollection`, `target`, `linkType`, `allowed`) at the
+link's line and column, `external-url` at the URL's line and column (or
+`external-url-unchecked` with no location), and `path-layout` (detail
+`paths`). Only links that resolve to exactly one document are policy findings.
+External URLs are `scheme://` URLs in the document's indexed text outside
+frontmatter, code and HTML comments; `gno://` and `file://` are local. Path
+globs use `pattern` syntax against `recordSourcePath ?? relPath`. A truncated
+snapshot makes all three `inconclusive`. Config validation: `linkCollections`
+members must name configured collections, `externalUrls` is `report` or
+`ignore`, and `paths` is 1-64 relative globs without `..` and with balanced
+`{}` / `[]`.
+
 The wiki link parser reads Obsidian's table-escaped alias `[[Note\|Alias]]`
 as target `Note` with alias `Alias`. Markdown link text may contain balanced
 square brackets (`[see [1]](note.md)`); a destination containing a square
@@ -1245,13 +1282,14 @@ Build or update the index end-to-end (update + embed).
 **Synopsis:**
 
 ```bash
-gno index [collection] [--no-embed] [--models-pull] [--git-pull] [--json] [--yes] [--lock-wait <duration>] [--no-wait]
+gno index [collection] [--path <path...>] [--no-embed] [--models-pull] [--git-pull] [--json] [--yes] [--lock-wait <duration>] [--no-wait]
 ```
 
 **Options:**
 | Option | Type | Description |
 |--------|------|-------------|
 | `--collection` | string | Scope to single collection |
+| `--path <path...>` | string[] | Reindex only these files of the collection (relative to its root, or absolute inside it); at most 256, not directories; requires a collection, not combinable with `--git-pull` |
 | `--no-embed` | boolean | Run ingestion only, skip embedding |
 | `--models-pull` | boolean | Download models if missing (prompts unless `--yes`) |
 | `--git-pull` | boolean | Run `git pull` in git repositories |
@@ -1264,6 +1302,7 @@ gno index [collection] [--no-embed] [--models-pull] [--git-pull] [--json] [--yes
 
 - Runs two separable stages: `lexical` (`update`) then `embed`
 - With `--no-embed`, runs the `lexical` stage only (embed stage `skipped`)
+- With `--path`, the `lexical` stage re-reads only the listed files and marks a listed file that no longer exists inactive; the collection's update command does not run. A path outside the collection root (including through a symlink), `--path` without a collection, or `--path` with `--git-pull` exits 1 (`VALIDATION`) before anything is written
 - Waits by default for the shared write lease; `--no-wait` fails immediately with exit 4
 
 **Staged, resumable contract:** each stage persists its own progress inside
@@ -1472,7 +1511,7 @@ BM25 keyword search over indexed documents.
 **Synopsis:**
 
 ```bash
-gno search [query] [--query-file <path>] [-n <num>] [--min-score <num>] [-c <collection>] [--since <date>] [--until <date>] [--category <values>] [--author <text>] [--intent <text>] [--exclude <values>] [--tags-all <tags>] [--tags-any <tags>] [--full] [--line-numbers] [--lang <bcp47>] [--json|--files|--csv|--md|--xml]
+gno search [query] [--query-file <path>] [-n <num>] [--min-score <num>] [-c <collection>]... [--since <date>] [--until <date>] [--category <values>] [--author <text>] [--intent <text>] [--exclude <values>] [--tags-all <tags>] [--tags-any <tags>] [--full] [--line-numbers] [--lang <bcp47>] [--json|--files|--csv|--md|--xml]
 ```
 
 **Arguments:**
@@ -1488,7 +1527,7 @@ gno search [query] [--query-file <path>] [-n <num>] [--min-score <num>] [-c <col
 | `--query-file`          | string   | none                      | Read the query from a file; `-` reads stdin so the query never appears on argv. Do not also pass a positional query. |
 | `-n`                    | integer  | 5 (20 for --json/--files) | Max results                                                                                                          |
 | `--min-score`           | number   | 0                         | Minimum score threshold                                                                                              |
-| `-c, --collection`      | string   | all                       | Filter to collection                                                                                                 |
+| `-c, --collection`      | string[] | all                       | Filter to collection; repeat to search several collections (at most 256)                                             |
 | `--since`               | string   | none                      | Modified-at lower bound (ISO date/time or relative token)                                                            |
 | `--until`               | string   | none                      | Modified-at upper bound (ISO date/time or relative token)                                                            |
 | `--category`            | string   | none                      | Filter to docs with matching category/content type (comma-separated)                                                 |
@@ -1621,6 +1660,19 @@ gno search "deploy staging" -n 10 --collection work
 gno search "contract" --json | jq '.[] | .uri'
 ```
 
+**Collection scope (`search`, `vsearch`, `query`):** one `-c` filters to that
+collection. Repeating `-c` (`-c work -c notes`) searches only those
+collections; the filter applies before every candidate limit, so other
+collections never take result slots, graph neighbours or rerank budget. Names
+are trimmed, lowercased, de-duplicated and sorted, and `--json` echoes them as
+`meta.collections` (`meta.collection` stays the single-collection field). More
+than 256 names after normalization exits 1 (`VALIDATION`); names that are not
+configured exit 2 with `Collection not found: <name>` or
+`Collections not found: <a>, <b>`, the same as a single unknown `-c`. When the
+listed collections resolve different embed, expand or rerank models, that role
+uses the unscoped default; when they agree, their shared model is used.
+`gno query diagnose` accepts one `-c` and exits 1 when given several.
+
 ---
 
 Keyword retrieval applies collection/path scope, caller allowlists, tags, modified-date bounds, category and author filters, managed-memory visibility, and whole-document exclusions before its ranked candidate limit. Higher-ranked ineligible documents cannot consume that window; fewer eligible matches still produce a short result. Existing BM25 weights, query syntax, recency/project-affinity reranking and minimum-score behavior are unchanged.
@@ -1632,7 +1684,7 @@ Vector semantic search over indexed documents.
 **Synopsis:**
 
 ```bash
-gno vsearch <query> [-n <num>] [--min-score <num>] [-c <collection>] [--since <date>] [--until <date>] [--category <values>] [--author <text>] [--intent <text>] [--exclude <values>] [--tags-all <tags>] [--tags-any <tags>] [--full] [--line-numbers] [--lang <bcp47>] [--json|--files|--csv|--md|--xml]
+gno vsearch <query> [-n <num>] [--min-score <num>] [-c <collection>]... [--since <date>] [--until <date>] [--category <values>] [--author <text>] [--intent <text>] [--exclude <values>] [--tags-all <tags>] [--tags-any <tags>] [--full] [--line-numbers] [--lang <bcp47>] [--json|--files|--csv|--md|--xml]
 ```
 
 **Options:** Same as `gno search` (including temporal/category/author, tag, and
@@ -1677,7 +1729,7 @@ Hybrid search combining BM25 and vector retrieval with optional expansion and re
 **Synopsis:**
 
 ```bash
-gno query [query...] [--query-file <path>] [-n <num>] [--min-score <num>] [-c <collection>] [--since <date>] [--until <date>] [--category <values>] [--author <text>] [--intent <text>] [--exclude <values>] [-C <num>] [--tags-all <tags>] [--tags-any <tags>] [--full] [--line-numbers] [--lang <bcp47>] [--no-expand] [--no-rerank] [--graph] [--no-graph] [--query-mode <mode:text>]... [--explain] [--json|--files|--csv|--md|--xml]
+gno query [query...] [--query-file <path>] [-n <num>] [--min-score <num>] [-c <collection>]... [--since <date>] [--until <date>] [--category <values>] [--author <text>] [--intent <text>] [--exclude <values>] [-C <num>] [--tags-all <tags>] [--tags-any <tags>] [--full] [--line-numbers] [--lang <bcp47>] [--no-expand] [--no-rerank] [--graph] [--no-graph] [--query-mode <mode:text>]... [--explain] [--json|--files|--csv|--md|--xml]
 gno query diagnose <query> --target <doc> [-n <num>] [--min-score <num>] [-c <collection>] [--since <date>] [--until <date>] [--category <values>] [--author <text>] [--intent <text>] [--exclude <values>] [-C <num>] [--tags-all <tags>] [--tags-any <tags>] [--lang <bcp47>] [--no-expand] [--no-rerank] [--graph] [--no-graph] [--json]
 ```
 
@@ -2496,6 +2548,51 @@ See [Output Schemas](./output-schemas/multi-get.schema.json)
 
 ---
 
+### gno convert
+
+Print the Markdown GNO would index for one file. The file goes through the
+same conversion path as indexing (MIME detection, converter, canonical
+Markdown, mirror hash) with the default indexing limits, so the output equals
+the mirror `gno update` stores for the same bytes. No config, index, store or
+cache is read or written, and the command works with no GNO config present.
+
+**Synopsis:**
+
+```bash
+gno convert <file> [--json]
+```
+
+**Arguments:**
+| Arg | Type | Description |
+|-----|------|-------------|
+| `<file>` | path | One regular file (a symlink to a regular file is followed) |
+
+**Output:**
+
+- Terminal: exactly the Markdown on stdout; conversion warnings go to stderr.
+- `--json`: [convert@1.0](./output-schemas/convert.schema.json) with `source`
+  (`path`, `mime`, `ext`, `sizeBytes`), `converter` (`id`, `version`),
+  `title`, `languageHint`, `markdown`, `mirrorHash` (SHA-256 hex, as stored by
+  indexing) and `warnings`.
+
+Single-document formats are supported. Formats whose adapters split one file
+into several records (mail archives, calendars and the other record adapters)
+are refused, because their record identity comes from the collection and path.
+
+**Errors:** the standard error envelope, with `details.reason`:
+
+| Case                                                         | `details.reason`                                               | Exit |
+| ------------------------------------------------------------ | -------------------------------------------------------------- | ---- |
+| Path missing, a directory or another non-regular file        | `NOT_FOUND`                                                    | 1    |
+| Larger than the indexing size limit (checked before reading) | `TOO_LARGE`                                                    | 1    |
+| No converter for the type                                    | `UNSUPPORTED`                                                  | 1    |
+| Multi-record format (`details.format` names it)              | `MULTI_DOCUMENT`                                               | 1    |
+| Converter failure, timeout, memory limit or corrupt input    | the converter's code (`CORRUPT`, `PERMISSION`, `TIMEOUT`, ...) | 2    |
+
+The SDK exposes the same operation as `convertFile(path)`.
+
+---
+
 ### gno ls
 
 List documents in a collection or prefix.
@@ -2503,7 +2600,7 @@ List documents in a collection or prefix.
 **Synopsis:**
 
 ```bash
-gno ls [<scope>] [--json|--files|--md]
+gno ls [<scope>] [--filter <json>] [-n <num>] [--offset <num>] [--json|--files|--md]
 ```
 
 **Arguments:**
@@ -2511,23 +2608,49 @@ gno ls [<scope>] [--json|--files|--md]
 |-----|------|-------------|
 | `<scope>` | string | Collection name or `gno://collection/prefix` (default: all) |
 
-**Output (JSON):**
+**Options:**
+| Flag | Type | Description |
+|------|------|-------------|
+| `--filter` | JSON | Typed metadata predicate; same schema and semantics as `gno search --filter` |
+| `-n, --limit` | integer | Max documents (default 20) |
+| `--offset` | integer | Skip the first N documents |
+
+Active documents are listed in URI order. With `--filter`, only documents whose
+typed metadata satisfies the predicate are listed; documents with invalid or
+not-yet-extracted metadata never match, including under negated predicates.
+The filter and the scope both apply, before pagination: `limit`, `offset` and
+`meta.total` count matching documents only. Without `--filter`, output is
+unchanged.
+
+**Output (JSON):** [`ls@1.0`](output-schemas/ls.schema.json)
 
 ```json
-[
-  {
-    "docid": "#a1b2c3d4",
-    "uri": "gno://work/doc.md",
-    "title": "Document Title",
-    "source": { "relPath": "doc.md", "mime": "text/markdown", "ext": ".md" }
+{
+  "documents": [
+    {
+      "docid": "#a1b2c3d4",
+      "uri": "gno://work/doc.md",
+      "title": "Document Title",
+      "source": { "relPath": "doc.md", "mime": "text/markdown", "ext": ".md" }
+    }
+  ],
+  "meta": {
+    "total": 12,
+    "returned": 1,
+    "offset": 0,
+    "warnings": [{ "code": "METADATA_COVERAGE_INCOMPLETE", "message": "..." }]
   }
-]
+}
 ```
 
+`meta.warnings` appears only with `--filter` when documents in scope were
+skipped because their metadata is invalid or pending re-ingestion. Terminal,
+`--files` and `--md` output print the warning on stderr.
+
 **Exit Codes:**
 
 - 0: Success
-- 1: Invalid scope
+- 1: Invalid scope or invalid `--filter` (`VALIDATION`, same message as `gno search --filter`)
 - 2: DB failure
 
 ---