agentrealm 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Exis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,147 @@
-# realm
+# agentrealm
 
-Agentless sandbox workspaces. Placeholder — full release coming soon.
+**Agentless sandbox workspaces for AI agents**
+
+[![npm](https://img.shields.io/npm/v/agentrealm.svg)](https://www.npmjs.com/package/agentrealm)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js](https://img.shields.io/node/v/agentrealm)](package.json)
+
+---
+
+## What is a realm?
+
+A **realm** is a lightweight, agentless sandbox workspace for AI agents.
+
+In a traditional agent workspace, one agent permanently guards the space — it's always watching, always running. A realm is different: **no agent lives there**. Any AI agent (or human) can enter when needed, do focused work, and leave. When the objective is complete, the realm is sealed.
+
+Think of it as a shared project folder with built-in structure, a context loader, and a work diary — designed to be understood and entered by any agent without prior knowledge of the project.
+
+### Agent Workspace vs Realm
+
+| | Agent Workspace | Realm |
+|---|---|---|
+| Persistent agent | ✅ Always watching | ❌ Agentless |
+| Entry model | One dedicated agent | Any agent |
+| Context loading | Agent-managed | `realm prompt <name>` |
+| Lifecycle | Ongoing | Scoped → seal when done |
+| Use case | Long-lived assistant | Focused task or project |
+| Overhead | High | Low |
+
+---
+
+## Install
+
+```bash
+npm i -g agentrealm
+```
+
+Three binary aliases installed: `realm` (primary), `agentrealm`, `agent-realm`.
+
+---
+
+## Quick Start
+
+```bash
+# Create a new realm
+realm new my-project
+
+# Load context into an agent session
+realm prompt my-project
+
+# Copy context to clipboard (then paste into your agent)
+realm prompt my-project --copy
+
+# List all active realms
+realm ls
+
+# Add a diary entry
+realm diary my-project "Finished the API integration, tests passing"
+
+# Seal when done
+realm seal my-project
+```
+
+---
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `realm new <name> [--dir <path>] [--with-diary]` | Create a new realm |
+| `realm ls [--all]` | List realms (active by default; `--all` includes sealed) |
+| `realm cd <name>` | Print realm directory (`cd $(realm cd foo)`) |
+| `realm prompt <name>` | Build context bundle — stdout, clipboard, or file |
+| `realm seal <name>` | Seal a realm (mark complete) |
+| `realm unseal <name>` | Unseal a realm (reactivate) |
+| `realm rm <name> [--purge] [--yes]` | Remove from registry; `--purge` deletes directory |
+| `realm diary <name> [message]` | Append diary entry or open in `$EDITOR` |
+| `realm skill` | Print path to bundled SKILL.md |
+
+### `realm prompt` options
+
+```
+--memory          Include MEMORY.md if present
+--diary <date>    Include historical diary file (YYYY-MM-DD)
+--diaries-list    List available archived diaries
+--copy            Copy output to clipboard
+--out <file>      Write output to file
+```
+
+---
+
+## Realm File Structure
+
+```
+~/realms/my-project/
+├── INDEX.md        # Read order + quick load instructions
+├── REALM.md        # Purpose, rules, and context
+├── TOOLS.md        # Tool checklist for this realm
+├── DIARY.md        # Rolling work log (optional: --with-diary)
+├── MEMORY.md       # Accumulated knowledge (manual, optional)
+└── diaries/        # Archived diary files (auto-rotated at 200 lines)
+    └── 2026-04-18.md
+```
+
+The **registry** lives at `~/.realm.yml`:
+
+```yaml
+version: 1
+realms:
+  my-project:
+    dir: /Users/you/realms/my-project
+    status: active
+    created: 2026-04-18T08:55:00.000Z
+    sealed_at: null
+    description: ""
+```
+
+---
+
+## Why "agentless" matters
+
+When an AI agent enters a workspace, it usually needs to know a lot of context to be useful: what's the purpose? What tools are available? What's been tried before? This typically lives in the agent's memory or a long system prompt.
+
+With realms, **the context travels with the workspace** — not the agent. Run `realm prompt my-project` and any agent instantly has everything it needs. Agents stay stateless and interchangeable. Realms stay self-describing.
+
+This unlocks:
+- **Multi-agent collaboration** — different models for different subtasks, no coordination overhead
+- **Resume from anywhere** — any agent, any session, full context in seconds
+- **Clean boundaries** — one realm per project, sealed when done, archived forever
+
+---
+
+## AgentSkill Integration
+
+`agentrealm` ships a bundled [AgentSkill](https://openclaw.ai/skills) that tells agents how to use realms:
+
+```bash
+realm skill    # prints path to skill/SKILL.md
+```
+
+Register it with your agent system to make realm-entry automatic.
+
+---
+
+## MIT License
+
+Copyright (c) 2026 Exis. See [LICENSE](LICENSE).

package/bin/agentrealm.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../src/cli.js';

package/package.json

@@ -1,22 +1,46 @@
 {
   "name": "agentrealm",
-  "version": "0.0.1",
-  "description": "Realm — agentless sandbox workspaces (placeholder, full release coming)",
+  "version": "0.1.0",
+  "description": "Agentless sandbox workspaces for AI agents",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
   "bin": {
-    "realm": "./bin.js"
+    "realm": "bin/agentrealm.js",
+    "agentrealm": "bin/agentrealm.js",
+    "agent-realm": "bin/agentrealm.js"
   },
-  "main": "bin.js",
-  "license": "MIT",
-  "author": "exisz",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/exisz/realm.git"
+  "files": [
+    "bin/",
+    "src/",
+    "templates/",
+    "skill/"
+  ],
+  "scripts": {
+    "test": "node --test test/basic.test.js"
   },
   "keywords": [
+    "agent",
+    "workspace",
     "realm",
+    "ai",
     "sandbox",
-    "workspace",
-    "agent",
-    "ai"
-  ]
-}
+    "agentless"
+  ],
+  "author": "Exis",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/exisz/agentrealm.git"
+  },
+  "homepage": "https://github.com/exisz/agentrealm#readme",
+  "bugs": {
+    "url": "https://github.com/exisz/agentrealm/issues"
+  },
+  "dependencies": {
+    "chalk": "^5.4.1",
+    "commander": "^13.1.0",
+    "js-yaml": "^4.1.0"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: agentrealm
+version: 0.1.0
+description: Enter and work within agentless realm workspaces
+triggers:
+  - realm
+  - agentrealm
+  - agentless workspace
+  - sandbox workspace
+install: npm i -g agentrealm
+---
+
+# AgentSkill: agentrealm
+
+## What is a Realm?
+
+A **realm** is an agentless sandbox workspace. Unlike an agent workspace where a dedicated agent
+permanently guards the space, realms are ephemeral collaboration zones. Any agent can enter,
+work, and leave. Realms are sealed when the work is done.
+
+## When This Skill Applies
+
+Use this skill when:
+- You are asked to work in a realm
+- You see a `REALM.md` file in a directory
+- A user says "enter the realm" or "work in realm X"
+
+## Entering a Realm
+
+When entering a realm, load its full context first:
+
+```bash
+realm prompt <name>
+```
+
+This outputs the bundled INDEX.md + REALM.md + TOOLS.md + DIARY.md (if present) as a single
+context block. Paste it into your session or use `--copy` to get it on the clipboard.
+
+## Working in a Realm
+
+1. Read REALM.md — understand the purpose and rules
+2. Read TOOLS.md — know what tools are available
+3. Read DIARY.md — understand recent progress and context
+4. Do your work
+5. **Before leaving:** if the realm has a DIARY.md, log a brief note:
+   ```bash
+   realm diary <name> "Brief note: what you did, what's next"
+   ```
+
+## Leaving / Sealing
+
+- Leave freely — no cleanup required beyond a diary note
+- Seal when the work is fully done: `realm seal <name>`
+
+## Common Commands
+
+| Command | Description |
+|---------|-------------|
+| `realm new <name>` | Create a new realm |
+| `realm prompt <name>` | Load realm context |
+| `realm ls` | List active realms |
+| `realm diary <name> "msg"` | Log a diary entry |
+| `realm seal <name>` | Seal a completed realm |
+| `realm cd <name>` | Get realm directory path |
+
+## Finding This Skill
+
+```bash
+realm skill
+```
+
+Prints the absolute path to this file.

package/src/cli.js

@@ -0,0 +1,36 @@
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { Command } from 'commander';
+
+import { newCommand } from './commands/new.js';
+import { lsCommand } from './commands/ls.js';
+import { cdCommand } from './commands/cd.js';
+import { promptCommand } from './commands/prompt.js';
+import { sealCommand } from './commands/seal.js';
+import { unsealCommand } from './commands/unseal.js';
+import { rmCommand } from './commands/rm.js';
+import { diaryCommand } from './commands/diary.js';
+import { skillCommand } from './commands/skill.js';
+
+const __dirname = join(fileURLToPath(import.meta.url), '..');
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+
+const program = new Command();
+
+program
+  .name('realm')
+  .description('Agentless sandbox workspaces for AI agents')
+  .version(pkg.version);
+
+newCommand(program);
+lsCommand(program);
+cdCommand(program);
+promptCommand(program);
+sealCommand(program);
+unsealCommand(program);
+rmCommand(program);
+diaryCommand(program);
+skillCommand(program);
+
+program.parse();

package/src/commands/cd.js

@@ -0,0 +1,12 @@
+import { readRegistry, requireRealm } from '../registry.js';
+
+export function cdCommand(program) {
+  program
+    .command('cd <name>')
+    .description('Print realm directory path (use: cd $(realm cd <name>))')
+    .action((name) => {
+      const registry = readRegistry();
+      const realm = requireRealm(registry, name);
+      process.stdout.write(realm.dir + '\n');
+    });
+}

package/src/commands/diary.js

@@ -0,0 +1,56 @@
+import { existsSync, readFileSync, writeFileSync, appendFileSync, renameSync } from 'fs';
+import { join } from 'path';
+import { execSync } from 'child_process';
+import { readRegistry, requireRealm } from '../registry.js';
+
+function countLines(content) {
+  return content.split('\n').length;
+}
+
+function todayStr() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function nowStr() {
+  const d = new Date();
+  return d.toISOString().slice(0, 16).replace('T', ' ');
+}
+
+export function diaryCommand(program) {
+  program
+    .command('diary <name> [message]')
+    .description('Append to or open DIARY.md')
+    .action((name, message) => {
+      const registry = readRegistry();
+      const realm = requireRealm(registry, name);
+      const diaryPath = join(realm.dir, 'DIARY.md');
+
+      if (!message) {
+        // Open in $EDITOR
+        const editor = process.env.EDITOR || 'vi';
+        if (!existsSync(diaryPath)) {
+          writeFileSync(diaryPath, `# Diary — ${name}\n\n`, 'utf8');
+        }
+        execSync(`${editor} "${diaryPath}"`, { stdio: 'inherit' });
+        return;
+      }
+
+      // Create if missing
+      if (!existsSync(diaryPath)) {
+        writeFileSync(diaryPath, `# Diary — ${name}\n\n`, 'utf8');
+      }
+
+      const content = readFileSync(diaryPath, 'utf8');
+
+      // Rotate if > 200 lines
+      if (countLines(content) > 200) {
+        const archivePath = join(realm.dir, 'diaries', `${todayStr()}.md`);
+        renameSync(diaryPath, archivePath);
+        writeFileSync(diaryPath, `# Diary — ${name}\n\n`, 'utf8');
+        console.error(`Diary rotated to diaries/${todayStr()}.md`);
+      }
+
+      appendFileSync(diaryPath, `\n## ${nowStr()}\n${message}\n`, 'utf8');
+      console.log(`✓ Diary entry added.`);
+    });
+}

package/src/commands/ls.js

@@ -0,0 +1,42 @@
+import chalk from 'chalk';
+import { readRegistry } from '../registry.js';
+
+export function lsCommand(program) {
+  program
+    .command('ls')
+    .description('List realms')
+    .option('--all', 'Include sealed realms')
+    .action((opts) => {
+      const registry = readRegistry();
+      const realms = Object.entries(registry.realms || {});
+
+      const filtered = opts.all
+        ? realms
+        : realms.filter(([, r]) => r.status !== 'sealed');
+
+      if (filtered.length === 0) {
+        console.log('No realms found. Create one with: realm new <name>');
+        return;
+      }
+
+      const col1 = Math.max(4, ...filtered.map(([n]) => n.length));
+      const col2 = 8;
+      const col3 = Math.max(3, ...filtered.map(([, r]) => r.dir.length));
+
+      const header =
+        chalk.bold('NAME'.padEnd(col1)) + '  ' +
+        chalk.bold('STATUS'.padEnd(col2)) + '  ' +
+        chalk.bold('DIR');
+      console.log(header);
+      console.log('─'.repeat(col1 + col2 + col3 + 4));
+
+      for (const [name, realm] of filtered) {
+        const statusColor = realm.status === 'sealed' ? chalk.gray : chalk.green;
+        console.log(
+          name.padEnd(col1) + '  ' +
+          statusColor(realm.status.padEnd(col2)) + '  ' +
+          chalk.dim(realm.dir)
+        );
+      }
+    });
+}

package/src/commands/new.js

@@ -0,0 +1,33 @@
+import { homedir } from 'os';
+import { join } from 'path';
+import { readRegistry, addRealm } from '../registry.js';
+import { scaffoldRealm } from '../scaffold.js';
+
+export function newCommand(program) {
+  program
+    .command('new <name>')
+    .description('Create a new realm')
+    .option('--dir <path>', 'Custom directory (default: ~/realms/<name>)')
+    .option('--with-diary', 'Include a DIARY.md in the realm')
+    .action((name, opts) => {
+      const dir = opts.dir || join(homedir(), 'realms', name);
+      const registry = readRegistry();
+
+      if (registry.realms?.[name]) {
+        console.error(`Realm "${name}" already exists.`);
+        process.exit(1);
+      }
+
+      scaffoldRealm(name, dir, opts.withDiary || false);
+
+      addRealm(registry, name, {
+        dir,
+        status: 'active',
+        created: new Date().toISOString(),
+        sealed_at: null,
+        description: '',
+      });
+
+      console.log(`✓ Realm "${name}" created at ${dir}`);
+    });
+}

package/src/commands/prompt.js

@@ -0,0 +1,53 @@
+import { writeFileSync } from 'fs';
+import { execSync } from 'child_process';
+import { readRegistry, requireRealm } from '../registry.js';
+import { buildPrompt, listDiaries } from '../prompt.js';
+
+export function promptCommand(program) {
+  program
+    .command('prompt <name>')
+    .description('Build and output the realm context prompt')
+    .option('--memory', 'Include MEMORY.md if present')
+    .option('--diary <date>', 'Include a historical diary (YYYY-MM-DD)')
+    .option('--diaries-list', 'List available diary files')
+    .option('--copy', 'Copy output to clipboard')
+    .option('--out <file>', 'Write output to file')
+    .action((name, opts) => {
+      const registry = readRegistry();
+      const realm = requireRealm(registry, name);
+
+      if (opts.diariesList) {
+        const files = listDiaries(realm);
+        if (files.length === 0) {
+          console.log('No diary archives found.');
+        } else {
+          files.forEach(f => console.log(f));
+        }
+        return;
+      }
+
+      const output = buildPrompt(realm, {
+        memory: opts.memory,
+        diary: opts.diary,
+      });
+
+      if (opts.out) {
+        writeFileSync(opts.out, output, 'utf8');
+        console.error(`Written to ${opts.out}`);
+        return;
+      }
+
+      if (opts.copy) {
+        const platform = process.platform;
+        let cmd;
+        if (platform === 'darwin') cmd = 'pbcopy';
+        else if (platform === 'win32') cmd = 'clip';
+        else cmd = 'xclip -selection clipboard 2>/dev/null || wl-copy';
+        execSync(cmd, { input: output });
+        console.error('Copied to clipboard.');
+        return;
+      }
+
+      process.stdout.write(output);
+    });
+}

package/src/commands/rm.js

@@ -0,0 +1,42 @@
+import { rmSync, existsSync } from 'fs';
+import { createInterface } from 'readline';
+import { readRegistry, requireRealm, removeRealm } from '../registry.js';
+
+function confirm(question) {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase() === 'y');
+    });
+  });
+}
+
+export function rmCommand(program) {
+  program
+    .command('rm <name>')
+    .description('Remove a realm from registry')
+    .option('--purge', 'Also delete the realm directory')
+    .option('--yes', 'Skip confirmation')
+    .action(async (name, opts) => {
+      const registry = readRegistry();
+      const realm = requireRealm(registry, name);
+
+      if (opts.purge && !opts.yes) {
+        const ok = await confirm(`This will delete ${realm.dir}. Continue? [y/N] `);
+        if (!ok) {
+          console.log('Aborted.');
+          process.exit(0);
+        }
+      }
+
+      removeRealm(registry, name);
+
+      if (opts.purge && existsSync(realm.dir)) {
+        rmSync(realm.dir, { recursive: true, force: true });
+        console.log(`✓ Realm "${name}" removed from registry and directory deleted.`);
+      } else {
+        console.log(`✓ Realm "${name}" removed from registry.`);
+      }
+    });
+}

package/src/commands/seal.js

@@ -0,0 +1,16 @@
+import { readRegistry, requireRealm, updateRealm } from '../registry.js';
+
+export function sealCommand(program) {
+  program
+    .command('seal <name>')
+    .description('Seal a realm (mark as done)')
+    .action((name) => {
+      const registry = readRegistry();
+      requireRealm(registry, name);
+      updateRealm(registry, name, {
+        status: 'sealed',
+        sealed_at: new Date().toISOString(),
+      });
+      console.log(`✓ Realm "${name}" sealed.`);
+    });
+}

package/src/commands/skill.js

@@ -0,0 +1,14 @@
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SKILL_PATH = join(__dirname, '..', '..', 'skill', 'SKILL.md');
+
+export function skillCommand(program) {
+  program
+    .command('skill')
+    .description('Print path to bundled SKILL.md')
+    .action(() => {
+      console.log(SKILL_PATH);
+    });
+}

package/src/commands/unseal.js

@@ -0,0 +1,16 @@
+import { readRegistry, requireRealm, updateRealm } from '../registry.js';
+
+export function unsealCommand(program) {
+  program
+    .command('unseal <name>')
+    .description('Unseal a realm (reactivate)')
+    .action((name) => {
+      const registry = readRegistry();
+      requireRealm(registry, name);
+      updateRealm(registry, name, {
+        status: 'active',
+        sealed_at: null,
+      });
+      console.log(`✓ Realm "${name}" unsealed.`);
+    });
+}

package/src/prompt.js

@@ -0,0 +1,50 @@
+import { readFileSync, existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+
+function section(filename, content) {
+  return `=== ${filename} ===\n\n${content}\n\n`;
+}
+
+export function buildPrompt(realm, options = {}) {
+  const dir = realm.dir;
+  const parts = [];
+
+  for (const file of ['INDEX.md', 'REALM.md', 'TOOLS.md']) {
+    const p = join(dir, file);
+    if (existsSync(p)) {
+      parts.push(section(file, readFileSync(p, 'utf8')));
+    }
+  }
+
+  // DIARY.md — always include if exists (unless --diary flag overrides)
+  const diaryPath = join(dir, 'DIARY.md');
+  if (!options.diary && existsSync(diaryPath)) {
+    parts.push(section('DIARY.md', readFileSync(diaryPath, 'utf8')));
+  }
+
+  if (options.memory) {
+    const memPath = join(dir, 'MEMORY.md');
+    if (existsSync(memPath)) {
+      parts.push(section('MEMORY.md', readFileSync(memPath, 'utf8')));
+    }
+  }
+
+  if (options.diary) {
+    const histPath = join(dir, 'diaries', `${options.diary}.md`);
+    if (existsSync(histPath)) {
+      parts.push(section(`diaries/${options.diary}.md`, readFileSync(histPath, 'utf8')));
+    } else {
+      console.error(`Diary file not found: diaries/${options.diary}.md`);
+    }
+  }
+
+  return parts.join('');
+}
+
+export function listDiaries(realm) {
+  const dirPath = join(realm.dir, 'diaries');
+  if (!existsSync(dirPath)) return [];
+  return readdirSync(dirPath)
+    .filter(f => f.endsWith('.md') && f !== '.gitkeep')
+    .sort();
+}

package/src/registry.js

@@ -0,0 +1,51 @@
+import { readFileSync, existsSync, writeFileSync, renameSync, mkdirSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import yaml from 'js-yaml';
+
+const REGISTRY_PATH = join(homedir(), '.realm.yml');
+
+function emptyRegistry() {
+  return { version: 1, realms: {} };
+}
+
+export function readRegistry() {
+  if (!existsSync(REGISTRY_PATH)) return emptyRegistry();
+  const content = readFileSync(REGISTRY_PATH, 'utf8');
+  return yaml.load(content) || emptyRegistry();
+}
+
+export function writeRegistry(data) {
+  const tmp = REGISTRY_PATH + '.tmp';
+  writeFileSync(tmp, yaml.dump(data, { lineWidth: -1 }), 'utf8');
+  renameSync(tmp, REGISTRY_PATH);
+}
+
+export function getRealm(registry, name) {
+  return registry.realms?.[name] ?? null;
+}
+
+export function requireRealm(registry, name) {
+  const realm = getRealm(registry, name);
+  if (!realm) {
+    console.error(`Realm "${name}" not found. Run: realm ls`);
+    process.exit(1);
+  }
+  return realm;
+}
+
+export function addRealm(registry, name, data) {
+  registry.realms = registry.realms || {};
+  registry.realms[name] = data;
+  writeRegistry(registry);
+}
+
+export function updateRealm(registry, name, updates) {
+  registry.realms[name] = { ...registry.realms[name], ...updates };
+  writeRegistry(registry);
+}
+
+export function removeRealm(registry, name) {
+  delete registry.realms[name];
+  writeRegistry(registry);
+}

package/src/scaffold.js

@@ -0,0 +1,37 @@
+import { mkdirSync, writeFileSync, existsSync, readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = join(__dirname, '..', 'templates');
+
+function readTemplate(name) {
+  return readFileSync(join(TEMPLATES_DIR, name), 'utf8');
+}
+
+function renderTemplate(content, vars) {
+  return content
+    .replace(/\{\{name\}\}/g, vars.name)
+    .replace(/\{\{created\}\}/g, vars.created)
+    .replace(/\{\{status\}\}/g, vars.status || 'active')
+    .replace(/\{\{dir\}\}/g, vars.dir);
+}
+
+export function scaffoldRealm(name, dir, withDiary) {
+  mkdirSync(dir, { recursive: true });
+  mkdirSync(join(dir, 'diaries'), { recursive: true });
+
+  const now = new Date().toISOString();
+  const vars = { name, created: now, status: 'active', dir };
+
+  writeFileSync(join(dir, 'INDEX.md'), renderTemplate(readTemplate('INDEX.md'), vars), 'utf8');
+  writeFileSync(join(dir, 'REALM.md'), renderTemplate(readTemplate('REALM.md'), vars), 'utf8');
+  writeFileSync(join(dir, 'TOOLS.md'), renderTemplate(readTemplate('TOOLS.md'), vars), 'utf8');
+
+  if (withDiary) {
+    writeFileSync(join(dir, 'DIARY.md'), renderTemplate(readTemplate('DIARY.md'), vars), 'utf8');
+  }
+
+  // gitkeep for diaries
+  writeFileSync(join(dir, 'diaries', '.gitkeep'), '', 'utf8');
+}

package/templates/DIARY.md

@@ -0,0 +1,19 @@
+# Diary — {{name}}
+
+This is the rolling work log for realm **{{name}}**.
+
+Entries are added via:
+```bash
+realm diary {{name}} "Your note here"
+```
+
+Or open in your editor:
+```bash
+realm diary {{name}}
+```
+
+When this file exceeds 200 lines, it is automatically archived to `diaries/<date>.md`
+and a fresh file is started.
+
+---
+

package/templates/INDEX.md

@@ -0,0 +1,28 @@
+# Index — {{name}}
+
+> **This is a realm** — an agentless sandbox workspace. No agent permanently guards this space.
+> Any agent may enter, work, and leave. When the work is done, seal the realm.
+
+## Read Order
+
+When entering this realm, load files in this order:
+
+1. **REALM.md** — Purpose, rules, and context for this realm
+2. **TOOLS.md** — Tool checklist and constraints for work in this realm
+3. **DIARY.md** — Rolling work log (if present)
+4. **MEMORY.md** — Accumulated knowledge (if present)
+
+## Quick Load
+
+```bash
+realm prompt {{name}}
+```
+
+This command bundles the above files into a single context block ready to paste into an agent session.
+
+## About Realms
+
+Unlike an agent workspace (where a dedicated agent is always watching), realms are **agentless**.
+They are shared collaboration spaces — any AI agent or human can enter, contribute, and leave.
+
+Use `realm seal {{name}}` when the work is done.

package/templates/REALM.md

@@ -0,0 +1,37 @@
+---
+name: {{name}}
+created: {{created}}
+status: {{status}}
+---
+
+# Realm: {{name}}
+
+## Purpose
+
+<!-- Describe the purpose of this realm. What problem does it solve? What work happens here? -->
+
+## Rules
+
+- Any agent may enter and contribute — coordinate via DIARY.md
+- Keep changes focused and scoped to this realm's purpose
+- Document significant decisions and findings in DIARY.md
+- Don't leave this realm in a broken state
+
+## Who Can Enter
+
+<!-- List which agents or humans are expected to work in this realm -->
+
+- Any agent with the `agentrealm` skill installed
+
+## Context
+
+<!-- Additional context, links, references, or background information -->
+
+## When to Seal
+
+Seal this realm when:
+- The primary objective is complete
+- The work has been merged/shipped/delivered
+- No further active work is expected
+
+To seal: `realm seal {{name}}`

package/templates/TOOLS.md

@@ -0,0 +1,35 @@
+# Tools — {{name}}
+
+This file documents the tools, CLIs, and APIs available in this realm.
+Check items you've confirmed work, and add notes about limitations.
+
+## General
+
+- [ ] `realm prompt {{name}}` — load full context into agent session
+- [ ] `realm diary {{name}} "message"` — log a diary entry
+- [ ] `realm seal {{name}}` — seal when done
+
+## Filesystem & Shell
+
+- [ ] `read` / `write` / `edit` — file operations
+- [ ] `exec` — shell commands
+- [ ] `find`, `grep`, `rg` — search
+
+## Version Control
+
+- [ ] `git` — version control
+- [ ] `gh` — GitHub CLI
+
+## Language / Runtime
+
+<!-- Add language-specific tools here -->
+- [ ] Node.js / npm
+- [ ] Python / pip
+
+## External APIs
+
+<!-- Document any external APIs or services used in this realm -->
+
+## Notes
+
+<!-- Tool-specific notes, limitations, credentials info -->

package/bin.js

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-console.log("realm — placeholder. Full release coming soon. https://github.com/exisz/realm");