Walkthroughs

A walkthrough is an ordered tour of code that an agent writes for you: notes, line ranges in files, files at a commit, and diffs, each with Markdown narration. Ask an agent to explain a pull request, a branch, or how a feature works as a walkthrough; Source Zero shows it beside the code.

Following a walkthrough

Open the Walkthroughs view (the route icon in the activity bar), or the link the agent prints. The badge counts walkthroughs published since you last looked. Choose one to see its steps; Overview opens its cover, with the summary and an outline.

Each step opens an ordinary tab: the file in Source with the step's lines selected, a read-only snapshot at a commit, or a review of uncommitted work, a commit, a range, or a branch. The narration appears inside the code, right after the step's lines, with Previous, Next, and Close. Notes appear in the walkthrough's own tab.

Present hides the activity bar, sidebar, tabs, and status bar and floats a step bar over the document. On phones the step bar shows while you follow a walkthrough; Steps opens the list.

A step can record the start of its first line when it is written. If the code changes later, the step says so instead of guessing where the code moved. Steps pinned to a commit never change.

Walkthroughs live in your user cache (srcz/walkthroughs), up to 100 per project; the least recently updated go first. Delete one from its step list. They are per machine and are not shared through git.

Writing walkthroughs (for agents)

The quickest start: choose Copy agent instructions (the copy icon in the Walkthroughs header, or the button in an empty list), paste it into your agent, and finish the last line, “Walk me through: ”, with what to explain. The instructions carry this Source Zero's address, your project's path, the format, and how to publish.

Agents publish with the Source Zero CLI; no running server is needed:

srcz walkthrough publish walkthrough.json

{
  "project": "/absolute/path/to/repository",
  "title": "How login sessions refresh",
  "summary": "From the cookie check to the token refresh.",
  "steps": [
    { "title": "Where it starts", "body": "Every request passes through `requireSession`." },
    { "title": "The cookie check", "body": "Expired cookies fall through to refresh.", "file": { "path": "auth/session.go", "lines": [40, 58] } },
    { "title": "What this branch changes", "body": "Refresh now retries once.", "diff": { "compare": { "kind": "branch", "base": "main" }, "path": "auth/refresh.go", "lines": [12, 30] } }
  ]
}

Source Zero checks every path, line, and commit, stores the walkthrough, and prints its id. An open browser lists it within seconds. project is the repository or worktree root (git rev-parse --show-toplevel) or a folder outside any repository; folders inside a repository are rejected. Publishing again with the same id replaces it. Any mistake exits 1 and names each problem field, such as steps[2].file.lines: end 90 is past the file's last line, 61.

When the desktop app is installed and the daemon serves the project, the CLI prints a srcz:// url and "open": true opens it in the app. On a machine serving with --remote, it prints a srcz:// link that opens on your connected computer (desktopUrl in --json; see Remote hosts). Otherwise, when a running browser server shows the project, the CLI prints its web url, and "open": true opens it in the browser (never on a machine without a UI, such as an SSH session). Without one, it prints how to view the walkthrough: srcz <project>, then the Walkthroughs view. The CLI never starts a server. srcz walkthrough schema prints the JSON Schema.

Agents can also publish with POST /api/walkthroughs on a running srcz:

curl -q -sS -X POST -H 'Content-Type: application/json' \
  --data @walkthrough.json http://localhost:7971/api/walkthroughs

The response carries the walkthrough's id and url; "open": true also opens it in the browser unless Source Zero runs with --no-open. GET /api/walkthrough-schema returns the JSON Schema, and any mistake comes back as a 400 naming each problem field.

Source Zero ships an agent skill with the full guidance: discovery, targets, and how to tell a good story. Install it with the skills CLI:

npx skills add flexdinesh/srcz --skill srcz-walkthrough

The skill is documentation only; Source Zero does not install it. Its source is skills/srcz-walkthrough.

The endpoint accepts JSON only, from any local process; requests from another site's pages are refused.