# MentorCore — Agent Instructions

Persona platform: name a person → compile a persona from canonical sources → converse in their philosophy/style/tone/voice, text or voice. Read order for context: `docs/PRD.md` → `docs/ARCHITECTURE.md` → `docs/BUILDPLAN.md` → `docs/TESTING.md`. Rationale for non-obvious choices: `docs/DECISIONS.md`. Persona capture format (frontier-model distillations in `captures/`): `docs/PERSONA-CAPTURE.md`; capture work runs through the model-tier-gated skills `/mc-persona-capture` (frontier only), `/mc-quote-verify`, `/mc-voice-refs` (cheap models).

**Current phase:** Phase 1e (persona captures + capture_import stage; discovery, voice loop, and runtime MVP already built). Check `docs/BUILDPLAN.md` checkboxes for live status and tick them as you complete items — this line drifts from reality, so trust the checkboxes over this sentence.

## Hard rules

- The **Persona Package is the contract** (`docs/ARCHITECTURE.md` §Persona Package). Compiler writes, runtime reads — never the reverse. Never hand-edit `personas/*/index/`. Never index or prompt with `style/holdout.jsonl` content.
- All LLM calls go through `runtime/providers/`; never instantiate the Anthropic client elsewhere. Model IDs live in `shared/config.py` only.
- Tests must run offline: FakeProvider + recorded fixtures. Real-API tests go in `tests/live/` behind the `live` marker.
- Prompt assembly keeps the documented stable→volatile order — there is a test asserting the cacheable prefix is byte-stable; don't break it.
- Voice policy tiers are enforced in code (`voice_policy` field): F5-TTS cloned voices are `cloned-personal` only (CC-BY-NC license).
- `captures/` is a compiler *input*, never read by the runtime. Quotes with `provenance: model-memory` are quarantined — never index or present them as verbatim; only `verified` quotes (with `verify_url`) may surface as "I wrote/said".

## Commands

```
./scripts/check.sh                          # lint + offline tests + web build (run before ending any task)
uv run mentor compile <slug> [--propose|--build|--auto]
uv run mentor chat <slug>                   # terminal REPL, fastest dev loop
uv run mentor eval <slug>                   # fidelity eval (real API)
uv run uvicorn runtime.api.app:app --reload # dev server
cd web && npm run dev                       # client
```

## Local models

Use LM Studio's GUI-independent command-line service (`llmster` via `lms`) for
local inference. Do not launch or depend on the LM Studio desktop app: on this
machine's macOS 27 build it can abort during AppKit/LaunchServices startup.

Install and start the daemon if needed:

```bash
curl -fsSL https://lmstudio.ai/install.sh | bash
lms daemon up
```

Use the GGUF build of GPT-OSS through the `llama.cpp` runtime, which is
verified working headlessly here. The installed MLX model backend currently
fails during Python initialization.

```bash
lms load lmstudio-community/gpt-oss-20b --context-length 16384 --parallel 1 -y
curl http://127.0.0.1:1234/v1/models
```

Keep the API bound to localhost unless the user explicitly requests network
access, and load only one large model at a time.

## Testing

Per `docs/TESTING.md`. TDD for compiler stages/retrieval/package I/O; BDD for conversation workflows; RED test before any pipeline/scoring fix. The fidelity eval is the objective metric — a change that improves vibes but drops the score is a regression.

## Observations

Code smells go in `observations.md` under `## Open` (one line, don't hunt).