@@ -1,19 +1,58 @@
 <p align="center">
-  <img height="320" src="https://github.com/user-attachments/assets/66089ca0-96b9-45e3-a423-0261b2ff7ba1" />
+  <img height="320" src="img/organization-logo.png" alt="Unleashed Pascal" />
 </p>
 
-# FPC Unleashed
+<h1 align="center">Unleashed Pascal</h1>
 
-A fork of the Free Pascal Compiler that adds modern language features behind opt-in modeswitches. Inline variables, pattern matching, tuples, `defer` / `autofree`, flexible arrays, multiline strings, RTTI stripping, and more.
+<p align="center">
+  <b>Modern Pascal, today.</b><br />
+  A community-driven toolchain exploring where the language can go next - built on top of the Free Pascal ecosystem.
+</p>
+
+<p align="center">
+  <a href="https://unleashedpascal.org/">Website</a> &middot;
+  <a href="https://github.com/unleashedpascal/freepascal/blob/main/unleashed/docs/README.md">Documentation</a> &middot;
+  <a href="https://github.com/unleashedpascal/installer/releases">Downloads</a>
+</p>
+
+---
+
+## What this is
+
+Unleashed Pascal is an umbrella for a set of forks and tools that explore what Pascal can look like: a compiler, an IDE, an installer, and whatever else the language needs next. It is a playground for ideas that are easier to try in a fork than in a stable, widely-deployed toolchain - built, documented, and shipped here so they can be used in practice rather than argued about in the abstract.
+
+The whole ecosystem shares one rule: **everything is opt-in**. Existing Pascal code keeps compiling untouched. New behaviour turns on per file with a single directive, or per feature with a single modeswitch.
+
+```pascal
+{$mode unleashed}
+```
+
+## Principles
+
+- **Backward compatibility is non-negotiable.** No feature may break code that compiles today.
+- **Opt-in, always.** Per file, or per individual feature - never global, never implicit.
+- **Documented on arrival.** Every feature ships with grammar, semantics, edge cases, and a runnable demo.
+- **Ship it.** Working code in `main` beats a design discussion that runs for years.
+- **Open.** Same licenses as upstream, same freedom to fork again.
+
+## Projects
+
+| Repository | What it is |
+| --- | --- |
+| [**freepascal**](https://github.com/unleashedpascal/freepascal) | The compiler and runtime - a fork of Free Pascal carrying the Unleashed language features |
+| [**lazarus**](https://github.com/unleashedpascal/lazarus) | The IDE - a fork of Lazarus that understands the language as it actually compiles |
+| [**installer**](https://github.com/unleashedpascal/installer) | Cross-platform installer that builds compiler and IDE into a self-contained directory. Every install is fully isolated, so any number of them can coexist side by side - including a stock FPC / Lazarus setup - without interfering with each other |
+
+## Getting started
+
+Grab the installer for your host from the [latest release](https://github.com/unleashedpascal/installer/releases), pick a target directory, click **Install**. It fetches the sources and builds the compiler, the runtime, any cross targets you ticked, and the IDE - without touching the registry, `PATH`, or an existing FPC install.
 
-Existing FPC / Lazarus code compiles unchanged - new features turn on per file with `{$mode unleashed}` or per feature with a specific `{$modeswitch}`.
+Prefer to build by hand? Each repository carries its own build instructions in its README.
 
-## Repos
+## Contributing
 
-- **[freepascal](https://github.com/fpc-unleashed/freepascal)** - compiler and runtime
-- **[lazarus](https://github.com/fpc-unleashed/lazarus)** - companion fork of the Lazarus IDE
-- **[installer](https://github.com/fpc-unleashed/installer)** - bundle installer for compiler, RTL, and IDE
+Issues and pull requests are welcome in whichever repository they belong to. A bug report with a minimal reproducer is worth more than a long description. New language features are expected to arrive with documentation and tests, and to be gated behind a modeswitch.
 
-## Documentation
+## License
 
-Per-feature pages with grammar, examples, and modeswitch info: [`unleashed/docs/README.md`]([https://github.com/fpc-unleashed/freepascal/tree/main/unleashed/docs](https://github.com/fpc-unleashed/freepascal/blob/main/unleashed/docs/README.md)).
+Each repository keeps the license of the project it forked from. See the `LICENSE` / `COPYING` files in the individual repositories.