@kontextmind/kxm/.kxm/README.md

KXM local-first multi-agent orchestration and operator dashboard

# The `.kxm` directory

`.kxm/` holds a KXM project's reviewable definition and its local workspace. You
commit the configuration; logs, restart state and generated files stay on the
machine. This directory is the KXM repository's own project. In your project,
`kxm init` creates the core files: `project.yaml`, `repo/repo.yaml`, two agents,
a `default` workflow, `gates.yaml` and `template-provenance.yaml`.

## Layout

| Path | Contents | Git |
|---|---|---|
| `project.yaml` | Project identity, repositories and defaults (`kxm.project.v1`) | Tracked |
| `repo/repo.yaml` | This repository's definition (`kxm.repository.v1`) | Tracked |
| `agents/`, `models/`, `workflows/` | Agents, model profiles and workflows, one YAML file each | Tracked |
| `gates.yaml` | The executable gate registry | Tracked |
| `roles/`, `routes.yaml`, `prices.yaml` | Role rosters, admitted model routes, dated list prices | Tracked |
| `template-provenance.yaml` | Hashes of the template `kxm init` used | Tracked |
| `models/inventory.yaml` | The discovered model catalog | Generated; track it for a reviewed snapshot |
| `config.yaml` | Shared personalization settings | Tracked if the project shares them |
| `memory/` | Project memory facts that `kxm memory` projects into `AGENTS.md`, `CLAUDE.md` and `GEMINI.md` | Tracked |
| `knowledge/` | Authored project wiki. The hub-compiled view, when written, is `knowledge/wiki/` | Tracked |
| `assets/` | Intentional workflow inputs and outputs; `assets/generated/` is for machine output | Tracked intentionally; `generated/` ignored |
| `tasks/` | Task records from `kxm task` | Your choice |
| `logs/` | Hub, worker and agent logs | Ignored |
| `state/` | The hub database `kxm.db`, Pi sessions and restart state | Ignored |
| `run/` | SSH control sockets from `kxm ssh` | Ignored |

The role files under `.kxm/roles/` and the model files under `.kxm/models/`
carry the developer policy. The assignment runner reads them at one commit
(`HEAD`, which must be an ancestor of `refs/remotes/origin/main`). A rename
does not rewrite a commit that still uses the old ids. An old id resolves
only when that id is absent and the other side is present.

Ids in this checkout follow one convention per kind:

| Kind | Convention | This checkout |
|---|---|---|
| Role | The purpose: `planner`, `writer`, `reviewer-arch`, `reviewer-cli` | Unchanged |
| Agent | The same id as its `role` | `planner`, `writer`, `reviewer-arch`, `reviewer-cli` |
| Route | `<harness>-<model-slug>[-<provider>]`, with `.` written as `-` | `grok-grok-4-7`, `claude-fable`, `pi-qwen3-7-plus-openrouter` |
| Workflow | `default`, `land`, or `<role>-only` | `default`, `land`, `writer-only`, `reviewer-arch-only`, `reviewer-cli-only` |
| Agent step | The agent's role id | `writer`, `reviewer-arch`, `reviewer-cli` |

`coordinator`, `implementer`, `critic-arch`, and `critic-cli` are aliases of
the agent ids. `implement`, `review-arch`, and `review-cli` are aliases of
the step ids. Route aliases include `grok-native`, `fable-claude`, and
`sol-codex`. Using an alias prints `kxm: deprecated <kind> id '<from>' resolves to '<to>'`.
`opus-claude` does not resolve to another model.

The [configuration reference](../docs/reference/config-reference.md#workspace-layout-tracked-ignored-and-state)
describes every file, the ignore rules to add, and the state KXM keeps outside
the project.

## Rules

- **No secrets here.** Keep tokens, webhook secrets and credentials in
  environment variables or a secret manager. Never commit logs, SQLite files, or
  raw prompts.
- **YAML only.** JSON definitions in a `config/` subdirectory are a retired
  format: their presence makes the project refuse to load with
  `legacy_state_unsupported`. The hub may create an empty `config/` directory;
  that alone is harmless.
- **Moving the workspace.** `KXM_WORKSPACE_DIR`, `KXM_LOGS_DIR`,
  `KXM_ASSETS_DIR` and `KXM_STATE_DIR` relocate `logs/`, `assets/` and
  `state/`. The configuration files always stay in `<project root>/.kxm/`.