### Global Install and Initialization

Source: https://github.com/mithun-chandar/rivergen/blob/main/README.md

Commands to install the rivergen CLI globally or run it without a global installation, and then initialize the project.

```bash
# Global install
npm install -g @rivergen/cli

# Or without a global install
npx @rivergen/cli init

```

--------------------------------

### Task Spec Example

Source: https://github.com/mithun-chandar/rivergen/blob/main/README.md

An example JSON specification for the 'task' domain.

```json
{
  "version": 2,
  "domain": { "key": "task", "displayName": "Task" },
  "entity": { "key": "task", "eventPrefix": "task" },
  "events": ["task.created", "task.updated", "task.deleted", "task.assigned"],
  "room": {
    "template": "project:${projectId}",
    "visibilityField": "visibility"
  }
}
```

--------------------------------

### Rivergen Configuration

Source: https://github.com/mithun-chandar/rivergen/blob/main/README.md

Example of a rivergen.config.json file to override default paths.

```json
{
  "dbImport": "{ prisma } from \"../lib/db\"",
  "sharedPackage": "@myapp/shared",
  "auditDir": "witness",
  "api": {
    "srcRoot": "apps/api/src",
    "packageJsonPath": "apps/api/package.json"
  },
  "web": {
    "srcRoot": "apps/web/src",
    "hooksDir": "apps/web/src/hooks",
    "projectionsDir": "apps/web/src/lib/projections",
    "witnessDir": "apps/web/src/witness",
    "packageJsonPath": "apps/web/package.json"
  }
}
```

--------------------------------

### Invoice Spec Example

Source: https://github.com/mithun-chandar/rivergen/blob/main/README.md

An example JSON specification for the 'invoice' domain, illustrating the structure and fields.

```json
{
  "version": 2,
  "domain": {
    "key": "invoice", // kebab-case — used in filenames
    "displayName": "Invoice" // used in generated comments
  },
  "entity": {
    "key": "invoice", // camelCase — used in type and function names
    "eventPrefix": "invoice" // must match the prefix of every event below
  },
  "events": [
    "invoice.created", // dot notation only — colons rejected
    "invoice.updated",
    "invoice.sent",
    "invoice.voided"
  ],
  "room": {
    "template": "workspace:${workspaceId}", // socket.io room pattern
    "visibilityField": "visibility" // required for private entities — omit to broadcast publicly
  }
}
```

--------------------------------

### Initialize Rivergen Project

Source: https://github.com/mithun-chandar/rivergen/blob/main/README.md

Command to run the rivergen initialization process, which sets up the infrastructure layer.

```bash
rivergen init

```

--------------------------------

### RiverGen Workflow

Source: https://github.com/mithun-chandar/rivergen/blob/main/README.md

The typical workflow for using RiverGen, from initialization to verification.

```bash
# 1. Initialize once per project
rivergen init

# 2. Write a spec
# specs/task.json

# 3. Inspect before writing
rivergen plan specs/task.json

# 4. Scaffold all 12 files + regenerate barrels
rivergen gen specs/task.json

# 5. Fill business logic in this order:
#    a. mutations.ts          → DB call + input validation
#    b. schemas/task.ts       → event payload fields (before adding to publish())
#    c. task.listener.ts      → wire subscribe → broadcast
#    d. use-task.ts           → query key context in onMutate
#    e. task-projections.ts   → list key context in applyEntity*()
#    f. task.witness.ts       → field continuity contract

# 6. Verify — all 12 gates must pass
rivergen verify
```

--------------------------------

### Rivergen CLI Commands

Source: https://github.com/mithun-chandar/rivergen/blob/main/README.md

Reference for Rivergen CLI commands and options.

```bash
rivergen init                   Write infrastructure files (once per project)
rivergen plan  <spec>           Dry-run: show what would be generated
rivergen gen   <spec>           Write domain files + regenerate barrels
rivergen verify                 Run all 12 gates

Options:
  --force                       Overwrite existing files
  --install                     Auto-install missing packages via pnpm
  --root <path>                 Project root (default: cwd)
```

--------------------------------

### Rivergen Generation and Verification Commands

Source: https://github.com/mithun-chandar/rivergen/blob/main/README.md

Commands to plan, generate, and verify code using Rivergen.

```bash
rivergen plan specs/task.json   # inspect what will be written
rivergen gen specs/task.json    # write 12 files + regenerate barrels
```

```bash
rivergen verify
# ✓ ALL GATES PASSED (11/11, 1 skipped)
```

--------------------------------

### Verify RiverGen gates

Source: https://github.com/mithun-chandar/rivergen/blob/main/CONTRIBUTING.md

Command to run all 12 gates against a real project that uses a changed template.

```bash
rivergen verify
```

--------------------------------

### Verify Witness suite

Source: https://github.com/mithun-chandar/rivergen/blob/main/CONTRIBUTING.md

Command to run the full Witness suite and check Layer 3 assertion counts.

```bash
rivergen verify
# Look for: Layer 3: N/N assertions passed
```

--------------------------------

### Add Witness as Dev Dependency

Source: https://github.com/mithun-chandar/rivergen/blob/main/README.md

Command to add the @rivergen/witness package as a development dependency to a specific project (apps/web) using pnpm or npm.

```bash
pnpm add -D @rivergen/witness --filter ./apps/web
# or: npm install -D @rivergen/witness (inside apps/web)

```

--------------------------------

### Task Witness Scaffold

Source: https://github.com/mithun-chandar/rivergen/blob/main/README.md

This is a generated scaffold for defining witness assertions for the 'task' domain. It includes the payload interface, domain definition, required fields for events, test payloads, and a lifecycle function for writing assertions.

```typescript
// task.witness.ts — generated scaffold, you fill the assertions
import type { DomainWitness, WitnessAssertion } from "@rivergen/witness";

export interface TaskPayload {
  taskId: string;
  title: string;
  projectId: string;
  clientTempId?: string;
  // ... all fields the UI reads from useQuery data
}

export const taskWitness: DomainWitness<TaskPayload> = {
  domain: "task",
  events: ["task.created", "task.updated", "task.deleted"],

  requiredFields: {
    "task.created": ["taskId", "title", "projectId"],
    "task.updated": ["taskId", "title"],
    "task.deleted": ["taskId"],
  },

  testPayloads: {
    "task.created": { taskId: "task-001", title: "Fix bug", projectId: "proj-001",
      clientTempId: "ghost-001", _meta: { resourceId: "task-001",
        actor: { id: "user-01", type: "user" }, context: { realmId: "proj-001" },
        correlationId: "corr-01", eventVersion: "1.0" } },
    // ...
  },

  async lifecycle(queryClient): Promise<WitnessAssertion[]> {
    const assertions: WitnessAssertion[] = [];
    // seed cache, apply events, assert fields survived each hop
    // apply${E}Created(testPayloads["task.created"], queryClient);
    // const list = queryClient.getQueryData<Task[]>(taskKeys.list("proj-001")) ?? [];
    // assertions.push({ name: "task.created lands in list", ok: list.some(t => t.id === "task-001") });
    return assertions;
  },

  signals: {},
};

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.