rangers 0.6.1__tar.gz

rangers-0.6.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AlexKay28
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rangers-0.6.1/MANIFEST.in

@@ -0,0 +1,6 @@
+include LICENSE
+include README.md
+include SKILL.md
+include docs/cheatsheet.png
+include docs/*.md
+include scripts/cheatsheet.py

rangers-0.6.1/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: rangers
+Version: 0.6.1
+Summary: Agent-as-a-library: drive headless coding-agent harnesses from Python
+Author: AlexKay28
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/AlexKay28/ranger
+Project-URL: Documentation, https://github.com/AlexKay28/ranger/tree/main/docs
+Project-URL: Repository, https://github.com/AlexKay28/ranger
+Project-URL: Issues, https://github.com/AlexKay28/ranger/issues
+Keywords: agent,ai,automation,codex,coding-agent,opencode
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: twine>=6.0; extra == "dev"
+Dynamic: license-file
+
+# ranger
+
+![CI](https://github.com/AlexKay28/ranger/actions/workflows/ci.yml/badge.svg)
+
+Agent-as-a-library. Run the [opencode](https://opencode.ai) or
+[codex](https://github.com/openai/codex) coding agents headlessly from plain
+Python code — for agentic-loop prototyping. You write code, not chat.
+
+The whole design follows one paradigm: **the agent is a function call —
+Python owns the loop, the harness is just the data plane.** Plan → act →
+check → repeat maps 1:1 onto expression, statement and condition. See
+[docs/PARADIGM.md](docs/PARADIGM.md) for the seven laws every feature is
+reviewed against.
+
+AI coding agents: start with [SKILL.md](SKILL.md) for the library's safe
+workflow, contracts, and repository contribution rules.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/AlexKay28/ranger/main/docs/cheatsheet.png" alt="ranger command cheatsheet" width="760">
+</p>
+
+## Install
+
+```bash
+pip install rangers
+```
+
+The distribution is named **`rangers`** on PyPI; the Python import remains
+`import ranger`. For development from a clone: `pip install -e .[dev]`.
+Maintainers: see the [publishing checklist](docs/PUBLISHING.md) before any
+release.
+
+Requires a harness CLI on PATH: [opencode](https://opencode.ai) (default
+backend) and/or [codex](https://github.com/openai/codex). On a distro-pegged
+pip (e.g. 22.x) an editable install can fail with "build backend is missing
+the build_editable hook" — fix the tool, not the package:
+`pip install -U pip`, then retry.
+
+## Quick start (no clone needed)
+
+Straight from GitHub, then a one-line sanity check in your terminal:
+
+```bash
+pip install git+https://github.com/AlexKay28/ranger
+
+python -c "import ranger; print(ranger.Ranger.models(match='claude'))"
+```
+
+The check needs no model or API budget — it just lists what your local
+opencode CLI offers. Got model ids back? You're ready:
+
+```python
+import ranger
+agent = ranger.Ranger(model="<one of the ids above>")
+print(agent.ask("say ok"))
+```
+
+Runnable applications live in [examples/](examples/): quickstart, model
+discovery, a full agentic loop, a self-hosted project-growth loop, plus three
+small day-to-day recipes — repair a red test command, independently review a
+local diff before merge, review one file, and draft release notes from git
+history. They are organized by use case in the
+[examples index](examples/README.md): getting started, code work, monitoring,
+multi-agent, backends, and no-model dummy runs.
+
+Live progress: each command draws a morphing line on stderr while it runs
+(`⠹ search · TODO items in this repo · 00:03`) and settles as
+`✓ search · 00:07 · <first line of answer>` — opencode-wizard style, colors
+included. It auto-disables in pipes/tests and honors `NO_COLOR`;
+turn it off with `pretty=False`.
+
+Model priority: explicit `Ranger(model=...)` → `$RANGER_MODEL` env var →
+package default.
+
+## Usage
+
+```python
+agent = ranger.Ranger(model="openrouter/anthropic/claude-sonnet-4.5")
+agent.summarize("notes.md")          # -> str summary of the file
+agent.write("a one-page report on X")  # -> path of the file the agent wrote
+agent.do("rename all *.txt files in data/ to *.md")  # -> report of CLI-like work
+agent.search("where do we parse config?")            # -> multiline findings report
+agent.ask("anything at all")         # -> raw prompt, raw answer
+agent.check("all tests pass")        # -> YES/NO verdict as a bool
+agent.gate("python -m pytest -q")    # -> exit-code booleans, no model
+agent.until("make the tests green", gate_cmd="python -m pytest -q")
+                                    # -> loop: plan/do/verify until green
+```
+
+Each call is one fresh headless `opencode run` in the agent's working directory
+(`cwd=`), with permissions auto-approved so it can actually touch the filesystem.
+Pass `session="..."` to share context between calls, `model=` to pick any
+`provider/model` ID from `opencode models`.
+
+## Model discovery & configuration
+
+```python
+import ranger
+
+ranger.Ranger.models()                      # -> all model IDs
+ranger.Ranger.models(match="claude")           # -> substring filter
+
+smart = ranger.Ranger(model="openrouter/anthropic/claude-sonnet-4.5")
+fast  = smart.with_config(model="openrouter/google/gemini-2.5-flash", agent="build")
+```
+
+Every command method also accepts per-call overrides:
+
+```python
+fast.search("todo items", title="quick scan")
+smart.do("refactor auth", timeout=1800)
+```
+
+Overridable: `model`, `timeout`, `auto`, `session`, `agent` (opencode agent
+name like "build"/"plan"), `title`, `thinking`. Unknown keywords raise
+`TypeError` so typos fail loudly.
+
+See [docs/commands.md](docs/commands.md) for the full command catalog —
+15 methods at three maturity tiers: what's shipped, what's next, and
+what needs bigger machinery (gates, retries, safety rails) —
+[docs/API.md](docs/API.md) for the complete, per-setting API reference
+(kept mechanically in sync with the code by the test suite), and
+[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for a high-level tour of
+the codebase and its three architectural decisions.
+
+## Context state (memory)
+
+The agent remembers. Every command exchange is recorded to
+`agent.context` in classic OpenAI message format
+(`{"role": "user"|"assistant"|"system", "content": ...}`) and recent
+history (within a character budget) is recalled into later runs — so
+follow-ups like "now do the same for tests/" just work.
+
+```python
+agent.context         # the message list
+agent.context_summarize()   # -> digest of what happened so far
+agent.context_compact()     # collapse history to one system digest
+agent.context_clear()       # wipe; returns what was cleared
+agent.ask("...", memory=False)  # one stateless run
+ranger.Ranger(memory=False)      # or a fully stateless agent
+```
+
+Context memory colors your dialogues, never your facts: `ask`/`do`/`write`
+recall the recent conversation; `check`/`search`/`summarize` always run
+history-independent, so a verdict is about the repo, not the chat
+([PARADIGM.md](docs/PARADIGM.md), law 4).
+
+## Backends (harness adapters)
+
+The same API drives different harnesses; the setting is one constructor
+argument, per-call overridable:
+
+```python
+import ranger
+
+agent = ranger.Ranger(model="openrouter/anthropic/claude-sonnet-4.5")  # opencode (default)
+gpt   = ranger.Ranger(backend="codex")            # model from ~/.codex/config.toml
+gpt   = ranger.Ranger(backend="codex", model="gpt-5.1-codex")
+
+ranger.register_backend("mine", MyHarnessAdapter)  # your own — one small class
+```
+
+Harness differences (flags, sessions, sandboxes, output schemas) are
+absorbed by one adapter class per backend — see the Backends section of
+[docs/API.md](docs/API.md) for the full capability map and the recipe for
+adding your own harness.
+
+## Multi-agent interactions
+
+Two (or three) agents, and the expected patterns as ready-made methods —
+verdicts are grammar, budgets are honest, reviewers run free of their own
+chat history:
+
+```python
+both    = builder.second_opinion(critic, prompt)    # {mine, theirs, differs}
+verdict = critic.review(subject, author=builder)    # APPROVE/REJECT/REQUEST_CHANGES
+outcome = builder.refine_with(critic, goal)          # the two-agent until()
+duel    = critic.challenge(builder)                  # adversarial claim attack
+talk    = ranger.debate(builder, critic, topic, judge=skeptic)
+```
+
+See the Multi-agent interactions section of [docs/API.md](docs/API.md)
+and [`examples/multiagent/multi_agent.py`](examples/multiagent/multi_agent.py).
+
+## Skills allow-list
+
+Grant the agent specific skills or operating rules per run — a markdown
+file or directory rides along via opencode's `--file` attachment; plain
+prose entries are injected as prompt grants.
+
+```python
+agent = ranger.Ranger(skills=[
+    "skills/haiku/SKILL.md",        # file -> --file attachment
+    "skills/pack",                  # dir -> all its *.md attached
+    'Always answer in British spelling',  # prose -> prompt grant
+])
+agent.do("write the changelog", skills=["docs/changelog_style.md"])  # per call
+```
+
+## AGI loop, the point of the whole thing
+
+```python
+agent = ranger.Ranger(model="openrouter/anthropic/claude-sonnet-4.5")
+
+for i in range(10):
+    hits = agent.search(f"TODO and unimplemented spots, pass {i}")
+    plan = agent.ask(f"Pick ONE thing to fix from:\n{hits}\nReply with a one-line fix plan.")
+    report = agent.do(plan)
+    print(f"[pass {i}] {report}")
+```

rangers-0.6.1/README.md

@@ -0,0 +1,210 @@
+# ranger
+
+![CI](https://github.com/AlexKay28/ranger/actions/workflows/ci.yml/badge.svg)
+
+Agent-as-a-library. Run the [opencode](https://opencode.ai) or
+[codex](https://github.com/openai/codex) coding agents headlessly from plain
+Python code — for agentic-loop prototyping. You write code, not chat.
+
+The whole design follows one paradigm: **the agent is a function call —
+Python owns the loop, the harness is just the data plane.** Plan → act →
+check → repeat maps 1:1 onto expression, statement and condition. See
+[docs/PARADIGM.md](docs/PARADIGM.md) for the seven laws every feature is
+reviewed against.
+
+AI coding agents: start with [SKILL.md](SKILL.md) for the library's safe
+workflow, contracts, and repository contribution rules.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/AlexKay28/ranger/main/docs/cheatsheet.png" alt="ranger command cheatsheet" width="760">
+</p>
+
+## Install
+
+```bash
+pip install rangers
+```
+
+The distribution is named **`rangers`** on PyPI; the Python import remains
+`import ranger`. For development from a clone: `pip install -e .[dev]`.
+Maintainers: see the [publishing checklist](docs/PUBLISHING.md) before any
+release.
+
+Requires a harness CLI on PATH: [opencode](https://opencode.ai) (default
+backend) and/or [codex](https://github.com/openai/codex). On a distro-pegged
+pip (e.g. 22.x) an editable install can fail with "build backend is missing
+the build_editable hook" — fix the tool, not the package:
+`pip install -U pip`, then retry.
+
+## Quick start (no clone needed)
+
+Straight from GitHub, then a one-line sanity check in your terminal:
+
+```bash
+pip install git+https://github.com/AlexKay28/ranger
+
+python -c "import ranger; print(ranger.Ranger.models(match='claude'))"
+```
+
+The check needs no model or API budget — it just lists what your local
+opencode CLI offers. Got model ids back? You're ready:
+
+```python
+import ranger
+agent = ranger.Ranger(model="<one of the ids above>")
+print(agent.ask("say ok"))
+```
+
+Runnable applications live in [examples/](examples/): quickstart, model
+discovery, a full agentic loop, a self-hosted project-growth loop, plus three
+small day-to-day recipes — repair a red test command, independently review a
+local diff before merge, review one file, and draft release notes from git
+history. They are organized by use case in the
+[examples index](examples/README.md): getting started, code work, monitoring,
+multi-agent, backends, and no-model dummy runs.
+
+Live progress: each command draws a morphing line on stderr while it runs
+(`⠹ search · TODO items in this repo · 00:03`) and settles as
+`✓ search · 00:07 · <first line of answer>` — opencode-wizard style, colors
+included. It auto-disables in pipes/tests and honors `NO_COLOR`;
+turn it off with `pretty=False`.
+
+Model priority: explicit `Ranger(model=...)` → `$RANGER_MODEL` env var →
+package default.
+
+## Usage
+
+```python
+agent = ranger.Ranger(model="openrouter/anthropic/claude-sonnet-4.5")
+agent.summarize("notes.md")          # -> str summary of the file
+agent.write("a one-page report on X")  # -> path of the file the agent wrote
+agent.do("rename all *.txt files in data/ to *.md")  # -> report of CLI-like work
+agent.search("where do we parse config?")            # -> multiline findings report
+agent.ask("anything at all")         # -> raw prompt, raw answer
+agent.check("all tests pass")        # -> YES/NO verdict as a bool
+agent.gate("python -m pytest -q")    # -> exit-code booleans, no model
+agent.until("make the tests green", gate_cmd="python -m pytest -q")
+                                    # -> loop: plan/do/verify until green
+```
+
+Each call is one fresh headless `opencode run` in the agent's working directory
+(`cwd=`), with permissions auto-approved so it can actually touch the filesystem.
+Pass `session="..."` to share context between calls, `model=` to pick any
+`provider/model` ID from `opencode models`.
+
+## Model discovery & configuration
+
+```python
+import ranger
+
+ranger.Ranger.models()                      # -> all model IDs
+ranger.Ranger.models(match="claude")           # -> substring filter
+
+smart = ranger.Ranger(model="openrouter/anthropic/claude-sonnet-4.5")
+fast  = smart.with_config(model="openrouter/google/gemini-2.5-flash", agent="build")
+```
+
+Every command method also accepts per-call overrides:
+
+```python
+fast.search("todo items", title="quick scan")
+smart.do("refactor auth", timeout=1800)
+```
+
+Overridable: `model`, `timeout`, `auto`, `session`, `agent` (opencode agent
+name like "build"/"plan"), `title`, `thinking`. Unknown keywords raise
+`TypeError` so typos fail loudly.
+
+See [docs/commands.md](docs/commands.md) for the full command catalog —
+15 methods at three maturity tiers: what's shipped, what's next, and
+what needs bigger machinery (gates, retries, safety rails) —
+[docs/API.md](docs/API.md) for the complete, per-setting API reference
+(kept mechanically in sync with the code by the test suite), and
+[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for a high-level tour of
+the codebase and its three architectural decisions.
+
+## Context state (memory)
+
+The agent remembers. Every command exchange is recorded to
+`agent.context` in classic OpenAI message format
+(`{"role": "user"|"assistant"|"system", "content": ...}`) and recent
+history (within a character budget) is recalled into later runs — so
+follow-ups like "now do the same for tests/" just work.
+
+```python
+agent.context         # the message list
+agent.context_summarize()   # -> digest of what happened so far
+agent.context_compact()     # collapse history to one system digest
+agent.context_clear()       # wipe; returns what was cleared
+agent.ask("...", memory=False)  # one stateless run
+ranger.Ranger(memory=False)      # or a fully stateless agent
+```
+
+Context memory colors your dialogues, never your facts: `ask`/`do`/`write`
+recall the recent conversation; `check`/`search`/`summarize` always run
+history-independent, so a verdict is about the repo, not the chat
+([PARADIGM.md](docs/PARADIGM.md), law 4).
+
+## Backends (harness adapters)
+
+The same API drives different harnesses; the setting is one constructor
+argument, per-call overridable:
+
+```python
+import ranger
+
+agent = ranger.Ranger(model="openrouter/anthropic/claude-sonnet-4.5")  # opencode (default)
+gpt   = ranger.Ranger(backend="codex")            # model from ~/.codex/config.toml
+gpt   = ranger.Ranger(backend="codex", model="gpt-5.1-codex")
+
+ranger.register_backend("mine", MyHarnessAdapter)  # your own — one small class
+```
+
+Harness differences (flags, sessions, sandboxes, output schemas) are
+absorbed by one adapter class per backend — see the Backends section of
+[docs/API.md](docs/API.md) for the full capability map and the recipe for
+adding your own harness.
+
+## Multi-agent interactions
+
+Two (or three) agents, and the expected patterns as ready-made methods —
+verdicts are grammar, budgets are honest, reviewers run free of their own
+chat history:
+
+```python
+both    = builder.second_opinion(critic, prompt)    # {mine, theirs, differs}
+verdict = critic.review(subject, author=builder)    # APPROVE/REJECT/REQUEST_CHANGES
+outcome = builder.refine_with(critic, goal)          # the two-agent until()
+duel    = critic.challenge(builder)                  # adversarial claim attack
+talk    = ranger.debate(builder, critic, topic, judge=skeptic)
+```
+
+See the Multi-agent interactions section of [docs/API.md](docs/API.md)
+and [`examples/multiagent/multi_agent.py`](examples/multiagent/multi_agent.py).
+
+## Skills allow-list
+
+Grant the agent specific skills or operating rules per run — a markdown
+file or directory rides along via opencode's `--file` attachment; plain
+prose entries are injected as prompt grants.
+
+```python
+agent = ranger.Ranger(skills=[
+    "skills/haiku/SKILL.md",        # file -> --file attachment
+    "skills/pack",                  # dir -> all its *.md attached
+    'Always answer in British spelling',  # prose -> prompt grant
+])
+agent.do("write the changelog", skills=["docs/changelog_style.md"])  # per call
+```
+
+## AGI loop, the point of the whole thing
+
+```python
+agent = ranger.Ranger(model="openrouter/anthropic/claude-sonnet-4.5")
+
+for i in range(10):
+    hits = agent.search(f"TODO and unimplemented spots, pass {i}")
+    plan = agent.ask(f"Pick ONE thing to fix from:\n{hits}\nReply with a one-line fix plan.")
+    report = agent.do(plan)
+    print(f"[pass {i}] {report}")
+```

rangers-0.6.1/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: ranger
+description: Use the ranger Python library to drive headless coding agents from ordinary Python. Load BEFORE writing a Ranger loop, agent-backed repair or review workflow, multi-agent composition, custom backend, or tests around ranger. Triggers - ranger, rangers, Ranger(), agent-as-a-library, headless coding agent in Python, ask/do/check/until/refine_with, coding-agent loop, агент как библиотека, цикл агента на Python, ранжер. Do NOT use for a hosted agent runtime, background task queue, or streaming chat server - ranger intentionally has none; Python owns the loop.
+---
+
+# ranger — agent-as-a-library
+
+`rangers` is the PyPI distribution; the import is `ranger`:
+
+```python
+# shell: pip install rangers
+import ranger
+
+agent = ranger.Ranger(cwd="/path/to/project", timeout=180)
+answer = agent.ask("Find the smallest safe fix for the failing parser test.")
+```
+
+Every live Ranger call starts one headless harness CLI process and blocks until
+it returns. Python, not an agent runtime, owns the control flow.
+
+## Non-negotiable rules
+
+| Need | Use | Do not substitute |
+|---|---|---|
+| Open-ended answer or one small plan | `ask(prompt)` | A custom chat loop |
+| Make a filesystem change | `do(goal)` | A claim that a change happened |
+| Produce one document | `write(task, path=...)` | Parsing prose for a filename |
+| Read-only codebase findings | `search(goal)` / `summarize(file)` | `do()` |
+| Agent-verified fact | `check(condition)` | Truthy prose; it must parse YES/NO |
+| Deterministic acceptance | `gate(shell_command)` | An agent's opinion |
+| Bounded repair loop | `until(..., gate_cmd=..., max_iter=N)` | An unbounded `while` loop |
+| Independent review | `critic.review(subject, author=claims)` | Trusting the author report |
+
+**Use a mechanical gate whenever one exists.** For a repair, the shell test
+command decides success:
+
+```python
+result = agent.until(
+    "Make the parser tests pass; reproduce first and make the smallest fix.",
+    gate_cmd="python -m pytest -q tests/test_parser.py",
+    max_iter=2,
+)
+if not result["achieved"]:
+    raise RuntimeError(result["report"])
+```
+
+`until` never invents success after its budget runs out. `gate()` returns only
+an exit-code boolean and does not call a model.
+
+## Costs, cancellation, and state
+
+- Set an explicit `timeout=` for real work and a small `max_iter`/`rounds`
+  budget for every loop. A loop costs one or more full CLI calls per iteration.
+- Ctrl+C / notebook interrupt raises `KeyboardInterrupt`, stops the CLI client,
+  and retires the progress spinner. Long loops put honest partial state in the
+  interrupt message; nothing is claimed complete.
+- `ask`, `do`, and `write` record and recall bounded `agent.context`. Treat it
+  as conversational color, never as a fact store.
+- `check`, `search`, `summarize`, `review`, challenge judgments, and debate
+  judges are memory- and session-free by contract. Do not try to override that
+  purity with `session=`.
+- A model answer is not a success signal. `check()` rejects ambiguous,
+  contradictory, or uncertain replies with `RangerError`.
+
+## Multi-agent work
+
+Interactions are normal Python compositions, not a scheduler or swarm.
+Pass another agent's report as **unverified claims** and let the receiver verify
+the repository itself:
+
+```python
+builder = ranger.Ranger(cwd=".", timeout=180)
+critic = ranger.Ranger(cwd=".", timeout=180)
+
+outcome = builder.refine_with(
+    critic,
+    "Add a regression test for empty parser input and make it pass.",
+    max_iter=2,
+)
+if not outcome["approved"]:
+    print(outcome["reviews"][-1]["changes"])
+```
+
+Use the smallest fitting pattern:
+
+- `second_opinion(other, prompt)` — compare two answers; disagreement is the
+  signal, not a vote.
+- `review(subject, author=...)` — strict `VERDICT`, `FINDINGS`, `CHANGES`.
+- `challenge(other, claim=..., rounds=1)` — adversarial evidence check.
+- `refine_with(critic, goal, max_iter=2)` — do → review → revise.
+- `ranger.debate(a, b, topic, judge=...)` — surface factual disagreements;
+  the judge digests evidence and never crowns a winner.
+
+Do not parse model prose yourself. The interaction methods validate their
+frozen grammars and raise `RangerError` on malformed or conflicting replies.
+
+## Backends and models
+
+- Use `Ranger(backend="opencode")` (default) or `Ranger(backend="codex")`.
+  The public API stays the same; CLI flags and output parsing do not.
+- Use OpenRouter-style public model IDs in repository files. Do **not** add
+  internal provider/model names to code, docs, examples, tests, or commits.
+- For a new harness, register a small adapter with
+  `ranger.register_backend(name, adapter_cls)`; do not fork command logic.
+- Resolve a model only when needed: explicit per-call model beats constructor,
+  then `RANGER_MODEL`, then the effective backend's default.
+
+## Contributing to this repository
+
+- Read [docs/PARADIGM.md](docs/PARADIGM.md) before changing public behavior.
+  The core laws are grammar over vibes, explicit Python state, and a
+  replaceable harness data plane.
+- Keep normal tests fully mocked. Agent calls use the
+  `ranger.subprocess.run` seam; `gate()` uses `ranger.subprocess.Popen`.
+  Do not put live opencode/codex calls in the test suite.
+- Add truth-table tests for parsers, verdicts, option precedence, and loop
+  outcomes. The suite has a strict one-minute budget.
+- Update `docs/API.md`, README, examples, and docs gates whenever public API
+  changes. Examples must be main-guarded and import-safe.
+- Run `python -m pytest -q`; for releases also run `python -m build` and
+  `python -m twine check --strict dist/*`. See [docs/PUBLISHING.md](docs/PUBLISHING.md).
+
+## Execution-bug feedback for maintainers
+
+If a user asks you to use ranger and you encounter a reproducible library or
+harness-execution bug, help the maintainers learn from it: create an issue at
+[`AlexKay28/ranger`](https://github.com/AlexKay28/ranger/issues) when GitHub
+authentication and issue-creation permission are available. If they are not,
+give the user the complete ready-to-paste issue instead. Do this after a
+minimal reproduction attempt — not for a malformed prompt, a missing CLI, an
+expired model quota, or an expected `RangerError` caused by invalid input.
+
+**Never include secrets.** Redact API tokens, credentials, private prompts,
+absolute private paths, and proprietary source. Link to public output only.
+
+Use this issue format:
+
+````markdown
+## ranger execution bug
+
+**ranger version:** `ranger.__version__`
+**Python / OS:** `python --version`; operating system
+**Backend / model:** `opencode|codex`; public model ID or `redacted`
+**Command or minimal code:**
+```python
+# smallest self-contained reproduction
+```
+**Expected behavior:** what should have happened
+**Actual behavior:** exact exception, exit code, or unexpected result
+**Reproduction:** always / intermittent; smallest known steps
+**Relevant non-secret context:** timeout, session/memory setting, and whether
+the problem remains with `memory=False` and a fresh session
+````
+
+Title issues as: `bug: <short observable failure>`. Before filing, search
+existing open issues for the same error and add reproduction details there
+instead of creating a duplicate. The report is feedback, not a substitute for
+the user's immediate workaround: state the workaround or honest blocker too.
+
+## Choose an example before inventing a workflow
+
+See [examples/README.md](examples/README.md) for runnable recipes:
+
+- `examples/code-work/fix_failing_tests.py` — bounded repair with a real test
+  command as the gate.
+- `examples/code-work/simple_code_review.py` — one file, one strict verdict.
+- `examples/monitoring/project_health.py` — read-only health snapshot.
+- `examples/multiagent/multi_agent.py` — all collaboration patterns.
+- `examples/dummy/mechanical_gates.py` — no model or login required.