thurview 0.16.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thurview",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Guided, evidence-anchored reviews of agent-written code. A coding agent authors the review; you read, ask, comment and decide in the browser.",
   "license": "MIT",
   "type": "module",

package/skills/thurview/references/components.md

@@ -170,6 +170,53 @@ Rules:
    against added lines in the pinned diff. Listing a frame on one side only
    for contrast is rejected.
 
+## flow
+
+````markdown
+```flow
+label: Sign in
+steps:
+  - { id: land,  label: Visitor opens /login, actor: visitor, next: post }
+  - { id: post,  label: Credentials posted,   anchor: loginRoute, next: check }
+  - { id: check, label: Credentials valid?,   anchor: checkUser,
+      when: [{ case: valid, to: home }, { case: rejected, to: retry }] }
+  - { id: retry, label: Error shown,          anchor: renderError, next: post }
+  - { id: home,  label: Dashboard,            anchor: dashboard }
+```
+````
+
+A user journey and where it branches - the shape `sequence` cannot hold,
+because a decision is not a message. The first step is the entry; a step
+continues with `next` or branches with `when`, and one with neither ends the
+flow. Cycles are fine: a retry loop is what a journey does, and a step that
+leads back up is drawn down a lane on the right, one lane per loop so two
+retries never share a vertical run.
+
+Every step is either code or a person: `anchor` is where the code does it and
+the reader opens it by clicking, `actor` is a declared actor doing it outside
+the code, and a step carries at least one of the two. An actor-only step is
+drawn dashed, so the reader can see at a glance which parts open something.
+
+`publish` refuses:
+
+1. A step with neither `anchor` nor `actor`, and a block where no step has an
+   `anchor` at all - a flow nothing opens is prose in a box.
+2. `next` and `when` on one step, and a `when` with a single case. One is a
+   branch, the other is a `next`.
+3. A `next` or `to` naming a step the block does not declare, or naming itself.
+4. A step unreachable from the first one, a duplicate `id`, an unknown `actor`,
+   and an anchor with no `peek`.
+
+## Fences thurview does not render
+
+`mermaid`, `plantuml`, `puml`, `dot`, `graphviz` and `d2` in a document body are
+a publish error. They used to be neither components nor an error, so the block
+reached the reader as its own source text with nothing saying so. thurview draws
+only what it can anchor at the pinned commit: use `flow` for a journey and
+`sequence` for a message exchange. To quote one of those languages as source -
+reviewing a change to a repository's own diagrams - fence it as `text`, which
+renders as the code block it is.
+
 ## database
 
 ````markdown

package/skills/thurview/references/document-authoring.md

@@ -142,11 +142,14 @@ A claim you cannot anchor is a question, not a fact. Write it as one.
 Use the fenced components for behaviour that prose explains badly:
 
 - `sequence` for temporal behaviour across actors
+- `flow` for a user journey and where it branches
 - `callstack` for call-flow differences between base and head
 - `database` for persisted-state structure and the operations on it
 
-Each message, frame and operation carries an anchor, so the reader can open
-the code behind every arrow. See [Components](components.md).
+Each message, frame, step and operation carries an anchor, so the reader can
+open the code behind every arrow. `mermaid` and the other general diagram
+languages are a publish error rather than a fifth option: thurview draws only
+what it can anchor. See [Components](components.md).
 
 Add a diagram only when it materially helps. A document with one good
 sequence diagram beats one with four.