polily 0.11.1__tar.gz

polily-0.11.1/.envrc.example

@@ -0,0 +1,24 @@
+# .envrc.example — Copy to .envrc and run `direnv allow` to activate.
+# Provides per-developer overrides so polily uses repo-local data dir
+# ($REPO_ROOT/data) instead of the v0.11.0 default
+# ~/Library/Application Support/polily.
+
+# Setup:
+#   1. Install direnv: `brew install direnv` (or your distro's package manager)
+#   2. Hook into your shell: https://direnv.net/docs/hook.html
+#   3. Copy this file: `cp .envrc.example .envrc`
+#   4. Activate: `direnv allow`
+#
+# Now `cd $REPO_ROOT` auto-loads these env vars; `cd` away auto-unloads.
+
+export POLILY_DATA_DIR="$(git rev-parse --show-toplevel)/data"
+export POLILY_LOG_DIR="$POLILY_DATA_DIR/logs"
+
+# Use a distinct launchd label so dev daemon and prod daemon coexist.
+# Without this, `polily scheduler restart` would clobber the user's
+# real ~/Library/LaunchAgents/com.polily.scheduler.plist with one
+# pointing at the dev clone's data dir.
+export POLILY_LAUNCHD_LABEL="com.polily.scheduler.dev"
+
+# Optional shell alias fallback if you don't want direnv at all:
+#   alias polily-dev='POLILY_DATA_DIR=$(pwd)/data POLILY_LAUNCHD_LABEL=com.polily.scheduler.dev .venv/bin/polily'

polily-0.11.1/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,26 @@
+---
+name: Bug Report
+about: Report a bug
+labels: bug
+---
+
+**Describe the bug**
+A clear description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce:
+1. Run `polily ...`
+2. Press '...'
+3. See error
+
+**Expected behavior**
+What you expected to happen.
+
+**Environment**
+- OS: [e.g. macOS 14, Ubuntu 22.04]
+- Python version: [e.g. 3.11.8]
+- Polily version: [e.g. 0.1.0]
+- Claude CLI installed: [yes/no]
+
+**Logs / Screenshots**
+If applicable, add logs or screenshots.

polily-0.11.1/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,14 @@
+---
+name: Feature Request
+about: Suggest a new feature
+labels: enhancement
+---
+
+**Problem**
+What problem does this solve?
+
+**Proposed Solution**
+How should it work?
+
+**Alternatives Considered**
+Any other approaches you've thought about.

polily-0.11.1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,12 @@
+## Summary
+
+Brief description of changes.
+
+## Checklist
+
+- [ ] Tests pass (`pytest tests/ -q`)
+- [ ] Lint passes (`ruff check polily/ tests/`)
+- [ ] Type check passes (`pyright polily/`)
+- [ ] New features have tests
+- [ ] Code comments in English
+- [ ] No definitive trade signals added (project red line)

polily-0.11.1/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  push:
+    branches: [master, dev]
+  pull_request:
+    branches: [master, dev]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # hatch-vcs needs full history + tags to derive version from
+          # the nearest git tag. fetch-depth: 0 = full history.
+          fetch-depth: 0
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install system dependencies
+        run: sudo apt-get update && sudo apt-get install -y build-essential
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check polily/ tests/
+
+      - name: Type check
+        run: pyright polily/ || true  # tracked as follow-up, not blocking CI yet
+
+      - name: Test
+        run: pytest tests/ -q --tb=short
+
+  # Release-PR discipline gate. Only runs on dev → master PRs; feature PRs
+  # into dev are expected to be [Unreleased]-topped (CHANGELOG rename
+  # happens in the release PR, not the feature PR).
+  changelog-check:
+    if: github.event_name == 'pull_request' && github.base_ref == 'master'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Validate CHANGELOG release discipline
+        run: python scripts/check_changelog.py CHANGELOG.md

polily-0.11.1/.github/workflows/publish-to-pypi.yml

@@ -0,0 +1,94 @@
+name: Publish to PyPI
+
+# Why this workflow exists
+# ------------------------
+# Automatically publish polily to PyPI on every stable release. Triggered
+# by the `released` event (when `gh release create vX.Y.Z` flips the
+# release out of draft into "published"); skipped for prereleases.
+#
+# Authentication is via PyPI Trusted Publishing (OIDC) — no long-lived
+# API token. PyPI verifies the OIDC token from GitHub identifies the
+# expected repo + workflow + environment, and issues a short-lived
+# upload token automatically. See https://docs.pypi.org/trusted-publishers/
+#
+# Pre-flight requirement: the project owner registers a "pending
+# publisher" on PyPI (https://pypi.org/manage/account/publishing/) with
+# matching repo / workflow / environment names BEFORE the first release.
+#
+# Note on action pinning: actions are pinned to major version (@v4, @v5)
+# rather than commit SHA. Trade-off: floating-tag (lower friction, auto
+# security patches in v4.x) vs. SHA-pin (supply-chain hardening). Major-
+# pin matches the existing ci.yml convention. Future hardening: pin to
+# SHA via dependabot when GH supply-chain risk profile justifies it.
+
+on:
+  release:
+    types: [released]
+
+# Single in-flight publish. Defends against the rare case where a release
+# is flipped draft→published twice (e.g., GH UI hiccup) and two workflow
+# runs race the actual upload. cancel-in-progress: false because PyPI
+# rejects double-uploads anyway — better to let the first one finish
+# than half-cancel and confuse logs.
+concurrency:
+  group: pypi-publish
+  cancel-in-progress: false
+
+permissions:
+  id-token: write    # required for PyPI Trusted Publishing OIDC + sigstore attestations
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10  # OIDC handshake + build + upload finishes well under this
+    environment: pypi-publish    # matches PyPI pending publisher registration
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # hatch-vcs derives version from the nearest git tag.
+          # fetch-depth: 0 = full history, required for clean version.
+          fetch-depth: 0
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade pip build
+
+      - name: Build wheel + sdist
+        run: python -m build
+
+      - name: Verify built version matches release tag
+        # Defense against tag/version drift: if hatch-vcs produces something
+        # other than the clean release tag, fail fast before publishing.
+        # Example: tag v0.11.1 must produce polily-0.11.1-py3-none-any.whl.
+        #
+        # Extraction strategy: parse wheel filename via sed regex anchored
+        # on the canonical "-py3-none-any.whl" suffix. This handles PEP 440
+        # local versions (e.g. "0.11.1+local.foo") that the prior
+        # `re.match(r'polily-([^-]+)-')` would have truncated incorrectly.
+        run: |
+          tag="${GITHUB_REF#refs/tags/v}"
+          # ls -1 to one-per-line; head -1 to handle the (rare) multi-wheel case.
+          wheel=$(ls -1 dist/polily-*-py3-none-any.whl | head -1)
+          built=$(echo "$wheel" | sed -E 's|dist/polily-(.+)-py3-none-any\.whl|\1|')
+          echo "Release tag (without 'v' prefix): $tag"
+          echo "Built wheel version:               $built"
+          echo "Built wheel filename:              $wheel"
+          if [ "$tag" != "$built" ]; then
+            echo "::error::Version mismatch — tag=$tag built=$built. Aborting publish."
+            exit 1
+          fi
+
+      - name: Publish to PyPI via Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # Sigstore attestations: cryptographic proof that this artifact was
+          # built by THIS workflow run on THIS repo. PyPI auto-attaches the
+          # bundle to the release. Free with OIDC, and impossible to retrofit
+          # to existing releases later — turn it on at first publish.
+          # See https://docs.pypi.org/attestations/
+          attestations: true

polily-0.11.1/.github/workflows/sync-master-to-dev.yml

@@ -0,0 +1,95 @@
+name: Sync master → dev
+
+# Why this workflow exists
+# ------------------------
+# When a release PR (dev → master) is merged via "Create a merge commit"
+# (per CLAUDE.md release discipline, NOT squash), the merge commit is
+# added to master but NOT to dev. Dev then drifts behind master by one
+# commit. The next release PR flags "branch out-of-date with base"
+# until a manual sync PR is opened.
+#
+# This workflow runs that sync automatically: on every push to master,
+# open a sync/master-into-dev-<timestamp> branch, merge master, open
+# a PR to dev, enable auto-merge. Once CI on the sync PR goes green,
+# GitHub merges it with a merge-commit, restoring dev as a clean
+# descendant of master.
+#
+# Respects all branch protection rules — the bot goes through a PR
+# like any other contributor, and auto-merge only kicks in after the
+# protection rules (CI green, etc.) are satisfied.
+
+on:
+  push:
+    branches: [master]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          # SYNC_PAT (fine-grained PAT, Contents+PRs on polily) so
+          # the later `git push` and `gh pr create/merge` authenticate
+          # as a real user — triggers CI on the sync PR. GITHUB_TOKEN
+          # would create the PR as github-actions[bot], which GitHub
+          # intentionally does NOT trigger workflows for (prevents
+          # recursive workflow invocation).
+          token: ${{ secrets.SYNC_PAT }}
+
+      - name: Check whether dev is already up-to-date with master
+        id: check
+        run: |
+          git fetch origin dev master
+          BEHIND=$(git rev-list --count origin/dev..origin/master)
+          echo "Dev is behind master by $BEHIND commit(s)."
+          echo "behind=$BEHIND" >> "$GITHUB_OUTPUT"
+
+      - name: Skip — dev already contains master
+        if: steps.check.outputs.behind == '0'
+        run: echo "No sync needed; dev is already a descendant of master."
+
+      - name: Create sync branch, merge master, open + auto-merge PR
+        if: steps.check.outputs.behind != '0'
+        env:
+          # See Task 3.2 rationale: SYNC_PAT so the created PR triggers CI.
+          GH_TOKEN: ${{ secrets.SYNC_PAT }}
+        run: |
+          set -euo pipefail
+
+          SYNC_BRANCH="sync/master-into-dev-$(date +%Y%m%d-%H%M%S)"
+
+          # Bot identity for the merge commit.
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          # Branch off current dev, then merge master in with --no-ff to
+          # guarantee a merge commit (preserves ancestry even if dev
+          # happens to be a strict ancestor of master).
+          git checkout -b "$SYNC_BRANCH" origin/dev
+          git merge --no-ff origin/master \
+            -m "Sync master → dev (auto after release)"
+
+          git push origin "$SYNC_BRANCH"
+
+          gh pr create \
+            --base dev \
+            --head "$SYNC_BRANCH" \
+            --title "sync: master → dev (auto)" \
+            --body "$(cat <<'BODY'
+          Auto-generated by the `Sync master → dev` workflow after a push
+          to master. Keeps dev a strict descendant of master so the next
+          release PR lands as a clean fast-forward.
+
+          No code changes — merge commit only. CI runs as a sanity check
+          before auto-merge.
+          BODY
+          )"
+
+          # Auto-merge with merge-commit strategy (matches CLAUDE.md
+          # release discipline; squash would defeat the whole purpose).
+          gh pr merge --merge --auto "$SYNC_BRANCH"

polily-0.11.1/.gitignore

@@ -0,0 +1,49 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environment
+.venv/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# Runtime data (all user-generated, never committed)
+data/
+
+# Auto-generated by polily from db on every startup; users should not
+# edit or commit this file. Edit via TUI → ⚙ 配置.
+/config.yaml
+
+# Environment
+.env*
+# v0.11.0 — .envrc.example is a dev-workflow template that must be in git;
+# .envrc itself stays ignored via .env* above
+!.envrc.example
+
+# Internal docs (not for public repo)
+companion-note.md
+docs/internal/
+
+# Temp files
+*.tmp
+/tmp/
+
+# Test/coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Claude Code
+.claude/
+*.db-shm
+*.db-wal
+docs/internal/

polily-0.11.1/AGENTS.md

@@ -0,0 +1,168 @@
+# AGENTS.md
+
+Instructions for Codex when working on this codebase.
+
+## Product Identity
+
+**Polily — A Polymarket Monitoring Agent That Actually Works**
+
+Finds structure, surfaces risk, sizes friction, watches positions. The user pulls the trigger today. Autopilot is on the roadmap but not the current default — design new features so they remain compatible with both modes.
+
+## Design Context
+
+Not a user-profile spec — these are facts about how the product is used, useful when deciding trade-offs:
+
+- **Small-account usage pattern.** $5 in friction cost is not a rounding error at this tier. Surface every fee / slippage component explicitly; never silently absorb costs into a "net" number.
+- **Manual operation, not automation.** Users click buttons; sub-second latency isn't the pressure. But signals must be scannable — a user should decide "look closer vs. skip" in ≤5s.
+- **Daily review cadence.** ≥5s refresh intervals are fine; no tick-level streaming UI needed. Heartbeat-driven refresh (see `polily/tui/screens/main.py::_bus_heartbeat`) is the canonical pattern.
+- **URL-driven depth, not scan breadth.** Users bring their own events. The pipeline is deep due-diligence on one event at a time, not shallow breadth across thousands. If a feature requires iterating 8000+ markets, it's likely a misunderstanding of the product shape.
+- **Due diligence, not signal generation.** Output is "here's what the numbers say, here's the risk, here's the friction" — conditional framing, never unconditional commands like "buy YES".
+
+## Architecture (Event-First)
+
+**Data model:** Events (parent) → Markets (children). All state in unified SQLite (`data/polily.db`). No scan archives, no JSON files. Events carry tier/score/monitor state; markets carry prices/orderbook.
+
+**Entry flow:** **URL-driven, single-event.** User pastes a Polymarket event URL into the TUI. `polily.url_parser` extracts the event slug. `polily.scan.pipeline.fetch_and_score_event` fetches the event + child markets from Gamma API → applies hard filters → computes structure score (5-dim) → runs mispricing detection → optionally calls NarrativeWriter agent → assigns tier → persists to events/markets tables. **There is no batch scan over 8000+ markets** — that pattern was removed in v0.5.0.
+
+**Poll architecture:** Single global poll job runs every **30 seconds** on a dedicated 1-thread executor. Fetches prices for all markets the user has added to monitoring. Movement detection runs inline per tick (magnitude + quality scoring). If significant movement detected, triggers AI analysis on the `ai` executor (5 threads).
+
+**Daemon:** Dual-executor APScheduler daemon (`polily/daemon/scheduler.py`). Poll executor (1 thread) for price polling. AI executor (5 threads) for concurrent analysis jobs. Managed via `polily scheduler run/stop/restart/status`. Started via launchd in production.
+
+**Why "monitoring agent" rather than research assistant / signal generator?**
+Users don't want data dumps (research) or commands (signals). They want something that keeps watching on their behalf and surfaces what actually changed — price moves, structure shifts, position risk, end-dates coming up. Conditional advice ("if you're bullish, this may have edge") is OK. Definitive signals are not.
+
+**Why Structure Score ≠ trade quality?**
+Score measures tradability (spread, depth, objectivity, time, friction). Not profitability. Always communicate it that way to users.
+
+**Why URL-driven instead of batch scanning?**
+Users have domain edge in specific events — they already know what they want to look at. Batch scanning produced noise and rate-limit issues; deep single-event analysis is what actually informs decisions.
+
+**Why Binance (ccxt) not CoinGecko?**
+CoinGecko free tier rate-limits aggressively (429 errors). Binance via ccxt has 6000 weight/min, no API key needed, first-party exchange data.
+
+**Why AI agents use `Codex -p` CLI?**
+Included in Codex subscription, no per-token cost. Response parsed from `result` field (not `structured_output`). JSON extracted from markdown code blocks via regex fallback.
+
+## Coding Conventions
+
+- Python 3.11+, type hints everywhere
+- Pydantic for data models and config
+- `async` for I/O (HTTP, ccxt), `sync` for pipeline orchestration
+- TDD: write test first (red), implement (green), refactor
+- Chinese for all user-facing output (terminal, narratives, prompts)
+- English for code, variable names, comments
+- No unnecessary abstractions — three similar lines beats a premature abstraction
+- Config-driven: thresholds, weights, behavior live in `polily.db` `config` table (canonical since v0.10.0). TUI ⚙ 配置 edits live values via `save_knob`; `config.yaml` on disk is a read-only auto-generated snapshot regenerated after each save. Do NOT edit `config.yaml` and expect it to load — it's overwritten on every TUI launch / save / `polily config reset`. The CLI escape hatch is `polily config reset --all` or `polily config reset <key>`. Pre-v0.10.0 `config.yaml` files are auto-migrated to db on first boot (invalid yaml is preserved as `config.yaml.bak`).
+- Single AI agent (NarrativeWriter). No silent fallback — CLI failures raise and land as `failed` scan_logs rows.
+- **All AI calls go through `Codex -p` CLI**, never the `anthropic` SDK. Reason: uses the user's Codex subscription instead of per-token billing. `BaseAgent` at `polily/agents/base.py` is the only place that shells out — don't add a second integration path.
+
+## Key Files
+
+| File | Role |
+|------|------|
+| `polily/__init__.py` | Public API surface (v0.6.0) |
+| `polily/cli.py` | CLI: TUI launch + `scheduler` subcommands + `reset` (`--wallet-only`) |
+| `polily/url_parser.py` | Polymarket URL → event slug |
+| `polily/scan_log.py` | Scan log entries (per-event run history) |
+| `polily/analysis_store.py` | NarrativeWriter analysis versions per event |
+| `polily/core/db.py` | Unified SQLite database (PolilyDB) |
+| `polily/core/config.py` | All Pydantic config models |
+| `polily/core/models.py` | Market, BookLevel, Trade models |
+| `polily/core/event_store.py` | EventRow, MarketRow, upsert/query |
+| `polily/core/lifecycle.py` | Market / Event lifecycle state derivation (v0.8.5). `MarketState` (TRADING / PENDING_SETTLEMENT / SETTLING / SETTLED) + `EventState` (ACTIVE / AWAITING_FULL_SETTLEMENT / RESOLVED) derived from `closed` + `end_date` + `resolved_outcome` — no DB column, derive-on-read |
+| `polily/core/monitor_store.py` | Event monitor state (v0.7.0: user-intent flag only — `auto_monitor` / `price_snapshot` / `notes`) |
+| `polily/core/wallet.py` | WalletService — cash + ledger + atomicity contract (commit=False) |
+| `polily/core/positions.py` | PositionManager — aggregated (market_id, side) positions, weighted-avg cost |
+| `polily/core/trade_engine.py` | TradeEngine — atomic buy/sell (wallet + position + fee in one BEGIN/COMMIT) |
+| `polily/core/fees.py` | Polymarket category-based taker fee curve |
+| `polily/core/wallet_reset.py` | Hard reset util (requires no concurrent writer — see docstring) |
+| `polily/scan/pipeline.py` | **Single-event** orchestrator: fetch → filter → score → mispricing → AI → tier |
+| `polily/scan/scoring.py` | Structure score (5-dimension) |
+| `polily/scan/event_scoring.py` | Event-level aggregation + tier assignment |
+| `polily/scan/filters.py` | Hard filters |
+| `polily/scan/mispricing.py` | Crypto vol-implied mispricing detection |
+| `polily/scan/commentary.py` | Per-dimension score commentary |
+| `polily/scan/tag_classifier.py` | Market type / tag classification |
+| `polily/monitor/scorer.py` | Movement scorer (magnitude + quality) |
+| `polily/monitor/signals.py` | Movement signal computation |
+| `polily/monitor/drift.py` | CUSUM drift detector |
+| `polily/monitor/store.py` | Movement records storage |
+| `polily/monitor/event_metrics.py` | Per-event movement metrics |
+| `polily/daemon/scheduler.py` | APScheduler daemon: dual executor + launchd; wires scheduler into `_ctx` so `global_poll`'s Step 3.5 dispatcher can submit. Plist auto-heal in `ensure_daemon_running` (v0.9.0) |
+| `polily/daemon/launchctl_query.py` | `launchctl list com.polily.scheduler` parser + `kill_daemon(sig)` helper (v0.9.0). Replaced `data/scheduler.pid` as source of truth for "is daemon alive" |
+| `polily/daemon/poll_job.py` | Global poll job (30s): fetch prices → auto-resolution → score refresh → **Step 3.5 dispatcher (drain overdue `scan_logs` pending rows)** → intelligence layer |
+| `polily/daemon/resolution.py` | ResolutionHandler — atomic per-market settle on Gamma outcomePrices |
+| `polily/daemon/close_event.py` | Event archival / close handling |
+| `polily/daemon/auto_monitor.py` | Auto-monitor toggle logic |
+| `polily/daemon/score_refresh.py` | Periodic structure-score refresh |
+| `polily/agents/narrator_registry.py` | In-process narrator cancel registry (scope: process-local; see docstring for cross-process limitation) |
+| `polily/agents/base.py` | BaseAgent: Codex CLI invoke + retry + JSON parsing |
+| `polily/agents/narrative_writer.py` | NarrativeWriter agent (decision advisor) |
+| `polily/agents/schemas.py` | Pydantic schemas for agent I/O |
+| `polily/agents/prompts/` | Markdown prompt files for agents |
+| `polily/tui/app.py` | Textual TUI entry point |
+| `polily/tui/screens/main.py` | Main screen: sidebar + content + worker (menu: tasks/monitor/paper/wallet/history/notifications); 5s `_bus_heartbeat` bridges daemon-side DB writes to TUI subscribers |
+| `polily/tui/_dispatch.py` | `dispatch_to_ui(app, fn)` thread-hop helper + `@once_per_tick` coalescing decorator (React-style batching). Load-bearing for heartbeat-driven refresh — see v0.9.0 `call_later` signature fix |
+| `polily/tui/service.py` | `PolilyService` — bridge between TUI views and backend; owns wallet/positions/trade_engine |
+| `polily/tui/views/` | Per-pane views (scan_log, monitor_list, paper_status, event_detail, wallet, history, archived_events, changelog) |
+| `polily/tui/views/changelog.py` | ChangelogView — renders CHANGELOG.md via Markdown widget; reads from repo root in dev or from packaged resource (see `pyproject.toml` `force-include`) in installed wheels |
+| `polily/tui/views/trade_dialog.py` | Modal with Buy/Sell tabs — calls TradeEngine.execute_buy/sell |
+| `polily/tui/views/wallet.py` | WalletView — balance + transactions ledger + topup/withdraw/reset |
+| `polily/tui/views/wallet_modals.py` | TopupModal / WithdrawModal / WalletResetModal |
+
+## Common Pitfalls
+
+- **No batch scan.** If a feature seems to require iterating all 8000 markets, it's likely a misunderstanding — the pipeline is single-event by URL. Batch poll only covers markets the user has explicitly added to monitoring.
+- NarrativeWriter agent uses `Codex -p --allowedTools Read,Bash,Grep,WebSearch,StructuredOutput` — agent autonomously reads DB, searches web, then outputs via StructuredOutput. Prompt rules in `polily/agents/prompts/narrative_writer.md`.
+- `Codex -p --output-format json` (CLI v2.1+) returns a **JSON array**: `[{"type":"system",...}, {"type":"assistant",...}, {"type":"result","result":"..."}]`. Find the `{"type":"result"}` element (last in array), then parse `result` field.
+- TUI exit uses `os._exit(0)` because `Codex -p` spawns Node.js subprocesses that survive normal shutdown.
+- Textual workers: pass function reference (no parentheses), not coroutine. All UI updates from worker threads must use `call_from_thread`.
+- Global poll runs every **30s** on a dedicated single-thread executor. Movement detection is inline (no separate job). AI analysis is triggered on the ai executor (5 threads).
+- Daemon aliveness + PID lookup all go through `launchctl list com.polily.scheduler` (see `polily/daemon/launchctl_query.py`). The legacy `data/scheduler.pid` file was dropped in v0.9.0 — launchctl is the single source of truth. `SIGUSR1` still triggers job reload from DB.
+- **CLOB /book API returns distorted books for negRisk markets** (GitHub Issue #180): returns the raw token book with bid=0.01 / ask=0.99, which does not reflect the real liquidity provided by complement matching. Use `/midpoint` for the true price and the difference between `/price?side=BUY` and `/price?side=SELL` for the true spread. `/book` depth data is unreliable for negRisk markets.
+- **`paper_trades` no longer exists.** Dropped in v0.6.1 — `positions` + `wallet_transactions` are the only trade-state tables. On DB init, `PolilyDB._init_schema` executes `DROP TABLE IF EXISTS paper_trades` so old installs auto-clean. All writes go through `TradeEngine.execute_buy/sell`; history reads go through `PolilyService.get_realized_history` (SELL + RESOLVE ledger rows).
+- **`wallet.credit(commit=False)` defers the cash write to the outer transaction.** `ResolutionHandler.resolve_market` wraps one BEGIN around the credit + position delete + ledger insert, so passing `commit=True` would split them and re-credit on retry. Any new "bulk close" code path must preserve this contract (see `polily/core/wallet.py:113-154`).
+- **`reset_wallet` has no built-in writer lock.** The CLI path stops the scheduler daemon first; the TUI `WalletResetModal` sends SIGTERM + 1s grace before calling reset (on a worker thread so the event loop doesn't freeze). Any new caller MUST guarantee no concurrent writer — otherwise DELETE races with a mid-flight poll INSERT.
+- **`cumulative_realized_pnl` on the wallet snapshot is derived**, not stored: `SUM(wallet_transactions.realized_pnl) WHERE realized_pnl IS NOT NULL`. Goes to 0 automatically after reset (wallet_transactions is cleared). Don't try to mirror it into a stored column.
+
+## Release Process
+
+Polily is open source; releases need to follow a standard. Always use `gh release create` (which creates the tag and release page together); don't run `git tag` standalone.
+
+| Stage | Branch | Command | GitHub label |
+|-------|--------|---------|--------------|
+| Early access | dev | `gh release create v0.6.0-beta.1 --target dev --prerelease` | Pre-release |
+| Stable | master | `gh release create v0.6.0 --target master` | Latest |
+
+**Cadence:**
+1. Feature-complete on dev → ship `vX.Y.0-beta.N` (prerelease)
+2. Collect feedback, fix bugs → ship `vX.Y.0-beta.N+1` (prerelease)
+3. Once stable, merge to master → ship `vX.Y.0` (latest)
+
+**CHANGELOG.md workflow** (Keep a Changelog + SemVer):
+- Update `[Unreleased]` as part of every PR that has user-visible change. Don't let it drift — it's the source of truth for what ships next.
+- Before `gh release create`, diff dev since the last tag and cross-check that every commit with user-visible impact is already in `[Unreleased]` (or the version section). Commits made after the PR merged (hotfixes, follow-ups, docs-only cleanups) are the usual gap.
+- On release, rename `[Unreleased]` → `[X.Y.Z] — YYYY-MM-DD` and update the compare/tag links at the bottom. Don't open a new section for the same version across beta→stable — keep accumulating in one section so the stable release notes reflect the cumulative truth.
+- If you realize post-release the section missed something, patch that version's section directly (commit to dev titled `docs(changelog): catch up [X.Y.Z]`), don't start a new section.
+
+**Branch channel discipline:**
+- **dev is the only channel to master.** Every PR into master MUST have `head=dev`. Never open a PR to master from a release branch, feature branch, or any other source — even if the content would be identical to dev.
+
+**Merge strategy per PR type:**
+- **Feature PR → dev**: squash merge (keep dev's log granular, one commit per feature).
+- **Release PR `dev → master`**: **"Create a merge commit"** — NOT squash. The merge commit preserves dev's commits as ancestors of master, so the next release PR is a clean fast-forward.
+- **Sync PR (one-time fix when ancestry is broken)**: merge commit. Same reason.
+- **Why this matters:** v0.6.0 + v0.6.1 both had 5-file conflicts on `dev → master` because prior syncs/releases were squashed — that collapses master's history into a single commit on dev (or vice versa), losing the ancestry link. v0.6.1's PR #43 + #44 both used merge commits to establish proper ancestry; v0.6.2 and forward should be clean fast-forwards.
+- **Repo setting**: `allow_merge_commit=true` (enabled 2026-04-19 as part of v0.6.1 release). `allow_squash_merge=true` stays on for feature PRs.
+
+**Auto-sync master → dev (post-v0.9.0)**:
+- `.github/workflows/sync-master-to-dev.yml` triggers on every push to master (including release merge-commits).
+- Workflow opens `sync/master-into-dev-<timestamp>` PR and enables auto-merge; once CI passes, GitHub merges it with a merge-commit, restoring dev as a strict descendant of master.
+- Net effect: after a release PR merges, the next release PR is a clean fast-forward within a few minutes. **No manual sync work needed.**
+- If the auto-sync ever fails (CI red on the sync PR, merge conflict, workflow disabled), fall back to the manual steps below.
+
+**Manual sync fallback** (only if auto-sync fails):
+1. Branch `sync/master-into-dev` from dev.
+2. `git merge origin/master`, resolve conflicts (usually take dev's version — it's the newer state).
+3. PR that branch → **dev** (not master). **Merge via "Create a merge commit"**, not squash.
+4. After merge, dev is a clean descendant of master. Open the release PR dev → master (clean fast-forward).