@karmaniverous/jeeves-meta 0.3.3 → 0.4.1

package/README.md

@@ -1,62 +1,73 @@
 # @karmaniverous/jeeves-meta
 
-Core synthesis engine for the Jeeves platform. Provides schemas, filesystem discovery, weighted staleness scheduling, three-step orchestration, and a full CLI.
+HTTP service for the Jeeves knowledge synthesis engine. Provides a Fastify API, built-in croner-based scheduler, single-threaded synthesis queue, and a Commander CLI.
 
 ## Features
 
-- **Zod schemas** — validated `meta.json` and config structures with open schema support
-- **Filesystem discovery** — glob `.meta/` directories, build ownership trees, compute scopes
-- **Weighted staleness** — depth-aware scheduling formula with emphasis multipliers
+- **Fastify HTTP API** — `/status`, `/metas`, `/preview`, `/synthesize`, `/seed`, `/unlock`, `/config/validate`
+- **Built-in scheduler** — croner-based cron with adaptive backoff
+- **Synthesis queue** — single-threaded, priority-aware, deduplicated
 - **Three-step orchestration** — architect, builder, critic with conditional re-architecture
+- **Discovery via watcher** — scan-based meta discovery with configurable domain tags
+- **Ownership tree** — hierarchical scoping with child meta rollup
 - **Archive management** — timestamped snapshots with configurable pruning
-- **Structure hashing** — detect scope changes (file additions/removals)
-- **Lock management** — filesystem locks with 30-minute stale timeout
-- **Pluggable executor** — `SynthExecutor` interface for runtime-agnostic subprocess spawning
-- **Pluggable watcher client** — `WatcherClient` interface with HTTP implementation (3-retry exponential backoff)
-- **Token tracking** — per-step token counts with exponential moving averages
-- **CLI** — 10 commands for status, listing, synthesis, debugging, and maintenance
-- **Config loader** — `loadSynthConfig()` with `@file:` reference resolution
+- **Lock staging** — write to `.lock` → copy to `meta.json` → archive (crash-safe)
+- **Virtual rule registration** — registers 3 watcher inference rules at startup with retry
+- **Progress reporting** — real-time synthesis events via gateway channel messages
+- **Graceful shutdown** — stop scheduler, release locks, close server
+- **Config hot-reload** — schedule, reportChannel, log level reload without restart
+- **Token tracking** — per-step counts with exponential moving averages
+- **CLI** — `status`, `list`, `detail`, `preview`, `synthesize`, `seed`, `unlock`, `validate`, `service` commands
+- **Zod schemas** — validated meta.json and config with open schema support
 
 ## Install
 
 ```bash
-npm install @karmaniverous/jeeves-meta
+npm install -g @karmaniverous/jeeves-meta
 ```
 
 ## Quick Start
 
-### Library usage
+```bash
+# Start the service
+jeeves-meta start --config /path/to/jeeves-meta.config.json
+
+# Check status
+jeeves-meta status
 
-```typescript
-import {
-  createSynthEngine,
-  HttpWatcherClient,
-  loadSynthConfig,
-} from '@karmaniverous/jeeves-meta';
+# List all metas
+jeeves-meta list
 
-const config = loadSynthConfig('/path/to/jeeves-meta.config.json');
-const watcher = new HttpWatcherClient({ baseUrl: config.watcherUrl });
+# Run synthesis
+jeeves-meta synthesize
 
-const engine = createSynthEngine(config, myExecutor, watcher);
-const results = await engine.synthesize();
+# Install as a system service (prints OS-specific instructions)
+jeeves-meta service install --config /path/to/jeeves-meta.config.json
 ```
 
-### CLI usage
+## HTTP API
 
-```bash
-export JEEVES_META_CONFIG=/path/to/jeeves-meta.config.json
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/status` | Service health, queue state, dependency checks |
+| GET | `/metas` | List metas with filtering and field projection |
+| GET | `/metas/:path` | Single meta detail with optional archive |
+| GET | `/preview` | Dry-run: preview inputs for next synthesis |
+| POST | `/synthesize` | Enqueue synthesis (stalest or specific path) |
+| POST | `/seed` | Create `.meta/` directory + meta.json |
+| POST | `/unlock` | Remove `.lock` file from a meta entity |
+| GET | `/config/validate` | Return sanitized active configuration |
 
-npx @karmaniverous/jeeves-meta status       # summary stats
-npx @karmaniverous/jeeves-meta list         # list all metas
-npx @karmaniverous/jeeves-meta synthesize   # run synthesis cycle
-npx @karmaniverous/jeeves-meta help         # all commands
-```
+## Configuration
+
+See the [Configuration Guide](guides/configuration.md) for all fields, defaults, and environment variable substitution.
 
 ## Documentation
 
-- **[Engine Guides](guides/index.md)** — concepts, configuration, orchestration, scheduling, architecture patterns
-- **[CLI Reference](guides/cli.md)** — all 10 commands with examples
+- **[Guides](guides/index.md)** — concepts, configuration, orchestration, scheduling, architecture
+- **[CLI Reference](guides/cli.md)** — all commands with usage
 
 ## License
 
 BSD-3-Clause
+