triflux 10.48.0 → 10.49.0

package/README.md

@@ -10,18 +10,11 @@
 
 <h3 align="center">CLI-first multi-model orchestration for Claude Code, Codex, and Antigravity</h3>
 
-<p align="center">
-  One front door for routing work, coordinating agents, running local/remote teams,<br>
-  and keeping Codex/Antigravity/Claude execution behind auditable guards.
-</p>
-
 <p align="center">
   <a href="https://www.npmjs.com/package/triflux"><img src="https://img.shields.io/npm/v/triflux?style=flat-square&color=FFAF00&label=npm" alt="npm version"></a>
   <a href="https://www.npmjs.com/package/triflux"><img src="https://img.shields.io/npm/dm/triflux?style=flat-square&color=F5C242" alt="npm downloads"></a>
   <a href="https://github.com/tellang/triflux/stargazers"><img src="https://img.shields.io/github/stars/tellang/triflux?style=flat-square&color=FFAF00" alt="GitHub stars"></a>
-  <img src="https://img.shields.io/badge/skill_files-34-F5C242?style=flat-square" alt="34 skill files">
-  <sub>11 compatibility aliases are deprecated</sub>
-  <img src="https://img.shields.io/badge/node-%3E%3D18-374151?style=flat-square" alt="Node >= 18">
+  <img src="https://img.shields.io/badge/node-%3E%3D20-374151?style=flat-square" alt="Node >= 20">
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-374151?style=flat-square" alt="License: MIT"></a>
 </p>
 
@@ -29,409 +22,220 @@
   <img alt="triflux demo" src="docs/assets/demo-multi.gif" width="680">
 </p>
 
-<p align="center">
-  <a href="#quick-start">Quick Start</a> &middot;
-  <a href="#current-surface">Current Surface</a> &middot;
-  <a href="#canonical-workflows">Canonical Workflows</a> &middot;
-  <a href="#architecture">Architecture</a> &middot;
-  <a href="#operations">Operations</a> &middot;
-  <a href="#security-and-guards">Security</a>
-</p>
-
----
-
-## What is triflux?
-
-triflux is a **Claude Code plugin + npm CLI** for routing AI coding work across
-Claude, Codex, and Antigravity without letting ad-hoc shell commands or stale skill
-aliases become the control plane.
+triflux is a Claude Code plugin and npm CLI that routes coding work across Claude, Codex,
+and Antigravity. You describe the task once with `/tfx-auto`; triflux picks the CLI lane
+(Codex by default), runs it through managed routes instead of ad-hoc shell commands, and
+can fan the work out to parallel workers, worktree-isolated swarms, live Claude↔Codex
+sessions, or remote hosts. The `tfx` shell CLI covers setup, diagnostics, the local Hub,
+and team orchestration.
 
-The current design is intentionally simpler than the old README implied:
-
-- **`/tfx-auto` is the canonical Claude Code skill front door.** Use flags to
-  express quick/deep/consensus/parallel/retry behavior.
-- **`tfx` is the shell CLI.** Use it for setup, diagnostics, hub lifecycle,
-  MCP sync, team/swarm orchestration, and handoffs.
-- **Compatibility aliases still exist, but they are not the primary API.** They
-  are documented in [`docs/legacy-skill-aliases.md`](https://github.com/tellang/triflux/blob/main/docs/legacy-skill-aliases.md)
-  so the main README stays focused on the supported path.
-- **Host-local Codex harnesses are out of package scope.** For example, a local
-  `~/.codex/skills/tfx-harness` can recommend workflows on one machine, but it
-  is not shipped in this repository, npm package, or Claude plugin.
-
----
-
-## Quick Start
-
-### 1. Install
-
-Claude Code plugin install:
-
-```text
-/plugin marketplace add tellang/triflux
-/plugin install triflux@tellang
-```
-
-npm install:
+## Install
 
 ```bash
-npm install -g triflux
+npm install -g triflux   # postinstall runs the setup script
+tfx doctor               # check CLIs, tmux, Hub, MCP, profiles, skills
 ```
 
-Then run the setup/diagnostic path from a terminal:
+Or install the Claude Code plugin from this repository's marketplace:
 
 ```bash
-tfx setup
-tfx doctor
+claude plugin marketplace add tellang/triflux
+claude plugin install triflux@triflux
 ```
 
-Use `tfx doctor --json` when you need machine-readable status for automation.
+`tfx doctor --fix` repairs common drift; `tfx doctor --json` is for automation.
 
-### 2. Use the canonical front doors
-
-Claude Code slash skills:
+## First steps
 
 ```text
-/tfx-auto "review this change" --mode consensus
-/tfx-auto "implement auth flow with tests" --mode deep --retry ralph
-/tfx-auto "split this PRD across isolated shards" --parallel swarm --mode consensus --isolation worktree
-/tfx-remote spawn ryzen5-7600 "run a security review"
-/tfx-doctor
-```
-
-Shell CLI:
-
-```bash
-tfx list
-tfx hub ensure
-tfx mcp list
-tfx handoff --target remote --output .omx/handoff.md
-tfx swarm preflight docs/prd/example.md --json
-tfx codex-team "refactor auth + add tests"
+/tfx-auto "fix the failing auth tests"
+/tfx-auto "review this change for trust-boundary issues" --mode consensus
+/tfx-auto "finish the migration and verify it" --mode deep --retry ralph --max-iterations 10
 ```
 
-> Deep, consensus, team, and swarm paths need the relevant CLIs and a terminal
-> multiplexer. Run `tfx doctor` first; it reports missing Codex/Antigravity/Claude,
-> psmux/tmux, Hub, MCP, profile, and stale-skill issues.
-
----
+Run `tfx auto "<task>" --json` in a shell to preview the routing decision without executing it.
 
-## Current Surface
+## Skills
 
-### Shell commands
+Skills you invoke directly:
 
-The `tfx` CLI currently exposes these primary commands:
-
-| Command | Use |
+| Skill | Use |
 | --- | --- |
-| `tfx setup` | Sync scripts, HUD, hooks, MCP, and profiles. Supports `--dry-run`. |
-| `tfx doctor` | Diagnose and repair installation state. Supports `--fix`, `--reset`, `--diagnose`, `--json`. |
-| `tfx auto` | Preview the `tfx-auto` routing decision. Supports `--cli`, `--mode`, `--parallel`, `--json`. |
-| `tfx mcp` | Manage MCP registry targets with `list`, `sync`, `add`, and `remove`. |
-| `tfx hub` | Start, stop, ensure, or inspect the local MCP message bus. |
-| `tfx list` | Show installed package and user skills. |
-| `tfx handoff` | Serialize the current context for local or remote continuation. |
-| `tfx schema` | Print CLI and Hub delegator schemas. |
-| `tfx hooks` | Scan, diff, apply, restore, or inspect hook orchestrator state. |
-| `tfx tray` | Start the tray/HUD status process; use `--attach` for foreground debugging. |
-| `tfx multi` | Launch local multi-agent team mode through tmux/psmux + Hub. |
-| `tfx swarm` | Plan, preflight, run, or list PRD-based worktree-isolated swarm work. |
-| `tfx synapse` | Inspect swarm registry and leases. |
-| `tfx review` | Run Codex-backed git diff review. |
-| `tfx codex-team` | Codex-led team mode convenience wrapper. |
-| `tfx notion-read` | Convert Notion pages to Markdown through configured MCP clients. |
-| `tfx why` | Read intent trailers from the last commit touching a path. |
-| `tfx update` | Update to the latest stable or dev package. |
-| `tfx monitor` | Open the terminal TUI monitor. |
-| `tfx version` | Print version information. |
-| `tfx-profile` | Convenience binary for interactive Codex profile management. |
-
-Run `tfx schema <command>` for the exact argument contract.
-
-### Claude Code skills
-
-The package ships **34 skill files**. The important split is:
-
-- **Canonical entrypoints**: `tfx-auto`, `tfx-remote`, `tfx-doctor`,
-  `tfx-setup`, `tfx-profile`, `tfx-hub`, `tfx-hooks`, `tfx-ship`, `tfx-wt`.
-- **Task helpers**: `tfx-plan`, `tfx-review`, `tfx-qa`, `tfx-research`,
-  `tfx-analysis`, `tfx-find`, `tfx-index`, `tfx-interview`, `tfx-prune`,
-  `tfx-forge`, `merge-worktree`, `star-prompt`.
-- **Deprecated compatibility aliases**: 11 legacy names remain only as transition
-  shims. Prefer the canonical commands above and see the alias table only when
-  migrating old prompts.
-
-### Canonical flag map
-
-Most old skill names now map to explicit `tfx-auto` flags:
-
-| Intent | Canonical form |
+| `/tfx-auto` | Front door for implementing, fixing, reviewing, and parallel work. Behavior is set by flags (below). |
+| `/tfx-live` | Live Claude↔Codex sessions: `start`/`ask`/`stop`, `peer` relay, `orchestrate`, `list-sessions`. |
+| `/tfx-remote` | Remote Claude Code sessions over SSH: `setup`, `spawn`, `list`, `attach`, `send`, `resume`, `probe`, `kill`. |
+| `/tfx-setup` | Interactive setup: file sync, HUD, Codex profiles, MCP, hook priority. |
+| `/tfx-doctor` | Diagnose and repair; also starts, stops, and checks the Hub. |
+| `/tfx-profile` | Manage Codex profiles. |
+| `/tfx-ship` | triflux release flow (maintainers). |
+| `/tfx-wt` | Windows Terminal tabs and panes. `tfx setup` installs it on Windows only. |
+
+Internal lanes (marked `internal: true`; other skills and the router call them, but you can name them explicitly):
+
+| Skill | Use |
 | --- | --- |
-| quick single-lane work | `/tfx-auto "task" --mode quick` |
-| deeper plan/execute/verify loop | `/tfx-auto "task" --mode deep` |
-| persistent retry loop | `/tfx-auto "task" --retry ralph` |
-| consensus review | `/tfx-auto "task" --mode consensus` |
-| debate or panel report | `/tfx-auto "task" --mode consensus --shape debate|panel` |
-| local parallel work | `/tfx-auto "task" --parallel N --mode deep` or shell `tfx multi ...` |
-| PRD/worktree swarm | `/tfx-auto "task" --parallel swarm --mode consensus --isolation worktree` or shell `tfx swarm ...` |
-| force a CLI lane | `/tfx-auto "task" --cli codex|antigravity|claude` |
+| `tfx-harness` | Meta routing: returns which skill or path fits a request, without running it. |
+| `tfx-plan` | Multi-model implementation plan (`--quick` for a lighter pass). |
+| `tfx-review` | Code review verdict (`--quick` for a lighter pass). |
+| `tfx-research` | Web research with cross-checked sources (`--quick`, `--auto`, `--depth`). |
+| `tfx-interview` | Requirements interview; `--format goal` turns an idea into a Claude Code `/goal` block. |
 
-### Control-plane boundaries
+The package also bundles two general helpers, `merge-worktree` and `star-prompt`.
+A keyword hook may suggest a skill from your prompt; invoke `/tfx-*` explicitly when you want a predictable route.
 
-Keep these surfaces separate when debugging or extending triflux:
+## `/tfx-auto` flags
 
-| Surface | Source of truth | Ships in npm/plugin? |
+| Flag | Values | Effect |
 | --- | --- | --- |
-| Public CLI/runtime | `bin/`, `scripts/`, `hub/`, `hooks/`, `skills/` | Yes |
-| Published mirror | `packages/triflux/` | Yes; must match root runtime files |
-| Claude plugin metadata | `.claude-plugin/` | Yes; points at npm package contents |
-| Codex-local harness experiments | `~/.codex/skills/*` | No |
-| Legacy aliases | `skills/<alias>/` + `docs/legacy-skill-aliases.md` | Yes, but deprecated |
-
-If a local Codex harness recommends a workflow, treat that as host-local routing
-advice. The package contract is still the CLI, Claude skill, hook, and Hub surface
-above.
-
----
-
-## Canonical Workflows
-
-### Direct implementation or review
-
-```text
-/tfx-auto "fix the failing auth tests" --risk-tier medium
-/tfx-auto "review this PR for SQL and trust-boundary issues" --mode consensus
-```
-
-Use `--risk-tier low|medium|high` when you want verification intensity to be
-explicit. Use `--mode quick|deep|consensus` when you already know the mode.
-
-### Persistent completion loop
-
-```text
-/tfx-auto "finish the migration and verify it" --mode deep --retry ralph --max-iterations 10
-```
-
-`--retry ralph` uses the retry state machine and stuck detection. Set
-`--max-iterations` when the loop must be bounded.
-
-### Consensus, debate, or panel output
-
-```text
-/tfx-auto "Postgres LISTEN/NOTIFY vs Redis Streams" --mode consensus --shape debate
-/tfx-auto "review the migration strategy" --mode consensus --shape panel
-```
-
-Consensus participants are the configured Claude/Codex/Antigravity lanes. If a lane is
-unavailable, the result should report partial/degraded status instead of hiding it.
-
-### Local team or PRD swarm
-
-```text
-# Local team mode
-tfx multi "refactor auth + update UI + add tests"
-
-# Worktree-isolated PRD swarm
-tfx swarm preflight docs/prd/my-feature.md --json
-tfx swarm run docs/prd/my-feature.md
-```
-
-Swarm work uses isolated worktrees and file leases. Use preflight before running a
-large PRD so missing hosts, CLI profiles, and lease conflicts are caught first.
-
-### Remote sessions
-
-```text
-/tfx-remote setup
-/tfx-remote spawn ryzen5-7600 "run security review"
-/tfx-remote list
-/tfx-remote attach <session>
-/tfx-remote send <session> "continue with fixes"
-```
-
-`tfx-remote` is the consolidated Claude skill surface for setup/spawn/list/attach/send/resume/probe/kill flows.
-
-### Save or restore context
+| `--mode` | `quick` (default), `deep`, `consensus`, `live` | `deep` = plan → execute → verify loop; `consensus` = multi-CLI agreement; `live` = hand off to `tfx-live peer` |
+| `--shape` | `consensus`, `debate`, `panel` | Output shape for `--mode consensus` |
+| `--cli` | `auto`, `codex`, `antigravity`, `claude` | Force a CLI lane |
+| `--cli-set` | `triad`, `no-antigravity`, `custom` | Consensus participants |
+| `--parallel` | `1`, `N`, `swarm` | `N` = local workers (`tfx multi`); `swarm` = PRD shards in worktrees (`tfx swarm`) |
+| `--isolation` | `none`, `worktree` | Worktree isolation per shard (forced on with `swarm`) |
+| `--remote` | `<host>` | Send swarm shards to a host from `hosts.json` |
+| `--retry` | `0`, `1` (default), `ralph`, `auto-escalate` | `ralph` = retry state machine with stuck detection; `auto-escalate` = move up the model chain |
+| `--max-iterations` | `N` | Cap for `ralph` / `auto-escalate` (`0` = unlimited) |
+| `--rounds` | `N` (default 4) | Round trips for `--mode live` |
+| `--risk-tier` | `auto`, `low`, `medium`, `high` | Pick verification strength from the change; ignored when `--mode` is set |
+| `--skill` | `<name>` | Prepend `skills/<name>/SKILL.md` to the Codex/Antigravity prompt |
+| `--no-native-bridge-ui` | | Hide headless workers from the `claude agents` panel |
+
+The full contract, including `--lead`, `--options`, `--experts`, and conflict rules, lives in
+[`skills/tfx-auto/SKILL.md`](skills/tfx-auto/SKILL.md).
+
+## Models and profiles
+
+Codex runs through named profiles; model IDs live in `~/.codex/<profile>.config.toml`, and the
+role → profile map lives in [`scripts/lib/agent-route-policy.mjs`](scripts/lib/agent-route-policy.mjs).
+Claude is called by alias, so the newest model in each tier is picked up automatically.
+
+| Profile / alias | Lanes |
+| --- | --- |
+| `gpt6_astra_xhigh` | Architecture, planning, critique, debugging, security review, deep execution |
+| `gpt6_astra_max`, `gpt6_astra_ultra` | Hardest single tasks (`TFX_CODEX_PROFILE=max\|ultra`); `max` is the first `auto-escalate` step |
+| `gpt61_sol_high` / `gpt61_sol_med` | Default implementation, review, verification, tests, docs / cleanup |
+| `gpt6_luna_high` / `gpt6_luna_low` | Build fixes, writing / latency-first lookups |
+| Claude `fable` | Final `--retry auto-escalate` step |
+| Claude `opus` / `sonnet` / `haiku` | Meta routing and planning gates / Claude-native QA and verification / fast exploration |
 
-```bash
-tfx handoff --target remote --decision "Keep README canonical; move aliases to docs" --output .omx/handoff.md
-```
+Routing policy: [`.claude/rules/tfx-routing.md`](.claude/rules/tfx-routing.md) ·
+escalation chain: [`.claude/rules/tfx-escalation-chain.md`](.claude/rules/tfx-escalation-chain.md).
 
-Use handoffs when a session is ending or when another host/agent needs the current
-state without replaying the entire conversation.
+## Shell CLI
 
----
+| Command | Use |
+| --- | --- |
+| `tfx setup` / `tfx doctor` | Sync files, hooks, HUD, MCP, profiles / diagnose and repair (`--fix`, `--json`) |
+| `tfx auto` | Preview the `tfx-auto` routing decision |
+| `tfx multi` | Local multi-CLI team in tmux + Hub |
+| `tfx swarm` | PRD-based, worktree-isolated work: `plan`, `preflight`, `run`, `list` |
+| `tfx synapse` | Swarm session registry and leases |
+| `tfx hub` | Local Hub: `start`, `stop`, `status`, `ensure` |
+| `tfx mcp` | Managed MCP registry: `list`, `sync`, `add`, `remove` |
+| `tfx hooks` | Hook orchestrator: scan, diff, apply, status |
+| `tfx handoff` | Serialize the current context for another session or host |
+| `tfx cto` | Repo-local authority console: `collect`, `status`, `dashboard`, `hygiene`, `steward`, `event` |
+| `tfx review` / `tfx codex-team` | Codex git-diff review / Codex-led team mode |
+| `tfx stealth-fetch <url>` | Fetch one URL through cloakbrowser (JSON on stdout) |
+| `tfx notion-read`, `tfx why`, `tfx schema`, `tfx list`, `tfx monitor`, `tfx update`, `tfx version` | Notion → Markdown, commit intent trailers, CLI schemas, installed skills, TUI monitor, update, version |
+| `tfx-live` | Live session bridge (same as the `/tfx-live` skill) |
+| `tfx-profile` | Interactive Codex profile manager |
+
+`tfx <command> --help` and `tfx schema <command>` print the exact arguments.
+
+## Runtime features
+
+**Live sessions.** `tfx-live` drives Claude Code and Codex TUI sessions. Claude daemon targets
+(`--short`/`--session-id`) try UDS first and fall back to tmux when `--session` is also given;
+Codex uses tmux, or UDS with
+`--transport uds --thread <id|auto>`. `peer` relays between two sessions for `--rounds`, and
+`orchestrate` runs Claude + Codex on one task. triflux's Codex hook records running Codex
+sessions under `~/.local/state/triflux/codex-sessions/`, so `tfx-live list-sessions --cli codex|claude`
+also finds sessions you started yourself in tmux.
+
+**Long jobs.** `scripts/tfx-route.sh --async <agent> "<prompt>"` returns a job id at once, which
+gets past Claude Code's 600-second Bash limit. Follow up with `--job-status`, `--job-wait`, and
+`--job-result`.
+
+**Hub.** A local message bus for teams, remote sessions, MCP tools, and status surfaces. It binds
+to `127.0.0.1:27888` by default (`TFX_HUB_PORT` overrides) and accepts a bearer token from
+`TFX_HUB_TOKEN`. Headless workers from `tfx-auto`, `tfx multi`, and local swarm shards appear in
+the `claude agents` panel unless you pass `--no-native-bridge-ui`.
+
+**Retry and escalation.** `--retry ralph` loops until done or stuck (three identical failures).
+`--retry auto-escalate` steps from Codex `gpt6_astra_max` to Claude `fable`; override the chain in
+`.triflux/config/escalation-chain.json`.
+
+**Machine profile.** Setup records which CLIs this machine may use and its timeout policy in
+`~/.config/triflux/machine-profile.env`. `TFX_DISABLE_CODEX=1` or `TFX_DISABLE_ANTIGRAVITY=1`
+removes a CLI from routing; if no allowed CLI is available the route fails instead of silently
+falling back. Details: [`.claude/rules/tfx-machine-profile.md`](.claude/rules/tfx-machine-profile.md).
+
+**CTO lake.** `tfx cto` keeps an append-only history of the repo in `.triflux/lake/`. Automatic
+behavior is off by default; opt in with `TFX_CTO_AUTO_COLLECT=1` or `TFX_CTO_NORTH_STAR=1`
+([ADR-0018](docs/adr/0018-cto-auto-behaviors-opt-in.md)). The old tray UI was removed
+([ADR-0022](docs/adr/0022-remove-cto-tray.md)).
+
+**Remote hosts.** `/tfx-remote` and `--remote <host>` read hosts from `~/.config/triflux/hosts.json`
+(Windows: `%APPDATA%\triflux\hosts.json`). Run `/tfx-remote setup` to add one, then
+`/tfx-remote spawn <host> "run a security review"`.
 
 ## Architecture
 
-> 상세 구조·패키지 레이아웃·실행 경로는 [ARCHITECTURE.md](ARCHITECTURE.md), 문서 전체 지도는 [docs/README.md](docs/README.md) 참조.
-
-<p align="center">
-  <img src="docs/assets/architecture.svg" alt="triflux architecture" width="680">
-</p>
-
 ```mermaid
 graph TD
-    User([User / Claude Code / shell]) --> Skills[Claude skills]
+    User([Claude Code prompt / shell]) --> Skills["/tfx-auto · /tfx-live · /tfx-remote"]
     User --> CLI[tfx CLI]
-    Skills --> Auto["/tfx-auto"]
-    Skills --> Remote["/tfx-remote"]
-    CLI --> Hub[triflux Hub]
-    CLI --> Team[tfx multi / swarm]
-    Auto --> Route[tfx-route.sh + guards]
-    Team --> Hub
-    Remote --> Hub
+    Skills --> Route[tfx-route.sh]
+    Skills --> Live[tfx-live]
+    CLI --> Team["tfx multi · tfx swarm"]
     Route --> Codex[Codex CLI]
-    Route --> Antigravity[Antigravity agy CLI]
+    Route --> Agy[Antigravity agy]
     Route --> Claude[Claude Code]
-    Hub --> MCP[MCP registry + bridge]
+    Team --> Route
+    Team --> WT[(git worktrees)]
+    Live -->|UDS or tmux| Sessions[Claude / Codex TUI sessions]
+    Route --> Hub["Hub 127.0.0.1:27888"]
+    Team --> Hub
     Hub --> Store[(SQLite or memory store)]
-    Hub --> Dashboard[HUD / monitor]
-```
-
-The common routing path is:
-
-1. Claude Code prompt or explicit skill invocation.
-2. Keyword/routing hooks may add context or choose a skill.
-3. `tfx-auto` normalizes intent into mode, retry, parallelism, risk tier, and
-   target CLI lane.
-4. `tfx-route.sh`, Hub workers, or the `tfx` CLI execute the actual Codex/Antigravity/
-   Claude-backed work.
-5. Hub records team messages, leases, retries, handoffs, and status surfaces.
-
-### Hub
-
-The Hub is the local message bus for teams, remote sessions, MCP tools, and
-status surfaces. It binds to localhost, uses pipe/HTTP transports, and can be
-managed with:
-
-```bash
-tfx hub ensure
-tfx hub status --json
-tfx hub stop
-```
-
-macOS may show a firewall prompt when tests or Hub startup open a localhost port
-through `node`. For normal documentation work this is not needed; for active Hub,
-team, or MCP workflows allow localhost access if your environment requires it.
-
-### Guards
-
-triflux keeps risky execution behind managed routes:
-
-- CLI calls should flow through `tfx-route.sh`, Hub workers, or the `tfx` CLI.
-- Direct `codex exec`, unmanaged `agy`, and deprecated `gemini` routes are guarded in the installed workflow.
-- psmux/Windows Terminal flows must use the managed API and documented rules, not
-  ad-hoc `wt.exe` or `psmux send-keys` snippets.
-
-### Profiles and model routing
-
-Use `tfx-profile` for Codex profiles and `tfx setup`/`tfx doctor` for Antigravity plus legacy Gemini compatibility state. Do not hardcode
-model and effort flags in launcher scripts when a profile already owns them.
-
----
-
-## Operations
-
-### Diagnostics
-
-```bash
-tfx doctor
-tfx doctor --json
-tfx doctor --fix
-tfx doctor --diagnose
-```
-
-`doctor` checks CLI availability, profiles, hooks, skills, Hub, MCP registry,
-route-script sync, stale teams, and common local configuration drift.
-
-### MCP registry
-
-```bash
-tfx mcp list
-tfx mcp sync
-tfx mcp add context7 --url https://mcp.context7.com/mcp
-tfx mcp remove context7
-```
-
-The registry is the source of truth for managed MCP targets. Avoid hand-editing
-Codex/Antigravity/Claude MCP files unless you are intentionally debugging drift.
-
-### State snapshots
-
-Hub startup can take best-effort daily snapshots of selected `~/.codex/` and Antigravity/Gemini `~/.gemini/` state into ignored `references/*-snapshots/` folders. Manual helpers:
-
-```bash
-npm run snapshot:codex
-npm run snapshot:gemini
-npm run snapshot:all
-```
-
-### Release and mirror checks
-
-For repository changes that affect package contents, run the release gates before
-shipping:
-
-```bash
-npm run lint:skills
-npm run gen:skill-manifest
-npm run release:check-sync
-npm run release:check-mirror
-npm run lint
+    Hub --> MCP[MCP tools]
+    Hub --> UI["HUD · claude agents panel"]
+    CLI --> Lake[(".triflux/lake (tfx cto)")]
 ```
 
-`packages/triflux` is the npm-publishable mirror for several top-level runtime
-folders. Keep it synchronized when touching mirrored runtime files.
+Package layout and execution paths: [ARCHITECTURE.md](ARCHITECTURE.md). Documentation map:
+[docs/README.md](docs/README.md).
 
----
-
-## Platform Support
+## Platforms
 
 | Platform | Multiplexer | Notes |
 | --- | --- | --- |
-| macOS | tmux | Supported. Requires a timeout provider such as `gtimeout` for some flows. |
+| macOS | tmux | Default path. Install `coreutils` (`gtimeout`) if you keep a positive hard ceiling. |
 | Linux | tmux | Supported. |
-| Windows | psmux + Windows Terminal | Supported through managed psmux/WT paths. PowerShell is the default psmux shell. |
-
-See `.claude/rules/tfx-psmux.md` for the stricter Windows/psmux
-rules used by agents and launch scripts.
+| Windows | psmux + Windows Terminal | See below. |
 
----
+**Windows.** psmux (a tmux fork) runs PowerShell by default. safety-guard blocks direct `wt.exe`
+and raw `psmux kill-session`, so tabs and panes go through the `tfx-wt` skill (set up only on
+Windows) and `hub/team/wt-manager.mjs`. Agent rules:
+[`.claude/rules/tfx-psmux.md`](.claude/rules/tfx-psmux.md).
 
-## Security and Guards
+## Security and guards
 
 | Layer | Protection |
 | --- | --- |
-| Hub token auth | Local bearer token for Hub APIs where configured. |
-| Localhost binding | Hub defaults to `127.0.0.1`. |
-| MCP registry guard | Replaces unsupported or stale MCP records with managed HTTP entries. |
-| Headless guard | Blocks unmanaged Codex/Antigravity headless execution paths and deprecated Gemini routes. |
-| Safety guard | Sanitizes shell-sensitive psmux/SSH/WT flows. |
-| Consensus reporting | Deep/consensus workflows should report degraded or disputed findings explicitly. |
-
----
-
-## Development
-
-```bash
-npm ci
-npm test
-npm run lint
-npm run release:check-sync
-npm run release:check-mirror
-```
-
-Notes for contributors:
-
-- Keep deprecated alias details out of the main README; update
-  [`docs/legacy-skill-aliases.md`](https://github.com/tellang/triflux/blob/main/docs/legacy-skill-aliases.md) instead.
-- Keep Codex-local experiments under `~/.codex/skills`, not in this package,
-  unless the package boundary is intentionally changed.
-- For docs-only changes, targeted checks such as `npm run lint` and release sync
-  checks are usually enough; full integration tests may start Hub servers and
-  local listener prompts.
-
----
+| Managed routes | Codex and Antigravity are called through `tfx-route.sh`, Hub workers, or `tfx`, never through a bare `codex exec` or `agy`. This is a rule for callers; no hook enforces it. |
+| safety-guard hook | Blocks destructive shell commands (root `rm -rf`, force push to main, `git clean -fd`, SQL `DROP`), direct `wt.exe`, raw psmux kill, and bash syntax sent over SSH to Windows hosts, and points to the managed alternative. |
+| Hub | Binds to localhost; optional bearer token (`TFX_HUB_TOKEN`). |
+| MCP registry | Replaces stale or unsupported MCP entries with managed ones. |
+| Consensus | Deep and consensus runs report degraded or disputed results instead of hiding them. |
+
+## Contributing
+
+Node 20 or newer. See [CONTRIBUTING.md](CONTRIBUTING.md) for tests, lint, package boundaries,
+mirror and release checks, and state snapshots. Releases are automated: merging a version-bump
+commit to `main` runs `release.yml` after CI passes; it tags, creates the GitHub release, and publishes to npm
+through OIDC Trusted Publishing. Decisions are recorded in [docs/adr/](docs/adr/README.md).
 
 <p align="center">
   <sub>MIT License &middot; Made by <a href="https://github.com/tellang">tellang</a></sub>