# Framework Model — Layout, Tiers, and Where the Answers Live
Generated by `tm generate capabilities` from the harness's own path constants and tier resolvers (`core::paths::FrameworkPaths`, `core::delegation_authority::deployed_agent_dirs_from`, `core::skill_deploy_tiers::skill_deploy_tiers`, `core::harness_root`). Nothing here is restated by hand: move a directory or reorder a tier and this file drifts, failing `scripts/check_capabilities.sh`. Paths are shown against `~` because the real layout is home-relative.
## Install Layout
| Path | What lives there |
|---|---|
| `~/.trusty-mpm` | Framework install root. |
| `~/.trusty-mpm/framework` | tm-owned, auto-materialised bundled tree. Never hand-edit — `tm install` and session prep overwrite it. |
| `~/.trusty-mpm/framework/agents` | Bundled agent SOURCE files (pre-composition). |
| `~/.trusty-mpm/framework/skills` | Bundled skill SOURCE files, re-materialised whenever the binary's embedded bundle fingerprint changes. |
| `~/.trusty-mpm/skills` | USER-authored skill source. Sits outside `framework/` precisely because that tree is overwritten. Deployed into every session, outranking a same-named bundled skill. |
| `~/.trusty-mpm/framework/hooks` | Optimizer / overseer hook policy. |
| `~/.trusty-mpm/framework/instructions` | Framework instruction assets. The prompt a session actually ran with is NOT here — it is per-session (see below). |
| `~/.trusty-mpm/registry` | Shared project registry. |
| `~/.trusty-tools/trusty-mpm/claude-config` | The tm-managed `CLAUDE_CONFIG_DIR` (see below). |
| `~/.claude` | The operator's OWN Claude Code install. tm reads it as the lowest agent tier and never writes framework-owned agents into it. |
## Why `CLAUDE_CONFIG_DIR` Is Relocated
Managed sessions launch `claude` with `CLAUDE_CONFIG_DIR` pointed at `~/.trusty-tools/trusty-mpm/claude-config`, not the operator's `~/.claude`. Two things follow. Framework-owned agents and skills land in a tm-controlled directory, so they cannot contaminate — or be contaminated by — a Claude Code install the operator maintains for their own use. And because the relocated directory is global rather than per-workspace, one roster serves every session instead of each project carrying a mutable copy that can silently shadow the real agent.
A session that has this variable set is reading the managed tier. A session that does not is reading the operator's own.
## Agent Tier Precedence
Highest precedence first — on a name collision the earlier tier wins, case-insensitively. Rendered from `deployed_agent_dirs_from`, the same function the runtime resolves against.
1. `<project>/.claude/agents` — Hand-placed and project-custom agents only. tm does not deploy bundled agents here.
2. `~/.trusty-tools/trusty-mpm/claude-config/agents` — Where every BUNDLED agent deploys. The `CLAUDE_CONFIG_DIR` env var overrides this path when set.
3. `~/.claude/agents` — The operator's own Claude Code agents. Read, never written by tm.
There is no `~/.trusty-mpm/agents/` tier. No code reads that path; a copy placed there is loaded by nothing.
## Skill Deploy Tiers
Skills, unlike agents, have no single destination — a bundled skill is deployed into each of these independently, so one can be stale while another is current. Rendered from `skill_deploy_tiers`.
| Tier | Directory |
|---|---|
| managed config | `~/.trusty-tools/trusty-mpm/claude-config/skills` |
| operator home | `~/.claude/skills` |
| project | `<project>/.claude/skills` |
Source precedence when the same skill name exists in more than one source: project-custom, then user-custom (`~/.trusty-mpm/skills/`), then bundled. A deployed skill you hand-edit is frozen — its checksum no longer matches, so redeploy skips it rather than overwriting your edit. A skill whose slug contains `mcp` is never deployed; it would shadow Claude Code's built-in `/mcp`.
## Per-Session State
Session records live under `<project>/.trusty-mpm/sessions/<session-id>`, and the prompt a session was actually launched with is `INSTRUCTIONS-COMPILED.md` inside it. Both are keyed by session id, so two concurrent sessions in one project cannot overwrite each other.
The `<project>` here is the checkout that OWNS the project — the main checkout, never one of its git worktrees. Harness state belongs to the project; a worktree carries only code.
## Authoritative Documentation
This catalog answers layout and tier questions. Design rationale, behaviour contracts, and operational procedure live in documents — but only some of them travel with the installed binary.
### Ships in the published crate
- `crates/trusty-mpm/docs/ARCHITECTURE-MEMORY-SESSIONS-SEARCH.md`
- `crates/trusty-mpm/docs/WHAT-IS-TRUSTY-MPM.md`
- `crates/trusty-mpm/README.md`, `crates/trusty-mpm/CHANGELOG.md`
### Repo-only — NOT in the published crate
`cargo package` includes only files under `crates/trusty-mpm/`, so everything below requires a checkout of `github.com/bobmatnyc/trusty-tools`. A session running against an installed binary alone cannot open these.
| Path | Holds | Present in this checkout |
|---|---|---|
| `docs/adr/INDEX.md` | Index of every architecture decision record — the ADR is the authority on why a mechanism is shaped the way it is. | yes |
| `docs/specs/README.md` | Index of the numbered DOC-* specs (behaviour contracts). A spec, not an ADR, is what a source file's `# Spec References` block links back to. | yes |
| `docs/reference/` | Operational reference: release workflow, worktree discipline, SLOC cap, environment variables, threat model. | yes |
| `docs/SUMMARY.md` | mdBook table of contents spanning every crate's docs. | yes |
## Resolving Live State
This file describes the layout a correct install has. To learn what THIS machine actually resolved, run one of these rather than guessing — the `about` text is pulled from the CLI itself.
- `tm doctor` — Whether each tier is actually populated on this machine, and which check failed.
- CLI: Run a full system diagnostic of the trusty-mpm stack
- `tm sessions instructions` — The composed prompt this project's session would receive, verbatim — the ground truth when the prompt and this catalog disagree.
- CLI: Print the composed launch instructions a session would receive
- `tm install` — Re-materialise the bundled agent/skill/hook artifacts into the layout above.
- CLI: Install the bundled framework artifacts to `~/.trusty-mpm/framework/`
When the compiled prompt and this catalog disagree about a path, the prompt is the thing the session is actually obeying and this catalog is the thing derived from code. Report the disagreement; do not silently pick one.