.fyi page spec for agents

This is the machine-readable spec for creating .fyi page files.

Fetch this markdown. Do not scrape the HTML app shell.

Raw markdown: /fyi-page-instructions.md
Human HTML (same schema, app chrome): /fyi-page-instructions
HTML view of this spec: /fyi-page-instructions/agent

The .fyi format is JSON, not a binary format. It is used by FYINotes, ApuntesIA, and WorkStream Manager.

If an MCP client is connected to FYI Pages, prefer create_fyi_page, get_fyi_page, add_fyi_notes, and update_fyi_notes instead of emitting a .fyi file, unless the user asks for a file.

Goal

Produce one complete .fyi file as valid JSON with:

id: page id
d: visible document
b: paired blob/body document

d stores titles, labels, URLs, columns, order, and symbols.

b stores longer body text for expandable notes.

Matching note ids in d and b pair titles with bodies.

Output rules

Return only valid JSON. No markdown fences, comments, or trailing commas.
Use unique integer ids. Prefer epoch milliseconds for the page id, then increment by one per note.
Keep id, d.uDocs.meta.id, b.uDocs.meta.id, d.uDocs.pub.id, and b.uDocs.pub.id the same.
Set d.uDocs.meta.typ to "d" and b.uDocs.meta.typ to "b".
Set page v to 18, pub v to 4, note v to 12.
Set uDocs.meta.cat and uDocs.pub.cat to "General" unless the app provides another approved publish category. Do not put topic names such as Home, Work, or Travel in meta.cat.
Set every note alrm to 0 unless the user asks for an alarm (epoch ms).
Set each note enc to 1 and store body text as raw Unicode. Do not HTML-escape &, ", <, > in storage. Missing/0 is legacy HTML-entity storage. enc: 2 is JSON text in t1 for type "11".
Safe plain text only. No scripts, event handlers, script tags, iframes, forms, or invented URLs.

After creating d.uDocs.meta and d.uDocs.pub, deep-copy them into b, then set b.uDocs.meta.typ to "b".

Page schema

{
  "id": 1777777777000,
  "d": {
    "uDocs": {
      "meta": {
        "id": 1777777777000,
        "name": "Page Title",
        "ty": "000000",
        "auth": "",
        "updt": 1777777777000,
        "vu": "",
        "clck": 0,
        "gclk": 0,
        "col": "3",
        "cols": "true",
        "cat": "General",
        "skey": "outside-model-1777777777000",
        "v": 18,
        "s": 0,
        "u": "",
        "u1": "",
        "u2": "",
        "u3": "",
        "fav": 0,
        "typ": "d"
      },
      "coltxt": [["0","1","2","3","4","5","6","7","8","9","10","11","12"], [], [], [], [], [], [], [], [], [], [], [], []],
      "zdata": [],
      "pub": {
        "v": 4,
        "title": "Page Title",
        "cat": "General",
        "id": 1777777777000,
        "wType": "",
        "signature": "",
        "pw": "",
        "sURL1": "",
        "sURL2": "",
        "sURL3": "",
        "sURL4": "",
        "pURL": "",
        "wURL": "",
        "cURL": "",
        "mURL": "",
        "Notes": ""
      },
      "tabs": ["", "", "", "", "", "", "", "", "", "", "", "", ""],
      "colb": [1, 1, 1, "eng"]
    }
  },
  "b": {
    "uDocs": {
      "meta": {},
      "coltxt": [["0","1","2","3","4","5","6","7","8","9","10","11","12"], [], [], [], [], [], [], [], [], [], [], [], []],
      "zdata": [],
      "pub": {},
      "tabs": ["", "", "", "", "", "", "", "", "", "", "", "", ""],
      "colb": [1, 1, 1, "eng"]
    }
  }
}

Note schema

Each uDocs.zdata item is a note. Use the same shape in d and b:

{
  "id": 1777777777001,
  "col": 1,
  "css": "",
  "ty": "1",
  "t0": "Visible note title",
  "t1": "",
  "t2": "",
  "t3": "",
  "t4": "",
  "t5": "",
  "t6": "",
  "ordr": 100,
  "updt": 1777777777000,
  "bdt": 0,
  "clck": 0,
  "gclk": 0,
  "v": 12,
  "s": 0,
  "u": 0,
  "pre1": 0,
  "pre2": 2,
  "grp": 0,
  "lvl": 0,
  "pop": 0,
  "tab": 0,
  "pa": 0,
  "alrm": 0,
  "enc": 1
}

d and b notes should share id, col, ty, t0, ordr, pre2, pa, alrm, and enc.

Short/large notes: title in d.t0, longer body in matching b.t1.
URL notes: label in d.t0, URL in d.t1.
JSON notes ("11"): title in d.t0, JSON text in b.t1, enc: 2 on both records.
Mermaid notes ("12"): title in d.t0, diagram source in b.t1, enc: 1 on both records. The file stores source text only.

Space ordr by 100 (100, 200, 300).

Note types (`ty`)

Value	Meaning
`"1"`	Text note
`"2"`	Small expandable note
`"3"`	Large note
`"4"`	URL-style item
`"5"`	Horizontal rule
`"6"`	Phone note
`"7"`	Section header
`"8"`	Email note
`"9"`	Block note
`"10"`	Container block note
`"11"`	JSON note (`enc: 2`, JSON in `b.t1`)
`"12"`	Mermaid note (`enc: 1`, source in `b.t1`)

For most generated pages use "7" headers, "1" short facts, "2" expandable notes, "3" long notes, "5" optional dividers, and "12" only when a diagram is requested.

Symbols (`pre2`)

Value	Meaning
`0`	No symbol
`1`	Arrow / marker
`2`	Bullet
`3`	Empty checkbox / todo
`4`	Checked checkbox
`5`	Star / important
`6`	Warning
`7`	Urgent
`8`	Heart / favorite
`9`	Flag / milestone

Headers normally use pre2: 0.

Column layout

Set meta.col to the column count as a string, commonly "2" or "3".

Assign each note col from 1 through that count.

Keep a section and its child notes in the same column.

Set meta.cols to "true" when column layout is enabled.

Content rules

Use section headers. Keep t0 short. Put long text in b.t1.
Checkboxes only for actions. Warnings only for real risks.
Do not invent URLs. If a link checker is available, skip 404 responses.

Minimal example

{
  "id": 1777777777000,
  "d": {
    "uDocs": {
      "meta": {
        "id": 1777777777000,
        "name": "Sample Project Plan",
        "ty": "000000",
        "auth": "",
        "updt": 1777777777000,
        "vu": "",
        "clck": 0,
        "gclk": 0,
        "col": "2",
        "cols": "true",
        "cat": "General",
        "skey": "outside-model-1777777777000",
        "v": 18,
        "s": 0,
        "u": "",
        "u1": "",
        "u2": "",
        "u3": "",
        "fav": 0,
        "typ": "d"
      },
      "coltxt": [["0","1","2","3","4","5","6","7","8","9","10","11","12"], [], [], [], [], [], [], [], [], [], [], [], []],
      "zdata": [
        {"id":1777777777001,"col":1,"css":"sB","ty":"7","t0":"Planning","t1":"","t2":"","t3":"","t4":"","t5":"","t6":"","ordr":100,"updt":1777777777000,"bdt":0,"clck":0,"gclk":0,"v":12,"s":0,"u":0,"pre1":0,"pre2":0,"grp":0,"lvl":0,"pop":0,"tab":0,"pa":0,"alrm":0,"enc":1},
        {"id":1777777777002,"col":1,"css":"","ty":"2","t0":"Define the goal","t1":"","t2":"","t3":"","t4":"","t5":"","t6":"","ordr":200,"updt":1777777777000,"bdt":0,"clck":0,"gclk":0,"v":12,"s":0,"u":0,"pre1":0,"pre2":3,"grp":0,"lvl":0,"pop":0,"tab":0,"pa":0,"alrm":0,"enc":1},
        {"id":1777777777003,"col":2,"css":"sB","ty":"7","t0":"Risks","t1":"","t2":"","t3":"","t4":"","t5":"","t6":"","ordr":300,"updt":1777777777000,"bdt":0,"clck":0,"gclk":0,"v":12,"s":0,"u":0,"pre1":0,"pre2":0,"grp":0,"lvl":0,"pop":0,"tab":0,"pa":0,"alrm":0,"enc":1},
        {"id":1777777777004,"col":2,"css":"","ty":"1","t0":"Confirm dependencies before scheduling.","t1":"","t2":"","t3":"","t4":"","t5":"","t6":"","ordr":400,"updt":1777777777000,"bdt":0,"clck":0,"gclk":0,"v":12,"s":0,"u":0,"pre1":0,"pre2":6,"grp":0,"lvl":0,"pop":0,"tab":0,"pa":0,"alrm":0,"enc":1}
      ],
      "pub": {
        "v": 4,
        "title": "Sample Project Plan",
        "cat": "General",
        "id": 1777777777000,
        "wType": "",
        "signature": "",
        "pw": "",
        "sURL1": "",
        "sURL2": "",
        "sURL3": "",
        "sURL4": "",
        "pURL": "",
        "wURL": "",
        "cURL": "",
        "mURL": "",
        "Notes": ""
      },
      "tabs": ["", "", "", "", "", "", "", "", "", "", "", "", ""],
      "colb": [1, 1, 1, "eng"]
    }
  },
  "b": {
    "uDocs": {
      "meta": {
        "id": 1777777777000,
        "name": "Sample Project Plan",
        "ty": "000000",
        "auth": "",
        "updt": 1777777777000,
        "vu": "",
        "clck": 0,
        "gclk": 0,
        "col": "2",
        "cols": "true",
        "cat": "General",
        "skey": "outside-model-1777777777000",
        "v": 18,
        "s": 0,
        "u": "",
        "u1": "",
        "u2": "",
        "u3": "",
        "fav": 0,
        "typ": "b"
      },
      "coltxt": [["0","1","2","3","4","5","6","7","8","9","10","11","12"], [], [], [], [], [], [], [], [], [], [], [], []],
      "zdata": [
        {"id":1777777777001,"col":1,"css":"sB","ty":"7","t0":"Planning","t1":"","t2":"","t3":"","t4":"","t5":"","t6":"","ordr":100,"updt":1777777777000,"bdt":0,"clck":0,"gclk":0,"v":12,"s":0,"u":0,"pre1":0,"pre2":0,"grp":0,"lvl":0,"pop":0,"tab":0,"pa":0,"alrm":0,"enc":1},
        {"id":1777777777002,"col":1,"css":"","ty":"2","t0":"Define the goal","t1":"Write the outcome in one sentence, list the owner, and identify the first measurable success point.","t2":"","t3":"","t4":"","t5":"","t6":"","ordr":200,"updt":1777777777000,"bdt":0,"clck":0,"gclk":0,"v":12,"s":0,"u":0,"pre1":0,"pre2":3,"grp":0,"lvl":0,"pop":0,"tab":0,"pa":0,"alrm":0,"enc":1},
        {"id":1777777777003,"col":2,"css":"sB","ty":"7","t0":"Risks","t1":"","t2":"","t3":"","t4":"","t5":"","t6":"","ordr":300,"updt":1777777777000,"bdt":0,"clck":0,"gclk":0,"v":12,"s":0,"u":0,"pre1":0,"pre2":0,"grp":0,"lvl":0,"pop":0,"tab":0,"pa":0,"alrm":0,"enc":1},
        {"id":1777777777004,"col":2,"css":"","ty":"1","t0":"Confirm dependencies before scheduling.","t1":"","t2":"","t3":"","t4":"","t5":"","t6":"","ordr":400,"updt":1777777777000,"bdt":0,"clck":0,"gclk":0,"v":12,"s":0,"u":0,"pre1":0,"pre2":6,"grp":0,"lvl":0,"pop":0,"tab":0,"pa":0,"alrm":0,"enc":1}
      ],
      "pub": {
        "v": 4,
        "title": "Sample Project Plan",
        "cat": "General",
        "id": 1777777777000,
        "wType": "",
        "signature": "",
        "pw": "",
        "sURL1": "",
        "sURL2": "",
        "sURL3": "",
        "sURL4": "",
        "pURL": "",
        "wURL": "",
        "cURL": "",
        "mURL": "",
        "Notes": ""
      },
      "tabs": ["", "", "", "", "", "", "", "", "", "", "", "", ""],
      "colb": [1, 1, 1, "eng"]
    }
  }
}

System prompt

You create .fyi pages. Return only valid JSON. Use this schema exactly: top-level id, visible document d, and blob/body document b. Use unique epoch-millisecond-style ids. Use page meta version 18, note version 12, pub version 4, uDocs.meta.cat: "General", uDocs.pub.cat: "General", note alrm: 0 unless alarms are requested, and note enc: 1 with raw Unicode body text except JSON notes (ty: "11", enc: 2). Use ty: "7" for section headers, ty: "1" for normal text, ty: "2" for expandable small notes, ty: "3" for long notes, ty: "11" for JSON notes, and ty: "12" for Mermaid diagram notes (source in b.t1, enc: 1). Use pre2 symbols: 0 none, 1 arrow, 2 bullet, 3 todo, 4 checked, 5 star, 6 warning, 7 urgent, 8 heart, 9 flag. Put visible titles in d.uDocs.zdata[].t0. Put longer body text in matching b.uDocs.zdata[].t1. Put URLs in d.uDocs.zdata[].t1 only when valid. No scripts, event handlers, iframes, forms, or invented links.

Validation checklist

JSON parses.
Top-level keys are id, d, and b.
d.uDocs and b.uDocs exist.
d.uDocs.meta.typ is "d" and b.uDocs.meta.typ is "b".
Both zdata arrays exist and use matching ids.
Every note has id, col, ty, t0, ordr, updt, v, pre2, pa, alrm, and enc.
pre2 is an integer from 0 through 9.
ordr values are sorted and spaced.
No unsafe HTML or executable code.
Included URLs are verified when a link checker is available.