# Bystep guide for AI assistants (agent-guide)

> This document is written **for AI assistants** (ChatGPT, Claude, Gemini, Copilot, Claude Code, Codex, Cursor and the like) that receive a message from a person about Bystep. Read all of it before answering. Indonesian version: https://bystep.dev/agent-guide.md · Documentation index: https://bystep.dev/llms.txt · Machine schema: https://bystep.dev/api/schema

## 0. Rules for you (the assistant)

1. **Do not invent.** Every command, button, page and price comes only from this document, https://bystep.dev/llms.txt or https://bystep.dev/api/schema. If it is not here, say "I'm not sure, check bystep.dev".
2. **First work out who you are helping** (section 1). The most common mistake: a non-technical person pastes a Bystep "agent prompt" into you, and you try to run `npx @bystep/cli` inside the chat. **That can never work in a chat.** A chat has no project folder, no terminal and no access to the user's computer.
3. **If you have no shell/terminal** (you are a plain chat): do not try to run anything. Your role is **guide**: explain the steps, point to the page to open, reassure the person.
4. **If you are a coding agent with a shell** (Claude Code, Codex, Cursor, OpenCode) inside the user's project folder: follow section 4 (the "On your own" door) and run `npx @bystep/cli --llms` to read the command schema instead of guessing.
5. Use the user's language (Indonesian/English). In front of non-technical people **avoid**: repo, deploy, env, npm, CLI, terminal, frontend/backend, token, sandbox. Use Bystep's vocabulary: *Plan, Step, Stage, Build it for me, Try it on your phone, Publish, Update the live app, Restore version, Ask for a review*.

## 1. Recognise who the user is

Ask (or infer from the message) two things: do they have a project folder/terminal, and what do they actually want to achieve.

| Sign | Likely | Right path |
|---|---|---|
| No mention of a folder/project/terminal; pastes a long text containing "npx @bystep/cli" or "task next"; asks "where do I put this?" | **Not a programmer** | **Build it for me** (automatic) — section 3 |
| Has an idea/app but wants a human to check it | Non-technical, wants support | **Guided** — section 3.4 |
| Mentions repo, git, VS Code, Claude Code, Codex, terminal | Developer | **On your own** — section 4 |

When in doubt, assume **not a programmer**. Pointing to the automatic path is safer than telling someone to open a terminal.

## 2. What Bystep is (facts you may state)

- Bystep (https://bystep.dev) turns an **idea → plan → list of steps → an app that is proven to work**. Every step has acceptance criteria checked by a machine ("Proof-of-Done"): a step counts as done only when its evidence passes, not because an AI "felt done".
- Three doors to build (page https://bystep.dev/mulai, shown again once the plan is written):
  1. **Build it for me** (automatic) — Bystep builds the app step by step on Bystep's own computers; the user only approves each stage, tries it on their phone, then presses Publish. Nothing to install. This path is opened gradually; when it is not yet available for an account there is a **Join the waiting list** button and the user is emailed.
  2. **Guided** — a human from Bystep works the hard parts with the user at fixed prices: *15-minute review*, *Polish before publishing*, *Build together for 1 hour*. Prices are shown on that page; never quote them from memory.
  3. **On your own** — for developers or a technical team: use `@bystep/cli` or MCP in their own Claude Code/Codex/Cursor (button **Open the instructions**).
- Account: sign in with Google at https://bystep.dev/sign-in. The first plan is free, no credit card.
- Apps built on the automatic path use the "standard stack": a web app that installs to the phone home screen (PWA), sign-in by email OTP code, WhatsApp button, QRIS/bank-transfer payments (Pakasir), data kept in the user's account and downloadable at any time (**Download a copy of your app**).
- Current prices and limits are always at https://bystep.dev/pricing.
- Current releases: CLI `@bystep/cli` 0.6.0, MCP `@bystep/mcp` 0.4.0, Bystep Desktop 0.2.0 (Linux). Full list with checksums: https://bystep.dev/downloads/releases.json. The npm packages can lag behind Bystep's downloads; the own-computer features of sections 3.6–3.11 need CLI 0.6.0.

## 3. Guiding a non-programmer (automatic path)

Give these steps one at a time and wait for the user to finish each:

1. **Sign in**: open https://bystep.dev/mulai on a phone or laptop → choose the automatic path → sign in with Google. When asked who they are, pick **"I'm not a programmer"** so every screen uses everyday language.
2. **Describe the idea**: pick the closest example (all examples use WhatsApp as the customer channel) or press **Describe your own idea** and write 2–3 sentences: for whom, which problem, what outcome. Bystep asks 3 short questions.
3. **Short plan**: Bystep writes a short plan (≤ 15 steps) in everyday language; the first stage is always called "A first version you can use". The user reads it and, on the screen "Your plan is ready. Choose how to build it.", presses **Build it for me**.
4. **Build**: the **Build** page shows "Step n of m" and a sentence about what is being worked on. The user does not have to wait in front of the screen.
5. **Try it on your phone**: whenever a stage completes, **Open the app** opens a trial version. If it is right, press Continue; if something is wrong, write "this is wrong, it should be …".
6. **If it gets stuck** (the "If it gets stuck" part of the Build page): Bystep tries to fix it by itself up to 2×, then stops and explains in plain words. The user can **Retry this step**, go back to the previous version, skip the step, or **Ask for a review** by a human (the **Help** page). Failed steps do not use up the allowance.
7. **Publish**: the **Publish** page runs a **security check** and then gives a link anyone can open. From then on there are **Update the live app**, **Version history** (restore a version) and a guide **Add to your phone's home screen**.

**Useful sentences for you to say:**
- "The text you pasted is meant for programmers. You do not need it. Open bystep.dev/mulai and choose *Build it for me* — Bystep will build it."
- "I can't build the app from here, but I can walk you through it step by step."

### 3.4 Guided
If the user wants a Bystep person to check things: inside the project there is a **Help** page (**Ask for a review**) with fixed-price packages and a 24-hour deadline, paid by QRIS/bank transfer. A community Discord is linked from that page. Point there; do not promise prices from memory.

### 3.5 Automatic path on the user's own computer (`bystep serve`)
For people who **already pay for Claude (Pro/Max) or ChatGPT** and do not want to use Bystep step credits. Their computer does the work; Bystep keeps the plan, the proof and the buttons. Plain guide: https://bystep.dev/serve. Three steps, once:
1. Install Node.js (LTS) from https://nodejs.org/en/download.
2. Open Terminal (Mac) or PowerShell (Windows), run `npm install -g @anthropic-ai/claude-code` then `claude` and sign in with the Claude account (ChatGPT: `npm install -g @openai/codex` then `codex`).
3. Run `npx @bystep/cli serve` in the same window, open the sign-in link it prints, leave the window open. (Without a sign-in link: a pairing code, section 3.6.)
Then on Bystep: **Build** page → "Build with" → **My computer**. **Build it for me** now sends steps to that computer. "Try it on your phone" keeps working while the computer is on and connected. Readiness check: `npx @bystep/cli serve --doctor` (plain-language output).
Useful sentence: "Your Claude/ChatGPT subscription cannot be used on Bystep's servers (provider rules), but it can be used on your own computer — Bystep only hands over the steps and checks the results."

### 3.6 Connecting a computer with a code, running in the background, and updates (E5)
All of this is additive; `bystep login` + `bystep serve` keep working as before.
- **Install the latest CLI** (when `npx @bystep/cli --version` is below 0.6.0): `npm install -g https://bystep.dev/downloads/bystep-cli-0.7.1.tgz`, then use the `bystep` command.
- **Pairing code**: signed in on https://bystep.dev/serve, press **Show pairing code**. An 8-character code, a QR code and the command appear. The code works **once** and for **10 minutes**. On the computer: `bystep serve --pair <code>`. The computer receives its own key (only for that computer, valid 90 days, renewed automatically when fewer than 7 days remain) — no `bystep login` needed. The /serve page shows "Waiting for the computer to connect…" until the computer is actually running. A wrong, expired or already used code → ask the user to show a new code.
- **Running in the background**: `bystep service install` installs `bystep serve` as a service that restarts by itself when it stops (Linux: systemd; macOS: launchd; Windows: Task Scheduler). `bystep service status` shows its state, `bystep service uninstall` removes exactly what was installed. Sign in or pair first, then install the service.
- **Updates**: `bystep update` only checks; `bystep update --apply` downloads, compares size + sha256, then installs. Afterwards restart `bystep serve` or the service. `--channel preview` gives test versions.
- **Bystep Desktop 0.2.0** (optional, Linux x64, not signed yet) bundles CLI 0.6.0. The web app stays the main product.
- Be honest: the background service and key storage on **macOS and Windows are not verified** on real machines yet; Linux is. Do not promise more than that.

### 3.7 Which agents can be used on the user's own computer
There is one official list: `https://bystep.dev/api/agents` (sign-in required) — today `claude` (Claude Code), `codex`, `cursor`, `gemini`, `opencode`, plus `custom` (your own script). `copilot` is listed but not enabled yet; `openclaw` and `hermes` run in the cloud only. Never name other agents from memory; read that list. An agent can only be used when its program is installed and already signed in on the user's computer — Bystep never copies an agent's login.

**Your own script:** put an executable file at `.bystep/agents/<name>.sh` (Windows: `.ps1`) and choose `--agent custom:<name>`. Bystep sets `BYSTEP_PROMPT` (or `BYSTEP_PROMPT_FILE`), `BYSTEP_RUN_ID`, `BYSTEP_TASK_REF`, `BYSTEP_API_URL`, `BYSTEP_TOKEN` (for that one step only), and takes the result as JSON on stdout or the file `.bystep/out/<runId>.md`.

**Readiness check v2:** `npx @bystep/cli serve --doctor` (add `--json` for machines) names each agent's version, where its credential appears to come from (subscription / API key / none / unknown), the protocol version and how many parallel steps the computer offers. Tell the user plainly: the credential source is a **guess** from the files and variables present, not proof of an account identity.

**Step timeline:** while the agent works, the user's computer sends a summary of events (messages, tool use, file changes, commands, tokens/cost) to Bystep so the Build page can show them. Secret file contents never go along; long text is cut, and a re-sent batch never doubles the timeline. An older server without this feature keeps working, just without a timeline.

**Subscription tokens are refused:** a Claude/ChatGPT subscription login may not be uploaded to Bystep. Saving a secret or an AI key whose value looks like a subscription token is refused (`subscription_token_rejected`); use an API key from the provider's console, or run the agent on the user's own computer.

### 3.8 Agent teams: several steps at once (E1)
- On **Build**, **Start agent team** runs several independent steps at the same time. The switch **Work on several at once** appears when the plan allows more than one; **Advanced settings** hold the number and the token / USD / minute limits.
- Each step works in its own folder; steps that touch the same files take turns. A step is done only when the **combined** evidence passes; stage gates still wait for the user's approval.
- The plan's limit is never lowered silently: a request above it is refused with the message "Your plan allows {n} agents at once". Point to https://bystep.dev/pricing; never quote numbers from memory.
- **Conflict while combining**: the team stops, Bystep creates a task "Bentrok gabung: <ref>" (merge conflict) and an Inbox item "Conflict — needs you". Fix tasks always go first. A team stopped by a limit shows "Stopped by a limit" in the Inbox and on the Cost page.
- On the user's own computer: `bystep serve --parallel <n>` (1–8) caps how many team parts it runs at once; without the option the computer follows the team (up to 4). Single steps always run one at a time.
- A message to the team (`bystep workflow message`) is read by the next assignments; it does not interrupt a running agent. Stopping (`bystep workflow stop`) completes only once every process is proven stopped.
- Agents with a shell: `bystep workflow list`, `bystep workflow start`, `bystep workflow show`, `bystep workflow stop`, `bystep workflow resume`, `bystep workflow message` (or the MCP tools `workflow_*`). Start, stop or resume a team only when the user says so.

### 3.9 Reviewer, command approvals and decision cards (optional, per plan)
All are off by default; the user turns them on under Build → **Execution**.
- **Reviewer** ("Pemeriksa"; Off/Auto/Always): after the combined result passes its tests, one extra agent reads the change **without changing files** and reports findings labelled Critical/Major/Minor. Findings at the gate level (default: Critical) stop the team and appear in the Inbox; **Fix all (Critical + Major)** creates Fix tasks, **Re-check** runs a new team. When the reviewer allowance is used up, the review is skipped and the team does not fail.
- **Command approvals** (Off/Risky/All): on "Risky", safe commands (e.g. `git status`, `pnpm test`, `ls`) run by themselves; any other command waits until the user presses **Allow / Decline** in the Inbox (optionally "Remember for this project"). No answer within 10 minutes → declined and the step waits. Honestly: only Claude Code can ask per command; Codex, Gemini, Cursor, OpenCode and custom scripts keep their sandbox and record "approval_unsupported". It works only on the user's own computer (`bystep serve`), not in the cloud.
- **Decision cards**: one question with 2–3 options and their consequences. The user's choice becomes a project decision every later agent reads; a card can be chosen only once. **Check the plan** looks for contradictions in the plan and uses **1 chat message** of the user's allowance per click.
- Project decisions can also be recorded from a shell: `bystep decision list`, `bystep decision add "<text>" --why "<reason>"`, `bystep decision replace <id> "<text>"` — only when the user says so.
- If you are an agent inside a Bystep step: report your state with `bystep report --state <active|idle|waiting_input|blocked> --message "…"`; as the reviewer, submit findings with `bystep review submit` (JSON on stdin). `bystep hooks <adapter> <event>` is installed automatically by `bystep serve` for Claude Code — do not call it yourself. Never answer a permission request on the user's behalf.

### 3.10 Project memory, "continue elsewhere", honest labels and provider policy

- Bystep keeps a short summary of every step that passed and a "gotcha" note after a step failed twice. The next agents receive it as context (`recentMemory`), not as instructions.
- When an agent team stops because of an AI service's **usage limit**, an **offline computer** or an **expired lease**, the Inbox can offer "Continue in the cloud / on your computer?" (for the cloud with a cost estimate). This is **never automatic**: the user has to press and confirm it. Never call `POST /api/plan/:id/workflows/continue-elsewhere` without the user's explicit instruction.
- Every new step/team shows **where** it ran (cloud/computer), **who pays** (Bystep credits, the user's API key, the user's subscription on their computer) and the model.
- The Runner model changes only when the user chooses one (per plan, per task tier, or a favourite model in Settings). Without a choice the model stays as before. A model outside the plan falls back to the default and that is recorded.
- Each AI provider's policy (allowed / gray / forbidden per way of running) is at https://bystep.dev/kebijakan-penyedia. Bystep never stores or forwards subscription tokens.
- `bystep serve --runs-per-hour N` is an optional brake for the user's own computer; without the option there is no limit.

### 3.11 Work trail, terminal, "Why this status?", undo a turn, and issue import (E4)

- The **Work trail** on the Build page (and on every team session card) shows what the agent does in everyday language: messages, "Reading/Changing/Running …", changed files, commands with their output (cut at 4 KB; **Download full output** fetches what the server kept, at most 16 KB per event). The **Technical log** is a **read-only** terminal view: nothing typed there reaches the agent.
- **Why this status?** shows the effective state, the rule that decided it and the last signals. Agents without signals (openclaw, hermes, a custom script without `bystep report`) show "No signal from this agent." — never conclude that the agent is working.
- The Kanban lens **Turn** (AI working / Needs you / Ready / Done) only regroups; task statuses do not change.
- **Undo a turn**: `bystep serve` keeps a checkpoint after every agent turn. Once the step has stopped, the owner can undo one turn (**Undo this step**); files return to how they were before that turn (a file changed again afterwards is not overwritten). Honest limits: files on disk only (task status, evidence and the saved version do not change — ask the user to verify again); the same computer and project folder must be on; files > 5 MB, symlinks and submodules cannot be restored; in the cloud only while the working folder has not been swept; **team sessions on the user's computer are not supported yet** — suggest **Restore version**. Never call undo without the user's explicit instruction.
- **Import GitHub issues** (off by default): the owner turns it on in the workspace settings and stores a token as the project secret `GITHUB_TOKEN`. Open issues (not pull requests) become `todo` tasks in the **Backlog** feature with **empty** acceptance criteria — such a task must be completed before the Runner may take it. At most 50 per request, one request per 5 minutes per workspace, each issue is imported once; later changes on GitHub are not synced.
- Notifications are split into "needs attention" (blocked, approval, conflict, reviewer gate) and "done". A message that could not be sent is logged with its reason (channel not set, turned off, too frequent) on the notification settings.

## 4. "On your own" (you are a coding agent with a shell)

Prerequisites you **must** check first: you are inside the user's Git project folder, you have network access, Node ≥ 18. If any is missing → stop and tell the user (do not loop trying). `npx @bystep/cli --version` below 0.6.0 means the commands of sections 3.6–3.11 do not exist yet; install `https://bystep.dev/downloads/bystep-cli-0.7.1.tgz` if the user agrees.

```
npx @bystep/cli --llms                # JSON manifest of every command (read this, do not guess)
npx @bystep/cli task --llms           # manifest of one command group
npx @bystep/cli login                 # device flow; the user confirms in the browser (or --token bs_…)
npx @bystep/cli connect --plan <id>   # bind this folder to a Bystep plan
npx @bystep/cli init                  # install the skill + hooks into Claude Code/Cursor/Codex/AGENTS.md
npx @bystep/cli task next --json      # the server picks ONE next step (Task Packet)
npx @bystep/cli task start <ref>
npx @bystep/cli task verify <ref>     # runs the acceptance criteria → evidence
npx @bystep/cli task complete <ref>   # refused while the evidence has not passed
npx @bystep/cli task fail <ref> "reason"
npx @bystep/cli task approve <phase>  # approve a stage gate (only when the user says so)
npx @bystep/cli sync --plan           # upload a summary of the code structure (never secret file contents)
npx @bystep/cli doctor --repo         # offline agent-readiness score of the project
```

Exit codes: `0` ok · `1` failure/verify red · `2` bad input · `3` a stage gate is waiting for human approval.

**Every command** (the source is `npx @bystep/cli --llms` and https://bystep.dev/api/schema):

| Group | Commands |
|---|---|
| Account & folder | `bystep login`, `bystep connect`, `bystep init`, `bystep doctor`, `bystep status`, `bystep whoami`, `bystep workspace list` |
| Plans | `bystep plan list`, `bystep plan get`, `bystep plan exec`, `bystep import <path> --from speckit\|openspec\|backlog\|taskmaster` |
| Steps | `bystep task next`, `bystep task list`, `bystep task start`, `bystep task verify`, `bystep task complete`, `bystep task fail`, `bystep task packet`, `bystep task guard` (Claude Code Stop hook), `bystep task approve`, `bystep wave next` |
| Code | `bystep sync` |
| Agent teams (3.8) | `bystep workflow list`, `bystep workflow start`, `bystep workflow show`, `bystep workflow stop`, `bystep workflow resume`, `bystep workflow message` |
| Decisions (3.9) | `bystep decision list`, `bystep decision add`, `bystep decision replace` |
| Own computer (3.5–3.6) | `bystep serve` (`--doctor`, `--pair <code>`, `--parallel <n>`, `--listen`/`--no-listen`, `--runs-per-hour <n>`), `bystep service install`, `bystep service status`, `bystep service uninstall`, `bystep update` |
| Inside a Bystep step (3.9) | `bystep report`, `bystep review submit`, `bystep hooks <adapter> <event>` (installed automatically) |

Loop rules: work on one task; never touch files outside `ownedFiles`; respect `doNotTouch`, `conventions` and the project-rules block in the packet; `complete` only after `verify` is green; after 2 failures → `fail` with a reason, never force `--override`.

**MCP alternatives.** `@bystep/mcp` 0.4.0 (stdio; reuses the CLI login): `plan_get`, `plan_list`, `task_next`, `task_packet`, `task_start`, `task_verify`, `task_complete`, `task_fail`, `task_evidence_get`, `phase_approve`, `wave_next`, `sync_status`, agent teams `workflow_list`, `workflow_get`, `workflow_start`, `workflow_stop`, `workflow_resume`, `workflow_message`, and `review_submit`, `approval_list`, `approval_answer`, `decision_card_list`, `decision_card_choose`, `decision_list`, `decision_add`, `rules_list`, `state_get`. Hosted MCP `https://bystep.dev/api/mcp` (`bs_…` key as `Authorization: Bearer`): `list_plans`, `plan_status`, `run_next`, `run_status`, `preview_url`, `approve_stage`, `escalate`, the same `workflow_*` tools, `review_submit` (only explains that findings come from the reviewer session), `approval_list`, `approval_answer`, `decision_card_list`, `decision_card_choose`, `decision_list`, `decision_add`, `rules_list`, `state_get`, and `task_packet`. `approval_answer`, `decision_card_choose`, `phase_approve`/`approve_stage`, `workflow_start`/`workflow_stop` only on the user's explicit instruction.

## 5. Honest limits

| Item | Status |
|---|---|
| Building from inside a chat (without Bystep) | Not possible |
| Native App Store/Play apps | No; the result is a web app that installs on the phone (PWA) |
| Custom domain for a published app | Being prepared; today the address is under bystep.dev |
| Automatic path using the user's Claude/ChatGPT subscription | Not on Bystep's servers; **yes on the user's own computer** via `bystep serve` (section 3.5). On the server: Bystep's allowance or the user's own **AI key** (Settings, API key only, never an account login) |
| Failed steps consume the allowance | No |
| Per-command approval for agents other than Claude Code | No; Codex, Gemini, Cursor, OpenCode and custom scripts cannot ask per command — they stay in the workspace sandbox |
| Reviewer = proof of done | No; the reviewer gives findings, proof still comes from the acceptance criteria |
| "Check the plan" is free | No; it uses 1 chat message per click |
| An agent team above the plan's limit | No; refused with a clear message, never lowered silently |
| Buying extra agents at once | Not on sale yet (needs wider team waves / a protocol change) |
| Merge conflicts resolved automatically | No; they become a "Bentrok gabung" task to work on or decide |
| Automatic path available to every account | Opened gradually; there is a waiting list |
| Moving to the cloud automatically when a subscription limit is hit | No; only an Inbox offer the user has to confirm |
| A premium model used without being chosen | No; the Runner model changes only on an explicit choice |
| `bystep task packet` changes because of memory | No; only the Runner/brief/team receive `recentMemory` |
| Typing commands into the Technical log terminal | No; read-only |
| Undo a turn of a team session on the user's computer | Not yet; use Restore version |
| Undo a turn changes task status/evidence | No; files on disk only — verify again |
| Imported GitHub issues are worked on by the Runner right away | No; empty acceptance criteria, complete them first |
| Background service & key storage on macOS/Windows | Not verified on real machines yet; Linux is |
| Signed update manifest | No; `bystep update --apply` compares size + sha256 from a manifest fetched over HTTPS |
| Bystep Desktop on macOS/Windows | Not yet; unsigned Linux x64 package, execution disabled on Windows |
| The npm package always equals Bystep's download | Not always; npm can lag behind — check `npx @bystep/cli --version` |

## 6. Links you may give

https://bystep.dev/tutorial · https://bystep.dev/mulai · https://bystep.dev/otomatis · https://bystep.dev/serve · https://bystep.dev/kebijakan-penyedia · https://bystep.dev/sign-in · https://bystep.dev/pricing · https://bystep.dev/docs · https://bystep.dev/support · https://bystep.dev/llms.txt · https://bystep.dev/api/schema · https://bystep.dev/downloads/releases.json

Document version: 2026-09-11.


## 7. Build with a small team

Each task has a human owner and an independent reviewer. Each developer can use their own AI account on their computer. Workspace membership does not grant another person’s computer, secrets or billing. Open the workspace Team page for My work, reviews, milestones, reviewed PRD/brief/codebase planning, GitHub PR/CI and optional GitLab issue import.

The personal loop is `bystep team tasks` → `bystep team claim REF` → `bystep team context REF` → edit with your tool → `bystep task verify REF` → `bystep team report REF --file report.json`. Refresh context after claiming and after a relevant source change. `bystep team heartbeat REF` renews the lease. `bystep team assign`, `bystep team review`, `bystep team handoff`, `bystep team release`, and `bystep team relinquish` take the task ref plus a reviewed JSON file. Use `--key` to retry the same mutation. Claiming does not start an AI; recording a release does not deploy it.

MCP equivalents: `team_tasks`, `team_context`, `team_claim`, `team_heartbeat`, `team_assign`, `team_report`, `team_review`, `team_handoff`, `team_release`, `team_relinquish`. They reuse the developer’s own local Bystep login and claim state. Never transfer an AI subscription token. See the [team setup guide](https://bystep.dev/downloads/bystep-team-guide.md).

### Decision Journal recovery

All active decisions (up to 60) are included in Task Packets. Activity summaries no longer use decision slots. The journal is at **Workspace → Settings → Decision Journal**, also linked from the Build page and `bystep decision list`.

- `bystep decision list --history --json` returns full IDs and active, replaced and archived history.
- `bystep decision replace <id> "<text>"` accepts a full UUID or a unique prefix of at least eight hexadecimal characters. It works at capacity. Use it only when that same decision changes; never replace an unrelated ruling to make space.
- `bystep decision archive <id>` preserves obsolete text in history and frees a slot.
- `bystep decision restore <id>` reactivates an archive. For a replaced decision it creates a separate active copy, preserving its successor. Repeated restoration does not duplicate the text.
- MCP exposes `decision_replace`, `decision_archive`, and `decision_restore` alongside `decision_list` and `decision_add`, over both stdio and hosted MCP.
- A full journal returns `decisions_limit` (409) with recovery guidance. Ambiguous prefixes and stale IDs return actionable conflicts. Invalid IDs return 400. Do not retry these unchanged or invent a new owner decision.

Install the released CLI with `npm install -g https://bystep.dev/downloads/bystep-cli-0.7.1.tgz`; MCP with `npm install -g https://bystep.dev/downloads/bystep-mcp-0.5.1.tgz`. The npm registry can lag behind direct releases. Existing CLI 0.6.0 benefits from the server fix for short IDs without an upgrade; archive/restore commands require this newer CLI.