Skip to content

Troubleshooting guidance depends on injection logs that are disabled by default (v0.45.1) #131

Description

@vidaunited

README.md:292, in the "file an issue" checklist, asks reporters for:

What the plugin injected (or didn't) — enable debug logs with VERCEL_PLUGIN_LOG_LEVEL=debug

That cannot produce output on a default install, because the hooks that emit
those logs are not registered.

hooks/hooks.json registers four hooks:

SessionStart -> session-start-seen-skills.mjs
SessionStart -> session-start-profiler.mjs
SessionStart -> inject-claude-md.mjs
SessionEnd   -> session-end-cleanup.mjs

user-prompt-submit-skill-inject.mjs, pretooluse-skill-inject.mjs,
prompt-analysis.mjs, unified-ranker.mjs and lexical-index.mjs all
instantiate the logger but are absent from hooks.json, and no registered hook
imports or spawns them (checked both).

I understand this is intentional — README.md:36 says skills "are no longer
auto-injected on every tool call or every prompt by default" and the engine is
kept "for targeted or future opt-in workflows". The problem is that the rest of
the docs don't reflect it.

Measured on v0.45.1, running the registered hooks directly with
VERCEL_PLUGIN_LOG_LEVEL=trace:

session-start-seen-skills.mjs   stderr: 172 bytes   (one SessionStart line)
session-start-profiler.mjs      stderr: 0 bytes
inject-claude-md.mjs            stderr: 0 bytes     (no logger at all)

So trace — the loudest level — yields a single line about session state and
nothing about injection. A user following README:292 sees silence and cannot
distinguish "plugin decided not to inject" from "logging is broken" from
"plugin never ran".

Docs that read as currently-active but are not, by default:

  • CLAUDE.md:52-59 — describes the SessionStart → PreToolUse → UserPromptSubmit
    injection flow in the present tense, including budgets and dedup
  • CLAUDE.md:170-175 — documents VERCEL_PLUGIN_INJECTION_BUDGET (18000),
    VERCEL_PLUGIN_PROMPT_INJECTION_BUDGET (8000) and
    VERCEL_PLUGIN_TSX_EDIT_COUNT as live knobs
  • vercel.md:963 — documents VERCEL_PLUGIN_HOOK_DEDUP=off, read only by
    prompt-analysis.mjs and user-prompt-submit-skill-inject.mjs, so it is
    currently inert

Suggested fix, in rough priority order:

  1. Amend README:292 so the troubleshooting checklist doesn't depend on logs that
    are off by default — or point at whatever is observable (the SessionStart
    line, active-session.json).
  2. Note in CLAUDE.md's Skill Injection Flow that steps 2 and 3 are not
    registered by default.
  3. Document how to opt in, which README:36 implies is supported ("targeted or
    future opt-in workflows") but does not explain. If there is no supported
    opt-in yet, saying so explicitly would help — the env knobs currently read as
    though there is.

Not asking for the injection hooks to be re-enabled; the lightweight default
seems deliberate and reasonable. This is only about the docs matching it.

Environment: vercel plugin 0.45.1 (claude-plugins-official), macOS, Claude Code.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions