@astrosheep/keiyaku 0.1.87 → 1.0.1

package/README.md

@@ -13,20 +13,20 @@ npm install -g @astrosheep/keiyaku
 Missing any of these? Don't come crying.
 
 - **Git repo.** Clean worktree. Dirty = refused.
-- **Supported providers.** `codex-cli`, `codex-sdk`, `claude-agent-sdk`, `gemini-cli-core`, `opencode-sdk`. CLI-backed providers need their matching executable (`codex`, `gemini`, `opencode`). `claude-agent-sdk` uses the installed Agent SDK package and can optionally point at a `claude` executable override via `executable`.
+- **Supported providers.** `codex-sdk`, `codex-app-server`, `claude-agent-sdk`, `opencode-sdk`, and `pi`.
 
 ---
 
 ## Setup
 
-Open a git repo. Run `keiyaku guide` and `keiyaku zako list`. Then use `keiyaku <command> --help` for exact command formats.
+Open a git repo. Run `keiyaku guide` and `keiyaku akuma list`. Then use `keiyaku <command> --help` for exact command formats.
 
 ---
 
 ## Flow
 
 ```
-bind → round open → [summon/ask | amend | delivery work] → delivery commits → round close → [round open | amend | petition]
+bind → arc → [summon/ask | amend | delivery work] → arc | renew | petition
 ```
 
 ---
@@ -51,11 +51,11 @@ keiyaku resume .keiyaku/response/previous.md "Continue from here"
 
 ---
 
-**`zako list` / `zako show <name>`** — Inspect available helpers before choosing `keiyaku summon NAME`.
+**`akuma list` / `akuma show <name>`** — Inspect available helpers before choosing `keiyaku summon NAME`.
 
 ```bash
-keiyaku zako list
-keiyaku zako show codex
+keiyaku akuma list
+keiyaku akuma show akuma-codex
 ```
 
 ---
@@ -76,7 +76,7 @@ bind:
 
 ---
 
-**`round open`** — Frame a delivery round before work starts.
+**`arc`** — Frame the next delivery arc. An existing open arc is sealed first.
 
 ```
 # Retry backoff
@@ -85,19 +85,7 @@ bind:
 Implement retries with exponential backoff.
 
 ## Brief
-Keep the public API unchanged. Commit the delivery work before closing the round.
-```
-
----
-
-**`round close`** — Record a completed round from git commits.
-
-```
-## Commits
-- abc1234
-
-## Report
-Retry tests pass and backoff is now 2x.
+Keep the public API unchanged. Commit the delivery work before sealing the arc.
 ```
 
 ---
@@ -112,7 +100,7 @@ Oath required unless you explicitly bypass gates. Configured verification and re
 
 **`status`** — Current state and what's blocking you.
 
-**`keiyaku guide`** — Full reference.
+**`keiyaku guide`** — Workflow guide.
 
 ---
 
@@ -133,63 +121,84 @@ Don't want these tracked:
 
 ---
 
-## Advanced
+## Configuration
+
+Keiyaku works with its builtin `akuma-codex` and `akuma-claude` profiles without a settings file. Inspect the effective catalog before launching an Akuma:
 
 ```bash
-keiyaku dump-env
+keiyaku akuma list
+keiyaku akuma show akuma-codex
 ```
 
-Per-agent runtime settings live in `.keiyaku/settings.json` and use `provider` / `executable`:
+### Akuma profiles
+
+Akuma profiles are Markdown files. The filename is the profile name, YAML frontmatter configures the provider, and the Markdown body supplies the Akuma instructions.
+
+| Layer | Location | Precedence |
+|---|---|---|
+| Builtin | packaged with Keiyaku | lowest |
+| User | `<KEIYAKU_HOME>/akuma/<name>.md` | replaces the same builtin name |
+| Project | `.keiyaku/akuma/<name>.md` | highest |
+
+`KEIYAKU_HOME` defaults to `~/.keiyaku`. A higher layer replaces the whole file; layers are not field-merged.
+
+Minimal project profile:
+
+```markdown
+---
+provider: codex-sdk
+description: Repository implementation agent
+model: gpt-5.4
+effort: high
+accessPolicy: write
+networkPolicy: disabled
+webSearchPolicy: disabled
+threadOptions.sandboxMode: workspace-write
+---
+Follow the repository instructions, make scoped changes, and run relevant tests.
+```
+
+Provider fields:
+
+| Provider | Supported profile fields |
+|---|---|
+| `codex-sdk` | `description`, `model`, `profile`, `executable`, `effort`, `accessPolicy`, `networkPolicy`, `webSearchPolicy`, `threadOptions.*`, `config.*` |
+| `codex-app-server` | `description`, `model`, `profile`, `executable`, `config.*` |
+| `claude-agent-sdk` | `description`, `model`, `executable`, `effort`, `permissionMode`, `settingSources` |
+| `opencode-sdk` | `description`, `model`, `executable` |
+| `pi` | `description`, `model` |
+
+For `threadOptions.*`, JSON values such as arrays and objects are accepted. Keiyaku owns `workingDirectory` and `skipGitRepoCheck`, so profiles cannot set those paths.
+
+### Settings
+
+Settings select roles and workflow knobs; provider definitions do not belong in settings. Keiyaku loads user settings first and overlays project settings:
+
+- User: `<KEIYAKU_HOME>/settings.json`
+- Project: `.keiyaku/settings.json`
 
 ```json
 {
-  "agents": {
-    "claude": {
-      "provider": "claude-agent-sdk",
-      "model": "claude-sonnet-4-5",
-      "executable": "claude",
-      "description": "Claude-side Zako for review and integration.",
-      "systemPromptFile": ".keiyaku/claude-system.md"
-    },
-    "codex": {
-      "provider": "codex-sdk",
-      "executable": "codex",
-      "description": "Default Codex-side Zako.",
-      "config": {
-        "developer_instructions": "Adapter-level instructions appended to Codex sessions."
-      }
-    },
-    "gemini": {
-      "provider": "gemini-cli-core",
-      "model": "gemini-2.5-pro",
-      "description": "Gemini-side Zako for preview and synthesis.",
-      "systemPromptFile": ".keiyaku/gemini-system.md"
-    }
-  },
-  "default": "codex",
-  "reviewer": "codex"
+  "default": "akuma-codex",
+  "reviewer": "akuma-claude",
+  "defaultBranch": "main",
+  "gate": {
+    "commands": [
+      { "label": "tests", "command": "npm", "args": ["test"] }
+    ]
+  }
 }
 ```
 
-Claude defaults:
-- `settingSources: ["project"]`
-- `permissionMode: "bypassPermissions"`
-- `keiyaku resume RESPONSE_PATH` resumes via persisted provider session metadata
-
-Codex SDK notes:
-- `config` is passed through to Codex. Use `developer_instructions` for adapter-level instructions.
-- `model_instructions_file` is also accepted through `config`, but it replaces Codex built-in instructions.
+The only settings keys are `default`, `reviewer`, `defaultBranch`, and `gate`. The former `agents` key is invalid; define profiles in an `akuma/` directory instead. `keiyaku status` reports invalid settings without hiding the rest of the board.
 
-Gemini notes:
-- `systemPromptFile` is passed to Gemini CLI core as `GEMINI_SYSTEM_MD`, which replaces Gemini's base system prompt.
+### Environment
 
-`keiyaku zako list` and `keiyaku zako ls` show each profile's description when present.
+```bash
+keiyaku dump-env
+```
 
-| Variable | Default | |
-|----------|---------|--|
-| `KEIYAKU_SUBAGENT_EXEC_TIMEOUT_MS` | — | Execution timeout |
-| `KEIYAKU_SUBAGENT_EXEC_IDLE_TIMEOUT_MS` | — | Idle timeout |
-| `KEIYAKU_FAKE_SUBAGENT` | `0` | `1` = test stub |
+Keiyaku loads `<KEIYAKU_HOME>/.env`, then `.keiyaku/.env`; values already present in the process environment take precedence. `dump-env` is the authoritative template for supported keys and defaults.
 
 ---