---
type: "TechArticle"
softwareVersion: "1.0.0"
url: "https://registry.docsloth.dev/components/tutorial.html"
markdown: "https://registry.docsloth.dev/docs/tutorial.md"
component: "tutorial"
section: "connected"
trust_class: "connected"
implementation_status: "implemented_native"
renderer: "native block"
install: "docsloth component add @docsloth/tutorial@1.0.0"
spec: "packages/contracts/component-specs/tutorial.md"
props_schema: "packages/contracts/component-props/tutorial.schema.json"
---

> Index: [Agent index](https://registry.docsloth.dev/llms.txt)

# tutorial

Verified multistep task tutorial

| Field | Value |
| --- | --- |
| Trust class | connected |
| Implementation status | implemented_native |
| Renderer | native block |
| Key prop (production schema) | workflow_id |
| Key prop (protocol fixture) | workflowId |
| Tools | next, verify, reset |
| Package version | 1.0.0 |
| Package digest | sha256:d8935cd3b71884c7b5704305752a4a464fcd43a97e37e08aaeefbed5bc7897d2 |

## Install

```sh
docsloth component add @docsloth/tutorial@1.0.0
```

Live package: sha256:d8935cd3b71884c7b5704305752a4a464fcd43a97e37e08aaeefbed5bc7897d2 with 2 file digest(s); the catalog entry is generated from the built package, not a placeholder.

## Props

The prop schema is normative in `packages/contracts/component-props/tutorial.schema.json`.

| Prop | Type | Required | Constraints |
| --- | --- | --- | --- |
| `title` | string | no | maxLength: 160 |
| `workflow_id` | string | yes | maxLength: 256 |
| `steps` | array<object> | yes |  |
| `resource` | object | no | additionalProperties: false |
| `resource.resource_id` | string | yes | format: uuid |
| `resource.operation` | string | yes | maxLength: 160 |
| `resource.environment` | "test" \| "staging" \| "production" | yes |  |
| `persist_progress` | boolean | yes |  |

Example props generated from this schema:

```json
{
  "title": "example-title",
  "workflow_id": "example-workflow_id",
  "steps": [
    {
      "id": "example-id",
      "title": "example-title",
      "block_ids": [
        "00000000-0000-4000-8000-000000000000"
      ],
      "check_id": "example-check_id",
      "required": true
    }
  ],
  "resource": {
    "resource_id": "00000000-0000-4000-8000-000000000000",
    "operation": "example-operation",
    "environment": "test"
  },
  "persist_progress": true
}
```

Required props: workflow_id, steps, persist_progress.

## Example

Example document IR (the block the renderer consumes):

```json
{
  "type": "tutorial",
  "props": {
    "title": "example-title",
    "workflow_id": "example-workflow_id",
    "steps": [
      {
        "id": "example-id",
        "title": "example-title",
        "block_ids": [
          "00000000-0000-4000-8000-000000000000"
        ],
        "check_id": "example-check_id",
        "required": true
      }
    ],
    "resource": {
      "resource_id": "00000000-0000-4000-8000-000000000000",
      "operation": "example-operation",
      "environment": "test"
    },
    "persist_progress": true
  }
}
```

Renderer HTML (entities decoded and wrapped for display):

```html
<section class="ds-block ds-tutorial" data-component="tutorial" aria-labelledby="b-title">
<h3 class="ds-block-title" id="b-title">example-title</h3>
<ol class="ds-list">
<li>
<strong>example-title</strong> (required) — verified by <code>example-check_id</code>
</li>
</ol>
<dl class="ds-facts">
<div>
<dt>Workflow</dt>
<dd>
<code>example-workflow_id</code>
</dd>
</div>
<div>
<dt>Progress</dt>
<dd>Saved between visits</dd>
</div>
<div>
<dt>Runs</dt>
<dd>
<code>example-operation</code> in the test environment</dd>
</div>
</dl>
<p class="ds-live-note" role="note">Step checks and saved progress need the live documentation site.</p>
</section>
```

Preview (interface-only; the markup above is the same output):

The renderer resolves this component as a native block; the preview above is its real HTML output, and Markdown parity for native blocks is covered by the renderer test suite.

## Specification

Generated from `packages/contracts/component-specs/tutorial.md`.

### Contract

Production props are normative in `../contracts/component-props/tutorial.schema.json`. The corresponding `component-fixtures` manifest is only a minimal protocol fixture; use the production props schema when building the published package. The packaged artifact ships exactly its generated `component-package.json` manifest plus `props.schema.json` (the production props schema, copied byte-for-byte) and `spec.md` (this spec, copied byte-for-byte); it contains no executable payload, fallback implementation, Storybook, test suite, SSR harness or README. Rendering behavior and the acceptance cases below belong to the renderer and the repository tests, not to the package. Installation pins the package version and the digest of every shipped byte.

### Intended behavior

Durable scoped progress tied to publication/version; completion depends on actual configured checks.

### Failure and fallback

Blocked step permits viewing next content but not false completion.

### Required acceptance cases

Failed check remains failed after refresh; reset scoped session only. Also test empty data, loading, denied access, browser without JS, mobile 360px, keyboard navigation, dark mode and an explicit constrained agent tool call. The server independently authorizes capability requests; a package manifest cannot grant authority.

### Data and maintenance

Data bindings resolve from a specific publication/release vector and permitted fact/evidence graph. Configuration edits create versioned component patches. Update invalidation uses dependency IDs, never indiscriminate whole-page regeneration. Human-owned props survive automatic updates unless invalidated with an explicit conflict. Missing optional resources leave an honest inert/readable fallback, not a broken page or fake success.

### Cost and tools

Pure/local interaction must never invoke a model by accident. Any model, remote query or executor call must reserve approved budget before dispatch. Public visitors do not inherit owner resources. The component may call only named tools in its signed manifest with valid typed inputs. A cancelled job stops polling and closes resources. No component gets platform administration, raw credentials or an unlimited execution loop.

### React tutorial adapter

Production `workflow_id`, `steps`, `persist_progress` and optional `resource` select a host binding from `ComponentContentProvider.tutorials`, keyed with `tutorialKey(workflow_id, resource)` from `@docsloth/official-components/host`. Step `block_ids` resolve only through this provider's already authorized blocks. All instructions and native step links work without JavaScript. Browsing later steps after failure is allowed and never changes check results. There are at most 100 steps, 50 block references per step and 1,000 references overall; duplicate step IDs and invalid inputs refuse. Missing content is labelled rather than fabricated.

An available adapter names the exact release ID, workflow ID/version, actor session ID, persistence mode (`durable` or `session`), and a progress snapshot. Snapshots include the same scope, a revision and a map keyed by step ID. Each result names the configured `check_id` and has `not_run`, `passed`, `failed` or `blocked` status, plus an optional public-safe message. Only matching configured passed checks count toward required completion. Missing, restricted, loading, wrong-scope or malformed progress never becomes success. Persisted failures are rendered on reload; `persist_progress: true` requires the host's durable mode, rather than silently using local storage.

Optional `verify` and `reset` callbacks receive the exact scope, expected progress revision, persistence choice and abort signal; verify additionally receives the selected step/check IDs. They return typed `ok` progress, `permission_required`, `unsupported` or `failed`. HTTP success or stdout is not a check result. Reset affects the bound tutorial session only and must return cleared checks. Failed or invalid replies retain previous results. Replacing workflow/release/session or host progress invalidates outstanding results; stopping aborts the adapter and discards late responses. The UI does not claim an already-started remote mutation was rolled back.

The host must independently authorize capability and audience, validate published steps/checks, reserve approved execution budget, compare revisions and persist results/reset atomically. Its `durable` declaration is a contract, not evidence that browser storage is durable. This component does not dispatch arbitrary `/v1/executions` requests, store proofs in localStorage, create grants, or manufacture passed outcomes. Actual core/cloud transport, durable storage and constrained agent-tool wiring remain host integration work; the browser acceptance fixture exercises the adapter over HTTP with scoped server state across reloads, not a production database deployment.

## Package manifest

Protocol fixture: `packages/contracts/component-fixtures/tutorial.json`.

| Field | Value |
| --- | --- |
| Name | @docsloth/tutorial |
| Version | 1.0.0 |
| Protocol | 1.x |
| License | Apache-2.0 |
| Runtime | react |
| Entry | dist/index.js |
| Recording policy | blocked |
| Fallback | html, markdown, json |
| Network hosts | none |
| Production write | no |
| Max runtime seconds | 120 |
| Integrity | all zeros (protocol fixture placeholder) |

| Tool | Effect | Confirmation | Input |
| --- | --- | --- | --- |
| next | read | no | value |
| verify | execute | no | value |
| reset | local_write | no | value |

## Sources

| Source | Path |
| --- | --- |
| Component page | https://registry.docsloth.dev/components/tutorial.html |
| Markdown twin | https://registry.docsloth.dev/docs/tutorial.md |
| LLM index | https://registry.docsloth.dev/llms.txt |
| Specification | packages/contracts/component-specs/tutorial.md |
| Prop schema | packages/contracts/component-props/tutorial.schema.json |
| Protocol fixture | packages/contracts/component-fixtures/tutorial.json |
| Catalog | packages/contracts/component-catalog.json |