@zh-xx/antu 0.9.0

package/examples/relationship/sample-group-guarantee.en.json

@@ -0,0 +1,138 @@
+{
+  "type": "relationship",
+  "specVersion": 1,
+  "title": "Xinghe Group · Shareholdings and guarantees",
+  "asOf": "2024-06-30",
+  "groups": [
+    {
+      "id": "g-1",
+      "label": "Plaintiff side"
+    },
+    {
+      "id": "g-2",
+      "label": "Defendant side"
+    }
+  ],
+  "entities": [
+    {
+      "id": "e-1",
+      "kind": "company",
+      "label": "Huafeng Investment Co.",
+      "role": "Lender",
+      "groupId": "g-1"
+    },
+    {
+      "id": "e-2",
+      "kind": "person",
+      "label": "Mr. Chen",
+      "role": "Huafeng's controlling shareholder",
+      "groupId": "g-1"
+    },
+    {
+      "id": "e-3",
+      "kind": "company",
+      "label": "Xinghe Group Co.",
+      "role": "Borrower",
+      "groupId": "g-2"
+    },
+    {
+      "id": "e-4",
+      "kind": "person",
+      "label": "Li Ming",
+      "role": "Chairman of Xinghe Group",
+      "groupId": "g-2"
+    },
+    {
+      "id": "e-5",
+      "kind": "company",
+      "label": "Xinghe Trading Co.",
+      "groupId": "g-2"
+    },
+    {
+      "id": "e-6",
+      "kind": "company",
+      "label": "Xinghe Logistics Co.",
+      "groupId": "g-2"
+    },
+    {
+      "id": "e-7",
+      "kind": "organization",
+      "label": "Rong'an Guarantee Co.",
+      "role": "Guarantor"
+    },
+    {
+      "id": "e-8",
+      "kind": "government",
+      "label": "Municipal Market Regulation Bureau",
+      "role": "Registration authority"
+    }
+  ],
+  "relations": [
+    {
+      "id": "r-1",
+      "from": "e-2",
+      "to": "e-1",
+      "kind": "equity",
+      "share": 70
+    },
+    {
+      "id": "r-2",
+      "from": "e-4",
+      "to": "e-3",
+      "kind": "equity",
+      "share": 55
+    },
+    {
+      "id": "r-3",
+      "from": "e-3",
+      "to": "e-5",
+      "kind": "equity",
+      "share": 100
+    },
+    {
+      "id": "r-4",
+      "from": "e-3",
+      "to": "e-6",
+      "kind": "equity",
+      "share": 80
+    },
+    {
+      "id": "r-5",
+      "from": "e-1",
+      "to": "e-3",
+      "kind": "debt",
+      "amount": "CNY 30,000,000",
+      "label": "Loan"
+    },
+    {
+      "id": "r-6",
+      "from": "e-7",
+      "to": "e-1",
+      "kind": "guarantee",
+      "label": "Joint and several guarantee",
+      "secures": "r-5"
+    },
+    {
+      "id": "r-7",
+      "from": "e-4",
+      "to": "e-1",
+      "kind": "guarantee",
+      "label": "Personal joint and several guarantee",
+      "secures": "r-5"
+    },
+    {
+      "id": "r-8",
+      "from": "e-3",
+      "to": "e-7",
+      "kind": "contract",
+      "label": "Counter-guarantee contract"
+    },
+    {
+      "id": "r-9",
+      "from": "e-8",
+      "to": "e-3",
+      "kind": "other",
+      "label": "Registration"
+    }
+  ]
+}

package/examples/relationship/sample-group-guarantee.zh-CN.json

@@ -0,0 +1,138 @@
+{
+  "type": "relationship",
+  "specVersion": 1,
+  "title": "星河集团股权与担保",
+  "asOf": "2024-06-30",
+  "groups": [
+    {
+      "id": "g-1",
+      "label": "原告方"
+    },
+    {
+      "id": "g-2",
+      "label": "被告方"
+    }
+  ],
+  "entities": [
+    {
+      "id": "e-1",
+      "kind": "company",
+      "label": "华峰投资有限公司",
+      "role": "出借人",
+      "groupId": "g-1"
+    },
+    {
+      "id": "e-2",
+      "kind": "person",
+      "label": "陈总",
+      "role": "华峰实际控制人",
+      "groupId": "g-1"
+    },
+    {
+      "id": "e-3",
+      "kind": "company",
+      "label": "星河集团有限公司",
+      "role": "借款人",
+      "groupId": "g-2"
+    },
+    {
+      "id": "e-4",
+      "kind": "person",
+      "label": "李明",
+      "role": "星河集团董事长",
+      "groupId": "g-2"
+    },
+    {
+      "id": "e-5",
+      "kind": "company",
+      "label": "星河商贸有限公司",
+      "groupId": "g-2"
+    },
+    {
+      "id": "e-6",
+      "kind": "company",
+      "label": "星河物流有限公司",
+      "groupId": "g-2"
+    },
+    {
+      "id": "e-7",
+      "kind": "organization",
+      "label": "融安担保公司",
+      "role": "保证人"
+    },
+    {
+      "id": "e-8",
+      "kind": "government",
+      "label": "市市场监督管理局",
+      "role": "登记机关"
+    }
+  ],
+  "relations": [
+    {
+      "id": "r-1",
+      "from": "e-2",
+      "to": "e-1",
+      "kind": "equity",
+      "share": 70
+    },
+    {
+      "id": "r-2",
+      "from": "e-4",
+      "to": "e-3",
+      "kind": "equity",
+      "share": 55
+    },
+    {
+      "id": "r-3",
+      "from": "e-3",
+      "to": "e-5",
+      "kind": "equity",
+      "share": 100
+    },
+    {
+      "id": "r-4",
+      "from": "e-3",
+      "to": "e-6",
+      "kind": "equity",
+      "share": 80
+    },
+    {
+      "id": "r-5",
+      "from": "e-1",
+      "to": "e-3",
+      "kind": "debt",
+      "amount": "人民币 3000 万元",
+      "label": "借款"
+    },
+    {
+      "id": "r-6",
+      "from": "e-7",
+      "to": "e-1",
+      "kind": "guarantee",
+      "label": "连带责任保证",
+      "secures": "r-5"
+    },
+    {
+      "id": "r-7",
+      "from": "e-4",
+      "to": "e-1",
+      "kind": "guarantee",
+      "label": "个人连带保证",
+      "secures": "r-5"
+    },
+    {
+      "id": "r-8",
+      "from": "e-3",
+      "to": "e-7",
+      "kind": "contract",
+      "label": "反担保合同"
+    },
+    {
+      "id": "r-9",
+      "from": "e-8",
+      "to": "e-3",
+      "kind": "other",
+      "label": "登记"
+    }
+  ]
+}

package/examples/relationship/sample-loan-guarantee.en.json

@@ -0,0 +1,122 @@
+{
+  "type": "relationship",
+  "specVersion": 1,
+  "title": "Zhang San v. Li Si · Parties and relations",
+  "asOf": "2023-03-10",
+  "groups": [
+    {
+      "id": "g-1",
+      "label": "Creditor side"
+    },
+    {
+      "id": "g-2",
+      "label": "Debtor side"
+    }
+  ],
+  "entities": [
+    {
+      "id": "e-1",
+      "kind": "person",
+      "label": "Zhang San",
+      "role": "Lender",
+      "groupId": "g-1"
+    },
+    {
+      "id": "e-2",
+      "kind": "person",
+      "label": "Li Si",
+      "role": "Borrower",
+      "groupId": "g-2"
+    },
+    {
+      "id": "e-3",
+      "kind": "person",
+      "label": "Wang Wu",
+      "role": "Guarantor",
+      "groupId": "g-2"
+    },
+    {
+      "id": "e-4",
+      "kind": "company",
+      "label": "Xinghe Trading Co.",
+      "groupId": "g-2"
+    },
+    {
+      "id": "e-5",
+      "kind": "person",
+      "label": "Zhao Liu",
+      "role": "Li Si's spouse",
+      "groupId": "g-2"
+    }
+  ],
+  "relations": [
+    {
+      "id": "r-1",
+      "from": "e-1",
+      "to": "e-2",
+      "kind": "debt",
+      "label": "Loan",
+      "amount": "CNY 500,000",
+      "sourceIds": [
+        "s-1"
+      ]
+    },
+    {
+      "id": "r-2",
+      "from": "e-3",
+      "to": "e-1",
+      "kind": "guarantee",
+      "label": "Joint and several guarantee",
+      "secures": "r-1",
+      "sourceIds": [
+        "s-2"
+      ]
+    },
+    {
+      "id": "r-3",
+      "from": "e-2",
+      "to": "e-4",
+      "kind": "equity",
+      "share": 60,
+      "sourceIds": [
+        "s-3"
+      ]
+    },
+    {
+      "id": "r-4",
+      "from": "e-2",
+      "to": "e-5",
+      "kind": "kinship",
+      "label": "Spouses"
+    }
+  ],
+  "sources": [
+    {
+      "id": "s-1",
+      "type": "contract",
+      "name": "Loan contract",
+      "loc": {
+        "file": "loan-contract.pdf",
+        "page": 1
+      }
+    },
+    {
+      "id": "s-2",
+      "type": "contract",
+      "name": "Guarantee contract",
+      "loc": {
+        "file": "guarantee.pdf",
+        "page": 1
+      }
+    },
+    {
+      "id": "s-3",
+      "type": "evidence",
+      "name": "Business registration record",
+      "loc": {
+        "file": "registry.pdf",
+        "page": 2
+      }
+    }
+  ]
+}

package/examples/relationship/sample-loan-guarantee.zh-CN.json

@@ -0,0 +1,122 @@
+{
+  "type": "relationship",
+  "specVersion": 1,
+  "title": "张三诉李四 · 当事方及其关系",
+  "asOf": "2023-03-10",
+  "groups": [
+    {
+      "id": "g-1",
+      "label": "债权人一方"
+    },
+    {
+      "id": "g-2",
+      "label": "债务人一方"
+    }
+  ],
+  "entities": [
+    {
+      "id": "e-1",
+      "kind": "person",
+      "label": "张三",
+      "role": "出借人",
+      "groupId": "g-1"
+    },
+    {
+      "id": "e-2",
+      "kind": "person",
+      "label": "李四",
+      "role": "借款人",
+      "groupId": "g-2"
+    },
+    {
+      "id": "e-3",
+      "kind": "person",
+      "label": "王五",
+      "role": "保证人",
+      "groupId": "g-2"
+    },
+    {
+      "id": "e-4",
+      "kind": "company",
+      "label": "星河商贸有限公司",
+      "groupId": "g-2"
+    },
+    {
+      "id": "e-5",
+      "kind": "person",
+      "label": "赵六",
+      "role": "李四之妻",
+      "groupId": "g-2"
+    }
+  ],
+  "relations": [
+    {
+      "id": "r-1",
+      "from": "e-1",
+      "to": "e-2",
+      "kind": "debt",
+      "label": "借款",
+      "amount": "人民币 50 万元",
+      "sourceIds": [
+        "s-1"
+      ]
+    },
+    {
+      "id": "r-2",
+      "from": "e-3",
+      "to": "e-1",
+      "kind": "guarantee",
+      "label": "连带责任保证",
+      "secures": "r-1",
+      "sourceIds": [
+        "s-2"
+      ]
+    },
+    {
+      "id": "r-3",
+      "from": "e-2",
+      "to": "e-4",
+      "kind": "equity",
+      "share": 60,
+      "sourceIds": [
+        "s-3"
+      ]
+    },
+    {
+      "id": "r-4",
+      "from": "e-2",
+      "to": "e-5",
+      "kind": "kinship",
+      "label": "夫妻"
+    }
+  ],
+  "sources": [
+    {
+      "id": "s-1",
+      "type": "contract",
+      "name": "借款合同",
+      "loc": {
+        "file": "loan-contract.pdf",
+        "page": 1
+      }
+    },
+    {
+      "id": "s-2",
+      "type": "contract",
+      "name": "保证合同",
+      "loc": {
+        "file": "guarantee.pdf",
+        "page": 1
+      }
+    },
+    {
+      "id": "s-3",
+      "type": "evidence",
+      "name": "工商登记记录",
+      "loc": {
+        "file": "registry.pdf",
+        "page": 2
+      }
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@zh-xx/antu",
+  "version": "0.9.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",
+  "homepage": "https://github.com/zh-xx/Antu",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zh-xx/Antu.git"
+  },
+  "bugs": {
+    "url": "https://github.com/zh-xx/Antu/issues"
+  },
+  "keywords": [
+    "legal",
+    "diagram",
+    "mcp",
+    "model-context-protocol",
+    "agent",
+    "visualization"
+  ],
+  "mcpName": "io.github.zh-xx/antu",
+  "type": "module",
+  "bin": {
+    "antu": "bin/antu.mjs",
+    "antu-mcp": "bin/antu-mcp.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/server.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.zh-xx/antu",
+  "description": "Legal diagrams (fact, procedure, relationship, justification) from JSON, as one offline HTML page.",
+  "repository": {
+    "url": "https://github.com/zh-xx/Antu",
+    "source": "github"
+  },
+  "version": "0.9.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@zh-xx/antu",
+      "version": "0.9.0",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

package/spec/agent/fact/guide.md

@@ -0,0 +1,114 @@
+# 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
+> 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
+> the field table and the validation errors. See the header of `src/core/i18n.js`.
+
+## In one sentence
+
+A fact JSON describes: **when, who, did what, resting on which material**.
+The engine draws it as a timeline: time runs downwards, parties and sides are laid
+out left and right.
+
+The reader can also switch to a **chronicle** (one column in slot order, the time passed
+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.
+
+## Where an event is drawn is decided by three things
+
+```
+Row (time)   the order of the slots array. Earlier in the array = earlier in time.
+             date is display-only: it never orders or reorders anything.
+
+Column (side) groupId decides which side:
+              the 1st group  -> side 1 (left when vertical)
+              the 2nd group  -> side 2 (right when vertical)
+              the 3rd group or none -> the axis (the middle column)
+
+Column (lane) actorIds decides the lane:
+              exactly 1 party -> that party's lane
+              2 or more, or none -> the axis
+```
+
+**An event with several parties lands on the axis.** That is a hard rule: it means
+"both sides did this" or "this happened objectively", and belongs to neither side.
+
+So list in `actorIds` **the party who did it**: "A pays B" is A's act (one party, A's lane); "A and B sign a
+contract" is both's (two parties, the axis). Name the other party in the label or the summary, not in `actorIds`,
+unless both acted.
+
+## What a view is
+
+The same data can be looked at in several ways. A view only changes how the two
+rules above are applied. It **never changes the data**:
+
+```json
+{ "label": "parties side by side", "splitBy": "actor",
+  "side1": { "label": "Huayuan Trading", "actors": ["a-1"] },
+  "side2": { "label": "Xincheng Building Materials", "actors": ["a-2"] } }
+```
+
+- `splitBy: "actor"`: split by party; `side1` / `side2` say who is on which side;
+- `splitBy: "group"`: split by group; no need to name parties;
+- `views` may be omitted; the engine then provides a single "all" view.
+
+## One limit: one event per cell
+
+**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
+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.
+
+Three ways to fix it, most common first:
+
+1. **Split the time point.** If two things happened at 9:24, one at 9:24:03 and one at
+   9:24:16, make two slots and give each its exact time.
+2. **Add actorIds.** If the two events belong to different parties, add `actorIds` and
+   they fall into different lanes.
+3. **Add groupId.** If they are of different kinds, add `groupId` and they fall on
+   different sides.
+
+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
+```
+
+**Passing validation is only the pass mark.** Validation cannot tell whether the
+diagram looks good. Always run `antu_preview` and look before delivering.
+
+## Things that are easy to get wrong
+
+- **date does not decide order.** The order is the `slots` array. To reorder, reorder
+  the array.
+- **Referenced ids must exist.** `actorIds` / `groupId` / `sourceIds` pointing at an id
+  that does not exist is an error.
+- **List only the sources this diagram uses.** `sources` travels inside the diagram;
+  there is no need to list the whole case file.
+- **approx is not "roughly written".** It is the formal marker that the time is not
+  exact, and the diagram then shows "approx."; explain why in `dateNote`.
+- **No date in the material: leave `date` out.** It is optional, and the card then says the date
+  is unknown. Do not borrow a neighbour's date, and do not use `approx` for it: `approx` is for a
+  date that was estimated or worked out, not for one that is missing. The place in the array still
+  puts the event in order ("and afterwards they never replied" goes after the event it follows).
+  `dateEnd` needs a `date`.
+- **`quote` is verbatim.** It is shown on the card as the material's own words, so it must be an exact passage of
+  the source: copy it, do not shorten or reword it. Join several passages with `……`. A condensed version of what
+  the source says belongs in `detail`, not in `quote`. If you do not have the text, leave `quote` out.
+- **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`.