claude-smart 0.2.25 → 0.2.27

package/README.md

@@ -13,7 +13,7 @@
     <img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License">
   </a>
   <a href="plugin/pyproject.toml">
-    <img src="https://img.shields.io/badge/version-0.2.25-green.svg" alt="Version">
+    <img src="https://img.shields.io/badge/version-0.2.27-green.svg" alt="Version">
   </a>
   <a href="plugin/pyproject.toml">
     <img src="https://img.shields.io/badge/python-%3E%3D3.12-brightgreen.svg" alt="Python">
@@ -81,66 +81,45 @@ Four ways this changes what your coding assistant can do for you:
 ### Claude Code
 
 ```bash
-claude plugin marketplace add ReflexioAI/claude-smart
-claude plugin install claude-smart@reflexioai
+npx claude-smart install     # or: uvx claude-smart install
 ```
 
-The plugin Setup hook installs its own `uv`, Python 3.12 environment, and
-private Node.js/npm runtime under `~/.claude-smart/` when they are missing, so
-you do not need to install Python or Node globally for the plugin/dashboard.
+Then restart Claude Code.
 
-If you already have Node.js or uv, these convenience wrappers are equivalent
-but require their own runtime to already exist:
+Requires Node.js (for `npx`) or uv (for `uvx`) to already exist.
+
+Alternatively, install via Claude Code's plugin marketplace:
 
 ```bash
-npx claude-smart install     # or: uvx claude-smart install
+claude plugin marketplace add ReflexioAI/claude-smart
+claude plugin install claude-smart@reflexioai
 ```
 
-Then restart Claude Code.
+The plugin Setup hook installs its own `uv`, Python 3.12 environment, and
+private Node.js/npm runtime under `~/.claude-smart/` when they are missing, so
+you do not need to install Python or Node globally for the plugin/dashboard.
 
 To uninstall:
 
 ```bash
-claude plugin uninstall claude-smart@reflexioai
+npx claude-smart uninstall     # or: uvx claude-smart uninstall
 ```
 
-Or, if you already have Node.js or uv:
+Or, if installed via the plugin marketplace:
 
 ```bash
-npx claude-smart uninstall     # or: uvx claude-smart uninstall
+claude plugin uninstall claude-smart@reflexioai
 ```
 
 ### Codex
 
-You need the `codex` CLI on `PATH` and Node.js available for `npx`:
-
 ```bash
 npx claude-smart install --host codex
 ```
 
-The helper registers the bundled **ReflexioAI** marketplace with Codex, enables
-Codex's `plugin_hooks` feature, installs `claude-smart` into Codex's local
-plugin cache, and enables it in `~/.codex/config.toml`. Hooks are not active in
-already-running Codex windows; after the command finishes:
-
-1. Fully quit and reopen Codex in your project so hooks reload.
-2. Run `/plugins` only if you want to verify `claude-smart` shows as installed
-   from the **ReflexioAI** marketplace.
-
-If you install or toggle `claude-smart` manually from `/plugins`, still run
-`npx claude-smart install --host codex` once afterward so `plugin_hooks` is
-enabled and the cache/config are prepared.
-
-Do not create a `~/plugins/claude-smart` symlink for a normal `npx` install;
-that symlink is only for plugin development from a cloned checkout.
-
-Installing from a clone is only for plugin development; see
-[DEVELOPER.md](./DEVELOPER.md#developing-locally).
-
-Codex and Claude Code intentionally share the same `CLAUDE_SMART_*` environment
-variables, `~/.reflexio/` data, `~/.claude-smart/` session buffers, backend,
-dashboard, and learned skills/preferences.
+Then fully quit and reopen Codex so hooks reload.
 
+Requires the `codex` CLI on `PATH` and Node.js (for `npx`).
 
 To uninstall:
 
@@ -148,11 +127,10 @@ To uninstall:
 npx claude-smart uninstall --host codex
 ```
 
-This removes the Codex marketplace registration, installed plugin config, and
-Codex plugin cache. Local data under `~/.reflexio/` and `~/.claude-smart/` is
-left in place — remove manually if desired. Restart Codex after uninstalling.
+Restart Codex after uninstalling. Learned data under `~/.reflexio/` and `~/.claude-smart/` is preserved and shared with Claude Code, so you can switch between hosts without losing skills or preferences.
+
+Developing the plugin itself? See [DEVELOPER.md](./DEVELOPER.md#developing-locally) for what the installer does, manual toggles via `/plugins`, and clone-based development.
 
-Developing the plugin itself? See [DEVELOPER.md](./DEVELOPER.md#developing-locally).
 > **Not supported:** Claude Code Cowork, claude.ai/code web, or remote Codex environments without local plugin hooks — they run outside your local machine, so the local backend/dashboard and `~/.reflexio/` aren't reachable.
 
 ---
@@ -200,9 +178,7 @@ Under the hood: hooks watch your turns, tool calls, and assistant replies, auto-
 ```
 
 That signals a preference (`p…`) or skill (`s…`) materially shaped the reply.
-Standalone wrappers like `✨abc123✨` are not claude-smart citations and will not
-link back to dashboard entries. Open the interaction's detail page in the
-[dashboard](#dashboard) to see the exact cited item.
+Open the session's detail page in the [dashboard](http://localhost:3001) to see the exact cited item.
 
 See [ARCHITECTURE.md](./ARCHITECTURE.md) for hooks, data flow, and reflexio details.
 
@@ -211,16 +187,17 @@ See [ARCHITECTURE.md](./ARCHITECTURE.md) for hooks, data flow, and reflexio deta
 ## Commands
 
 Claude Code installs these as plugin slash commands. Codex does not currently
-support these plugin-provided slash commands, so run the equivalent shell command
-directly, or ask Codex to run it.
+support plugin-provided slash commands, so claude-smart ships a Codex skill that
+maps requests like "claude-smart show" or "run claude-smart learn" to the
+equivalent action.
 
-| Claude Code | Codex / shell | What it does |
+| Claude Code | Codex request | What it does |
 | --- | --- | --- |
-| `/claude-smart:dashboard` | `bash ~/.reflexio/plugin-root/scripts/dashboard-open.sh` | Open the dashboard in your browser, auto-starting the reflexio backend and dashboard services if they aren't already running. |
-| `/claude-smart:show` | `bash ~/.reflexio/plugin-root/scripts/cli.sh show` | Print current project-specific skills, shared skills, and the current project's preferences so you can audit learned state manually. |
-| `/claude-smart:learn [note]` | `bash ~/.reflexio/plugin-root/scripts/cli.sh learn --note "optional note"` | Flag the most recent turn as a correction (for cases the automatic heuristic missed) and force reflexio to run extraction *now* on the session's unpublished interactions. The optional note becomes the correction description the extractor sees. |
-| `/claude-smart:restart` | `bash ~/.reflexio/plugin-root/scripts/cli.sh restart` | Restart the reflexio backend and dashboard to pick up new changes (e.g. after upgrading the plugin or editing local reflexio code). |
-| `/claude-smart:clear-all` | `bash ~/.reflexio/plugin-root/scripts/cli.sh clear-all --yes` | **Destructive.** Delete *all* reflexio interactions, preferences, and skills. Use when you want to wipe learned state and start fresh. |
+| `/claude-smart:dashboard` | `open claude-smart dashboard` | Open the dashboard in your browser, auto-starting the reflexio backend and dashboard services if they aren't already running. |
+| `/claude-smart:show` | `claude-smart show` | Print current project-specific skills, shared skills, and the current project's preferences so you can audit learned state manually. |
+| `/claude-smart:learn [note]` | `claude-smart learn with note "optional note"` | Flag the most recent turn as a correction (for cases the automatic heuristic missed) and force reflexio to run extraction *now* on the session's unpublished interactions. The optional note becomes the correction description the extractor sees. |
+| `/claude-smart:restart` | `restart claude-smart` | Restart the reflexio backend and dashboard to pick up new changes (e.g. after upgrading the plugin or editing local reflexio code). |
+| `/claude-smart:clear-all` | `clear all claude-smart learnings` | **Destructive.** Delete *all* reflexio interactions, preferences, and skills. Use when you want to wipe learned state and start fresh. |
 
 ---
 
@@ -235,7 +212,7 @@ Advanced users can tune claude-smart via environment variables — see [DEVELOPE
 | `~/.reflexio/data/reflexio.db` | Source of truth for learned preferences, skills, interactions, full-text indexes, and embedding tables (plus `.db-shm` / `.db-wal` WAL sidecars). Inspect with `sqlite3`. |
 | `~/.reflexio/.env` | Provider config — `CLAUDE_SMART_USE_LOCAL_CLI`, `CLAUDE_SMART_USE_LOCAL_EMBEDDING`, any optional API keys. |
 | `.claude/settings.local.json` or `~/.claude/settings.json` | Claude Code hook environment, such as `CLAUDE_SMART_ENABLE_OPTIMIZER`; use project-local settings for one repo or user settings for all projects. |
-| `~/.codex/config.toml` | Codex feature flags, including `plugin_hooks = true` after `claude-smart install --host codex`. |
+| `~/.codex/config.toml` | Codex plugin state, hook feature flags, and per-hook trust entries after `claude-smart install --host codex`. |
 | `~/.codex/plugins/cache/reflexioai/claude-smart/<version>/` | Codex's cached install of the `claude-smart` plugin from the `ReflexioAI` marketplace. |
 | `~/.reflexio/plugin-root` | Self-healed symlink to the active plugin dir (managed by `ensure-plugin-root.sh` — written on install, refreshed each `SessionStart`). Claude Code slash commands and Codex shell-command helpers resolve through it, so don't delete it; if you do, the next session will recreate it. |
 | `~/.claude-smart/sessions/{session_id}.jsonl` | Per-session buffer. User turns, assistant turns, tool invocations, `{"published_up_to": N}` watermarks. Safe to inspect and safe to delete — everything past the latest watermark has already been written to reflexio's DB. |