docs(skills): invoke-registry-parity — Fresh vs TanStack loader registration

[JonasJesus42]

Summary

Adds .claude/skills/invoke-registry-parity/SKILL.md documenting the architectural difference between Fresh (`@deco/deco`) and TanStack (`@decocms/start`) in how the invoke registry is populated.

In Fresh, `manifestGen.ts` walks every file under `src/loaders/`, `src/actions/` and registers all of them. In TanStack, `scripts/generate-loaders.ts` filters by `__resolveType` references in `.deco/blocks/` when called with `--decofile-dir`, so code-only invocations (header components, hooks, effects) silently 404.

This caused the Bagaggio delivery-promise drawer + popup to never populate after migration. Fix on the site side was dropping `--decofile-dir` from `package.json`'s `generate:loaders`.

Related issues

• generate-loaders.ts: prune-by-decofile should be opt-in, not the template default #189 — propose flipping the default so prune-by-decofile is opt-in
• invoke handler: dev-mode filesystem fallback / actionable 404 for unknown loader keys #190 — propose dev-mode filesystem fallback in `findHandler` + actionable 404

Test plan

• Skill renders correctly when invoked via Claude Code's Skill tool
• Cross-references to other skills (`[[deco-htmx-cache-contamination]]`) resolve

🤖 Generated with Claude Code

---

Summary by cubic

Adds .claude/skills/invoke-registry-parity/SKILL.md explaining why loaders/actions can 404 after migrating from @deco/deco (Fresh) to @decocms/start (TanStack), and how to fix it. This helps teams unblock runtime.site.loaders.X calls that return undefined.

• New Features
  • Documents Fresh auto-discovery vs TanStack prune-by-decofile in generate-loaders.ts.
  • Shows the 404 symptom for /deco/invoke/site/loaders/* and how to detect missing registry entries.
  • Provides site fixes: remove --decofile-dir or manually register loaders/actions.
  • References follow-up framework work (opt-in prune, dev-mode fallback).
  • Includes a real-world case (Bagaggio) with steps and verification.

^{Written for commit 1c322fc. Summary will update on new commits. Review in cubic}

[cubic-dev-ai]

1 issue found across 1 file

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name=".claude/skills/invoke-registry-parity/SKILL.md">

<violation number="1" location=".claude/skills/invoke-registry-parity/SKILL.md:194">
P2: Cross-reference `[[deco-htmx-cache-contamination]]` links to a skill file that does not exist in this repository. Either create that file or remove the reference.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: Cross-reference [[deco-htmx-cache-contamination]] links to a skill file that does not exist in this repository. Either create that file or remove the reference.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At .claude/skills/invoke-registry-parity/SKILL.md, line 194:

<comment>Cross-reference `[[deco-htmx-cache-contamination]]` links to a skill file that does not exist in this repository. Either create that file or remove the reference.</comment>

<file context>
@@ -0,0 +1,206 @@
+- The `@decocms/start` invoke route is `/deco/invoke/...`. Fresh's was `/live/invoke/...`. Both shapes are still accepted on the handler.
+- `setupApps()` in `@decocms/apps` uses `registerInvokeHandlers()` (additive registry) for VTEX/Shopify keys — independent of `setInvokeLoaders()`. The site-side `generate-loaders.ts` only governs `site/*` keys.
+- The same pruning logic also drops loaders that aren't referenced by `__resolveType` even if they're imported in code via `runtime.site.loaders.X`. The static analyzer doesn't see those runtime-string keys.
+- This is closely related to (but distinct from) `[[deco-htmx-cache-contamination]]` — that one is about SSR-cached HTML leaking cookies, this is about invoke routing.
+
+## Bagaggio incident — exact reproduction (2026-05)
</file context>