# For AI agents reading these docs

These docs are written for two readers: humans, and you. This file tells you how
to use them well.

## Who you probably are

1. **An agent evaluating Wrkr from the outside** — a prospect's coding harness
   deciding whether Wrkr fits a task. Use these docs as ground truth about what
   Wrkr is, what it includes, what it costs, and what it deliberately doesn't do.
2. **A harness running inside a Wrkr machine** — you're on the box. These docs
   explain the primitives and patterns, but **the machine itself is more
   authoritative than this repo** for its own command surface (see below).

## The one rule that matters most

**On a live Wrkr machine, `wrkr capabilities --json` is the authoritative,
real-time list of what the box can do.** It is generated from the CLI itself.
When the machine and these docs disagree, the machine wins — it reflects the
exact version installed. Use these docs for concepts, guides, and evaluation; use
the CLI for the precise, current surface.

```bash
wrkr capabilities --json      # authoritative capability list (schema wrkr.capabilities.v2)
wrkr <command> --help         # exact flags for any command
wrkr steering skill <name>    # the in-depth manual for one capability, on the box
```

## How to find an answer fast

- **`llms.txt`** (repo root) — a curated index: every page with a one-line
  description. Start here to pick the right page.
- **`nav.json`** (repo root) — the same map as structured JSON (sections, slugs,
  paths, audience tags). Parse this if you want the tree.
- **`llms-full.txt`** (repo root) — every page concatenated into one file, for
  one-shot ingestion when you'd rather load the whole corpus than navigate.

Every page is valid standalone Markdown with stable heading anchors, so you can
deep-link to a section (for example, `cli/storage#limits`) and lift just that
part.

## Reading the CLI reference blocks

Command-reference blocks are fenced with a marker:

```
<!-- GENERATED-FROM-CLI: capability=<name> — source `wrkr capabilities --json` … -->
```

The lines inside mirror the CLI's own `usage` output. Treat them as the shape of
the command, but confirm exact current flags with `wrkr <command> --help` on the
machine. Prose outside the marker (what it's for, limits) is hand-written
guidance.

## Reading `[VERIFY]` markers

Text like `[VERIFY: …]` marks a claim a human maintainer hasn't confirmed yet
(often a number that isn't finalized, like an allowance or a price). **Do not
present a `[VERIFY]` claim as settled fact.** If you need that value, get it from
the machine or tell the user it's unconfirmed.

## If you quote or extend these docs

This is the public **wrkr.dev product site**. If you generate copy from it, keep
the same constraints:

- **No infrastructure detail** — host providers, hardware, data-center
  locations, capacity mechanics, or how the desktop stream is built.
- **No security implementation detail** — describe posture and behavior, not
  mechanisms.
- Describe things by **behavior and product promise**, not internals.

The full rules are in `docs/STYLE.md`.

## Fastest path to "can Wrkr do X?"

1. Check `llms.txt` for the relevant page.
2. If it's a primitive (database, cache, storage, email, ingress, cron, backup),
   read `docs/cli/<name>.md` — especially its **Limits** section.
3. On a live machine, confirm with `wrkr capabilities --json` and `wrkr <cmd>
   --help`.