QUERY FLAGS (rank the results; compose via AND with the filter flags):

  --fuzzy QUERY               Subsequence match on title and key (typo/partial tolerant).
  --lexical QUERY             BM25 full-text match on title and body (stemmed exact tokens).
  QUERY (positional)          DEPRECATED alias for --fuzzy; prints a warning.
  Setting both --fuzzy and --lexical fuses the two with Reciprocal Rank Fusion.
  Queries are bag-of-words (word order ignored, no quoted-phrase matching).

FILTER FLAGS (compose via AND with the query):

  --filter "EXPR"             Inline filter expression (YAML).
                              Example: --filter 'status: draft'
  -k, --key KEY               $key match. Repeatable: 1 key uses $eq, 2+ uses $in.
  --includes KEY[:DEPTH]      $includes anchor. DEPTH defaults to --max-depth.
  --included-by KEY[:DEPTH]   $includedBy anchor. DEPTH defaults to --max-depth.
  --references KEY[:DIST]     $references anchor. DIST defaults to --max-distance.
  --referenced-by KEY[:DIST]  $referencedBy anchor. DIST defaults to --max-distance.
  --max-depth N               Default maxDepth for inclusion anchors without :DEPTH. Default 1.
  --max-distance N            Default maxDistance for reference anchors without :DIST. Default 1.

SHAPE FLAGS:

  --project SPEC              Projection (replaces defaults). Accepts: comma-list
                              (name, name=path, name=$selector, $selector) or YAML mapping.
  --add-fields SPEC           Additive projection (extends defaults). Same grammar as
                              --project. Mutually exclusive with --project.
  --sort field:1|-1           Sort by frontmatter field (1=asc, -1=desc).
  -l, --limit N               Cap results (0 = unlimited).

LIMITS (bound output for context-limited callers; off by default):

  --max-tokens N              Cap total projected `$content` tokens across all results.
                              Rows are dropped whole once the budget is reached.
  --max-document-tokens N          Cap projected `$content` tokens per result, head-truncating
                              with a "⋯ truncated (N tokens omitted)" marker.
  0 = unlimited. Token budgets only act when `$content` is projected; a metadata index
  carries no content tokens, so use --limit to bound it. A truncation warning is printed
  to stderr when output is clipped.

OUTPUT FORMATS:

  -f markdown (default)       Compact index, one line per document; body only when
                              $content is projected.
  -f keys                     One key per line.
  -f json                     Structured array of result objects.
  -f yaml                     Same shape as JSON, rendered as YAML.

EXAMPLES:

  iwe find --fuzzy rust                                # subsequence on title/key
  iwe find --lexical rust                              # BM25 on title/body
  iwe find --fuzzy rust --lexical rust                 # both, fused with RRF
  iwe find --filter 'status: draft'                    # all drafts
  iwe find --lexical rust --filter 'status: draft'     # BM25 AND status==draft
  iwe find --included-by projects/alpha:5              # descendants within 5 levels
  iwe find --included-by projects/alpha:0              # all descendants (unbounded)
  iwe find --references people/dmytro                  # docs that reference dmytro
  iwe find --filter 'priority: { $gt: 3 }' --sort modified_at:-1
  iwe find --project title,status -f json              # only two fields
  iwe find --add-fields 'body=$content' -f json        # default projection + body
