diff --git a/packages/pointfree-lang/README.md b/packages/pointfree-lang/README.md
index 9f29d5cb84..d589ffa6d5 100644
--- a/packages/pointfree-lang/README.md
+++ b/packages/pointfree-lang/README.md
@@ -60,8 +60,6 @@ import * as pf from "@thi.ng/pointfree-lang";
 ## Usage examples
 
 ```ts
-import * as pf from "../src";
-
 // DSL source code (syntax described further below)
 
 const src = `
@@ -131,9 +129,13 @@ env.height = 480;
 // now actually call the `hairx` word with args pulled from env
 // words prefixed w/ `@` are variable lookups
 pf.run(`@mouseX @mouseY @width @height hairx`, env);
+// draw line: 100,0 -> 100,480
+// draw line: 0,200 -> 640,200
 
 // or call precompiled word/function directly w/ given initial stack
 pf.runWord("hairx", env, [100, 200, 640, 480]);
+// draw line: 100,0 -> 100,480
+// draw line: 0,200 -> 640,200
 ```
 
 ## Language & Syntax
diff --git a/packages/pointfree/README.md b/packages/pointfree/README.md
index 2a57ff5488..a1e5d198a0 100644
--- a/packages/pointfree/README.md
+++ b/packages/pointfree/README.md
@@ -2,6 +2,8 @@
 
 [![npm (scoped)](https://img.shields.io/npm/v/@thi.ng/pointfree.svg)](https://www.npmjs.com/package/@thi.ng/pointfree)
 
+This project is part of the [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo.
+
 <!-- TOC depthFrom:2 depthTo:3 -->
 
 - [About](#about)
@@ -37,9 +39,16 @@
 ## About
 
 [Pointfree](https://en.wikipedia.org/wiki/Concatenative_programming_language)
-functional composition via lightweight (~3KB gzipped), stack-based DSL:
+functional composition via lightweight (~3KB gzipped), stack-based embedded DSL.
+
+This module implements the language's core components in vanilla ES6 and
+is perfectly usable like that. **The related [@thi.ng/pointfree-lang](https://github.com/thi-ng/umbrella/tree/master/packages/pointfree-lang)
+module defines an actual language with a powerful and more concise
+syntax around this module and might be better suited for some use
+cases.**
+
+Current features:
 
-- powerful, concise syntax
 - words implemented as tiny vanilla JS functions (easily extensible)
 - optimized pre-composition/compilation of custom user defined words (see [comp.ts](https://github.com/thi-ng/umbrella/tree/master/packages/pointfree/src/comp.ts))
 - dual stack (main & stash/scratch space)