@zh-xx/antu 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zh-xx/antu",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Antu: legal diagrams (fact, procedure, relationship, justification) from JSON, as one offline HTML page. The command line and the MCP server.",
   "license": "AGPL-3.0-or-later",
   "author": "Ji Cheng",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/zh-xx/Antu",
     "source": "github"
   },
-  "version": "0.9.0",
+  "version": "0.10.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@zh-xx/antu",
-      "version": "0.9.0",
+      "version": "0.10.0",
       "transport": {
         "type": "stdio"
       }

package/spec/agent/fact/guide.md

@@ -1,7 +1,7 @@
 # Mechanism notes for an agent
 
-> This is an **operating note**, not the specification. The field list is served by
-> `antu_schema`, examples by `antu_examples`, and the design rationale lives in the
+> This is an **operating note**, not the specification. The field list is a separate
+> document, the examples are separate files, and the design rationale lives in the
 > human-facing documents under `spec/` (you do not need them to write JSON).
 >
 > **This file is English on purpose.** It goes into a model's context, the same as
@@ -17,7 +17,7 @@ The reader can also switch to a **chronicle** (one column in slot order, the tim
 written between events) or a **time scale** (distance is real time, the axis breaks where the
 scale changes). `date`, `dateEnd` and their precision matter more there: a day-only date is
 drawn as the whole day. The same JSON draws in all three; `kind: "chronicle"` or
-`kind: "scale"` on antu_layout / antu_preview / antu_render shows it.
+`kind: "scale"` on `layout`, `preview` and `render` shows it.
 
 ## Where an event is drawn is decided by three things
 
@@ -61,9 +61,9 @@ rules above are applied. It **never changes the data**:
 
 **A time point holds at most one event per lane.** Two events in the same lane of the
 same slot means that view cannot be drawn, and it disappears from the interface options
-(an option that cannot be clicked is noise). `antu_validate` checks the data once and does not call
+(an option that cannot be clicked is noise). `validate` checks the data once and does not call
 this an error, since a data set may keep a view that does not fit on purpose; it does list each such
-view as a note after "Validation passed", so it never goes unseen. `antu_layout` reports the same views.
+view as a note after "Validation passed", so it never goes unseen. `layout` reports the same views.
 
 Three ways to fix it, most common first:
 
@@ -79,17 +79,17 @@ After splitting, check again that each slot holds exactly one event.
 ## After writing
 
 ```
-antu_validate   reports each problem, with the field path and the event id
-                (e.g. slots[0].events[1] (ev-2)); when it passes, notes any view that
-                does not fit (not an error, but that view will not be offered)
-antu_layout     no rendering: how large, which orientation, which views do not fit
-antu_preview    take a screenshot and look: are cards cramped, is the text small,
-                is there too much empty space
-antu_render     produce the self-contained HTML
+validate    reports each problem, with the field path and the event id
+            (e.g. slots[0].events[1] (ev-2)); when it passes, notes any view that
+            does not fit (not an error, but that view will not be offered)
+layout      no rendering: how large, which orientation, which views do not fit
+preview     take a screenshot and look: are cards cramped, is the text small,
+            is there too much empty space
+render      produce the self-contained HTML
 ```
 
 **Passing validation is only the pass mark.** Validation cannot tell whether the
-diagram looks good. Always run `antu_preview` and look before delivering.
+diagram looks good. Always run `preview` and look before delivering.
 
 ## Things that are easy to get wrong
 
@@ -112,3 +112,15 @@ diagram looks good. Always run `antu_preview` and look before delivering.
 - **Keep the summary short.** `summary` fits one line of the card (about 22 full-width
   characters); a longer one is **rejected**, not truncated, because it would overflow
   the card. Put the long text in `detail`.
+
+## The examples
+
+Each adds one idea (`<name>.zh-CN.json`, `<name>.en.json`):
+
+- `1-minimal`: two parties, no `groups` (every card on the axis)
+- `2-single-actor`: one party
+- `3-groups`: `groupId` picks the side
+- `4-views`: the same data, two views
+- `5-duration`: spans and approximate times
+- `6-sources`: facts traced to sources
+- `7-undated`: no `date`

package/spec/agent/justification/guide.md

@@ -1,7 +1,7 @@
 # Mechanism notes for an agent
 
-> This is an **operating note**, not the specification. The field list is served by
-> `antu_schema`, examples by `antu_examples`, and the design rationale lives in
+> This is an **operating note**, not the specification. The field list is a separate
+> document, the examples are separate files, and the design rationale lives in
 > `spec/justification/schema-draft.md` (you do not need it to write JSON).
 >
 > **This file is English on purpose.** It goes into a model's context, the same as
@@ -75,20 +75,21 @@ it twice.
 ## Big diagrams
 
 A reader can fold each issue up to its conclusion (its box title is a button; the dock has "Fold issues"), so a
-diagram of several issues can be read at a glance. Nothing to write for it: it is not in the JSON. Still split a
-diagram that grows past about 60 nodes.
+diagram of several issues can be read at a glance. Nothing to write for it: it is not in the JSON. A diagram whose
+text would be under 9 px fitted to a screen **opens with its issues folded** (`layout` says "Opens with the issues
+folded"). Still split a diagram that grows past about 60 nodes.
 
 ## After writing
 
 ```
-antu_validate   each problem with its path and id: links[3] (f-9 -> e-9): `to` refers to ...
-                on a pass it can still add notes (a fact with no source, nothing supports a conclusion)
-antu_layout     counts, layers, size per orientation; no rendering
-antu_preview    a screenshot: is each issue clear, do the lines cross badly, is anything cut off
-antu_render     the self-contained HTML
+validate    each problem with its path and id: links[3] (f-9 -> e-9): `to` refers to ...
+            on a pass it can still add notes (a fact with no source, nothing supports a conclusion)
+layout      counts, layers, size per orientation; no rendering
+preview     a screenshot: is each issue clear, do the lines cross badly, is anything cut off
+render      the self-contained HTML
 ```
 
-**Passing validation is only the pass mark.** Always look with `antu_preview` before delivering. A big diagram
+**Passing validation is only the pass mark.** Always look with `preview` before delivering. A big diagram
 (past about 40 nodes) is small on one screen: split it, one diagram per issue.
 
 ## Also easy to get wrong
@@ -98,3 +99,14 @@ antu_render     the self-contained HTML
 - **`holds` is not for facts and norms; `date` is only for facts** (`2032-04-14` or `2032-04-14T22:22`).
 - **At least one conclusion has no outgoing link**: the conclusion the whole reasoning leads to.
 - **Do not invent a date**: leave `date` out when the source does not give one.
+
+## The examples
+
+Each adds one idea (`<name>.zh-CN.json`, `<name>.en.json`):
+
+- `1-minimal`: conclusion, norm, element, two facts
+- `2-against-and-rejected`: the rejected side
+- `3-issues`: one box per issue
+- `4-shared-fact`: one fact, two issues
+- `5-sources`: time and sources
+- `6-all-or-any`: and / or

package/spec/agent/procedure/guide.md

@@ -1,7 +1,7 @@
 # Mechanism notes for an agent
 
-> This is an **operating note**, not the specification. The field list is served by
-> `antu_schema`, examples by `antu_examples`, and the design rationale lives in the
+> This is an **operating note**, not the specification. The field list is a separate
+> document, the examples are separate files, and the design rationale lives in the
 > human-facing documents under `spec/` (you do not need them to write JSON).
 >
 > **This file is English on purpose.** It goes into a model's context, the same as
@@ -86,13 +86,13 @@ they are not in the data.
 ## After writing
 
 ```
-antu_validate   each problem with its path and node id: nodes (n-4): kind is "decision" but ...
-antu_layout     counts, layers, loops, rules, size per orientation; no rendering
-antu_preview    a screenshot: is the main line obvious, are the branches readable
-antu_render     the self-contained HTML
+validate    each problem with its path and node id: nodes (n-4): kind is "decision" but ...
+layout      counts, layers, loops, rules, size per orientation; no rendering
+preview     a screenshot: is the main line obvious, are the branches readable
+render      the self-contained HTML
 ```
 
-**Passing validation is only the pass mark.** Always look with `antu_preview` before
+**Passing validation is only the pass mark.** Always look with `preview` before
 delivering.
 
 ## Also easy to get wrong
@@ -106,4 +106,16 @@ delivering.
 
 The reader can switch to the **route map**: the main line as one line, with rework loops and early endings
 hanging below it. It needs a clear main line, so **mark `main` along the whole line from start to end**
-(or on none, and the engine infers it). `kind: "route"` on antu_layout / antu_preview / antu_render shows it.
+(or on none, and the engine infers it). `kind: "route"` on `layout`, `preview` and `render` shows it.
+
+## The examples
+
+Each adds one idea (`<name>.zh-CN.json`, `<name>.en.json`):
+
+- `1-minimal`: three steps in a line
+- `2-decision`: decision point, conditions, edge back
+- `3-branches`: several edges from one step
+- `4-stages`: stages, actors, outcomes
+- `5-inferred-spine`: engine infers the main line
+- `6-merged-edges`: several edges to one target
+- `7-rules`: what may happen at any time

package/spec/agent/relationship/guide.md

@@ -1,7 +1,7 @@
 # Mechanism notes for an agent
 
-> This is an **operating note**, not the specification. The field list is served by
-> `antu_schema`, examples by `antu_examples`, and the design rationale lives in
+> This is an **operating note**, not the specification. The field list is a separate
+> document, the examples are separate files, and the design rationale lives in
 > `spec/relationship/schema-draft.md` (you do not need it to write JSON).
 >
 > **This file is English on purpose.** It goes into a model's context, the same as
@@ -23,7 +23,7 @@ relation between A and B". The **equity tree** draws the `equity` relations in l
 line, so **write `share` on every equity relation**. The **authority chart** draws `control`, `employment` and `agency` as an organisation chart; the **related-party
 list** is a table of one party's relations (to paste into a brief); the **path** draws the shortest chains between
 two parties; the **summary** draws each camp (`groupId`) as one block. The same JSON draws in all nine;
-`kind: "focus"`, `"chain"`, `"matrix"`, `"equity"`, `"authority"`, `"related"`, `"path"` or `"summary"` on antu_layout / antu_preview / antu_render shows it.
+`kind: "focus"`, `"chain"`, `"matrix"`, `"equity"`, `"authority"`, `"related"`, `"path"` or `"summary"` on `layout`, `preview` and `render` shows it.
 
 ## Three things, three places
 
@@ -75,14 +75,14 @@ group (`groupId`); groups do not nest. Leave a party out of every group and it s
 ## After writing
 
 ```
-antu_validate   each problem with its path and id: relations (r-2): `secures` points at ...
-                on a pass it can still add notes (an entity nothing relates to, shares over 100%)
-antu_layout     counts, layers, size per orientation; no rendering
-antu_preview    a screenshot: are the camps clear, do the lines cross badly
-antu_render     the self-contained HTML
+validate    each problem with its path and id: relations (r-2): `secures` points at ...
+            on a pass it can still add notes (an entity nothing relates to, shares over 100%)
+layout      counts, layers, size per orientation; no rendering
+preview     a screenshot: are the camps clear, do the lines cross badly
+render      the self-contained HTML
 ```
 
-**Passing validation is only the pass mark.** Always look with `antu_preview` before delivering.
+**Passing validation is only the pass mark.** Always look with `preview` before delivering.
 
 ## Also easy to get wrong
 
@@ -90,3 +90,13 @@ antu_render     the self-contained HTML
 - **`share` is only for `equity`, `amount` only for `debt` and `contract`, `secures` only for `guarantee`.**
 - **An entity nothing relates to floats beside the diagram** (a hint): relate it or leave it out.
 - **`amount` is a string**, written the way it should be read, with the currency.
+
+## The examples
+
+Each adds one idea (`<name>.zh-CN.json`, `<name>.en.json`):
+
+- `1-minimal`: one loan
+- `2-equity`: who holds whom, how much
+- `3-guarantee`: names the claim it secures
+- `4-groups`: camps
+- `5-kinship`: undirected beside directed relations