vercel / vercel/vercel-plugin

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

Open
#131 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
287
Forks
58
Avg merge
1d 1h
Merged PRs (30d)
17

Description

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.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with README.md:292 and :36, CLAUDE.md:52-59 and :170-175, vercel.md:963, and hooks/hooks.json; compare the documented behavior with the registered hooks and the named injection entry points. Update the documentation to distinguish default behavior from supported opt-in behavior and make troubleshooting observable. Done means the docs no longer present inactive defaults as live and clearly explain any supported opt-in path.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.