@iamu-dev/iamu 0.0.0-stage → 0.2.0-beta.2

package/LICENSE

@@ -0,0 +1,9 @@
+Copyright (c) 2026 iamu-dev. All rights reserved.
+
+This software and associated documentation files are proprietary and confidential
+to iamu-dev. 
+
+Use of this software is permitted solely for evaluation and testing purposes
+under authorization from iamu-dev. Unauthorized copying, modification, reverse
+engineering, decompilation, redistribution, or commercial use, via any medium,
+is strictly prohibited.

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# @iamu-dev/iamu
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Scenario-driven development CLI — test your product as realistic personas.
+
+Part of the [iamu](https://iamu.dev) platform.
+
+## Installation
+
+Run directly with `npx`:
+
+```bash
+npx @iamu-dev/iamu@beta <command>
+```
+
+Or install globally:
+
+```bash
+npm install -g @iamu-dev/iamu@beta
+```
+
+**Prerequisites:** Node.js 22+ and Google Chrome.
+
+## Quick Start
+
+In the root of your project:
+
+```bash
+npx @iamu-dev/iamu@beta init
+```
+
+`iamu init` scaffolds the `iamu/` directory and configures skills for your editor (Claude Code, Cursor, Windsurf, Cline, Codex, RooCode).
+
+## Core Commands
+
+### Project & Health
+
+| Command | Description |
+|---------|-------------|
+| `iamu init [--yes] [--json]` | Initialize or configure an iamu project in current workspace |
+| `iamu status [--json]` | Overview of personas, scenarios, active runs, and cloud sync status |
+| `iamu doctor` | Diagnose directory structure, schemas, and missing dependencies |
+| `iamu list [type] [--capability <slug>] [--json [fields]]` | List personas, scenarios, findings, capabilities, or outlines |
+| `iamu validate [path] [--all]` | Validate entity files against protocol schemas |
+| `iamu update` | Refresh installed editor agent skills to latest templates |
+
+### Walkthrough Execution Loop
+
+```
+start-run → browse → step → new-finding → complete → match → match-record → evaluate → evaluate-record
+```
+
+| Command | Description |
+|---------|-------------|
+| `iamu start-run <scenario> --target <url>` | Scaffold a new walkthrough run directory with metadata |
+| `iamu browse <command> [args]` | Control Google Chrome via CDP (start, goto, click, fill, shot, snapshot) |
+| `iamu step [run-id] --action "..."` | Record a walkthrough step atomically into `steps/` and `screenshots/` |
+| `iamu new-finding [run-id]` | Scaffold a new finding markdown file with valid UUID and frontmatter |
+| `iamu complete <run-id> [--json]` | Assemble canonical report, evaluate provenance, and mirror to cloud |
+| `iamu match <run-id>` | Generate matching prompt to link findings to prior runs |
+| `iamu match-record <run-id> --file <path> [--json]` | Record matcher resolutions and re-derive run delta |
+| `iamu evaluate <run-id> [--json]` | Compose evaluation prompt for human-test questions |
+| `iamu evaluate-record <run-id> --file <path> [--json]` | Record evaluation verdicts into `verdicts.json` |
+
+### Findings & Review
+
+| Command | Description |
+|---------|-------------|
+| `iamu findings [--open] [--resolved] [--json [fields]]` | List findings with triage status and severity |
+| `iamu triage <finding-ref...> --status <status>` | Triage findings (`open`, `resolved`, `dismissed`) |
+| `iamu report [scenario] [--json]` | View walkthrough reports and finding summaries |
+| `iamu prune [--keep <n>] [--days <n>]` | Prune old runs and reclaim disk space |
+
+### Cloud Sync & Collaboration
+
+| Command | Description |
+|---------|-------------|
+| `iamu auth login [--token <key>]` | Authenticate with Iamu Cloud |
+| `iamu auth status [--json]` | Check authentication and linked cloud project status |
+| `iamu sync [--confirm-deletes] [--json]` | Push local runs and entities to cloud |
+| `iamu pull [--preview] [--force] [--json]` | Pull remote team updates into local store |
+| `iamu open [run-id]` | Open run or project in the cloud web dashboard |
+
+## Programmatic & MCP Integration
+
+### MCP Sync Server
+
+To run the Model Context Protocol sync server for agent integration:
+
+```bash
+iamu sync-server
+```
+
+### JSON Projection Convention
+
+Commands supporting `--json` emit machine-readable JSON to stdout:
+
+```bash
+iamu list personas --json slug,name,role
+iamu findings --open --json slug,severity,type
+```
+
+## License
+
+MIT © [iamu-dev](https://github.com/iamu-dev/iamu)