sciqnt 0.1.0__py3-none-any.whl

sciqnt-0.1.0.dist-info/METADATA

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: sciqnt
+Version: 0.1.0
+Summary: sciqnt — local-first, agent-native cross-asset portfolio tracker & data layer (CLI/TUI)
+Author: sciqnt
+License: MIT
+Project-URL: Homepage, https://github.com/sciqnt/sciqnt
+Project-URL: Source, https://github.com/sciqnt/sciqnt
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sciqnt-schema<0.2,>=0.1
+Requires-Dist: sciqnt-fmt<0.2,>=0.1
+Requires-Dist: sciqnt-config<0.2,>=0.1
+Requires-Dist: sciqnt-price-store<0.2,>=0.1
+Requires-Dist: sciqnt-compute<0.2,>=0.1
+Requires-Dist: sciqnt-performance<0.2,>=0.1
+Requires-Dist: sciqnt-market-data<0.2,>=0.1
+Requires-Dist: sciqnt-fx<0.2,>=0.1
+Requires-Dist: sciqnt-secrets<0.2,>=0.1
+Requires-Dist: sciqnt-analytics<0.2,>=0.1
+Requires-Dist: sciqnt-aggregator<0.2,>=0.1
+Requires-Dist: sciqnt-skills<0.2,>=0.1
+Requires-Dist: sciqnt-agents<0.2,>=0.1
+Requires-Dist: prompt-toolkit
+Requires-Dist: questionary
+Dynamic: license-file
+
+# sciqnt
+
+**A local-first, agent-native portfolio tracker & cross-asset financial data
+layer.** One canonical, point-in-time-correct schema for your positions,
+transactions, cash and prices — fed by community connectors for each broker
+/ exchange / data source, rendered in a fast TUI, and consumable by any AI
+agent (Claude Code, Codex, …) through plain CLI + versioned JSON surfaces.
+
+Deterministic code computes the numbers. Agents reason and explain. You own
+every byte: your credentials live in your OS keyring, your data on your
+disk — there is no server.
+
+```
+  net worth (EUR) │ daily
+
+  24,570 ┤                                                       ⢀⡤⠖⠋⠹
+         │                                 ⣀⡤⣄⣤⣀⣀⣀⣀⣀  ⡤⠤⠤⠤⣄ ⣀⣀⣀⣀⡤⠞
+  22,019 ┤                            ⢀⣠⢤⣰⠒⠃     ⠉ ⠈⠉⠛⠁   ⠈⠉⠁⠉⠈⠁
+         │                    ⢀⣰⠒⠚⠉⠉⠓⠒⠋
+         │⣀          ⣀⢀⣀⣠⠤⠖⠋⠛⠉⠉
+  19,468 ┤⠈⠙⠒⢦⣀⡤⠤⣤⣄⣠⠴⠋⠉
+         ╰────────────────────────────────────────────────────────────
+          2026-01-02                                        2026-06-12
+
+  total value             24,121.05 EUR      TWR        13.70 %/yr
+  total P/L (lifetime)    +3,340.95 EUR      XIRR        9.79 %/yr
+  dividends (lifetime)      +395.10 EUR      max DD     −14.5 %
+```
+
+*That's the built-in demo portfolio — synthetic and deterministic. sciqnt
+runs in demo mode until you connect an account; no real finances appear in
+any screenshot or doc, ever.*
+
+## Install
+
+```sh
+git clone https://github.com/sciqnt/sciqnt && cd sciqnt
+python3 -m venv .venv && .venv/bin/pip install pydantic prompt-toolkit keyring
+./bin/sciqnt install        # adds `sciqnt` to your PATH
+sciqnt                      # the interactive home (demo portfolio until you connect)
+```
+
+PyPI packages (`uv tool install sciqnt`, `pip install sciqnt-degiro`, …) are
+coming with the first tagged release. macOS note: use a Python built
+against modern OpenSSL (e.g. Homebrew `python@3.13`) — the system Python's
+LibreSSL is fragile against financial-API TLS.
+
+## What you get
+
+- **The TUI**: portfolio home with net-worth chart (1D…All ranges,
+  5-minute intraday), positions / exposure / income / news / flows /
+  history tabs, account drill-downs — everything keyboard-driven.
+- **Honest money math**: `Decimal` end-to-end, FIFO/LIFO/AVG lots,
+  fees-inclusive cost basis, TWR (GIPS-style breaks), XIRR, max drawdown,
+  benchmark comparison — computed from your raw transaction history,
+  point-in-time-correct (`sciqnt --asof 2024-12-31`).
+- **Connectors as self-contained bundles** (`modules/sq-*`): manifest +
+  agent-facing SKILL + a living quirks log (FINDINGS) + conformance tests.
+  Degiro (CSV + live), Robinhood, Kalshi, Polymarket, Yahoo, Tiingo, ECB
+  FX, SEC EDGAR, FIRDS, OpenFIGI, RSS news — and a scaffold + harness for
+  building your own.
+- **Agent-native, both directions**: every view is reproducible from the
+  CLI (`sciqnt --help` maps it; `--json` gives versioned, Decimal-as-string
+  data — `sciqnt.portfolio/v1`, `sciqnt.history/v1`, …). Summon your coding
+  agent from any screen and it receives where you are, what's on your
+  screen, and the command that reproduces it; agents can leave findings on
+  your home screen (`sciqnt insight add`).
+- **A point-in-time price archive**: append-only, bitemporal, yours.
+
+## For agents
+
+Run `sciqnt --help`. Every screen of the app has a CLI form; add `--json`
+for structured data. Skills ship in-repo (`sq-portfolio`, `sq-connectors`)
+and install into Claude Code / Codex automatically when summoned from the
+app. **[`AGENTS.md`](AGENT_GUIDE.md) is the codebase map — start there if
+you're an agent.**
+
+## Build a connector for your broker
+
+The platform ships the contract + conformance harness + a scaffold — the
+long tail of connectors belongs to the community (and to your coding
+agent). See [CONTRIBUTING.md](CONTRIBUTING.md); the short version:
+
+```
+"build a sciqnt connector for <my broker>"   # tell your coding agent
+```
+
+Independent connector repos install with `sciqnt modules add owner/repo`
+(conformance runs locally before first use — trust is earned by the
+harness, not claimed).
+
+## Going deeper
+
+- [`FOUNDATION.md`](FOUNDATION.md) — the worldview + the 13 Founding Articles.
+- [`PRINCIPLES.md`](PRINCIPLES.md) — the 18 operating principles.
+- [`research/`](research/) — the grounded reasoning behind every decision.
+
+Principles, the short list: local-first and sovereign — fire us and keep
+everything. Deterministic core, probabilistic edge — LLMs never touch the
+money math. Data first — rendered text is for humans, versioned JSON is the
+contract. Read wide, execute gated. Synthetic fixtures only.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

sciqnt-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+sciqnt_cli.py,sha256=NPRwf1ZXn7OY8KXShJ_ZBTGGNl0RzzvN5TUGFuR8nQo,4801
+sciqnt-0.1.0.dist-info/licenses/LICENSE,sha256=rozsqhc3L9xo499FRoHjuzJHojz77OlAQzl_T7VKJPE,1069
+sq_config_ui/__init__.py,sha256=kvd_d3J-UjqSTq3vL8BG-c1tTPsilDexfvG3GY0P1Ls,10515
+sq_platform/__init__.py,sha256=e_PtFqX1K0kytqwaPNHwGJuDo9uN_ucWzTGbW3zwj_4,19188
+sq_platform/_cache.py,sha256=6HLXzkYE-pgBzvnW7TwTt21xSu3Plb0_6kZsA8jWBvU,9041
+sq_platform/aggregated.py,sha256=4xEk-Nfi-NHu04gXOEAYvLVaHL1HmFOL2L5QtR7Cf-c,130608
+sq_platform/home.py,sha256=_x8923kIPyTIXtttQfJrZo9gNquX1fqBmN6Cen40ANM,55851
+sq_platform/insights.py,sha256=stu65YZWhUCUw7Miy-eRECymYOtCCrNkgcvynqRZqe4,4798
+sq_platform/modules_cmd.py,sha256=8XvFXoyDA2inpXsJzp46tpwWt90rJ4a5QyM5slfWXvY,11499
+sq_tui/__init__.py,sha256=rNi1qmz-_55MjzAuZiaYTmwKpPl7xPFo-VB1uA_y7Bs,51015
+sciqnt-0.1.0.dist-info/METADATA,sha256=xDvX2g-7yCGPca0zC_03gGjouCruOfIWeLzLNKgLIU8,5968
+sciqnt-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+sciqnt-0.1.0.dist-info/entry_points.txt,sha256=uwhH-DEVGXRVCvSb-XlU3MZ_sjny7WzD2EQeSp_qpqY,43
+sciqnt-0.1.0.dist-info/top_level.txt,sha256=ghRsqQpgT-FsNH8n2XxZanwpZVvZs7f_kvI4ft6hHeE,43
+sciqnt-0.1.0.dist-info/RECORD,,

sciqnt-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sciqnt-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sciqnt = sciqnt_cli:main

sciqnt-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DavideGCosta
+
+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.

sciqnt-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,4 @@
+sciqnt_cli
+sq_config_ui
+sq_platform
+sq_tui

sciqnt_cli.py

@@ -0,0 +1,107 @@
+"""sciqnt — the installed CLI front door.
+
+The pip-installable entry point for the component-world structure: `pip install
+sciqnt` brings the app (sq_platform + sq_tui + config-UI) plus its library deps
+(pinned to the `sciqnt/sq-*` repos), and `sciqnt` launches it.
+
+Unlike the in-repo `bin/sciqnt` launcher (which assumed the monorepo layout), this
+entry is layout-free: the app's library deps are installed packages, and connectors
+are discovered from the **user dir** (`~/.local/share/sciqnt/modules/`, populated by
+`sciqnt modules add owner/repo`) — sovereign, no repo `modules/` needed.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from datetime import datetime, time, timezone
+from pathlib import Path
+
+
+def _root() -> Path:
+    """The app's data root. For an installed app there's no repo `modules/`, so the
+    root is the user data dir — `bundle_dirs(root)` then resolves to the same user
+    modules dir connectors are added into. Overridable via $SQ_ROOT."""
+    return Path(os.environ.get("SQ_ROOT", Path.home() / ".local" / "share" / "sciqnt"))
+
+
+def _setup_bundles(root: Path) -> None:
+    """Put every installed connector bundle's src/ on sys.path so `import sq_<broker>`
+    resolves inside the aggregation registry (mirrors bin/sciqnt-aggregated.py)."""
+    import sq_platform
+    for src in sq_platform.bundle_src_paths(root):
+        if src not in sys.path:
+            sys.path.insert(0, src)
+
+
+def _parse_asof(s: str) -> datetime:
+    try:
+        return (datetime.fromisoformat(s).replace(tzinfo=timezone.utc) if "T" in s
+                else datetime.combine(datetime.fromisoformat(s).date(),
+                                      time(23, 59, 59), tzinfo=timezone.utc))
+    except ValueError as e:
+        raise argparse.ArgumentTypeError(
+            f"--asof must be YYYY-MM-DD or ISO timestamp; got {s!r}") from e
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    root = _root()
+    root.mkdir(parents=True, exist_ok=True)
+
+    # Sub-commands that route straight into the platform (parsed before the
+    # aggregated-view flags, exactly like the original bin/sciqnt dispatcher).
+    if argv and argv[0] == "modules":
+        import sq_platform  # noqa: F401
+        from sq_platform import modules_cmd
+        _setup_bundles(root)
+        return modules_cmd.cli(root, argv[1:])
+    if argv and argv[0] == "--list":
+        import sq_platform
+        _setup_bundles(root)
+        return sq_platform.find_modules(root, " ".join(argv[1:]))
+
+    # Otherwise: the aggregated / interactive portfolio view.
+    _setup_bundles(root)
+    import sq_config
+    sq_config.materialise()
+    from sq_platform.aggregated import run_aggregated
+    from sq_platform.home import run_home
+
+    p = argparse.ArgumentParser(prog="sciqnt", description="sciqnt — portfolio view")
+    p.add_argument("--asof", type=_parse_asof, default=None,
+                   help="as-of date (YYYY-MM-DD) for a PIT historical view")
+    p.add_argument("--fresh", action="store_true",
+                   help="bypass the snapshot cache and force a live fetch")
+    p.add_argument("--once", action="store_true",
+                   help="print the aggregated view once and exit (non-interactive dump)")
+    p.add_argument("--history", nargs="?", const="30", default=None, metavar="RANGE",
+                   help="print portfolio state history and exit")
+    p.add_argument("--account", default=None, metavar="LABEL",
+                   help="one account only, in its own base currency")
+    p.add_argument("--tab", default=None, metavar="NAME",
+                   help="dump just one tab (summary/positions/exposure/news/flows/detailed)")
+    p.add_argument("--json", action="store_true", dest="as_json",
+                   help="emit structured data instead of the rendered view")
+    args = p.parse_args(argv)
+
+    interactive = (sys.stdin.isatty() and sys.stdout.isatty()
+                   and args.asof is None and not args.once
+                   and args.history is None and args.account is None
+                   and args.tab is None and not args.as_json)
+    try:
+        if interactive:
+            return run_home(root, use_snapshot_cache=not args.fresh)
+        if args.history is not None:
+            from sq_platform.aggregated import run_history
+            return run_history(root, args.history, account=args.account,
+                               as_json=args.as_json, use_snapshot_cache=not args.fresh)
+        return run_aggregated(root, asof=args.asof, account=args.account, tab=args.tab,
+                              as_json=args.as_json, use_snapshot_cache=not args.fresh)
+    except KeyboardInterrupt:
+        print()
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

sq_config_ui/__init__.py

@@ -0,0 +1,252 @@
+"""sq_config_ui — THE interactive settings screen for sciqnt.
+
+One full-screen settings experience (sq_tui.select_screen on the alternate
+screen), consistent with the rest of the app — NOT questionary (questionary
+choices don't render ANSI, which is how the old picker leaked raw `^[[2m`
+escapes into labels). Every entry point shares this loop:
+
+  * `sciqnt config` (bare) and `sciqnt config set`  → set.py → run_settings()
+  * the home's Settings action                       → sq_platform.home calls
+    run_settings() in-process with the home chrome, so the experience is
+    identical from home and CLI.
+
+The screen lists every setting from `sq_config.schema()`: key left, CURRENT
+value right (accent bold); not-yet-wired (`mvp=False`) settings render dim
+with a "(soon)" suffix. Per-setting help lives in the `?` overlay, not in the
+rows. Selecting a row edits it:
+  enum → a second select_screen (current preselected, per-option descriptions),
+  bool → toggles immediately (no second screen),
+  str  → text_input_screen prefilled with the current value (empty → cancel).
+All writes go through `sq_config.set()` (schema-validated, atomic) — an
+invalid value is never written. After an edit the screen re-renders with the
+cursor kept on the same row. Esc/q returns.
+
+Non-interactive callers must NOT enter this loop — `set.py` checks
+`sq_tui._streams_interactive()` and prints the plain dump (`show.py`, the
+script/agent-facing surface) instead.
+"""
+import textwrap
+from pathlib import Path
+
+import sq_config
+import sq_tui
+from sq_tui import BOLD, DIM, RST
+
+# repo root: modules/sq-config/src/sq_config_ui/__init__.py → up 4 levels
+_ROOT = Path(__file__).resolve().parents[4]
+
+# Style for the value cell on a non-hovered, wired row (accent bold — matches
+# the hover/selection accent everywhere else). Dim rows pass "" so the value
+# inherits the row's dim base.
+_VALUE_STYLE = f"fg:{sq_tui.ACCENT_HEX} bold"
+
+# Per-option descriptions for enum settings whose schema help implies them.
+# preferred_agent is handled dynamically (live install detection).
+_ENUM_DESC = {
+    "cost_basis_method": {
+        "FIFO": "first in, first out",
+        "LIFO": "last in, first out",
+        "AVG":  "average cost · ACB / Section-104 pool / Degiro BEP",
+    },
+    "performance_return_method": {
+        "TWR": "time-weighted — manager skill (GIPS default)",
+        "MWR": "money-weighted / XIRR — your personal cash-flow experience",
+    },
+}
+
+
+def parse_bool(v) -> bool:
+    """Tolerant bool read for the toggle (true/false/yes/no/1/0/on/off…).
+    Anything unrecognised reads as False — the toggle then writes True, a
+    safe self-heal for a hand-mangled value. Writes still go through
+    `sq_config.set`, which is strict."""
+    if isinstance(v, bool):
+        return v
+    return str(v).strip().lower() in ("true", "1", "yes", "on")
+
+
+def display_value(setting, value) -> str:
+    """The row's value cell: bools as lowercase true/false (matching the JSON
+    on disk), None as an em-dash, everything else str()."""
+    if value is None:
+        return "—"
+    if setting.type == "bool":
+        return "true" if parse_bool(value) else "false"
+    return str(value)
+
+
+def build_settings_items(schema, data):
+    """The settings rows for select_screen: (items, item_styles).
+
+    Each item is (fragments, key) — rich labels so the value cell can carry
+    its own style: key left, current value right in accent bold; mvp=False
+    rows get base style 'dim' plus a "(soon)" suffix (their value inherits
+    the dim base instead of the accent). Pure — unit-testable without a
+    terminal. Help text deliberately NOT in the row (it's in the ? overlay)."""
+    keyw = max(len(s.key) for s in schema)
+    vals = {s.key: display_value(s, data.get(s.key, s.default)) for s in schema}
+    valw = max(len(v) for v in vals.values())
+    items, styles = [], []
+    for s in schema:
+        frags = [("", f"{s.key:<{keyw}}   "),
+                 (_VALUE_STYLE if s.mvp else "", f"{vals[s.key]:>{valw}}")]
+        if not s.mvp:
+            frags.append(("", "  (soon)"))
+        items.append((frags, s.key))
+        styles.append(None if s.mvp else "dim")
+    return items, styles
+
+
+def help_text(schema) -> str:
+    """The `?` overlay: the keymap plus every setting's full help (the rows
+    stay data-only; the prose lives one keystroke away)."""
+    lines = [
+        f"  {BOLD}Keys{RST}",
+        "",
+        "  ↑ ↓  ·  j k     move",
+        "  enter           edit (a true/false setting toggles immediately)",
+        "  ?               toggle this help",
+        "  esc  ·  q       back",
+        "",
+        f"  {BOLD}Settings{RST}",
+        "",
+    ]
+    for s in schema:
+        soon = "" if s.mvp else f"  {DIM}(soon — declared, not yet wired){RST}"
+        lines.append(f"  {BOLD}{s.key}{RST}{soon}")
+        for ln in textwrap.wrap(s.help or "—", 72):
+            lines.append(f"    {DIM}{ln}{RST}")
+    lines += ["", f"  {DIM}config file: {sq_config.path()}{RST}"]
+    return "\n".join(lines)
+
+
+def _default_header(*crumbs) -> str:
+    """Standalone-CLI chrome: the banner + a bold 'Menu › Settings[ › …]'
+    breadcrumb — the same level layout as the home (which passes its own
+    richer chrome via `make_header`)."""
+    menu = "  Menu › Settings" + "".join(f" › {c}" for c in crumbs)
+    try:                                      # banner needs sq_platform (core)
+        from sq_platform import banner_text
+        top = banner_text(_ROOT) + "\n\n"
+    except Exception:                                       # noqa: BLE001
+        top = ""
+    return f"{top}{BOLD}{menu}{RST}"
+
+
+def _intro(s, cur) -> str:
+    """Dim context block for an edit screen: the setting's help (wrapped) +
+    current/default, appended to the header (header is ANSI-rendered, unlike
+    row labels — this is where styled prose belongs)."""
+    lines = textwrap.wrap(s.help or "", 72)
+    lines.append(f"current: {display_value(s, cur)} · default: {s.default}")
+    return "\n\n" + "".join(f"  {DIM}{ln}{RST}\n" for ln in lines)
+
+
+def _agent_descs(s):
+    """Live per-option tags for preferred_agent — like picking a default
+    browser: what 'auto' resolves to, and which agents are actually
+    installed. Degrades to no descriptions if detection fails."""
+    try:
+        import sq_agents
+        installed = set(sq_agents.detect())
+        auto = sq_agents.resolve("auto")
+        hint = sq_agents.label(auto) if auto else "none installed"
+        return {v: (f"auto → {hint}" if v == "auto"
+                    else "installed" if v in installed else "not installed")
+                for v in s.allowed}
+    except Exception:                                       # noqa: BLE001
+        return {}
+
+
+def enum_options(s, cur):
+    """The second-screen rows for an enum setting: value left, dim
+    description right (rich fragments — select_screen strips raw ANSI from
+    labels, so styling MUST be fragments, never escape codes), '(current)'
+    on the active value."""
+    descs = _agent_descs(s) if s.key == "preferred_agent" else \
+        _ENUM_DESC.get(s.key, {})
+    w = max(len(v) for v in s.allowed)
+    out = []
+    for v in s.allowed:
+        frags = [("", f"{v:<{w}}")]
+        d = descs.get(v, "")
+        if d:
+            frags.append(("class:dim", f"  {d}"))
+        if v == cur:
+            frags.append(("class:dim", "  (current)"))
+        out.append((frags, v))
+    return out
+
+
+def _pick_enum(s, cur, header_for):
+    """Enum edit: a second select_screen over the allowed values, the current
+    one preselected. Returns the picked value, or None on Esc."""
+    sel = sq_tui.select_screen(
+        enum_options(s, cur),
+        header=header_for(s.key) + _intro(s, cur),
+        selected=(s.allowed.index(cur) if cur in s.allowed else 0),
+        footer_hint="↑↓ move · enter set · esc cancel",
+        esc_result=sq_tui.BACK)
+    if sel in (sq_tui.BACK, sq_tui.QUIT):
+        return None
+    return sel
+
+
+def _enter_text(s, cur, header_for):
+    """Free-form edit: full-screen text input prefilled with the current
+    value. Empty (or Esc) → None = cancel, nothing written."""
+    raw = sq_tui.text_input_screen(
+        f"{s.key}:", header=header_for(s.key) + _intro(s, cur),
+        default="" if cur is None else str(cur),
+        footer_hint="enter save · esc cancel")
+    if raw == sq_tui.BACK or not str(raw).strip():
+        return None
+    return str(raw).strip()
+
+
+def _edit(s, header_for):
+    """Dispatch one edit by setting type. All writes go through
+    `sq_config.set` (schema-validated); a ValueError is swallowed — the loop
+    re-renders unchanged rather than ever writing an invalid value."""
+    cur = sq_config.get(s.key)
+    if s.type == "bool":
+        new = not parse_bool(cur)          # toggle immediately — no 2nd screen
+    elif s.type == "enum":
+        new = _pick_enum(s, cur, header_for)
+    else:                                  # str / int → free-form text
+        new = _enter_text(s, cur, header_for)
+    if new is None:
+        return
+    try:
+        sq_config.set(s.key, new)
+    except ValueError:
+        pass
+
+
+def run_settings(make_header=None):
+    """The settings loop. `make_header(*crumbs)` builds the chrome above the
+    list (the home passes its `_static_chrome`; standalone CLI defaults to
+    banner + breadcrumb). Re-renders after every edit with the cursor kept on
+    the edited row (select_screen.last_index); Esc/q returns.
+
+    Off-TTY, select_screen itself degrades to the numbered fallback — but
+    entry points should route pipes to the plain dump instead (see set.py)."""
+    header_for = make_header or _default_header
+    sq_config.materialise()                # file exists + carries every key
+    cursor = 0
+    while True:
+        schema = sq_config.schema()
+        items, styles = build_settings_items(schema, sq_config.all())
+        sel = sq_tui.select_screen(
+            items, header=header_for() + "\n",
+            item_styles=styles, selected=cursor,
+            footer_hint="↑↓ move · enter edit · ? help · esc back",
+            help_lines=help_text(schema), esc_result=sq_tui.BACK)
+        if sel in (sq_tui.BACK, sq_tui.QUIT):
+            return
+        li = getattr(sq_tui.select_screen, "last_index", 0)
+        if isinstance(li, int):            # mocked select stubs may omit it
+            cursor = li
+        s = next((x for x in schema if x.key == sel), None)
+        if s is not None:
+            _edit(s, header_for)