@bybrawe/opencode-loop 0.5.33 → 0.5.34

package/README.md

@@ -1,330 +1,261 @@
 # OpenCode Loop
 
-**Claude Code-style auto-continue, scheduled OpenCode work, and background loops.**
+**Idle-safe auto-continue, scheduled OpenCode work, and background loops.**
 
-OpenCode Loop adds `/loop`, scheduled prompt/command/shell jobs, compact scheduling, safe long-running continuation helpers, and the `opencode-loopd` background daemon.
+OpenCode Loop adds `/loop`, scheduled prompt/command/shell jobs, compact scheduling, verification/checkpoints, and the `opencode-loopd` background daemon.
 
-> **Current release: `0.5.33`.** Loop also contains an older experimental `/loop-goal` mode, but for strong persistent Goal contracts and host-verified completion, use the separate **OpenCode Goals** plugin described below.
+> **Current stable release: `0.5.34`.**
 
 ## Install or update
 
-Choose either installation method below.
-
-### Option 1 — one-command install with `npx` (recommended)
+Recommended:
 
 ```bash
 npx -y @bybrawe/opencode-loop@latest
 ```
 
-Run the same command again whenever you want to update. If **OpenCode Goals is already installed**, a normal Loop install/update also makes a best-effort call to the official `@bybrawe/opencode-goal@latest` installer so the companion Goal plugin does not silently remain on an older release.
-
-Install Loop and Goals together from scratch with:
+Run the same command again to update. Then **fully restart OpenCode** and verify:
 
-```bash
-npx -y @bybrawe/opencode-loop@latest --with-goals
+```text
+/loop-help
+/loop-doctor
 ```
 
-If you use the dedicated OpenCode Goals plugin and do not want Loop's older experimental `/loop-goal*` commands in the slash-command list, use:
+Install/update Loop and the dedicated Goals companion together:
 
 ```bash
 npx -y @bybrawe/opencode-loop@latest --with-goals --without-loop-goals
 ```
 
-`--without-loop-goals` removes only Loop's packaged experimental `/loop-goal*` command files for that install/update. It keeps `/loop`, `/loop-command`, `/loop-shell`, the Loop runtime, and the separate OpenCode Goals `/goal` workflow. The choice is not persisted: run the flag again on a later Loop update if you want to keep those legacy command files omitted.
+`--without-loop-goals` removes only Loop's older experimental `/loop-goal*` command files. It keeps normal `/loop`, command/shell scheduling, daemon support, and the separate `/goal` plugin.
 
-Update/install only Loop and skip all Goals companion network work with:
+Install only Loop and skip companion network work:
 
 ```bash
 npx -y @bybrawe/opencode-loop@latest --loop-only
 ```
 
-`--with-goals` is explicit and fails if the requested Goals install/update fails. The automatic refresh of an already-installed Goals companion is best-effort: Loop still finishes its own update and prints a retry command if the companion registry/install step is temporarily unavailable.
-
-### Option 2 — install with npm
-
-Install OpenCode Loop globally so its installer and daemon commands are available:
+Global npm alternative:
 
 ```bash
 npm install -g @bybrawe/opencode-loop@latest
 opencode-loop
 ```
 
-To update later:
+To uninstall:
 
 ```bash
-npm install -g @bybrawe/opencode-loop@latest
-opencode-loop
+npx -y @bybrawe/opencode-loop@latest --uninstall
 ```
 
-If you want the global Loop installer to install Goals too, run:
+or, for a global install:
 
 ```bash
-opencode-loop --with-goals
+opencode-loop --uninstall
+npm uninstall -g @bybrawe/opencode-loop
 ```
 
-For the cleaner command surface with the dedicated Goals plugin:
-
-```bash
-opencode-loop --with-goals --without-loop-goals
-```
+Project Loop state under `.opencode/opencode-loop/` is intentionally preserved by uninstall.
 
-`npm install @bybrawe/opencode-loop` by itself only adds the Node package to the current project. For a normal OpenCode installation, use the global npm method above or the recommended `npx` installer.
+## The mental model
 
-The installer:
+Loop separates two ideas:
 
-- installs/updates the OpenCode Loop plugin;
-- installs the `/loop-*` slash-command definitions;
-- installs the tool-denied, hidden `opencode-loop-local` acknowledgement subagent used only by Loop's bound local command definitions;
-- keeps an existing npm plugin entry pinned to the installer’s exact version to avoid stale OpenCode package-cache resolution;
-- removes duplicate old local Loop plugin copies when the package entry is authoritative;
-- refreshes OpenCode Goals through **Goals' own official installer** when an existing managed Goals installation is detected;
-- can explicitly install both packages with `--with-goals`, skip companion network work with `--loop-only`, or omit the packaged experimental `/loop-goal*` command files with `--without-loop-goals`.
+1. **When does work become due?** Idle, a timer, a watch trigger, or `/loop-now`.
+2. **When is it safe to dispatch?** Only when the session is actually idle and no active tool/child work would overlap it.
 
-Then **fully restart OpenCode** and verify:
+A timer expiring does **not** intentionally inject a second model turn on top of an active one. Due work waits for idle.
 
-```text
-/loop-help
-/loop-doctor
-```
+## Quick start
 
-If Goals is installed too, also verify:
+### Keep saying “continue” whenever the assistant stops
 
 ```text
-/goal status
+/loop continue
 ```
 
-### Uninstall
-
-If you use the `npx` installer:
+Turkish shorthand works naturally too:
 
-```bash
-npx -y @bybrawe/opencode-loop@latest --uninstall
+```text
+/loop devam et
 ```
 
-If you installed OpenCode Loop globally with npm:
+Explicit equivalent:
 
-```bash
-opencode-loop --uninstall
-npm uninstall -g @bybrawe/opencode-loop
+```text
+/loop idle continue
 ```
 
-Run `opencode-loop --uninstall` before removing the global npm package so it can clean its OpenCode registrations and managed command files.
+This is an **unlimited idle loop** by default. When the assistant finishes and the session becomes safely idle, Loop sends the prompt again. When that turn finishes, it does the same again, until you pause/stop it or a configured limit is reached.
 
-Uninstall removes known OpenCode Loop package registrations, local plugin files, `/loop-*` command markdown files, and the Loop local command agent while preserving unrelated OpenCode configuration. It **does not uninstall OpenCode Goals**; Goals remains separately managed by its own installer.
+For very short continuation prompts such as `continue`, `keep going`, or `devam et`, Loop adds project-continuation guidance: treat the turn as continuation of the current repository/conversation, inspect relevant files/TODO/progress/git state as needed, find the next unfinished step, avoid redoing completed work, and verify meaningful changes when practical.
 
-Project Loop state is intentionally preserved under:
+For project work, a strong default is:
 
 ```text
-.opencode/opencode-loop/
+/loop --safe --ask-never --progress-file progress.md devam et
 ```
 
-Delete that directory yourself only when you intentionally want to erase saved Loop jobs, logs, checkpoints, or related local state. Restart OpenCode after uninstalling.
-
-## Quick start
-
-Auto-continue whenever OpenCode becomes idle:
+Create a starter progress file first if needed:
 
 ```text
-/loop 0s continue from progress.md and implement the next unfinished TODO
+/loop-init
 ```
 
-Run a prompt every 5 minutes when idle:
+### Repeat every 5 minutes
 
 ```text
-/loop 5m continue the project
+/loop every 5m continue the project
 ```
 
-Wait before the first run:
+This waits five minutes before the first run, then becomes due every five minutes. If the timer expires while OpenCode is busy, it waits for the next safe idle boundary rather than stacking prompts.
+
+### Do it once after 5 minutes
 
 ```text
-/loop 5m --no-now continue the project
+/loop after 5m continue once
 ```
 
-Schedule an OpenCode command such as compaction:
+Alias:
 
 ```text
-/loop-command 200m /compact
+/loop in 5m continue once
 ```
 
-Run a real shell command on a schedule:
+This is a one-shot delayed job. Five minutes passing makes it due; it still waits for idle before dispatching.
+
+### Legacy compact syntax remains supported
 
 ```text
-/loop-shell 10m npm test
+/loop 5m continue the project
 ```
 
-Ask a recurring quality-control question:
+For backward compatibility, this form starts on the next safe idle boundary and then follows a five-minute interval.
+
+Delay its first run explicitly:
 
 ```text
-/loop-ask 1h did you run tests, typecheck, and build? If not, run them and fix errors.
+/loop 5m --no-now continue the project
 ```
 
-## What OpenCode Loop is for
-
-Use Loop when the important question is **“what should run again, and when?”**
+Legacy idle form is still valid:
 
-Typical uses:
-
-- Claude Code-style auto-continue after idle;
-- recurring coding prompts;
-- progress.md / TODO workflows;
-- scheduled `/compact` or other OpenCode commands;
-- recurring tests/lint/build shell jobs;
-- retry/fix loops with verification;
-- patch checkpoints;
-- maximum run/runtime/failure limits;
-- prompt-file workflows;
-- background work through `opencode-loopd`;
-- Windows Task Scheduler integration.
+```text
+/loop 0s continue
+```
 
-Loop is idle-safe: if a job becomes due while the session is busy, active tools or child work are still running, the job waits instead of intentionally stacking another turn on top of the current one.
+For the exact schedule truth table and edge cases, see [docs/SCHEDULING.md](./docs/SCHEDULING.md).
 
-## For stronger persistent Goals, use OpenCode Goals
+## Schedule summary
 
-OpenCode Loop still includes the older **experimental** `/loop-goal` workflow for backward compatibility unless you install/update with `--without-loop-goals`. It is useful for compatibility and lightweight outcome-driven automation, but it is not the strongest Goal implementation in this project family.
+| Command | Meaning | First dispatch | Repeats |
+|---|---|---|---|
+| `/loop continue` | auto-continue on idle | next safe idle | every idle |
+| `/loop idle continue` | explicit idle loop | next safe idle | every idle |
+| `/loop every 5m continue` | recurring timer | after 5m, then idle | yes |
+| `/loop after 5m continue` | delayed one-shot | after 5m, then idle | no |
+| `/loop in 5m continue` | delayed one-shot alias | after 5m, then idle | no |
+| `/loop 5m continue` | legacy recurring form | next safe idle | yes |
+| `/loop 5m --no-now continue` | legacy delayed-first recurring | after 5m, then idle | yes |
+| `/loop 0s continue` | legacy idle form | next safe idle | every idle |
 
-For durable Goal Contracts, host-owned evidence, semantic verification, native Todo coordination, revision isolation, false-completion protection, restart recovery, Goal audit, budgets, and ordered Goals, install **OpenCode Goals**.
+## Understand an unfamiliar project and keep going
 
-Convenient combined installer from Loop:
+A useful first loop for an unfamiliar repository is:
 
-```bash
-npx -y @bybrawe/opencode-loop@latest --with-goals
+```text
+/loop-init
+/loop --safe --ask-never --progress-file progress.md Understand the existing project architecture and current state first. Inspect relevant source, tests, docs, TODOs, git status, and recent work. Record useful state in progress.md, choose the next unfinished safe improvement, implement it, verify it, update progress.md, and continue from there on later idle turns.
 ```
 
-For new installations where the dedicated `/goal` workflow replaces Loop's older experimental Goal commands, prefer:
+Once the project state is established, this is enough:
 
-```bash
-npx -y @bybrawe/opencode-loop@latest --with-goals --without-loop-goals
+```text
+/loop --safe --ask-never --progress-file progress.md devam et
 ```
 
-Or install Goals directly with its standalone installer:
+The short continuation form is deliberately interpreted as “resume this project”, not “invent a new task from scratch”.
 
-```bash
-npx -y @bybrawe/opencode-goal@latest
-```
+## Other job types
 
-Or install its CLI globally with npm and run the installer:
+Schedule an OpenCode slash command:
 
-```bash
-npm install -g @bybrawe/opencode-goal@latest
-opencode-goal
+```text
+/loop-command 200m /compact
 ```
 
-Then use:
+Run a real shell command:
 
 ```text
-/goal <objective>
-/goal status
-/goal contract
-/goal audit
+/loop-shell 10m npm test
 ```
 
-### Can Loop and Goals be installed together?
-
-Yes. `@bybrawe/opencode-loop` and `@bybrawe/opencode-goal` use different package names, commands, and project-state directories, so they can coexist in one OpenCode installation.
-
-Recommended split:
-
-- use **`/goal`** for persistent, strongly verified outcome completion;
-- use **`/loop`**, `/loop-command`, `/loop-shell`, and `opencode-loopd` for scheduling/repetition/background infrastructure.
-
-Do **not** run Loop’s `/loop-goal` and OpenCode Goals `/goal` against the same work in the same session. Both can autonomously continue on idle boundaries and can compete to start turns. Use `--without-loop-goals` when you want to remove that legacy command surface entirely.
-
-Likewise, avoid leaving a prompt-producing `/loop ...` job continuously injecting agent turns into a session while an OpenCode Goal is actively continuing. Use separate sessions or pause/remove that prompt loop until the Goal is done. Scheduled shell/command jobs should also be chosen carefully so they do not race files or verification.
-
-Install both with one `npx` command:
+Ask a recurring quality-control prompt:
 
-```bash
-npx -y @bybrawe/opencode-loop@latest --with-goals
+```text
+/loop-ask 1h did you run tests, typecheck, and build? If not, run them and fix errors.
 ```
 
-Or install both globally with npm, then run the Loop installer with the companion flag:
+Watch a path:
 
-```bash
-npm install -g @bybrawe/opencode-loop@latest @bybrawe/opencode-goal@latest
-opencode-loop --with-goals
+```text
+/loop --watch progress.md inspect the updated progress and continue
 ```
 
-Once Goals is managed in the OpenCode config, future normal `opencode-loop` / `npx ...opencode-loop@latest` updates also attempt to refresh Goals to its latest stable release. Use `--loop-only` when you intentionally do not want that companion refresh. Use `--without-loop-goals` on any install/update where you want the older Loop Goal command files omitted.
+Prompt, command, shell, compact, and watch jobs use the same idle-safe scheduling path but different execution transports.
 
 ## Core commands
 
 | Command | Purpose |
 |---|---|
-| `/loop <interval> <prompt>` | Add/update an idle/interval prompt loop |
-| `/loop-command <interval> <slash-command>` | Schedule OpenCode slash commands |
+| `/loop <prompt>` | Add/update an unlimited idle prompt loop |
+| `/loop idle <prompt>` | Explicit idle-loop form |
+| `/loop every <duration> <prompt>` | Recurring timer, first run delayed |
+| `/loop after <duration> <prompt>` | One-shot delayed prompt |
+| `/loop in <duration> <prompt>` | Alias for `after` |
+| `/loop <duration> <prompt>` | Backward-compatible compact interval form |
+| `/loop-command <interval> <slash-command>` | Schedule an OpenCode command |
 | `/loop-cmd <interval> <slash-command>` | Alias for `/loop-command` |
-| `/loop-ask <interval> <question>` | Schedule recurring quality/check prompts |
-| `/loop-shell <interval> <command>` | Schedule a real shell command |
-| `/loop-status` | Show active jobs |
-| `/loop-now [id/name/all]` | Run selected jobs immediately |
+| `/loop-ask <interval> <question>` | Schedule a recurring check/question |
+| `/loop-shell <interval> <command>` | Schedule a shell command |
+| `/loop-status` | Show jobs plus schedule/state |
+| `/loop-now [id/name/all]` | Mark selected jobs due now; still waits for idle |
 | `/loop-pause [id/name/all]` | Pause jobs |
 | `/loop-resume [id/name/all]` | Resume jobs |
 | `/loop-remove [id/name/all]` | Remove jobs |
-| `/loop-clear` | Remove all current-session Loop jobs |
-| `/loop-doctor` | Diagnose Loop/OpenCode state |
+| `/loop-clear` | Remove all jobs for the current session |
+| `/loop-logs` | Show recent scheduler/runtime events |
+| `/loop-doctor` | Diagnose session/state/scheduling problems |
 | `/loop-init` | Create a starter `progress.md` |
-| `/loop-export` | Export Loop state as JSON |
-| `/loop-goal <objective>` | Start the older experimental Loop Goal Mode when those optional legacy command files are installed |
-
-## Intervals and job types
-
-Examples:
-
-```text
-0s     run whenever OpenCode becomes idle
-5m     run every 5 minutes when idle
-200m   run every 200 minutes when idle
-1h     run every hour when idle
-```
-
-OpenCode Loop separates prompt, slash-command, and shell work because they should not be executed the same way.
-
-| Type | Example |
-|---|---|
-| Prompt | `/loop 0s continue from progress.md` |
-| Scheduled question | `/loop-ask 1h did you run tests?` |
-| OpenCode command | `/loop-command 200m /compact` |
-| Shell | `/loop-shell 10m npm test` |
-
-Do not use a normal prompt loop when you mean to run `/compact`. Prefer:
-
-```text
-/loop-command 200m /compact
-```
+| `/loop-export` | Export current-session Loop state |
 
 ## Useful flags
 
-### Naming and lifecycle
-
-```text
-/loop 0s --name dev continue the project
-/loop-pause dev
-/loop-resume dev
-/loop-stop dev
-```
-
-### Limits
+Lifecycle and limits:
 
 ```text
+--name <name>
 --max-runs <n>
 --max-runtime <duration>
 --max-failures <n>
 --timeout <duration>
+--no-now
+--now
 ```
 
-### Verification and safety
+Safety and verification:
 
 ```text
+--safe
+--ask-never
+--no-overlap
 --verify "npm test"
 --preflight "npm install"
 --postrun "git status --short"
 --pause-on-verify-fail
---safe
---ask-never
---no-overlap
 ```
 
-### Context and TODO workflows
+Project context:
 
 ```text
 --progress-file progress.md
@@ -335,119 +266,137 @@ Do not use a normal prompt loop when you mean to run `/compact`. Prefer:
 --watch progress.md
 ```
 
-### Checkpoints
+Checkpoints:
 
 ```text
 --checkpoint-only
 --git-checkpoint
 ```
 
-`--git-checkpoint` may stage and commit work. Use it only when that behavior is intentional.
+`--git-checkpoint` may stage/commit work; use it only when intentional.
 
-## Recommended development loop
+## Status and diagnostics
+
+`/loop-status` reports both the **schedule definition** and the **current scheduler state**. Examples:
 
 ```text
-/loop 0s --name dev --ask-never --safe --no-overlap --batch 5 --compact-every 200m --checkpoint-only --progress-file progress.md Treat progress.md as the project state. Continue with the next unfinished TODO, implement it, mark completed items, add useful follow-up TODOs, run tests/lint/build when available, and keep going while work remains.
+schedule=every idle | state=waiting for idle
+schedule=every 5m, first after 5m | state=due in 3m
+schedule=once after 5m | state=due; waiting for idle
 ```
 
-## Test-fix loop
+This is intentional: “due” is a clock fact, while “waiting for idle” is an admission/safety fact.
+
+### If a job says enabled but never runs
+
+The problematic shape is typically:
 
 ```text
-/loop 0s --name testfix --ask-never --safe --verify "npm test" --max-failures 3 Continue from progress.md. If tests fail, analyze the failure, fix it, and run the tests again.
+enabled=true
+paused=false
+runCount=0
+lastRunAt=0
 ```
 
-## Background daemon
+Some OpenCode TUI versions can leave `session.status` at `busy`/`retry` after a plugin command acknowledgement. Loop cross-checks that stale state against the chronological message tail before the first Loop run too. It recovers only when the latest assistant message is actually completed and no active tool/child work is known. A genuinely unfinished assistant turn, latest user turn, active tool, busy child, or unknown completion remains busy.
 
-The normal `/loop` plugin is session-bound. If OpenCode closes, that TUI/session loop cannot keep running in the background. `opencode-loopd` resolves the session once at startup and pins that exact session for later iterations, so a newer unrelated session cannot steal the daemon. If no session exists, the daemon creates one and pins it before the second iteration. Each daemon run is bounded by `--timeout` (30 minutes by default; use `--timeout 0s` to disable).
+Recovery is logged as:
 
-For long-running background jobs use:
-
-```bash
-opencode-loopd --project . --every 5m --prompt-file loop-prompt.md
+```text
+status-message-idle-recovery
 ```
 
-Run immediately on each daemon iteration:
+Busy retries are also written as throttled `deferred` events so `loop.log` does not misleadingly contain only the original `add` line.
 
-```bash
-opencode-loopd --project . --every 0s --prompt "continue from progress.md and implement the next unfinished TODO"
+Use:
+
+```text
+/loop-status
+/loop-logs
+/loop-doctor
 ```
 
-Select a model and agent:
+### Session-bound state
 
-```bash
-opencode-loopd --project . --every 0s --max-runs 1 --timeout 30m --model provider/model --agent build --prompt-file loop-prompt.md
+Normal plugin Loop jobs are session-bound and stored under:
+
+```text
+.opencode/opencode-loop/<session-id>.json
 ```
 
-Pin a specific existing session when needed:
+A new OpenCode session does not silently inherit another session's jobs. `/loop-doctor` reports other persisted session files that still contain enabled jobs, including jobs that have never run, so an old loop is visible instead of appearing lost.
 
-```bash
-opencode-loopd --project . --session ses_xxx --every 5m --prompt-file loop-prompt.md
-```
+For work that must continue after the TUI/session closes, use `opencode-loopd`.
 
-Limit total runs:
+## Loop and dedicated OpenCode Goals
 
-```bash
-opencode-loopd --project . --every 5m --max-runs 20 --prompt-file loop-prompt.md
-```
+They can be installed together. Recommended split:
 
-## Windows Task Scheduler
+- use **`/goal`** for durable outcome-driven work, evidence, verification, restart recovery, and semantic completion;
+- use **`/loop`**, `/loop-command`, `/loop-shell`, and `opencode-loopd` for scheduling/repetition/background infrastructure.
 
-Install a scheduled daemon task:
+A prompt-producing Loop and an active dedicated `/goal` should not both own autonomous continuation of the **same session**. The runtime therefore blocks a new prompt Loop when it detects an active dedicated Goal for that session.
 
-```powershell
-opencode-loopd install-task --project "C:\path\to\project" --every 10m --prompt-file loop-prompt.md --name OpenCodeLoop
+Recommended choices are to finish/pause the Goal or use a separate session. Advanced users can deliberately override the guard with:
+
+```text
+/loop --allow-goal-overlap continue
 ```
 
-Remove it:
+That escape hatch can create competing autonomous turns; use it only when that is intentional.
 
-```powershell
-opencode-loopd uninstall-task --name OpenCodeLoop
-```
+Loop's older experimental `/loop-goal*` commands remain available for compatibility unless installed with `--without-loop-goals`. For new strongly verified Goal work, prefer:
 
-## Experimental Loop Goal Mode
+```bash
+npx -y @bybrawe/opencode-goal@latest
+```
 
-Loop’s original Goal Mode remains available for existing users by default. If you install/update Loop with `--without-loop-goals`, its packaged `/loop-goal*` command definitions are removed while the rest of Loop keeps working.
+## Recommended development loop
 
 ```text
-/loop-goal --check "npm test" --complete-when-checks-pass fix the failing tests
+/loop --name dev --ask-never --safe --no-overlap --batch 5 --compact-every 200m --checkpoint-only --progress-file progress.md Treat progress.md as the project state. Continue with the next unfinished TODO, implement it, mark completed items, add useful follow-up TODOs, run tests/lint/build when available, and keep going while work remains.
 ```
 
-Controls:
+Test/fix loop:
 
 ```text
-/loop-goal-status
-/loop-goal-pause
-/loop-goal-resume
-/loop-goal-clear
-/loop-goal-done <summary>
-/loop-goal-blocked <reason>
+/loop --name testfix --ask-never --safe --verify "npm test" --max-failures 3 Continue from progress.md. If tests fail, analyze the failure, fix it, and run the tests again.
 ```
 
-It supports acceptance criteria, check commands, evidence text, no-progress guards, turn/runtime limits, and reports under:
+## Background daemon
 
-```text
-.opencode/opencode-loop/goals/
+The normal `/loop` plugin is session-bound. `opencode-loopd` pins one exact OpenCode session for daemon iterations and can keep scheduling outside the normal interactive Loop timer lifecycle.
+
+```bash
+opencode-loopd --project . --every 5m --prompt-file loop-prompt.md
 ```
 
-For new work where completion integrity matters, prefer the dedicated **OpenCode Goals** package instead:
+Immediate daemon cadence:
 
 ```bash
-npx -y @bybrawe/opencode-goal@latest
+opencode-loopd --project . --every 0s --prompt "continue from progress.md and implement the next unfinished TODO"
 ```
 
-or:
+Pin a session and limit runs:
 
 ```bash
-npm install -g @bybrawe/opencode-goal@latest
-opencode-goal
+opencode-loopd --project . --session ses_xxx --every 5m --max-runs 20 --timeout 30m --prompt-file loop-prompt.md
+```
+
+Windows Task Scheduler:
+
+```powershell
+opencode-loopd install-task --project "C:\path\to\project" --every 10m --prompt-file loop-prompt.md --name OpenCodeLoop
+opencode-loopd uninstall-task --name OpenCodeLoop
 ```
 
 ## State and checkpoints
 
-Loop runtime state:
+Runtime state and logs:
 
 ```text
 .opencode/opencode-loop/
+.opencode/opencode-loop/loop.log
 ```
 
 Patch checkpoints:
@@ -456,62 +405,27 @@ Patch checkpoints:
 .opencode/opencode-loop/checkpoints/
 ```
 
-Recent plugin events:
+Add `.opencode/opencode-loop/` to `.gitignore` if runtime state should not be committed.
 
-```text
-.opencode/opencode-loop/loop.log
-```
+## Permissions
 
-Add `.opencode/opencode-loop/` to `.gitignore` when you do not want runtime noise committed.
+For unattended work, avoid permanently allowing every shell command. Grant routine read/edit/test operations while keeping destructive commands on ask/deny. `--safe` reduces risk but does not replace OpenCode permission configuration.
 
-## Suggested OpenCode permissions
-
-For unattended loops, avoid granting every shell command permanently. Allow routine read/edit/test operations and keep destructive operations on ask/deny.
-
-Example:
-
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "permission": {
-    "read": "allow",
-    "grep": "allow",
-    "glob": "allow",
-    "todowrite": "allow",
-    "edit": "allow",
-    "bash": {
-      "*": "ask",
-      "git status*": "allow",
-      "git diff*": "allow",
-      "npm test*": "allow",
-      "npm run test*": "allow",
-      "npm run lint*": "allow",
-      "git push*": "ask",
-      "git reset*": "ask",
-      "git clean*": "deny",
-      "rm *": "deny"
-    },
-    "external_directory": "ask"
-  }
-}
-```
-
-`--safe` reduces risk but does not replace careful OpenCode permission configuration.
-
-## Package
+## Package and compatibility
 
 ```text
 @bybrawe/opencode-loop
 ```
 
-The package also installs:
+Stable package peer range:
 
-```bash
-opencode-loop --help
-opencode-loopd --help
+```text
+@opencode-ai/plugin >=1.4.0 <2
 ```
 
-See [CHANGELOG.md](./CHANGELOG.md) for release history.
+The repository contains experimental OpenCode 2 work, but the stable package does not claim full OpenCode 2 parity.
+
+See [docs/SCHEDULING.md](./docs/SCHEDULING.md) for the scheduling contract and [CHANGELOG.md](./CHANGELOG.md) for release history.
 
 ## License