update docs

doc/stories.org

@@ -0,0 +1,69 @@
+:PROPERTIES:
+:ID:       bbd0d76c-33c8-47d7-8eb7-79f5f9e5e633
+:END:
+#+title: Grimu-R stories
+#+STARTUP: show3levels
+
+* As a Grimu-R project developer, I want
+** To get started quickly
+*** And import my lousy shell scripts or code notebooks
+*** And have the entire dev environment set up with a single command
+*** And employ readily available scrolls, such as
+**** A wrapper supporting most Unix utilities specified via inscription
+**** HTTP fetch / post / stream / subscribe to event source
+**** General purpose templates (Mustache)
+**** Basic HTML with simple query param state
+**** Large file reader, the file being
+***** Arbitrary text (streamed)
+***** CSV / JSON lines
+***** SQLite / DuckDB database
+**** Integrations for services like
+***** Telegram
+***** Slack
+***** Database servers
+** To have full granular control over weave's dataflow
+*** And push or pull data as needed
+*** And batch data
+*** And throttle/debounce data
+*** And retry computations if they fail
+**** With flexible custom retry policies
+** To depend on other Grimu-R projects
+*** And get their environments composed with mine
+*** And use their scrolls
+*** And use their ornaments
+** To author scroll/spell code in
+*** Browser JavaScript
+*** Deno TypeScript
+*** GHC Haskell
+*** SQL (DuckDB, SQLite)
+*** Python
+** To extend the available toolset
+*** By authoring my own scrolls
+*** By calling executables outside of the Nix store
+*** By upstreaming support for new programming language with its ecosystem
+** To deploy my project as
+*** Standalone CLI
+*** CLI + RPC server
+*** Web application server hosting a frontend
+*** Mobile application
+*** React component
+** To interact with the weave programmatically
+*** And inspect its contents
+*** And run ornaments
+*** And edit it
+*** And check its validity
+* As a Grimu-R project user, I want
+** To build and host it myself
+** To use loom to edit the client-side part of the weave
+** To keep the changes I made
+*** In the browser's local storage
+*** And export them elsewhere
+* As a Grimu-R loom visual editor consumer, I want
+** To use it interactively
+*** And see the actual data passing across stitches
+*** And test parts of the weave with mock data
+*** And quickly add debug displays
+*** And change the inscriptions
+**** Right in the visual editor
+**** In an external editor of my preference
+*** And undo/redo my changes

doc/vocabulary.org

@@ -0,0 +1,87 @@
+:PROPERTIES:
+:ID:       00790dad-7881-4252-8951-23f770e3f070
+:END:
+#+BEGIN_EXPORT html
+<style>
+body {
+  font-family: 'Courier New', Courier, monospace;
+  background-color: ivory;
+  line-height: 1.5;
+  padding-right: 1em;
+}
+
+h2 {
+  margin-top: 1.8rem;
+  padding-left: 0.5rem;
+  border-left: 4px solid #3498db;
+}
+
+
+table {
+  width: 100%;
+}
+
+#content {
+  max-width: 48em;
+}
+
+.outline-2 div {
+  padding-left: 1em;
+}
+
+a:link { 
+  color: #2E5EAA;
+  text-decoration: none;
+}
+a:visited { 
+  color: #663399;
+}
+a:hover { 
+  color: #1a4480; 
+  text-decoration: underline; 
+}
+</style>
+#+END_EXPORT
+#+title: Grimu-R vocabulary
+
+** Weave
+Defines a collection of ornaments.
+** Ornament
+Has reactive inputs and outputs.
+Serves as an externally invocable entry point.
+Contains spells or nested ornament instances connected by stitches.
+Can be distributed within an edition.
+** Spell
+Has reactive inputs and outputs.
+Atomic execution unit.
+Cannot be directly invoked by an edition consumer.
+May have an inscription.
+Created from a scroll and executed in the shelf environment.
+** Stitch
+Connects a reactive input to a compatible reactive output.
+Can be decorated on both upstream and downstream ends.
+May be parameterized by a reactive input, consuming variable assignments for the decoration.
+** Stitch decorator
+Defines reactive behavior.
+May refer to variables defined by the reactive input.
+** Inscription
+Defines code in a scripting language to be run when the corresponding spell is executed.
+May be defined statically in the weave or considered a reactive input.
+** Scroll
+Defines source code, its build dependencies and runtime environment.
+Provides a default spell configuration.
+Provides default upstream/downstream stitch decorators for outputs/inputs respectively.
+Declares runtime compatibility (browser-only, non-browser, or universal).
+** Shelf
+Contains a collection of scrolls.
+Provisions a shared runtime environment for spells based on these scrolls.
+** Edition
+Represents (a part of) the weave as a grimoire, a servitor, or a consistent collection of these.
+** Grimoire
+Presents a subweave as a program with human-facing interface.
+Uses bridge spells to communicate with servitor-side ornaments within the same edition.
+Has a dedicated interface ornament (entry point).
+** Servitor
+Presents a subweave as a local/remote daemon's/server's endpoints/methods.
+** Loom
+Provisions tools for interactive or programmatic weaving.