[WIP] 0.10.0

.github/copilot-instructions.md

@@ -192,6 +192,7 @@ For Discovery View, both `treeId` and `clusterId` are sanitized (all `/` replace
 
 See `src/tree/models/BaseClusterModel.ts` and `docs/analysis/08-cluster-model-simplification-plan.md` for details.
 
+- [skills/tree-cluster-architecture/SKILL.md](skills/tree-cluster-architecture/SKILL.md) - Required patterns for cluster tree items, dual identity, provider lookup, and regression tests
 - [skills/telemetry-instrumentation/SKILL.md](skills/telemetry-instrumentation/SKILL.md) - Telemetry instrumentation patterns
 
 ## Terminology
@@ -226,4 +227,5 @@ For detailed patterns, see:
 
 - [instructions/typescript.instructions.md](instructions/typescript.instructions.md) - TypeScript patterns and anti-patterns
 - [instructions/wizard.instructions.md](instructions/wizard.instructions.md) - AzureWizard implementation details
+- [skills/tree-cluster-architecture/SKILL.md](skills/tree-cluster-architecture/SKILL.md) - Cluster tree items, identity, lookup, and test contracts
 - [skills/telemetry-instrumentation/SKILL.md](skills/telemetry-instrumentation/SKILL.md) - Telemetry instrumentation patterns

.github/skills/tree-cluster-architecture/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: tree-cluster-architecture
+description: Patterns for cluster nodes and tree data providers in vscode-documentdb. Use when adding or changing a cluster tree item, discovery provider, Connections/Azure/Discovery tree hierarchy, tree/list mode, cluster identity, treeId/clusterId lookup, Collection View import/export resolution, reveal behavior, credentials, shell actions, or copy connection string support.
+---
+
+# Tree Cluster Architecture
+
+Use this skill whenever a tree node represents a database cluster or a hierarchy change can move a cluster node.
+
+## Non-Negotiable Rule
+
+Every **browsable cluster node** must extend `ClusterItemBase<TModel>` from `src/tree/documentdb/ClusterItemBase.ts`.
+
+Do not implement a cluster as a plain `TreeElement` or `createGenericElement*` node. Hand-rolled cluster nodes silently lose shared behavior and force each feature to reimplement it:
+
+- database and collection expansion
+- credential/client cache integration
+- retry and open-shell recovery nodes
+- the canonical `treeItem_documentdbcluster` context tag
+- standard command/menu eligibility
+- `getCredentials()` used by Copy Connection String and Save/Add to Connections flows
+- consistent connection progress, cancellation, and error handling
+
+Generic tree elements are appropriate for structural parents, placeholders, actions, and **non-browsable state rows**. When a state becomes browsable, render a `ClusterItemBase` subclass.
+
+## Implementing a Cluster Item
+
+1. Define a model extending `BaseClusterModel`.
+2. Construct a `TreeCluster<TModel>` containing both stable identity and tree position.
+3. Extend `ClusterItemBase<TModel>` and call `super(cluster)`.
+4. Implement:
+   - `getCredentials(): Promise<EphemeralClusterCredentials | undefined>`
+   - `authenticateAndConnect(): Promise<ClustersClient | null>`
+5. Optionally override:
+   - `beforeCachedClientConnect()` for tunnels or reachability preparation
+   - presentation through `descriptionOverride`, `tooltipOverride`, `iconPath`, or a justified `getTreeItem()` override
+6. Preserve the base context value. Add feature tags with `createContextValue([this.contextValue, ...extraTags])`; never replace it with a string that omits `treeItem_documentdbcluster`.
+7. Use `this.cluster.clusterId` for `CredentialCache` and `ClustersClient`, never `this.id`.
+
+Representative subclasses:
+
+- Stored connection: `src/tree/connections-view/DocumentDBClusterItem.ts`
+- Kubernetes discovery: `src/plugins/service-kubernetes/discovery-tree/documentdb/KubernetesResourceItem.ts`
+- Atlas discovery: `src/plugins/service-atlas-mongodb/discovery-tree/AtlasClusterItem.ts`
+- Managed synthetic cluster: `QuickStartClusterItem` in `src/tree/connections-view/LocalQuickStart/LocalQuickStartItem.ts`
+
+## Dual Identity Contract
+
+A cluster has two IDs with different ownership:
+
+| ID          | Meaning                            | Stability                                      | Valid uses                                                                       |
+| ----------- | ---------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------- |
+| `clusterId` | Stable resource/cache identity     | Must survive tree moves and layout changes     | credentials, clients, sessions, serialized webview context, reverse lookup input |
+| `treeId`    | Current hierarchical tree position | May change with folders, parents, or view mode | `TreeElement.id`, child IDs, reveal/navigation                                   |
+
+Rules:
+
+- `clusterId` must not contain `/`.
+- `treeId` must represent the node's actual rendered path.
+- `viewId` must identify the branch provider that owns the rendered node.
+- Child IDs derive from `treeId`, using helpers such as `buildDatabaseTreeId()` and `buildCollectionTreeId()`.
+- Never cache by `treeId` or `this.id`.
+- Never assume a stable ID is also a tree path unless the provider explicitly guarantees `clusterId === treeId`.
+- Never change tree construction without checking reverse lookup from `clusterId`.
+
+## Design Rendering and Lookup Together
+
+When adding a cluster hierarchy or a tree/list mode, specify these four functions before coding:
+
+1. **Stable identity:** How is `clusterId` built and made collision-safe?
+2. **Rendering:** How is `treeId` built in every layout?
+3. **Ownership:** Which branch provider receives `viewId` and `clusterId` later?
+4. **Reverse lookup:** How does that provider recover the current `treeId` and then the collection node?
+
+The round trip must hold:
+
+```text
+rendered cluster
+  -> { clusterId, treeId, viewId }
+  -> open Collection View with { clusterId, viewId }
+  -> owning provider resolves current treeId
+  -> provider resolves <treeId>/<database>/<collection>
+```
+
+### Connections View
+
+Persisted connections use `clusterId = storageId`. Reconstruct the current folder path from storage with `buildFullTreePath()`; do not persist or guess an old `treeId`.
+
+Synthetic nodes are not in connection storage. Their feature must own:
+
+- an exact, side-effect-free ownership predicate
+- tree path builders used by rendering and reveal code
+- stable-ID-to-tree-ID resolution
+
+The Connections provider may dispatch to that feature before falling back to persisted storage. Classify ownership **before invoking feature code**, so a feature resolver failure cannot break ordinary stored connections. See:
+
+- `src/tree/connections-view/resolveConnectionsClusterTreeId.ts`
+- `src/tree/connections-view/LocalQuickStart/quickStartTreeIdentity.ts`
+
+Do not put feature-specific ID prefixes or synthetic paths into `buildFullTreePath()`.
+
+### Discovery View
+
+`clusterId` is provider-prefixed. The current `DiscoveryBranchDataProvider` removes that prefix and finds a cached tree node by its final suffix. Therefore every layout for that provider must end the cluster `treeId` with the same stable unprefixed suffix.
+
+- Preserve visible hierarchy in preceding path segments.
+- Use one helper to build the stable suffix for both `clusterId` and every tree layout.
+- Make the suffix collision-safe within the provider.
+- Test tree and list modes separately.
+- Do not rely on cluster display names alone when uniqueness is scoped by project, namespace, context, or source.
+
+This suffix lookup is a current compatibility contract, not an ideal general identity mechanism. Issue #869 tracks exact stable-identity lookup. Until that changes, new Discovery providers must satisfy the suffix contract.
+
+### Azure Resources View
+
+Direct lookup is valid only where the provider intentionally guarantees `clusterId === treeId`. Document that invariant and test it.
+
+## Provider Responsibilities
+
+Branch providers must implement both when their clusters can open Collection View:
+
+- `findClusterNodeByClusterId(clusterId)`
+- `findCollectionByClusterId(clusterId, databaseName, collectionName)`
+
+Prefer one shared cluster-ID-to-tree-ID resolver so cluster and collection lookup cannot drift. Once the cluster node is known, use scoped child lookup to avoid expanding unrelated branches.
+
+Do not silently fall back between providers or storage zones unless identity ownership is explicit. An owned but currently unavailable synthetic cluster should return `undefined`, not masquerade as a persisted connection.
+
+## Required Tests for New Cluster Nodes or Layouts
+
+Add focused tests before considering the feature complete.
+
+### 1. Base cluster behavior
+
+- The browsable item is a `ClusterItemBase` subclass.
+- Its context value retains `treeItem_documentdbcluster` plus feature tags.
+- `getCredentials()` is implemented for commands that need connection material.
+- Expansion returns database nodes and base failure paths return retry/open-shell nodes as applicable.
+
+Use `src/tree/documentdb/ClusterItemBase.test.ts` as the base-behavior reference.
+
+### 2. Identity invariants
+
+- `clusterId` is stable and slash-free.
+- Moving folders or switching layout changes only `treeId`, not `clusterId`.
+- IDs remain unique where display names can repeat.
+- Cache operations use `clusterId`, not `treeId`.
+
+Use `src/tree/connections-view/models/ConnectionClusterModel.test.ts` as a reference.
+
+### 3. Render-to-lookup round trip (mandatory)
+
+Construct the cluster through the **real parent/root item**, not only as a model fixture, then assert:
+
+```typescript
+expect(rendered.cluster.clusterId).toBe(expectedStableId);
+expect(rendered.cluster.treeId).toBe(expectedTreePath);
+expect(await provider.findClusterNodeByClusterId(rendered.cluster.clusterId)).toBe(rendered);
+expect(await provider.findCollectionByClusterId(rendered.cluster.clusterId, databaseName, collectionName)).toBe(
+  expectedCollection,
+);
+```
+
+This test must exist for every materially different layout: root/folder, tree/list, or other synthetic hierarchy. It would have caught both the Atlas suffix mismatch and the Quick Start storage-path mismatch.
+
+### 4. Ownership isolation for synthetic nodes
+
+- Exact owned ID uses the feature resolver.
+- Ordinary IDs never invoke the feature resolver.
+- Owned-but-unavailable IDs do not fall through to persisted lookup.
+- A feature resolver failure cannot affect ordinary persisted lookup.
+
+Use `src/tree/connections-view/resolveConnectionsClusterTreeId.test.ts` as a reference.
+
+### 5. Command compatibility
+
+At minimum, verify the context contract and `getCredentials()` path needed by:
+
+- Copy Connection String
+- Open Shell
+- Save/Add to Connections when enabled
+
+If a command is intentionally unavailable, gate it explicitly with context values and document why; do not omit base behavior accidentally.
+
+## Review Checklist
+
+Before approving a cluster tree change, answer yes to all:
+
+- [ ] Browsable cluster extends `ClusterItemBase`.
+- [ ] Base cluster context tag is preserved.
+- [ ] `clusterId`, `treeId`, and `viewId` have documented owners.
+- [ ] Credentials and clients use `clusterId` only.
+- [ ] Every rendered layout has a reverse lookup strategy.
+- [ ] Cluster and collection lookup share one resolver.
+- [ ] Synthetic ownership is exact and isolated from stored lookup.
+- [ ] IDs are collision-safe beyond display names.
+- [ ] A real render-to-lookup round-trip test covers every layout.
+- [ ] Standard cluster commands work or are explicitly gated off.

.github/workflows/main.yml

@@ -2,7 +2,7 @@ name: CI
 
 # This workflow handles the following scenarios:
 #
-# 1. Push to `main` or `release/**`:
+# 1. Push to `main`:
 #    - Runs all jobs: code checks, tests, packaging, and caches build sizes
 #      for PR comparisons
 #
@@ -25,7 +25,6 @@ on:
     push:
         branches:
             - main
-            - release/**
 
     pull_request:
         branches:
@@ -34,11 +33,7 @@ on:
             - feature/**
 
 concurrency:
-    # Use head_ref for PRs, ref_name for pushes. When a forward-merge PR
-    # (release/X.Y → main) is open, both the push to release/X.Y and the
-    # PR trigger resolve to the same group (release/X.Y) so they cancel
-    # each other instead of running CI twice.
-    group: ${{ github.head_ref || github.ref_name }}
+    group: '${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}'
     cancel-in-progress: true
 
 jobs:

README.md

@@ -74,7 +74,7 @@ Connect to any database that speaks the MongoDB API wire protocol.
 - **Azure Service Discovery**: Browse and connect to Azure DocumentDB, Azure Cosmos DB for MongoDB (RU), and DocumentDB on Azure VMs directly from the sidebar
 - **MongoDB Atlas**: Connect using your Atlas connection string
 - **Entra ID authentication**: Multi-account, multi-tenant support for Azure-hosted databases
-- **Local instances and emulators**: Connect to DocumentDB Local, Azure Cosmos DB Emulator, or any local MongoDB API instance
+- **Local instances and emulators**: [Create and manage DocumentDB Local with Docker Quick Start](docs/user-manual/local-quick-start.md), or connect to Azure Cosmos DB Emulator and other local MongoDB API instances
 - **Folder organization**: Group your connections into folders and subfolders
 
 ## Browse and Manage Data

docs/ai-and-plans/PRs/653-local-quickstart-design/description.md

@@ -0,0 +1,79 @@
+# PR #653: Local DocumentDB Quick Start — Design Decisions
+
+**Status:** Open
+**Branch:** `guanzhou/local-quickstart-design`
+**Base:** `main`
+**Date:** 2026-06-15
+
+## Why this note
+
+This PR adds a design doc only (no shipping code). Before implementation we
+benchmarked the design against a proven, shipping reference — the
+**PostgreSQL extension's "Local Docker Server"** flow (`ms-ossdata.vscode-pgsql`,
+read at the source level). This note records the **non-obvious decisions**:
+where we deliberately diverge from that reference and why, where we match it,
+and the deviations that override shared/base behavior inside our own codebase.
+It exists so human reviewers and review agents don't have to re-derive the
+rationale — or mistake a deliberate deviation for an oversight.
+
+Full design: [`../../local-quickstart/local-quickstart-v2.md`](../../local-quickstart/local-quickstart-v2.md)
+(iteration 2, supersedes iteration 1). Review-resolution map is in v2 §18.
+
+## Reference: PostgreSQL "Local Docker Server"
+
+A 3-page webview (Home → Prereqs → Create form) that checks Docker (CLI +
+daemon) via VS Code tasks, runs a **required-field** form, creates a container
+through `@microsoft/vscode-container-client`, passes credentials via a temp
+`--env-file`, waits for `pg_isready` **inside** the container, then saves +
+reveals the connection and auto-closes the webview. It is **create-and-connect
+only** — no persistent volume, no lifecycle (stop/start/delete), no
+labels/adopt. The "Easy Management" welcome copy is marketing; no such
+commands exist in its source.
+
+## Deliberate deviations from the reference (non-obvious — keep)
+
+| We do                                                 | PG does                        | Why we deviate                                                                                     |
+| ----------------------------------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------- |
+| **Zero required fields** (generate creds/names)       | 3 required fields              | First-run friction is the thing to remove; PG even shipped a "password required before start" bug. |
+| **Persistent named volume**                           | No volume (data lost on `rm`)  | A local dev DB that silently loses data on container removal is a footgun.                         |
+| **Wire-protocol readiness, 60 s**                     | `pg_isready` in-container, 5 s | DocumentDB has no in-image readiness CLI we can rely on; PG's 5 s is fragile on a cold `initdb`.   |
+| **Full lifecycle (7 states; stop/start/delete/logs)** | None (create-only)             | The managed-instance tree is our core value; PG only _markets_ lifecycle.                          |
+| **tRPC + FluentUI**                                   | mssql-fork custom RPC          | Matches this repo's webview stack (CollectionView/DocumentView); we are not a fork.                |
+| **Stricter telemetry** (resolved semver only)         | sends registry/image/tag       | Avoid leaking image/registry identifiers.                                                          |
+| **Docker labels + adopt**                             | name-only refuse               | Lets us recognize and re-attach containers we created.                                             |
+
+## Changes folded back into v2 from the PG study
+
+- **v1.0 create-progress = terminal task + button spinner + auto-close** (the
+  in-webview multi-step progress card is descoped to v1.1). PG proves the
+  terminal-task model ships without streaming `docker pull` % into a webview.
+- **Adopt `@microsoft/vscode-container-client`** (the runtime layer PG uses;
+  ships both `DockerClient` and `PodmanClient`) instead of a hand-rolled
+  abstraction → makes "OCI/podman later" a driver swap, not a rewrite.
+- **Port rule:** only auto-fallback the _default_ port; never silently relocate
+  a port the user typed in Advanced (match PG's intent-respecting behavior).
+- **Read the real bound host port from `docker inspect`** before composing the
+  saved connection string (don't trust the requested port; matters with fallback).
+- **Distinguish failed-to-create vs failed-to-start** in error copy (cheap, via inspect).
+- **Pre-create duplicate check on both connection name and container name.**
+
+## Deviations that override shared/base behavior (flag for reviewers)
+
+These are the easy-to-miss ones — we extend or override shared infrastructure
+rather than add isolated code:
+
+1. **TLS exception folded into the shared new-connection wizard** (gated to
+   localhost / private hosts) instead of a separate emulator wizard. This
+   overrides the shared wizard with a conditional step, and the old
+   `New Local Connection...` entry point is removed.
+2. **Canonical port `10260` overrides the shared wizard's hardcoded `10255`**
+   (`PromptConnectionTypeStep.ts`, `PromptPortStep.ts`). This is a pre-ship fix
+   that changes existing manual-connection defaults — not Quick-Start-local.
+3. **Legacy migration mutates the shared `ConnectionType.Emulators` storage
+   zone** (moves entries into a `Local Connections (Legacy)` folder; the old
+   zone is kept read-only for one release before removal as a rollback path).
+
+## Status
+
+Design only; no implementation in this PR. Open questions are tracked in
+v2 §17; the full reviewer-comment → resolution map is in v2 §18.