# Card Oracle Help Documentation

This comprehensive guide covers all features, settings, and functionality of the Card Oracle Premium plugin for WordPress.

## Table of Contents

1. [Getting Started](#getting-started)
2. [Understanding the Data Model](#understanding-the-data-model)
3. [Creating Readings](#creating-readings)
4. [Working with Cards](#working-with-cards)
5. [Defining Positions](#defining-positions)
6. [Writing Descriptions](#writing-descriptions)
7. [Embedding Readings](#embedding-readings)
8. [Shortcode Reference](#shortcode-reference)
9. [Layout Options](#layout-options)
10. [Settings Configuration](#settings-configuration)
11. [Premium Features](#premium-features)
12. [Payment Integration](#payment-integration)
13. [Email Integration](#email-integration)
14. [Demo Data](#demo-data)
15. [Frequently Asked Questions](#frequently-asked-questions)

---

## Getting Started

### Installation

1. Upload the `card-oracle-premium` folder to `/wp-content/plugins/`
2. Activate the plugin through the **Plugins** menu in WordPress
3. Navigate to **Card Oracle** in the admin sidebar to begin

### Quick Start Workflow

1. Go to **Card Oracle > Wizard** and use the Template Builder
2. Enter a reading name, number of positions, and number of cards
3. Click **Create Template** to generate all required posts
4. Edit the generated content to add your interpretations
5. Embed the reading on any page using the shortcode or Gutenberg block
6. Find the shortcode either on the individual reading record in the readings overview page (Card Oracle > Readings) or at the bottom of the Dashboard (Card Oracle > Dashboard)

### Activating Premium Features

1. Navigate to **Card Oracle > Premium**
2. Connect your Freemius account with a valid license
3. Premium features unlock automatically after activation

---

## Understanding the Data Model

Card Oracle uses four custom post types that work together:

### Readings (`co_readings`)
The container for a spread. Stores layout preferences, shuffle settings, and pricing.

### Positions (`co_positions`)
Individual slots within a reading. Each position has an order number that determines display sequence.

### Cards (`co_cards`)
The tarot or oracle cards in your deck. Each card can have a featured image and default description.

### Descriptions (`co_descriptions`)
The interpretations linking specific cards to specific positions. This is where you write what each card means when it appears in a particular position.

### How They Connect

```
Reading (e.g., "Celtic Cross")
    ├── Position 1 ("The Situation")
    ├── Position 2 ("The Challenge")
    ├── Position 3 ("The Past")
    └── ...

Cards (e.g., Major Arcana deck)
    ├── The Fool
    ├── The Magician
    ├── The High Priestess
    └── ...

Descriptions (Card + Position = Interpretation)
    ├── "The Fool" in "The Situation" = "New beginnings..."
    ├── "The Fool" in "The Challenge" = "Fear of the unknown..."
    └── ...
```

---

## Creating Readings

### Method 1: Template Builder (Recommended)

1. Go to **Card Oracle > Dashboard > Wizard**
2. In the Template Builder section, enter:
   - **Reading name**: The title of your spread
   - **Number of positions**: How many card slots
   - **Number of cards**: How many unique cards
   - **Position prefix**: Optional custom prefix (default: "Position")
   - **Card prefix**: Optional custom prefix (default: "Card")
3. Click **Create Template**
4. The wizard creates:
   - 1 Reading post
   - N Position posts (with order fields pre-filled)
   - N Card posts
   - N x M Description posts (cards × positions)

### Method 2: Manual Creation

1. **Create the Reading**:
   - Go to **Card Oracle > Readings > Add New**
   - Enter title and description
   - Configure layout settings in the meta boxes
   - Publish

2. **Add Positions**:
   - Go to **Card Oracle > Positions > Add New**
   - Enter position title (e.g., "Position 1 - Past")
   - Select the parent Reading
   - Set the Order field (1, 2, 3, etc.)
   - Publish and repeat

3. **Add Cards**:
   - Go to **Card Oracle > Cards > Add New**
   - Enter card title
   - Upload a featured image
   - Select the parent Reading
   - Publish and repeat

4. **Create Descriptions**:
   - Go to **Card Oracle > Descriptions > Add New**
   - Select the Card and Position
   - Write the upright interpretation in the editor
   - Add reversed interpretation (premium)
   - Publish and repeat for all card-position combinations

---

## Working with Cards

### Adding Card Images

1. Edit the card post
2. In the right sidebar, click **Set featured image**
3. Upload or select an image from the media library
4. Update the post

### Card Naming Conventions

- Use meaningful card names (e.g., "The Fool", "King of Cups")
- Keep names consistent with your descriptions
- Featured images display on the frontend during readings

### Card Organization

- Cards are associated with readings via the `CO_READING_ID` meta field
- You can reuse card images across multiple readings
- Filter cards by reading in the admin list view of the Cards overview page

---

## Defining Positions

### Position Order

The **Order** field determines where the position appears in the spread:
- Order 1 = First position
- Order 2 = Second position
- And so on...

Positions render in ascending order.

### Position Titles

Use descriptive titles that help users understand each position's meaning:
- "Position 1 - Past Influences"
- "Position 2 - Present Situation"
- "Position 3 - Future Outcome"

### Reordering Positions

1. Edit each position
2. Update the Order field
3. Save changes

Alternatively, use the Wizard's drag-and-drop interface for bulk reordering.

---

## Writing Descriptions

### Description Structure

Each description links one card to one position with an interpretation.

**Required fields:**
- **Card**: Select from dropdown
- **Position**: Select from dropdown
- **Upright Meaning**: Main editor content

**Premium fields:**
- **Reversed Meaning**: Interpretation when card appears reversed

### Best Practices

1. **Be specific to the position**: "The Fool in the Past position suggests..."
2. **Write for the reader**: Use second person ("You may find...")
3. **Cover both aspects**: Include upright and reversed meanings (NOTE: you will need the Premium version for reversed meanings)
4. **Keep it concise**: 2-4 sentences per interpretation works well

### Bulk Editing Tips

- Use the Descriptions list filter to show entries for a specific reading
- The title convention "Card Name - Position Name" helps with sorting
- Consider using a spreadsheet to draft content, then copy/paste

---

## Embedding Readings

### Using Shortcodes

Add to any post, page, or widget:

```
[card-oracle name="your-reading-slug"]
```

### Using the Gutenberg Block

1. Edit a post or page in the Block Editor
2. Add a new block and search for "Card Oracle Reading"
3. Select your reading from the dropdown
4. Configure display options in the sidebar
5. Preview shows the actual reading appearance

### Using PHP Templates

```php
<?php echo do_shortcode('[card-oracle name="reading-slug"]'); ?>
```

---

## Shortcode Reference

### Main Reading Shortcode

```
[card-oracle]
```

| Parameter | Values | Description |
|-----------|--------|-------------|
| `name` | slug | Reading slug (preferred) |
| `id` | number | Reading post ID |
| `deck_layout` | standard, overlapping, circular*, spread* | Card deck presentation |
| `presentation` | standard, mobile, three_layout_1, etc. | Layout template |
| `show_layout_table` | yes, no | Display position reference |
| `display_question` | yes, no | Show question input |
| `question_layout` | card-oracle-form-left, right, top, bottom | Question position |

*Premium only

**Examples:**
```
[card-oracle name="celtic-cross"]
[card-oracle id="123" deck_layout="overlapping"]
[card-oracle name="love-reading" display_question="yes" question_layout="card-oracle-form-top"]
```

### Daily Card Shortcode

```
[card-oracle-daily name="reading-slug"]
```

Displays a single card that rotates daily at midnight. Cached using transients.

| Parameter | Values | Description |
|-----------|--------|-------------|
| `name` | slug | Reading slug |
| `id` | number | Reading post ID |
| `email` | true | Format for email output |

### Random Card Shortcode

```
[card-oracle-random name="reading-slug"]
```

Displays a random card with configurable cache duration (default: 10 minutes, for any other display time, update the 'Days to display random card' field on Card Oracle > Dashboard > General tab -> Configuration > General Settings).

| Parameter | Values | Description |
|-----------|--------|-------------|
| `name` | slug | Reading slug |
| `id` | number | Reading post ID |

---

## Layout Options

### Deck Layouts

Control how the card deck appears:

| Layout | Description | Availability |
|--------|-------------|--------------|
| **Standard** | Cards in a horizontal row | Free |
| **Overlapping** | Cards layered with overlap effect | Free |
| **Circular** | Cards arranged in a wheel pattern | Premium |
| **Spread** | Custom positional visualization | Premium |

### Presentation Layouts

Control the overall page template:

| Layout | Description |
|--------|-------------|
| **Standard** | Full-width card selection and results |
| **Mobile** | Single-column mobile-optimized layout |
| **Three Layout 1** | Three-card spread variation 1 |
| **Three Layout 2** | Three-card spread variation 2 |
| **Extended** | Premium variations are available with additional elements |

### Question Layouts

Control where the question input appears:

| Layout | Position |
|--------|----------|
| `card-oracle-form-left` | Left sidebar |
| `card-oracle-form-right` | Right sidebar |
| `card-oracle-form-top` | Above reading |
| `card-oracle-form-bottom` | Below reading |

---

## Settings Configuration

Access via **Card Oracle > Dashboard > General**.

### General Settings Tab

| Setting | Description |
|---------|-------------|
| Enable RSS Feed | Toggle for daily reading RSS functionality (premium). Used for creating an RSS feed for Daily Cards that can be fed into Social Media Account management tools e.g. SocialBee |
| Cache TTL | Transient cache duration in seconds. This controls how long new media might take to update on the front end of the website |
| Debug Logging | Enable error log collection |
| Default Reading | Primary reading selection |
| Default Draw Count | Number of cards drawn per reading |

### Reading Meta Box Settings

Configure per-reading in the edit screen:

| Setting | Description |
|---------|-------------|
| Deck Layout | Card presentation style |
| Presentation Layout | Frontend display template |
| Question Layout | Position of question input |
| Reverse Percentage | Incidence (0-100%) of reversed cards |
| Show Layout Table | Display position reference table |
| Display Question | Show question input field |
| Auto Submit | Automatic form submission behavior |
| Price | Reading cost (premium) |
| Subscriber List | Default email list (premium) |

---

## Premium Features

Premium features require an active Freemius license.

### Layout Features
- Circular deck layout
- Spread deck layout
- Extended presentation layouts
- Advanced mobile layouts

### Payment Features
- PayPal Standard integration
- Stripe payment forms
- Order tracking and management
- Per-reading pricing

### Email Features
- MailChimp integration
- ActiveCampaign integration
- Brevo integration
- Automated reading delivery
- Subscription management

### Additional Features
- Reversed card descriptions
- RSS feed generation
- Automated cron jobs
- Webhook integrations

---

## Payment Integration

### PayPal Setup (Premium)

1. Go to **Card Oracle > Dashboard > Payment Provider**
2. Enter your PayPal credentials:
   - PayPal username
3. Select currency and checkout language
4. Toggle sandbox mode for testing
5. Save changes

### Stripe Setup (Premium)

1. Go to **Card Oracle > Dashboard > Payment Provider**
2. Enter your Stripe credentials:
   - Publishable key
   - Secret key
3. Configure webhook endpoint in Stripe dashboard
4. Toggle sandbox mode for testing
5. Save changes

### Setting Reading Prices

1. Edit the reading post
2. In the meta box, enter the price
3. Save the reading
4. Payment form displays automatically when price is set
5. Currency displayed is taken from the currency you have defined on your payment provider

### Payment Flow

1. User selects cards and views reading preview
2. If reading has a price, payment form appears
3. User completes payment via PayPal or Stripe. Please note integration with Stripe to send reader back to see the rest of the reading is currently automatic. PayPal requires you to set up an IPN (Instant Payment Notification) to ensure reading doesn't refresh 
4. On success: Order created, full reading displayed
5. Email sent to user with reading results (if configured)

---

## Email Integration

Email integration will required you to have an email server setup on your WordPress site. Typically we suggest using a third party plugin such as e.g. WP Mail SMTP - not affiliated, tested or recommended - to do this.

### MailChimp Setup (Premium)

1. Go to **Card Oracle > Dashboard > Integrations**
2. Enter your MailChimp API key
3. Select default audience/list
4. Configure merge field mapping
5. Save changes

### ActiveCampaign Setup (Premium)

1. Go to **Card Oracle > Dashboard > Integrations**
2. Enter your ActiveCampaign API URL
3. Enter your API key
4. Select default list
5. Configure tag assignments
6. Save changes

### Brevo Setup (Premium)

1. Go to **Card Oracle > Dashboard > Integrations**
2. Enter your Brevo API key
3. Select default contact list
4. Save changes

### Email Settings

| Setting | Description |
|---------|-------------|
| From Email | Sender email address |
| From Name | Sender display name |
| Enable Delivery | Toggle automated email delivery |
| Template | Email format customization |

### Per-Reading Lists

Override the default list for specific readings:
1. Edit the reading
2. Select a different subscriber list in the meta box
3. Save changes

---

## Demo Data

### Installing Demo Readings

1. Go to **Card Oracle > Demo Data**
2. Browse available reading tiles
3. Click **Install Reading** on your selection
4. Optionally check **Insert Images** to include Marseille artwork

### Available Demo Readings

Demo readings are stored as JSON files in `assets/readings/`:
- Past-Present-Future
- And more...

---

## Frequently Asked Questions

### General Questions

**Q: How many readings can I create?**
A: There is no limit with the Premium version - create as many readings as you need. The free version gives you three published readings.

**Q: Can I use Card Oracle with any theme?**
A: Yes, Card Oracle works with any properly-coded WordPress theme. Some layout adjustments may be needed for optimal display.

**Q: Is Card Oracle compatible with page builders?**
A: Yes, use the shortcodes within any page builder that supports WordPress shortcodes.

### Technical Questions

**Q: Why isn't my reading appearing in the dropdown?**
A: Ensure the reading is published (not draft or trashed). The REST endpoint only returns published posts.

**Q: Why are positions out of order?**
A: Check the Order field on each position. Positions display in ascending order by this field.

**Q: Why is a description missing from the reading?**
A: You need a description entry for every card-position combination you want to display. Check that the description exists and has both card and position assigned.

**Q: How do I change the daily card?**
A: The daily card rotates automatically at midnight. 

### Premium Questions

**Q: How do I activate premium features?**
A: Go to Card Oracle > Account and connect your Freemius account with a valid license.

**Q: Can I test payments before going live?**
A: Yes, both PayPal and Stripe support sandbox/test modes. Enable sandbox mode in Dashboard > Payment Provider.

**Q: How do I troubleshoot email delivery?**
A: Check the integration settings, verify API keys, and enable debug logging to capture errors.

### Content Questions

**Q: How many descriptions do I need?**
A: For complete coverage, you need one description for every card-position combination. For a 10-card, 10-position reading, that's 100 descriptions.

**Q: Can cards be used in multiple readings?**
A: Cards are associated with specific readings. To use the same card imagery across readings, create separate card posts and use the same featured image.

**Q: What image size works best for cards?**
A: Recommended: 320x620 pixels or similar portrait ratio. Images are responsive and scale appropriately.

---

## Getting Help

- **Documentation**: This help file and related docs in `/docs/`
- **Status Tab**: Card Oracle > Status for diagnostics
- **Support**: Contact support@chillichalli.com

See also:
- [User Guide](user-guide.md)
- [Wizard Guide](wizard-guide.md)
- [Troubleshooting Guide](troubleshooting.md)
- [Architecture Guide](architecture.md)