Monorepo layout: introduce apps/ for end-user surfaces

[amrmelsayed]

Goal

Adopt an apps/ vs packages/ split so end-user client surfaces (web UI, VS Code extension, future mobile app) are a discoverable peer set, distinct from shared libraries.

Motivation

A mobile app is on the horizon. Today all six packages share packages/*. Adding apps/mobile while leaving the existing end-user clients under packages/ is the worst option — a new contributor would see apps/mobile, packages/vscode, packages/dashboard and reasonably ask why three end-user clients live in different directories. Half-applied conventions cost cognition without paying for it. Either go all-in on the split or stay all-in on packages/.

Proposal

Move

• packages/vscode → apps/vscode
• packages/dashboard → apps/web (rename — see below)
• New apps/mobile lands fresh when built

Unchanged

• packages/codev, packages/core, packages/types, packages/config — stay where they are. Not in scope for this proposal.

Workspace glob

packages:
 - packages/*
 - apps/*

Reasoning per decision

Why apps/ vs packages/ at all

End-user clients and shared libraries have different lifecycles, different release cadences, different ownership. Exposing the distinction in directory structure improves navigability and matches widely-used monorepo conventions (Turborepo, Next.js, Vercel templates).

Why web (not dashboard)

• Functional accuracy: the package exposes the full Tower management surface (workspace overview, builder spawn, file browse, terminal attach, PR view, send messages) — far more than a dashboard
• Symmetry: web / mobile / vscode all describe where the client lives in the user's life
• Future-proof: marketing pages, settings, billing portals would still fit under web
• Convention: Turborepo's default app name
• Package-name impact: @cluesmith/codev-dashboard is private: true — renaming has zero external blast radius (referenced only internally via workspace:*)
• User-facing brand stays separate: the product surface can still be called "Dashboard" to users if desired; this is a directory decision, not a brand decision

Why mobile (not native)

• All other directory names describe surface (where the client lives). native would describe implementation tech, breaking the axis.
• React Native is precisely the ambiguous case — branded "native" but isn't really. apps/native amplifies the confusion rather than resolving it.
• Stable under tech refactor: mobile stays accurate whether the implementation is React Native, Flutter, or future native Swift+Kotlin.
• Matches the product positioning ("Codev on the go", 30-second attention windows).

Migration cost (per package moved)

What changes:

• pnpm-workspace.yaml: one-line glob addition (does not need to change again per package after that)
• CI workflows referencing packages/<name>/** paths — grep + replace
• scripts/local-install.sh and release scripts — grep + replace
• Docs (CLAUDE.md, AGENTS.md, README, others) — grep + replace
• Git history: preserved across renames; git log --follow is the cost paid by readers

What does NOT change:

• pnpm workspace dependencies (workspace:* resolves by package name, not path)
• npm publish (package names are independent of source location)
• VS Code Marketplace publish (keys off the package, not the directory)
• TypeScript path mappings that use package names rather than relative paths

Suggested phasing

1. Add apps/* to the workspace glob (one-line PR).
2. Move apps/vscode/ — lowest risk; marketplace publish, no npm dependency from other packages.
3. Move + rename apps/web/ — private package, internal-only references.
4. apps/mobile/ lands fresh when mobile work begins.

Questions for the team

1. Is the apps/ vs packages/ split worth the migration cost, or stay with packages/* and let packages/mobile join the existing convention?
2. Rename the npm package name @cluesmith/codev-dashboard → @cluesmith/codev-web in the same PR (it's private, so risk is internal-only)?
3. User-facing "Dashboard" brand: stays as-is, or rebrand alongside the directory rename?
4. Better naming candidates anyone wants to argue for — dashboard over web, native over mobile, etc.?

[amrmelsayed]

On it! Working on this with the PIR protocol (plan + dev-approval gates before PR).

[amrmelsayed]

Decisions (resolved with reviewer, 2026-07-16 — see codev/plans/855-monorepo-layout-introduce-apps.md):

1. Split: proceeding, all in one PR (supersedes the 3-PR phasing in the description).
2. Package rename @cluesmith/codev-dashboard → @cluesmith/codev-web: yes (private package, internal-only blast radius: one dependency entry + three test imports).
3. User-facing "Dashboard" product word: kept as-is — this is a directory + package-name rename only; the area/dashboard label, "Tower dashboard" comments, and UI copy stay untouched.
4. web / mobile / vscode surface axis kept. The single-Expo/React-Native-Web-app option (one codebase for web + mobile) was researched and rejected — it reinforces this split rather than changing it. Basis: the project's own mobile research already decided it (codev/research/mobile/interaction-model.md §7.1 "Do NOT merge apps/web and apps/mobile"), corroborated by fresh external evidence. The genuinely reusable value is the data/logic layer (a future packages/tower-sdk), not a unified view layer.

Note: package count is now 7 — @cluesmith/codev-artifact-canvas was added since this issue was filed and stays in packages/ (shared React rendering library, not an end-user surface).