raiseCatError · Oct 5, 2026 · Oct 5, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -62,8 +62,8 @@ Released (0.16.0): a real ShellAdapter with zsh, Fish and Bash 4.4+ backends ([d
 - Installs are typed argv shown before confirmation; special installers are never run by NMSh.
 - Chroma never reaches generated external artifacts.
 
-## Current surfaces (unreleased beyond v0.16.0)
-Theme Studio (`/theme`), Theme Bridge (`/theme-bridge`), `/providers`, `/tools` with filesystem-detected shell frameworks, `/configure`, `/tmux` Config Studio, `/integrations`, `/dotfiles`, the Oh My Posh provider, and Keep Awake (`/caffeinate`, `/awake`, `/zoomies`, with composer-edge, Status Strip, idle-reminder and screensaver presentation). See CHANGELOG.md → Unreleased.
+## Current surfaces (v0.17.0 release candidate)
+Theme Studio (`/theme`), Theme Bridge (`/theme-bridge`), `/providers`, `/tools` with filesystem-detected shell frameworks, `/configure`, `/tmux` Config Studio, `/integrations`, `/dotfiles`, the Oh My Posh provider, and Keep Awake (`/caffeinate`, `/awake`, `/zoomies`, with composer-edge, Status Strip, idle-reminder and screensaver presentation). Context Engine fact metadata, native module routing and Context Rail are also implemented. See CHANGELOG.md → 0.17.0; tagging and publication are pending.
 
 ## Testing / verification
 During implementation, run focused affected tests. Use `npm run verify:fast` for
@@ -126,7 +126,7 @@ Key references:
 - [GitHub Issues](https://github.com/raiseCatError/notMyShell/issues) — actionable work
 - [v0.16.0 Release](https://github.com/raiseCatError/notMyShell/releases/tag/v0.16.0) — current stable release
 - [PR #303](https://github.com/raiseCatError/notMyShell/pull/303) — the merged cumulative v0.16 release
-- [PR #315](https://github.com/raiseCatError/notMyShell/pull/315) — open development PR for the work after v0.16.0 (not released; the package version stays 0.16.0)
+- [PR #322](https://github.com/raiseCatError/notMyShell/pull/322) — merged checkpoint on master; package 0.17.0 is the release candidate, not yet tagged or published
 - [GitHub Project](https://github.com/users/raiseCatError/projects/1) — live development status board
 - [docs/architecture/terminal-stack.md](docs/architecture/terminal-stack.md) — terminology and stack model
 - [docs/design/structured-execution.md](docs/design/structured-execution.md) — v0.2.0 design decisions

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,8 +6,20 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.17.0] - 2026-10-06
+
+Context Engine, Themes & Discovery: native context routing and Rail foundations, Theme Studio and Theme Bridge, shell/transcript refinements, contextual tools and portability hardening.
+
+### Context Engine and shell/transcript UX
+- **Context Engine foundation:** immutable fact metadata (provenance, freshness, trust, sensitivity and persistence), a native module registry, bounded trusted metadata/Git collection, and Surface Router placement across Main Prompt, Context Rail and Right Context. Repository entry never executes arbitrary repository-controlled code through discovery. General capability scheduling, a broader first-party module catalog and installable declarative Context Packs remain upcoming; no finalized pack SDK or executable plugin API is available.
+- **Context Rail:** independent relation, direction, integration, spacing and divider-anchor controls; one or two actual content rows; horizontal Inside dividers; priority overflow; shared preview/live geometry. Right shell context retains its independent anchor, and existing custom prompt/module configurations are preserved.
+- `/transcript` exposes the same Normal / Chat live presentation setting as `/layout` and Settings, alongside historical prompt and divider controls.
+- `/shell` keeps the current row visibly ticked and highlighted independently of keyboard focus, with explicit current/default markers. Shell indicator Hidden / When not default / Always and Left / Right edit the existing prompt module; changing Side preserves a saved Hidden state and never changes the active session.
+- `/btw` is the canonical local guidance command; `/ask` remains a compatibility alias of the same feature.
+- Portable shell/default-selection coverage, selection-band assertions and canonical CI sharding; full macOS/Ubuntu suites, Node 22 compatibility, Fedora portability and bounded timing smoke cover release candidates.
+
 ### UI consistency and showcase
-- Shared bold accent focus labels across menus, settings, pickers and setup; `/tools` keeps explicit checked markers when focus moves, including without color.
+- Shared bold accent focus labels across menus, settings, pickers and setup; `/tools` keeps full-row semantic selection bands when focus moves, with reverse video without color.
 - Consistent Chroma preview state and base-color guidance; `/syntax` exposes the shared theme families and variants, with previews and cache updates for custom colors and accents.
 - First launch opens Setup Cat. Apply completes onboarding even without appearance edits; presets and completed onboarding bypass discovery.
 - The current-shell module leads the default Native prompt; the former untouched default migrates, while customized module ordering is preserved.
@@ -65,11 +77,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Docs and demos
 - [ARCHITECTURE.md](ARCHITECTURE.md): a plain-language overview of how NMSh works, linked from the README, CONTRIBUTING, AGENTS and llms.txt.
-- README rewritten around what NMSh is, a short hero clip, a visual tour and the safety model; stale zsh-only, fixed-bottom, bat and release claims corrected.
+- README rewritten around what NMSh is, a GitHub-hosted reel hero with YouTube/X links, a mascot-left-of-logo lockup, a visual tour and the safety model; stale zsh-only, fixed-bottom, bat and release claims corrected.
 - Reproducible visual docs: `npm run demos` renders the README and [demo gallery](docs/demos.md) clips from committed VHS tapes in `scripts/demos/` against a disposable demo home (no user config, no network, the inert Keep Awake backend). It replaces the old asciinema/tmux recorder. A small Vespyr divider is generated from the real sprite.
 
 ### Updates and sessions
 - **Automatic updates** (Automatic / Notify only / Off, Daily or Weekly). New installs default to Automatic / Daily; saved Daily/Weekly checks migrate to Notify only and Off stays Off. Automatic prepares a verified stable release only where `/update apply`'s own checks pass, with the same build verification and rollback; the running session keeps its version. Status shows Running version, Latest, Mode and State.
+- Homebrew install provenance prevents the source-checkout updater from mutating the Cellar. Homebrew distribution is still being prepared and is not yet available; publishing remains disabled.
 - Detached sessions can be ended from the startup picker with `X` and confirmation; the transcript is archived and stays in `/resume`.
 
 ## [0.16.0] - 2026-10-04

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -21,7 +21,7 @@ Before starting work, check:
 - **[ROADMAP.md](ROADMAP.md)** — product direction and what is planned
 - **[GitHub Issues](https://github.com/raiseCatError/notMyShell/issues)** — concrete actionable work; acceptance criteria in each issue are authoritative
 - **[v0.16.0 Release](https://github.com/raiseCatError/notMyShell/releases/tag/v0.16.0)** — current stable release
-- **[PR #315](https://github.com/raiseCatError/notMyShell/pull/315)** — current development after v0.16.0 (unreleased; see [ROADMAP.md](ROADMAP.md))
+- **[PR #322](https://github.com/raiseCatError/notMyShell/pull/322)** — merged master checkpoint for the v0.17.0 release candidate (tagging and publication pending; see [ROADMAP.md](ROADMAP.md))
 - **GitHub Project** — [NMSh Development](https://github.com/users/raiseCatError/projects/1) — live development status board
 
 ## Branch Model

diff --git a/README.md b/README.md
@@ -18,7 +18,7 @@
 
 **notMyShell (NMSh)** runs your real zsh, Bash or Fish in a persistent session and gives it a better front end: a composer that stays put, semantic highlighting, a readable transcript, live command feedback, sessions that survive closing the window, and themes that can reach the tools you use.
 
-Current stable release: [v0.16.0 — Sessions, Agents & Portability](https://github.com/raiseCatError/notMyShell/releases/tag/v0.16.0). The `master` branch is the released state; newer work (themes, Theme Bridge, tool configuration, shell frameworks, Keep Awake) is in development and listed under *Unreleased* in the [changelog](CHANGELOG.md). The Context Engine and Context Rail are being developed on `feature/305-context-engine`.
+Latest published stable release: [v0.16.0 — Sessions, Agents & Portability](https://github.com/raiseCatError/notMyShell/releases/tag/v0.16.0). The `master` branch contains the prepared **v0.17.0 — Context Engine, Themes & Discovery** release candidate; tagging and publication are pending. See the [changelog](CHANGELOG.md#0170---2026-10-06) for its implemented scope.
 
 ## See notMyShell in motion
 
@@ -64,7 +64,7 @@ NMSh is a **frontend**. Your shell stays underneath and does what it always did:
 
 The current engineering focus is NMSh's native module ecosystem: trusted capabilities resolve contextual facts, modules turn those facts into presentation, and a Surface Router places them in the Main Prompt, Context Rail or Right Context.
 
-The development branch implements fact metadata, native module routing and the Context Rail. Installable, declarative Context Packs are upcoming; they are not an executable plugin API. Entering a repository must never execute arbitrary repository-controlled code through context discovery.
+The v0.17.0 release candidate implements fact metadata, native module routing and the Context Rail. Installable, declarative Context Packs are upcoming; they are not an executable plugin API. Entering a repository must never execute arbitrary repository-controlled code through context discovery.
 
 Read the [Context Modules guide](docs/architecture/context-modules.md) for the implemented surfaces, discovery boundaries and pack direction, or the [roadmap](ROADMAP.md#current-engineering-focus--native-modules-and-context-engine) for what remains.
 

diff --git a/ROADMAP.md b/ROADMAP.md
@@ -5,22 +5,22 @@
 | | |
 |---|---|
 | **Current release** | [v0.16.0 — Sessions, Agents & Portability](https://github.com/raiseCatError/notMyShell/releases/tag/v0.16.0) — released |
-| **Next development milestone** | [v0.17.0 — Compatibility & Discovery](https://github.com/raiseCatError/notMyShell/milestone/15) |
-| **Current engineering focus** | [#305 — Native modules / Context Engine](https://github.com/raiseCatError/notMyShell/issues/305); foundation and Context Rail implemented on `feature/305-context-engine`, unreleased |
-| **In development (unreleased)** | [PR #315](https://github.com/raiseCatError/notMyShell/pull/315) — Theme Studio, Theme Bridge, tool configuration, shell frameworks, Keep Awake; see CHANGELOG → Unreleased |
+| **Prepared release candidate** | v0.17.0 — Context Engine, Themes & Discovery; on `master`, tagging and publication pending |
+| **Current engineering focus** | [#305 — Native modules / Context Engine](https://github.com/raiseCatError/notMyShell/issues/305); foundation and Context Rail implemented on `master` in the v0.17.0 release candidate |
+| **Included in the release candidate** | Theme Studio, Theme Bridge, tool configuration, shell frameworks, Keep Awake and Context Engine foundation; merged through [PR #322](https://github.com/raiseCatError/notMyShell/pull/322), see CHANGELOG → 0.17.0 |
 | **Unscheduled** | [Future / Backlog](https://github.com/raiseCatError/notMyShell/milestone/7) |
 | **Development branch** | `dev` |
 | **Project board** | [NMSh Development](https://github.com/users/raiseCatError/projects/1) |
 
-GitHub issues define actionable remaining work. Closed issues represent completed work, not a promise that future refinements are finished. The released package is 0.16.0; v0.17 is the next development milestone.
+GitHub issues define actionable remaining work. Closed issues represent completed work, not a promise that future refinements are finished. The latest published release is 0.16.0; the package on `master` is the 0.17.0 release candidate.
 
 ## Current engineering focus — native modules and Context Engine
 
-The primary current direction is [#305](https://github.com/raiseCatError/notMyShell/issues/305): a native module ecosystem built around **Capability → Fact → Module → Surface Router → presentation surfaces**. The [Context Modules guide](docs/architecture/context-modules.md) explains the public model. This work is unreleased; the stable package remains v0.16.0 and the release sequence below remains the planned track.
+The primary current direction is [#305](https://github.com/raiseCatError/notMyShell/issues/305): a native module ecosystem built around **Capability → Fact → Module → Surface Router → presentation surfaces**. The [Context Modules guide](docs/architecture/context-modules.md) explains the public model. The foundation is in the v0.17.0 release candidate on `master`; the broader module ecosystem remains ongoing.
 
 | State | Scope |
 |---|---|
-| Implemented on the feature branch | Typed fact metadata and privacy filtering; trusted bounded metadata/Git collection; the first-party module registry; Main Prompt / Right Context / Context Rail routing; Rail geometry, priority fitting and shared previews |
+| Implemented in the v0.17.0 release candidate | Typed fact metadata and privacy filtering; trusted bounded metadata/Git collection; the first-party module registry; Main Prompt / Right Context / Context Rail routing; Rail geometry, priority fitting and shared previews |
 | Preserved | Existing Native module order, visibility and left/right placement; real zsh/Bash/Fish sessions; prompt snapshots and fullscreen passthrough |
 | Upcoming | General capability scheduling and fuller fact migration; a bounded expansion of useful first-party modules; installable declarative Context Packs with validation and policy |
 | Deferred | Status Strip module routing and any executable extension tier; no finalized public pack API |
@@ -144,7 +144,7 @@ The work formerly planned as v0.8–v0.15 ships together with v0.16 in one cumul
 | Ask & Local Understanding | Deterministic Ask, optional local model (Auto by default, never downloads without a Yes), `/llm` |
 | Appearance | `/appearance` hub; Clean and Rich motion rendering with per-rendering tuning; cursor effects with a capability matrix; Setup Cat as the complete customization entry point; grouped Config and Status |
 
-## Next development — v0.17 Compatibility & Discovery
+## Release candidate — v0.17 Context Engine, Themes & Discovery
 
 [Milestone #15](https://github.com/raiseCatError/notMyShell/milestone/15). Code and automated coverage for `Relevant here`, package-manager plans with bulk install, activation detection, host profiles, Linux/WSL hardening, automatic update staging and startup session kill. Physical validation in iTerm2, Kitty, WezTerm, Linux and WSL 2 is tracked as a separate `needs-human-test` follow-up and does not block the release.
 
@@ -160,8 +160,8 @@ The work formerly planned as v0.8–v0.15 ships together with v0.16 in one cumul
 
 | Release | Theme | Tracker |
 |---|---|---|
-| v0.18.0 | Theme Bridge and semantic terminal integration | [#304](https://github.com/raiseCatError/notMyShell/issues/304), delivered in focused slices; in development on [PR #315](https://github.com/raiseCatError/notMyShell/pull/315), not released. Still deferred: terminal title ownership (OSC 0/2), delta custom styles, terminal emulator and editor base-theme takeover. |
-| v0.19.0 | NMSh Native module ecosystem: current Context Engine foundation and Rail, then capability scheduling, a bounded first-party module expansion and declarative packs | [#305](https://github.com/raiseCatError/notMyShell/issues/305) |
+| v0.18.0 | Theme Bridge and semantic terminal integration | [#304](https://github.com/raiseCatError/notMyShell/issues/304), core Theme Bridge and host semantics are included in the v0.17.0 release candidate; remaining refinements follow in focused slices. Still deferred: terminal title ownership (OSC 0/2), delta custom styles, terminal emulator and editor base-theme takeover. |
+| v0.19.0 | NMSh Native module ecosystem: capability scheduling beyond the v0.17.0 Context Engine foundation and Rail, a bounded first-party module expansion and declarative packs | [#305](https://github.com/raiseCatError/notMyShell/issues/305) |
 
 ## Backlog — future, unscheduled
 

diff --git a/docs/architecture/context-modules.md b/docs/architecture/context-modules.md
@@ -5,9 +5,9 @@ present useful context about that session and workspace without taking over shel
 execution. The Context Engine is the current engineering direction for sharing
 that context across NMSh's presentation surfaces.
 
-This guide describes the unreleased implementation on `feature/305-context-engine`.
-The stable release remains v0.16.0. Installable Context Packs are a direction,
-not an available public extension API.
+This guide describes the v0.17.0 release candidate on `master`; tagging and
+publication are pending. The latest published stable release remains v0.16.0.
+Installable Context Packs are a direction, not an available public extension API.
 
 ## From capability to presentation
 

diff --git a/llms.txt b/llms.txt
@@ -1,6 +1,6 @@
 # notMyShell (NMSh)
 
-Stable release: v0.16.0. Unreleased development continues on feature branches (see CHANGELOG.md).
+Latest published stable release: v0.16.0. Master contains the v0.17.0 release candidate; tagging and publication are pending (see CHANGELOG.md).
 
 notMyShell is a terminal frontend that runs on top of a real persistent shell instead of replacing the shell.
 
@@ -57,7 +57,7 @@ navigation. NMSh bridges to it (/open, /open-diff) and does not clone it.
 - nmsh config export/import, nmsh uninstall, nmsh doctor
 - NMSH_DETERMINISTIC=1 for repeatable presentation in tests and VHS demos
 
-## Native modules / Context Engine (unreleased)
+## Native modules / Context Engine (v0.17.0 release candidate)
 
 Current engineering focus: Capability → immutable Fact → Module → Surface Router
 → Main Prompt / Context Rail / Right Context. Core services own bounded collection;
@@ -66,7 +66,7 @@ freshness, trust, sensitivity and persistence policy. The Rail is live frontend
 geometry, separate from transcript snapshots and the right-context anchor.
 
 The first-party module registry, fact adapter and surface routing are implemented
-on feature/305-context-engine. Installable declarative Context Packs, broader
+on master in the v0.17.0 release candidate. Installable declarative Context Packs, broader
 capability scheduling and Status Strip module routing remain upcoming. No finalized
 pack SDK or executable plugin API is available. Repository entry must never execute
 arbitrary repo-controlled code through discovery; metadata is parser-only and

diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "nmsh",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "A cleaner terminal frontend for zsh with persistent input, autocomplete, semantic highlighting, scrollable history, and better command feedback.",
   "private": true,
   "main": "dist/index.js",