Enhancement proposal EPR-0004 The command line, configuration and the agent skill proposed

0 of 2 decisions settled 1 assumption to confirm pinned at 4fcfb4a pull request #133 tracking issue: none (a baseline proposal describes code that already ships, so there is no milestone to track) started: 2026-10-04feature name: command_line_and_configuration decides: the owner, who alone sets the status to accepted

EPR-0004 0 of 2 settled 1 to confirm

Enhancement proposal EPR-0004 The command line, configuration and the agent skill proposed

pinned at 4fcfb4a pull request #133 tracking issue: none (a baseline proposal describes code that already ships, so there is no milestone to track) started: 2026-10-04feature name: command_line_and_configuration decides: the owner, who alone sets the status to accepted

EPR-0004: The command line, configuration and the agent skill

enhancement proposal: proposed

on this record: read, decide, confirm
Started
2026-10-04
Pinned at
4fcfb4a, the commit every code citation below opens at
Decides
the owner, who alone sets the status to accepted
Proposal PR
#133
Tracking issue
none (a baseline proposal describes code that already ships, so there is no milestone to track)
Feature name
command_line_and_configuration

Summary

There is one matra command line, written in Rust as the library module matra::cli, whose whole surface is cli::run(args, out, err) -> u8. Two launchers call it: the Rust binary and the Python entry point that pip and uvx install. Every --json result is one envelope with a version number. Where things live and what the defaults are come from Config, which resolves each key from an explicit argument, then the environment, then a TOML file, then defaults compiled into the crate, and records which of those each value came from. Configuration never decides what a call computes. The binary prints its own agent instructions with matra --skill, embedded from the same files a plugin distributes, and a test runs every command in them.

This is a baseline proposal. It describes the code at the pinned commit and carries forward the reasons that still hold from RFC-0011, RFC-0012, RFC-0020, EP-0010 and EP-0011. A later proposal that changes any of it says so. Unmarked statements about the code are observed at the pinned commit through the link beside them; a claim that is inferred or assumed says so.

Motivation

One program, not two that agree by inspection. 0.1.0 shipped two command lines: the Rust binary and a Python re-implementation in click and rich so that uvx matra worked. They drifted: the Python one grew a flag the Rust one lacked, lacked one the Rust one had, and had earlier re-implemented passive detection and got it wrong (RFC-0011). The command line now lives in the library because a binary target cannot be reached from PyO3, and maturin's own guidance for a crate that is both a library and a tool is a Python entry point that calls into the extension.

Working with no setup, on every surface. Before 0.2.0 the library required a model directory every caller re-derived, under a path (~/.matra) no developer tool on Linux or macOS uses (RFC-0011). Config gives every surface one resolution order and the XDG locations.

Configuration is where things are, not what happens. A config format that reaches into the library would put pipeline policy in a file the library parses. So the file carries only what a caller could pass as an argument; which metrics run and how output looks stay with the caller and the binary (RFC-0011, option B over option C).

An agent's instructions should match the installed binary. An agent reaches the docsite by link and prior knowledge; --help carries no semantics. Instructions printed by the program they describe cannot be stale against it (RFC-0012).

Guide-level explanation

Running it

matra analyze notes.md                 # a table of metrics
matra analyze notes.md --json          # the same, as JSON
matra summarize report.txt -n 3 --method textrank
matra keyphrases - --stdin-filename draft.md < draft.md
matra config show                      # every setting and where it came from
matra --skill                          # the agent skill

The commands are analyze (with --sections), summarize, keyphrases, config show, config init [--force] and completions <bash|zsh|fish> observed cli/mod.rs:112-242. The global flags are --json, --model-dir, --quiet, --color, --stdin-filename, --skill and --reference observed cli/mod.rs:112-242. - reads stdin, and --stdin-filename both labels it and chooses its decomposer by extension.

Exit codes follow ripgrep: 0 when something was found, 1 when the command succeeded and found nothing, 2 on an error; a broken pipe is 0 observed cli/mod.rs:1-19.

Reading --json

Every --json invocation emits one object with four keys observed cli/mod.rs:677-709:

{ "format_version": 1, "command": "analyze", "input": "notes.md", "result": { } }

result is the serialized domain value unchanged (EPR-0002). input is null for a command that reads no document. format_version increments on any change to the envelope's shape or to the meaning of a field in result observed cli/mod.rs:34-39. Both launchers are held to spec/tests/cli/envelope.json observed envelope.json:1-19.

Configuration

matra config init writes the shipped defaults to the config path; matra config show prints every resolved key beside its source. The file:

[models]
embedding = "potion-base-8M"

[summarize]
n = 3
algorithm = "tfidf"

[keyphrases]
n = 10
algorithm = "rake"

(config/default.toml.) Three environment variables name what they override: MATRA_CONFIG_FILE, MATRA_DATA_DIR, MATRA_MODEL_DIR. --model-dir on the command line, or Config::with_model_dir in Rust, outranks all three.

A file written by an earlier config init may also set models.udpipe or semantic.threshold. Both still load, both are ignored, and config show names each one on stderr so the line can be removed.

For an agent

uvx matra --skill prints SKILL.md: what matra is for, every command with its JSON shape, how to read the numbers, and the limits. --skill -r lists the references (errors, json, metrics, python, semantic, structure) and --skill -r <name> prints one. With --json each is the same envelope, with command set to "skill" and input null.

Reference-level explanation

One command line, two launchers

cli::run parses, dispatches and renders, never calls std::process::exit, and never touches the process's own streams: the caller passes both observed cli/mod.rs:50-106. It returns a u8 because ExitCode cannot be read back for the Python launcher observed cli/mod.rs:50-106. src/bin/matra.rs locks stdout and stderr, calls it, and converts with ExitCode::from observed bin/matra.rs:1-26. python/matra/cli.py passes sys.argv[1:] to _core.cli_main and exits with the result; cli_main passes each argument through os.fsencode so a non-UTF-8 path on Unix reaches the command line as the same bytes the Rust binary would see observed cli.py:1-10 lib.rs:776-829. pyproject.toml installs that launcher as the matra script (scripts), and the python feature enables cli, which enables udpipe (features).

src/cli/ is the application tier. Boundary rule 7 holds it to the public surface (Engine, Ingest, extraction, config, domain) and never a port or an adapter; a semgrep rule checks the imports (EPR-0001). It validates an input path before building the engine, so a missing file is reported before a 16 MB download observed cli/mod.rs:372-430. The download notice goes to stderr so --json stdout stays one object, and --quiet silences it observed cli/mod.rs:486-530.

--skill outranks a subcommand: matra analyze x --skill prints the skill observed cli/mod.rs:372-430. Bare matra with neither is a usage error, exit 2 observed cli/mod.rs:252-288.

Config resolution

Config is a composition-root value beside Engine, #[non_exhaustive] with private fields. Config::resolve reads the process environment and the file; Config::from_sources takes both injected, which is how tests avoid the developer's home.

KeyRungs, highest first
config file pathMATRA_CONFIG_FILE, $XDG_CONFIG_HOME/matra/config.toml, ~/.config/matra/config.toml (resolver)
data_dirMATRA_DATA_DIR, $XDG_DATA_HOME/matra, ~/.local/share/matra
model_dirwith_model_dir, MATRA_MODEL_DIR, an existing non-empty ~/.matra/models when data_dir/models does not exist, data_dir/models (resolve_model_dir)
models.embedding, summarize.n, summarize.algorithm, keyphrases.n, keyphrases.algorithmthe file, the compiled default

matra never creates ~/.matra; the fallback only keeps an existing cache working. Environment values are used as paths unchanged, with no ~ expansion, and an empty variable counts as unset.

The file is capped at 64 KiB by its metadata before it is read (InputTooLarge, what = "config_file"), and may be a symlink, since dotfiles repositories commonly link it observed config.rs:49 config.rs:703-720. Unknown keys are rejected (deny_unknown_fields), so a setting a user believes is in force cannot be silently ignored observed config.rs:467-503. An unknown algorithm name fails at resolve time. models.embedding must be a single ordinary path component, because the embedding provisioner sweeps aged temporaries inside the directory it names observed config.rs:588-606.

Config::sources yields each resolved key with its ValueSource (Argument, Environment, File, Default), which is what config show prints (accessors).

The deprecated keys

RFC-0020 deprecated models.udpipe and semantic.threshold, because neither selected anything: the UDPipe model is pinned in the adapter beside its digest, and every clustering call takes its threshold as an argument. They left config/default.toml; the schema still accepts them so a 0.2.x file loads; Config::udpipe_model and Config::semantic_threshold carry #[deprecated] and return the file's value or the former default; Config::deprecated_keys lists which ones the file set; and Config::sources omits them (accessors). config show writes one stderr line per deprecated key, naming the file, unless --quiet observed cli/config_cmd.rs:82-111. Removing them is a breaking change and takes its own proposal.

config init writes atomically: a temporary file in the same directory, then a hard link when not forced (which fails if the target appeared in the meantime) or a rename when forced observed cli/config_cmd.rs:213-293.

The skill

SKILL.md and six references under skills/matra/ are embedded with include_str! observed cli/skill.rs:1-70. Each reference's summary is read from its own frontmatter rather than kept in a second list, and a test holds the table of names equal to the directory. The frontmatter's version matches the crate's observed SKILL.md:1-5 Cargo.toml:1-14. tests/skill.rs extracts every fenced block whose first line is a matra command, runs it through cli::run (or as a subprocess with a clean environment, for config), and asserts the annotated exit code and, for --json, the envelope; the block count is checked against a fence-aware scan so an unfenced command cannot hide observed tests/skill.rs:1-37. Alongside the flag: AGENTS.md for contributing agents, .claude-plugin/plugin.json so the repository installs as a plugin, and site/content/llms.txt, generated from the docsite's SUMMARY.md and held current by a docs gate.

No longer in force

  • semantic.threshold and models.udpipe as settings. RFC-0011 and EP-0010 list both among the defaults Config carries; RFC-0020 deprecated them (above).
  • book/src/llms.txt. RFC-0012 and EP-0011 place it under the mdBook source; the docsite moved, and the file is site/content/llms.txt, generated by scripts/gen-llms-txt.sh.
  • CITATION.cff as blocked. EP-0011 records it as waiting on the attribution decision; RFC-0013 settled it and the file exists (EPR-0003).

Drawbacks

  • The config schema is public surface, versioned with the crate, and deny_unknown_fields means a key can only leave by deprecation.
  • The python feature compiles clap, and the wheel carries the whole command line.
  • The skill is public surface. A wording change that alters an incantation is breaking for agents and goes through the CHANGELOG like an API change.
  • A deprecated key is accepted and ignored outside config show, which is the silence deny_unknown_fields exists to prevent, narrowed rather than closed (RFC-0020).
  • The legacy ~/.matra/models fallback keeps capturing downloads for a user who has one, until they create the new location or set MATRA_MODEL_DIR.

Rationale and alternatives

  • Configuration in the application only: every library caller keeps writing the path, and "works out of the box" is true only of the binary. Rejected in RFC-0011 (option A).
  • A configuration schema that drives the pipeline: puts policy in a file the library parses and couples the library to a presentation vocabulary. Rejected in RFC-0011 (option C).
  • Two command lines with a parity test: catches drift after it happens, for a second implementation a launcher replaces. Rejected in RFC-0011 (option D).
  • Docs and llms.txt only, or a skill file only, or an MCP server: the first two drift from the installed binary and nothing runs their commands; an MCP server is a second protocol surface beside a CLI and JSON that already are the tool interface. Rejected in RFC-0012.
  • matra skill get <name> as a subcommand: rejected for a flag, because the hand-off to an agent is uvx matra --skill and a flag reads as a property of the program (RFC-0012).
  • Delete the unread keys, accept them silently, or make them act: the first breaks every 0.2.x file, the second leaves users editing keys that do nothing, and the third would load an unpinned model or let configuration decide a computation. Rejected in RFC-0020.

Prior art

  • uv documents that it follows the XDG conventions on Linux and macOS; gh resolves $XDG_CONFIG_HOME/gh before ~/.config/gh. UV_CONFIG_FILE, UV_CACHE_DIR and OLLAMA_MODELS name the thing they override, as the MATRA_* variables do.
  • ruff and uv ship their Rust command lines to uvx; maturin recommends a Python entry point into the extension for a crate that is both library and tool.
  • cargo metadata --format-version is the precedent for a versioned integer on a JSON output rather than a published schema; cargo config get --show-origin for printing where each value came from; Cargo's "unused manifest key" warning for a deprecated key that still loads.
  • ripgrep's exit codes (0 found, 1 nothing found, 2 error), and no-color.org for NO_COLOR.
  • Vercel Labs' agent-browser prints its own agent instructions with a second tier of detail, for the same reason: they cannot drift from the installed binary (RFC-0012's survey).

Unresolved questions

For the owner to settle in this proposal's review. Each is a decision of its own.

The exit code type. cli::run returns u8 observed cli/mod.rs:50-106 grounds for decision 1; whether that is the permanent shape was left open by RFC-0011 and is still open. Changing it is a breaking change.

Decision · open · costly to reverse

1. Is u8 the permanent return type of cli::run?

A Yes; keep u8 recommended

run keeps returning u8, and its documentation says the shape is permanent and names the three codes.

B No; a named exit status

run returns a type that names its three codes and converts to both u8 and ExitCode.

Claude recommends A, Yes; keep u8. inferred, a judgment

The reason it is a u8 still holds: ExitCode cannot be read back, and the Python launcher needs the number. The three codes are documented beside run already, and a second type would wrap one integer to name three values.

The strongest case against it

A bare u8 admits codes the command line never returns, and only review keeps a new return path to 0, 1 or 2; a type would hold it. The change is breaking whenever it lands, so it costs less before more callers depend on the integer.

The owner's decision: open. Answer with accept, accept with a reservation, object or redirect, in a comment on this block or on the pull request; Claude then records your ruling here, as a named step in a pull request. A comment is never read as a ruling. Silence is not assent.

No error envelope under --json. A failure writes text to stderr and nothing to stdout, so a JSON consumer reads text for every failure observed cli/mod.rs:50-106 grounds for decision 2. The command line's own refusals are untyped strings, so an error envelope needs a kind vocabulary for the application tier or a move of src/cli/ onto domain::Error. RFC-0015 deferred it as worth doing on its own.

Decision · open · costly to reverse

2. Does a --json failure get an envelope, and whose kinds does it carry?

A An envelope, with kinds of the command line's own recommended

A failure under --json writes the envelope with an error in place of result. Its kind is Error::kind for a failure from the library, and a word from a small vocabulary of the command line's own for its refusals.

B An envelope, on domain::Error

src/cli/ reports its refusals as domain::Error variants, so every failure carries a library kind.

C No envelope

Failures stay text on stderr, as now.

Claude recommends A, An envelope, with kinds of the command line's own. inferred, a judgment

Failures from the library already have kinds, pinned for every binding, so only the command line's own refusals need new words. Putting those words in domain::Error would grow the library's vocabulary with application-tier failures the library never raises. Once a consumer branches on the envelope's kinds, removing or renaming one breaks it, so this is costly to reverse. assumed grounds for decision 2

The strongest case against it

Two vocabularies behind one envelope means a consumer reads two lists, and the library's is the one a conformance fixture already pins. Option B keeps a single list.

The owner's decision: open. Answer with accept, accept with a reservation, object or redirect, in a comment on this block or on the pull request; Claude then records your ruling here, as a named step in a pull request. A comment is never read as a ruling. Silence is not assent.

1 claim stands on no grounds yet. Confirm or strike each with a comment on it.

  1. Once a consumer branches on the envelope's kinds, removing or renaming one breaks it, so this is costly to reverse. where: Unresolved questions bears on decision 2

Future possibilities

  • The error envelope above, under the same format_version.
  • A terminal UI for the Rust command line, which ROADMAP.md lists.
  • Removing the deprecated keys and accessors in a later breaking release, by a new proposal.