# Agent Docs Maintenance

Rules for maintaining the Mithril CLI agent documentation.

## 1. Scope & Exclusions

### Audience

These docs are for **Mithril CLI users**, not general SkyPilot users. Keep focus on Mithril-specific workflows.

### Do not document

#### Global SkyPilot config for `limit_price`

Do not include `~/.sky/config.yaml` as an option for setting limit_price:

```yaml
# DO NOT DOCUMENT THIS
mithril:
  limit_price: 8.0
```

Only document the task YAML `config` block:

```yaml
# DOCUMENT THIS
config:
  mithril:
    limit_price: 8.0
```

Reason: Users should set limit_price per-task, not globally. Global config is a SkyPilot detail that adds confusion.

#### `use_spot` / `--use-spot`

These are SkyPilot concepts that don't apply to Mithril. All Mithril compute is spot — the only user-facing knob is `limit_price`. Do not reference `use_spot` or `--use-spot` anywhere in docs.

## 2. Content Model

Domain concepts that shape every page.

### Two provisioning paths

Mithril has two ways to get compute. Docs must make the distinction clear without confusing users.

| Path | Command | Persona | Mental model |
|------|---------|---------|-------------|
| **Launch** | `ml launch` | ML practitioner | "I have code, I need GPUs to run it" |
| **Instances** | `ml instance create` | Platform/infra engineer | "I need GPU VMs to build infrastructure" |

### `ml exec` is the iteration companion to `ml launch`

- **In launch docs**: present exec as the natural next step — "iterate on the launched cluster." Don't bury it; link to the exec doc from the launch overview.
- **Decision rule**: exec when only your code changed, launch when setup or resources changed.
- **Don't call it "running commands"**: that's too generic and doesn't convey why exec exists. The value is *fast iteration on an already-running cluster*.

### YAML is primary, CLI flags are overrides

YAML task files are the primary way to specify task parameters. CLI flags exist to override YAML fields at launch time. Don't present CLI flags and YAML as parallel "modes" — document YAML fields as the source of truth and annotate each field with its CLI override flag (e.g., a `CLI override` column in reference tables).

## 3. Information Architecture

Where content lives and how to avoid drift.

### Organize by workflow, not by interface

Top-level sections should reflect what users are *doing* (launch, manage clusters, manage volumes), not which interface they're using (CLI vs SDK vs YAML). A user thinks "I want to launch something," not "I want to use the CLI."

### Single source of truth

- Cross-cutting concepts (spot bidding, preemption lifecycle, pricing) live in `concepts/` at the docs root. In command-specific docs, show only the mechanics of that command (flags, YAML fields) and link to the canonical doc with `→ [Title](../concepts/<file>.md)`.
- Workflow docs should show only the most common flags inline. Repeating the same table in multiple places creates drift.

### Keep reference pages focused and split

Prefer multiple short reference pages (one per topic: task spec, resources, file mounts) over a single merged page. Users scan for a specific field — smaller pages are faster to search.

## 4. Writing Style

Voice, framing, and formatting rules.

### General principles

- Keep docs concise and scannable
- Use tables for reference material
- Include practical examples
- Focus on common workflows, not edge cases

### Framing rules

- **Frame by intent, not command**: section names/headers should signal purpose ("Run Code on GPUs" vs "Manage GPU Infrastructure"), not just CLI syntax.
- **Describe intent, not mechanics**: prefer "iterate on the launched cluster" over "submit a new job without re-provisioning." Users care about what they can *do*, not what the system skips internally.
- **Avoid infrastructure jargon**: terms like "provisioning" or "re-provisioning" are opaque to many ML users. Use plain language: "without waiting for setup," "without the full launch cycle."
- **Neither provisioning path is second-class**: both are legitimate tools for different jobs. Don't frame instances as "advanced" — frame them as "different purpose."
- **Keep `ml launch` as the default path**: quickstart channels users to `ml launch`. That's correct — it's the right choice for most ML users.

### Linking & context

- **Always link cross-section references.** If section A mentions a command documented in section B, make it a clickable link. A bare `ml exec` with no link is a dead end.
- **Link related commands to the reader's current context.** If the reader just learned about `ml launch`, describe `ml exec` relative to launch — not in the abstract.
