update docs

README.org

@@ -82,6 +82,8 @@ It consists primarily of the following components:
   - [[#can-i-opt-out-of-nix][Can I opt out of Nix?]]
   - [[#how-do-i-test-my-weave][How do I test my weave?]]
   - [[#can-i-integrate-ai-models][Can I integrate AI models?]]
+- [[#licensing][Licensing]]
+  - [[#how-it-works-1][How it works]]
 
 * Inspiration
 - [[https://github.com/enso-org/enso][Enso]]
@@ -105,7 +107,7 @@ a CLI tool, an RPC server, or a web application, to be distributed as such or in
 
 Powered by Nix, Grimu-R projects require minimal effort to build, run, or depend on.
 
-For interactive use with scripts, the default mode is runtime dependencies.
+For interactive use with scripts, the default mode is runtime dependency loading.
 
 For builds, it is recommended to have dependencies defined statically and provisioned by Nix.
 
@@ -131,7 +133,7 @@ Real code blocks in familiar languages are prioritized from day one, leveraging
 
 Get started without implementing your own components.
 
-No code to low code to high code.
+Low code to high code.
 
 * Non-goals
 Some things Grimu-R itself will not take care of, delegating them to the surrounding environment:
@@ -164,7 +166,7 @@ Below is a brief explanation for the key terms:
 
 A Grimu-R project's weave is what changes when someone is working on it ("weaving").
 
-It's a persistent representation of the dataflow graph and its graphic layout.
+It's a persistent, Git-friendly representation of the dataflow graph and its graphic layout.
 
 ** Ornament
 
@@ -291,3 +293,31 @@ There are three integration scenarios which would make sense:
 #1 is easy to do even with no out-of-the-box support.
 
 #2 and #3 would require some work on development tooling.
+
+* Licensing
+The Grimu-R platform components, including Loom development utilities and
+the execution engine, are licensed under AGPL v3.
+
+Base scrolls and other non-platform code are licensed under MIT.
+
+** Repository Structure                                           :noexport:
+In this repository:
+- Platform components are in the ~platform/~ directory
+- Everything outside ~platform/~ falls under MIT licensing
+- Full license texts are in ~LICENSE_PLATFORM~ and ~LICENSE_AMBIENT~
+
+** Copyright and Contributions                                     :noexport:
+Copyright (C) 2025 Voleum
+
+By contributing to this repository, you assign your copyright to Voleum under
+the condition that your contribution will always remain available under the
+original license terms specified above.
+
+Alternative contribution arrangements may be available upon request.
+
+** How it works
+If you fork the platform and build a product on top of its code,
+the fork MUST be licensed under AGPL v3 (or a more restrictive copyleft license),
+even if it's a cloud product.
+
+All other code can be used without restrictions.

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

@@ -6,11 +6,39 @@
 body {
   font-family: 'Courier New', Courier, monospace;
   background-color: ivory;
-  line-height: 1.3;
+  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 {
-  margin-left: 1em;
+  padding-left: 1em;
+}
+
+a:link { 
+  color: #2E5EAA;
+  text-decoration: none;
+}
+a:visited { 
+  color: #663399;
+}
+a:hover { 
+  color: #1a4480; 
+  text-decoration: underline; 
 }
 </style>
 #+END_EXPORT
@@ -21,33 +49,39 @@ Defines a collection of ornaments.
 ** Ornament
 Has reactive inputs and outputs.
 Serves as an externally invocable entry point.
-Contains spells or nested ornaments.
-Can be distributed within a grimoire or a servitor.
+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 externally.
+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 all the scrolls defined in a project as well as its dependencies.
+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 set of ornaments as a program with human-facing interface.
+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 set of ornaments as a local/remote daemon/server endpoints/methods.
+Presents a subweave as a local/remote daemon's/server's endpoints/methods.
 ** Loom
 Provisions tools for interactive or programmatic weaving.