clojure(docs[guide]): Fix reader wording and links

docs/guide/clojure.md

@@ -4,10 +4,10 @@
 encoding, transport, server identity and compatibility in Java, while exposing
 captured persistent Clojure values and ordinary collection operations.
 
-Start with the package [README](../../libtmux-clojure/README.md) for the
-install boundary and one capture. This guide explains the choices that matter
-after the first program: what is captured, what can perform I/O, who owns
-workers and streams, and where model-facing MCP tooling begins.
+Start with the [install and quick start](../../libtmux-clojure/README.md) for
+the install boundary and one capture. This guide explains the choices that
+matter after the first program: what is captured, what can perform I/O, who
+owns workers and streams, and where model-facing MCP tooling begins.
 
 The native API references list every documented public var in
 [the core façade](clojure-api.md) and
@@ -134,16 +134,16 @@ submission does not add another tmux transport or alter the captured values.
 
 <!-- clojure-snippet: fixture -->
 ```clojure
-(require '[libtmux.async :as async]
+(require '[libtmux.async :as tm-async]
          '[libtmux.core :as tm])
 
 (let [socket-path (java.nio.file.Path/of
                    (System/getProperty "libtmux.docs.socket")
                    (make-array String 0))]
   (with-open [server (tm/open! {:socket-path socket-path})
-              runtime (async/runtime! {:max-running 3})]
+              runtime (tm-async/runtime! {:max-running 3})]
     (tm/new-session! server {:name "docs-parallel"})
-    (let [tasks (mapv (fn [_] (async/submit! runtime #(tm/snapshot! server)))
+    (let [tasks (mapv (fn [_] (tm-async/submit! runtime #(tm/snapshot! server)))
                       (range 2))]
       (mapv #(boolean (some (fn [session]
                               (= "docs-parallel" (:session/name session)))
@@ -158,22 +158,22 @@ started. Use a separate `:wait` task for operations that wait for a release.
 
 <!-- clojure-snippet: fixture -->
 ```clojure
-(require '[libtmux.async :as async]
+(require '[libtmux.async :as tm-async]
          '[libtmux.core :as tm])
 (import '[java.time Duration])
 
 (let [socket-path (java.nio.file.Path/of
                    (System/getProperty "libtmux.docs.socket")
                    (make-array String 0))]
   (with-open [server (tm/open! {:socket-path socket-path})
-              runtime (async/runtime! {})]
+              runtime (tm-async/runtime! {})]
     (let [started (promise)
-          task (async/submit! runtime {:kind :wait}
-                              #(do (deliver started true)
-                                   (tm/await-channel! server "docs-cancel"
-                                      (Duration/ofSeconds 20))))]
+          task (tm-async/submit! runtime {:kind :wait}
+                                 #(do (deliver started true)
+                                      (tm/await-channel! server "docs-cancel"
+                                         (Duration/ofSeconds 20))))]
       @started
-      (async/cancel! task)
+      (tm-async/cancel! task)
       (try
         @task
         (catch clojure.lang.ExceptionInfo failure
@@ -369,7 +369,7 @@ explicitly when ownership requires it.
 
 <!-- clojure-snippet: fixture -->
 ```clojure
-(require '[libtmux.async :as async]
+(require '[libtmux.async :as tm-async]
          '[libtmux.core :as tm]
          '[manifold.deferred :as deferred])
 (import '[java.util.concurrent CompletionStage])
@@ -378,14 +378,14 @@ explicitly when ownership requires it.
                    (System/getProperty "libtmux.docs.socket")
                    (make-array String 0))]
   (with-open [server (tm/open! {:socket-path socket-path})
-              runtime (async/runtime! {})]
+              runtime (tm-async/runtime! {})]
     (tm/new-session! server {:name "docs-manifold"})
-    (let [task (async/submit! runtime #(tm/snapshot! server))
-          stage (async/then! runtime task
-                             #(boolean (some (fn [session]
-                                               (= "docs-manifold"
-                                                  (:session/name session)))
-                                             (:tmux/sessions %))))
+    (let [task (tm-async/submit! runtime #(tm/snapshot! server))
+          stage (tm-async/then! runtime task
+                                #(boolean (some (fn [session]
+                                                  (= "docs-manifold"
+                                                     (:session/name session)))
+                                                (:tmux/sessions %))))
           observed (deferred/->deferred stage)]
       [(instance? CompletionStage stage) @observed])))
 ;; => [true true]

libtmux-clojure-core-async/README.md

@@ -21,7 +21,8 @@ core.async dependency.
 
 This adapter has not shipped. Its Maven coordinate is
 `io.github.libtmux:libtmux-clojure-core-async`; there is no public release to
-install yet. Build and verify it from this checkout:
+install yet. To build and verify it from source, run this from the root of a
+libtmux-java clone:
 
 ```console
 $ ./gradlew :libtmux-clojure-core-async:check
@@ -47,8 +48,9 @@ The [complete core.async program][program] includes imports, a CLI entry point,
 the optional dependency alias, private-server setup and cleanup. It closes its
 events consumer, reads the terminal outcome, and reuses the borrowed connection.
 
-The `javadoc` classifier contains native reference HTML and an offline source
-browser, generated from this module's var metadata.
+The `javadoc` classifier of the `libtmux-clojure-core-async` artifact contains
+native reference HTML and an offline source browser, generated from the
+adapter's var metadata.
 
 [api]: ../docs/guide/clojure-core-async-api.md
 [core-async]: https://clojure.github.io/core.async/clojure.core.async.html

libtmux-clojure/README.md

@@ -22,7 +22,8 @@ leaves ordinary Clojure collection processing local and unconstrained.
 
 The Clojure façade has not shipped. Its Maven coordinate is
 `io.github.libtmux:libtmux-clojure`; there is no public release to install yet.
-Build and verify it from this checkout:
+To build and verify it from source, run this from the root of a
+libtmux-java clone:
 
 ```console
 $ ./gradlew :libtmux-clojure:check :integration-tests:clojureIntegrationTest
@@ -128,13 +129,14 @@ with the tmux version, endpoint choice, and the smallest reproducer.
   run. It does not yet claim a façade-specific benchmark.
 - [Changelog](CHANGELOG.md) — module-visible changes once this façade ships.
 
-Every Clojure snippet in this README and the guide runs against an isolated
-tmux server in `:integration-tests:clojureIntegrationTest`; no snippet is
-illustrative pseudocode.
+Every Clojure snippet on this page and in the [guide][guide] runs against an
+isolated tmux server in `:integration-tests:clojureIntegrationTest`; no snippet
+is illustrative pseudocode.
 
-The module's `javadoc` classifier contains native Clojure reference HTML and
-an offline source browser. Build it with `:libtmux-clojure:clojureApiJar`;
-the generated site starts at `build/docs/clojure/index.html` in this module.
+The `javadoc` classifier of the `libtmux-clojure` artifact contains native
+Clojure reference HTML and an offline source browser. To build it from source,
+run `:libtmux-clojure:clojureApiJar`; the generated site starts at
+`libtmux-clojure/build/docs/clojure/index.html`.
 
 [benchmarks]: ../benchmarks/README.md
 [api]: ../docs/guide/clojure-api.md
@@ -145,7 +147,7 @@ the generated site starts at `build/docs/clojure/index.html` in this module.
 [core-async]: ../libtmux-clojure-core-async/README.md
 [data-api]: ../docs/guide/clojure-api.md#libtmuxdata
 [guide]: ../docs/guide/clojure.md
-[guide-streaming]: ../docs/guide/clojure.md
+[guide-streaming]: ../docs/guide/clojure.md#lifecycle-streaming-and-optional-adapters
 [java-core]: ../libtmux/README.md
 [mcp-guide]: ../docs/guide/mcp.md
 [programs]: ../examples/api/README.md#clojure-programs