" heading, followed by one "## Step N" section per image, each embedding the image as a relative Markdown image link (![Step N](relative/path/to/image.png)) and the caption text as a paragraph beneath it. Images are referenced by relative path, never as base64 data URIs, so the generated doc is meant to sit on disk alongside the real image files (unlike the single portable HTML blob SnapDocs' browser export produces). 5. With --html, also writes a standalone HTML version to <out-dir>/<folder-basename>.html, with its own <style> block and images referenced via <img src="relative/path"> using the same relative-path convention (not base64). When multiple <folder> arguments are given, each is processed independently into its own separate output document — this is the "batch" part of the value proposition: one invocation, many docs, one per input folder. DocSnap prints a per-folder summary (steps found, captions matched, output path(s)) followed by a final batch summary (N docs generated, M total steps, K captions matched vs. missing). Options: --title string Document title, used as the top-level heading. Required. --out-dir dir Directory to write generated docs into. Default: current directory. --html Also generate a standalone HTML version of each doc, alongside the Markdown. --sort name|mtime Screenshot ordering. "name" (default) sorts alphabetically by filename. "mtime" sorts by file modification time, ascending — useful when screenshots aren't consistently named. ### validate docsnap validate <folder> [<folder> ...] Read-only QA check: for each folder, reports which image files have no matching caption in captions.txt ("what's still undocumented"), without generating any doc files. A folder with images but some missing captions is informational only, not an error — matching the same graceful-partial-captions philosophy as build. A folder with zero image files IS flagged as an error and causes DocSnap to exit non-zero, since that usually means an empty or wrong folder was pointed at. ### captions.txt sidecar format A plain text file named captions.txt placed inside each screenshot folder, one line per screenshot: 01-login.png: Open the login screen and click Sign In 02-forgot.png: Select the forgot-password link under the password field 03-reset.png: Enter your new password twice and submit Format is "filename: caption text" (the first colon separates the two). Blank lines are ignored. A screenshot file with no matching line simply gets an empty caption in the generated doc. The file itself is fully optional — if it's missing entirely, DocSnap generates the doc with just step numbers and images, no captions. ## Prebuilt binaries See ../downloads/ for prebuilt binaries (Windows/macOS/Linux) and CHECKSUMS.txt for their SHA-256 hashes. These are unsigned indie builds — Windows SmartScreen and macOS Gatekeeper will warn on first run, which is expected until a code-signing certificate is in place.

# DocSnap (CLI prototype) DocSnap is a batch, headless documentation generator: point it at one or more folders of screenshots you've already captured, each with a simple captions.txt sidecar file, and it produces polished Markdown (and optionally HTML) step-by-step docs automatically, in bulk, across many folders in a single invocation. It is the scriptable/bulk counterpart to the sibling SnapDocs browser app, which is built for a person interactively dragging in and captioning screenshots one at a time in a browser tab. DocSnap targets support, QA, training, and operations teams who need to turn many screenshot folders (one per ticket, one per test case) into docs without opening a browser UI for each one. Live capture, scrolling capture, OCR, and annotation from the full product concept are still on the roadmap for this tier — SnapDocs' web build covers the interactive assembly half of the concept, and this CLI covers the batch-processing half. See ../plan.md for the full product plan. ## Build from source Requires Go 1.24+, no external dependencies. go build -o docsnap . Cross-compile for another platform: GOOS=windows GOARCH=amd64 go build -o docsnap.exe . GOOS=darwin GOARCH=arm64 go build -o docsnap . ## Usage docsnap build [ ...] --title "Doc Title" [options] docsnap validate [ ...] docsnap help ### build For each given, DocSnap: 1. Finds image files directly inside the folder (.png, .jpg, .jpeg, .gif, .bmp — case-insensitive extension match). 2. Sorts them per --sort (see below). 3. Reads captions.txt inside the folder, if present, and matches caption lines to filenames. A screenshot with no matching caption line still becomes a step, just with no caption text beneath the image — it is never skipped and never fails the build. A folder with no captions.txt at all is not an error either; every step is generated with an empty caption. 4. Writes a Markdown document to /.md: a top-level "# " heading, followed by one "## Step N" section per image, each embedding the image as a relative Markdown image link (![Step N](relative/path/to/image.png)) and the caption text as a paragraph beneath it. Images are referenced by relative path, never as base64 data URIs, so the generated doc is meant to sit on disk alongside the real image files (unlike the single portable HTML blob SnapDocs' browser export produces). 5. With --html, also writes a standalone HTML version to <out-dir>/<folder-basename>.html, with its own <style> block and images referenced via <img src="relative/path"> using the same relative-path convention (not base64). When multiple <folder> arguments are given, each is processed independently into its own separate output document — this is the "batch" part of the value proposition: one invocation, many docs, one per input folder. DocSnap prints a per-folder summary (steps found, captions matched, output path(s)) followed by a final batch summary (N docs generated, M total steps, K captions matched vs. missing). Options: --title string Document title, used as the top-level heading. Required. --out-dir dir Directory to write generated docs into. Default: current directory. --html Also generate a standalone HTML version of each doc, alongside the Markdown. --sort name|mtime Screenshot ordering. "name" (default) sorts alphabetically by filename. "mtime" sorts by file modification time, ascending — useful when screenshots aren't consistently named. ### validate docsnap validate <folder> [<folder> ...] Read-only QA check: for each folder, reports which image files have no matching caption in captions.txt ("what's still undocumented"), without generating any doc files. A folder with images but some missing captions is informational only, not an error — matching the same graceful-partial-captions philosophy as build. A folder with zero image files IS flagged as an error and causes DocSnap to exit non-zero, since that usually means an empty or wrong folder was pointed at. ### captions.txt sidecar format A plain text file named captions.txt placed inside each screenshot folder, one line per screenshot: 01-login.png: Open the login screen and click Sign In 02-forgot.png: Select the forgot-password link under the password field 03-reset.png: Enter your new password twice and submit Format is "filename: caption text" (the first colon separates the two). Blank lines are ignored. A screenshot file with no matching line simply gets an empty caption in the generated doc. The file itself is fully optional — if it's missing entirely, DocSnap generates the doc with just step numbers and images, no captions. ## Prebuilt binaries See ../downloads/ for prebuilt binaries (Windows/macOS/Linux) and CHECKSUMS.txt for their SHA-256 hashes. These are unsigned indie builds — Windows SmartScreen and macOS Gatekeeper will warn on first run, which is expected until a code-signing certificate is in place.