update docs

README.org

@@ -49,7 +49,7 @@ Grimu-R is an *open ecosystem* and a framework for mixed visual-textual *dataflo
 It consists primarily of the following components:
 - Execution model allowing computations to be expressed as *reactive graphs*
 - *Polyglot scripting* runtime environment
-- Live web-based *visual-textual* editor
+- Interactive web-based *visual-textual* editor
 #+TOC: headlines 2
 * Table of Contents                                                :TOC_2_gh:noexport:
 - [[#inspiration][Inspiration]]
@@ -78,10 +78,10 @@ It consists primarily of the following components:
 - [[#features][Features]]
 - [[#faq][FAQ]]
   - [[#is-this-a-yet-another-web-framework][Is this a yet another web framework?]]
-  - [[#a-user-can-execute-arbitrary-code-on-my-backend-really][A user can execute arbitrary code on my backend? Really?]]
+  - [[#how-does-malleability-work-in-client-server-applications][How does malleability work in client-server applications?]]
   - [[#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-intergate-ai-models][Can I intergate AI models?]]
+  - [[#can-i-integrate-ai-models][Can I integrate AI models?]]
 
 * Inspiration
 - [[https://github.com/enso-org/enso][Enso]]
@@ -105,6 +105,10 @@ 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 builds, it is recommended to have dependencies defined statically and provisioned by Nix.
+
 ** Reactivity taken seriously
 
 Push or pull? Throttle, debounce, batch?
@@ -133,9 +137,8 @@ No code to low code to high code.
 Some things Grimu-R itself will not take care of, delegating them to the surrounding environment:
 
 - Resumable/durable execution
-- Distributed computing (outside of client-server) 
+- Distributed deployment orchestration
 - Collaborative editing
-- Untrusted code sandboxing
 - Authentication and access control
 - Telemetry
 * Use cases
@@ -196,7 +199,7 @@ directly in the visual editor, enabling live code changes without rebuilding the
 * How it works
 ** Development environment
 
-Grimu-R projects being Nix flakes, the development tooling ("loom") is provisioned as a Nix shell.
+Grimu-R projects being Nix flakes, the development tooling ("loom") is provisioned in a Nix shell.
 
 It gives you the visual editor, the companion CLI tool and the execution context for spells.
 
@@ -205,7 +208,7 @@ It gives you the visual editor, the companion CLI tool and the execution context
 - The visual editor is served by a development or application server.
 - Changes and execution requests for server-side spells are sent over a bidirectional WebSocket connection.
 - User modifications are stored locally in the browser's storage, exportable as a file.
-- Weaves are tracked by usual VSC tools.
+- Weaves are tracked by usual VCS tools.
 
 ** Cross-language connections
 
@@ -213,10 +216,14 @@ Think Unix pipes but with structured data formats like JSON lines instead of pla
 
 ** Execution environment
 
-Scrolls used in a weave have their requirements defined in Nix terms.
+Purpose-specific scrolls used in a weave have their requirements defined in Nix terms.
 
-For example, if several scrolls need Node.js, they can all refer to the same nodejs Nix package defined in the flake.
-All of that, and optionally the visual editor, is bundled into a target build ("edition").
+For example, if several scrolls need Deno, they can all refer to the same deno Nix package defined in the flake and declare their Deno dependencies normally.
+
+A single copy of Deno runtime and a shared Deno cache would be bundled in an edition.
+
+However, the general-purpose Deno scroll executing arbitrary TypeScript inscriptions
+would have Deno fetch dependencies during runtime.
 
 * Features
 |                          | On the roadmap                 | Ideas              |
@@ -238,16 +245,13 @@ One framework called [[https://cycle.js.org/][Cycle.js]] defines a web applicati
 Grimu-R can do a similar thing if you want it to.
 Or you could use any framework you like with the dataflow stuff being incidental.
 
-** A user can execute arbitrary code on my backend? Really?
+** How does malleability work in client-server applications?
 
-By default, any client-server Grimu-R build ("edition") would allow users to see
-and edit client-side parts of the weave only.
+Unlike standalone editions executing entirely on the end user's machine,
+client-server editions split the weave between runtime components.
 
-This is but superficially different from users messing around in their
-browser's console or employing a browser extension.
-
-On the other hand, if the server-side parts run in a trusted environment with authorized access,
-you could give users a more generous degree of control.
+Only the client-side part of the weave can be inspected and edited by
+the end user.
 
 ** Can I opt out of Nix?
 
@@ -257,6 +261,8 @@ While Grimu-R is built on top of Nix and wouldn't make a lot of sense otherwise,
 you always have the option to access out-of-store files from your spells' inscriptions,
 at the cost of reproducibility.
 
+So you could use e. g. runtime JS imports or call some executable on PATH from a shell script.
+
 ** How do I test my weave?
 
 If you do it manually: right in the visual editor.
@@ -265,10 +271,23 @@ Add spells with a constant output as test data sources and stitch them to the sp
 If you need automation: build an edition and call the ornaments programmatically.
 If you already have test data stored in the weave, you can extract it by the spell's id using loom CLI or library.
 
-** Can I intergate AI models?
+** Can I integrate AI models?
 
-If you want something like [[https://computer.tldraw.com/][tldraw computer]], Grimu-R would accomodate that and beyond,
-potentially supporting fancier features like tool use and MCP servers.
+There are three integration scenarios which would make sense:
 
-However, until someone contributes scrolls tailored for the purpose, Grimu-R would offer worse ergonomics.
+1. AI spells in the weave:
 
+   Spells calling inference APIs, equipped with MCP spells and
+   template spells for prompt composition
+
+2. AI weaving copilot:
+
+   Loom providing AI tools to edit the weave
+
+3. MCP server editions:
+
+   Ornaments exposed as tools for external AI systems
+
+#1 is easy to do even with no out-of-the-box support.
+
+#2 and #3 would require some work on development tooling.

vocabulary.org

@@ -18,27 +18,36 @@ body {
 
 ** Weave
 Defines a collection of ornaments.
-Can assign one weave as default.
 ** 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.
 ** Spell
 Has reactive inputs and outputs.
 Atomic execution unit.
 Cannot be directly invoked externally.
 May have an inscription.
-Created from a scroll and executed in its runtime environment.
+Created from a scroll and executed in the shelf environment.
 ** Stitch
 Connects a reactive input to a compatible reactive output.
 ** Inscription
-Defines code in a scripting language to be ran when the corresponding spell is executed.
+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.
+Declares runtime compatibility (browser-only, non-browser, or universal).
 ** Shelf
 Contains all the scrolls defined in a project as well as its dependencies.
+Provisions a shared runtime environment for spells based on these scrolls.
 ** Edition
-Represents a weave as a compiled program.
+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.
+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.
 ** Loom
 Provisions tools for interactive or programmatic weaving.