openryoko 0.9.4-ryoko.2

package/template/docs/architecture.md

@@ -0,0 +1,74 @@
+# Architecture
+
+{{portalName}} runs as a single Node.js process acting as a gateway between external connectors and AI engines.
+
+## Components
+
+```
+┌─────────────────────────────────────────────────┐
+│              {{portalName}} Gateway                │
+│                                                  │
+│  ┌───────────┐  ┌────────────┐  ┌────────────┐  │
+│  │ HTTP Server│  │ WebSocket  │  │   Cron     │  │
+│  │ REST + UI  │  │  Server    │  │ Scheduler  │  │
+│  └─────┬─────┘  └─────┬──────┘  └─────┬──────┘  │
+│        │               │               │         │
+│  ┌─────┴───────────────┴───────────────┴──────┐  │
+│  │            Session Manager                  │  │
+│  │  Routes messages, manages engine lifecycle  │  │
+│  └─────────────────┬──────────────────────────┘  │
+│                    │                              │
+│  ┌─────────────────┴──────────────────────────┐  │
+│  │           Engine Abstraction                │  │
+│  │  ┌──────────────┐  ┌───────────────────┐   │  │
+│  │  │ Claude Engine │  │   Codex Engine    │   │  │
+│  │  │ (spawns CLI)  │  │   (uses SDK)      │   │  │
+│  │  └──────────────┘  └───────────────────┘   │  │
+│  └────────────────────────────────────────────┘  │
+│                                                  │
+│  ┌────────────┐  ┌────────────┐  ┌───────────┐  │
+│  │ Connector  │  │   File     │  │  SQLite   │  │
+│  │  System    │  │  Watcher   │  │  Registry │  │
+│  └────────────┘  └────────────┘  └───────────┘  │
+└─────────────────────────────────────────────────┘
+```
+
+### HTTP Server
+REST API for session management, configuration, and health checks. Also serves the static web UI.
+
+### WebSocket Server
+Pushes live events (session updates, engine output, cron results) to connected clients.
+
+### Session Manager
+Central router. Receives messages from connectors, resolves the target employee and engine, creates or reuses sessions, and delivers responses back through the originating connector.
+
+### Engine Abstraction
+Uniform interface over different AI backends:
+- **Claude Engine**: Spawns `claude` CLI as a child process with `--resume` for session continuity
+- **Codex Engine**: Uses the Codex SDK directly in-process
+
+### Connector System
+Modular adapters that implement a standard interface. Each connector translates between its platform's message format and {{portalName}}'s internal message format. See `connectors.md`.
+
+### Cron Scheduler
+Uses `node-cron` to run scheduled AI jobs. Watches `cron/jobs.json` for hot-reload. See `cron.md`.
+
+### File Watcher
+Uses `chokidar` to watch `~/.jinn/` for changes and trigger appropriate reloads:
+- `config.yaml` changes → reload gateway configuration
+- `cron/jobs.json` changes → reschedule cron jobs
+- `org/` changes → rebuild employee registry
+
+### SQLite Session Registry
+Stores session metadata (id, engine, employee, connector source, timestamps) in `jinn.db`.
+
+## Data Flow
+
+1. Connector receives an external message (e.g., Slack message)
+2. Connector normalizes the message and calls session manager
+3. Session manager resolves the target employee and engine
+4. Session manager creates or reuses a session for the source reference
+5. Engine processes the message (Claude CLI or Codex SDK)
+6. Engine streams or returns the result
+7. Session manager delivers the result back through the originating connector
+8. WebSocket server broadcasts the event to any connected web UI clients

package/template/docs/connectors.md

@@ -0,0 +1,72 @@
+# Connectors
+
+Connectors are modular adapters that bridge external messaging platforms with {{portalName}}'s session manager.
+
+## Connector Interface
+
+```typescript
+interface Connector {
+  name: string;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  sendMessage(sourceRef: string, text: string): Promise<void>;
+  addReaction(sourceRef: string, emoji: string): Promise<void>;
+  removeReaction(sourceRef: string, emoji: string): Promise<void>;
+  editMessage(sourceRef: string, text: string): Promise<void>;
+  onMessage(handler: (msg: IncomingMessage) => void): void;
+}
+
+interface IncomingMessage {
+  sourceRef: string;     // Unique identifier for routing
+  text: string;          // Message content
+  userId: string;        // Platform user ID
+  userName: string;      // Display name
+  connector: string;     // Connector name
+}
+```
+
+## Slack Connector
+
+Uses `@slack/bolt` with Socket Mode (no public URL required).
+
+### Configuration
+
+```yaml
+connectors:
+  slack:
+    appToken: xapp-...    # Socket Mode app token
+    botToken: xoxb-...    # Bot user OAuth token
+```
+
+### Thread Mapping
+
+Slack messages are mapped to sessions based on conversation context:
+
+| Slack Context | Source Ref Format | Session Behavior |
+|---|---|---|
+| Direct message | `slack:dm:<userId>` | One session per DM user |
+| Channel root message | `slack:<channelId>` | One session per channel |
+| Thread reply | `slack:<channelId>:<threadTs>` | One session per thread |
+
+### Reaction Workflow
+
+Reactions provide visual feedback during processing:
+
+1. Message received → add :eyes: reaction (acknowledged)
+2. Engine processing...
+3. On success → remove :eyes:, add :white_check_mark:
+4. On error → remove :eyes:, add :x:
+
+### Employee Routing
+
+- Default: messages route to the default employee ({{portalName}})
+- `@mention`: messages mentioning a specific employee name route to that employee
+- Thread continuity: replies in a thread continue with the same employee
+
+## Future Connectors
+
+The connector interface is designed for additional platforms:
+- **Discord**: Bot integration via discord.js
+- **iMessage**: macOS-only via AppleScript bridge
+- **Web UI**: Built-in, served by the HTTP server
+- **CLI**: Direct terminal input/output

package/template/docs/cron.md

@@ -0,0 +1,137 @@
+# Cron
+
+{{portalName}} supports scheduled AI jobs defined in `~/.jinn/cron/jobs.json`.
+
+## Job Schema
+
+```typescript
+interface CronJob {
+  id: string;            // Unique identifier
+  name: string;          // Human-readable name
+  enabled: boolean;      // Whether the job is active
+  schedule: string;      // Cron expression (standard 5-field)
+  timezone?: string;     // IANA timezone (default: system timezone)
+  engine: string;        // "claude" or "codex"
+  model?: string;        // Override default model
+  employee?: string;     // Employee persona to use
+  prompt: string;        // The prompt to send to the engine
+  delivery?: {           // Optional output delivery
+    connector: string;   // Connector name (e.g., "slack")
+    channel: string;     // Target channel or user
+  };
+}
+```
+
+## Schedule Format
+
+Standard 5-field cron expressions:
+
+```
+┌────────── minute (0-59)
+│ ┌──────── hour (0-23)
+│ │ ┌────── day of month (1-31)
+│ │ │ ┌──── month (1-12)
+│ │ │ │ ┌── day of week (0-7, 0 and 7 = Sunday)
+│ │ │ │ │
+* * * * *
+```
+
+Examples:
+- `0 9 * * 1-5` — 9:00 AM, Monday through Friday
+- `*/30 * * * *` — Every 30 minutes
+- `0 0 1 * *` — Midnight on the 1st of each month
+
+## Hot Reload
+
+The gateway watches `cron/jobs.json` with chokidar. When the file changes:
+1. All existing scheduled jobs are cancelled
+2. The new file is parsed and validated
+3. Enabled jobs are rescheduled with the updated definitions
+
+No restart required. Engines can edit `jobs.json` directly to create or modify scheduled jobs.
+
+## Run Logs
+
+Each job execution is logged to `~/.jinn/cron/runs/<jobId>.jsonl`. Each line is a JSON object:
+
+```json
+{
+  "runId": "run_abc123",
+  "jobId": "daily-standup",
+  "startedAt": "2026-01-15T09:00:00.000Z",
+  "completedAt": "2026-01-15T09:00:45.000Z",
+  "status": "success",
+  "output": "..."
+}
+```
+
+## Delegation Pattern
+
+When a cron job produces analytical, reporting, or decision-informing output, it should **always target {{portalSlug}}** (the COO), not the employee directly. {{portalName}} then delegates to the employee via a child session, reviews the output, filters noise, and delivers the final result.
+
+**Correct** — cron → {{portalSlug}} → employee (via child session) → {{portalSlug}} reviews → delivery:
+```json
+{
+  "id": "daily-pulse",
+  "name": "Daily Pulse Analytics",
+  "enabled": true,
+  "schedule": "0 8 * * *",
+  "engine": "claude",
+  "employee": "{{portalSlug}}",
+  "prompt": "Delegate to @pulse: pull analytics for all products. Review the output, filter noise, and deliver a concise summary of what matters.",
+  "delivery": {
+    "connector": "slack",
+    "channel": "#analytics"
+  }
+}
+```
+
+**Incorrect** — cron → employee → delivery (bypasses COO review):
+```json
+{
+  "id": "daily-pulse",
+  "name": "Daily Pulse Analytics",
+  "enabled": true,
+  "schedule": "0 8 * * *",
+  "engine": "claude",
+  "employee": "pulse",
+  "prompt": "Pull analytics for all products and summarize.",
+  "delivery": {
+    "connector": "slack",
+    "channel": "#analytics"
+  }
+}
+```
+
+Direct employee-to-user delivery is only acceptable for simple, no-review-needed tasks (e.g. a health check ping). The gateway will log a warning if it detects a non-{{portalSlug}} employee with delivery configured.
+
+## Example Configuration
+
+```json
+[
+  {
+    "id": "daily-standup",
+    "name": "Daily Standup Summary",
+    "enabled": true,
+    "schedule": "0 9 * * 1-5",
+    "timezone": "America/New_York",
+    "engine": "claude",
+    "employee": "{{portalSlug}}",
+    "prompt": "Delegate to @project-manager: review yesterday's board activity across all departments. Review the output and write a concise standup summary.",
+    "delivery": {
+      "connector": "slack",
+      "channel": "#engineering"
+    }
+  },
+  {
+    "id": "weekly-cleanup",
+    "name": "Weekly Skill Review",
+    "enabled": true,
+    "schedule": "0 18 * * 5",
+    "timezone": "America/New_York",
+    "engine": "claude",
+    "employee": "{{portalSlug}}",
+    "prompt": "Review all skills in ~/.jinn/skills/ and suggest improvements or removals for unused skills."
+  }
+]
+```

package/template/docs/mcp.md

@@ -0,0 +1,108 @@
+# MCP (Model Context Protocol) Integration
+
+{{portalName}} automatically configures MCP servers for AI engine sessions, giving employees access to browser automation, web search, and gateway tools without manual setup.
+
+## How It Works
+
+1. MCP servers are defined in `config.yaml` under the `mcp:` section
+2. When a session starts, {{portalName}} resolves which MCP servers the employee needs
+3. A temporary MCP config JSON file is written to `~/.jinn/tmp/mcp/`
+4. The file is passed to Claude Code via `--mcp-config <path>`
+5. The file is cleaned up after the session completes
+
+## Built-in MCP Servers
+
+### Browser (Playwright)
+Full browser automation — navigate, click, type, screenshot, extract content.
+
+```yaml
+mcp:
+  browser:
+    enabled: true
+    provider: playwright  # or "puppeteer"
+```
+
+### Web Search (Brave)
+Search the web and get structured results.
+
+```yaml
+mcp:
+  search:
+    enabled: true
+    provider: brave
+    apiKey: ${BRAVE_API_KEY}  # reads from environment variable
+```
+
+### Fetch
+Extract readable content from URLs (HTML → markdown/text).
+
+```yaml
+mcp:
+  fetch:
+    enabled: true
+```
+
+### Gateway
+Built-in MCP server that wraps {{portalName}}'s own API. Gives employees tools to:
+- Send messages via connectors (Slack, etc.)
+- List and query sessions
+- Manage cron jobs
+- Query the org structure
+- Update department boards
+
+```yaml
+mcp:
+  gateway:
+    enabled: true  # enabled by default
+```
+
+## Custom MCP Servers
+
+Add any MCP server via the `custom:` section:
+
+```yaml
+mcp:
+  custom:
+    my-database:
+      enabled: true
+      command: npx
+      args: ["-y", "@my/mcp-server-postgres"]
+      env:
+        DATABASE_URL: ${DATABASE_URL}
+    my-api:
+      command: node
+      args: ["/path/to/my-mcp-server.js"]
+```
+
+## Per-Employee Overrides
+
+Employees can opt out of MCP servers or request only specific ones:
+
+```yaml
+# In employee YAML (e.g. org/engineering/backend-dev.yaml)
+name: backend-dev
+mcp: false  # No MCP servers at all
+
+# Or specific servers only:
+mcp:
+  - search
+  - gateway
+```
+
+By default, all globally enabled MCP servers are available to all employees.
+
+## Environment Variables
+
+API keys and secrets should use `${VAR_NAME}` syntax to reference environment variables:
+
+```yaml
+mcp:
+  search:
+    apiKey: ${BRAVE_API_KEY}
+  custom:
+    stripe:
+      env:
+        STRIPE_KEY: ${STRIPE_SECRET_KEY}
+```
+
+This keeps secrets out of config files.

package/template/docs/org.md

@@ -0,0 +1,105 @@
+# Organization
+
+{{portalName}} supports an organizational structure with employee personas, departments, ranks, and inter-agent communication through boards.
+
+## Employee Personas
+
+Employee files live at `~/.jinn/org/<department>/<name>.yaml`.
+
+```yaml
+name: alice
+displayName: Alice
+department: engineering
+rank: senior
+engine: claude
+model: opus
+persona: |
+  You are Alice, a senior engineer focused on backend systems.
+  You write clean, well-tested code and prefer simple solutions.
+  You review PRs thoroughly and flag potential performance issues.
+```
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `name` | string | yes | Unique identifier (lowercase, no spaces) |
+| `displayName` | string | yes | Human-readable name |
+| `department` | string | yes | Department directory name |
+| `rank` | string | yes | One of: executive, manager, senior, employee |
+| `engine` | string | yes | Engine to use: "claude" or "codex" |
+| `model` | string | no | Model override (default from config) |
+| `persona` | string | yes | System prompt defining personality and behavior |
+
+## Departments
+
+Each department is a directory under `~/.jinn/org/` containing:
+
+```
+~/.jinn/org/engineering/
+  department.yaml     # Department metadata
+  board.json          # Shared task board
+  alice.yaml          # Employee persona
+  bob.yaml            # Employee persona
+```
+
+### department.yaml
+
+```yaml
+name: engineering
+displayName: Engineering
+description: Builds and maintains the product codebase.
+```
+
+### board.json
+
+A JSON array of task objects used for inter-agent communication:
+
+```json
+[
+  {
+    "id": "task_001",
+    "title": "Refactor auth module",
+    "assignee": "alice",
+    "status": "in-progress",
+    "priority": "high",
+    "description": "Move auth logic into a dedicated service class.",
+    "createdAt": "2026-01-10T14:00:00.000Z",
+    "updatedAt": "2026-01-11T09:30:00.000Z"
+  }
+]
+```
+
+Task fields: `id`, `title`, `assignee`, `status` (open, in-progress, done, blocked), `priority` (low, medium, high, critical), `description`, `createdAt`, `updatedAt`.
+
+## Ranks
+
+| Rank | Privileges |
+|---|---|
+| **executive** | Full access. Can message any employee, modify org structure, create departments. {{portalName}} holds this rank. |
+| **manager** | Can message employees in their department. Can assign tasks on their department's board. |
+| **senior** | Can message employees in their department. Can update tasks assigned to them. |
+| **employee** | Can update tasks assigned to them. Can post to their department's board. |
+
+## Communication
+
+- **Downward**: Higher-ranked agents write tasks to lower-ranked agents' department boards
+- **@mentions**: Messages containing `@name` route to that specific employee
+- **Board-based**: Agents check their department's `board.json` for assigned tasks
+- **Cross-department**: Executives and managers can write to any department's board
+
+## Default Organization
+
+{{portalName}} ships with a single executive employee:
+
+```yaml
+name: {{portalSlug}}
+displayName: {{portalName}}
+department: executive
+rank: executive
+engine: claude
+model: opus
+persona: |
+  You are {{portalName}}, the executive AI assistant and gateway administrator.
+  You manage the organization, delegate tasks, and handle direct requests.
+```

package/template/docs/overview.md

@@ -0,0 +1,39 @@
+# {{portalName}} Overview
+
+{{portalName}} is a lightweight AI gateway daemon that wraps professional AI CLI tools as "engines." It is published as `jinn-cli`.
+
+## Core Principle
+
+**{{portalName}} is a bus, not a brain.** All AI intelligence comes from the engines natively. {{portalName}} adds no custom agentic loop, no prompt engineering layer, no opinions on how AI should behave. It delegates everything to professional tools (Claude Code CLI, Codex SDK) and focuses solely on routing, scheduling, and connectivity.
+
+## What {{portalName}} Does
+
+- **Gateway**: Single Node.js process that accepts messages from multiple sources and routes them to AI engines
+- **Connectors**: Modular input/output adapters (Slack, web UI, future: Discord, iMessage)
+- **Cron**: Scheduled AI jobs with hot-reloadable configuration
+- **Organization**: Employee personas with departments, ranks, and inter-agent communication via boards
+- **Skills**: Markdown instruction sets that engines read and follow natively
+- **Self-modification**: {{portalName}} can edit its own config, skills, cron jobs, and org structure at runtime
+
+## How It Differs from Custom Agentic Frameworks
+
+Traditional approaches build custom tool-calling loops, manage context windows, and implement retry logic. {{portalName}} does none of that. The engines (Claude Code, Codex) already handle tool use, file editing, command execution, and multi-step reasoning. {{portalName}} just connects them to the outside world.
+
+## Directory Structure
+
+```
+~/.jinn/
+  config.yaml          # Gateway configuration
+  jinn.db             # SQLite session registry
+  docs/                # These reference docs
+  skills/              # Skill directories with SKILL.md files
+  cron/
+    jobs.json          # Cron job definitions
+    runs/              # Run logs (JSONL)
+  org/
+    <department>/
+      department.yaml  # Department config
+      board.json       # Task board
+      <name>.yaml      # Employee persona
+  logs/                # Application logs
+```

package/template/docs/self-modification.md

@@ -0,0 +1,65 @@
+# Self-Modification
+
+{{portalName}}'s engines operate within `~/.jinn/` and can modify any file in that directory. This enables {{portalName}} to update its own configuration, create skills, manage cron jobs, and restructure the organization at runtime.
+
+## What {{portalName}} Can Edit
+
+| File/Directory | Effect of Modification |
+|---|---|
+| `config.yaml` | File watcher triggers full config reload |
+| `cron/jobs.json` | File watcher triggers cron reschedule |
+| `org/**/*.yaml` | File watcher triggers employee registry rebuild |
+| `org/**/board.json` | Read on demand by employees; no watcher needed |
+| `skills/*/SKILL.md` | Read on demand by engines; no watcher needed |
+| `skills/**/*` | Supporting skill data; read on demand |
+
+## File Watcher Reactions
+
+The gateway uses chokidar to watch for changes:
+
+- **config.yaml** → Parse YAML, validate schema, reload gateway configuration (port, engines, connectors, logging)
+- **cron/jobs.json** → Cancel all scheduled jobs, parse JSON, validate schema, reschedule enabled jobs
+- **org/\*\*/\*.yaml** → Rebuild the employee registry from all persona and department YAML files
+
+Changes take effect immediately. No restart required.
+
+## Safety Guidelines
+
+Engines have full file access within `~/.jinn/`. To avoid breaking the gateway:
+
+### Do
+
+- Validate YAML before writing to `config.yaml` (must be valid YAML with expected schema)
+- Validate JSON before writing to `jobs.json` or `board.json`
+- Use atomic writes (write to temp file, then rename) for critical files
+- Back up files before making destructive changes
+- Test cron expressions before adding them to `jobs.json`
+
+### Do Not
+
+- Break `config.yaml` structure — invalid YAML will prevent config reload
+- Corrupt `jinn.db` — the SQLite database is managed by the gateway process
+- Write invalid JSON to `jobs.json` — this will cancel all cron jobs with nothing to replace them
+- Delete the `docs/` directory — these reference docs are needed for self-awareness
+- Modify files outside `~/.jinn/` unless explicitly instructed by the user
+
+## Example: Creating a Cron Job at Runtime
+
+An engine can create a new cron job by reading `cron/jobs.json`, appending a new entry, and writing it back:
+
+```
+1. Read ~/.jinn/cron/jobs.json
+2. Parse the JSON array
+3. Append new job object with unique id, schedule, prompt, etc.
+4. Validate the full array
+5. Write back to ~/.jinn/cron/jobs.json
+6. The file watcher automatically reschedules all jobs
+```
+
+## Example: Adding a New Employee
+
+```
+1. Create ~/.jinn/org/<department>/<name>.yaml with required fields
+2. The file watcher detects the new file and rebuilds the employee registry
+3. The new employee is immediately available for @mention routing
+```

package/template/docs/skills.md

@@ -0,0 +1,58 @@
+# Skills
+
+Skills are markdown instruction sets that engines read and follow. There is no runtime, no loading system, no plugin API. Engines handle skills natively by reading the SKILL.md file.
+
+## How Skills Work
+
+Each skill is a directory in `~/.jinn/skills/` containing at minimum a `SKILL.md` file. When an engine starts a session, it has access to the skills directory and can read any skill's instructions.
+
+The `SKILL.md` file contains:
+- **Trigger description**: When this skill should be activated
+- **Instructions**: Step-by-step directions for the engine
+- **Data file references**: Paths to any supporting files in the skill directory
+
+## Creating a Skill
+
+```
+~/.jinn/skills/
+  my-skill/
+    SKILL.md          # Required: instructions
+    data.json         # Optional: supporting data
+    template.txt      # Optional: templates, examples, etc.
+```
+
+### Example SKILL.md
+
+```markdown
+# Deploy Notification Skill
+
+## Trigger
+When the user says "deploy" or asks about deployment status.
+
+## Instructions
+1. Read the deployment config from `data/deploy-targets.json` in this skill directory
+2. Check the current git branch and latest commit
+3. Format a deployment summary with target environment, branch, and commit hash
+4. Ask for confirmation before proceeding
+
+## Data Files
+- `deploy-targets.json`: List of deployment targets with URLs and environment names
+```
+
+## Pre-packaged Skills
+
+{{portalName}} ships with several default skills:
+
+- **self**: Instructions for {{portalName}} to understand and modify its own configuration
+- **slack**: Slack-specific behavior and formatting guidelines
+- **cron**: How to create and manage scheduled jobs
+- **org**: Working with the organization structure and employee personas
+- **skills**: Meta-skill for creating and managing other skills
+
+## Key Points
+
+- Skills are just files. Engines read them as context.
+- No compilation, no imports, no runtime hooks.
+- Any file format works as supporting data (JSON, YAML, CSV, plain text).
+- Skills can reference other skills by path.
+- Engines decide when and how to apply skill instructions based on the trigger description.