Skip to content

Tutorial Authoring Guide

The Naftiko Fleet tutorials are organized into tracks — each track is a self-contained learning path covering one persona's path through the platform. This page explains how to author a track or a tutorial step.

Track structure

Every track lives under docs/tutorials/track-N-name/ with:

tutorials/track-1-context-engineering/
├── index.md             # track landing — overview, steps, prerequisites
├── step-1-mock.md       # one file per step (optional)
├── step-2-wiring.md
└── ...

For shorter tracks, the entire track can live in index.md with steps as sections.

The four current tracks are:

Track Persona Focus
1 — Context Engineering AI-first developer Mock → wire → auth
2 — API Reusability Platform / SDI engineer Skill, Aggregates, REST
3 — Agent Orchestration Agent designer Fleet manifests, multi-capability
4 — Platform Operations Platform engineer CI, observability, environments

The "Shipyard" example

All tutorials use the same running example: a maritime shipping company called Shipyard. Domain entities:

Entity Tutorial use
Ships Single-resource lookups, basic GET operations
Crews Multi-step (ship → crew) for aggregate examples
Voyages Time-bounded operations, status transitions
Cargo Joins and lookup: examples

Stick to these entities across all tutorial content. Don't introduce a new domain unless the track really calls for one.

Step anatomy

Each step follows the same shape:

## Step N — Title

> **Goal:** one-sentence statement of what the reader achieves.
> **Time:** ~X minutes.
> **Prerequisites:** Step N-1 completed (or "none").

### Why this step

One paragraph framing — what problem are we solving?

### Walk-through

Numbered steps with code blocks. Every concept gets a YAML or code example.

### What you learned

- Bullet 1
- Bullet 2

### Continue to [Step N+1](step-n+1.md)

Conventions

Length

  • Steps: 100-300 lines of Markdown each
  • Track index: 80-200 lines

If a step exceeds 300 lines, split it into two steps rather than scrolling.

Voice

  • Second person ("you'll declare …"), not first person
  • Imperative for actions ("Declare …", "Run …")
  • No "let's"

Code blocks

  • Always include # filename.naftiko.yml (or similar) as the first line of multi-file examples
  • Diff-style highlights for changes between steps: 
    - baseUri: "https://api.example.com/v1/"
+ baseUri: "https://api.example.com/v1"

Admonitions

  • !!! tip — alternative paths, optimization hints
  • !!! warning — common pitfalls
  • !!! info — version-specific or planned-feature callouts

Cross-track references

If a step builds on a concept from another track, link to the concept page (under docs/concepts/) rather than to the other track's step. Concept pages are stable; step pages may be reorganized.

Reviewing tutorial PRs

Reviewers check:

  1. It runs. Every YAML and command in the tutorial is verified end-to-end.
  2. Schema version. All YAML samples pin the current schema version.
  3. Naming consistency. The Shipyard domain is used consistently.
  4. Cross-references. Internal links resolve.
  5. Polychro-clean. Sample capabilities pass polychro:governance and polychro:ai-safety (unless the step is about demonstrating a violation).