update-waystone-inventory

name	update-waystone-inventory
description	Update the waystone (contextual help marker) inventory when waystones are added or removed. Use when adding new waystones, after code reviews flag inventory mismatches, or periodically to ensure docs match reality.

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:

{
	"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

# 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

# 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:

   "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:

   "lastUpdated": "YYYY-MM-DD",
   "lastAuditedBy": "claude/<context>"
   

5. Commit Changes

git commit -m "docs: update waystone inventory

- Add <slug> waystone to <package>
- Update total: X -> Y
- Update package breakdown"

Quick Reference Commands

# 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