zinkee 0.1.44 → 0.1.46

package/docs/superpowers/plans/2026-03-24-zinkee-cli-implementation.md

@@ -1,837 +0,0 @@
-# Zinkee CLI Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Build a complete Zinkee API v2 CLI from scratch, with backward-compatible profile config, agent-friendly JSON output, and full domain coverage matching the approved design spec.
-
-**Architecture:** The CLI will follow the `store-manager` reference structure: a thin `commander` entrypoint, domain command modules in `src/commands`, REST transport modules in `src/api`, a shared runtime layer for config/output/errors/parsing, and a central command registry that powers read-only enforcement and example support. Domain implementation should proceed from core runtime outward so later domain workers can plug into stable shared contracts.
-
-**Tech Stack:** Node.js 20+, TypeScript, ESM, commander, chalk, cli-table3, tsup, tsx, vitest, native fetch, TOML parser/stringifier dependency.
-
----
-
-### Task 1: Bootstrap Project Tooling
-
-**Files:**
-- Create: `package.json`
-- Create: `tsconfig.json`
-- Create: `tsup.config.ts`
-- Create: `src/index.ts`
-- Create: `src/types.ts`
-- Test: `src/index.test.ts`
-
-- [ ] **Step 1: Add the base project files and first smoke test**
-
-```ts
-// src/index.test.ts
-import { describe, expect, it } from "vitest";
-
-describe("project bootstrap", () => {
-  it("loads the CLI entry module", async () => {
-    const mod = await import("./index.js");
-    expect(mod).toBeTruthy();
-  });
-});
-```
-
-- [ ] **Step 2: Run the targeted bootstrap test and capture the current failure**
-
-Run: `npm test -- src/index.test.ts`
-Expected: failure because the package, scripts, and entrypoint do not exist yet
-
-- [ ] **Step 3: Create the package, build config, and entrypoint scaffold**
-
-```ts
-// src/index.ts
-#!/usr/bin/env node
-
-import chalk from "chalk";
-import { Command } from "commander";
-
-export function buildProgram(): Command {
-  return new Command()
-    .name("zinkee")
-    .description("CLI for Zinkee API v2")
-    .showHelpAfterError();
-}
-
-if (import.meta.url === `file://${process.argv[1]}`) {
-  try {
-    await buildProgram().parseAsync(process.argv);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : "Unknown error";
-    process.stderr.write(`${chalk.red("Error:")} ${message}\n`);
-    process.exitCode = 1;
-  }
-}
-```
-
-- [ ] **Step 4: Run bootstrap verification**
-
-Run:
-- `npm run build`
-- `npm run typecheck`
-- `npm test -- src/index.test.ts`
-
-Expected:
-- build succeeds
-- typecheck succeeds
-- bootstrap test passes
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add package.json tsconfig.json tsup.config.ts src/index.ts src/types.ts src/index.test.ts
-git commit -m "chore: bootstrap zinkee cli project"
-```
-
-### Task 2: Build Config Compatibility and Runtime Context
-
-**Files:**
-- Create: `src/config.ts`
-- Create: `src/config.test.ts`
-- Create: `src/runtime-context.ts`
-- Modify: `src/types.ts`
-- Modify: `src/index.ts`
-
-- [ ] **Step 1: Add tests for TOML compatibility and runtime context resolution**
-
-```ts
-// src/config.test.ts
-import { describe, expect, it } from "vitest";
-
-import { parseConfig, resolveProfile } from "./config.js";
-
-describe("parseConfig", () => {
-  it("reads the legacy config shape without migration", () => {
-    const config = parseConfig(`
-default_profile = "prod"
-
-[profiles.prod]
-api_key = "token"
-base_url = "https://api.zinkee.com"
-`);
-
-    expect(config.defaultProfile).toBe("prod");
-    expect(config.profiles.prod?.apiKey).toBe("token");
-  });
-});
-
-describe("resolveProfile", () => {
-  it("prefers explicit profile over default_profile", () => {
-    const config = {
-      defaultProfile: "prod",
-      profiles: {
-        prod: { apiKey: "a" },
-        local: { apiKey: "b", baseUrl: "http://localhost:8088" },
-      },
-    };
-
-    expect(resolveProfile(config, { profile: "local" }).name).toBe("local");
-  });
-});
-```
-
-- [ ] **Step 2: Run the config test and capture the failure**
-
-Run: `npm test -- src/config.test.ts`
-Expected: failure because config parsing/resolution does not exist yet
-
-- [ ] **Step 3: Implement TOML-backed config reading and runtime context resolution**
-
-```ts
-// src/types.ts
-export interface ProfileConfig {
-  apiKey: string;
-  baseUrl?: string;
-  name?: string;
-  description?: string;
-}
-
-export interface AppConfig {
-  defaultProfile?: string;
-  profiles: Record<string, ProfileConfig>;
-}
-
-export interface RuntimeOverrides {
-  profile?: string;
-  baseUrl?: string;
-  apiKey?: string;
-  readOnly?: boolean;
-  json?: boolean;
-}
-```
-
-- [ ] **Step 4: Verify config compatibility and root wiring**
-
-Run:
-- `npm test -- src/config.test.ts`
-- `npm run typecheck`
-
-Expected:
-- legacy TOML parsing passes
-- runtime context resolution is typed and working
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/config.ts src/config.test.ts src/runtime-context.ts src/types.ts src/index.ts
-git commit -m "feat: add config compatibility and runtime context"
-```
-
-### Task 3: Add Shared Output, Error, and Command Registry Infrastructure
-
-**Files:**
-- Create: `src/utils/output.ts`
-- Create: `src/utils/errors.ts`
-- Create: `src/utils/examples.ts`
-- Create: `src/command-registry.ts`
-- Create: `src/utils/output.test.ts`
-- Modify: `src/index.ts`
-- Modify: `src/types.ts`
-
-- [ ] **Step 1: Add tests for JSON envelope, error mapping, and registry lookup**
-
-```ts
-// src/utils/output.test.ts
-import { describe, expect, it } from "vitest";
-
-import { buildJsonSuccess, buildJsonError } from "./output.js";
-
-describe("buildJsonSuccess", () => {
-  it("wraps data in the standard success envelope", () => {
-    expect(buildJsonSuccess([{ id: "1" }], { command: "schemas list" })).toEqual({
-      data: [{ id: "1" }],
-      meta: { command: "schemas list" },
-    });
-  });
-});
-
-describe("buildJsonError", () => {
-  it("wraps error details in the standard error envelope", () => {
-    expect(buildJsonError({ reason: "invalid_request", message: "Bad request" }, {})).toMatchObject({
-      error: { reason: "invalid_request" },
-      meta: {},
-    });
-  });
-});
-```
-
-- [ ] **Step 2: Run the targeted shared-runtime test**
-
-Run: `npm test -- src/utils/output.test.ts`
-Expected: failure because the shared output/error helpers do not exist yet
-
-- [ ] **Step 3: Implement envelope rendering, exit code mapping, and command metadata**
-
-```ts
-// src/command-registry.ts
-export type CommandAccessLevel = "read" | "write" | "destructive";
-
-export interface CommandMeta {
-  command: string;
-  accessLevel: CommandAccessLevel;
-  supportsExample?: boolean;
-  supportsRaw?: boolean;
-  output: "table-json" | "json-only" | "binary";
-}
-```
-
-- [ ] **Step 4: Verify the shared runtime layer**
-
-Run:
-- `npm test -- src/utils/output.test.ts`
-- `npm run typecheck`
-
-Expected:
-- JSON envelope helpers pass
-- error mapping is typed
-- command registry compiles and can be consumed by the root program
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/utils/output.ts src/utils/errors.ts src/utils/examples.ts src/utils/output.test.ts src/command-registry.ts src/index.ts src/types.ts
-git commit -m "feat: add output error and command registry runtime"
-```
-
-### Task 4: Add REST Client and Shared Parsers
-
-**Files:**
-- Create: `src/client.ts`
-- Create: `src/client.test.ts`
-- Create: `src/parsers/expressions.ts`
-- Create: `src/parsers/expressions.test.ts`
-- Create: `src/parsers/kv.ts`
-- Create: `src/parsers/kv.test.ts`
-- Create: `src/parsers/selectors.ts`
-- Create: `src/parsers/selectors.test.ts`
-
-- [ ] **Step 1: Add transport and parser tests**
-
-```ts
-// src/parsers/kv.test.ts
-import { describe, expect, it } from "vitest";
-
-import { parseKeyValue, parseJsonAssignment } from "./kv.js";
-
-describe("parseKeyValue", () => {
-  it("splits field=value pairs", () => {
-    expect(parseKeyValue("status=active")).toEqual({ key: "status", value: "active" });
-  });
-});
-
-describe("parseJsonAssignment", () => {
-  it("parses field=json pairs", () => {
-    expect(parseJsonAssignment('payload={"a":1}')).toEqual({ key: "payload", value: { a: 1 } });
-  });
-});
-```
-
-- [ ] **Step 2: Run parser and client checks to capture the failure**
-
-Run:
-- `npm test -- src/parsers/kv.test.ts`
-- `npm test -- src/parsers/expressions.test.ts`
-- `npm test -- src/client.test.ts`
-
-Expected: failures because parsers and transport do not exist yet
-
-- [ ] **Step 3: Implement the shared client and parser layer**
-
-```ts
-// src/client.ts
-export interface ApiClientOptions {
-  baseUrl: string;
-  apiKey: string;
-  timeoutMs?: number;
-}
-
-export class ApiClient {
-  constructor(private readonly options: ApiClientOptions) {}
-
-  async getJson<T>(path: string): Promise<T> {
-    return this.requestJson<T>(path, { method: "GET" });
-  }
-
-  async requestJson<T>(path: string, init: RequestInit): Promise<T> {
-    // fetch + auth header + timeout + JSON/error normalization
-    throw new Error("not implemented");
-  }
-}
-```
-
-- [ ] **Step 4: Verify the transport and parser contracts**
-
-Run:
-- `npm test -- src/parsers/kv.test.ts`
-- `npm test -- src/parsers/expressions.test.ts`
-- `npm test -- src/parsers/selectors.test.ts`
-- `npm test -- src/client.test.ts`
-- `npm run typecheck`
-
-Expected:
-- assignment parsing works
-- expression parsing works
-- selector normalization works
-- client error handling and timeout behavior are covered
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/client.ts src/client.test.ts src/parsers/expressions.ts src/parsers/expressions.test.ts src/parsers/kv.ts src/parsers/kv.test.ts src/parsers/selectors.ts src/parsers/selectors.test.ts
-git commit -m "feat: add shared rest client and parsers"
-```
-
-### Task 5: Implement `profiles` and `config` Commands
-
-**Files:**
-- Create: `src/commands/profiles.ts`
-- Create: `src/commands/config.ts`
-- Create: `src/commands/profiles.test.ts`
-- Create: `src/commands/config.test.ts`
-- Modify: `src/index.ts`
-- Modify: `src/command-registry.ts`
-
-- [ ] **Step 1: Add command tests for profile and config management**
-
-```ts
-// src/commands/profiles.test.ts
-import { describe, expect, it } from "vitest";
-
-import { buildProgram } from "../index.js";
-
-describe("profiles commands", () => {
-  it("registers the profiles command group", () => {
-    const program = buildProgram();
-    expect(program.commands.some((command) => command.name() === "profiles")).toBe(true);
-  });
-});
-```
-
-- [ ] **Step 2: Run the profiles/config command tests**
-
-Run:
-- `npm test -- src/commands/profiles.test.ts`
-- `npm test -- src/commands/config.test.ts`
-
-Expected: failure because the command groups are not registered yet
-
-- [ ] **Step 3: Implement profile mutation commands and config inspection commands**
-
-```ts
-// src/commands/config.ts
-export function registerConfigCommands(program: Command): void {
-  program.command("config").description("Inspect CLI configuration");
-}
-```
-
-- [ ] **Step 4: Verify command registration and local behavior**
-
-Run:
-- `npm test -- src/commands/profiles.test.ts`
-- `npm test -- src/commands/config.test.ts`
-- `npm run typecheck`
-
-Expected:
-- both groups are registered
-- read/write commands are tagged in the command registry
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/commands/profiles.ts src/commands/config.ts src/commands/profiles.test.ts src/commands/config.test.ts src/index.ts src/command-registry.ts
-git commit -m "feat: add profiles and config commands"
-```
-
-### Task 6: Implement `schemas` Commands and Schema API Module
-
-**Files:**
-- Create: `src/api/schemas.ts`
-- Create: `src/commands/schemas.ts`
-- Create: `src/commands/schemas.test.ts`
-- Modify: `src/index.ts`
-- Modify: `src/command-registry.ts`
-
-- [ ] **Step 1: Add schema command tests**
-
-```ts
-// src/commands/schemas.test.ts
-import { describe, expect, it } from "vitest";
-
-import { normalizeUuidOrSlug } from "../parsers/selectors.js";
-
-describe("schema selector parsing", () => {
-  it("keeps UUIDs as UUID selectors", () => {
-    expect(normalizeUuidOrSlug("550e8400-e29b-41d4-a716-446655440000").kind).toBe("uuid");
-  });
-});
-```
-
-- [ ] **Step 2: Run the schemas test and capture the current failure**
-
-Run: `npm test -- src/commands/schemas.test.ts`
-Expected: failure because schema API and command group do not exist yet
-
-- [ ] **Step 3: Implement schema CRUD and field CRUD commands**
-
-```ts
-// src/api/schemas.ts
-export async function listSchemas(client: ApiClient) {
-  return client.getJson("/api/v2/schemas");
-}
-```
-
-- [ ] **Step 4: Verify schema behavior**
-
-Run:
-- `npm test -- src/commands/schemas.test.ts`
-- `npm run typecheck`
-
-Expected:
-- schema selectors resolve by UUID or slug
-- commands register and map to `/api/v2/schemas` and `/fields`
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/api/schemas.ts src/commands/schemas.ts src/commands/schemas.test.ts src/index.ts src/command-registry.ts
-git commit -m "feat: add schemas command surface"
-```
-
-### Task 7: Implement `records` and `comments`
-
-**Files:**
-- Create: `src/api/records.ts`
-- Create: `src/api/comments.ts`
-- Create: `src/commands/records.ts`
-- Create: `src/commands/comments.ts`
-- Create: `src/commands/records.test.ts`
-- Create: `src/commands/comments.test.ts`
-- Modify: `src/index.ts`
-- Modify: `src/command-registry.ts`
-
-- [ ] **Step 1: Add tests for query parsing and record mutation flags**
-
-```ts
-// src/commands/records.test.ts
-import { describe, expect, it } from "vitest";
-
-import { parseKeyValue } from "../parsers/kv.js";
-
-describe("record write flags", () => {
-  it("parses --set assignments", () => {
-    expect(parseKeyValue("status=active")).toEqual({ key: "status", value: "active" });
-  });
-});
-```
-
-- [ ] **Step 2: Run records/comments targeted tests**
-
-Run:
-- `npm test -- src/commands/records.test.ts`
-- `npm test -- src/commands/comments.test.ts`
-
-Expected: failure because records/comments command groups do not exist yet
-
-- [ ] **Step 3: Implement list/query/get/create/update/delete records and list/create comments**
-
-```ts
-// src/api/records.ts
-export async function queryRecords(client: ApiClient, schemaId: string, body: unknown) {
-  return client.requestJson(`/api/v2/schemas/${schemaId}/records:query`, {
-    method: "POST",
-    body: JSON.stringify(body),
-  });
-}
-```
-
-- [ ] **Step 4: Verify record and comment behavior**
-
-Run:
-- `npm test -- src/commands/records.test.ts`
-- `npm test -- src/commands/comments.test.ts`
-- `npm run typecheck`
-
-Expected:
-- `--set`, `--set-json`, and `--unset` map correctly
-- `records list` and `records query` share the same query model
-- comments stay text-first with raw fallback
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/api/records.ts src/api/comments.ts src/commands/records.ts src/commands/comments.ts src/commands/records.test.ts src/commands/comments.test.ts src/index.ts src/command-registry.ts
-git commit -m "feat: add records and comments commands"
-```
-
-### Task 8: Implement `files`, `navigation`, and `teamspace`
-
-**Files:**
-- Create: `src/api/files.ts`
-- Create: `src/api/navigation.ts`
-- Create: `src/api/teamspace.ts`
-- Create: `src/commands/files.ts`
-- Create: `src/commands/navigation.ts`
-- Create: `src/commands/teamspace.ts`
-- Create: `src/commands/files.test.ts`
-- Create: `src/commands/navigation.test.ts`
-- Create: `src/commands/teamspace.test.ts`
-- Modify: `src/index.ts`
-- Modify: `src/command-registry.ts`
-
-- [ ] **Step 1: Add command tests for binary/download rules and folder resolution**
-
-```ts
-// src/commands/files.test.ts
-import { describe, expect, it } from "vitest";
-
-import { buildJsonError } from "../utils/output.js";
-
-describe("files download json mode", () => {
-  it("requires --output when --json is used", () => {
-    const result = buildJsonError({ reason: "output_required", message: "Use --output with --json." }, {});
-    expect(result.error.reason).toBe("output_required");
-  });
-});
-```
-
-- [ ] **Step 2: Run the targeted tests**
-
-Run:
-- `npm test -- src/commands/files.test.ts`
-- `npm test -- src/commands/navigation.test.ts`
-- `npm test -- src/commands/teamspace.test.ts`
-
-Expected: failure because these domains are not implemented yet
-
-- [ ] **Step 3: Implement file, folder, move, publish, and unpublish commands**
-
-```ts
-// src/api/files.ts
-export async function downloadFile(client: ApiClient, fileId: string) {
-  return client.requestBinary(`/api/v2/files/${fileId}`, { method: "GET" });
-}
-```
-
-- [ ] **Step 4: Verify organization-domain behavior**
-
-Run:
-- `npm test -- src/commands/files.test.ts`
-- `npm test -- src/commands/navigation.test.ts`
-- `npm test -- src/commands/teamspace.test.ts`
-- `npm run typecheck`
-
-Expected:
-- files support upload/download/delete/storage
-- folder selectors resolve by UUID or exact name with ambiguity failures
-- teamspace/resource verbs map cleanly to publish/unpublish
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/api/files.ts src/api/navigation.ts src/api/teamspace.ts src/commands/files.ts src/commands/navigation.ts src/commands/teamspace.ts src/commands/files.test.ts src/commands/navigation.test.ts src/commands/teamspace.test.ts src/index.ts src/command-registry.ts
-git commit -m "feat: add files navigation and teamspace commands"
-```
-
-### Task 9: Implement `displays`
-
-**Files:**
-- Create: `src/api/displays.ts`
-- Create: `src/commands/displays.ts`
-- Create: `src/commands/displays.test.ts`
-- Modify: `src/index.ts`
-- Modify: `src/command-registry.ts`
-
-- [ ] **Step 1: Add tests for widget flag normalization and nested subresource registration**
-
-```ts
-// src/commands/displays.test.ts
-import { describe, expect, it } from "vitest";
-
-import { buildProgram } from "../index.js";
-
-describe("displays command group", () => {
-  it("registers widget and variable subresources", () => {
-    const program = buildProgram();
-    const displays = program.commands.find((command) => command.name() === "displays");
-    expect(displays).toBeTruthy();
-  });
-});
-```
-
-- [ ] **Step 2: Run the displays test**
-
-Run: `npm test -- src/commands/displays.test.ts`
-Expected: failure because the displays domain does not exist yet
-
-- [ ] **Step 3: Implement display, layout, tabs, variables, widgets, navigation-targets, and cross-widget-filter**
-
-```ts
-// src/api/displays.ts
-export async function listDisplays(client: ApiClient) {
-  return client.getJson("/api/v2/displays");
-}
-```
-
-- [ ] **Step 4: Verify displays behavior**
-
-Run:
-- `npm test -- src/commands/displays.test.ts`
-- `npm run typecheck`
-
-Expected:
-- widget commands use `--type`
-- `--widget-read-only` does not collide with root `--read-only`
-- complex sections support `--raw` and JSON file helpers
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/api/displays.ts src/commands/displays.ts src/commands/displays.test.ts src/index.ts src/command-registry.ts
-git commit -m "feat: add displays command surface"
-```
-
-### Task 10: Implement `automations`
-
-**Files:**
-- Create: `src/api/automations.ts`
-- Create: `src/commands/automations.ts`
-- Create: `src/commands/automations.test.ts`
-- Modify: `src/index.ts`
-- Modify: `src/command-registry.ts`
-
-- [ ] **Step 1: Add tests for trigger/action polymorphism and flow flag parsing**
-
-```ts
-// src/commands/automations.test.ts
-import { describe, expect, it } from "vitest";
-
-import { parseKeyValue } from "../parsers/kv.js";
-
-describe("automation action args", () => {
-  it("parses key=value mappings for action config", () => {
-    expect(parseKeyValue("status=active")).toEqual({ key: "status", value: "active" });
-  });
-});
-```
-
-- [ ] **Step 2: Run the automations test**
-
-Run: `npm test -- src/commands/automations.test.ts`
-Expected: failure because the automations domain does not exist yet
-
-- [ ] **Step 3: Implement folders, automations, trigger, actions, flow, webhook, plugins, and connections**
-
-```ts
-// src/api/automations.ts
-export async function listAutomations(client: ApiClient, query: URLSearchParams) {
-  return client.getJson(`/api/v2/automations?${query.toString()}`);
-}
-```
-
-- [ ] **Step 4: Verify the automations domain**
-
-Run:
-- `npm test -- src/commands/automations.test.ts`
-- `npm run typecheck`
-
-Expected:
-- triggers and actions are modeled generically with `--type`
-- flow parsing supports repeated `--entry` and `--transition`
-- connections separate `config` and `secret` semantics
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/api/automations.ts src/commands/automations.ts src/commands/automations.test.ts src/index.ts src/command-registry.ts
-git commit -m "feat: add automations command surface"
-```
-
-### Task 11: Add Examples, Help Text, and Agent-Facing Docs
-
-**Files:**
-- Modify: `src/commands/config.ts`
-- Modify: `src/commands/profiles.ts`
-- Modify: `src/commands/schemas.ts`
-- Modify: `src/commands/records.ts`
-- Modify: `src/commands/comments.ts`
-- Modify: `src/commands/files.ts`
-- Modify: `src/commands/navigation.ts`
-- Modify: `src/commands/teamspace.ts`
-- Modify: `src/commands/displays.ts`
-- Modify: `src/commands/automations.ts`
-- Create: `README.md`
-- Create: `AGENTS.md`
-- Create: `docs/cli-contract.md`
-
-- [ ] **Step 1: Add or adjust example rendering coverage**
-
-```ts
-// docs/cli-contract.md
-// Capture the true command contract order:
-// 1. live --help
-// 2. command modules
-// 3. docs
-```
-
-- [ ] **Step 2: Run a help/example validation pass**
-
-Run:
-- `npm run build`
-- `node dist/index.js --help`
-- `node dist/index.js records query --help`
-- `node dist/index.js records query --example --json`
-
-Expected:
-- help is present
-- examples are realistic
-- JSON examples use the standard envelope
-
-- [ ] **Step 3: Implement example registration and docs**
-
-```ts
-// src/utils/examples.ts
-export interface CommandExample {
-  description: string;
-  command: string;
-}
-```
-
-- [ ] **Step 4: Verify docs/help consistency**
-
-Run:
-- `npm run typecheck`
-- `npm test`
-
-Expected:
-- all registered commands expose aligned help and examples
-- docs reflect the real command surface
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/commands/*.ts src/utils/examples.ts README.md AGENTS.md docs/cli-contract.md
-git commit -m "docs: add examples help text and agent docs"
-```
-
-### Task 12: Final Integration Verification
-
-**Files:**
-- Modify: `src/index.ts`
-- Modify: `src/utils/errors.ts`
-- Modify: `src/utils/output.ts`
-- Modify: `src/command-registry.ts`
-- Modify: `src/client.ts`
-
-- [ ] **Step 1: Add final verification coverage for root behavior**
-
-```ts
-// Verify root behaviors:
-// - read-only blocking
-// - JSON-only stdout
-// - exit code mapping
-// - binary command JSON constraints
-```
-
-- [ ] **Step 2: Run the full verification suite**
-
-Run:
-- `npm run build`
-- `npm run typecheck`
-- `npm test`
-
-Expected:
-- all tests pass
-- build succeeds
-- typecheck succeeds
-
-- [ ] **Step 3: Exercise representative commands locally**
-
-Run:
-- `node dist/index.js profiles list --json`
-- `node dist/index.js schemas list --json --read-only`
-- `node dist/index.js files storage --json`
-
-Expected:
-- stable JSON envelope
-- read-only respected
-- no stray stdout text in JSON mode
-
-- [ ] **Step 4: Fix any final root-contract regressions**
-
-Run:
-- `npm run build`
-- `npm run typecheck`
-- `npm test`
-
-Expected:
-- green final verification
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/index.ts src/utils/errors.ts src/utils/output.ts src/command-registry.ts src/client.ts
-git commit -m "test: finalize root contract verification"
-```
-