From 1deaa2495119d54b92d7e5234e102aa5968c0dfa Mon Sep 17 00:00:00 2001 From: Astra Logical Date: Sat, 25 Jul 2026 19:04:11 -0400 Subject: [PATCH] AI pass at getting-started --- user-facing/getting-started.md | 142 ++++++++++++++++++--------------- 1 file changed, 78 insertions(+), 64 deletions(-) diff --git a/user-facing/getting-started.md b/user-facing/getting-started.md index d1cae3b..bc8e695 100644 --- a/user-facing/getting-started.md +++ b/user-facing/getting-started.md @@ -1,68 +1,82 @@ -# Getting Started with The Nest +# Welcome to The Nest: Getting Started Guide -Welcome! This guide will walk you through your first steps on **The Nest**! - -## Requesting Access to the Nest - -Are you a new user looking to join The Nest? You're in the right place! Take a trip to [https://fledgling.mynest.love](https://fledgling.mynest.love) to request initial access. - -In order to join The Nest you'll need: - -- A username you're happy with. You can't change this later without a lot of hassle! -- A working email. I don't care if this is an alias, but it will need to work for initial account setup, account recovery, and service notifications (if you enroll in them). - -Once you've requested access, an admin will review your request and approve or deny you. - -## Signing In with a Passkey - -The Nest uses **passwordless authentication** powered by [Keycloak](https://keycloak.org/) and WebAuthn passkeys. This means: - -1. You will never log in with a password (after initial setup). -2. You need a **passkey-capable password manager or device** — [Vaultwarden](communication-and-security/vaultwarden.md) (you will be given access to Vaultwarden upon account approval), a smartphone, tablet, or computer with a fingerprint reader, face scanner, or security key (e.g., YubiKey). -3. You will use the same passkey for all services in The Nest. - -### First-Time Setup - -Once approved, you will receive two emails: -1. An invite to join Vaultwarden. -2. An email with instructions on first-time setup that pointed you here. Hi! - -If you would like to make use of Vaultwarden, accept the Vaultwarden invite, otherwise feel free to ignore it. - -Once you have a passkey-capable password manager or device: - -1. Visit [sso.mynest.love](https://sso.mynest.love) and click **Sign In**. -2. Enter the account name and temporary password you were provided. - - **Note:** this will be the only time you are allowed to sign in using a traditional password. -3. Follow the instructions to set up a passkey for your account - -## Your Default Account - -When you join The Nest, you are granted access to the following services by default: - -- [**Matrix**](communication-and-security/matrix.md) — Chat and voice/video calls -- [**Vaultwarden**](communication-and-security/vaultwarden.md) — Password manager (Bitwarden-compatible) -- [**Forgejo**](productivity-and-creation/forgejo.md) — Git hosting for code collaboration -- [**This Documentation Site**](https://mynest.love) — You're reading it right now -- [**Foundry VTT**](productivity-and-creation/foundry-vtt.md) - A virtual tabletop for RPGs - -All other services require an admin to grant you access. See [Requesting Service Access](access-requests.md) for details. - -## Exploring Services - -Once your account is set up, browse the user-facing guides to learn about each service. Most will use **"Sign in with The Nest"** as their authentication method — no separate credentials needed. - -*You may also see verbiage like "Sign in with OIDC", "Sign in with Keycloak", or "Sign in with SSO". These are all the same.* - -## What If Something Goes Wrong? - -- **Can't sign in?** Try a different passkey-capable device or contact an admin via Matrix. -- **Service won't load?** Some services auto-update daily around 03:00 EST. Wait a few minutes and try again. -- **Need help with a specific service?** Ask in the Matrix admin room. - ->[!TIP] ->There is an "Admin" space in matrix with an "Ask an Admin" room. +Welcome to **The Nest**! This guide serves as your starting point for creating your account, navigating available services, and getting support whenever you need it. --- -*Ready to dive in? Pick a service from the sidebar and start exploring.* +## 1. Requesting Access + +Ready to join the community? Head over to [fledgling.mynest.love](https://fledgling.mynest.love) to submit your account request. + +To complete your request, you will need: +* **A Username:** Choose carefully! Usernames cannot be easily changed once created. +* **A Working Email Address:** Email aliases are completely fine. This address will be used for your initial setup, account recovery, and optional service notifications. + +Once submitted, an administrator will review your request and approve your access. + +--- + +## 2. Signing In with a Passkey + +The Nest uses **passwordless authentication** (powered by Keycloak and WebAuthn). Instead of remembering complex passwords, you'll log in securely using a **passkey**. + +> [!NOTE] +> **What is a Passkey?** +> A passkey lets you sign in using your physical device or password manager instead of typing a password. You will use the exact same passkey for all services across The Nest. + +### What You Need +To sign in, you will need a passkey-compatible device or tool, such as: +* A smartphone or tablet +* A computer equipped with a fingerprint reader or face scanner +* A hardware security key (such as a YubiKey) +* A passkey-capable password manager like **Vaultwarden** + +### First-Time Account Setup + +Once your account is approved by an administrator, you will receive two emails: +1. **An invitation to Vaultwarden** (an optional password manager service). +2. **Setup instructions** directing you to this guide. + +If you would like to use Vaultwarden, accept the invite; if not, feel free to ignore it. + +**To complete your initial sign-in:** +1. Navigate to [sso.mynest.love](https://sso.mynest.love) and click **Sign In**. +2. Enter the account username and temporary password provided in your setup details. + *(Note: This is the **only** time you will use a traditional password.)* +3. Follow the on-screen prompts to register a passkey on your device. + +--- + +## 3. Your Default Account Services + +Upon joining The Nest, you automatically gain access to several core platforms: + +| Service | Description | +| :--- | :--- | +| **Matrix** | Group chat, direct messaging, and voice/video calling | +| **Vaultwarden** | Bitwarden-compatible password manager for securing credentials | +| **Forgejo** | Code hosting and collaborative project workspace | +| **Documentation Site** | The user guide platform you are currently reading | +| **Foundry VTT** | Virtual tabletop platform for tabletop RPG games | + +*Additional services require separate administrator authorization. Please review the [Requesting Service Access](access-requests.md) guide for more information.* + +--- + +## 4. Exploring & Signing Into Services + +As you explore the user guides for each platform, signing in is straightforward. Most services use a single button labeled **"Sign in with The Nest"**. + +> [!TIP] +> **Terminology Tip:** +> Depending on the app, you might see phrases like *"Sign in with OIDC"*, *"Sign in with Keycloak"*, or *"Sign in with SSO"*. These all mean the exact same thing: sign in using your standard Nest passkey! + +--- + +## 5. Troubleshooting & Support + +If you run into any issues along the way, here is how to resolve them: + +* **Unable to Sign In?** Try using a different passkey-supported device, or reach out to an administrator on Matrix. +* **Service Unavailable or Unresponsive?** Systems undergo automated daily updates around **03:00 EST**. Please wait a few minutes and refresh your browser. +* **Need General Assistance?** Head over to the **Admin** space in Matrix and drop your question in the **"Ask an Admin"** room.