@eventmodelers/cli 2.0.46 → 2.0.48

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "2.0.46",
+  "version": "2.0.48",
   "description": "Eventmodelers CLI — real-time Claude agent + skills for Claude Code, for any stack (Node, Supabase, Axon, OpenCQRS, UmaDB, Kurrent, or modeling-only)",
   "type": "module",
   "bin": {

package/shared/skills/learn-eventmodelers-api/references/basics-architecture-element-types.md

@@ -36,6 +36,13 @@ INFOGRAPHIC    // Pinned infographic poster (an `infographic` chat snippet saved
 REPORT         // Pinned report chart (a `report` chat snippet saved to the board): `meta.reportJson` (the snippet's JSON
                // as a string, without `kind`/`confirm`), `meta.title`. Free-floating, view only. To change it, send a
                // `node:changed` that sets `meta.reportJson` (the `/regenerate-report` skill does).
+PDF            // A PDF pasted onto the board (Ctrl/Cmd+V of a PDF file, ≤ 2 MB): `meta.title` is the file name. The file
+               // itself is a blob in the board's image storage under the node id (like an image, `images/<nodeId>`; a
+               // `GET .../images/<nodeId>` returns the PDF bytes) — there is no text, field or data on the node.
+               // Free-floating, resizable, in no chapter or cell, never part of a slice. Ignore it when building slices,
+               // wiring edges or counting elements; it is reference material for people. To put one on the board, upload
+               // the file to `POST .../images/<nodeId>` (the server keeps a PDF as it is) and create the node with
+               // `submit_node_events` (type `PDF`, position, no chapterId/cellId). A picture pasted the same way becomes an OUTLINE.
 TIMELINE_REFERENCE // Read-only view of a timeline (chapter) from ANOTHER board:
                // `meta.data.reference = {boardId, timelineId}`. Created in the UI only. It is not a real
                // chapter: no children, no handles, nothing can connect to it, and it is never part of a

package/shared/skills/learn-eventmodelers-api/references/mcp-tool-catalog.md

@@ -35,7 +35,7 @@ Write tools take their items as an array (`nodeIds[]`, `elements[]`, `connection
 | `place_element` | `boardId`, `timelineId`, `elements[]` (each `action?` = `create` (default) with `elementType`, `title`, `fields?`, `lane?`, `columnIndex?`, `autoConnect?` · `move` with `nodeId` + target `cellName` · `clear` with `nodeId` (preferred for an existing node) or `cellName`), `compact?` | Find/create an empty cell in the right lane and place a COMMAND/READMODEL/EVENT/AUTOMATION/MARKDOWN/TABLE. `action: "move"` puts an existing node of any type into that (empty) cell, moving it if it already sits elsewhere on the timeline; `action: "clear"` unplaces a node without deleting it (`delete_node` deletes) — pass its `nodeId` to empty the cell it sits in, or a `cellName`. These replace `drop_node_to_cell`, `move_node_in_timeline` and `clear_cell`, which still exist but are deprecated — don't use them. `fields` writes the element's attributes in the same call — don't follow a placement with a `submit_node_events` just to set them. A whole slice's or column run's worth goes in one call, applied in order so each entry sees the columns the previous one added; answers `{results}` (`compact: true` → `{nodeId, cellName, columnIndex}` per entry). `autoConnect: false` places without wiring to timeline neighbors — wire the edges yourself | — (MCP-only convenience; composes §2+§3) |
 | `list_slices` | `boardId`, `contextName?` | List slices (id, title, status). `contextName` restricts to one MODEL_CONTEXT (or timeline) — an unknown name is a `CONTEXT_NOT_FOUND` error, not an empty list | §8 `GET .../slicedata/slices` |
 | `get_slice_rework` | `boardId`, `contextId` | How much each slice of one context has been reworked: changes, steps backwards, and reopens after Done, most reworked first, plus planning metrics over them. `contextId` is a MODEL_CONTEXT or a timeline (a timeline resolves to the context it belongs to). Always per context — there is no board-wide form | §8 `GET .../reporting/rework/contexts/:contextId` |
-| `update_slice_status` | `boardId`, `newStatus`, plus exactly one of `sliceId` / `sliceTitle` | Change a SLICE_BORDER's `sliceStatus`. With a title there is no need to call `list_slices` first; an ambiguous title comes back with its candidates. A slice being created takes its status from `create_slice`/`create_slice_definition` instead | — (via `node:changed` event, §3) |
+| `update_slice_status` | `boardId`, `newStatus`, `statusReason?` (optional, but you should set it: one sentence — why; shown as an info icon in the planning view; stored as `meta.statusReason` next to `sliceStatus`), plus exactly one of `sliceId` / `sliceTitle` | Change a SLICE_BORDER's `sliceStatus`. With a title there is no need to call `list_slices` first; an ambiguous title comes back with its candidates. A slice being created takes its status from `create_slice`/`create_slice_definition` instead | — (via `node:changed` event, §3) |
 | `get_slice_data` | `boardId`, `contextName?`, `contextId?`, `sliceId?`, `projection?` (`"outline"` \| `"fields"` \| `"specs"`), `format?` | Full element graph for slices in a context. `projection` trims it first: `outline` = slice header + each element as `{id, title, type}`; `fields` = elements with fields and dependencies, no specs/comments/prompts; `specs` = specifications and storylines, no elements — prefer one over the full graph when only part is needed. `outline`/`specs` encode only as `json`, `yaml` or `toon` (other formats are a `PROJECTION_FORMAT_UNSUPPORTED` error); an unknown `sliceId` is `SLICE_NOT_FOUND` | §8 `GET /slicedata` |
 | `get_spec_info` | `boardId`, `timelineId`, `elementTypes?` | EVENT/COMMAND/READMODEL nodes valid in GWT steps. Pass `elementTypes` (subset of `EVENT`/`COMMAND`/`READMODEL`) to avoid pulling the full element list when only one or two types are needed — filtered server-side, not just after a full fetch | §6 `GET .../spec-info` |
 | `get_board_outline` | `boardId`, `chapterId` | One chapter's structure, compact: per-column node lists (`{id, type, title, lane, cellName}`) + a flat edge list, no HTML pages / field bodies / meta. `cellName` is each node's real cell address (column letter + row number) — the only read that returns cell names at all; use it when a placement needs a cell address. For an empty target cell, take the column's `letter` plus the lane's 1-based position in the outline's `lanes` list (e.g. `letter: "C"`, second lane → `C2`) — never convert array indexes yourself. The cheap "what is where and how is it wired" read — prefer over `get_nodes` (no projection) for orientation checks | — (MCP-only convenience) |

package/shared/skills/request-feedback/SKILL.md

@@ -129,10 +129,12 @@ or contradictory — not just "please clarify this slice."
 
 ## Step 4 — Mark the slice Blocked
 
+Blocking is two things: the comment from Step 3 holds the full question, and the `statusReason` is its one-sentence summary (what is missing or contradictory) that people see as an exclamation-mark icon in the planning view and on the slice header. Set both — the reason is optional, but you should always give it here.
+
 Prefer MCP:
 
 ```
-mcp__eventmodelers__update_slice_status { "boardId": "<BOARD_ID>", "sliceId": "<SLICE_NODE_ID>", "newStatus": "Blocked" }
+mcp__eventmodelers__update_slice_status { "boardId": "<BOARD_ID>", "sliceId": "<SLICE_NODE_ID>", "newStatus": "Blocked", "statusReason": "<one sentence: what is missing>" }
 ```
 
 Also mark the slice 'blocked' locally in the index.json if possible.
@@ -149,10 +151,11 @@ curl -s -X POST "<BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/events" \
     "id": "<new-random-uuid>",
     "eventType": "node:changed",
     "nodeId": "<SLICE_NODE_ID>",
-    "changedAttributes": ["sliceStatus"],
+    "changedAttributes": ["sliceStatus", "statusReason"],
     "meta": {
       "type": "SLICE_BORDER",
-      "sliceStatus": "Blocked"
+      "sliceStatus": "Blocked",
+      "statusReason": "<one sentence: what is missing>"
     }
   }]'
 ```

package/shared/skills/update-slice-status/SKILL.md

@@ -17,6 +17,7 @@ From `$ARGUMENTS`, extract:
 |-------|---------------|---------|
 | `sliceName` | the slice title to update (case-insensitive match) | **required** |
 | `newStatus` | the target status value | **required** |
+| `statusReason` | ONE sentence saying why the status changes | optional, but you **should** set it |
 
 Valid status values (case-sensitive):
 
@@ -35,6 +36,13 @@ Valid status values (case-sensitive):
 
 If `newStatus` is not one of these exact values, stop and tell the user the valid options.
 
+### Give a reason (optional, but you should)
+
+`statusReason` is optional — a status change works without it — but whenever you change a status you **should** send one: **one sentence**, in plain words, saying *why* the status changes
+("Backend built and tested, UI contract published.", "Blocked: the order total rule is unclear.", "Reviewed and approved by Anna.").
+It is stored next to `sliceStatus` in the SLICE_BORDER's meta and shown to people as an exclamation-mark icon in the planning view and on the slice header,
+so write it for a person who was not watching. Say what happened, not the status name again. For `Blocked`, also post a comment with the details (see `request-feedback`) and let `statusReason` be its short summary. Don't leave an old reason in place when the status changes — send a new one each time.
+
 ---
 
 ## Step 2 — List all slices
@@ -69,13 +77,13 @@ Save the matched slice as:
 Prefer the MCP tool — it does the same `node:changed`/`sliceStatus` update in one call, no event envelope to hand-assemble:
 
 ```
-mcp__eventmodelers__update_slice_status { "boardId": "<BOARD_ID>", "sliceId": "<SLICE_NODE_ID>", "newStatus": "<newStatus>" }
+mcp__eventmodelers__update_slice_status { "boardId": "<BOARD_ID>", "sliceId": "<SLICE_NODE_ID>", "newStatus": "<newStatus>", "statusReason": "<one sentence: why>" }
 ```
 
 The tool also resolves the slice itself — pass `sliceTitle` (or `columnId`) instead of `sliceId` and the listing step above can be skipped entirely; an ambiguous title comes back with its candidates instead of a guess:
 
 ```
-mcp__eventmodelers__update_slice_status { "boardId": "<BOARD_ID>", "sliceTitle": "Place Order", "newStatus": "<newStatus>" }
+mcp__eventmodelers__update_slice_status { "boardId": "<BOARD_ID>", "sliceTitle": "Place Order", "newStatus": "<newStatus>", "statusReason": "<one sentence: why>" }
 ```
 
 A slice that is being *created* takes its status straight from `create_slice`/`create_slice_definition` (`status`) — don't create it and then call this.
@@ -91,10 +99,11 @@ curl -s -X POST "<BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/events" \
     "id": "<new-random-uuid>",
     "eventType": "node:changed",
     "nodeId": "<SLICE_NODE_ID>",
-    "changedAttributes": ["sliceStatus"],
+    "changedAttributes": ["sliceStatus", "statusReason"],
     "meta": {
       "type": "SLICE_BORDER",
-      "sliceStatus": "<newStatus>"
+      "sliceStatus": "<newStatus>",
+      "statusReason": "<one sentence: why>"
     }
   }]'
 ```
@@ -122,6 +131,7 @@ Tell the user:
 - **Slice**: the title that was updated
 - **Previous status**: `CURRENT_STATUS`
 - **New status**: `newStatus`
+- **Reason**: `statusReason` (if set)
 - **Node ID**: `SLICE_NODE_ID`
 - **Outcome**: `SUCCESS`, `ALREADY_IN_STATUS` (another agent got there first — see above), or `ERROR`
 - **Any errors**: raw API message if something failed for a reason other than `ALREADY_IN_STATUS`

package/stacks/modeling-kit/templates/.claude/skills/analyze-code-base/SKILL.md

@@ -1,19 +1,19 @@
 ---
 name: analyze-code-base
-description: Uncover the business process behind an existing code base and build it on the board as an interview, iteratively — all chapters at high level first, then one chapter per pass, the person choosing which. Reads the code for hypotheses, asks one question at a time, draws as answers land. Use for "analyze this code base", "analyze this existing system", "reverse-engineer the model from the code", "model the legacy app".
+description: Uncover the business process behind an existing code base and build it on the board as an interview, iteratively — all chapters at high level first, then one chapter per pass, the person choosing which. Reads the code and its documentation (README, docs, ADRs, API specs, diagrams, feature files) for hypotheses, asks one question at a time, draws as answers land. Use for "analyze this code base", "analyze this existing system", "reverse-engineer the model from the code", "model the legacy app".
 ---
 
 # Analyze a Code Base
 
-You are the **orchestrator** of an interview. The code gives you a hypothesis; the person gives you the truth. **The board is the deliverable** — never hand over a JSON model, `config.json` or `high-level-analysis.json`.
+You are the **orchestrator** of an interview. The code and its documentation give you hypotheses; the person gives you the truth. **The board is the deliverable** — never hand over a JSON model, `config.json` or `high-level-analysis.json`.
 
-This skill owns only what is specific to legacy code: reading the sources, mapping code to elements, the layering of passes, and recording decisions with code references. Every modeling rule (naming, element types, chaptering, ordering, screens, scenarios, interviewing) lives in the skill named at each step — **read and follow that skill, don't restate or re-implement it here**.
+This skill owns only what is specific to legacy code: reading the sources (code **and** documentation), mapping them to elements, the layering of passes, and recording decisions with code references. Every modeling rule (naming, element types, chaptering, ordering, screens, scenarios, interviewing) lives in the skill named at each step — **read and follow that skill, don't restate or re-implement it here**.
 
 ---
 
 ## Step 0 — Is there a code base?
 
-Resolve the directory to analyse: `$EVENTMODELERS_CODE_DIR` if set (treat it as the repository root for every step below), otherwise the current directory. It must contain source code (`src/`, `pom.xml`, `build.gradle*`, `package.json`, `*.csproj`, …).
+Resolve the directory to analyse: `$EVENTMODELERS_CODE_DIR` if set (treat it as the repository root for every step below), otherwise the current directory. It must contain source code (`src/`, `pom.xml`, `build.gradle*`, `package.json`, `*.csproj`, …). Documentation alongside it (`README*`, `docs/`, ADRs, specs) is read too, but documentation alone is not a code base — without source code, stop as below.
 
 If it does not (an empty folder, a modeling-only workspace holding just `.claude/`, `.eventmodelers/` or `.agent-modeling-kit/`), **stop and answer in one or two plain sentences** — "There is no legacy code here to analyse; run this in the code base" — and do nothing else.
 
@@ -66,9 +66,9 @@ Naming, what to model and the anti-patterns are in `eventmodeling-core-rules` (r
 
 ---
 
-## Reading the sources — four lenses
+## Reading the sources — five lenses
 
-Every pass reads the code through the same four lenses; each produces *hypotheses* to put to the person, never elements on its own. Read only as deep as the current layer needs.
+Every pass reads the code and its documentation through the same five lenses; each produces *hypotheses* to put to the person, never elements on its own. Read only as deep as the current layer needs.
 
 1. **API** (look hardest here) — REST controllers, routes, handlers, message listeners, scheduled jobs, outbound clients. Each entry point is a candidate **screen + command** (a person writes), **screen + read model** (a person reads) or **automation** (jobs, listeners, calls to other systems). Request/response payloads hint at fields; the caller hints at who triggers it.
 2. **Tests** — test names, fixtures, assertions. Names reveal the business vocabulary; arrange/act/assert is a *hint* for Given/When/Then, not its shape — which element goes into Given, When and Then is decided by `eventmodeling-elaborating-scenarios`, never by the test's structure (see *Scenarios* below); error cases reveal the rules that matter. Fixtures are the source of realistic example values.
@@ -81,13 +81,22 @@ Every pass reads the code through the same four lenses; each produces *hypothese
 
 If the code is a generic engine (templates, schemas, configurable entities), model one real case it handles, not the engine (see *Concrete Over Generic* in `eventmodeling-core-rules`).
 
-Where the lenses disagree (a route nobody calls, a table never written, a test for removed behaviour, a screen with no backend), that is a question for the person — not something to model.
+5. **Documentation & other artifacts** — everything that explains the system without being executable. Look for it in the code root and its parents' obvious places: `README*`, `docs/`, `doc/`, `wiki/`, `adr/` / `docs/decisions/` (architecture decision records), `CHANGELOG*` / release notes, `CONTRIBUTING*`, API specs (OpenAPI/Swagger, AsyncAPI, GraphQL schemas, Postman collections, `.http` files), diagrams (PlantUML, Mermaid, draw.io, C4, images in `docs/`), BDD/acceptance material (`*.feature` Gherkin files, acceptance criteria), requirements, user stories and specs (Markdown, `.docx`/PDF exports), runbooks, DB documentation, and in-repo ticket or issue exports. Also read what configures behaviour: CI/CD pipelines, infra (Docker, Helm, Terraform), feature-flag and environment config — they show integrations and jobs the code alone hides.
+   - **No fixed list of file types.** Anything that could plausibly carry business meaning is a candidate: Markdown, text, PDFs, Word/Excel/PowerPoint, CSV and spreadsheets (reference data, rate tables, code lists), JSON/YAML/XML samples and fixtures, HTML pages, images and diagrams, email or chat exports, notebooks. The lists above are examples, not a filter. Judge by what the file may tell you, and treat the unclear ones through the relevance question below.
+   - **Find it by what is committed, not only by name.** List the tracked documents (`git ls-files` filtered to everything that is not source code, lock files or build output; without git, find them) and skim titles and file names. Any committed Markdown, text or PDF file can hold requirements, specs, notes or a glossary — but also changelogs of dependencies, licences, generated output or stale scratch notes.
+   - **In doubt, ask whether a document is relevant** — one question, listing the candidates: *"I found `docs/visits.md`, `NOTES.txt` and `design/old-flow.md`. Which of these describe the business and should I use? Anything to ignore?"* Like the Step 1 question this is **not a gate**: post it, carry on with the code, and use only the unambiguous documents (README, `docs/`, ADRs, API specs) until the answer arrives. Record the answer (relevant / ignored) in the chapter's `Legacy Sources` note and reuse it on later passes. Never read a document as authoritative just because it is committed.
+   - **What it gives you**: the **vocabulary** and the *intent* — glossary terms, personas and roles, the stated purpose of a flow, the rules in prose, the order in user stories and sequence diagrams, the systems around this one, and the *why* behind decisions (ADRs). Often the quickest source for the order and for the business term behind a code name.
+   - **Trust it least on "what the system does today".** Documentation goes stale; code and tests show behaviour, docs show intent. Where a document and the code disagree, that is a question for the person (see below) — and the date, version or commit of the document is part of the evidence. A document is also a *summary*: a flow it describes still has to be found in the code, or marked as documented-only.
+   - **PDFs** (specs, requirement documents, manuals, exported wiki pages) are read like any other document: with the Read tool page by page (`pages`, max 20 per request), starting with the table of contents and the pages relevant to the current chapter. They are subject to the same relevance question as `.md`/`.txt` files.
+   - Documents too large or too binary to read fully (very long PDFs, Word files, a diagram image): skim headings and the parts for the current chapter, and for a whole document to be modelled use `summarize` instead of re-implementing it here.
+
+Where the lenses disagree (a route nobody calls, a table never written, a test for removed behaviour, a screen with no backend, a document describing a flow the code no longer has, or code doing something the documentation never mentions), that is a question for the person — not something to model.
 
 ---
 
 ## From code to elements — the mapping rules
 
-Start with the **API** and **persistence** lenses; they carry the most signal. Tests and UI then confirm and name what they found.
+Start with the **API** and **persistence** lenses; they carry the most signal. Tests, UI and documentation then confirm, name and order what they found — documentation is the first place to look for the business word and the sequence.
 
 | In the code | On the board |
 |-------------|--------------|
@@ -96,6 +105,7 @@ Start with the **API** and **persistence** lenses; they carry the most signal. T
 | **Inbound API call nobody types in** — a webhook, a message/queue listener, a scheduled job, a call from another system | an **AUTOMATION** (+ its COMMAND). A webhook or message from another system goes through the translation chain: external EVENT → todo-list READMODEL → translation AUTOMATION → internal EVENT. |
 | **Outbound call to another system** — HTTP client, SDK, mail/SMS/payment/queue publish | an **AUTOMATION**: it reacts to an event (via its todo-list READMODEL), makes the call, and its COMMAND records the outcome as an EVENT (`Confirmation Mail Sent`, `Payment Failed`). |
 | **Read endpoint / query / join** | a **READMODEL**, fed by the events behind the tables it reads. |
+| **Documentation** — a user story, sequence diagram, ADR, glossary entry, API spec, `.feature` file | no element on its own: it **names** (glossary → titles), **orders** (stories, sequence diagrams → column order), **explains** (ADRs, rules in prose → decision rows, scenario candidates) and **corroborates** the elements derived from code. An API spec lists entry points and payloads like the *API* lens; a documented step with no counterpart in the code is documented-only — ask. |
 
 Rules of thumb: every API call is either a screen-driven command/read or an automation that does something; reaching out to other systems is typically an automation; a row that is only ever read, never written by this system, is reference data from outside — ask where it comes from instead of inventing an event. Class, table and endpoint names go in `description`, not titles.
 
@@ -104,7 +114,7 @@ Rules of thumb: every API call is either a screen-driven command/read or an auto
 ## Progressive elaboration — all chapters first, then one chapter per pass
 
 ### Pass 0 — all chapters, high level
-1. Read the sources broadly through the four lenses to spot the business workflows — don't wait for the Step 1 answer; walk the running UI via `discover-storyboard` once a URL has been given (also when it arrives after Pass 0).
+1. Read the sources broadly through the five lenses — start with the README and `docs/` for the overview and vocabulary — to spot the business workflows — don't wait for the Step 1 answer; walk the running UI via `discover-storyboard` once a URL has been given (also when it arrives after Pass 0).
 2. Group them into chapters and create them as `eventmodeling-brainstorming-events` (§ *Group events by workflow* / *Create one chapter per group*) does — a chapter is a user journey, never one endpoint, controller or CRUD operation. Code is split by operation (`OwnerController#initCreationForm`, `#processFindForm`, `#showOwner`, `#processUpdateOwnerForm`); the story is not — registering, finding, viewing and updating an owner are **one** chapter. Order the chapters per `eventmodeling-plotting-events`; ask where it is unclear. Add the **Decisions** lane, put the `Legacy Sources` note into **column 0** (see *The analysis log*), then sketch only the milestones (titles only) **from column 1 on**.
 3. Report the chapters and **ask which chapter to start with**. Never pick for them.
 
@@ -116,6 +126,7 @@ Rules of thumb: every API call is either a screen-driven command/read or an auto
    - `eventmodeling-designing-automation-chains` / `eventmodeling-translating-external-events` — jobs, listeners, webhooks, outbound calls;
    - `eventmodeling-elaborating-scenarios` — rules from the tests (layer 1+ only), built exactly as that skill says (see *Scenarios* below).
    Feed each skill what the lenses and the mapping table give you; ask only where the code stops (see *Step 1* when the order is unclear).
+   **Screens and scenarios are part of the pass — never skip them.** A chapter with only events, commands and read models is not detailed yet. Every command and read model a person uses gets its `HTML_SCREEN` (storyboarding step), and every command gets at least its happy-path scenario from `eventmodeling-elaborating-scenarios`. Never report "not done: screens, scenarios, tests, UI" and ask for the next chapter; run those steps first. If a step truly can't be done (e.g. no tests to mine for a rule), say why in the chapter's decision rows, but still place the screens and the happy-path scenario.
 2. Stay within the layer's detail budget (below). Every placement batch carries its decision rows (see *Recording decisions*).
 3. Re-space the chapters (see *Keeping chapters apart*) after every batch.
 4. Append this pass's row to the chapter's *Analysis history*.
@@ -150,7 +161,8 @@ Every decision you make while turning code into the model is recorded **on the t
 | Decision | Example |
 |----------|---------|
 | Code construct → element | `VisitController#processNewVisitForm` + `visits` insert → *Book Visit* / *Visit Booked* |
-| Order | *Owner Registered* before *Pet Added* — from the UI click path, confirmed by the person |
+| Order | *Owner Registered* before *Pet Added* — from the UI click path or `docs/user-stories.md`, confirmed by the person |
+| Code vs. documentation conflict | `docs/visits.md` says visits can be cancelled, the code has no cancel path → asked; recorded as the person answered |
 | Code term → business term | `PetType` → *Species*, the person's word |
 | Person overrides the code | Code allows cancelling a visit; the person says it never happens → not modeled |
 | Merged / split | Two writes in `OwnerService#save` → one event; one endpoint → two commands |
@@ -205,6 +217,7 @@ Code root `petclinic/` · running UI: http://localhost:8080 (test account `georg
 | API | `src/main/java/org/acme/visit/` | `VisitController` |
 | Persistence | `src/main/resources/db/schema.sql` | `visits` table, `VisitRepository` |
 | Tests | `src/test/java/org/acme/visit/` | `VisitControllerTests` |
+| Docs | `docs/visits.md`, `docs/adr/0007-visit-scheduling.md` | user story *Book a Visit*, ADR 7 |
 | UI | `src/main/resources/templates/pets/` | `createOrUpdateVisitForm.html` |
 
 ## Chapter decisions
@@ -232,7 +245,7 @@ Code root `petclinic/` · running UI: http://localhost:8080 (test account `georg
 | `description` (Visit) | *Reason for Visit* |
 ```
 
-The `Confirmed by` column shows how far to trust a decision: `code` (derived from the sources), `person` (they said so) or `assumed` (neither, still open). An `assumed` row whose question can't be settled from the model also gets a QUESTION comment on the node (see *Principles*); the row records the assumption, the comment asks the question.
+The `Confirmed by` column shows how far to trust a decision: `code` (derived from the sources), `docs` (taken from documentation only, not seen in the code — say which document), `person` (they said so) or `assumed` (neither, still open). An `assumed` row whose question can't be settled from the model also gets a QUESTION comment on the node (see *Principles*); the row records the assumption, the comment asks the question.
 
 Element `description`s still carry their own short code reference. The feedback notes add the *why* and the decisions that span several elements.