{
  "generator": {
    "matra": "0.3.0",
    "udpipe_model": {
      "name": "english-ewt-ud-2.5-191206",
      "sha256": "784bd0fa85e3d831fd02a55290d0acfd05c953159dc38cc33d52e1b28add9957"
    }
  },
  "page": "guides/cli.md",
  "paragraphs": [
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.561,
      "readability_grade": 7.8717,
      "sentences": 3,
      "text": "matra reads a file, a directory or stdin and writes to stdout. matra --help describes the tool in the line built into the command: \"matra parses text into CoNLL-U structure and measures it. It reports what is there; interpretation is yours.\"",
      "words": 42
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 1,
      "readability_grade": null,
      "sentences": 1,
      "text": "Nothing installed, nothing configured:",
      "words": 4
    },
    {
      "compression_ratio": 0.5581,
      "kind": "paragraph",
      "lexical_density": 0.5446,
      "readability_grade": 4.3132,
      "sentences": 5,
      "text": "The version floor is load-bearing. A bare uvx matra takes whatever release is newest, which is 0.3.x today and will not stay that way, and 0.1.0 and 0.2 are still on PyPI for anything pinned to them. 0.2's command line spells its JSON and its config file differently; Migrate from 0.2 to 0.3 lists each change. 0.1.0's analyze is a separate Python implementation rather than this one missing a flag: --json prints a bare document with no envelope, the human table is a different renderer, and the model cache lands in ~/.matra/models instead of the resolved model directory. It does not fail, it succeeds and gives you something else, so pin it.",
      "words": 116
    },
    {
      "compression_ratio": 0.4734,
      "kind": "paragraph",
      "lexical_density": 0.609,
      "readability_grade": 10.008,
      "sentences": 8,
      "text": "With the floor in place the command ships two ways beyond that, and all three run the same program. The Python package's matra command is the Rust CLI reached through the extension module, not a second implementation, so the flags, the output, and the exit codes are the same whichever route you took. One thing does differ: which features were compiled in. cargo install matra --version '^0.3' --features cli reports features: udpipe cli, while the published wheel reports features: udpipe model2vec python cli, so the embedding adapter is present on the Python route and absent from a --features cli build, whose matra clusters refuses and names the feature. cargo install matra --features cli,model2vec builds one with it. matra --version prints the list of the binary in front of you on its second line.",
      "words": 134
    },
    {
      "compression_ratio": 0.5693,
      "kind": "paragraph",
      "lexical_density": 0.5493,
      "readability_grade": 11.4231,
      "sentences": 3,
      "text": "Every route caches the model at the resolved model directory (about 16 MB) and downloads it the first time any command needs it. No flag and no environment variable is required to make that happen. If the cached file fails its SHA-256 check, matra never deletes it: a download that verifies replaces it through an atomic rename, and a download that fails leaves the file you had exactly as it was.",
      "words": 72
    },
    {
      "compression_ratio": 0.5849,
      "kind": "paragraph",
      "lexical_density": 0.6,
      "readability_grade": 9.078,
      "sentences": 3,
      "text": "A pre-existing ~/.matra/models from an older install is still used when the new location does not exist yet. matra never creates ~/.matra; when a non-empty legacy cache is selected it is the resolved model directory, downloads and re-downloads included. Create the new location, or set MATRA_MODEL_DIR, to move off it.",
      "words": 53
    },
    {
      "compression_ratio": 0.503,
      "kind": "paragraph",
      "lexical_density": 0.6038,
      "readability_grade": 9.7792,
      "sentences": 3,
      "text": "Per key, --model-dir outranks every environment variable, which outranks the config file, which outranks the defaults compiled into the crate. The config file has no key for the model directory, so that value comes from the flag, the environment, or the defaults. matra config show prints which rung each value actually came from.",
      "words": 54
    },
    {
      "compression_ratio": 0.5859,
      "kind": "paragraph",
      "lexical_density": 0.6154,
      "readability_grade": 9.5508,
      "sentences": 3,
      "text": "analyze, summarize, keyphrases and clusters each read a file, or - for stdin. analyze also reads a directory, one result per file. The other three report on one document, so they refuse a directory and name analyze, which reads one; picking one file out of it would answer a question nobody asked.",
      "words": 51
    },
    {
      "compression_ratio": 0.6032,
      "kind": "paragraph",
      "lexical_density": 0.5833,
      "readability_grade": 10.8933,
      "sentences": 3,
      "text": "Every subcommand routes through the library pipeline, which rejects symlinks, rejects files over 8 MiB before reading them, and picks a reader from the file's bytes and extension. --format markdown|plain_text|blocks names the format instead, which is how a JSON file of blocks is read, since no extension implies one. A PDF or DOCX signature in the bytes still outranks it.",
      "words": 65
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.5714,
      "readability_grade": null,
      "sentences": 1,
      "text": "Analyzes a file and reports its metrics.",
      "words": 7
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.6667,
      "readability_grade": 13.2956,
      "sentences": 1,
      "text": "--sections adds a per-section breakdown under the metric table: one row per section with its heading level, heading, and the paragraph, sentence, and word counts underneath it.",
      "words": 28
    },
    {
      "compression_ratio": 0.5414,
      "kind": "paragraph",
      "lexical_density": 0.53,
      "readability_grade": 8.73,
      "sentences": 5,
      "text": "Given a directory, analyze reads every regular file in it, one level deep and in name order, and reports each one: a table per file, or under --json one envelope per line. A file that fails is reported where it happens, on stderr and under --json as its own line with its error, and the walk goes on to the next file. The exit code is 2 if any file failed. Symlinks and subdirectories are skipped, as the library's Inputs::dir skips them. --format is refused with a directory, because each of its files is read as its own name says.",
      "words": 102
    },
    {
      "compression_ratio": 0.4845,
      "kind": "paragraph",
      "lexical_density": 0.5446,
      "readability_grade": 10.6353,
      "sentences": 5,
      "text": "--depth decides how much of the parse --json writes. document writes the provenance, the metrics and skipped, and no sections; paragraph adds the sections and their paragraphs, with no sentences; sentence adds the sentences, with no tokens; and token, the default, writes everything. A level below the depth is absent as a key, never an empty array, because an empty sentences would say a paragraph has none, and what remains keeps the whole document's key order, so the two diff line for line. Tokens are most of a document's JSON, so a caller that reads only the measures pays for no more than it reads. --depth without --json is a usage error.",
      "words": 114
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.5909,
      "readability_grade": 7.5618,
      "sentences": 3,
      "text": "On a markdown file, front matter, code blocks, tables, HTML blocks, thematic breaks and link reference definitions are not analyzed. They are listed in the JSON's skipped, each with its kind and span, rather than dropped. ## References is a heading like any other.",
      "words": 44
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.6522,
      "readability_grade": 12.8757,
      "sentences": 1,
      "text": "--json emits the full Document (provenance, sections, and metrics, which carries the counts and ratios the table prints) inside the envelope described below:",
      "words": 23
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.5429,
      "readability_grade": 12.1379,
      "sentences": 3,
      "text": "That query returns null more often than you might expect. Per-paragraph metrics have thresholds: readability_grade needs more than 10 words, compression_ratio needs more than 50, and quotes are skipped entirely. Filter for non-null before aggregating:",
      "words": 35
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.625,
      "readability_grade": null,
      "sentences": 1,
      "text": "Extracts the top-N sentences as an extractive summary.",
      "words": 9
    },
    {
      "compression_ratio": 0.4684,
      "kind": "paragraph",
      "lexical_density": 0.5421,
      "readability_grade": 8.0163,
      "sentences": 7,
      "text": "TF-IDF scores each sentence by term frequency against the document. TextRank scores by a graph-coherence measure over sentence similarity. TF-IDF is the default because it is cheap and needs no graph, not because it picks better sentences. It favours sentences dense in the document's rarer terms, and on narrative prose that can mean short sentences that make little sense on their own. Reach for TextRank when the summary should carry the document's main thread, when sentences restate and build on each other, or when the TF-IDF picks read as fragments. Read both on your own text before you rely on either. Both reject input over 2000 sentences.",
      "words": 113
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.5952,
      "readability_grade": 10.3,
      "sentences": 2,
      "text": "Both methods select their top-N sentences by score internally, then return that selection re-sorted into document order, not score order. The score field tells you how each sentence ranked; the list order tells you where each sentence sits in the source text.",
      "words": 43
    },
    {
      "compression_ratio": 0.5581,
      "kind": "paragraph",
      "lexical_density": 0.5574,
      "readability_grade": 9.9433,
      "sentences": 3,
      "text": "The human table prints each score at three decimals. Two sentences whose scores differ in the fourth therefore print the same number, and a summary of three sentences can arrive looking as though the ranker scored them identically when it did not. --json carries the full float, so reach for it whenever the ordering has to be defended rather than read.",
      "words": 61
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.4324,
      "readability_grade": 17.0184,
      "sentences": 1,
      "text": "Under --json the result is a summary: the document's provenance, with the method that ran and its parameters ({\"n\": 3}), and the sentences, each with its index among the document's sentences and its span in the input.",
      "words": 40
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 1,
      "readability_grade": null,
      "sentences": 1,
      "text": "Extracts ranked keyphrases.",
      "words": 3
    },
    {
      "compression_ratio": 0.572,
      "kind": "paragraph",
      "lexical_density": 0.5867,
      "readability_grade": 9.7693,
      "sentences": 5,
      "text": "RAKE splits on stop words and scores the remaining word runs by a co-occurrence degree-to-frequency ratio. It is rule-based and fast. YAKE scores individual terms by position, frequency, and how varied their surrounding context is, then builds one-word to three-word candidates from those scores. It tends to surface longer, more specific phrases and to notice terms that first appear later in a long document, at more computation than RAKE. Both reject input over 200000 tokens.",
      "words": 80
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.5714,
      "readability_grade": 12.267,
      "sentences": 2,
      "text": "Unlike summarize, keyphrases output stays in score order, highest first. A phrase is not tied to one location the way a sentence is, so under --json each carries occurrences, the span of every place in the input it was found, beside the result's provenance with its method and parameters.",
      "words": 50
    },
    {
      "compression_ratio": 0.5293,
      "kind": "paragraph",
      "lexical_density": 0.5664,
      "readability_grade": 8.7762,
      "sentences": 6,
      "text": "Phrases are printed as lowercased lemmas, not as the surface text of the document. \"Dependency Parses\" appears as dependency parse, and its occurrences point at the surface text. The lemma is the parser's, read in each sentence's context, and the parser does not always lemmatize one word the same way twice. \"Reading room\" can come out as reading room in one sentence and read room in another, two phrases for one surface form. Merge such pairs yourself if they matter. Phrases with equal scores come back in the same order on every run, the order they are first met, so a tie at the -n boundary is decided the same way each time.",
      "words": 115
    },
    {
      "compression_ratio": 0.5091,
      "kind": "paragraph",
      "lexical_density": 0.5556,
      "readability_grade": 8.3853,
      "sentences": 6,
      "text": "Neither number is a probability, a percentage, or comparable with the other. RAKE sums a per-word degree-over-frequency ratio across the words of the phrase, and that ratio is at least 1 for every word, so a phrase of k words scores at least k. That is a floor per length, not an order across lengths: on this book's methodology page the two-word lexical density scores 5.667 and the three-word model file name scores 5.200. YAKE multiplies its words' term scores and returns the reciprocal, so it is unbounded above and carries no interpretable unit, and phrase length does not predict where a YAKE score lands. Use either score to order phrases within one document under one method. Do not read it as a magnitude, and do not compare a RAKE number with a YAKE number.",
      "words": 141
    },
    {
      "compression_ratio": 0.5548,
      "kind": "paragraph",
      "lexical_density": 0.5333,
      "readability_grade": 5.315,
      "sentences": 5,
      "text": "Expect the top phrase not to be the document's topic. On this book's errors page, RAKE puts error implement st ::error, read off the code span std::error::Error and the words around it, first at 12.135 and scores the bare error at 1.468, while YAKE's first is move copy at 2257.447. What is low there is the score, not the position: 1.468 sits not far above 1.000, the floor any single word scores, and 229 of the 589 phrases sit flat on that floor underneath it, which puts error around the middle of the ranking, 306th. Both methods are behaving as specified: they rank properties of word co-occurrence, not aboutness. Methodology carries both formulas and every departure from the published versions.",
      "words": 125
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.5,
      "readability_grade": 11.91,
      "sentences": 1,
      "text": "Groups a document's sentences by the similarity of their embeddings.",
      "words": 11
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.5476,
      "readability_grade": 8.0524,
      "sentences": 2,
      "text": "On prose that does not repeat itself, expect the first line to find nothing. 0.85 joins near-restatements, and an essay whose sentences each say something new has none, so the table is empty, stderr says so, and the exit code is 1:",
      "words": 42
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.4483,
      "readability_grade": 5.5271,
      "sentences": 2,
      "text": "That is a result, not a failure. summarize and keyphrases say the same when they find nothing, and under --json or --quiet none of the three writes the line.",
      "words": 29
    },
    {
      "compression_ratio": 0.5007,
      "kind": "paragraph",
      "lexical_density": 0.5526,
      "readability_grade": 9.7377,
      "sentences": 5,
      "text": "Each sentence is embedded with potion-base-8M, the embedding model models.embedding names, downloaded into the model directory on first use (30.9 MB), with the same two lines on stderr the parsing model's first download prints. Two sentences whose cosine similarity is at least the threshold are joined, and a cluster is a connected component of that graph, so co-membership is transitive and is not pairwise similarity. A sentence with no partner is in no cluster. The table prints each cluster with its members' sentence indices and text; --json writes the Clusters value, with edges, every pair that cleared the threshold and its score, and the embedder's identity in provenance.parameters. Finding no cluster is exit 1.",
      "words": 120
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.5,
      "readability_grade": 6.3977,
      "sentences": 2,
      "text": "The threshold does not travel between models, domains or granularities, and 0.85 is a starting point for sentences only. Semantic clusters says how to choose one.",
      "words": 26
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.5357,
      "readability_grade": 8.8343,
      "sentences": 2,
      "text": "The command needs a build with the model2vec feature, which the Python wheel has. A build without it refuses before it reads anything, with invalid_input naming the feature.",
      "words": 28
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.76,
      "readability_grade": 11.624,
      "sentences": 1,
      "text": "matra config show prints every resolved value with the rung it came from, one key per line, in the shape cargo config get --show-origin uses:",
      "words": 26
    },
    {
      "compression_ratio": 0.5624,
      "kind": "paragraph",
      "lexical_density": 0.5556,
      "readability_grade": 10.8637,
      "sentences": 3,
      "text": "models.embedding is the name of the embedding model's directory under model_dir, which matra clusters, Model2Vec::from_config and Python's Model2Vec.from_config() provision into and load from. The file's sections are [models], [summary] and [keyphrases], each of the last two with n and method, and [clusters] with threshold. They configure the command line only: the library and Python take every count, method and threshold as an argument.",
      "words": 67
    },
    {
      "compression_ratio": 0.5645,
      "kind": "paragraph",
      "lexical_density": 0.5652,
      "readability_grade": 5.9126,
      "sentences": 7,
      "text": "A config file from 0.2 does not load. 0.3.0 renamed [summarize] to [summary], algorithm to method, and semantic.threshold to clusters.threshold, and dropped models.udpipe, since the parsing model is pinned in the source beside its digest. Every command that reads such a file fails with invalid_input, naming the file and each key's replacement, so the file can be fixed from the message. matra config init --force writes a fresh one.",
      "words": 70
    },
    {
      "compression_ratio": 0.5267,
      "kind": "paragraph",
      "lexical_density": 0.5385,
      "readability_grade": 4.1237,
      "sentences": 2,
      "text": "The origin is default for a value compiled into the crate, a path for one read from your config file, environment variable ... for one an environment variable set, and command line for one a flag set. With --json, each key carries its value, the rung, and what the rung pointed at.",
      "words": 52
    },
    {
      "compression_ratio": 0.4756,
      "kind": "paragraph",
      "lexical_density": 0.5357,
      "readability_grade": 8.4228,
      "sentences": 5,
      "text": "What that listing does not carry is the config file path. Every key whose origin is default names no file, so a run with no config file on disk prints no path at all, and \"where is my config\" is not a question the human table answers. Two commands do answer it, once there is a file. matra config show --json puts the config file's path in the envelope's input field when that file exists, and null when it does not: input names what the run read, and a run with no config file read none. matra config init prints the path it wrote to, which is also where config show looks.",
      "words": 114
    },
    {
      "compression_ratio": 0.5606,
      "kind": "paragraph",
      "lexical_density": 0.5932,
      "readability_grade": 12.08,
      "sentences": 2,
      "text": "matra config init writes the shipped defaults (models.embedding, and the summary, keyphrase and cluster keys) to the resolved config path and prints where it wrote them. It creates the parent directories, writes through a temporary file in the same directory so a reader never sees a half-written config, and refuses to overwrite an existing file unless you pass --force.",
      "words": 60
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.6667,
      "readability_grade": null,
      "sentences": 1,
      "text": "Prints a completion script for bash, zsh, or fish.",
      "words": 9
    },
    {
      "compression_ratio": 0.5392,
      "kind": "paragraph",
      "lexical_density": 0.4526,
      "readability_grade": 3.8046,
      "sentences": 4,
      "text": "matra --skill prints the agent skill: what matra is for, when to reach for it, every command with its JSON shape, how to read each number and what it does not mean, the limits, and the errors. It is the whole hand-off. If you are pointing an agent at matra and it has nothing installed, uvx 'matra>=0.3' --skill is the line to give it. Pin the version: --skill arrived in 0.2.0, and a bare uvx matra takes whatever release is newest, which before 0.2.0 was a different command line that does not have the flag.",
      "words": 97
    },
    {
      "compression_ratio": 0.5775,
      "kind": "paragraph",
      "lexical_density": 0.4265,
      "readability_grade": 7.2241,
      "sentences": 3,
      "text": "The text is compiled into the program with include_str! from skills/matra/SKILL.md and skills/matra/references/*.md, so what you read is what the installed version does, not a copy of the docs that may have moved on. The same files are what the repository ships as a plugin. Every command in them is executed against the command line by the test suite, so an incantation that no longer runs fails CI.",
      "words": 73
    },
    {
      "compression_ratio": 0.5956,
      "kind": "paragraph",
      "lexical_density": 0.5469,
      "readability_grade": 6.1801,
      "sentences": 4,
      "text": "--skill outranks a subcommand: matra analyze essay.md --skill prints the skill and never looks at the file. -r without --skill is an error that says so, and an unknown reference name exits 2 naming the ones that exist. Everything else exits 0. --quiet does not apply, as it does not to completions: the text is the command's output, not a rendering of a result.",
      "words": 65
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.619,
      "readability_grade": 12.2667,
      "sentences": 1,
      "text": "Under --json the skill uses the same envelope every other command uses, with input null because the command reads no document:",
      "words": 21
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.64,
      "readability_grade": 5.805,
      "sentences": 2,
      "text": "result.name is SKILL for the top level and the reference's own name for matra --skill -r <name> --json. The list replaces result with one key:",
      "words": 26
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.4516,
      "readability_grade": 14.3903,
      "sentences": 1,
      "text": "The list is every file under references/, in file-name order, and each summary is read from that file's own frontmatter rather than from a second list that could drift from it.",
      "words": 33
    },
    {
      "compression_ratio": 0.6431,
      "kind": "paragraph",
      "lexical_density": 0.5686,
      "readability_grade": 10.2439,
      "sentences": 2,
      "text": "The same files install as a plugin: claude --plugin-dir <checkout> over a clone of the repository picks up skills/matra/, which is where plugin discovery looks. And this documentation site serves llms.txt at its root, the map of every page with its one-line summary, for an agent reading the human door instead.",
      "words": 55
    },
    {
      "compression_ratio": 0.5375,
      "kind": "paragraph",
      "lexical_density": 0.4868,
      "readability_grade": 6.7959,
      "sentences": 5,
      "text": "- in place of the path reads stdin, as bytes, and the format is detected the way it is for a file. --stdin-filename gives that input a name, which is the label in the output and the envelope, and whose extension stands in for a file's. --format names the format outright. With neither, the input is read as plain text and labelled <stdin>. Bytes that are not UTF-8 text fail as unsupported_format, as a file's do.",
      "words": 79
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.4667,
      "readability_grade": 9.705,
      "sentences": 2,
      "text": "The 8 MiB cap applies to stdin as it does to a file, and it is enforced while reading rather than after, so an unbounded stream is refused instead of buffered. Stdin is read before the model loads, so an oversized stream costs no download.",
      "words": 45
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.6122,
      "readability_grade": 11.4902,
      "sentences": 3,
      "text": "--color takes auto (the default), always, or never. Under auto, matra colors an interactive terminal and nothing else, and honors NO_COLOR: if that variable is present and not empty, color is off whatever its value. --color always and --color never are explicit requests and outrank NO_COLOR in both directions.",
      "words": 49
    },
    {
      "compression_ratio": 0.5167,
      "kind": "paragraph",
      "lexical_density": 0.5238,
      "readability_grade": 10.1595,
      "sentences": 4,
      "text": "--quiet suppresses the human-readable output while leaving the exit code alone, so a script can branch on \"found something\" without collecting the table. It has no effect on --json. It also silences the one line the command prints to standard error before it downloads a model, which names the artifact, its size and where it is going. That line is the only output a first run produces during a wait that can reach half a minute, so silence it deliberately rather than by habit.",
      "words": 86
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.4615,
      "readability_grade": 6.7262,
      "sentences": 1,
      "text": "--version prints the version and then the features this build was compiled with:",
      "words": 13
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.75,
      "readability_grade": 9.74,
      "sentences": 1,
      "text": "--json emits one object for every command but completions, success or failure:",
      "words": 12
    },
    {
      "compression_ratio": 0.4595,
      "kind": "paragraph",
      "lexical_density": 0.5083,
      "readability_grade": 11.0767,
      "sentences": 5,
      "text": "command is analyze, summarize, keyphrases, clusters, config, skill or schema. input is the path that was read, or the name --stdin-filename gave it. For config it is the config file the run read, and null when there is none, and for skill and schema, which read no document, it is always null. result is the serde form of the domain value the command produced: a Document for analyze, a Summary for summarize, a Keyphrases for keyphrases and a Clusters for clusters, each of the last three carrying the document's provenance with the method that ran and its parameters. For config it is an object keyed by setting, each carrying value, source and origin, and for skill the shapes shown above.",
      "words": 121
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.625,
      "readability_grade": 18.3,
      "sentences": 2,
      "text": "All five keys are always present, and exactly one of result and error is null. A failure writes the envelope with result null and error holding the failure's kind, message and details, the same three Rust serializes and Python raises:",
      "words": 41
    },
    {
      "compression_ratio": 0.492,
      "kind": "paragraph",
      "lexical_density": 0.5659,
      "readability_grade": 8.386,
      "sentences": 7,
      "text": "The message still goes to stderr and the exit code is still 2, so a script that reads only the exit code is unchanged. Branch on error.kind and read values from error.details, never from the message. The command line's own refusals carry the kind whose remedy matches, which for every one of them is invalid_input, a call to change, with error.details.reason naming which refusal it is: a directory given to a command that reads one document, --format with a directory, -r without --skill, an unknown reference or schema name, config init over an existing file, and clusters in a build without an embedder. A usage error under --json, such as an unknown flag, is an envelope too, with command null when the arguments name none. Errors lists every kind.",
      "words": 130
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.697,
      "readability_grade": 13.0133,
      "sentences": 1,
      "text": "analyze DIR --json writes one envelope per line, one line per file, each compact rather than indented, so the output is a stream of JSON values that jq reads one at a time.",
      "words": 33
    },
    {
      "compression_ratio": 0.5627,
      "kind": "paragraph",
      "lexical_density": 0.6,
      "readability_grade": 12.386,
      "sentences": 3,
      "text": "Stability: format_version increments on any change to the envelope, and whenever the document schema's major version moves; the result value is the serde form of the documented domain types. That is the same promise cargo makes for cargo metadata --format-version. Pin your consumer to a format_version you have tested against.",
      "words": 52
    },
    {
      "compression_ratio": 0.558,
      "kind": "paragraph",
      "lexical_density": 0.5645,
      "readability_grade": 6.9013,
      "sentences": 3,
      "text": "A Document also names its own schema version, in result.provenance.schema (\"2.0\"), and that is the only place it appears. A minor version adds optional fields only; anything else is a major. So ignore fields you do not recognize, treat every string set you receive as open (format, pos, dep, mood, pattern, the feature names), and reject a major you do not know.",
      "words": 62
    },
    {
      "compression_ratio": 0.5577,
      "kind": "paragraph",
      "lexical_density": 0.5373,
      "readability_grade": 9.6112,
      "sentences": 4,
      "text": "The JSON Schemas for this major are compiled into the program. matra --schema lists them with their titles, and matra --schema NAME prints one: document, summary, keyphrases, clusters and error for the outputs, and blocks for block input. Like --skill it outranks a subcommand and reads no document, and under --json it is the envelope with command schema. The same files are in the repository under spec/schema/v2/.",
      "words": 68
    },
    {
      "compression_ratio": 0.5077,
      "kind": "paragraph",
      "lexical_density": 0.4918,
      "readability_grade": 12.6509,
      "sentences": 4,
      "text": "0 on success when the command found something, 1 on success when it found nothing (an empty summary, no keyphrases, no clusters, a file with zero sentences), and 2 when an error occurred. Model load failure, a missing or unreadable file, a directory where one document is read, input over the size cap, a bad argument, and a parse failure all land on 2, with the message on stderr prefixed matra: and, under --json, the envelope with its error on stdout. For a directory the code is 2 if any file failed, 0 if none failed and any had a sentence, and 1 otherwise. A broken pipe, which is what you get piping into head, is treated as success and exits 0.",
      "words": 123
    }
  ]
}
