Documentation Validation

Documentation code examples break silently. A website redesigns, an API method gets renamed, a tutorial’s hardcoded coordinates drift, and your quickstart guide stops working. The first person to discover it is a prospective user who leaves and never comes back. Northstar fixes this by visually locating UI elements and verifying workflows end-to-end, the same way a human QA tester would.

Self-heal coordinate-dependent examples

Tutorials that show GUI interactions with hardcoded coordinates break when the target website or rendering environment changes. Northstar finds the correct coordinates by looking at the screen:

heal_coordinates.py

from tzafon import Lightcone

client = Lightcone()

TOOL = {
    "type": "computer_use",
    "display_width": 1280,
    "display_height": 720,
    "environment": "browser",
}

with client.computer.create(kind="browser") as computer:
    computer.navigate("https://quotes.toscrape.com/login")
    computer.wait(2)
    screenshot_url = computer.get_screenshot_url(computer.screenshot())

    # Ask Northstar to locate each form element
    elements = ["username input field", "password input field", "Login button"]

    for element in elements:
        response = client.responses.create(
            model="tzafon.northstar-cua-fast-1.6",
            tools=[TOOL],
            input=[{
                "role": "user",
                "content": [
                    {"type": "input_text", "text": f"Click the {element}"},
                    {"type": "input_image", "image_url": screenshot_url, "detail": "auto"},
                ],
            }],
        )

        for item in response.output:
            if item.type == "computer_call":
                print(f"{element}: ({item.action.x}, {item.action.y})")

heal_coordinates.ts

import Lightcone from "@tzafon/lightcone";

const client = new Lightcone();

const tool = {
  type: "computer_use" as const,
  display_width: 1280,
  display_height: 720,
  environment: "browser",
};

const computer = await client.computers.create({ kind: "browser" });
const id = computer.id!;

try {
  await client.computers.navigate(id, { url: "https://quotes.toscrape.com/login" });
  await new Promise((r) => setTimeout(r, 2000));
  const ss = await client.computers.screenshot(id);
  const screenshotUrl = ss.result?.screenshot_url as string;

  const elements = ["username input field", "password input field", "Login button"];

  for (const element of elements) {
    const response = await client.responses.create({
      model: "tzafon.northstar-cua-fast-1.6",
      tools: [tool],
      input: [{
        role: "user",
        content: [
          { type: "input_text", text: `Click the ${element}` },
          { type: "input_image", image_url: screenshotUrl, detail: "auto" },
        ],
      }],
    });

    for (const item of response.output ?? []) {
      if (item.type === "computer_call") {
        console.log(`${element}: (${item.action.x}, ${item.action.y})`);
      }
    }
  }
} finally {
  await client.computers.delete(id);
}

Northstar returns exact pixel coordinates for each element. Diff these against the hardcoded values in your docs and update any that have drifted.

Verify the fix end-to-end

After healing coordinates, replay the full workflow to confirm it actually works before committing:

verify_fix.py

from tzafon import Lightcone

client = Lightcone()

# Coordinates from the heal step above
coords = {
    "username": (189, 163),
    "password": (189, 246),
    "login": (93, 302),
}

with client.computer.create(kind="browser") as computer:
    computer.navigate("https://quotes.toscrape.com/login")
    computer.wait(2)

    # Replay the tutorial with corrected coordinates
    computer.click(*coords["username"])
    computer.type("scraper")
    computer.click(*coords["password"])
    computer.type("password")
    computer.click(*coords["login"])
    computer.wait(2)

    # Verify the workflow actually completes
    html = computer.get_html_content(computer.html())
    assert "Logout" in html, "Login failed; coordinates may still be wrong"
    print("Verified: tutorial works with healed coordinates")

verify_fix.ts

import Lightcone from "@tzafon/lightcone";

const client = new Lightcone();

const coords = {
  username: [189, 163] as const,
  password: [189, 246] as const,
  login: [93, 302] as const,
};

const computer = await client.computers.create({ kind: "browser" });
const id = computer.id!;

try {
  await client.computers.navigate(id, { url: "https://quotes.toscrape.com/login" });
  await new Promise((r) => setTimeout(r, 2000));

  await client.computers.click(id, { x: coords.username[0], y: coords.username[1] });
  await client.computers.type(id, { text: "scraper" });
  await client.computers.click(id, { x: coords.password[0], y: coords.password[1] });
  await client.computers.type(id, { text: "password" });
  await client.computers.click(id, { x: coords.login[0], y: coords.login[1] });
  await new Promise((r) => setTimeout(r, 2000));

  const html = await client.computers.html(id);
  const content = html.result?.html_content as string;
  if (!content.includes("Logout")) throw new Error("Login failed");
  console.log("Verified: tutorial works with healed coordinates");
} finally {
  await client.computers.delete(id);
}

The pattern is: detect drift (run examples, catch failures) -> heal (ask Northstar for correct coordinates) -> verify (replay the full workflow) -> commit (update the docs). Run this in CI nightly and broken examples never reach your users.

Let Northstar run the tutorial itself

For the strongest validation, give Northstar the tutorial instructions and let it complete the workflow autonomously. If the agent succeeds, the tutorial works:

validate_tutorial.py

from tzafon import Lightcone

client = Lightcone()

for event in client.agent.tasks.start_stream(
    instruction=(
        "Go to https://quotes.toscrape.com/login. "
        "Log in with username 'scraper' and password 'password'. "
        "After logging in, verify you can see quotes on the page. "
        "Report whether the login succeeded and what quotes you see."
    ),
    kind="browser",
    max_steps=15,
):
    print(event)

validate_tutorial.ts

import Lightcone from "@tzafon/lightcone";

const client = new Lightcone();

const stream = await client.agent.tasks.startStream({
  instruction:
    "Go to https://quotes.toscrape.com/login. " +
    "Log in with username 'scraper' and password 'password'. " +
    "After logging in, verify you can see quotes on the page. " +
    "Report whether the login succeeded and what quotes you see.",
  kind: "browser",
  max_steps: 15,
});

for await (const event of stream) {
  console.log(event);
}

This is the highest-fidelity test. Northstar navigates, finds the form fields visually, enters credentials, submits, and verifies the result. No coordinates to maintain at all.

Why Northstar for docs validation

	Manual QA	Static analysis	Northstar
Catches runtime failures	Yes, but doesn’t scale	No	Yes, automatically
Handles coordinate drift	Human finds new positions	Cannot	Looks at the screen and finds them
Covers real API calls	Time-consuming	No	Executes against live API
Scales with docs growth	Linearly slower	Fast but shallow	Fast and deep
Self-heals	Requires human intervention	No	Finds correct values and patches files

This pattern is especially powerful for documentation that includes GUI interactions: tutorials showing form filling, web scraping, or multi-step workflows. Traditional static analysis can check syntax but cannot verify that a tutorial actually works when a user follows it.

See also

• Software Testing: test applications with natural language instructions
• Responses API: build custom validation loops with screenshot feedback
• Computers: manage browser sessions for automated verification