uxon 3.0.0__tar.gz

uxon-3.0.0/.gitignore

@@ -0,0 +1,30 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+
+# Build artefacts (hatchling / python -m build)
+dist/
+build/
+*.egg-info/
+
+# Local config (gitignored except the example)
+config/*
+!config/config.example.toml
+
+# Agent-only material — kept on local disk, never tracked in git
+.claude/
+AGENTS.md
+CLAUDE.md
+docs/agents/
+
+# Misc
+_external_sources/
+
+# Local environments and editor / OS junk
+.venv/
+.env
+.envrc
+.DS_Store
+*.swp
+.idea/
+.vscode/

uxon-3.0.0/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to this project are documented here. The format
+follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
+this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [3.0.0] — 2026-05-01
+
+First PyPI release.
+
+### Added
+
+- Released on PyPI as [`uxon`](https://pypi.org/project/uxon/).
+  Install with `uv tool install uxon`, `pipx install uxon`, or
+  `pip install --user uxon`.
+- `python -m uxon` works alongside the generated `uxon` console
+  script — same entrypoint, useful for in-tree development.
+- PyPI release pipeline at `.github/workflows/release.yml`: pushing
+  a `v*` tag builds sdist + wheel, publishes via OIDC trusted
+  publisher (no API token in GitHub Secrets), and creates a GitHub
+  Release with auto-generated notes. PEP 740 attestations are
+  generated automatically.
+- `legacy_session_prefixes` config key — array of additional `tmux`
+  prefixes that `uxon list` / `attach` / `kill` recognise alongside
+  `session_prefix`. Useful when migrating from a previous prefix.
+  New sessions are always created under `session_prefix`.
+- `docs/cli.md` — full CLI reference (every flag, exit code,
+  identifier resolution, repeat behaviour).
+- `docs/configuration.md` — use-case-driven configuration guide
+  (single-user laptop, multi-user host, sandboxed agent user,
+  pinning agents to directories, GitHub repo creation).
+
+### Changed
+
+- **`uxon` ships as a `src/uxon/` Python package** built with
+  `hatchling`. Out-of-tree consumers import from `uxon.*` (e.g.
+  `from uxon.settings import ...`, `from uxon.tui.app import ...`).
+- **`install/install_uxon.py`** now creates a dedicated venv at
+  `--venv-dir` (default `/opt/uxon/venv`), installs the package
+  into it, and symlinks the venv's console script to
+  `--install-path`. Used for the shared-host / multi-user VPS
+  scenario only — solo laptops use `uv tool install` /
+  `pipx install`. Adds `--dry-run` and `--reinstall` flags.
+- README rewritten around the TUI as the primary interface, with a
+  compact CLI summary linking to `docs/cli.md`. Install section
+  leads with `uv tool install uxon` and `pipx install uxon`.
+
+### Dependencies
+
+- `textual >=0.80,<9` and `tomlkit` are hard runtime dependencies,
+  pulled in automatically by `pip install` / `pipx install` /
+  `uv tool install`. The optional `dev` extra ships `pytest`,
+  `pytest-xdist`, `ruff`, and `pyright`.

uxon-3.0.0/CONTRIBUTING.md

@@ -0,0 +1,137 @@
+# Contributing to uxon
+
+Thanks for taking the time. This guide covers everything you need
+to make and ship a change.
+
+## Local setup
+
+`uxon` is a regular Python package (`pyproject.toml`, hatchling backend).
+For development, install editable into a venv. Two equivalent paths:
+
+```bash
+git clone https://github.com/vzd3v/uxon.git
+cd uxon
+
+# A) uv (recommended; faster, shared dep cache)
+uv venv
+uv pip install -e ".[dev]"
+source .venv/bin/activate
+
+# B) plain venv + pip
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install -e ".[dev]"
+
+uxon --version
+```
+
+Both pull `ruff`, `pyright`, `pytest`, `textual`, `tomlkit`
+automatically.
+
+`uxon` requires Python 3.11+. The TUI uses `textual >=0.80,<9`; config
+writes use `tomlkit`. Both are hard runtime dependencies (pulled in by
+`pip install` / `pipx install` / `uv tool install`).
+
+## Local checks
+
+Before opening a PR, run:
+
+```bash
+python3 -m py_compile $(git ls-files '*.py')
+python3 -m pytest tests/ -n auto
+ruff check .
+ruff format --check .
+pyright
+python -m build               # smoke-test the wheel/sdist
+twine check dist/*            # README rendering on PyPI
+```
+
+CI runs the same. If something passes locally but breaks CI, please
+add a test that catches it.
+
+## Branching and commits
+
+- Branch off `main`. Open PRs against `main`.
+- One logical unit per commit. No drive-by refactors mixed in with a
+  bug fix; split them into separate commits.
+- Commit-message subject in imperative mood ("add", "fix",
+  "rewrite") with a short body explaining *why*. Conventional Commits
+  (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`) is the existing
+  style — match it.
+- Never bypass git hooks (`--no-verify`) and never amend a published
+  commit.
+
+## When to bump `__version__`
+
+Bump `__version__` in [`src/uxon/__init__.py`](src/uxon/__init__.py)
+in the same commit as any user-visible behaviour change. Hatch reads
+the same string at build time, so wheels and the in-tree CLI always
+agree. Semver:
+- **Major** for breaking changes to the CLI surface, the config
+  schema, or the on-disk session-naming scheme.
+- **Minor** for new features that don't break existing config or
+  session names.
+- **Patch** for bug fixes and doc-only changes that affect users.
+
+Then add a matching entry to [`CHANGELOG.md`](CHANGELOG.md) under
+`## [Unreleased]`.
+
+## Architectural rules a contributor will hit
+
+These are non-negotiable — see [`docs/architecture.md`](docs/architecture.md)
+for the full picture. Quick list:
+
+- **`textual` is imported lazily inside `do_interactive`.** Non-TUI
+  subcommands (`uxon list`, `uxon doctor`, `uxon version`) must run
+  without `textual` installed.
+- **All key handling goes through `BINDINGS`.** No `on_key` overrides
+  on screen classes; a drift guard test refuses the PR otherwise.
+- **Config writes use `tomlkit`** — round-trip preserves comments and
+  formatting. CLI read paths stay on stdlib `tomllib`.
+- **One launch builder.** `uxon` is the single place that builds agent
+  command lines (`_build_tmux_launch_request` in `src/uxon/cli.py`).
+  Don't add direct agent exec calls anywhere else.
+- **Module boundaries.** `src/uxon/cli.py` may import from sibling
+  modules in `src/uxon/*`; those modules never import from `cli`. UI
+  files under `src/uxon/tui/` must not import `subprocess`/`pwd` or
+  touch the filesystem directly — push that through callbacks on
+  `TuiContext`.
+
+## Tests
+
+- Prefer pure tests in `src/uxon/tui/state.py` for branchy UI logic.
+  Pilot/pty tests are reserved for Textual wiring (mounting, key
+  routing, `ListView`/`DataTable` events, async workers,
+  `call_later`).
+- Don't add a new `App.run_test()` case when a pure state helper can
+  cover the behaviour and a smoke test already proves the wiring.
+- Batch compatible Pilot scenarios via
+  `tests/harness/textual_scenarios.py::run_screen_scenarios` —
+  amortise the Textual lifecycle.
+- Run the minimum sufficient subset while iterating
+  (`pytest tests/test_specific.py -k name`); always run the full
+  suite (`-n auto`) before pushing.
+
+## Adding a config key
+
+1. Extend `DEFAULT_CONFIG`, `Config`, and `load_config` in
+   `src/uxon/cli.py`.
+2. Add validation if the value space is constrained.
+3. Add a matching `SettingSpec` in
+   `src/uxon/settings.py::SETTINGS_SPECS` so the TUI Settings screen
+   exposes it.
+4. Document it in the README config table.
+5. Add a `load_config` test in `tests/test_uxon.py` and a
+   round-trip test in `tests/test_uxon_settings.py` if the value
+   has non-trivial encoding.
+
+## Reporting bugs and proposing features
+
+Please use the issue templates (bug reports include `uxon doctor`
+output and the exact command). For security issues, see
+[`SECURITY.md`](SECURITY.md).
+
+## License
+
+By contributing, you agree that your contributions are licensed
+under the [MIT License](LICENSE).

uxon-3.0.0/LICENSE

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

uxon-3.0.0/PKG-INFO

@@ -0,0 +1,373 @@
+Metadata-Version: 2.4
+Name: uxon
+Version: 3.0.0
+Summary: Multi-user wrapper for managing terminal AI coding agent sessions (claude, codex, cursor)
+Project-URL: Homepage, https://github.com/vzd3v/uxon
+Project-URL: Issues, https://github.com/vzd3v/uxon/issues
+Project-URL: Source, https://github.com/vzd3v/uxon
+Project-URL: Changelog, https://github.com/vzd3v/uxon/blob/main/CHANGELOG.md
+Author-email: Vasily Zakharov <vz@vz.team>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,claude,cli,codex,cursor,tmux
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Environment :: Console :: Curses
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Terminals
+Requires-Python: >=3.11
+Requires-Dist: textual<9,>=0.80
+Requires-Dist: tomlkit
+Provides-Extra: dev
+Requires-Dist: pyright; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-xdist; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# uxon
+
+[![PyPI](https://img.shields.io/pypi/v/uxon.svg)](https://pypi.org/project/uxon/)
+[![CI](https://github.com/vzd3v/uxon/actions/workflows/ci.yml/badge.svg)](https://github.com/vzd3v/uxon/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)
+![Platform: Linux](https://img.shields.io/badge/platform-Linux-lightgrey)
+
+**Run terminal AI coding agents (Claude Code, Codex, Cursor) on a shared
+server — safely, persistently, and visibly to the operator.**
+
+`uxon` is a small `tmux` wrapper with a full-screen TUI session picker.
+It standardises session names, isolates each user on a dedicated `tmux`
+socket, and lets you start, attach, monitor, and kill agent sessions
+from one screen — your laptop, your phone over SSH, or a sysadmin's
+shell with `sudo`.
+
+<!-- screenshot goes here -->
+
+## What it solves
+
+- **Sandboxed agent runs.** Drop the agent into a low-privilege OS
+  account with a restricted filesystem view via `sudo -iu`, while you
+  keep operating from your own login. The agent can't reach what its
+  user can't reach.
+- **Many users on one box.** Each developer logs into their own OS
+  user, runs their own authenticated `claude` / `codex` / `cursor`
+  with their own keys and quotas, and never sees another user's tmux
+  sessions by accident — every launch user gets a dedicated socket
+  at `/tmp/uxon-<user>.sock`.
+- **Operator visibility.** Anyone with passwordless `sudo` opens
+  `uxon` and immediately sees every agent session on the host:
+  CPU, RAM, age, last attach, attached-or-not. Attach to any of
+  them with `Enter`, kill a runaway with `d`, nuke the lot with
+  a confirmed `kill-all-global`. No more "who's that 38 GB python
+  on the dashboard?".
+- **Attach from anywhere.** Sessions live in `tmux`, so they survive
+  every disconnect. Start at your desk, reattach from your phone over
+  SSH on the train, switch to a tablet later — same session, same
+  state. The TUI is keyboard-only and fits a small screen.
+- **Predictable session names.** `uxon-<project>@<agent>` (`-2`,
+  `-3` for parallels). No more hand-rolled `tmux new -s` strings or
+  guessing what you called it yesterday.
+- **Permissive by default, lockable for ops.** Out of the box you
+  can launch an agent in any folder where the launch user has write
+  access. On a shared host, set `allowed_roots` in the config to
+  pin agents to specific directories. See
+  [`docs/configuration.md`](docs/configuration.md).
+- **One tool, every agent.** Flip a config switch to enable Claude
+  Code, Codex, Cursor — together or any subset. Built-in `--auto`
+  and `--dsp` (skip-permissions / "yolo") flags translate to whatever
+  the underlying agent uses today.
+- **Optional niceties.** Git worktrees, GitHub repo creation on a new
+  project (with a strict whitelist), per-project config overrides.
+  All off by default.
+
+---
+
+## Install
+
+Requires **Python 3.11+**, `tmux`, and Linux. Dependencies (`textual`,
+`tomlkit`) are pulled in automatically.
+
+### Single-user laptop (recommended)
+
+```bash
+# uv tool — recommended. uv is the 2026 default Python toolchain;
+# fast, uses uv-managed Python and a shared dep cache.
+uv tool install uxon
+
+# pipx — equivalent. Same console-script entrypoint.
+pipx install uxon
+```
+
+Either creates an isolated venv and puts `uxon` on your `PATH`.
+Update with `uv tool upgrade uxon` / `pipx upgrade uxon`.
+
+For the bleeding edge from `main` (before a release lands on PyPI):
+
+```bash
+uv tool install git+https://github.com/vzd3v/uxon.git
+# or:  pipx install git+https://github.com/vzd3v/uxon.git
+```
+
+If you maintain your own Python (pyenv, asdf, uv-managed) and prefer
+no isolation, `pip install --user uxon` works too — `uxon` lands in
+`~/.local/bin/`. On Debian/Ubuntu/Fedora system Python, PEP 668 blocks
+plain `pip install`; use `pipx` (recommended) or know-what-you-do
+`pip install --user --break-system-packages uxon`.
+
+```bash
+uxon doctor                       # verify the install
+# Optional: bootstrap an example config (uxon runs in $HOME with defaults).
+curl -fsSL https://raw.githubusercontent.com/vzd3v/uxon/main/config/config.example.toml -o ./config.toml
+$EDITOR ./config.toml             # set allowed_roots, session_users, agents
+```
+
+You'll also need at least one of the agent CLIs installed for the
+launch user — see [Supported agents](#supported-agents).
+
+### Shared host / multi-user VPS
+
+For a host where several Linux users need a single shared `uxon` on
+`PATH`, install into a dedicated venv and symlink the console script:
+
+```bash
+git clone https://github.com/vzd3v/uxon.git
+cd uxon
+sudo python3 install/install_uxon.py \
+  --repo-dir "$(pwd)" \
+  --install-path /usr/local/bin/uxon
+# (uses /opt/uxon/venv by default; override with --venv-dir)
+```
+
+The installer creates a venv at `--venv-dir`, installs the package
+into it, and symlinks `/opt/uxon/venv/bin/uxon` to `/usr/local/bin/uxon`.
+
+For multi-host rollout, generated config from a JSON payload, and
+deployment topology, see [`docs/deployment.md`](docs/deployment.md).
+
+## Quick start
+
+```bash
+uxon                  # full-screen TUI picker (recommended; needs a TTY)
+```
+
+That's the intended entry point. Everything below — creating
+projects, attaching, killing, switching agents — happens inside the
+TUI. Read on.
+
+For non-interactive use (scripts, CI, SSH one-liners), the same
+operations are available as subcommands; see [CLI](#cli) at the end.
+
+---
+
+## The TUI
+
+`uxon` with no arguments on a TTY opens a full-screen `textual`
+picker. One screen, three blocks:
+
+### 1. Actions (top)
+
+1. **New session in current folder** — start the default agent in
+   `$PWD` (gated on the allowed-roots check).
+2. **Create new project** — prompt for a name, create
+   `<new_project_root>/<name>`, optionally create a GitHub remote
+   (if [git-remote profiles](docs/configuration.md#use-case-github-repo-creation-on-new-project)
+   are configured), launch the agent.
+3. **Open existing project** — pick a directory under
+   `new_project_root` and launch.
+
+Before every launch, a permissions modal asks whether to start the
+agent in normal mode or with `--dangerously-skip-permissions`
+("yolo"). No accidental yolos.
+
+### 2. Your sessions
+
+Live list of `uxon-*` sessions for the current user with:
+
+- session name, agent, working directory;
+- live CPU / RAM (refreshed every `tui_refresh_interval_seconds`);
+- attached-or-not marker;
+- creation time and last-attach time.
+
+`Enter` attaches. `d` kills (with confirmation). `D` kills *all your
+own* sessions after typing `kill-all`.
+
+### 3. Server status (bottom)
+
+Load average, normalised CPU load, RAM, disk, uptime. When you're
+inside an SSH session, an async `ssh-link` probe shows RTT, jitter,
+and retransmits — quick read on whether the lag you're feeling is
+the agent or the network.
+
+### ⚡ Superuser block (only when passwordless `sudo` is detected)
+
+Appears below your own sessions whenever the host trusts you with
+`sudo`:
+
+- **Other users' sessions** with a yellow `USER` column. `Enter`
+  attaches via `sudo -iu <user>` (read-only-ish — you're a guest in
+  their tmux); `d` kills the highlighted one.
+- **⚙ Settings** — repo-level `config.toml` editor. Bool keys
+  toggle, enums cycle, strings open an input, arrays use
+  comma-separated input. Saves rewrite the file via a `tomlkit`
+  round-trip (using `sudo tee` automatically when needed) and
+  preserve untouched comments and formatting. Project-level
+  `.uxon.toml` keys are read-only here — edit them in the project.
+- **Kill ALL uxon sessions (all users)** — appears when at least
+  one session exists anywhere; requires typing `kill-all-global`
+  to confirm. The "fire alarm" button.
+
+### Keys
+
+| Key                | Action |
+|--------------------|--------|
+| `↑` `↓` / `j` `k`  | Navigate |
+| `1`–`9`            | Jump to item by number |
+| `Enter`            | Activate (launch / attach) |
+| `d`                | Kill highlighted session (with confirmation) |
+| `D`                | Kill all *own* sessions (`kill-all` to confirm) |
+| `r`                | Refresh |
+| `g` / `G`          | Jump to first / last |
+| `q` / `Esc`        | Quit (or back, in sub-screens) |
+
+### Detach and re-enter
+
+When the launched session exits — or you `Ctrl-b d` to detach —
+`uxon` returns to the main screen with a refreshed list. The same
+binary you launched is the same binary you come back to. `q` / `Esc`
+on the main screen exits to the shell.
+
+If a launch fails, the failure output stays on the physical
+terminal with a banner before the TUI re-enters fullscreen, so you
+can read whatever stderr the agent printed.
+
+---
+
+## Supported agents
+
+| Agent id | Binary | `--auto` mode | `--dsp` (yolo) | Install |
+|----------|--------|---------------|----------------|---------|
+| `claude` | `claude` | `--permission-mode auto` | `--dangerously-skip-permissions` | [Anthropic docs](https://docs.claude.com/claude-code) |
+| `codex`  | `codex` | `--full-auto` | `--dangerously-bypass-approvals-and-sandbox` | `npm i -g @openai/codex` |
+| `cursor` | `cursor-agent` | (not supported) | `--yolo` | `curl https://cursor.com/install -fsSL \| bash` |
+
+Enable agents in `config/config.toml`:
+
+```toml
+[agents]
+enabled = ["claude", "codex"]
+default = "claude"
+```
+
+`uxon doctor` probes each enabled agent and prints its path, version,
+and status. If none of the enabled agents are installed for the
+launch user, the TUI shows a modal with install hints.
+
+`-w <branch>` (worktree mode) is currently claude-only.
+`--auto` is unavailable for cursor.
+
+---
+
+## Configuration
+
+`uxon` works out of the box with no configuration — the launch user
+can run an agent anywhere they have write access, and `uxon new`
+creates projects under `~/projects`.
+
+Configuration becomes useful once you're hosting more than one user,
+or want to restrict where agents may run, or want one-shot GitHub
+repo creation, or want to switch the default agent. All keys, with
+the **use case** for each, live in
+**[`docs/configuration.md`](docs/configuration.md)**.
+
+Two config layers (later wins):
+
+1. **Repo config** — `<repo>/config/config.toml`, host-wide.
+   `config/config.example.toml` is the tracked starting point.
+2. **Project config** — the nearest `.uxon.toml` in `cwd` or a
+   parent inside an `allowed_roots` entry. Per-project overrides.
+   The TUI never writes `.uxon.toml`.
+
+---
+
+## CLI
+
+The TUI is the recommended entry point. The CLI exposes the same
+operations for scripting, SSH one-liners, and CI. Brief summary:
+
+| Command | What it does |
+|---------|--------------|
+| `uxon` | Open the interactive TUI (needs a TTY). |
+| `uxon run [-w <branch>] [agent-flags...]` | Start an agent in `$PWD`. |
+| `uxon new <name> [-w <branch>] [...]` | Create / reuse a project under `new_project_root` and start an agent. |
+| `uxon list [--all-users]` | List `uxon-*` sessions for this user (or all configured users). |
+| `uxon attach <id>` | Re-attach to a session. Accepts full name, short name, bare stem, or active-pane PID. |
+| `uxon kill <id>` | Kill one session. |
+| `uxon kill-all [--force]` | Kill every `uxon-*` session for the current launch user. |
+| `uxon doctor` | Read-only diagnostics: caller / launch user, config, allowed_roots, agents, sockets, sessions, detected issues. Run this first when something looks wrong. |
+| `uxon version` | Print version + git commit. |
+
+Short forms: `-l` / `-a` / `-k` / `-n` / `-V` / `--killall`.
+
+Full reference with every flag, exit code, identifier-resolution
+rules, repeat-behaviour, worktree details, and legacy-session notes
+is in **[`docs/cli.md`](docs/cli.md)**.
+
+---
+
+## Troubleshooting
+
+- **`uxon` started inside an existing `tmux`?** Handled
+  transparently when `$TMUX` names the same socket as `uxon`. If
+  it's a different (foreign) `tmux`, `uxon` prints an actionable
+  error — `Ctrl-b d` first.
+- **`textual` not installed?** The TUI prints an install hint and
+  exits. The whole CLI keeps working.
+- **TUI errors render as a red toast.** Tmux-gone, permission
+  denied, allowed-roots mismatch, git remote failure, config-write
+  conflict — all caught and shown in-place rather than crashing.
+- **Always run `uxon doctor` first.** It prints the resolved caller /
+  launch user, active config paths, allowed roots, agent paths,
+  socket details, current sessions, and any detected configuration
+  issues.
+
+More edge cases (legacy session prefixes, failed-launch banner, the
+`--dsp` flag and its legacy aliases) are documented in
+[`docs/cli.md`](docs/cli.md).
+
+---
+
+## Documentation
+
+- [`docs/configuration.md`](docs/configuration.md) — all config keys
+  organised by use case (single-user laptop, shared multi-user host,
+  restricted launch directories, GitHub repo on new project, …).
+- [`docs/cli.md`](docs/cli.md) — full CLI reference (every flag,
+  exit code, identifier resolution, repeat behaviour).
+- [`docs/deployment.md`](docs/deployment.md) — multi-host rollout,
+  config rendering from JSON, runtime dependencies.
+- [`docs/architecture.md`](docs/architecture.md) — module map, TUI
+  internals, code boundaries.
+- [`CONTRIBUTING.md`](CONTRIBUTING.md) — local checks, branch
+  policy, release process.
+- [`SECURITY.md`](SECURITY.md) — threat model, disclosure policy.
+- [`CHANGELOG.md`](CHANGELOG.md) — version history.
+
+## Versioning
+
+`uxon` follows [SemVer](https://semver.org/). `uxon --version`
+prints the version and short git commit (with `-dirty` when the
+checkout is dirty).
+
+## License
+
+[MIT](LICENSE) © 2026 Vasily Zakharov.