Summary
The README sells the idea, docs/words.md catalogues the 315 primitives,
and the whitepaper covers the theory. There is currently no short,
hands-on walkthrough for a reader who has just run cargo install unit,
hit >, and is wondering what to type. The closest thing is the embedded
tutorial in the WASM demo, which a CLI-first reader will never see.
This issue is to write docs/first-word.md: a 5–10 minute walkthrough
that takes a reader from 2 3 + . to defining their own Forth word,
inspecting it with SEE, listing the dictionary with WORDS, and finally
sharing it across two units on the local mesh with SHARE-ALL /
SHARED-WORDS. The goal is to leave the reader with a working mental
model of what "the dictionary is the genome" actually means.
Why it's a good first issue
It's a docs PR — no Rust, no WASM, no test surface. But the writer has to
use unit to write it, which means a contributor will end up touching
the REPL, the mesh, and the dictionary while producing something that
will help every reader who comes after them.
It's also concrete and finishable in one evening. The shape is fixed:
intro paragraph, a sequence of REPL transcripts with brief commentary
between them, a closing pointer to docs/words.md and the demo.
Acceptance criteria
Where to look
README.md — tone reference; the "Try It" section is roughly the
prose register to aim for.
docs/words.md — the catalogue this walkthrough complements.
src/prelude.fs — examples of idiomatic :/; definitions.
justfile — just swarm 2 is the easiest way to bring up two units
on loopback for the sharing demo.
Nice-to-haves (not required)
- A short "what's next" paragraph pointing at
SPAWN, GP-EVOLVE, the
immune system, and the v0.28 signaling words (SAY!, LISTEN,
COURT, see docs/signaling.md) as natural
next steps.
Summary
The README sells the idea,
docs/words.mdcatalogues the 315 primitives,and the whitepaper covers the theory. There is currently no short,
hands-on walkthrough for a reader who has just run
cargo install unit,hit
>, and is wondering what to type. The closest thing is the embeddedtutorial in the WASM demo, which a CLI-first reader will never see.
This issue is to write
docs/first-word.md: a 5–10 minute walkthroughthat takes a reader from
2 3 + .to defining their own Forth word,inspecting it with
SEE, listing the dictionary withWORDS, and finallysharing it across two units on the local mesh with
SHARE-ALL/SHARED-WORDS. The goal is to leave the reader with a working mentalmodel of what "the dictionary is the genome" actually means.
Why it's a good first issue
It's a docs PR — no Rust, no WASM, no test surface. But the writer has to
use unit to write it, which means a contributor will end up touching
the REPL, the mesh, and the dictionary while producing something that
will help every reader who comes after them.
It's also concrete and finishable in one evening. The shape is fixed:
intro paragraph, a sequence of REPL transcripts with brief commentary
between them, a closing pointer to
docs/words.mdand the demo.Acceptance criteria
docs/first-word.md.: NAME ... ;, calling it, inspecting it withSEE, listing thedictionary with
WORDS, and sharing/receiving the word across twounitprocesses on loopback.no invented prompts or values.
docs/words.mdfor the full referenceand the live demo URL for readers who don't want to install.
README.md.Where to look
README.md— tone reference; the "Try It" section is roughly theprose register to aim for.
docs/words.md— the catalogue this walkthrough complements.src/prelude.fs— examples of idiomatic:/;definitions.justfile—just swarm 2is the easiest way to bring up two unitson loopback for the sharing demo.
Nice-to-haves (not required)
SPAWN,GP-EVOLVE, theimmune system, and the v0.28 signaling words (
SAY!,LISTEN,COURT, see docs/signaling.md) as naturalnext steps.