> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sovara-labs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Lessons

> Read and manage Sovara lessons from the CLI.

Lessons are reusable instructions, domain facts, and operating rules that
Sovara can retrieve for future agent runs.

Every `sovara lessons` subcommand requires `--project-id` (or `--proj-id`). The
selector accepts a full project ID, an unambiguous ID prefix, or an exact
project name. Examples below use a shell variable to keep commands readable:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
PROJECT=support-agent
```

## List and read lessons

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara lessons list --project-id "$PROJECT"
sovara lessons list --project-id "$PROJECT" --path "support/refunds/"
sovara lessons get <lesson-id> --project-id "$PROJECT"
```

`ls` is the folder-oriented view:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara lessons ls --project-id "$PROJECT" "support/refunds/"
```

## Query lessons for context

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara lessons query --project-id "$PROJECT" --path "support/refunds/"
sovara lessons retrieve --project-id "$PROJECT" "Customer asks for a refund exception"
```

Use `query` to render lessons in a folder. Use `retrieve` to see which lessons
match concrete agent context.

## Create a lesson

Creation requires a title, content, and retrieval-oriented usage hint:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara lessons create \
  --project-id "$PROJECT" \
  --title "Retry rate-limited provider calls" \
  --content "When an upstream API returns HTTP 429, retry with exponential backoff and jitter." \
  --when-to-use "When a provider request fails because of rate limiting" \
  --path "reliability/providers/" \
  --run-id "<full-run-uuid>"
```

Use the full run UUID when a lesson comes from a specific run.

## Improve a lesson

Ask for a non-mutating wording proposal:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara lessons polish <lesson-id> --project-id "$PROJECT"
```

Apply an update:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara lessons update <lesson-id> \
  --project-id "$PROJECT" \
  --content "Retry HTTP 429 responses with exponential backoff and jitter." \
  --run-id "<full-run-uuid>"
```

## Manage folders

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara lessons mkdir "support/refunds/" --project-id "$PROJECT"
sovara lessons mv -i <lesson-id> "support/refunds/" --project-id "$PROJECT"
sovara lessons cp "support/refunds/" "support/escalations/" --project-id "$PROJECT"
```

Use restructure commands only when intentionally reorganizing a larger lesson
taxonomy. Pass the same explicit project selector to every command.