Feat/sokoban visual

.agents/skills/add-agent-recipe/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: add-agent-recipe
+description: Add or update runnable use-case recipes for existing System1-Agents agents, with setup, inference-backend configuration, independent result checks, demo evidence and troubleshooting. Use for recipe authoring; use build-s1a-agent when the task needs a new agent implementation.
+---
+
+# Add an agent use-case recipe
+
+Read the target checkout's local instructions, [CONTRIBUTING.md](../../../CONTRIBUTING.md),
+[recipe index](../../../recipes/README.md) and [template](../../../recipes/TEMPLATE.md).
+Recipes live at `recipes/<use-case>/README.md`, with small safe fixtures beside them.
+
+Resolve the concrete task, existing agent/front and observable completion check. Trace its state source,
+enumerated choices, execution tools and evaluator; do not assume a `DONE` signal establishes success.
+If it needs a new runtime behavior or backend integration, identify that separate scope before presenting
+a runnable recipe for it.
+
+Check the actual CLI, extras, environment precedence and artifact paths. State the decision model's
+checkpoint/revision and library or serving engine separately from the chat model's role. For System1-Omni,
+verify both worker support and the agent client's modality/question/window/hardware contract. Pin both
+repositories and record a missing client or configuration instead of inventing a supported command.
+
+Write one complete setup → run → verify path, then clearly identified alternatives. Use a bounded task and
+independent result check; include errors, incomplete work and incorrect actions in the check. Label key-free
+rule/scripted controls separately from learned-model inference. State required credentials by variable name
+and expected downloads or external calls. Keep demonstrations outside measured benchmark runs.
+
+Validate links, fixture schema and example flags against the implementation. Exercise the recipe only within
+the task's authorized resources and budgets; follow applicable GPU reservation and experiment rules. Record
+source revisions/local modifications, fixture hashes, environment, exact commands and raw results. Label
+command-only checks and untested profiles explicitly. One working demo is not a quality or performance claim.
+
+Prepare the demo using [the video guide](../../../CONTRIBUTING.md#agent-video-demos), including captions,
+trace links and actual engine provenance. For important PRs, require a video of the application/task,
+System1-Agents decision-model agent and System1-Omni inference in the same run, as in the linked PR #35 example.
+Choose the relevant computer/browser/embodied/game/routing/guardrail application from the guide's README candidates.
+A rule control or in-process run does not fulfill that requirement. Record missing support/resources as a
+review gap and keep the PR draft unless a maintainer accepts the documented exception.
+Retain failures, interventions and replay speed/source. Add the recipe to the index and link reusable
+shared documentation rather than copying it. Use the
+[self-review skill](../self-review/SKILL.md) for the final contributor report. Recipe authoring does not itself
+authorize live model calls, downloads or external publication.

.agents/skills/self-review/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: self-review
+description: Self-review System1-Agents changes before opening a PR or requesting review, with reproducible task outcomes, appropriate demos, and evidence-backed claims.
+---
+
+# System1-Agents self-review
+
+Read the target checkout's `CONTRIBUTING.md`, PR template, and applicable local
+instructions. Record the actual target branch and base/head commits, and review
+the full diff from their merge base plus relevant uncommitted changes. Distinguish
+what is in the PR from local-only work; disclose if the base could not be refreshed.
+
+Apply the [large-code-change requirements](../../../CONTRIBUTING.md#large-code-changes):
+report authored-code and total diff counts separately using the guide's counting
+convention. Above 3,000 changed code lines, verify the contributor's full
+self-review, split rationale, component map/review order, and validation across
+affected components and interfaces before recommending readiness. A quick
+precheck is insufficient; keep the PR draft until the contributor self-review is
+complete. Report missing preparation as a readiness gap; size alone is not a
+correctness finding or a reason to require expensive model/GPU runs.
+
+Check correctness, focused scope, decision-model and front contracts, fallback
+behavior, cancellation/timeouts, and resource cleanup as relevant. Verify tests
+cover the changed behavior, including failure paths and a regression case for a
+fix. Match docs and commands to the implementation. Run the applicable checks in
+`CONTRIBUTING.md`; report exact commands, outcomes, and skipped checks with reasons.
+Documentation-only changes need link/example/claim checks, not unrelated model runs.
+For use-case recipes, check the [recipe template](../../../recipes/TEMPLATE.md): commands reach the named
+agent/backend, result checks can detect failure, and each profile's validation status matches its evidence.
+
+This skill prepares a local contributor report. It does not itself authorize
+edits, commits, pushes, external posts, paid model calls, downloads, or changes to
+review status. Use only separately authorized execution resources and budgets.
+
+## Committed artifact hygiene
+
+Apply this check in every review, including quick prechecks. Inspect added and
+changed artifacts in the complete diff, including JSON/JSONL, CSV, logs, reports,
+source/binary hash inventories, and generated media. Classify them by purpose and
+actual consumer, rather than rejecting a file extension.
+
+- Keep necessary configuration, request examples, maintained benchmark inputs,
+  and small deterministic fixtures or reference oracles in the repository's
+  intended locations. Identify the test, tool, or documented workflow that needs
+  each retained artifact, such as labelled agent datasets or replay inputs.
+- Flag one-off run summaries, response dumps, cache statistics, profiler output,
+  agent process notes, and duplicate historical results that have no maintained
+  source-tree role. A link from PR prose or documentation alone does not justify
+  committing generated run output. Report concrete paths and consumers.
+- Preserve raw measurements, failures, and provenance in a durable artifact
+  archive or PR/CI evidence, and link the exact revision or run from the summary.
+  Do not discard evidence to reduce the diff or hide it in a committed archive.
+- When removing redundant output, check its callers, links, and reproduction
+  commands. Keep replay inputs and expected responses intact; verify their
+  hashes and rerun the affected replay or documentation checks.
+
+## Task evidence
+
+For changes to what an agent can accomplish, show a concrete task as **input →
+actions → final result**. Define success using an observable outcome, not just a
+`DONE` signal. Use a safe, reproducible scenario or fixture; include setup,
+commands, inputs/seed, model and configuration, environment, and exact source
+commits. Link the resulting logs or artifacts so a reviewer can trace the story.
+
+When claiming improvement, compare baseline and head on the same tasks, inputs,
+success criteria, and budgets. Report completion counts/denominators, elapsed
+time, model calls and tool calls when measured. Include cost only if measured,
+with the accounting scope and pricing basis; do not infer total cost from latency
+or an incomplete token charge. Keep failures, retries, timeouts, and human
+intervention in the results. Report repetitions and variation; one successful
+demo is not a task-success rate. Mark missing metrics unmeasured, and remove or
+qualify unsupported claims rather than manufacturing a comparison.
+
+Use [CONTRIBUTING.md's video guide](../../../CONTRIBUTING.md#agent-video-demos)
+to classify the PR and prepare, record and attach its demo. Important PRs require
+a video of the application/task, System1-Agents decision-model agent and actual
+System1-Omni inference in the same run. Check all three parts against the linked
+trace; a terminal recording works for text agents and rails. Screenshots and logs
+support the clip. Use PR #35's recording linked in the guide as the example and
+choose a relevant README application candidate from the guide. Show the
+relevant input, action sequence, and result, with failures or human intervention
+visible. Label cuts, replay speed, and elapsed timing honestly; link a fuller
+trace when a clip omits context. Do not stage screens or present a replay as a
+live run. A replay must identify the source
+run/commit, workload, and speed; a historical or upstream model demo is not proof
+that the current agent integration works.
+
+Choose figures that answer the review question: workflow screenshots, a short
+action timeline, or task-success comparisons backed by the run records. There is
+no asset quota. Only the guide's minor docs/formatting/test-only exemption permits
+`N/A` with a reason; a nonvisual task still needs a terminal video when the PR is
+important. If a required run cannot be made within the available authorization,
+resources, or budget, report the gap and its impact; keep the important PR draft
+until the video is supplied or a maintainer accepts
+the documented exception. Do not turn a missing run into a pass or require a
+production-scale demonstration.
+
+## PR demo/evidence section
+
+Prepare a **Demo / evidence** section for the PR containing what applies:
+
+- Required application + agents + Omni video and trace, or the documented exemption/blocker.
+- Task and observable result, or `N/A` for an exempt change with a concrete reason.
+- Reproduction command/fixture, configuration, and baseline/head commits.
+- Measured comparison and raw result links, including failures and limitations;
+  distinguish personally run checks, author-reported results, and observed CI.
+- Demo/figure links with captions stating the workload, source revision, and
+  whether each item is an actual run, recorded replay, or explanatory illustration.
+
+Make evidence reusable for accurate reviews and public updates without implying
+permission to publish it elsewhere. Before attaching assets, check ownership,
+license/attribution, and permission to share. Use safe sample data and redact
+credentials, private URLs, personal/customer information, and sensitive screen or
+log content. Verify redaction in the final exported files, captions, and metadata.
+Keep useful measurement context after redaction. Clearly label diagrams, mockups,
+and generated artwork as illustrations; never fabricate screens, results, or
+performance claims. Link durable, reviewer-accessible artifacts rather than local
+paths. If rights or safe disclosure are unresolved, omit the asset and state why.
+
+Check System1-Omni's current model, modality and hardware support as described in
+the video guide. Use a supported serving path for the required video when the
+branch has a compatible client; otherwise record the missing integration or
+configuration. Pin both repositories and verify the actual worker/frontend from run evidence. Keep
+agent-task evidence separate from serving/kernel measurements. Do not add an
+unrequested backend integration or run outside the authorized resources/budget
+merely to produce a demo.
+
+## Report
+
+Lead with actionable findings and file/line references, then the reviewed scope,
+commands/results, demo/evidence summary, and remaining gaps. Say when there are no
+actionable findings without implying maintainer approval. Keep blocking gaps
+visible and recommend a draft while they remain. Do not check the contributor's
+boxes or publish on their behalf without separate authorization.

.claude/skills/build-s1a-agent/SKILL.md

@@ -76,4 +76,21 @@ key-free rung is the offline test from step 4. The paid rung follows. A browser
 needs the chat-model key and a Jev key: `uv run s1a run <name> --model jev --goal "..."`. A rail runs its
 labelled set and needs a Jev key: `uv run s1a run <name> --labelled-set records.jsonl`.
 
-Report the table and stop. Series of a hundred episodes cost money; ask the user before starting one.
+Report the table, then prepare the demo/evidence handoff below. Series of a hundred episodes cost money;
+ask the user before starting one.
+
+## 6. Demo and handoff
+
+For a reusable use case, add a recipe using [the recipe template](../../../recipes/TEMPLATE.md) and
+[add-agent-recipe skill](../../../.agents/skills/add-agent-recipe/SKILL.md), then update the recipe index.
+Follow [CONTRIBUTING.md's video guide](../../../CONTRIBUTING.md#agent-video-demos)
+for the required video of the application/task, the System1-Agents decision-model agent and System1-Omni
+inference in the same run. Show actual input, selected/executed actions, engine identity and checked result.
+Choose an application from the guide's README candidates that exercises the new agent's actual behavior.
+Use a terminal recording for a text agent or rail; label scripted checks and recorded replays.
+Use a supported System1-Omni path; record missing support or integration as a review gap. Follow PR #35's
+worked example linked in the guide. Keep an important PR draft until its video is supplied or a maintainer
+accepts the documented exception.
+Prepare the PR's **Demo / evidence** section with the clip, reproduction command and linked run artifacts.
+Recording, model execution and uploading each require the authorization/resources already established for
+the task. If any are unavailable, report the gap and hand off the prepared instructions.

.claude/skills/review-pr/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: review-pr
+description: Review pull requests for system1-agents with high-confidence, evidence-based feedback. Use when the user asks to review a PR, a diff, or code changes in this repository.
+---
+
+# Review PR
+
+You are a senior maintainer reviewing a pull request for `system1-agents`. Your job is to find real problems that CI cannot prove, not to restate style preferences or summarize the diff.
+
+CodeRabbit reads this file as review guidelines (`.coderabbit.yaml`), so the quality contract and the review focus
+below apply to its comments on every pull request. The process and the output format are for a review run by hand,
+for example by a maintainer with Claude Code; CodeRabbit keeps its own comment layout.
+
+## Quality contract
+
+Every comment must satisfy all six criteria:
+
+1. **Correct** — the issue is real and reproducible.
+2. **Prioritized** — label as `blocker`, `major`, `minor`, or `nit`.
+3. **Actionable** — include a concrete fix or next step.
+4. **Evidence-backed** — cite file, line, test, or command.
+5. **Concise** — one problem per comment; no essays.
+6. **Calibrated** — if uncertain, say so; do not assert.
+
+If a comment cannot meet all six, omit it.
+
+## Review focus for this repository
+
+- **System 1 decision path**: Jev invocation, model selection, fallback behavior, and deterministic replay.
+- **Multi-model comparison**: benchmark fairness, random seeds, caching, concurrency, and result aggregation.
+- **Async/concurrency**: asyncio cancellation, timeouts, resource cleanup, and race conditions.
+- **Public API compatibility**: type hints, backward compatibility, and documented behavior.
+- **Tests**: new tests cover edge cases, error paths, model-unavailable scenarios, and regressions.
+- **Performance**: token usage, latency, memory, and unnecessary model calls.
+- **Security**: API keys, prompt injection, log redaction, and dependency changes.
+
+## Process
+
+1. For a pull request, read its title and description and every issue it closes or links. For a branch with no pull
+   request, ask the user for the change's purpose and any issues it addresses before reviewing. Then read the changed
+   files.
+2. Check the change against its purpose, and report a mismatch like any other finding:
+   - the diff fixes the symptom the issue describes;
+   - nothing changes that the issue and description do not call for;
+   - nothing the issue or description asks for is missing;
+   - the description says what the diff does.
+
+   With no linked issue, check against the description, or against the purpose the user gave for a branch without a
+   pull request, and say there is no issue.
+3. Run or inspect the relevant tests when possible.
+4. Identify only issues that CI cannot prove.
+5. Produce a short review with at most 5 high-confidence comments.
+6. If there are no blocking issues, say so explicitly.
+
+## Output format
+
+```
+## Review summary
+<one paragraph: what changed and overall risk>
+
+## Findings
+### [blocker|major|minor|nit] <title>
+- **Where**: `path/to/file.py:123`
+- **Evidence**: <test, command, or reasoning>
+- **Why it matters**: <impact>
+- **Suggested fix**: <concrete change>
+
+## Questions
+- <only if genuinely needed>
+```
+
+## Do not
+
+- Do not comment on formatting, naming, or style unless it causes a bug.
+- Do not repeat CI failures.
+- Do not speculate without evidence.
+- Do not approve or request changes on behalf of a human maintainer.

.coderabbit.yaml

@@ -0,0 +1,64 @@
+# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
+# CodeRabbit reviews each non-draft pull request when it opens and again on every push. The criteria come from
+# .claude/skills/review-pr/SKILL.md, which the knowledge base below reads as a guideline file.
+language: en-US
+tone_instructions: "Short and plain. Evidence first: cite the file, the line and the scenario that breaks."
+
+reviews:
+  profile: chill
+  poem: false
+  sequence_diagrams: false
+  assess_linked_issues: true
+  suggested_reviewers: false
+  finishing_touches:
+    docstrings:
+      enabled: false
+    unit_tests:
+      enabled: false
+    autofix:
+      enabled: false
+  auto_review:
+    enabled: true
+    drafts: false
+    auto_pause_after_reviewed_commits: 0
+    ignore_usernames:
+      - dependabot[bot]
+  path_filters:
+    - "!uv.lock"
+    - "!evals/results/**"
+    - "!evals/showcase/**"
+  path_instructions:
+    - path: "s1a/**/*.py"
+      instructions: |
+        The System 1 decision path: Jev and local model invocation, model selection, fallback behavior and
+        deterministic replay. Check asyncio cancellation, timeouts and resource cleanup, and that a public
+        signature, a flag or a documented behavior does not change without the docs and CHANGELOG saying so.
+    - path: "evals/**"
+      instructions: |
+        Benchmark fairness: the same seeds, inputs and budget on every arm, no caching that favors one model,
+        and result aggregation that cannot drop a failed run. A number in a doc must match the record it cites.
+    - path: "docs/**"
+      instructions: |
+        A number in a doc must match the record it cites (the archives under docs/results/ and the files under
+        evals/), and a flag, an environment variable or a command in a doc must match what the code does now.
+    - path: "tests/**"
+      instructions: |
+        Edge cases, error paths and model-unavailable scenarios. A test that cannot fail, or that needs a key
+        or the network, is a finding: nothing in the suite may need either.
+    - path: ".github/workflows/**"
+      instructions: |
+        Security first. Flag pull_request_target or issue_comment jobs that check out or run pull request code,
+        any ${{ }} expression of untrusted text (titles, bodies, branch names, model output) inside a run
+        script, secrets handed to steps that do not need them, and permissions wider than the job uses.
+    - path: "pyproject.toml"
+      instructions: |
+        A new or changed extra must agree with the extras table in CONTRIBUTING.md, and a new agent's extra is also
+        listed in EXTRAS in s1a/run.py (the other extras, such as laya, cua, report and dev, are not agents and
+        are not listed there). CI checks uv.lock and the review does not see it, so do not comment on the lock.
+
+knowledge_base:
+  code_guidelines:
+    enabled: true
+    filePatterns:
+      - .claude/skills/review-pr/SKILL.md
+      - CONTRIBUTING.md