feat: add get started block

docs/README.md

@@ -6,6 +6,11 @@ Semaphore is written in **Go** (lightweight, fast) and runs on **Windows**, **ma
 
 ## Choose your path
 
+- **I’m evaluating Semaphore or getting my first task running**
+  - Start here: [Getting Started](./getting-started/README.md)
+  - Run a first task: [Quick Start](./getting-started/quickstart.md)
+  - Learn the layout: [UI Tour](./getting-started/ui-tour.md)
+
 - **I’m installing or operating Semaphore (admins/operators)**
   - Install: [Installation](/admin-guide/installation)
   - Configure: [Configuration](/admin-guide/configuration)

docs/admin-guide/README.md

@@ -1,6 +1,8 @@
 # Administration Guide
 
-Welcome to the Semaphore UI Administration Guide. This guide provides comprehensive information for installing, configuring, and maintaining your Semaphore instance.
+Welcome to the Semaphore UI Administration Guide. This guide provides comprehensive information for installing, configuring, securing, and maintaining your Semaphore instance.
+
+> Just evaluating or setting up your first project? Start with the [Getting Started](../getting-started/README.md) section before diving into the full administration topics.
 
 ## What is Semaphore UI?
 

docs/getting-started/README.md

@@ -0,0 +1,20 @@
+# Getting Started
+
+New to Semaphore UI? Start here to understand what the platform offers, set up a working environment in minutes, and learn the vocabulary used throughout the rest of the documentation.
+
+## Who this guide is for
+
+* **Evaluators** who want to try Semaphore in a lab or proof-of-concept.
+* **System administrators** who are planning a production deployment.
+* **Automation engineers** who will build and operate projects day-to-day.
+
+Each subsection is written as a short, self-contained guide that links to deeper administration and user topics when you are ready to dive in.
+
+## What you will learn
+
+1. [Quick Start](./quickstart.md) – install Semaphore locally or with Docker and run your first task.
+2. [Core Concepts](./concepts.md) – understand the primary building blocks (projects, task templates, inventories, secrets, runners).
+3. [UI Tour](./ui-tour.md) – get oriented in the navigation, project dashboards, and execution views.
+4. [Next Steps](./next-steps.md) – adopt Semaphore in a team: configure authentication, connect source control, and enforce process.
+
+> Looking for scripted installs, advanced configuration, or scaling guidance? Skip to the [Administration Guide](../admin-guide/README.md). If you already have Semaphore and need help operating it, check the [User Guide](../user-guide/README.md).

docs/getting-started/concepts.md

@@ -0,0 +1,86 @@
+# Core Concepts
+
+Semaphore UI groups automation around a few key building blocks. Understanding how they relate makes the rest of the documentation easier to navigate.
+
+## Projects
+
+Projects are secure containers for everything your team needs to run automation: repositories, inventories, secrets, runners, and task templates. Each project maintains its own permissions, allowing you to separate teams or environments (for example `Production`, `Staging`, `Sandbox`).
+
+* Access control is role-based (viewer, operator, admin) and can be delegated per project.
+* Integrations such as repositories, keys, and notifications are scoped to the project.
+* Activity history shows who ran which tasks and when.
+
+See the detailed [Projects guide](../user-guide/projects.md).
+
+## Repositories
+
+A repository is the source of automation content: Ansible playbooks, Terraform configurations, shell scripts, and more. Semaphore pulls code on demand from Git, local paths, or archive files.
+
+* Supports HTTPS/SSH Git, Bitbucket, GitLab, GitHub, Gitea, and custom providers.
+* Optionally use access keys or deploy keys from the [Key Store](../user-guide/key-store.md).
+* Pin branches, tags, or commit SHAs for reproducible runs.
+
+Learn how to add repositories in the [Repositories guide](../user-guide/repositories.md).
+
+## Inventories
+
+Inventories describe the infrastructure or targets your automation will operate on. Semaphore supports:
+
+* Static inventories defined inline.
+* Dynamic inventories fetched from scripts or sources like NetBox.
+* Per-project defaults and overrides.
+
+Inventories are configured under **Inventory**, covered in the [Inventory guide](../user-guide/inventory.md).
+
+## Task Templates
+
+Task templates specify what Semaphore runs (e.g. an Ansible playbook, Terraform plan, shell script) and how it runs (repository, inventory, environment variables, surveys, confirmations).
+
+* Templates support different executors: Ansible, Terraform/OpenTofu, Bash, PowerShell, Python, and more.
+* Surveys gather runtime input from operators to avoid hard-coded variables.
+* Templates can require manual approval before execution.
+
+See [Task Templates](../user-guide/task-templates/README.md) for detailed options per executor.
+
+## Tasks & Schedules
+
+When you run a task template, Semaphore creates a *task* instance. Tasks record logs, target hosts, outputs, and metadata.
+
+* Tasks can be triggered manually, via schedules, or through the REST API/CLI.
+* Schedule rules support cron-style expressions with timezone awareness.
+* Task history is searchable for auditing and troubleshooting.
+
+Review the [Tasks](../user-guide/tasks.md) and [Schedules](../user-guide/schedules.md) guides to learn more.
+
+## Secrets & Variables
+
+Projects keep secrets and configuration data separate from code. Use:
+
+* **Key Store** for SSH keys, tokens, and credentials.
+* **Environment** (variable groups) for runtime variables and secrets exposed as environment variables.
+* **Vaults** to store Ansible Vault passwords securely.
+
+Details live in [Key Store](../user-guide/key-store.md) and [Variable Groups](../user-guide/environment.md).
+
+## Runners
+
+Runners execute tasks. By default Semaphore runs tasks on the server host, but you can register additional runners to scale out or isolate workloads.
+
+* Remote runners connect over gRPC and support labels to target specific workloads.
+* Projects can restrict templates to a subset of runners.
+* Runner health is visible in the project dashboard and API.
+
+Learn how to install and manage runners in the [Runners guide](../admin-guide/runners.md).
+
+## Notifications & Integrations
+
+Semaphore can notify teams about task outcomes and integrate with chat, email, and webhooks.
+
+* Built-in connectors include Email, Slack, Microsoft Teams, Telegram, Rocket.Chat, DingTalk, Gotify, and custom webhooks.
+* Configure notifications per project or per template.
+
+See [Notifications](/category/notifications) for configuration steps.
+
+---
+
+Ready to see how these pieces surface in the interface? Continue with the [UI Tour](./ui-tour.md).

docs/getting-started/next-steps.md

@@ -0,0 +1,37 @@
+# Next Steps
+
+Turn a successful smoke test into a durable deployment. This checklist helps you transition from a local install to a shared production instance.
+
+## Harden and scale
+
+1. **Secure transport** – Place Semaphore behind a reverse proxy (NGINX, Apache, Traefik) with TLS. Use our [reverse proxy guides](../admin-guide/reverse-proxy/nginx.md) and [Apache instructions](../admin-guide/reverse-proxy/apache.md).
+2. **External database** – Move from the embedded BoltDB to PostgreSQL or MySQL for reliability and backups. Follow the [database configuration guide](../admin-guide/configuration/config-file.md).
+3. **High availability** – Register additional [runners](../admin-guide/runners.md) to isolate workloads and provide redundancy. Label runners for production vs. staging tasks.
+
+## Configure authentication and authorization
+
+1. Integrate with your identity provider using [OpenID Connect](../admin-guide/openid.md) or [LDAP](../admin-guide/ldap.md).
+2. Map groups/claims to Semaphore roles so new users inherit the correct access automatically.
+3. Define project-level roles (viewer, operator, admin) and limit who can create templates vs. run tasks.
+
+## Establish automation practices
+
+1. **Version control** – Store playbooks and infrastructure code in Git. Branch protection keeps production templates stable.
+2. **Code reviews** – Use pull requests and testing (lint, syntax) before updating templates. Consider running validation tasks via the [CLI](../admin-guide/cli.md) or CI pipelines.
+3. **Secrets management** – Rotate keys in the [Key Store](../user-guide/key-store.md), use environment variables for non-secret configuration, and document ownership.
+
+## Operationalize monitoring and alerts
+
+1. Set up [notifications](/category/notifications) for critical projects (Slack, Teams, email, etc.).
+2. Export logs to your observability stack or enable structured logging via configuration flags.
+3. Define on-call or escalation procedures backed by Semaphore task history.
+
+## Document and train
+
+1. Capture the workflow for creating new projects or templates. Link your runbooks directly to relevant sections in the [User Guide](../user-guide/README.md).
+2. Share the [UI Tour](./ui-tour.md) with operators so they build confidence quickly.
+3. Encourage teams to contribute to this documentation. The docs site makes it easy to submit pull requests with updates.
+
+---
+
+Need help? Join the [Discord community](https://discord.gg/5R6k7hNGcH) or open an issue on [GitHub](https://github.com/semaphoreui/semaphore) to discuss best practices with the maintainers and community.

docs/getting-started/quickstart.md

@@ -0,0 +1,74 @@
+# Quick Start
+
+Follow this walkthrough to get Semaphore UI running on your workstation and execute a simple automation task. The steps take around 10–15 minutes and require no prior knowledge of the platform.
+
+## 1. Pick an install method
+
+Choose the option that best fits your environment:
+
+| When to use | Recommended guide |
+| --- | --- |
+| You want an isolated test environment in minutes | [Docker install](../admin-guide/installation/docker.md)
+| You prefer native binaries and system integration | [Binary install](../admin-guide/installation/binary-file.md)
+| You run on Kubernetes and want to evaluate at cluster scale | [Helm chart](../admin-guide/installation/k8s.md)
+
+> Need another option (package manager, cloud images, manual install)? See the full [Installation overview](../admin-guide/installation.md).
+
+After installation, run the `semaphore` binary (or container) and browse to `http://localhost:3000` to complete the initial setup wizard.
+
+## 2. Complete the setup wizard
+
+Semaphore walks you through the steps below:
+
+1. Create the first administrator user.
+2. Provide database connection details.
+3. Generate or supply an encryption key (used for secrets).
+4. Confirm SMTP settings if you want email alerts. You can skip this for a quick evaluation.
+
+The wizard produces a configuration file on disk. You can always adjust it later using the [configuration reference](../admin-guide/configuration.md).
+
+## 3. Create a sandbox project
+
+Once you sign in, create a project to hold your automation assets:
+
+1. Go to **Projects → New Project**.
+2. Give it a name like `Demo Project` and keep the default repository and inventory settings.
+3. After the project opens, note the tabs across the top: **Task Templates**, **Tasks**, **Schedules**, **Access Keys**, **Repositories**, **Inventory**, and **Environment**.
+
+Projects let you scope permissions and integrations. Learn more in the [Projects overview](../user-guide/projects.md).
+
+## 4. Add a repository and key
+
+You can use any Git repository with an Ansible playbook or shell script. For a quick test, use a public sample playbook.
+
+1. Navigate to **Repositories → Add Repository**.
+2. Select `Git`, paste the repository URL (for example, `https://github.com/semaphoreui/semaphore-demo`), and save.
+3. If the repository is private, create an access key under **Key Store** and reference it here. Keys and tokens are encrypted at rest; see [Key Store](../user-guide/key-store.md).
+
+## 5. Define a task template
+
+Task templates describe what Semaphore will run.
+
+1. Open **Task Templates → New Template**.
+2. Choose **Ansible Playbook** (or another executor you prefer).
+3. Select the repository and playbook path (e.g. `site.yml`).
+4. Pick an inventory (the default `Static Inventory` works for local demos) and click **Create**.
+
+Read more in the [Task Templates guide](../user-guide/task-templates/README.md).
+
+## 6. Run and inspect the task
+
+1. In the template list, click **Run**.
+2. Provide optional variables or confirmations, then start the task.
+3. Observe the live output and status indicators.
+4. After completion, review the log, duration, and host results. You can download logs or re-run from the same page.
+
+The [Tasks guide](../user-guide/tasks.md) explains status codes, log retention, and re-run behavior.
+
+## 7. Keep going
+
+You now have a functioning Semaphore environment. Continue with:
+
+* [Core Concepts](./concepts.md) to understand how projects, inventories, templates, and permissions fit together.
+* [UI Tour](./ui-tour.md) for a guided walkthrough of navigation, filters, and dashboards.
+* [Next Steps](./next-steps.md) to move from a sandbox to a shared or production deployment.

docs/getting-started/ui-tour.md

@@ -0,0 +1,69 @@
+# UI Tour
+
+This guided tour highlights the primary areas of Semaphore UI so you can quickly find the features you need. Screens may look slightly different depending on your version, theme, or feature flags, but the navigation stays consistent.
+
+## Global navigation
+
+The top-level navigation bar includes:
+
+* **Projects** – all projects you can access. Pin frequently used projects to the sidebar.
+* **Administration** – system-wide settings (available to administrators only), including user management, runners, license information, and system diagnostics.
+* **Help** – links to documentation, community resources, and version information.
+
+Use the profile menu (top right) to update your account details, configure notification preferences, or sign out.
+
+## Project dashboard
+
+Opening a project lands you on the **Task Templates** view by default. The project header contains:
+
+* Project information: name, description, default environment.
+* Quick stats: recent task success/failure and queued runs.
+* Tabs for resources within the project.
+
+Tabs available in every project:
+
+| Tab | Purpose |
+| --- | --- |
+| Task Templates | Define what Semaphore runs, configure surveys, matrices, approvals. |
+| Tasks | Monitor historical and in-flight task executions. Filters support status, authors, templates, and time ranges. |
+| Schedules | Automate recurring runs with cron-like rules. |
+| Repositories | Manage source control integrations and ref selections. |
+| Inventory | Configure static or dynamic inventories used by templates. |
+| Environment | Define variable groups exposed to tasks. |
+| Key Store | Store SSH keys, API tokens, passwords, vault secrets. |
+| Team | Invite users and assign roles (viewer, operator, admin). |
+
+Some projects display extra tabs (for example **Runners** or **Integrations**) when features are enabled.
+
+## Task details view
+
+Clicking a task opens a detailed execution view:
+
+* **Summary panel** shows status, duration, initiator, runner, commit SHA, and inventory.
+* **Live log** streams output in real time with search and download options.
+* **Hosts/Steps tabs** break down playbook results or Terraform steps.
+* **Artifacts** lists generated files or state snapshots where applicable.
+* **Actions menu** lets you rerun, cancel, or clone the task (depending on permissions).
+
+Use the breadcrumb trail to jump back to the originating template or project dashboard.
+
+## Administration area
+
+Administrators gain a system-level sidebar:
+
+* **Users & Teams** – manage global accounts, SSO mapping, and roles.
+* **Runners** – view registered runners, labels, versions, and last-seen status.
+* **System** – check version, license state (if applicable), background job queues, and telemetry.
+* **Settings** – configure global options such as OpenID providers, SMTP, audit retention, or feature flags.
+
+Most settings link directly to detailed instructions in the [Administration Guide](../admin-guide/README.md).
+
+## Keyboard and productivity tips
+
+* Press `Ctrl/⌘ + K` to open the command palette for quick navigation.
+* Use saved filters on the **Tasks** view to monitor specific templates or teams.
+* Pin projects to the left sidebar by clicking the star icon next to their name.
+
+---
+
+Next, review [Next Steps](./next-steps.md) to turn your evaluation into a repeatable, collaborative setup.

sidebars.js

@@ -16,6 +16,18 @@ const sidebars = {
   // By default, Docusaurus generates a sidebar from the docs folder structure
   tutorialSidebar: [
     'README',
+    {
+      type: 'category',
+      label: 'Getting Started',
+      collapsed: false,
+      link: { type: 'doc', id: 'getting-started/README' },
+      items: [
+        'getting-started/quickstart',
+        'getting-started/concepts',
+        'getting-started/ui-tour',
+        'getting-started/next-steps',
+      ],
+    },
     {
       type: 'category',
       label: 'Admin Guide',