diff --git a/gen/deco.hoon b/gen/deco.hoon
new file mode 100644
index 0000000000..7575534754
--- /dev/null
+++ b/gen/deco.hoon
@@ -0,0 +1,179 @@
+::
+::  this is a sample file designed to set conventions for
+::  high-quality conventional hoon.
+::
+::  all lines must be under 80 characters.  no blank lines.
+::  any line longer than 60 characters is probably too long.
+::  uppercase or non-ascii letters are strongly discouraged.
+::  
+::  informal comments (lines with {::}) should be used only for
+::  meta-discussion *about* the code.  
+::
+::  whenever possible, use formal decorations. {:>} decorates
+::  the next expression; {:<} decorates the previous one.
+::
+::  there are two places to put decorations: in line with the 
+::  code, and on the right margin.
+::
+::  in comments and decorations, use *phrase* for emphasis
+::  and {braces} to surround code literals.  (documentation will 
+::  eventually be automatically generated from formal comments.)
+::  %literal, ++literal, ~ship need no braces.  for a valid 
+::  hoon expression, `exp.
+::
+::  there are three conventions for naming: *ultralapidary*,
+::  *lapidary*, and *natural*.  this file is mostly natural.
+::
+::  when in doubt, use the *natural* naming convention.  for 
+::  both arms and faces, natural naming means long, legible,
+::  english-language phrases, in hyphen-separated {kebab-case}.
+::
+::  lapidary conventions should be used only for small, simple,
+::  self-contained systems.  lapidary mode means three-letter
+::  faces ("variable names") and four-letter arms ("methods").
+::
+::  ultralapidary conventions use single-letter names starting
+::  with {a}.  use this convention only for one-liners, etc.
+::  
+::  the file below is a medium-sized generator, built around
+::  a typical two-core structure.  the cores are labeled {%arch}
+::  (structures) and {%work} (productions).  this is canonical.
+::
+::  this code is written to display the variety of formatting
+::  options the parser allows.  a specific convention should pick
+::  one of these styles and stick to it.
+::
+::  a forward decoration block {:>} is either a *document block* or
+::  a *definition block*.
+
+::  a document block has two parts, each of which is optional: 
+::  the *title* and the *body*, 
+::
+::  the title is a ++term preceded by {:>  ||  %}.  only cores
+::  and core chapters (preceded by {+|}) can use titles.  titles
+::  are optionally surrounded by blank or semi-blank decorations, 
+::  {:>} or {:>  ||}.
+::
+::  the body is either short or long.  a short body is a *single line* 
+::  preceded by {:>  } - ie, not indented.  a long body starts with
+::  a *single line* indented by two extra spaces, {:>    }, then a
+::  blank line, then a series of paragraphs.
+::
+::  a definition block is a list of name definitions.  the twig below
+::  the block is traversed for bindings on these names.
+::
+::  a name definition can be short or long.  a short definition is
+::  a *single line* of the form {:>  name: value}.
+::
+::  a long definition is a short definition, followed by a blank
+::  decoration {:>}, followed by a series of paragraphs each
+::  indented by an extra two spaces.
+::
+::  a paragraph is a series of lines, not indented for text,
+::  indented by four extra spaces, {:>      }, for code.
+::
+::  a backward decoration {:<} is only one line, always parsed
+::  as a short body.
+::
+:-  %say
+|=  *
+=<  [%noun (say-hello %world)]
+=>  :>  ||
+    :>  ||  %arch
+    :>  ||
+    :>    structures for our imaginary hello, world generator.
+    :>
+    :>  nothing forces us to put structures in a separate core.
+    :>  but compile-time evaluation doesn't work in the current
+    :>  core; we often want to statically evaluate structures.
+    :>
+    :>  there are three kinds of structures: models (normalizing
+    :>  functions), patterns (functions that build models), and
+    :>  constants (static data).
+    :>
+    :>  most code will not need its own patterns.  but put them
+    :>  in a separate chapter (separated by {+|}).
+    |%
+    :>  ||
+    :>  ||  %model
+    :>  ||
+    :>    models (molds) are functions that normalize nouns.
+    :> 
+    :>  arms producing molds are introduced with {+=}.  for molds,
+    :>  we decorate the mold rather than the arm.  the compiler
+    :>  will copy the mold decoration onto the arm.
+    +|
+    +=  spot  {p/@ q/@}                                 :<  a coordinate
+    +=  tops                                            :>  also a coordinate
+      {p/@ q/@}
+    +=  goof                                            :>  a simple tuple
+      $:  foo/@                                         :<  something mysterious
+          bar/@                                         :<  go here for drink
+          moo/(binary-tree juice)                       :<  cows do this
+      ==
+    +=  juice                                           :>  fruity beverage
+      $%  {$plum p/@}                                   :<  fresh prune
+          {$pear p/@ q/@}                               :<  good for cider
+          {$acai p/@}                                   :<  aztec superfood
+      ==
+    :>  ||  %pattern
+    :>    patterns are functions that build models.
+    :>
+    :>  other languages might call these "type constructors"
+    :>  or "higher-kinded types".
+    +|
+    ++  binary-tree                                     :<  tree pattern
+      |*  a/$-(* *)
+      $@($~ {n/a l/(binary-tree a) r/(binary-tree a)})
+    :>  ||
+    :>  ||  %constant
+    :>  ||
+    :>    if you have constants, put them in their own chapter.
+    +|
+    ++  answer                                          :<  answer to everything
+      42
+    --
+:>  ||  %work
+:>    engines for our imaginary hello, world app. 
+:>
+:>  note that ++say-goodbye is the correct notation, even though
+:>  it's a {+-} arm.
+|%
+:>                                                      :>  ++say-hello
+++  say-hello                                           :<  say hi to someone
+  :>  friendly welcome message
+  :>
+  |=  :>  txt: friend to say hi to
+      :>
+      txt/term
+  ^-  tape
+  "hello, {(rip 3 txt)}"
+:>    ++say-goodbye: say a really proper goodbye
+:>
+:>  some paragraphs about the goodbye algorithm, possibly
+:>  including code indented by four extra spaces:
+:>  
+:>      ?:  =(%hello %world)
+:>        %hello
+:>      %world
+:>                                                      ::  ++say-goodbye
++-  say-goodbye                                         ::
+  :>  describe product of function
+  :>
+  |=  :>  txt: departing friend
+      :>  num: number of friends
+      $:  txt/term
+          num/@
+      ==
+  ^-  tape
+  :>  foo: four
+  :>  bar: forty-two
+  =/  foo  (add 2 2)
+  =/  bar  (add (mul num foo) 2)
+  =/  moo  (mul num bar)                                :<  for all the cows
+  "goodbye and {(scot %ud moo)}, {(rip 3 txt)}"
+:>                                                      :>  ++say-minimum
+++  say-minimum                                         :>  minimal decoration
+  |=  txt/term
+  "nothing to say to {(rip 3 txt)}"
+--
diff --git a/gen/walk.hoon b/gen/walk.hoon
index 70ade92ee6..90f90b21e4 100644
--- a/gen/walk.hoon
+++ b/gen/walk.hoon
@@ -1,354 +1,160 @@
-::
+!:
 ::::
   ::
 :-  %say
 |=  $:  {now/@da * bec/beak}
         *
     ==
-=<  ~&  %walk-testing
-    :-  %noun
-    =+  sys=`path`/(scot %p p.bec)/[q.bec]/(scot %da now)/sys
-    =+  compiler-source=.^(@t %cx (welp sys /hoon/hoon))
-    ~&  %test-parsing
-    =+  compiler-twig=(ream compiler-source)
-    ~&  %test-walking
-    ~(test ap compiler-twig)
-=<  |%
-    ++  come                                            ::  parsed docline
-      $%  {$blank $~}
-          {$var p/term q/
-    ++  post                                            ::  print state
-    
-    --
+=<  :-  %noun
+    %hello
 |%
 ::
-++  ap                                                  ::  twig engine
+++  ap
   |_  gen/twig
-  ::
-  ++  test                                            ::  test ++walk
-    ^-  ?
-    =-  ~|  [gen+gen neg+neg ~]
-        ?>  =(gen neg)
-        &
-    ^=  neg
-    ^-  twig
-    =<  -
-    %+  (walk $~)
-      ~
-    |=  {gen/twig vit/$~ aid/$-({? twig $~} {twig $~})}
-    ~
-  ++  dock                                              ::  apply document
-    |=  doc/cord
-    |^  ^-  (unit twig)
-        =/  rah  ^-  (each (pair term cord) cord)
-                 (rash doc very)
-        ?-(-.rah $& (rave p.rah), $| (graf p.rah))
+  ++  gi
+    =|  whit
+    =*  wit  -
+    |%
+    ++  gray
+      ^-  ?
+      |
+      ::  on reflection, perhaps just obsessive linting
+      ::
+      ::  ?|  ?=(^ lab)
+      ::      ?=(^ boy)
+      ::      |-  ^-  ?
+      ::      ?~  def  | 
+      ::      |($(def l.def) $(def r.def) !(~(has in use) p.n.def))
+      ::  ==
     ::
-    ++  graf                                            ::  apply general doc
-      =*  life  (unit cord)
-      |=  doc/cord
-      ^-  (unit twig)
-      =-  ?^  q.dep  `[%help [doc ~] gen]
-          `p.dep
-      ^=  dep
-      =/  foo/@tas  %foobar
-      ^-  (pair twig life)
-      %+  (walk life)
-        `doc
-      |=  {gen/twig vit/life aid/$-({? twig life} {twig life})}
-      ^-  (unit (pair twig life))
-      ?~  vit  `[gen ~]
-      |^  ?+  -.gen  
-                   outside-image
-            ^      outside-image
-            $dbug  ~
-            $help  `[[%help [doc p.gen] q.gen] ~]
-            $claw  outside-model
-            $shoe  outside-model
-            $bank  outside-model
-            $lamb  outside-model
-            $bush  outside-model
-            $pick  outside-model
-            $coat  outside-model
-            $halo  `[[%halo [doc p.gen] q.gen] ~]
+    ++  grad
+      |=  $:  gen/twig 
+              wit/whit 
+              aid/$-({? twig whit} {twig whit})
           ==
-      ++  outside-model
-        `[[%halo [doc ~] gen] ~]
-      ++  outside-image
-        `[[%help [doc ~] gen] ~]
-      --
-    ::
-    ++  rave                                            ::  apply variable doc
-      =*  life  (unit (pair term cord))
-      |=  {cog/term doc/cord}
-      ^-  (unit twig)
-      =-  ?^  q.dep  ~
-          `p.dep
-      ^=  dep
-      ^-  (pair twig life)
-      %+  (walk life)
-        `[cog doc]
-      |=  {gen/twig vit/life aid/$-({? twig life} {twig life})}
-      ^-  (unit (pair twig life))
-      ?~  vit  `[gen ~]
-      ~
-    ::
-    ++  very                                            ::  variable reparse
-      %+  pick
-        ;~(plug sym (cook crip ;~(pfix ;~(plug col ace) (star prn))))
-      (cook crip (star prn))
-    --
-  ::
-  ++  walk                                              ::  forward traverse
-    |*  life/mold
-    |=  $:  vit/life
-            $=  mac
-            $-  $:  twig
-                    life
-                    $-({? twig life} {twig life})
-                ==
-            (unit (pair twig life))
+      ^-  (unit (pair twig whit))
+      =:  ^gen  gen
+          ^wit  wit
         ==
-    ^-  {twig life}
-    =/  use  &
-    =<  apex 
-    |%  
-    ++  apex
-      |-  ^-  {twig life}
-      =*  aid  |=  {use/? gen/twig vit/life} 
-               ^$(use use, gen gen, vit vit)
-      =/  gun  ?:(use (mac gen vit aid) ~)
-      ?^  gun  u.gun
-      ?:  ?=(^ -.gen)
-        %.(gen dubs)
-      ?-  -.gen
-        $$     (lead -.gen %.(+.gen noop))
-        $base  (lead -.gen %.(+.gen noop))
-        $bunt  (lead -.gen %.(+.gen expr))
-        $bust  (lead -.gen %.(+.gen noop))
-        $dbug  (lead -.gen %.(+.gen nexp))
-        $hand  (lead -.gen %.(+.gen noop))
-        $knit  (lead -.gen %.(+.gen (moto bark)))
-        $leaf  (lead -.gen %.(+.gen noop))
-        $limb  (lead -.gen %.(+.gen noop))
-        $lost  (lead -.gen %.(+.gen expr))
-        $rock  (lead -.gen %.(+.gen noop))
-        $sand  (lead -.gen %.(+.gen noop))
-        $tell  (lead -.gen %.(+.gen moar))
-        $tune  (lead -.gen %.(+.gen tung))
-        $wing  (lead -.gen %.(+.gen noop))
-        $yell  (lead -.gen %.(+.gen moar))
-        $claw  (lead -.gen %.(+.gen dubs))
-        $shoe  (lead -.gen %.(+.gen expr))
-        $bank  (lead -.gen %.(+.gen moar))
-        $book  (lead -.gen %.(+.gen moar))
-        $lamb  (lead -.gen %.(+.gen dubs))
-        $bush  (lead -.gen %.(+.gen dubs))
-        $pick  (lead -.gen %.(+.gen moar))
-        $coat  (lead -.gen %.(+.gen nexp))
-        $grow  (lead -.gen %.(+.gen expr))
-        $door  (lead -.gen %.(+.gen (trio noop expr arms)))
-        $door  (lead -.gen %.(+.gen (trio noop expr arms)))
-        $gasp  (lead -.gen %.(+.gen (twin noop dubs)))
-        $corp  (lead -.gen %.(+.gen (twin noop arms)))
-        $trap  (lead -.gen %.(+.gen (twin noop expr)))
-        $cork  (lead -.gen %.(+.gen (trio noop expr arms)))
-        $loop  (lead -.gen %.(+.gen (twin noop expr)))
-        $port  (lead -.gen %.(+.gen (twin noop dubs)))
-        $gill  (lead -.gen %.(+.gen (twin noop dubs)))
-        $gate  (lead -.gen %.(+.gen (twin noop dubs)))
-        $tray  (lead -.gen %.(+.gen (twin noop expr)))
-        $scon  (lead -.gen %.(+.gen dubs))
-        $conq  (lead -.gen %.(+.gen (quad expr expr expr expr)))
-        $cons  (lead -.gen %.(+.gen dubs))
-        $cont  (lead -.gen %.(+.gen trey))
-        $conl  (lead -.gen %.(+.gen moar))
-        $conp  (lead -.gen %.(+.gen moar))
-        $keep  (lead -.gen %.(+.gen (twin noop moan)))
-        $lace  (lead -.gen %.(+.gen dubs))
-        $call  (lead -.gen %.(+.gen (twin expr moar)))
-        $bake  (lead -.gen %.(+.gen (trio noop expr moan)))
-        $calq  (lead -.gen %.(+.gen (quad expr expr expr expr)))
-        $calt  (lead -.gen %.(+.gen trey))
-        $open  (lead -.gen %.(+.gen (trio noop expr moar)))
-        $make  (lead -.gen %.(+.gen (twin noop moan)))
-        $wish  (lead -.gen %.(+.gen dubs))
-        $bump  (lead -.gen %.(+.gen expr))
-        $nock  (lead -.gen %.(+.gen dubs))
-        $same  (lead -.gen %.(+.gen dubs))
-        $deep  (lead -.gen %.(+.gen expr))
-        $iron  (lead -.gen %.(+.gen expr))
-        $ward  (lead -.gen %.(+.gen dubs))
-        $like  (lead -.gen %.(+.gen dubs))
-        $cast  (lead -.gen %.(+.gen dubs))
-        $zinc  (lead -.gen %.(+.gen expr))
-        $burn  (lead -.gen %.(+.gen expr))
-        $name  (lead -.gen %.(+.gen nexp))
-        $lead  (lead -.gen %.(+.gen expr))
-        $halo  (lead -.gen %.(+.gen nexp))
-        $help  (lead -.gen %.(+.gen nexp))
-        $show  (lead -.gen %.(+.gen dubs))
-        $lurk  (lead -.gen %.(+.gen dubs))
-        $crap  (lead -.gen %.(+.gen (raid expr)))
-        $fast  (lead -.gen %.(+.gen (quad noop expr moan expr)))
-        $funk  (lead -.gen %.(+.gen nexp))
-        $thin  (lead -.gen %.(+.gen (twin toad expr)))
-        $hint  (lead -.gen %.(+.gen (twin toad expr)))
-        $poll  (lead -.gen %.(+.gen nexp))
-        $memo  (lead -.gen %.(+.gen nexp))
-        $dump  (lead -.gen %.(+.gen trip))
-        $ddup  (lead -.gen %.(+.gen dubs))
-        $warn  (lead -.gen %.(+.gen (quad noop expr expr expr)))
-        $peep  (lead -.gen %.(+.gen dubs))
-        $wad   (lead -.gen %.(+.gen (twin expr moar)))
-        $nub   (lead -.gen %.(+.gen expr))
-        $dip   (lead -.gen %.(+.gen (twin expr moar)))
-        $fry   (lead -.gen %.(+.gen dubs))
-        $new   (lead -.gen %.(+.gen dubs))
-        $fix   (lead -.gen %.(+.gen (twin moan expr)))
-        $var   (lead -.gen %.(+.gen (trio tora expr expr)))
-        $rev   (lead -.gen %.(+.gen (trio tora expr expr)))
-        $set   (lead -.gen %.(+.gen trip))
-        $huh   (lead -.gen %.(+.gen (quad noop expr expr expr)))
-        $rap   (lead -.gen %.(+.gen dubs))
-        $nip   (lead -.gen %.(+.gen dubs))
-        $per   (lead -.gen %.(+.gen dubs))
-        $sip   (lead -.gen %.(+.gen (quad tora noop expr expr)))
-        $pin   (lead -.gen %.(+.gen dubs))
-        $tow   (lead -.gen %.(+.gen moar))
-        $aka   (lead -.gen %.(+.gen trip))
-        $use   (lead -.gen %.(+.gen dubs))
-        $or    (lead -.gen %.(+.gen moar))
-        $case  (lead -.gen %.(+.gen (twin noop (moto dubs))))
-        $if    (lead -.gen %.(+.gen trey))
-        $lest  (lead -.gen %.(+.gen trey))
-        $ifcl  (lead -.gen %.(+.gen trip))
-        $deny  (lead -.gen %.(+.gen dubs))
-        $sure  (lead -.gen %.(+.gen dubs))
-        $deft  (lead -.gen %.(+.gen (trio noop expr (moto dubs))))
-        $and   (lead -.gen %.(+.gen moar))
-        $ifat  (lead -.gen %.(+.gen trip))
-        $ifno  (lead -.gen %.(+.gen trip))
-        $fits  (lead -.gen %.(+.gen (twin expr noop)))
-        $not   (lead -.gen %.(+.gen expr))
-        $twig  (lead -.gen %.(+.gen dubs))
-        $wrap  (lead -.gen %.(+.gen expr))
-        $spit  (lead -.gen %.(+.gen dubs))
-        $code  (lead -.gen %.(+.gen expr))
-        $need  (lead -.gen %.(+.gen nexp))
-        $fail  (lead -.gen %.(+.gen noop))
-      ==
-    ++  arms
-      (raid (twin noop (raid (twin noop heel))))
-    ::
-    ++  bark 
-      |=  wof/woof
-      ?-(wof @ [wof vit], ^ (lead ~ (expr p.wof)))
-    ::
-    ++  dubs
-      (twin expr expr)
-    ::
-    ++  expr
-      |=  p/twig
-      ^$(gen p)
-    ::
-    ++  heel
-      |=  bud/foot
-      ?-  -.bud
-        $ash  =^(nex vit ^$(gen p.bud) [[%ash nex] vit])
-        $elm  =^(nex vit ^$(gen p.bud) [[%elm nex] vit])
-      ==
-    ::
-    ++  lead
-      |*  {sem/@tas out/{* life}}
-      [[sem -.out] +.out]
-    ::
-    ++  moan
-      (moto nexp)
-    ::
-    ++  moar
-      (moto expr)
-    ::
-    ++  moto
-      |*  etc/$-(* {* life})
-      |*  bud/*
-      ^+  [bud vit]
-      ?:  =(~ bud)  [bud vit]
-      =^  heb  vit  (etc -.bud)
-      =^  mor  vit  $(bud +.bud)
-      [[heb mor] vit]
-    ::
-    ++  nexp
-      (twin noop expr)
-    ::
-    ++  noop
-      |*  bud/*
-      [bud vit]
-    ::
-    ++  quad
-      |*  $:  one/$-(* {* life})
-              two/$-(* {* life})
-              tri/$-(* {* life})
-              qua/$-(* {* life})
-          ==
-      |*  bud/*
-      =^  yal  vit  (one -.bud)
-      =^  ves  vit  (two +<.bud)
-      =^  jot  vit  (tri +>-.bud)
-      =^  wip  vit  (qua +>+.bud)
-      [[yal ves jot wip] vit]
-    ::
-    ++  raid
-      |*  etc/$-(* {* life})
-      |*  bud/*
-      ^+  [bud vit]
-      ?:  =(~ bud)  [bud vit]
-      =^  lef  vit  $(bud +<.bud)
-      =^  ryt  vit  $(bud +>.bud)
-      =^  top  vit  (etc ->.bud)
-      [[[-<.bud top] lef ryt] vit]
-    ::
-    ++  trey
-      (trio expr expr expr)
-    ::
-    ++  trio
-      |*  $:  one/$-(* {* life})
-              two/$-(* {* life})
-              tri/$-(* {* life})
-          ==
-      |*  bud/*
-      =^  yal  vit  (one -.bud)
-      =^  ves  vit  (two +<.bud)
-      =^  jot  vit  (tri +>.bud)
-      [[yal ves jot] vit]
-    ::
-    ++  trip
-      (trio noop expr expr)
-    ::
-    ++  toad
-      |=  bud/$@(term {p/term q/twig})
-      ?@  bud  [bud vit]
-      (lead p.bud (expr q.bud))
-    ::
-    ++  tora
-      (twin noop twee)
-    ::
-    ++  tung
-      |=  bud/{p/wain q/$@(term tune)}
-      ?@  q.bud  [bud vit]
-      (lead p.bud %.(q.bud (twin (raid (twin noop twee)) (moto expr))))
-    ::
-    ++  twee
-      |=  bud/(unit twig)
-      ?~  bud  [~ vit]
-      (lead ~ (expr u.bud))
-    ::
-    ++  twin
-      |*  {one/$-(* {* life}) two/$-(* {* life})}
-      |*  bud/*
-      =^  yal  vit  (one -.bud)
-      =^  ves  vit  (two +.bud)
-      [[yal ves] vit]
+      ?:  =([~ ~ ~ ~] wit)  `[gen wit]
+      =<  apex
+      |%
+      ++  apex
+        ^-  (unit (pair twig whit))
+        =^  one  wit  prim
+        =^  two  wit  senc(gen one)
+        ?:  =(gen two) 
+          ~
+        `(aid & two wit)
+      ::
+      ::  resolve body and label issues
+      ::
+      ++  prim
+        ^-  (pair twig whit)
+        ?:  ?=(^ -.gen)  flam
+        ?+  -.gen  flam
+          $halo   flam
+          $base   runk
+          $leaf   runk
+          $claw   runk
+          $shoe   runk
+          $bank   runk
+          $book   runk
+          $lamb   runk
+          $bush   runk
+          $pick   runk
+          $coat   flam 
+          $grow   runk
+          $door   ((doof -.gen +>.gen) p.gen)
+          $gasp   ((doof -.gen +>.gen) p.gen)
+          $corp   ((doof -.gen +>.gen) p.gen)
+          $trap   ((doof -.gen +>.gen) p.gen)
+          $cork   ((doof -.gen +>.gen) p.gen)
+          $loop   ((doof -.gen +>.gen) p.gen)
+          $port   ((doof -.gen +>.gen) p.gen)
+          $gill   ((doof -.gen +>.gen) p.gen)
+          $gate   ((doof -.gen +>.gen) p.gen)
+          $tray   ((doof -.gen +>.gen) p.gen)
+        ==
+      ::
+      ::  resolve variable issues
+      ::
+      ++  senc
+        ^-  (pair twig whit)
+        ?:  ?=(^ -.gen)  flam
+        ?+  -.gen  flam
+          $name  ((helk -.gen +>.gen) p.gen)
+          $coat  ((helk -.gen +>.gen) p.gen)
+          $var   ((hulp -.gen +>.gen) p.gen)
+          $rev   ((hulp -.gen +>.gen) p.gen)
+          $sip   ((hulp -.gen +>.gen) p.gen)
+          $aka   ((humm -.gen +>.gen) p.gen)
+        ==
+      ::
+      ++  flam  [gen wit]
+      ++  grif
+        |=  {cog/term wat/what}
+        ^-  {what whit}
+        ?:  =(~ def)
+          ?~  boy  [wat wit]
+          [boy wit(boy ~)]
+        =+  yeb=(~(get by def) cog)
+        ?~  yeb  [wat wit]
+        [`u.yeb wit(use (~(put in use) cog))]
+      ::
+      ++  doof
+        |*  {pif/@tas suf/*}
+        |=  pac/chap
+        ^-  (pair twig whit)
+        :_  wit(lab ~, boy ~)
+        =-  [pif - suf]
+        ^-  chap
+        :-  ?~(lab p.pac [u.lab ~])
+            ?~(boy q.pac boy)
+      ::
+      ++  helk
+        |*  {pif/@tas suf/*}
+        |=  got/toga
+        ^-  (pair twig whit)
+        =^  gef  wit  (tong got)
+        [[pif gef suf] wit]
+      ::
+      ++  hulp
+        |*  {pif/@tas suf/*}
+        |=  hot/toro
+        ^-  (pair twig whit)
+        =^  tog  wit  (tong p.hot)
+        [[pif [tog q.hot] suf] wit] 
+      ::
+      ++  humm
+        |*  {pif/@tas suf/*}
+        |=  {cog/term wat/what)
+        ^-  (pair twig whit)
+        =^  taw  wit  (grif cog wat)
+        [[pif [cog taw] suf] wit] 
+      ::
+      ++  runk
+        ^-  (pair twig whit)
+        ?~  boy  flam
+        [[%halo boy gen] wit(boy ~)]
+      ::
+      ++  tong
+        |=  got/toga
+        ^-  {toga whit}
+        ?@  got
+          =^  wat  wit  (grif got ~)
+          ?~  wat  [got wit]
+          [[%1 [wat got] [%0 ~]] wit]
+        ?-  -.got
+          $0  [got wit]
+          $1  =^  wat  wit  (grif q.p.got p.p.got)
+              =^  sub  wit  $(got q.got)
+              [[%1 [wat q.p.got] sub] wit]
+          $2  =^  one  wit  $(got p.got)
+              =^  two  wit  $(got q.got)
+              [[%2 one two] wit]
+        ==
+      --
     --
   --
 --
diff --git a/sys/hoon.hoon b/sys/hoon.hoon
index 4d51a96d14..e9a2d5b783 100644
--- a/sys/hoon.hoon
+++ b/sys/hoon.hoon
@@ -1,4 +1,4 @@
-!:                                                      ::
+::                                                      ::
 ::::    /sys/hoon                                       ::
   ::                                                    ::
 ~>  %slog.[0 leaf+"hoon-assembly"]
@@ -9,7 +9,6 @@
   ::                                                    ::
 ~%  %k.144  ~  ~                                        ::
 |%
-++  a144  %144
 ++  hoon  +
 --  =>
 ::                                                      ::
@@ -21,7 +20,6 @@
   ::
 ~%  %one  +  ~
 |%
-++  a144  %144
 ::                                                      ::
 ::::    1a: unsigned arithmetic                         ::
   ::
@@ -207,7 +205,6 @@
   ::
 ~%  %two  +  ~
 |%
-++  a144  %144
 ::                                                      ::
 ::::  2a: unit logic                                    ::
   ::                                                    ::
@@ -1724,7 +1721,6 @@
   ::                                                    ::
 ~%  %tri  +  ~
 |%
-++  a144  %144
 ::
 ::::  3a: signed and modular ints                       ::
   ::                                                    ::
@@ -3439,7 +3435,6 @@
     %show  show
   ==
 |%
-++  a144  %144
 ::
 ::::  4a: exotic bases
   ::
@@ -4538,7 +4533,8 @@
          ;~(plug hit hit)
 ++  nix  (boss 256 (star ;~(pose aln cab)))             ::
 ++  nud  (shim '0' '9')                                 ::  numeric
-++  prn  ;~(less (just `@`127) (shim 32 256))
+++  prn  ;~(less (just `@`127) (shim 32 256))           ::  non-control
+++  prz  ;~(less (just `@`127) (shim 33 256))           ::  non-trivial
 ++  qat  ;~  pose                                       ::  chars in blockcord
              prn
              ;~(less ;~(plug (just `@`10) soz) (just `@`10))
@@ -5359,6 +5355,7 @@
           $%  {$& p/span}                               ::  leg
               {$| p/axis q/(set {p/span q/foot})}       ::  arm
           ==                                            ::
+++  pica  (pair ? cord)                                 ::  & prose, | code
 ++  palo  (pair vein opal)                              ::  wing trace, match
 ++  pock  (pair axis nock)                              ::  changes
 ++  port  (each palo (pair span nock))                  ::  successful match
@@ -5404,6 +5401,7 @@
     {$bunt p/root}                                      ::  mold default value
     {$bust p/base}                                      ::  bunt base
     {$dbug p/spot q/twig}                               ::  debug info in trace
+    {$eror p/tape}                                      ::  assembly error
     {$hand p/span q/nock}                               ::  premade result
     {$help p/what q/twig}                               ::  annotate image
     {$halo p/what q/root}                               ::  annotate model
@@ -5500,7 +5498,7 @@
     {$sip p/toro q/wing r/twig s/twig}                  ::  =^  state machine
     {$pin p/twig q/twig}                                ::  =+  q w/[p subject]
     {$tow p/(list twig)}                                ::  =~  twig stack
-    {$aka p/term q/twig r/twig}                         ::  =*  r w/alias p/q
+    {$aka p/(pair what term) q/twig r/twig}             ::  =*  r w/alias p/q
     {$use p/twig q/twig}                                ::  =,  overload p in q
   ::                                            ::::::  conditionals
     {$or p/(list twig)}                                 ::  ?|  loobean or
@@ -5568,7 +5566,14 @@
 ++  vial  ?($read $rite $both $free)                    ::  co/contra/in/bi
 ++  vair  ?($gold $iron $lead $zinc)                    ::  in/contra/bi/co
 ++  vein  (list (unit axis))                            ::  search trace
-++  what  (unit (pair cord (list wain)))                ::  help slogan/sections
+++  sect  (list pica)                                   ::  paragraph
+++  whit                                                ::  
+          $:  lab/(unit term)                           ::  label
+              boy/(unit (pair cord (list sect)))        ::  body
+              def/(map term (pair cord (list sect)))    ::  definitions
+              use/(set term)                            ::  defs used
+          ==                                            ::
+++  what  (unit (pair cord (list sect)))                ::  help slogan/sections
 ++  wing  (list limb)                                   ::  search path
 ++  worm                                                ::  compiler cache
   $:  nes/(set ^)                                       ::  ++nest
@@ -5595,7 +5600,6 @@
     %ut    ut
   ==
 |%
-++  a144  %144
 ::
 ::::  5a: compiler utilities
   ::
@@ -5867,7 +5871,7 @@
     |=  gen/twig
     ^-  twig
     ?-  -.tik
-      $&  ?~(p.tik gen [%aka u.p.tik [%wing q.tik] gen])
+      $&  ?~(p.tik gen [%aka [~ u.p.tik] [%wing q.tik] gen])
       $|  [%pin ?~(p.tik q.tik [%name u.p.tik q.tik]) gen]
     ==
   ::
@@ -5969,6 +5973,7 @@
       (hail [%rock p.sec q.sec])
     ::
         {$plow *}
+      ?>  =(*what wat)
       $(sec q.sec, wat p.sec)
     ::
         {$reed *}
@@ -5979,7 +5984,9 @@
         {$weed *}
       (hail (home p.sec))
     ==
-  ++  clam  ^-(twig [%gate [~ ~] [%base %noun] (whip(gom 7) 6)])
+  ++  clam  
+    ^-   twig  
+    [%gate [~ ~] [%base %noun] (whip(gom 7) 6)]
   ::
   ++  whip
     |=  axe/axis
@@ -6117,46 +6124,6 @@
       %rake  rake
     ==
   |_  gen/twig
-  ++  dock                                              ::  apply document
-    |=  doc/cord
-    |^  ^-  (unit twig)
-        =/  rah  ^-  (each (pair term cord) cord)
-                 (rash doc very)
-        ?-(-.rah $& (rave p.rah), $| (graf p.rah))
-    ::
-    ++  graf                                            ::  apply general doc
-      |=  doc/cord
-      ^-  (unit twig)
-      =-  ?^  q.dep  `[%help ~ gen]
-          `p.dep
-      ^=  dep
-      ^-  (pair twig (unit cord))
-      %+  (walk (unit cord))
-        `doc
-      |=  {gen/twig vit/(unit cord)}
-      ^-  (unit (pair twig (unit cord)))
-      ::  XX stub
-      ~
-    ::
-    ++  rave                                            ::  apply variable doc
-      |=  {cog/term doc/cord}
-      ^-  (unit twig)
-      =-  ?^  q.dep  ~
-          `p.dep
-      ^=  dep
-      ^-  (pair twig (unit (pair term cord)))
-      %+  (walk (unit (pair term cord)))
-        `[cog doc]
-      |=  {gen/twig vit/(unit (pair term cord))}
-      ^-  (unit (pair twig (unit (pair term cord))))
-      ::  XX stub
-      ~
-    ::
-    ++  very                                            ::  variable cord rule
-      %+  pick
-        ;~(plug sym (cook crip ;~(pfix ;~(plug col ace) (star prn))))
-      (cook crip (star prn))
-    --
   ++  etch
     ~_  leaf+"etch"
     |-  ^-  term
@@ -6173,6 +6140,159 @@
       *               ~
     ==
   ::
+  ++  gi
+    =|  whit
+    =*  wit  -
+    |%
+    ++  gray
+      ^-  ?
+      |
+      ::  on reflection, perhaps just obsessive linting
+      ::
+      ::  ?|  ?=(^ lab)
+      ::      ?=(^ boy)
+      ::      |-  ^-  ?
+      ::      ?~  def  | 
+      ::      |($(def l.def) $(def r.def) !(~(has in use) p.n.def))
+      ::  ==
+    ::
+    ++  grad
+      |=  $:  gen/twig 
+              wit/whit 
+              aid/$-({? twig whit} {twig whit})
+          ==
+      ^-  (unit (pair twig whit))
+      =:  ^gen  gen
+          ^wit  wit
+        ==
+      ?:  =([~ ~ ~ ~] wit)  `[gen wit]
+      =<  apex
+      |%
+      ++  apex
+        ^-  (unit (pair twig whit))
+        =^  one  wit  prim
+        =^  two  wit  senc(gen one)
+        ?:  =(gen two) 
+          ~
+        `(aid & two wit)
+      ::
+      ::  resolve body and label issues
+      ::
+      ++  prim
+        ^-  (pair twig whit)
+        ?:  ?=(^ -.gen)  flam
+        ?+  -.gen  flam
+          $halo   flam
+          $base   runk
+          $leaf   runk
+          $claw   runk
+          $shoe   runk
+          $bank   runk
+          $book   runk
+          $lamb   runk
+          $bush   runk
+          $pick   runk
+          $coat   flam 
+          $grow   runk
+          $door   ((doof -.gen +>.gen) p.gen)
+          $gasp   ((doof -.gen +>.gen) p.gen)
+          $corp   ((doof -.gen +>.gen) p.gen)
+          $trap   ((doof -.gen +>.gen) p.gen)
+          $cork   ((doof -.gen +>.gen) p.gen)
+          $loop   ((doof -.gen +>.gen) p.gen)
+          $port   ((doof -.gen +>.gen) p.gen)
+          $gill   ((doof -.gen +>.gen) p.gen)
+          $gate   ((doof -.gen +>.gen) p.gen)
+          $tray   ((doof -.gen +>.gen) p.gen)
+        ==
+      ::
+      ::  resolve variable issues
+      ::
+      ++  senc
+        ^-  (pair twig whit)
+        ?:  ?=(^ -.gen)  flam
+        ?+  -.gen  flam
+          $name  ((helk -.gen +>.gen) p.gen)
+          $coat  ((helk -.gen +>.gen) p.gen)
+          $var   ((hulp -.gen +>.gen) p.gen)
+          $rev   ((hulp -.gen +>.gen) p.gen)
+          $sip   ((hulp -.gen +>.gen) p.gen)
+          $aka   ((humm -.gen +>.gen) p.gen)
+        ==
+      ::
+      ++  flam  [gen wit]
+      ++  grif
+        |=  {cog/term wat/what}
+        ^-  {what whit}
+        ?:  =(~ def)
+          ?~  boy  [wat wit]
+          [boy wit(boy ~)]
+        =+  yeb=(~(get by def) cog)
+        ?~  yeb  [wat wit]
+        [`u.yeb wit(use (~(put in use) cog))]
+      ::
+      ++  doof
+        |*  {pif/@tas suf/*}
+        |=  pac/chap
+        ^-  (pair twig whit)
+        :_  wit(lab ~, boy ~)
+        =-  [pif - suf]
+        ^-  chap
+        :-  ?~(lab p.pac [u.lab ~])
+            ?~(boy q.pac boy)
+      ::
+      ++  helk
+        |*  {pif/@tas suf/*}
+        |=  got/toga
+        ^-  (pair twig whit)
+        =^  gef  wit  (tong got)
+        [[pif gef suf] wit]
+      ::
+      ++  hulp
+        |*  {pif/@tas suf/*}
+        |=  hot/toro
+        ^-  (pair twig whit)
+        =^  tog  wit  (tong p.hot)
+        [[pif [tog q.hot] suf] wit] 
+      ::
+      ++  humm
+        |*  {pif/@tas suf/*}
+        |=  {wat/what cog/term}
+        ^-  (pair twig whit)
+        =^  taw  wit  (grif cog wat)
+        [[pif [taw cog] suf] wit] 
+      ::
+      ++  runk
+        ^-  (pair twig whit)
+        ?~  boy  flam
+        [[%halo boy gen] wit(boy ~)]
+      ::
+      ++  tong
+        |=  got/toga
+        ^-  {toga whit}
+        ?@  got
+          =^  wat  wit  (grif got ~)
+          ?~  wat  [got wit]
+          [[%1 [wat got] [%0 ~]] wit]
+        ?-  -.got
+          $0  [got wit]
+          $1  =^  wat  wit  (grif q.p.got p.p.got)
+              =^  sub  wit  $(got q.got)
+              [[%1 [wat q.p.got] sub] wit]
+          $2  =^  one  wit  $(got p.got)
+              =^  two  wit  $(got q.got)
+              [[%2 one two] wit]
+        ==
+      --
+    ::
+    ++  graf
+      ::  ^-  (unit twig)
+      ::  =^  nex  wit  ((walk whit) wit grad)
+      ::  ?:(gray ~ `nex)
+      =^  nex  wit  ((walk whit) wit grad)
+      nex
+    --
+  ::
   ::  not used at present; see comment at $csng in ++open
 ::::
 ::++  hail
@@ -6211,6 +6331,8 @@
   ++  bile
     =+  sec=boil
     |-  ^-  (each line tile)
+    ?:  ?=({$plow *} sec)
+      $(sec q.sec)
     ?:  ?=({$deet *} sec)
       $(sec q.sec)
     ?:  ?=({{$deet *} *} sec)
@@ -6267,6 +6389,7 @@
         {$base *}  ~(clam al boil)
         {$bust *}  ~(bunt al %axil p.gen)
         {$dbug *}   q.gen
+        {$eror *}  ~|(p.gen !!)
     ::
         {$knit *}                                       ::
       :+  %per  [%name %v %$ 1]                         ::  =>  v=.
@@ -6586,10 +6709,254 @@
   ++  walk                                              ::  forward traverse
     |*  life/mold
     |=  $:  vit/life
-            mac/$-({twig life} (unit (pair twig life)))
+            $=  mac
+            $-  $:  twig
+                    life
+                    $-({? twig life} {twig life})
+                ==
+            (unit (pair twig life))
         ==
     ^-  {twig life}
-    !!
+    =/  use  &
+    =<  apex 
+    |%  
+    ++  apex
+      |-  ^-  {twig life}
+      =*  aid  |=  {use/? gen/twig vit/life} 
+               ^$(use use, gen gen, vit vit)
+      =/  gun  ?:(use (mac gen vit aid) ~)
+      ?^  gun  u.gun
+      ?:  ?=(^ -.gen)
+        %.(gen dubs)
+      ?-  -.gen
+        $$     (lead -.gen %.(+.gen noop))
+        $base  (lead -.gen %.(+.gen noop))
+        $bunt  (lead -.gen %.(+.gen expr))
+        $bust  (lead -.gen %.(+.gen noop))
+        $dbug  (lead -.gen %.(+.gen nexp))
+        $hand  (lead -.gen %.(+.gen noop))
+        $knit  (lead -.gen %.(+.gen (moto bark)))
+        $leaf  (lead -.gen %.(+.gen noop))
+        $limb  (lead -.gen %.(+.gen noop))
+        $lost  (lead -.gen %.(+.gen expr))
+        $rock  (lead -.gen %.(+.gen noop))
+        $sand  (lead -.gen %.(+.gen noop))
+        $tell  (lead -.gen %.(+.gen moar))
+        $tune  (lead -.gen %.(+.gen tung))
+        $wing  (lead -.gen %.(+.gen noop))
+        $yell  (lead -.gen %.(+.gen moar))
+        $claw  (lead -.gen %.(+.gen dubs))
+        $shoe  (lead -.gen %.(+.gen expr))
+        $bank  (lead -.gen %.(+.gen moar))
+        $book  (lead -.gen %.(+.gen moar))
+        $lamb  (lead -.gen %.(+.gen dubs))
+        $bush  (lead -.gen %.(+.gen dubs))
+        $pick  (lead -.gen %.(+.gen moar))
+        $coat  (lead -.gen %.(+.gen nexp))
+        $grow  (lead -.gen %.(+.gen expr))
+        $door  (lead -.gen %.(+.gen (trio noop expr arms)))
+        $door  (lead -.gen %.(+.gen (trio noop expr arms)))
+        $gasp  (lead -.gen %.(+.gen (twin noop dubs)))
+        $corp  (lead -.gen %.(+.gen (twin noop arms)))
+        $trap  (lead -.gen %.(+.gen (twin noop expr)))
+        $cork  (lead -.gen %.(+.gen (trio noop expr arms)))
+        $loop  (lead -.gen %.(+.gen (twin noop expr)))
+        $port  (lead -.gen %.(+.gen (twin noop dubs)))
+        $gill  (lead -.gen %.(+.gen (twin noop dubs)))
+        $gate  (lead -.gen %.(+.gen (twin noop dubs)))
+        $tray  (lead -.gen %.(+.gen (twin noop expr)))
+        $scon  (lead -.gen %.(+.gen dubs))
+        $conq  (lead -.gen %.(+.gen (quad expr expr expr expr)))
+        $cons  (lead -.gen %.(+.gen dubs))
+        $cont  (lead -.gen %.(+.gen trey))
+        $conl  (lead -.gen %.(+.gen moar))
+        $conp  (lead -.gen %.(+.gen moar))
+        $keep  (lead -.gen %.(+.gen (twin noop moan)))
+        $lace  (lead -.gen %.(+.gen dubs))
+        $call  (lead -.gen %.(+.gen (twin expr moar)))
+        $bake  (lead -.gen %.(+.gen (trio noop expr moan)))
+        $calq  (lead -.gen %.(+.gen (quad expr expr expr expr)))
+        $calt  (lead -.gen %.(+.gen trey))
+        $open  (lead -.gen %.(+.gen (trio noop expr moar)))
+        $make  (lead -.gen %.(+.gen (twin noop moan)))
+        $wish  (lead -.gen %.(+.gen dubs))
+        $bump  (lead -.gen %.(+.gen expr))
+        $nock  (lead -.gen %.(+.gen dubs))
+        $same  (lead -.gen %.(+.gen dubs))
+        $deep  (lead -.gen %.(+.gen expr))
+        $iron  (lead -.gen %.(+.gen expr))
+        $ward  (lead -.gen %.(+.gen dubs))
+        $like  (lead -.gen %.(+.gen dubs))
+        $cast  (lead -.gen %.(+.gen dubs))
+        $zinc  (lead -.gen %.(+.gen expr))
+        $burn  (lead -.gen %.(+.gen expr))
+        $name  (lead -.gen %.(+.gen nexp))
+        $lead  (lead -.gen %.(+.gen expr))
+        $halo  (lead -.gen %.(+.gen nexp))
+        $help  (lead -.gen %.(+.gen nexp))
+        $show  (lead -.gen %.(+.gen dubs))
+        $lurk  (lead -.gen %.(+.gen dubs))
+        $crap  (lead -.gen %.(+.gen (raid expr)))
+        $fast  (lead -.gen %.(+.gen (quad noop expr moan expr)))
+        $funk  (lead -.gen %.(+.gen nexp))
+        $thin  (lead -.gen %.(+.gen (twin toad expr)))
+        $hint  (lead -.gen %.(+.gen (twin toad expr)))
+        $poll  (lead -.gen %.(+.gen nexp))
+        $memo  (lead -.gen %.(+.gen nexp))
+        $dump  (lead -.gen %.(+.gen trip))
+        $ddup  (lead -.gen %.(+.gen dubs))
+        $warn  (lead -.gen %.(+.gen (quad noop expr expr expr)))
+        $peep  (lead -.gen %.(+.gen dubs))
+        $wad   (lead -.gen %.(+.gen (twin expr moar)))
+        $nub   (lead -.gen %.(+.gen expr))
+        $dip   (lead -.gen %.(+.gen (twin expr moar)))
+        $fry   (lead -.gen %.(+.gen dubs))
+        $new   (lead -.gen %.(+.gen dubs))
+        $fix   (lead -.gen %.(+.gen (twin moan expr)))
+        $var   (lead -.gen %.(+.gen (trio tora expr expr)))
+        $rev   (lead -.gen %.(+.gen (trio tora expr expr)))
+        $set   (lead -.gen %.(+.gen trip))
+        $huh   (lead -.gen %.(+.gen (quad noop expr expr expr)))
+        $rap   (lead -.gen %.(+.gen dubs))
+        $nip   (lead -.gen %.(+.gen dubs))
+        $per   (lead -.gen %.(+.gen dubs))
+        $sip   (lead -.gen %.(+.gen (quad tora noop expr expr)))
+        $pin   (lead -.gen %.(+.gen dubs))
+        $tow   (lead -.gen %.(+.gen moar))
+        $aka   (lead -.gen %.(+.gen trip))
+        $use   (lead -.gen %.(+.gen dubs))
+        $or    (lead -.gen %.(+.gen moar))
+        $case  (lead -.gen %.(+.gen (twin noop (moto dubs))))
+        $if    (lead -.gen %.(+.gen trey))
+        $lest  (lead -.gen %.(+.gen trey))
+        $ifcl  (lead -.gen %.(+.gen trip))
+        $deny  (lead -.gen %.(+.gen dubs))
+        $sure  (lead -.gen %.(+.gen dubs))
+        $deft  (lead -.gen %.(+.gen (trio noop expr (moto dubs))))
+        $and   (lead -.gen %.(+.gen moar))
+        $ifat  (lead -.gen %.(+.gen trip))
+        $ifno  (lead -.gen %.(+.gen trip))
+        $fits  (lead -.gen %.(+.gen (twin expr noop)))
+        $not   (lead -.gen %.(+.gen expr))
+        $twig  (lead -.gen %.(+.gen dubs))
+        $wrap  (lead -.gen %.(+.gen expr))
+        $spit  (lead -.gen %.(+.gen dubs))
+        $code  (lead -.gen %.(+.gen expr))
+        $need  (lead -.gen %.(+.gen nexp))
+        $fail  (lead -.gen %.(+.gen noop))
+      ==
+    ++  arms
+      (raid (twin noop (raid (twin noop heel))))
+    ::
+    ++  bark 
+      |=  wof/woof
+      ?-(wof @ [wof vit], ^ (lead ~ (expr p.wof)))
+    ::
+    ++  dubs
+      (twin expr expr)
+    ::
+    ++  expr
+      |=  p/twig
+      ^$(gen p)
+    ::
+    ++  heel
+      |=  bud/foot
+      ?-  -.bud
+        $ash  =^(nex vit ^$(gen p.bud) [[%ash nex] vit])
+        $elm  =^(nex vit ^$(gen p.bud) [[%elm nex] vit])
+      ==
+    ::
+    ++  lead
+      |*  {sem/@tas out/{* life}}
+      [[sem -.out] +.out]
+    ::
+    ++  moan
+      (moto nexp)
+    ::
+    ++  moar
+      (moto expr)
+    ::
+    ++  moto
+      |*  etc/$-(* {* life})
+      |*  bud/*
+      ^+  [bud vit]
+      ?:  =(~ bud)  [bud vit]
+      =^  heb  vit  (etc -.bud)
+      =^  mor  vit  $(bud +.bud)
+      [[heb mor] vit]
+    ::
+    ++  nexp
+      (twin noop expr)
+    ::
+    ++  noop
+      |*  bud/*
+      [bud vit]
+    ::
+    ++  quad
+      |*  $:  one/$-(* {* life})
+              two/$-(* {* life})
+              tri/$-(* {* life})
+              qua/$-(* {* life})
+          ==
+      |*  bud/*
+      =^  yal  vit  (one -.bud)
+      =^  ves  vit  (two +<.bud)
+      =^  jot  vit  (tri +>-.bud)
+      =^  wip  vit  (qua +>+.bud)
+      [[yal ves jot wip] vit]
+    ::
+    ++  raid
+      |*  etc/$-(* {* life})
+      |*  bud/*
+      ^+  [bud vit]
+      ?:  =(~ bud)  [bud vit]
+      =^  lef  vit  $(bud +<.bud)
+      =^  ryt  vit  $(bud +>.bud)
+      =^  top  vit  (etc ->.bud)
+      [[[-<.bud top] lef ryt] vit]
+    ::
+    ++  trey
+      (trio expr expr expr)
+    ::
+    ++  trio
+      |*  $:  one/$-(* {* life})
+              two/$-(* {* life})
+              tri/$-(* {* life})
+          ==
+      |*  bud/*
+      =^  yal  vit  (one -.bud)
+      =^  ves  vit  (two +<.bud)
+      =^  jot  vit  (tri +>.bud)
+      [[yal ves jot] vit]
+    ::
+    ++  trip
+      (trio noop expr expr)
+    ::
+    ++  toad
+      |=  bud/$@(term {p/term q/twig})
+      ?@  bud  [bud vit]
+      (lead p.bud (expr q.bud))
+    ::
+    ++  tora
+      (twin noop twee)
+    ::
+    ++  tung
+      |=  bud/{p/what q/$@(term tune)}
+      ?@  q.bud  [bud vit]
+      (lead p.bud %.(q.bud (twin (raid (twin noop twee)) (moto expr))))
+    ::
+    ++  twee
+      |=  bud/(unit twig)
+      ?~  bud  [~ vit]
+      (lead ~ (expr u.bud))
+    ::
+    ++  twin
+      |*  {one/$-(* {* life}) two/$-(* {* life})}
+      |*  bud/*
+      =^  yal  vit  (one -.bud)
+      =^  ves  vit  (two +.bud)
+      [[yal ves] vit]
+    --
   --
 ::
 ::::  5c: compiler backend and prettyprinter
@@ -6676,9 +7043,9 @@
   ::
   ++  buss
     ~/  %buss
-    |=  {cog/term gen/twig}
+    |=  {{wat/what cog/term} gen/twig}
     ^-  span
-    [%face [~ [[cog ~ ~ gen] ~ ~] ~] sut]
+    [%face [wat [[cog ~ ~ gen] ~ ~] ~] sut]
   ::
   ++  conk
     |=  got/toga
@@ -8634,8 +9001,134 @@
   ++  mota  %+  cook
               |=({a/tape b/tape} (rap 3 (weld a b)))
             ;~(plug (star low) (star hig))
-  ++  epic                                              ::  to end of line 
-    (cook crip (ifix [;~(plug ace ace) (just `@`10)] (star prn)))
+  ++  glom
+    |=  {wit/whit taw/whit}
+    ^-  whit
+    :*  ?~(lab.wit lab.taw lab.wit)
+        ?~(boy.wit boy.taw boy.wit)
+        (~(uni by def.wit) def.taw)
+        (~(uni in use.wit) use.taw)
+    ==
+  ++  docs
+    |%
+    ::  above core
+    ::
+    ++  apex
+      %+  cook  beer
+      ;~  plug
+        =/  ron  (punt (into noel))
+        (punt (ifix [ron ron] (into (step head))))
+        ;~(pfix (punt (into null)) (punt body))
+        (star fill)
+      ==
+    ::  backward line
+    ::
+    ++  apse
+      ;~  pose
+        %+  cook
+          |=  a/(each (pair term cord) cord)
+          ^-  whit
+          ?-  -.a
+            $&  [~ ~ [[p.p.a [q.p.a ~]] ~ ~] ~]
+            $|  [~ `[p.a ~] ~ ~]
+          ==
+        (exit (step (pick fine line)))
+        (easy *whit)
+      ==
+    ::
+    ::
+    ++  beer
+      |=  $:  a/(unit term)
+              b/(unit (pair cord (list sect)))
+              c/(list (pair (pair term cord) (list sect)))
+          ==
+      ^-  whit
+      =/  d
+        |-  ^-  (map term (pair cord (list sect)))
+        ?~  c  ~
+        =/  e  $(c t.c)
+        (~(put by e) p.p.i.c [q.p.i.c q.i.c])
+      [a b d ~]
+    ::
+    ::
+    ++  body
+      ;~  sfix
+        ;~  pose
+          ;~  plug
+            (into ;~(pfix (punt ;~(plug (star ace) col gar)) (step line)))
+            (easy ~)
+          ==
+          ;~  plug
+            (into (dubs line))
+            (rant text)
+          ==
+        ==
+        (punt (into null))
+      ==
+    ::
+    ::  null: blank line
+    ::  line: prose line
+    ::  code: code line
+    ::  text: text line
+    ::  fine: definition line
+    ::
+    ++  line  (cook crip ;~(plug prz (star prn)))
+    ++  head  ;~(pfix ;~(plug bar bar ace ace cen) sym)
+    ++  text  (pick line code)
+    ++  code  (cook crip (dubs (star prn)))
+    ++  null  (star ace)
+    ++  noel  ;~(pose (step ;~(sfix ;~(plug bar bar) (star ace))) null)
+    ++  fine  ;~(plug sym (cook crip ;~(pfix ;~(plug col ace) (star prn))))
+    ::
+    ::  lean: line delimited
+    ::
+    ++  lean
+      |*  gyf/rule
+      |*  bod/rule
+      ;~(pfix ;~(plug col gyf) bod)
+    ::
+    ::  step: indent
+    ::
+    ++  step
+      |*  fel/rule
+      ;~(pfix ;~(plug ace ace) fel)
+    ::
+    ::  dubs: double-indent
+    ::
+    ++  dubs
+      |*  fel/rule
+      ;~(pfix ;~(plug ace ace ace ace) fel)
+    ::
+    ::  into: :> to end of line, consuming following space.
+    ::
+    ++  into  
+      |*  bod/rule
+      ;~(sfix ((lean gar) bod) ;~(plug (just `@`10) (punt gap)))
+    ::
+    ::  exit: :< to end of line, not consuming following space.
+    ::
+    ++  exit
+      |*  bod/rule
+      ;~(pfix (star ace) ((lean gal) bod))
+    ::
+    ::  fill: full definition
+    ::
+    ++  fill
+      ;~  sfix 
+        ;~(plug (into (step fine)) (rant (step text))) 
+        (punt (into null))
+      ==
+    ::
+    ::  rant: series of sections.
+    ::
+    ++  rant
+      |*  sec/rule
+      %-  star
+      ;~  pfix  
+        (into null)
+        (plus (into (step sec)))
+      ==
+    --
   ::
   ++  plex
     |=  gen/twig  ^-  (unit path)
@@ -9559,30 +10052,40 @@
     |%
     ++  boog                                            ::  core arms
       %+  knee  [p=*term q=*(pair what foot)]  |.  ~+
-      ;~  pfix  lus
-        ;~  pose
-          %+  cook
-            |=({a/$ash b/term c/twig} [b *what a c])
-          ;~  gunk
-            (cold %ash (just '+'))
-            ;~(pose (cold %$ buc) sym)
-            loaf
-          ==
-        ::
-          %+  cook
-            |=({a/$elm b/term c/twig} [b *what a c])
-          ;~  gunk
-            (cold %elm (just '-'))
-            ;~(pose (cold %$ buc) sym)
-            loaf
-          ==
-        ::
-          %+  cook
-            |=({a/$ash b/term c/root} [b *what a c])
-          ;~  gunk
-            (cold %ash (just '='))
-            sym
-            loan
+      %+  cook
+        |=  {a/whit b/term c/whit d/foot}
+        =+  e=(glom a c)
+        [b boy.e d]
+      ;~  plug
+        apex:docs
+        ;~  pfix  lus
+          ;~  pose
+            %+  cook
+              |=({a/$ash b/term c/whit d/twig} [b c a d])
+            ;~  plug
+              (cold %ash (just '+'))
+              ;~(pfix gap ;~(pose (cold %$ buc) sym))
+              apse:docs
+              ;~(pfix gap loaf)
+            ==
+          ::
+            %+  cook
+              |=({a/$elm b/term c/whit d/twig} [b c a d])
+            ;~  plug
+              (cold %elm (just '-'))
+              ;~(pfix gap ;~(pose (cold %$ buc) sym))
+              apse:docs
+              ;~(pfix gap loaf)
+            ==
+          ::
+            %+  cook
+              |=({a/$ash b/term c/whit d/root} [b c a d])
+            ;~  plug
+              (cold %ash (just '='))
+              ;~(pfix gap sym)
+              apse:docs
+              ;~(pfix gap loan)
+            ==
           ==
         ==
       ==
@@ -9593,33 +10096,33 @@
     ++  wisp                                            ::  core tail
       ?.  tol  fail
       %+  sear
-        |=  a/(list (list (pair term (pair what foot))))
+        |=  a/(list (pair whit (list (pair term (pair what foot)))))
         =|  {b/(map @ tomb) c/@}
         |-  ^-  (unit (map @ tomb))
         ?~  a  `b
         =/  d
           =|  e/(map term (pair what foot))
           |-  ^-  (unit (map term (pair what foot)))
-          ?~  i.a  `e
-          ?:  ?|  (~(has by e) p.i.i.a)
+          ?~  q.i.a  `e
+          ?:  ?|  (~(has by e) p.i.q.i.a)
                   |-  ^-  ?
                   ?:  =(0 c)  |
                   =.  c  (dec c)
-                  |((~(has by q:(~(got by b) c)) p.i.i.a) $)
+                  |((~(has by q:(~(got by b) c)) p.i.q.i.a) $)
               ==
-            ::  XX we don't have a good way to annotate
-            ::  postparse construction "syntax" errors
+            ::  XX hokey, refactor this to produce %eror
             ::
-            ~&(duplicate-arm+p.i.i.a ~)
-          $(i.a t.i.a, e (~(put by e) p.i.i.a q.i.i.a))
+            ~&(duplicate-arm+p.i.q.i.a ~)
+          $(q.i.a t.q.i.a, e (~(put by e) p.i.q.i.a q.i.q.i.a))
         ?~  d  ~
-        $(a t.a, b (~(put by b) c [*chap u.d]), c +(c))
+        =*  hap  `chap`[?~(lab.p.i.a ~ [u.lab.p.i.a ~]) boy.p.i.a]
+        $(a t.a, b (~(put by b) c [hap u.d]), c +(c))
       ;~  pose
         dun
         ;~  sfix
           ;~  pose
-            (most muck ;~(pfix ;~(plug lus bar gap) whap))
-            ;~(plug whap (easy ~))
+            (most muck ;~(plug apex:docs ;~(pfix ;~(plug lus bar gap) whap)))
+            ;~(plug ;~(plug (easy *whit) whap) (easy ~))
           ==
           ;~(plug gap dun)
         ==
@@ -9711,9 +10214,8 @@
     ++  expg  |.(;~(gunk sym loaf))                     ::  term and twig
     ++  exph  |.((butt ;~(gunk rope rick)))             ::  wing, [tile twig]s
     ++  expi  |.((butt ;~(gunk loaf hank)))             ::  one or more twigs
-    ++  expj  |.(;~(gunk sym rope loaf))                ::  term, wing, and twig
     ++  expk  |.(;~(gunk loaf ;~(plug loaf (easy ~))))  ::  list of two twigs
-    ++  expl  |.(;~(gunk sym loaf loaf))                ::  term, two twigs
+    ++  expl  |.(;~(gunk ;~(plug (easy ~) sym) loaf loaf))  ::  term, two twigs
     ++  expm  |.((butt ;~(gunk rope loaf rick)))        ::  several [tile twig]s
     ++  expo  |.(;~(gunk wise loaf loaf))               ::  =;
     ++  expp  |.(;~(gunk (butt rick) loaf))             ::  [wing twig]s, twig
@@ -9888,58 +10390,33 @@
     ==
   ::
   ++  wise  ;~(plug sym (punt ;~(pfix ;~(pose fas tis) wyde)))
-  ++  wack
+  ++  wrap
+    |*  fel/rule
     %+  cook
-      |=  {a/wain b/twig c/(unit cord)}
+      |=  {a/whit b/twig c/whit}
       ^-  twig
-      =.  a  ?~(c a [u.c a])
-      ?~  a  b
-      [%help ~ b]
+      ~(graf ~(gi ap b) (glom a c))
+    ::
+    ::  XX performance: this makes the parser about 50% slower.
+    ::  because we double-parse most of the spaces in the file.
+    ::  just so we can do a postfix doc-comment.
+    ::  
+    ::  the correct solution to this problem is to unify the
+    ::  parsing of docs with the parsing of comments/spaces.
+    ::  but at this point we're pretty much in parser rewrite.
+    ::
+    ::  it should go without saying that ++vast needs a rewrite.
+    ::  it dates to 2011.
+    ::
     ;~  plug
-      (star (ifix [;~(plug col gar) (punt gap)] epic))
-      ;~(pose (norm | &) long lute ape:(sail &))
-      ::
-      ::  XX performance: this makes the parser about 50% slower.
-      ::  because we double-parse most of the spaces in the file.
-      ::  just so we can do a postfix doc-comment.
-      ::  
-      ::  the correct solution to this problem is to unify the
-      ::  parsing of docs with the parsing of comments/spaces.
-      ::  but at this point we're pretty much in parser rewrite.
-      ::
-      ::  it should go without saying that ++vast needs a rewrite.
-      ::  it dates to 2011.
-      ::
-      (punt ;~(pfix ;~(plug (star ace) col gal) epic))
-    ==
-  ++  wock
-    %+  cook
-      |=  {a/wain b/twig c/(unit cord)}
-      ^-  twig
-      =.  a  ?~(c a [u.c a])
-      ?~  a  b
-      [%help ~ b]
-    ;~  plug
-      (star (ifix [;~(plug col gar) (punt gap)] epic))
-      ;~(pose (norm & &) scad)
-      ::
-      ::  XX performance: this makes the parser about 50% slower.
-      ::  because we double-parse most of the spaces in the file.
-      ::  just so we can do a postfix doc-comment.
-      ::  
-      ::  the correct solution to this problem is to unify the
-      ::  parsing of docs with the parsing of comments/spaces.
-      ::  but at this point we're pretty much in parser rewrite.
-      ::
-      ::  it should go without saying that ++vast needs a rewrite.
-      ::  it dates to 2011.
-      ::
-      (punt ;~(pfix ;~(plug (star ace) col gal) epic))
+      apex:docs
+      fel
+      apse:docs
     ==
   ++  tall  %+  knee  *twig                             ::  full tall form
-            |.(~+((wart wack)))
+            |.(~+((wart (wrap ;~(pose (norm | &) long lute ape:(sail &))))))
   ++  till  %+  knee  *root                             ::  full tall form
-            |.(~+((wart wock)))
+            |.(~+((wart (wrap ;~(pose (norm & &) scad)))))
   ++  wide  %+  knee  *twig                             ::  full wide form
             |.(~+((wart ;~(pose (norm | |) long ape:(sail |)))))
   ++  wyde  %+  knee  *root                             ::  full wide form