diff --git a/app/talk.hoon b/app/talk.hoon
index 4323b9d60..c7452a07f 100644
--- a/app/talk.hoon
+++ b/app/talk.hoon
@@ -1,13 +1,23 @@
 ::                                                      ::  ::  
 ::::  /hoon/talk/app                                    ::  ::
   ::                                                    ::  ::   
-/?    310
-/-    talk, sole
-/+    talk, sole, time-to-id, twitter
+::
+::TODO  master changes
+::TODO  =/ instead of =+ ^= where possible
+::TODO  avoid lark where possible
+::TODO  remove old/unused code
+::TODO  improve naming
+::TODO  tidiness
+::
+/?    310                                               ::  hoon version
+/-    talk, sole                                        ::  structures
+/+    talk, sole, time-to-id, twitter                   ::  libraries
 /=    seed  /~  !>(.)
 ::
 ::::
   ::
+::x  include talk and sole cores from the /+ include into our subject,
+::x  so we can do some-arm instead of some-arm:talk.
 [. talk sole]
 =>  |%                                                  ::  data structures
     ++  house  {$6 house-6}                             ::  full state
@@ -121,6 +131,8 @@
       ==                                                ::
     ++  where  (set partner)                            ::  non-empty audience 
     ++  sigh                                            ::  assemble label
+      ::x?  why is this not in ++ta?
+      ::
       |=  {len/@ud pre/tape yiz/cord}
       ^-  tape
       =+  nez=(trip yiz)
@@ -132,8 +144,11 @@
         ?.  (lth lez len)  nez
         (runt [(sub len lez) '-'] nez)
       :(welp pre (scag (dec len) nez) "+")  
-    ++  glyphs  `wall`~[">=+-" "}),." "\"'`^" "$%&@"]     :: station char pool
+    ++  glyphs  `wall`~[">=+-" "}),." "\"'`^" "$%&@"]     :: station char pool'
     ++  peer-type                                       ::  stream requests
+      ::x  helper functions for determining/specifying from/in a path, what kind
+      ::x  of subscription our peer wants/what they're interested in.
+      ::
       =<  apex
       |%
       ++  apex  ?($a-group $f-grams $v-glyph $x-cabal)  ::  options
@@ -151,22 +166,37 @@
 |%
 ::  old protocol workaround door
 ++  timed
+  ::x?  seems hacky. if old, should be removed in "new talk", right?
+  ::x?  seems like it's used for adding/dealing with "fake"/workaround ships
+  ::x?  with datetimes in their status. but why?
+  ::x  looking at ++pa-remind, this can safely be deleted when breaching state.
+  ::
+  ::x  a: stations with ships and their status.
   |_  a/(map partner atlas) :: XX (map partner (pair @da atlas))
   ++  strip
+    ::x  removes workaround ships from all partner's status lists.
+    ::
     (~(run by a) |=(b/atlas (~(del by b) `@p`%timed-sub)))
   ::
   ++  put  ::  XX put:by
+    ::x  adds workaround ship to d with pretty-printed date c in its status,
+    ::x  then adds it to a with key/partner b.
+    ::
     |=  {b/partner c/@da d/atlas}
     =/  sta/status  [%gone [~ (some (scot %da c))]]
     (~(put by a) b (~(put by d) `@p`%timed-sub sta))
   ::
   ++  decode-status
+    ::x  attempts to retrieve datetime from status (as inserted by put:timed).
+    ::
     |=  a/status  ^-  (unit @da)
     ?.  ?=({$gone $~ $~ tym/@t} a)  ~
     =>  .(a `{$gone $~ $~ tym/@t}`a)
     (slaw %da tym.a)
   ::
   ++  uni
+    ::x  union of two station-shipstatus maps.
+    ::
     |=  b/_a  ^+  a
     :: XX efficiency
     %-  ~(uni by a)
@@ -190,12 +220,34 @@
 --
 |_  {hid/bowl house}
 ++  ra                                                  ::  per transaction
+  ::x  gets called when talk gets poked or otherwise prompted/needs to perform
+  ::x  an action.
+  ::x  arms generally modify state, and store moves in ++ra's moves. these get
+  ::x  produced when calling ++ra-abet.
+  ::x  in applying commands and making reports, it uses ++pa for story work.
+  ::
+  ::x  moves: moves storage, added to by ++ra-emit and -emil, produced by -abed.
   |_  moves/(list move)
   ++  sh                                                ::  per console
-    |_  $:  coz/(list command)                          ::  talk actions
+    ::x  shell core, responsible for doing things with console sessions,
+    ::x  like parsing input, acting based on input, showing output, keeping
+    ::x  track of settings and other frontend state.
+    ::x  important arms include ++sh-repo which is used to apply reports, and
+    ::x  ++sh-sole which gets called upon cli prompt interaction.
+    ::x  any talk commands the core's arms want to have executed get put into
+    ::x  coz. the stored commands get applied upon calling ++sh-abet. 
+    ::
+    |_  $:  ::x  coz: talk commands storage, applied by ++sh-abet.
+            ::x  she: console session state used in this core.
+            ::
+            coz/(list command)                          ::  talk actions
             she/shell
         ==
     ++  sh-scad                                         ::  command parser
+      ::x  builds a core with parsers for talk-cli, and produces its work arm.
+      ::x  ++work uses those parsers to parse the current talk-cli prompt input
+      ::x  and produce a work item to be executed by ++sh-work.
+      ::
       =<  work
       |%
       ++  expr                                          ::  [cord twig]
@@ -346,47 +398,71 @@
         ==
       --
     ++  sh-abet
-      ^+  +>
+      ::x  applies talk commands (in reverse order, because ++sh-tell adds them
+      ::x  to coz as [new coz], but you want to apply them in the order
+      ::x  [coz new]). produces an updated context for the ++sh core.
+      ::
+      ^+  +>  ::x  points to ++sh's |_ core's context.
       =+  zoc=(flop coz)
-      |-  ^+  +>+>
+      |-  ^+  +>+>  ::x  +> would point to |-'s context. +>+> goes to ++sh |_'s.
+      ::x  produce context with this shell updated.
       ?~  zoc  +>+>.$(shells (~(put by shells) ost.hid she))
+      ::x  recurse, with context (of |-?) modified.
       $(zoc t.zoc, +>.$ (sh-deal i.zoc))
     ::
     ++  sh-deal                                         ::  apply from shell
+      ::x  used by ++sh-abet, applies an individual talk command.
+      ::
       |=  cod/command
       ^+  +>
       ?-    -.cod
+        ::x  the $design command is used for modifying channel configs,
+        ::x  which is done when joining, leaving or creating channels.
           $design
         ?~  q.cod
+          ::x  updates context with new config state.
           =.  +>+>.$  (ra-config p.cod *config)
+          ::x  produces context with story p.cod deleted.
           +>.$(stories (~(del by stories) p.cod))
+        ::x  produces +> with its +> (so, +>+>) updated by ++ra-think.
         +>(+> (ra-config p.cod u.q.cod))
       ::
+        ::x  used for relaying messages (as a station host).
           $review   +>(+> (ra-think | her.she +.cod))
+        ::x  used for sending messages (as their author).
           $publish  +>(+> (ra-think & her.she +.cod))
       ==
     ::
     ++  sh-fact                                         ::  send console effect
+      ::x  adds a console effect to ++ra's moves.
+      ::
       |=  fec/sole-effect
       ^+  +>
       +>(moves :_(moves [ost.hid %diff %sole-effect fec]))
     ::
     ++  sh-peep                                         ::  peer to path
+      ::x?  unused?
+      ::
       |=  pax/path
       ^+  +>
       +>(+> (ra-subscribe her.she pax))
     ::
     ++  sh-peer                                         ::  subscribe shell
+      ::x  create a shell, subscribe to default stories.
+      ::
       =<  sh-prod
       %_    .
           +>
         =/  typ
           =+  (ly ~[%a-group %f-grams %x-cabal])
           (rap 3 (turn - encode:peer-type))
+        ::x  subscriptions to the shell's ship's default channels.
         (ra-subscribe:(ra-subscribe her.she ~) her.she [typ man.she ~])
       ==
     ::
     ++  sh-prod                                         ::  show prompt
+      ::x  make and store a move to modify the cli prompt, displaying audience.
+      ::
       ^+  .
       %+  sh-fact  %pro
       :+  &  %talk-line
@@ -400,19 +476,27 @@
       (weld `tape`[p.p.rew por] `tape`[q.p.rew ' ' ~])
     ::
     ++  sh-pact                                         ::  update active aud
+      ::x  change currently selected audience to lix, updating prompt.
+      ::
       |=  lix/(set partner)
       ^+  +>
-      =+  act=(sh-pare lix)
-      ?~  act  ~|(%no-audience !!)
+      =+  act=(sh-pare lix)  ::x  ensure we can see what we send.
+      ?~  act  ~|(%no-audience !!)  ::x?  this can't actually happen, right?
       ?:  =(active.she `act)  +>.$
       sh-prod(active.she `act)
     ::
     ++  sh-pare                                         ::  adjust target list
+      ::x  if the audience paz does not contain a partner we're subscribed to,
+      ::x  add our mailbox to the audience (so that we can see our own message).
+      ::
       |=  paz/(set partner)
       ?:  (sh-pear paz)  paz
       (~(put in paz) [%& our.hid man.she])
     ::
     ++  sh-pear                                         ::  hearback
+      ::x  produces true if any partner is included in our subscriptions,
+      ::x  aka, if we hear messages sent to paz.
+      ::
       |=  paz/(set partner)
       ?~  paz  |
       ?|  $(paz l.paz) 
@@ -421,20 +505,28 @@
       ==
     ::
     ++  sh-pest                                         ::  report listen
+      ::x  updates audience to be tay, only if tay is not a village/%white.
+      ::x?  why exclude village (invite-only?) audiences from this?
+      ::
       |=  tay/partner
       ^+  +>
-      ?.  ?=($& -.tay)  +>
-      =+  sib=(~(get by ham.system.she) `station`p.tay)
+      ?.  ?=($& -.tay)  +>  ::x  if partner is a passport, do nothing.
+      =+  sib=(~(get by ham.system.she) `station`p.tay)  ::x  get config for tay
       ?.  |(?=($~ sib) !?=($white p.cordon.u.sib))
         +>.$
       (sh-pact [tay ~ ~])
     ::
     ++  sh-rend                                         ::  print on one line
+      ::x  renders a telegram as a single line, adds it as a console move,
+      ::x  and updates the selected audience to match the telegram's.
+      ::
       |=  gam/telegram
       =+  lin=~(tr-line tr man.she settings.she gam)
       (sh-fact %txt lin)
     ::
     ++  sh-numb                                         ::  print msg number
+      ::x  does as it says on the box.
+      ::
       |=  num/@ud
       ^+  +>
       =+  bun=(scow %ud num)
@@ -442,18 +534,27 @@
       (runt [(sub 13 (lent bun)) '-'] "[{bun}]")
     ::
     ++  sh-glyf                                         ::  decode glyph
+      ::x  gets the partner(s) that match a glyph.
+      ::x?  why (set partner)? it seems like it only ever returns a single one.
+      ::TODO should produce a set when ambiguous.
+      ::
       |=  cha/char  ^-  (unit (set partner))
       =+  lax=(~(get ju nak) cha)
-      ?:  =(~ lax)  ~
-      ?:  ?=({* $~ $~} lax)  `n.lax
+      ?:  =(~ lax)  ~  ::x  no partner.
+      ?:  ?=({* $~ $~} lax)  `n.lax  ::x  single partner.
+      ::x  in case of multiple partners, pick the most recently active one.
       =+  grams=grams:(~(got by stories) man.she)
       |-  ^-  (unit (set partner))
       ?~  grams  ~
+      ::x  get first partner from a telegram's audience.
       =+  pan=(silt (turn (~(tap by q.q.i.grams)) head))
       ?:  (~(has in lax) pan)  `pan
       $(grams t.grams)
-      ::
+    ::
+    ::TODO  we have a stdlib set diff now!
     ++  sh-repo-house-diff
+      ::x  calculates difference between two shelves (channel definitions).
+      ::
       |=  {one/shelf two/shelf}
       =|  $=  ret
           $:  old/(list (pair knot (pair posture cord)))
@@ -482,6 +583,8 @@
       ret 
     ::
     ++  sh-repo-atlas-diff
+      ::x  calculates the difference between two atlasses (presence lists).
+      ::
       |=  {one/atlas two/atlas}
       =|  $=  ret
           $:  old/(list (pair ship status))
@@ -516,6 +619,8 @@
       ret 
     ::
     ++  sh-repo-cabal-diff
+      ::x  calculates the difference between two cabals (station configurations)
+      ::
       |=  {one/(map station config) two/(map station config)}
       =|  $=  ret
           $:  old/(list (pair station config))
@@ -544,6 +649,9 @@
       ret
     ::
     ++  sh-repo-rogue-diff
+      ::x  calculates the difference between two maps of stations and their
+      ::x  presence lists.
+      ::
       |=  {one/(map partner atlas) two/(map partner atlas)}
       =|  $=  ret
           $:  old/(list (pair partner atlas))
@@ -574,6 +682,8 @@
       ret
     ::
     ++  sh-repo-whom-diff
+      ::x  calculates the difference between two partner sets.
+      ::
       |=  {one/(set partner) two/(set partner)}
       =|  $=  ret
           $:  old/(list partner)
@@ -599,6 +709,8 @@
       ret
     ::
     ++  sh-repo-ship-diff
+      ::x  calculates the difference between two ship sets.
+      ::
       |=  {one/(set ship) two/(set ship)}
       =|  $=  ret
           $:  old/(list ship)
@@ -624,6 +736,8 @@
       ret 
     ::
     ++  sh-puss
+      ::x  posture as text.
+      ::
       |=  a/posture  ^-  tape
       ?-  a
         $black  "channel"
@@ -633,6 +747,8 @@
       ==
     ::
     ++  sh-repo-config-exceptions
+      ::x  used by ++sh-repo-config-show to aid in printing info to cli.
+      ::
       |=  {pre/tape por/posture old/(list ship) new/(list ship)}
       =+  out=?:(?=(?($black $brown) por) "try " "cut ")
       =+  inn=?:(?=(?($black $brown) por) "ban " "add ")
@@ -649,6 +765,9 @@
       +>.$
     ::
     ++  sh-repo-config-sources
+      ::x  used by ++sh-repo-config-show to aid in printing info to cli,
+      ::x  pertaining to the un/subscribing to partners.
+      ::
       |=  {pre/tape old/(list partner) new/(list partner)}
       ^+  +>
       =.  +>.$
@@ -664,6 +783,8 @@
       +>.$
     ::
     ++  sh-repo-config-show
+      ::x  prints config changes to the cli.
+      ::
       |=  {pre/tape laz/config loc/config}
       ^+  +>
       =.  +>.$
@@ -685,6 +806,8 @@
       (sh-repo-ship-diff q.cordon.laz q.cordon.loc)
     ::
     ++  sh-repo-cabal-changes
+      ::x  used by ++sh-repo-cabal for printing cabal config changes to cli.
+      ::
       |=  $:  laz/(map station config)
               old/(list (pair station config))
               new/(list (pair station config))
@@ -708,6 +831,8 @@
       +>.$
     ::
     ++  sh-repo-cabal
+      ::x  updates the current shell's cabal and prints changes to cli.
+      ::
       |=  bal/cabal
       ^+  +>
       =+  laz=system.she
@@ -718,6 +843,8 @@
       (sh-repo-config-show "" loc.laz loc.bal)
     ::
     ++  sh-repo-house
+      ::x  applies new shelf ("house"?) and prints changes to cli.
+      ::
       |=  awl/(map knot (pair posture cord))
       ^+  +>
       =+  dif=(sh-repo-house-diff harbor.she awl) 
@@ -748,16 +875,22 @@
       +>.$
     ::
     ++  sh-note                                         ::  shell message
+      ::x  prints a txt to cli in talk's format.
+      ::
       |=  txt/tape
       ^+  +>
       (sh-fact %txt (runt [14 '-'] `tape`['|' ' ' (scag 64 txt)]))
     ::
     ++  sh-spaz                                         ::  print status
+      ::x  gets the presence of a status.
+      ::
       |=  saz/status
       ^-  tape
       ['%' (trip p.saz)]
     ::
     ++  sh-repo-group-diff-here                         ::  print atlas diff
+      ::x  prints presence notifications.
+      ::
       |=  $:  pre/tape 
             $=  cul
             $:  old/(list (pair ship status))
@@ -786,6 +919,8 @@
       +>.$
     ::
     ++  sh-repo-group-here                              ::  update local
+      ::x  updates local presence store and prints changes.
+      ::
       |=  loc/atlas
       ^+  +>
       =+  cul=(sh-repo-atlas-diff p.owners.she loc)
@@ -793,6 +928,8 @@
       (sh-repo-group-diff-here "" cul)
     ::
     ++  sh-repo-group-there                             ::  update foreign
+      ::x  updates remote presences(?) and prints changes.
+      ::
       |=  yid/(map partner atlas)
       =+  day=(sh-repo-rogue-diff q.owners.she yid)
       =+  dun=q.owners.she
@@ -823,6 +960,8 @@
       +>.$
     ::
     ++  sh-repo-group
+      ::x  update local and remote presences.
+      ::
       |=  ges/register
       ^+  +>
       =.  +>  (sh-repo-group-here p.ges)
@@ -830,6 +969,9 @@
       +>
     ::
     ++  sh-repo-gram
+      ::x  renders telegram: increase gram count and print the gram.
+      ::x  every fifth gram, prints the number.
+      ::
       |=  {num/@ud gam/telegram}
       ^+  +>
       ?:  =(num count.she)
@@ -841,12 +983,16 @@
       +> 
     ::
     ++  sh-repo-grams                                   ::  apply telegrams
+      ::x  renders telegrams.
+      ::
       |=  {num/@ud gaz/(list telegram)}
       ^+  +>
       ?~  gaz  +>
       $(gaz t.gaz, num +(num), +> (sh-repo-gram num i.gaz))
     ::
     ++  sh-repo-glyph                                   ::  apply binding
+      ::x  updates glyph bindings and lookup, and updates selected audience.
+      ::
       |=  nac/(jug char (set partner))
       ^+  +>
       %_  sh-prod
@@ -859,6 +1005,8 @@
       ==
     ::
     ++  sh-repo                                         ::  apply report
+      ::x  applies the different kinds of reports using their handler arms above
+      ::
       |=  rad/report
       ^+  +>
       ::  ~&  [%sh-repo rad]
@@ -871,6 +1019,9 @@
       ==
     ::
     ++  sh-sane-chat                                    ::  sanitize chatter
+      ::x  (for chat messages) sanitizes the input buffer and splits it into
+      ::x  multiple lines ('•').
+      ::
       |=  buf/(list @c)
       ^-  (list sole-edit)
       ?~  buf  ~
@@ -911,6 +1062,8 @@
       --
     ::
     ++  sh-sane                                         ::  sanitize input
+      ::x  parses cli prompt input using ++sh-scad and sanitizes when invalid.
+      ::
       |=  {inv/sole-edit buf/(list @c)}
       ^-  {lit/(list sole-edit) err/(unit @u)}
       =+  res=(rose (tufa buf) sh-scad)
@@ -929,6 +1082,8 @@
       ==
     ::
     ++  sh-slug                                         ::  edit to sanity
+      ::x  corrects invalid prompt input.
+      ::
       |=  {lit/(list sole-edit) err/(unit @u)}
       ^+  +>
       ?~  lit  +>
@@ -937,6 +1092,9 @@
       (sh-fact [%mor [%det lic] ?~(err ~ [%err u.err]~)])
     ::
     ++  sh-stir                                         ::  apply edit
+      ::x  called when typing into the talk prompt. applies the change and does
+      ::x  sanitizing.
+      ::
       |=  cal/sole-change
       ^+  +>
       =^  inv  say.she  (~(transceive sole say.she) cal)
@@ -950,23 +1108,34 @@
       (sh-slug fix)
     ::
     ++  sh-lame                                         ::  send error
+      ::x  just puts some text into the cli.
+      ::
       |=  txt/tape
       (sh-fact [%txt txt])
     ::
     ++  sh-whom                                         ::  current audience
+      ::x  produces the currently selected audience for this shell.
+      ::
       ^-  audience
       %-  ~(gas by *audience)
       %+  turn  (~(tap in u.active.she))
       |=(a/partner [a *envelope %pending])
     ::
     ++  sh-tell                                         ::  add command
+      ::x  adds talk command to core state. these get applied with ++sh-abet.
+      ::
       |=  cod/command
       %_(+> coz [cod coz])
     ::
     ++  sh-twig-head  ^-  vase                          ::  eval data
+      ::x  makes a vase of environment data to evaluate against (#-messages).
+      ::
       !>(`{our/@p now/@da eny/@uvI}`[our.hid now.hid (shas %eny eny.hid)])
     ::
     ++  sh-work                                         ::  do work
+      ::x  implements worker arms for different talk commands.
+      ::x  all worker arms must produce updated state/context.
+      ::
       |=  job/work
       ^+  +>
       =+  roy=(~(got by stories) man.she)
@@ -1037,6 +1206,7 @@
           =+  cha=(glyph (mug pan))
           (sh-note:(set-glyph cha pan) "new glyph {<cha>}")
         =+  loc=loc.system.she
+        ::x  change local mailbox config to include subscription to pan.
         %^  sh-tell  %design  man.she
         `loc(sources (~(uni in sources.loc) pan))
       ::
@@ -1044,6 +1214,7 @@
         |=  pan/(set partner)
         ^+  ..sh-work
         =+  loc=loc.system.she
+        ::x  change local mailbox config to exclude subscription to pan.
         %^  sh-tell  %design  man.she
         `loc(sources (~(dif in sources.loc) pan))
       ::
@@ -1104,6 +1275,7 @@
         ?:  (~(has in stories) nom) 
           (sh-lame "{(trip nom)}: already exists")
         =.  ..sh-work
+            ::x  create new config for channel.
             %^  sh-tell  %design  nom
             :-  ~
             :+  *(set partner)
@@ -1222,6 +1394,10 @@
       --
     ::
     ++  sh-done                                         ::  apply result
+      ::x  called upon hitting return in the prompt. if input is invalid,
+      ::x  ++sh-slug is called. otherwise, the appropriate work is done
+      ::x  and the entered command (if any) gets displayed to the user.
+      ::
       =+  fix=(sh-sane [%nop ~] buf.say.she)
       ?^  lit.fix
         (sh-slug fix)
@@ -1241,6 +1417,8 @@
       ==
     ::
     ++  sh-sole                                         ::  apply edit
+      ::x  applies sole action.
+      ::
       |=  act/sole-action
       ^+  +>
       ?-  -.act
@@ -1250,33 +1428,46 @@
       ==
     ::
     ++  sh-uniq
+      ::x  generates a new serial.
+      ::
       ^-  {serial _.}
       [(shaf %serial eny.hid) .(eny.hid (shax eny.hid))]
     --
   ++  ra-abed                                           ::  resolve core
+    ::x  produces the moves stored in ++ra's moves.
+    ::x  sole-effects get special treatment to become a single move.
+    ::
     ^+  [*(list move) +>]
     :_  +>
-    =+  ^=  yop  
+    ::x  seperate our sole-effects from other moves.
+    =+  ^=  yop
         |-  ^-  (pair (list move) (list sole-effect))
         ?~  moves  [~ ~]
         =+  mor=$(moves t.moves)
-        ?:  ?&  =(ost.hid p.i.moves) 
+        ?:  ?&  =(ost.hid p.i.moves)
                 ?=({$diff $sole-effect *} q.i.moves)
             ==
           [p.mor [+>.q.i.moves q.mor]]
         [[i.moves p.mor] q.mor]
+    ::x  flop moves, flop and squash sole-effects into a %mor.
     =+  :*  moz=(flop p.yop)
             ^=  foc  ^-  (unit sole-effect)
-            ?~  q.yop  ~ 
+            ?~  q.yop  ~
             ?~(t.q.yop `i.q.yop `[%mor (flop `(list sole-effect)`q.yop)])
         ==
+    ::x  produce moves or sole-effects and moves.
     ?~(foc moz [[ost.hid %diff %sole-effect u.foc] moz])
   ::
   ++  ra-abet                                           ::  complete core
+    ::x  applies talk reports, then produces moves and updated state.
+    ::
     ra-abed:ra-axel
   ::
   ++  ra-axel                                           ::  rebound reports
+    ::x  extracts and applies the talk-reports in moves.
+    ::
     ^+  .
+    ::x  separate our talk-reports from other moves.
     =+  ^=  rey
         |-  ^-  (pair (list move) (list (pair bone report)))
         ?~  moves
@@ -1287,20 +1478,26 @@
             ==
           [[i.moves p.mor] q.mor]
         [p.mor [[p.i.moves +>.q.i.moves] q.mor]]
+    ::x  update moves to exclude talk-reports.
     =.  moves  p.rey
     =.  q.rey  (flop q.rey)
     ?:  =(q.rey ~)  +
     |-  ^+  +>
     ?~  q.rey  ra-axel
+    ::x  apply reports.
     =+  bak=(ra-back(ost.hid p.i.q.rey) q.i.q.rey)
     $(q.rey t.q.rey, +> bak(ost.hid ost.hid))
   ::
   ++  ra-back
+    ::x  applies report.
+    ::
     |=  rad/report
     ^+  +>
     sh-abet:(~(sh-repo sh ~ (~(got by shells) ost.hid)) rad)
   ::
   ++  ra-sole
+    ::x  applies sole-action.
+    ::
     |=  act/sole-action
     ^+  +>
     =+  shu=(~(get by shells) ost.hid)
@@ -1311,19 +1508,29 @@
     sh-abet:(~(sh-sole sh ~ u.shu) act)
   ::  
   ++  ra-emil                                           ::  ra-emit move list
+    ::x  adds multiple moves to the core's list. flops to emulate ++ra-emit.
+    ::
     |=  mol/(list move)
     %_(+> moves (welp (flop mol) moves))
   ::
   ++  ra-emit                                           ::  emit a move
+    ::x  adds a move to the core's list.
+    ::
     |=  mov/move
     %_(+> moves [mov moves])
   ::
   ++  ra-evil                                           ::  emit error
+    ::x  stack trace and crash.
+    ::
     |=  msg/cord
     ~|  [%ra-evil msg]
     !!
   ::
   ++  ra-house                                          ::  emit partners
+    ::x  emits a talk-report move containing all our stories?
+    ::x?  this is for showing people what they can subscribe to, right?
+    ::x?  but this also shows invite-only stories, aren't they secret clubs?
+    ::
     |=  ost/bone
     %+  ra-emit  ost.hid
     :+  %diff  %talk-report
@@ -1333,6 +1540,8 @@
     |=({a/knot b/story} [a p.cordon.shape.b caption.shape.b])
   ::
   ++  ra-homes                                          ::  update partners
+    ::x  send a list of our stories to all general subscribers.
+    ::
     =+  gel=general
     |-  ^+  +>
     ?~  gel  +>
@@ -1341,6 +1550,8 @@
     (ra-house n.gel)
   ::
   ++  ra-init                                           ::  initialize talk
+    ::x  populate state on first boot. creates our main and public stories.
+    ::
     %+  roll
       ^-  (list {posture knot cord})
       :~  [%brown (main our.hid) 'default home']
@@ -1353,26 +1564,37 @@
     [des [typ ~]]
   ::
   ++  ra-apply                                          ::  apply command
+    ::x  applies the command sent by her.
+    ::
     |=  {her/ship cod/command}
     ^+  +>
     ?-    -.cod
+      ::x  the $design command is used for modifying channel configs,
+      ::x  which is done when joining, leaving or creating channels.
+      ::x  this may only be done by ourselves.
+      ::x?  shouldn't this be team-only too?
         $design
       ?.  =(her our.hid)
         (ra-evil %talk-no-owner)
       ?~  q.cod
         ?.  (~(has by stories) p.cod)
           (ra-evil %talk-no-story)
+        ::x?  why delete story if we got no config? can't we overwrite?
         (ra-config(stories (~(del by stories) p.cod)) p.cod *config)
       (ra-config p.cod u.q.cod)
     ::
+      ::x  used for relaying messages (as a station host).
         $review   (ra-think | her +.cod)
     ::
+      ::x  used for sending messages (as their author).
         $publish
       ?.  (team our.hid her)  +>.$
       (ra-think & her +.cod)
     ==
   ::
   ++  ra-config                                         ::  configure story
+    ::x  (re)configures story man. if it's a new story, emit our stories.
+    ::
     |=  {man/knot con/config}
     ^+  +>
     =+  :-  neu=(~(has by stories) man)
@@ -1380,9 +1602,16 @@
     =.  +>.$  pa-abet:(~(pa-reform pa man pur) con)
     ?:(neu +>.$ ra-homes)
   ::
-  ++  ra-base-hart  .^(hart %e /(scot %p our.hid)/host/(scot %da now.hid))
+  ++  ra-base-hart
+    ::x  produces our ship's host desk's web address as a hart.
+    ::
+    .^(hart %e /(scot %p our.hid)/host/(scot %da now.hid))
+  ::
   ++  ra-fora-post
+    ::x  sends a fora post. if we don't have a channel for posts yet, create one
+    ::
     |=  {pax/path sup/spur hed/@t txt/@t}
+    ::x  tell %hood to submit a fora post.
     =.  ..ra-emit
       %+  ra-emit  ost.hid
       :*  %poke
@@ -1391,22 +1620,28 @@
           [%write-fora-post sup src.hid hed txt]
       ==
     =+  man=%posts
+    ::x  if we have a %posts story, go ahead and consume.
     ?:  (~(has by stories) man)
       (ra-consume-fora-post man pax hed txt)
+    ::x  if we have no %posts story, first create it, then consume.
     =;  new  (ra-consume-fora-post:new man pax hed txt)
     =.  ..ra-apply
       %+  ra-apply  our.hid
       :+  %design  man
-      :-  ~  :-  ~
-      :-  'towards a community'
-      [%brown ~] 
+      :-  ~  :-  ~               ::x  sources
+      :-  'towards a community'  ::x  caption
+      [%brown ~]                 ::x  cordon
+    ::x  send informative message to our mailbox.
     %^  ra-consume  &  our.hid
-    :^    (shaf %init eny.hid)  
-        (my [[%& our.hid (main our.hid)] *envelope %pending] ~)
+    :^    (shaf %init eny.hid)  ::x  serial
+        (my [[%& our.hid (main our.hid)] *envelope %pending] ~)  ::x  audience
+    ::x  statement
       now.hid
     [~ %app %tree 'receiving forum posts, ;join %posts for details']
   ::
   ++  ra-consume-fora-post
+    ::x  add a message for a fora post to the man story.
+    ::
     |=  {man/knot pax/path hed/@t txt/@t}  ^+  +>
     =.  pax  (welp pax /posts/(crip "{<now.hid>}~"))
     %^  ra-consume  |
@@ -1422,6 +1657,8 @@
     ==
   ::
   ++  ra-comment
+    ::x  sends a comment. if we don't have a channel for them yet, creates one.
+    ::
     |=  {pax/path sup/spur txt/@t}
     =.  ..ra-emit
       %+  ra-emit  ost.hid
@@ -1447,6 +1684,8 @@
     [~ %app %tree 'receiving comments, ;join %comments for details']
   ::
   ++  ra-consume-comment
+    ::x  adds a message for a comment to the man story.
+    ::
     |=  {man/knot pax/path sup/spur txt/@t}  ^+  +>
     =+  nam=?~(sup "" (trip i.sup))                     :: file name
     =+  fra=(crip (time-to-id now.hid))                 :: url fragment
@@ -1463,6 +1702,9 @@
     ==
   ::
   ++  ra-know                                           ::  story monad
+    ::x  produces a wet core that takes a gate that takes a story core and
+    ::x  produces updated state.
+    ::
     |=  man/knot
     |*  fun/$-(_pa _+>)
     ^+  +>+>
@@ -1470,28 +1712,40 @@
     ?~  pur
       ~&  [%ra-know-not man]                            ::  XX should crash
       +>+>.$
+    ::x  call the sample gate with a ++pa core.
     (fun ~(. pa man u.pur))
   ::
   ++  ra-diff-talk-report                               ::  subscription update
+    ::x  process a talk report from cuz into story man.
+    ::
     |=  {man/knot cuz/station rad/report}
     %-  (ra-know man)  |=  par/_pa  =<  pa-abet
     (pa-diff-talk-report:par cuz rad)
   ::
   ++  ra-quit                                           ::  subscription quit
+    ::x  removes cuz from the subscribers of story man.
+    ::
     |=  {man/knot cuz/station}
     %-  (ra-know man)  |=  par/_pa  =<  pa-abet
     (pa-quit:par %& cuz)
   ::
   ++  ra-retry                                          ::  subscription resend
+    ::x  produce a %peer/subscribe move for cuz to story man.
+    ::
     |=  {man/knot cuz/station}
     %-  (ra-know man)  |=  par/_pa  =<  pa-abet
     (pa-acquire:par [%& cuz]~)
   ::
   ++  ra-coup-repeat                                    ::
+    ::x  assemble partner and call ++ra-repeat.
+    ::
     |=  {{num/@ud her/@p man/knot} saw/(unit tang)}
     (ra-repeat num [%& her man] saw)
   ::
-  ++  ra-repeat                                         ::  remove from outbox 
+  ++  ra-repeat                                         ::  remove from outbox
+    ::x  take message out of outbox, mark it as received or rejected.
+    ::x  crashes if pan is not in message's audience.
+    ::
     |=  {num/@ud pan/partner saw/(unit tang)}
     =+  oot=(~(get by q.outbox) num)
     ?~  oot  ~|([%ra-repeat-none num] !!)
@@ -1506,14 +1760,20 @@
     (ra-think | our.hid u.oot ~)
   ::
   ++  ra-cancel                                         ::  drop a bone
+    ::x  removes a bone from the story in pax.
+    ::
     |=  {src/ship pax/path}
     ^+  +>
     ?.  ?=({@ @ *} pax)
+      ::x  if story is not in path, just delete the bone from general.
       +>(general (~(del in general) ost.hid))
     %-  (ra-know i.t.pax)  |=  par/_pa  =<  pa-abet
+    ::x  delete bone from all follower groups and set src's status to %gone.
     (pa-notify:pa-cancel:par src %gone *human)
   ::
   ++  ra-human                                          ::  look up person
+    ::x  get her identity. if she has none, make her one.
+    ::
     |=  her/ship
     ^-  {human _+>}
     =^  who  folks
@@ -1524,8 +1784,11 @@
     [who +>.$]
   ::
   ++  ra-console                                        ::  console subscribe
+    ::x  make a shell for her, subscribe her to it.
+    ::
     |=  {her/ship pax/path}
     ^+  +>
+    ::x  get story from the path, default to standard mailbox.
     =/  man/knot
       ?+  pax  !!
         $~        (main her)
@@ -1536,9 +1799,12 @@
     sh-abet:~(sh-peer sh ~ `shell`she)
   ::
   ++  ra-subscribe                                      ::  listen to
+    ::x  subscribe her at pax.
+    ::
     |=  {her/ship pax/path}
     ^+  +>
     ::  ~&  [%ra-subscribe ost.hid her pax]
+    ::x  empty path, meta-subscribe and send report with all our stories.
     ?:  ?=($~ pax)
       (ra-house(general (~(put in general) ost.hid)) ost.hid)
     ?.  ?=({@ @ *} pax)
@@ -1549,23 +1815,31 @@
       ~&  [%bad-subscribe-story-c i.t.pax]
       (ra-evil %talk-no-story)
     =+  soy=~(. pa i.t.pax u.pur)
+    ::x  check her read permissions.
     ?.  (pa-visible:soy her)
       (ra-evil %talk-no-story)
     =^  who  +>.$  (ra-human her)
+    ::x  for each stream type she is interested in, add her to the followers.
     =.  soy  ?.((~(has in vab) %a-group) soy (pa-watch-group:soy her))
     =.  soy  ?.((~(has in vab) %v-glyph) soy (pa-watch-glyph:soy her))
     =.  soy  ?.((~(has in vab) %x-cabal) soy (pa-watch-cabal:soy her))
     =.  soy  ?.((~(has in vab) %f-grams) soy (pa-watch-grams:soy her t.t.pax))
+    ::x  add her status to presence map.
     =.  soy  (pa-notify:soy her %hear who)
+    ::x  apply changes to story.
     pa-abet:soy
   ::
   ++  ra-think                                          ::  publish+review
+    ::x  consumes each thought.
+    ::
     |=  {pub/? her/ship tiz/(list thought)}
     ^+  +>
     ?~  tiz  +>
     $(tiz t.tiz, +> (ra-consume pub her i.tiz))
   ::
   ++  ra-normal                                         ::  normalize
+    ::x  sanitize %lin speech, enforce lowercase and no special characters.
+    ::
     |=  tip/thought
     ^-  thought
     ?.  ?=({$lin *} r.r.tip)  tip
@@ -1584,14 +1858,19 @@
     ==
   ::
   ++  ra-consume                                        ::  consume thought
+    ::x  if pub is true, sends the thought to each partner in the audience.
+    ::x  if false, updates the thought in our store.
+    ::
     |=  {pub/? her/ship tip/thought}
     =.  tip  (ra-normal tip)
-    =+  aud=(~(tap by q.tip) ~)
+    =+  aud=(~(tap by q.tip) ~)  ::x  why ~ ?
     |-  ^+  +>.^$
     ?~  aud  +>.^$
     $(aud t.aud, +>.^$ (ra-conduct pub her p.i.aud tip))
   ::
   ++  ra-conduct                                        ::  thought to partner
+    ::x  record a message or sends it.
+    ::
     |=  {pub/? her/ship tay/partner tip/thought}
     ^+  +>
     ::  ~&  [%ra-conduct pub her tay]
@@ -1608,11 +1887,15 @@
     ==
   ::
   ++  ra-record                                         ::  add to story
+    ::x  add or update a telegram in story man.
+    ::
     |=  {man/knot gam/telegram}
     %-  (ra-know man)  |=  par/_pa  =<  pa-abet
     (pa-learn:par gam)
   ::
   ++  ra-transmit                                       ::  send to neighbor
+    ::x  sends a thought to a station, adds it to the outbox.
+    ::
     |=  {cuz/station tip/thought}
     ^+  +>
     =.  +>
@@ -1625,14 +1908,28 @@
     +>(p.outbox +(p.outbox), q.outbox (~(put by q.outbox) p.outbox tip))
   ::
   ++  pa                                                ::  story core
-    |_  $:  man/knot
+    ::x  story core, used for doing work on a story.
+    ::x  as always, an -abet arms is used for applying changes to the state.
+    ::x  ++pa-watch- arms get called by ++ra-subscribe to add a subscriber.
+    ::x  bones are used to identify subscribers (source event identifiers)
+    ::
+    |_  ::x  man: the knot identifying the story in stories.
+        ::x  story doesn't get a face because ease of use
+        ::
+        $:  man/knot
             story
         ==
     ++  pa-abet
+      ::x  apply/fold changes back into the stories map.
+      ::
       ^+  +>
       +>(stories (~(put by stories) man `story`+<+))
     ::
     ++  pa-admire                                       ::  accept from
+      ::x  should be checking her write permissions, but defaults to allowed.
+      ::x  commented code seems to use an older control structure.
+      ::x?  this seems like an easy fix, why was this ever disabled?
+      ::
       |=  her/ship
       ^-  ?
       ::?-  -.cordon.shape
@@ -1642,16 +1939,20 @@
       &
     ::
     ++  pa-visible                                      ::  display to
+      ::x  checks her read permissions.
+      ::
       |=  her/ship
       ^-  ?
       ?-  p.cordon.shape
-        $black  &
-        $green  &
-        $brown  (team our.hid her)
-        $white  (~(has in q.cordon.shape) her)
+        $black  &                                       ::x  channel, all
+        $green  &                                       ::x  journal, all
+        $brown  (team our.hid her)                      ::x  mailbox, our
+        $white  (~(has in q.cordon.shape) her)          ::x  village, invite
       ==
     ::
     ++  pa-report                                       ::  update
+      ::x  sends report to all bones.
+      ::
       |=  {wac/(set bone) caw/report}
       ::  ~&  [%pa-report man -.caw]
       ^+  +>
@@ -1662,6 +1963,9 @@
       (pa-sauce n.wac [%diff %talk-report caw]~)
     ::
     ++  pa-watch-group                                  ::  subscribe presence
+      ::x  if she may, add her bone to presence followers and send her a group
+      ::x  (presence) report.
+      ::
       |=  her/ship
       ?.  (pa-admire her)
         (pa-sauce ost.hid [%quit ~]~)
@@ -1669,6 +1973,9 @@
       (pa-report-group ost.hid ~ ~)
     ::
     ++  pa-watch-cabal                                  ::  subscribe config
+      ::x  if she may, add her bone to config followers and send her an updated
+      ::x  cabal (config) report.
+      ::
       |=  her/ship
       ?.  (pa-admire her)
         ~&  [%pa-admire-not her]
@@ -1678,6 +1985,9 @@
       (pa-sauce ost.hid [[%diff %talk-report %cabal shape mirrors] ~])
     ::
     ++  pa-watch-glyph                                  ::  subscribe config
+      ::x  if she may, add her bone to glyph followers and send an updated glyph
+      ::x  report.
+      ::
       |=  her/ship
       ?.  (pa-admire her)
         ~&  [%pa-admire-not her]
@@ -1686,6 +1996,10 @@
       (pa-report [ost.hid ~ ~] %glyph nak)
     ::
     ++  pa-report-group                                  ::  update presence
+      ::x  build a group report, containing our different presence maps, and
+      ::x  send it to all bones.
+      ::x?  why should we be responsible for sending remotes presences?
+      ::
       |=  vew/(set bone)
       %^  pa-report  vew  %group
       :-  %-  ~(run by locals)
@@ -1699,9 +2013,15 @@
       |=({@ a/status} a)
     ::
     ++  pa-report-cabal                                 ::  update config
+      ::x  a cabal report, containing our and remote configs, to all config
+      ::x  followers.
+      ::
       (pa-report cabalers %cabal shape mirrors)
     ::
     ++  pa-cabal
+      ::x  add station's config to our remote config map.
+      ::x?  ham is unused, not even when calling this.
+      ::
       |=  {cuz/station con/config ham/(map station config)}
       ^+  +>
       =+  old=mirrors
@@ -1711,8 +2031,11 @@
       pa-report-cabal 
     ::
     ++  pa-diff-talk-report                             ::  subscribed update
+      ::x  process a talk report from cuz.
+      ::
       |=  {cuz/station rad/report}
       ^+  +>
+      ::x  verify we are supposed to receive reports from cuz.
       ?.  (~(has in sources.shape) [%& cuz])
         ~&  [%pa-diff-unexpected cuz rad]
         +>
@@ -1723,10 +2046,14 @@
       ==
     ::
     ++  pa-quit                                         ::  stop subscription
+      ::x  delete tay from our subscriptions, then send an updated capal report.
+      ::
       |=  tay/partner
       pa-report-cabal(sources.shape (~(del in sources.shape) tay))
     ::
     ++  pa-sauce                                        ::  send backward
+      ::x  turns cards into moves, reverse order, prepend to existing moves.
+      ::
       |=  {ost/bone cub/(list card)}
       %_    +>.$
           moves
@@ -1734,8 +2061,10 @@
       ==
     ::
     ++  pa-abjure                                       ::  unsubscribe move
+      ::x  for each partner, produce a %pull/unsubscribe move.
+      ::
       |=  tal/(list partner)
-      %+  pa-sauce  0
+      %+  pa-sauce  0  ::x  why bone 0?
       %-  zing
       %+  turn  tal
       |=  tay/partner
@@ -1754,6 +2083,8 @@
       ==
     ::
     ++  pa-acquire                                      ::  subscribe to
+      ::x  for each partner, produce a %peer/subscribe move.
+      ::
       |=  tal/(list partner)
       %+  pa-sauce  0
       %-  zing
@@ -1762,6 +2093,8 @@
       ^-  (list card)
       =+  num=(~(get by sequence) tay)
       =+  old=(sub now.hid ~d1)                         :: XX full backlog
+      ::x  subscribe starting at the last message we read,
+      ::x  or if we haven't read any yet, messages from up to a day ago.
       =+  ini=?^(num (scot %ud u.num) (scot %da old))
       =/  typ
         =+  (ly ~[%a-group %f-grams %x-cabal])
@@ -1778,6 +2111,9 @@
       ==
     ::
     ++  pa-reform                                       ::  reconfigure, ugly
+      ::x  change config of current story, subscribe/unsubscribe to/from the
+      ::x  partners we gained/lost, and send out an updated cabal report.
+      ::
       |=  cof/config
       =+  ^=  dif  ^-  (pair (list partner) (list partner))
           =+  old=`(list partner)`(~(tap in sources.shape) ~)
@@ -1790,6 +2126,8 @@
       pa-report-cabal
     ::
     ++  pa-cancel                                       ::  unsubscribe from
+      ::x  deletes the current ost.hid from all follower groups.
+      ::
       ::  ~&  [%pa-cancel ost.hid]
       %_  .
         gramsers  (~(del by gramsers) ost.hid)
@@ -1799,6 +2137,8 @@
       ==
     ::
     ++  pa-notify                                       ::  local presence
+      ::x  add her status to our presence map. if this changes it, send report.
+      ::
       |=  {her/ship saz/status}
       ^+  +>
       =/  nol  (~(put by locals) her now.hid saz)
@@ -1806,7 +2146,11 @@
       (pa-report-group(locals nol) groupers)
     ::
     ++  pa-remind                                       ::  remote presence
+      ::x  adds tay's loc to our remote presence map, after merging with rem.
+      ::x  if this changes anything, send update report.
+      ::
       |=  {tay/partner loc/atlas rem/(map partner atlas)}
+      ::x  remove this story from the presence map, since it's in local already.
       =.  rem  (~(del by rem) %& our.hid man)  :: superceded by local data
       =/  buk  (~(uni timed remotes) rem)  ::  XX drop?
       =.  buk  (~(put timed buk) tay now.hid loc)
@@ -1814,12 +2158,15 @@
       (pa-report-group(remotes buk) groupers)
     ::
     ++  pa-start                                        ::  start stream
+      ::x  grab all telegrams that fall within the river and send them in a
+      ::x  grams report to ost.hid.
+      ::
       |=  riv/river
       ^+  +>
       =-  ::  ~&  [%pa-start riv lab]
           =.  +>.$
           (pa-sauce ost.hid [[%diff %talk-report %grams q.lab r.lab] ~])
-          ?:  p.lab
+          ?:  p.lab  ::x?  dun never gets changed, so always | ?
             (pa-sauce ost.hid [[%quit ~] ~])
           +>.$(gramsers (~(put by gramsers) ost.hid riv))
       ^=  lab
@@ -1830,22 +2177,29 @@
             $ud  (lte p.q.riv end)
             $da  (lte p.q.riv p.r.q.i.gaz)
           ==
+        ::x  if we're past the river, continue browsing back.
         $(end (dec end), gaz t.gaz)
       ?:  ?-  -.p.riv                                   ::  before the start
             $ud  (lth end p.p.riv)
             $da  (lth p.r.q.i.gaz p.p.riv)
           ==
+        ::x  if we're before the river, we're done.
         [dun end zeg]
+      ::x  if we're in the river, add this gram and continue.
       $(end (dec end), gaz t.gaz, zeg [i.gaz zeg])
     ::
     ++  pa-watch-grams                                  ::  subscribe messages
+      ::x  (called upon subscribe) send backlog of grams to her.
+      ::x  deduces which messages to send from pax.
+      ::
       |=  {her/ship pax/path}
       ^+  +>
       ?.  (pa-admire her)
         ~&  [%pa-watch-grams-admire ~]
         (pa-sauce ost.hid [%quit ~]~)
+      ::x  find the range of grams to send.
       =+  ^=  ruv  ^-  (unit river)
-          %+  biff
+          %+  biff  ::x  collapse unit list.
             (zl:jo (turn pax ;~(biff slay |=(a/coin `(unit dime)`?~(-.a a ~)))))
           |=  paf/(list dime)
           ?~  paf
@@ -1854,6 +2208,7 @@
             $(t.paf [%da (dec (bex 128))]~)
           ?.  ?=({{?($ud $da) @} {?($ud $da) @} $~} paf)
             ~
+          ::x?  the switches, they do nothing!
           `[[?+(- . $ud .)]:i.paf [?+(- . $ud .)]:i.t.paf]  ::  XX types
       ::  ~&  [%pa-watch-grams her pax ruv]
       ?~  ruv
@@ -1862,6 +2217,10 @@
       (pa-start u.ruv)
     ::
     ++  pa-refresh                                      ::  update to listeners
+      ::x  called when grams get added or changed. calculates the changes and
+      ::x  sends them to all message followers. if we run into any followers
+      ::x  that are no longer interested in this story, remove them.
+      ::
       |=  {num/@ud gam/telegram}
       ^+  +>
       =+  ^=  moy
@@ -1889,33 +2248,43 @@
       $(p.moy t.p.moy, gramsers (~(del by gramsers) i.p.moy))
     ::
     ++  pa-lesson                                       ::  learn multiple
+      ::x  learn all telegrams in a list.
+      ::
       |=  gaz/(list telegram)
       ^+  +>
       ?~  gaz  +>
       $(gaz t.gaz, +> (pa-learn i.gaz))
     ::
     ++  pa-learn                                        ::  learn message
+      ::x  store an incoming telegram, modifying audience to say we received it.
+      ::x  update existing telegram if it already exists.
+      ::
       |=  gam/telegram
       ^+  +>
+      ::x  if author isn't allowed to write here, reject.
       ?.  (pa-admire p.gam)
         ~&  %pa-admire-rejected
         +>.$
-      =.  q.q.gam  
+      =.  q.q.gam
+        ::x  if we are in the audience, mark us as having received it.
         =+  ole=(~(get by q.q.gam) [%& our.hid man])
         ?^  ole  (~(put by q.q.gam) [%& our.hid man] -.u.ole %received)
         ::  for fedearted stations, pretend station src/foo is also our/foo
         ::  XX pass src through explicitly instead of relying on implicit
-        ::     value in hid from the subscription to src/foo 
+        ::     value in hid from the subscription to src/foo
         =+  ole=(~(get by q.q.gam) [%& src.hid man])
         ?~  ole  q.q.gam
+        ::x  as described above, fake src into our.
         =.  q.q.gam  (~(del by q.q.gam) [%& src.hid man])
         (~(put by q.q.gam) [%& our.hid man] -.u.ole %received)
       =+  old=(~(get by known) p.q.gam)
       ?~  old
-        (pa-append gam)
-      (pa-revise u.old gam)
+        (pa-append gam)      ::x  add
+      (pa-revise u.old gam)  ::x  modify
     ::
     ++  pa-append                                       ::  append new
+      ::x  add gram to our story, and update our subscribers.
+      ::
       |=  gam/telegram
       ^+  +>
       %+  %=  pa-refresh
@@ -1927,6 +2296,8 @@
       gam
     ::
     ++  pa-revise                                       ::  revise existing
+      ::x  modify a gram in our story, and update our subscribers.
+      ::
       |=  {num/@ud gam/telegram}
       =+  way=(sub count num)
       ?:  =(gam (snag (dec way) grams))
@@ -1937,30 +2308,50 @@
   --
 ::
 ++  sn                                                  ::  station render core
+  ::x  used in both station and ship rendering.
+  ::
+  ::x  man: mailbox.
+  ::x  one: the station.
   |_  {man/knot one/station} 
   ++  sn-best                                           ::  best to show
+    ::x  returns true if one is better to show, false otherwise.
+    ::x  prioritizes: our > main > size.
+    ::
     |=  two/station
     ^-  ?
+    ::x  the station that's ours is better.
     ?:  =(our.hid p.one)
       ?:  =(our.hid p.two)
         ?<  =(q.one q.two)
+        ::x  if both stations are ours, the main story is better.
         ?:  =((main p.one) q.one)  %&
         ?:  =((main p.two) q.two)  %|
+        ::x  if neither are, pick the "larger" one.
         (lth q.one q.two)
       %&
+    ::x  if one isn't ours but two is, two is better.
     ?:  =(our.hid p.two)
       %|
     ?:  =(p.one p.two)
+      ::x  if they're from the same ship, pick the "larger" one.
       (lth q.one q.two)
+    ::x  when in doubt, pick one if its ship is "smaller" than its channel.
+    ::x?  i guess you want this to be consistent across (a b) and (b a), but
+    ::x  this still seems pretty arbitrary.
     (lth p.one q.one)
   ::
   ++  sn-curt                                           ::  render name in 14
+    ::x  prints a ship name in 14 characters. left-pads with spaces.
+    ::x?  mup is unused, what is it even for? ++ta-show still uses it.
+    ::
     |=  mup/?
     ^-  tape
     =+  raw=(cite p.one)
     (runt [(sub 14 (lent raw)) ' '] raw)
   ::
   ++  sn-nick
+    ::x  get nick for ship, or shortname if no nick. left-pads with spaces.
+    ::
     |.  ^-  tape
     =+  nym=(~(get by folks) p.one)
     ?~  nym
@@ -1972,6 +2363,10 @@
     (weld (reap len ' ') raw)
   ::
   ++  sn-phat                                           ::  render accurately
+    ::x  prints a station fully, but still taking "shortcuts" where possible:
+    ::x  ":" for local mailbox, "~ship" for foreign mailbox,
+    ::x  "%channel" for local station, "/channel" for parent station.
+    ::
     ^-  tape
     ?:  =(p.one our.hid)
       ?:  =(q.one man)
@@ -1986,8 +2381,16 @@
   --
 ::
 ++  ta                                                  ::  partner core
+  ::x  used primarily for printing partners.
+  ::
+  ::x  man: mailbox.
+  ::x  one: the partner.
   |_  {man/knot one/partner}
   ++  ta-beat                                           ::  more relevant
+    ::x  returns true if one is better to show, false otherwise.
+    ::x  prefers stations over passports. if both are stations, sn-best. if both
+    ::x  are passports, pick the "larger" one, if they're equal, content hash.
+    ::
     |=  two/partner  ^-  ?
     ?-    -.one
         $&
@@ -2004,14 +2407,19 @@
             (lth -.p.two -.p.one)
       ==
     ==
-  ++  ta-best                                           ::  most relevant 
+  ++  ta-best                                           ::  most relevant
+    ::x  picks the most relevant partner.
+    ::
     |=(two/partner ?:((ta-beat two) two one))
   ::
   ++  ta-full  (ta-show ~)                              ::  render full width
   ++  ta-show                                           ::  render partner
+    ::x  renders a partner as text.
+    ::
     |=  moy/(unit ?)
     ^-  tape
     ?-    -.one
+    ::x render station as glyph if we can.
         $&
       ?~  moy
         =+  cha=(~(get by nik) one ~ ~)
@@ -2019,6 +2427,7 @@
         ~(sn-phat sn man p.one)
       (~(sn-curt sn man p.one) u.moy)
     ::
+    ::x  render passport.
         $|
       =+  ^=  pre  ^-  tape
           ?-  -.p.one
@@ -2032,8 +2441,14 @@
   --
 ::
 ++  te                                                  ::  audience renderer
+  ::x  used for representing audiences (sets of partners) as tapes.
+  ::
+  ::  man: mailbox.
+  ::  lix: members of the audience.
   |_  {man/knot lix/(set partner)}
   ++  te-best  ^-  (unit partner)
+    ::x  pick the most relevant partner.
+    ::
     ?~  lix  ~
     :-  ~
     |-  ^-  partner
@@ -2044,13 +2459,19 @@
     n.lix
   ::
   ++  te-deaf  ^+  .                                    ::  except for self
+    ::x  remove ourselves from the audience.
+    ::
     .(lix (~(del in lix) `partner`[%& our.hid man]))
   ::
   ++  te-maud  ^-  ?                                    ::  multiple audience
+    ::x  checks if there's multiple partners in the audience via pattern match.
+    ::
     =.  .  te-deaf
     !?=($@($~ {* $~ $~}) lix)
   ::
   ++  te-prom  ^-  tape                                 ::  render targets
+    ::x  render all partners, ordered by relevance.
+    ::
     =.  .  te-deaf
     =+  ^=  all
         %+  sort  `(list partner)`(~(tap in lix))
@@ -2066,9 +2487,13 @@
     ==
   ::
   ++  te-whom                                           ::  render sender
+    ::x  render sender as the most relevant partner.
+    ::
     (~(ta-show ta man (need te-best)) ~ te-maud)
   ::
   ++  ta-dire                                           ::  direct message
+    ::x  returns true if partner is a mailbox of ours.
+    ::
     |=  pan/partner  ^-  ?
     ?&  ?=($& -.pan)
         =(p.p.pan our.hid)
@@ -2078,6 +2503,9 @@
     ==
   ::
   ++  te-pref                                           ::  audience glyph
+    ::x  get the glyph that corresponds to the audience, with a space appended.
+    ::x  if it's a dm to us, use :. if it's a dm by us, use ;. complex, use *.
+    ::
     ^-  tape
     =+  cha=(~(get by nik) lix)
     ?^  cha  ~[u.cha ' ']
@@ -2089,7 +2517,22 @@
   --
 ::
 ++  tr                                                  ::  telegram renderer
-  |_  $:  man/knot
+  ::x  responsible for converting telegrams and everything relating to them to
+  ::x  text to be displayed in the cli.
+  ::
+  |_  $:  ::x  man: story.
+          ::x  sef: settings flags.
+          ::x  telegram:
+          ::x   who: author.
+          ::x   thought:
+          ::x    sen: unique identifier.
+          ::x    aud: audience.
+          ::x    statement:
+          ::x     wen: timestamp.
+          ::x     bou: complete aroma.
+          ::x     sep: message contents.
+          ::
+          man/knot
           sef/(set knot)
           who/ship
           sen/serial
@@ -2099,9 +2542,14 @@
           sep/speech
       ==
   ++  tr-fact  ^-  sole-effect                          ::  activate effect
+    ::x  produce sole-effect for printing message details.
+    ::
     ~[%mor [%tan tr-meta] tr-body]
   ::
   ++  tr-line  ^-  tape                                 ::  one-line print
+    ::x  crams a telegram into a single line by displaying a short ship name,
+    ::x  a short representation of the gram, and an optional timestamp.
+    ::
     =+  txt=(tr-text =(who our.hid))
     ?:  =(~ txt)  ""
     =+  ^=  baw
@@ -2122,6 +2570,9 @@
     (weld baw txt)
   ::
   ++  tr-meta  ^-  tang
+    ::x  build strings that display metadata, including message serial,
+    ::x  timestamp, author and audience.
+    ::
     =.  wen  (sub wen (mod wen (div wen ~s0..0001)))     :: round
     =+  hed=leaf+"{(scow %uv sen)} at {(scow %da wen)}"
     =+  =<  paz=(turn (~(tap by aud)) .)
@@ -2130,6 +2581,8 @@
     [%rose [" " ~ ~] [hed >who< [%rose [", " "to " ~] paz] bok]]~
   ::
   ++  tr-body
+    ::x  long-form display of message contents, specific to each speech type.
+    ::
     |-  ^-  sole-effect
     ?+  -.sep  tan+[>sep<]~
       $exp  tan+~[leaf+"# {(trip p.sep)}"]
@@ -2151,6 +2604,8 @@
     ==
   ::
   ++  tr-rend-tors
+    ::x  render an attachment.
+    ::
     |=  a/torso  ^-  tang
     ?-  -.a
       $name  (welp $(a q.a) leaf+"={(trip p.a)}" ~)
@@ -2159,11 +2614,16 @@
     ==
   ::
   ++  tr-pals
+    ::x  strip delivery info from audience, producing a set of partners.
+    ::
     ^-  (set partner)
     %-  ~(gas in *(set partner))
     (turn (~(tap by aud)) |=({a/partner *} a))
   ::
   ++  tr-chow
+    ::x  truncate the txt to be of max len characters. if it does truncate,
+    ::x  indicates it did so by appending a character.
+    ::
     |=  {len/@u txt/tape}  ^-  tape
     ?:  (gth len (lent txt))  txt
     =.  txt  (scag len txt)
@@ -2175,12 +2635,16 @@
     [i.txt $(txt t.txt)]
   ::
   ++  tr-both
+    ::x  try to fit two tapes into a single line.
+    ::
     |=  {a/tape b/tape}  ^-  tape
     ?:  (gth (lent a) 62)  (tr-chow 64 a)
     %+  weld  a
     (tr-chow (sub 64 (lent a)) "  {b}")
   ::
   ++  tr-text
+    ::x  gets a tape representation of a message that fits within a single line.
+    ::
     |=  oug/?
     ^-  tape
     ?+    -.sep  ~&(tr-lost+sep "")
@@ -2225,6 +2689,8 @@
   -- 
 ::
 ++  peer                                                ::  accept subscription
+  ::x  incoming subscription on pax.
+  ::
   |=  pax/path
   ^+  [*(list move) +>]
   ~?  !=(src.hid our.hid)  [%peer-talk-stranger src.hid]
@@ -2237,6 +2703,8 @@
   ra-abet:(ra-subscribe:ra src.hid pax)
 ::
 ++  poke-talk-command                                   ::  accept command
+  ::x  incoming talk command. process it and update logs.
+  ::
   |=  cod/command
   ^+  [*(list move) +>]
   ::  ~&  [%talk-poke-command src.hid cod]
@@ -2246,10 +2714,14 @@
   [(welp mos mow) +>.$]
 ::
 ++  poke-sole-action                                    ::  accept console
+  ::x  incoming sole action. process it.
+  ::
   |=  act/sole-action
   ra-abet:(ra-sole:ra act)
 ::
 ++  diff-talk-report                                    ::
+  ::x  incoming talk-report. process it and update logs.
+  ::
   |=  {way/wire rad/report}
   ^-  (quip move +>)
   =^  mos  +>.$
@@ -2259,11 +2731,16 @@
   [(welp mos mow) +>.$]
 ::
 ++  coup-repeat                                         ::
+  ::x  ack from ++ra-transmit. mark the message as received or rejected.
+  ::
   |=  {way/wire saw/(unit tang)}
   %+  etch-repeat  [%repeat way]  |=  {num/@ud src/@p man/knot}
   ra-abet:(ra-coup-repeat:ra [num src man] saw)
 ::
 ++  etch                                                ::  parse wire
+  ::x  parse wire to obtain either %friend with story and station or %repeat
+  ::x  with message number, source ship and story.
+  ::
   |=  way/wire
   ^-  weir
   ?+    -.way  !!
@@ -2277,16 +2754,22 @@
   ==
 ::
 ++  etch-friend                                         ::
+  ::x  parse a /friend wire, call gate with resulting data.
+  ::
   |=  {way/wire fun/$-({man/knot cuz/station} {(list move) _.})}
   =+  wer=(etch way)
   ?>(?=($friend -.wer) (fun p.wer q.wer))
 ::
 ++  etch-repeat                                         ::
+  ::x  parse a /repeat wire, call gate with resulting data.
+  ::
   |=  {way/wire fun/$-({num/@ud src/@p man/knot} {(list move) _.})}
   =+  wer=(etch way)
   ?>(?=($repeat -.wer) (fun p.wer q.wer r.wer))
 ::
 ++  reap-friend                                         ::
+  ::x  subscription n/ack. if it failed, remove their subscription from state.
+  ::
   |=  {way/wire saw/(unit tang)}
   ^-  (quip move +>)
   ?~  saw  [~ +>]
@@ -2296,11 +2779,15 @@
   ra-abet:(ra-quit:ra man cuz)
 ::
 ++  quit-friend                                         ::
+  ::x  resubscribe.
+  ::
   |=  way/wire
   %+  etch-friend  [%friend way]  |=  {man/knot cuz/station}
   ra-abet:(ra-retry:ra man cuz)
 ::
 ++  pull                                                ::
+  ::x  unsubscribe. remove from story and shells.
+  ::
   |=  pax/path
   ^+  [*(list move) +>]
   ::  ~&  [%talk-pull src.hid ost.hid pax]
@@ -2308,6 +2795,9 @@
   [moz +>.$(shells (~(del by shells) ost.hid))]
 ::
 ++  log-all-to-file
+  ::x  for every story we're logging, (over)write all their grams to log files,
+  ::x  if new ones have arrived.
+  ::
   ^-  (quip move .)
   ?:  &  [~ .]  ::  XXX!!!!
   :_  %_  .
@@ -2322,6 +2812,8 @@
   `(log-to-file man)
 ::
 ++  log-to-file
+  ::x  log all grams of story man to a file.
+  ::
   |=  man/knot
   ^-  move
   =+  ^-  paf/path
@@ -2332,14 +2824,20 @@
   [ost.hid %info /jamfile our.hid (foal paf [%talk-telegrams !>(-)])]
 ::
 ++  poke-talk-comment
+  ::x  send a comment.
+  ::
   |=  {pax/path sup/spur txt/@t}  ^-  (quip move +>)
   ra-abet:(ra-comment:ra pax sup txt)
 ::
 ++  poke-talk-fora-post
+  ::x  send a fora post.
+  ::
   |=  {pax/path sup/spur hed/@t txt/@t}  ^-  (quip move +>)
   ra-abet:(ra-fora-post:ra pax sup hed txt)
 ::
 ++  poke-talk-save
+  ::x  store the talk telegrams of story man in a log file.
+  ::
   |=  man/knot
   ^-  (quip move +>)
   =+  paf=/(scot %p our.hid)/home/(scot %da now.hid)/talk/[man]/talk-telegrams
@@ -2347,6 +2845,8 @@
   [[ost.hid %info /jamfile our.hid (foal paf [%talk-telegrams !>(-)])]~ +>.$]
 ::
 ++  poke-talk-load
+  ::x  load/update the story man into our state, as saved in ++poke-talk-save.
+  ::
   |=  man/knot
   =+  ^=  grams
       .^  (list telegram)
@@ -2357,6 +2857,8 @@
   [~ +>.$(stories (~(put by stories) man toy(grams grams, count (lent grams))))]
 ::
 ++  poke-talk-log
+  ::x  start logging story man.
+  ::
   |=  man/knot
   ~&  %poke-log
   ^-  (quip move +>)
@@ -2364,12 +2866,16 @@
   +>.$(log (~(put by log) man count:(~(got by stories) man)))
 ::
 ++  poke-talk-unlog
+  ::x  stop logging story man.
+  ::
   |=  man/knot
   ^-  (quip move +>)
   :-  ~
   +>.$(log (~(del by log) man))
 ::
 ++  prep
+  ::x  state adapter.
+  ::
   |=  old/(unit house-any)
   ^-  (quip move ..prep)
   ?~  old