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

# Your first assessment

> What session start hands your agent, how to work inside it, and how to finish.

Everything an assessment is allowed to do is enumerated in one place: the **session
context**. The agent does not invent scope, quota, workspace, or cloud state — it asks
the CLI and works inside the answer.

## Start a session

```bash theme={null}
myrqen --json session start --effort auto --agent "claude-code" --model "claude-opus-5"
```

Or use the effort shorthand, which is the same thing:

```bash theme={null}
myrqen auto        # also: low, high, xhigh, ultra
```

Useful flags on start:

| Flag                  | Purpose                                                       |
| --------------------- | ------------------------------------------------------------- |
| `--sync yes\|no\|ask` | Answer the sync question up front. Default `ask`.             |
| `--workspace <id>`    | Bind this repository to an explicit workspace. Never guessed. |
| `--agent <name>`      | Host agent name, recorded on the report.                      |
| `--agent-version <v>` | Host agent version.                                           |
| `--model <model>`     | Host model identifier, when the agent can report it.          |

## What comes back

The context is authoritative. Its shape is `SessionContext` in
`packages/contracts/src/agent-protocol.ts`:

```json theme={null}
{
  "contextVersion": 1,
  "localReportId": "rpt_…",
  "sessionDir": "/path/to/project/.myrqen/sessions/rpt_…",
  "repositoryRoot": "/path/to/project",
  "project": { "name": "…", "workspaceKind": "personal", "bindingSource": "unbound" },
  "effort": { "requested": "auto", "resolved": "high", "profile": { … }, "rationale": ["…"] },
  "scope": {
    "localTargetPatterns": ["http://127.0.0.1:*", "http://localhost:*", "http://[::1]:*"],
    "discoveredLocalTargets": ["…"],
    "authorizedExternalTargets": [],
    "pendingExternalCandidates": ["https://api.example.com"]
  },
  "policy": {
    "destructiveActionsAllowed": false,
    "prohibitedActions": ["…"],
    "externalTargetsRequireExactAuthorization": true,
    "uploadFullRepository": false,
    "untrustedContentRule": "…"
  },
  "stack": { "languages": [], "frameworks": [], "packageManagers": [], "services": [] },
  "artifacts": {
    "sessionFile": "…/session.json",
    "reportJson": "…/report.json",
    "reportHtml": "…/report.html",
    "reportMarkdown": "…/report.md",
    "reportSarif": "…/report.sarif.json"
  },
  "cloud": { "state": "not_requested", "reason": "…" },
  "staticPass": { "filesParsed": 0, "rulesRun": 0, "durationMs": 0, "candidatesRecorded": 0, "notAssessed": [] },
  "nextSteps": ["…"]
}
```

Three parts deserve attention on a first read.

<AccordionGroup>
  <Accordion title="effort — resolved, with a rationale">
    `auto` inspects source size, route count, detected authentication and roles, database
    access, upload surfaces, server-side fetches, payment integrations, and referenced
    external origins, then resolves to `low`, `high`, `xhigh`, or `ultra`. Both the
    requested and the resolved value are recorded, so runs stay comparable. See
    [Effort modes](/concepts/effort-modes).
  </Accordion>

  <Accordion title="scope — what is already in bounds, and what is not">
    Loopback origins are the normal target class and need no prompt.
    `pendingExternalCandidates` are origins the project references that are **not**
    authorized. Each needs an explicit, exact-origin grant before a single request goes
    to it. See [Authorization and safety](/concepts/authorization-and-safety).
  </Accordion>

  <Accordion title="staticPass — claims, not findings">
    `session start` runs Myrqen's own static analysis before it hands over the session.
    `candidatesRecorded` is how many claims it filed; `notAssessed` is what it could not
    see. The agent's first job is to settle each candidate against the running
    application.
  </Accordion>
</AccordionGroup>

## The sync question

If this scan can sync, the CLI asks once, in an interactive terminal:

```
Sync this report to Myrqen for live progress and sharing? [Y/n]
```

An agent has no terminal, so the CLI does not guess. `cloud.state` comes back as
`decision_required`, the agent asks the user in those words, and records the answer:

```bash theme={null}
myrqen --json session sync-decision yes    # or: no
```

If `cloud.state` is `quota_blocked`, do not ask — the question could not succeed. Say the
scan will stay local and continue.

## Work the phases

```bash theme={null}
myrqen phase start discovery
myrqen phase complete discovery
```

The eight phases, in order:

`preflight` · `scope` · `discovery` · `source_review` · `runtime_validation` ·
`access_control` · `validation` · `reporting`

What each one means is in
[`references/METHODOLOGY.md`](https://github.com/stijnswapped/Myrqen/blob/main/packages/skill/myrqen/references/METHODOLOGY.md)
inside the Agent Skill, and summarised in [Scan lifecycle](/concepts/scan-lifecycle).

## Settle the static candidates

```bash theme={null}
myrqen --json finding verify MYR-001 \
  --description "As user_a, GET /api/orders/102 returned HTTP 200 with userId 2." \
  --location "GET /api/orders/102"

myrqen --json finding refute MYR-002 \
  --reason "The lookup is scoped by session in middleware the static pass could not follow; the cross-account request returns 404."
```

Verifying attaches the observation and raises verification to `verified`. Refuting keeps
the finding, labels it a false positive, and records why — a reader can disagree with
that, which they cannot do with something silently deleted.

<Warning>
  Do not resubmit a candidate to confirm it. A resubmission only merges when the summary
  matches the original word for word, so in practice it produces the same issue twice.
</Warning>

## Submit what the static pass missed

One finding per root cause, as JSON on stdin:

```bash theme={null}
echo '{ … }' | myrqen --json finding submit
myrqen --json finding submit --file finding.json
```

The contract is in [Finding schema](/reference/finding-schema). Exit code `2` means the
submission was rejected, and the output says exactly what to fix.

## Record coverage and metrics honestly

```bash theme={null}
myrqen note coverage "Cross-account object access compared with two test identities." --area "Object-level authorization"
myrqen note limitation "No admin identity was available, so role separation was not tested." --area "Role separation"
myrqen metrics token --source estimated --count 412000 --estimator transcript-v1
```

Use `--source unavailable` when token usage cannot be measured. Never state an exact
count that did not come from the host.

## Finish

```bash theme={null}
myrqen --json session finish
```

This validates every finding, writes the local HTML, JSON, Markdown, and SARIF reports,
and syncs only if this scan opted in. `myrqen session cancel` finishes early and keeps
whatever was validated so far.

## Next

<CardGroup cols={2}>
  <Card title="Findings" icon="magnifying-glass" href="/concepts/findings">
    Severity versus verification, deduplication, and redaction.
  </Card>

  <Card title="Reports" icon="file-lines" href="/concepts/reports">
    The four formats, and what a projection does and does not include.
  </Card>
</CardGroup>