From a6b20ca7c7075f74147ed612f2a74110a200c024 Mon Sep 17 00:00:00 2001 From: Zain Dana Harper <17142659+HarperZ9@users.noreply.github.com> Date: Thu, 8 Oct 2026 20:58:27 -0700 Subject: [PATCH] docs: Watch and Walkthrough sections in the README and explainer The README and docs/explainer/index.html gain two sections. Watch says plainly that no concept film fits this tool yet, and notes that a narrated video walkthrough comes with the next release. Walkthrough takes a reader through install, a first run and the main feature, step by step, with commands and output copied from real runs recorded on the explainer page. Co-Authored-By: Claude Opus 5.5 --- README.md | 49 +++++++++++++++++++++++++++++++++++++++ docs/explainer/index.html | 49 ++++++++++++++++++++++++++++++++------- 2 files changed, 90 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index e8a1a2f..a3a36ee 100644 --- a/README.md +++ b/README.md @@ -142,6 +142,55 @@ The [animated explainer](https://harperz9.github.io/repo-explainers/plexus.html) walks through two small manifests wired into one edge, the unmet input and terminal output plexus names, a plan with its receipt, verify passing and then failing after a manifest changes, and the built-in ten-tool mesh. Every value on it is output from this repository. Its source is [docs/explainer/index.html](docs/explainer/index.html). +## Watch + +No concept film fits this tool closely yet. The walkthrough below covers it in text, with real commands and output. + +Video walkthrough: coming with the next release. + +## Walkthrough + +Install it, run it once, then use the main feature. Each command below is real, and so is its output. + +1. **Install.** Install from PyPI. Python 3.11 or newer; discovery runs no tool. + + ```text + $ python -m pip install plexus-mesh + ``` + +2. **First run: is there a route?.** Ask whether one tool's output can reach another's input through the built-in manifests. + + ```text + $ plexus route --from gather --to crucible --builtin + "connected": true, + "hops": 1, + ``` + +3. **Discover your own tools.** Point plexus at a folder of manifests to see each tool's ports. + + ```text + $ plexus discover --dir m + producer notes + consumer review + capability notes.summary/1 + self_loop false + via src/notes/summary.py:build + evidence declared + ``` + +4. **Plan and verify a pipeline.** Plan a pipeline toward a goal, then verify the plan against the manifests you have now. + + ```text + $ plexus plan --dir m --goal review + order notes -> review + sources notes + cyclic [] + receipt plexus.plan-receipt/1, method plexus-plan/1 + notes 53ab6c24d374afa4... + review 0d50accb0759561e... + plan_sha256 aeb01289ea823d89... + ``` + ## The problem You wire up a set of tools. Each one produces artifacts and accepts inputs, but diff --git a/docs/explainer/index.html b/docs/explainer/index.html index 4e62e31..b8ae061 100644 --- a/docs/explainer/index.html +++ b/docs/explainer/index.html @@ -121,6 +121,14 @@ @media (prefers-reduced-motion:reduce){ *,*::before,*::after{transition-duration:0s!important;animation-duration:0s!important;animation-iteration-count:1!important;scroll-behavior:auto!important} } +.film{margin:1rem 0 0;max-width:56rem} +.film video{width:100%;height:auto;display:block;background:#000;border:1px solid var(--line)} +.film figcaption{font-size:.9rem;color:var(--ink-soft);margin-top:.55rem;max-width:44rem;line-height:1.5} +.soon{font-family:var(--font-mono);font-size:.8rem;color:var(--muted);margin-top:.8rem} +ol.walkthrough{padding-left:1.4rem;max-width:56rem;margin:1rem 0 0} +ol.walkthrough li{margin:0 0 1.4rem} +ol.walkthrough h3{margin:0 0 .3rem;font-size:1.05rem} +ol.walkthrough p{margin:0 0 .3rem;max-width:44rem} /* generic scene kit: a pipeline strip, an input/output panel, a case picker, a table */ .kscene{display:flex;flex-direction:column;gap:.8rem} @@ -174,6 +182,12 @@

What it does for you

Source: README.md at d889be9 (release 0.4.0)

+
+

Watch

+

No concept film fits this tool closely yet. The walkthrough below covers it in text, with real commands and output.

+

Video walkthrough: coming with the next release.

+
+

How it works, one step at a time

Scroll, or use the step buttons. The first steps use two small manifests written for this page, notes and review. The last uses the ten built-in manifests that ship with plexus. Every line is output from plexus at commit d889be9.

@@ -233,15 +247,34 @@

How it works, one step at a time

-
-

Try it

-

Install from PyPI (Python 3.11 or newer). Discovery reads manifests and runs no tool.

-
$ python -m pip install plexus-mesh
-$ plexus route --from gather --to crucible --builtin
+

+  
Walkthrough

+  
Install it, run it once, then use the main feature. Each command below is real, and so is its output.

+  
    
+    
  1. Install
    Install from PyPI. Python 3.11 or newer; discovery runs no tool.
    
+
    $ python -m pip install plexus-mesh
    2. 
+    
  2. First run: is there a route?
    Ask whether one tool's output can reach another's input through the built-in manifests.
    
+
    $ plexus route --from gather --to crucible --builtin
   "connected": true,
-  "hops": 1,
-$ plexus plan --goal crucible --builtin > plan.json
-$ plexus verify --plan plan.json --builtin
    
+  "hops": 1,
+

  • Discover your own tools

    Point plexus at a folder of manifests to see each tool's ports.

    +
    $ plexus discover --dir m
+producer    notes
+consumer    review
+capability  notes.summary/1
+self_loop   false
+via         src/notes/summary.py:build
+evidence    declared
    • +

  • Plan and verify a pipeline

    Plan a pipeline toward a goal, then verify the plan against the manifests you have now.

    +
    $ plexus plan --dir m --goal review
+order    notes -> review
+sources  notes
+cyclic   []
+receipt  plexus.plan-receipt/1, method plexus-plan/1
+  notes   53ab6c24d374afa4...
+  review  0d50accb0759561e...
+  plan_sha256  aeb01289ea823d89...
    • +

    Output from plexus at d889be9 run from source; plexus-mesh 0.4.0 is the current PyPI release.