docs: add core concepts (sense, signal, reflex, workflow) to agent rules

- .cursor/rules/global.mdc: coding conventions as Cursor agent rules
- CLAUDE.md: same conventions for Claude Code / Hermes agents
- Content derived from docs/coding-conventions.md
- Includes no-dynamic-import rule in CLAUDE.md for completeness

.cursor/rules/global.mdc

@@ -0,0 +1,189 @@
+---
+description: Nerve project coding conventions — style, patterns, and toolchain
+globs: packages/*/src/**/*.ts
+alwaysApply: true
+---
+
+# Nerve Coding Conventions
+
+## Core Concepts
+
+```
+External World → Sense → Signal → Reflex → Workflow → Log
+                  ↑                                     ↑
+              "what to observe"                  "what to do"
+```
+
+**Nerve** is a lightweight observation engine daemon for autonomous agents. It continuously observes external state, reacts to changes via declarative rules, and orchestrates multi-step workflows.
+
+### Key Terms
+
+| Concept | What it is |
+|---------|-----------|
+| **Sense** | A `compute()` function that samples or derives data. Returns `T \| null` — non-null emits a Signal, null is silent. Each Sense has its own SQLite database. |
+| **Signal** | A notification emitted when a Sense returns non-null. Pure fact, no intent. Distributed via an in-memory Signal Bus. Not persisted. |
+| **Reflex** | A declarative trigger (YAML) connecting Senses to actions. Trigger types: `interval` (periodic), `on` (react to Signals). Action types: trigger a Sense, or start a Workflow. |
+| **Workflow** | A stateful multi-step execution. Contains **Roles** (actors with side effects) and a **Moderator** (pure router). Each instance is a **Thread** with a unique `runId`. |
+| **Log** | Immutable audit trail. Records executions, state transitions, errors. **Cannot trigger Reflexes** — prevents feedback loops. |
+| **Engine** | The kernel orchestrating everything. Holds Signal Bus, Reflex Scheduler, Process Manager, Workflow Manager. Never loads user code directly — all user code runs in isolated Workers. |
+| **Daemon** | The `nerve-daemon` package — engine runtime. Runs as a background process. |
+
+### Architecture Rules
+
+- **Three orthogonal extension points**: Sense (what to compute), Reflex (when to compute), Workflow (what to do)
+- **Process isolation**: One worker per Sense group (long-lived), one per Workflow type (on-demand). Workers never talk to each other.
+- **Causality is one-directional**: External world → Sense → Signal → Reflex → Action + Log. Logs are the end of the chain.
+
+
+
+## Language & Paradigm
+
+### Functional-first
+
+Use `function` + `type`, not `class` + `interface`.
+
+```typescript
+// ✅ Good
+type Signal = {
+  senseId: string;
+  value: unknown;
+  ts: number;
+};
+
+function createSignal(senseId: string, value: unknown): Signal {
+  return { senseId, value, ts: Date.now() };
+}
+
+// ❌ Bad — no class, no interface
+class Signal implements ISignal { ... }
+```
+
+### Rules
+
+| Rule | Description |
+|------|-------------|
+| `type` over `interface` | All type definitions use `type` |
+| `function` over `class` | Pure functions + closures, no class |
+| No `this` | Functions must not depend on `this` context |
+| No inheritance | No `extends`, `implements`, `abstract` |
+| Composition over inheritance | Use function composition |
+| Immutability first | Use `Readonly<T>`, `as const`, avoid mutation |
+| No optional properties | Use `T \| null` instead of `?:` — see below |
+
+### Exceptions
+
+Classes are allowed when:
+- Required by a third-party library (e.g. Drizzle's `sqliteTable`)
+- Error subclasses (`class NerveError extends Error`)
+
+### No Optional Properties
+
+Never use `?:`. All nullable fields must be explicit `T | null`.
+
+```typescript
+// ✅ Good
+type SenseConfig = {
+  group: string;
+  throttle: string | null;
+  timeout: string | null;
+};
+
+// ❌ Bad
+type SenseConfig = {
+  group: string;
+  throttle?: string;
+  timeout?: string;
+};
+```
+
+For mutually exclusive fields, use discriminated unions:
+
+```typescript
+// ✅ Good
+type ReflexConfig =
+  | { kind: "sense"; sense: string; interval: string | null; on: string[] | null }
+  | { kind: "workflow"; workflow: string; on: string[] | null };
+```
+
+## Modules & Exports
+
+- Always named exports, never default exports
+- One module = one responsibility, filename = purpose
+
+```typescript
+// ✅ Named exports only
+export function startEngine(config: EngineConfig): Engine { ... }
+export type EngineConfig = { ... };
+
+// ❌ No default exports
+export default function startEngine() { ... }
+```
+
+## Naming
+
+| Type | Style | Example |
+|------|-------|---------|
+| Files | kebab-case | `signal-bus.ts` |
+| Types | PascalCase | `SignalBus` |
+| Functions/variables | camelCase | `createSignalBus` |
+| Constants | UPPER_SNAKE | `MAX_RETRY_COUNT` |
+| Generics | Single letter or descriptive | `T`, `TValue` |
+
+## Error Handling
+
+- Use `Result` type for expected failures
+- `throw` only for unrecoverable bugs (programmer errors)
+- No try-catch for flow control
+
+```typescript
+type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };
+
+function parseSenseConfig(raw: unknown): Result<SenseConfig> { ... }
+```
+
+## Async
+
+- Always `async/await`, never `.then()` chains
+
+## Toolchain
+
+| Tool | Purpose |
+|------|---------|
+| **pnpm** | Package manager |
+| **TypeScript** | Type checking (strict mode) |
+| **Biome** | Lint + format (replaces ESLint + Prettier) |
+| **tsup** | Bundling |
+
+### Commands
+
+```bash
+pnpm run check      # biome check (lint + format)
+pnpm run format     # biome format --write
+pnpm run build      # full build
+pnpm test           # run tests
+```
+
+## Monorepo Structure
+
+```
+nerve/
+  packages/
+    core/           # @nerve/core — shared types and utils
+    cli/            # @nerve/cli — CLI entry point
+    daemon/         # @nerve/daemon — engine runtime
+  docs/             # RFCs, conventions
+  biome.json        # root Biome config
+  tsconfig.json     # root TypeScript config (composite project references)
+```
+
+- `core` is the shared layer; `cli` and `daemon` both depend on it
+- `cli` and `daemon` must NOT depend on each other
+
+## Commit Convention
+
+```
+<type>(<scope>): <description>
+
+type: feat | fix | refactor | docs | chore | test
+scope: core | cli | daemon | rfc-001 | ...
+```

.github/copilot-instructions.md

@@ -0,0 +1,180 @@
+# Nerve Coding Conventions
+
+## Core Concepts
+
+```
+External World → Sense → Signal → Reflex → Workflow → Log
+                  ↑                                     ↑
+              "what to observe"                  "what to do"
+```
+
+**Nerve** is a lightweight observation engine daemon for autonomous agents. It continuously observes external state, reacts to changes via declarative rules, and orchestrates multi-step workflows.
+
+### Key Terms
+
+| Concept | What it is |
+|---------|-----------|
+| **Sense** | A `compute()` function that samples or derives data. Returns `T \| null` — non-null emits a Signal, null is silent. Each Sense has its own SQLite database. |
+| **Signal** | A notification emitted when a Sense returns non-null. Pure fact, no intent. Distributed via an in-memory Signal Bus. Not persisted. |
+| **Reflex** | A declarative trigger (YAML) connecting Senses to actions. Trigger types: `interval` (periodic), `on` (react to Signals). Action types: trigger a Sense, or start a Workflow. |
+| **Workflow** | A stateful multi-step execution. Contains **Roles** (actors with side effects) and a **Moderator** (pure router). Each instance is a **Thread** with a unique `runId`. |
+| **Log** | Immutable audit trail. Records executions, state transitions, errors. **Cannot trigger Reflexes** — prevents feedback loops. |
+| **Engine** | The kernel orchestrating everything. Holds Signal Bus, Reflex Scheduler, Process Manager, Workflow Manager. Never loads user code directly — all user code runs in isolated Workers. |
+| **Daemon** | The `nerve-daemon` package — engine runtime. Runs as a background process. |
+
+### Architecture Rules
+
+- **Three orthogonal extension points**: Sense (what to compute), Reflex (when to compute), Workflow (what to do)
+- **Process isolation**: One worker per Sense group (long-lived), one per Workflow type (on-demand). Workers never talk to each other.
+- **Causality is one-directional**: External world → Sense → Signal → Reflex → Action + Log. Logs are the end of the chain.
+
+
+
+## Language & Paradigm
+
+### Functional-first
+
+Use `function` + `type`, not `class` + `interface`.
+
+```typescript
+// ✅ Good
+type Signal = {
+  senseId: string;
+  value: unknown;
+  ts: number;
+};
+
+function createSignal(senseId: string, value: unknown): Signal {
+  return { senseId, value, ts: Date.now() };
+}
+
+// ❌ Bad — no class, no interface
+class Signal implements ISignal { ... }
+```
+
+### Rules
+
+| Rule | Description |
+|------|-------------|
+| `type` over `interface` | All type definitions use `type` |
+| `function` over `class` | Pure functions + closures, no class |
+| No `this` | Functions must not depend on `this` context |
+| No inheritance | No `extends`, `implements`, `abstract` |
+| Composition over inheritance | Use function composition |
+| Immutability first | Use `Readonly<T>`, `as const`, avoid mutation |
+| No optional properties | Use `T \| null` instead of `?:` — see below |
+
+### Exceptions
+
+Classes are allowed when:
+- Required by a third-party library (e.g. Drizzle's `sqliteTable`)
+- Error subclasses (`class NerveError extends Error`)
+
+### No Optional Properties
+
+Never use `?:`. All nullable fields must be explicit `T | null`.
+
+```typescript
+// ✅ Good
+type SenseConfig = {
+  group: string;
+  throttle: string | null;
+  timeout: string | null;
+};
+
+// ❌ Bad
+type SenseConfig = {
+  group: string;
+  throttle?: string;
+  timeout?: string;
+};
+```
+
+For mutually exclusive fields, use discriminated unions:
+
+```typescript
+// ✅ Good
+type ReflexConfig =
+  | { kind: "sense"; sense: string; interval: string | null; on: string[] | null }
+  | { kind: "workflow"; workflow: string; on: string[] | null };
+```
+
+## Modules & Exports
+
+- Always named exports, never default exports
+- One module = one responsibility, filename = purpose
+
+## Naming
+
+| Type | Style | Example |
+|------|-------|---------|
+| Files | kebab-case | `signal-bus.ts` |
+| Types | PascalCase | `SignalBus` |
+| Functions/variables | camelCase | `createSignalBus` |
+| Constants | UPPER_SNAKE | `MAX_RETRY_COUNT` |
+| Generics | Single letter or descriptive | `T`, `TValue` |
+
+## Error Handling
+
+- Use `Result` type for expected failures
+- `throw` only for unrecoverable bugs (programmer errors)
+- No try-catch for flow control
+
+```typescript
+type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };
+```
+
+## Async
+
+- Always `async/await`, never `.then()` chains
+
+## No Dynamic Import
+
+Do NOT use `await import()` in production code. Always use static top-level `import`.
+
+Exceptions (must include a comment):
+1. `sense-runtime.ts` — user module paths known only at runtime
+2. `workflow-worker.ts` — user module paths known only at runtime
+
+Test files (`__tests__/**`) are exempt.
+
+## Toolchain
+
+| Tool | Purpose |
+|------|---------|
+| **pnpm** | Package manager |
+| **TypeScript** | Type checking (strict mode) |
+| **Biome** | Lint + format (replaces ESLint + Prettier) |
+| **tsup** | Bundling |
+
+### Commands
+
+```bash
+pnpm run check      # biome check (lint + format)
+pnpm run format     # biome format --write
+pnpm run build      # full build
+pnpm test           # run tests
+```
+
+## Monorepo Structure
+
+```
+nerve/
+  packages/
+    core/           # @nerve/core — shared types and utils
+    cli/            # @nerve/cli — CLI entry point
+    daemon/         # @nerve/daemon — engine runtime
+  docs/             # RFCs, conventions
+```
+
+- `core` is the shared layer; `cli` and `daemon` both depend on it
+- `cli` and `daemon` must NOT depend on each other
+
+## Commit Convention
+
+```
+<type>(<scope>): <description>
+
+type: feat | fix | refactor | docs | chore | test
+scope: core | cli | daemon | rfc-001 | ...
+```

CLAUDE.md

@@ -0,0 +1,180 @@
+# Nerve Coding Conventions
+
+## Core Concepts
+
+```
+External World → Sense → Signal → Reflex → Workflow → Log
+                  ↑                                     ↑
+              "what to observe"                  "what to do"
+```
+
+**Nerve** is a lightweight observation engine daemon for autonomous agents. It continuously observes external state, reacts to changes via declarative rules, and orchestrates multi-step workflows.
+
+### Key Terms
+
+| Concept | What it is |
+|---------|-----------|
+| **Sense** | A `compute()` function that samples or derives data. Returns `T \| null` — non-null emits a Signal, null is silent. Each Sense has its own SQLite database. |
+| **Signal** | A notification emitted when a Sense returns non-null. Pure fact, no intent. Distributed via an in-memory Signal Bus. Not persisted. |
+| **Reflex** | A declarative trigger (YAML) connecting Senses to actions. Trigger types: `interval` (periodic), `on` (react to Signals). Action types: trigger a Sense, or start a Workflow. |
+| **Workflow** | A stateful multi-step execution. Contains **Roles** (actors with side effects) and a **Moderator** (pure router). Each instance is a **Thread** with a unique `runId`. |
+| **Log** | Immutable audit trail. Records executions, state transitions, errors. **Cannot trigger Reflexes** — prevents feedback loops. |
+| **Engine** | The kernel orchestrating everything. Holds Signal Bus, Reflex Scheduler, Process Manager, Workflow Manager. Never loads user code directly — all user code runs in isolated Workers. |
+| **Daemon** | The `nerve-daemon` package — engine runtime. Runs as a background process. |
+
+### Architecture Rules
+
+- **Three orthogonal extension points**: Sense (what to compute), Reflex (when to compute), Workflow (what to do)
+- **Process isolation**: One worker per Sense group (long-lived), one per Workflow type (on-demand). Workers never talk to each other.
+- **Causality is one-directional**: External world → Sense → Signal → Reflex → Action + Log. Logs are the end of the chain.
+
+
+
+## Language & Paradigm
+
+### Functional-first
+
+Use `function` + `type`, not `class` + `interface`.
+
+```typescript
+// ✅ Good
+type Signal = {
+  senseId: string;
+  value: unknown;
+  ts: number;
+};
+
+function createSignal(senseId: string, value: unknown): Signal {
+  return { senseId, value, ts: Date.now() };
+}
+
+// ❌ Bad — no class, no interface
+class Signal implements ISignal { ... }
+```
+
+### Rules
+
+| Rule | Description |
+|------|-------------|
+| `type` over `interface` | All type definitions use `type` |
+| `function` over `class` | Pure functions + closures, no class |
+| No `this` | Functions must not depend on `this` context |
+| No inheritance | No `extends`, `implements`, `abstract` |
+| Composition over inheritance | Use function composition |
+| Immutability first | Use `Readonly<T>`, `as const`, avoid mutation |
+| No optional properties | Use `T \| null` instead of `?:` — see below |
+
+### Exceptions
+
+Classes are allowed when:
+- Required by a third-party library (e.g. Drizzle's `sqliteTable`)
+- Error subclasses (`class NerveError extends Error`)
+
+### No Optional Properties
+
+Never use `?:`. All nullable fields must be explicit `T | null`.
+
+```typescript
+// ✅ Good
+type SenseConfig = {
+  group: string;
+  throttle: string | null;
+  timeout: string | null;
+};
+
+// ❌ Bad
+type SenseConfig = {
+  group: string;
+  throttle?: string;
+  timeout?: string;
+};
+```
+
+For mutually exclusive fields, use discriminated unions:
+
+```typescript
+// ✅ Good
+type ReflexConfig =
+  | { kind: "sense"; sense: string; interval: string | null; on: string[] | null }
+  | { kind: "workflow"; workflow: string; on: string[] | null };
+```
+
+## Modules & Exports
+
+- Always named exports, never default exports
+- One module = one responsibility, filename = purpose
+
+## Naming
+
+| Type | Style | Example |
+|------|-------|---------|
+| Files | kebab-case | `signal-bus.ts` |
+| Types | PascalCase | `SignalBus` |
+| Functions/variables | camelCase | `createSignalBus` |
+| Constants | UPPER_SNAKE | `MAX_RETRY_COUNT` |
+| Generics | Single letter or descriptive | `T`, `TValue` |
+
+## Error Handling
+
+- Use `Result` type for expected failures
+- `throw` only for unrecoverable bugs (programmer errors)
+- No try-catch for flow control
+
+```typescript
+type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };
+```
+
+## Async
+
+- Always `async/await`, never `.then()` chains
+
+## No Dynamic Import
+
+Do NOT use `await import()` in production code. Always use static top-level `import`.
+
+Exceptions (must include a comment):
+1. `sense-runtime.ts` — user module paths known only at runtime
+2. `workflow-worker.ts` — user module paths known only at runtime
+
+Test files (`__tests__/**`) are exempt.
+
+## Toolchain
+
+| Tool | Purpose |
+|------|---------|
+| **pnpm** | Package manager |
+| **TypeScript** | Type checking (strict mode) |
+| **Biome** | Lint + format (replaces ESLint + Prettier) |
+| **tsup** | Bundling |
+
+### Commands
+
+```bash
+pnpm run check      # biome check (lint + format)
+pnpm run format     # biome format --write
+pnpm run build      # full build
+pnpm test           # run tests
+```
+
+## Monorepo Structure
+
+```
+nerve/
+  packages/
+    core/           # @nerve/core — shared types and utils
+    cli/            # @nerve/cli — CLI entry point
+    daemon/         # @nerve/daemon — engine runtime
+  docs/             # RFCs, conventions
+```
+
+- `core` is the shared layer; `cli` and `daemon` both depend on it
+- `cli` and `daemon` must NOT depend on each other
+
+## Commit Convention
+
+```
+<type>(<scope>): <description>
+
+type: feat | fix | refactor | docs | chore | test
+scope: core | cli | daemon | rfc-001 | ...
+```

README.md

@@ -1,3 +1,165 @@
 # nerve
 
-Observation engine — Sense, Reflex, Workflow
+**Observation engine for autonomous agents** — sense the world, react to changes, run workflows.
+
+Nerve is a lightweight daemon that continuously observes external state through **Senses**, reacts via declarative **Reflexes**, and orchestrates multi-step **Workflows**. Built for the [Uncaged](https://github.com/uncaged) agent framework.
+
+## Core Concepts
+
+```
+External World → Sense → Signal → Reflex → Workflow → Log
+                  ↑                                     ↑
+              "what to observe"                  "what to do"
+```
+
+| Concept | Metaphor | Role |
+|---------|----------|------|
+| **Sense** | 👁️ Perception | A `compute()` function that samples or derives data. Each sense has its own SQLite database. |
+| **Reflex** | ⚡ Reaction | Declarative trigger — interval-based, event-driven, or both. Connects senses to actions. |
+| **Signal** | 📡 Notification | Emitted when a sense returns non-null. Other reflexes can listen for signals. |
+| **Workflow** | 🔧 Action | Stateful multi-step execution with Roles (actors) and a Moderator (coordinator). |
+| **Log** | 📝 Record | Immutable audit trail. Queryable by senses, but **cannot** trigger reflexes (prevents feedback loops). |
+
+Three extension points, fully orthogonal — a Sense doesn't know when it runs, a Reflex doesn't know what it computes, a Workflow doesn't know why it was triggered.
+
+## Packages
+
+| Package | Description |
+|---------|-------------|
+| [`@uncaged/nerve-core`](./packages/core) | Shared types and config parser |
+| [`@uncaged/nerve-daemon`](./packages/daemon) | The observation engine — kernel, sense runtime, reflex scheduler, workflow manager |
+| [`@uncaged/nerve-cli`](./packages/cli) | CLI tool (`nerve`) — init, start, stop, logs, query |
+
+## Quick Start
+
+```bash
+# Requirements: Node.js ≥ 22.5, pnpm
+pnpm add -g @uncaged/nerve-cli
+
+# Initialize a workspace
+mkdir my-agent && cd my-agent
+nerve init
+
+# Write a sense
+cat > senses/cpu-usage/compute.ts << 'EOF'
+export async function compute() {
+  const [load] = (await import("node:os")).loadavg();
+  return load > 2.0 ? { load } : null;  // signal only when load is high
+}
+EOF
+
+# Configure reflexes in nerve.yaml
+cat > nerve.yaml << 'EOF'
+senses:
+  cpu-usage:
+    group: system
+    throttle: 10s
+
+reflexes:
+  - kind: sense
+    sense: cpu-usage
+    interval: 30s
+EOF
+
+# Run
+nerve dev          # foreground (development)
+nerve daemon start # background (production)
+nerve status       # check health
+nerve logs         # view logs
+```
+
+## Configuration
+
+`nerve.yaml` declares senses, reflexes, and workflows:
+
+```yaml
+senses:
+  cpu-usage:
+    group: system          # senses in the same group share a worker process
+    throttle: 10s          # min interval between computes
+    timeout: 30s           # max compute duration
+    gracePeriod: 5s        # wait before first compute after startup
+
+reflexes:
+  - kind: sense
+    sense: cpu-usage
+    interval: 30s          # periodic trigger
+    on: [disk-pressure]    # also trigger on signals from other senses
+
+  - kind: workflow
+    workflow: cleanup
+    on: [disk-pressure]    # start a workflow when signal fires
+
+workflows:
+  cleanup:
+    concurrency: 1
+    overflow: drop         # discard if already running
+  code-review:
+    concurrency: 3
+    overflow: queue
+    maxQueue: 20
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Kernel                                                 │
+│                                                         │
+│  ┌──────────┐   ┌──────────┐   ┌──────────┐           │
+│  │ Worker   │   │ Worker   │   │ Worker   │  (1 per   │
+│  │ (group A)│   │ (group B)│   │ (group C)│   group)  │
+│  │ sense-1  │   │ sense-3  │   │ sense-5  │           │
+│  │ sense-2  │   │ sense-4  │   │          │           │
+│  └────┬─────┘   └────┬─────┘   └────┬─────┘           │
+│       │              │              │                   │
+│       └──────────────┼──────────────┘                   │
+│                      ▼                                  │
+│              ┌──────────────┐                           │
+│              │  Signal Bus  │                           │
+│              └──────┬───────┘                           │
+│                     ▼                                   │
+│           ┌──────────────────┐                          │
+│           │ Reflex Scheduler │                          │
+│           └────────┬─────────┘                          │
+│                    ▼                                    │
+│          ┌───────────────────┐                          │
+│          │ Workflow Manager  │──→ Log Store (SQLite)    │
+│          └───────────────────┘                          │
+└─────────────────────────────────────────────────────────┘
+```
+
+- **Worker processes** — one per sense group, forked by the kernel. Isolated compute execution.
+- **Signal Bus** — in-memory pub/sub for signal distribution.
+- **Reflex Scheduler** — interval timers + signal subscriptions, with throttle/coalesce.
+- **Workflow Manager** — concurrency control (drop/queue), thread lifecycle tracking.
+- **Log Store** — WAL-mode SQLite via `node:sqlite`, with archival and retention policies.
+
+## Tech Stack
+
+- **Zero native addons** — uses Node.js built-in `node:sqlite` (DatabaseSync)
+- **Drizzle ORM** v1.0 for sense databases
+- **rslib** (rspack) for building
+- **Biome** for formatting/linting
+- **Vitest** for testing
+- **pnpm** workspaces for monorepo management
+
+## Development
+
+```bash
+git clone https://git.shazhou.work/uncaged/nerve.git
+cd nerve
+pnpm install
+pnpm build
+pnpm -r test     # run all tests
+```
+
+## Design Documents
+
+- [RFC-001: Observation Engine](./docs/rfc-001-observation-engine.md) — Sense, Signal, Reflex model
+- [RFC-002: Workflow Engine](./docs/rfc-002-workflow-engine.md) — Stateful workflow execution
+- [Coding Conventions](./docs/coding-conventions.md)
+
+## License
+
+MIT

packages/cli/README.md

@@ -0,0 +1,69 @@
+# @uncaged/nerve-cli
+
+Command-line interface for the [nerve](../../README.md) observation engine.
+
+## Install
+
+```bash
+pnpm add -g @uncaged/nerve-cli
+# or
+npx @uncaged/nerve-cli
+```
+
+Requires Node.js ≥ 22.5.
+
+## Commands
+
+### Workspace
+
+```bash
+nerve init                  # Initialize a nerve workspace (installs deps, scaffolds config)
+nerve validate              # Validate nerve.yaml configuration
+```
+
+### Daemon Management
+
+```bash
+nerve daemon start          # Start the daemon (background)
+nerve daemon stop           # Stop the daemon
+nerve daemon status         # Check daemon health
+nerve daemon restart        # Restart the daemon
+nerve daemon logs           # Tail daemon logs
+```
+
+### Development
+
+```bash
+nerve dev                   # Run in foreground mode (no daemon, Ctrl+C to stop)
+```
+
+### Querying
+
+```bash
+nerve logs                  # View structured logs
+nerve sense query <name>    # Query a sense's SQLite database
+nerve sense schema <name>   # Show a sense's database schema
+nerve status                # Daemon health summary
+```
+
+### Workflows
+
+```bash
+nerve workflow list         # List workflow runs
+nerve workflow show <runId> # Show workflow run details
+```
+
+### Top-level Aliases
+
+For convenience, these aliases are available:
+
+```bash
+nerve start    → nerve daemon start
+nerve stop     → nerve daemon stop
+nerve status   → nerve daemon status
+nerve logs     → nerve daemon logs
+```
+
+## License
+
+MIT

packages/cli/package.json

@@ -3,7 +3,7 @@
   "engines": {
     "node": ">=22.5.0"
   },
-  "version": "0.1.8",
+  "version": "0.2.0",
   "type": "module",
   "bin": {
     "nerve": "dist/cli.js"

packages/core/README.md

@@ -0,0 +1,39 @@
+# @uncaged/nerve-core
+
+Shared types and configuration parser for the [nerve](../../README.md) observation engine.
+
+## What's Inside
+
+- **Type definitions** — `Signal`, `SenseConfig`, `ReflexConfig`, `WorkflowConfig`, `NerveConfig`, and all related types
+- **Config parser** — `parseNerveConfig(yaml)` validates and parses `nerve.yaml` into a typed `NerveConfig`
+- **Result type** — `Result<T>` with `ok()` / `err()` helpers for explicit error handling (no thrown exceptions)
+
+## Usage
+
+```typescript
+import { parseNerveConfig, ok, err } from "@uncaged/nerve-core";
+import type { NerveConfig, Signal, Result } from "@uncaged/nerve-core";
+
+const result: Result<NerveConfig> = parseNerveConfig(yamlString);
+if (result.ok) {
+  console.log(result.value.senses);
+}
+```
+
+## Duration Format
+
+Config fields like `throttle`, `timeout`, and `interval` accept human-readable durations:
+
+- `5s` — 5 seconds
+- `10m` — 10 minutes
+- `1h` — 1 hour
+
+## Install
+
+```bash
+pnpm add @uncaged/nerve-core
+```
+
+## License
+
+MIT

packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/nerve-core",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "type": "module",
   "main": "dist/index.js",
   "files": [

packages/daemon/README.md

@@ -0,0 +1,57 @@
+# @uncaged/nerve-daemon
+
+The observation engine runtime for [nerve](../../README.md) — runs senses, routes signals, schedules reflexes, and manages workflows.
+
+## Architecture
+
+| Module | Responsibility |
+|--------|---------------|
+| **Kernel** | Top-level orchestrator — spawns workers, wires up signal bus, scheduler, and workflow manager. Supports hot reload and graceful shutdown. |
+| **Sense Runtime** | Per-sense SQLite database (via `node:sqlite` + Drizzle ORM), migration runner, peer DB read access. |
+| **Sense Worker** | Forked child process — one per sense group. Runs compute functions in isolation. |
+| **Signal Bus** | In-memory pub/sub. Sense computes emit signals; reflexes and workflows subscribe. |
+| **Reflex Scheduler** | Drives compute triggers — interval timers, signal-based events, throttle/coalesce logic. |
+| **Workflow Manager** | Concurrency control (drop/queue), thread lifecycle, worker process management (RFC-002). |
+| **Log Store** | Structured log storage in WAL-mode SQLite. Supports retention policies, archival to JSONL, and workflow run tracking. |
+| **Blob Store** | Binary artifact storage for workflow outputs. |
+| **File Watcher** | Watches `nerve.yaml` and sense files for hot reload. |
+| **Daemon IPC** | Unix socket server for CLI ↔ daemon communication. |
+
+## Key Design Decisions
+
+- **One worker process per sense group** — isolation between groups, shared compute within a group
+- **`node:sqlite` (DatabaseSync)** — zero native addons, WAL mode, built into Node.js ≥ 22.5
+- **Throttle + coalesce** — if compute is in-flight, at most one pending trigger is queued (no unbounded accumulation)
+- **Log ≠ Signal** — logs are queryable data assets but cannot trigger reflexes (prevents feedback loops)
+
+## Usage
+
+The daemon is typically started via the CLI (`nerve daemon start`), but can be used programmatically:
+
+```typescript
+import { createKernel } from "@uncaged/nerve-daemon";
+
+const kernel = await createKernel(nerveRoot);
+await kernel.ready;
+
+// Trigger a sense manually
+kernel.triggerSense("cpu-usage");
+
+// Check health
+const health = kernel.getHealth();
+
+// Graceful shutdown
+await kernel.stop();
+```
+
+## Install
+
+```bash
+pnpm add @uncaged/nerve-daemon
+```
+
+Requires Node.js ≥ 22.5 (for `node:sqlite`).
+
+## License
+
+MIT

packages/daemon/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/nerve-daemon",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

packages/daemon/src/workflow-worker.ts

@@ -120,8 +120,7 @@ async function runThread(
 
   const initialEvent: CommandEvent = {
     type: "thread_start",
-    triggerPayload:
-      triggerPayload != null && typeof triggerPayload === "object" ? triggerPayload : {},
+    triggerPayload: triggerPayload ?? {},
   };
 
   // On resume: replay persisted events, run the next un-executed role, then continue.