snapdocs 1.0.0
Screenshot to Documentation - Simple variant
Techlosoft desktop command-line tool (Windows / macOS / Linux)
==============================================================================

WHAT IT IS
------------------------------------------------------------------------------
snapdocs turns a folder of screenshots plus a small plain-text steps file into
one finished documentation file.

The headline output is a SINGLE, FULLY SELF-CONTAINED HTML document: every
screenshot is embedded directly in the file as a base64 data: URI and all CSS
is inlined. There are no external references of any kind - no <script>, no
<link>, no @import, no url(), no http:// or https://. You can email the file,
put it on a USB stick, or open it on a machine with no network, and it just
works.

A Markdown mode is also provided for wikis and repositories.

snapdocs is a desktop command-line tool. It is not a web application and it
has no browser component.


WHAT IT DOES *NOT* DO (READ THIS FIRST)
------------------------------------------------------------------------------
snapdocs DOES NOT CAPTURE SCREENSHOTS. You supply the images.

Use whatever your operating system already gives you (Win+Shift+S on Windows,
Cmd+Shift+4 on macOS, or any capture utility), save the images into one folder,
and point snapdocs at that folder. snapdocs reads images; it never talks to the
screen, the window server, or the clipboard.

The following are ROADMAP items. They are NOT implemented in 1.0.0, because
each one needs operating-system screen-capture or vision APIs that this
release deliberately does not link against:

  - Native screen capture (full screen, window, or region) from inside snapdocs
  - Scrolling / full-page capture that stitches a long window into one image
  - OCR of screenshot text, and searching or indexing that text
  - Automatic step numbering and callout arrows derived from click coordinates
  - Cursor / click highlighting, blur-out of sensitive regions, annotation
  - Video or GIF capture, and frame extraction from a recording
  - PDF output

Also not implemented in 1.0.0:

  - Recursive scanning of subdirectories (only the top level of <dir> is read)
  - Image resizing, cropping, compression or format conversion; images are
    embedded and copied BYTE FOR BYTE exactly as you supplied them
  - Templates or user-supplied CSS themes; the HTML style is fixed
  - Localisation; all output text is English


WHAT *IS* IMPLEMENTED
------------------------------------------------------------------------------
  - snapdocs init   : scan a folder and write a starter steps file
  - snapdocs check  : validate a steps file against the folder before building
  - snapdocs build  : write the finished HTML or Markdown document
  - Input formats   : PNG, JPEG (.jpg and .jpeg), GIF
  - Output formats  : self-contained HTML, or Markdown + an images/ folder
  - Dry run by default on everything that writes; --apply commits
  - Refuses to overwrite an existing output file unless --force is given, and
    even then the old file is renamed aside, never deleted
  - Every image is really decoded before use, so a text file named "shot.png"
    is reported as an error instead of being embedded as garbage
  - Step titles and bodies are HTML-escaped, so angle brackets and ampersands
    in your text cannot break or inject into the document


INSTALL
------------------------------------------------------------------------------
Pre-built binaries are in dist/:

  dist/snapdocs-windows-amd64.exe   Windows 10/11, 64-bit
  dist/snapdocs-darwin-arm64        macOS, Apple silicon
  dist/snapdocs-darwin-amd64        macOS, Intel
  dist/snapdocs-linux-amd64         Linux, 64-bit

There is nothing to install. Copy the binary somewhere on your PATH and run it.
It has no runtime dependencies: no interpreter, no DLLs, no network access.

To build from source (Go 1.24 or newer, no third-party modules required):

  go build -o snapdocs .


QUICK START
------------------------------------------------------------------------------
  1. Take your screenshots and save them all into one folder, named so that
     they sort into the right order, e.g. 01-open.png, 02-settings.png ...

  2. Generate a starter steps file:

       snapdocs init ./shots            (dry run - shows what it would write)
       snapdocs init ./shots --apply    (writes ./shots/steps.txt)

  3. Open steps.txt in any text editor and fill in the titles and bodies.

  4. Validate:

       snapdocs check ./shots --steps steps.txt

  5. Build:

       snapdocs build ./shots --steps steps.txt --out guide.html \
           --title "Pairing a Bluetooth Mouse" --author "IT Support"
       (dry run - shows exactly what it would write, writes nothing)

       ...add --apply to actually write guide.html.


COMMANDS
------------------------------------------------------------------------------
  snapdocs init  <dir> [--steps <file>] [--force] [--apply]

      Scans the top level of <dir> for images in sorted (byte-order) file-name
      order and writes a starter steps file containing one stanza per image,
      with the filename filled in and the title and body left blank.
      DRY RUN unless --apply is given.
      Refuses to replace an existing steps file unless --force is given; with
      --force the old file is renamed to <name>.bak-<timestamp> first.
      Files with an image extension that do not actually decode are reported
      as warnings and left out of the steps file.

  snapdocs check <dir> --steps <file>

      Read-only. Validates the steps file against the folder and reports every
      problem it finds. Exits 0 when clean, 1 when any problem is found.
      Problem classes reported:

        [missing-image]        a step references an image that is not in <dir>
        [unreferenced-image]   an image is in <dir> but no step references it
        [empty-title]          a stanza has an empty or whitespace-only title
        [duplicate-reference]  two or more steps reference the same image
        [unreadable-image]     a file has an image extension but does not
                               decode as PNG/JPEG/GIF

  snapdocs build <dir> --steps <file> --out <file> [options]

      Reads the steps file, pairs each stanza with its image, and writes the
      document. DRY RUN unless --apply is given: without --apply nothing at
      all is created and the exact list of paths it would write is printed.

      Steps appear in the document in STEPS-FILE ORDER, not directory order.
      Reorder the stanzas in the steps file to reorder the document.

      build refuses to start if any referenced image is missing or unreadable.
      Unreferenced images and duplicate references are printed as warnings but
      do not stop the build; run check for the full report.


OPTIONS
------------------------------------------------------------------------------
  --steps <file>   Steps file to read (build/check) or write (init).
                   Default "steps.txt". A relative path is tried as given
                   first, then relative to <dir>.
  --out <file>     Path of the document to write. Required by build.
  --format <fmt>   "html" (default) or "md". If --format is not given, it is
                   inferred from the --out extension: .md and .markdown mean
                   Markdown, anything else means HTML.
  --title <T>      Document title. Default "Documentation".
  --author <A>     Author line printed under the title. Optional.
  --force          Allow existing output paths to be replaced. Each old file
                   is renamed to <name>.bak-<timestamp> first; snapdocs never
                   deletes anything.
  --apply          Actually write files. Without it, nothing is created.
  -h, --help       Show help on stdout and exit 0. Also "snapdocs help".

Bad invocations print the usage text to stderr and exit 1.
Flags may be given before or after the <dir> argument.


STEPS-FILE FORMAT
------------------------------------------------------------------------------
Plain text, hand-editable, no YAML or JSON. One stanza per step; stanzas are
separated by one or more blank lines. A stanza is a set of "key: value" lines.
Three keys are recognised:

    image: shot1.png       (required) file name of the screenshot, relative
                           to <dir>. One line, no path separators needed.
    title: Open Settings   (required) short heading for the step.
    body:  Press Win+I...  (optional) explanatory text for the step.

Rules:

  - A line that does not begin with image:, title: or body: is treated as a
    CONTINUATION of the previous key's value, so bodies may span many lines.
    Continuation lines are joined with a line break in the output.
  - A blank line ENDS the stanza. To make a new paragraph inside one body,
    keep writing continuation lines - do not use a blank line, because that
    would start a new step.
  - Lines whose first non-space character is # are comments and are ignored.
  - Keys are case-insensitive; leading and trailing whitespace is trimmed.
  - Giving the same key twice inside one stanza is an error (it almost always
    means a missing blank line between two steps).

Complete example:

    # Pairing a Bluetooth mouse
    image: shot1.png
    title: Open Settings
    body: Press Win+I to open the Settings app.

    image: shot2.png
    title: Choose Bluetooth
    body: Click "Bluetooth & devices" in the left sidebar.
      The pane on the right refreshes to show your paired devices.

    image: shot3.png
    title: Add a device
    body: Click the "Add device" button at the top of the pane.


OUTPUT FORMATS
------------------------------------------------------------------------------
html (default)

    ONE file. Nothing else is written. Every image is embedded as
    <img src="data:image/png;base64,...."> (or image/jpeg, or image/gif) and
    the stylesheet is inlined in a single <style> block. The document contains
    a numbered contents list, a numbered step for each stanza with its title,
    body and screenshot, and a caption under each image giving the original
    file name, pixel dimensions and file size. It prints sensibly and has a
    dark-mode variant that follows the reader's system setting.

    Because everything is inlined, the HTML file is roughly 4/3 the size of
    the images it contains, plus a few kilobytes.

md

    Two things are written: the .md file, and an "images" FOLDER created
    BESIDE the .md file. Each referenced screenshot is copied into that folder
    byte for byte, and linked from the Markdown as images/<name>. This is the
    layout Git repositories and wikis expect. Markdown output is therefore
    NOT self-contained - if you move the .md file, take the images folder
    with it. If you need one portable file, use the HTML format.


SAFETY MODEL
------------------------------------------------------------------------------
  - init and build are DRY RUNS by default. Without --apply they create
    nothing and modify nothing; they only print what they would do.
  - check never writes anything at all, with or without any flag.
  - An output path that already exists is REFUSED. build exits 1 and writes
    nothing, listing the paths that are in the way.
  - --force permits replacement, but the existing file is RENAMED to
    <name>.bak-<timestamp> before the new one is written. snapdocs contains
    no delete operation; it never removes a file.
  - Source images are only ever read. They are never modified, moved,
    recompressed or resized.
  - The tool makes no network connections and reads no environment variables.


EXIT CODES
------------------------------------------------------------------------------
  0   success (including a clean check and any dry run)
  1   any error: bad arguments, unreadable directory, malformed steps file,
      missing or unreadable image, refused overwrite, or problems found by
      check


LIMITS AND KNOWN BEHAVIOUR
------------------------------------------------------------------------------
  - Only the top level of <dir> is scanned; subdirectories are ignored.
  - Recognised extensions are .png .jpg .jpeg .gif, case-insensitive. A file
    with any other extension is invisible to snapdocs even if it is an image.
  - Whole images are held in memory while the document is assembled, so a
    folder of very large screenshots needs proportionate RAM.
  - Base64 makes the HTML about 33% larger than the raw image bytes. A guide
    with 100 large screenshots produces a large HTML file; some mail systems
    reject attachments over 20-25 MB. Use the Markdown format for very big
    guides.
  - Step titles and bodies are HTML-escaped, so you cannot put your own HTML
    markup into a step. This is deliberate: it is what keeps the document
    safe to open.
  - Duplicate references and unreferenced images are warnings for build but
    errors for check, so that check can act as a strict pre-flight gate.