docs: describe global-first storage model

CHANGELOG.md

@@ -7,6 +7,7 @@ The format is inspired by Keep a Changelog and is intentionally lightweight whil
 ## [Unreleased]
 
 ### Changed
+- Documentation now describes the global-first storage model: `AGENT_LEARNER_HOME` (default `~/.agent-learner/`) is the canonical home, while project-local `.agent-learner/` assets are legacy migration sources rather than fallback stores.
 - 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.
 - Hermes user-scope bootstrap now auto-merges `pre_llm_call` and `on_session_end` hooks into an existing `~/.hermes/config.yaml`, writes a backup before updating the active config, and keeps `config.agent-learner.yaml` as a re-sync/reference snippet.

README.md

@@ -4,7 +4,7 @@ Reusable learning control plane for coding-agent workflows.
 
 `agent-learner` helps you:
 - capture learned rules from agent work
-- keep project-local and global learning assets separate
+- keep repo-scoped and global learning assets in one canonical global store
 - review candidates and promote useful rules
 - use a dashboard UI for history, rules, and promotions
 
@@ -65,22 +65,23 @@ Docker is optional convenience only. It is not the primary OSS install path.
 2. Run `doctor`
 3. Open the dashboard
 4. Review rules, candidates, and history
-5. Promote reusable learning assets to the global layer when appropriate
+5. Promote reusable learning assets after review; repo scoping is tracked by metadata, not separate local stores
 
 ## Core concepts
 
-### Project-local vs global learning
+### Global-first learning storage
 
-- project-local knowledge lives under `<project>/.agent-learner/`
-- reusable shared knowledge lives under `~/.agent-learner/global/`
-- retrieval is local-first, then global
-- Codex can be installed once at user scope while still writing learning assets per project
+- canonical durable learning lives under `AGENT_LEARNER_HOME` (default `~/.agent-learner/`)
+- events, candidates, history, rules, and indexes are stored in that global home
+- repo-specific behavior is selected by repo identity, learning scope, and provenance metadata rather than by a project-local storage root
+- existing `<project>/.agent-learner/` and `.codex/references/learning/` assets are treated as legacy migration sources, not normal fallback stores
+- Codex, Claude, and Hermes can be installed at user scope while still resolving the active repo from `cwd`
 - external wiki/KB systems remain separate and are not part of the canonical learning lifecycle
 
 ### Indexed retrieval and pruning
 
-- rules are indexed into machine-readable metadata under `.agent-learner/index/rules.json`
-- a human-readable summary is also written to `.agent-learner/index/index.md`
+- rules are indexed into machine-readable metadata under `$AGENT_LEARNER_HOME/index/rules.json`
+- a human-readable summary is also written to `$AGENT_LEARNER_HOME/index/index.md`
 - retrieval uses the index first, then loads only the top matching rules
 - `approved` rules are injected by default; `needs_review` and `deprecated` stay out unless explicitly requested
 - use `agent-learner rebuild-index --project-root "$PWD"` if you want to force a full reindex after manual edits

docs/adapter-convergence.md

@@ -23,7 +23,7 @@ After inspecting the current local environments:
 - OMX adds routing/state/trace infrastructure, but not a shared learned-feedback control plane equivalent to Claude's `cc-learner`
 
 ### Hermes today (`.hermes` / `~/.hermes`)
-- thin experimental adapter path built around project-local learned rules
+- thin experimental adapter path built around globally stored learned rules with repo provenance
 - prompt-time context injection via the real Hermes `pre_llm_call` shell hook
 - session-end capture via the real Hermes `on_session_end` shell hook and normalized `session_end` events
 - shared retrieval and event-processing core reused instead of adding a Hermes-specific learner
@@ -41,9 +41,9 @@ Instead:
 ## What this repo now provides
 
 - shared retrieval/ranking core
-- shared normalized raw hook event location under `.agent-learner/events/`
-- transcript-aware candidate extraction into `.agent-learner/candidates/`
-- processed marker state under `.agent-learner/state/processed-events/`
+- shared normalized raw hook event location under `$AGENT_LEARNER_HOME/events/`
+- transcript-aware candidate extraction into `$AGENT_LEARNER_HOME/candidates/`
+- processed marker state under `$AGENT_LEARNER_HOME/state/processed-events/`
 - Codex prompt-time learning context injection
 - Hermes prompt-time learning context injection via `render-hermes-context`
 - Hermes normalized `session_end` event capture and processing

docs/architecture.md

@@ -3,15 +3,15 @@
 - `src/agent_learner/core/` holds lifecycle and retrieval logic.
 - `src/agent_learner/adapters/` holds adapter-specific installation and rendering surfaces.
 - `frontend/` holds the React + Vite dashboard UI that talks to the FastAPI dashboard surface.
-- Consumer repos can install adapters independently, while the Codex adapter can also be installed once at user scope and still resolve per-project learning roots from `cwd`.
+- Consumer repos can install adapters independently, while user-scope adapters still resolve the active repo from `cwd` and attach repo identity/provenance metadata to global learning artifacts.
 - `agent-learner` owns the canonical learning plane, not cross-runtime wiki management.
 - Codex prompt application is retrieval-first: approved learned rules are ranked per-turn and injected through `UserPromptSubmit` as ephemeral additional context instead of expanding the persistent system prompt.
-- Long-lived storage remains file-native under `.agent-learner/learning/`, while runtime context stays token-budgeted and temporary.
-- Both adapters now emit normalized raw hook events under `.agent-learner/events/<adapter>/` so stronger Claude-side learning logic can be absorbed into shared core workflows instead of remaining adapter-local only.
+- Long-lived storage remains file-native under `AGENT_LEARNER_HOME` (default `~/.agent-learner/`), while runtime context stays token-budgeted and temporary.
+- Adapters emit normalized raw hook events under `$AGENT_LEARNER_HOME/events/<adapter>/` so stronger runtime-specific learning logic can be absorbed into shared core workflows instead of remaining adapter-local only.
 - Normalized raw hook events feed a shared transcript-aware extraction pipeline that writes draft candidates and processed markers independently of adapter-specific storage.
 - Shared context detection (project, language, framework, current model) now informs retrieval so approved rules can be gated similarly to Claude's `cc-learner` portfolio behavior.
 - Retrieval and lifecycle now support model-aware validation/exclusion metadata and sweep-based status transitions.
 - External wiki/KB systems such as `.omx/wiki/` or runtime-specific KBs may coexist, but they are outside the canonical learning lifecycle.
 
-- Retrieval is now two-stage: a machine-readable rule index under `.agent-learner/index/rules.json` narrows candidates first, then only the top matching rule files are loaded for prompt injection.
-- Human-readable index snapshots under `.agent-learner/index/index.md` make it easier to audit and prune stale knowledge without opening every rule file.
+- Retrieval is now two-stage: a machine-readable rule index under `$AGENT_LEARNER_HOME/index/rules.json` narrows candidates first, then only the top matching rule files are loaded for prompt injection.
+- Human-readable index snapshots under `$AGENT_LEARNER_HOME/index/index.md` make it easier to audit and prune stale knowledge without opening every rule file.

docs/install.md

@@ -68,7 +68,7 @@ npm-wrapper goal:
 npx @cafitac/agent-learner@latest dashboard --project-root "$PWD" --open
 ```
 
-The retrieval path uses `.agent-learner/index/rules.json` first and only loads the top matching rules into prompt context.
+The retrieval path uses `$AGENT_LEARNER_HOME/index/rules.json` first and only loads the top matching rules into prompt context.
 If you edit rule files manually, rebuild the index with:
 
 ```bash
@@ -107,8 +107,9 @@ agent-learner bootstrap --adapters codex --target /path/to/consumer-repo
 ```
 
 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:
+Codex home. Each project is resolved from `cwd`, while events, candidates,
+history, indexes, and durable rules are written to `AGENT_LEARNER_HOME`
+(default `~/.agent-learner/`) with repo provenance metadata:
 
 ```bash
 agent-learner bootstrap --adapters codex
@@ -120,33 +121,37 @@ If you want the older repo-local hook install, opt into it explicitly:
 agent-learner bootstrap --adapters codex --codex-scope project --target /path/to/consumer-repo
 ```
 
-This creates:
+For a project-scope Codex hook install, this creates the adapter surface:
 - `.codex/hooks.json`
 - `.codex/skills/session-wrap/`
 - `.codex/skills/feedback-learning/`
 - `.codex/skills/hermit-learner/`
 - `.codex/references/scripts/auto_session_learning.py`
 - `.codex/references/scripts/codex_prompt_context.py`
-- `.agent-learner/learning/`
-- `.agent-learner/events/codex/`
-- `.agent-learner/candidates/`
-- `.agent-learner/history/`
-- `.agent-learner/state/processed-events/`
+
+The learning data itself is stored globally:
+- `$AGENT_LEARNER_HOME/learning/`
+- `$AGENT_LEARNER_HOME/events/codex/`
+- `$AGENT_LEARNER_HOME/candidates/`
+- `$AGENT_LEARNER_HOME/history/`
+- `$AGENT_LEARNER_HOME/state/processed-events/`
 
 The Codex adapter wires two native hook paths:
 - `UserPromptSubmit` -> retrieve approved learning assets and inject compact per-turn context
 - `Stop` -> capture new learning candidates and refresh the dashboard
 
-Canonical durable learning storage lives under `.agent-learner/learning/`.
-`.codex/` remains the adapter and hook surface, not the system of record.
+Canonical durable learning storage lives under `$AGENT_LEARNER_HOME/learning/`
+(default `~/.agent-learner/learning/`). `.codex/` remains the adapter and hook
+surface, not the system of record.
 External wiki/KB systems are intentionally out of scope for normal adapter install
 and runtime behavior.
 With the default `user` scope, hook scripts are installed under `~/.codex/`, but the hook
-still resolves the active project from `cwd` and writes learning assets under the
-current repo instead of mixing everything into the user home.
-If legacy rules already exist under `.codex/references/learning/`, install/bootstrap
-copies them into the canonical root and writes a migration marker so reads switch
-cleanly without hiding existing assets.
+still resolves the active project from `cwd`; repo identity and provenance keep
+project-specific retrieval separate inside the global learning home.
+If legacy rules already exist under `<project>/.agent-learner/` or
+`.codex/references/learning/`, install/bootstrap copies them into the canonical
+global root and writes a migration marker so reads switch cleanly without hiding
+existing assets.
 
 Preview the prompt injection locally:
 

docs/scope-learning-system.md

@@ -44,7 +44,7 @@ That would weaken the OSS story and blur the product boundary.
 `agent-learner` should own and evolve only the learning-oriented data plane:
 
 ```text
-.agent-learner/
+$AGENT_LEARNER_HOME/        # defaults to ~/.agent-learner/
   events/
   candidates/
   learning/
@@ -60,6 +60,9 @@ These artifacts are the canonical inputs for:
 - promotion/deprecation history
 - future `autoresearch`
 
+Project-specific behavior is tracked through repo identity, learning scope, and
+provenance metadata rather than a project-local canonical root.
+
 ## What is explicitly out of scope
 
 `agent-learner` should not become responsible for:

docs/storage-independence-and-provenance.md

@@ -8,20 +8,20 @@ provenance, comparison, and revision history.
 
 ## Current state
 
-`agent-learner` already has a shared-core data plane under `.agent-learner/`:
+`agent-learner` already has a shared-core data plane under `AGENT_LEARNER_HOME` (default `~/.agent-learner/`):
 
-- `.agent-learner/events/`
-- `.agent-learner/candidates/`
-- `.agent-learner/state/`
+- `$AGENT_LEARNER_HOME/events/`
+- `$AGENT_LEARNER_HOME/candidates/`
+- `$AGENT_LEARNER_HOME/state/`
 
 The earlier design problem was that Codex-side learning could write
 session-wrap artifacts into `.omx/wiki/session-log/`, which made the adapter
 feel coupled to OMX even though OMX is supposed to be an optional runtime
 integration, not a required storage dependency.
 
 That coupling has been removed from the current repo direction: canonical
-learning state now lives under `.agent-learner/`, and external wiki/KB systems
-are outside the canonical lifecycle.
+learning state now lives under `AGENT_LEARNER_HOME`, and external wiki/KB
+systems are outside the canonical lifecycle.
 
 The current implementation also does **not** have a real "compare old learned
 rule vs new learned rule and update the existing rule with an explicit diff
@@ -65,13 +65,13 @@ This leads to a bad middle ground:
 
 ## Decision
 
-`agent-learner` will treat `.agent-learner/` as the only canonical storage root.
+`agent-learner` will treat `AGENT_LEARNER_HOME` as the only canonical storage root.
 
 Adapter and runtime folders stay thin:
 
 - `.codex/` and `.claude/` are adapter surfaces
 - `.omx/` and `.omc/` are optional integration surfaces
-- `.agent-learner/` is the learning system of record
+- `AGENT_LEARNER_HOME` is the learning system of record
 
 We will not keep full session logs as a default durable artifact.
 
@@ -96,10 +96,10 @@ that keeps wiki/KB systems outside the canonical learning scope.
 
 ## Canonical storage layout
 
-Proposed canonical tree:
+Implemented canonical tree:
 
 ```text
-.agent-learner/
+$AGENT_LEARNER_HOME/        # defaults to ~/.agent-learner/
   events/
     codex/
     claude/
@@ -121,9 +121,8 @@ Proposed canonical tree:
 
 Notes:
 
-- `learning/` becomes the canonical lifecycle root.
-- Existing `.codex/references/learning/` can remain adapter-facing for a migration
-  window, but the long-term source of truth should move to `.agent-learner/learning/`.
+- `learning/` is the canonical lifecycle root inside `AGENT_LEARNER_HOME`.
+- Existing `<project>/.agent-learner/` and `.codex/references/learning/` assets are migration sources; reads and writes use the global home after migration.
 - Wiki/KB systems remain external integrations, not part of the canonical tree.
 
 ## Why session logs are not the primary artifact
@@ -186,7 +185,7 @@ last_validated_by: "human-review"
 Add a canonical append-only ledger:
 
 ```text
-.agent-learner/history/promotions.jsonl
+$AGENT_LEARNER_HOME/history/promotions.jsonl
 ```
 
 Each entry records a learning decision:
@@ -565,12 +564,12 @@ In short:
 ### Phase 1
 
 - completed: stop writing canonical artifacts into `.omx/wiki/session-log/`
-- add `.agent-learner/history/promotions.jsonl`
+- add `$AGENT_LEARNER_HOME/history/promotions.jsonl`
 - add provenance fields to rule metadata
 
 ### Phase 2
 
-- move canonical lifecycle root from `.codex/references/learning/` to `.agent-learner/learning/`
+- move canonical lifecycle root from `.codex/references/learning/` and project-local `.agent-learner/learning/` into `$AGENT_LEARNER_HOME/learning/`
 - keep adapter-facing compatibility shims during migration
 
 ### Phase 3

plugins/codex/README.md

@@ -7,7 +7,7 @@ Codex-specific overlay assets live here.
 - install `.codex/hooks.json`
 - install Codex-facing skills
 - install learning references
-- keep Codex integration thin while canonical learning state lives under `.agent-learner/`
+- keep Codex integration thin while canonical learning state lives under `AGENT_LEARNER_HOME` (default `~/.agent-learner/`)
 
 ## Design goal