docs: add per-package READMEs for all symbi-* workspace packages

packages/agent/README.md

@@ -0,0 +1,53 @@
+# symbi-agent
+
+[![npm](https://img.shields.io/npm/v/symbi-agent.svg)](https://www.npmjs.com/package/symbi-agent)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](../../LICENSE)
+
+Agent, schedule, channel, workflow, and AgentPin clients for the [Symbiont JavaScript/TypeScript SDK](https://github.com/ThirdKeyAI/symbiont-sdk-js).
+
+Most users don't install this directly — the unified `SymbiontClient` in [`symbi-core`](https://www.npmjs.com/package/symbi-core) already exposes these as `client.agents`, `client.schedules`, `client.channels`, `client.workflows`, and `client.agentpin`. Pull `symbi-agent` in explicitly when you want a narrow dependency or you're composing your own client.
+
+## Install
+
+```bash
+npm install symbi-agent
+```
+
+## Usage
+
+```typescript
+import { AgentClient, ScheduleClient, ChannelClient, AgentPinClient } from 'symbi-agent';
+
+// Given an authenticated Symbiont HTTP transport (see symbi-core for the full client):
+const agents = new AgentClient(transport);
+const agent = await agents.createAgent({
+  name: 'textProcessor',
+  description: 'Processes text input',
+  parameters: [{ name: 'text', type: { name: 'string' }, required: true }],
+  returnType: { name: 'string' },
+  capabilities: ['text_processing'],
+});
+
+const result = await agents.executeAgent(agent.id, { text: 'Hello, Symbiont!' });
+console.log(result.result);
+```
+
+## Exports
+
+| Client | Purpose |
+|--------|---------|
+| `AgentClient` | Agent lifecycle: create, update, execute, re-execute, delete, list, status, history, heartbeat, push events |
+| `ScheduleClient` | Cron schedules with pause/resume/trigger and run history |
+| `ChannelClient` | Slack / Teams / Mattermost channel adapters, user mappings, audit |
+| `WorkflowClient` | Multi-agent workflow execution |
+| `AgentPinClient` | Client-side AgentPin — keygen, credential issuance, 12-step verification, discovery, key pinning, trust bundles (no runtime required) |
+
+## See also
+
+- [`symbi-core`](https://www.npmjs.com/package/symbi-core) — main client exposing all of these as sub-clients
+- [SDK README](https://github.com/ThirdKeyAI/symbiont-sdk-js#readme) — full examples including AgentPin and reasoning loop
+- [docs.symbiont.dev](https://docs.symbiont.dev) — runtime documentation
+
+## License
+
+Apache 2.0. See [LICENSE](../../LICENSE).

packages/cli/README.md

@@ -0,0 +1,72 @@
+# symbi-cli
+
+[![npm](https://img.shields.io/npm/v/symbi-cli.svg)](https://www.npmjs.com/package/symbi-cli)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](../../LICENSE)
+
+Command-line tooling for the [Symbiont JavaScript/TypeScript SDK](https://github.com/ThirdKeyAI/symbiont-sdk-js). Drive the Symbiont runtime from your shell — manage agents, run development helpers, handle auth.
+
+> Distinct from [`symbi`](https://crates.io/crates/symbi), the Rust-native runtime binary. `symbi-cli` is a thin Node-based helper that speaks to the runtime over its HTTP API; `symbi` is the runtime itself.
+
+## Install
+
+```bash
+npm install -g symbi-cli
+```
+
+Or use `npx`:
+
+```bash
+npx symbi-cli agent list
+```
+
+## Configuration
+
+```bash
+export SYMBIONT_API_KEY=...
+export SYMBIONT_API_URL=http://localhost:8080/api/v1
+```
+
+Or create `~/.symbiont/config.json`:
+
+```json
+{
+  "apiKey": "...",
+  "apiUrl": "http://localhost:8080/api/v1"
+}
+```
+
+## Examples
+
+```bash
+# Authenticate and verify the runtime is reachable
+symbi-cli auth login
+symbi-cli auth whoami
+
+# Agent lifecycle
+symbi-cli agent list
+symbi-cli agent create --file ./my-agent.json
+symbi-cli agent exec <agent-id> --input '{"text":"hello"}'
+
+# Development helpers
+symbi-cli dev watch ./agents/
+```
+
+## Programmatic use
+
+```typescript
+import { program } from 'symbi-cli';
+program.parse(['agent', 'list']);
+```
+
+Utilities from `symbi-cli/utils/*` — config loading, error handling, output formatting — are re-exportable for downstream tools.
+
+## See also
+
+- [`symbi`](https://crates.io/crates/symbi) — the Rust-native Symbiont runtime binary
+- [`symbi-core`](https://www.npmjs.com/package/symbi-core) — the programmatic client `symbi-cli` wraps
+- [SDK README](https://github.com/ThirdKeyAI/symbiont-sdk-js#readme)
+- [docs.symbiont.dev/getting-started](https://docs.symbiont.dev/getting-started) — full installation options
+
+## License
+
+Apache 2.0. See [LICENSE](../../LICENSE).

packages/core/README.md

@@ -0,0 +1,75 @@
+# symbi-core
+
+[![npm](https://img.shields.io/npm/v/symbi-core.svg)](https://www.npmjs.com/package/symbi-core)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](../../LICENSE)
+
+Main client for the [Symbiont JavaScript/TypeScript SDK](https://github.com/ThirdKeyAI/symbiont-sdk-js) — the official client for Symbiont, the policy-governed agent runtime.
+
+`symbi-core` exposes `SymbiontClient` plus standalone modules (webhook verification, markdown memory, skill scanning, metrics). Types are re-exported from [`symbi-types`](https://www.npmjs.com/package/symbi-types), so most projects only need this one install.
+
+## Install
+
+```bash
+npm install symbi-core
+```
+
+A running Symbiont runtime is required for client calls. The fastest way:
+
+```bash
+docker run --rm -p 8080:8080 -p 8081:8081 ghcr.io/thirdkeyai/symbi:latest up
+```
+
+## Quick start
+
+```typescript
+import { SymbiontClient } from 'symbi-core';
+
+const client = new SymbiontClient({
+  apiKey: process.env.SYMBIONT_API_KEY,
+  apiUrl: 'http://localhost:8080/api/v1',
+});
+
+await client.connect();
+
+const agents = await client.agents.listAgents();
+const result = await client.agents.executeAgent(agents[0].id, { text: 'Hello, Symbiont!' });
+console.log(result.result);
+```
+
+## What's exported
+
+| Export | Purpose |
+|--------|---------|
+| `SymbiontClient` | Unified client with namespaced sub-clients for every runtime surface (see SDK README) |
+| `AuthenticationManager`, `MemoryTokenCache` | Auth / token refresh |
+| `HmacVerifier`, `JwtVerifier`, `createProviderVerifier` | Inbound webhook signature verification (GitHub, Stripe, Slack, custom) |
+| `MarkdownMemoryStore` | File-based agent context that survives restarts |
+| `SkillScanner`, `SkillLoader` | ClawHavoc security scanning (10 built-in rules) + YAML frontmatter loading |
+| `MetricsApiClient`, `FileMetricsExporter`, `CompositeExporter`, `MetricsCollector` | Runtime metrics snapshots + periodic export |
+| `SystemClient`, `CommunicationClient`, `ToolCladClient`, `ReasoningClient` | Runtime sub-clients |
+| `HttpEndpointManager` | Dynamic HTTP endpoint management |
+
+All types and Zod schemas from `symbi-types` are re-exported for convenience.
+
+## Companion packages
+
+| Package | Purpose |
+|---------|---------|
+| [`symbi-types`](https://www.npmjs.com/package/symbi-types) | Types + Zod schemas |
+| [`symbi-agent`](https://www.npmjs.com/package/symbi-agent) | `AgentClient`, `ScheduleClient`, `ChannelClient`, `WorkflowClient`, `AgentPinClient` |
+| [`symbi-policy`](https://www.npmjs.com/package/symbi-policy) | Policy builder |
+| [`symbi-secrets`](https://www.npmjs.com/package/symbi-secrets) | Vault / file / env secret backends |
+| [`symbi-mcp`](https://www.npmjs.com/package/symbi-mcp) | MCP client |
+| [`symbi-tool-review`](https://www.npmjs.com/package/symbi-tool-review) | Tool review workflow |
+| [`symbi-testing`](https://www.npmjs.com/package/symbi-testing) | Mocks + test helpers |
+| [`symbi-cli`](https://www.npmjs.com/package/symbi-cli) | Command-line tooling |
+
+## See also
+
+- [SDK README](https://github.com/ThirdKeyAI/symbiont-sdk-js#readme) — full capabilities, examples, Trust Stack integration
+- [docs.symbiont.dev](https://docs.symbiont.dev) — runtime documentation
+- [Symbiont runtime](https://github.com/thirdkeyai/symbiont) — the Rust-native runtime this SDK talks to
+
+## License
+
+Apache 2.0. See [LICENSE](../../LICENSE).

packages/mcp/README.md

@@ -0,0 +1,41 @@
+# symbi-mcp
+
+[![npm](https://img.shields.io/npm/v/symbi-mcp.svg)](https://www.npmjs.com/package/symbi-mcp)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](../../LICENSE)
+
+MCP (Model Context Protocol) client for the [Symbiont JavaScript/TypeScript SDK](https://github.com/ThirdKeyAI/symbiont-sdk-js). Drives the Symbiont runtime's governed MCP integration — listing connected servers, invoking tools, and surfacing resources under runtime policy.
+
+Most users install [`symbi-core`](https://www.npmjs.com/package/symbi-core), which exposes this as `client.mcp`. Pull `symbi-mcp` directly when you want a narrow dependency.
+
+## Install
+
+```bash
+npm install symbi-mcp
+```
+
+## Usage
+
+```typescript
+import { McpClient } from 'symbi-mcp';
+
+const mcp = new McpClient(transport);
+
+const servers = await mcp.listServers();
+const tools = await mcp.listTools(servers[0].id);
+const resources = await mcp.listResources(servers[0].id);
+
+const result = await mcp.invokeTool(servers[0].id, 'search', { query: 'symbiont' });
+```
+
+Tool calls flow through the runtime's SchemaPin verification and Cedar policy gates — unverified or denied tools never execute.
+
+## See also
+
+- [`symbi-core`](https://www.npmjs.com/package/symbi-core) — exposes `client.mcp`
+- [SDK README](https://github.com/ThirdKeyAI/symbiont-sdk-js#readme)
+- [docs.symbiont.dev](https://docs.symbiont.dev) — runtime documentation
+- [SchemaPin](https://github.com/ThirdKeyAI/SchemaPin) — the tool-signature verification layer
+
+## License
+
+Apache 2.0. See [LICENSE](../../LICENSE).

packages/policy/README.md

@@ -0,0 +1,41 @@
+# symbi-policy
+
+[![npm](https://img.shields.io/npm/v/symbi-policy.svg)](https://www.npmjs.com/package/symbi-policy)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](../../LICENSE)
+
+Policy builder for the [Symbiont JavaScript/TypeScript SDK](https://github.com/ThirdKeyAI/symbiont-sdk-js). Constructs `Policy` objects that the Symbiont runtime evaluates via its built-in DSL and [Cedar](https://www.cedarpolicy.com/) authorization.
+
+Most users install [`symbi-core`](https://www.npmjs.com/package/symbi-core), which exposes a `policyBuilder` namespace on `SymbiontClient`. Pull this package directly when you want a narrow dependency for agents/services that only need to construct policies.
+
+## Install
+
+```bash
+npm install symbi-policy
+```
+
+## Usage
+
+```typescript
+import { PolicyBuilder, createPolicyBuilder } from 'symbi-policy';
+
+const policy = createPolicyBuilder()
+  .allow({ action: 'read', resource: 'documents' })
+  .deny({ action: 'write', resource: '*' })
+  .audit({ action: '*', resource: '*' })
+  .build();
+
+// Attach to an agent definition or register with the runtime:
+// await client.agents.createAgent({ name, description, policies: [policy], ... });
+```
+
+Fluent API supports `allow` / `deny` / `audit` effects, conditions (`when`, `unless`, timeboxed rules), priorities, and action/resource globbing.
+
+## See also
+
+- [`symbi-core`](https://www.npmjs.com/package/symbi-core) — exposes `client.policyBuilder`
+- [SDK README](https://github.com/ThirdKeyAI/symbiont-sdk-js#readme)
+- [docs.symbiont.dev/security-model](https://docs.symbiont.dev/security-model) — how Cedar policies flow through the runtime
+
+## License
+
+Apache 2.0. See [LICENSE](../../LICENSE).

packages/secrets/README.md

@@ -0,0 +1,57 @@
+# symbi-secrets
+
+[![npm](https://img.shields.io/npm/v/symbi-secrets.svg)](https://www.npmjs.com/package/symbi-secrets)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](../../LICENSE)
+
+Secret management for the [Symbiont JavaScript/TypeScript SDK](https://github.com/ThirdKeyAI/symbiont-sdk-js). Provides a pluggable `SecretManager` with HashiCorp Vault, encrypted-file, and environment-variable backends.
+
+Most users install [`symbi-core`](https://www.npmjs.com/package/symbi-core), which exposes secrets via `client.secrets`. Pull this package directly when you want a narrow dependency for services that only need secret resolution.
+
+## Install
+
+```bash
+npm install symbi-secrets
+```
+
+## Usage
+
+```typescript
+import {
+  SecretManager,
+  EnvironmentVariableProvider,
+  FileProvider,
+  VaultProvider,
+} from 'symbi-secrets';
+
+const manager = new SecretManager({
+  providers: [
+    new EnvironmentVariableProvider({ prefix: 'SYMBIONT_' }),
+    new FileProvider({ path: '/run/secrets/symbiont.json' }),
+    new VaultProvider({ endpoint: 'https://vault.internal', token: process.env.VAULT_TOKEN }),
+  ],
+});
+
+const apiKey = await manager.get('api-key');
+```
+
+The manager tries providers in order. Use it for database credentials, API keys, and signing keys that shouldn't live in config.
+
+## Providers
+
+| Provider | Backend |
+|----------|---------|
+| `EnvironmentVariableProvider` | `process.env` with optional prefix and mapping |
+| `FileProvider` | JSON / YAML / flat key-value files with optional AES-256-GCM encryption |
+| `VaultProvider` | HashiCorp Vault (Token, Kubernetes, AWS IAM, AppRole auth methods) |
+
+Implement the `SecretProvider` interface to add more.
+
+## See also
+
+- [`symbi-core`](https://www.npmjs.com/package/symbi-core) — exposes `client.secrets`
+- [SDK README](https://github.com/ThirdKeyAI/symbiont-sdk-js#readme)
+- [docs.symbiont.dev/security-model](https://docs.symbiont.dev/security-model)
+
+## License
+
+Apache 2.0. See [LICENSE](../../LICENSE).