-- Support article deploy script — Build Your First Schedule (Spec 051 T0.4 fallback)
-- Generated: 2026-09-04 21:07:40
-- Source: local kiosk_buykiosk.support_articles row (id=117) — this article
--         has no markdown source file under docs/support-articles/; it was authored
--         directly into the local DB during the driver.js spike. See
--         docs/specs/051-scheduling-onboarding/spikes/driver-js-spike.md §6.
-- Target: production kiosk_buykiosk DB
--
-- Scope: 1 article in the Scheduling category — walkthrough M11-08 fallback
--   (deep link + support article for stores where the interactive driver.js
--   walkthrough is unavailable or the engine fails to load)
--
-- Idempotent: safe to re-run. Matching is by slug, not by ID.
-- Wrapped in a transaction; existing prod state (status, view_count,
-- author_id, is_featured) is preserved on ON DUPLICATE KEY UPDATE.
--
-- Recommended invocation:
--   mysql --default-character-set=utf8mb4 -h <prod-host> -u <user> -p kiosk_buykiosk \
--     < deploy-support-article-first-schedule-deploy.sql
--
-- No new image files referenced by this article.

START TRANSACTION;

-- ---- Article #117: Build Your First Schedule (slug=build-your-first-schedule, status=published, category=scheduling, 4492 bytes) ----
INSERT INTO support_articles
    (category_id, title, slug, content_md, content_html, author_id,
     status, view_count, is_featured, created_at, updated_at)
VALUES (
    (SELECT id FROM support_categories WHERE slug = 'scheduling' LIMIT 1),
    'Build Your First Schedule',
    'build-your-first-schedule',
    'Ready to build your first week of shifts? This guide walks through the four things every store does to go from a blank calendar to a published schedule: create a shift, create an open shift with a required position, let AI fill it, and publish. It takes about five minutes.\n\n<br>\n*The four-step path from an empty calendar to a published, staffed schedule.*\n\n***\n\n## Before You Start\n\nNavigate to **Scheduling** \\> **Schedule Calendar** from the admin sidebar, or go directly to `/admin/{store}/schedule`. Make sure you have at least one position created (Scheduling Settings) and a few team members added — you\'ll need both to fill shifts.\n\n***\n\n## Step 1: Create a Shift\n\n1. Click on any empty cell in the calendar grid — the intersection of an employee\'s row and a day column.\n2. A shift creation form appears with start time, end time, and position fields.\n3. Set the shift details and click `Save`.\n\nThis assigns the shift directly to that employee. You\'ll see it appear as a colored block on the calendar.\n\n> **Tip:** You can also drag an existing shift to a different day or employee row to move it, or hold `Ctrl` (`Cmd` on Mac) while dragging to copy it.\n\n***\n\n## Step 2: Create an Open Shift with a Required Position\n\nOpen shifts are unassigned shifts that any qualified employee can claim through the mobile app or the approval queue — instead of scheduling a specific person, you\'re scheduling a *role*.\n\n1. Click the `Open` button in the toolbar to show the **Open Shifts** row at the top of the calendar, if it isn\'t already visible.\n2. Click an empty cell in the Open Shifts row for the day you need coverage.\n3. Set the start time, end time, and — importantly — the **required position** (for example, Shift Lead or Buyer). This position requirement is what determines who\'s eligible to claim it or be assigned to it by AI.\n4. Click `Save`.\n\nYour open shift now appears in the Open Shifts row, waiting to be filled.\n\n***\n\n## Step 3: Run AI Fill\n\nWith at least one open shift on the calendar, you\'re ready to let AI suggest who should work it.\n\n1. Click `Generate with AI` in the toolbar.\n2. The system reviews employee availability, position qualifications, historical patterns, and labor budget to suggest assignments for your open shifts.\n3. Review the suggestions — each one shows who\'s proposed and why.\n4. Click `Apply` to accept the suggestions you want, or `Dismiss All` to discard the set and try again.\n\n> **Tip:** AI can only assign employees who have availability set for the week and who qualify for the shift\'s required position. If a shift comes back unfilled, expand it to see the specific reason (no qualified employees available, everyone at max hours, etc.).\n\nApplied AI assignments become regular shifts — you can edit, move, or delete them like any other shift afterward.\n\n***\n\n## Step 4: Publish\n\nYour schedule isn\'t visible to your team until you publish it.\n\n1. Check the schedule status shown in the toolbar (`DRAFT` or `PUBLISHED`).\n2. Review the week for accuracy — coverage, overtime, and any remaining open shifts.\n3. Click `Publish Changes`.\n\nOnce published, employees are notified and can see their shifts on the mobile app and the My Schedule page.\n\n> **Tip:** You can always come back and adjust a published schedule — just remember to publish again after making changes so your team sees the update.\n\n***\n\n## Frequently Asked Questions\n\n### Do I have to create an open shift before using AI fill?\n\nYes — AI fill only assigns employees to **open (unassigned) shifts**. If your week has no open shifts, there\'s nothing for it to fill. Create at least one open shift with a required position first (Step 2).\n\n### What if AI can\'t fill a shift?\n\nCommon reasons: no qualified employees available during that time slot, everyone eligible is already at max hours, or a time-off conflict. Expand the unfilled shift on the calendar to see the specific reason, and adjust availability or the position requirement as needed.\n\n### Can I publish with open shifts still unfilled?\n\nYes. Open shifts remain visible and claimable by employees through the mobile app even after you publish — publishing doesn\'t require every shift to be assigned.\n\n### Where do I go to try this?\n\nHead to your Schedule Calendar: `/admin/{store}/schedule`.\n\n***\n\n## Related Articles\n\n* Scheduling System — full calendar reference (views, templates, overlays, labor summary)\n* AI Schedule Generation — a deeper look at AI fill, tips, and troubleshooting\n',
    NULL,
    COALESCE((SELECT id FROM kiosk_users.users WHERE username = 'rvanvuren' LIMIT 1), 1),
    'published',
    0,
    1,
    NOW(), NOW()
)
ON DUPLICATE KEY UPDATE
    content_md = VALUES(content_md),
    content_html = NULL,
    category_id = VALUES(category_id),
    title = VALUES(title),
    updated_at = NOW();

COMMIT;

-- ============================================================
-- Verification (uncomment and run after deploy)
-- ============================================================
-- SELECT id, slug, title, status, category_id,
--        LENGTH(content_md) AS bytes, updated_at
--   FROM support_articles
--  WHERE slug = 'build-your-first-schedule';