reword intros, consolidate

Author: ricardo-devis-agullo

website/docs/components/cli.md

@@ -4,6 +4,14 @@ sidebar_position: 2
 
 # Command Line Tool
 
+## Prerequisites
+
+- **Node.js** 20 or newer (verify with `node -v`)
+- **npm** (ships with Node) — ensure it’s on your `$PATH`
+- Network reachability to your component registry (VPN/proxy if corporate)
+
+If these are satisfied you can install the CLI as shown below.
+
 ## Install the cli
 
 To install cli, you should type:
@@ -101,33 +109,47 @@ oc mock plugin hash "test-value"
 ## Most Frequently Used Commands
 
 ### Essential Commands (Daily Use)
+
 - `oc init <name>` - Create new component
 - `oc dev . <port>` - Start development server
 - `oc preview <url>` - Preview component
 - `oc publish <path>` - Publish component
 
 ### Setup Commands (One-time)
+
 - `oc registry add <url>` - Add registry
 - `oc registry ls` - List registries
 
 ### Maintenance Commands (Occasional)
+
 - `oc clean <path>` - Clean dependencies
 - `oc package <path>` - Package component
 - `oc mock plugin <name> <value>` - Mock plugins
 
 ## Quick Reference
 
-| Command | Purpose | Example |
-|---------|---------|---------|
-| `init` | Create component | `oc init header` |
-| `dev` | Start dev server | `oc dev . 3030` |
-| `preview` | Test component | `oc preview http://localhost:3030/header` |
-| `publish` | Deploy component | `oc publish header/` |
-| `registry add` | Add registry | `oc registry add https://my-registry.com` |
-| `clean` | Remove node_modules | `oc clean . --yes` |
+| Command        | Purpose             | Example                                   |
+| -------------- | ------------------- | ----------------------------------------- |
+| `init`         | Create component    | `oc init header`                          |
+| `dev`          | Start dev server    | `oc dev . 3030`                           |
+| `preview`      | Test component      | `oc preview http://localhost:3030/header` |
+| `publish`      | Deploy component    | `oc publish header/`                      |
+| `registry add` | Add registry        | `oc registry add https://my-registry.com` |
+| `clean`        | Remove node_modules | `oc clean . --yes`                        |
 
 ---
 
+## Installation Troubleshooting
+
+| Symptom                                   | Fix                                                                                     |
+| ----------------------------------------- | --------------------------------------------------------------------------------------- |
+| `EACCES` permission errors on macOS/Linux | Re-run with `sudo npm install -g oc` or configure a user-level npm prefix               |
+| `oc: command not found`                   | Ensure npm global bin folder is in `$PATH` (`npm config get prefix` → add `prefix/bin`) |
+| Port already in use when running `oc dev` | Choose another port: `oc dev . 3031`                                                    |
+| Component stuck on "Loading…"             | Check browser console, verify registry URL, review template syntax                      |
+
+For additional issues search the [GitHub discussions](https://github.com/opencomponents/opencomponents/discussions) or open a new ticket.
+
 ### clean
 
 Remove the node_modules directory from each component's subfolder
@@ -206,8 +228,8 @@ $ oc init <componentPath> [templateType]
 
 #### Parameters:
 
-| Name            | Description                                              | Default                |
-| --------------- | -------------------------------------------------------- | ---------------------- |
+| Name            | Description                                              | Default         |
+| --------------- | -------------------------------------------------------- | --------------- |
 | `componentPath` | The relative path with a name of the component to create |
 | `templateType`  | The name of the published template module on npm         | oc-template-es6 |
 

website/docs/components/getting-started.md

@@ -6,24 +6,9 @@ sidebar_position: 1
 
 ## Prerequisites
 
-Before creating your first component, ensure you have:
+Before creating your first component, make sure your workstation meets the [CLI installation requirements](cli.md#installation). If you followed the **Quick-Start Tutorial** you can skip this.
 
-- **Node.js** (version 20 or higher) - [Download here](https://nodejs.org/)
-- **npm** (comes with Node.js) - Basic familiarity with npm commands
-- **Basic JavaScript knowledge** - Understanding of functions, objects, and modules
-- **Command line familiarity** - Ability to navigate directories and run commands
-
-**New to OpenComponents?** Consider starting with our [Quick Start Tutorial](../quick-start-tutorial) for a complete step-by-step guide.
-
-## Component Creation
-
-To create a component you need to install oc with a command:
-
-```bash
-$ npm install oc -g
-```
-
-The next step is to initialise a component:
+First create the component directory:
 
 ```bash
 $ oc init hello-world
@@ -167,69 +152,7 @@ Explore these example repositories to see OpenComponents in action:
 
 ## Troubleshooting Common Issues
 
-### Installation Problems
-
-**Problem**: Permission errors when installing globally
-
-```bash
-# Solution: Use sudo (macOS/Linux) or run as administrator (Windows)
-sudo npm install oc -g
-```
-
-**Problem**: `oc` command not found after installation
-
-```bash
-# Check if npm global bin is in your PATH
-npm config get prefix
-# Add {prefix}/bin to your PATH environment variable
-```
-
-### Component Creation Issues
-
-**Problem**: `oc init` fails with template errors
-
-```bash
-# Solution: Specify template explicitly (ES6 is default)
-oc init hello-world oc-template-es6
-```
-
-**Problem**: Component won't start with `oc dev`
-
-```bash
-# Solution: Install dependencies first
-cd hello-world
-npm install
-oc dev . 3030
-```
-
-### Development Server Issues
-
-**Problem**: Port already in use
-
-```bash
-# Solution: Use a different port
-oc dev . 3031
-```
-
-**Problem**: Component shows "Loading..." forever
-
-- Check browser console for JavaScript errors
-- Verify the registry URL is accessible
-- Ensure component syntax is valid
-
-### Template Compilation Errors
-
-**Problem**: Template syntax errors
-
-- For ES6 templates: Validate your template literal syntax and ensure the function returns valid HTML
-- For legacy Handlebars templates: Validate template syntax and check for missing variables in server.js
-- Check for missing variables in server.js
-
-**Problem**: Server.js runtime errors
-
-- Check the server.js syntax
-- Verify all required parameters are handled
-- Add error handling in your data function
+- For installation problems, component creation errors, or dev-server hiccups, refer to the in-depth [CLI guide](cli.md#troubleshooting) which contains up-to-date solutions.
 
 ## Next Steps
 

website/docs/intro.md

@@ -6,6 +6,10 @@ sidebar_position: 1
 
 OpenComponents is a framework for building and deploying **micro frontends** - small, independent, and reusable UI components that can be developed by different teams and composed into larger applications.
 
+## Target Audience
+
+OpenComponents is built for **companies with multiple autonomous teams** that ship UI independently. If you’re a solo developer, this approach may be over-engineering.
+
 ## What is OpenComponents?
 
 Think of OpenComponents as a way to break down your frontend into small, manageable pieces that can be:
@@ -193,13 +197,9 @@ When retrieving multiple components, a [batch POST endpoint](/docs/consumers/bat
 - [Rails client](https://github.com/opencomponents/opencomponents-rails)
 - [Sinatra client](https://github.com/opencomponents/sinatra-opencomponents)
 
-# Install the cli
+### Install the CLI
 
-```sh
-npm install oc -g
-# to see available commands:
-oc
-```
+See the dedicated [CLI guide](components/cli#install-the-cli) for installation, shell-autocomplete, and update instructions.
 
 # Setup a library
 

website/docs/quick-start-tutorial.md

@@ -8,16 +8,7 @@ This comprehensive tutorial will guide you through creating your first OpenCompo
 
 ## Prerequisites
 
-Before you begin, make sure you have:
-
-- **Node.js** (version 20 or higher) - [Download here](https://nodejs.org/)
-- **npm** (comes with Node.js) - Basic familiarity with npm commands
-- **Basic JavaScript knowledge** - Understanding of functions, objects, and modules
-- **Command line familiarity** - Ability to navigate directories and run commands
-- **A cloud storage solution** such as:
-  - [AWS S3](https://aws.amazon.com/s3)
-  - [Azure Blob Storage](https://azure.microsoft.com/en-us/services/storage/blobs/)
-  - [Google Cloud Storage](https://cloud.google.com/storage)
+OpenComponents requires [Node.js](https://nodejs.org/) 20+ and the OC CLI. If the CLI isn’t installed yet, follow the [CLI installation guide](components/cli#install-the-cli) and then return here.
 
 ## What You'll Learn
 
@@ -29,36 +20,7 @@ By the end of this tutorial, you'll know how to:
 - Publish components to a registry
 - Consume components in web applications
 
-## Step 1: Install the OpenComponents CLI
-
-First, install the OpenComponents command-line interface globally:
-
-```bash
-npm install -g oc
-```
-
-Verify the installation:
-
-```bash
-oc --version
-```
-
-You should see the version number displayed.
-
-### Troubleshooting Installation
-
-**Problem**: Permission errors on macOS/Linux
-
-```bash
-sudo npm install -g oc
-```
-
-**Problem**: `oc` command not found
-
-- Make sure your npm global bin directory is in your PATH
-- Try: `npm config get prefix` and add `{prefix}/bin` to your PATH
-
-## Step 2: Create Your First Component
+## Step 1: Create Your First Component
 
 Let's create a simple "hello-world" component:
 
@@ -102,7 +64,7 @@ oc init my-component --template-type=vue
 oc init my-component --template-type=svelte
 ```
 
-## Step 3: Explore Your Component
+## Step 2: Explore Your Component
 
 Navigate to your component directory:
 
@@ -129,7 +91,7 @@ export default function (model) {
 }
 ```
 
-## Step 4: Start Local Development
+## Step 3: Start Local Development
 
 Start a local development registry:
 
@@ -164,7 +126,7 @@ Or use the CLI preview:
 oc preview http://localhost:3030/hello-world
 ```
 
-## Step 5: Customize Your Component
+## Step 4: Customize Your Component
 
 Let's modify the component to make it more interesting. Edit the `server.js` file:
 
@@ -208,15 +170,15 @@ export default function (model) {
 
 Save the files and refresh your browser - you should see the changes immediately!
 
-## Step 6: Test with Parameters
+## Step 5: Test with Parameters
 
 Try your component with different parameters:
 
 ```
 http://localhost:3030/hello-world?name=Alice
 ```
 
-## Step 7: Create a Test HTML Page
+## Step 6: Create a Test HTML Page
 
 Create a simple HTML file to test client-side rendering:
 
@@ -242,7 +204,7 @@ Create a simple HTML file to test client-side rendering:
 
 Open this HTML file in your browser to see client-side rendering in action.
 
-## Step 8: Set Up a Registry (Production)
+## Step 7: Set Up a Registry (Production)
 
 For production use, you'll need a registry connected to cloud storage. Here's a basic setup:
 
@@ -294,7 +256,7 @@ registry.start((err, app) => {
 });
 ```
 
-## Step 9: Publish Your Component
+## Step 8: Publish Your Component
 
 ### Configure Registry
 
@@ -321,7 +283,7 @@ Your component should now be available at:
 https://your-registry-domain.com/hello-world
 ```
 
-## Step 10: Consume in Production
+## Step 9: Consume in Production
 
 Update your HTML to use the production registry: