Connect

GRAPH.md spec

What a valid GRAPH.md must contain and in what order. vinc graph-md check tests exactly these points.

What the file looks like

A Markdown file of about 75 lines: a title, a header line, then the sections below with the generated region near the end.

# GRAPH.md
<!-- vinc-graph-md: 1 · built 2026-10-01 · the store is canonical, this file is a view of it -->

## What this is [this graph decides]
The house style for writing into this knowledge graph. ...

## Node kinds [schema-fixed]
- Concept: one reusable idea. If it will not be reused, do not create it.
...

<!-- vinc:generated start · ... -->
## Domains in this graph
...
<!-- vinc:generated end -->

## Do not [this graph decides]
- Do not ratify your own proposal. A person does that.

One of the first four lines must be . The number is the format version, currently 1. The rest of the line holds the build date and a reminder that the graph is the original and the file a copy of it. A rebuild updates the date.

Sections, in order

The sections must come in this order. Vinc recognises a section by its heading name, so keep the names as they are, all in the file's language (English or Korean). The tag after the name is optional for the check, but the template writes it.

#	Heading	Tag	Needed	What it says
1	`## What this is`	[this graph decides]	Required	That the file fixes conventions, and judging meaning is the reader's job.
2	`## Read before you write`	[this graph decides]	Required	Search first, reuse ids, id prefixes such as `concept:`, and writing in English.
3	`## Node kinds`	[schema-fixed]	Required	Concept, Episode, Record, Decision, Bridge and Entity, and when to use each.
4	`## How big is one concept`	[varies by topic]	Required	Good and bad examples of one concept, and a two-sentence test.
5	`## Relations`	[schema-fixed]	Required	The six edge names and their direction, and which need `evidence`.
6	`## Documents`	[schema-fixed]	Required	Source text goes in through `vinc_doc_put`, not pasted into a Record.
7	`## Validity`	[this graph decides]	Optional	`valid_from` and `valid_until` instead of deleting a past claim.
8	`## Roles`	[schema-fixed]	Optional	How an Agent role is written: id, topic and the required props.
9	`## Topics`	[this graph decides]	Optional	How the domain field is shaped, and how big one leaf should be.
10	`## Domains in this graph`	generated	Required	Generated. Domains with node counts.
11	`## Ratified vocabulary`	generated	Required	Generated. Approved node and edge types.
12	`## Do not`	[this graph decides]	Required	The three rules below.

A required section that is missing, or a section out of order, fails the check.
An optional section may be left out. If it is there, it must be in its place.
You may add your own sections, such as a glossary, anywhere. The check does not look at them.
If the Roles section is missing, vinc_conventions adds the default one when an assistant reads it. Your stored file stays as it is.

The generated region

The two generated sections sit between exactly one start line and one end line:

<!-- vinc:generated start ... -->
<!-- vinc:generated end -->

Do not edit inside them. The next rebuild replaces that part, and the check compares it with the graph. See what the region holds.

Relation names

In the Relations section, list only these six edge names, plus any edge type a person has ratified:

relates_to, prerequisite_of, derives_from, inherits_from, connects_via, about

Any other name in a list item there fails the check, because an assistant would copy it into the graph.

The three Do-not rules

Do not ratify your own proposal. A type an assistant made up is kept as proposed. Approving it is a person's job.
Do not create a node you did not search for first. This keeps one thing from ending up under two names.
Do not invent a domain name inline. Propose it and say why.

Length and characters

Over 75 lines asks for a fix; over 100 lines fails. The template is already 75 lines, so when you add a line, shorten another.
No em-dash. Use a colon, brackets or a new sentence.
Any vinc_ tool named in the prose must be one of the current tools, so an assistant does not call one that is gone.