diff --git a/src/content/docs/getting-started/first-contract.md b/src/content/docs/getting-started/first-contract.md
index 40b8ff3..9ecc72b 100644
--- a/src/content/docs/getting-started/first-contract.md
+++ b/src/content/docs/getting-started/first-contract.md
@@ -1,18 +1,175 @@
 ---
 title: Your First Contract
-description: A minimal Fe contract example
+description: Write, test, deploy, and interact with a Counter contract
 ---
 
-Let's write your first Fe smart contract.
+In this tutorial you'll create a Counter contract, test it, compile it, deploy it to a local chain with [Foundry](https://book.getfoundry.sh/), and interact with it.
 
-## A Minimal Example
+## Prerequisites
 
-TODO: Add minimal contract example
+- **Fe** installed ([Installation](/getting-started/installation/))
+- **Foundry** installed ([getfoundry.sh](https://getfoundry.sh/))
 
-## Compiling
+## Create a Project
 
-TODO: Add compilation instructions
+Fe has a built-in project scaffolding command. Run it to create a new project called `counter`:
 
-## Deploying
+```bash
+fe new counter
+cd counter
+```
 
-TODO: Add deployment instructions
+This creates the following structure:
+
+```
+counter/
+├── fe.toml
+└── src/
+    └── lib.fe
+```
+
+`fe.toml` is the project manifest. `src/lib.fe` contains a starter Counter contract.
+
+## The Contract
+
+Open `src/lib.fe`. You'll see the following contract:
+
+```fe
+use std::abi::sol
+use std::evm::{Evm, Call}
+use std::evm::effects::assert
+
+msg CounterMsg {
+    #[selector = sol("increment()")]
+    Increment,
+    #[selector = sol("get()")]
+    Get -> u256,
+}
+
+struct CounterStore {
+    value: u256,
+}
+
+pub contract Counter {
+    mut store: CounterStore
+
+    init() uses (mut store) {
+        store.value = 0
+    }
+
+    recv CounterMsg {
+        Increment uses (mut store) {
+            store.value = store.value + 1
+        }
+
+        Get -> u256 uses (store) {
+            store.value
+        }
+    }
+}
+```
+
+Let's break this down:
+
+- **`msg CounterMsg`** defines the contract's public interface. Each variant becomes a callable function. The `sol(...)` helper computes standard Solidity function selectors, making the contract compatible with existing Ethereum tooling.
+
+- **`struct CounterStore`** declares the on-chain storage layout. Its fields are persisted between calls.
+
+- **`pub contract Counter`** is the contract itself. The `mut store` field connects it to its storage.
+
+- **`init()`** is the constructor. It runs once when the contract is deployed. The `uses (mut store)` clause explicitly declares that this function writes to storage.
+
+- **`recv CounterMsg`** is the receive block. It routes incoming messages to handlers. `Increment` needs `mut store` because it writes; `Get` only needs `store` (read-only).
+
+This explicit declaration of effects — what each function reads or writes — is one of Fe's defining features. Nothing is hidden.
+
+## Run the Tests
+
+The generated file also includes a test. Run it:
+
+```bash
+fe test
+```
+
+You should see the test pass. The test deploys the contract in a local EVM sandbox, calls `Get` (expects `0`), calls `Increment`, then calls `Get` again (expects `1`).
+
+## Build
+
+Compile the contract to EVM bytecode:
+
+```bash
+fe build
+```
+
+This creates an `out/` directory with the compiled artifacts:
+
+```
+out/
+├── Counter.bin           # Deploy (init) bytecode
+└── Counter.runtime.bin   # Runtime bytecode
+```
+
+## Deploy to a Local Chain
+
+Start a local Ethereum node with Foundry's `anvil`:
+
+```bash
+anvil
+```
+
+Anvil prints a list of pre-funded accounts and their private keys. Keep it running and **open a second terminal**.
+
+Deploy the Counter contract using `cast`:
+
+```bash
+cast send \
+  --rpc-url http://127.0.0.1:8545 \
+  --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 \
+  --create 0x$(cat out/Counter.bin)
+```
+
+:::note
+The private key above is Anvil's default first account. Never use it outside of local development.
+:::
+
+In the output, look for the `contractAddress` field — that's your deployed Counter. Export it for the next steps:
+
+```bash
+export COUNTER=<the contract address from the output>
+```
+
+## Interact with the Contract
+
+Read the current counter value:
+
+```bash
+cast call --rpc-url http://127.0.0.1:8545 $COUNTER "get()(uint256)"
+```
+
+This should return `0`.
+
+Increment the counter:
+
+```bash
+cast send \
+  --rpc-url http://127.0.0.1:8545 \
+  --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 \
+  $COUNTER "increment()"
+```
+
+Read the value again:
+
+```bash
+cast call --rpc-url http://127.0.0.1:8545 $COUNTER "get()(uint256)"
+```
+
+It should now return `1`. Each `cast send` with `increment()` will increase the value by one.
+
+## Next Steps
+
+You've written, tested, compiled, deployed, and interacted with a Fe contract. From here:
+
+- [Key Concepts](/getting-started/key-concepts/) — understand Fe's core ideas
+- [Effects & the `uses` Clause](/effects/overview/) — learn how Fe tracks state access
+- [Messages & Receive Blocks](/messages/overview/) — dig deeper into the message model
+- [Examples](/examples/erc20/) — see more realistic contracts
diff --git a/src/content/docs/getting-started/installation.md b/src/content/docs/getting-started/installation.md
index 944a240..cd9ac91 100644
--- a/src/content/docs/getting-started/installation.md
+++ b/src/content/docs/getting-started/installation.md
@@ -3,35 +3,72 @@ title: Installation
 description: Setting up the Fe compiler
 ---
 
-:::caution[No Release Available]
-Fe is currently under active development and there is no installable release available. The last published release is over two years old and does not reflect the current state of the language documented here.
+:::caution[Pre-Release Software]
+Fe is in active development. The current releases are alpha versions and not yet suitable for production use.
 :::
 
-## Current Status
+## Quick Install (recommended)
 
-The Fe compiler has undergone intensive rework over the past two years, introducing significant improvements including:
+The fastest way to install Fe is via **feup**, the Fe toolchain installer. It automatically detects your platform and downloads the latest release.
 
-- A new effect system for explicit capability tracking
-- Message-based contract interfaces
-- Enhanced type system with traits and generics
-- Improved tooling (formatter, language server, package manager)
+```bash
+curl -fsSL https://raw.githubusercontent.com/argotorg/fe/master/feup/feup.sh | bash
+```
 
-This documentation covers these upcoming features.
+This will:
+- Install the `fe` compiler to `~/.fe/bin/`
+- Install the `feup` command for future updates
+- Add `~/.fe/bin` to your `PATH`
 
-## Following Development
+After installation, restart your shell or run:
 
-Until a new release is available, you can follow Fe's development:
+```bash
+source ~/.fe/env
+```
 
-- **GitHub Repository**: [github.com/argotorg/fe](https://github.com/argotorg/fe) - Watch for releases and follow development
-- **Build from Source**: Advanced users can build the compiler from the repository's main branch
+To install a specific version:
 
-## What's Next
+```bash
+curl -fsSL https://raw.githubusercontent.com/argotorg/fe/master/feup/feup.sh | bash -s -- --version v26.0.0-alpha.5
+```
 
-Once a release is available, this page will include:
+## Homebrew
 
-- Binary downloads for major platforms
-- Package manager installation (cargo, brew, etc.)
-- Verification steps
-- IDE setup instructions
+On macOS and Linux you can also install Fe via Homebrew:
 
-For now, continue reading to learn about Fe's design and features. When the release is ready, you'll be prepared to start building.
+```bash
+brew install argotorg/tap/fe
+```
+
+## Supported Platforms
+
+Fe provides pre-built binaries for:
+
+| Platform | Architecture |
+|----------|-------------|
+| Linux    | x86_64, ARM64 |
+| macOS    | x86_64, ARM64 (Apple Silicon) |
+
+## Verify Installation
+
+After installing, verify that Fe is working:
+
+```bash
+fe --version
+```
+
+## Build from Source
+
+To build the compiler from source, clone the repository and build with Cargo:
+
+```bash
+git clone https://github.com/argotorg/fe.git
+cd fe
+cargo install --path crates/driver
+```
+
+This requires a working [Rust toolchain](https://rustup.rs/).
+
+## Next Steps
+
+With Fe installed, head over to [Your First Contract](/getting-started/first-contract/) to write, deploy, and interact with a Counter contract.