@gmickel/gno 2.13.0 → 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.13.0**. 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,7 +154,9 @@ 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)
 
@@ -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

@@ -510,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
@@ -653,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
@@ -849,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
@@ -253,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.13.0"
+  "version": "2.14.0"
 }

package/package.json

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

@@ -191,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.
@@ -893,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
@@ -1046,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
@@ -2564,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:**
@@ -2572,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
 
 ---

package/spec/mcp.md

@@ -338,6 +338,13 @@ compatible collection policy. Policy denial returns HTTP 403 with stable
 `EGRESS_DENIED` data and a redacted evaluator audit. Write authorization remains
 an independent additional requirement.
 
+The check covers the request's collection scope: the collections it names, or
+every configured collection when it names none. One decision covers at most 64
+collections and one policy lineage at most 128. A scope over either bound is
+denied with reason `COLLECTION_LIMIT_EXCEEDED` through the same 403 response,
+whose audit names no collection; it is never an internal error. A request that
+names a few collections is evaluated normally however many are configured.
+
 The MCP tool and resource registry is paired with a callsite-level
 network-boundary inventory. A TypeScript AST scan covers shipped TS, TSX, JS,
 and JSX and recognizes direct, qualified, bracketed, imported, and aliased
@@ -411,7 +418,10 @@ Rules report `pass`, `fail`, `skip`, `unavailable`, or `inconclusive`; reports
 are `complete`, `partial`, `changed_during_audit`, or `failed`. A passing rule
 may carry `info` findings (`links.outside-index`: link targets that exist as
 files in the link workspace but are not indexed); only `warning` and `error`
-findings fail a rule. Link semantics match `gno audit` (spec/cli.md). Unavailable or
+findings fail a rule. Link semantics match `gno audit` (spec/cli.md),
+including the opt-in `links.collection-policy`, `links.external-url` and
+`links.path-layout` rules read from collection `audit` config; they add no
+tool inputs. Unavailable or
 changing evidence never appears healthy. Stable finding IDs are derived from
 rule, normalized subject/location, and evidence fingerprint. Responses are
 canonically ordered and bounded while retaining exact pre-truncation totals.
@@ -3386,7 +3396,10 @@ Read tools:
   caller authentication/authorization, content class, and partial mode. It
   performs no action and returns the canonical decision/explanation contract.
   An explicit scope is a non-empty, duplicate-free list of at most 64 canonical
-  collection names; omitted scope means all configured collections.
+  collection names; omitted scope means all configured collections. Omitted
+  scope with more than 64 configured collections returns a denied decision
+  with reason `COLLECTION_LIMIT_EXCEEDED`; with more than 128 it returns a
+  `VALIDATION` error asking for named collections.
 - `gno_egress_audit_list`, `gno_egress_audit_show`, and
   `gno_egress_audit_status` expose only content-free local receipts.
 

package/spec/output-schemas/collection-list.schema.json

@@ -57,6 +57,34 @@
         "type": "string",
         "enum": ["none", "detected", "configured", "disabled", "unavailable"],
         "description": "CLI list only: how the link workspace was set"
+      },
+      "audit": {
+        "type": "object",
+        "description": "Opt-in report-only link and path rules for gno audit links. Absent when not configured.",
+        "additionalProperties": false,
+        "properties": {
+          "linkCollections": {
+            "type": "array",
+            "description": "Other collections this one may link to; its own is always allowed",
+            "maxItems": 256,
+            "items": {
+              "type": "string",
+              "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$"
+            }
+          },
+          "externalUrls": {
+            "type": "string",
+            "enum": ["report", "ignore"],
+            "description": "report lists external URLs written in documents"
+          },
+          "paths": {
+            "type": "array",
+            "description": "Relative globs; each document path must match at least one",
+            "minItems": 1,
+            "maxItems": 64,
+            "items": { "type": "string", "maxLength": 1024 }
+          }
+        }
       }
     }
   }

package/spec/output-schemas/ls.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/ls@1.0",
+  "title": "GNO Document Listing",
+  "description": "Output of gno ls --json and SDK list(): one page of active documents in URI order",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["documents", "meta"],
+  "properties": {
+    "documents": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["docid", "uri", "source"],
+        "properties": {
+          "docid": { "type": "string", "pattern": "^#[a-f0-9]+$" },
+          "uri": { "type": "string", "pattern": "^gno://" },
+          "title": { "type": "string" },
+          "source": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["relPath", "mime", "ext"],
+            "properties": {
+              "relPath": { "type": "string" },
+              "mime": { "type": "string" },
+              "ext": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "meta": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["total", "returned", "offset"],
+      "properties": {
+        "total": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Documents in scope that match the filter, before pagination"
+        },
+        "returned": { "type": "integer", "minimum": 0 },
+        "offset": { "type": "integer", "minimum": 0 },
+        "warnings": {
+          "type": "array",
+          "description": "Present only with a typed metadata filter when some documents could not be judged",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["code", "message"],
+            "properties": {
+              "code": {
+                "type": "string",
+                "enum": ["METADATA_COVERAGE_INCOMPLETE"]
+              },
+              "message": { "type": "string" }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/src/cli/commands/ls.ts

@@ -5,9 +5,14 @@
  * @module src/cli/commands/ls
  */
 
+import type { MetadataPredicate } from "../../core/typed-metadata";
 import type { DocumentRow, StorePort, StoreResult } from "../../store/types";
 
 import { decorateUriForIndex } from "../../app/constants";
+import {
+  filterDocumentsByMetadata,
+  metadataCoverageWarnings,
+} from "../../pipeline/filters";
 import { initStore } from "./shared";
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -23,6 +28,8 @@ export interface LsCommandOptions {
   limit?: number;
   /** Skip first N results */
   offset?: number;
+  /** Typed metadata predicate (same semantics as search --filter) */
+  filter?: MetadataPredicate;
   /** JSON output */
   json?: boolean;
   /** File protocol output */
@@ -48,6 +55,8 @@ export interface LsResponse {
     total: number;
     returned: number;
     offset: number;
+    /** Only with a filter, when documents could not be judged. */
+    warnings?: { code: string; message: string }[];
   };
 }
 
@@ -128,9 +137,16 @@ export async function ls(
       return { success: false, error: docs.error.message };
     }
 
-    // Filter active only, sort by URI
-    const allActive = docs.value
-      .filter((d) => d.active)
+    const active = docs.value.filter((d) => d.active);
+    const filtered = options.filter
+      ? filterDocumentsByMetadata(active, options.filter)
+      : undefined;
+    const warnings = filtered
+      ? metadataCoverageWarnings(filtered, "listing")
+      : undefined;
+
+    // Sort by URI
+    const allActive = (filtered?.matches ?? active)
       .map((d) => ({
         docid: d.docid,
         uri: d.uri,
@@ -160,6 +176,7 @@ export async function ls(
           total: allActive.length,
           returned: paged.length,
           offset,
+          ...(warnings ? { warnings } : {}),
         },
       },
     };

package/src/cli/commands/profile-apply.ts

@@ -267,7 +267,8 @@ export async function runProjectProfileApplyCommand(
       ];
       const validationFailure =
         applied.error.code === "PROFILE_INVALID" ||
-        applied.error.code === "RUNTIME_PATH_OVERLAP";
+        applied.error.code === "RUNTIME_PATH_OVERLAP" ||
+        applied.error.code === "WORKSPACE_ROOT_CONFLICT";
       return {
         result: failedApplyResult(
           validationFailure ? "invalid" : "failed",

package/src/cli/program.ts

@@ -2625,6 +2625,7 @@ function wireRetrievalCommands(program: Command): void {
       "Skip first N results",
       parsePositiveInt.bind(null, "offset")
     )
+    .option("--filter <json>", "typed custom metadata predicate (JSON)")
     .option("--json", "JSON output")
     .option("--files", "File protocol output")
     .option("--md", "Markdown output")
@@ -2633,6 +2634,7 @@ function wireRetrievalCommands(program: Command): void {
         const format = getFormat(cmdOpts);
         assertFormatSupported(CMD.ls, format);
         const globals = getGlobals();
+        const filter = parseCliMetadataFilter(cmdOpts.filter);
 
         const { ls, formatLs } = await import("./commands/ls");
         const result = await ls(scope, {
@@ -2640,6 +2642,7 @@ function wireRetrievalCommands(program: Command): void {
           indexName: globals.index,
           limit: cmdOpts.limit as number | undefined,
           offset: cmdOpts.offset as number | undefined,
+          filter,
           json: format === "json",
           files: format === "files",
           md: format === "md",
@@ -2652,6 +2655,14 @@ function wireRetrievalCommands(program: Command): void {
           );
         }
 
+        // JSON carries warnings in meta; other formats keep stdout clean.
+        if (format !== "json") {
+          for (const warning of result.data.meta.warnings ?? []) {
+            process.stderr.write(
+              `Warning: ${warning.code}: ${warning.message}\n`
+            );
+          }
+        }
         const output = formatLs(result, {
           json: format === "json",
           files: format === "files",