| 1 | import type { DocsReviewDict } from "../types"; |
| 2 | |
| 3 | /** |
| 4 | * English reference dictionary for `app/[locale]/docs/review/page.tsx` |
| 5 | * ("Review what changed"). Checked against the slash-command registry |
| 6 | * (`/diff`, `/restore`, `/undo`, `/review`, `/export`), the workspace |
| 7 | * snapshot module (crates/tui/src/snapshot/mod.rs), `ReviewArgs` in |
| 8 | * crates/tui/src/lib.rs, and docs/RECEIPTS.md. |
| 9 | */ |
| 10 | export const docsReview: DocsReviewDict = { |
| 11 | metaTitle: "Review what changed · Codewhale Docs", |
| 12 | metaDescription: |
| 13 | "See every file Codewhale changed in a session, roll the workspace back to an earlier turn, get a code review of a diff, and keep a receipt of that review.", |
| 14 | bodyClassName: "text-ink-soft leading-relaxed", |
| 15 | title: "Review what changed", |
| 16 | lede: |
| 17 | "Codewhale shows you each edit as it happens and keeps a snapshot of your workspace before and after every turn. Use this page to check what changed, put files back, and get a second opinion before you push.", |
| 18 | sections: [ |
| 19 | { |
| 20 | id: "diff", |
| 21 | title: "See the changes", |
| 22 | blocks: [ |
| 23 | { |
| 24 | p: "Every file edit appears in the transcript as a diff when it is made. To see everything at once, run:", |
| 25 | }, |
| 26 | { code: "/diff", lang: "Codewhale" }, |
| 27 | { |
| 28 | p: "`/diff` shows all changes since this session started. Your own git history is untouched, so `git diff` and `git status` work as usual.", |
| 29 | }, |
| 30 | ], |
| 31 | }, |
| 32 | { |
| 33 | id: "restore", |
| 34 | title: "Roll files back to an earlier turn", |
| 35 | blocks: [ |
| 36 | { |
| 37 | p: "Before and after each turn, Codewhale snapshots the workspace into a separate git store. It never writes to your repository's own `.git`, and it works in folders that are not git repositories.", |
| 38 | }, |
| 39 | { |
| 40 | code: `/restore # list the 20 most recent snapshots |
| 41 | /restore list 50 # list more (up to 100) |
| 42 | /restore 1 # put files back to the newest snapshot`, |
| 43 | lang: "Codewhale", |
| 44 | }, |
| 45 | { |
| 46 | p: "Restoring changes files, so it needs a trusted workspace (`/trust on`) or Full Access; anyone can list snapshots. You can also just ask — “undo your last edit” — and Codewhale can roll back its own turn.", |
| 47 | }, |
| 48 | { |
| 49 | p: "`/undo` is different: it removes the last exchange from the conversation. Use `/restore` when you want files back.", |
| 50 | }, |
| 51 | { |
| 52 | note: "Snapshots are kept for 7 days. A workspace larger than 2 GB skips snapshots and Codewhale tells you once; raise `[snapshots] max_workspace_gb` in config if you want them anyway. If git is missing or the disk is full, the turn still runs without a snapshot.", |
| 53 | }, |
| 54 | ], |
| 55 | }, |
| 56 | { |
| 57 | id: "code-review", |
| 58 | title: "Get a code review", |
| 59 | blocks: [ |
| 60 | { |
| 61 | p: "Inside a session, `/review` runs a structured review of a file, a diff, or a pull request. From the shell, `codewhale review` reviews a git diff and prints findings:", |
| 62 | }, |
| 63 | { |
| 64 | code: `codewhale review # unstaged changes in the working tree |
| 65 | codewhale review --staged # what you are about to commit |
| 66 | codewhale review --base origin/main # everything on this branch |
| 67 | codewhale review --pr 123 # a GitHub pull request (needs gh)`, |
| 68 | lang: "Terminal", |
| 69 | }, |
| 70 | { |
| 71 | p: "Add `--path <file>` to review one path, `--model` to pick the reviewer, or `--json` for machine-readable output. A diff over 200,000 characters is refused rather than cut short; raise the limit with `--max-chars`.", |
| 72 | }, |
| 73 | { |
| 74 | note: "`--post` publishes the review as a comment on the pull request. Without it, nothing leaves your terminal except the model request.", |
| 75 | }, |
| 76 | ], |
| 77 | }, |
| 78 | { |
| 79 | id: "receipts", |
| 80 | title: "Keep a receipt of the review", |
| 81 | blocks: [ |
| 82 | { |
| 83 | p: "A review receipt records what was reviewed and what the review found, so you can prove the diff you push is the diff that was reviewed.", |
| 84 | }, |
| 85 | { |
| 86 | code: `codewhale review --base origin/main --write-receipt |
| 87 | codewhale review --base origin/main --check-receipt`, |
| 88 | lang: "Terminal", |
| 89 | }, |
| 90 | { |
| 91 | list: [ |
| 92 | "`--write-receipt` saves a local JSON file after a successful review: a fingerprint of the diff, the provider and model, finding counts, unresolved risk, and a hash of the review text. It does not store the diff itself.", |
| 93 | "`--check-receipt` makes no model call. It exits non-zero if the diff has changed since the receipt, if the review left unresolved risk, or if an attached check did not pass — so it works as a pre-push gate.", |
| 94 | "`--receipt-path <file>` writes or reads a specific receipt instead of the latest one.", |
| 95 | ], |
| 96 | }, |
| 97 | { |
| 98 | note: "Receipts cover code reviews today. A receipt for an ordinary agent turn — every tool call, approval, and file change in one export — is designed but not built yet.", |
| 99 | }, |
| 100 | ], |
| 101 | }, |
| 102 | { |
| 103 | id: "export", |
| 104 | title: "Save the whole session", |
| 105 | blocks: [ |
| 106 | { |
| 107 | p: "To keep or share the full record of a session, export it:", |
| 108 | }, |
| 109 | { |
| 110 | code: `/export clipboard # a redacted copy of this session |
| 111 | /export file notes/session.md # the same, written to a file |
| 112 | codewhale sessions export <id> # full archive: messages, tool calls, results, artifacts`, |
| 113 | lang: "Codewhale / Terminal", |
| 114 | }, |
| 115 | { |
| 116 | p: "`codewhale sessions` lists saved sessions and their ids. The archive holds the complete context, so treat it like source code.", |
| 117 | }, |
| 118 | ], |
| 119 | }, |
| 120 | ], |
| 121 | next: [ |
| 122 | { |
| 123 | href: "/docs/modes", |
| 124 | label: "Set modes and approvals", |
| 125 | note: "Choose whether Codewhale asks before it edits or runs anything.", |
| 126 | }, |
| 127 | { |
| 128 | href: "/docs/fleet", |
| 129 | label: "Run a workflow", |
| 130 | note: "Repeatable, multi-step work with a record of every run.", |
| 131 | }, |
| 132 | { |
| 133 | href: "/docs/troubleshooting", |
| 134 | label: "Fix a problem", |
| 135 | note: "What to do when a turn stalls, a key fails, or a session will not resume.", |
| 136 | }, |
| 137 | ], |
| 138 | sourceNote: |
| 139 | "Source documents: docs/RECEIPTS.md, docs/CONFIGURATION.md ([snapshots]), crates/tui/src/snapshot/mod.rs · Update docs-map.ts when changing.", |
| 140 | }; |
| 141 |