OUTPUT FORMATS:

MARKDOWN (default, -f markdown):
  Each document is wrapped in a four-backtick fenced block with the info
  string "markdown #<key>". Inside the fence: YAML frontmatter, a blank
  line, then the rendered markdown body.

    ````markdown #doc-a
    ---
    title: Document A
    includedBy:
      - key: parent-doc
        title: Parent Doc
    ---

    # Document A

    Content here...
    ````

  Multiple documents are separated by one blank line between blocks.
  Empty edge lists (includedBy, includes, referencedBy) are omitted
  from frontmatter.

KEYS (-f keys):
  One document key per line, suitable for piping:

    doc-a
    child-doc
    parent-doc

JSON (-f json):
  Flat array of document objects:

    [{"key": "...", "title": "...", "content": "...",
      "includedBy": [...], "includes": [...],
      "referencedBy": [...]}]

YAML (-f yaml):
  Same shape as JSON, rendered as YAML.

FILTER FLAGS (narrow the result set):

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

EXPANSION (pull related documents into the result; nothing is followed by default):

  --expand-includes [N]       Follow child (block-ref) documents down N levels.
  --expand-included-by [N]    Pull N levels of parent context.
  --expand-references [N]     Follow outbound reference links N levels.
  --expand-referenced-by [N]  Pull documents that reference a seed, N levels.
  Bare flag = 1 level; N = 0 = unbounded; omitted = not followed.

SEED SEARCH (find seeds by relevance instead of naming keys):

  --lexical QUERY             BM25 full-text query over title and body.
  --fuzzy QUERY               Fuzzy query over title and key. Fuses with --lexical (RRF).

SHAPE FLAGS:

  --children                  Populate the includes array with child document edges.
  -b, --backlinks             Include incoming references (referencedBy). On by default.
  -e, --exclude KEY           Exclude document key(s) from results. Repeatable.

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

  --limit N                   Cap the seed documents kept before expansion — top-N by
                              relevance when searching, first-N of the selection otherwise.
  --max-documents N           Cap the documents returned after expansion; the periphery is
                              trimmed first.
  --max-tokens N              Cap total tokens across all documents. Whole documents are
                              dropped from the periphery once the budget is reached.
  --max-document-tokens N     Cap body tokens per document. A longer body is head-truncated
                              with a "⋯ truncated (N tokens omitted)" marker.
  0 = unlimited for every knob. Tokens count each document's body plus its edge lists
  (JSON/YAML structural overhead is not counted); the count is an approximate proxy and the
  truncation marker itself is uncounted, so a clipped body lands slightly over the cap. The
  main document(s) come first and survive; budgets trim the deepest expansion / context, so a
  clipped result set is not relationally closed (a kept child may lose its parent-context
  doc). When output is truncated a warning is printed to stderr; stdout stays clean. Page
  with --exclude: fetch, note the returned keys, then re-run excluding them.

EXAMPLES:

  iwe retrieve -k doc-a                                # single document (doc-only)
  iwe retrieve -k doc-a --expand-includes 2            # two levels of children
  iwe retrieve -k doc-a --children -f json             # includes array populated
  iwe retrieve -k x -k y -k z                          # multiple specific keys
  iwe retrieve --included-by projects/alpha -f keys    # keys inside alpha
  iwe retrieve --lexical "topic" --limit 5 --expand-included-by   # top-5 seeds + parents
  iwe retrieve -k doc-a --expand-includes 3 --max-tokens 8000     # bound total output size
