Extract a Getting-Started Command Atlas; Hand-Write Every Warranty Row

Generated onboarding documentation fails when it mixes extractable repo inventory with unverified product warranties that no compiler can prove. Commands, package names, and Makefile targets can be listed from files without guessing product intent. Support hours, security posture, and compatibility windows cannot be inferred from a repository tree with acceptable risk. Publish only after a human signs every warranty row, even when the command atlas was machine compiled.

This article proposes a two-stage workflow for getting-started pages, not a claim about production traffic or measured reader conversion. Stage one compiles an atlas of commands and paths that already exist in the tree. Stage two forbids the drafting model from inventing promises, then requires a reviewer to own every warranty cell before merge. The method is useful if every product name is removed, because the failure mode is documentation that looks complete while remaining legally and operationally false.

What belongs in the atlas versus the warranty sheet

Inventory rows are statements a script can defend with a file path, a parse tree, or a command that exits zero in a clean checkout. Warranty rows are statements a user would treat as a guarantee: supported versions, data retention, threat models, uptime, and “we never log secrets.” Mixing those classes is how generated READMEs acquire confident sentences that no owner would sign in an incident review. The atlas may be regenerated on every tag. The warranty sheet must not be regenerated without a human diff.

Treat the following classes as inventory unless a check fails: console script names, documented Makefile targets, example module import paths, and flags discovered on --help for local binaries. Treat the following classes as warranty even when a model proposes fluent wording: security claims, compatibility windows, performance numbers, support channels, license interpretations, and any sentence using always, never, or production-ready. If a sentence could become an incident ticket, it is a warranty row.

Prerequisites and a labeled example tree

The compiler below is a proposed local tool. It is not a report of a shipped internal platform, a customer deployment, or a benchmarked documentation pipeline. It expects Python 3.11 or newer for tomllib, a pyproject.toml at the repo root, and an optional Makefile. It writes JSON that a reviewer edits; it does not publish Markdown by itself.

repo/
  pyproject.toml
  Makefile
  src/demo_app/__init__.py
  docs/getting-started.ledger.json   # generated, then edited
  docs/getting-started.md            # published only after warranty signatures

Step 1 — Compile the command atlas from files you already own

Run the extractor from the repository root so relative paths in the ledger match review comments. The script records evidence for every inventory row and leaves warranty rows empty on purpose. Empty warranty cells are a feature: they block copy-paste publication of model prose that was never owned.

#!/usr/bin/env python3
"""Proposed command-atlas compiler. Label: unexecuted example, not production telemetry."""
from __future__ import annotations

import json
import re
import tomllib
from pathlib import Path

ROOT = Path(".")
MAKE_TARGET = re.compile(r"^([a-zA-Z0-9][a-zA-Z0-9_-]*):", re.M)


def load_project() -> dict:
    pyproject = ROOT / "pyproject.toml"
    if not pyproject.is_file():
        return {"name": None, "scripts": {}}
    data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
    project = data.get("project") or {}
    scripts = project.get("scripts") or {}
    return {"name": project.get("name"), "scripts": dict(scripts)}


def makefile_targets() -> list[str]:
    path = ROOT / "Makefile"
    if not path.is_file():
        return []
    return sorted(set(MAKE_TARGET.findall(path.read_text(encoding="utf-8"))))


def build_ledger() -> dict:
    project = load_project()
    inventory = []
    if project["name"]:
        inventory.append({
            "id": "pkg-name",
            "kind": "inventory",
            "text": f"Python package name is {project['name']}.",
            "evidence": "pyproject.toml:project.name",
        })
    for name, target in sorted(project["scripts"].items()):
        inventory.append({
            "id": f"script-{name}",
            "kind": "inventory",
            "text": f"Console script `{name}` maps to `{target}`.",
            "evidence": "pyproject.toml:project.scripts",
        })
    for target in makefile_targets():
        inventory.append({
            "id": f"make-{target}",
            "kind": "inventory",
            "text": f"Makefile defines target `{target}`.",
            "evidence": "Makefile",
        })
    warranties = [
        {"id": "compat", "kind": "warranty", "prompt": "Supported runtimes and upgrade window", "text": "", "signer": ""},
        {"id": "secrets", "kind": "warranty", "prompt": "What the getting-started path stores or logs", "text": "", "signer": ""},
        {"id": "support", "kind": "warranty", "prompt": "Who answers issues and in what time bound", "text": "", "signer": ""},
        {"id": "security", "kind": "warranty", "prompt": "Threat model for the sample commands", "text": "", "signer": ""},
    ]
    return {
        "status": "unsigned",
        "inventory": inventory,
        "warranties": warranties,
    }


def main() -> None:
    out = ROOT / "docs" / "getting-started.ledger.json"
    out.parent.mkdir(parents=True, exist_ok=True)
    payload = build_ledger()
    out.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
    print(f"wrote {out} inventory={len(payload['inventory'])} warranties={len(payload['warranties'])}")


if __name__ == "__main__":
    main()

A short command sequence keeps the artifact reproducible in review notes. Create a sample pyproject.toml if you are evaluating the compiler on a throwaway tree rather than a real package. Do not point the script at secrets files, .env contents, or credential stores; those paths are out of scope for a getting-started atlas.

mkdir -p docs src/demo_app
cat > pyproject.toml <<'EOF'
[project]
name = "demo-app"
version = "0.0.0"
[project.scripts]
demo-app = "demo_app.cli:main"
EOF
printf 'test:\n\tpython -m compileall src\n' > Makefile
python3 command_atlas.py
python3 -m json.tool docs/getting-started.ledger.json | head

Step 2 — Draft only narrative glue around inventory rows

After the ledger exists, a drafting model may rewrite inventory rows into readable paragraphs, ordered lists, and fenced command blocks. It may not fill warranty cells, invent version numbers, or promote a sample command into a production architecture. If the atlas lists make test, the draft may show that target as a local check. If the atlas does not list a cloud region, the draft must not recommend one.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. A reviewer who already uses MonkeyCode's free model access can paste inventory rows only, then request prose that quotes those rows verbatim. The free server option is relevant when the compiler should run beside the checkout rather than on a laptop that lacks Python 3.11. This article does not name models, quotas, hardware, or duration, because those details are not part of the method and would be unverified here.

Keep the drafting prompt mechanical so the model cannot launder warranties into the inventory section. A proposed prompt, labeled as unexecuted, is: “Rewrite each inventory row as one command block. Do not add compatibility, security, or support sentences. Leave warranty headings as empty placeholders.” Reject any draft that introduces numbers, SLAs, or vendor comparisons that are absent from the ledger.

Step 3 — Sign warranty rows with evidence a human can defend

Numbered review is cheaper than deleting a README after a user files a security ticket against a generated claim. Require a signer string, a date, and a pointer to a primary source such as a support policy, a SECURITY.md file, or an explicit “unknown / do not claim” value. Unknown is a valid signature. Silence is not.

1. Open docs/getting-started.ledger.json and confirm every inventory evidence path still exists on the tag you will publish.
2. Fill each warranty text with a sentence you would repeat in a postmortem, or write do-not-claim.
3. Set signer to a real reviewer identity used by the project, not a model name and not an anonymous bot.
4. Flip status from unsigned to signed only when every warranty cell is non-empty.
5. Render Markdown from the signed ledger; fail the docs job if status remains unsigned.

# Proposed gate. Label: example logic for CI, not a hosted service.
import json
from pathlib import Path

ledger = json.loads(Path("docs/getting-started.ledger.json").read_text(encoding="utf-8"))
errors = []
if ledger.get("status") != "signed":
    errors.append("ledger status must be signed")
for row in ledger.get("warranties", []):
    if not str(row.get("text", "")).strip():
        errors.append(f"unsigned warranty {row.get('id')}")
    if not str(row.get("signer", "")).strip():
        errors.append(f"missing signer {row.get('id')}")
if errors:
    raise SystemExit("\n".join(errors))
print("warranty gate passed")

Step 4 — Render a page that preserves the split in the published text

Readers should see commands first and promises last, with headings that make the split inspectable. Inventory sections can be regenerated. Warranty sections must show a signer so later diffs reveal who changed a guarantee. The renderer below is intentionally small: it concatenates signed JSON into Markdown and refuses unsigned ledgers.

#!/usr/bin/env python3
"""Proposed renderer. Label: example, not a measured publishing pipeline."""
from __future__ import annotations

import json
from pathlib import Path


def render(ledger: dict) -> str:
    if ledger.get("status") != "signed":
        raise ValueError("refusing to render unsigned getting-started ledger")
    lines = ["# Getting started", "", "## Commands compiled from this repository", ""]
    for row in ledger["inventory"]:
        lines.append(f"- {row['text']} (evidence: `{row['evidence']}`)")
    lines.extend(["", "## Warranties signed by a human reviewer", ""])
    for row in ledger["warranties"]:
        lines.append(f"### {row['prompt']}")
        lines.append("")
        lines.append(row["text"])
        lines.append("")
        lines.append(f"_Signer: {row['signer']}_")
        lines.append("")
    return "\n".join(lines) + "\n"


def main() -> None:
    ledger = json.loads(Path("docs/getting-started.ledger.json").read_text(encoding="utf-8"))
    Path("docs/getting-started.md").write_text(render(ledger), encoding="utf-8")


if __name__ == "__main__":
    main()

A decision table keeps arguments short during review. Use it when a draft sentence is fluent but unclassified. If two reviewers disagree, default to warranty and require a signature rather than hoping the model was conservative.

Sentence shape	Class	May a model draft it?	Publish rule
Named console script from pyproject.toml	Inventory	Yes, quoting the file	Allowed after path check
make target present in Makefile	Inventory	Yes, as a local command	Allowed after target check
“Works on every Linux distro”	Warranty	No	Sign or delete
“Secrets never leave the host”	Warranty	No	Sign with threat model or write do-not-claim
“Maintainers reply within one business day”	Warranty	No	Sign from a real policy
“Install with pip from this extras set”	Inventory if extras exist	Yes, quoting tables	Allowed after TOML check
Any percentage, SLA, or CVE status	Warranty	No	Human-owned only

Limitations and who should skip this workflow

The compiler does not execute help text against installed wheels, so stale project.scripts entries can still enter the atlas until a separate install test exists. Makefile parsing is a regular expression, not a Make database dump, so computed targets and include files are missed by design. The warranty gate proves that cells are non-empty; it does not prove that signed sentences are true. Truth remains a reviewer problem, which is the point of the split.

Skip this approach when the repository has no inspectable package metadata, when getting-started content is a marketing page rather than a command list, or when legal claims must be written only by counsel. Skip it when the team wants a model to own support policy, because that ownership cannot be delegated to generated prose. Skip it for secrets onboarding; command atlases should not harvest environment values, tokens, or private hostnames into docs.

The adjacent failure in current AI-assisted engineering is not that models draft paragraphs. The failure is publishing those paragraphs as if inventory and warranty were the same kind of sentence. A free drafting pass can still save time on command lists if the ledger stays the source of truth. Keep warranty rows in human review even when inventory rendering is fully automatic.