docs/README.md · jibb · git.iko.soy

git.iko.soy/jibb

jibb/docs/README.md

39 lines 3.5 kB history raw

1# Docs

3Jibb's spec is a design doc by @iko, [Jibb — an Elm-architecture UI language for Urbit](https://claude.ai/artifact/DMBr48qzi5z8hcwn2ccPBv), and its repository copy in `spec/`. The repository copy records decisions made on 2026-10-30, including dropping `$?`, adding `%$` as a term literal and pattern, making `@` an unrestricted atom, treating `?` as two atoms for union disjointness, and the milestone 2 type and prelude decisions; the Claude document still needs to be synchronized. This folder also holds where the build stands, what is still open, and how to work on the code.

5| File | What it holds |

6| --- | --- |

7| [spec/](spec/) | The doc's tabs, as Markdown |

8| [status.md](status.md) | The eight milestones, what milestone 1 built, and how to check it |

9| [open-questions.md](open-questions.md) | Questions still open: the plan's, the grammar's, and those milestone 2 raises |

10| [development.md](development.md) | Setting up a machine, the ground rules, the checks to run before pushing |

11| [compiler.md](compiler.md) | A map of `jibb-dev/lib/jibb.hoon`: its API, data, errors and printed formats |

12| [prelude-inventory.md](prelude-inventory.md) | Working source audit for the prelude's exported inventory |

13| [prompts/milestone-2.md](prompts/milestone-2.md) | A brief for the developer who builds milestone 2, types and prelude |

14| [prompts/drop-union-rune.md](prompts/drop-union-rune.md) | The completed brief for dropping `$?`, as decided on 2026-10-30, before milestone 2 |

16## The spec

18`spec/` began as a snapshot of the doc taken on 2026-10-30, after @iko's answers to the 12 grammar questions that day. It has since been edited to record decisions including dropping `$?`, local type-variable scope, cells and changes, record faces, and the noun type `*`; the Claude document still needs those edits. It also has the doc's rules of the same day for gates generic over auras. Each file corresponds to one tab:

20| File | Tab |

21| --- | --- |

22| [spec/overview.md](spec/overview.md) | Jibb — an Elm-architecture UI language for Urbit: the language, the stages, the mark, the host, worked examples |

23| [spec/grammar.md](spec/grammar.md) | Grammar: lexical rules, literals, runes, imports, modules, molds, tag resolution, patterns, the EBNF |

24| [spec/core-language.md](spec/core-language.md) | Core language: the untyped language between the checker and both backends |

25| [spec/decisions.md](spec/decisions.md) | Decisions: every choice, with the date it was made |

26| [spec/implementation-plan.md](spec/implementation-plan.md) | Implementation plan: the eight milestones, ground rules, architecture, risks, open questions |

28The doc has a sixth tab, "Loom on Urbit", which is empty, so it has no file.

30The overview's pipeline diagram, "Jibb pipeline · source to browser in three stages", is embedded content, so the export holds only a placeholder line for it under Architecture. The doc shows it.

32The two copies can diverge. Sync the repository decisions to the Claude document before refreshing this copy, then export each tab as Markdown again (in a Claude session, the Claude Docs connector's `export` gives each tab's Markdown), replace the files, and run:

34```

35git diff docs/spec # what changed in the doc

36tools/doc-blocks docs/spec # every code block labelled jibb has its golden case

37```

39A `jibb` block that changed or is new needs its golden case, `tests/golden/doc-<tab>-<n>-<what>/`, where `<n>` counts every code block of the tab, labelled or not ([development.md](development.md)).