@outfitter/kit 0.2.0 → 0.2.2

package/README.md

@@ -1,130 +1,60 @@
 # @outfitter/kit
 
-Version coordination meta-package for Outfitter.
+Foundation facade for Outfitter.
 
-## Purpose
+`@outfitter/kit` provides a single foundation entrypoint over:
 
-This package ensures compatible versions across all `@outfitter/*` packages. Install it alongside specific packages to get coordinated version constraints via `peerDependencies`.
+- `@outfitter/contracts`
+- `@outfitter/types`
 
-## Installation
+Runtime and transport packages (`@outfitter/cli`, `@outfitter/mcp`, etc.) remain explicit dependencies.
+
+## Install
 
 ```bash
 bun add @outfitter/kit
 ```
 
-## When to Use
+## Root Facade
 
-Use `@outfitter/kit` when:
+The root entrypoint re-exports the contracts surface and exposes types under a namespace.
 
-1. **Building applications** that use multiple Outfitter packages
-2. **Ensuring compatibility** between package versions
-3. **Checking version requirements** programmatically
+```typescript
+import { Result, ValidationError, Types } from "@outfitter/kit";
 
-```bash
-# Install stack alongside the packages you need
-bun add @outfitter/kit @outfitter/cli @outfitter/logging @outfitter/config
+const value = Result.ok({ id: Types.shortId() });
 ```
 
-The stack's `peerDependencies` will warn if you have incompatible versions installed.
-
-## Version Matrix
-
-See [VERSIONS.md](./VERSIONS.md) for the complete compatibility matrix.
-
-### Current Release (0.1.0-rc.1)
+## Foundation Subpaths
 
-| Package | Minimum Version |
-|---------|-----------------|
-| @outfitter/contracts | 0.1.0-rc.1 |
-| @outfitter/types | 0.1.0-rc.1 |
-| @outfitter/cli | 0.1.0-rc.1 |
-| @outfitter/config | 0.1.0-rc.1 |
-| @outfitter/logging | 0.1.0-rc.1 |
-| @outfitter/file-ops | 0.1.0-rc.1 |
-| @outfitter/state | 0.1.0-rc.1 |
-| @outfitter/mcp | 0.1.0-rc.1 |
-| @outfitter/index | 0.1.0-rc.1 |
-| @outfitter/daemon | 0.1.0-rc.1 |
-| @outfitter/testing | 0.1.0-rc.1 |
+Use subpaths when you want explicit import intent.
 
-## Exports
-
-### STACK_VERSION
-
-The current stack version (matches package.json).
+### Contracts
 
 ```typescript
-import { STACK_VERSION } from "@outfitter/kit";
-
-console.log(`Using Outfitter Stack ${STACK_VERSION}`);
+import { Result, createLoggerFactory } from "@outfitter/kit/foundation/contracts";
 ```
 
-### MINIMUM_VERSIONS
-
-Minimum compatible versions for each package.
+### Types
 
 ```typescript
-import { MINIMUM_VERSIONS } from "@outfitter/kit";
-
-// Check if a package meets the minimum version
-const cliMinimum = MINIMUM_VERSIONS["@outfitter/cli"]; // "0.1.0-rc.0"
+import { shortId, isDefined } from "@outfitter/kit/foundation/types";
 ```
 
-### OutfitterPackage
-
-Type for valid package names in the stack.
+### Aggregate Foundation
 
 ```typescript
-import { type OutfitterPackage, MINIMUM_VERSIONS } from "@outfitter/kit";
-
-function getMinVersion(pkg: OutfitterPackage): string {
-  return MINIMUM_VERSIONS[pkg];
-}
-
-getMinVersion("@outfitter/cli"); // "0.1.0-rc.0"
-getMinVersion("@outfitter/invalid"); // TypeScript error
+import { Result, Types } from "@outfitter/kit/foundation";
 ```
 
-## API Reference
-
-| Export | Type | Description |
-|--------|------|-------------|
-| `STACK_VERSION` | `string` | Current stack version |
-| `MINIMUM_VERSIONS` | `Record<OutfitterPackage, string>` | Minimum versions for all packages |
-| `OutfitterPackage` | `type` | Union type of valid package names |
-
-## Dependency Tiers
-
-Packages are organized into tiers based on stability:
-
-### Foundation (cold)
-Stable APIs, rarely change:
-- `@outfitter/contracts` - Result/Error patterns
-- `@outfitter/types` - Branded types
+## What Kit Does Not Hide
 
-### Runtime (warm)
-Expected to evolve:
-- `@outfitter/cli` - CLI framework (includes terminal rendering)
-- `@outfitter/config` - Configuration
-- `@outfitter/logging` - Structured logging
-- `@outfitter/file-ops` - File operations
-- `@outfitter/state` - State management
-- `@outfitter/mcp` - MCP server framework
-- `@outfitter/index` - SQLite FTS5 indexing
-- `@outfitter/daemon` - Daemon lifecycle
+`@outfitter/kit` does not implicitly install or expose runtime transports.
+Keep transport dependencies explicit in your app:
 
-### Tooling (lukewarm)
-Workflow-focused:
-- `@outfitter/testing` - Test harnesses
-
-## Related Packages
-
-All `@outfitter/*` packages are designed to work together. See individual package documentation:
-
-- [@outfitter/contracts](../contracts/README.md) - Result types and error patterns
-- [@outfitter/cli](../cli/README.md) - CLI framework
-- [@outfitter/daemon](../daemon/README.md) - Daemon lifecycle management
-- [@outfitter/testing](../testing/README.md) - Test harnesses
+```bash
+bun add @outfitter/kit @outfitter/cli @outfitter/mcp
+```
 
 ## License
 

package/dist/foundation/contracts.d.ts

@@ -0,0 +1 @@
+export * from "@outfitter/contracts";

package/dist/foundation/contracts.js

@@ -0,0 +1,3 @@
+// @bun
+// packages/kit/src/foundation/contracts.ts
+export * from "@outfitter/contracts";

package/dist/foundation/index.d.ts

@@ -0,0 +1,3 @@
+export * from "@outfitter/contracts";
+import * as Types from "@outfitter/types";
+export { Types };

package/dist/foundation/index.js

@@ -0,0 +1,7 @@
+// @bun
+// packages/kit/src/foundation/index.ts
+export * from "@outfitter/contracts";
+import * as Types from "@outfitter/types";
+export {
+  Types
+};

package/dist/foundation/types.d.ts

@@ -0,0 +1 @@
+export * from "@outfitter/types";

package/dist/foundation/types.js

@@ -0,0 +1,3 @@
+// @bun
+// packages/kit/src/foundation/types.ts
+export * from "@outfitter/types";

package/dist/index.d.ts

@@ -1,33 +1,3 @@
-/**
-* @outfitter/kit - Version coordination meta-package
-*
-* This package coordinates versions across all @outfitter packages.
-* Install it alongside specific packages to ensure compatible versions.
-*
-* @packageDocumentation
-*/
-/**
-* Stack version - matches package.json version
-*/
-declare const STACK_VERSION = "0.1.0-rc.1";
-/**
-* Minimum compatible versions for each package
-*/
-declare const MINIMUM_VERSIONS: {
-	readonly "@outfitter/cli": "0.1.0-rc.1";
-	readonly "@outfitter/config": "0.1.0-rc.1";
-	readonly "@outfitter/contracts": "0.1.0-rc.1";
-	readonly "@outfitter/daemon": "0.1.0-rc.1";
-	readonly "@outfitter/file-ops": "0.1.0-rc.1";
-	readonly "@outfitter/index": "0.1.0-rc.1";
-	readonly "@outfitter/logging": "0.1.0-rc.1";
-	readonly "@outfitter/mcp": "0.1.0-rc.1";
-	readonly "@outfitter/state": "0.1.0-rc.1";
-	readonly "@outfitter/testing": "0.1.0-rc.1";
-	readonly "@outfitter/types": "0.1.0-rc.1";
-};
-/**
-* Type for package names in the stack
-*/
-type OutfitterPackage = keyof typeof MINIMUM_VERSIONS;
-export { STACK_VERSION, OutfitterPackage, MINIMUM_VERSIONS };
+export * from "@outfitter/contracts";
+import * as Types from "@outfitter/types";
+export { Types };

package/dist/index.js

@@ -1,19 +1,7 @@
-// src/index.ts
-var STACK_VERSION = "0.1.0-rc.1";
-var MINIMUM_VERSIONS = {
-  "@outfitter/cli": "0.1.0-rc.1",
-  "@outfitter/config": "0.1.0-rc.1",
-  "@outfitter/contracts": "0.1.0-rc.1",
-  "@outfitter/daemon": "0.1.0-rc.1",
-  "@outfitter/file-ops": "0.1.0-rc.1",
-  "@outfitter/index": "0.1.0-rc.1",
-  "@outfitter/logging": "0.1.0-rc.1",
-  "@outfitter/mcp": "0.1.0-rc.1",
-  "@outfitter/state": "0.1.0-rc.1",
-  "@outfitter/testing": "0.1.0-rc.1",
-  "@outfitter/types": "0.1.0-rc.1"
-};
+// @bun
+// packages/kit/src/index.ts
+export * from "@outfitter/contracts";
+import * as Types from "@outfitter/types";
 export {
-  STACK_VERSION,
-  MINIMUM_VERSIONS
+  Types
 };

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@outfitter/kit",
-  "description": "Version coordination meta-package for Outfitter",
-  "version": "0.2.0",
+  "description": "Foundation facade for Outfitter contracts and types",
+  "version": "0.2.2",
   "type": "module",
   "files": [
     "dist",
-    "VERSIONS.md"
+    "shared/migrations"
   ],
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -16,63 +16,36 @@
         "default": "./dist/index.js"
       }
     },
-    "./package.json": "./package.json"
-  },
-  "peerDependencies": {
-    "@outfitter/cli": ">=0.1.0",
-    "@outfitter/config": ">=0.1.0",
-    "@outfitter/contracts": ">=0.1.0",
-    "@outfitter/daemon": ">=0.1.0",
-    "@outfitter/file-ops": ">=0.1.0",
-    "@outfitter/index": ">=0.1.0",
-    "@outfitter/logging": ">=0.1.0",
-    "@outfitter/mcp": ">=0.1.0",
-    "@outfitter/state": ">=0.1.0",
-    "@outfitter/testing": ">=0.1.0",
-    "@outfitter/types": ">=0.1.0",
-    "@outfitter/ui": ">=0.1.0-rc.1"
-  },
-  "peerDependenciesMeta": {
-    "@outfitter/cli": {
-      "optional": true
-    },
-    "@outfitter/config": {
-      "optional": true
-    },
-    "@outfitter/contracts": {
-      "optional": true
-    },
-    "@outfitter/daemon": {
-      "optional": true
-    },
-    "@outfitter/file-ops": {
-      "optional": true
-    },
-    "@outfitter/index": {
-      "optional": true
-    },
-    "@outfitter/logging": {
-      "optional": true
-    },
-    "@outfitter/mcp": {
-      "optional": true
-    },
-    "@outfitter/state": {
-      "optional": true
+    "./foundation/contracts": {
+      "import": {
+        "types": "./dist/foundation/contracts.d.ts",
+        "default": "./dist/foundation/contracts.js"
+      }
     },
-    "@outfitter/testing": {
-      "optional": true
+    "./foundation/types": {
+      "import": {
+        "types": "./dist/foundation/types.d.ts",
+        "default": "./dist/foundation/types.js"
+      }
     },
-    "@outfitter/types": {
-      "optional": true
+    "./foundation": {
+      "import": {
+        "types": "./dist/foundation/index.d.ts",
+        "default": "./dist/foundation/index.js"
+      }
     },
-    "@outfitter/ui": {
-      "optional": true
-    }
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@outfitter/contracts": "0.2.0",
+    "@outfitter/types": "0.2.0"
   },
   "scripts": {
-    "build": "bunup --filter @outfitter/kit",
-    "typecheck": "tsc --noEmit"
+    "build": "bun run sync:migrations && cd ../.. && bunup --filter @outfitter/kit",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "sync:migrations": "bun run ../../scripts/sync-migrations.ts",
+    "prepack": "bun run sync:migrations"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/shared/migrations/README.md

@@ -0,0 +1,63 @@
+# Migration Docs
+
+Versioned migration guides for `@outfitter/*` packages. Used by the `outfitter-check` skill and `outfitter update` CLI command to compose upgrade guidance.
+
+## Naming Convention
+
+```
+outfitter-<package>-<version>.md
+```
+
+Examples:
+- `outfitter-contracts-0.2.0.md`
+- `outfitter-cli-0.2.0.md`
+
+## Ordering
+
+Migration docs are applied sequentially by version (semver ascending). Within a version, packages are ordered by dependency tier:
+
+1. **Foundation**: contracts, types
+2. **Runtime**: cli, mcp, config, logging, file-ops, state, index, daemon, testing
+3. **Tooling**: outfitter (umbrella CLI)
+
+## Template
+
+```markdown
+---
+package: @outfitter/<name>
+version: 0.2.0
+breaking: false
+---
+
+# @outfitter/<name> → 0.2.0
+
+## New APIs
+
+<what's available now, with code examples>
+
+## Migration Steps
+
+<specific things to change, with before/after>
+
+## No Action Required
+
+<things that just work after bumping>
+```
+
+### Frontmatter Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `package` | string | Full package name (`@outfitter/contracts`) |
+| `version` | string | Target version |
+| `breaking` | boolean | Whether this version has breaking changes |
+
+## Adding New Migration Docs
+
+When releasing a new version:
+
+1. Create `outfitter-<package>-<version>.md` for each package with changes
+2. Follow the template above
+3. Include before/after code examples for any API changes
+4. Mark `breaking: true` if there are breaking changes
+5. Omit packages that only received dependency bumps (no API changes)

package/shared/migrations/outfitter-cli-0.2.0.md

@@ -0,0 +1,150 @@
+---
+package: "@outfitter/cli"
+version: 0.2.0
+breaking: false
+---
+
+# @outfitter/cli → 0.2.0
+
+## New APIs
+
+### Portable `createCLI` from `@outfitter/cli/command`
+
+`createCLI` and `command` are now available from the `@outfitter/cli/command` subpath export. This is the recommended import path for building CLIs.
+
+```typescript
+import { createCLI, command } from "@outfitter/cli/command";
+
+const cli = createCLI({
+  name: "my-tool",
+  version: "1.0.0",
+  description: "My CLI tool",
+});
+
+cli.register(
+  command("hello <name>")
+    .description("Greet someone")
+    .action(async (name) => {
+      console.log(`Hello, ${name}!`);
+    })
+);
+
+await cli.parse(process.argv);
+```
+
+### Command Normalization
+
+Command specs now separate the command name from argument syntax. The CLI framework handles parsing `"get <id>"` into a command named `get` with argument `<id>`.
+
+```typescript
+// Arguments are separated from the command name during registration
+command("get <id>")          // name: "get", args: ["<id>"]
+command("[directory]")       // name: undefined, args: ["[directory]"]
+command("add <block>")       // name: "add", args: ["<block>"]
+```
+
+### `--json` Output Mode
+
+Commands can support structured JSON output via the `--json` flag:
+
+```typescript
+import { output } from "@outfitter/cli/output";
+
+// Human-readable (default)
+await output(["Line 1", "Line 2"]);
+
+// JSON mode (via --json flag or OUTFITTER_JSON=1)
+await output({ users: [...] }, { mode: "json" });
+
+// JSONL mode (for streaming)
+await output(record, { mode: "jsonl" });
+```
+
+Mode is auto-detected:
+1. Explicit `mode` option
+2. `OUTFITTER_JSONL=1` env var → jsonl
+3. `OUTFITTER_JSON=1` env var → json
+4. TTY → human, non-TTY → json
+
+### `pageSize` Prompt Option
+
+Select and multi-select prompts now accept a `pageSize` option to control visible items:
+
+```typescript
+import { promptSelect, promptMultiSelect } from "@outfitter/cli/prompt";
+
+const choice = await promptSelect({
+  message: "Pick a template",
+  options: [...],
+  pageSize: 8, // Show 8 items at a time
+});
+
+const choices = await promptMultiSelect({
+  message: "Select features",
+  options: [...],
+  pageSize: 6,
+});
+```
+
+### `ANSI.inverse` + Theme Support
+
+The `ANSI` constant now includes `inverse` for swapping foreground/background colors. Themes expose it as a function:
+
+```typescript
+import { ANSI } from "@outfitter/cli";
+
+// Raw escape code
+console.log(`${ANSI.inverse}Highlighted${ANSI.reset}`);
+
+// Via theme
+import { createTheme } from "@outfitter/cli";
+const theme = createTheme();
+console.log(theme.inverse("Highlighted"));
+```
+
+New theme semantic colors:
+- `theme.accent(text)` — Cyan for interactive elements
+- `theme.highlight(text)` — Bold for strong emphasis
+- `theme.link(text)` — Cyan + underline for URLs
+- `theme.destructive(text)` — Bright red for dangerous actions
+- `theme.subtle(text)` — Dim gray for less prominent text
+
+### `getSeverityIndicator()`
+
+Severity-level indicator function for compliance and diagnostic output:
+
+```typescript
+import { getSeverityIndicator } from "@outfitter/cli/render";
+
+getSeverityIndicator("minor");    // "◇"
+getSeverityIndicator("moderate"); // "◆"
+getSeverityIndicator("severe");   // "◈"
+
+// Fallback for terminals without unicode
+getSeverityIndicator("minor", false);    // "◊"
+getSeverityIndicator("moderate", false); // "♦"
+getSeverityIndicator("severe", false);   // "♦♦"
+```
+
+## Migration Steps
+
+### Import `createCLI` from the command subpath
+
+**Before:**
+```typescript
+import { createCLI } from "@outfitter/cli/cli";
+```
+
+**After:**
+```typescript
+import { createCLI, command } from "@outfitter/cli/command";
+```
+
+Both paths work, but `@outfitter/cli/command` is the canonical entry point.
+
+## No Action Required
+
+- Existing `output()` calls work unchanged — JSON mode is opt-in
+- Theme color functions are backward-compatible (new colors are additive)
+- `ANSI` constant additions don't affect existing usage
+- Prompt APIs are backward-compatible (`pageSize` is optional)

package/shared/migrations/outfitter-config-0.2.0.md

@@ -0,0 +1,59 @@
+---
+package: "@outfitter/config"
+version: 0.2.0
+breaking: false
+---
+
+# @outfitter/config → 0.2.0
+
+## New APIs
+
+### JSONC Parsing
+
+Config files with `.jsonc` or `.json5` extensions are now parsed with comment support via JSON5:
+
+```typescript
+import { loadConfig } from "@outfitter/config";
+
+// config.jsonc is now a valid config file
+const result = loadConfig("my-app", schema);
+```
+
+Supported config formats:
+- `.json` — Strict JSON (no comments)
+- `.jsonc` / `.json5` — JSON with comments and trailing commas
+- `.toml` — TOML format
+- `.yaml` / `.yml` — YAML with merge key support
+
+### MCP Resource Handlers
+
+Config loading now integrates with MCP resource handlers, allowing config values to be exposed as MCP resources.
+
+## Migration Steps
+
+### Use `.jsonc` for configs that need comments
+
+**Before** (workaround with `.json`):
+```json
+{
+  "debug": true
+}
+```
+
+**After** (`.jsonc` with comments):
+```jsonc
+{
+  // Enable debug mode for development
+  "debug": true,
+
+  // API endpoint — override in production
+  "apiUrl": "http://localhost:3000",
+}
+```
+
+## No Action Required
+
+- Existing `.json`, `.toml`, `.yaml` configs work unchanged
+- `loadConfig()` signature unchanged
+- XDG directory resolution unchanged
+- `extends` support unchanged

package/shared/migrations/outfitter-contracts-0.2.0.md

@@ -0,0 +1,200 @@
+---
+package: "@outfitter/contracts"
+version: 0.2.0
+breaking: false
+---
+
+# @outfitter/contracts → 0.2.0
+
+## New APIs
+
+### `create()` Static Factories
+
+All error classes now have a `create()` static method that auto-generates messages from structured inputs. This is the preferred way to construct errors.
+
+```typescript
+import {
+  ValidationError,
+  NotFoundError,
+  AmbiguousError,
+  ConflictError,
+  PermissionError,
+  TimeoutError,
+  RateLimitError,
+  NetworkError,
+  InternalError,
+  AuthError,
+  CancelledError,
+} from "@outfitter/contracts";
+
+// ValidationError — field + reason
+ValidationError.create("email", "format invalid");
+// → message: "email: format invalid", field: "email"
+
+// NotFoundError — resourceType + resourceId
+NotFoundError.create("user", "user-123");
+// → message: "user not found: user-123", resourceType: "user", resourceId: "user-123"
+
+// AmbiguousError — what + candidates
+AmbiguousError.create("heading", ["Introduction", "Intro to APIs"]);
+// → message: "Ambiguous heading: 2 matches found", candidates: [...]
+
+// ConflictError — message
+ConflictError.create("User already exists");
+
+// PermissionError — message
+PermissionError.create("Cannot delete admin users");
+
+// TimeoutError — operation + timeoutMs
+TimeoutError.create("database query", 5000);
+// → message: "database query timed out after 5000ms"
+
+// RateLimitError — message + optional retryAfterSeconds
+RateLimitError.create("API rate limit exceeded", 30);
+
+// NetworkError — message
+NetworkError.create("Failed to connect to API");
+
+// InternalError — message
+InternalError.create("Unexpected failure");
+
+// AuthError — message + optional reason
+AuthError.create("Invalid API key", "invalid");
+
+// CancelledError — message
+CancelledError.create("Operation cancelled by user");
+```
+
+All `create()` methods accept an optional `context` parameter:
+
+```typescript
+ValidationError.create("email", "format invalid", { received: "not-an-email" });
+NotFoundError.create("user", "user-123", { searchedIn: "active_users" });
+```
+
+### `context` Field
+
+All error classes now support an optional `context` field for attaching structured metadata without overloading the message string:
+
+```typescript
+new NotFoundError({
+  message: "Heading not found",
+  resourceType: "heading",
+  resourceId: "h:Intro",
+  context: { availableHeadings: ["Introduction", "Getting Started"] },
+});
+
+new ValidationError({
+  message: "Value out of range",
+  field: "age",
+  context: { min: 0, max: 150, received: -1 },
+});
+
+new InternalError({
+  message: "Failed to add block",
+  context: { action: "add", blockName: "scaffolding" },
+});
+```
+
+### `AmbiguousError`
+
+New error class for disambiguation scenarios. Uses `validation` category (exit 1, HTTP 400).
+
+```typescript
+import { AmbiguousError } from "@outfitter/contracts";
+
+// When a search matches multiple candidates
+const error = new AmbiguousError({
+  message: "Multiple headings match 'Intro'",
+  candidates: ["Introduction", "Intro to APIs"],
+});
+
+// Or use the factory
+const error = AmbiguousError.create("heading", ["Introduction", "Intro to APIs"]);
+
+// Access candidates for disambiguation UI
+error.candidates; // ["Introduction", "Intro to APIs"]
+error.category;   // "validation"
+error.exitCode(); // 1
+```
+
+### `AssertionError`
+
+New error class for invariant violations. Uses `internal` category (exit 8, HTTP 500).
+
+```typescript
+import { AssertionError } from "@outfitter/contracts";
+
+// Used by assertion utilities that return Result instead of throwing
+const error = new AssertionError({
+  message: "Cache should always have value after init",
+});
+```
+
+### `expect()` Result Boundary Helper
+
+Unwraps a `Result` or throws with a contextual message. Use at system boundaries where you need to exit the Result railway.
+
+```typescript
+import { expect } from "@outfitter/contracts";
+
+// Unwraps Ok, throws on Err
+const config = expect(loadConfig(), "Failed to load config");
+
+// Throws: Error("Failed to load config: <original error>")
+```
+
+## Migration Steps
+
+### Use `create()` factories instead of manual construction
+
+**Before:**
+```typescript
+new ValidationError({ message: "email: format invalid", field: "email" });
+new NotFoundError({ message: "user not found: user-123", resourceType: "user", resourceId: "user-123" });
+```
+
+**After:**
+```typescript
+ValidationError.create("email", "format invalid");
+NotFoundError.create("user", "user-123");
+```
+
+### Use `context` instead of `details`
+
+The `context` field replaces ad-hoc `details` patterns:
+
+**Before:**
+```typescript
+new InternalError("Unexpected error", { cause: error });
+```
+
+**After:**
+```typescript
+new InternalError({ message: "Unexpected error", context: { cause: error } });
+// Or with factory:
+InternalError.create("Unexpected error", { cause: error });
+```
+
+### Use `AmbiguousError` for multi-match scenarios
+
+**Before:**
+```typescript
+new ValidationError({
+  message: `Multiple matches found for '${query}'`,
+  field: "query",
+});
+```
+
+**After:**
+```typescript
+AmbiguousError.create(query, matchedCandidates);
+// Carries the candidate list for transport layers to use
+```
+
+## No Action Required
+
+- Existing error constructors still work — `create()` is additive
+- `exitCode()` and `statusCode()` methods unchanged
+- `_tag` discriminators unchanged
+- Pattern matching with `_tag` works the same way

package/shared/migrations/outfitter-daemon-0.2.0.md

@@ -0,0 +1,11 @@
+---
+package: "@outfitter/daemon"
+version: 0.2.0
+breaking: false
+---
+
+# @outfitter/daemon → 0.2.0
+
+## No Action Required
+
+Version alignment release. No API changes — bump your dependency version and continue.

package/shared/migrations/outfitter-file-ops-0.2.0.md

@@ -0,0 +1,11 @@
+---
+package: "@outfitter/file-ops"
+version: 0.2.0
+breaking: false
+---
+
+# @outfitter/file-ops → 0.2.0
+
+## No Action Required
+
+Version alignment release. No API changes — bump your dependency version and continue.

package/shared/migrations/outfitter-index-0.2.0.md

@@ -0,0 +1,11 @@
+---
+package: "@outfitter/index"
+version: 0.2.0
+breaking: false
+---
+
+# @outfitter/index → 0.2.0
+
+## No Action Required
+
+Version alignment release. No API changes — bump your dependency version and continue.

package/shared/migrations/outfitter-logging-0.2.0.md

@@ -0,0 +1,66 @@
+---
+package: "@outfitter/logging"
+version: 0.2.0
+breaking: false
+---
+
+# @outfitter/logging → 0.2.0
+
+## New APIs
+
+### Console Sink Fallback
+
+`createConsoleSink()` provides a ready-to-use sink that routes log messages to the appropriate console method based on severity:
+
+```typescript
+import { createConsoleSink } from "@outfitter/logging";
+
+const sink = createConsoleSink({ colors: true });
+
+// Routing:
+// fatal, error → console.error()
+// warn        → console.warn()
+// debug, trace → console.debug()
+// info        → console.info()
+```
+
+Color support is auto-detected from `process.stdout.isTTY` if not explicitly set.
+
+### Logger Method Overloads
+
+Logger methods now accept both string and structured log arguments:
+
+```typescript
+// String message
+logger.info("User logged in");
+
+// Structured with context
+logger.info("User logged in", { userId: "123", method: "oauth" });
+```
+
+## Migration Steps
+
+### Remove top-level `node:*` imports
+
+If you were importing Node.js built-in modules at the top level alongside `@outfitter/logging`, the package no longer relies on top-level `node:*` imports. This improves compatibility with edge runtimes.
+
+**Before:**
+```typescript
+import { createConsoleSink } from "@outfitter/logging";
+// Package internally used: import { Console } from "node:console";
+```
+
+**After:**
+```typescript
+import { createConsoleSink } from "@outfitter/logging";
+// Package uses runtime-safe console access
+```
+
+This change is transparent — your code doesn't need modification unless you were relying on side effects from the package importing `node:*` modules.
+
+## No Action Required
+
+- Existing logger setup works unchanged
+- Redaction patterns (`DEFAULT_PATTERNS`) unchanged
+- Sensitive key detection unchanged
+- LogTape integration unchanged

package/shared/migrations/outfitter-mcp-0.2.0.md

@@ -0,0 +1,180 @@
+---
+package: "@outfitter/mcp"
+version: 0.2.0
+breaking: false
+---
+
+# @outfitter/mcp → 0.2.0
+
+## New APIs
+
+### Tool Annotations
+
+Tools can now declare behavioral hints for clients via `annotations`:
+
+```typescript
+import { defineTool } from "@outfitter/mcp";
+
+const listUsers = defineTool({
+  name: "list-users",
+  description: "List all users",
+  inputSchema: z.object({ limit: z.number().optional() }),
+  annotations: {
+    readOnlyHint: true,       // Does not modify state
+    destructiveHint: false,   // Not destructive
+    idempotentHint: true,     // Same input → same result
+    openWorldHint: false,     // Operates on closed dataset
+  },
+  handler: async (input, ctx) => { /* ... */ },
+});
+```
+
+Annotation hints help clients make decisions about confirmation dialogs, caching, and retry behavior.
+
+### Resource Read Handlers
+
+Resources can now include inline read handlers instead of relying on external dispatch:
+
+```typescript
+import type { ResourceDefinition } from "@outfitter/mcp";
+
+const configResource: ResourceDefinition = {
+  uri: "config:///app",
+  name: "App Configuration",
+  description: "Current application configuration",
+  mimeType: "application/json",
+  handler: async (uri, ctx) => {
+    const config = await loadConfig();
+    return Result.ok([{ uri, text: JSON.stringify(config) }]);
+  },
+};
+```
+
+### Resource Templates
+
+URI-templated resources with variable completion:
+
+```typescript
+import type { ResourceTemplateDefinition } from "@outfitter/mcp";
+
+const userProfile: ResourceTemplateDefinition = {
+  uriTemplate: "db:///users/{userId}/profile",
+  name: "User Profile",
+  description: "Profile for a specific user",
+  handler: async (uri, variables, ctx) => {
+    const user = await getUser(variables.userId);
+    return Result.ok([{
+      uri,
+      text: JSON.stringify(user),
+      mimeType: "application/json",
+    }]);
+  },
+  complete: {
+    userId: async (partial) => {
+      const users = await searchUsers(partial);
+      return { values: users.map((u) => u.id) };
+    },
+  },
+};
+```
+
+### Prompt System
+
+Define reusable prompt templates for MCP clients:
+
+```typescript
+import type { PromptDefinition } from "@outfitter/mcp";
+
+const codeReview: PromptDefinition = {
+  name: "code-review",
+  description: "Review code changes",
+  arguments: [
+    { name: "file", description: "File to review", required: true },
+    { name: "focus", description: "Review focus area", required: false },
+  ],
+  handler: async (args, ctx) => {
+    return {
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Review ${args.file} focusing on ${args.focus ?? "general quality"}`,
+          },
+        },
+      ],
+    };
+  },
+};
+```
+
+### Content Annotations
+
+Annotate content with audience and priority hints:
+
+```typescript
+{
+  type: "text",
+  text: "Debug trace information",
+  annotations: {
+    audience: ["assistant"],  // Not shown to user
+    priority: 0.2,            // Low priority
+  },
+}
+```
+
+### Completions, Logging, Notifications, Progress
+
+- **Completions**: Resource template variables and prompt arguments support auto-completion handlers
+- **Logging**: Structured logging via `ctx.logger` with severity levels
+- **Notifications**: Server-to-client notifications for resource changes
+- **Progress**: Long-running operations can report progress via `ctx.progress(current, total)`
+
+## Migration Steps
+
+### Add annotations to existing tools
+
+**Before:**
+```typescript
+const tool = defineTool({
+  name: "delete-user",
+  description: "Delete a user",
+  inputSchema: z.object({ id: z.string() }),
+  handler: deleteUserHandler,
+});
+```
+
+**After:**
+```typescript
+const tool = defineTool({
+  name: "delete-user",
+  description: "Delete a user",
+  inputSchema: z.object({ id: z.string() }),
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+  },
+  handler: deleteUserHandler,
+});
+```
+
+### Add `.describe()` to Zod schemas for MCP tools
+
+MCP clients use schema descriptions for tool documentation:
+
+```typescript
+// Before
+z.object({ limit: z.number().optional() })
+
+// After
+z.object({
+  limit: z.number().optional().describe("Maximum number of results to return"),
+})
+```
+
+## No Action Required
+
+- Existing tool definitions work without annotations
+- `deferLoading` defaults to `true` (unchanged)
+- Handler signatures are backward-compatible
+- Resource and prompt systems are additive

package/shared/migrations/outfitter-state-0.2.0.md

@@ -0,0 +1,11 @@
+---
+package: "@outfitter/state"
+version: 0.2.0
+breaking: false
+---
+
+# @outfitter/state → 0.2.0
+
+## No Action Required
+
+Version alignment release. No API changes — bump your dependency version and continue.

package/shared/migrations/outfitter-testing-0.2.0.md

@@ -0,0 +1,78 @@
+---
+package: "@outfitter/testing"
+version: 0.2.0
+breaking: false
+---
+
+# @outfitter/testing → 0.2.0
+
+## New APIs
+
+### Type Re-exports
+
+All harness and factory types are now re-exported from the package root for convenient access:
+
+```typescript
+import {
+  // Fixtures
+  createFixture,
+  loadFixture,
+  withEnv,
+  withTempDir,
+
+  // CLI Harness
+  createCliHarness,
+  captureCLI,
+  mockStdin,
+  type CliHarness,
+  type CliResult,
+  type CliTestResult,
+
+  // MCP Harness
+  createMcpHarness,
+  createMcpTestHarness,
+  type McpHarness,
+  type McpTestHarnessOptions,
+  type McpToolResponse,
+
+  // Mock Factories
+  createTestConfig,
+  createTestContext,
+  createTestLogger,
+  type LogEntry,
+  type TestLogger,
+} from "@outfitter/testing";
+```
+
+## Migration Steps
+
+### Remove top-level `node:*` imports
+
+Like `@outfitter/logging`, the testing package no longer uses top-level `node:*` imports. This is transparent to consumers.
+
+### Import types from the root
+
+**Before** (importing from submodules):
+```typescript
+import { createCliHarness } from "@outfitter/testing/cli-harness";
+import { createMcpHarness } from "@outfitter/testing/mcp-harness";
+import type { CliHarness } from "@outfitter/testing/cli-harness";
+```
+
+**After** (import from root):
+```typescript
+import {
+  createCliHarness,
+  createMcpHarness,
+  type CliHarness,
+} from "@outfitter/testing";
+```
+
+Both paths work, but the root import is preferred.
+
+## No Action Required
+
+- Existing test harness usage works unchanged
+- Fixture utilities unchanged
+- Mock factory APIs unchanged
+- Submodule imports still work (root is additive)

package/shared/migrations/outfitter-tooling-0.2.0.md

@@ -0,0 +1,66 @@
+---
+package: "@outfitter/tooling"
+version: 0.2.0
+breaking: false
+---
+
+# @outfitter/tooling → 0.2.0
+
+## New (First npm Publish)
+
+This is the first npm-published release of `@outfitter/tooling`. It provides dev tooling presets and a CLI for Outfitter projects.
+
+### Biome Preset
+
+Shared Biome configuration with Outfitter-specific rules:
+
+```json
+{
+  "extends": ["@outfitter/tooling/biome"]
+}
+```
+
+### TypeScript Presets
+
+Strict TypeScript configurations:
+
+```json
+// tsconfig.json — strict base
+{ "extends": "@outfitter/tooling/tsconfig" }
+
+// tsconfig.json — Bun variant
+{ "extends": "@outfitter/tooling/tsconfig-bun" }
+```
+
+### Lefthook Git Hooks
+
+Pre-configured git hooks for pre-commit (format, lint, typecheck) and pre-push (build, test):
+
+```yaml
+# lefthook.yml
+extends:
+  - "@outfitter/tooling/lefthook"
+```
+
+### CLI Commands
+
+```bash
+# Initialize tooling in a project
+bunx @outfitter/tooling init
+
+# Check formatting and linting
+bunx @outfitter/tooling check
+
+# Auto-fix issues
+bunx @outfitter/tooling fix
+
+# Upgrade Bun version across the repo
+bunx @outfitter/tooling upgrade-bun [version]
+
+# TDD-aware pre-push hook
+bunx @outfitter/tooling pre-push
+```
+
+## No Action Required
+
+If you were previously using `@outfitter/tooling` from the monorepo workspace, no changes needed — just ensure your dependency points to `^0.2.0`.

package/shared/migrations/outfitter-types-0.2.0.md

@@ -0,0 +1,11 @@
+---
+package: "@outfitter/types"
+version: 0.2.0
+breaking: false
+---
+
+# @outfitter/types → 0.2.0
+
+## No Action Required
+
+Version alignment release. No API changes — bump your dependency version and continue.

package/VERSIONS.md

@@ -1,38 +0,0 @@
-# Version Compatibility Matrix
-
-This document tracks version compatibility across @outfitter packages.
-
-## Current Release
-
-| Package | Version | Status |
-|---------|---------|--------|
-| @outfitter/contracts | 0.1.0-rc.0 | RC |
-| @outfitter/types | 0.1.0-rc.0 | RC |
-| @outfitter/cli | 0.1.0-rc.0 | RC |
-| @outfitter/config | 0.1.0-rc.0 | RC |
-| @outfitter/logging | 0.1.0-rc.0 | RC |
-| @outfitter/file-ops | 0.1.0-rc.0 | RC |
-| @outfitter/state | 0.1.0-rc.0 | RC |
-| @outfitter/mcp | 0.1.0-rc.0 | RC |
-| @outfitter/index | 0.1.0-rc.0 | RC |
-| @outfitter/daemon | 0.1.0-rc.0 | RC |
-| @outfitter/testing | 0.1.0-rc.0 | RC |
-
-## Dependency Tiers
-
-### Foundation (cold)
-- `@outfitter/contracts` - Result/Error patterns
-- `@outfitter/types` - Branded types
-
-### Runtime (warm)
-- `@outfitter/cli` - CLI framework (includes terminal rendering)
-- `@outfitter/config` - Configuration
-- `@outfitter/logging` - Structured logging
-- `@outfitter/file-ops` - File operations
-- `@outfitter/state` - State management
-- `@outfitter/mcp` - MCP server framework
-- `@outfitter/index` - SQLite FTS5 indexing
-- `@outfitter/daemon` - Daemon lifecycle
-
-### Tooling (lukewarm)
-- `@outfitter/testing` - Test harnesses