@navels/neal 0.1.0

package/docs/troubleshooting.md

@@ -0,0 +1,152 @@
+# Troubleshooting
+
+Symptom / cause / fix, in the order you'll hit them. Quoted text is what neal
+prints. When in doubt: `neal check`, then `.neal/runs/<run-id>/stderr.log`.
+
+## Install and first run
+
+**Symptom:** install or startup fails on an old Node.
+**Cause:** neal requires Node.js >= 22.13 (`engines`); `.nvmrc` pins `24`.
+**Fix:** `nvm use` in this repo, or upgrade Node before `npm install -g @navels/neal`.
+
+**Symptom:** `pnpm: command not found` when running from source.
+**Cause:** the source path uses pnpm >= 11 via corepack.
+**Fix:** `corepack enable && corepack prepare pnpm@11 --activate`, then `pnpm install`.
+
+**Symptom:** `neal` not found after `pnpm run dev:link`.
+**Cause:** the dev link registers `bin.neal` with the active Node installation only.
+**Fix:** diagnose with `command -v neal` and `npm list -g --depth 0 --link=true`.
+After source changes, `pnpm build` again so the linked command sees `dist/`.
+
+**Symptom:** `neal setup` lists a provider with `- runtime not found`.
+**Cause:** setup detects local runtime surfaces only (the `@openai/codex-sdk`
+entrypoint; an SDK-bundled or on-PATH `claude` executable) — never auth.
+**Fix:** install the provider's SDK/CLI, then rerun `neal setup` and `neal check`.
+
+## Provider auth failures (`neal check`)
+
+`neal check` sends one small prompt per unique configured provider/model
+(interactive TTY only — non-interactive input prints
+`Provider verification skipped: non-interactive input.`). Known failures:
+
+**Symptom:** `Claude Code refused bypass-permissions mode while running as root.`
+**Cause:** the Claude provider uses `permissionMode: bypassPermissions`, which
+Claude Code refuses under root/sudo.
+**Fix:** run neal from a non-root user, then `neal check` again.
+
+**Symptom:** `OpenAI Codex has not trusted this directory yet.`
+**Cause:** the Codex CLI's own per-directory trust prompt has not been answered.
+**Fix:** complete the provider's normal local trust/setup step for the current
+directory (e.g. run the `codex` CLI there once), then `neal check` again.
+
+**Symptom:** `OpenAI Codex could not persist the check session.`
+**Fix:** transient; run `neal check` again. If it repeats, redo the provider's
+local setup.
+
+**Symptom:** a `not logged in` message from either vendor CLI.
+**Cause:** provider auth is provider-owned; neal never collects credentials.
+**Fix:** complete the provider's normal local auth setup (the `codex` / `claude`
+login flows), then `neal check` again.
+
+**Symptom:** `Set providers.openai_compatible.base_url (or OPENAI_COMPATIBLE_BASE_URL) and OPENAI_COMPATIBLE_API_KEY before running Neal.`
+(or `No model is resolvable for the openai-compatible ... role`).
+**Cause:** `openai-compatible` / `generic-agentic` resolve settings config-first
+with env fallbacks: `base_url` → `OPENAI_COMPATIBLE_BASE_URL`; the key is read
+from the env var named by `api_key_env` (default `OPENAI_COMPATIBLE_API_KEY`);
+model from `agent.<role>.model` → `default_model` → `OPENAI_COMPATIBLE_MODEL`.
+**Fix:** set the missing key. For OpenRouter: `base_url: https://openrouter.ai/api/v1`,
+`api_key_env: OPENROUTER_API_KEY`, and export `OPENROUTER_API_KEY`. (OpenRouter
+wraps upstream 429s in HTTP-200 bodies; neal unwraps and retries them.)
+
+## Runs that won't start
+
+**Symptom:** plan validation errors such as
+`Missing required `## Execution Shape` section.` or
+``## Execution Shape` must contain exactly one non-empty line.`
+**Cause:** every executable plan must declare exactly one of
+`executionShape: one_shot | multi_scope | multi_scope_unknown`; `multi_scope`
+also requires an `## Execution Queue` with contiguous `### Scope N:` headings,
+each carrying `- Goal:` / `- Verification:` / `- Success Condition:` bullets.
+**Fix:** see [plan-format.md](plan-format.md), or let `neal plan` refine the
+document into executable shape.
+
+**Symptom:** a missing-config error naming `agent.coder.provider` or
+`agent.reviewer.provider`.
+**Cause:** fresh writer runs require explicit coder and reviewer providers;
+built-in defaults are not enough.
+**Fix:** `neal setup`, then `neal check`.
+
+**Symptom:** `Cannot start neal execute with a dirty worktree:` followed by
+`git status` lines (queues: `Cannot continue neal run with a dirty worktree:`).
+**Cause:** writer admission requires a clean worktree; only the selected plan
+document and neal-owned paths (`.neal/`) are exempt. Leftover reviewer scratch
+(`build_review/`, `scratch/`, …) gets a
+`Likely Neal reviewer scratch leakage detected:` diagnostic but still blocks —
+the paths are not proven neal-owned.
+**Fix:** use `neal resume` for in-progress scope work, or commit, stash, move,
+or remove the dirty paths and start clean.
+
+**Symptom:** a Git precondition error before any provider runs.
+**Fix:** writer commands require a Git repository with an existing `HEAD`
+commit; create the initial baseline commit first.
+
+## Stuck or blocked runs
+
+**Symptom:** the run stops with `status: "blocked"` (exit code 2).
+**Cause:** blocked is a controlled state, not a failure: the coder hit
+something it may not resolve alone, and attended runs wait for guidance.
+**Fix:** `neal status` explains the blocker and prints the exact
+`neal resume --run <run-id> --message "..."` command. `--message` is only
+accepted in that waiting-for-guidance state.
+
+**Symptom:** `effectiveStatus: "waiting_for_manual_gate"`.
+**Cause:** the scope reached expected human work; instructions are in the
+run-local `GATE-<id>.md` file shown by `neal status`.
+**Fix:** do the manual step, then `neal resume --run <run-id>` — it re-runs
+the gate's checks and resumes the scope when they pass. No `--message` here.
+
+**Symptom:** a run seems hung or died silently.
+**Where to look:** raw detail is persisted even when hidden from the terminal:
+`.neal/runs/<run-id>/stderr.log` (full transcript) and
+`.neal/runs/<run-id>/events.ndjson` (event log; startup-silence retries appear
+as `provider.turn_liveness_*` events). On a live TTY, press `v` for the
+low-level detail view. `neal status --json --run <run-id>` carries the latest
+`providerError` classification.
+
+## Lock issues
+
+The writer lock is `.neal/active-run.lock`; writer processes remove it on
+normal shutdown and on SIGINT/SIGTERM.
+
+**Symptom:** `another Neal writer run is active in this checkout`.
+**Fix:** as printed — `neal resume --run <run-id>` to continue that run, or
+wait for it to finish.
+
+**Symptom:** `another Neal process is already resuming this run` (with
+`owning pid`). A live same-run lock under another pid is refused, not shared.
+**Fix:** wait for that process, or inspect with `neal status --run <run-id>`.
+
+**Symptom:** `stale Neal writer lock found in this checkout` /
+`no process with that PID is running on this host.`
+**Fix:** `neal resume --run <run-id>` clears stale same-host locks itself; if
+you're starting different work instead, inspect the run, then remove the lock
+file the message names.
+
+**Symptom:** `Neal writer lock belongs to another host`.
+**Fix:** inspect the other host before removing the lock; the message prints
+the exact resume command for that checkout.
+
+**Symptom:** `could not read the active Neal writer lock`.
+**Fix:** as printed: inspect the named lock file before starting another
+writer run; remove it only after confirming no writer process is active.
+
+## "It squashed when I didn't want it to"
+
+**Symptom:** per-scope commits are gone after a completed run.
+**Cause:** completed `neal execute` / `neal run` runs squash run-owned commits
+by default, without confirmation.
+**Fix:** pass `--no-squash` to keep individual commits. The squashed range is
+recorded in `.neal/runs/<run-id>/SQUASH_RESULT.json` and under `squash`
+(`originalBaseCommit` / `replacementCommit`) in `neal status --json`.
+Standalone `neal squash` is the opposite: it previews, requires interactive TTY
+confirmation, and preserves later commits by replaying them on top.

package/examples/compat/add-edit-verify/PLAN.md

@@ -0,0 +1,29 @@
+# Compat fixture: fix `add`
+
+## Execution Shape
+
+executionShape: one_shot
+
+## Objective
+
+`src/add.js` exports an `add(a, b)` helper that is supposed to return the sum of
+its two arguments, but it currently returns the difference. The test in
+`test/add.test.js` fails because of this bug.
+
+Make the smallest complete change to `src/add.js` so that `add(a, b)` returns the
+sum of `a` and `b`, then confirm the test passes.
+
+## Boundaries
+
+Allowed paths:
+
+- `src/add.js`
+
+Forbidden:
+
+- Do not edit the test file.
+- Do not add dependencies or new files.
+
+## Verification
+
+Run `node --test test/add.test.js`; it must exit `0`.

package/examples/compat/add-edit-verify/broken.diff

@@ -0,0 +1,8 @@
+diff --git a/src/add.js b/src/add.js
+index 4125f75..a3e4914 100644
+--- a/src/add.js
++++ b/src/add.js
+@@ -1,2 +1,2 @@
+ // Trivial compat fixture: this addition helper is intentionally buggy.
+-export const add = (a, b) => a - b;
++export const add = (a, b) => a * b;

package/examples/compat/add-edit-verify/good.diff

@@ -0,0 +1,8 @@
+diff --git a/src/add.js b/src/add.js
+index 4125f75..0088c50 100644
+--- a/src/add.js
++++ b/src/add.js
+@@ -1,2 +1,2 @@
+ // Trivial compat fixture: this addition helper is intentionally buggy.
+-export const add = (a, b) => a - b;
++export const add = (a, b) => a + b;

package/examples/compat/add-edit-verify/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "@navels/neal-compat-add-edit-verify",
+  "private": true,
+  "type": "module"
+}

package/examples/compat/add-edit-verify/src/add.js

@@ -0,0 +1,2 @@
+// Trivial compat fixture: this addition helper is intentionally buggy.
+export const add = (a, b) => a - b;

package/examples/compat/add-edit-verify/test/add.test.js

@@ -0,0 +1,9 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { add } from '../src/add.js';
+
+test('add returns the sum of two numbers', () => {
+  assert.equal(add(2, 3), 5);
+  assert.equal(add(10, 4), 14);
+});

package/examples/compat/is-even-add-test/PLAN.md

@@ -0,0 +1,30 @@
+# Compat fixture: replace the placeholder test
+
+## Execution Shape
+
+executionShape: one_shot
+
+## Objective
+
+`src/is-even.js` exports a correct `isEven(n)` helper. Its test in
+`test/is-even.test.js` is only a placeholder that always fails
+(`assert.ok(false, ...)`).
+
+Replace the placeholder assertion with a real test that exercises `isEven` —
+asserting `isEven(4)` is `true` is enough — so the test suite passes. Keep the
+existing `test(...)` block; only the placeholder assertion needs to change.
+
+## Boundaries
+
+Allowed paths:
+
+- `test/is-even.test.js`
+
+Forbidden:
+
+- Do not edit `src/is-even.js` (it is already correct).
+- Do not add dependencies or new files.
+
+## Verification
+
+Run `node --test test/is-even.test.js`; it must exit `0`.

package/examples/compat/is-even-add-test/broken.diff

@@ -0,0 +1,11 @@
+diff --git a/test/is-even.test.js b/test/is-even.test.js
+index 52c2a94..0e9eec5 100644
+--- a/test/is-even.test.js
++++ b/test/is-even.test.js
+@@ -5,5 +5,5 @@ import { isEven } from '../src/is-even.js';
+ 
+ test('isEven identifies even numbers', () => {
+   // TODO: replace this placeholder with a real assertion on isEven.
+-  assert.ok(false, 'TODO: replace this placeholder with a real test for isEven');
++  assert.equal(isEven(4), false);
+ });

package/examples/compat/is-even-add-test/good.diff

@@ -0,0 +1,11 @@
+diff --git a/test/is-even.test.js b/test/is-even.test.js
+index 52c2a94..28d1d73 100644
+--- a/test/is-even.test.js
++++ b/test/is-even.test.js
+@@ -5,5 +5,5 @@ import { isEven } from '../src/is-even.js';
+ 
+ test('isEven identifies even numbers', () => {
+   // TODO: replace this placeholder with a real assertion on isEven.
+-  assert.ok(false, 'TODO: replace this placeholder with a real test for isEven');
++  assert.equal(isEven(4), true);
+ });

package/examples/compat/is-even-add-test/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "@navels/neal-compat-is-even-add-test",
+  "private": true,
+  "type": "module"
+}

package/examples/compat/is-even-add-test/src/is-even.js

@@ -0,0 +1,3 @@
+// Trivial compat fixture: this helper is already correct. The work is to add a
+// real test in place of the placeholder.
+export const isEven = (n) => n % 2 === 0;

package/examples/compat/is-even-add-test/test/is-even.test.js

@@ -0,0 +1,9 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { isEven } from '../src/is-even.js';
+
+test('isEven identifies even numbers', () => {
+  // TODO: replace this placeholder with a real assertion on isEven.
+  assert.ok(false, 'TODO: replace this placeholder with a real test for isEven');
+});

package/examples/compat/manifest.json

@@ -0,0 +1,60 @@
+{
+  "fixtures": [
+    {
+      "id": "add-edit-verify",
+      "roles": ["coder", "reviewer"],
+      "projectDir": "add-edit-verify",
+      "planDoc": "add-edit-verify/PLAN.md",
+      "verifyCommand": "node --test test/add.test.js",
+      "referenceFix": { "file": "src/add.js", "from": "a - b", "to": "a + b" },
+      "reviewer": {
+        "goodDiff": "add-edit-verify/good.diff",
+        "brokenDiff": "add-edit-verify/broken.diff"
+      }
+    },
+    {
+      "id": "reverse-grep-edit",
+      "roles": ["coder", "reviewer"],
+      "projectDir": "reverse-grep-edit",
+      "planDoc": "reverse-grep-edit/PLAN.md",
+      "verifyCommand": "node --test test/strings.test.js",
+      "referenceFix": {
+        "file": "src/strings.js",
+        "from": "s.split('').join('')",
+        "to": "s.split('').reverse().join('')"
+      },
+      "reviewer": {
+        "goodDiff": "reverse-grep-edit/good.diff",
+        "brokenDiff": "reverse-grep-edit/broken.diff"
+      }
+    },
+    {
+      "id": "is-even-add-test",
+      "roles": ["coder", "reviewer"],
+      "projectDir": "is-even-add-test",
+      "planDoc": "is-even-add-test/PLAN.md",
+      "verifyCommand": "node --test test/is-even.test.js",
+      "referenceFix": {
+        "file": "test/is-even.test.js",
+        "from": "assert.ok(false, 'TODO: replace this placeholder with a real test for isEven');",
+        "to": "assert.equal(isEven(4), true);"
+      },
+      "reviewer": {
+        "goodDiff": "is-even-add-test/good.diff",
+        "brokenDiff": "is-even-add-test/broken.diff"
+      }
+    },
+    {
+      "id": "plan-greeting",
+      "roles": ["planner"],
+      "projectDir": "plan-greeting",
+      "issuePrompt": "plan-greeting/ISSUE.md",
+      "verifyCommand": "node --test test/greet.test.js",
+      "referenceFix": {
+        "file": "src/greet.js",
+        "from": "`Hello!`",
+        "to": "`Hello, ${name}!`"
+      }
+    }
+  ]
+}

package/examples/compat/plan-greeting/ISSUE.md

@@ -0,0 +1,25 @@
+# Plan seed: fix the greeting helper
+
+## Execution Shape
+
+executionShape: one_shot
+
+## Objective
+
+`src/greet.js` exports `greet(name)`, which should return `Hello, <name>!` but
+currently always returns `Hello!`, ignoring its argument. The test in
+`test/greet.test.js` fails because of this.
+
+Produce a one-shot plan that makes the smallest complete change to `src/greet.js`
+so `greet(name)` returns `Hello, <name>!`, verified by
+`node --test test/greet.test.js` exiting `0`.
+
+## Boundaries
+
+Allowed paths:
+
+- `src/greet.js`
+
+Forbidden:
+
+- Do not edit the test file or add dependencies.

package/examples/compat/plan-greeting/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "@navels/neal-compat-plan-greeting",
+  "private": true,
+  "type": "module"
+}

package/examples/compat/plan-greeting/src/greet.js

@@ -0,0 +1,2 @@
+// Trivial compat fixture used by the planner role: the greeting omits the name.
+export const greet = (name) => `Hello!`;

package/examples/compat/plan-greeting/test/greet.test.js

@@ -0,0 +1,8 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { greet } from '../src/greet.js';
+
+test('greet includes the supplied name', () => {
+  assert.equal(greet('Ada'), 'Hello, Ada!');
+});

package/examples/compat/reverse-grep-edit/PLAN.md

@@ -0,0 +1,32 @@
+# Compat fixture: fix the broken string helper
+
+## Execution Shape
+
+executionShape: one_shot
+
+## Objective
+
+`src/strings.js` exports several small string helpers. Exactly one of them is
+buggy: `reverse(s)` is supposed to return the string with its characters
+reversed, but it returns the string unchanged. The `reverse` test in
+`test/strings.test.js` fails because of this.
+
+Read `src/strings.js`, locate the faulty `reverse` helper, and make the smallest
+complete change so it returns the reversed string. Do not touch the other
+helpers, which already pass their tests.
+
+## Boundaries
+
+Allowed paths:
+
+- `src/strings.js`
+
+Forbidden:
+
+- Do not edit the test file.
+- Do not change the other (already-correct) helpers.
+- Do not add dependencies or new files.
+
+## Verification
+
+Run `node --test test/strings.test.js`; it must exit `0`.

package/examples/compat/reverse-grep-edit/broken.diff

@@ -0,0 +1,12 @@
+diff --git a/src/strings.js b/src/strings.js
+index c338691..fbfe71b 100644
+--- a/src/strings.js
++++ b/src/strings.js
+@@ -5,6 +5,6 @@ export const upper = (s) => s.toUpperCase();
+ export const lower = (s) => s.toLowerCase();
+ 
+ // BUG: this does not actually reverse the string.
+-export const reverse = (s) => s.split('').join('');
++export const reverse = (s) => s.split('').join('-');
+ 
+ export const repeat = (s, n) => s.repeat(n);

package/examples/compat/reverse-grep-edit/good.diff

@@ -0,0 +1,12 @@
+diff --git a/src/strings.js b/src/strings.js
+index c338691..d17fc16 100644
+--- a/src/strings.js
++++ b/src/strings.js
+@@ -5,6 +5,6 @@ export const upper = (s) => s.toUpperCase();
+ export const lower = (s) => s.toLowerCase();
+ 
+ // BUG: this does not actually reverse the string.
+-export const reverse = (s) => s.split('').join('');
++export const reverse = (s) => s.split('').reverse().join('');
+ 
+ export const repeat = (s, n) => s.repeat(n);

package/examples/compat/reverse-grep-edit/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "@navels/neal-compat-reverse-grep-edit",
+  "private": true,
+  "type": "module"
+}

package/examples/compat/reverse-grep-edit/src/strings.js

@@ -0,0 +1,10 @@
+// Trivial compat fixture: several string helpers live here. Exactly one of them
+// is buggy, so an agent must read/grep to locate the faulty function.
+export const upper = (s) => s.toUpperCase();
+
+export const lower = (s) => s.toLowerCase();
+
+// BUG: this does not actually reverse the string.
+export const reverse = (s) => s.split('').join('');
+
+export const repeat = (s, n) => s.repeat(n);

package/examples/compat/reverse-grep-edit/test/strings.test.js

@@ -0,0 +1,15 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { lower, repeat, reverse, upper } from '../src/strings.js';
+
+test('upper/lower/repeat helpers are correct', () => {
+  assert.equal(upper('abc'), 'ABC');
+  assert.equal(lower('ABC'), 'abc');
+  assert.equal(repeat('ab', 3), 'ababab');
+});
+
+test('reverse returns the string reversed', () => {
+  assert.equal(reverse('abc'), 'cba');
+  assert.equal(reverse('neal'), 'laen');
+});

package/examples/issue-triage-js/PLAN.md

@@ -0,0 +1,83 @@
+# Issue Triage Example Improvement Plan
+
+## Execution Shape
+
+executionShape: multi_scope
+
+## Objective
+
+Improve this dependency-free JavaScript issue-triage example in small, reviewable
+steps. Keep the package local to this directory and keep every scope verifiable
+with the example's built-in Node test suite.
+
+## Boundaries
+
+Allowed paths:
+
+- `examples/issue-triage-js/src/issue-triage.js`
+- `examples/issue-triage-js/test/issue-triage.test.js`
+- `examples/issue-triage-js/README.md`
+
+`examples/issue-triage-js/PLAN.md` may be updated only if Neal's
+plan-refinement loop makes a necessary structural clarification.
+
+Forbidden paths and work:
+
+- Do not edit Neal runtime source under `src/`.
+- Do not edit root documentation, root package metadata, workflows, benchmark
+  files, or other repository-level files.
+- Do not add dependencies, lockfiles, generated artifacts, provider transcripts,
+  or `.neal/` artifacts to Git.
+- Do not call live network services from tests or package code.
+
+## Current Behavior
+
+The seed implementation parses simple lines such as
+`- [P1] auth: Login fails @web #bug #customer`, summarizes counts, and formats a
+short markdown report. It intentionally leaves several realistic edge cases for
+this plan to improve.
+
+## Execution Queue
+
+### Scope 1: Add parser edge-case tests and support lowercase priorities, leading/trailing whitespace, and `*` bullets
+- Goal: Add focused parser tests, then update `parseIssueLine` and `parseIssues` so issue lines can use lowercase priorities, leading or trailing whitespace, and either `-` or `*` bullets while preserving normalized `P1`-style priorities.
+- Verification: Run `pnpm test` from `examples/issue-triage-js/`.
+- Success Condition: Parser tests cover the new edge cases, the implementation handles them, existing baseline parsing still works, and the example test suite passes.
+
+Implementation notes:
+
+- Keep comments and blank lines ignored by `parseIssues`.
+- Preserve the exported function names.
+- Do not broaden the parser beyond issue-triage lines needed by this example.
+
+### Scope 2: Add summary tests and fix optional owners, `unassigned` owner grouping, duplicate tag handling, and deterministic ordering
+- Goal: Add summary-focused tests, then update parsing and summarization so owners are optional, missing owners are counted as `unassigned`, duplicate tags on one issue are counted once, and summary count objects are built in deterministic key order.
+- Verification: Run `pnpm test` from `examples/issue-triage-js/`.
+- Success Condition: Summary tests cover optional owners, duplicate tags, and deterministic ordering; `summarizeIssues` returns stable counts by priority, area, owner, and tag; and the example test suite passes.
+
+Implementation notes:
+
+- Keep `parseIssueLine` returning `owner: null` for issues without an owner.
+- Apply the `unassigned` grouping in `summarizeIssues`.
+- Prefer simple deterministic ordering over a new dependency.
+
+### Scope 3: Add formatter tests and make `formatSummary(summary)` produce deterministic markdown sorted by priority, area, owner, and tag
+- Goal: Add formatter tests, then update `formatSummary(summary)` so its markdown sections are deterministic and sorted by priority, area, owner, and tag.
+- Verification: Run `pnpm test` from `examples/issue-triage-js/`.
+- Success Condition: Formatter tests cover stable section ordering, sorted entries, and empty sections where relevant; `formatSummary(summary)` produces deterministic markdown; and the example test suite passes.
+
+Implementation notes:
+
+- Keep the report compact and readable.
+- Do not change the summary object shape unless the tests require a small
+  backward-compatible clarification.
+
+### Scope 4: Update the example README or sample usage to match the final behavior and keep the example tests passing
+- Goal: Update `examples/issue-triage-js/README.md` or its sample usage so the documentation matches the final parser, summarizer, and formatter behavior.
+- Verification: Run `pnpm test` from `examples/issue-triage-js/`.
+- Success Condition: The README or sample usage accurately reflects the final behavior, does not direct users outside the example directory for code edits, and the example test suite passes.
+
+Implementation notes:
+
+- Keep the README focused on running and understanding this example.
+- Do not document behavior that the tests do not cover.

package/examples/issue-triage-js/README.md

@@ -0,0 +1,76 @@
+# Issue Triage JavaScript Example
+
+This is a tiny dependency-free JavaScript package for trying Neal against a
+real but small codebase. The seed package already has passing tests and a
+limited implementation. `PLAN.md` asks Neal to improve the parser, summary, and
+formatter across four local scopes.
+
+The package parses issue lines shaped like:
+
+```text
+- [P1] auth: Login fails @web #bug #customer
+```
+
+## Requirements
+
+- Node.js 22 or newer
+- pnpm
+- A Git repository with an initial commit before running Neal
+- Configured Neal providers for the live `neal run` path
+
+## Non-Live Verification
+
+From the repository root:
+
+```sh
+pnpm --dir examples/issue-triage-js test
+```
+
+From this example directory:
+
+```sh
+pnpm test
+```
+
+These commands use Node's built-in test runner. They do not call Neal, use
+provider credentials, or spend model budget.
+
+## Live Neal Run
+
+Use a disposable branch or worktree so the example changes are easy to inspect
+or discard.
+
+From the repository root:
+
+```sh
+neal setup
+neal check
+cd examples/issue-triage-js
+neal run PLAN.md
+pnpm test
+```
+
+Use `neal run --no-squash PLAN.md` when you want to inspect the per-scope
+commits Neal creates during the run.
+
+`neal run` uses the providers configured by `neal setup`. It can take time and
+may spend provider budget. Passing the local tests before the run does not
+guarantee that a live provider-backed run will complete successfully.
+
+Normal repository CI validates this example through non-live tests and package
+checks without running providers.
+
+## Manual Canary Workflow
+
+Maintainers can dispatch the `Example Canary` GitHub Actions workflow when they
+want a live provider-backed smoke test for this example. The workflow is
+manual-only, uses the `example-canary` environment, and requires the
+environment to provide `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or both depending
+on the selected coder and reviewer providers.
+
+The canary builds Neal, writes a temporary `~/.neal/config.yml` from the
+selected provider roles, runs the example baseline tests, runs
+`node ../../dist/neal/index.js run PLAN.md --no-squash` from this directory,
+and uploads only curated markdown support artifacts from the example-local
+`.neal/` directory. Scheduled canaries are deferred until cost and flakiness are
+understood from intentional manual runs.