maestro-care 0.0.1__tar.gz

maestro_care-0.0.1/.env.example

@@ -0,0 +1,337 @@
+# CARE environment-variable overrides (TODO §2 P1).
+#
+# Every setting in `CareConfig` has a `CARE_*` env var equivalent.
+# Nested sections use double-underscores (so `[mage] mode = "fast"`
+# in TOML is `CARE_MAGE__MODE=fast` here). Env vars override values
+# from both `~/.config/care/config.toml` and per-project
+# `./care.toml`; defaults from `care.config` apply for anything
+# you leave unset.
+#
+# Precedence: defaults < ~/.config/care/config.toml < ./care.toml < env.
+#
+# Copy this file to `.env` (or export the vars in your shell) and
+# fill in only the values you need to override.
+
+# ---------------------------------------------------------------------------
+# [mage] — MAGE generator
+# ---------------------------------------------------------------------------
+
+# Generation mode. `deep` does the full multi-stage pipeline; `fast`
+# is single-shot.
+# CARE_MAGE__MODE=deep
+
+# Base URL of the OpenAI-compatible HTTP endpoint MAGE / CARL
+# should talk to. Any provider with an OpenAI-shaped API works
+# (OpenAI, OpenRouter, Groq, DeepSeek, Together, a local
+# Ollama / llama.cpp server, etc.). Examples:
+#   https://api.openai.com/v1
+#   https://openrouter.ai/api/v1
+#   http://localhost:11434/v1
+# REQUIRED.
+# CARE_MAGE__BASE_URL=https://openrouter.ai/api/v1
+
+# API key sent as `Authorization: Bearer …`. REQUIRED.
+# CARE_MAGE__API_KEY=
+
+# Model id the endpoint understands. REQUIRED.
+# CARE_MAGE__MODEL=anthropic/claude-3.5-sonnet
+
+# Whether MAGE recalls relevant past chains/knowledge from Memory during
+# generation (stage 0a) and feeds a digest to the planner — generation
+# gets smarter as Memory fills. On by default; costs ~one extra sub-query
+# LLM call per generation. Set to false for the lowest-latency path.
+# Accepts `true` / `false` / `1` / `0`.
+# CARE_MAGE__ENABLE_MEMORY_RESEARCH=true
+
+# Strategy for Memory recall during generation. `bm25` (default) suits the
+# bundled Memory deployment, which ships with vector search OFF — `hybrid`
+# /`vector` silently fall back to bm25 with a per-search warning. Flip to
+# `hybrid` once Memory has vector search + sentence-transformers enabled.
+# CARE_MAGE__MEMORY_SEARCH_MODE=bm25
+
+# Minimum relevance score for a recalled chain to be kept. Default 0.0 —
+# bm25 scores are small (~0.1), so a higher gate silently drops every real
+# hit (perpetual cold-start). MAGE's applicability gate (an LLM judge)
+# still filters quality downstream.
+# CARE_MAGE__MEMORY_RELEVANCE_THRESHOLD=0.0
+
+# Whether MAGE may issue web-search queries. Off by default to keep
+# generation deterministic + cheap.
+# CARE_MAGE__ENABLE_WEB_RESEARCH=false
+
+# Web-search engine MAGE uses (tavily / serpapi / brave). Mirrors
+# CARE_TOOLS__WEB_SEARCH_PROVIDER so generation + the runtime
+# web_search tool share one engine.
+# CARE_MAGE__WEB_SEARCH_PROVIDER=tavily
+
+# API key for the web-search provider. Only consulted when
+# `enable_web_research=true`.
+# CARE_MAGE__WEB_SEARCH_API_KEY=
+
+# --- MAGE planning-stage discovery (forwarded to mmar_mage) ---
+# CARE normally INJECTS capabilities into generation, which bypasses MAGE's
+# own discovery agents — so all three default OFF. Flip them only for
+# deployments where MAGE should discover tools/skills itself.
+
+# Run MAGE's CapabilityLookupAgent at plan time.
+# CARE_MAGE__ENABLE_CAPABILITY_LOOKUP=false
+
+# Let MAGE query Memory for `agent_skill` entities during capability lookup
+# (needs MAGE's memory client working — Phase C).
+# CARE_MAGE__ENABLE_MEMORY_SKILL_LOOKUP=false
+
+# Surface packaged AgentSkills via MAGE's built-in SkillRegistry.
+# CARE_MAGE__ENABLE_SKILL_DISCOVERY=false
+
+# --- Chain topology + depth ---
+# MAGE's own defaults bias hard toward short LINEAR chains (it halves the
+# analyzer's suggested step count and never varies the shape), which
+# collapses most generations to a 2-step tool→llm chain. CARE overrides them
+# so generation can pick richer shapes (diamond / map_reduce / tree_of_thought
+# / hierarchical / …) with appropriate depth. Steps whose type the installed
+# CARL can't run are downgraded to `llm` at run time (the DAG shape survives).
+
+# Hint the planner toward a task-appropriate topology instead of always a
+# linear pipeline. One extra LLM call per generation. Set false to force
+# linear chains (MAGE's stock behaviour).
+# CARE_MAGE__ENABLE_TOPOLOGY_SELECTION=true
+
+# How many ranked topology candidates the selector keeps (1–8).
+# CARE_MAGE__TOPOLOGY_MAX_CANDIDATES=3
+
+# Scales the analyzer's suggested step count by (1 - bias), floored at 2.
+# MAGE defaults to 0.5 (aggressive shortening); CARE uses 0.2 so non-trivial
+# tasks keep enough steps to form a real topology. 0.0 = fully trust the
+# analyzer; 0.5+ = force short chains.
+# CARE_MAGE__SIMPLICITY_BIAS=0.2
+
+# Hard cap on plan length (2–30) — a longer plan without a filled rationale
+# is truncated. Raise for deliberately long pipelines.
+# CARE_MAGE__SIMPLICITY_MAX_STEPS=7
+
+# ---------------------------------------------------------------------------
+# [memory] — GigaEvo Memory connection
+# ---------------------------------------------------------------------------
+
+# Base URL for the GigaEvo Memory server.
+# CARE_MEMORY__BASE_URL=http://localhost:8000
+
+# API key (sent as `X-API-Key`). Only required when Memory has
+# `AUTH_REQUIRED=true`; dev installs leave it empty.
+# CARE_MEMORY__API_KEY=
+
+# Per-request HTTP timeout in seconds.
+# CARE_MEMORY__TIMEOUT=30.0
+
+# ---------------------------------------------------------------------------
+# [platform] — GigaEvo Platform connection
+# ---------------------------------------------------------------------------
+
+# Base URL for the GigaEvo Platform `master_api`.
+# CARE_PLATFORM__BASE_URL=http://localhost:8001
+
+# API key. Same convention as `CARE_MEMORY__API_KEY`.
+# CARE_PLATFORM__API_KEY=
+
+# Per-request HTTP timeout.
+# CARE_PLATFORM__TIMEOUT=30.0
+
+# ---------------------------------------------------------------------------
+# [upload] — External chain-upload target (Phase 3 P2)
+# ---------------------------------------------------------------------------
+
+# POST endpoint that receives a saved chain when the user runs
+# `/upload <chain_id>` in chat. Empty disables the slash
+# command. Body shape: {"chain_id": "...", "chain": {...}}.
+# CARE_UPLOAD__URL=
+
+# Optional credential sent in `auth_header`. With the default
+# `Authorization` header, value rides as `Bearer <key>`; with a
+# different header name (e.g. `X-API-Key`) the value is sent
+# raw.
+# CARE_UPLOAD__API_KEY=
+
+# Header name to carry the credential. Default fits the
+# canonical OAuth-style `Authorization: Bearer <key>`.
+# CARE_UPLOAD__AUTH_HEADER=Authorization
+
+# Per-request HTTP timeout in seconds.
+# CARE_UPLOAD__TIMEOUT=30.0
+
+# ---------------------------------------------------------------------------
+# [sandbox] — AgentSkill sandbox backend
+# ---------------------------------------------------------------------------
+
+# Backend kind. `local` is unsafe — appropriate only for CARE-internal
+# testing. Choose `docker`, `e2b`, or `firejail` for real runs.
+# CARE_SANDBOX__KIND=docker
+
+# CPU limit (cores). Float; passed as the `--cpus` argument to
+# DockerSandboxBackend.
+# CARE_SANDBOX__CPU_LIMIT=2.0
+
+# Memory limit. Docker-style suffix: `512k`, `512m`, `1g`, etc.
+# CARE_SANDBOX__MEM_LIMIT=1g
+
+# Network policy. `none` = isolated; `skill_declared` = allow the
+# domains the AgentSkill manifest lists; `open` = unrestricted.
+# CARE_SANDBOX__NETWORK_POLICY=skill_declared
+
+# Container image (only consulted by DockerSandboxBackend).
+# CARE_SANDBOX__IMAGE=python:3.12-slim
+
+# `--pids-limit` for the container.
+# CARE_SANDBOX__PIDS_LIMIT=256
+
+# ---------------------------------------------------------------------------
+# [tools] — Tools: user `@carl_tool` registry + bundled builtins + synthesis
+# ---------------------------------------------------------------------------
+
+# Directory the loader scans for `*.py` files with
+# `@carl_tool`-decorated callables.
+# CARE_TOOLS__PATH=~/.config/care/tools
+
+# Optional tag whitelist — only tools whose
+# `@carl_tool(tags=[...])` intersect this set get registered.
+# Env vars don't support lists natively; use TOML for this.
+# (Setting it via env will be parsed as a single-item list.)
+# CARE_TOOLS__TAG_FILTER=
+
+# Optional prefix prepended to every registered tool name. Handy
+# when sourcing third-party tools so they don't collide with
+# built-ins.
+# CARE_TOOLS__NAME_PREFIX=
+
+# --- Bundled standard tools (see care.builtin_tools) ---
+
+# Register CARE's bundled tools (web_search, fetch_url, http_request,
+# calculator, current_datetime, run_python) into every execution context so
+# MAGE-generated chains that reference them actually run. Set false for a
+# bring-your-own-tools deployment.
+# CARE_TOOLS__ENABLE_BUILTINS=true
+
+# Backend for the bundled web_search tool. One of: tavily, serpapi, brave.
+# CARE_TOOLS__WEB_SEARCH_PROVIDER=tavily
+
+# API key for the web_search provider. Without it web_search stays
+# registered but inert (returns a "not configured" line, never raises).
+# Tavily keys look like `tvly-...`. REQUIRED for live web search.
+# CARE_TOOLS__WEB_SEARCH_API_KEY=
+
+# How many results web_search returns per call (1–20).
+# CARE_TOOLS__WEB_SEARCH_MAX_RESULTS=5
+
+# Character cap on text returned by fetch_url / http_request / run_python —
+# keeps one page from blowing the downstream LLM step's context (200–200000).
+# CARE_TOOLS__FETCH_URL_MAX_CHARS=4000
+
+# Register the run_python builtin (runs in the [sandbox] Docker sandbox,
+# never in CARE's process). Set false to drop the code-exec surface while
+# keeping the web/http tools.
+# CARE_TOOLS__ENABLE_CODE_EXEC=true
+
+# Wall-clock seconds a single run_python sandbox call may run (5–600).
+# CARE_TOOLS__CODE_EXEC_TIMEOUT=60
+
+# --- On-the-fly tool synthesis (see care.tool_synthesis) ---
+
+# Self-healing synthesis: before a generated chain runs, scan it for tool
+# steps whose tool_name isn't registered and have the LLM write + register
+# a sandboxed implementation. Requires ENABLE_CODE_EXEC.
+# CARE_TOOLS__AUTO_SYNTHESIZE_TOOLS=true
+
+# Disk cache for synthesised tools (one <name>.json each; re-registered +
+# advertised to MAGE every run, so a tool is generated once and reused).
+# CARE_TOOLS__SYNTHESIZED_TOOLS_PATH=~/.config/care/synthesized_tools
+
+# Also persist each synthesised tool to GigaEvo Memory (as an agent_skill)
+# and check Memory for an existing impl before generating. Best-effort — a
+# Memory outage never blocks a run.
+# CARE_TOOLS__SAVE_SYNTHESIZED_TO_MEMORY=true
+
+# At generation time, search Memory for previously-saved tools relevant to
+# the task and advertise them to MAGE (so a tool from an earlier session is
+# reused by name, not re-invented). Best-effort.
+# CARE_TOOLS__RECALL_TOOLS_FROM_MEMORY=true
+
+# Before running an all-LLM chain, ask the model whether any step needs
+# live/external data (date, weather, news, prices, web facts) and rewrite it
+# into a tool call if so — the "google anything" routing.
+# CARE_TOOLS__ROUTE_LIVE_DATA_TO_TOOLS=true
+
+# Before synthesising a missing tool, web_search for a REAL keyless public
+# API and feed it into codegen — so the tool hits a live endpoint instead of
+# one the LLM guessed. Needs WEB_SEARCH_API_KEY; degrades to ungrounded.
+# CARE_TOOLS__GROUND_SYNTHESIS_WITH_WEB_SEARCH=true
+
+# After synthesising a tool, run it once with the model's own sample inputs;
+# on a runtime error (e.g. wrong endpoint) regenerate once with the failure
+# fed back. Costs one extra sandbox run per newly-synthesised tool.
+# CARE_TOOLS__SELF_TEST_SYNTHESIZED_TOOLS=true
+
+# ---------------------------------------------------------------------------
+# [telemetry] — Opt-in event-stream recording
+# ---------------------------------------------------------------------------
+
+# Master switch. Defaults to `false`; flip to `true` to ship
+# generation/run/evolution events to the configured backend.
+# CARE_TELEMETRY__ENABLED=false
+
+# Backend identifier. Built-ins: `null` (no-op, for debugging the
+# pipeline without a remote sink), `langfuse`. Custom backends
+# register via `care.runtime.register_telemetry_backend()`.
+# CARE_TELEMETRY__BACKEND=null
+
+# Langfuse host. Defaults to Langfuse cloud; point at a self-
+# hosted deployment for on-prem.
+# CARE_TELEMETRY__HOST=https://cloud.langfuse.com
+
+# Langfuse public + secret keys. Required only when
+# `backend=langfuse` and `enabled=true`.
+# CARE_TELEMETRY__PUBLIC_KEY=
+# CARE_TELEMETRY__SECRET_KEY=
+
+# ---------------------------------------------------------------------------
+# [defaults] — UI defaults
+# ---------------------------------------------------------------------------
+
+# TUI language. Currently `en` or `ru`.
+# CARE_DEFAULTS__LANGUAGE=en
+
+# How many entries the history widgets retain. 1–10000.
+# CARE_DEFAULTS__MAX_HISTORY_ENTRIES=50
+
+# ---------------------------------------------------------------------------
+# [chat] — ChatScreen (the primary chat surface)
+# ---------------------------------------------------------------------------
+
+# Which mode the chat boots into.
+#   ad_hoc      — generate-and-execute on the spot, ReAct-style loop.
+#                 Nothing is persisted to Memory.
+#   production  — generate, save to Memory under a stable chain_id,
+#                 seed a dataset card, and (when Platform is wired)
+#                 kick off evolution.
+# Accepted aliases: ad-hoc / adhoc / prod. Default: ad_hoc.
+# CARE_CHAT__DEFAULT_MODE=ad_hoc
+
+# ── Context / memory (CARE.md + CARL LTM) ────────────────────────────────
+# Persistent user/project context (CARE.md) injected into generation, plus
+# CARL's long-term memory injected into every answer + planner prompt.
+# CARE_CONTEXT__ENABLED=true
+# CARE_CONTEXT__GLOBAL_PATH=~/.config/care/CARE.md
+# CARE_CONTEXT__PROJECT_FILENAME=CARE.md
+# CARE_CONTEXT__MAX_CHARS=8000
+# Post-turn: extract durable user facts into CARE.md (one extra LLM call).
+# CARE_CONTEXT__AUTO_LEARN_FACTS=false
+# CARL long-term memory: attach + inject + post-turn save-decision.
+# CARE_CONTEXT__LTM_ENABLED=true
+# CARE_CONTEXT__LTM_DIR=~/.config/care/ltm
+# CARE_CONTEXT__LTM_SESSION_ID=default
+# CARE_CONTEXT__LTM_INJECT_MAX_CHARS=2000
+# CARE_CONTEXT__LTM_AUTOSAVE=true
+
+# ── Artifacts (P6.5) ─────────────────────────────────────────────────────
+# Root directory for files a chain/skill produces (.pptx/.xlsx/.docx/…).
+# Unset → defaults to ~/.care/artifacts (cross-platform, under your home).
+# Each saved file is surfaced in the TUI as a `📄 saved: <path>` line.
+# CARE_ARTIFACTS__DIR=~/.care/artifacts

maestro_care-0.0.1/.gitignore

@@ -0,0 +1,43 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Environment files
+deploy/.env
+.env
+
+# Docker
+docker-compose.override.yml
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache
+
+# OS
+.DS_Store
+Thumbs.db
+uv.lock
+.claude
+logs/*
+!logs/.gitkeep

maestro_care-0.0.1/Makefile

@@ -0,0 +1,49 @@
+.PHONY: run sync help test lint
+
+LOG_DIR := logs
+TIMESTAMP := $(shell date +%Y%m%d-%H%M%S)
+UI_LOG := $(LOG_DIR)/care-ui-$(TIMESTAMP).log
+APP_LOG := $(LOG_DIR)/care-app-$(TIMESTAMP).log
+
+# `make run` launches the TUI. Pass `LOG=1` to also capture
+# debug logs to `./logs`:
+#
+#   * care-ui-<timestamp>.log   — Textual UI events (compose,
+#                                 mount, dispatch, render)
+#                                 driven by TEXTUAL_LOG.
+#   * care-app-<timestamp>.log  — Python app/client log
+#                                 (care.* modules, httpx Memory
+#                                 / Platform calls, MAGE / CARL
+#                                 workers) driven by CARE_LOG_FILE
+#                                 / CARE_LOG_LEVEL.
+#
+# Pass `LOG_LEVEL=DEBUG` to widen the app-log channel (default INFO).
+# `PYTHONIOENCODING=utf-8` keeps non-ASCII output safe when LC_*
+# is unset or set to `C`.
+LOG_LEVEL ?= INFO
+
+run: sync
+ifeq ($(LOG),1)
+	@mkdir -p $(LOG_DIR)
+	@echo "UI  log -> $(UI_LOG)"
+	@echo "App log -> $(APP_LOG) (level=$(LOG_LEVEL))"
+	PYTHONIOENCODING=utf-8 \
+	TEXTUAL_LOG=$(UI_LOG) \
+	CARE_LOG_FILE=$(APP_LOG) \
+	CARE_LOG_LEVEL=$(LOG_LEVEL) \
+	uv run care
+else
+	PYTHONIOENCODING=utf-8 uv run care
+endif
+
+sync:
+	uv sync
+
+help:
+	uv run care --help
+
+test:
+	uv run pytest
+
+lint:
+	uv run ruff check .

maestro_care-0.0.1/PKG-INFO

@@ -0,0 +1,263 @@
+Metadata-Version: 2.4
+Name: maestro-care
+Version: 0.0.1
+Summary: Collaborative Agent Reasoning Ecosystem — Textual TUI demo
+Project-URL: Homepage, https://github.com/AIRI-Institute/care
+Project-URL: Repository, https://github.com/AIRI-Institute/care
+Project-URL: Issues, https://github.com/AIRI-Institute/care/issues
+Keywords: agents,care,carl,evolution,llm,mage,textual,tui
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Terminals
+Requires-Python: >=3.12
+Requires-Dist: gigaevo-client>=0.3.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: mmar-mage>=0.1
+Requires-Dist: pydantic>=2.11
+Requires-Dist: pypdf>=4.0
+Requires-Dist: python-pptx>=0.6.21
+Requires-Dist: rich-pixels>=3.0
+Requires-Dist: textual>=8.2.6
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.20; extra == 'anthropic'
+Provides-Extra: carl
+Requires-Dist: mmar-carl>=0.2; extra == 'carl'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: docker
+Requires-Dist: docker>=7.0; extra == 'docker'
+Provides-Extra: e2b
+Requires-Dist: e2b>=0.17; extra == 'e2b'
+Provides-Extra: full
+Requires-Dist: anthropic>=0.20; extra == 'full'
+Requires-Dist: docker>=7.0; extra == 'full'
+Requires-Dist: e2b>=0.17; extra == 'full'
+Requires-Dist: mmar-carl>=0.2; extra == 'full'
+Requires-Dist: openai>=1.0; extra == 'full'
+Requires-Dist: plotext>=5.2; extra == 'full'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == 'openai'
+Provides-Extra: plots
+Requires-Dist: plotext>=5.2; extra == 'plots'
+Description-Content-Type: text/markdown
+
+# CARE — Collaborative Agent Reasoning Ecosystem
+
+A Textual TUI + CLI for generating, running, and evolving CARL agent
+chains. CARE is the user-facing consumer on top of a four-module stack —
+**MAGE** for chain generation, **CARL** for execution, **GigaEvo Memory**
+for persistence, and **GigaEvo Platform** for evolution.
+
+## Run
+
+```bash
+uv sync
+uv run care init       # one-shot: write a minimal .env with MAGE creds
+uv run care            # launch the TUI
+uv run care --help     # list CLI subcommands
+```
+
+`care init` walks the minimum MAGE credentials (base URL, API key,
+model) and writes a `./.env` so a fresh checkout can boot. Use
+`--non-interactive` with explicit flags for CI / scripted setup:
+`care init --non-interactive --api-key sk-... --base-url ... --model ...`.
+
+The TUI opens directly into the **chat surface** — a Claude-Code-style
+transcript with a prompt at the bottom and a mode toggle above it.
+Type a task in natural language to generate + run an agent chain;
+type a slash command (`/help`, `/mode`, `/library`, `/dataset`,
+`/evolution`, `/tour`, …) for the non-chat affordances. First-time
+users see a one-line offer to type `/tour` for a 5-step walkthrough.
+
+### Chat modes
+
+The toggle above the prompt picks one of two modes; `/mode` switches
+the same setting via the keyboard. Default is **Ad-Hoc** —
+configurable per-deployment with `CARE_CHAT__DEFAULT_MODE`.
+
+| Mode           | What happens on every prompt                                                                                                                                                                                                                                                                         |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Ad-Hoc**     | MAGE generates a chain, CARL runs it on the spot, the answer prints inline. The agent may loop (ReAct) until it decides the task is done. **Nothing is saved.**                                                                                                                                      |
+| **Production** | MAGE generates a _reproducible_ chain, CARE saves it to Memory under a stable `chain_id`, runs one baseline to seed a dataset entry, and (when Platform is wired) kicks off an evolution run. Use `/dataset list <chain_id>` / `/dataset run <chain_id>` / `/evolution watch <run_id>` to follow up. |
+
+Production requires `CARE_MEMORY__BASE_URL` (and `CARE_MEMORY__API_KEY`
+when the deployment enforces auth). Without Memory configured,
+selecting Production auto-falls back to Ad-Hoc with a warning line —
+the toggle's tooltip explains why.
+
+First boot (no `~/.config/care/config.toml` on disk) lands on the
+**Settings** screen so you can configure Memory / Platform base URLs +
+the MAGE LLM credentials before doing anything else. Returning users
+land on the chat surface; `/library` opens the saved-agents table
+(last-run time, favourite status, fitness scores, row-action keys
+below).
+
+## Canonical user flow
+
+Generate Agent A → save it → generate B and C → return to A from the
+library → re-run from the same task + context files → optionally
+evolve A and accept the best individual back into the stable channel.
+
+## Screens
+
+CARE ships **18+ screens** covering the full lifecycle:
+
+| Screen                | Purpose                                          |
+| --------------------- | ------------------------------------------------ |
+| `WelcomeScreen`       | Boot splash + recents sidebar                    |
+| `LibraryScreen`       | Saved-agent table, row actions, search           |
+| `QueryScreen`         | + New agent — task description + context files   |
+| `GenerationScreen`    | Live MAGE progress                               |
+| `InspectionScreen`    | Saved-chain detail + run history                 |
+| `EditAgentScreen`     | Inline edit + Save / Promote-to-stable           |
+| `ExecutionScreen`     | Live CARL run + token streaming                  |
+| `EvolutionScreen`     | GA + Pareto picker + accept-winner               |
+| `ReplayScreen`        | Step through a saved ReasoningResult             |
+| `CatalogScreen`       | Browse installed capabilities (skills/MCP/tools) |
+| `MarketplaceScreen`   | Search shared agent_skill listings on Memory     |
+| `HelpScreen`          | Tutorial + key cheat-sheet                       |
+| `SettingsScreen`      | Edit MAGE / Memory / Platform / theme            |
+| `TaskListDrawer`      | In-flight tasks panel                            |
+| `CommandPaletteModal` | Fuzzy palette over commands + saved entities     |
+| `DiffModal`           | Side-by-side compare two chains                  |
+| `LineageModal`        | Walk a chain's ancestry DAG                      |
+| `ConflictModal`       | Resolve a name collision on save                 |
+
+## Global keys
+
+- `Ctrl+P` — Command palette (search commands + chains + skills)
+- `Ctrl+B` — Task list drawer
+- `Ctrl+K` — Capability catalog
+- `Ctrl+S` — Save current artifact
+- `Ctrl+R` — Re-run current chain
+- `?` — Help (tutorial + every binding)
+- `Esc` — Back / cancel
+- `Ctrl+Q` — Quit
+
+Each screen layers its own bindings — see `?` (Help) for the full set
+filtered by the active screen.
+
+A single-page reference table covering every screen + modal lives at
+[`docs/screens/README.md`](docs/screens/README.md). It maps each
+surface to its slash command + status (M0/M1) + primary purpose so a
+new contributor can locate the right module from one click.
+
+## Demo
+
+A short asciicast walks the three CLI surfaces against a
+hermetic seed directory. Reproduce or re-record with:
+
+```bash
+scripts/record_demo.sh
+```
+
+See [`examples/asciicast/recording_script.md`](examples/asciicast/recording_script.md)
+for the per-act keystroke list. The output lands at
+`docs/asciicasts/care-tour.cast` and can be embedded in this
+README once recorded (`asciinema upload` for a hosted player or
+a local relative link for offline reading).
+
+## Architecture
+
+CARE is the consumer at the top of a four-module stack — see
+[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the layer-by-layer
+walk-through (generation / execution / persistence / evolution) with
+cross-links to the upstream modules and CARE's internal module
+boundaries.
+
+## Configuration
+
+CARE reads its configuration from three sources, in increasing precedence:
+
+1. Defaults baked into `care.config.CareConfig`.
+2. `~/.config/care/config.toml` (user-global TOML).
+3. `./care.toml` in the current working directory (per-project overrides).
+4. `CARE_*` environment variables.
+
+Nested fields use double-underscores in env-var form, mirroring how the
+TOML sections nest. For example, `[mage] mode = "fast"` in TOML is
+`CARE_MAGE__MODE=fast` in the environment.
+
+See [`.env.example`](.env.example) for the complete list of supported
+variables with descriptions and defaults. Copy it to `.env` (or export the
+vars in your shell) and override only what you need.
+
+### Quick reference
+
+| Section     | Env-var prefix      | Purpose                                |
+| ----------- | ------------------- | -------------------------------------- |
+| `mage`      | `CARE_MAGE__*`      | MAGE generator (provider, API key, …)  |
+| `memory`    | `CARE_MEMORY__*`    | GigaEvo Memory connection              |
+| `platform`  | `CARE_PLATFORM__*`  | GigaEvo Platform connection            |
+| `sandbox`   | `CARE_SANDBOX__*`   | AgentSkill sandbox backend + limits    |
+| `tools`     | `CARE_TOOLS__*`     | `@carl_tool` registry + bundled builtins (web_search, …) + on-the-fly synthesis |
+| `telemetry` | `CARE_TELEMETRY__*` | Opt-in event-stream sink (Langfuse, …) |
+| `defaults`  | `CARE_DEFAULTS__*`  | UI defaults (language, history size)   |
+
+## CLI
+
+`care` (no subcommand) launches the TUI. The headless subcommands share
+the `CareConfig` and data layers the TUI uses — every screen's primary
+affordance has a terminal twin.
+
+**Setup**
+
+- `care init [--non-interactive] [--api-key X] [--base-url Y] [--model Z] [--mode ad_hoc|production] [--force]` —
+  one-shot quick-start: writes a minimal `.env` with the four MAGE +
+  chat keys a fresh checkout needs. Refuses to overwrite an existing
+  `.env` without `--force`.
+
+**Discovery & validation**
+
+- `care catalog [--json] [--kind ...]` — list installed AgentSkills,
+  MCP servers, tools, capability memory cards.
+- `care validate <chain.json>` — parse + preflight a CARL chain.
+- `care import <pattern>... [--apply]` — batch-validate (dry-run
+  default) or import chain JSON files.
+
+**Generate / run / replay**
+
+- `care generate "<task>" [--mode fast|deep] [--save NAME] [--output PATH]` —
+  one-shot MAGE generation.
+- `care run <chain_id> [--execute] [--task TEXT] [--input KEY=VAL] [--save-result NAME]` —
+  fetch a saved chain, preflight, and optionally execute via CARL.
+- `care replay <run.json>` — step through a saved
+  `ReasoningResult` / `RunRecord` JSON.
+
+**Memory browse**
+
+- `care memory ls [--entity-type ...] [--tag ...] [--q ...]` —
+  list saved entities.
+- `care memory show <entity_id> [--content-only]` — drill down on
+  a single entity.
+- `care memory history <chain_id>` — list recorded runs for a
+  chain.
+- `care search "<query>" [--search-type bm25|vector|hybrid]` —
+  BM25 / vector / hybrid search across saved entities.
+- `care diff <left_id> <right_id>` — side-by-side chain compare.
+- `care lineage <chain_id>` — walk the ancestry DAG.
+- `care favourite <entity_id> [--off]` — star / unstar a library
+  entity.
+
+**Capabilities & evolution**
+
+- `care marketplace "<query>"` — search shared agent_skill listings.
+- `care evolve <chain_id> [--wait] [--accept]` — submit + watch +
+  accept an evolution run.
+
+**UX**
+
+- `care help [--markdown]` — render the tutorial + cheat-sheet.
+
+Run `care <subcommand> --help` for the full flag set on each.