# Your first day

Conduit is a social blogging site where you sign in or create an account, then use Home to discover
articles. Home is the starting point for article lists.

## Your first day with Conduit

Use this page to set up Conduit, choose an authentication route, and reach Home.

| If you need to… | Go to |
|---|---|
| install and start the application | [Set up and start Conduit](#set-up-and-start-conduit) |
| choose between signing in and creating an account | [Find the sign-in or registration page](#find-the-sign-in-or-registration-page) |
| enter credentials | [Sign in or create an account](#sign-in-or-create-an-account) |
| understand the fields and feed areas | [Understand the authentication and Home surfaces](#understand-the-authentication-and-home-surfaces) |
| find articles after reaching Home | [Find articles in Your Feed and Global Feed](doc:find-articles-in-feeds) |
| resolve a loading or error condition | [When first use does not go as expected](#when-first-use-does-not-go-as-expected) |

Home provides the `Your Feed` and `Global Feed` choices, and it can show popular tags and article
pagination.

## Before you start

You need Bun and the cloned application repository before you run the setup flow. The Login and
Register routes are available to readers who are not signed in.

For setup requirements and the application command flow, see [System requirements](doc:system-requirements).
For the two authentication choices, see [Sign in](doc:sign-in) and [Create an account](doc:create-an-account).

## Set up and start Conduit

Run this procedure when you have the repository and Bun available.

**Prerequisites**

- Have Bun installed.
- Have the application repository available.

**Steps**

1. Open a terminal in the repository root.
2. Type `bun run setup` in the terminal.
3. Run `bun run start`.

**Result:** The application is started for the Login or Register route.

## Find the sign-in or registration page

Login is the route for an existing account. Register is the route for creating an account.

**Prerequisites**

- Have the application running.

**Steps**

1. Choose the route that matches what you need:

   | If you need to… | Open |
   |---|---|
   | use an existing account | `/login` |
   | create an account | `/register` |

2. Select **Need an account?** on Login or **Have an account?** on Register.

Authenticated readers are prevented from activating the Login and Register routes.

**Result:** The selected authentication form is on screen.

## Understand the authentication and Home surfaces

The authentication surface collects the credentials needed for sign-in or registration. Home is the
article-discovery surface after authentication.

### Authentication fields and controls

| Route | Field or control | What to use it for |
|---|---|---|
| Login | **Email** | Enter the account email address. |
| Login | **Password** | Enter the account password. |
| Login | **Sign in** | Submit the sign-in form. |
| Login | **Need an account?** | Open Register. |
| Register | **Username** | Enter the username for the new account. |
| Register | **Email** | Enter the new account email address. |
| Register | **Password** | Enter the new account password. |
| Register | **Sign up** | Submit the registration form. |
| Register | **Have an account?** | Open Login. |

Email and Password are required on both routes. Username is required on Register and does not appear
on Login. The form's submit control is disabled while the form is invalid. During submission, the
authentication fieldset is disabled.

### Home areas and conditions

| What you need to do | Area or condition | What appears |
|---|---|---|
| read the general article list | Global Feed | The article list uses the global-feed path when no tag or following-feed choice applies. |
| read articles from followed users | Your Feed | The link appears for authenticated readers. |
| read articles for a tag | popular tag link | A tag link appears for each returned popular tag. |
| move through article results | pagination | Page-number buttons appear after articles load and pages exist. |
| wait for article results | article loading | `Loading articles...` |
| check an empty following feed | following-feed empty state | `Your feed is empty. Follow some users to see their articles here, or check out the Global Feed!` |
| check an empty global feed | global-feed empty state | `No articles are here... yet.` |
| wait for tags | tag loading | `Loading tags...` |
| check an empty tag list | empty-tags state | `No tags are here... yet.` |

## Sign in or create an account

Complete the form for the account route you selected before working in the Home feed.

**Prerequisites**

- Have the authentication form open.
- For Login, have an existing account's email address and password.
- For Register, have a username, email address, and password for the new account.

**Steps**

1. Choose one path:

   | If you need to… | Use |
   |---|---|
   | sign in with an existing account | Login |
   | create an account | Register |

2. Complete and submit the chosen form:

   | If you chose… | Complete these actions |
   |---|---|
   | Login | Enter the account email address in **Email**. Enter the account password in **Password**. Select **Sign in**. |
   | Register | Enter the new account username in **Username**. Enter the account email address in **Email**. Enter the account password in **Password**. Select **Sign up**. |

After a successful submission, Home opens.

**Result:** Home opens after successful authentication.

## Handle first-use branches and errors

Use this procedure when you need to choose an account path, select a feed, or respond to a
message on the first-use surfaces.

**Prerequisites**

- Have the application running.
- Have Login, Register, or Home open.

**Steps**

1. Choose the account path that matches your need:

   | If you need to… | Use this path |
   |---|---|
   | create an account | Register, where **Username** appears in addition to **Email** and **Password**. |
   | use an existing account | Login, where **Email** and **Password** appear. |

2. Select the feed that matches your need:

   | If you need to… | Select |
   |---|---|
   | read articles from followed users while authenticated | **Your Feed** |
   | read the general article list | **Global Feed** |

3. If an authentication error appears, read the error entry in the form's error area.

The **Your Feed** action is available to authenticated readers. If you need to use it, complete
the sign-in procedure first. When the article request has no results, the following feed uses
`Your feed is empty. Follow some users to see their articles here, or check out the Global Feed!`.
The general article list uses `No articles are here... yet.`. When the tags request has no results,
the tag area uses `No tags are here... yet.`.

**Result:** The selected feed is on screen, or the message that requires your next action is visible.

## When first use does not go as expected

Use the message or route that matches what is on screen.

| What you see | What it indicates | Next action |
|---|---|---|
| `Loading articles...` | The article request is loading. | Wait for the article list result. |
| `Loading tags...` | The tags request is loading. | Wait for the tag list result. |
| `Your feed is empty. Follow some users to see their articles here, or check out the Global Feed!` | The following feed has no articles. | Open Global Feed. |
| `No articles are here... yet.` | The general article list has no articles. | Use the Home feed or a returned tag link. |
| `No tags are here... yet.` | The tags result has no tags. | Continue with the article feed. |
| An authentication error entry in the error area | The authentication request returned an error entry. | Read the entry in the form's error area and correct the account information before submitting again. |
| The **Your Feed** action is unavailable | The following feed requires authentication. | Sign in, then select **Your Feed**. |

For the application-wide message catalogue, see [General error messages](doc:general-error-messages).
For broader issue routing, see [Common issues and solutions](doc:common-issues-and-solutions).

## After you reach Home

After authentication, continue with daily article discovery. Home can list articles from the general
feed, the following feed, or a tag, and it can provide pagination.

| Next task | Continue with |
|---|---|
| find articles in the two feed choices | [Find articles in Your Feed and Global Feed](doc:find-articles-in-feeds) |
| browse articles by a tag | [Browse articles by tag](doc:browse-articles-by-tag) |
| understand loading states | [Loading and unavailable states](doc:loading-and-unavailable-states) |
| read or work with an article | [Read an article](doc:read-an-article) |
| update account settings | [Update settings](doc:update-settings) |
| get help with a problem | [Getting help](doc:getting-help) |