# Conduit (Angular)

<!-- source: article-workspace.md -->

# Article workspace

## Article workspace overview

An Article workspace is the page where you read an article, see who wrote it, review its
tags and comments, and choose what to do next with it. Comments are discussion entries
attached to the article. Metadata is the author's image, name, and creation date. The
article body is displayed as Markdown.

| If you need to… | Go to… |
| --- | --- |
| Read the article and review its tags | [Understand the article workspace](#understand-the-article-workspace) |
| Edit or delete an article you own | [Choose the article action](#choose-the-article-action) |
| Follow the author or favorite the article | [Choose the article action](#choose-the-article-action) |
| Add or remove a comment | [Handle sign-in and comment branches](#handle-sign-in-and-comment-branches) |
| Open the editor | Create and edit an article |
| Sign in or create an account | Sign in or Create an account |
| Open the author's profile | View a profile |

## Before you start

The Article workspace changes its visible actions according to the article you opened, your
account state, and whether you own the article or a comment.

| Before you start | What it changes |
| --- | --- |
| The article loads | The article content and workspace appear. |
| You own the article | **Edit Article** and **Delete Article** appear. |
| You do not own the article | The follow and favorite controls appear. |
| You are signed in | The comment form appears. |
| You are signed out | **Sign in**, **sign up**, and the prompt to add comments appear. |
| You own a displayed comment | Its delete target appears. |
| The article is already favorited | The favorite control says **Unfavorite Article**. |
| You already follow the author | The follow control says **Unfollow** followed by the author's name. |

**Prerequisites**

- Open the article you want to read at its Article workspace.
- Know whether you are signed in.
- If you plan to change the article, own the article.
- If you plan to remove a comment, own that comment.

With these conditions clear, find and open the article you want to use.

## Find and open an article

An article record is the Article workspace for one article. Use its article route when you
already have an article destination.

**Prerequisites**

- Have the article destination.

**Steps**

1. Open the article's destination in the browser.

**Result:** The Article workspace opens for that article.

## Understand the article workspace

The Article workspace puts the article's identity, content, tags, and discussion in one
reading surface. The author image and author name open the author's profile.

The metadata area appears above the article and again below it. The article body is rendered
as Markdown, and the article's tags appear below the body.

The comment area contains the comments already attached to the article. The Article workspace
presents this reading and discussion content directly; it does not present a grid of columns.

Use the ownership and relationship actions that appear for your situation to continue.

## Choose the article action

Choose an article action according to your relationship with the article and the author.

### Edit or delete an article you own

Use this procedure when the Article workspace shows the owner actions.

**Prerequisites**

- Own the article.
- Decide whether you need to change the article or remove it.

**Steps**

1. Select the action that matches your goal.

   | If you need to… | Select… |
   | --- | --- |
   | Change the article | **Edit Article** |
   | Remove the article | **Delete Article** |

**Result:** **Edit Article** takes you to the article editor. After **Delete Article**
completes, the page navigates to `/`.

### Follow the author or favorite the article

Use this procedure when the Article workspace shows the relationship actions instead of
the owner actions.

**Prerequisites**

- Do not own the article.
- Decide whether you want to follow the author or favorite the article.

**Steps**

1. Select the relationship action that matches your goal.

   | If you need to… | Select… |
   | --- | --- |
   | Follow the author | **Follow** followed by the author's name |
   | Stop following the author | **Unfollow** followed by the author's name |
   | Favorite the article | **Favorite Article** |
   | Remove the article from your favorites | **Unfavorite Article** |

**Result:** The selected relationship changes, the follow or favorite label changes to its
opposite, and the favorite count changes when you favorite or unfavorite the article.

## Handle sign-in and comment branches

The controls available in this area depend on whether you are signed in and whether you
authored a displayed comment.

| Your situation | What appears |
| --- | --- |
| You are signed out | **Sign in**, **sign up**, and the prompt to add comments. |
| You are signed in | **Write a comment...** and **Post Comment**. |
| You authored a displayed comment | The comment delete target. |
| You did not author a displayed comment | No delete target for that comment. |

### Sign in or create an account before commenting

**Prerequisites**

- Have the Article workspace open.
- Be signed out.

**Steps**

1. Select **Sign in** or **sign up** according to your goal.

**Result:** The selected account page opens.

### Post a comment

**Prerequisites**

- Be signed in.
- Have the comment text ready.

**Steps**

1. Enter the comment text in **Write a comment...**.
2. Select **Post Comment**.

**Result:** The new comment appears at the top of the comment list, and **Write a comment...**
is cleared.

### Remove your comment

**Prerequisites**

- Be signed in.
- Own the comment you want to remove.

**Steps**

1. Select the delete target on your comment.

**Result:** The comment is removed from the displayed comment list.

## When the article task goes wrong

The Article workspace displays page and comment errors in an error list. Use the message on
screen to choose the next action.

| What you see | What it means | What to do |
| --- | --- | --- |
| `Failed to load article` | The article could not be loaded. | Return to an article destination and open it again. |
| `Comment body cannot be empty` | The submitted comment has no text. | Enter text in **Write a comment...** and select **Post Comment** again. |
| `Must be logged in` | The action requires a signed-in account. | Select **Sign in** and return to the article. |
| `Article not found` | The article destination does not identify an article. | Open a valid article destination. |
| `Comment not found` | The selected comment is not available. | Return to the displayed comment list. |
| `Cannot delete this comment` | The comment cannot be removed by this account. | Continue without deleting that comment. |
| `Cannot delete` | The article cannot be removed by this account. | Continue without deleting the article. |

The error list displays the error strings returned by the article or comment operation.
API-provided error strings render as list items.
The Article workspace does not display a success or confirmation message for posting, following,
favoriting, or deleting; use the changed comment list, label, count, or destination to check
the result.

After resolving the message, continue with the destination that matches your next task.

## Know what comes next

After you choose an action, continue in the page that owns that part of the work.

| What you selected or need next | Continue with… |
| --- | --- |
| **Edit Article** | Create and edit an article |
| **Sign in** | Sign in |
| **sign up** | Create an account |
| Author image or author name | View a profile |
| **Post Comment** or comment removal | Comment on an article |
| **Favorite Article** or **Unfavorite Article** | Favorite articles |
| **Follow** or **Unfollow** | Follow a user |
| **Delete Article** | The home route `/` |

<!-- source: faq.md -->

# FAQ

## Questions this page answers

Conduit is a social blogging site with authentication, article feeds, profiles, comments,
favorites, and account settings.

Use this page to choose the answer that matches what you are trying to do:

| If you need to… | Go to |
| --- | --- |
| understand the product and its main features | [What is Conduit](doc:what-is-conduit) or [What can you do with Conduit](doc:what-can-you-do-with-conduit) |
| prepare for your first sign-in or registration | [Your first day](doc:your-first-day) |
| sign in | [Sign in](doc:sign-in) |
| create an account | [Create an account](doc:create-an-account) |
| choose between the article feeds | [Find articles in Your Feed and Global Feed](doc:find-articles-in-feeds) |
| understand a loading or unavailable state | [Authentication and loading messages](doc:authentication-and-loading-messages) or [Loading and unavailable states](doc:loading-and-unavailable-states) |
| update your profile settings | [Update settings](doc:update-settings) |
| leave the application | [Sign out](doc:sign-out) |
| investigate an error | [General error messages](doc:general-error-messages) or [Common issues and solutions](doc:common-issues-and-solutions) |

Start with **Before you start** when you need to know which access state or information is
needed first.

## Before you start

Authentication identifies the account that can use protected parts of Conduit. The Login
and Register routes are available to unauthenticated users, while Settings requires an
authenticated user.

Have the following in place before you begin:

| You need | Why it matters |
| --- | --- |
| An unauthenticated session for Login or Register | The authentication routes allow access when the current user is not authenticated. |
| An authenticated session for Settings | The Settings route requires authentication. |
| Your email address and password for Login | **Email** and **Password** are required on the Login form. |
| A username, email address, and password for Register | **Username**, **Email**, and **Password** are required on the Register form. |
| Your current profile information for Settings | Settings fills the form from the current user when that user is available. |

Conduit authenticates users with JWT-based authentication. The application uses the token to
identify the authenticated user.

With the access state and account information ready, continue to **Sign in or create an
account**.

## Sign in or create an account

Use Login to enter an existing account, or Register to create one. Login asks for **Email**
and **Password**; Register adds **Username**.

**Prerequisites**

- For Login, have the existing account's email address and password.
- For Register, have the username, email address, and password for the new account.

**Steps**

1. Choose the route that matches your task:

   | If you want to… | Use |
   | --- | --- |
   | enter an existing account | [Sign in](doc:sign-in) |
   | create an account | [Create an account](doc:create-an-account) |

2. Follow only the sequence for the route you chose:

   | Route | Sequence |
   | --- | --- |
   | Login | 1. If you need a new account, select **Need an account?**; otherwise, enter a value in **Email**, enter a value in **Password**, and select **Sign in**. |
   | Register | 1. If you already have an account, select **Have an account?**; otherwise, enter a value in **Username**, enter a value in **Email**, enter a value in **Password**, and select **Sign up**. |

**Sign in** and **Sign up** are disabled while the required form values are not valid.

**Result:** A successful Login or Register request takes you to Home. If the request is
rejected, the returned error text appears in the error list on the authentication page.

## Use Home and its feed states

Home is the article-browsing surface: it offers **Your Feed**, **Global Feed**, popular tags,
and a paginated article list.

**Prerequisites**

- To use **Your Feed**, be signed in.
- To browse the public article list, open Home and use **Global Feed**.

**Steps**

1. Open Home.
2. Choose the feed that answers your question:

   | If you want to… | Select |
   | --- | --- |
   | read articles from users you follow | **Your Feed** |
   | read the global article list | **Global Feed** |

3. Use the **Popular Tags** area to choose a tag when a tag is listed.

While tags are loading, the page displays `Loading tags...`. If no tags are available after
loading, it displays `No tags are here... yet.`

While articles are loading, the list displays `Loading articles...`. When the following feed
has no articles, the list displays `Your feed is empty. Follow some users to see their articles here, or check out the Global Feed!`.
When the other article list is empty, the list displays `No articles are here... yet.`

**Result:** Home shows the selected feed, its article results, or the loading or empty-state
message that matches the current list state.

For account maintenance, continue to **Update Settings or sign out**.

## Update Settings or sign out

Settings is the account-maintenance surface for the profile picture URL, username, short bio,
email address, and password.

**Prerequisites**

- Sign in before opening Settings.
- Have the profile values you want to keep.

The Settings fields are:

| Field | Use |
| --- | --- |
| **URL of profile picture** | Enter the profile picture URL. |
| **Username** | Enter the account username. |
| **Short bio about you** | Enter the short biography. |
| **Email** | Enter the account email address. |
| **New Password** | Enter a new password when you want to change it. |

**Steps**

1. Open Settings.
2. Choose the action that matches your task:

   | If you want to… | Select |
   | --- | --- |
   | save profile changes | **Update Settings** |
   | leave the account | **Or click here to logout.** |

3. For profile changes, enter the new values in the applicable fields.
4. For a password change, enter the new value in **New Password**.
5. Select **Update Settings**.

When you are not changing the password, leave **New Password** empty. The update omits the
password in that case.

**Result:** A successful settings update takes you to the updated user's profile. Selecting
**Or click here to logout.** logs you out and takes you to Home. If the settings update is
rejected, its returned error text appears in the error list.

If an authentication, loading, or network message appears, continue to **When loading or
errors occur**.

## When loading or errors occur

Use the message you can read on screen to choose the next help page. The application displays
`Each returned error string is rendered as a list item.`

| What you see | What to do next |
| --- | --- |
| `Loading...` | Open [Authentication and loading messages](doc:authentication-and-loading-messages). |
| `Connecting...` | Wait for authentication to retry, or open [Authentication and loading messages](doc:authentication-and-loading-messages). |
| `Auth unavailable - retrying automatically` | Open [Loading and unavailable states](doc:loading-and-unavailable-states). |
| `Unable to connect. Please check your internet connection.` | Check the connection, then open [Common issues and solutions](doc:common-issues-and-solutions). |
| A returned API error string | Match the text in [General error messages](doc:general-error-messages). |

When authentication is temporarily unavailable, the header displays `Connecting...` and the
title `Auth unavailable - retrying automatically`. Authentication retries automatically.

When you have identified the message, continue to the linked task or troubleshooting page.

## Continue with the right help page

Choose the destination that matches your next action:

| Your next action is to… | Continue with |
| --- | --- |
| sign in | [Sign in](doc:sign-in) |
| create an account | [Create an account](doc:create-an-account) |
| find articles in a feed | [Find articles in Your Feed and Global Feed](doc:find-articles-in-feeds) |
| browse by tag | [Browse articles by tag](doc:browse-articles-by-tag) |
| update profile settings | [Update settings](doc:update-settings) |
| sign out | [Sign out](doc:sign-out) |
| change your password | [Change your password](doc:change-your-password) |
| investigate an authentication or loading message | [Authentication and loading messages](doc:authentication-and-loading-messages) |
| investigate a general error | [General error messages](doc:general-error-messages) |
| solve a common issue | [Common issues and solutions](doc:common-issues-and-solutions) |

**Result:** You have the next task or troubleshooting page for the question you are answering.

<!-- source: find-articles-in-feeds.md -->

# Find articles in feeds

## Find articles in the feeds

Home is the article-discovery page: **Your Feed** lists articles from authors you follow, while
**Global Feed** lists articles from the whole application. A tag narrows the list to one subject,
and pagination lets you move through additional results without leaving the feed.

| If you need to… | Go to |
|---|---|
| See articles from authors you follow | [Choose a feed](#choose-a-feed) and select **Your Feed** |
| See all available articles | [Choose a feed](#choose-a-feed) and select **Global Feed** |
| See articles with a particular tag | [Browse tags and more pages](#browse-tags-and-more-pages) |
| Recognize the information on an article preview | [Read the article list](#read-the-article-list) |
| Open the selected article | [Continue from an article or tag](#continue-from-an-article-or-tag) |
| Understand Conduit and its general features | [What can you do with Conduit](doc:what-can-you-do-with-conduit) |
| Learn the application's navigation | [Navigation basics](doc:navigation-basics) |

## Before you start

Your Feed requires sign-in. Home starts an article request when the feed or page changes and loads
the popular tags separately.

Prerequisites

- Be signed in before selecting **Your Feed**.
- Wait for the article list to finish loading before choosing an article or page number.
- Wait for the tags area to finish loading before choosing a tag.

If a following-feed request is made while you are signed out, Home sends you to `/login`.

## Choose a feed

Use the feed tabs to decide which set of articles you want to browse. **Your Feed** opens the
following feed at `/` with the `feed=following` query value. **Global Feed** opens the all-articles
feed at `/`.

Prerequisites

- Be signed in before selecting **Your Feed**.

Steps

1. Choose the feed that answers your question.

   | If you want to… | Select |
   |---|---|
   | Read articles from authors you follow | **Your Feed** |
   | Read the application's all-articles list | **Global Feed** |

2. Confirm that the selected feed's article list appears.

**Result:** Home displays the selected feed's article list.

## Read the article list

An article preview identifies an article by its title and description, then gives you its
author, creation date, tags, favorite control, and a link to the full article. The right side
of Home contains **Popular Tags**; each returned tag is a link to that tag's article list.

When results have loaded, each preview can contain the following information:

| Information | What you use it for |
|---|---|
| Article title | Identify the article and open it |
| Article description | Decide whether the article is relevant |
| Author username and image | Open the author's profile |
| Created date | See when the article was created |
| Article tags | Recognize the subjects attached to the article |
| Heart icon with favorites count | Toggle the article's favorite state |

The article list shows up to 10 articles for each request. **Popular Tags** also has its own
loading state, separate from the article list.

## Browse tags and more pages

Use a tag when you want to narrow article discovery to one subject, or use pagination when the
current feed has more results than the first page.

Prerequisites

- Have a loaded article list with a returned tag or more than one page available.

Steps

1. Choose the result you want to open.

   | If you want to… | Select |
   |---|---|
   | Narrow the list by a popular tag | The returned tag text under **Popular Tags** |
   | Read an article | The article title or **Read more...** |
   | See another page in the current list | The required page number |

2. Confirm that the selected tag list, article page, or article-list page appears.

**Result:** A tag selection opens the selected tag's article list, an article selection opens
the selected article, or a page-number selection displays that page of the current article list.
When you change pages, the current feed query is preserved; page 1 does not add a `page` query
value.

## Handle empty and loading results

Home displays a status message while it retrieves articles or tags, and it replaces the list
with a different message when the selected result contains no articles.

Prerequisites

- Have the selected feed or tag list open.

| What you see | What it means | What to do |
|---|---|---|
| `Loading articles...` | The article request is still loading. | Wait for the list to finish loading. |
| `Loading tags...` | The popular-tags request is still loading. | Wait for the tags to finish loading. |
| `Your feed is empty. Follow some users to see their articles here, or check out the Global Feed!` | Your following feed has no articles. | Follow users or select **Global Feed**. |
| `No articles are here... yet.` | The global or tag-filtered list has no articles. | Choose another feed or tag. |
| `No tags are here... yet.` | No popular tags are available. | Continue with the feed or article list. |

Steps

1. Read the status message shown on the current Home surface.
2. For `Loading articles...`, follow the action in the matching decision-table row.
3. Confirm that the article list appears.
4. For `Loading tags...`, follow the action in the matching decision-table row.
5. Confirm that the tags area appears.
6. For `Your feed is empty. Follow some users to see their articles here, or check out the Global Feed!`, follow the action in the matching decision-table row.
7. For `No articles are here... yet.`, follow the action in the matching decision-table row.
8. For `No tags are here... yet.`, follow the action in the matching decision-table row.

**Result:** You can distinguish a list that is still loading from a list that has finished with
no articles or no tags.

## When a result is not available

Use the message on the page to choose the next action. The Home page is a browsing surface: it
does not provide data-entry fields for creating or editing an article.

Prerequisites

- Have one of the messages below visible.

| What you see | What to do next |
|---|---|
| `Your feed is empty. Follow some users to see their articles here, or check out the Global Feed!` | Select **Global Feed** to browse the all-articles list, or follow users. |
| `No articles are here... yet.` | Choose a different feed or tag. |
| `Loading articles...` | Wait for the article request to finish. |
| `Loading tags...` | Wait for the popular-tags request to finish. |

Steps

1. Read the message and locate its matching row in the decision table.
2. For `Your feed is empty. Follow some users to see their articles here, or check out the Global Feed!`, follow the action in the matching decision-table row.
3. For `No articles are here... yet.`, follow the action in the matching decision-table row.
4. For `Loading articles...`, follow the action in the matching decision-table row.
5. Confirm that the article list appears.
6. For `Loading tags...`, follow the action in the matching decision-table row.
7. Confirm that the tags area appears.

**Result:** The message tells you whether to choose another list, continue waiting, or continue
with the available feed and article surfaces.

## Continue from an article or tag

After you choose an article or tag, continue on the page for that destination rather than
trying to complete that task from Home.

Steps

1. Select the article title or **Read more...** to open the article page.
2. Select a returned tag under **Popular Tags** to open its tag list.

**Result:** You are on the selected article page or the selected tag's article list.

<!-- source: sign-in.md -->

# Sign in

## Sign in to Conduit

The Login route is `/login`.

Sign-in is the authentication step that takes you from the public application into an authenticated
session.

| If you need to… | Go to |
|---|---|
| prepare the information needed for sign-in | [Before you start](#before-you-start) |
| open the sign-in surface | [Open the sign-in page](#open-the-sign-in-page) |
| identify the fields and error area | [Understand the sign-in screen](#understand-the-sign-in-screen) |
| submit your credentials | [Submit your sign-in details](#submit-your-sign-in-details) |
| create an account instead | [Create an account](doc:create-an-account) |
| understand shared authentication messages | [Authentication and loading messages](doc:authentication-and-loading-messages) |
| continue through the initial application journey | [Your first day](doc:your-first-day) |
| resolve a general authentication problem | [Common issues and solutions](doc:common-issues-and-solutions) |

## Before you start

**Prerequisites**

Have an email address and password ready. The Login route is available when the authentication
check allows access for an unauthenticated session.

| What you need | Why it matters |
|---|---|
| Email address | The sign-in form requires an email value. |
| Password | The sign-in form requires a password value. |

## Open the sign-in page

The Login page is where you enter the credentials for an existing account. If you need to create an
account, use the registration route instead.

**Prerequisites**

You are ready to authenticate an existing account, or you know that you need to create an account.

**Steps**

1. Open `/login`, then choose the route that matches your need.

   | If you need to… | Choose |
   |---|---|
   | sign in to an existing account | Stay on the Login page. |
   | create an account | Select **Need an account?** to open registration. |

**Result:** The sign-in form is open, or the registration form is open for account creation.

## Understand the sign-in screen

The sign-in screen contains two credential fields, one submit control, and an area for
authentication errors. The Username field belongs to registration, so the Login form uses Email and
Password instead.

| Screen item | What to enter or expect |
|---|---|
| **Email** | Enter the email address for the account. This field is required. |
| **Password** | Enter the account password. This field is required and accepts password input. |
| **Sign in** | Submit the sign-in form after the required fields contain values. |
| Username | This field appears on the registration form, not the Login form. |
| Authentication error area | A populated error list displays each returned error as a list item. |

When no errors are available, the error list is not displayed. When the service returns an
authentication error, the area can display `Invalid credentials`.

## Submit your sign-in details

Entering the required credentials and selecting **Sign in** sends the sign-in request. The form
prevents submission while it is invalid and disables its fieldset while the request is in progress.

**Prerequisites**

You have the account's email address and password, and the Login page is open.

**Steps**

1. Enter the account email address in **Email**.
2. Enter the account password in **Password**.
3. Select **Sign in**.

**Result:** The sign-in request is submitted. After a successful response, the application navigates
to `/`.

## Handle sign-in alternatives

The Login and Register routes support different account tasks. The Register route adds Username and
changes the submit title to **Sign up**.

**Prerequisites**

Decide whether you are authenticating an existing account or creating a new one.

**Steps**

1. Choose one route.

   | If you need to… | Use this route |
   |---|---|
   | authenticate an existing account | Use `/login` with Email and Password. |
   | create an account | Select **Need an account?** and use `/register` with Username, Email, and Password. |

**Result:** The form matches the account task: Login shows **Sign in**, while Register shows
**Sign up** and includes **Username**.

## When sign-in goes wrong

The authentication error area lists errors returned after a rejected sign-in request. Use the text
shown there to correct the credentials before submitting again.

| What you see | What it means | What to do |
|---|---|---|
| `Invalid credentials` | The submitted credentials were rejected. | Check **Email** and **Password**, then select **Sign in** again. |
| Each server error is displayed as `<key> <value>`. | The error area presents each returned entry using its key and value. | Read the displayed entry, correct the relevant credential, and submit again. |
| An error entry in the authentication error area | The service returned an error entry for the request. | Read the entry, correct the relevant credential, and submit again. |
| No error list | No authentication error needs attention. | Continue with the sign-in form. |

For the wider catalogue of shared messages, see [General error messages](doc:general-error-messages).

## Know what comes next

A successful sign-in takes you to the application's home route, where you can continue with the
authenticated application journey. The authentication flow is shared with account creation and
loading messages.

**Result:** After a successful sign-in, you are at `/` and can continue using the application.

Continue with [Your first day](doc:your-first-day), or review [Authentication and loading
messages](doc:authentication-and-loading-messages).

<!-- source: update-settings.md -->

# Update settings

## Update your settings

The Settings page is where you maintain your own account details after you sign in. Open
**Your Settings** when you need to change your profile picture URL, username, bio, email, or
password. The page is available at `/settings`.

The profile page links your own profile to this task through **Edit Profile Settings**. The
settings page supports creating, reading, and updating user information; it does not provide a
delete operation.

| If you need to… | Go to |
|---|---|
| Open the settings form | [Open Your Settings](#open-your-settings) |
| Identify a field or control | [Understand the Settings screen](#understand-the-settings-screen) |
| Change your account details | [Save your settings](#save-your-settings) |
| Change your password | [Change your password](doc:change-your-password) |
| Sign out | [Sign out](doc:sign-out) |
| Review the profile entry point | [View a profile](doc:view-a-profile) |

## Before you start

Your account settings are personal details associated with the signed-in user. You need to be
signed in before opening the Settings page, and you need the details you want to enter before
you begin.

**Prerequisites**

- You are signed in.
- You have the profile picture URL, username, bio, email, or new password you want to enter.
- You know which details you want to leave unchanged.

The form loads the current user's details when that user is available. The page does not use a
conditional field rule, so the same five settings fields are part of the form.

## Open Your Settings

Use **Edit Profile Settings** from your own profile, or open the authenticated `/settings` route
directly.

**Steps**

1. Choose one entry path:

   | If you need to… | Select or use |
   |---|---|
   | Open settings from your own profile | Select **Edit Profile Settings**. |
   | Open the authenticated route directly | Open `/settings`. |

**Result:** The Settings form opens with the five settings fields and its account controls.

## Understand the Settings screen

The Settings screen is a single form for your profile details and password. Its fields are the
places where you enter the values you want to maintain.

| Field | Use it to… | Input type |
|---|---|---|
| **URL of profile picture** | Enter the address of your profile picture. | Text |
| **Username** | Enter your username. | Text |
| **Short bio about you** | Enter your short biography. | Text area |
| **Email** | Enter your email address. | Email |
| **New Password** | Enter a new password. | Password |

Select **Update Settings** to submit the form. While a submission is in progress, the form
fields are disabled. The page also provides **Or click here to logout.** below the form.

## Save your settings

Change one or more details in **Your Settings** when needed. Leave a detail as it is when you do
not want to change it.

**Prerequisites**

- **Your Settings** is open.
- You know which values to enter.

**Steps**

1. Enter the profile picture address in **URL of profile picture** when you want to change it.
2. Enter the account name in **Username** when you want to change it.
3. Enter your description in **Short bio about you** when you want to change it.
4. Enter your address in **Email** when you want to change it.
5. Enter a new password in **New Password** when you want to change it.
6. Select **Update Settings**.
7. Review the returned user's profile.

The password field is included in the form, but an empty password is removed from the update
request. A successful update uses the returned user information and takes you to that user's
profile.

> **Note:** Leave **New Password** empty when you are not changing the password.

**Result:** Your settings are submitted, and a successful update opens the returned user's
profile.

## Choose an account-maintenance branch

The Settings form includes **New Password**, while the separate **Or click here to logout.**
control handles signing out. Use the branch that matches the task you need to complete.

**Steps**

1. Choose one account-maintenance task:

   | If you need to… | Select or use |
   |---|---|
   | Change the password as its own task | Select [Change your password](doc:change-your-password). |
   | Leave the account signed in and update profile details | Select [Save your settings](#save-your-settings). |
   | End the signed-in session | Select **Or click here to logout.** |

**Result:** You can continue with the account-maintenance task you selected.

## When an update goes wrong

The Settings error list contains the server response for an unsuccessful update.

**Prerequisites**

- **Your Settings** is open.
- You have selected **Update Settings**.

**Steps**

1. Read the item in the error list.
2. Review the error list after the update response finishes.

The screen renders each server error as `<key> <message>` in its error list.

| What you see | What it means | What to do |
|---|---|---|
| An item in the error list | The update response contains a server error. | Read the complete item before trying the update again. |
| The form does not remain available during submission | The form is disabled while the update is in progress. | Wait for the submission to finish before entering another value. |

**Result:** The error item is visible in the error list, and you know to review it before trying
the update again.

## Know what to do next

After a successful settings update, continue from the returned user's profile. To edit those
details again, use **Edit Profile Settings**, which opens `/settings` from your own profile.

If your next task is account security, use [Change your password](doc:change-your-password).
If you are finished with the account, use [Sign out](doc:sign-out).

**Result:** You know whether to continue with the profile, password, or sign-out task.

<!-- source: view-a-profile.md -->

# View a profile

## What a profile contains

A profile is a public view of a user's basic information and the articles that user has
created or favorited. Open it when you need to identify the user behind an article or review
that user's article lists.

| If you need to… | Go to |
|---|---|
| Find a profile from another part of the application | [Navigation basics](doc:navigation-basics) |
| Review the user's authored or favorited articles | [View My Posts and Favorited Posts](doc:view-my-posts-and-favorited-posts) |
| Follow another user | [Follow a user](doc:follow-a-user) |
| Edit your own profile information | [Update settings](doc:update-settings) |
| Understand this profile screen | [Understand the profile screen](#understand-the-profile-screen) |
| Open one of the profile's article lists | [Review a profile's article lists](#review-a-profiles-article-lists) |

## Before you start

The profile page uses a username in its destination to load the corresponding profile. You
need a profile link or another in-app route to the profile before you begin; do not replace the
username with a value from a different profile.

**Prerequisites**

- You have an in-app link to the profile you want to open.
- You know whether you are reviewing your own profile or another user's profile, because the
  profile header offers different controls in those two cases.

## Find and open a profile

An in-app profile destination opens the profile for the username carried by that destination.
Use this route when you need to review an existing user's information rather than enter new
profile data.

**Steps**

1. In an article's byline, select the link that displays the author's username.
2. Confirm that the profile information appears.

**Result:** The Profile screen opens for the selected username.

## Understand the profile screen

The profile screen identifies a user at the top and places that user's article list below the
profile header. It provides the user's profile image, username, and bio, followed by the article
list tabs **My Posts** and **Favorited Posts**.

The profile image appears above the username. The bio appears below the username; when no bio is
available, the profile shows an empty bio paragraph. The article list appears below the tabs.

| Area | What you use it for |
|---|---|
| Profile image | Recognize the profile visually. |
| Username | Confirm whose profile is open. |
| Bio | Read the user's short profile description. |
| Error area | Read a profile-load message when the profile cannot be loaded. |
| **My Posts** | Open articles created by the user whose profile is open. |
| **Favorited Posts** | Open articles favorited by the user whose profile is open. |
| Article list | Review the articles for the selected tab. |

The profile view displays profile information and article lists. Profile editing belongs in
[Update settings](doc:update-settings), rather than in the profile information area.

## Review a profile's article lists

The profile's article lists let you switch between articles created by the user whose profile is
open and articles that user has favorited.

**Prerequisites**

- The Profile screen is open.

**Steps**

1. Select the tab that matches what you want to review:

   | If you want to… | Select |
   |---|---|
   | Review articles created by the user whose profile is open | **My Posts** |
   | Review articles favorited by the user whose profile is open | **Favorited Posts** |

2. Review the article list below the tabs.

**Result:** The selected article list is displayed for the profile you opened.

## Profile variations

The profile header changes according to whether the open profile belongs to you or to another
user. This determines whether the header offers profile settings or a follow relationship
control.

| Profile you opened | Header option |
|---|---|
| Your own profile | **Edit Profile Settings** opens the settings page. |
| Another user's profile | A follow relationship control appears in the header. |

On another user's profile, the control displays a follow or unfollow action according to the
current relationship. Follow the dedicated [Follow a user](doc:follow-a-user) procedure for
that task. On your own profile, use [Update settings](doc:update-settings) to edit your profile
information.

## When the profile cannot load

The profile page displays its error area above the profile information when loading fails.

| What you see | What it means | What to do |
|---|---|---|
| `Failed to load profile` | The profile information did not load. | Return to the profile link and try opening the profile again. |

## What to do next

After reviewing the profile header, choose the next task from the profile's available
destinations:

| Condition | Next action or destination |
|---|---|
| You want to review articles created by the user whose profile is open | Select **My Posts**. |
| You want to review articles favorited by the user whose profile is open | Select **Favorited Posts**. |
| The profile belongs to you and you want to edit your profile information | Select **Edit Profile Settings** to continue in settings. |
| The profile belongs to another user and you want to manage the follow relationship | Continue with [Follow a user](doc:follow-a-user). |

For the two profile article-list destinations, see [View My Posts and Favorited Posts](doc:view-my-posts-and-favorited-posts).

**Result:** You have a clear next destination for the profile task you want to complete.

<!-- source: what-is-conduit.md -->

# What is Conduit

## What Conduit is

Conduit is a social blogging site and a Medium.com clone. You use it
to authenticate, create and manage articles, comment on articles, browse paginated article
lists, favorite articles, and follow other users.

| If you need to… | Go to |
|---|---|
| Understand who Conduit is for | [Who uses Conduit](doc:who-uses-conduit) |
| See the complete capability overview | [What can you do with Conduit](doc:what-can-you-do-with-conduit) |
| Sign in or create an account | [Sign in](doc:sign-in) or [Create an account](doc:create-an-account) |
| Reach your first feed | [Your first day](doc:your-first-day) |
| Find articles in a feed | [Find articles in feeds](doc:find-articles-in-feeds) |
| Browse articles by tag | [Browse articles by tag](doc:browse-articles-by-tag) |
| Read an article | [Read an article](doc:read-an-article) |
| Work with an article | [Article workspace](doc:article-workspace) |
| Understand the interface and routes | [Understanding the interface](doc:understanding-the-interface) or [Navigation basics](doc:navigation-basics) |
| Follow a user or favorite an article | [Follow a user](doc:follow-a-user) or [Favorite articles](doc:favorite-articles) |

## Before you start

Home is the place to find articles, rather than a form where you enter or save records. The
public **Global Feed** is available without signing in. **Your Feed** is available when you are
authenticated; it collects the following feed for your account.

**Prerequisites**

- To use **Global Feed**, have access to the Home page at `/`.
- To use **Your Feed**, sign in first. It shows articles from people you follow. Use [Sign in](doc:sign-in) if you are not authenticated.
- To browse articles by topic, start from Home with a topic link available in the **Popular Tags** area.

If you request that list without authentication, Conduit redirects you to `/login`.

When these conditions are ready, open Home.

A feed is an article list. A tag is a topic value that filters the article list.

## Open Home

Home is the article-finding surface at `/`. It brings together the feed choices, article list,
tag list, and article pagination in one place.

**Prerequisites**

- You know whether you want the public **Global Feed** or the authenticated **Your Feed**.

**Steps**

1. Open `/`.

**Result:** Home opens with the feed choices and the article-finding surface.

With Home open, choose the feed or topic that matches what you want to read.

## Choose a feed and browse articles

**Prerequisites**

- Home is open at `/`.
- You are signed in before choosing **Your Feed**.

**Steps**

1. Choose the list that matches what you want to read.

   | If you want to… | Select |
   |---|---|
   | Browse the public article list | **Global Feed** |
   | Browse articles from people you follow | **Your Feed** |
   | Browse articles marked with a topic | A tag in **Popular Tags** |

2. Select an article title or **Read more...** to open the article.

3. Select a page number when the article list has more than one page.

**Result:** The selected feed or tag determines the article list, and a selected article opens
the article surface.

Use the Home results to interpret what is loading, available, or empty.

## Understand the Home results

Home presents article previews alongside **Popular Tags**. The article area changes between
loading, loaded, and empty states; the sidebar changes between loading tags, showing tags, and
showing that no tags are available.

The tag tab appears when Home is filtered by a tag. The article area shows pagination in its
loaded state, with one page button for each available page.

Home does not provide fields to complete, a grid to edit, or a save or submit action. Use the
article pages for article work instead.

| What you see | What it means |
|---|---|
| `Loading articles...` | The article list is loading. |
| `Your feed is empty. Follow some users to see their articles here, or check out the Global Feed!` | The following feed has no articles; follow users or choose **Global Feed**. |
| `No articles are here... yet.` | The current global or tag-filtered list has no articles. |
| `Loading tags...` | The **Popular Tags** list is loading. |
| `No tags are here... yet.` | No tags are available in the sidebar. |

For feed-specific guidance, see [Loading and unavailable states](doc:loading-and-unavailable-states).

With the results understood, continue to the area that matches your next task.

## Continue from Home

Use Home to discover content, then continue to the surface that matches your next task. Conduit
includes sign-in and sign-up pages, an Editor page, an Article page, and a Profile page around the
Home experience. It also includes authentication,
article work, comments, favorites, and following.

| Next task | Continue with |
|---|---|
| Sign in or register | [Sign in](doc:sign-in) or [Create an account](doc:create-an-account) |
| Create or edit an article | [Create and edit an article](doc:create-and-edit-an-article) |
| Read, comment on, or favorite an article | [Read an article](doc:read-an-article), [Comment on an article](doc:comment-on-an-article), or [Favorite articles](doc:favorite-articles) |
| View profiles or follow users | [View a profile](doc:view-a-profile) or [Follow a user](doc:follow-a-user) |
| Personalize your account | [Update settings](doc:update-settings) |
| Get help with an error | [Getting help](doc:getting-help) or [General error messages](doc:general-error-messages) |

<!-- source: your-first-day.md -->

# 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) |

<!-- source: browse-articles-by-tag.md -->

# Browse articles by tag

## Browse articles by tag

A tag-filtered article list is the Home article list narrowed to one tag. Use it when you
want to find articles grouped under the same subject label. The list belongs to the Home
flow, alongside the lists reached through **Your Feed** and **Global Feed**.

| If you need to… | Go to |
|---|---|
| Open the list for a subject label | [Open a tag-filtered list](#open-a-tag-filtered-list) |
| Recognize the tag list and its messages | [Read the filtered list](#read-the-filtered-list) |
| Move through the results | [Browse the article pages](#browse-the-article-pages) |
| Continue to general route guidance | [Navigation basics](doc:navigation-basics) |
| Read an article from the list | [Read an article](doc:read-an-article) |

## Before you start

You need the tag you want to browse, either as a tag link on Home or as the tag value for the
tag route.

**Prerequisites**

- You have a tag value to open.
- If you start on Home, its tag list is available to select.

The tag route opens the Home article list for the tag value you provide. This task does not
require entering information in a form; open a tag instead.

**Result:** You have a tag value and a starting point for opening its filtered list.

## Open a tag-filtered list

Use a tag link when you are already on Home. If you already know the route value, open the
tag route directly.

**Prerequisites**

- You are on Home, or you know the tag value to use in the route.

**Steps**

1. Choose one route to open the list:

   | If you are trying to… | Do this |
   |---|---|
   | Browse a tag shown on Home | Select the tag for the subject you want in Home’s tag list. |
   | Open a known tag directly | Open the tag route with the tag value. |

   Each tag link on Home opens the tag route with the selected tag value.

**Result:** The Home article-list surface opens with the selected tag in its tag tab.

## Read the filtered list

The filtered list is the Home surface for finding articles under one tag. Read the active
tag in the tag tab, the article results in the main list, and the available page numbers
below the results.

| Area | What you use it for |
|---|---|
| **Your Feed** | Open the following feed when you are authenticated. |
| **Global Feed** | Open the general article list. |
| Tag tab | Confirm which tag filters the current list. |
| Article list | Read the articles returned for the selected list. |
| Page number | Move to an available page of results after the articles load. |
| Tag list | Choose another subject label from Home. |

The Home page contains a tag list, an article list from Feed, Global, or Tag, and pagination
for the article list. The tag tab appears when the route contains a tag, and the article
list uses that route value as its filter.

**Result:** You can tell which tag is active, where its articles appear, and which page
numbers are available.

## Browse the article pages

An article page is one numbered portion of the selected tag's results. Use the page numbers
to continue through the list without changing the tag filter.

**Prerequisites**

- The tag-filtered Home list is open.
- More than one article page is available.

**Steps**

1. Select the page number you want to read.
2. Read the articles shown for that page.

The article list requests 10 articles per page. When you select a page after page 1, the
route includes its `page` query parameter. Returning to page 1 removes that parameter; the
current feed parameter is preserved when one is present.

**Result:** The selected page of articles is displayed under the same tag filter. If a loading
or empty message appears, use [Handle loading and empty lists](#handle-loading-and-empty-lists).

## Handle loading and empty lists

The list gives you a different message while data is loading and when the completed request
contains no results. Use the message you see to decide whether to wait, choose another tag,
or switch to the general list.

| What you see | What to do |
|---|---|
| `Loading tags...` | Wait for the tag list to load. |
| `No tags are here... yet.` | Open the tag route with a tag value. |
| `Loading articles...` | Wait for the article list to load. |
| `No articles are here... yet.` | Select another tag link. |
| `Your feed is empty. Follow some users to see their articles here, or check out the Global Feed!` | Select **Global Feed** to open the general article list. |

**Result:** You know whether the list is still loading or has finished with no articles or
tags to display. When results are available, continue with [Continue from the article list](#continue-from-the-article-list).

## Continue from the article list

After browsing the filtered list, continue with the task that matches what you want to do
next.

| If you need to… | Go to |
|---|---|
| Learn the wider Home and route navigation | [Navigation basics](doc:navigation-basics) |
| Find articles in the general or following list | [Find articles in feeds](doc:find-articles-in-feeds) |
| Continue with loading and unavailable states | [Loading and unavailable states](doc:loading-and-unavailable-states) |
| Read an article you selected | [Read an article](doc:read-an-article) |

**Result:** You have either continued through the selected tag's article pages or moved to
the page for the next article-list task.

<!-- source: create-an-account.md -->

# Create an account

Create an account when you need to use Conduit's authenticated features for the first time.
Registration is available at `/register`.

| If you need to… | Go to |
|---|---|
| Check what registration is for | [Create an account](#create-an-account) |
| Confirm what you need before starting | [Before you start](#before-you-start) |
| Reach the registration form | [Open the Register screen](#open-the-register-screen) |
| Identify the fields and controls | [Understand the registration form](#understand-the-registration-form) |
| Submit your registration | [Enter details and sign up](#enter-details-and-sign-up) |
| Resolve an authentication error | [When registration goes wrong](#when-registration-goes-wrong) |
| Sign in with an existing account | [Sign in](doc:sign-in) |
| Read shared authentication messages | [Authentication and loading messages](doc:authentication-and-loading-messages) |

## Before you start

You need to be signed out to open the registration form. Have a username, email address, and
password ready before you begin.

| Before starting | What to have ready |
|---|---|
| Access | A signed-out session |
| Account name | The username you want to use |
| Contact | The email address for the account |
| Sign-in secret | The password for the account |

If you already have an account, use [Sign in](doc:sign-in) instead.

## Open the Register screen

The Register screen is the public entry point for creating a Conduit account.

**Prerequisites**

- You are signed out.

**Steps**

1. Open `/register` in your browser.

**Result:** The Register screen opens with the registration form.

## Understand the registration form

The registration form collects the three details needed to submit an account request and places
authentication errors above the form.

| What you need to do | Control or area | What it does |
|---|---|---|
| Enter the account name | **Username** | Accepts the username for the new account |
| Enter the account email | **Email** | Accepts the email address for the new account |
| Enter the sign-in secret | **Password** | Accepts the password as a password field |
| Submit the details | **Sign up** | Submits the registration form |
| Read a registration error | Authentication error area | Lists the response errors above the form |

**Username** appears for registration. **Email** and **Password** remain on the authentication
form. The form requires all three fields, and **Sign up** is unavailable while the form is
invalid. While submission is in progress, the form fields are disabled.

The inputs use their visible placeholder text rather than separate field labels. The screen does
not add a field-level validation message, confirmation dialog, or grid.

## Enter details and sign up

Use this procedure to send the three required account details and continue to the application's
main route after a successful response.

**Prerequisites**

- The Register screen is open.
- You have the username, email address, and password you want to submit.

**Steps**

1. Enter the account name in **Username**.
2. Enter the account email address in **Email**.
3. Enter the account password in **Password**.
4. Select **Sign up**.

**Result:** The registration request is submitted. A successful response takes you to `/`.

## When registration goes wrong

If registration returns an error, read it in the authentication error area above the form.

| What you see | What it means | What to do |
|---|---|---|
| An authentication error in the error list | The registration response contains one or more errors | Read the listed error and correct the relevant registration detail before selecting **Sign up** again |

Each API error is rendered as `<key> <value>` in an error list. No fixed authentication error text
is used by the registration screen.

[Authentication and loading messages](doc:authentication-and-loading-messages) covers shared
authentication messages outside this registration error area.

<!-- source: general-error-messages.md -->

# General error messages

Use an error list to read the messages the application displays together. `Each supplied error value is rendered as a separate list item.` Authentication status messages tell you whether the
application is still checking authentication or is waiting to reconnect.

Use this page when a message appears and you need to decide whether to wait, continue, or
open the related task or help page.

| If you need to… | Go to |
|---|---|
| Identify the message you see | [Recognize and respond to a message](#recognize-and-respond-to-a-message) |
| Handle an error that remains on screen | [When an error persists](#when-an-error-persists) |
| Resolve a sign-in message | [Sign in](doc:sign-in) |
| Resolve a registration message | [Create an account](doc:create-an-account) |
| Read about authentication and loading status messages | [Authentication and loading messages](doc:authentication-and-loading-messages) |
| Read about loading and unavailable states | [Loading and unavailable states](doc:loading-and-unavailable-states) |
| Review common application issues | [Common issues and solutions](doc:common-issues-and-solutions) |
| Get general help | [Getting help](doc:getting-help) |

## Before you start

**Prerequisites**

- If the header shows `Loading...`, allow the authentication check to continue.
- If the header shows `Connecting...`, the application is retrying authentication.

## Recognize and respond to a message

Use this procedure to identify the message branch and follow the supported response.

**Prerequisites**

- You can see the message on the current page or in the header.

**Steps**

1. Read the message exactly as it appears.
2. Match the message to the action you need:

   | If you see… | Do this |
   |---|---|
   | An error list | Read each list item before deciding what to correct. |
   | `Loading...` | Wait while authentication is checked. |
   | `Auth unavailable - retrying automatically` or `Connecting...` | Wait for the automatic authentication retry. |

3. Continue with the current task when the message clears.
4. Open [When an error persists](#when-an-error-persists) when the message remains on
   screen.

**Result:** You have identified the message branch and either continued when the message
cleared or moved to persistent-error guidance.

## When an error persists

A persistent error remains after the application has handled the action or authentication
check.

| What you see | What it means | Next page |
|---|---|---|
| One or more messages in an error list | The page received error values. | [Common issues and solutions](doc:common-issues-and-solutions) |
| `Auth unavailable - retrying automatically` with `Connecting...` | Authentication is temporarily unavailable and the application is retrying. | [Loading and unavailable states](doc:loading-and-unavailable-states) |
| A sign-in error | The sign-in form owns the authentication error area. | [Sign in](doc:sign-in) |
| A registration error | The registration form owns the authentication error area. | [Create an account](doc:create-an-account) |
The application classifies 4XX responses from its authentication check as invalid
authentication. It treats 5XX or network responses as temporarily unavailable, keeps the
authentication token for retry, and schedules automatic retries.

**Result:** You know which related page to open for the message that remains on screen.

<!-- source: read-an-article.md -->

# Read an article

## Read an article

An article is a published post whose body is written in markdown and presented with its
title, metadata—the author and publication date—tags, comments, and reader actions.

Use this page to open an article, read its content and metadata, and choose the next action.

| If you need to… | Go to |
| --- | --- |
| Find an existing article | [Find and open the article](#find-and-open-the-article) |
| Find articles in a feed | [Find articles in feeds](doc:find-articles-in-feeds) |
| Browse articles by tag | [Browse articles by tag](doc:browse-articles-by-tag) |
| Recognize the article screen | [Understand the article screen](#understand-the-article-screen) |
| Read the body and check its author or date | [Read the article and its metadata](#read-the-article-and-its-metadata) |
| Add a comment | [Comment on an article](doc:comment-on-an-article) |
| Favorite or unfavorite the article | [Favorite articles](doc:favorite-articles) |
| Use author-only article actions | [Article actions reference](doc:article-actions-reference) |

## Before you start

The article page displays a saved article when its article data is available. Your account state
changes which controls appear: authenticated readers get the comment form, while unauthenticated
readers get links to sign in or create an account.

**Prerequisites**

- Know which article to select from the article list, feed, or tag view.
- If you want to comment, select **Sign in** before opening the article.

## Find and open the article

Use this procedure to open an existing article from an article list or a tag view.

**Prerequisites**

- Have an article list, feed, or tag view open.

**Steps**

1. Choose the view that contains the article, then select the article you want to read.

   | If you are… | Select the article from… |
   | --- | --- |
   | Reading a feed or article list | The article list or feed. |
   | Browsing by subject | The tag view. |

The article page opens for the selected article.

**Result:** The selected article page is on screen.

## Understand the article screen

The article screen is the reading surface for one article: the title and metadata identify the
post, the markdown body contains its content, tags describe its subject, and the lower area
contains comments and reader actions.

| Area | What you find there |
| --- | --- |
| Article heading | The article title. |
| Article metadata | The author and publication date. |
| Article body | The article text formatted from markdown. |
| Tags | The article's tags below the body. |
| Article actions | Author actions, or follow and favorite controls for other readers. |
| Comment area | Existing comments and, for authenticated readers, the comment form. |

The page does not provide article-editing fields, a grid, or a configurable surface. Editing is
handled in the article workspace, while this page is for reading the article and its associated
activity.

## Read the article and its metadata

Read the article body first, then use the metadata to identify who published it and when.

**Prerequisites**

- Have the article page open.

**Steps**

1. Read the article title at the top of the page.
2. Read the article body below the title.
3. In the article metadata, read the author's name and publication date.

The author's name is a link to that author's profile.

**Result:** The article content, author, and publication date are on screen.

## Use the reading controls

The controls on the article page depend on whether you own the article or a comment, whether you
are signed in, and whether the article is already in your favorites.

**Prerequisites**

- Have the article page open.

**Steps**

1. Choose the action that matches your situation.

   | Your situation or goal | Select |
   | --- | --- |
   | You own the article and want to edit it | **Edit Article** |
   | You own the article and want to delete it | **Delete Article** |
   | You want to follow the author | **Follow** |
   | You want to stop following the author | **Unfollow** |
   | You want to save the article as a favorite | **Favorite Article** |
   | You want to remove the article from your favorites | **Unfavorite Article** |
   | You want to add a comment | Enter text in **Write a comment...**, then select **Post Comment**. |
   | You need to sign in | **Sign in** |
   | You need to create an account | **sign up** |

2. Use the handling shown for the action you selected.

   | Action | Handling |
   | --- | --- |
   | **Edit Article** | [Article workspace](doc:article-workspace) |
   | **Sign in** | [Sign in](doc:sign-in) |
   | **sign up** | [Create an account](doc:create-an-account) |
   | **Delete Article** | Select the control for the direct delete action. |
   | **Follow** or **Unfollow** | Select the control for the direct follow action. |
   | **Favorite Article** or **Unfavorite Article** | Select the control for the direct favorite action. |
   | **Post Comment** | Enter text in **Write a comment...**, then select the direct **Post Comment** action. |

**Result:** **Edit Article**, **Sign in**, and **sign up** take you to their linked pages. The
other controls start direct actions on the article page; **Delete Article** leads away after the
delete action, while follow, favorite, and comment actions remain on this page.

## Handle errors and continue

The article page displays loading and server-response errors in its error area.

**Prerequisites**

- Have the article page open.

**Steps**

1. Read the message in the error area.

   | What you see | What to do |
   | --- | --- |
   | `Failed to load article` | Return to the article list and open the article again. |
   | Returned errors show a key followed by its value. | Read the entry and use the matching next step in this table. |
   | **Sign in** and **sign up** instead of the comment form | Select **Sign in** or **sign up** before trying to comment. |
   | **Edit Article** and **Delete Article** | Use [Article actions reference](doc:article-actions-reference) for author-only actions. |
   | **Write a comment...** and **Post Comment** | Use [Comment on an article](doc:comment-on-an-article) to add a comment. |
   | **Favorite Article** or **Unfavorite Article** | Use [Favorite articles](doc:favorite-articles) to manage favorites. |

2. Select the next task from the message's matching row.

**Result:** You are back at the article list to retry loading, or you have continued to the
procedure or page that addresses the message.

<!-- source: sign-out.md -->

# Sign out of Conduit

Signing out ends your authenticated session. Use the protected **Settings** route when you
want to leave the signed-in part of Conduit.

| If you need to… | Go to |
|---|---|
| Open the page used for sign-out | [Open Settings](#open-settings) |
| Check why Settings is unavailable | [If you cannot open Settings](#if-you-cannot-open-settings) |
| Find **Or click here to logout.** below the form | [Find **Or click here to logout.** below the form](#find-or-click-here-to-logout-below-the-form) |
| End the session | [Sign out](#sign-out) |
| Maintain profile settings | [Update settings](doc:update-settings) |
| Change the password | [Change your password](doc:change-your-password) |
| Review authentication messages | [Authentication and loading messages](doc:authentication-and-loading-messages) |

## Before you start

You must be authenticated to open `/settings`. The route directs an unauthenticated request to
`/login`, and the sign-out control is available on the authenticated Settings surface.

## Open Settings

**Prerequisites**

You are signed in.

**Steps**

1. Open Settings using one of these paths:

   | If you are… | Do this |
   |---|---|
   | On a page with the authenticated navigation bar | Select **Settings**. |
   | Opening the route directly | Open `/settings`. |

**Result:** The `/settings` attempt either opens the authenticated Settings screen or directs an
unauthenticated request to `/login`.

## If you cannot open Settings

An unauthenticated session cannot use the protected Settings route.

**Prerequisites**

The `/settings` attempt did not open the authenticated Settings screen.

**Steps**

1. Choose the path that matches what you see:

   | What you see | Next action |
   |---|---|
   | The authenticated Settings page | Continue to [Find **Or click here to logout.** below the form](#find-or-click-here-to-logout-below-the-form). |
   | `/login` | Select [**Sign in**](doc:sign-in), then open `/settings` again after authentication. |

**Result:** You either have the Settings page ready for sign-out or a Login page ready for authentication.

## Find **Or click here to logout.** below the form

The Settings screen is the account-maintenance surface. Its heading is **Your Settings**. The
settings form has a separate **Update Settings** action, while the sign-out action sits below the
form.

| Screen area | Use |
|---|---|
| **Your Settings** | Compare the heading with the Settings page you intend to use. |
| Settings form | Leave the form unchanged when you only want to sign out. |
| **Update Settings** | Do not select this action when you only want to end the session. |
| **Or click here to logout.** | Select this action to end the authenticated session. |

The form uses input placeholder text rather than separate field captions. The screen has no
grid or column set, and sign-out has no fixed success, error, or confirmation message.

## Sign out

**Prerequisites**

The authenticated Settings screen is open.

**Steps**

1. Select **Or click here to logout.**.

**Result:** The session becomes unauthenticated, the token and current user are cleared, and the
app navigates to `/`.

## When sign-out does not complete

Sign-out is a direct action. It does not open a confirmation dialog or display a fixed
sign-out success or error message.

| What you see | What it means | What to do |
|---|---|---|
| No confirmation dialog appears | The sign-out action has no confirmation step. | Select **Or click here to logout.**. |
| No fixed success or error message appears | Sign-out has no fixed message. | Continue at `/` after selecting **Or click here to logout.**. |
| An error list appears on Settings | Each returned entry uses the format `<key> <message>`. | For settings changes, see [Update settings](doc:update-settings). |

## Know what happens next

After sign-out, authentication state is `unauthenticated`. The token is destroyed, the current
user is cleared, and navigation targets `/`.

<!-- source: understanding-the-interface.md -->

# Understanding the interface

## What the interface contains

This page covers **Home**, Article, and Profile, along with the shared header that connects them.

| If you need to… | Go to |
| --- | --- |
| Choose an article list or browse tags | [Find articles in Your Feed and Global Feed](doc:find-articles-in-feeds) or [Browse articles by tag](doc:browse-articles-by-tag) |
| Read, comment on, or favorite an article | [Read an article](doc:read-an-article), [Comment on an article](doc:comment-on-an-article), or [Favorite articles](doc:favorite-articles) |
| Create or change an article | [Create and edit an article](doc:create-and-edit-an-article) |
| View a person's posts or favorites | [View a profile](doc:view-a-profile) or [View My Posts and Favorited Posts](doc:view-my-posts-and-favorited-posts) |
| Follow a person | [Follow a user](doc:follow-a-user) |
| Find a route or tab | [Navigation basics](doc:navigation-basics) |
| Change account or workspace details | [Personalizing your workspace](doc:personalizing-your-workspace) |

## Before you start

The interface changes according to whether you are signed in and whether the Article or
Profile belongs to you. On **Home**, signed-in readers see **Your Feed** as well as
**Global Feed**. The public view has the banner and public header links instead.

On an Article, the owner sees **Edit Article** and **Delete Article**. Another reader sees
the available follow and favorite actions. On a Profile, the owner sees **Edit Profile Settings**;
another profile shows the available follow and favorite actions. These branches determine which action to choose.

The Article comment area follows the same access rule. A signed-in reader gets the comment
field and **Post Comment**. A signed-out reader gets **Sign in** or **sign up** instead.

**Prerequisites**

- Know whether you are signed in.
- For an Article, know whether you are viewing your own article.
- For a Profile, know whether it is your profile or another person's profile.
- Have the Article or Profile route you want to open.

## Choose a destination from the shared header

The shared header is the navigation strip at the top of each surface. Use it to move to a
destination without first returning to a list.

**Steps**

1. Choose the destination that matches your task:

   | If you need to… | Select |
   | --- | --- |
   | Open the Home surface | **Home** |
   | Sign in | **Sign in** |
   | Create an account | **Sign up** |
   | Start a new article | **New Article** |
   | Change account settings | **Settings** |
   | Open your profile | Your username in the header |

**Result:** The selected destination opens, and its own surface becomes available.

## Recognize the Home surface

**Home** is the article-discovery surface. Its feed selector, article list, and tag area
help you choose which articles to read.

Select **Your Feed** for the following feed when you are signed in. Select **Global Feed**
for the all-articles feed. When a tag filter is active, Home adds the selected tag as an
active feed item. The tag area is headed **Popular Tags**.

The article list can display these states:

| What you see | What it means |
| --- | --- |
| `Loading articles...` | The article list is loading. |
| `Your feed is empty. Follow some users to see their articles here, or check out the Global Feed!` | The following feed has no articles. |
| `No articles are here... yet.` | The loaded article list is empty. |
| `Loading tags...` | The tag list is loading. |
| `No tags are here... yet.` | No tags are available in the tag area. |

## Recognize the Article surface

An Article is the surface where you read an article and work with its related actions.
The page contains the article body and tags, followed by the comment area.

On an article preview, `Read more...` opens the full article.

Use the ownership branch at the top of the page:

| If you are viewing… | The page provides |
| --- | --- |
| Your own article | **Edit Article** and **Delete Article** |
| Another reader's article | the available follow and favorite actions |

When you are signed in, enter text in the comment field and select **Post Comment**.
The comment field is a textarea and is not marked as required. When you are signed out,
the comment form is replaced by **Sign in** or **sign up**.

If the article cannot load, the page can show `Failed to load article`.

## Recognize the Profile surface

A Profile is the surface for a person's identity and article lists. It shows the profile
image, username, biography, and the list selected by the profile tabs.

| If you are viewing… | The page provides |
| --- | --- |
| Your own profile | **Edit Profile Settings** |
| Another person's profile | the available follow and favorite actions plus the person's username |
| Authored articles | **My Posts** |
| Favorited articles | **Favorited Posts** |

Select **My Posts** to view the profile's authored articles, or select **Favorited Posts**
to view the profile's favorited articles. If the profile cannot load, the page can show
`Failed to load profile`.

## Interpret a message on these surfaces

Returned error entries use the format `<key> <value>` and appear as list items. Use the
message text to identify which action needs attention, then follow the task page for that
surface. Article and Profile load messages identify which surface could not load.

| Message or situation | Continue with |
| --- | --- |
| A returned error in the `<key> <value>` format | [General error messages](doc:general-error-messages) |

## Continue to the task you need

Identify the surface, then continue with the page that owns the work:

- From Home, continue to [Find articles in Your Feed and Global Feed](doc:find-articles-in-feeds),
  [Browse articles by tag](doc:browse-articles-by-tag), or [Loading and unavailable states](doc:loading-and-unavailable-states).
- From Article, continue to [Article workspace](doc:article-workspace), [Read an article](doc:read-an-article),
  [Create and edit an article](doc:create-and-edit-an-article), [Comment on an article](doc:comment-on-an-article),
  [Favorite articles](doc:favorite-articles), or [Article actions reference](doc:article-actions-reference).
- From Profile, continue to [View a profile](doc:view-a-profile),
  [View My Posts and Favorited Posts](doc:view-my-posts-and-favorited-posts), or [Follow a user](doc:follow-a-user).
- For account entry, continue to [Sign in](doc:sign-in) or [Create an account](doc:create-an-account).
- For account and workspace changes, continue to [Personalizing your workspace](doc:personalizing-your-workspace).
- For authentication messages, continue to [Authentication and loading messages](doc:authentication-and-loading-messages).
- For common problems, continue to [Common issues and solutions](doc:common-issues-and-solutions).

<!-- source: view-my-posts-and-favorited-posts.md -->

# View My Posts and Favorited Posts

## Overview

A profile's **My Posts** list contains articles written by that profile. **Favorited Posts**
contains articles that profile has marked as favorites. Use the first list to find the profile's own
articles and the second to revisit articles the profile chose to keep.

| If you need to… | Go to |
|---|---|
| Find articles written by the profile | [Switch between My Posts and Favorited Posts](#switch-between-my-posts-and-favorited-posts) |
| Revisit articles the profile has favorited | [Switch between My Posts and Favorited Posts](#switch-between-my-posts-and-favorited-posts) |
| Read an article from either list | [What to do next](#what-to-do-next) |
| Open a profile and review its basic information | [View a profile](doc:view-a-profile) |
| Find your way around profile destinations | [Navigation basics](doc:navigation-basics) |

## Prerequisites

Before you start, have an article preview with an author name at its top. The profile information
and its two list tabs appear after the profile loads. If you plan to use the favorite action on an
article, use the signed-in route required for that action.

## Find and open a profile

Open the profile from the author name so the application supplies the profile to the parameterized
profile route.

**Prerequisites**

- You are on a page that contains a profile link.

**Steps**

1. Select the author name at the top of the article preview.
2. When the profile page finishes loading, select the list that matches your task:

   | If you need to… | Select |
   |---|---|
   | Review articles written by the profile | **My Posts** |
   | Review articles the profile has favorited | **Favorited Posts** |

   The profile page uses the profile route, and its list tabs use the profile route's empty child
   route and `favorites` child route.

**Result:** The profile page is open with the list you selected.

## Understand the profile lists

The profile area identifies the profile with its username and bio, then places the two article
lists below the profile information. The lists show articles rather than editable article fields.

| Surface | What you use it for |
|---|---|
| Username | Identify the profile currently open |
| Bio | Read the profile's description |
| **My Posts** | Open articles authored by the profile |
| **Favorited Posts** | Open articles favorited by the profile |
| Article results | Open or review articles returned for the selected list |
| Page numbers | Move through additional result pages when they are available |

While the list loads, it displays `Loading articles...`. If the selected list has no results, it
displays `No articles are here... yet.`

## Switch between My Posts and Favorited Posts

Use this procedure when you want to compare the profile's authored articles with the articles the
profile has favorited.

**Prerequisites**

- You have opened the profile page.

**Steps**

1. Select **My Posts**.
2. Review the authored-article list.
3. Select **Favorited Posts**.
4. Review the favorited-article list.

**Result:** The profile's favorited-article list is open. Select **My Posts** whenever you need to
return to the profile's authored articles.

## Handle list variations

Each selected list can show a loading message, no results, one page, or several pages. Article
previews also provide actions for opening an article and changing its favorite state.

| What you see | What to do |
|---|---|
| `Loading articles...` | When the message appears, continue after the article results or empty-list message appears. |
| `No articles are here... yet.` | Select the other list if you need to check the profile's other collection. |
| More than one page number | Select the page number you need. |
| An article preview | Select **Read more...** to open that article. |
| The favorite action on an article preview | Select the favorite action to change the article's favorite state. |

**Prerequisites**

- You have opened either **My Posts** or **Favorited Posts**.

**Steps**

1. When `Loading articles...` appears, continue after the article results or empty-list message appears.
2. If the list has more than one page, select the required page number.
3. If you want to open an article, select **Read more...** on its preview.

**Result:** The selected article page is open, or the requested result page is displayed.

## When profile loading goes wrong

If the profile cannot load, the profile page uses the message `Failed to load profile`.

| What you see | What it means | What to do |
|---|---|---|
| `Failed to load profile` | The profile page could not load the requested profile. | Return to the page with the in-app profile link and select the profile again. |

## What to do next

After you find the article or profile action you need, continue with the page that owns that work.

| If you want to… | Continue with |
|---|---|
| Read the selected article | [Read an article](doc:read-an-article) |
| Change an article's favorite state | [Favorite articles](doc:favorite-articles) |
| Follow the profile | [Follow a user](doc:follow-a-user) |
| Change your profile settings | [Update settings](doc:update-settings) |

Select **Read more...** on an article preview to open the selected article.

<!-- source: who-uses-conduit.md -->

# Who uses Conduit

## What Conduit is for

A profile is a user's basic information together with the user's authored or favorited articles.
Conduit lets you browse articles, follow users, and join article conversations through comments. The
home page brings together tags and articles.

| If you need to… | Go to |
|---|---|
| Browse the full article list | [Find articles in feeds](doc:find-articles-in-feeds) |
| Browse articles by a subject tag | [Browse articles by tag](doc:browse-articles-by-tag) |
| Open a user's information and article lists | [View a profile](doc:view-a-profile) |
| Review a user's authored or favorited articles | [View my posts and favorited posts](doc:view-my-posts-and-favorited-posts) |
| Follow a user | [Follow a user](doc:follow-a-user) |
| Read an article | [Read an article](doc:read-an-article) |
| Add a comment | [Comment on an article](doc:comment-on-an-article) |
| Mark an article as a favorite | [Favorite articles](doc:favorite-articles) |

## Before you start

Your account determines which feed and profile actions are available. **Your Feed** appears for an
authenticated user. A profile's information and profile actions appear when the profile is available.

Before you start, use this checklist:

| Check | What to have ready |
|---|---|
| Account | Sign in if you need **Your Feed**. |
| Content | Know whether you want the full article list, a tag-filtered list, or a user's profile. |
| Profile | Be ready to select an author's name beside an article. |

## Find people and content

Use the home screen to choose a feed or a tag, or select an author's name beside an article to open
that author's profile. The home page lists articles pulled from the following feed, the global feed,
or a tag.

Prerequisites

- You know whether you want all articles, articles from followed users, or articles under a tag.
- You can select an author's name beside an article to open the profile you want.

Steps

1. Select one destination from the table.

   | If you want to… | Select |
   |---|---|
   | Browse all articles | **Global Feed** |
   | Browse articles from users you follow | **Your Feed** |
   | Browse articles under a subject | the tag you need from the list beneath **Popular Tags** |
   | Inspect an author's profile | the author's name beside the article you want to inspect |

**Result:** The selected feed, tag list, or profile opens.

## Understand the feed and profile surfaces

The feed surface combines feed choices, subject tags, and the article list. The profile surface
combines basic user information with two article-list choices: **My Posts** and **Favorited Posts**.

| Surface | What you use it for |
|---|---|
| **Popular Tags** | Choose a subject tag for the article list. |
| Profile image | Recognize the displayed profile. |
| Username | Identify whose profile is open. |
| Bio | Read the displayed user's short description. |
| **My Posts** | Open the displayed user's authored article list. |
| **Favorited Posts** | Open the displayed user's favorited article list. |
| Error area | Read profile-loading errors when they appear. |

## Choose what to do with a profile

A profile gives you two article lists, and your own profile also offers **Edit Profile Settings**.

Prerequisites

- A profile is open and its information is available.

Steps

1. Select one profile destination from the table.

   | If you need to… | Select |
   |---|---|
   | Review the displayed user's authored articles | **My Posts** |
   | Review the displayed user's favorited articles | **Favorited Posts** |
   | Change your own profile information | **Edit Profile Settings** |

To follow another user, continue to [Follow a user](doc:follow-a-user).

**Result:** The selected profile list or profile settings destination opens.

## Choose the next content activity

The feed you choose answers a different reading need: the global list shows all available articles,
the following list focuses on users you follow, and a tag list narrows articles to a subject.

Prerequisites

- You have opened the home feed or a profile article list.

Steps

1. Choose the content path that matches your goal.

   | If you need to… | Continue with |
   |---|---|
   | Read an article | [Read an article](doc:read-an-article) |
   | Discuss an article | [Comment on an article](doc:comment-on-an-article) |
   | Mark an article as a favorite | [Favorite articles](doc:favorite-articles) |
   | Follow the article's author | [Follow a user](doc:follow-a-user) |

**Result:** The dedicated article or profile task is ready to continue.

## When content is unavailable

The home screen has two tag-list states: it can show `Loading tags...` while tags are loading, or
`No tags are here... yet.` when the loaded list is empty. A profile also has an error area that
appears when profile errors are present.

| What you see | What to do |
|---|---|
| `Loading tags...` | Wait for the tag list to finish loading. |
| `No tags are here... yet.` | Continue with **Global Feed** or **Your Feed**, or open a profile. |
| The profile error area | Read the message shown there before trying the profile again. |

## Continue with the selected activity

After choosing a feed or profile list, continue with the page that owns the next activity:

| Next activity | Continue with |
|---|---|
| Find articles in a feed | [Find articles in feeds](doc:find-articles-in-feeds) |
| Browse a subject tag | [Browse articles by tag](doc:browse-articles-by-tag) |
| Read article content | [Read an article](doc:read-an-article) |
| Add a comment | [Comment on an article](doc:comment-on-an-article) |
| Favorite an article | [Favorite articles](doc:favorite-articles) |
| Follow a user | [Follow a user](doc:follow-a-user) |
| Review profile article lists | [View my posts and favorited posts](doc:view-my-posts-and-favorited-posts) |

The article list beneath a feed or profile leads to the relevant article or profile-list activity.

<!-- source: authentication-and-loading-messages.md -->

# Authentication and loading messages

Authentication messages tell you which authentication form is open or whether the
application is still resolving authentication. Use this page when you are choosing
between **Sign in** and **Sign up**, waiting for the authentication state, or interpreting the
header while authentication is temporarily unavailable.

| If you need to… | Go to |
|---|---|
| Enter credentials for an existing account | [**Sign in**](doc:sign-in) |
| Create an account | [Create an account](doc:create-an-account) |
| Understand loading or unavailable states | [Loading and unavailable states](doc:loading-and-unavailable-states) |
| Resolve an authentication error | [General error messages](doc:general-error-messages) |
| Find broader troubleshooting guidance | [Common issues and solutions](doc:common-issues-and-solutions) |

## Before you start

You can use the authentication forms at `/login` and `/register`. The forms ask for
the information in this table.

| Form | Information |
|---|---|
| **Sign in** | **Email** and **Password** |
| **Sign up** | **Username**, **Email**, and **Password** |
| Both forms | The form's submit action is **Sign in** or **Sign up**, according to the route |

Have the information for the selected form ready before you open it.

## Open the authentication form

Use the form that matches what you need to do. The authentication page provides a link
to the other form so you can change your choice without using the browser address bar.

Steps

1. Choose one option:

   | If you need to… | Select |
   |---|---|
   | Enter credentials for an existing account | **Sign in** |
   | Create a new account | **Sign up** |

2. Change forms when needed:

   | If you are on… | Select to change forms |
   |---|---|
   | **Sign in** | **Need an account?** |
   | **Sign up** | **Have an account?** |

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

## Understand the form

**Sign in** is the form for an existing account. **Sign up** is the form for creating an
account. The route determines which form-specific field and submit label appear.

| On the form | Fields | Submit action |
|---|---|---|
| **Sign in** | **Email**, **Password** | Select the **Sign in** button |
| **Sign up** | **Username**, **Email**, **Password** | Select the **Sign up** button |

The **Username** field belongs to **Sign up**. **Sign in** uses **Email** and
**Password**. The form requires **Email** and **Password** on both routes, and
**Username** on **Sign up**.

The submit action is disabled while the form is invalid. During submission, the form
fields are disabled until the request finishes.

With the correct form and information identified, continue to the submission steps.

## **Sign in** or create an account

Complete the form that matches your route. Use **Sign in** for an existing account and
**Sign up** for a new account.

Prerequisites

- You are on the correct form.
- You have the information required by that form.

Steps

1. Enter the account details for your form:

   | If you are on… | Enter… |
   |---|---|
   | **Sign in** | The account email in **Email** and the account password in **Password** |
   | **Sign up** | The new account name in **Username**, the account email in **Email**, and the account password in **Password** |

2. Submit the form:

   | If you are on… | Select |
   |---|---|
   | **Sign in** | Select the **Sign in** button |
   | **Sign up** | Select the **Sign up** button |

**Result:** After successful authentication, the application navigates to the home
route.

## When a message appears

The header uses short messages while authentication is being resolved or temporarily
unavailable.

| Message | Meaning |
|---|---|
| `Loading...` | Authentication state is loading. |
| `Auth unavailable - retrying automatically` | Authentication is temporarily unavailable and retrying automatically. |
| `Connecting...` | The header is showing the temporary unavailable state. |

If an authentication request returns an error, the authentication page displays the
returned error values in its error area and allows submission again.

Use the message that appears while the request is resolving to decide what to do next.

## Continue from authentication

After successful authentication, continue on the home route. For the task-specific
steps, use [**Sign in**](doc:sign-in) or [Create an account](doc:create-an-account).
For state messages, use [Loading and unavailable states](doc:loading-and-unavailable-states).
For error guidance, use [General error messages](doc:general-error-messages) and
[Common issues and solutions](doc:common-issues-and-solutions).

<!-- source: change-your-password.md -->

# Change your password

## Change your password

Changing your password is an account-maintenance task on the authenticated Settings page.
Use it when you need to replace the password for your signed-in account.

| If you need to… | Go to |
| --- | --- |
| Open the page that contains **New Password** | [Open Your Settings](#open-your-settings) |
| Check the password field and its rules | [Understand the password field](#understand-the-password-field) |
| Save a replacement password | [Save a new password](#save-a-new-password) |
| Work with the other profile fields | [Update settings](doc:update-settings) |
| Sign out | [Sign out](doc:sign-out) |

## Before you start

**Prerequisites**

- You are signed in. The Settings route is protected by authentication.
- You have the new password ready before you begin.
- You are working with the current user's Settings page.

## Open Your Settings

Your Settings is the account page where you edit the signed-in user's profile details and
password.

**Prerequisites**

- You are signed in.

**Steps**

1. Open the Settings page from your account navigation.

**Result:** Your Settings is open and contains the **New Password** field.

## Understand the password field

**New Password** is a password input for replacing the password used to sign in.

| What you see | What to do |
| --- | --- |
| **New Password** | Enter the replacement password here. |
| A password input | Type the value without displaying it as ordinary text. |
| **Update Settings** | Submit the Settings form after entering the replacement password. |

The password field has a required rule. The page does not show a visible required marker next
to the field, and it does not declare a password format, length, or confirmation rule.
The form fields are disabled while the update is being submitted.

## Save a new password

Changing the password updates the signed-in user's Settings form through **Update Settings**.

**Prerequisites**

- Your Settings page is open.
- You know the replacement password.

**Steps**

1. Select **New Password**.
2. Enter the replacement password.
3. Select **Update Settings**.

When the password field is empty, the update removes the password from the submitted data.
Enter a replacement value when your task is to change the password.

**Result:** After a successful update, your new password is saved.

## Handle an empty or valid password

The password field gives you two ways to leave the Settings form: submit it with **New Password**
empty, or enter a replacement value before selecting **Update Settings**.

**Prerequisites**

- Your Settings page is open.
- You know whether you are preserving the current password or replacing it.

**Steps**

1. Choose the path that matches your task:

   | If you need to… | Do this |
   | --- | --- |
   | Keep the current password | Leave **New Password** empty, then select **Update Settings**. |
   | Replace the current password | Enter a value in **New Password**, then select **Update Settings**. |

**Result:** The Settings update has been submitted through the path you selected.

## When the password change goes wrong

The Settings page displays errors in a list. Each item combines an error key and
its message.

**Prerequisites**

- You have submitted the Settings form.

**Steps**

1. Read the error key and its message in the error list.
2. Select **New Password**.
3. Enter a corrected value.
4. Select **Update Settings** to retry the update.

**Result:** The corrected password update is submitted again.

For application-wide error guidance, see [General error messages](doc:general-error-messages).

## Know what to do next

After a successful Settings update, the application navigates to the returned user's profile.
Continue with [View a profile](doc:view-a-profile) there.

If you need to edit **URL of profile picture**, **Username**, **Short bio about you**, or **Email**,
use [Update settings](doc:update-settings). If you need to leave the account, use [Sign out](doc:sign-out).

<!-- source: common-issues-and-solutions.md -->

# Common issues and solutions

## Common issues and solutions

Use this page when you are starting Conduit, signing in, waiting for authentication,
or opening a route that depends on your authentication state.

| If you need to… | Go to |
|---|---|
| Start the application and reach Home | [Set up the application and reach Home](#set-up-the-application-and-reach-home) |
| Sign in or create an account | [Sign in or create an account](#sign-in-or-create-an-account) |
| Interpret `Loading...` or `Connecting...` | [Recognize loading and unavailable authentication](#recognize-loading-and-unavailable-authentication) |
| Understand why a route does not open | [Handle guarded routes and settings access](#handle-guarded-routes-and-settings-access) |
| Work through an authentication or setup problem | [Troubleshoot authentication, setup, and settings problems](#troubleshoot-authentication-setup-and-settings-problems) |

## Before you start

Have the following ready before you begin:

| What you need | Why it matters |
|---|---|
| Bun | Conduit requires Bun to run the setup and start commands. |
| The setup sequence | Run `bun run setup`, then `bun run start`. |
| The correct authentication state | Settings requires authentication. Login and Register are for unauthenticated access. |

Keep the account details you need for the Login or Register form ready before you start.
On Settings, enter a new password only when you want to change it.

## Set up the application and reach Home

Home is the starting surface for the article feeds. The application loads it at `/`, where
you can use **Your Feed** when authenticated or **Global Feed** otherwise.

**Prerequisites**

- Have Bun installed.
- Have the project available locally.

**Steps**

1. In a terminal, enter the command `bun run setup`.
2. Run `bun run start`.
3. Open `/`.
4. Select **Global Feed** to view the global feed.
5. Select **Your Feed** when you are authenticated and want the following feed.

**Result:** Home opens at `/` with the feed choices available according to your
authentication state. You can now continue to Login or Register.

## Sign in or create an account

Login authenticates an existing account with **Email** and **Password**. Register creates
an account with **Username**, **Email**, and **Password**.
Login requires **Email** and **Password**. Register requires **Username**, **Email**, and
**Password**.

**Prerequisites**

- Be unauthenticated.
- Have an account for Login, or be ready to create one with Register.

**Steps**

1. Choose the route that matches what you need:

   | If you need to… | Open |
   |---|---|
   | Access an existing account | `/login` |
   | Create an account | `/register` |

2. Complete the fields for the route:

   | Route | Fields |
   |---|---|
   | `/login` | **Email** and **Password** |
   | `/register` | **Username**, **Email**, and **Password** |

3. Choose the account action that matches your route:

   | If you need to… | Select |
   |---|---|
   | Submit Login | **Sign in** |
   | Submit Register | **Sign up** |
   | Move from Login to Register | **Need an account?** |
   | Move from Register to Login | **Have an account?** |

**Result:** A successful sign-in or registration navigates to `/`. Continue to [Recognize
loading and unavailable authentication](#recognize-loading-and-unavailable-authentication).

## Recognize loading and unavailable authentication

The header communicates whether Conduit is still checking authentication or is retrying
after an unavailable authentication service.

| What you see | Meaning in the application flow |
|---|---|
| `Loading...` | Authentication is loading. |
| `Connecting...` | Authentication is unavailable and the application is retrying. |
| `Auth unavailable - retrying automatically` | The title on the retry status. |

The authentication service treats a 4XX response while loading `/user` as invalid
authentication and purges it. A 5XX or network error keeps the token and enters the
unavailable state. Retry delays are 2, 4, 8, and then 16 seconds, with 16 seconds as the
cap.

## Handle guarded routes and settings access

Settings is an authenticated route. Login and Register are routes for unauthenticated
readers, so the application applies the opposite route condition to them.

**Prerequisites**

- Know whether you are currently authenticated.
- Open `/settings` only when you are authenticated.

**Steps**

1. Open `/settings`.
2. Choose the route that matches your authentication state:

   | If you are… | Do this |
   |---|---|
   | Unauthenticated | Open `/login` and complete the sign-in procedure. |
   | Authenticated and managing account details | Select **Settings**. |

**Result:** Authenticated access can continue to Settings; unauthenticated access to
Settings is directed to `/login`.

## Troubleshoot authentication, setup, and settings problems

Use the message on screen to choose the next action. Authentication and Settings display
API error values in the error list.

**Prerequisites**

- Have the Login, Register, or Settings screen open.
- Have the message you need to resolve visible on screen.

**Steps**

1. Read the message shown on screen.
2. Choose the response that matches the message:

   | If you see… | Meaning | Do this |
   |---|---|---|
   | `Loading...` | The application has not finished checking authentication. | Wait until the authentication state resolves. |
   | `Connecting...` | The authentication check is retrying. | Allow the retry state to continue. |
   | `Auth unavailable - retrying automatically` | The header reports unavailable authentication. | Check the authentication state again after the retry. |
   | An API error value | The submitted request returned an error value. | Review the displayed value. Edit the submitted fields to correct the displayed problem. Select **Sign in**, **Sign up**, or **Update Settings** to submit the form again. |

The application retries unavailable authentication at 2, 4, 8, and 16-second intervals,
then continues at the 16-second cap.

**Result:** The message remains available while the application is loading or retrying, or
the form is ready for another submission after you correct the displayed problem.

## Continue with the related task

Continue with the page that owns the next action:

- [Sign in](doc:sign-in) for the Login procedure.
- [Create an account](doc:create-an-account) for registration.
- [Authentication and loading messages](doc:authentication-and-loading-messages) for the message reference.
- [Loading and unavailable states](doc:loading-and-unavailable-states) for loading-state handling.
- [Update settings](doc:update-settings) for changing account details.
- [Sign out](doc:sign-out) for ending the authenticated session.
- [General error messages](doc:general-error-messages) for application error messages.
- [FAQ](doc:faq) for broader questions.

<!-- source: create-and-edit-an-article.md -->

# Create or edit an article

An article is a post that you create in the editor and then open on its article page.
The article editor is the form for entering or revising its title, description, body, and
tags. Use the blank editor to create an article, or open an article that you own to change
it. Selecting **Publish Article** sends either a create request or an update request,
depending on which editor route you opened.

| If you need to… | Go to |
|---|---|
| Create a new article | [Open the editor](#open-the-editor), then follow [Enter article details and publish](#enter-article-details-and-publish). |
| Change an article you own | [Open the editor](#open-the-editor), then follow [Handle create, edit, and tag variations](#handle-create-edit-and-tag-variations). |
| Read the article after publishing | [Read an article](doc:read-an-article). |
| Use the article's other actions | [Article workspace](doc:article-workspace) and [Article actions reference](doc:article-actions-reference). |

## Before you start

Both editor routes require you to be signed in. For an existing article, the editor loads
the article and the current user, then fills the form only when that user is the article's
author.

**Prerequisites**

| Before you begin | What to have ready |
|---|---|
| Sign-in | An authenticated session. |
| New article | The title, short description, article text, and any tags you want to add. |
| Existing article | An article that you own. |
| Existing article values | The article's saved title, description, body, and tags appear in the editor when the ownership check succeeds. |

The new editor starts its title, description, and body controls with empty strings. The
tag input also starts empty.

## Open the editor

Use the new-article link for a blank form. Use an article's **Edit Article** link when you
want to revise an article you own.

**Steps**

1. Select the link for the work you need.

   | If you need to… | Select |
   |---|---|
   | Create a new article | **New Article** |
   | Revise an article you own | **Edit Article** |

**Result:** The article editor opens with the four article inputs and **Publish Article**.

## Understand the editor

The editor contains three article-content controls, one tag input, a tag list, and
**Publish Article**. The first three controls hold the article itself; the tag input adds
labels that appear with it.

| Area | What you use it for | What you see |
|---|---|---|
| Title | Enter the article title. | **Article Title** |
| Description | Enter the article's short description. | **What's this article about?** |
| Body | Enter the article text in Markdown. | **Write your article (in markdown)** |
| Tags | Add article tags. | **Enter tags** |
| Publication | Submit the new or changed article. | **Publish Article** |

The four inputs have no required marker declared for them. To add a tag, enter it in
**Enter tags** and press Enter. A tag already in the list, or a tag containing only
spaces, is not added. Each tag in the tag list has an icon before its tag text; selecting
that icon removes the tag.

While submission is in progress, the editor's form controls are disabled. This includes
the article inputs, the tag input, and **Publish Article**.

## Enter article details and publish

Enter the article's identifying text first, then its body and tags. Publishing uses the
same control for both routes: the new-article route creates an article, while the edit route
updates the article loaded by that route.

**Prerequisites**

- You are signed in.
- The editor is open.
- For an edit, the loaded article belongs to you.

**Steps**

1. In **Article Title**, enter the title.
2. In **What's this article about?**, enter the short description.
3. In **Write your article (in markdown)**, enter the article text.
4. In **Enter tags**, enter a tag.
5. Press Enter to add the tag to the tag list.
6. Repeat steps 4 and 5 for each tag you want to add.
7. Select **Publish Article**.

   | Editor route | What the control submits |
   |---|---|
   | New-article route | A new article without an article identifier. |
   | Edit route | An update containing the loaded article's route identifier. |

**Result:** After a successful create or update request, the application navigates to the
article route for the submitted article.

## Handle create, edit, and tag variations

The editor chooses between creating and updating from the route. A new-article route has
no article identifier, while an edit route has an article identifier and loads the existing
article before filling the form. The edit form also loads the article's saved tag list when
the ownership check succeeds.

| If you are… | Use this behaviour |
|---|---|
| Creating an article | Start with the new-article route; **Publish Article** calls the create path. |
| Editing your article | Start from **Edit Article**; **Publish Article** calls the update path. |
| Adding a new tag | Enter a nonblank tag that is not already in the list, then press Enter; the input clears. |
| Re-entering an existing tag | The duplicate is ignored. |
| Entering only spaces | The blank tag is ignored. |
| Removing a tag | Select the icon beside that tag. |
| Editing an article you do not own | The application returns you to the home page. |

**Steps**

1. For an existing article, review the saved values in **Article Title**, **What's this
   article about?**, and **Write your article (in markdown)** before you edit them.
2. In **Enter tags**, enter a nonblank tag that is not already listed.
3. Press Enter to add the tag.
4. Select the removal icon beside a listed tag when you want to remove it.

**Result:** The tag list contains each accepted tag once, and removed tags no longer appear
in the list.

## When submission goes wrong

**Prerequisites**

- An error is displayed above the form.

**Steps**

1. Read the displayed error.
2. Correct the related information in **Article Title**, **What's this article about?**,
   **Write your article (in markdown)**, or **Enter tags**.
3. Select **Publish Article** again.
4. When the form becomes available, read the displayed error again if it remains.

**Result:** The form becomes available again after the submission finishes.

## Know what happens next

After a successful create or update, the editor opens the submitted article at its article
route. Continue there to read the article or use its article actions.

**Result:** The submitted article page is open.

Continue with [Read an article](doc:read-an-article), [Article workspace](doc:article-workspace),
or [Article actions reference](doc:article-actions-reference).

<!-- source: follow-a-user.md -->

# Follow a user

A **Profile** page identifies a user and lists that user's articles. Use it to review basic
information and change whether you follow them.

## Follow another user

The follow task belongs on the **Profile** page, alongside the user's basic information and
article lists.

| If you need to… | Go to |
|---|---|
| Open an existing user's profile | [View a profile](doc:view-a-profile) |
| Read the user's posts or favorites | [View My Posts and Favorited Posts](doc:view-my-posts-and-favorited-posts) |
| Follow or unfollow the user | Before you start, then [Follow or unfollow the user](#follow-or-unfollow-the-user) |
| Change your own profile settings | [Update settings](doc:update-settings) |
| Sign in before changing the relationship | [Sign in](doc:sign-in) |

## Before you start

**Prerequisites**

- Know the username for the profile you want to open.
- Open a profile that has loaded before selecting **Follow <username>** or **Unfollow <username>**.
- Sign in before following or unfollowing a user.

Open the user's **Profile** page using their username. If you select **Follow <username>** or
**Unfollow <username>** while you are not signed in, the application takes you to [Sign in](doc:sign-in)
instead of calling the follow or unfollow operation.

## Find and open the profile

Use this task to open an existing user's profile. The profile route accepts the username as its
parameter; creating a user is a separate task.

**Steps**

1. Open the Profile route for the user whose username you want to view.

**Result:** The user's profile page opens when the profile data is available.

## Read the profile header

The profile header is the area that identifies the user before you change the following
relationship.

| Information | What appears on the page |
|---|---|
| Profile image | The user's image, with a default image applied when needed |
| Username | The user's username |
| Bio | The user's biography, or an empty area when no biography is available |

The article area provides two destinations:

| If you need to… | Select |
|---|---|
| Read articles created by the user | **My Posts** |
| Read articles the user has favorited | **Favorited Posts** |

For another user's profile, **Follow <username>** or **Unfollow <username>** appears in the
header. For your own profile, **Edit Profile Settings** appears instead and opens [Update settings](doc:update-settings).

## Follow or unfollow the user

Use this procedure when the profile header shows **Follow <username>** or
**Unfollow <username>** for another user.

**Prerequisites**

- The user's profile is open and its profile information is visible.
- You are signed in.

**Steps**

1. Select the control that matches the relationship you want:

   | If the control says… | Select it to… |
   |---|---|
   | **Follow <username>** | Follow the displayed user |
   | **Unfollow <username>** | Stop following the displayed user |

**Result:** The profile page receives the profile returned by the selected follow or unfollow
operation.

## Handle the profile and authentication branches

The available action depends on whose profile you opened and whether you already follow that
user.

| What you see | What to do | Outcome |
|---|---|---|
| **Follow <username>** | Select the button | The follow operation is used for the displayed user |
| **Unfollow <username>** | Select the button | The unfollow operation is used for the displayed user |
| **Edit Profile Settings** | Select the link | [Update settings](doc:update-settings) opens for your own profile |
| **Follow <username>** or **Unfollow <username>** while you are not signed in | Select the button | [Sign in](doc:sign-in) opens and the follow or unfollow operation is skipped |

**Steps**

1. Select the button in the row that matches what you see in the profile header.

**Result:** The selected **Follow <username>** or **Unfollow <username>** action runs,
**Edit Profile Settings** opens settings, or [Sign in](doc:sign-in) opens sign-in.

## When the profile cannot load

The page lists a profile-load fallback when the profile request fails. A server-provided profile
error can also appear in the page's error list.

| What you see | What it means | What to do |
|---|---|---|
| `Failed to load profile` | The profile request returned without a usable profile error list | Read the displayed message |
| ``Each value in `error.errors` `` | The profile request returned a server-provided profile error | Read the displayed message |
| No follow or unfollow success message | The page does not display a success message for that relationship operation | Check the profile header for the returned profile state |
| No follow or unfollow error message | The page does not display a relationship-specific error message | Check the profile header for the returned profile state |

After either relationship request, the page clears the submitting state on success or error. On
success, it uses the returned profile; it does not display a follow or unfollow error message.

## Know what happens next

After a successful relationship operation, the profile page receives the returned profile and
updates its profile value. The next destination depends on the branch you took.

| After this branch… | Continue at… |
|---|---|
| You opened your own profile | [Update settings](doc:update-settings) through **Edit Profile Settings** |
| You are not signed in when you select **Follow <username>** or **Unfollow <username>** | [Sign in](doc:sign-in) |
| You followed or unfollowed another user | [View a profile](doc:view-a-profile) or return to the profile's article list |

**Prerequisites**

- The relationship operation has returned the profile page to its normal state.

**Steps**

1. Select the next destination in the row that matches the branch you took.

**Result:** The destination named in the selected row opens, or the profile's article list is
available again.

<!-- source: loading-and-unavailable-states.md -->

# Loading and unavailable states

## Loading and unavailable states

Loading content means the application is retrieving it. An unavailable authentication state
means the application cannot currently complete its authentication check and is retrying when a
stored token is available.

| If you need to… | Go to |
|---|---|
| Recognize the message beside article content or tags | [Understand the messages and fields](#understand-the-messages-and-fields) |
| Wait for content or reload while authentication retries | [Wait for content or reload](#wait-for-content-or-reload) |
| Distinguish an empty result from a temporary failure | [Handle the different states](#handle-the-different-states) |
| Recover after authentication does not load | [When authentication or content does not load](#when-authentication-or-content-does-not-load) |
| Sign in after authentication is cleared | [Sign in](doc:sign-in) |
| Read broader authentication guidance | [Authentication and loading messages](doc:authentication-and-loading-messages) |

On Home, the article area uses this pattern while the header communicates whether access is still
being checked, signed in, signed out, or temporarily unavailable.

## Before you start

Prerequisites

- Have access to the application and the Home or [Sign in](doc:sign-in) page.
- If authentication becomes unavailable, keep the stored token in place so automatic retry can
  continue.
- Allow the authentication request to return before deciding whether the state is temporary or
  requires signing in again.

Authentication becomes temporarily unavailable after a server error or network error. With a stored
token, retry waits for 2 seconds, then 4, then 8, and then 16 seconds; later retries remain at
16 seconds. A client error in the 4XX range clears authentication instead.

## Find the state on screen

Prerequisites

- Know whether you are checking article and tag content or authentication.

Steps

1. Select the matching navigation label:

   | If you need to check… | Select… |
   |---|---|
   | The header, article area, or Popular Tags area | **Home** |
   | The authentication form | **Sign in** |

**Result:** You are on the screen that can display the loading or unavailable message you need to
identify.

## Understand the messages and fields

Loading and authentication status appear in different areas. Use the message and its location to
identify what is happening.

| Area | What you can see | When it appears |
|---|---|---|
| Article area | `Loading articles...` | Article data is being requested |
| Tags area | `Loading tags...` | The tags request has not completed |
| Tags area | `No tags are here... yet.` | The tags request completes with no tags |
| Header | `Loading...` | Authentication is still loading |
| Header | `Connecting...` | Authentication is temporarily unavailable |
| Header tooltip | `Auth unavailable - retrying automatically` | Authentication is unavailable while retry is scheduled |

The authentication form uses **Email** and **Password**. On Register it also uses **Username**;
the username field does not appear on Login. The submit button uses the current page title,
which is **Sign in** on Login and **Sign up** on Register.

While the article area is retrieving content, article results, pagination, and the empty-article
message are not shown. When tags are empty, tag links are not shown. While the application is
checking access or reconnecting, signed-in navigation is not shown; the header instead uses the
message-specific navigation described above.

## Wait for content or reload

Use this procedure when Home is still retrieving article or tag content, or when the header says
`Connecting...`.

Prerequisites

- Be on Home.
- The page shows `Loading articles...`, `Loading tags...`, or `Connecting...`.

Steps

1. Keep the relevant page open and follow the matching action:

   | When you see… | Do this… |
   |---|---|
   | `Loading articles...` in the article area | Keep Home open until the article area changes |
   | `Loading tags...` in the tags area | Keep Home open until the tags area changes |
   | `Connecting...` in the header | Reload the page while automatic authentication retry continues |

**Result:** The page shows article results and pagination after a successful article request, or
it continues its authentication retry cycle after a temporary authentication failure.

## Handle the different states

Use the message and the content around it to choose the matching path.

Prerequisites

- Be on Home and see one of the messages or content conditions below.

Steps

1. Match what you see to the reader action in the table:

| What you see | What it means | What to do |
|---|---|---|
| `Loading...` in the header | Authentication is loading | Wait for the authentication check to finish |
| `Connecting...` in the header | Authentication is temporarily unavailable | Wait for automatic retry or reload the page |
| `Loading articles...` in the article area | The article request is in progress | Wait for the article request |
| `Loading tags...` in Popular Tags | The tags request is in progress | Wait for the tags request |
| `No tags are here... yet.` in Popular Tags | The tags request completed with no tags | Continue without selecting a tag |
| No articles are shown after the article request is loaded | The article list can show an empty-feed message | Read the empty-feed message in the article area |

**Result:** You have chosen the response that matches the message or content condition on screen.

Authentication responses take a different path: an invalid authentication response clears access,
while a server or network problem displays `Connecting...` and schedules retry. The article area
shows its loading message when a query starts and shows content when the query succeeds.

## When authentication or content does not load

Authentication failure handling determines whether the application clears the current
authentication or keeps it for retry. Dynamic API error entries are handled by the shared error
list on the pages that own those requests.

Prerequisites

- Know whether the header shows `Connecting...` or whether the page has returned to its signed-out
  view.

Steps

1. Follow the matching recovery action:

   | When you see… | Do this… |
   |---|---|
   | `Connecting...` in the header | Keep the current page open while automatic retry continues |
   | Access has been cleared after an invalid authentication response | Select [**Sign in**](doc:sign-in) |
   | A dynamic API error entry | Use [**General error messages**](doc:general-error-messages) |

**Result:** You either remain in the retrying authentication path or arrive at the sign-in task
after authentication is cleared.

## Know what happens next

A successful article request displays its results and calculates pagination. A successful
authentication retry restores signed-in navigation; an invalid authentication response clears
access and sends you to the sign-in task.

Prerequisites

- Have identified whether the page loaded content, is retrying authentication, or cleared
  authentication.

Steps

1. Follow the matching next action:

   | When… | Do this… |
   |---|---|
   | The article request finishes successfully | Continue reading the article results |
   | The header shows `Connecting...` | Keep the current page open while automatic retry uses 2, 4, 8, and 16-second intervals |
   | An invalid authentication response clears access | Select [**Sign in**](doc:sign-in) |
   | You need broader troubleshooting | Open [**Common issues and solutions**](doc:common-issues-and-solutions) |

**Result:** You continue with loaded content, remain in the automatic retry path, or reach the
next documented task for authentication recovery.

<!-- source: navigation-basics.md -->

# Navigation basics

Use the home feed to choose a feed or tag, open an article, and reach a person's article
lists. From those destinations, continue to article and profile tasks.

## Navigation basics

Navigation connects the home page to **Your Feed**, **Global Feed**, tag links, article pages,
and profile pages. The home route and the tag route open the home page; an article route opens
the article page; and profile child routes display article lists.

| If you need to… | Go to |
|---|---|
| Read articles from the feeds | [Choose a feed or browse by tag](#choose-a-feed-or-browse-by-tag) |
| Filter the article list by a tag | [Choose a feed or browse by tag](#choose-a-feed-or-browse-by-tag) or [Browse articles by tag](doc:browse-articles-by-tag) |
| Read an article | [Open an article and choose an article task](#open-an-article-and-choose-an-article-task) or [Read an article](doc:read-an-article) |
| View a profile | [Open a profile and switch profile lists](#open-a-profile-and-switch-profile-lists) or [View a profile](doc:view-a-profile) |
| Work with a profile's posts or favorites | [View My Posts and Favorited Posts](doc:view-my-posts-and-favorited-posts) |

## Before you start

Prerequisites

- Know whether you are signed in. **Your Feed** appears for authenticated users.
- Have the tag, article, or profile destination you want to open. These destinations carry a
  tag, article slug, or username in their route.
- To add a comment from an article, use the authenticated comment form. When you are signed
  out, the article offers **Sign in** or **sign up** instead.

Steps

1. Open the home feed.
2. Decide whether you need a feed, tag, article, or profile destination.

**Result:** You are on the home feed and know whether to choose a feed, tag, article, or profile
destination.

## Choose a feed or browse by tag

A feed is an article list selected by the feed tab; a tag is a link that takes you to an
article list filtered by that tag.

Prerequisites

- Start on the home feed.
- To use **Your Feed**, be signed in.

Steps

1. Select one of these options:

   | If you need to… | Select |
   |---|---|
   | Read articles from users you follow | **Your Feed** |
   | Read the global article list | **Global Feed** |
   | Read articles grouped under a topic | A tag under **Popular Tags** |

2. Confirm that the article list has loaded.
3. If you selected a tag, confirm that the tag appears as the active tab.

The home feed can show `Loading tags...` while tags load and `No tags are here... yet.` when
the loaded tag list is empty. The article list can show `Loading articles...` while articles
load. An empty following list shows `Your feed is empty. Follow some users to see their
articles here, or check out the Global Feed!`; an empty article list shows `No articles are
here... yet.`

**Result:** The selected feed or tag article list is on screen and ready for the next destination.

## Open an article and choose an article task

An article destination is the page for reading an article and continuing to article tasks.
It contains the article title, body, tags, comments, and article actions.

Prerequisites

- Start from an article list or another article link.
- To comment, be signed in; the signed-out article offers **Sign in** and **sign up**.

Steps

1. Select an article from the article list.
2. Choose the article task you need:

   | If you need to… | Select |
   |---|---|
   | Edit the article | **Edit Article** |
   | Delete the article | **Delete Article** |
   | Save or remove the article from your favorites | **Favorite Article** or **Unfavorite Article** |
   | Write a comment | **Write a comment...** |
   | Add the comment | **Post Comment** |

3. If the article cannot load, look for `Failed to load article`.

**Result:** The article destination is on screen, or the selected article task has been opened.

## Open a profile and switch profile lists

A profile destination displays a person's profile information and the article list associated
with that profile.

Prerequisites

- Start from a profile link or a profile route.
- Have the username for the profile destination.

Steps

1. Open the profile destination.
2. Select one of these tabs:

   | If you need to… | Select |
   |---|---|
   | Read the profile's posts | **My Posts** |
   | Read the profile's favorited posts | **Favorited Posts** |

3. Confirm that the selected article list is displayed.

**Result:** The selected profile article list is on screen for the next navigation choice.

## Choose the available navigation branch

Authentication and ownership determine which navigation controls appear on the home, article,
and profile surfaces.

Prerequisites

- Know whether you are signed in.
- On an article or profile, know whether the displayed record belongs to you.

Steps

1. Select the control shown for your situation:

   | If you are… | Select |
   |---|---|
   | Signed in on the home feed | **Your Feed** |
   | The article owner | **Edit Article** or **Delete Article** |
   | Reading another person's article | **Follow** or **Unfollow**; **Favorite Article** or **Unfavorite Article** |
   | Signed in on an article | **Write a comment...** and **Post Comment** |
   | Signed out on an article | **Sign in** or **sign up** |
   | Viewing your own profile | **Edit Profile Settings** |
   | Viewing another person's profile | **Follow** or **Unfollow** |

**Result:** The controls for your authentication and ownership situation are on screen, and
you can continue with the task that matches your situation.

## When navigation content is missing or loading

Loading and empty messages tell you whether a list is still loading or has no items. An
article-load message identifies an article that did not load.

| Message | Meaning |
|---|---|
| `Loading tags...` | Tags are loading. |
| `No tags are here... yet.` | The loaded tag list is empty. |
| `Loading articles...` | Articles are loading. |
| `Your feed is empty. Follow some users to see their articles here, or check out the Global Feed!` | The following feed has no articles. |
| `No articles are here... yet.` | The article list has no articles. |
| `Failed to load article` | The article did not load. |

## Continue from the destination

Use the destination as the hand-off point to the task you want to complete.

| After you reach… | Continue with… |
|---|---|
| A feed | [Find articles in Your Feed and Global Feed](doc:find-articles-in-feeds) |
| A tag list | [Browse articles by tag](doc:browse-articles-by-tag) |
| An article | [Read an article](doc:read-an-article), [Comment on an article](doc:comment-on-an-article), or [Favorite articles](doc:favorite-articles) |
| Article actions | [Article actions reference](doc:article-actions-reference) |
| An article workspace | [Article workspace](doc:article-workspace) |
| A profile | [View a profile](doc:view-a-profile), [View My Posts and Favorited Posts](doc:view-my-posts-and-favorited-posts), or [Follow a user](doc:follow-a-user) |
| A sign-in prompt | [Sign in](doc:sign-in) |
| A loading or unavailable message | [Loading and unavailable states](doc:loading-and-unavailable-states) |

<!-- source: what-can-you-do-with-conduit.md -->

# What can you do with Conduit

## What you can do with Conduit

Conduit is a social blogging site where you can create, read, and manage articles;
write and remove comments; favorite articles; and follow other users.
Profiles show basic user information and lists of articles created by or favorited by
the profile owner.
A feed is a list of articles gathered from the global list, the people you follow, or a
tag. Comments add discussion to an article, favoriting selects an article for your
favorited list, and following lets you use the following feed.

| If you need to… | Go to |
| --- | --- |
| Choose a feed or browse tags | [Find feeds, articles, and profiles](#find-feeds-articles-and-profiles) |
| Enter, publish, edit, or remove an article | [Create, edit, and remove articles](#create-edit-and-remove-articles) |
| Choose the right article or profile path | [Use the available article and profile paths](#use-the-available-article-and-profile-paths) |
| Understand the fields and areas on the main surfaces | [Understand the main surfaces](#understand-the-main-surfaces) |
| Read an article | [Read an article](doc:read-an-article) |
| Add a comment | [Comment on an article](doc:comment-on-an-article) |
| Favorite an article | [Favorite articles](doc:favorite-articles) |
| Follow another user | [Follow a user](doc:follow-a-user) |
| View a profile's article lists | [View My Posts and Favorited Posts](doc:view-my-posts-and-favorited-posts) |

## Before you start

Authentication determines which paths and controls are available. The following-feed
path requires authentication, and the article-writing route is protected. Article owner actions
appear only when the article belongs to the current user. Profile actions also change
according to whether the profile belongs to the current user.

**Prerequisites**

- Know whether you need your following feed or the global feed.
- Sign in before using **Your Feed**, the Editor, or the signed-in comment form.
- To edit or delete an article, open an article that belongs to you.
- To edit your profile, open your own profile.

## Find feeds, articles, and profiles

The Home surface is the starting point for article discovery. It offers **Global Feed**,
the authenticated **Your Feed**, and **Popular Tags**.

**Prerequisites**

- Open Home at `/`.

**Steps**

1. Choose the feed or discovery route that matches your goal.

   | If you need to… | Select or use… |
   | --- | --- |
   | Read the global article list | **Global Feed** |
   | Read articles from people you follow | **Your Feed** |
   | Filter the article list by a displayed tag | a tag under **Popular Tags** |

2. Use the article list and its pagination to continue through the available articles.

**Result:** The Home surface shows the feed or tag-filtered article list you selected.

## Understand the main surfaces

Conduit separates discovery, article writing, article reading, and profile work across
four main surfaces. Home is the article-discovery surface. Editor is where you enter
article content and tags. Article is where you read an article and use its owner or
visitor actions. Profile contains user information, profile actions, and the **My Posts** and
**Favorited Posts** tabs.

| Surface | Use it for | Reader-facing fields or controls |
| --- | --- | --- |
| Home | Find articles | **Your Feed**, **Global Feed**, **Popular Tags** |
| Editor | Create or edit an article | **Article Title**, **What's this article about?**, **Write your article (in markdown)**, **Enter tags**, **Publish Article** |
| Article | Read an article and manage its available actions | **Edit Article**, **Delete Article**, **Write a comment...**, **Post Comment** |
| Profile | View profile information and article lists | **Edit Profile Settings**, **My Posts**, **Favorited Posts** |

The Article and Profile surfaces also contain controls whose availability depends on
ownership or authentication. The Home surface includes the article list as an embedded
area rather than as a separate grid.

## Create, edit, and remove articles

An article is the content you publish for other people to read. Use the Editor to enter
its title, description, body, and tags; use the Article surface to edit or remove an
article you own.

### Publish or update an article

**Prerequisites**

- Sign in.
- For an update, open an article that belongs to you.

**Steps**

1. Choose the article task.

   | If you need to… | Select or open… |
   | --- | --- |
   | Create an article | the Editor at `/editor` |
   | Update an article | **Edit Article** on an article you own |

2. Enter the article title in **Article Title**.

3. Enter the article description in **What's this article about?**.

4. Enter the article body in **Write your article (in markdown)**.

5. Enter a tag in **Enter tags**.

6. Press Enter to add the tag.

7. Select **Publish Article**.

**Result:** The article is created or updated, and the app navigates to its Article
surface.

### Remove an article

**Prerequisites**

- Open an article that belongs to you.

**Steps**

1. Select **Delete Article**.

**Result:** The article is deleted and the app navigates to Home.

## Use the available article and profile paths

The Article surface changes according to who owns the article and whether you are signed
in. The Profile surface changes according to whether you are viewing your own profile or
another user's profile.

### Add a comment or reach the sign-in path

**Prerequisites**

- Open an Article surface.

**Steps**

1. Choose the path that matches your access.

   | If you are… | Use this path |
   | --- | --- |
   | Signed in and adding a comment | Enter text in **Write a comment...**, then select **Post Comment** |
   | Signed out and want to comment | Select **Sign in** or **sign up** |
   | The article owner | Use **Edit Article** or **Delete Article** |
   | Viewing another user's article | Continue with [Follow a user](doc:follow-a-user) or [Favorite articles](doc:favorite-articles) |

**Result:** The Article surface either provides the comment form, takes you to an
authentication path, or provides the owner or visitor actions that apply to the article.

### Open a profile list

**Prerequisites**

- Open a Profile surface.

**Steps**

1. Choose the action that matches your goal.

   | If you need to… | Select… |
   | --- | --- |
   | View the profile's created-article list | **My Posts** |
   | View the profile's favorited-article list | **Favorited Posts** |
   | Open Settings for your own profile | **Edit Profile Settings** |

**Result:** The selected profile list opens, or Settings opens for your own profile.

## When loading or submission fails

The Article and Profile surfaces have an error area for messages returned while loading
or submitting. The app provides these literal load fallbacks:

| What you see | Meaning | Next step |
| --- | --- | --- |
| `Failed to load article` | The Article load path returned an error without another message. | Return to the article path from the relevant focused article page. |
| `Failed to load profile` | The Profile load path returned an error without another message. | Return to the profile path from the relevant focused profile page. |

Errors returned by the Article comment form are displayed in the same error area. The
Editor also displays its returned errors above the form. Continue with [General error
messages](doc:general-error-messages) when you need the application's broader error
reference.

## Continue with a focused task

Use the focused page that matches the next job:

| Next job | Page |
| --- | --- |
| Sign in or create an account | [Sign in](doc:sign-in) or [Create an account](doc:create-an-account) |
| Understand authentication and loading messages | [Authentication and loading messages](doc:authentication-and-loading-messages) |
| Find articles in a feed | [Find articles in Your Feed and Global Feed](doc:find-articles-in-feeds) |
| Browse by tag | [Browse articles by tag](doc:browse-articles-by-tag) |
| Read or orient yourself on an article | [Read an article](doc:read-an-article) or [Article workspace](doc:article-workspace) |
| Create or edit an article | [Create and edit an article](doc:create-and-edit-an-article) |
| Comment, favorite, or use article actions | [Comment on an article](doc:comment-on-an-article), [Favorite articles](doc:favorite-articles), or [Article actions reference](doc:article-actions-reference) |
| View or manage a profile | [View a profile](doc:view-a-profile), [View My Posts and Favorited Posts](doc:view-my-posts-and-favorited-posts), or [Follow a user](doc:follow-a-user) |
| Update profile settings | [Update settings](doc:update-settings) |
| Handle loading or general errors | [Loading and unavailable states](doc:loading-and-unavailable-states), [General error messages](doc:general-error-messages), or [Common issues and solutions](doc:common-issues-and-solutions) |

<!-- source: comment-on-an-article.md -->

# Comment on an article

An article comment is text you add to an article for other readers to read. Use the comment
area to add a new comment, or remove a comment that you authored.

| If you need to… | Go to |
| --- | --- |
| Open the article and read its comments | [Read an article](doc:read-an-article) |
| Add text to an article | [Add a comment](#add-a-comment) |
| Remove a comment you wrote | [Delete a comment you authored](#delete-a-comment-you-authored) |
| Sign in before commenting | [Sign in](doc:sign-in) |
| Create an account before commenting | [Create an account](doc:create-an-account) |
| Find help for a general error | [General error messages](doc:general-error-messages) |

## Before you start

Have the following ready before you begin:

| What you need | Why it matters |
| --- | --- |
| The article you want to comment on | Comments are displayed in the article page's comments area. |
| A signed-in session | The comment form is available to authenticated readers. |
| The comment text you want to post | This is the text readers see in your comment. |
| Ownership of the comment you want to remove | A delete control appears beside comments you authored, not beside comments written by other readers. |

If you are not signed in, the article page provides **Sign in** and **sign up** links instead of
the comment form.

## Find and open the article

An article page is the place where the article content and its comments are available together.
Open the article page for the article you want to discuss.

**Steps**

1. Open the article through [Read an article](doc:read-an-article).

**Result:** The article page opens with the article content and its comment area.

## Understand the comment area

The comment area is the part of the article page where you enter a comment, submit it, and read
the comments already attached to the article. Each comment shows its text, author, and creation
date.

| What you need to do | What to use |
| --- | --- |
| Enter a comment | The multiline field with the placeholder **Write a comment...** |
| Submit the comment | **Post Comment** |
| Reach the form while signed out | **Sign in** or **sign up** |
| Remove your own comment | The delete control beside comments you authored, not beside comments written by other readers. |
| Read an existing comment | Its text, author, and creation date |

The form is available when you are signed in. While a comment is being submitted, the form is
disabled.

## Add a comment

Use this procedure when you are signed in and the article page is open.

**Prerequisites**

- Open the article you want to comment on.
- Sign in to your account.

**Steps**

1. In the comment area, enter your text in **Write a comment...**.
2. Select **Post Comment**.

   The form is disabled while the submission is in progress.

**Result:** The new comment is added to the beginning of the comments list, and the comment
field is cleared.

## Delete a comment you authored

Use this procedure to remove a comment that belongs to your account.

**Prerequisites**

- Open the article containing your comment.
- Confirm that the delete control appears beside your comment.

**Steps**

1. On your comment, select the delete control beside it.

**Result:** After deletion succeeds, the comment is removed from the comments list.

## When comment actions go wrong

The article page displays errors in its error area. If loading the article returns no specific
error message, the page displays `Failed to load article`.

| What you see | What to do |
| --- | --- |
| An error appears after submitting a comment | Read the error area for the returned error. |
| An error appears while deleting your comment | Read the error message. |
| The article cannot be loaded | Read the displayed error before attempting to comment. |

## What happens next

After a successful submission, the new comment appears at the beginning of the comments list and
the entry field is empty. After a successful deletion, the selected comment is removed from the
list. Continue reading in [Read an article](doc:read-an-article), or use [General error
messages](doc:general-error-messages) when the page displays an error.

<!-- source: personalizing-your-workspace.md -->

# Personalizing your workspace

## Personalize your workspace

Settings is where you maintain your account details. A Profile is your personal page for
information and articles; your own Profile provides access to Settings. Conduit is a social
blogging site.

| If you need to… | Go to |
| --- | --- |
| Find your personal fields and submit a change | [Update settings](doc:update-settings) |
| Decide whether to change personal details or a password | [Change your password](doc:change-your-password) |
| Leave the account | [Sign out](doc:sign-out) |
| View a profile and its posts | [View a profile](doc:view-a-profile) |

## Before you start

You must be signed in to open Settings. The route redirects an unauthenticated visitor
to `/login`.

**Prerequisites**

- Have the account whose personal details you want to maintain.
- Be signed in before opening Settings.
- To use **Edit Profile Settings**, open the profile that belongs to the signed-in account.
- To change a password, use the **New Password** field on Settings.

## Find Settings and your profile

Open your own Profile when you need the editing route.

**Prerequisites**

- Be signed in.

**Steps**

1. Open `/settings` to go directly to Settings.
2. Open your profile from the account link in the header.
3. Select **Edit Profile Settings** on your own profile.

The **Edit Profile Settings** link appears when the loaded profile belongs to the current
user. A profile that belongs to someone else shows **Follow** instead.

**Result:** You are on Settings, ready to review or change your personal details.

## Understand the Settings screen

The Settings screen contains five personal fields for your profile picture, username,
biography, email address, and new password. **New Password** has a required validator in the
form configuration; the other four controls have no configured validator.

| Field | What to enter |
| --- | --- |
| **URL of profile picture** | The URL for your profile picture |
| **Username** | Your username |
| **Short bio about you** | Your short biography |
| **Email** | Your email address |
| **New Password** | A new password |

Select **Update Settings** to submit the form. Select **Or click here to logout.** to leave
the account.

**Result:** You can identify each personal field and the action that submits or ends the session.

## Update your personal settings

Updating personal settings changes the account details used by your Profile. The form starts
with the current user's data when that data is available.

**Prerequisites**

- Be signed in and on Settings.
- Have the new profile details ready.

**Steps**

1. Enter the profile-picture address in **URL of profile picture**.
2. Enter the account name in **Username**.
3. Enter the biography in **Short bio about you**.
4. Enter the email address in **Email**.
5. Enter a new password in **New Password** when you are changing it.
6. Select **Update Settings**.

When you leave **New Password** empty, the update request omits that value. While the update
is being submitted, the form fields are disabled.

**Result:** After a successful update, the app opens the updated user's Profile.

## Choose the personal change you need

Use Settings for changes to your own account. Use a Profile to view personal information;
**Edit Profile Settings** is available when the profile is yours.

**Prerequisites**

- Be signed in.
- Know whether you are changing profile details, changing a password, or viewing another profile.

**Steps**

1. Choose the route that matches your task:

   | If you need to… | Use this route |
   | --- | --- |
   | Change your picture, username, biography, or email | Settings |
   | Change your password | **New Password** on Settings |
   | View another person's personal information | Their Profile |
   | Edit your own profile | **Edit Profile Settings** |

**Result:** You are using the personal surface that matches the change you want to make.

## When an update goes wrong

The shared error area lists returned errors. Each entry is displayed as a key followed by its
value, using the form `key value`.

| What you see | What it means | What to do |
| --- | --- | --- |
| `key value` | The page received an error entry from the operation. | Read the key and value, correct the related field, and submit **Update Settings** again. |
| `Failed to load profile` | The Profile request failed without an `errors` payload. | Return to the Profile route and try again. |

`Failed to load profile` is used when profile loading fails without an `errors` payload.

**Result:** You know where the error appears and which action to try next.

## Know what to do next

After you finish a personal-settings task, continue from the destination or choose the page
for the next account task.

**Steps**

1. Choose your next action:

   | If you need to… | Choose |
   | --- | --- |
   | Continue after a successful update | Open the updated user's Profile |
   | Complete the settings procedure | Open [Update settings](doc:update-settings) |
   | Change only the password | Open [Change your password](doc:change-your-password) |
   | Leave the account | Select **Or click here to logout.** or open [Sign out](doc:sign-out) |

**Result:** You are either on the updated Profile or at the dedicated page for your next
account task.

<!-- source: system-requirements.md -->

# System requirements

## What you need to run Conduit

Bun is the tool required to set up and start Conduit.

This page covers two project jobs:

| If you need to… | Go to |
| --- | --- |
| Prepare the project and start the local application | [Set up and start the project](#set-up-and-start-the-project) |
| Generate build artifacts | [Build the project](#build-the-project) |
| Sign in, register, and reach the main feed | [Your first day](doc:your-first-day) |
| Understand loading and unavailable states | [Loading and unavailable states](doc:loading-and-unavailable-states) |
| Find project and demo references or authentication errors | [Getting help](doc:getting-help) |

Build artifacts are covered in [Build the project](#build-the-project).

## Before you start

Have Bun available and work from the project directory before initializing the project.
Work in the project directory named by the setup instructions.

## Set up and start the project

Initialize the project and start the local application with this procedure.

**Prerequisites**

- Bun is available.
- You are in the project directory.

**Steps**

1. Enter `bun run setup` in a terminal.
2. Enter the command for your situation:

   | Situation | Command |
   | --- | --- |
   | After the initial setup | `bun run start` |
   | After a `git pull` updates the `realworld` submodule | `bun run setup` again |

**Result:** The local application is started from the project directory.

While the root page loads, it can show these messages:

| When | Message |
| --- | --- |
| Tags are loading | `Loading tags...` |
| Tags have loaded and the tag list is empty | `No tags are here... yet.` |
| Articles are loading | `Loading articles...` |
| The following feed has no articles | `Your feed is empty. Follow some users to see their articles here, or check out the Global Feed!` |
| The loaded article list has no articles | `No articles are here... yet.` |

## Build the project

Create the project's build artifacts with this procedure.

**Prerequisites**

- Bun is available.
- You are in the project directory.

**Steps**

1. Enter `bun run build` in a terminal.

**Result:** The build artifacts are stored in `dist/`.

<!-- source: basic-terminology.md -->

# Basic terminology

## What these terms mean

Conduit uses these terms for the main places where you browse, publish, and manage your account.

| Term | What you use it for |
| --- | --- |
| Feed | The article list on Home |
| Article | Published content that you read, edit, comment on, and remove |
| Profile | A person's posts and account identity |
| Favorites | Articles saved to a profile's favorites list |
| Editor | The form where you enter or revise an Article |
| Settings | The account form for profile details |
| Login | The form for using an existing account |
| Register | The form for creating an account |

| If you need to… | Go to |
| --- | --- |
| Choose your account branch | [Before you start](#before-you-start) |
| Recognize a feed or tag state | [Find and recognize the feeds](#find-and-recognize-the-feeds) |
| Understand an Article or Editor | [Understand Article and Editor screens](#understand-article-and-editor-screens) |
| Use a Profile, Favorites, or Settings | [Use Profile, Favorites, and Settings](#use-profile-favorites-and-settings) |
| Read an error message | [When a message appears](#when-a-message-appears) |
| See articles from everyone | [Find articles in feeds](doc:find-articles-in-feeds) |
| See articles from followed profiles | [Find articles in feeds](doc:find-articles-in-feeds) |
| Open an article by its tag | [Browse articles by tag](doc:browse-articles-by-tag) |
| Write or revise an article | [Create and edit an article](doc:create-and-edit-an-article) |
| Read an article and its comments | [Read an article](doc:read-an-article) |
| Add a comment | [Comment on an article](doc:comment-on-an-article) |
| Save an article to your favorites | [Favorite articles](doc:favorite-articles) |
| View a profile | [View a profile](doc:view-a-profile) |
| See your posts or favorited posts | [View my posts and favorited posts](doc:view-my-posts-and-favorited-posts) |
| Change profile or account details | [Update settings](doc:update-settings) |
| Leave the account | [Sign out](doc:sign-out) |

Start with [Before you start](#before-you-start) to choose the account branch that applies to
you.

## Before you start

**Prerequisites**

- Know whether you are signing in to an existing account or registering a new one.
- For Login, have the account's **Email** and **Password** ready.
- For Register, have a **Username**, **Email**, and **Password** ready.
- To use **Your Feed**, be signed in.
- To open Settings, be signed in.

The account form uses **Email** and **Password** on both Login and Register. **Username** appears
on Register. A form submission control is disabled while its form is invalid.

After you know the account branch, continue to Home to identify the feed you need.

## Find and recognize the feeds

**Prerequisites**

- Open Home.

**Steps**

1. Select **Global Feed** to browse the general article list.
2. If you are signed in, select **Your Feed** to browse the feed for profiles you follow.
3. Look under **Popular Tags** for links that open articles filtered by a tag.
4. While tags are loading, look for `Loading tags...`.
5. If loading finishes without tags, look for `No tags are here... yet.`.

**Result:** Home displays the selected feed, and the sidebar identifies the tag-list state.

From a feed, open an Article when you need to read or act on its content.

## Understand Article and Editor screens

The Editor contains these fields:

| You are entering… | Use |
| --- | --- |
| The article heading | **Article Title** |
| The short description | **What's this article about?** |
| The article body | **Write your article (in markdown)** |
| Tags for the article | **Enter tags** |

**Prerequisites**

- Open the Editor to create an article, or open an article you can modify to revise it.
- To comment, open an Article while signed in.

**Steps**

1. Enter the article heading in **Article Title**.
2. Enter its short description in **What's this article about?**.
3. Enter the content in **Write your article (in markdown)**.
4. Enter a tag in **Enter tags**.
5. Press Enter in **Enter tags** to add the tag to the tag list.
6. Select the close icon next to a tag to remove that tag.
7. Select **Publish Article** to create or update the Article.
8. On an Article you can modify, select **Edit Article** to open its Editor.
9. On an Article you can modify, select **Delete Article** to remove it.
10. In the signed-in comment form, enter text in **Write a comment...**.
11. Select **Post Comment** to add the comment.

**Result:** The Editor sends the article data, and a successful save opens the Article route.
The Article page shows the owner actions when you can modify that Article; other viewers receive
follow and favorite controls instead.

## Sign in or register

**Prerequisites**

- Open **Login** for an existing account or **Register** for a new account.

**Steps**

1. Choose the form that matches your task:

   | If you need to… | Choose |
   | --- | --- |
   | Use an existing account | [Login](doc:sign-in) |
   | Create an account | [Register](doc:create-an-account) |

2. Complete the fields and submit the selected form:

   | Form | Fields | Submit |
   | --- | --- | --- |
   | Login | **Email** and **Password** | **Sign in** |
   | Register | **Username**, **Email**, and **Password** | **Sign up** |

3. Switch forms when your task changes:

   | If you are on… | Select |
   | --- | --- |
   | Register | **Have an account?** |
   | Login | **Need an account?** |

**Result:** The selected account form submits only when its required fields are valid.

## Use Profile, Favorites, and Settings

**Prerequisites**

- Open a Profile.
- To change profile details, open the signed-in profile.

**Steps**

1. Select **My Posts** to view the profile's articles.
2. Select **Favorited Posts** to view the profile's favorites.
3. On your own profile, select **Edit Profile Settings**.
4. Enter a profile-picture address in **URL of profile picture**.
5. Enter the account name in **Username**.
6. Enter a short biography in **Short bio about you**.
7. Enter the account email in **Email**.
8. Enter a new password in **New Password** when you are changing it.
9. Select **Update Settings**.
10. Select **Or click here to logout.** when you need to leave the account.

**Result:** Settings sends the profile form; after a successful update, the application opens the
updated profile. Logging out uses the account's logout action.

## When a message appears

The application displays returned error entries in the error area for the screen. Each entry uses
the returned key followed by its value.

Error text is rendered as `<key> <value>` for each returned error entry.

| What you see | What it concerns | What to do |
| --- | --- | --- |
| `Failed to load article` | The Article could not be loaded. | Return to the Article route later. |
| `Failed to load profile` | The Profile could not be loaded. | Return to the Profile route later. |
| `<key> <value>` | A returned error entry. | Read the key and value shown in the error area. |

## Continue with a related task

Use [What is Conduit](doc:what-is-conduit) for orientation, [Who uses Conduit](doc:who-uses-conduit)
for audience information, and [What can you do with Conduit](doc:what-can-you-do-with-conduit)
for the product's capabilities. Use [System requirements](doc:system-requirements) before access
setup and [Getting help](doc:getting-help) when you need assistance.

For navigation and setup, continue with [Understanding the interface](doc:understanding-the-interface),
[Navigation basics](doc:navigation-basics), [Personalizing your workspace](doc:personalizing-your-workspace),
or [Your first day](doc:your-first-day). For loading and error handling, use
[Authentication and loading messages](doc:authentication-and-loading-messages),
[Loading and unavailable states](doc:loading-and-unavailable-states), [FAQ](doc:faq),
[General error messages](doc:general-error-messages), or
[Common issues and solutions](doc:common-issues-and-solutions).

<!-- source: favorite-articles.md -->

# Favorite articles

## Overview

Favoriting marks an article so you can find it later in the author's profile under **Favorited
Posts**. Conduit provides this capability on the Article surface and the profile surface.

| If you need to… | Go to |
| --- | --- |
| Open an article and change whether it is favorited | [Favorite or unfavorite an article](#favorite-or-unfavorite-an-article) |
| Open the profile list of saved articles | [Find the article and its favorites list](#find-the-article-and-its-favorites-list) |
| Read the article after opening it | [Read an article](doc:read-an-article) |
| Review profile lists and tabs | [View My Posts and Favorited Posts](doc:view-my-posts-and-favorited-posts) |
| Add a comment after opening the article | [Comment on an article](doc:comment-on-an-article) |
| Sign in before favoriting | [Sign in](doc:sign-in) |

## Prerequisites

You need an article to open, a signed-in account for the favorite action, and a profile whose
favorite list you can open. If you are not signed in, selecting **Favorite Article** or
**Unfavorite Article** takes you to
the registration page. The profile's favorites list appears after its favorites configuration loads.

The favorites list has no fields for you to complete. It displays article results, while the
Article surface displays the article title, body, and tags.

## Find the article and its favorites list

An article is the content you open to read or mark for later; **Favorited Posts** is the profile
list of articles that the profile has favorited.

**Prerequisites**

- You know which article and profile to open.
- You know the profile username for the favorites list.

**Steps**

1. Open the article you want to favorite.
2. Open the profile whose favorites you want to view.
3. Select **Favorited Posts**.
4. Select an article title in the list to open that article.

The profile surface also provides **My Posts**. The favorites list uses the profile username to
request that profile's favorited articles. Article metadata links to the author's profile.

**Result:** You are on the Article surface or viewing the selected profile's **Favorited Posts**
list.

## Understand the favorites screen

The favorites screen is a list of article previews; each preview can show the article's title, tags,
and favorite count. Selecting a title opens the Article surface,
where the title, markdown-rendered body, and tags are displayed.

| What you see | What it tells you |
| --- | --- |
| Article title | Which article the preview represents |
| Favorite count | The number displayed with the preview's favorite control |
| Page number | Which results page you are viewing |
| `Loading articles...` | The article list is loading |
| `No articles are here... yet.` | The loaded favorites query returned no articles |

The favorites list requests up to 10 articles per page. Pagination is calculated from the number
of articles returned. The favorite surfaces provide no required fields, grid columns, or configurable
fields to complete.

## Favorite or unfavorite an article

**Favorite Article** marks the article for inclusion in the profile's **Favorited Posts** list;
**Unfavorite Article** removes that mark.

**Prerequisites**

- You are signed in.
- The Article surface is displaying the article.
- The article is not one you can modify, so **Favorite Article** or **Unfavorite Article** is displayed.

**Steps**

1. Select **Favorite Article** or **Unfavorite Article** according to the article's current state:

   | If the article is… | Select |
   | --- | --- |
   | Not currently favorited | **Favorite Article** |
   | Currently favorited | **Unfavorite Article** |

The control calls the favorite or unfavorite action that matches the article's current state. While
the request is being submitted, the control is disabled. After a successful change, the displayed
favorite state and count update.

**Result:** The Article surface shows the selected favorite state and its updated count.

## Handle the alternate results

The favorite action has different outcomes depending on whether you are signed in and whether the
profile has any favorited articles.

**Prerequisites**

- Choose the row that matches what you see before selecting a control.

**Steps**

1. Use the applicable path:

   | If you need to… | Do this |
   | --- | --- |
   | Favorite an article while signed out | Select **Favorite Article** or **Unfavorite Article**; Conduit opens the registration page. |
   | View a profile with no favorited articles | Open **Favorited Posts** and wait for `No articles are here... yet.`. |
   | Work with an article you own | Favorite controls are absent when you can modify the article. |
   | Recover from a failed favorite request | Wait for the submitting state to clear; no failure message appears. |

**Result:** You follow the path that matches the account state, list contents, and article ownership
shown on screen.

## When favoriting goes wrong

Use the message on screen to choose the next action.

| Message | Meaning |
| --- | --- |
| `Loading articles...` | Wait for the favorites list to finish loading. |
| `No articles are here... yet.` | Open **Favorited Posts** after the favorites query has loaded. |
| `Failed to load article` | The article did not load. |

## After favoriting

**Prerequisites**

- The Article surface shows the updated favorite state.

**Steps**

1. Open the profile whose favorited articles you want to verify.
2. Select **Favorited Posts**.
3. Select the article title in the list.

The list uses the profile username for its favorites query and displays up to 10 articles per page.
Use the page numbers to move through additional results.

**Result:** The article appears in **Favorited Posts**, or the list shows `No articles are here... yet.`

<!-- source: getting-help.md -->

# Getting help

## What Conduit help covers

Conduit is a social blogging site for publishing and discussing articles.
Authentication is the sign-in or account-creation part of the application.
Use this page when you need project documentation, the live demo, or help with
authentication and connection messages.

| If you need to… | Go to |
|---|---|
| Understand what Conduit is | [What is Conduit](doc:what-is-conduit) |
| Find project documentation or the live demo | [Find project and demo help](#find-project-and-demo-help) |
| Prepare the project before starting it | [System requirements](doc:system-requirements) |
| Sign in or create an account | [Recognize the authentication screen](#recognize-the-authentication-screen) |
| Understand loading or unavailable states | [Authentication and loading messages](doc:authentication-and-loading-messages) |
| Resolve a general error | [General error messages](doc:general-error-messages) |
| Work through a broader setup or route problem | [Common issues and solutions](doc:common-issues-and-solutions) |

The project documentation explains how the application works. The live demo is
the place to use the application itself.
If you need setup, continue with the checklist below.

## Before you look for help

Before starting the project, have the required setup and the route that matches
your task in front of you.

| Before you start | Have ready |
|---|---|
| Install the project prerequisite | `Bun` |
| Get the project | `git clone https://github.com/realworld-apps/angular-realworld-example-app.git` |
| Install dependencies and initialise the project | `bun run setup` |
| Start the project | `bun run start` |
| Reinitialise after a submodule update | Run `bun run setup` again after a `git pull` that updates the `realworld` submodule |
| Choose the authentication task | `/login` for sign-in or `/register` for account creation |

The application uses the `/login` and `/register` routes for these two tasks.
For setup questions, continue with the project and demo resources below.

## Find project and demo help

Project documentation is the reference for how the project works; the live demo
is the place to use Conduit. Use the links below according to the question you
need to answer.

| If you need to… | Open |
|---|---|
| Read the project documentation | [Project documentation](https://docs.realworld.show/introduction/) |
| Use the application | [Live demo](https://demo.realworld.show) |
| Get the project source | [Angular Example App](https://github.com/realworld-apps/angular-realworld-example-app) |
| Read the broader Angular guidance | [RealWorld Angular](https://github.com/realworld-angular) |
| Read the Angular frontend or Realworld references shown on Home | [Angular frontend](https://github.com/realworld-apps/angular-realworld-example-app) or [Realworld](https://realworld.show) |

1. Choose the row that matches your question and open the linked resource.

**Result:** You are at the project, demo, or guidance resource that matches your
question.
If you are using the application, continue with the authentication-screen guidance.

## Recognize the authentication screen

The authentication screen lets you enter the application as a user or create an
account. The same screen serves both tasks, and its title and fields change with
the route.

Prerequisites

- You know whether you are signing in at `/login` or creating an account at
  `/register`.
- You have the email address and password for sign-in, or the username, email
  address, and password for account creation.

Steps

1. In the unauthenticated header, select the link for your task.

   | Task | Select |
   |---|---|
   | Sign in to an existing account | **Sign in** |
   | Create an account | **Sign up** |

2. Complete the fields for your task.

   | Task | Fields to complete |
   |---|---|
   | Sign in to an existing account | **Email** and **Password** |
   | Create an account | **Username**, **Email**, and **Password** |

3. Select **Sign in** for an existing account or **Sign up** for a new account.

The sign-in form provides **Need an account?** to reach registration. The
registration form provides **Have an account?** to return to sign-in.

**Result:** The selected authentication form is complete and its submit control
matches the route: **Sign in** on `/login` or **Sign up** on `/register`.

## Handle authentication and connection problems

An authentication state tells you whether the application is loading,
authenticated, unauthenticated, or temporarily unavailable. The header
communicates this state while the application checks the session or waits for
the server. Error messages appear in a list above the authentication form when
a request returns errors.
Each server error is rendered as `<key> <message>`.

| What you see | What it means | What to do |
|---|---|---|
| `Loading...` | The application is checking the current session. | Wait for the authentication state to finish loading. |
| `Connecting...` | Authentication is temporarily unavailable and the application is retrying. | Leave the page open while the application performs its automatic retry. |
| `Unable to connect. Please check your internet connection.` | A request did not provide a usable error body or the network could not connect. | Check the connection and retry the task. |
| A list item in the form of `<key> <message>` | The server returned a named error and its message. | Read the message next to its key and correct the indicated input. |

1. Find the visible message in the table and follow its corresponding action.

**Result:** The authentication state is loading, authenticated, or temporarily
unavailable, and any visible error message identifies the response that needs
attention.

The header shows different links for each state:

| Authentication state | Header content |
|---|---|
| Unauthenticated | **Home**, **Sign in**, and **Sign up** |
| Authenticated | **Home**, **New Article**, **Settings**, and the current user's name |
| Temporarily unavailable | **Home**, **New Article**, **Settings**, and `Connecting...` |
| Loading | **Home** and `Loading...` |

When authentication is temporarily unavailable, the application retries after
2, 4, and 8 seconds, then every 16 seconds. A non-`/user` request that returns
401 purges the authentication state.

For the complete shared message reference, open [General error messages](doc:general-error-messages).

## Choose the next help path

After you identify the task or message, choose the matching help topic below.

| Your next question | Continue with |
|---|---|
| How do I sign in? | [Sign in](doc:sign-in) |
| How do I create an account? | [Create an account](doc:create-an-account) |
| What do the authentication states mean? | [Authentication and loading messages](doc:authentication-and-loading-messages) |
| What happens while the application is loading or unavailable? | [Loading and unavailable states](doc:loading-and-unavailable-states) |
| What does a general error message mean? | [General error messages](doc:general-error-messages) |
| What should I try for a wider setup or route problem? | [Common issues and solutions](doc:common-issues-and-solutions) |

<!-- source: article-actions-reference.md -->

# Article actions reference

Use this page to create or edit an article, open an article record, and choose the
available article actions.

## Article actions at a glance

The Editor is where you enter an article, and the article record is where you read and
manage it after it has been created or updated.

| If you need to… | Go to |
| --- | --- |
| Create a new article | The Editor |
| Edit an existing article | The existing article's Editor |
| Read or manage an article | The article record |
| Add a comment | [Comment on an article](doc:comment-on-an-article) |
| Manage favorites | [Favorite articles](doc:favorite-articles) |

The article surfaces cover creating, editing, reading, deleting, favoriting, following,
and commenting. No article lifecycle stages are included in these surfaces.

Start with Before you start.

## Before you start

Prerequisites

- Sign in before opening the Editor or the existing article's Editor.
- To edit an existing article, be its author.
- Have the existing article's identifier when opening an existing article or the article record.

The Editor loads an existing article only when the signed-in user is its author. If the
author check does not pass, the Editor returns to the home surface.

With these conditions in place, continue to Find and open an article.

## Find and open an article

Use this procedure when you need to reach the correct article surface before entering
information or selecting an action.

Prerequisites

- Meet the sign-in and ownership requirements in Before you start.
- Have the existing article's identifier when you are opening its Editor or article record.

Steps

1. Choose the article surface that matches your task.

   | If you need to… | Open |
   | --- | --- |
   | Create an article | The Editor |
   | Edit an existing article | The existing article's Editor |
   | Read or manage an article | The article record |

2. On an article record, select **Edit Article** to open the existing article in the
   Editor.

**Result:** The Editor or the article record is open for the task you selected.

Continue to Understand the article surfaces.

## Understand the article surfaces

The Editor is the article-entry surface; the article record is the reading and
management surface.

| Surface | What you use it for |
| --- | --- |
| **Article Title** | Enter the article title. |
| **What's this article about?** | Enter the article description. |
| **Write your article (in markdown)** | Enter the article body. |
| **Enter tags** | Add tags to the article. |
| **Publish Article** | Submit a new article or an update to an existing article. |
| **Edit Article** | Open the current article in the Editor. |
| **Delete Article** | Delete the current article. |
| **Write a comment...** | Enter a comment on the article. |
| **Post Comment** | Submit the comment. |

The article owner sees **Edit Article** and **Delete Article**. A reader who is not the
owner sees follow and favorite controls instead. An authenticated reader sees the
comment form; an unauthenticated reader sees **Sign in** and **sign up** links instead.

Use Create or edit an article for the Editor, or Manage article actions and branches for
the article record.

## Create or edit an article

Use this procedure to enter the article information, add or remove tags, and submit a
new article or an update.

Prerequisites

- Open the Editor surface identified in Find and open an article.
- Meet the sign-in and ownership requirements in Before you start.

Steps

1. In the field with placeholder **Article Title**, enter the article title.
2. In the field with placeholder **What's this article about?**, enter the article
   description.
3. In the field with placeholder **Write your article (in markdown)**, enter the article
   body.
4. In **Enter tags**, enter a tag and press Enter to add it to the article.
5. To remove a tag, select the close icon beside that tag.
6. Select **Publish Article**.

   | Editor opened for | Request used |
   | --- | --- |
   | A new article | Create the article. |
   | An existing article | Update the existing article. |

**Result:** After a successful submission, the application opens the article record. While
the request is being submitted, the Editor fields and
the submit action are disabled. If the request returns an error, the error list appears
above the form.

Continue to Manage article actions and branches on the article record.

## Manage article actions and branches

An article record offers different actions according to whether you are its author and
whether you are signed in.

Prerequisites

- Open the article record identified in Find and open an article.
- Use the ownership and sign-in branch in the table below.

Steps

1. Choose the action that matches your role or task.

   | If you are… | Use this path |
   | --- | --- |
   | The article author | Select **Edit Article** to change the article, or select **Delete Article** to delete it. |
   | Not the article author | Select the follow control or the favorite control in the article metadata row. |
   | Signed in and adding a comment | Enter the comment in **Write a comment...**, then select **Post Comment**. |
   | Not signed in and adding a comment | Select **Sign in** or **sign up**. |

**Result:** A selected article action is applied, the comment is submitted, or the
article record is replaced by the home surface that follows a successful deletion.

If an action produces an error, continue to When an article action goes wrong; otherwise,
continue to What to do next.

## When an article action goes wrong

| What you see | What it means | What to do |
| --- | --- | --- |
| `Failed to load article` | The article could not be loaded. | Return to the article route and try again. |
| An error list appears above the Editor | The article request returned an error. | Correct the article information and select **Publish Article** again. |
| The article fields have no required marker | No required marker or validator is declared for these fields. | Enter the information needed for your article, then select **Publish Article**. |
| Selecting **Delete Article** does not open a confirmation step | No confirmation dialog is declared for this action. | Select **Delete Article** only when you intend to delete the article. |

For the broader application message catalogue, see [General error messages](doc:general-error-messages).

If no row above matches what you see, continue to What to do next.

## What to do next

After you submit an article, continue on the article record.
After a successful deletion, the application returns to the home surface.

| If you want to… | Continue with… |
| --- | --- |
| Read the article | [Read an article](doc:read-an-article) |
| Add or remove comments | [Comment on an article](doc:comment-on-an-article) |
| Manage favorite articles | [Favorite articles](doc:favorite-articles) |
| Follow another reader | [Follow a user](doc:follow-a-user) |