neonrp 0.1.0__tar.gz

neonrp-0.1.0/.env.example

@@ -0,0 +1,34 @@
+# NeonRP Environment Configuration Example
+# Copy this file to .env and fill in your values
+
+# =============================================================================
+# GLM (Zhipu AI) Configuration
+# =============================================================================
+# Get your API key from: https://open.bigmodel.cn/
+GLM_API_KEY=your_api_key_here
+GLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4
+GLM_MODEL=glm-4-flashx-250414
+
+# Optional GLM settings
+GLM_TEMPERATURE=0.1
+GLM_TOP_P=0.9
+GLM_MAX_TOKENS=4096
+GLM_RESPONSE_FORMAT=json_object
+
+# =============================================================================
+# OpenAI Configuration (alternative to GLM)
+# =============================================================================
+# OPENAI_API_KEY=sk-your-openai-key-here
+# OPENAI_BASE_URL=https://api.openai.com/v1
+# OPENAI_MODEL=gpt-4o
+
+# =============================================================================
+# E2E Testing
+# =============================================================================
+# Set to 1 to enable real LLM E2E tests (requires API key)
+# NEONRP_E2E_LLM=1
+
+# =============================================================================
+# Other Settings  
+# =============================================================================
+MAX_WORKERS=1

neonrp-0.1.0/.gitattributes

@@ -0,0 +1,25 @@
+# Normalize text files to LF in repository and working tree.
+* text=auto eol=lf
+
+# Windows shell scripts keep CRLF for compatibility.
+*.bat text eol=crlf
+*.cmd text eol=crlf
+
+# Common binary formats (never line-normalize).
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.bmp binary
+*.ico binary
+*.pdf binary
+*.zip binary
+*.gz binary
+*.7z binary
+*.tar binary
+*.jar binary
+*.dll binary
+*.exe binary
+*.pyd binary
+*.so binary
+*.dylib binary

neonrp-0.1.0/.githooks/pre-commit

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Normalize staged files according to .gitattributes before commit.
+mapfile -d '' -t staged < <(git diff --cached --name-only -z --diff-filter=ACMR)
+
+if [ "${#staged[@]}" -eq 0 ]; then
+  exit 0
+fi
+
+git add --renormalize -- "${staged[@]}"

neonrp-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,245 @@
+name: release
+
+# Publishes both `neonrp` and `worldlines` to PyPI via Trusted Publishing (OIDC).
+#
+# One-time PyPI setup required on the PyPI project page for EACH of the two
+# projects (neonrp and worldlines), under "Publishing":
+#
+#   - Owner:       LudicDynamics
+#     Repo:        NeonRP
+#     Workflow:    release.yml
+#     Environment: pypi
+#
+# PyPI accepts OIDC tokens that match ANY configured trusted publisher; if
+# this project later moves between orgs, register the new owner as another
+# pending publisher before pushing the first tag from there. See
+# `docs/releases.md → Owner handoff` for the full migration steps.
+#
+# Tag format:   v0.3.4 → publishes neonrp==0.3.4 and worldlines==0.3.4
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: "Build only; do not publish"
+        required: false
+        default: "false"
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Derive version from tag (or pyproject)
+        id: version
+        shell: bash
+        run: |
+          ref="${GITHUB_REF##*/}"
+          if [[ "${GITHUB_REF_TYPE}" == "tag" && "${ref}" =~ ^v ]]; then
+            version="${ref#v}"
+          else
+            version=$(awk -F'"' '/^version *=/{print $2; exit}' pyproject.toml)
+          fi
+          echo "version=${version}" >> "$GITHUB_OUTPUT"
+          echo "Using version: ${version}"
+
+      - name: Sync version into pyproject.toml files
+        shell: bash
+        run: |
+          version="${{ steps.version.outputs.version }}"
+          # neonrp
+          sed -i -E "s/^version *= *\".*\"/version = \"${version}\"/" pyproject.toml
+          # worldlines shim + pinned neonrp dependency
+          sed -i -E "s/^version *= *\".*\"/version = \"${version}\"/" packaging/worldlines/pyproject.toml
+          sed -i -E "s/\"neonrp==[^\"]*\"/\"neonrp==${version}\"/" packaging/worldlines/pyproject.toml
+          grep -E "^version" pyproject.toml packaging/worldlines/pyproject.toml
+
+      - name: Build neonrp distribution
+        run: |
+          uv build --out-dir dist/neonrp
+
+      - name: Build worldlines distribution
+        working-directory: packaging/worldlines
+        run: |
+          uv build --out-dir ../../dist/worldlines
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 7
+
+  publish-neonrp:
+    needs: build
+    if: ${{ github.event_name == 'push' || github.event.inputs.dry_run != 'true' }}
+    runs-on: ubuntu-latest
+    environment:
+      # Per-project environment: PyPI's pending-publisher table is unique
+      # by (owner, repo, workflow, environment) — even across different
+      # project names — so the two PyPI projects need two distinct
+      # environment names to register side-by-side.
+      name: pypi-neonrp
+      url: https://pypi.org/p/neonrp
+    permissions:
+      id-token: write   # required for OIDC trusted publishing
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish neonrp to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/neonrp
+
+  publish-worldlines:
+    needs: [build, publish-neonrp]
+    if: ${{ github.event_name == 'push' || github.event.inputs.dry_run != 'true' }}
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi-worldlines
+      url: https://pypi.org/p/worldlines
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish worldlines to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/worldlines
+
+  publish-release-manifest:
+    # Dual-host releases.json + install.sh so users have a fallback path:
+    #
+    #   Primary:   S3 bucket (fronted by worldlines.gg via Cloudflare)
+    #   Fallback:  LudicDynamics/WorldLines GitHub Release assets
+    #
+    # Both are uploaded fresh on every tag. S3 upload uses OIDC to assume
+    # an AWS IAM role (no long-lived AWS keys in secrets). GitHub Release
+    # creation uses the cross-repo PAT since the source repo is private.
+    #
+    # Required:
+    #   secrets.WORLDLINES_RELEASE_TOKEN — fine-grained PAT scoped to
+    #     LudicDynamics/WorldLines with Contents: read/write.
+    #
+    # Optional (skip cleanly if unset):
+    #   vars.S3_RELEASE_ROLE_ARN   — IAM role the OIDC token will assume
+    #   vars.S3_RELEASE_BUCKET     — target bucket (e.g. worldlines-releases)
+    #   vars.S3_RELEASE_REGION     — AWS region (e.g. ap-northeast-1)
+    #
+    # When the S3 vars are missing the S3 upload step short-circuits and
+    # only the GitHub Release is created — useful during initial bootstrap.
+    needs: [publish-neonrp, publish-worldlines]
+    if: ${{ github.event_name == 'push' }}
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write   # required for AWS OIDC trust exchange
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build releases.json
+        id: manifest
+        shell: bash
+        run: |
+          version="${GITHUB_REF##*/v}"
+          cat > releases.json <<EOF
+          {
+            "product": "neonrp",
+            "latest": { "stable": "${version}" },
+            "releases": {
+              "${version}": {
+                "channel": "stable",
+                "published_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+                "notes_url": "https://github.com/LudicDynamics/WorldLines/releases/tag/v${version}",
+                "artifacts": {
+                  "python-wheel": {
+                    "kind": "pypi",
+                    "version": "${version}",
+                    "packages": ["neonrp", "worldlines"]
+                  }
+                }
+              }
+            }
+          }
+          EOF
+
+      - name: Publish release on LudicDynamics/WorldLines with assets
+        uses: softprops/action-gh-release@v2
+        with:
+          repository: LudicDynamics/WorldLines
+          token: ${{ secrets.WORLDLINES_RELEASE_TOKEN }}
+          tag_name: ${{ github.ref_name }}
+          # Creates the tag on WorldLines' default branch (its HEAD at the
+          # time this job runs). `target_commitish` is optional; omitting
+          # it uses the default branch, which matches what we want for
+          # docs-only repos.
+          name: ${{ github.ref_name }}
+          generate_release_notes: false
+          files: |
+            releases.json
+            install.sh
+
+      # --- S3 primary (OIDC, best-effort) -----------------------------
+      # Skip cleanly if the S3 vars aren't configured yet — GitHub
+      # Release above is sufficient for a first release.
+
+      - name: Configure AWS credentials via OIDC
+        id: aws-auth
+        if: ${{ vars.S3_RELEASE_ROLE_ARN != '' }}
+        continue-on-error: true
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: ${{ vars.S3_RELEASE_ROLE_ARN }}
+          aws-region: ${{ vars.S3_RELEASE_REGION || 'ap-northeast-1' }}
+          audience: sts.amazonaws.com
+
+      - name: Upload releases.json + install.sh to S3
+        if: ${{ steps.aws-auth.outcome == 'success' }}
+        continue-on-error: true
+        shell: bash
+        env:
+          BUCKET: ${{ vars.S3_RELEASE_BUCKET }}
+        run: |
+          # Short TTL on releases.json so auto-update picks up new versions
+          # within ~5 min; longer on install.sh because it rarely changes
+          # and is also embedded in onboarding docs.
+          aws s3 cp releases.json "s3://${BUCKET}/releases.json" \
+              --cache-control "public, max-age=300" \
+              --content-type "application/json"
+
+          aws s3 cp install.sh "s3://${BUCKET}/install.sh" \
+              --cache-control "public, max-age=3600" \
+              --content-type "text/x-shellscript"
+
+          # Also drop a version-pinned copy so downgrade / pin-in-CI is easy.
+          version="${GITHUB_REF##*/v}"
+          aws s3 cp releases.json "s3://${BUCKET}/v${version}/releases.json" \
+              --cache-control "public, max-age=31536000, immutable" \
+              --content-type "application/json"

neonrp-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,41 @@
+name: test
+
+on:
+  push:
+    branches: [main, worldlines-dev]
+  pull_request:
+
+concurrency:
+  group: test-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint-and-test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Sync dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Lint (ruff)
+        run: uv run ruff check src tests
+
+      - name: Run tests
+        run: uv run pytest -q
+        env:
+          NEONRP_E2E_LLM: "0"

neonrp-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# Environment & secrets
+.env
+.env.*
+!.env.example
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Local runtime / sandbox data (keep local, do not track)
+/.neonrp/
+.neonrp/
+/my-rpg/

neonrp-0.1.0/CHANGELOG.md

@@ -0,0 +1,154 @@
+# Changelog (docs pack)
+
+## v0.9.3 (2026-03-29)
+- TUI build mode now works immediately after `neonrp init` in fresh directories, without requiring local agent scaffolding first.
+- Added packaged builtin skills under `src/neonrp/builtin_skills/` and project-level skill loading now falls back to those builtin skills automatically.
+- Added TUI Tavern import entry points:
+  - `neonrp tui --import-card <file> [--import-id <id>]`
+  - `/import sillytavern-card <file> [--id <id>]`
+- Improved SillyTavern import ergonomics:
+  - PNG/JSON import tool is exposed to build-mode agents as `import_sillytavern_card(...)`
+  - non-ASCII card names now derive stable ASCII entity IDs instead of collapsing to `unnamed`
+  - agent tool can set destination path and visible name explicitly.
+- Fixed Tavern "convert into full game" workflow:
+  - added `ensure_playable_scaffold(...)` to copy missing play agents/runtime scaffold
+  - normalized `game/meta/active-agent.json` to the canonical top-level `active_agent` protocol
+  - updated Tavern import skill/prompt guidance so generated worlds only claim playability after scaffold exists.
+
+## v0.9.2 (2026-02-16)
+- Added optional embedding-based retrieval pipeline:
+  - new `src/neonrp/core/embedding.py` (adapters + vector index persistence)
+  - hybrid fuzzy + vector ranking in `read_context` / `context`
+  - automatic fuzzy-only fallback when embedding is unavailable.
+- `index build` now precomputes embeddings by default when `embedding.enabled=true`.
+- Simplified embedding config workflow:
+  - supports minimal config with `embedding.enabled + embedding.model_ref`
+  - inherits provider/model/auth/base_url from `models[model_ref]`.
+- Applied fixes from `reviews/code_review_20260216.md` across apply/save-load/permissions/CLI consistency paths.
+- Added regression coverage for embedding and fuzzy retrieval:
+  - `tests/test_embedding.py`
+  - `tests/test_retrieval_fuzzy.py`
+
+## v0.9.1 (2026-02-10)
+- Added provider-specific request passthrough via model-level `extra` config (`models.<name>.extra`), including OpenRouter reasoning payloads.
+- Fixed OpenAI-compatible extra parameter compatibility:
+  - unknown extra fields are now routed through `extra_body` instead of top-level kwargs
+  - avoids SDK errors like `unexpected keyword argument 'reasoning'`.
+- Improved retry behavior for transient streaming failures:
+  - conversation loop now retries with fixed backoff `2s -> 7s -> 15s -> 30s`, then stops.
+  - streaming/network errors are now classified as retryable and propagated correctly.
+- Improved `ask_user` UX in TUI:
+  - selected answer is shown inline in the conversation as a user-visible message
+  - restored sessions re-render historical `ask_user` selections
+  - tool card detail now shows `selected: ...` for `ask_user`.
+- Test coverage updates for new behavior:
+  - added `tests/test_llm_openai_extra.py`
+  - expanded coverage in `test_conversation.py`, `test_conversation_edges.py`, `test_app_v2.py`, `test_llm_retry.py`, `test_llm_streaming.py`, `test_config.py`, `test_per_agent_llm.py`.
+
+## v0.9
+- **M10.1 delivered**: TUI/Conversation reliability and operability upgrades.
+- Added **ESC interrupt** for in-flight LLM turns in conversational TUI.
+- Added configurable per-turn tool-call ceiling via `tui.max_tool_rounds` in config.
+- Added **incremental session history saving** (Claude Code-style persistence behavior).
+- Added startup/session controls:
+  - `neonrp tui --continue` / `--new` / `--verbose`
+  - `/sessions` picker modal + `/continue` + `/new`
+  - `/verbose on|off|status` with debug JSONL logs.
+- Improved TUI telemetry and lifecycle:
+  - real-time local token estimation in status bar
+  - safer quit path (`Ctrl+Q`) while requests are running.
+- Todo workflow compatibility fixes:
+  - TodoWrite prompt now includes a **minimal valid example**
+  - todo validation aligned to mainstream UX (`<=1 in_progress`, `activeForm` optional, `done` alias accepted)
+  - todo rendering stabilized with literal markers ``[x]`` / ``[>]`` / ``[ ]``
+  - `/continue` now restores todo list from tool history.
+- Documentation refresh:
+  - synced `README.md`, `DEV_README.md`, `docs/TUTORIAL.md`, `docs/ROADMAP.md` with latest TUI/session behavior.
+
+## v0.8
+- **M9 + M10 stabilization delivered** (conversation-first TUI, ask_user modal, markdown transcript, slash suggestion UX)
+- Added coverage补测 wave focused on real runtime paths (not stub-only):
+  - `tests/test_conversation_edges.py`
+  - `tests/test_retrieval.py`
+  - `tests/test_tui_suggestions.py`
+  - `tests/test_llm_real_endpoint.py` (real endpoint e2e via `~/.neonrp/config.json`)
+- Coverage report updated (`reviews/coverage_report_20260209.md`):
+  - Total coverage: **63% → 65%**
+  - `core/conversation.py`: 80% → 99%
+  - `core/retrieval.py`: 33% → 95%
+  - `tui/suggestions.py`: 0% → 99%
+- Regression status updated: `803 passed, 7 skipped`
+
+## v0.7
+- **M4 Implementation**: Sandbox + Replay milestone complete (290 tests)
+- **Pre-M4 Housekeeping**:
+  - H7: Fixed `load` command crash-safety (atomic rename strategy)
+  - H8: Fixed deprecated `datetime.utcnow()` → `datetime.now(timezone.utc)`
+  - H9: Added PNG character card import (pure Python tEXt chunk reader, no Pillow)
+- Added `neonrp sandbox new|list|switch|drop` CLI commands
+- Added `neonrp replay verify|checkout` CLI commands
+- Added `core/hashing.py` — deterministic world tree hash utility
+- Added `core/replay.py` — replay engine (staging-based, non-destructive)
+- Added `core/system_proposal.py` — system proposal factory for import/game commands
+- Added `core/paths.py:validate_branch_name()` — path traversal protection
+- Extended `BranchMetadata` with `kind`/`parent`/`fork_event`/`base_save` for sandbox support
+- Save now includes `meta.json` (game_hash, head_event, branch) and `events.jsonl` copy
+- Atomic `events.jsonl` copy via temp file + `os.replace`
+- Import and `game new` now generate system proposals through apply pipeline
+- Sandbox switch invalidates `manifest.entities` with `index build` prompt
+- Bumped manifest.version to `"0.3"`
+- ADR 0011 (sandbox branch model), ADR 0012 (replay and determinism contract)
+
+## v0.6
+- **M3 Implementation**: LLM Integration + Skills + Import milestone complete (219 tests)
+- **Pre-M3 Housekeeping**:
+  - H3: Fixed `agent.py:393` active_branch bug
+  - H4: Atomic world/ directory replacement in `apply.py`
+  - H5: Empty index warning in `retrieval.py`
+  - H6: Standardized delete hunk header in `diffing.py`
+- Added LLM adapter Protocol (`core/llm.py`) with stub, OpenAI, and GLM providers
+- Added skill tool registry (`core/skills.py`) with per-file deny-first permissions and JSONL audit logging
+- Added `neonrp agent run <id> --query "..." [--provider] [--apply] [--json]` LLM-driven agent execution
+- Added `neonrp import sillytavern-card` with v1/v2 JSON card support, ID conflict resolution, raw payload preservation
+- Added `neonrp game new` scaffolding command with `--force`/`--json`
+- Added project config `.neonrp/config.json` with provider/model/CLI defaults
+- Added `.env` file loader for API key management
+- ADR 0008 (LLM adapter), ADR 0009 (skill registry), ADR 0010 (SillyTavern import)
+
+## v0.5
+- **M2 Implementation**: Agents + Plan/Diff/Apply milestone complete (110 tests)
+- Added `neonrp agent new|list|show|path` CLI commands with template generation
+- Added `core/proposal.py` — Proposal/Op models with path validation
+- Added `core/permissions.py` — deny-first glob matching permission engine
+- Added `core/diffing.py` — stable unified diff generation
+- Added `core/apply.py` — staging + validate + atomic swap apply pipeline
+- Added `core/retrieval.py` — agent-scoped context retrieval
+- Added `neonrp agent run --proposal --apply` and `neonrp agent logs` commands
+- GameEvent model extended with `actor` field for agent attribution
+- ADR 0006 (agent spec and permissions), ADR 0007 (proposal format)
+
+## v0.4
+- **M1 Implementation**: Validation + Indexing milestone complete (41 tests)
+- Added `neonrp validate` CLI with `--json` support and exit codes 0/1/2
+- Added `neonrp index build|update` CLI for entity indexing
+- Added `neonrp find` CLI with --id/--tag/--kind/keyword search
+- Added `neonrp context` CLI with explainable scoring and snippets
+- Fixed `scan_entities()` to handle partial failures (index valid, skip invalid)
+- Migrated to Pydantic v2 patterns (`ConfigDict`, `datetime.now(UTC)`)
+- Bumped manifest.version to `"0.2"`
+
+## v0.3
+- **M0 Implementation**: Skeleton + Core Lifecycle milestone complete
+- ARCHITECTURE: added write atomicity & crash recovery strategy; defined manifest.json minimal structure
+- QUALITY_GATES: added three-layer test strategy (unit/integration/E2E); added code review process
+- Replaced scripts/qa.sh with cross-platform scripts/qa.py
+
+## v0.2
+- Added ADRs: CLI framework (click), event storage format (NDJSON), snapshot & branch strategy
+- ROADMAP: split T4 into T4a (undo/redo) + T4b (branch); added R-number cross-references
+- QUALITY_GATES: added code review unrecoverable failure policy
+
+## v0.1
+- Initial documentation set: requirements, architecture, roadmap, progress, quality gates
+- Added opencode review gate and code review prompt
+

neonrp-0.1.0/DEV_README.md

@@ -0,0 +1,101 @@
+# Developer Guide
+
+Welcome to the NeonRP development documentation.
+
+## Documentation Structure
+
+Detailed documentation is located in the `docs/` directory:
+
+- **[REQUIREMENTS.md](docs/REQUIREMENTS.md)**: Product requirements (Source of Truth).
+- **[ROADMAP.md](docs/ROADMAP.md)**: Milestones, task lists, and acceptance criteria. **Check this first to see what to build.**
+- **[ARCHITECTURE.md](docs/ARCHITECTURE.md)**: System design, layers, invariants, event model, and on-disk layout.
+- **[QUALITY_GATES.md](docs/QUALITY_GATES.md)**: Definition of Done, testing strategy, and code review process.
+- **[PROGRESS.md](docs/PROGRESS.md)**: Execution log. Update this after every completed task.
+- **[ADRs/](docs/ADRs/)**: Architecture Decision Records (0001–0023).
+- **Per-milestone design docs**: `M1_*` through `M10_*` design specs and task cards.
+
+## Quick Start (Development)
+
+1. **Setup Environment**:
+   ```pwsh
+   # using uv (recommended)
+   uv sync
+   # or using pip
+   pip install -e ".[dev]"
+   ```
+
+2. **Run Tests**:
+   ```pwsh
+   uv run pytest
+   ```
+
+3. **Run Coverage (required for coverage-related work)**:
+   ```pwsh
+   uv run pytest --cov=neonrp --cov-report=term-missing -q
+   ```
+
+4. **Lint & Format**:
+   ```pwsh
+   uv run ruff format .
+   uv run ruff check .
+   ```
+
+5. **Verify Process**:
+   Use the QA script to run gates and get next steps:
+   ```pwsh
+   python scripts/qa.py
+   ```
+
+## Workflow
+
+1. Pick a task from `docs/ROADMAP.md`.
+2. Implement and test.
+3. Run `python scripts/qa.py`.
+4. Perform code review via `opencode`.
+5. Update `docs/PROGRESS.md` and checklists.
+
+## Task Plan Writing Guide
+
+Use this as a lightweight guide when writing a task plan. Keep it practical; don't over-specify.
+
+1. Define outcome first:
+   - One clear goal sentence (what changes for users or developers).
+   - In/out of scope boundaries.
+2. List deliverables:
+   - Files/modules expected to change.
+   - Observable outputs (CLI behavior, UI behavior, docs, tests).
+3. Add acceptance criteria:
+   - Use behavior-level checks ("when X, then Y"), not only internal implementation details.
+   - Include at least one end-to-end path for user-critical flows.
+4. Add test strategy in the plan:
+   - Unit tests for core logic and edge cases.
+   - Integration tests for framework boundaries (e.g., TUI input -> worker -> session send).
+   - For bug fixes, add a regression test that fails before the fix.
+5. Coverage requirement (recommended baseline):
+   - `src/` overall coverage >= 80%.
+   - Changed files coverage >= 85%.
+   - Critical modules (state, storage, conversation, dispatch, TUI event paths) should target >= 90%.
+   - Command example:
+     ```pwsh
+     uv run pytest --cov=neonrp --cov-report=term-missing -q
+     ```
+6. Real-endpoint E2E requirement (for LLM integration changes):
+   - Use user config endpoint in `~/.neonrp/config.json` when available.
+   - Gate with env var to avoid CI cost:
+     ```pwsh
+     $env:NEONRP_E2E_LLM='1'
+     uv run pytest tests/test_llm_real_endpoint.py -q
+     ```
+7. Code review requirement:
+   - Run an `opencode` review before merge.
+   - Save report under `reviews/` with date/task context.
+   - Fix must-fix findings, then rerun tests.
+   - Example:
+     ```pwsh
+     opencode run "Using prompts/code_review.md, review src/ changes against docs/REQUIREMENTS.md. Save report to reviews/REVIEW_YYYYMMDD.md"
+     ```
+8. Update records:
+   - Check off task items in `docs/ROADMAP.md`.
+   - Add a concise entry in `docs/PROGRESS.md` (what changed, tests, review result).
+   - If user-facing behavior changed (especially TUI), update `README.md`, `docs/TUTORIAL.md`, and `CHANGELOG.md` in the same PR.
+   - If coverage work was done, update `reviews/coverage_report_YYYYMMDD.md` with latest numbers and remaining gaps.