beddel 0.1.0 → 0.2.0

package/README.md

@@ -1,297 +1,551 @@
-# Beddel: Secure, Declarative, and Extensible Agent Runtimes
+# Beddel
+
+**Secure, Declarative, and Extensible Agent Runtime**
 
 [![NPM Version](https://img.shields.io/npm/v/beddel.svg)](https://www.npmjs.com/package/beddel)
 [![License](https://img.shields.io/npm/l/beddel.svg)](https://github.com/botanarede/beddel-alpha/blob/main/LICENSE)
 
-**Repos:** código-fonte em `https://github.com/botanarede/beddel-alpha` e app de exemplo Next.js em `https://github.com/botanarede/beddel-alpha-example`.
-
-## Usage Exemplo
+Beddel is a security-first toolkit for building and running declarative YAML agents with enterprise-grade isolation, automatic schema validation, and extensible architecture.
 
-> Declaração YAML + interpretação segura para que quem visita o perfil do pacote no npm entenda o fluxo em poucos segundos.
+## Quick Start
 
 ```yaml
-# joker-agent.yaml
+# agents/my-agent.yaml
 agent:
-  id: joker
+  id: my-agent
+  version: 1.0.0
   protocol: beddel-declarative-protocol/v2.0
+
 metadata:
-  name: Joker Agent
+  name: "My Custom Agent"
+  description: "A simple custom agent"
+  route: "/agents/my-agent"
+
 schema:
   input:
     type: "object"
-    properties: {}
-    required: []
+    properties:
+      message:
+        type: "string"
+    required: ["message"]
   output:
     type: "object"
     properties:
       response:
         type: "string"
     required: ["response"]
+
 logic:
   workflow:
-    - name: generate-joke
-      type: genkit-joke
+    - name: "process"
+      type: "genkit-joke"
       action:
-        type: joke
-        prompt: "Conte uma piada curta e original que funcione para qualquer público."
-        result: jokerResult
+        type: "joke"
+        prompt: "{{message}}"
+        result: "result"
 
-    - name: deliver-response
-      type: output-generator
-      action:
-        type: generate
-        output:
-          response: "$jokerResult.texto"
+output:
+  schema:
+    response: "$result.texto"
 ```
 
 ```typescript
-import {
-  SecureYamlParser,
-  DeclarativeAgentInterpreter,
-  SecureYamlRuntime,
-  IsolatedRuntimeManager,
-  type ExecutionContext,
-} from "beddel";
-import { readFileSync } from "node:fs";
-
-const yamlManifest = readFileSync("joker-agent.yaml", "utf8");
-
-const parser = new SecureYamlParser({ filename: "joker-agent.yaml" });
-const manifest = parser.parseSecure(yamlManifest); // FAILSAFE_SCHEMA + depth/size limits
-
-const context: ExecutionContext = {
-  logs: [],
-  status: "running",
-  output: null,
-  log: console.log,
-  setOutput: (output) => (context.output = output),
-  setError: (err) => console.error(err),
-};
+import { agentRegistry } from "beddel";
+
+// Execute the agent
+const result = await agentRegistry.executeAgent(
+  "my-agent.execute",
+  { message: "Hello world" },
+  { gemini_api_key: process.env.GEMINI_API_KEY },
+  context
+);
+```
 
-const interpreter = new DeclarativeAgentInterpreter();
-const agentResult = await interpreter.interpret({
-  yamlContent: yamlManifest,
-  input: {},
-  props: {
-    gemini_api_key: process.env.GEMINI_API_KEY ?? "",
-  },
-  context,
-});
+## Installation
 
-const secureRuntime = new SecureYamlRuntime(new IsolatedRuntimeManager());
-const execution = await secureRuntime.parseYamlSecureRuntime(yamlManifest, {
-  tenantId: "tenant-42",
-  securityProfile: "tenant-isolated",
-  validateSecurity: true,
-});
+```bash
+npm install beddel
 ```
 
-- `SecureYamlParser` garante o parsing estritamente FAILSAFE com validação de profundidade, tamanho e UTF-8.
-- `DeclarativeAgentInterpreter` executa apenas steps declarativos (`output-generator`, `genkit-joke`, `genkit-translation`, `genkit-image`) e mantém toda a validação em Zod (sem `eval`/`Function`).
-- `SecureYamlRuntime` conecta parser, scanner e `isolated-vm` para entregar auditoria, limites de tempo/memória e perfis multi-tenant.
+Requires Node.js 18+.
+
+---
+
+## Architecture Overview
 
-Beddel is a security-first toolkit that combines:
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                         Beddel Runtime                              │
+│                                                                     │
+│  ┌──────────────────────────────────────────────────────────────┐  │
+│  │                    Agent Registry                             │  │
+│  │                                                               │  │
+│  │  ┌─────────────────┐    ┌────────────────────────────────┐   │  │
+│  │  │  Built-in       │    │  Custom Agents                 │   │  │
+│  │  │  Agents         │    │  /agents/*.yaml                │   │  │
+│  │  │                 │    │                                │   │  │
+│  │  │ • joker         │    │  Automatically discovered      │   │  │
+│  │  │ • translator    │    │  and registered at startup     │   │  │
+│  │  │ • image         │    │                                │   │  │
+│  │  └─────────────────┘    └────────────────────────────────┘   │  │
+│  │                                                               │  │
+│  │         Priority: Custom Agents > Built-in Agents            │  │
+│  └──────────────────────────────────────────────────────────────┘  │
+│                                │                                    │
+│                                ▼                                    │
+│  ┌──────────────────────────────────────────────────────────────┐  │
+│  │              Declarative Agent Interpreter                    │  │
+│  │                                                               │  │
+│  │   • YAML Parsing (FAILSAFE schema)                           │  │
+│  │   • Schema Validation (Zod)                                  │  │
+│  │   • Workflow Execution                                       │  │
+│  │   • Genkit Integration (Gemini Flash)                        │  │
+│  └──────────────────────────────────────────────────────────────┘  │
+│                                │                                    │
+│                                ▼                                    │
+│  ┌──────────────────────────────────────────────────────────────┐  │
+│  │               Secure Runtime (isolated-vm)                    │  │
+│  │                                                               │  │
+│  │   • Memory limits         • V8 isolate                       │  │
+│  │   • Execution timeouts    • No Node.js access                │  │
+│  │   • Audit logging         • Multi-tenant isolation           │  │
+│  └──────────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────────┘
+```
 
-- A hardened YAML parser that only exposes the YAML FAILSAFE schema.
-- Multiple execution strategies powered by `isolated-vm`.
-- Declarative agent utilities, compliance helpers, performance monitors, and Firebase multi-tenant orchestration.
+---
 
-### Declarative agents shipped with Gemini Flash helpers
+## Custom Agents
 
-The declarative runtime now exposes three Genkit-based helpers—`callGeminiFlashText`, `callGeminiFlashTranslation`, and `callGeminiFlashImage`—which proxy `generateText`/`generateImage` calls to `google("models/gemini-flash-latest")`. Each helper validates the presence of `props.gemini_api_key`, builds friendly prompts, and returns consistent metadata (`modelo_utilizado`, `tempo_processamento`, etc.).
+Beddel supports custom agents that you define in your application's `/agents` directory. Custom agents are automatically discovered and registered at startup.
 
-| Agent | Method | Description | Inputs | Outputs | Required props |
-| --- | --- | --- | --- | --- | --- |
-| Joker Agent | `joker.execute` | Gera uma piada curta e original usando Gemini Flash. | — | `response` | `gemini_api_key` |
-| Translator Agent | `translator.execute` | Traduz textos via Gemini Flash com Genkit. | `texto`, `idioma_origem`, `idioma_destino` | `texto_traduzido`, `metadados` | `gemini_api_key` |
-| Image Generator Agent | `image.generate` | Cria imagens nos estilos `watercolor`, `neon` ou `sketch`. | `descricao`, `estilo`, `resolucao` | `image_url`, `image_base64`, `media_type`, `prompt_utilizado`, `metadados` | `gemini_api_key` |
+### Directory Structure
 
-> ⚠️ Todos os agentes embutidos dependem da prop `gemini_api_key`. Sem ela o runtime aborta a execução com uma mensagem amigável.
+```
+your-app/
+├── agents/                          # Custom agents directory
+│   ├── my-agent.yaml                # Simple YAML-only agent
+│   ├── my-chat.yaml                 # Agent with TypeScript code-behind
+│   ├── my-chat.ts                   # TypeScript implementation  
+│   ├── calculator/
+│   │   └── calculator.yaml          # Agent in subdirectory
+│   └── translator-custom/
+│       └── translator-custom.yaml   # Override built-in
+│
+└── packages/beddel/src/agents/      # Built-in agents (package)
+    ├── joker-agent.yaml
+    ├── translator-agent.yaml
+    └── image-agent.yaml
+```
 
-The code that backs this README lives under `packages/beddel/src` and is what the npm package exposes.
+### Agent Loading Flow
 
-## Package map
+```
+┌─────────────────────────────────────────────────────────────┐
+│                  Agent Loading Sequence                      │
+│                                                              │
+│  1. AgentRegistry constructor()                              │
+│     │                                                        │
+│     ├──▶ 2. registerBuiltinAgents()                         │
+│     │       ├── joker.execute                                │
+│     │       ├── translator.execute                           │
+│     │       └── image.generate                               │
+│     │                                                        │
+│     └──▶ 3. loadCustomAgents()                              │
+│             │                                                │
+│             ├── Recursively scans /agents/**/*.yaml         │
+│             │   └── Registers each agent                     │
+│             │       └── Custom agents override built-ins     │
+│             │                                                │
+│             └── Scans /agents/**/*.ts                        │
+│                 └── Dynamically imports TypeScript modules   │
+│                     └── Registers exported functions         │
+│                                                              │
+│  Priority: Custom Agents > Built-in Agents                   │
+└─────────────────────────────────────────────────────────────┘
+```
 
-| Capability | Entry point / module | Notes |
-| --- | --- | --- |
-| Secure YAML parsing | `SecureYamlParser` (`src/parser/secure-yaml-parser.ts`) | FAILSAFE schema, depth/size limits, UTF-8 validation, sync + async helpers. |
-| Sandboxed execution | `IsolatedRuntimeManager`, `SimpleIsolatedRuntimeManager` (`src/runtime`) | Uses `isolated-vm` with configurable security profiles, pool management, metrics. |
-| Declarative YAML interpretation | `DeclarativeAgentInterpreter`, `AgentRegistry` (`src/runtime/declarativeAgentRuntime.ts`, `src/agents/agentRegistry.ts`) | Executes YAML agents with variables plus `output-generator`, `genkit-joke`, `genkit-translation` e `genkit-image` steps (Gemini Flash). |
-| Security posture | `SecurityScanner`, `ThreatDetectionEngine`, validation utilities (`src/security`) | Static scanning, scoring, and threat inference the rest of the package consumes. |
-| Compliance & audit | `GDPRCompliance`, `LGPDCompliance`, `AuditTrail`, `AuditService` (`src/compliance`, `src/audit`, `src/runtime/audit.ts`) | Hash-based logging, anonymization helpers, compliance verification. |
-| Performance & autoscaling | `PerformanceMonitor`, `AutoScaler`, benchmarking helpers (`src/performance`) | Track execution time/memory, raise violations, recommend scaling actions. |
-| Firebase multi-tenancy | `MultiTenantFirebaseManager` (`src/firebase/tenantManager.ts`) | Per-tenant app bootstrap, isolation policies, audit logging hooks. |
+### Creating a Custom Agent
 
-Everything is re-exported via `src/index.ts`, so you can import from `beddel` directly.
+1. **Create the YAML file** in `/agents`:
 
-## Installation
+```yaml
+# agents/greeting.yaml
+agent:
+  id: greeting
+  version: 1.0.0
+  protocol: beddel-declarative-protocol/v2.0
 
-```bash
-npm install beddel
+metadata:
+  name: "Greeting Agent"
+  description: "Generates personalized greetings"
+  category: "utility"
+  route: "/agents/greeting"
+
+schema:
+  input:
+    type: "object"
+    properties:
+      name:
+        type: "string"
+        minLength: 1
+        maxLength: 100
+    required: ["name"]
+
+  output:
+    type: "object"
+    properties:
+      greeting:
+        type: "string"
+    required: ["greeting"]
+
+logic:
+  workflow:
+    - name: "generate-greeting"
+      type: "genkit-joke"
+      action:
+        type: "joke"
+        prompt: "Create a warm, friendly greeting for {{name}}"
+        result: "greetingResult"
+
+output:
+  schema:
+    greeting: "$greetingResult.texto"
 ```
 
-Ensure Node.js 18+ (per `package.json`) and install optional peer dependencies you plan to use (e.g., `firebase-admin` is already included).
+2. **The agent is automatically registered** when your application starts.
 
-## Project-agnostic guarantees
+3. **Execute via GraphQL or directly**:
 
-- No upstream app files are required—the npm tarball only ships `dist/` and the audited TypeScript sources exported through `beddel`.
-- `ExecutionContext` and every runtime type live inside the package, de-coupling consumers from any upstream monorepo or example app internals.
-- No secrets, API tokens, or environment-specific constants are embedded in the code or build output; everything is configured via your own runtime props.
-- Optional tools (Firebase, Upstash, benchmarking scripts) are defensive helpers; you decide which ones to instantiate depending on project size.
+```graphql
+mutation {
+  executeMethod(
+    methodName: "greeting.execute"
+    params: { name: "Alice" }
+    props: { gemini_api_key: "your-api-key" }
+  ) {
+    success
+    data
+  }
+}
+```
+
+### Custom Agents with TypeScript Code-Behind
 
-## Usage examples
+For more complex logic, create custom agents with TypeScript implementations:
 
-### Parse YAML with strict fail-safes
+#### 1. Create the TypeScript implementation:
 
 ```typescript
-import { SecureYamlParser } from "beddel";
+// agents/my-chat.ts
+export const chatHandler = async ({ input, variables, context }) => {
+  // Full TypeScript power available here
+  context.log("Processing chat message with custom TypeScript logic");
+  
+  const message = input.message || "";
+  const history = input.messages || [];
+  
+  // Add user message to history
+  history.push({ role: "user", content: message });
+  
+  // Your custom logic here - call external APIs, use Beddel helpers, etc.
+  const response = `Processed: "${message}"`;
+  
+  history.push({ role: "assistant", content: response });
+  
+  return { 
+    response,
+    history,
+    timestamp: new Date().toISOString()
+  };
+};
+```
 
-const parser = new SecureYamlParser({
-  maxDepth: 200,
-  filename: "agent-manifest",
-});
+#### 2. Create the YAML configuration:
 
-const manifest = parser.parseSecure(`
+```yaml
+# agents/my-chat.yaml
 agent:
-  id: joker
+  id: my-chat
+  version: 1.0.0
+  protocol: beddel-declarative-protocol/v2.0
+
+metadata:
+  name: "Custom Chat Agent"
+  description: "Chat agent with TypeScript code-behind"
+  route: "/agents/my-chat"
+
 schema:
-  input: {}
-  output: {}
+  input:
+    type: "object"
+    properties:
+      message:
+        type: "string"
+        minLength: 1
+    required: ["message"]
+
+  output:
+    type: "object"
+    properties:
+      response:
+        type: "string"
+    required: ["response"]
+
 logic:
   workflow:
-    - name: noop
-      type: output-generator
+    - name: process
+      type: custom-action
       action:
-        type: generate
-        output:
-          response: "lol"
-`);
+        function: "my-chat/chatHandler"  # Format: filename/exportedFunctionName
+        result: response
 
-console.log(manifest.agent.id); // joker
+output:
+  schema:
+    response: "$response.response"
 ```
 
-Behind the scenes, `SecureYamlParser` enforces depth, size, UTF-8, and allowed primitive types before returning the parsed object.
+#### 3. Function Arguments
 
-### Execute JavaScript in an isolate
+Custom functions receive a standardized arguments object:
 
 ```typescript
-import { IsolatedRuntimeManager } from "beddel";
+{
+  input: Record<string, any>,      // Validated input from the request
+  variables: Record<string, any>,  // Current workflow variables
+  action: Record<string, any>,     // Action configuration from YAML
+  context: ExecutionContext        // Logging and error handling
+}
+```
 
-const runtimeManager = new IsolatedRuntimeManager();
+### Overriding Built-in Agents
 
-const result = await runtimeManager.execute({
-  code: `
-    const secret = "sandboxed";
-    ({ success: true, value: secret.length });
-  `,
-  securityProfile: "ultra-secure",
-  timeout: 2000,
-});
+Create a custom agent with the same route to override a built-in:
 
-if (!result.success) {
-  throw result.error;
-}
+```yaml
+# agents/joker-custom.yaml
+agent:
+  id: joker
+  protocol: beddel-declarative-protocol/v2.0
 
-console.log(result.result); // { success: true, value: 9 }
+metadata:
+  route: "/agents/joker"  # Same route overrides built-in
+  # ... your custom implementation
 ```
 
-The manager bootstraps `isolated-vm` contexts, strips dangerous globals (`require`, `eval`, timers), enforces memory/time limits, records metrics, and can emit audit/security signals.
+---
+
+## Built-in Agents
 
-### Interpret a declarative YAML agent
+| Agent | Method | Description | Required Props |
+|-------|--------|-------------|----------------|
+| **Joker** | `joker.execute` | Generates short, original jokes | `gemini_api_key` |
+| **Translator** | `translator.execute` | Translates text between languages | `gemini_api_key` |
+| **Image Generator** | `image.generate` | Creates images (watercolor, neon, sketch) | `gemini_api_key` |
+
+### Joker Agent
 
 ```typescript
-import { DeclarativeAgentInterpreter } from "beddel";
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
-
-const interpreter = new DeclarativeAgentInterpreter();
-const yamlContent = readFileSync(join(process.cwd(), "joker-agent.yaml"), "utf8");
-
-const result = await interpreter.interpret({
-  yamlContent,
-  input: {},
-  props: {},
-  context: {
-    log: console.log,
-    setError: console.error,
+const result = await agentRegistry.executeAgent(
+  "joker.execute",
+  {},
+  { gemini_api_key: "..." },
+  context
+);
+// Returns: { response: "Why did the..." }
+```
+
+### Translator Agent
+
+```typescript
+const result = await agentRegistry.executeAgent(
+  "translator.execute",
+  {
+    texto: "Hello, world!",
+    idioma_origem: "en",
+    idioma_destino: "pt"
   },
-});
+  { gemini_api_key: "..." },
+  context
+);
+// Returns: { texto_traduzido: "Olá, mundo!", metadados: {...} }
+```
+
+### Image Generator Agent
 
-console.log(result.response); // lol
+```typescript
+const result = await agentRegistry.executeAgent(
+  "image.generate",
+  {
+    descricao: "A sunset over mountains",
+    estilo: "watercolor",
+    resolucao: "1024x1024"
+  },
+  { gemini_api_key: "..." },
+  context
+);
+// Returns: { image_url, image_base64, media_type, ... }
 ```
 
-Current interpreter capabilities:
+---
 
-- Validates protocol (`beddel-declarative-protocol/v2.0`), schema presence, workflow size.
-- Supports string/number/boolean/object variables and literal/variable references.
-- Executes `output-generator` workflow steps that map variables to response objects.
+## Core Components
 
-For projects that want auto-registration, instantiate `AgentRegistry` (bundled with the `joker` agent) and call `executeAgent("joker.execute", …)`.
+### Package Map
 
-### Automatic schema validation
+| Capability | Module | Description |
+|------------|--------|-------------|
+| **YAML Parsing** | `SecureYamlParser` | FAILSAFE schema, depth/size limits, UTF-8 validation |
+| **Sandboxed Execution** | `IsolatedRuntimeManager` | `isolated-vm` with security profiles |
+| **Agent Interpretation** | `DeclarativeAgentInterpreter` | Executes YAML agents with Genkit |
+| **Agent Registry** | `AgentRegistry` | Manages built-in and custom agents |
+| **Security** | `SecurityScanner`, `ThreatDetectionEngine` | Static scanning, scoring |
+| **Compliance** | `GDPRCompliance`, `LGPDCompliance` | Audit, anonymization |
+| **Performance** | `PerformanceMonitor`, `AutoScaler` | Metrics, scaling |
+| **Multi-tenancy** | `MultiTenantFirebaseManager` | Firebase tenant isolation |
 
-Every declarative agent must now declare `schema.input` and `schema.output` blocks that map directly to Zod primitives (`string`, `number`, `boolean`), objects (with `properties` + `required` arrays), and arrays (via `items`). The runtime compiles those YAML definitions into Zod schemas through the `DeclarativeSchemaCompiler`, caches the result per manifest, and runs validation twice per execution:
+### Secure YAML Parsing
 
-- **Before workflow execution** – payloads that are missing required fields, contain unexpected properties (objects are `strict` by default), or provide the wrong primitive types raise a `DeclarativeSchemaValidationError` and call `ExecutionContext.setError`.
-- **Before returning output** – the workflow result must match `schema.output`; mismatches are rejected, the error propagates through the same structured exception, and oversize payloads (>1 MB) are blocked.
+```typescript
+import { SecureYamlParser } from "beddel";
 
-Authors can opt into arrays by adding `type: "array"` + an `items` definition, mark optional fields by omitting them from `required`, and set `additionalProperties: true` only when extra keys should be allowed. Errors surface in GraphQL responses (and logs) as `Input validation failed: …` or `Output validation failed: …`, making it obvious which path failed.
+const parser = new SecureYamlParser({
+  maxDepth: 200,
+  filename: "agent-manifest",
+});
 
-### Parse + execute inside the secure runtime
+const manifest = parser.parseSecure(yamlContent);
+```
 
-Combine the parser, security scanner, and isolate manager through `SecureYamlRuntime`:
+### Sandboxed Execution
 
 ```typescript
-import { SecureYamlRuntime, IsolatedRuntimeManager } from "beddel";
+import { IsolatedRuntimeManager } from "beddel";
+
+const runtime = new IsolatedRuntimeManager();
 
-const runtime = new SecureYamlRuntime(new IsolatedRuntimeManager());
-const { success, result } = await runtime.parseYamlSecureRuntime(someYamlString, {
-  tenantId: "tenant-123",
-  securityProfile: "tenant-isolated",
-  validateSecurity: true,
+const result = await runtime.execute({
+  code: `({ value: 42 })`,
+  securityProfile: "ultra-secure",
+  timeout: 2000,
 });
 ```
 
-The helper performs pre-scan checks, runs within the requested profile, enforces performance targets, and produces audit hashes you can persist.
+### Agent Registry API
 
-## Architectural reference
+```typescript
+import { agentRegistry } from "beddel";
 
-- `src/parser`: Secure YAML parsing primitives.
-- `src/runtime`: `IsolatedRuntimeManager`, `SimpleIsolatedRuntimeManager`, auditing utilities, declarative interpreter, monitoring, and security hooks.
-- `src/security`: Validation, scoring, threat detection, dashboards.
-- `src/compliance`: GDPR/LGPD tooling, anonymization, export helpers.
-- `src/performance`: Monitoring, autoscaling, streaming metrics.
-- `src/firebase`: Tenant isolation via Firebase Admin SDK.
-- `src/agents`: Registry helpers and sample `joker-agent.yaml`.
-- `src/integration`: Glue code that wires parsing + runtime + scanner.
+// Get all registered agents
+const agents = agentRegistry.getAllAgents();
 
-Every module is documented inline with TypeScript types to make IDE discovery straightforward.
+// Get a specific agent
+const agent = agentRegistry.getAgent("joker.execute");
 
-## Development workflow
+// Execute an agent
+const result = await agentRegistry.executeAgent(
+  "joker.execute",
+  input,
+  props,
+  context
+);
 
-```bash
-# Build the package
-pnpm --filter beddel build
+// Load custom agents from a specific path
+agentRegistry.loadCustomAgents("/path/to/custom/agents");
+```
 
-# Lint and test
-pnpm --filter beddel lint
-pnpm --filter beddel test
+---
+
+## Schema Validation
+
+All agents must declare `schema.input` and `schema.output` blocks. The runtime compiles these into Zod schemas and validates:
+
+- **Before execution**: Input must match `schema.input`
+- **After execution**: Output must match `schema.output`
+
+```yaml
+schema:
+  input:
+    type: "object"
+    properties:
+      name:
+        type: "string"
+        minLength: 1
+        maxLength: 100
+      age:
+        type: "number"
+    required: ["name"]
+
+  output:
+    type: "object"
+    properties:
+      greeting:
+        type: "string"
+    required: ["greeting"]
+```
+
+Supported types: `string`, `number`, `boolean`, `object`, `array`
+
+---
+
+## Security
+
+### Multi-Layer Security Model
+
+1. **Parser Layer**: FAILSAFE schema, size limits, sanitization
+2. **Runtime Layer**: V8 isolate, memory limits, timeouts
+3. **Application Layer**: Authentication, rate limiting, tenant isolation
+
+### Security Profiles
+
+```typescript
+const result = await runtime.execute({
+  code: userCode,
+  securityProfile: "tenant-isolated", // ultra-secure | tenant-isolated
+  timeout: 5000,
+  memoryLimit: 128,
+});
 ```
 
-When contributing, keep README + `AGENTS.md` synchronized with any new exports or behavioral changes in `src`.
+---
 
-## Docs/beddel roadmap coverage
+## Project Structure
 
-The product briefs under `docs/beddel` describe a richer future-state language/runtime. The current package intentionally ships a smaller, auditable subset. Notable gaps you will still find only in documentation:
+```
+src/
+├── agents/                  # Agent registry and built-in agents
+│   ├── agentRegistry.ts     # Agent management
+│   ├── joker-agent.yaml     # Built-in: Joker
+│   ├── translator-agent.yaml
+│   └── image-agent.yaml
+├── parser/                  # Secure YAML parsing
+├── runtime/                 # Execution environments
+│   ├── isolatedRuntime.ts
+│   ├── declarativeAgentRuntime.ts
+│   └── schemaCompiler.ts
+├── security/                # Scanning and threat detection
+├── compliance/              # GDPR/LGPD utilities
+├── performance/             # Monitoring and autoscaling
+├── firebase/                # Multi-tenant management
+└── index.ts                 # Public exports
+```
 
-- **Advanced declarative language constructs** (`map-filter-reduce` pipelines, state machines, rule engines, temporal conditions, and loop semantics) are not implemented yet—the interpreter only supports literal variables and `output-generator` steps.
-- **Behavior marketplace & registry extensibility** (behaviors with versions, capabilities, restrictions, and monetization hooks) are not available. Only the bundled `joker` agent is registered by default.
-- **Automatic behavioral integrations and external API pipelines** (`integrations`, `decisions`, `behaviors` blocks described in `docs/beddel/brief.md`) have no runtime support.
-- **Marketplace/compliance automation flows** mentioned in the PRD (pre-built business behaviors, Firebase deployment recipes, global consent orchestration) are still roadmap items, even though compliance helpers exist as standalone utilities.
-- **High-level orchestration features** like parallel execution controls, resource policies (per-step concurrency, retry semantics), and auto-generated documentation have not been wired into the runtime.
+---
+
+## Development
+
+```bash
+# Build
+pnpm --filter beddel build
+
+# Test
+pnpm --filter beddel test
+
+# Lint
+pnpm --filter beddel lint
+```
 
-Use this section as a living checklist whenever you pull features from `docs/beddel` into the actual codebase.
+---
 
 ## License
 
-This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+MIT License. See [LICENSE](LICENSE) for details.