@astrosheep/keiyaku 1.0.0 → 1.0.2

package/README.md

@@ -13,7 +13,7 @@ npm install -g @astrosheep/keiyaku
 Missing any of these? Don't come crying.
 
 - **Git repo.** Clean worktree. Dirty = refused.
-- **Supported providers.** `codex-sdk`, `claude-agent-sdk`, `opencode-sdk`. Runtime executables are `codex`, `claude`, and `opencode`.
+- **Supported providers.** `codex-sdk`, `codex-app-server`, `claude-agent-sdk`, `opencode-sdk`, and `pi`.
 
 ---
 
@@ -26,16 +26,14 @@ Open a git repo. Run `keiyaku guide` and `keiyaku akuma list`. Then use `keiyaku
 ## Flow
 
 ```
-bind → round open → [summon/ask | amend | delivery work] → delivery commits → round close → [round open | amend | petition]
+bind → arc → [call | amend | delivery work] → arc | renew | petition
 ```
 
 ---
 
 ## Tools
 
-**`summon <name> [prompt|-]`** — Calls in an agent to do scoped work. If a round is open, the round scope is injected. Add `--incognito` for a one-off run with no response history.
-
-`ask <name> [prompt|-]` is the short alias for the same behavior.
+**`call <name> [prompt|-]`** — Calls in an agent to do scoped work. If a round is open, the round scope is injected. Add `--incognito` for a one-off run with no response history.
 
 ```
 Implement the retry tests. Report touched files and verification.
@@ -43,15 +41,15 @@ Implement the retry tests. Report touched files and verification.
 
 ---
 
-**`resume <response-path> [prompt|-]`** — Continues a prior summon session from a response artifact.
+**`revive <response-path> [prompt|-]`** — Continues a prior call session from a response artifact.
 
 ```bash
-keiyaku resume .keiyaku/response/previous.md "Continue from here"
+keiyaku revive .keiyaku/response/previous.md "Continue from here"
 ```
 
 ---
 
-**`akuma list` / `akuma show <name>`** — Inspect available helpers before choosing `keiyaku summon NAME`.
+**`akuma list` / `akuma show <name>`** — Inspect available helpers before choosing `keiyaku call NAME`.
 
 ```bash
 keiyaku akuma list
@@ -76,7 +74,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 +83,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 +98,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,53 +119,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": {
-    "akuma-claude": {
-      "provider": "claude-agent-sdk",
-      "model": "claude-sonnet-4-5",
-      "executable": "claude",
-      "description": "Claude-side Akuma for review and integration.",
-      "systemPromptFile": ".keiyaku/claude-system.md"
-    },
-    "akuma-codex": {
-      "provider": "codex-sdk",
-      "executable": "codex",
-      "description": "Default Codex-side Akuma.",
-      "config": {
-        "developer_instructions": "Adapter-level instructions appended to Codex sessions."
-      }
-    },
-  },
   "default": "akuma-codex",
-  "reviewer": "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
+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.
 
-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.
+### Environment
 
-`keiyaku akuma list` and `keiyaku akuma 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 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.
 
 ---