feat(local-mode): local-first developer experience with zero-ceremony setup

.github/workflows/e2e.yml

@@ -36,3 +36,5 @@ jobs:
 
       - name: Run e2e tests
         run: bun run test:e2e
+        env:
+          MESH_LOCAL_MODE: "false"

.github/workflows/publish-studio-npm.yaml

@@ -0,0 +1,74 @@
+name: Publish decocms
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "apps/mesh/package.json"
+      - "packages/studio/**"
+  workflow_dispatch:
+
+jobs:
+  publish:
+    name: Publish to npm
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Read mesh version
+        id: mesh-version
+        run: |
+          VERSION=$(node -e "console.log(require('./apps/mesh/package.json').version)")
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+          if [[ "$VERSION" == *-* ]]; then
+            echo "npm-tag=next" >> $GITHUB_OUTPUT
+          else
+            echo "npm-tag=latest" >> $GITHUB_OUTPUT
+          fi
+
+          echo "📦 @decocms/mesh version: $VERSION"
+
+      - name: Check if already published
+        id: check
+        run: |
+          VERSION=${{ steps.mesh-version.outputs.version }}
+          if npm view "decocms@$VERSION" version >/dev/null 2>&1; then
+            echo "skip=true" >> $GITHUB_OUTPUT
+            echo "⏭️ decocms@$VERSION already published"
+          else
+            echo "skip=false" >> $GITHUB_OUTPUT
+            echo "✅ Will publish decocms@$VERSION"
+          fi
+
+      - name: Patch studio package.json
+        if: steps.check.outputs.skip == 'false'
+        run: |
+          VERSION=${{ steps.mesh-version.outputs.version }}
+          cd packages/studio
+          node -e "
+            const pkg = require('./package.json');
+            pkg.version = '$VERSION';
+            pkg.dependencies['@decocms/mesh'] = '$VERSION';
+            require('fs').writeFileSync('package.json', JSON.stringify(pkg, null, 2) + '\n');
+          "
+          echo "✅ Patched to v$VERSION"
+          cat package.json
+
+      - name: Publish to npm
+        if: steps.check.outputs.skip == 'false'
+        run: npm publish --access public --tag ${{ steps.mesh-version.outputs.npm-tag }} --provenance
+        working-directory: packages/studio
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/release.yaml

@@ -143,15 +143,15 @@ jobs:
         uses: softprops/action-gh-release@v2
         with:
           tag_name: v${{ steps.version-check.outputs.current-version }}
-          name: "@decocms/mesh v${{ steps.version-check.outputs.current-version }}"
+          name: "Deco Studio v${{ steps.version-check.outputs.current-version }}"
           body: |
-            ## MCP Mesh v${{ steps.version-check.outputs.current-version }}
+            ## Deco Studio v${{ steps.version-check.outputs.current-version }}
 
-            Self-hostable Virtual MCP for managing AI connections and tools.
+            Open-source control plane for your AI agents.
 
-            ### Install via npm
+            ### Install via Bun
             ```bash
-            bunx @decocms/mesh@${{ steps.version-check.outputs.current-version }}
+            bunx decocms@${{ steps.version-check.outputs.current-version }}
             ```
 
             ### Install via Docker
@@ -175,11 +175,11 @@ jobs:
         run: |
           echo "## Release Summary" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
-          echo "🎉 **@decocms/mesh v${{ steps.version-check.outputs.current-version }} Released**" >> $GITHUB_STEP_SUMMARY
+          echo "🎉 **Deco Studio v${{ steps.version-check.outputs.current-version }} Released**" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
           echo "### npm" >> $GITHUB_STEP_SUMMARY
           echo "\`\`\`bash" >> $GITHUB_STEP_SUMMARY
-          echo "bunx @decocms/mesh@${{ steps.version-check.outputs.current-version }}" >> $GITHUB_STEP_SUMMARY
+          echo "bunx decocms@${{ steps.version-check.outputs.current-version }}" >> $GITHUB_STEP_SUMMARY
           echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
           echo "### Docker" >> $GITHUB_STEP_SUMMARY

DEBT.md

@@ -0,0 +1,98 @@
+# Technical Debt — Local-First DX
+
+Items to address after the core local-first DX lands.
+
+## NATS onboarding in local mode
+
+The agentic onboarding flow should detect whether NATS is available and, if not,
+offer to install and start it (via `brew install nats-server` or Docker). NATS
+enables stream recovery (switch tabs / refresh → restore in-progress AI
+responses). Without it, `NoOpStreamBuffer` is used and late-join replay is
+disabled.
+
+- Relevant code: `apps/mesh/src/api/app.ts` (NATS_URL detection),
+  `apps/mesh/src/api/routes/decopilot/stream-buffer.ts` (NoOpStreamBuffer fallback)
+
+## decocms package rename
+
+`packages/studio/` publishes as `decocms` on npm (`bunx decocms` / `deco` CLI).
+It's a thin wrapper that depends on `@decocms/mesh`. Eventually the source
+should move to `decocms` as the canonical package and `@decocms/mesh` becomes
+the wrapper (or is deprecated).
+
+## Playwright e2e excluded from `bun test`
+
+The Playwright e2e test (`apps/mesh/src/**/*.e2e.test.ts`) is picked up by
+`bun test` and fails because `@playwright/test` conflicts with bun's test
+runner. Should be excluded via bun test config or file naming convention.
+
+---
+
+## Items from PR review (deferred — belong to already-merged PRs)
+
+### PROJECT_PINNED_VIEWS_UPDATE missing org ownership check (PR #2567)
+
+The tool calls `requireAuth(ctx)` + `ctx.access.check()` but does not call
+`requireOrganization(ctx)` or validate `project.organizationId !== organization.id`.
+An authenticated user from org A could update pinned views on org B's project.
+
+- File: `apps/mesh/src/tools/projects/pinned-views-update.ts`
+
+### N+1 query in PROJECT_CONNECTION_LIST (PR #2567)
+
+Each connection is fetched individually via `findById` inside `Promise.all(map(...))`.
+No `findByIds` batch method exists on `ConnectionStorage`.
+
+- Fix: Add `findByIds(ids: string[])` using `WHERE id IN (...)`
+- File: `apps/mesh/src/tools/projects/connection-list.ts:52-56`
+
+### COLLECTION_CONNECTIONS_GET write side-effect in readOnly tool (PR #2567)
+
+The GET handler (annotated `readOnlyHint: true`) backfills missing tools via
+`fetchToolsFromMCP` with a 2s timeout and calls `ctx.storage.connections.update()`.
+A read operation should not have write side-effects.
+
+- Fix: Move backfill to an explicit tool or post-OAuth event trigger
+- File: `apps/mesh/src/tools/connection/get.ts`
+
+### TaskStreamManager useSyncExternalStore misuse (PR #2563)
+
+`subscribe` is a new function reference every render, causing interval leaks.
+`useSyncExternalStore` is used as a lifecycle hook rather than for external store
+subscription, which is semantically incorrect under React 19.
+
+- Fix: Stabilize `subscribe` via `useRef` or restructure
+- File: `apps/mesh/src/web/components/chat/context.tsx`
+
+### ResizeObserver memory leak in monitoring dashboard (PR #2554)
+
+Inline ref callback creates a new `ResizeObserver` on every render without
+disconnecting the old one. Use React 19 ref callback cleanup:
+`return () => observer.disconnect();`
+
+- File: monitoring dashboard component (TBD exact location)
+
+### Monitoring fetches 2000 raw rows to browser (PR #2554)
+
+Dashboard fetches 2000 full `MonitoringLog` rows (including `input`/`output` JSON)
+to the browser for client-side bucketing. Only 5 scalar fields are needed.
+
+- Fix: Push aggregation server-side or add field projection to `MONITORING_LOGS_LIST`
+- File: `apps/mesh/src/web/components/monitoring/hooks.ts:37`
+
+### ondownloadfile handler should validate URI scheme (PR #2571)
+
+`window.open(item.uri, "_blank")` accepts arbitrary URIs including `javascript:`.
+Validate scheme is `http:` or `https:` before calling `window.open`.
+
+- File: `apps/mesh/src/mcp-apps/use-app-bridge.ts`
+
+### Thread/Task naming asymmetry
+
+UI uses "task" but backend protocol uses "thread" everywhere (`COLLECTION_THREADS_LIST`,
+`thread_id`, etc.). Either rename fully or document the mapping explicitly.
+
+### Large component files should be split
+
+- `apps/mesh/src/web/components/settings-modal/pages/org-billing.tsx` (1,732 lines)
+- `apps/mesh/src/web/routes/orgs/monitoring.tsx` (1,510 lines)

README.md

@@ -61,7 +61,7 @@ bun run dev
 
 → runs at [http://localhost:3000](http://localhost:3000) (client) + API server
 
-Or use `npx @decocms/mesh` to instantly get a mesh running.
+Or use `bunx decocms` to instantly get a mesh running.
 
 ---
 

apps/docs/client/src/content/draft/en/mcp-mesh/self-hosting/quickstart.mdx

@@ -10,10 +10,10 @@ import Callout from "../../../../../components/ui/Callout.astro";
 
 Pick one:
 
-### Option A: one-command local setup (npx)
+### Option A: one-command local setup (bunx)
 
 ```bash
-npx @decocms/mesh
+bunx decocms
 ```
 
 ### Option B: local setup with Docker Compose

apps/docs/client/src/content/draft/pt-br/introduction.mdx

@@ -25,10 +25,10 @@ Se você conheceu a gente antes, como **deco.cx**, e está buscando **headless C
 
 Escolha uma opção:
 
-### Opção A: setup local com um comando (npx)
+### Opção A: setup local com um comando (bunx)
 
 ```bash
-npx @decocms/mesh
+bunx decocms
 ```
 
 ### Opção B: setup local com Docker Compose

apps/docs/client/src/content/draft/pt-br/mcp-mesh/quickstart.mdx

@@ -10,10 +10,10 @@ import Callout from "../../../../components/ui/Callout.astro";
 
 Escolha uma opção:
 
-### Opção A: setup local com um comando (npx)
+### Opção A: setup local com um comando (bunx)
 
 ```bash
-npx @decocms/mesh
+bunx decocms
 ```
 
 ### Opção B: setup local com Docker Compose

apps/docs/client/src/content/latest/en/introduction.mdx

@@ -26,10 +26,10 @@ If you know us from before (as **deco.cx**) and you’re looking for **headless
 
 Choose one:
 
-### Option A: one-command local setup (npx)
+### Option A: one-command local setup (bunx)
 
 ```bash
-npx @decocms/mesh
+bunx decocms
 ```
 
 ### Option B: local setup with Docker Compose

apps/docs/client/src/content/latest/en/mcp-mesh/quickstart.mdx

@@ -10,10 +10,10 @@ import Callout from "../../../../components/ui/Callout.astro";
 
 Pick one:
 
-### Option A: one-command local setup (npx)
+### Option A: one-command local setup (bunx)
 
 ```bash
-npx @decocms/mesh
+bunx decocms
 ```
 
 ### Option B: local setup with Docker Compose

apps/docs/client/src/content/latest/pt-br/introduction.mdx

@@ -26,10 +26,10 @@ Se você conheceu a gente antes, como **deco.cx**, e está buscando **headless C
 
 Escolha uma opção:
 
-### Opção A: setup local com um comando (npx)
+### Opção A: setup local com um comando (bunx)
 
 ```bash
-npx @decocms/mesh
+bunx decocms
 ```
 
 ### Opção B: setup local com Docker Compose

apps/docs/client/src/content/latest/pt-br/mcp-mesh/quickstart.mdx

@@ -10,10 +10,10 @@ import Callout from "../../../../components/ui/Callout.astro";
 
 Escolha uma opção:
 
-### Opção A: setup local com um comando (npx)
+### Opção A: setup local com um comando (bunx)
 
 ```bash
-npx @decocms/mesh
+bunx decocms
 ```
 
 ### Opção B: setup local com Docker Compose

apps/mesh/.gitignore

@@ -39,6 +39,9 @@ coverage/
 # Temporary files
 /tmp/
 
+# Dev/test local data directory
+.mesh-dev/
+
 
 
 # Authentication tokens

apps/mesh/index.html

@@ -1,7 +1,7 @@
 <!DOCTYPE html>
 <html>
   <head>
-    <title>MCP Mesh</title>
+    <title>Deco Studio</title>
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
   </head>
   <body>

apps/mesh/package.json

@@ -21,7 +21,8 @@
     "dist/**/*"
   ],
   "scripts": {
-    "dev": "bun run migrate && concurrently \"bun run dev:client\" \"bun run dev:server\"",
+    "dev": "bun run scripts/dev.ts",
+    "dev:saas": "bun run migrate && concurrently \"bun run dev:client\" \"bun run dev:server\"",
     "dev:client": "bun --bun vite dev",
     "dev:server": "NODE_ENV=development bun --env-file=.env --hot run src/index.ts",
     "build:client": "bun --bun vite build",