@alan512/experienceengine 0.1.2 → 0.2.0

package/docs/user-guide.md

@@ -11,6 +11,19 @@ In practice, this means:
 - noisy or harmful prior patterns can be cooled or retired
 - the system gradually learns which guidance is actually useful
 
+It also means ExperienceEngine separates:
+
+- `task history`
+  - broad runtime records of what happened
+- `reusable experience`
+  - only the subset of tasks that produced transferable decision guidance
+
+So a task can be recorded without being promoted into learning.
+
+For a focused explanation of what ExperienceEngine stores and how an experience node is governed, see:
+
+- [docs/development/experience-model.md](development/experience-model.md)
+
 For a practical end-to-end workflow on a real repository, see:
 
 - [docs/development/real-repo-playbook.md](development/real-repo-playbook.md)
@@ -48,6 +61,24 @@ When it injects guidance, you will usually see a lightweight notice like:
 
 If there is no intervention, it stays silent.
 
+When ExperienceEngine is less certain but still sees a credible same-family match, it may choose a conservative injection instead of skipping entirely. In that case the injected block stays smaller by default, but mature low-risk nodes can still include a short `Goal / Steps / Avoid` structure when that makes the guidance more actionable.
+
+When you inspect the latest turn, you may also see a learning decision such as:
+
+```text
+Learning status: captured
+Learning reason: provider routing debugging exposed a reusable configuration pattern
+```
+
+or:
+
+```text
+Learning status: rejected
+Learning reason: task stayed in expression-layer refinement: wording, copy, or presentation changes are recorded but not learned
+```
+
+This is intentional. ExperienceEngine now records broad task history, but it only promotes tasks with transferable decision value into the reusable experience pool.
+
 When the host surfaces task-finalization metadata, ExperienceEngine can also show a lightweight feedback reminder after an injected turn so the user can quickly mark whether the hint helped or harmed.
 
 You can also turn inline notices off:
@@ -58,76 +89,209 @@ ee config set notices.inline false
 
 ## Install And First Run
 
-ExperienceEngine installation is now host-native.
+ExperienceEngine installation now starts from the host you want to use.
 
 That means the first installation step belongs to the host you want to use, not to the `ee` CLI.
 
-Install ExperienceEngine through the host-specific flow for:
+Install ExperienceEngine through the host setup flow for:
 
 - `OpenClaw`
-  - planned one-step command:
+  - host-native plugin install:
     - `openclaw plugins install @alan512/experienceengine`
-  - current status:
-    - blocked until the public npm package `@alan512/experienceengine` is published
+  - after installing, restart the gateway before the first real task:
+    - `openclaw gateway restart`
 - `Codex`
-  - planned one-step command:
+  - EE-managed Codex setup:
+    - `ee install codex`
+  - native/manual fallback:
     - `codex mcp add experienceengine --env EXPERIENCE_ENGINE_HOME=$HOME/.experienceengine -- npx -y @alan512/experienceengine codex-mcp-server`
-  - current status:
-    - blocked until the public npm package `@alan512/experienceengine` is published
+  - after either path, start a new Codex session in this repo so the MCP wiring and `AGENTS.md` instruction block are picked up
 - `Claude Code`
-  - add the bundled marketplace from GitHub:
+  - host-native marketplace install:
+    - add the bundled marketplace from GitHub:
     - `/plugin marketplace add https://github.com/Alan-512/ExperienceEngine.git`
   - install the bundled plugin:
     - `/plugin install experienceengine@experienceengine`
   - `ee install claude-code` remains the explicit operator fallback when you need direct hooks + MCP wiring outside the marketplace flow
+  - after installation, start a new Claude Code session so the plugin hooks and bundled MCP config are loaded
+
+Across all three hosts, the intended product journey is the same:
+
+1. install ExperienceEngine through the host-specific setup path
+2. initialize shared ExperienceEngine state with `ee init`
+3. restart or open a fresh host session until the repo is `Ready`
+4. keep routine review and feedback inside the host agent when the host supports it cleanly
+5. use `ee` as the operator fallback for validation, repair, and deeper inspection
 
-Then use the `ee` CLI for validation and operations:
+The host-specific differences are real, but they sit underneath one shared model:
+
+- installation mechanics differ by host
+- routine interaction should feel similar wherever the host supports it
+- CLI remains the explicit fallback and operator surface
+
+Then continue using your host agent normally.
+
+For most users, ExperienceEngine should stay in the background and be inspected through the host agent itself. Typical prompts are:
+
+- "What did ExperienceEngine just inject?"
+- "Why did that ExperienceEngine hint match?"
+- "Mark the last ExperienceEngine intervention as helpful or harmful."
+
+OpenClaw also supports these additional phase-2 routine questions in-session:
+
+- "Is ExperienceEngine ready here?"
+- "Is ExperienceEngine still warming up in this repo?"
+- "Why didn't ExperienceEngine inject anything just now?"
+
+For `OpenClaw`, `Codex`, and `Claude Code`, these routine follow-ups should stay in the host session first.
+
+Use the `ee` CLI only when you need explicit validation, repair, or operator-style troubleshooting:
 
 ```bash
+ee init
 ee doctor <openclaw|claude-code|codex>
 ee status
 ```
 
+Use `ee init` once to initialize ExperienceEngine's shared distillation, embedding, and secret state. New host installations should reuse that same shared EE state instead of asking you to re-enter the same API key per host window.
+
+In practical terms, the routine loop currently looks like this:
+
+- `Codex`
+  - ask the host agent first for recent injections, matching reasons, and helped / harmed feedback
+- `Claude Code`
+  - ask the host agent first for recent injections, matching reasons, and helped / harmed feedback
+- `OpenClaw`
+  - ask the host agent first for recent injections, matching reasons, readiness, warm-up progress, recent silence, and helped / harmed feedback
+  - keep CLI/operator fallback for deeper inspection, repair, and advanced management
+
+For onboarding and first value, ExperienceEngine now uses a two-layer product model:
+
+- `Setup state`
+  - `Installed`
+  - `Initialized`
+  - `Ready`
+- `Value state`
+  - `Warming up`
+  - `First value reached`
+
+These are not one linear state machine.
+
+Examples:
+
+- a repo can already be `Ready` while still `Warming up`
+- a repo can be `Ready` and already have reached first value
+
+In practice:
+
+- installation into a host gets you to `Installed`
+- `ee init` moves the shared product state toward `Initialized`
+- a restart or new host session usually completes `Ready`
+- real task activity moves the value layer from `Warming up` toward `First value reached`
+
+`First value reached` must be tied to visible output from real work, such as:
+
+- a visible real task record
+- a visible learning decision
+- a visible intervention
+
+These do **not** count by themselves:
+
+- a static onboarding message
+- a generic warm-up explanation
+- a recommendation not tied to a real observed task run
+
 You do **not** need to clone the repository or run `pnpm build` for normal user installation.
 
 ### Operational CLI
 
-After a host-native installation succeeds, `ee` becomes the shared operational surface.
+After the host setup succeeds, the host agent remains the primary interaction surface.
 
-Use it for:
+Use `ee` for:
 
+- one-time shared initialization after the first host setup
 - installation validation
 - repair guidance
 - runtime status checks
 - learning and intervention inspection
 - quick helped / harmed feedback
 
+`ee status` and `ee doctor` now also summarize recent retrieval health in product language. They still show the raw counters, but they additionally explain whether ExperienceEngine is mostly injecting, mostly staying conservative, or still skipping too many close-match tasks in the current repo.
+
+Their roles are intentionally different:
+
+- `ee status`
+  - daily progress view
+  - current setup/value state
+  - next practical step
+- `ee doctor <host>`
+  - explicit validation and troubleshooting
+  - install and wiring verification
+  - repair-oriented next steps
+
+The most useful inspection command during product debugging is still:
+
+```bash
+ee inspect --last
+```
+
+That output now tells you both:
+
+- what was injected
+- whether the finalized task was learned, rejected from learning, or only kept as runtime history
+- whether the intervention was a normal injection or a conservative one
+- why ExperienceEngine acted that way in plain language instead of only raw gate fields
+- how trustworthy the selected guidance currently is
+
+When you inspect a specific node, ExperienceEngine now also shows a lightweight quality judgment layer:
+
+- a `quality band` (`strong`, `building`, or `risky`)
+- the short drivers behind that judgment
+- a compact applicability profile covering best fit, scope validity, confidence, risk, and when to avoid reuse
+
 ## How MCP Interaction Works
 
-For `Codex` and `Claude Code`, ExperienceEngine is designed to work mainly through MCP.
+For `Codex` and `Claude Code`, ExperienceEngine is designed to keep routine review and management inside the host session first.
+
+That means after installation, you usually do not leave the agent session to manage ExperienceEngine. Instead, you ask the agent naturally and the host uses its native EE wiring for routine interaction.
+
+This is one host-specific implementation of the same shared product model described above:
 
-That means after installation, you usually do not leave the agent session to manage ExperienceEngine. Instead, you ask the agent naturally and the agent can call ExperienceEngine MCP resources, prompts, and tools for you.
+- host-native install or wiring gets the repo to `Installed`
+- shared `ee init` state gets the product to `Initialized`
+- a fresh host session gets the repo to `Ready`
+- routine inspection and feedback stay inside the host when the host supports them cleanly
+- CLI remains the explicit fallback and operator path
 
 Typical examples:
 - "What did ExperienceEngine just inject?"
+- "Why did that ExperienceEngine hint match?"
 - "Show the recent injected turns."
 - "List active warning nodes."
 - "Pause ExperienceEngine for this project."
-- "Mark the last ExperienceEngine intervention as harmful."
-- "Record quick feedback for the last ExperienceEngine intervention."
+- "Mark the last ExperienceEngine intervention as helpful or harmful."
 - "Create a backup of ExperienceEngine state."
 - "Rollback ExperienceEngine to backup `<id>`."
 
 ### MCP Interaction Model
 
-ExperienceEngine exposes three MCP categories:
+`Codex` exposes a layered MCP surface:
 
-- `Resources`
-  - read-only state like last interaction, recent history, nodes, doctor output, update state, and backups
-- `Prompts`
-  - reusable workflows that guide the agent to inspect or manage ExperienceEngine safely
-- `Tools`
-  - executable actions like feedback, scope toggles, node lifecycle changes, and high-impact operations
+- `Direct tools`
+  - core loop actions like lookup, recording important tool outcomes, finalize, last-feedback, capabilities, and doctor
+- `Routine read resources`
+  - read-only state like last interaction, recent history, repo summary, and routine node views
+- `Brokered advanced actions`
+  - lower-frequency inspect, admin, maintenance, and high-impact plan/execute flows exposed through a small broker tool surface instead of many direct schemas
+
+For `Codex`, this means routine host-native interaction stays discoverable, while long-tail admin and maintenance actions are reached through brokered actions rather than public prompts or one-tool-per-action registration.
+
+`Claude Code` still uses both `hooks` and `MCP`:
+
+- hooks drive runtime capture and injection
+- MCP drives inspect, control, and operational interaction
+
+So the two hosts share the same product model, but they do not expose the exact same interaction shape.
 
 For high-impact actions, ExperienceEngine does not execute immediately. It uses a:
 
@@ -155,104 +319,17 @@ Today, ExperienceEngine's minimal governance surface is:
 
 A dedicated standalone review UI is still deferred. The current product shape is intentionally CLI/MCP-first rather than UI-first.
 
-## Experience Pack v1
-
-Experience Pack v1 is a **local shared-directory registry** for reusable experience assets.
+That does not mean every host surface is identical today:
 
-It lets you take a group of already-validated nodes and move them through a minimal lifecycle:
-
-```text
-draft -> review -> publish -> rollback
-```
-
-Pack v1 is intentionally local-first:
-
-- packs live under `~/.experienceengine/packs`
-- packs are host-agnostic assets, not host-specific config fragments
-- multiple local repos can reuse the same published pack
-- there is no team sync, remote distribution, or UI workflow in v1
-
-Current CLI surface:
-
-```bash
-ee pack list
-ee pack inspect <pack-id>
-ee pack status <pack-id> [version] [agents|codex|github|claude] [repo-path]
-ee pack draft create <pack-id> <node-id[,node-id...]> [name...]
-ee pack review <pack-id> <description...>
-ee pack publish <pack-id>
-ee pack compile <pack-id> [version]
-ee pack compile <pack-id> [version] codex
-ee pack compile <pack-id> [version] github
-ee pack compile <pack-id> [version] claude
-ee pack deploy <pack-id> [version] [agents|codex|github|claude] [repo-path] [--dry-run] [--force] [--status-only]
-ee pack rollback <pack-id> <version>
-```
-
-Use this when you want to turn a set of proven nodes into a managed local asset instead of leaving them only in SQLite state.
-
-### Compiler v1
-
-Compiler v1 turns a published or rolled-back Experience Pack into host-friendly static artifacts.
-
-It is intentionally conservative:
-
-- it only reads Pack files that already exist in the local registry
-- it only exports a static artifact
-- it does **not** auto-write into your repo root
-
-Example:
-
-```bash
-ee pack compile auth-debug-pack
-ee pack compile auth-debug-pack codex
-ee pack compile auth-debug-pack github
-ee pack compile auth-debug-pack claude
-ee pack deploy auth-debug-pack agents /path/to/repo --dry-run
-ee pack deploy auth-debug-pack codex /path/to/repo
-ee pack deploy github-pack github /path/to/repo --force
-ee pack deploy auth-debug-pack claude /path/to/repo
-ee pack deploy auth-debug-pack agents /path/to/repo --status-only
-ee pack status auth-debug-pack agents /path/to/repo
-```
-
-Default output location:
-
-```text
-~/.experienceengine/packs/<pack-id>/compiled/<target>/<version>/
-```
-
-Artifacts produced:
-
-- `AGENTS.md` for `agents` target
-- `CODEX.md` for `codex` target
-- `CLAUDE.md` for `claude` target
-- `<pack-id>.agent.md` for `github` target
-- `compile-report.json`
-
-Deploying compiled artifacts:
-
-- `agents` target writes to `<repo>/AGENTS.md`
-- `codex` target writes to `<repo>/CODEX.md`
-- `claude` target writes to `<repo>/CLAUDE.md`
-- `github` target writes to `<repo>/.github/agents/<pack-id>.md`
-
-Use `--dry-run` to preview the destination without writing files. Existing files are protected by default; use `--force` only when you intentionally want to overwrite the destination. Use `--status-only` to inspect whether the destination is `missing`, `up_to_date`, or `drifted` without writing anything.
-
-If you only want the deployment state without invoking the deploy command shape, use:
-
-```bash
-ee pack status <pack-id> [version] [agents|codex|github|claude] [repo-path]
-```
-
-Compiler visibility is also exposed through:
-
-- `ee pack list`
-- `ee pack inspect <pack-id>`
-- `ee inspect learning`
-- `ee doctor <adapter>`
-
-These surfaces show which targets the current Pack version has already compiled, whether a published Pack is stale, and the latest compile target/time.
+- `Codex` and `Claude Code` use MCP-native host interaction for routine use
+- `OpenClaw` now supports six in-session routine interaction families through the plugin path:
+  - what was injected
+  - why it matched
+  - helped / harmed feedback
+  - readiness in the current repo
+  - warm-up / first-value progress
+  - recent silence on the latest turn
+- advanced operator actions still remain more explicit in CLI across all hosts
 
 ## Host-Specific Setup
 
@@ -264,6 +341,14 @@ Before installing ExperienceEngine into any host, make sure the host CLI itself
 
 ExperienceEngine wires itself into an existing host environment. It does not install the host CLI for you.
 
+If you are installing ExperienceEngine into a repo for the first time, prefer:
+
+```bash
+ee install codex
+```
+
+That command wires the shared MCP server and writes the local `AGENTS.md` instruction block for the current repo.
+
 If you are operating or debugging the product directly, the explicit fallback commands still exist:
 
 ```bash
@@ -276,7 +361,14 @@ These are operator-facing controls, not the preferred public onboarding path.
 
 ## Embedding Retrieval
 
-ExperienceEngine now supports a multi-provider embedding stack for semantic retrieval.
+ExperienceEngine now supports a multi-provider embedding stack inside a staged hybrid retrieval pipeline.
+
+Retrieval is now hybrid by default:
+
+- query normalization and rewrite happen first so retrieval keeps engineering intent when prompt wording shifts
+- lexical and semantic retrieval are fused into one candidate shortlist instead of treating semantic retrieval as the unquestioned main path
+- policy enrichment stays separate from retrieval scoring, so maturity and governance signals do not replace retrieval evidence
+- reranking can promote a better-matching candidate above older score advantages, especially when an external reranker is configured
 
 Default behavior (`embeddingProvider = "api"`):
 
@@ -287,6 +379,12 @@ Default behavior (`embeddingProvider = "api"`):
 - if the API provider fails, ExperienceEngine falls back to the managed local model
 - if the local model fails, ExperienceEngine falls back to legacy hash-based retrieval
 
+Prompt-time behavior:
+
+- first-turn or prompt-only retrieval may not have any tool names or failure signatures yet
+- ExperienceEngine treats those fields as opportunistic evidence, not required retrieval inputs
+- when prompt-only evidence is sparse, lexical, semantic, and policy stages still run with the task summary and context summary alone
+
 Offline behavior (`embeddingProvider = "local"`):
 
 - the default local model is `Xenova/multilingual-e5-small`
@@ -332,6 +430,8 @@ ee install openclaw
 What happens:
 - ExperienceEngine installs as an OpenClaw plugin/runtime integration (not `src/adapters/`)
 - OpenClaw runtime events are used for intervention and persistence
+- OpenClaw uses the shared background learning loop by default
+- async hybrid posttask review stays disabled by default unless the runtime is explicitly overridden
 - management remains mostly through CLI fallback today
 - install ends with a short cold-start note so users know capture is active before the first formal hint appears
 
@@ -429,6 +529,9 @@ Useful commands:
 ```bash
 ee doctor codex
 ee upgrade codex
+ee codex exec -C /path/to/repo -s read-only "Say ok and exit."
+printf "Say ok and exit." | ee codex exec -C /path/to/repo -s read-only -
+ee codex exec --ee-session-id ci-smoke-1 -C /path/to/repo -s read-only "Say ok and exit."
 ```
 
 First validation:
@@ -447,6 +550,12 @@ Host note:
 - ExperienceEngine installs a longer `startup_timeout_sec` for Codex automatically
 - this avoids MCP handshake failures on slower local startups
 - if Codex still cannot see ExperienceEngine in new sessions, re-run `ee install codex`
+- `ee codex exec` is a deterministic wrapper for non-interactive runs
+- the wrapper owns `lookup -> child codex exec -> record -> finalize` outside the child process
+- for wrapped runs, ExperienceEngine removes the nested `experienceengine` MCP server from the child Codex config temporarily so lifecycle evidence is not double-written
+- use prompt `-` when you want the wrapper to read task instructions from stdin; child Codex still receives a wrapped prompt argument and does not inherit stdin
+- use `--ee-session-id <id>` when CI or debugging needs a stable ExperienceEngine session id
+- `codex exec review` is not wrapped yet; keep using native Codex review or the MCP/CLI surfaces for review workflows
 
 Developer validation docs:
 
@@ -463,6 +572,11 @@ Even though MCP is the main user interaction model for Claude/Codex, the `ee` CL
 
 Use MCP first for normal day-to-day interaction inside Claude/Codex.
 
+For the common routine loop, keep these actions in the host session first:
+- ask what ExperienceEngine just injected
+- ask why it matched
+- mark the last intervention as helped or harmed
+
 Use `ee` directly when:
 - the host session cannot currently access MCP
 - you are scripting or automating locally
@@ -494,7 +608,11 @@ ee rollback <backup-id>
 
 ## Doctor, Repair, and Upgrade
 
-Use doctor first if something looks wrong:
+If something feels wrong in normal use, ask the host agent to inspect ExperienceEngine first.
+
+Use the `ee` CLI when you need explicit local validation or the host cannot currently surface enough state.
+
+CLI fallback:
 
 ```bash
 ee doctor openclaw
@@ -511,7 +629,7 @@ What doctor tells you:
 - how many raw task records / task runs / pending candidates / formal nodes exist today
 - the next step to reach first durable value when the system is still warming up
 
-Use repair when host wiring drifted:
+Use repair when host wiring drifted and you need an explicit local recovery step:
 
 ```bash
 ee repair openclaw
@@ -558,7 +676,7 @@ Managed artifacts live under:
 
 Use backup when you want a restorable checkpoint of current ExperienceEngine state.
 
-In an MCP-capable host, ask the agent to create a backup. The agent should first show you a plan and only execute after you confirm.
+In an MCP-capable host, ask the agent to create a backup first. The agent should show a plan and only execute after you confirm.
 
 CLI fallback:
 
@@ -587,6 +705,8 @@ Import restores a valid ExperienceEngine snapshot directory.
 
 Before import overwrites current ExperienceEngine state, the system creates a safeguard backup automatically.
 
+In MCP-capable hosts, prefer asking the agent to plan the import first.
+
 CLI fallback:
 
 ```bash
@@ -599,6 +719,8 @@ Rollback restores one of the managed backups.
 
 Before rollback overwrites current ExperienceEngine state, the system also creates a safeguard backup automatically.
 
+In MCP-capable hosts, prefer asking the agent to plan the rollback first.
+
 CLI fallback:
 
 ```bash
@@ -618,6 +740,11 @@ For risky changes:
 
 ### Review what happened last
 
+For normal day-to-day usage in Claude Code or Codex, ask the host agent first:
+
+- "What did ExperienceEngine just inject?"
+- "Why did that ExperienceEngine hint match?"
+
 Fallback CLI:
 
 ```bash
@@ -629,11 +756,11 @@ This view now also shows:
 - origin record ids when they exist
 - the node evidence summary attached to each injected hint
 
-In MCP-capable hosts, ask:
+### Review recent injected turns
 
-- "What did ExperienceEngine just inject?"
+In MCP-capable hosts, ask:
 
-### Review recent injected turns
+- "Show the recent injected ExperienceEngine turns."
 
 Fallback CLI:
 
@@ -641,12 +768,10 @@ Fallback CLI:
 ee inspect recent injected 10
 ```
 
-In MCP-capable hosts, ask:
-
-- "Show the recent injected ExperienceEngine turns."
-
 ### Review current node inventory
 
+In MCP-capable hosts, ask for the current active strategies or warnings first.
+
 Fallback CLI:
 
 ```bash
@@ -658,6 +783,8 @@ ee inspect node <id>
 
 ### Manually correct feedback
 
+In MCP-capable hosts, prefer asking the agent to mark the last intervention as helpful or harmful.
+
 Fallback CLI:
 
 ```bash
@@ -673,6 +800,8 @@ ee feedback node <id> harmed
 
 ### Temporarily pause interventions
 
+In MCP-capable hosts, prefer asking the agent to pause or resume ExperienceEngine for the current scope.
+
 Fallback CLI:
 
 ```bash
@@ -687,12 +816,13 @@ What is already mature enough to use:
 - real runtime integration on Claude Code
 - real runtime integration on Codex
 - MCP-native inspect/control workflows on Claude/Codex
+- in-session routine review and feedback workflows on OpenClaw
 - managed state backup and restore over MCP `plan + confirm`
 
 What is still intentionally simpler:
-- OpenClaw does not yet have the same MCP-native user interaction layer as Claude/Codex
+- OpenClaw does not use the same MCP-native interaction shape as Claude/Codex
 - user-facing docs are lighter than a full product site
-- CLI fallback is still more complete than some host-native surfaces
+- CLI fallback is still more complete than some host-side surfaces
 
 ## If Something Feels Wrong