StepShot 1.0.0
Screenshots plus a manifest, published as a real document
Techlosoft - Screenshot to Documentation (Team variant)
==============================================================================


WHAT IT IS
------------------------------------------------------------------------------
StepShot turns a folder of screenshots plus a JSON manifest into a document you
can actually hand out.

You describe the steps once, in a manifest: which capture goes with which step,
what the step says, and where the callouts belong. StepShot numbers the steps,
DRAWS the callouts onto copies of the captures, and publishes three real,
openable files from the same source of truth:

    guide.html   ONE self-contained file. Every annotated screenshot is inlined
                 as a base64 data: URI, all CSS is inlined, there is no <script>
                 and no external reference of any kind. Email it as a single
                 attachment; it opens on a machine with no network.

    guide.docx   A genuinely valid Word document - a real OOXML package, written
                 part by part with archive/zip and hand-written XML, with the
                 annotated PNGs embedded as media parts and sized in EMUs. Every
                 build re-opens its own .docx and verifies it before exiting.

    guide.md     Markdown with relative image links, for a repository or a wiki.

Every build can append a line to a JSON-lines ledger recording the hash of the
manifest, the hash of every source capture, and the hash of every file written,
so a team can prove which document came from which captures.

StepShot is a desktop command-line tool. It is not a service and has no GUI.


HOW IT DIFFERS FROM SNAPDOCS
------------------------------------------------------------------------------
SnapDocs is the simple variant of the same job: a plain-text steps file in, one
HTML or Markdown file out, images embedded byte for byte.

StepShot is the team variant. What it adds:

  - a JSON manifest with explicit step numbers, notes and callout geometry,
    validated hard and reported with file:line:col
  - real image annotation - numbered circles, rectangles and arrows rasterised
    onto copies of the captures with an anti-aliasing rasteriser and a bitmap
    glyph set compiled into the binary
  - a .docx writer, and a .docx verifier
  - a build ledger of manifest and output checksums

Neither tool captures screenshots. Both read images you already have.


WHAT THIS DOES NOT DO - SCOPE
------------------------------------------------------------------------------
Read this before you decide StepShot is the tool for the job.

  - IT DOES NOT CAPTURE SCREENSHOTS. You supply PNG files. Use Win+Shift+S,
    Cmd+Shift+4, or any capture utility, and save into one folder. StepShot
    never touches the screen, the window server, or the clipboard.

  - NO SCROLLING OR FULL-PAGE CAPTURE, and no stitching of long windows.

  - NO PDF OUTPUT. The three formats above are the whole list. Open the HTML in
    a browser and print to PDF if you need one; the stylesheet has print rules.

  - NO OCR. StepShot does not read the text inside your screenshots, cannot
    search it, and cannot index it.

  - NO AUTOMATIC STEP DETECTION. It does not watch your clicks, infer steps
    from a recording, or place callouts for you. Every step and every callout
    coordinate is something you wrote in the manifest. StepShot's job is to
    render what you specified, correctly and repeatably.

  - NO REDACTION, BLURRING OR CROPPING. If a capture shows a password, StepShot
    will faithfully publish the password. Redact before you point it at them.

  - PNG INPUT ONLY. JPEG, GIF, WebP, BMP and TIFF are not decoded. A file with
    a .png name that is not a PNG is reported as an error, not embedded as
    garbage.

  - THE DOCX IS A DOCUMENTED MINIMAL OOXML SUBSET. It contains exactly five
    kinds of part: [Content_Types].xml, _rels/.rels, word/document.xml,
    word/_rels/document.xml.rels and word/media/imageN.png. There is NO
    styles.xml, so there is no styles gallery and no Heading 1/Heading 2 that
    Word's navigation pane or a table of contents field could pick up -
    headings are direct character formatting (bold, size, colour) on ordinary
    paragraphs. There are also no tables, no headers or footers, no page
    numbers, no footnotes, no numbering.xml (the step numbers are literal text,
    not a Word list), no theme, no fonts part, no document properties, and no
    hyperlinks. The written contents list is plain paragraphs, not a TOC field.
    Page setup is fixed at US Letter portrait with one-inch margins.

  - THE BITMAP GLYPHS ARE DIGITS AND ASCII ONLY. Callout labels are drawn from
    a 5x7 bitmap font compiled into the binary - no font file is read and no
    text-shaping library is linked. The set covers printable ASCII only: the
    space, the digits 0-9, the uppercase letters A-Z, and all 32 ASCII
    punctuation marks. LOWERCASE IS FOLDED TO UPPERCASE, so a label written
    "Toggle" is drawn "TOGGLE". ANYTHING ELSE - accented letters, CJK, emoji,
    any non-ASCII rune - is drawn as a hollow box and counted in the build
    summary. This affects only text drawn INTO the image; the step titles,
    bodies and notes in the HTML, DOCX and Markdown are full Unicode and
    entirely unaffected.

  - NO TEMPLATES OR THEMES. The HTML stylesheet and the DOCX formatting are
    fixed. Output text is English.

  - NO NETWORK, NO TELEMETRY, NO ENVIRONMENT VARIABLES. StepShot reads its
    arguments, the manifest and the images, and writes into --out-dir and the
    --ledger file. Nothing else.

  - IT NEVER MODIFIES OR DELETES YOUR SOURCE IMAGES. Callouts are drawn onto
    in-memory copies and written to the output directory. The program contains
    no delete operation at all, and opens the images directory read-only.


INSTALL
-------------------------------------------------------------------------------
Pre-built binaries are in dist/. There is nothing to install - copy the one for
your platform anywhere on your PATH and run it.

    dist/stepshot-linux-amd64        Linux, x86-64
    dist/stepshot-darwin-arm64       macOS, Apple Silicon
    dist/stepshot-darwin-amd64       macOS, Intel
    dist/stepshot-windows-amd64.exe  Windows, x86-64

On macOS and Linux you may need to mark it executable:

    chmod +x stepshot-linux-amd64

To build from source you need Go 1.24 or newer. There are no dependencies of
any kind and no cgo, so no network access is required:

    go build -o stepshot .


COMMANDS
========

    stepshot check  --manifest <file.json> [--strict] [--json]

    stepshot build  --manifest <file.json> --out-dir <dir>
                    [--format html,docx,md] [--name <base>]
                    [--ledger <file.jsonl>] [--force] [--json]

    stepshot verify <file.docx> [--json]

    stepshot ledger --ledger <file.jsonl> [--json]

    stepshot help | -h | --help

check
    Read-only. Validates the manifest against the image folder and prints every
    problem it finds, located at file:line:col inside the manifest wherever the
    offset is known. Exits 1 if any ERROR was found, 0 if there were only
    warnings. --strict makes warnings count as errors too.

build
    Decodes each referenced PNG, draws that step's callouts onto a copy,
    re-encodes it, and writes the annotated PNGs plus one document per
    requested format. Steps appear in the document in DECLARED STEP-NUMBER
    order, not in the order they happen to sit in the JSON.

    build refuses to start if check would report any error.
    build refuses to overwrite an existing output file unless --force is given,
    and refuses as a whole: if one path is in the way, nothing is written.

verify
    Opens an existing .docx, lists its parts, and checks that every required
    part is present, that every XML part parses with encoding/xml, that every
    media part really is a PNG, and that every relationship id referenced by
    word/document.xml resolves to a declared relationship whose target exists
    inside the package. Exits 1 if anything does not hold.

ledger
    Lists the build records recorded so far.

FLAGS

    --manifest <file>  The JSON manifest (check, build). Short form -m.
                       A bare positional argument works too.
    --out-dir <dir>    Where build writes. Created if missing. Short form -o.
    --format <list>    Comma-separated: html, docx, md. Default all three.
                       "markdown" is accepted as a synonym for "md".
                       Short form -f.
    --name <base>      Base file name for the documents. Defaults to the
                       manifest's file name without its extension, so
                       guide.json produces guide.html/.docx/.md. Short form -n.
    --ledger <file>    Append one JSON line per build to this file.
    --force            Permit replacing existing output files.
    --strict           check only: treat warnings as errors.
    --json             Machine-readable output (check, build, verify, ledger).

Flags may appear before or after positional arguments; either order works.


QUICK START
===========

    # 1. Put your captures in one folder, named so they sort sensibly.
    #    shots/01-open-settings.png, shots/02-choose-account.png, ...

    # 2. Write a manifest next to it (see MANIFEST FORMAT below).

    # 3. Validate before you build.
    stepshot check --manifest guide.json

    # 4. Publish all three formats, and record the build.
    stepshot build --manifest guide.json --out-dir dist \
        --format html,docx,md --ledger builds.jsonl

    # 5. Prove the Word file is sound (build already did this for you).
    stepshot verify dist/guide.docx

A complete worked example ships in example/. The screenshots there are
generated, not captured - regenerate them at any time with:

    go run ./fixturegen -out ./example/shots


MANIFEST FORMAT
===============

One JSON object. Unknown fields are rejected, so a typo is an error rather than
a silently ignored setting.

    {
      "title":      "Enrolling a Workstation in Two-Factor Authentication",
      "author":     "Techlosoft IT Support",          (optional)
      "intro":      "Read this first...",             (optional)
      "images_dir": "shots",                          (optional)
      "steps": [
        {
          "number": 1,
          "image":  "01-open-settings.png",
          "title":  "Open the Security settings",
          "body":   "Launch the portal.\n\nSecond paragraph.",   (optional)
          "note":   "Only visible to admins.",                   (optional)
          "callouts": [                                          (optional)
            { "kind": "circle", "x": 95,  "y": 90,  "r": 22 },
            { "kind": "rect",   "x": 8,   "y": 44,  "w": 174, "h": 30,
              "color": "blue" },
            { "kind": "arrow",  "x": 560, "y": 420, "x2": 790, "y2": 320,
              "label": "Toggle", "color": "green" }
          ]
        }
      ]
    }

TOP LEVEL

    title       Required. The document heading.
    author      Optional. Printed under the title.
    intro       Optional. Blank lines start new paragraphs.
    images_dir  Optional. Where the images live, relative to the manifest file
                (or absolute). Defaults to the manifest's own directory.
    steps       Required, non-empty.

STEP

    number      Required, 1 or greater. Must be unique. Determines document
                order and the number printed in the guide.
    image       Required. A file name relative to images_dir. It may not be
                absolute and may not escape the directory with "..".
    title       Required, non-empty.
    body        Optional. "\n\n" starts a new paragraph, "\n" is a line break.
    note        Optional. Rendered as a highlighted aside.
    callouts    Optional list, drawn in the order given.

CALLOUT

    kind        "circle", "rect" or "arrow". Defaults to "circle".
    x, y        For circle: the CENTRE. For rect: the TOP-LEFT corner.
                For arrow: the TAIL, the end you draw from.
    r           circle only. Radius in pixels. Default 20.
    w, h        rect only. Both must be positive.
    x2, y2      arrow only. The HEAD - where the arrowhead is drawn.
    label       Text drawn inside a circle or beside an arrow. Circles are
                auto-numbered 1, 2, 3... within their own step when no label
                is given. Remember the glyph set is ASCII only.
    color       "#rrggbb", "#rgb", "#rrggbbaa", or one of: red (default),
                orange, yellow, green, blue, purple, magenta, black, white,
                grey.

ALL COORDINATES ARE PIXELS IN THE SOURCE IMAGE, with (0,0) at the top-left.
They are not percentages and not points, and they do not scale with the size
the image is displayed at.


WHAT check REPORTS
==================

ERRORS - build refuses to run while any of these stands

    [unparseable-manifest]    the file is not valid JSON, or a field has the
                              wrong type; reported at file:line:col
    [empty-document-title]    no "title" at the top level
    [no-steps]                the steps list is empty
    [bad-step-number]         a step number is 0 or negative
    [duplicate-step-number]   two steps claim the same number; the message
                              points at the other one
    [empty-title]             a step has a blank title
    [missing-image]           a step names an image that is not in the folder,
                              or names no image at all
    [unreadable-image]        the file is there but is not a decodable PNG,
                              or is a directory
    [image-outside-folder]    the image path is absolute, or climbs out of
                              images_dir with ".."
    [missing-images-dir]      images_dir does not exist or is not a directory
    [bad-callout-kind]        kind is not circle, rect or arrow
    [bad-callout-size]        a rectangle with a non-positive side, a circle
                              with a negative radius, a zero-length arrow
    [bad-callout-color]       the colour string does not parse
    [callout-out-of-bounds]   a defining point (circle centre, rectangle
                              corner, arrow tail or head) is outside the
                              image, checked against the REAL decoded pixel
                              dimensions

WARNINGS - reported, but the build goes ahead

    [orphan-image]            a .png in images_dir that no step references.
                              This is the check that catches the capture you
                              forgot to write a step for.
    [duplicate-image]         two steps use the same capture
    [callout-clipped]         the shape fits its anchor point but spills over
                              the edge of the image and will be clipped

Use --strict to make check fail on warnings, for example in a review gate.


HOW THE ANNOTATION IS DRAWN
===========================

The source PNG is decoded with image/png and copied into a fresh RGBA buffer
with image/draw. Everything after that is drawn into the copy. The source file
is never reopened for writing.

Shapes are rasterised by StepShot's own code, not by a graphics library:

  circle      A white halo disc, the filled disc in the callout colour, then a
              darker ring. Coverage per pixel is computed from the distance to
              the centre with a one-pixel linear ramp, which is where the
              anti-aliasing comes from.
  rect        A signed distance to the rectangle border, same one-pixel ramp,
              drawn twice: a soft white halo underneath and the coloured
              stroke on top, so the box stays visible over a busy screenshot.
  arrow       The shaft is a distance-to-line-segment stroke with round caps.
              The head is a real filled triangle, evaluated with three edge
              functions at 4x4 supersampling, and the shaft stops where the
              head begins so the join stays crisp.
  label       Digits and letters come from a 5x7 bitmap glyph table compiled
              into the binary, scaled to fit inside the marker. Circle text is
              black or white depending on the luma of the fill colour, so a
              light and a dark callout are both readable.

The annotated image is re-encoded as PNG and written to <out-dir>/media/, named
step-NN-<original name>.png. Nothing is resized: the annotated copy has exactly
the pixel dimensions of the original.


THE DOCX PACKAGE
================

The file is a zip containing exactly:

    [Content_Types].xml            Defaults for rels, xml and png, plus the
                                   Override for the main document part
    _rels/.rels                    rId1 -> word/document.xml (officeDocument)
    word/document.xml              the whole body
    word/_rels/document.xml.rels   rIdN -> media/imageN.png, one per step
    word/media/imageN.png          the annotated captures, byte for byte the
                                   same PNGs written into <out-dir>/media/

Images are inline drawings sized in EMUs. Source pixels are treated as 96 dpi
(9525 EMU per pixel) and an image wider than the 6.5-inch content column is
scaled down proportionally. All text is escaped with encoding/xml, and code
points that are illegal in XML 1.0 are dropped rather than written out to
produce a file Word would refuse.

Every part is stamped with a fixed 1980-01-01 timestamp, so two builds from
unchanged inputs produce a byte-identical .docx and therefore an identical
ledger checksum.

Because there is no styles.xml, do not expect Word's navigation pane, an
automatic table of contents, or the styles gallery to be populated. See the
SCOPE section above for the full list of what the subset leaves out.

VERIFICATION IS NOT OPTIONAL. After writing the .docx, build reads it back off
disk and checks it. If anything fails, build reports the problems and exits 1.
The same check is available on any .docx as `stepshot verify`.


THE BUILD LEDGER
================

--ledger appends one JSON object per line, never rewriting earlier lines:

    {"ts":"2026-08-11T07:09:50Z","tool":"stepshot 1.0.0",
     "manifest":"example/guide.json","manifest_sha256":"738e92...",
     "title":"Enrolling a Workstation...","steps":4,"out_dir":"example/dist",
     "formats":["html","docx","md"],
     "sources":[{"step":1,"image":"01-open-settings.png",
                 "source_sha256":"...","annotated":"media/step-01-....png",
                 "annotated_sha256":"...","callouts_drawn":2}],
     "outputs":[{"path":"example/dist/guide.docx","format":"docx",
                 "bytes":20345,"bytes_human":"19.9 KiB","sha256":"..."}],
     "docx_verified":true}

That is enough to answer, months later, "which captures produced the guide we
sent the customer, and has either end been altered since?" - re-hash the files
and compare. StepShot does not do the comparison for you; the record is the
feature.


EXIT CODES
==========

    0   Success. A check that found only warnings is a success.
    1   Bad invocation (unknown command, missing required flag, unknown
        format), any validation error, a refused overwrite, a .docx that
        failed verification, or an I/O error. Explicit help exits 0.

Help goes to stdout. Errors and the usage text that follows them go to stderr.


LIMITS AND KNOWN BEHAVIOUR
==========================

  - The whole set of images is held in memory while the document is assembled,
    so a guide made of very large captures needs proportionate RAM.
  - Base64 makes the HTML about 33% larger than the raw image bytes. A guide
    with a hundred large captures makes a large HTML file, and some mail
    systems reject attachments over 20-25 MB. Use the Markdown format, or
    split the guide, when it gets that big.
  - Only the top level of images_dir is scanned for orphans; subdirectories
    are not searched. A step may still reference an image in a subdirectory by
    writing "sub/shot.png".
  - Markdown output is NOT self-contained. If you move the .md file, take the
    media/ folder with it. Use the HTML format when you need one portable file.
  - Step titles and bodies are escaped in all three formats, so you cannot put
    your own HTML or Markdown markup into a step. That is deliberate: it is
    what keeps the documents safe to open and to publish.
  - Callout coordinates are validated against the real decoded dimensions of
    each image, so re-cropping a capture without updating the manifest is
    caught by check rather than producing a marker in the wrong place - but
    only if the crop actually moves the point out of bounds. StepShot cannot
    know that a marker still points at the right button.