An Owned Command Matrix for Setup Guides That Models Must Not Extend

Generated setup guides stay reviewable when humans freeze commands, versions, and expected exits before any model writes narrative. That split stops a fluent paragraph from becoming the source of truth for a flag that nobody ran. The workflow uses a boundary file, a deterministic checker, and a narrow drafting pass with an explicit human owner. The examples below are a labeled proposal, and they were not executed against a production repository or a live package index.

Why setup prose outruns the last verified install

Install pages fail quietly when a draft invents a package flag, a minimum version, or a success line the last release never produced. Reviewers often approve the page because the sentences sound finished and the headings match the existing product voice. The operational facts sit inside those sentences, so a later release can change a flag without a named owner. A support matrix makes those facts visible and reviewable before anyone requests narrative from a model.

Split the page into a matrix lane and a narrative lane

The page has two lanes that meet only at review time, and neither lane is allowed to silently edit the other. The matrix lane stores owned facts, while the narrative lane stores explanations that must quote those facts rather than replace them. A fixture file sits beside each matrix row and holds the captured output from the last human verification. If a sentence in the draft conflicts with a row, the row wins and the sentence is rewritten or removed.

What the model may draft

A model may draft the section introduction, the reason a step exists, and a plain restatement of an owned command. It may draft troubleshooting hypotheses when each hypothesis is labeled unverified and cites a matrix row identifier. It may propose shorter headings when the owned command, version, and exit code remain byte-for-byte unchanged. It may not invent package names, version floors, environment variables, exit codes, download URLs, or alternate installers.

What a human must own

A human must own the operating system label, the package manager, the minimum version, and the exact install command. The same owner must record the expected exit code, the verification date, and the repository path of the fixture output. Those fields are the only inputs the checker treats as facts, and narrative quality never repairs a missing pin. Ownership here means a named person or rotation can refresh the row, not a shared inbox that nobody checks.

Store facts in a synthetic matrix

The JSON file below is synthetic, and the package name, versions, and dates are placeholders rather than measured results. Replace every placeholder after a person runs the command on a machine your team actually supports. Keep one row per supported path so a partial guide cannot hide an unverified installer inside a combined paragraph. Store the file in the docs repository so the review diff shows fact changes separately from prose changes.

{
  "schema": "support-matrix/v1",
  "rows": [
    {
      "id": "linux-apt",
      "os": "linux-placeholder",
      "manager": "apt",
      "min_version": "0.0.0-placeholder",
      "command": "sudo apt-get install -y examplectl",
      "expect_exit": 0,
      "verified_on": "YYYY-MM-DD",
      "fixture": "fixtures/linux-apt.out",
      "owner": "docs-platform-rotation"
    },
    {
      "id": "macos-brew",
      "os": "macos-placeholder",
      "manager": "brew",
      "min_version": "0.0.0-placeholder",
      "command": "brew install examplectl",
      "expect_exit": 0,
      "verified_on": "YYYY-MM-DD",
      "fixture": "fixtures/macos-brew.out",
      "owner": "docs-platform-rotation"
    }
  ]
}

Read the boundary as a decision table

The table below states the draft boundary in operational terms, which is easier to audit than a style guide paragraph. Use it during review when a sentence feels helpful but introduces a new flag, a new host, or a new success claim. If a cell says the human owns the field, the model output may mention it only by copying the matrix value. If a cell says the model may draft it, the checker does not treat that text as evidence of a working install.

Field or passage	Lane	Who may write it	Checker rule
Install command	Matrix	Human owner	Exact match required inside shell fences
Minimum version and exit code	Matrix	Human owner	Not inferred from prose
Fixture stdout and stderr	Fixture	Human owner	Not rewritten by the model
Why the step exists	Narrative	Model draft, then human edit	Must not add commands
Unverified troubleshooting idea	Narrative	Model draft, then human edit	Must cite a row id and must not be stated as fact

Run the workflow in five steps

1. Freeze one row per supported path

Start from the install paths you already support, and write one row before you open a drafting session. Copy the command from a shell history you trust, or retype it from the last release checklist, not from memory alone. Record the exit code you observed, including a non-zero code when the supported path is a documented failure. Leave the narrative file untouched until every supported path has an owner, a command, and a fixture path.

2. Capture fixture output without cleanup

Run the owned command in the environment named by the row, and save standard output and standard error without editing. Commit the fixture next to the matrix so a reviewer can see the captured text that the prose will later summarize. Do not let a model rewrite the fixture into a cleaner transcript, because cleanup is how invented success lines appear. If the command prints secrets, redact them with a documented rule before commit, and record that rule beside the row.

# proposal: capture the owned command; do not let a model rewrite this file
brew install examplectl > fixtures/macos-brew.out 2>&1
echo fixture_exit=$?

3. Reject unknown shell fences

Point the checker at the matrix and the markdown file so unknown shell lines fail before anyone requests new prose. The proposal script reads only fenced bash, sh, and shell blocks, and it ignores prose that merely names a tool. A failing exit means the draft contains a command the matrix does not own, not that the install itself is broken. Fix the failure by adding a verified row or by deleting the shell line, and do not silence the checker with a waiver comment.

Run the two commands below from the repository root after you place both files on the paths shown in the example. A zero exit means every fenced shell line matches an owned command, while a non-zero exit prints the unmatched lines. Treat the script as unexecuted proposal code, and read it before you rely on it in a continuous integration job. Extend the matcher only when your guides use a fence label the pattern does not already include.

python3 check_install_matrix.py support-matrix.json docs/install.md
echo checker_exit=$?

4. Request narrative by row identifier

Ask for narrative that explains each row identifier, and require the draft to repeat the owned command without edits. Ask for a short note on why the step exists, and forbid new flags, new packages, and new version comparisons. Ask for troubleshooting ideas only as unverified hypotheses that cite a row identifier and a fixture filename. Reject any completion that adds a shell block, even when the added command looks like a harmless variant of the owned line.

5. Let the named owner accept the diff

The named owner reads the diff, confirms the matrix did not change inside the prose pull request, and accepts or returns the narrative. A docs editor may improve clarity, but that editor may not update a version, a command, or an exit code alone. If the command must change, update the matrix and the fixture first, then regenerate the narrative in a follow-up commit. Merge only when the checker exits zero and the owner has confirmed the verification date is still within your team policy.

Inspect the proposal checker

The script builds a set of owned commands and compares each non-comment shell line from the draft against that set. Matching is exact, including spacing, because a changed flag is a different command even when the package name stays the same. Comment lines inside a fence are ignored so reviewers can annotate a block without creating a false missing command. The script does not execute the install command, does not fetch packages, and does not judge whether the fixture is stale.

#!/usr/bin/env python3
'''Proposal only: unexecuted checker. Rejects fenced commands absent from the matrix.'''

import json
import sys
from pathlib import Path

def load_matrix(path):
    data = json.loads(Path(path).read_text(encoding='utf-8'))
    return {row['command'] for row in data['rows']}

def fenced_commands(text):
    found = []
    marker = '`' * 3
    parts = text.split(marker)
    for index in range(1, len(parts), 2):
        header, sep, body = parts[index].partition(chr(10))
        if header.strip() not in ('bash', 'sh', 'shell'):
            continue
        for line in body.splitlines():
            stripped = line.strip()
            if stripped and not stripped.startswith('#'):
                found.append(stripped)
    return found

def main(argv):
    owned = load_matrix(argv[1])
    draft = Path(argv[2]).read_text(encoding='utf-8')
    missing = [cmd for cmd in fenced_commands(draft) if cmd not in owned]
    if missing:
        print('unowned commands:')
        for cmd in missing:
            print('- ' + cmd)
        return 1
    print('ok: ' + str(len(owned)) + ' owned commands, no extra shell lines')
    return 0

if __name__ == '__main__':
    sys.exit(main(sys.argv))

The main function returns one when any fenced line is missing from the matrix, and it returns zero when the sets agree. It prints a short summary on success so a log shows how many owned commands were loaded during that run. It does not parse continuations, and a fence marker inside the page can confuse the simple split. Those gaps are intentional in this proposal, because a small exact matcher is easier to audit than a shell interpreter.

An illustrative failure, not a measured run, would look like the lines below if a draft added an unowned flag. The checker would exit one and print the extra shell line so the owner can delete it or verify it first. That output is a format example for reviewers, and it is not evidence that any package manager returned those words. Use that sample only to explain the log shape during a design review, not as a recorded result from a package manager.

unowned commands:
- brew install examplectl --HEAD

Show a draft that stays inside the boundary

The markdown fragment below is also synthetic, and it shows how narrative can cite a row without adding a second installer. The shell fence repeats the owned command exactly, which is the only shape the proposal checker will accept. The hypothesis sentence names the row and the fixture, and it does not promote the guess into a supported step. A reviewer should still compare the fence with the matrix, because the checker does not understand synonyms or wrapped lines.

## Install on the apt path

The `linux-apt` row is the supported path for this placeholder page.
The command below is copied from that row and must not be edited in prose.

```bash
sudo apt-get install -y examplectl
```

If `fixtures/linux-apt.out` disagrees with this command, the matrix is stale and the prose must not paper over it.
Unverified hypothesis: a held package could explain a non-zero exit, but that idea cites `linux-apt` and is not a new command.

Use a free drafting pass without moving ownership

Once commands are frozen, the narrative lane is a bounded drafting task rather than a source of install facts. MonkeyCode's free model access can draft that lane, and its free server option can run the same checker you already trust locally. Disclosure: This article was prepared as part of MonkeyCode's product outreach. If this split matches your review, use that free model access for narrative only, and leave every command under the named owner.

This draft does not claim model names, quotas, hardware, duration, benchmarks, or permanence, because those details were not supplied. Keep fixtures in your repository, and treat a hosted run as a convenience that must match the local script. If the hosted result and the local script disagree, trust the local script and investigate the input files first. Do not send secrets, customer hostnames, or private fixture output to a hosted checker unless your policy already allows it.

Limitations of the checker and the split

The checker cannot prove that a command still works, because it never runs the installer or inspects the target machine. Exact string matching misses equivalent commands that differ only by argument order, quoting, or an inserted environment prefix. A stale verification date looks valid to the script, so your team still needs a calendar policy outside the code. Multi-line pipelines, heredocs, and generated shell from templates require a stricter parser than the proposal includes.

The approach also fails if reviewers paste commands into prose without fences, since those lines are invisible to the matcher. Fixture files can drift from the matrix when someone updates a command and forgets to replace the captured output. The proposal does not hash the fixture, so a follow-up change could add a digest if your review process needs it. Nothing here validates license text, trademark lines, or regional download rules that some install pages must carry.

Who should not use this workflow

Skip this workflow if no person can own each row, because an unowned matrix becomes another document that quietly rots. Skip it for marketing pages that contain no commands, since the checker would pass while saying nothing useful about claims. Skip it when install facts change many times a day and nobody can refresh fixtures before narrative is requested. Skip it for command lines that embed secrets, tokens, or customer hostnames, and keep those values out of both lanes.

What the split does and does not prove

The practical conclusion is narrow: freeze the support matrix, check fenced commands, and only then allow drafted explanation. Human ownership covers commands, versions, exits, dates, and fixtures, while the model covers clarity around those pins. That division will not make an install guide complete, but it will stop generated prose from owning facts it cannot verify. Adopt the checker only after a human reads the proposal and decides the exact-match rule fits the guides you publish.