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

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:

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

gw git commit --write -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