feat: make bootstrap the only install entrypoint

CHANGELOG.md

@@ -6,6 +6,10 @@ The format is inspired by Keep a Changelog and is intentionally lightweight whil
 
 ## [Unreleased]
 
+### Changed
+- Removed the legacy `install-codex`, `install-claude`, and `install-hermes` CLI commands. `agent-learner bootstrap` is now the only install entrypoint, with `--adapters` and per-adapter scope flags handling selective setup.
+- npm wrapper help, completion, and lane install forwarding now point to `bootstrap` instead of the removed top-level `install-*` aliases.
+
 ## [0.3.22] - 2026-04-25
 
 ### Fixed

README.md

@@ -59,7 +59,9 @@ Docker is optional convenience only. It is not the primary OSS install path.
 
 ## Typical workflow
 
-1. Install the Codex hook once at user scope or per project
+1. Install the adapter you want to use first
+   - Codex is the most established path
+   - Hermes is available as an explicit experimental opt-in
 2. Run `doctor`
 3. Open the dashboard
 4. Review rules, candidates, and history
@@ -97,17 +99,21 @@ Static dashboard generation and stdlib-only serving still exist, but they are se
 ```bash
 agent-learner doctor --project-root /path/to/repo
 agent-learner dashboard --project-root /path/to/repo --open
-agent-learner install-codex
-agent-learner bootstrap --target /path/to/repo
+agent-learner bootstrap
+agent-learner bootstrap --adapters hermes
 agent-learner review-candidates --project-root /path/to/repo
 agent-learner history --project-root /path/to/repo --latest-per-rule --last 10
 agent-learner history-summary --project-root /path/to/repo --by adapter-decision
 agent-learner overview --project-root /path/to/repo --format json
 agent-learner rebuild-index --project-root /path/to/repo
-agent-learner install-codex --target /path/to/repo
 agent-learner update
 ```
 
+Bootstrap note:
+- `agent-learner bootstrap` is now the only install entrypoint
+- default `bootstrap` installs `codex,claude,hermes`
+- use `agent-learner bootstrap --adapters hermes` if you only want Hermes
+
 ## Repository shape
 
 - `src/agent_learner/` — Python core
@@ -151,6 +157,7 @@ Current implemented areas:
 - dashboard UI
 - global promotion and sync
 - npm wrapper + source checkout helper
+- Hermes experimental adapter with user-scope config.yaml-based hook wiring and runtime smoke coverage
 
 ## Release note
 
@@ -175,10 +182,9 @@ Then follow `docs/publish-smoke-checklist.md`.
 Common wrapper aliases now work directly:
 
 ```bash
-agent-learner install-codex --target "$PWD"
-agent-learner install-claude --target "$PWD"
 agent-learner rebuild-index --project-root "$PWD"
-agent-learner bootstrap --target "$PWD"
+agent-learner bootstrap
+agent-learner bootstrap --adapters hermes
 agent-learner update
 agent-learner completion zsh
 ```

docs/install.md

@@ -100,22 +100,24 @@ or required OSS installation path.
 
 ## Codex adapter
 
+Primary install path for Codex only:
+
 ```bash
-agent-learner install-codex --target /path/to/consumer-repo
+agent-learner bootstrap --adapters codex --target /path/to/consumer-repo
 ```
 
-By default, `install-codex` installs the Codex hook once for your user-level
+By default, `bootstrap --adapters codex` installs the Codex hook once for your user-level
 Codex home so every project can learn into its own local `.agent-learner/`
 tree automatically:
 
 ```bash
-agent-learner install-codex
+agent-learner bootstrap --adapters codex
 ```
 
 If you want the older repo-local hook install, opt into it explicitly:
 
 ```bash
-agent-learner install-codex --scope project --target /path/to/consumer-repo
+agent-learner bootstrap --adapters codex --codex-scope project --target /path/to/consumer-repo
 ```
 
 This creates:
@@ -162,8 +164,10 @@ agent-learner qa-codex-smoke
 
 ## Claude adapter
 
+Primary install path for Claude only:
+
 ```bash
-agent-learner install-claude --target /path/to/consumer-repo
+agent-learner bootstrap --adapters claude --target /path/to/consumer-repo
 ```
 
 This creates:
@@ -172,21 +176,101 @@ This creates:
 - `.claude/skills/session-wrap/`
 - `.claude/skills/feedback-learning/`
 
+## Hermes adapter (experimental)
+
+Hermes support is currently experimental, but the default install path is now user scope so
+it matches Codex and Claude.
+
+Recommended path:
+
+```bash
+agent-learner bootstrap
+```
+
+If you only want Hermes instead of the full default bootstrap set:
+
+```bash
+agent-learner bootstrap --adapters hermes
+```
+
+This creates user-scope Hermes hook assets under `~/.hermes/`:
+- `~/.hermes/config.yaml` when it does not already exist
+- `~/.hermes/config.agent-learner.yaml`
+- `~/.hermes/AGENT_LEARNER_README.md`
+- `~/.hermes/hooks/auto_session_learning.py`
+- `~/.hermes/hooks/hermes_prompt_context.py`
+
+The Hermes adapter wires two real Hermes shell hooks:
+- `pre_llm_call` -> retrieve compact learned guidance with `render-hermes-context`
+- `on_session_end` -> capture a normalized `session_end` event and process it through the shared pipeline
+
+Safe activation model:
+- user-scope install reuses the Hermes config and model/auth you already run
+- `config.yaml` is only created automatically when missing
+- `config.agent-learner.yaml` is always written as a mergeable snippet for existing Hermes setups
+- `AGENT_LEARNER_README.md` explains the generated files and merge path
+
+If you already maintain your own Hermes config, review and merge the hook entries from
+`~/.hermes/config.agent-learner.yaml` into the config you actually run.
+
+If you explicitly want an isolated project-local Hermes home instead, that path is still available:
+
+```bash
+agent-learner bootstrap --adapters hermes --hermes-scope project --target /path/to/consumer-repo
+HERMES_HOME=/path/to/consumer-repo/.hermes hermes --accept-hooks
+```
+
+Preview the learned prompt injection locally:
+
+```bash
+agent-learner render-hermes-context \
+  --project-root /path/to/consumer-repo \
+  --prompt "update hermes bootstrap wiring and keep tests green"
+```
+
+For the actual Hermes hook wire shape:
+
+```bash
+agent-learner render-hermes-context \
+  --project-root /path/to/consumer-repo \
+  --prompt "update hermes bootstrap wiring and keep tests green" \
+  --format hook-json
+```
+
+This prints Hermes-compatible JSON like `{"context": "..."}` for `pre_llm_call`.
+
+Run the Hermes smoke path:
+
+```bash
+agent-learner qa-hermes-smoke
+```
+
+The smoke now verifies both direct script execution and real Hermes runtime wiring with
+`hermes hooks list`, `hermes hooks doctor`, and `hermes hooks test` in an isolated project.
+
+If you want Hermes-only onboarding instead of the default bootstrap:
+
+```bash
+agent-learner bootstrap --adapters hermes
+```
+
 ## One-command onboarding
 
 ```bash
-agent-learner bootstrap --target /path/to/consumer-repo
+agent-learner bootstrap
 ```
 
 Default adapters:
 - codex
 - claude
+- hermes
 
 Customize if needed:
 
 ```bash
-agent-learner bootstrap --target /path/to/consumer-repo --adapters codex
-agent-learner bootstrap --target /path/to/consumer-repo --adapters claude
+agent-learner bootstrap --adapters codex
+agent-learner bootstrap --adapters claude
+agent-learner bootstrap --adapters hermes
 ```
 
 ## Independence guarantee
@@ -287,11 +371,10 @@ These commands verify the expected adapter files/directories exist after install
 Common wrapper aliases now work directly:
 
 ```bash
-agent-learner install-codex --target "$PWD"
-agent-learner install-codex
-agent-learner install-claude --target "$PWD"
+agent-learner bootstrap
+agent-learner bootstrap --adapters codex
+agent-learner bootstrap --adapters hermes
 agent-learner rebuild-index --project-root "$PWD"
-agent-learner bootstrap --target "$PWD"
 agent-learner update
 agent-learner completion zsh
 ```

docs/prerelease-checklist.md

@@ -53,6 +53,7 @@ Then verify:
 ```bash
 npx @cafitac/agent-learner@next version
 npx @cafitac/agent-learner@next doctor
+npx @cafitac/agent-learner@next bootstrap --adapters codex --target /path/to/consumer-repo
 AGENT_LEARNER_UVX_INDEX_URL=https://test.pypi.org/simple \
 AGENT_LEARNER_UVX_EXTRA_ARGS="--refresh --with fastapi<1 --with uvicorn<1 --index-strategy unsafe-best-match" \
   npx @cafitac/agent-learner@next core --help

docs/publish-smoke-checklist.md

@@ -80,13 +80,15 @@ Expected:
 ```bash
 npx @cafitac/agent-learner doctor
 npx @cafitac/agent-learner dashboard --project-root /path/to/consumer-repo
+npx @cafitac/agent-learner bootstrap --adapters codex --target /path/to/consumer-repo
 ```
 
 Expected:
 
 - wrapper launches
 - `doctor` reports a dashboard-oriented verdict/advice
 - `dashboard` delegates correctly into the Python core
+- `bootstrap --adapters codex` reaches the Python core and uses the bootstrap-only install path
 
 ## 4. Source checkout helper smoke (recommended)
 

docs/quickstart.md

@@ -54,13 +54,38 @@ Docker is optional convenience only. The primary path is still `agent-learner da
 
 ```bash
 agent-learner rebuild-index --project-root "$PWD"
-agent-learner bootstrap --target /path/to/consumer-repo
+agent-learner bootstrap
 agent-learner review-candidates --project-root /path/to/consumer-repo
 agent-learner history --project-root /path/to/consumer-repo --latest-per-rule --last 10
 agent-learner history-summary --project-root /path/to/consumer-repo --by adapter-decision
 agent-learner overview --project-root /path/to/consumer-repo --format json
 ```
 
+## Hermes experimental quickstart
+
+If you want to try the Hermes adapter specifically, use the bootstrap path:
+
+```bash
+agent-learner bootstrap --adapters hermes
+agent-learner render-hermes-context --project-root "$PWD" --prompt "update hermes bootstrap wiring and keep tests green"
+agent-learner render-hermes-context --project-root "$PWD" --prompt "update hermes bootstrap wiring and keep tests green" --format hook-json
+agent-learner qa-hermes-smoke
+```
+
+If you explicitly want an isolated project-local Hermes home instead:
+
+```bash
+agent-learner bootstrap --adapters hermes --hermes-scope project --target "$PWD"
+HERMES_HOME=.hermes hermes --accept-hooks
+```
+
+Notes:
+- Hermes is still marked experimental.
+- Default `bootstrap` now installs `codex,claude,hermes`.
+- Hermes default install scope is `user`.
+- The installer writes `~/.hermes/config.agent-learner.yaml` and `~/.hermes/AGENT_LEARNER_README.md` so existing Hermes users can merge hook entries safely.
+- `qa-hermes-smoke` now checks direct script output plus `hermes hooks list/doctor/test` runtime wiring.
+
 ## If you are validating a release
 
 ```bash
@@ -76,10 +101,9 @@ Then follow `docs/publish-smoke-checklist.md`.
 Common wrapper aliases now work directly:
 
 ```bash
-agent-learner install-codex --target "$PWD"
-agent-learner install-claude --target "$PWD"
 agent-learner rebuild-index --project-root "$PWD"
-agent-learner bootstrap --target "$PWD"
+agent-learner bootstrap
+agent-learner bootstrap --adapters hermes
 agent-learner update
 agent-learner completion zsh
 ```

docs/release-process.md

@@ -28,6 +28,7 @@ Run the real user-facing smoke paths in this order:
 1. `pipx install "agent-learner[web]"` -> `agent-learner doctor` -> `agent-learner dashboard`
 2. `uvx --from "agent-learner[web]" agent-learner doctor`
 3. `npx @cafitac/agent-learner doctor`
+4. `npx @cafitac/agent-learner bootstrap --adapters codex --target /path/to/consumer-repo`
 
 Use `docs/publish-smoke-checklist.md` for the exact matrix and optional paths.