# Card Oracle User Guide

This guide introduces the Card Oracle Premium plugin, explains how it fits into your WordPress site, and walks through
the two primary ways to create a new tarot/oracle reading: using the Setup Wizard and building one manually. It also
highlights supporting tasks such as adding cards and descriptions, embedding readings on the front end, and keeping the
plugin up to date.

## 1. What the Plugin Does

Card Oracle turns WordPress into a tarot/oracle reading management system. Administrators can:

- Create spreads with the `Card Oracle` custom post types (`co_readings`, `co_positions`, `co_cards`, `co_descriptions`).
- Deliver “daily”, “random”, or full multi-card readings via shortcodes, widgets, and a Gutenberg block.
- Attach card imagery, define upright/reversed descriptions, and control deck layouts and presentation markup.
- Offer premium-only layouts, emailed readings, and integrations when the Freemius license is connected.

Front-end visitors can request readings through embedded shortcodes or blocks. The plugin handles card shuffling, deck
layout rendering, and displaying per-position meanings drawn from the descriptions catalog.

## 2. Prerequisites and Access

1. Install and activate Card Oracle Premium in `/wp-admin/plugins.php`.
2. Connect your Freemius license if you need premium-only layouts or automations (`Card Oracle → Premium` tab).
3. Ensure you have appropriate WordPress user capabilities (typically `manage_options`) to be able to create readings.
4. Optional: run `Card Oracle → Status → Wizard → “Load Demo Data”` to explore prebuilt spreads, before creating your
   own.

## 3. Navigating the Admin Area

Once activated, Card Oracle registers several admin menu entries under **Card Oracle**:

- **Dashboard**: Summary widgets, general settings, email settings, integrations, payment providers, the setup wizard, status (for trouble-shooting) and quick links. Note - the Guided Setup Wizard and new Template Builder act as a shortcut for scaffolding readings.
- **Readings / Positions / Cards / Descriptions**: Custom post type list available options for manual management.
- **Demo Data**: Modern installer that seeds curated spreads from JSON bundles under `assets/readings/`.
- **Documentation**: Full documentation of every aspect of the Plugin.
- **Purchased Readings**: Showing purchases made by Card Oracle users.
- **Validation**: Setup validation, showing any errors and providing links to correct them.
- **Affiliation**: Become a Card Oracle affiliate and earn cash for recommending us.
- **Account**: your account details and management.
- **Contact Us**: Where you can get in touch.
- **Support Forum**: Search for solutions to any problems you might encounter.


### 3.1 Custom Post Type Cheat Sheet

| CPT | Purpose | Key Meta |
| --- | --- | --- |
| `co_readings` | Container for a spread (name, deck/presentation layout, shuffle behaviours). | `CO_PRESENTATION_LAYOUT`, `CO_REVERSE_PERCENT`, premium toggles. |
| `co_positions` | Individual slots in a spread, stored with numeric order. | `CO_READING_ID`, `CO_CARD_ORDER`. |
| `co_cards` | Tarot/oracle cards (title, optional description and featured image). | `CO_READING_ID`, premium pricing metadata. |
| `co_descriptions` | Pairings of a card and position with upright/reversed meanings. | `CO_CARD_ID`, `CO_POSITION_ID`, `CO_REVERSE_DESCRIPTION`. |

### 3.2 Installing Demo Readings

Use **Card Oracle → Demo Data** to explore sample spreads before creating your own. The page now lists every JSON file in
`assets/readings/` and displays them as tiles alongside card/position counts and HTML descriptions.

- Click **Install Reading** to import the selected reading bundle. The importer prevents duplicates, so if the reading already exists
  you’ll see a warning instead of a second copy.
- Files with `__premium_only.json` in the filename show a Premium badge and require an active Premium licence to install.
- The optional **Insert Images** panel uploads the copyright-free Marseille deck artwork and stores each attachment as
  `Marseille - {Card Name}` for easy filtering in the standard WordPress media library.

## 4. Creating a Reading with the Setup Wizard

The Setup Wizard is the fastest way to assemble all related posts at once.

1. Go to **Card Oracle → Dashboard → Wizard**.
2. In **Template Builder**, enter:
   - *Reading name*: e.g., “Past-Present-Future”.
   - *Number of positions*: total positions in the spread.
   - *Number of cards*: this number typically matches the position count.
   - Optional prefixes for positions and cards (defaults to “Position” / “Card”). NOTE: you can easily note which positions and cards are linked with a particular reading here by using the name of the reading as the prefix. This will make reading management easier as your number of readings increases.
3. Click **Create Template**. The Template Builder scaffolds the reading, positions, cards, and descriptions (all are left blank) using
   the counts that you supplied.
4. Review the confirmation notice. The wizard stores your new assets and you can jump to editing them from the success
   message or the corresponding post list pages (found under the Readings, Positions, Cards menu items).
5. (Optional) Use the Reading Builder section below Template Builder if you’d rather add positions/cards one at a time before
   generating the reading. Save the reading title, list all positions, list all cards, then press **Create Reading**.
6. After scaffolding completes:
   - Edit each **Position** (`Card Oracle → Positions`) to adjust the order or rename placeholder titles.
   - Edit each **Card** (`Card Oracle → Cards`) to upload imagery and add detailed descriptions.
   - Fill in **Descriptions** (`Card Oracle → Descriptions`) with upright/reversed meanings for every card/position pair.

### Tips for the Wizard

- The Template Builder resets to blank after each successful run. If validation fails, your input stays on screen, and the
  error messages explain what needs adjusting.
- Use prefixes to tailor generated titles to your spread’s theme. You can still edit titles later.
- Remember to upload featured images for cards; the wizard leaves media management completely up to you.
- If you do not want to use the full automation of the Template Builder, you can use the Reading Builder on the same page. This gives you more control over names etc.

## 5. Creating a Reading Manually

Manual creation gives you full control over every post and is ideal when you already have card content prepared.

### 5.1 Create the Reading Container

1. Navigate to **Card Oracle → Readings → Add New**.
2. Enter the reading title and optional description.
3. Configure meta boxes:
   - **General**: select deck layout, presentation layout, question layout, and display toggles. NOTE: You can automatically submit the reading when the last card is selected by the user. When enabled (YES), the submit button is hidden from the user. ADDITIONALLY, only Layouts with the same number of positions as the reading will be available in the dropdown. Otherwise, the Submit button is only enabled once all cards have been selected.
   - **Display Question Options**: choose to display (or not) an input field to the users to enter a question, add text for the question input box. NOTE: do not use apostrophes in this text if you plan on allowing users to email the readings.
- **Text to display before Cards**: choose to display (or not) text before the cards.
- **Footer to be displayed on daily and random cards**: choose to display (or not) text on daily and random card readings.


4. Click **Publish**.

### 5.2 Add Positions

1. Go to **Card Oracle → Positions → Add New**.
2. Title the position (e.g., “Position 1 – Current Situation”).
3. Set the appropriate **Reading** in the sidebar meta box (the `CO_READING_ID` dropdown). NOTE: This is where you link a specific Position to a specific Reading.
4. Assign the **Order** field. Positions render ascending, so `1` is the first slot.
5. Publish and repeat for every position in the reading spread.

### 5.3 Add Cards

Note: existing cards can be added to new Readings.

1. Visit **Card Oracle → Cards → Add New**.
2. Title the card and add any default interpretation in the editor (optional).
3. Choose the related **Reading** in the meta box. NOTE: This is where you link a specific Card to a specific Reading.
4. Upload a featured image if desired. NOTE: if you do not, then no image will be displayed to the end user.
5. Publish and repeat until all cards for the spread exist.

### 5.4 Link Cards to Positions via Descriptions

1. Open **Card Oracle → Descriptions → Add New**.
2. The title convention follows “Card – Position” (e.g., “The Fool – Position 1”). Matching the format helps list-table
   filtering but is not required.
3. Enter the upright meaning in the main editor body.
4. Populate the reversed meaning in the “Reversed Description” meta field (premium).
5. In the meta box:
   - Select the **Card** associated with this description.
   - Select the **Position** associated with this description.
6. Publish and repeat for every card/position combo you want to interpret. The front end displays the matching description
   when a card lands in that position.

## 6. Embedding and Publishing the Reading

After your reading is assembled:

- **Shortcode**: Use `[card-oracle name="reading-slug"]` or `[card-oracle id="123"]` inside posts or pages. Combine with
  `layout`, `question_layout`, `show_table`, and `display_question_input` attributes to override defaults. NOTE: you can find the Shortcode assocated with each reading in the Reading Statistics block at the bottom of the Card Oracle Dashboard page, or you can pick it up from the Readings overview page.
- **Gutenberg Block**: Insert the “Card Oracle Reading” block. Select your reading in the sidebar and toggle layout or
  display overrides. Copy the generated shortcode from the preview if you need to reuse it elsewhere.
- **Widgets & Templates**: PHP templates can call `do_shortcode( '[card-oracle name="reading-slug"]' )` or use helper
  functions exposed in `public/class-card-oracle-public.php`.
- **Daily/Random Variants**: Leverage `[card-oracle-daily name="..."]` or `[card-oracle-random name="..."]` to rotate card
  draws using the same reading definition. NOTE: these can be picked up from the Reading Statistics block at the bottom of the Card Oracle Dashboard page.

## 7. Maintaining Content

- Check the **Validation** tab frequently, as this is where Card Oracle flags missing positions, cards, or descriptions for each reading, and then provides links to where corrections need to take place.
- Use bulk edit or the Setup Wizard’s “Clear” buttons when you want a fresh start without deleting individual posts.

## 8. Troubleshooting

- **Reading not appearing in block/shortcode dropdowns**: Confirm the reading is published and has not been trashed. The REST
  endpoint only includes published readings.
- **Positions out of order**: Reorder by editing each position’s `Order` field, or use the Wizard drag-and-drop interface.
- **Description missing**: Card Oracle needs a description entry that matches both the drawn card and the position. Check
  the Descriptions list for missing pairs.
- **Premium layout unavailable**: Verify the site is connected to Freemius and that your license includes premium access.

## 9. Additional Resources

- **Architecture Guide** (`docs/architecture.md`): Deep dive into code flow, module structure, and premium gating.
- **Shortcode Reference**: Open **Card Oracle → Wizard → Help & Docs** links or visit the online documentation for advanced
  embed recipes.
- **Support**: Reach out via the plugin’s support channel or email `support@chillichalli.com` if you encounter bugs or need
  enterprise integrations.

With this guide, you can confidently build and manage new oracle spreads... whether you prefer the streamlined wizard or the
granular manual workflow. Happy reading!