shopdb-flask/docs/GUIDES.md

<!-- docmeta
purpose: reference
audience: developer, integrator
status: current
summary: The guides block model, API, publishing rules and limits, for creating guides from a script.
loadwith: 
-->

# 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:

```json
{ "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:

```json
{ "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.

```bash
# 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

```bash
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