chore: clarify tui, tui-components, react package roles

.changeset/clarify-tui-package-roles.md

@@ -0,0 +1,4 @@
+---
+---
+
+Clarify tui, tui-components, react package roles: remove unused exports, update descriptions, add READMEs

packages/react/README.md

@@ -1,6 +1,6 @@
 # @perstack/react
 
-React hooks and utilities for Perstack integration.
+Reusable React hooks and utilities for Perstack integration. This is the shared React library layer that provides framework-agnostic hooks consumed by both TUI and web applications.
 
 ## Installation
 

packages/tui-components/README.md

@@ -0,0 +1,29 @@
+# @perstack/tui-components
+
+Ink/React TUI components for Perstack terminal interface.
+
+## Role
+
+This private package provides terminal UI components built on Ink and React. These components are specific to the Perstack CLI experience and are consumed by `@perstack/tui`.
+
+## What It Provides
+
+- **renderExecution** — Renders expert execution with streaming output
+- **renderSelection** — Renders interactive expert selection UI
+- **Types** — Shared types for runtime info, history items, and expert options
+
+## Dependencies
+
+```
+@perstack/tui
+  └── @perstack/tui-components  ← this package
+        └── @perstack/react
+```
+
+## Note
+
+This is a **private** package (`"private": true`) — it is not published to npm.
+
+## License
+
+Apache-2.0

packages/tui-components/package.json

@@ -2,7 +2,7 @@
   "name": "@perstack/tui-components",
   "private": true,
   "version": "0.0.5",
-  "description": "Shared TUI components and hooks for Perstack applications",
+  "description": "Ink/React TUI components for Perstack terminal interface",
   "author": "Wintermute Technologies, Inc.",
   "license": "Apache-2.0",
   "type": "module",

packages/tui-components/src/index.ts

@@ -1,9 +1,6 @@
 export type { ExecutionParams, ExecutionResult } from "./execution/index.js"
 // Execution
 export { renderExecution } from "./execution/index.js"
-export { useLatestRef } from "./hooks/use-latest-ref.js"
-export { useListNavigation } from "./hooks/use-list-navigation.js"
-export { useTextInput } from "./hooks/use-text-input.js"
 export type { SelectionParams, SelectionResult } from "./selection/index.js"
 // Selection
 export { renderSelection } from "./selection/index.js"

packages/tui/README.md

@@ -0,0 +1,27 @@
+# @perstack/tui
+
+Non-React TUI logic layer for Perstack CLI applications.
+
+## Role
+
+This package provides the logic layer between CLI apps (`perstack`, `create-expert`) and the UI component layer (`@perstack/tui-components`). It handles context resolution, configuration loading, and handler orchestration — without depending on React or Ink directly.
+
+## What It Provides
+
+- **startHandler / runHandler** — Entry points for CLI command execution
+- **Context resolution** — Resolves expert context from the filesystem
+- **Configuration loading** — Reads `perstack.toml` and provider config
+- **Environment setup** — Loads environment variables and API keys
+
+## Dependencies
+
+```
+CLI apps (perstack, create-expert)
+  └── @perstack/tui          ← this package
+        └── @perstack/tui-components
+              └── @perstack/react
+```
+
+## License
+
+Apache-2.0

packages/tui/package.json

@@ -2,6 +2,7 @@
   "name": "@perstack/tui",
   "private": true,
   "version": "0.0.1",
+  "description": "Non-React TUI logic layer for Perstack CLI applications",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",