shopdb-flask/docs/GUIDES.md

Guides: writing procedures in ShopDB, and generating them from elsewhere

A guide is a step-by-step procedure stored in ShopDB: images, working checklists, version history, and printable output. This is the reference for the data model and the API, aimed at somebody generating guides programmatically - from a script, an importer, or a model.

Not the knowledgebase plugin, which is a link registry pointing at documents held somewhere else. That one references documents; this one holds them. They share only a tag vocabulary and the global search box.

---

1. The shape of a guide

A guide is an ordered list of typed blocks, stored as JSON. Not HTML, and that is load-bearing:

• a tickable step needs a stable id to be remembered between visits
• dark mode needs semantic markup, not pasted colours
• print needs to know where a step begins so it does not split one across a page

Free-form HTML gives none of those, and pasted styling fights the theme.

Block types

type	Fields	Notes
heading	text	Section heading
paragraph	text	Body text
step	title, text	Numbers itself by position among steps
checklist	items[]	The tickable one. Items need their own ids
bullets	items[]	Unordered list
numbers	items[]	Ordered list
callout	text, title, variant	variant: info, warning, success
code	text, language, caption	Never autocorrected; wraps rather than clips
image	url, alt, caption	url comes from the image upload endpoint
table	header[], rows[][]	Simple grid

Every block needs:

{ "id": "b1", "type": "paragraph", "text": "..." }

Ids must be unique and stable. They are what a reader's tick is stored against, so a save without them is refused, and changing one loses that item's progress. Checklist items carry their own ids for the same reason:

{ "id": "b4", "type": "checklist",
  "items": [ { "id": "i1", "text": "Confirm the Verified date" } ] }

An unknown block type renders as nothing rather than an error, so a guide written against a newer version stays readable on an older one.

Inline text

Block text supports a deliberately small subset: **bold**, *italic*, `code`, [links](https://example.com), and line breaks. Nothing else - no fonts, sizes or colours. Emphasis is semantic and the theme decides how it looks, which is what makes dark mode work and keeps a guide written next year matching one written today.

Text is escaped before formatting is applied, so no markup in the source can reach the DOM. javascript: and data: links are dropped.

---

2. Creating a guide from a script

Every endpoint is listed in docs/api-inventory.json; this is the workflow.

# 1. Create - always starts as a draft
curl -X POST http://localhost:5001/api/guides \
  -H "Authorization: Bearer $TOK" -H 'Content-Type: application/json' \
  -d '{
    "title": "Replace a part marker controller",
    "summary": "Restoring patterns and settings after a swap",
    "tags": "partmarker, backups",
    "blocks": [
      {"id":"b1","type":"paragraph","text":"The new unit arrives **empty**."},
      {"id":"b2","type":"callout","variant":"warning","title":"Before you start",
       "text":"Check the marking head."},
      {"id":"b3","type":"checklist","items":[
        {"id":"i1","text":"Copy the snapshot path"},
        {"id":"i2","text":"Confirm the pattern count"}]}
    ]
  }'

# 2. Publish - readers see nothing until this happens
curl -X POST http://localhost:5001/api/guides/12/publish \
  -H "Authorization: Bearer $TOK"

$TOK is a login JWT or a scoped API token; they work the same way here.

What the server rejects

Validation happens at the door rather than at render time, because a malformed guide stored is a page that fails every time somebody opens it, long after the client bug that caused it:

• a block with no id, or a duplicate id
• an unknown block type (the error lists the known ones)
• a checklist item with no id
• more than 500 blocks, or more than 2 MB of blocks
• text longer than 20,000 characters in one block

Errors name the offending block by position: block 3: needs a stable id.

---

3. Drafts, versions and publishing

Three separate things, and the distinction is what stops a live procedure changing under somebody following it:

	What it is
Working copy	The guides row. What the editor loads and saves
Revisions	Immutable snapshots in guiderevisions, written when content changes
Published pointer	Which revision READERS get

• PUT /api/guides/<id> saves the working copy and writes a revision only if the content hash changed. An autosave that changed nothing records nothing, so the history stays readable. The response carries saved: false.
• The hash covers title, summary, tags and blocks - renaming or retagging is a change a reader notices.
• POST /api/guides/<id>/publish promotes an existing revision. It does not snapshot, so a publish cannot ship unsaved edits nobody reviewed.
• POST /api/guides/<id>/restore/<revisionid> brings old content back as a new revision. History is never rewritten.
• Drafts are invisible to readers, to GET /api/guides/<slug> (404, not 403), and to global search.

---

4. Images

curl -X POST http://localhost:5001/api/guides/images \
  -H "Authorization: Bearer $TOK" -F file=@screenshot.png -F guideid=12

Returns {"url": "/api/guides/images/5", ...} for use as an image block's url. PNG, JPEG, GIF and WebP, up to 8 MB. guideid is optional because an image is pasted before a new guide has an id.

Bytes live in the database, not on disk: a row travels with a database backup, whereas a file under instance/ has been lost to a container rebuild on this deployment before.

Known gap: images uploaded to a guide that is then abandoned are never pruned.

---

5. Proofing

The editor runs checks continuously and warns rather than blocking. They exist because none of these are spelling mistakes:

• a smart quote or long dash in a code block - autocorrect does this, the command then fails, and it still looks right to the author (one-click fix)
• an empty checklist item, which reads as a step somebody forgot to write
• a heading with nothing under it, left behind by a reorganise
• an image with no alt text
• a leftover TODO, TBD or FIXME
• no summary or tags, which makes a guide hard to find

Publishing with unresolved errors asks for confirmation; it does not refuse. A procedure that exists imperfectly beats one nobody wrote.

---

6. Printing

Print always renders light, whatever the screen theme, because a dark page lays a full sheet of toner down and knocks the text out in white. Buttons and progress bars are dropped, steps and code blocks are kept whole across page breaks, code wraps rather than clips, and checkboxes print empty even where ticked on screen - a printout is a worksheet somebody ticks by hand. The footer carries the version and the print date, so a stale copy on a noticeboard is spottable.

---

7. Permissions

Permission	Allows
guides.view	Read guides
guides.create	Create, and edit your OWN guide while it is unpublished
guides.edit	Edit any guide, including published ones
guides.publish	Publish or withdraw
guides.delete	Delete

The split between edit and publish is deliberate: a technician can write a procedure up while somebody else decides it is fit for the floor.

---

8. Converting existing documents

There is no importer; conversion is a script you write against section 2. What to expect from a source format:

• Structured HTML and Markdown convert cleanly - headings, fenced code, lists, tables and callout divs all have matching block types. The GE Aerospace KB template's alert alert-warning divs map to warning callouts, code-block to code blocks, step divs to steps.
• Plain-text runbooks convert poorly. ASCII underlines and hand-indented lists carry no structure, so everything lands as paragraphs and a person marks up the steps afterwards. Worth doing anyway - the text is then searchable and versioned - but budget the cleanup.
• Generate ids yourself and keep them stable across re-imports, or every re-import resets readers' progress.

---

See also

• docs/api-inventory.json - every endpoint with auth, params and an example
• plugins/guides/services/blocks.py - the validation rules, and why each exists
• plugins/guides/services/authoring.py - the single write path