Medios-Macina/docs/result_table_selector.md

Selector and `plugin-table` usage

This project provides a small plugin/table/selector flow that lets plugins and
cmdlets interact through a simple pipable API.

Key ideas:
- `plugin-table` renders a plugin result set and emits pipeline-friendly dicts for each row.
- Emitted rows can include `_selection_args` and, when needed, `_selection_action` for exact row replay.
- Use `@N` to select an item from a table and chain it to the next cmdlet.

Example:

    plugin-table -plugin example -sample | @1 | add-file -instance default

What plugins must implement:
- An adapter that yields `ResultModel` objects.
- Optionally a `columns` factory and `selection_fn`.

Implementation notes:
- `plugin-table` emits dicts like `{ 'title': ..., 'path': ..., 'metadata': ..., '_selection_args': [...] }`.
- When a row includes `_selection_action`, `@1` prefers that exact action.
- Otherwise `@1` falls back to `_selection_args`, then plugin selection logic, then sensible defaults such as `-path` or `-title`.

This design keeps selector-focused workflows small and predictable while still
allowing full cmdlet interoperability through piping and `-run-cmd`.