jinn-cli 0.1.0

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.

package/template/migrations/0.1.0/MIGRATION.md

@@ -0,0 +1,25 @@
+# Migration: 0.1.0 (Baseline)
+
+This is the initial release of Jinn. No migration steps are needed — fresh installs via `jinn setup` receive everything automatically.
+
+## What's included in the initial template
+
+- `config.default.yaml` — default gateway configuration
+- `CLAUDE.md` — operating instructions for the COO persona
+- `AGENTS.md` — Codex engine instructions
+- `docs/` — architecture documentation (overview, connectors, cron, org, skills, self-modification)
+- `skills/` — 10 built-in skills:
+  - `management` — org management (hire, fire, promote, delegate)
+  - `cron-manager` — cron job CRUD
+  - `skill-creator` — create new skills
+  - `self-heal` — diagnose and fix gateway issues
+  - `onboarding` — first-run setup wizard
+  - `migrate` — AI-assisted template migrations
+  - `sync` — sync employee conversation context
+  - `status` — session status display
+  - `new` — reset chat session
+  - `find-and-install` — skills.sh marketplace integration
+
+## For future releases
+
+Subsequent versions will include migration steps here (file additions, config changes, schema updates) along with a `files/` directory containing new or modified template files.

package/template/skills/cron-manager/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: cron-manager
+description: Create, edit, delete, enable, disable, and list scheduled cron jobs
+---
+
+# Cron Manager Skill
+
+## Trigger
+
+This skill activates when the user wants to create, edit, delete, enable, disable, or list scheduled cron jobs.
+
+## Data File
+
+All cron jobs are stored in `~/.jinn/cron/jobs.json` as a JSON array of job objects. If the file does not exist, create it with an empty array `[]`.
+
+## CronJob Schema
+
+```json
+{
+  "id": "uuid-v4",
+  "name": "daily-standup-summary",
+  "enabled": true,
+  "schedule": "0 9 * * 1-5",
+  "timezone": "America/New_York",
+  "engine": "claude",
+  "model": "sonnet",
+  "employee": "project-manager",
+  "prompt": "Review all department boards and summarize progress since yesterday. Highlight blockers and upcoming deadlines.",
+  "delivery": {
+    "connector": "slack",
+    "channel": "#engineering-standup"
+  }
+}
+```
+
+Field details:
+- `id` — UUID v4, generated when creating the job
+- `name` — kebab-case human-readable identifier, must be unique across all jobs
+- `enabled` — boolean, whether the job is active
+- `schedule` — standard cron expression (minute hour day month weekday)
+- `timezone` — IANA timezone string (e.g., `America/New_York`, `Europe/London`, `UTC`)
+- `engine` — AI engine to run the job: `claude` or `codex`
+- `model` — model identifier (e.g., `sonnet`, `opus`, `o3`)
+- `employee` — optional, the employee persona to use (must match an employee name in the org)
+- `prompt` — the instruction to execute when the job fires
+- `delivery` — optional object specifying where to send output
+  - `connector` — the connector to use (e.g., `slack`, `discord`)
+  - `channel` — the target channel or destination
+
+## Operations
+
+### Creating a Job
+
+1. Read the current `~/.jinn/cron/jobs.json` (or initialize as `[]` if missing).
+2. Ask the user for the required fields: name, schedule, engine, model, and prompt.
+3. Ask about the timezone. Default to `UTC` if not specified.
+4. Ask about the employee persona to use. This is optional.
+5. **Always ask the user about the delivery channel** if they did not specify one. Explain that without delivery, the output will only be logged.
+6. **Delegation check**: If the job has delivery configured AND targets a non-{{portalSlug}} employee, warn the user. The correct pattern for reporting/analytical jobs is: target `{{portalSlug}}`, and include delegation instructions in the prompt (e.g. "Delegate to @employee-name: ..."). {{portalName}} reviews and filters the output before it reaches the delivery channel. Only simple, no-review tasks (e.g. health checks) should target employees directly with delivery.
+7. Generate a UUID for the `id` field.
+8. Set `enabled` to `true` by default.
+9. Append the new job object to the array.
+10. Write the updated array back to `~/.jinn/cron/jobs.json`.
+11. Confirm the creation and summarize the schedule in plain English.
+
+### Editing a Job
+
+1. Read `~/.jinn/cron/jobs.json`.
+2. Find the job by name or id.
+3. Show the current values to the user.
+4. Apply the requested changes.
+5. Write the updated array back.
+6. Confirm the changes.
+
+### Deleting a Job
+
+1. Read `~/.jinn/cron/jobs.json`.
+2. Find the job by name or id.
+3. Confirm deletion with the user (show job details).
+4. Remove the job from the array.
+5. Write the updated array back.
+6. Confirm deletion.
+
+### Enabling / Disabling a Job
+
+1. Read `~/.jinn/cron/jobs.json`.
+2. Find the job by name or id.
+3. Set `enabled` to `true` (enable) or `false` (disable).
+4. Write the updated array back.
+5. Confirm the status change.
+
+### Listing Jobs
+
+1. Read `~/.jinn/cron/jobs.json`.
+2. Display jobs in a readable format, grouped by enabled/disabled.
+3. Include name, schedule (with plain-English interpretation), timezone, engine, and delivery info.
+
+## Cron Schedule Reference
+
+The schedule field uses standard 5-field cron syntax:
+
+```
+┌───────────── minute (0-59)
+│ ┌───────────── hour (0-23)
+│ │ ┌───────────── day of month (1-31)
+│ │ │ ┌───────────── month (1-12)
+│ │ │ │ ┌───────────── day of week (0-7, 0 and 7 = Sunday)
+│ │ │ │ │
+* * * * *
+```
+
+Common examples:
+- `0 9 * * 1-5` — Every weekday at 9:00 AM
+- `0 0 * * *` — Every day at midnight
+- `*/15 * * * *` — Every 15 minutes
+- `0 9 * * 1` — Every Monday at 9:00 AM
+- `0 8,17 * * *` — Every day at 8:00 AM and 5:00 PM
+- `0 0 1 * *` — First day of every month at midnight
+- `30 14 * * 5` — Every Friday at 2:30 PM
+
+## Error Handling
+
+- If `jobs.json` is malformed, attempt to fix it. If unrecoverable, back it up as `jobs.json.bak` and start fresh with `[]`.
+- If a job name already exists when creating, warn the user and ask for a different name.
+- Validate the cron expression format before saving. Warn if the expression looks incorrect.
+- Validate that the timezone is a valid IANA timezone string.
+- If an employee is specified, verify it exists in the org directory.

package/template/skills/find-and-install/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: find-and-install
+description: Find and install skills from skills.sh when a capability gap is detected
+---
+
+# Find & Install Skills
+
+## Trigger
+
+This skill activates when you detect a capability gap that a community skill might fill, the user explicitly asks to find or install a skill and a task would benefit from a specialized skill you don't currently have
+
+## Searching for Skills
+
+Run a search using the skills CLI:
+
+```bash
+npx skills find [query]
+```
+
+Review the results and assess trust level before suggesting:
+
+- 🟢 **VERIFIED** (1000+ installs or known orgs like `vercel-labs`, `anthropics`, `microsoft`): Suggest confidently
+- 🟡 **COMMUNITY** (50–999 installs): Suggest with a note about the install count
+- 🔴 **UNKNOWN** (<50 installs): Show but warn the user — offer to preview the SKILL.md before installing
+
+## Installing a Skill
+
+Once the user approves (or for 🟢 VERIFIED skills when you're confident it fits):
+
+### Step 1: Install globally
+
+```bash
+npx skills add <owner/repo@skill> -g -y
+```
+
+This places files into `~/.claude/skills/<name>/` or `~/.agents/skills/<name>/`.
+
+### Step 2: Copy into {{portalSlug}} skills directory
+
+```bash
+cp -r ~/.claude/skills/<name>/ ~/.{{portalSlug}}/skills/<name>/
+```
+
+The {{portalName}} file watcher will detect the new directory and create the appropriate symlinks automatically.
+
+### Step 3: Update the skills manifest
+
+Read `~/.{{portalSlug}}/skills.json`, add the new skill entry, and write it back.
+
+The manifest format:
+
+```json
+{
+  "installed": {
+    "<name>": {
+      "source": "<owner/repo@skill>",
+      "installedAt": "<ISO 8601 timestamp>"
+    }
+  }
+}
+```
+
+### Step 4: Apply the skill immediately
+
+Read the newly installed `~/.{{portalSlug}}/skills/<name>/SKILL.md` and follow its instructions to complete the current task.
+
+## When No Skills Are Found
+
+If `npx skills find` returns no results:
+
+1. Offer to help the user directly with the task using your built-in capabilities
+2. Suggest creating a custom skill if this is a recurring need (use the `skill-creator` skill)
+
+## Examples
+
+**User asks to deploy to Vercel:**
+
+```bash
+npx skills find "vercel deploy"
+# → vercel-labs/ai-skills@vercel-deploy (🟢 VERIFIED, 5200 installs)
+npx skills add vercel-labs/ai-skills@vercel-deploy -g -y
+cp -r ~/.claude/skills/vercel-deploy/ ~/.{{portalSlug}}/skills/vercel-deploy/
+# → update skills.json → read SKILL.md → follow deploy instructions
+```
+
+**User asks for an obscure skill:**
+
+```bash
+npx skills find "arduino serial monitor"
+# → random-user/arduino-tools@serial-monitor (🔴 UNKNOWN, 12 installs)
+# → Warn user, offer to preview SKILL.md before installing
+```