# Card Oracle Setup Wizard Guide

The Setup Wizard, located in the Card Oracle Dashboard, streamlines the creation of new tarot/oracle spreads by assembling readings, positions, cards, and descriptions from a single screen. This guide explains each portion of the wizard, including the Template Builder that automatically scaffolds placeholder content, and offers tips for iterating on the generated posts.

If you would rather start from a working example, go to **Card Oracle → Demo Data** in the Card Oracle Menu. Every JSON file that's currently available in `assets/readings/`appears as an import tile on the Demo Data screen, so you can install curated spreads (and optional copyright-free Marseille imagery) before tailoring them to your liking. If you import the Demo Data, and then decide you want to clear the data out before creating your own, there is also an option to remove the demo reading(s).

## 1. Opening the Wizard

1. Sign in to WordPress with an account that can manage Card Oracle content (typically this will be a user with the `manage_options`
   capability).
2. Go to **Card Oracle → Wizard** in the wp-admin menu sidebar. The page contains two major areas:
   - **Template Builder**: quickly generate a complete skeleton spread that you can then complete yourself by updating the information in the Readings, Positions and Descriptions sections of Card Oracle.
   - **Reading Builder**: hand-enter your reading name, positions and cards, before clicking the Create Reading button to create the reading yourself.

For the Reading Builder, if you have clicked the individual Save buttons (for the reading, positions and cards), the wizard will remember whatever you enter until you click **Clear All**, so that you can leave and return without losing drafts.

## 2. Using the Template Builder (Recommended)

The Template Builder is designed for speedy setup. It creates the entire spread structure in one click using placeholder
titles that you can refine later.

### 2.1 Choosing Template Settings

| Field | Required? | Purpose | Tips |
| --- | --- | --- | --- |
| **Reading name** | Yes | Title of the spread stored in the Readings section. | Use something descriptive (e.g. “Past-Present-Future”) so that it's easier to find the relevant reading once you have more than one. |
| **Number of positions** | Yes, needs to include at least one position (≥1) | How many card slots the spread contains. | Match the number of cards if every position draws a card. |
| **Number of cards** | Yes, needs to include at least one card (≥1) | How many cards to generate. | You can set a larger number than positions if you plan on using multiple decks. |
| **Position prefix** | Optional | Text that is prepended to each generated position name. You can use position names to identify the reading that they are connected to by using this.| Defaults to “Position”. Use “Stage”, “Path”, or any theme-friendly term. |
| **Card prefix** | Optional | Text added to the start of each generated card title. | Defaults to “Card”. Swap it for deck-specific language if desired. |

### 2.2 Creating the Template

1. Enter values in the Template Builder table.
2. Click **Create Template**.
3. If validation fails, the wizard displays error notices describing what to fix (e.g., missing reading name).
4. When validation succeeds:
   - A success notice confirms that the reading was created.
   - The wizard clears the Template Builder form.
   - New posts are created automatically:
     - One entry in **Card Oracle → Readings**.
     - A position for every count you supplied.
     - A card for every count you supplied.
     - Descriptions linking each generated card to every position (with empty upright/reversed text ready for editing).

### 2.3 Next Steps After Generating a Template

1. **Edit the Reading** (Card Oracle → Readings → Edit) to set the deck and presentation layouts, question prompts, and
   reversed percentages. Please note that only presentation layouts that match the number of cards defined for this reading will be displayed.
2. **Update Positions** to rename placeholder titles and adjust the draw order if needed.
3. **Customize Cards** with imagery and prose. Upload cards as featured images.
4. **Fill Descriptions** by opening each “Card – Position” entry and writing the upright (and optional reversed) meanings.

## 3. Using the Reading Builder (Manual Entry)

If you'd prefer to enter every card and position yourself before creating the spread, you can use the Reading Builder sections that are located directly beneath the Template Builder.

### 3.1 Define the Reading Name

1. In the **Reading** box, type the reading title.
2. Click **Save Reading**—the wizard stores it in the `co_wizard` option but does not create posts until you click the Create Reading button at the bottom of this section.
3. A reminder in the table footer prompts you to save the reading name before moving on.

### 3.2 Add Positions

1. Use the **Positions** table to enter each position name.
2. Press **Add Position** after each entry.
3. Reorder positions by using the drag-and-drop function (requires JavaScript) or adjust them later in the Positions section of the Card Oracle menu.
4. Use the trash icon to remove a position, or **Clear All** to reset the list.

### 3.3 Add Cards

1. Use the **Cards** table to list every card title.
2. Click **Add Card** for each entry. There is no drag and drop functionality here, as it is not relevant.
3. Remove cards with the trash icon or clear the Reading Builder entirely with **Clear All**.

### 3.4 Create the Reading

1. When the reading name, positions, and cards have been populated to your satisfaction, scroll to the bottom action bar.
2. Click **Create Reading**. The wizard validates your data and, if everything looks good, it creates all related posts, which is the
   same output as provided by the Template Builder.
3. Use **Clear All** from the action bar if you want to wipe every field and start over.

## 4. Editing Wizard-Generated Content

Regardless of whether you used the Template Builder or Reading Builder, the newly created posts live in their respective
custom post types. Edit them using the different menu items in the Card Oracle menu, located in the standard WordPress menu:

- **Readings**: adjust layout meta, update titles, modify post content to suit your needs.
- **Positions**: change order values or rename positions. Link positions with a specific reading.
- **Cards**: upload featured images, add main descriptions, link cards to a specific readings.
- **Descriptions**: write meaningful upright and reversed interpretations, then link the description to a specific position. These entries determine what appears in the front-end spread when a card is drawn into a specific position. Note: this is why it's helpful to be able to identify which position is linked with which reading by specifying it in the position name.

## 5. Troubleshooting and Tips

- **Validation errors**: Ensure you provide at least one card and one position, and that the reading name is not empty.
- **Duplicate templates**: Run the Template Builder multiple times if you want variations; each run creates a standalone
  reading.
- **Drag-and-drop sorting**: If reordering positions in the wizard does not work, check for JavaScript errors or deactivate
  conflicting admin scripts temporarily. Positions can be reorganised manually on each position record by updating the Order field.
- **Clearing partial data**: Use the Clear buttons to reset only positions or cards. The wizard stores data in an option so
  another admin can resume without repeating earlier steps.
- **Adding descriptions in bulk**: If you prefer editing descriptions outside the wizard, use the standard WordPress list view filters in
  **Card Oracle → Descriptions** to isolate a specific reading’s entries.

## 6. Related Resources

- **General User Guide** (`docs/user-guide.md`): Overview of the entire plugin, embedding options, and maintenance tips.
- **Architecture Guide** (`docs/architecture.md`): Technical deep dive for developers.

With the wizard, you can go from an idea to a fully-functional spread in a couple of clicks. Use the Template Builder to
bootstrap readings quickly, then refine each card, position, and description to deliver a polished reading experience for your
audience.