chore: repo hygiene — consolidate specs, refresh stale READMEs (slice A)

docs.md

@@ -12,7 +12,7 @@ This is the root repository containing the Nori CLI project:
 
 - **`nori-rs/`**: Main Rust implementation (Cargo workspace with all core functionality)
 - **`nori-cli/`**: Node.js launcher for npm distribution (thin wrapper that invokes the Rust binary)
-- **`docs/`**: Durable specs, implementation plans, and follow-up backlogs
+- **`docs/`**: Durable specs (`docs/specs/`), implementation plans, and follow-up backlogs — the single home for design material
 - **`.github/`**: Build and CI configuration
 - **`.claude/`**: Skills and configuration for Claude-based development
 - **`scripts/`**: Development scripts
@@ -95,7 +95,7 @@ Nori acts as an MCP client:
 
 ### Things to Know
 
-- The crate naming uses a `codex-` prefix (legacy from the OpenAI Codex fork), except for `nori-tui` and `nori-installed`
+- Nori-authored crates use a `nori-` prefix (`nori-cli`, `nori-tui`, `nori-acp`, `nori-protocol`, `nori-installed`); inherited crates keep the legacy `codex-` prefix from the OpenAI Codex fork and are progressively adopted or removed per `docs/specs/crate-layering.md`
 - The `nori-config` feature flag enables Nori-specific configuration paths (`~/.nori/cli/`) instead of the legacy Codex paths (`~/.codex/`)
 - The `unstable` feature flag gates experimental ACP features like model switching
 - Cross-platform sandboxing is implemented using Landlock (Linux), Seatbelt (macOS), and restricted tokens (Windows)

nori-rs/README.md

@@ -1,98 +1,37 @@
-# Codex CLI (Rust Implementation)
-
-We provide Codex CLI as a standalone, native executable to ensure a zero-dependency install.
-
-## Installing Codex
-
-Today, the easiest way to install Codex is via `npm`:
-
-```shell
-npm i -g @openai/codex
-codex
-```
-
-You can also install via Homebrew (`brew install --cask codex`) or download a platform-specific release directly from our [GitHub Releases](https://github.com/openai/codex/releases).
-
-## Documentation quickstart
-
-- First run with Codex? Follow the walkthrough in [`docs/getting-started.md`](../docs/getting-started.md) for prompts, keyboard shortcuts, and session management.
-- Already shipping with Codex and want deeper control? Jump to [`docs/advanced.md`](../docs/advanced.md) and the configuration reference at [`docs/config.md`](../docs/config.md).
-
-## What's new in the Rust CLI
-
-The Rust implementation is now the maintained Codex CLI and serves as the default experience. It includes a number of features that the legacy TypeScript CLI never supported.
-
-### Config
-
-Codex supports a rich set of configuration options. Note that the Rust CLI uses `config.toml` instead of `config.json`. See [`docs/config.md`](../docs/config.md) for details.
-
-### Model Context Protocol Support
-
-#### MCP client
-
-Codex CLI functions as an MCP client that allows the Codex CLI and IDE extension to connect to MCP servers on startup. See the [`configuration documentation`](../docs/config.md#mcp_servers) for details.
-
-#### MCP server (experimental)
-
-Codex can be launched as an MCP _server_ by running `codex mcp-server`. This allows _other_ MCP clients to use Codex as a tool for another agent.
-
-Use the [`@modelcontextprotocol/inspector`](https://github.com/modelcontextprotocol/inspector) to try it out:
-
-```shell
-npx @modelcontextprotocol/inspector codex mcp-server
-```
-
-Use `codex mcp` to add/list/get/remove MCP server launchers defined in `config.toml`, and `codex mcp-server` to run the MCP server directly.
-
-### Notifications
-
-You can enable notifications by configuring a script that is run whenever the agent finishes a turn. The [notify documentation](../docs/config.md#notify) includes a detailed example that explains how to get desktop notifications via [terminal-notifier](https://github.com/julienXX/terminal-notifier) on macOS.
-
-### `codex exec` to run Codex programmatically/non-interactively
-
-To run Codex non-interactively, run `codex exec PROMPT` (you can also pass the prompt via `stdin`) and Codex will work on your task until it decides that it is done and exits. Output is printed to the terminal directly. You can set the `RUST_LOG` environment variable to see more about what's going on.
-
-### Experimenting with the Codex Sandbox
-
-To test to see what happens when a command is run under the sandbox provided by Codex, we provide the following subcommands in Codex CLI:
-
-```
-# macOS
-codex sandbox macos [--full-auto] [--log-denials] [COMMAND]...
-
-# Linux
-codex sandbox linux [--full-auto] [COMMAND]...
-
-# Windows
-codex sandbox windows [--full-auto] [COMMAND]...
-
-# Legacy aliases
-codex debug seatbelt [--full-auto] [--log-denials] [COMMAND]...
-codex debug landlock [--full-auto] [COMMAND]...
-```
-
-### Selecting a sandbox policy via `--sandbox`
-
-The Rust CLI exposes a dedicated `--sandbox` (`-s`) flag that lets you pick the sandbox policy **without** having to reach for the generic `-c/--config` option:
-
-```shell
-# Run Codex with the default, read-only sandbox
-codex --sandbox read-only
-
-# Allow the agent to write within the current workspace while still blocking network access
-codex --sandbox workspace-write
-
-# Danger! Disable sandboxing entirely (only do this if you are already running in a container or other isolated env)
-codex --sandbox danger-full-access
-```
-
-The same setting can be persisted in `~/.codex/config.toml` via the top-level `sandbox_mode = "MODE"` key, e.g. `sandbox_mode = "workspace-write"`.
-
-## Code Organization
-
-This folder is the root of a Cargo workspace. It contains quite a bit of experimental code, but here are the key crates:
-
-- [`core/`](./core) contains the business logic for Codex. Ultimately, we hope this to be a library crate that is generally useful for building other Rust/native applications that use Codex.
-- [`exec/`](./exec) "headless" CLI for use in automation.
-- [`tui/`](./tui) CLI that launches a fullscreen TUI built with [Ratatui](https://ratatui.rs/).
-- [`cli/`](./cli) CLI multitool that provides the aforementioned CLIs via subcommands.
+# nori-rs
+
+The Rust workspace behind the `nori` binary — a multi-provider terminal AI
+coding assistant. Nori is an ACP (Agent Client Protocol) host: it spawns
+agents such as Claude Code, Codex, and Gemini as subprocesses and drives them
+over JSON-RPC/stdio, presenting one terminal interface for all of them.
+
+The workspace began as a fork of the OpenAI Codex CLI. The codex agent engine
+has since been removed; every agent — including Codex — runs as an external
+ACP subprocess. Remaining `codex-*` crates are inherited utility code being
+progressively adopted or removed (see `docs/specs/crate-layering.md`).
+
+## Key crates
+
+| Crate | Purpose |
+|-------|---------|
+| `cli/` (`nori-cli`) | The shipped `nori` binary: dispatch and subcommands |
+| `tui/` (`nori-tui`) | Ratatui interactive terminal interface |
+| `acp/` (`nori-acp`) | ACP backend: agent registry, connection, session runtime |
+| `nori-protocol/` | Session-runtime types over the ACP schema |
+| `installed/` (`nori-installed`) | Install detection and analytics |
+| `mock-acp-agent/` | Mock ACP agent used by tests |
+| `tui-pty-e2e/` | End-to-end PTY tests driving the real binary |
+
+## Working in this workspace
+
+- Build the shipped binary: `cargo build --bin nori`
+- Test a crate: `cargo test -p <crate>`; e2e: `cargo test -p tui-pty-e2e`
+  (requires `cargo build --bin nori` first)
+- Format and lint: `just fmt` and `just fix -p <crate>` from this directory
+- Contributor conventions live in the repo-root `AGENTS.md`; architecture
+  docs in `docs.md` files beside the code
+
+## Distribution
+
+The `nori` binary is packaged by the npm launcher in `../nori-cli/` and
+published as `nori-ai-cli`.