Guide

Package guide is a step-by-step checklist that gets your business running on AI.

Specification

/v1/guide is the Business AI Guide: an interactive launch checklist every org completes on-site — a checklist engine over a machine-readable curriculum, a Business AI agent that can execute a step through the caller's own tool plane, and a versioned brand blueprint the whole journey is projected from. It is implemented in hanzoai/cloud at apps/guide (HIP-0106).

Motivation

Onboarding advice that lives in prose goes stale and cannot be acted on. A journey that is data — steps with dependencies, done-criteria mapped to real signals, tools bound to steps — can be auto-marked when the org has demonstrably done the work, and executed by an agent when the org asks. The three concerns are kept orthogonal on purpose: the engine is pure functions over plain data, the agent acts only through the caller's own authority, and the blueprint is content a SuperAdmin authors live (apps/guide/curriculum.go:6-31).

Specification

The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are to be interpreted as in RFC 2119.

§1 Two stores, two tiers

Per-org progress and the org's own curriculum override live in that org's own database, opened through cloud.OrgStore — one file per org, resolved through the one namespace door (apps/guide/guide.go:47-63). The shared brand blueprint is a second, deployment-wide store (apps/guide/blueprint_store.go:45), seeded idempotently from embedded fixtures — the base journey plus one YAML file per brand (apps/guide/brands.go) — after which the database is authoritative and the fixture is only the fail-safe fallback. A redeploy MUST NOT clobber a live edit; seeding is if-absent (apps/guide/guide.go:78-88).

§2 The address

Nineteen operations under /v1/guide. All are typed except six, each declared with prose beside its route (apps/guide/guide.go:262-360) because its body has no declarable shape: the curriculum and blueprint writes accept YAML or JSON as a raw body (the canonical parsed form is what is stored); the blueprint PATCH is a shallow merge whose keys are the patched item's, not the route's; and steps/{id}/do answers either JSON or a Server-Sent-Event stream of the agent's actions. Every declared description renders only while the router serves the route, so the prose can never invent a path.

A step transition is dependency-gated: a blocked start or done is 409 carrying blockedBy naming the exact steps in the way. A write that does not parse or does not validate (unique ids, acyclic dependencies) is 422 and the journey in force is untouched.

§3 Tenancy, and the gate that differs by tier

The tenant is principal.Org — the org minted from the validated bearer (HIP-0026), never a header (apps/guide/guide.go:382-385). The per-org curriculum override is any validated member's surface. The brand blueprint is platform content: authoring it requires SuperAdmin (apps/guide/admin.go:39), a per-org admin is 403, and every write is audited and versioned with the prior versions kept as a recovery trail.

§4 Money

Guide is free (cloud.Free, plugin/guide/main.go). The one executing path — "do it for me" — runs the step's tool through the calling principal's own MCP plane (automations.InvokeTool), so the work is metered and audited by the plane that owns it, against the caller's ledger (apps/guide/agent.go:61). Guide itself debits nothing and MUST NOT acquire an authority the caller does not hold.

§5 Events and observability

It publishes nothing on the bus. It emits nothing beyond the request span every route gets; the audit trail for blueprint authoring is the shared audit plane, not a telemetry stream.

§6 Stage

beta: a vertical application — a guided launch product over the core planes, not one of them.

§7 Upstream

It derives from none. The curriculum fixtures are embedded YAML authored here; the growth signals are injected read seams bound at the composition root, so guide imports none of the subsystems it observes (apps/guide/signals.go).

Rationale

The alternative to a data blueprint is a hard-coded journey, which makes every white-label brand and every content edit a code change. The alternative to executing through the caller's own tool plane is a service identity that acts for orgs — which is an escalation surface, and the reason the agent runs AS the caller instead.

Security Considerations

The two tiers are the exposure. If the per-org gate could reach the shared blueprint, one tenant would edit every org's journey — including which MCP tools the Business AI runs for a step, which is a lever over agents in every org; the SuperAdmin gate and the audit trail on that tier exist for exactly this. On the executing path, the wrong implementation runs tools under an authority wider than the caller's; here the invocation is per-principal, so a step can never do what its asker could not.

Four surfaces

Quickstart

export HANZO_API_KEY=sk-...   # console.hanzo.ai → API keys

Then the first call — a read that needs nothing but the key. GET /v1/guide, operation get_guide:

hanzo guide get

import { Configuration, GuideApi } from 'hanzoai';

const api = new GuideApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getGuide();

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import GuideApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = GuideApi(client).get_guide()

cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)

resp, _, err := client.GuideAPI.GetGuide(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_cloud::apis::{configuration::Configuration, guide_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = guide_api::get_guide(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.GuideApi;

ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));

var result = new GuideApi(client).getGuide();

curl https://api.hanzo.ai/v1/guide \
  -H "Authorization: Bearer $HANZO_API_KEY"

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "guide",
         "arguments": {
           "op": "get_guide",
           "input": {}
         }
       }
     }'

Answers 200 with object — ok.

Endpoints

All Hanzo APIs · Interactive reference