Jeden/Docs

CLI command

jeden context recommend

Return ranked locators for a task, with the state of every source that answered.

Exact invocation#

Shell
jeden context recommend "<task>" [--limit n] [--source list] [--json] [--cwd path]

Inputs and options#

  • --source takes any comma-separated subset of files, ground-truth, memory, transcripts, or all. Without it, context.advisor.sources decides, which defaults to files,memory.
  • --limit is how many recommendations to return, a whole number above zero; without it context.advisor.limit decides, and a request with neither is refused as limit-undeclared. Every selected source is awaited until it answers, fails or observes its caller's cancellation; an acknowledgement alone does not mean that source has stopped. --cwd selects the workspace whose project configuration and memory scope apply. Jeden Desktop's Context screen takes the same count in its Recommendations field.
  • --json returns the authoritative object.

Output and state effect#

Each recommendation carries source, title, locator, score, matched and snippet. File-source titles come from Markdown headings; other text sections, and Markdown before its first heading, use the file name rather than promoting an unparsed source or data line to title metadata. That content remains searchable and appears in the snippet. Locators are path:first-last for a file chunk, memory:&lt;id&gt; for a recalled memory, session:&lt;id&gt; for a transcript, and repo/path@commit:first-last for a ground-truth citation. The sources array carries available, the observed detail, considered, returned and elapsedMs for each source, so a short list can be told apart from a refused one.

Refusals and boundaries#

  • The functionality is jeden.context; jeden errors show jeden.context prints every cause with its test (tests/context/command.mjs). Each refusal prints what failed, why and what was observed, then fix: … and cause: jeden.context.&lt;cause&gt;. Read before any source is asked, each exit 2: verb-missing (no word at all), task-missing (&lt;verb&gt; answers for a task, and the command line holds only options), option-unknown (an option the verb does not take; prompt takes neither --limit nor --source), limit-missing, limit-invalid (--limit takes a whole number of recommendations above zero, and `X` is not one), source-missing (--source with no list, or a list of separators only), source-unknown (the context advisor has no source named X, observed: the sources there are) and argument-unexpected (a word after sources).
  • Exit 1, from the configuration: configured-source-unknown (context.advisor.sources names a source the advisor does not have; a typo never narrows the answer silently), sources-none (it holds only separators; recommend only) and limit-undeclared (recommend only). signal-unregistered, exit 69: the operating system refused the Ctrl-C handler, registered only once the request was read whole; no source starts without it.
  • A source that fails to answer does not discard completed recommendations: it is reported as unavailable with its actual reason in sources and unanswered. A successful search with no matches is not unanswered. An exit-zero recommendation command therefore does not prove that every source worked; inspect unanswered. This final-result contract does not impose a deadline on a source that is still running.
  • Over Jeden's RPC the request must name cwd, the workspace it reads; one that names none is refused as invalid_params: the request names no cwd, the workspace it reads from, never answered from the server's own working directory.
  • A command line of the wrong form (an unknown command or option, a missing, unexpected or invalid argument, a missing confirmation) prints the error and the usage and exits 2; a refusal that retrying unchanged can help (a dependency down or not answering, a rate limit) exits 69; any other refusal or failure exits 1. A refusal a functionality declares ends with fix: … and cause: &lt;operation&gt;.&lt;cause&gt;, and jeden errors show &lt;operation&gt; lists every cause of that functionality.