Update README.md files with "readmes" tool.

crates/arti-client/README.md

@@ -188,7 +188,7 @@ implementation with another.
 ### Experimental and unstable features
 
  Note that the APIs enabled by these features are NOT covered by semantic
- versioning guarantees: we might break them or remove them between patch
+ versioning[^1] guarantees: we might break them or remove them between patch
  versions.
 
 * `experimental-api` -- build with experimental, unstable API support.
@@ -199,4 +199,8 @@ implementation with another.
 * `experimental` -- Build with all experimental features above, along with
   all experimental features from other arti crates.
 
+[^1]: Remember, semantic versioning is what makes various `cargo` features
+work reliably. To be explicit: if you want `cargo update` to _only_ make safe
+changes, then you cannot enable these features.
+
 License: MIT OR Apache-2.0

crates/arti/README.md

@@ -54,6 +54,10 @@ example see [`arti_defaults.toml`](./arti_defaults.toml).
   (default)
 * `journald` -- Build with support for logging to the `journald` logging
   backend (available as part of systemd.)
+* `dns-proxy` (default) -- Build with support for proxying certain simple
+  DNS queries over the Tor network.
+* `harden` (default) -- Build with support for hardening the Arti process by
+  disabling debugger attachment and other local memory-inspection vectors.
 
 * `full` -- Build with all features above, along with all stable additive
   features from other arti crates.  (This does not include experimental
@@ -90,12 +94,19 @@ implementation with another.
 ### Experimental features
 
  Note that the APIs enabled by these features are NOT covered by semantic
- versioning guarantees: we might break them or remove them between patch
+ versioning[^1] guarantees: we might break them or remove them between patch
  versions.
 
+* `experimental-api` -- build with experimental, unstable API support.
+   (Right now, most APIs in the `arti` crate are experimental, since this
+   crate was originally written to run as a binary only.)
 * `experimental` -- Build with all experimental features above, along with
   all experimental features from other arti crates.
 
+[^1]: Remember, semantic versioning is what makes various `cargo` features
+work reliably. To be explicit, if you want `cargo update` to _only_ make
+correct changes, then you cannot enable these features.
+
 ## Limitations
 
 There are many missing features.  Among them: there's no onion service

crates/fs-mistrust/README.md

@@ -117,8 +117,9 @@ use fs_mistrust::Mistrust;
 let my_mistrust = Mistrust::builder()
     // Assume that our home directory and its parents are all well-configured.
     .ignore_prefix("/home/doze/")
-    // Assume that a given group will only contain trusted users.
+    // Assume that a given group will only contain trusted users (this feature is only
-    .trust_group(413)
+    // available on Unix-like platforms).
+    // .trust_group(413)
     .build()?;
 ```
 

crates/tor-congestion/README.md

@@ -1 +1,15 @@
-(stub, will get replaced soon)
+# tor-congestion
+
+`tor-congestion`: algorithms for congestion control on the Tor network
+
+## Overview
+
+This crate is part of
+[Arti](https://gitlab.torproject.org/tpo/core/arti/), a project to
+implement [Tor](https://www.torproject.org/) in Rust.
+
+This implements some of the algorithms needed to implement congestion control
+as part of
+[Tor proposal #324](https://gitlab.torproject.org/tpo/core/torspec/-/blob/main/proposals/324-rtt-congestion-control.txt).
+
+License: MIT OR Apache-2.0

crates/tor-proto/README.md

@@ -55,16 +55,32 @@ library, or the `arti` CLI.
 
 ## Design notes
 
-This crate's APIs are structured to explicitly avoid any usage of
+This crate's APIs are structured to limit usage of an asynchronous runtime:
-an asynchronous runtime: It doesn't launch tasks or include
+It doesn't launch tasks or create timers except when necessary.
-timeouts.  Those are done at a higher level in Arti, via the
-[`tor-rtcompat`] crate.
 
 To the extent possible, this crate avoids doing public-key
 cryptography in the same functions it uses for network activity.
 This makes it easier for higher-level code to parallelize or yield
 around public-key operations.
 
+Also, this crate tries to avoid knowing or encoding information about what
+its objects (channels, circuits, streams) are "used for".  That is, whenever
+possible, we encode _how an object should behave_, not _the reason that it
+should behave that way_.  For example, the `Circuit` object in this crate
+remembers the path through which the circuit was built, but _not_ the
+purpose that the circuit serves, or what it may be used for.  It's the
+responsibility of other crates to enforce that kind of rule.
+
+Why separate behavior from purpose in this way?
+We do so in order to prevent a kind of logical overloading that we ran into
+with the C tor implementation, where usage information is _not_ separate
+from behavioral settings.  Since usage information is available, at all
+points in the codebase the C tor code has converged in many places on
+complex logic involving that usage information in order to set individual
+behaviors.  Because of that, adding a new kinds usage or behavior in C tor
+has become quite complex.  We're trying to avoid that kind of complexity in
+Arti.
+
 ## Limitations
 
 This is all a work in progress, and will need severe refactoring