WIP: Add user manual content and update site navigation

- Updated the site navigation to include a link to the new user manual under the Resources menu.

Author: Sam-Max

hugo-site/content/_index.md

@@ -8,7 +8,7 @@ links:
     text: "Video Talks"
     icon: "fas fa-video"
     color: "is-medium-blue"
-  - url: "https://docs.freenet.org/"
+  - url: "/manual/"
     text: "User Manual"
     icon: "fas fa-book"
     color: "is-medium-teal"

hugo-site/content/manual/README.md

@@ -0,0 +1,64 @@
+**NOTE:** This document is a work in progress. You can [submit an issue](https://github.com/freenet/freenet-core/issues/new?labels=A-documentation) if you find a problem or have a suggestion. The source for this documentation is in our repository at [freenet-core/docs/src](https://github.com/freenet/freenet-core/tree/main/docs/src). We welcome pull requests.
+
+# Introduction
+
+## What is Freenet?
+
+Freenet is a global, [observable](https://en.wikipedia.org/wiki/Small-world_network), decentralized key-value store. Values are arbitrary blocks of data, called the contract's "state." Keys are cryptographic contracts that specify:
+
+- Whether a given state is permitted under this contract
+- How the state can be modified over time
+- How two valid states can be merged
+- How to efficiently synchronize a contract's state between peers
+
+Freenet is a true decentralized peer-to-peer network, and is robust and scalable, through its use of a [small-world network](https://en.wikipedia.org/wiki/Small-world_network).
+
+Applications on Freenet can be built in any language that is supported by web browsers, including JavaScript and WebAssembly. These applications are distributed over Freenet and can create, retrieve, and update contracts through a WebSocket connection to the local Freenet peer.
+
+## Writing a Contract
+
+Freenet contracts can be written in any language that compiles to WebAssembly.
+This includes [Rust](https://www.rust-lang.org/), and
+[AssemblyScript](https://www.assemblyscript.org/), among many others.
+
+A contract consists of the WebAssembly code itself and its "parameters," which are additional data like cryptographic keys. This makes it easy to configure contracts without having to recompile them.
+
+A contract can be retrieved using a key, which is a cryptographic hash derived from the contract's WebAssembly code together with its parameters.
+
+## Small world routing
+
+Freenet peers self-organize into a [small-world network](https://en.wikipedia.org/wiki/Small-world_routing) to allow contracts to be found in a fast, scalable, and decentralized way.
+
+Every peer in Freenet is assigned a number between 0 and 1 when it first joins the network, this is the peer's "location". The small world network topology ensures that peers with similar locations are more likely to be connected.
+
+Contracts also have a location, which is derived from the contract's key. Peers cache contracts close to their locations.
+
+## Writing an Application
+
+Creating a decentralized application on Freenet is very similar to creating a normal web application. You can use familiar frameworks like React, Bootstrap, Angular, Vue.js, and so on.
+
+The main difference is that instead of connecting to a REST API running on a server, the web application connects to the Freenet peer running on the local computer through a [WebSocket](https://en.wikipedia.org/wiki/WebSocket) connection.
+
+Through this the application can:
+
+- Create new contracts and their associated state
+- Retrieve contracts and their state
+- Modify contract state when permitted by the contract
+
+## How to use Contracts
+
+Contracts are extremely flexible. they can be used to create decentralized data structures like hashmaps, inverted indices for keyword search, or efficient buffers for streaming audio and video.
+
+## Delegate Ecosystem
+
+Applications in Freenet don't need to be built from scratch, they can be built on top of components provided by us or others.
+
+### Reputation system
+
+Allows users to build up reputation over time based on feedback from those they interact with. Think of the feedback system in services like Uber, but with Freenet it will be entirely decentralized and cryptographically secure. It can be used for things like spam prevention (with IM and email), or fraud prevention (with an online store).
+
+This is conceptually similar to Freenet's [Web of Trust](http://www.draketo.de/english/freenet/friendly-communication-with-anonymity) plugin.
+
+### Arbiters
+
+Arbiters are trusted services that can perform tasks and authenticate the results, such as verifying that a contract had a particular state at a given time, or that external blockchains (Bitcoin, Ethereum, Solana etc) contain specific transactions. Trust is achieved through the reputation system.

hugo-site/content/manual/_index.md

@@ -0,0 +1,45 @@
+---
+title: "Manual"
+date: 2025-04-13        # For blog-style ordering or metadata
+draft: false            # Prevents Hugo from skipping the page in output
+weight: 3               # Controls order in listings (lower = higher)
+---
+
+
+# Manual Index
+
+## Introduction
+
+- [Introduction](introduction)
+
+## Components
+
+- [Overview](components/overview)
+- [Contracts](components/contracts)
+- [Delegates](components/delegates)
+- [User Interfaces](components/ui)
+
+## Architecture
+
+- [P2P Network](architecture/p2p-network)
+- [Intelligent Routing](architecture/irouting)
+- [Transport](architecture/transport)
+
+## Developer Guide
+
+- [Tutorial: Create an App](tutorial)
+- [Contract interfaces](contract-interface)
+- [freenet.toml format](manifest)
+
+## Examples
+
+- [Antiflood Tokens](examples/antiflood-tokens)
+- [Blind Trust Tokens](examples/blind-trust-tokens)
+
+## Community and Support
+
+- [Community](community)
+
+## Reference
+
+- [Glossary](glossary)

hugo-site/content/manual/architecture/irouting.md

@@ -0,0 +1,63 @@
+---
+title: "Intelligent Routing"
+date: 2025-04-13
+draft: false
+weight: 2
+---
+
+## Intelligent Routing
+
+Freenet's request routing mechanism plays a crucial role in the efficiency of
+the network.
+
+It is responsible for deciding which peer to route a request to when attempting
+to read, create, or modify a contract's state. The mechanism is designed to
+select the peer that can complete the request the fastest, which may not always
+be the peer closest to the contract's location - the traditional approach for
+routing in a small-world network, known as [greedy
+routing](https://en.wikipedia.org/wiki/Small-world_routing#Greedy_routing).
+
+### Isotonic Regression
+
+Freenet uses [isotonic regression](https://github.com/sanity/pav.rs), a method
+for estimating a monotonically increasing or decreasing function given a set of
+data, to predict the response time from a peer based on its ring distance from
+the target location of the request.
+
+This estimation is then adjusted by the average difference between the isotonic
+regression estimate and the actual response time from previous interactions with
+the peer. This process enables a form of adaptive routing that selects the peer
+with the lowest estimated response time.
+
+### Router Initialization and Event Handling
+
+When a new
+[Router](https://github.com/freenet/freenet-core/blob/main/crates/core/src/router.rs)
+is created, it's initialized with a history of routing events. These events are
+processed to generate the initial state of the isotonic estimators. For example,
+failure outcomes and success durations are computed for each event in the
+history and used to initialize the respective estimators. The average transfer
+size is also computed from the history.
+
+The Router can add new events to its history, updating its estimators in the
+process. When a successful routing event occurs, the Router updates its response
+start time estimator, failure estimator, and transfer rate estimator based on
+the details of the event. If a failure occurs, only the failure estimator is
+updated.
+
+### Peer Selection
+
+To select a peer for routing a request, the Router first checks whether it has
+sufficient historical data. If not, it selects the peer with the minimum
+distance to the contract location. If it does have sufficient data, it predicts
+the outcome of routing the request to each available peer and selects the one
+with the best predicted outcome.
+
+### Outcome Prediction
+
+To predict the outcome of routing a request to a specific peer, the Router uses
+its isotonic estimators to predict the time to the start of the response, the
+chance of failure, and the transfer rate. These predictions are used to compute
+an expected total time for the request, with the cost of a failure being assumed
+as a multiple of the cost of success. The peer with the lowest expected total
+time is selected for routing the request.

hugo-site/content/manual/architecture/p2p-network.md

@@ -0,0 +1,40 @@
+---
+title: "P2P Network"
+date: 2025-04-13
+draft: false
+weight: 1
+---
+
+# Freenet Network Topology
+
+## Small-World Network
+
+Freenet is structured as a decentralized peer-to-peer network, based on the idea of
+a [small-world network](https://en.wikipedia.org/wiki/Small-world_network). This
+network topology is scalable and efficient, allowing contract state to be found
+quickly and without any reliance on a central authority.
+
+![Small World Network](p2p-network.svg)
+
+## Freenet Peers
+
+In Freenet, a "peer" is any computer running the [Freenet
+Core](https://github.com/freenet/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 IP address.
+
+## Establishing Neighbor Connections
+
+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 [Firewall 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.
+
+## Adaptive behavior
+
+Peers keep track of their neighbor's performance and learn to prefer faster
+connections over time.
+
+Peers can also identify bad behavior by other peers like excess resource usage and
+will disconnect from them.