# .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

```json
{
  "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`:

```json
{
  "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

```json
{
  "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.