Output destination routing (--output file/clip/stdout/all) and pager research

[djdarcy]

Output destination routing and optional paging

Problem

When running unbounded or large enumerations like --expr "tri(n)" --max-n 100000, the output floods the terminal and the user loses shell history. Users can pipe to less or redirect to a file, but:

1. They have to know to do that before running the command
2. There's no built-in way to write to both stdout and file simultaneously (tee)
3. Clipboard output is useful for quick results but requires external tools
4. A built-in pager or buffer would let users maintain control of their terminal without pre-planning

Proposal

Add --output / -o flag supporting multiple destinations, modeled on the listall.py pattern from Z:\OmniTools\listall:

--output stdout       (default, current behavior)
--output file         (write to auto-timestamped file)
--output clip         (copy to clipboard)
--output all          (all three)
--output file,stdout  (comma-separated for specific combos)

Optional: --filename / -F for custom output filename when using --output file.

Buffer / Pager Concept (research)

The more speculative part: should we buffer large enumerations and present them through a pager (like less) by default when output exceeds a threshold? Arguments:

For built-in paging:

• Protects users from runaway stdout filling their terminal
• No pre-planning needed ("I forgot to pipe to less")
• Could integrate with --limit as a soft vs. hard cap

Against built-in paging:

• Users can already | less or | head
• Pager behavior varies across platforms (Windows vs. Unix)
• Adding pager logic to a math tool is scope creep
• --limit N already provides a hard cap

This may be best left as a "document the pattern" rather than implement — show users in help/docs that | less and > file.txt are the recommended approaches for large output, and keep --output file as the built-in alternative.

Reference

The Z:\OmniTools\listall\listall.py output routing:

• output_results() function (lines 572-592): multi-destination router
• --output uses action="append" with set-based expansion ("all" → {clip, stdout, file})
• Auto-timestamped filenames: listall_25.01.13_14-30_EST.txt
• Content fully assembled in memory, then routed — no streaming/paging

Placement

v1.0 milestone — fits under "Stable CLI interface" alongside output formatting (#55) and enhanced JSON (#35). The output routing is a CLI maturity feature, not a math/enumeration feature.

Related Issues

• Configurable output formatting for expression results #55 Configurable output formatting
• Enhanced JSON output with expression context #35 Enhanced JSON output with expression context
• Multi-level verbosity system (-v, -vv, -vvv) #31 Multi-level verbosity (v0.8.1, done)
• Quantifier UX: helpful hints for does_exist + --limit N for bounded for_any enumeration #53 --limit N (v0.8.1, done)

[djdarcy]

Per-channel stream routing (stdout vs stderr)

Expanding scope: in addition to destination routing (--output file/clip/stdout), we need stream routing — letting users configure which channels go to stdout vs stderr.

Problem

v0.8.1 routes all non-error output to stderr (hints, progress, timing, verbose info). The intent was to keep stdout clean for data piping. But this has a UX problem:

Many users habitually run 2>/dev/null to suppress warnings and errors. This inadvertently hides helpful hints and tips like:

Tip: Use "for_any" to find all matches in the search space.
Note: --limit has no effect with does_exist (stops at first match).

These are user-facing guidance, not diagnostic noise. Suppressing them silently makes the tool less helpful.

Proposal

Add a config.json section for channel-to-stream mapping:

{
  "output": {
    "channels": {
      "hint":      "stdout",
      "progress":  "stderr",
      "timing":    "stderr",
      "config":    "stderr",
      "algorithm": "stderr",
      "iter":      "stderr",
      "parse":     "stderr"
    }
  }
}

Sensible defaults:

• stdout: hints/tips (level 0 guidance users should see)
• stderr: progress, timing, config, algorithm, parse, iter (diagnostic/verbose)

Each verbosity level (-v, -vv, -vvv) and each channel represents a routing decision the user should be able to control.

Relationship to existing #59 scope

This is the "which pipe" complement to #59's "which destination":

• Output destination routing (--output file/clip/stdout/all) and pager research #59 destination routing: stdout / file / clip / all
• This addition: per-channel stdout vs stderr assignment

Both should land together as part of the v1.0 output maturity work.

Current state (v0.8.1)

The channel infrastructure is already in place — every emit() call has a channel parameter. The OutputManager just needs to consult a routing table instead of hardcoding sys.stderr.