vscode: in-IDE 'Initialize this Project' affordance so new users don't hit the activation chicken-and-egg

[amrmelsayed]

Problem

The VS Code extension's activationEvents are scoped to projects that already contain a .codev/ or codev/ directory:

"activationEvents": [
  "workspaceContains:.codev",
  "workspaceContains:codev"
]

This creates a chicken-and-egg problem for new users: a developer who installs the Codev extension expecting an in-IDE "Get Started" UI to surface on first open of any folder will see nothing. The status bar item, the sidebar, the walkthrough, the preflight — all of them require activation, and activation requires .codev/ or codev/ to already exist. Which requires codev init to have been run from the terminal first.

The discoverability path today is:

1. User installs the extension (from Marketplace or Open VSX).
2. User opens a project folder.
3. Nothing visible in VS Code.
4. User has to know — from external documentation, the GitHub README, a colleague, or the Codev website — that they need to run codev init in their terminal first.
5. Only after codev init lands a .codev/ directory does the extension activate and the walkthrough surface.

This is intentional (zero noise in non-codev projects, which is the vast majority of any user's projects), but the new-user friction is real and measurable. Anyone installing the extension to try out Codev hits a dead end with no in-IDE signal that anything else is needed.

What's not currently in the codebase

• No Codev: Initialize this Project command palette entry.
• No "welcome view" that surfaces in the Codev sidebar when no codev project is detected.
• No fallback activation event (onCommand, onStartupFinished, or onView) that fires in a non-codev folder.
• No setting or one-time prompt that asks "open in a folder without codev — would you like to initialize?"

Proposed surfaces (plan-gate picks)

The fix is a small bootstrap surface; the design decision is which surface(s) and how aggressive the activation footprint becomes. Three reasonable options the plan-gate could pick:

Option A — Command-only (smallest footprint)

Add onCommand:codev.initialize to activationEvents, plus a new Codev: Initialize this Project command palette entry. Users who know the command exists can run it from the palette in any folder; it activates the extension, runs codev init (or shells out to the CLI), and from there the standard Get started with Codev walkthrough handles the rest.

• Pros: zero noise in non-codev projects until the user opts in. Smallest activation cost.
• Cons: discoverability is the same chicken-and-egg — the user has to know the command exists. The palette is searchable but the user has to think to look there.

Option B — Welcome view in the Codev sidebar (medium footprint)

Mark the codev.welcome view as "when": "!codev.workspaceHasProject" and contribute a welcome view that renders a Run codev init button + a one-paragraph explanation. The sidebar's Codev container becomes always-visible (in non-codev folders it shows the welcome, in codev folders it shows the normal views).

Requires either keeping activationEvents permissive (e.g. onStartupFinished, which adds load to every VS Code session) OR contributing the welcome view declaratively in package.json so it renders before activation (VS Code supports viewsWelcome natively without firing the extension's activate()).

• Pros: discoverable. New users see "Codev" in the activity bar / sidebar by default and click into the welcome view to learn what to do. The Run codev init button is one click away.
• Cons: the welcome view is visible in every folder a Codev user opens, including non-codev folders — some users will find that noisy. viewsWelcome declarative form mitigates the activation cost.

Option C — Hybrid: declarative welcome + lazy activation

viewsWelcome declarative contribution provides the always-visible welcome content (no activation cost). When the user clicks Run codev init, that fires a command that does activate the extension and runs the init flow. From then on, the extension is active and the standard preflight + walkthrough handles the rest.

• Pros: discoverable AND zero activation cost until the user opts in. Best of both options.
• Cons: most moving parts; needs careful state handling for "after init completes, switch the sidebar to the normal codev views."

Acceptance criteria

• A Codev: Initialize this Project command is registered and visible in the command palette, regardless of whether .codev/ or codev/ exists in the current folder. It shells out to codev init (with appropriate handling for missing CLI per the existing #791 preflight UX) and on success transitions the extension into the normal active state without requiring a window reload.
• At least one in-IDE affordance (per the plan-gate's chosen option) makes the existence of Codev discoverable to a user who has installed the extension but never run codev init. Options A / B / C above; plan picks.
• Existing workspaceContains activation events stay intact so the standard "open a codev project" UX is unaffected.
• The CLI-not-installed path still routes through the Get started with Codev walkthrough (don't duplicate the install flow).
• Manual verification at the dev-approval gate: spawn the extension in a mkdir /tmp/empty && code /tmp/empty empty folder and confirm the init affordance is discoverable AND that running it produces a working codev project with the standard views populated post-init.

Out of scope

• Replacing the existing Get started with Codev walkthrough. The walkthrough is the right home for the CLI-install / detect / verify steps; this issue adds the prerequisite "first, run codev init from inside VS Code" affordance, not a parallel walkthrough.
• Auto-running codev init without user consent. Initialization writes files to the user's project; it must always be an explicit action.
• Bootstrapping a codev/resources/ layout for fresh projects. That's scaffold: codev init bootstraps empty codev/resources/ with arch.md + lessons-learned.md starters #1012's scope.
• Multi-folder workspace handling beyond the current single-root behavior. Existing detection logic (detectWorkspacePath walks up from workspaceFolders[0]) stays as-is.

Suggested protocol

PIR. The fix is small mechanically (one new command + activation event + possibly a viewsWelcome contribution), but the activation-strategy decision (Option A / B / C) is a real UX trade-off worth locking before code. Plan-gate is the right place; dev-approval gate has visible behavior (open VS Code in an empty folder and look) so the human review is concrete.

The CMAP at PR is the usual single advisory pass per PIR's convention.

Related

• vscode: startup preflight — verify codev CLI installed and version ≥ extension version; guide install/upgrade otherwise #791 — the existing CLI preflight + Get started with Codev walkthrough. The init affordance complements this, doesn't replace it.
• vscode: guarded-command feedback is silent after first click — replace setupToastShown one-shot suppression with modal-first / ephemeral-after pattern #989 — guarded-command feedback pattern; the init command should hook into the same showPreflightFeedback helper if the CLI is missing.
• scaffold: codev init bootstraps empty codev/resources/ with arch.md + lessons-learned.md starters #1012 — codev init bootstrap for codev/resources/. Different scope (init content, not init trigger), but a related improvement to the first-run UX.
• The existing detectWorkspacePath / findProjectRoot logic in packages/vscode/src/workspace-detector.ts:27 — needs no change beyond the fact that newly-init'd projects will start resolving non-null after the init runs.