diff --git a/.changeset/breezy-rings-glow.md b/.changeset/breezy-rings-glow.md
new file mode 100644
index 00000000..d720b2d3
--- /dev/null
+++ b/.changeset/breezy-rings-glow.md
@@ -0,0 +1,7 @@
+---
+"@perfect-abstractions/compose-cli": patch
+"@perfect-abstractions/compose": patch
+"compose-documentation": patch
+---
+
+add installation commands to docs & readme
diff --git a/README.md b/README.md
index 3fc66ce5..96922bbb 100644
--- a/README.md
+++ b/README.md
@@ -31,22 +31,30 @@ We build high-quality smart contracts by <a href="https://compose.diamonds/docs/
 
 ## Quick Start
 
+## Create a new project with Compose CLI
+
 ```bash
-# Clone the repository
-git clone https://github.com/Perfect-Abstractions/Compose.git
-cd Compose
+npx @perfect-abstractions/compose-cli init
+```
+
+## Add Compose to an existing project (Manual Installation)
 
-# Install dependencies
-forge install
+### Foundry
 
-# Build the project
-forge build
+```bash
+forge install Perfect-Abstractions/Compose@tag=compose@0.0.3
+```
 
-# Run tests
-forge test
+### Hardhat / NPM
 
-# For test documentation, see test/README.md
+```bash
+npm install @perfect-abstractions/compose
 ```
+
+Packages: [`@perfect-abstractions/compose`](https://www.npmjs.com/package/@perfect-abstractions/compose) · [`@perfect-abstractions/compose-cli`](https://www.npmjs.com/package/@perfect-abstractions/compose-cli). More detail: [Installation](https://compose.diamonds/docs/getting-started/installation).
+
+
+
 ## Documentation
 
 Please see our [documentation website](https://compose.diamonds/docs/) for full documentation.
diff --git a/cli/README.md b/cli/README.md
index 5b44ecbf..131e1b30 100644
--- a/cli/README.md
+++ b/cli/README.md
@@ -1,16 +1,14 @@
 # Compose CLI
 
-`@perfect-abstractions/compose-cli` scaffolds diamond-based projects using the Compose Library.
-Supports both Foundry and Hardhat.
+Creates new diamond-based projects using the Compose Library.
+Supports both [Foundry](https://book.getfoundry.sh/) and [Hardhat](https://hardhat.org/) frameworks.
 
-## Install (Soon)
+## Create a new project with Compose CLI
 
 ```bash
-npm install -g @perfect-abstractions/compose-cli
+npx @perfect-abstractions/compose-cli init
 ```
 
-Requires Node.js >= 20.
-
 ## Usage
 
 ```bash
@@ -58,11 +56,6 @@ compose init --name my-hardhat-mocha-ethers \
 
 `compose templates` prints this information in a friendly format.
 
-## Notes on `@perfect-abstractions/compose`
-
-Hardhat scaffolds inject `@perfect-abstractions/compose` as the dependency name.  The current package isn't published yet.
-
-
 ## Development
 
 From the `cli` directory:
diff --git a/website/docs/contribution/how-to-contribute.mdx b/website/docs/contribution/how-to-contribute.mdx
index 87c6ec7c..1f1c576a 100644
--- a/website/docs/contribution/how-to-contribute.mdx
+++ b/website/docs/contribution/how-to-contribute.mdx
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 2
+sidebar_position: 1
 title: How to Contribute
 description: Learn how to contribute to Compose
 ---
diff --git a/website/docs/getting-started/installation.md b/website/docs/getting-started/installation.md
index b16802e2..4dcbe6f2 100644
--- a/website/docs/getting-started/installation.md
+++ b/website/docs/getting-started/installation.md
@@ -2,110 +2,67 @@
 sidebar_position: 1
 ---
 
-# Installation
-
-Get up and running with Compose in just a few minutes.
+import DocSubtitle from '@site/src/components/docs/DocSubtitle';
 
-## Prerequisites
+# Installation
 
-Before you begin, make sure you have the following installed:
+<DocSubtitle>Get up and running with Compose in just a few minutes.</DocSubtitle>
 
-- **[Foundry](https://book.getfoundry.sh/getting-started/installation)** - Fast, portable Ethereum development framework
-- **Git** - For cloning repositories
-- **Node.js 20+** - (Optional) For running tests and scripts
+## Packages
 
-## Quick Start
+Compose is published as two npm packages:
 
-### Option 1: Clone the Repository (Contributors)
+- **[`@perfect-abstractions/compose`](https://www.npmjs.com/package/@perfect-abstractions/compose)**: Solidity library
+- **[`@perfect-abstractions/compose-cli`](https://www.npmjs.com/package/@perfect-abstractions/compose-cli)**: CLI to create Foundry or Hardhat diamond starter projects that use the library
 
-If you're contributing to Compose:
+## Prerequisites
 
-```bash
-# Clone the repository
-git clone https://github.com/Perfect-Abstractions/Compose.git
-cd Compose
+- **Node.js >= 20**: required for the CLI and for npm-based Hardhat workflows
+- **[Foundry](https://book.getfoundry.sh/getting-started/installation) (Optional)**: required if you use a Foundry scaffold or integrate Solidity with Forge
+- **Git**: used by Foundry dependency installs inside generated projects
 
-# Install dependencies
-forge install
+## Create a new project with Compose CLI
 
-# Build the project
-forge build
+The fastest path is to run the CLI with `npx` (no global install):
 
-# Run tests
-forge test
+```bash
+npx @perfect-abstractions/compose-cli init
 ```
 
-### Option 2: Install as Dependency (Coming Soon)
+### Manual Installation
 
-In the future, you'll be able to install Compose as a Foundry dependency:
+To install the CLI globally:
 
 ```bash
-# This will be available when Compose reaches stable release
-forge install Perfect-Abstractions/Compose
+npm install -g @perfect-abstractions/compose-cli
+compose init
 ```
 
-## Project Structure
+## Add Compose to an existing project (Manual Installation)
 
-After installation, you'll find the following structure:
+### Foundry
 
-```
-Compose/
-├── src/                    # Source contracts
-│   ├── facets/            # Facet implementations
-│   ├── libraries/         # Library helpers
-│   └── interfaces/        # Standard interfaces
-├── test/                  # Test files
-├── script/                # Deployment scripts
-├── lib/                   # Dependencies
-└── foundry.toml          # Foundry configuration
+```bash
+forge install Perfect-Abstractions/Compose@tag=compose@0.0.3
 ```
 
-## Configuration
-
-### Foundry Setup
-
-Compose includes a pre-configured `foundry.toml`. If you're integrating Compose into an existing project, add these settings:
-
-```toml
-[profile.default]
-src = "src"
-out = "out"
-libs = ["lib"]
-optimizer = true
-optimizer_runs = 20_000
-evm_version = "prague"
-
-[profile.ci]
-src = "src"
-out = "out"
-libs = ["lib"]
-optimizer = true
-optimizer_runs = 20_000
-evm_version = "prague"
-# Coverage settings
-fuzz = { runs = 1000 }
-invariant = { runs = 1000 }
-
-[fmt]
-line_length = 120
-tab_width = 4
-bracket_spacing = false
-int_types = 'long'
-multiline_func_header = 'attributes_first'
-quote_style = 'double'
-number_underscore = 'preserve'
-single_line_statement_blocks = 'preserve'
+Create a `remappings.txt` file in the root of your project with the following content:
+```txt
+@perfect-abstractions/compose/=lib/Compose/src/
 ```
 
-## Verify Installation
 
-Run the tests to verify everything is working:
+### Hardhat / NPM
 
 ```bash
-forge test -vvv
+npm install @perfect-abstractions/compose
 ```
 
-You should see output indicating all tests pass.
+## Import Compose in your project
+
+```solidity
+import {DiamondMod} from "@perfect-abstractions/compose/diamond/DiamondMod.sol";
+```
 
 <!-- ## What's Next?
 
@@ -124,6 +81,6 @@ Having trouble with installation?
 - Open an **[issue on GitHub](https://github.com/Perfect-Abstractions/Compose/issues)**
 
 :::tip Development Environment
-We recommend using VSCode with the **Solidity** extension by Juan Blanco for the best development experience.
+We recommend using VSCode with the [**Solidity** extension](https://github.com/juanfranblanco/vscode-solidity) by Juan Blanco for the best development experience.
 :::
 
diff --git a/website/sidebars.js b/website/sidebars.js
index d684cc43..f8f0990b 100644
--- a/website/sidebars.js
+++ b/website/sidebars.js
@@ -19,27 +19,27 @@ const sidebars = {
     'intro',
     {
       type: 'category',
-      label: 'Foundations',
-      collapsed: false,
-      link: {
-        type: 'doc',
-        id: 'foundations/index',
-      },
+      label: 'Getting Started',
+      collapsed: true,
       items: [
         {
           type: 'autogenerated',
-          dirName: 'foundations',
+          dirName: 'getting-started',
         },
       ],
     },
     {
       type: 'category',
-      label: 'Getting Started',
-      collapsed: true,
+      label: 'Foundations',
+      collapsed: false,
+      link: {
+        type: 'doc',
+        id: 'foundations/index',
+      },
       items: [
         {
           type: 'autogenerated',
-          dirName: 'getting-started',
+          dirName: 'foundations',
         },
       ],
     },