feat: add story engine HEAD main

1 files changed, 110 insertions, 0 deletions

diff --git a/src/story/README.md b/src/story/README.md
new file mode 100644
index 0000000..0cb81f4
--- /dev/null
+++ b/src/story/README.md
@@ -0,0 +1,110 @@
+## Format
+
+Here is a list of lists
+representing a slightly augmented
+deck of cards
+(basically the heckadeck):
+
+
+```
+:: suit
+spades
+hearts
+clubs
+diamonds
+acorns
+clouds
+swords
+planets
+
+:: face
+beast
+thief
+jack
+queen
+king
+
+:: number
+zero
+one
+two
+three
+four
+five
+six
+seven
+eight
+nine
+ten
+eleven
+twelve
+
+:: special
+crone
+joker
+watcher
+traveler
+
+:: card
+[[number]]
+[[face]]
+
+:: draw
+[[card]] of [[suit]]
+[[special]]
+```
+
+A list title appears on a line by itself,
+preceded by a double colon (::)
+and at least one space.
+A list title can contain alphabet characters and a dash.
+
+Following the list title are list items,
+each on its own line.
+A list item may be (or contain) a reference
+to a list title in double brackets.
+e.g. [[list-title]]
+
+Blank lines are ignored.
+
+## Usage
+
+Pass the filename of a file of lists formatted in this way
+to `create_corpus`
+and get a "corpus" in return.
+A corpus is just a deserialized fennel table
+of list titles and list items.
+
+Then pass the corpus to `flatten`
+along with a string or a list to serve as the "origin".
+In this case if you pass `corpus.draw`,
+then `flatten` will return a random selection from `:draw`,
+expanding references along the way:
+
+- beast of spades
+- five of hearts
+- jack of acorns
+- watcher
+- three of planets
+- beast of clubs
+ 
+Read and run `story.test.fnl` for an example.
+
+## Inspiration
+
+This is inspired by [tracery][1]
+and [perchance][4]
+and the [List to HTML Generator][5],
+and is similar to [twee][2] format.
+In fact,
+with just a little modification,
+you can use this story file 
+to generate tracery output
+in a twine story
+using [trice][3].
+
+[1]: https://github.com/galaxykate/tracery
+[2]: https://twinery.org/cookbook/terms/terms_twee.html
+[3]: https://github.com/incobalt/Trice
+[4]: https://perchance.org/
+[5]: https://slightadjustments.blogspot.com/p/generator.html