feat: delegate composite checkpoints to glossdoc

README.md

@@ -34,6 +34,8 @@ A skill is any directory containing a `SKILL.md`. Cross-tool discovery (Cursor,
 
 This repo ships one project-local skill of its own: [`founding-doc`](.claude/skills/founding-doc/) — it produces a [Conviction Doc](docs/founding/index.html) as a `composite` doc-type, and is how this repo's own founding doc was written. It's checked in as a worked example of a chainable skill, not as part of the plugin.
 
+> **Companion plugin — [glossdoc](https://github.com/jyliang/glossdoc).** Flow is *process*; glossdoc is *representation*. When a step binds a `composite` (`format: html`) doc-type, the run hands its checkpoint to the glossdoc skill, which renders one source through many *glosses* (lenses) — the same fragments a human reads in a browser and a machine parses on disk. Install it (`glossdoc@glossdoc`) to get composite checkpoints; without it, flow falls back to markdown.
+
 ## Core concepts
 
 Six words run everything.

bin/flow

@@ -459,17 +459,17 @@ cmd_resume() {
   if [ -z "$from" ]; then
     local last
     last="$(ls "$rundir" 2>/dev/null | grep -E '^[0-9]{2}-' | sed 's/-.*//' | sort -n | tail -1)"
-    [ -n "$last" ] || die "no NN-*.md checkpoints in $rundir"
+    [ -n "$last" ] || die "no NN-* checkpoints in $rundir"
     from="$last"
   fi
   case "$from" in [0-9]) from="0$from" ;; esac
   case "$from" in *[!0-9]*) die "--from must be a number like 03" ;; esac
 
-  ls "$rundir"/"$from"-*.md >/dev/null 2>&1 || die "no checkpoint $from-*.md in $rundir"
+  ls -d "$rundir"/"$from"-* >/dev/null 2>&1 || die "no checkpoint $from-* in $rundir"
 
   printf 'from=%s\nat=%s\n' "$from" "$(date -u +%Y-%m-%dT%H-%M)" > "$rundir/.resume"
 
-  local cp; cp="$(basename "$(ls "$rundir"/"$from"-*.md | head -1)")"
+  local cp; cp="$(basename "$(ls -d "$rundir"/"$from"-* | head -1)")"
   say "✓ marked $rundir to resume from checkpoint $from ($cp)."
   say ""
   say "Edit that checkpoint to fork, then in Claude Code run:"

templates/protocol-spike.md

@@ -18,7 +18,7 @@ For step `NN` (its skill → its doc-type) in chain order:
 
 1. **Do the work.** Invoke the step's skill, passing the previous checkpoint as input.
 2. **Decide for yourself.** When the skill needs a decision, take the `(Recommended)` option, else the first reasonable one. Append the decision and a one-line rationale to `spike-log.md`.
-3. **Capture the result** as the step's doc-type and write it to `.flow/runs/{{FLOW}}/<run>/NN-<doc-type>.md` (NN zero-padded).
+3. **Capture the result** as the step's doc-type, by its **format**: **markdown** → write `.flow/runs/{{FLOW}}/<run>/NN-<doc-type>.md` (NN zero-padded); **html** → hand the content to the **glossdoc** skill and capture it as a composite directory `NN-<doc-type>/` (fall back to markdown if glossdoc isn't installed).
 
 ### On completion
 

templates/protocol-step.md

@@ -14,16 +14,18 @@ Establish the run, then advance through the chain in `## The chain` order, writi
 Steps are numbered in `## The chain`. For step `NN` (its skill → its doc-type):
 
 1. **Do the work.** Invoke the step's skill, passing the previous checkpoint document as its input.
-2. **Capture the result** as the step's doc-type, following that doc-type's template in `## Doc-type contracts`. Write it to `.flow/runs/{{FLOW}}/<run>/NN-<doc-type>.md` (NN zero-padded: `01`, `02`, …).
+2. **Capture the result** as the step's doc-type, following its template in `## Doc-type contracts`. Where it lands depends on that doc-type's **format** (shown in the contract):
+   - **markdown** → write `.flow/runs/{{FLOW}}/<run>/NN-<doc-type>.md` (NN zero-padded: `01`, `02`, …).
+   - **html** (a composite) → hand the content to the **glossdoc** skill and capture it as a directory `.flow/runs/{{FLOW}}/<run>/NN-<doc-type>/` — an HTML host plus `sections/*.md`, read over HTTP via its `serve.sh`. The directory *is* the checkpoint. If glossdoc isn't installed, fall back to the markdown form and say so.
 3. **Pause at the checkpoint.** Ask the human via `AskUserQuestion`:
    - **Yes, advance** — move to the next step.
-   - **Adjust** — the human edits `NN-<doc-type>.md`; re-read the file and continue from their version.
+   - **Adjust** — the human edits the checkpoint (`NN-<doc-type>.md`, or the fragments under `NN-<doc-type>/`); re-read it and continue from their version.
    - **Pause** — stop here. Tell them to resume with `/flow:{{FLOW}}-step`, or `flow resume {{FLOW}}/<run> --from <next NN>`.
-4. When the final step's checkpoint is approved, the run is complete. Report the trail of checkpoint files.
+4. When the final step's checkpoint is approved, the run is complete. Report the trail of checkpoints (files and composite directories).
 
 ### Rules
 
-- **DO** write each checkpoint to a file *before* pausing — the trail is the state.
+- **DO** write each checkpoint (a file, or a composite directory) *before* pausing — the trail is the state.
 - **DO** re-read a checkpoint after the human adjusts it; their edit is authoritative.
 - **DO** carry each checkpoint forward as the next skill's input.
 - **DO NOT** skip a pause, judge the skill's output quality, or edit the chained skills.