update-waystone-inventory

# Update Waystone Inventory Skill ## When to Activate Activate this skill when: - Adding new `<Waystone>` components to any Grove package - Removing waystones from pages - The waystone-inventory CI check fails - You want to verify the inventory matches actual codebase usage - After merging PRs that add/remove waystones ## Files Involved | File | Purpose | | --------------------------------------------------------------- | --------------------------------------- | | `.github/waystone-inventory.json` | Source of truth for waystone placements | | `libs/engine/src/lib/ui/components/ui/waystone/Waystone.svelte` | Component source | | `docs/specs/waystone-spec.md` | Waystone system specification | ## Inventory Structure The inventory tracks waystones by slug, with each slug containing its instances: ```json { "waystones": { "total": 15, "breakdown": { "engine": 15, "login": 0, "landing": 0 }, "bySlugs": 10 }, "slugs": [ { "slug": "what-is-rings", "usageCount": 2, "instances": [ { "file": "libs/engine/src/routes/arbor/analytics/+page.svelte", "label": "Learn about Rings", "placement": "page-header", "size": "sm" } ] } ] } ``` ## Placement Types When adding instances, use the appropriate placement type: | Type | Description | | ---------------- | ------------------------------------------------ | | `page-header` | Beside `<h1>` titles on major pages | | `section-header` | Beside `<h2>` section titles within pages | | `feature-card` | Inside feature showcase cards | | `inline-help` | Inline with paragraph text for contextual hints | | `error-context` | Within error messages linking to troubleshooting | | `panel-header` | In panel or control headers | | `auth-context` | Near auth-related UI for trust building | ## Step-by-Step Process ### 1. Find All Waystone Usages ```bash # Search for <Waystone in all Svelte files across ALL packages rg '<Waystone' --type svelte -l # Get slug and label details rg '<Waystone' --type svelte -A 3 ``` ### 2. Compare with Inventory ```bash # Read current inventory cat .github/waystone-inventory.json | jq '.waystones.total' # Count actual usages rg '<Waystone' --type svelte | wc -l ``` ### 3. Identify Discrepancies Look for: - **New waystones**: `<Waystone>` tags in code but not in inventory - **Removed waystones**: Instances in inventory whose files no longer contain the waystone - **Changed metadata**: Slug, label, or placement changed ### 4. Update Inventory JSON Edit `.github/waystone-inventory.json`: 1. **Update counts**: ```json "waystones": { "total": <new total instances>, "breakdown": { "engine": <count in engine>, "login": <count in login>, ... }, "bySlugs": <number of distinct slugs> } ``` 2. **Add/update slug entries** — add new slugs to the `slugs` array, or add instances to existing slugs 3. **Update metadata**: ```json "lastUpdated": "YYYY-MM-DD", "lastAuditedBy": "claude/<context>" ``` ### 5. Commit Changes ```bash git commit -m "docs: update waystone inventory - Add <slug> waystone to <package> - Update total: X -> Y - Update package breakdown" ``` ## Quick Reference Commands ```bash # Count all waystone instances across all packages rg '<Waystone' apps/ libs/ services/ workers/ --type svelte | wc -l # List all unique slugs in use rg 'slug="([^"]+)"' apps/ libs/ services/ workers/ --type svelte -o -r '$1' | sort -u # Count instances per directory for dir in apps libs services workers; do count=$(rg '<Waystone' "$dir" --type svelte 2>/dev/null | wc -l | tr -d ' ') echo "$dir: $count" done # Find waystones with specific placement patterns rg '<Waystone' apps/ libs/ services/ workers/ --type svelte -B 2 -A 2 ``` ## Adding a New Waystone (Full Checklist) When adding a new waystone: - [ ] Add `<Waystone>` component to the target file with appropriate slug, label, and size - [ ] Ensure the file imports Waystone (from `$lib/ui` in engine, or `@autumnsgrove/lattice/ui` in other packages) - [ ] Add the instance to `.github/waystone-inventory.json` - [ ] If it's a new slug, add a new entry to the `slugs` array - [ ] If the slug already exists, add an instance to the existing entry - [ ] Update `waystones.total` count - [ ] Update `waystones.breakdown.<package>` count - [ ] Update `waystones.bySlugs` if a new slug was added - [ ] Update `lastUpdated` and `lastAuditedBy` - [ ] Verify the KB article exists (or note it needs to be created) ## CI Integration The `.github/workflows/waystone-inventory.yml` workflow: - Runs on PRs touching `**/*.svelte` files - Counts `<Waystone` occurrences across all packages - Compares to inventory total - Comments on PRs when there's a mismatch - Creates issues for drift on scheduled runs (Thursdays) When CI fails, run this skill to fix the mismatch. ## Checklist Before finishing: - [ ] All `<Waystone>` instances in code have entries in inventory - [ ] All inventory instances still exist in code - [ ] `total` equals sum of all `breakdown` values - [ ] `bySlugs` equals the length of the `slugs` array - [ ] Each slug's `usageCount` matches its `instances` array length - [ ] `lastUpdated` date is today - [ ] Changes committed with descriptive message