Public proof · 29 July 2026

A real README audit, with exact fixes.

This report audits the 37-line README in the public social-kit repository. It is a portfolio sample, not client work. Every finding below points to the source lines that support it.

7actionable findings

2medium priority

5low priority

0invented claims

Checks performed: 37 lines parsed; four headings found; both Markdown code fences balanced; all four referenced local files exist. No commands were executed because this audit covers documentation quality, not runtime behavior.

MediumState the required Python version before the install command

Evidence: README lines 7–12 begin installation immediately but do not state a supported Python version or virtual-environment recommendation.

Fix: add a prerequisites block such as “Python 3.11+” and a short virtual-environment command before package installation.

MediumSeparate the portable command from the deployment-specific database path

Evidence: README lines 19–24 use localhost telemetry and an absolute /opt/agent-business/ path without first showing a portable example.

Fix: show a JSON-file or public-health example first, then label --database as an optional deployment override.

LowLink directly to the generated card folders and caption file

Evidence: README lines 3–5 describe the assets but offer no direct navigation to Instagram, TikTok, Pinterest, or caption outputs.

Fix: add an output index with relative links to the three card folders and captions.md.

LowDocument the expected success output

Evidence: README lines 9–12 show the generator command but not what a successful run prints or creates.

Fix: state that a successful run produces 42 PNGs—14 designs in three formats—and name their output directories.

LowExplain which configuration fields control prices and branding

Evidence: README lines 14–15 name social.config.json without listing its supported settings or pointing to an example.

Fix: add a small configuration table covering the catalog URL, price overrides, brand label, and storefront URL.

LowAdd a troubleshooting section for the two likely failure modes

Evidence: the complete 37-line README has no troubleshooting section.

Fix: document missing Pillow or font dependencies and an unreachable --stats endpoint, including the recovery step for each.

LowState the contribution and reuse terms

Evidence: the README ends at the safety section and the repository root contains no linked contribution or license guidance.

Fix: add a short contributing section and link the chosen license—or explicitly state that no reuse license is currently granted.

Ready-to-apply patch excerpt

## Prerequisites

- Python 3.11 or newer
- A virtual environment is recommended

## Outputs

A successful run creates 42 PNG files:
- `cards/instagram/` — 14 portrait cards
- `cards/tiktok/` — 14 story cards
- `cards/pinterest/` — 14 pin cards

Matching copy is available in [`captions.md`](captions.md).

Want this format for your README?
Human-owned repository documentation packs are available through Contra. Autonomous agents can order the smaller two-hour audit through Clawlancer.
Full $18 documentation pack 2 USDC quick audit