Refresh README and scrub personal/local identifiers

README.md

@@ -1,63 +1,293 @@
+<!--
+SEO keywords: alice ai memory, ai agent memory, continuity layer, mcp memory server,
+durable memory for agents, agent resumption, open loop tracking, local-first ai runtime
+-->
+
 # Alice
 
-Alice is a local-first memory and continuity engine for AI agents.
+**The memory and continuity layer for AI agents.**
+
+![Local-first](https://img.shields.io/badge/local--first-core-0A7B61)
+![MCP](https://img.shields.io/badge/MCP-supported-1f6feb)
+![License](https://img.shields.io/badge/license-MIT-2ea043)
+
+Alice gives agents something most assistants still lack:
+**durable memory, clean resumption, open-loop continuity, and correction-aware context.**
+
+Instead of forcing you to restate context over and over, Alice helps your tools and agents remember what matters, resume work intelligently, and improve when corrected.
+
+## What Alice does
+
+Alice helps agents and users:
+
+- **Capture** important notes, decisions, and commitments quickly
+- **Recall** what was decided about a person, project, or topic
+- **Resume** work without rereading long threads
+- **Track open loops** like waiting-fors, blockers, and stale items
+- **Correct memory** so future answers improve deterministically
+
+## Why Alice exists
+
+Most AI assistants still break in the same places:
+
+- they forget why decisions were made
+- they lose context between sessions
+- they treat memory as vague summaries
+- they make correction hard
+- they do not help you resume interrupted work
+
+Alice is built to solve that.
+
+It is a **local-first continuity engine** with:
+
+- structured memory revisions
+- deterministic recall and resumption
+- provenance-aware corrections
+- open-loop management
+- MCP access for external agents
+- importers for existing workflows
+
+## Who it is for
+
+Alice is built for:
+
+- founders
+- operators
+- consultants
+- researchers
+- technical teams
+- agent builders
+- anyone who wants their AI systems to remember and resume work properly
+
+## What makes Alice different
+
+### Memory that can be corrected
+
+Alice does not just store chats.
+It keeps explicit continuity objects and supports review, correction, and supersession.
+
+### Resumption, not just search
+
+Alice is designed to answer:
+
+- What did we decide?
+- What changed?
+- What am I waiting on?
+- Get me back into this project.
+
+### Agent-agnostic by design
 
-Phase 9 is complete. Alice Connect is the planned Phase 10 product layer on top of that shipped core, `P10-S1` through `P10-S4` are shipped, and `P10-S5` is the active execution sprint.
+Use Alice on its own, through the CLI, through MCP, or alongside external agent systems.
 
-## What v0.1 Ships
+### Local-first core
 
-- local-first runtime (`docker compose`, Postgres, API)
-- continuity CLI (`python -m alicebot_api` / `alicebot`)
-- MCP server (`python -m alicebot_api.mcp_server` / `alicebot-mcp`)
-- shipped importer paths: OpenClaw, Markdown, ChatGPT export
-- reproducible evaluation harness (`./scripts/run_phase9_eval.sh`)
+Alice Core runs locally and keeps continuity close to the user.
+
+## Current surfaces
+
+Today, Alice ships with:
+
+- **Alice Core**
+- **CLI**
+- **MCP server**
+- **OpenClaw adapter**
+- **Importers**
+  - OpenClaw
+  - Markdown
+  - ChatGPT exports
 
 ## Quickstart
 
-Run this path on a clean checkout:
+> Replace these commands with your exact final install path before launch.
 
 ```bash
+git clone https://github.com/your-org/alice.git
+cd alice
 cp .env.example .env
-python3 -m venv .venv
-./.venv/bin/python -m pip install -e '.[dev]'
 docker compose up -d
-./scripts/migrate.sh
-./scripts/load_sample_data.sh
-APP_RELOAD=false ./scripts/api_dev.sh
 ```
 
-In another terminal:
+Check status:
+
+```bash
+alice status
+```
+
+Capture something:
+
+```bash
+alice capture "Remember that the Q3 board pack is due on Thursday."
+```
+
+Recall it later:
 
 ```bash
-curl -sS http://127.0.0.1:8000/healthz
-./.venv/bin/python -m alicebot_api status
-./.venv/bin/python -m alicebot_api recall --query local-first --limit 5
-./.venv/bin/python -m alicebot_api resume --max-recent-changes 5 --max-open-loops 5
+alice recall "What do I know about the Q3 board pack?"
 ```
 
-Detailed guide: [docs/quickstart/local-setup-and-first-result.md](docs/quickstart/local-setup-and-first-result.md)
+Resume work:
+
+```bash
+alice resume q3-board-pack
+```
+
+Review open loops:
+
+```bash
+alice open-loops
+```
+
+Correct memory:
+
+```bash
+alice correct-memory
+```
+
+## Use Alice with your agents
+
+Alice is designed to be a continuity layer, not a closed assistant silo.
+
+### MCP
+
+Alice exposes a narrow, stable MCP surface for continuity workflows:
+
+- `alice_capture`
+- `alice_recall`
+- `alice_resume`
+- `alice_open_loops`
+- `alice_recent_decisions`
+- `alice_recent_changes`
+- `alice_memory_review`
+- `alice_memory_correct`
+- `alice_context_pack`
+
+This makes it easy to connect Alice to MCP-capable assistants and development environments.
+
+See:
+
+- [docs/integrations/mcp.md](docs/integrations/mcp.md)
+
+### OpenClaw
+
+Alice includes an OpenClaw integration path for import and augmentation.
+
+You can:
+
+- import existing OpenClaw memory into Alice
+- normalize it into Alice continuity objects
+- use Alice recall and resumption on imported work
+- augment OpenClaw workflows through Alice MCP tools
+
+See:
+
+- [docs/integrations/importers.md](docs/integrations/importers.md)
+
+## Example workflows
+
+### Founder continuity
+
+- capture strategic decisions
+- resume fundraising or product threads
+- track waiting-fors and follow-ups
+- stop losing context across days and weeks
+
+### Consulting continuity
+
+- recall client decisions
+- resume project threads fast
+- maintain open loops without building a manual CRM ritual
+
+### Agent memory upgrade
+
+- plug Alice into your existing agent stack
+- improve recall, resumption, and correction
+- avoid rebuilding your whole runtime
+
+## Architecture at a glance
+
+Alice is built around a shared continuity core:
+
+- immutable events
+- structured memory revisions
+- provenance-aware recall
+- deterministic resumption briefs
+- open-loop objects
+- MCP and CLI surfaces on the same semantics
+
+This means Alice behaves consistently whether you use:
+
+- CLI
+- MCP
+- imported data
+- external adapters
+
+## Why people share Alice
+
+Because Alice solves a very real problem:
+your AI can only be useful if it can remember, resume, and stay aligned with how you actually work.
+
+## Roadmap
+
+### Available now
+
+- local-first core
+- CLI
+- MCP
+- importers
+- OpenClaw adapter
+- reproducible eval harness
+
+### In progress
+
+- Alice Connect
+- hosted identity and workspace bootstrap
+- Telegram-first conversational surface
+- chat-native approvals
+- daily continuity briefs
+
+## Docs
+
+- [Quickstart](docs/quickstart/local-setup-and-first-result.md)
+- [Architecture](ARCHITECTURE.md)
+- [MCP](docs/integrations/mcp.md)
+- [Integrations](docs/integrations/importers.md)
+- [Examples](docs/examples/phase9-command-walkthrough.md)
+
+## Tags
+
+`ai-memory` `agent-memory` `durable-memory` `continuity-layer` `mcp` `local-first` `resumption` `open-loops` `ai-agents` `memory-correction`
+
+## GitHub Topics To Set
+
+Use these in GitHub repository settings (`About` -> `Edit` -> `Topics`):
+
+- [ ] `ai-memory`
+- [ ] `agent-memory`
+- [ ] `mcp`
+- [ ] `local-first`
+- [ ] `continuity-layer`
+- [ ] `durable-memory`
+- [ ] `context-engineering`
+- [ ] `developer-tools`
+- [ ] `openclaw`
+- [ ] `memory-correction`
+
+## Contributing
+
+We welcome issues, adapters, importers, eval contributions, and integration examples.
+
+See:
+
+- [CONTRIBUTING.md](CONTRIBUTING.md)
 
-## Integration Docs
+## Security
 
-- CLI: [docs/integrations/cli.md](docs/integrations/cli.md)
-- MCP: [docs/integrations/mcp.md](docs/integrations/mcp.md)
-- Importers: [docs/integrations/importers.md](docs/integrations/importers.md)
-- Walkthrough: [docs/examples/phase9-command-walkthrough.md](docs/examples/phase9-command-walkthrough.md)
+If you discover a security issue, please report it through the process in:
 
-## Evaluation And Release
+- [SECURITY.md](SECURITY.md)
 
-- Eval harness: `./scripts/run_phase9_eval.sh`
-- Baseline: `eval/baselines/phase9_s37_baseline.json`
-- Latest report path: `eval/reports/phase9_eval_latest.json`
-- Release checklist: [docs/release/v0.1.0-release-checklist.md](docs/release/v0.1.0-release-checklist.md)
-- Release tag plan: [docs/release/v0.1.0-tag-plan.md](docs/release/v0.1.0-tag-plan.md)
-- Release runbook: [docs/runbooks/phase9-public-release-runbook.md](docs/runbooks/phase9-public-release-runbook.md)
+## License
 
-## Canonical Docs
+See:
 
-- Product: [PRODUCT_BRIEF.md](PRODUCT_BRIEF.md)
-- Architecture: [ARCHITECTURE.md](ARCHITECTURE.md)
-- Roadmap: [ROADMAP.md](ROADMAP.md)
-- Rules: [RULES.md](RULES.md)
-- Current state: [.ai/handoff/CURRENT_STATE.md](.ai/handoff/CURRENT_STATE.md)
-- Historical planning and control docs: [docs/archive/planning/2026-04-08-context-compaction/README.md](docs/archive/planning/2026-04-08-context-compaction/README.md)
+- [LICENSE](LICENSE)

REVIEW_REPORT.md

@@ -4,7 +4,7 @@
 PASS
 
 ## criteria met
-- Hosted admin/support visibility for `P10-S5` is implemented with all in-scope endpoints in [`/Users/samirusani/Desktop/Codex/AliceBot/apps/api/src/alicebot_api/main.py`](/Users/samirusani/Desktop/Codex/AliceBot/apps/api/src/alicebot_api/main.py):
+- Hosted admin/support visibility for `P10-S5` is implemented with all in-scope endpoints in [`apps/api/src/alicebot_api/main.py`](apps/api/src/alicebot_api/main.py):
   - `GET /v1/admin/hosted/overview`
   - `GET /v1/admin/hosted/workspaces`
   - `GET /v1/admin/hosted/delivery-receipts`
@@ -13,14 +13,14 @@ PASS
   - `PATCH /v1/admin/hosted/rollout-flags`
   - `GET /v1/admin/hosted/analytics`
   - `GET /v1/admin/hosted/rate-limits`
-- In-scope data additions are present in [`/Users/samirusani/Desktop/Codex/AliceBot/apps/api/alembic/versions/20260409_0047_phase10_beta_hardening_launch.py`](/Users/samirusani/Desktop/Codex/AliceBot/apps/api/alembic/versions/20260409_0047_phase10_beta_hardening_launch.py), including `chat_telemetry` plus additive rollout/support/rate-limit/incident evidence fields.
+- In-scope data additions are present in [`apps/api/alembic/versions/20260409_0047_phase10_beta_hardening_launch.py`](apps/api/alembic/versions/20260409_0047_phase10_beta_hardening_launch.py), including `chat_telemetry` plus additive rollout/support/rate-limit/incident evidence fields.
 - Hosted chat and scheduled-delivery paths enforce deterministic rollout and abuse/rate-limit controls with telemetry evidence.
 - Onboarding failure-state visibility is hardened and now avoids cross-tenant side effects:
-  - admin access requires explicit operator authorization (`hosted_admin_read` + `hosted_admin_operator`) in [`/Users/samirusani/Desktop/Codex/AliceBot/apps/api/src/alicebot_api/main.py:1557`](/Users/samirusani/Desktop/Codex/AliceBot/apps/api/src/alicebot_api/main.py:1557).
-  - bootstrap failure recording only occurs after a resolved member workspace (`resolved_workspace_id` no longer trusts request input) in [`/Users/samirusani/Desktop/Codex/AliceBot/apps/api/src/alicebot_api/main.py:5069`](/Users/samirusani/Desktop/Codex/AliceBot/apps/api/src/alicebot_api/main.py:5069).
+  - admin access requires explicit operator authorization (`hosted_admin_read` + `hosted_admin_operator`) in [`apps/api/src/alicebot_api/main.py:1557`](apps/api/src/alicebot_api/main.py:1557).
+  - bootstrap failure recording only occurs after a resolved member workspace (`resolved_workspace_id` no longer trusts request input) in [`apps/api/src/alicebot_api/main.py:5069`](apps/api/src/alicebot_api/main.py:5069).
 - Rollout patch scope is constrained to hosted flags and caller cohort:
-  - hosted-only key guard in [`/Users/samirusani/Desktop/Codex/AliceBot/apps/api/src/alicebot_api/hosted_rollout.py:55`](/Users/samirusani/Desktop/Codex/AliceBot/apps/api/src/alicebot_api/hosted_rollout.py:55).
-  - caller-cohort enforcement in [`/Users/samirusani/Desktop/Codex/AliceBot/apps/api/src/alicebot_api/hosted_rollout.py:221`](/Users/samirusani/Desktop/Codex/AliceBot/apps/api/src/alicebot_api/hosted_rollout.py:221) and [`/Users/samirusani/Desktop/Codex/AliceBot/apps/api/src/alicebot_api/main.py:5568`](/Users/samirusani/Desktop/Codex/AliceBot/apps/api/src/alicebot_api/main.py:5568).
+  - hosted-only key guard in [`apps/api/src/alicebot_api/hosted_rollout.py:55`](apps/api/src/alicebot_api/hosted_rollout.py:55).
+  - caller-cohort enforcement in [`apps/api/src/alicebot_api/hosted_rollout.py:221`](apps/api/src/alicebot_api/hosted_rollout.py:221) and [`apps/api/src/alicebot_api/main.py:5568`](apps/api/src/alicebot_api/main.py:5568).
 - Launch-facing OSS-vs-hosted clarity updates are present in sprint-owned web/docs surfaces (`README`, admin/onboarding/home shell copy).
 - `P10-S1` through `P10-S4` behavior remains baseline truth; `P10-S5` changes are additive hardening/control-plane seams.
 - Control docs are aligned to an active `P10-S5` execution sprint and baseline-shipped `P10-S1` through `P10-S4` state:

apps/api/src/alicebot_api/retrieval_evaluation.py

@@ -303,6 +303,15 @@ def _repo_root() -> Path:
     return Path(__file__).resolve().parents[4]
 
 
+def _public_source_path(source_path: Path) -> str:
+    resolved = source_path.expanduser().resolve()
+    repo_root = _repo_root()
+    try:
+        return resolved.relative_to(repo_root).as_posix()
+    except ValueError:
+        return f"external/{resolved.name}"
+
+
 def _as_int(value: object) -> int:
     if isinstance(value, bool):
         return int(value)
@@ -411,7 +420,7 @@ def _run_phase9_importer_evidence(
             {
                 "importer": definition.importer_name,
                 "source_kind": definition.source_kind,
-                "source_path": str(definition.source_path.expanduser().resolve()),
+                "source_path": _public_source_path(definition.source_path),
                 "first_run": first_run,
                 "second_run": second_run,
                 "import_success": import_success,