rewrite

docs/src/architecture/p2p-network.md

@@ -2,48 +2,30 @@
 
 ## Small-World Network
 
-Freenet operates as a decentralized peer-to-peer network based on the principles
-of a [small-world network](https://en.wikipedia.org/wiki/Small-world_network).
-This network topology allows Freenet to be resilient against denial-of-service
-attacks, automatically scale to accommodate demand, and provide observable data
-stores. Users can subscribe to specific keys to receive notifications of updates
-as they occur.
+Freenet is structured as a decentralized peer-to-peer network, utilizing the
+principles of a small-world network. This unique network topology enhances
+Freenet's robustness against denial-of-service attacks, enables it to scale
+dynamically based on user demand, and facilitates efficient and transparent data
+storage. Additionally, users can subscribe to specific data keys to receive
+immediate notifications about any updates.
 
 ![Small World Network](p2p-network.svg)
 
 ## Understanding Freenet Peers
 
-A Freenet peer refers to a computer that runs the Freenet core software and
-participates in the network. The organization of peers follows a ring structure,
-where each position on the ring represents a numerical value ranging from 0.0 to
-1.0. This value signifies the peer's location within the network.
+In Freenet, a "peer" is any computer running the Freenet Core software. The 
+peers are organized in a ring-like structure, with each peer assigned a 
+specific numerical value between 0.0 and 1.0, indicating its location in the 
+network's topology. This location is derived from the peer's public key.
 
 ## Establishing Neighbor Connections
 
-Each Freenet peer, or core, establishes bi-directional connections with a
-group of other peers known as its "neighbors." These connections rely on the
-User Datagram Protocol (UDP) and may involve techniques to traverse firewalls
-when required.
-
-To optimize resource utilization, peers monitor the resources they use while
-responding to neighbor requests, including bandwidth, memory, CPU usage, and
-storage. Peers also track the services offered by their neighbors, measured by
-the number of requests directed to those neighbors.
-
-To ensure network efficiency, a peer may sever its connection with a neighbor
-that consumes excessive resources relative to the number of requests it
-receives.
-
-## Implementing Adaptive Routing for Efficient Data Retrieval
-
-When a peer intends to read, create, or modify a contract, it sends a request to
-the peers hosting the contract. The request is directed to the neighbor most
-likely to retrieve the contract quickly. Ideally, this neighbor is the one
-closest to the contract's location, a concept known as "greedy routing."
-However, other factors, such as connection speed, may influence the selection.
-
-Freenet addresses this challenge by monitoring the past performance of peers and
-selecting the one most likely to respond quickly and successfully. This
-selection considers both past performance and proximity to the desired contract.
-The process, known as adaptive routing, employs an algorithm called [isotonic
-regression](https://github.com/sanity/pav.rs).
+Every Freenet peer, also referred to as a node, forms two-way connections with a
+set of other peers, termed "neighbors." These connections utilize the User
+Datagram Protocol (UDP) and can do [Frewall hole punching](https://en.wikipedia.org/wiki/Hole_punching_(networking)) when necessary. Peers manage their resource usage —
+bandwidth, memory, CPU, and storage — based on limits set by the user.
+They keep track of their neighbor's performance and so learn to prefer faster
+connections over time.
+
+Peers can identify bad behavior by other peers like excess resource usage and 
+will disconnect from them.

docs/src/components/delegates.md

@@ -1,11 +1,10 @@
 # Delegates
 
-In Freenet, Delegates act like advanced representatives, similar to a human
-delegate, performing actions on Freenet on your behalf. Think of them as a more
-sophisticated version of a web browser's local storage, with similarities to
-Unix "Daemons". Operating within the Freenet core on your device, Delegates
-are a secure and flexible mechanism for managing private data, such as
-cryptographic keys, tokens, and passwords, and executing complex tasks.
+In Freenet, Delegates are software components that can act on the user's behalf. 
+Think of them as a more sophisticated version of a web browser's local storage, 
+with similarities to Unix "Daemons". Operating within the Freenet core on your 
+device, Delegates are a secure and flexible mechanism for managing private data, 
+such as cryptographic keys, tokens, and passwords, and executing complex tasks.
 
 Delegates interact with various components within Freenet, including Contracts,
 User Interfaces, and other Delegates. They can also communicate directly with
@@ -18,11 +17,11 @@ securely on your devices.
 
 ## Actor Model and Message Passing
 
-Delegates utilize a message passing system similar to the [actor
-model](https://en.wikipedia.org/wiki/Actor_model) to interact with Contracts,
-other Delegates, and Applications.
+Delegates communicate with Contracts, other Delegates, and UIs by passing
+messages, similar to the [actor
+model](https://en.wikipedia.org/wiki/Actor_model).
 
-The Freenet core makes sure that for any incoming message, whether it's from
+The Freenet Core makes sure that for any incoming message, whether it's from
 another Delegate, a User Interface, or a Contract update, the receiver knows who
 the sender is. This allows delegates to verify the behavior of any component
 they interact with, and decide if they can be trusted.

docs/src/introduction.md

@@ -4,10 +4,10 @@ Freenet is a distributed, decentralized alternative to the centralized World
 Wide Web, designed to unleash a new era of innovation and competition, while
 protecting freedom of speech and privacy. 
 
-At the core of Freenet is the Freenet core, which runs on users' computers,
-smartphones, or other devices. The core is tiny, less than 5 MB, allowing it
-to be installed in a matter of seconds and is compatible with a wide range of
-hardware.
+The heart of Freenet is the [Core](https://github.com/freenet/freenet-core), 
+which runs on users' computers, smartphones, or other devices. The Core is 
+tiny, less than 5 MB, allowing it to be installed in a matter of seconds and 
+is compatible with a wide range of hardware.
 
 ![Freenet in Context](freenet_in_context.svg)