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.

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.
  -d N                        Follow block refs down N levels (default 1).
  -c N                        Include N levels of parent context (default 1).
  -l, --links                 Include inline references.

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

  --limit N                   Maximum number of documents to return.
  --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
  iwe retrieve -k doc-a -d 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 -k doc-a -d 3 --max-tokens 8000          # bound total output size
