guide

type ActionRecord ¶

type ActionRecord struct {
	ID        string `json:"id"`
	StepID    string `json:"stepId"`
	Tool      string `json:"tool"`
	Args      string `json:"args,omitempty"`
	Result    string `json:"result,omitempty"`
	OK        bool   `json:"ok"`
	Err       string `json:"err,omitempty"`
	CreatedAt int64  `json:"createdAt"`
}

ActionRecord is one Business AI tool execution — the audit-visible ledger row.

type Blog ¶

type Blog struct {
	Slug      string `json:"slug,omitempty"`
	Title     string `json:"title,omitempty"`
	Why       string `json:"why,omitempty"`
	How       string `json:"how,omitempty"`
	CaseStudy string `json:"caseStudy,omitempty"`
}

Blog is a tactic's long-form home: why it works (the principle in prose), how to run it, and a worked caseStudy. slug/title name the post. All fields are optional so a tactic without a blog omits it entirely (Strategy.Blog is nil).

type Blueprint ¶

type Blueprint struct {
	Version    string        `json:"version"`
	Brand      string        `json:"brand,omitempty"`
	Title      string        `json:"title,omitempty"`
	Enabled    *bool         `json:"enabled,omitempty"`
	Principles []Principle   `json:"principles,omitempty"` // the 64-principle spine (Zen of Hanzo archetypes)
	Sections   []Section     `json:"sections,omitempty"`
	Steps      []JourneyStep `json:"steps"`
	Strategies []Strategy    `json:"strategies,omitempty"`
	Templates  []Template    `json:"templates,omitempty"`
}

Blueprint is the full authored playbook. `brand` is the white-label key (""==the global default); `enabled` at the root is the whole-blueprint lever (a disabled blueprint is skipped by resolution, falling through to the next tier). The four arrays are the content. The engine runs on Curriculum() — the enabled projection.

func Parse(raw []byte) (Blueprint, error)

func (b Blueprint) Curriculum() Curriculum

func (b Blueprint) Validate() error

type BlueprintStore ¶

type BlueprintStore struct {
	// contains filtered or unexported fields
}

BlueprintStore persists brand blueprints as versioned canonical-JSON docs.

func (s *BlueprintStore) Close() error

func (s *BlueprintStore) LatestResolved(ctx context.Context, brand string) (doc []byte, version int, key string, ok bool, err error)

func (s *BlueprintStore) ListVersions(ctx context.Context, brand string) ([]VersionMeta, error)

func (s *BlueprintStore) SaveVersion(ctx context.Context, brand string, doc []byte, now int64) (int, error)

func (s *BlueprintStore) SeedOrUpgrade(ctx context.Context, brand string, doc []byte, seedVersion int, now int64) (SeedAction, error)

type Curriculum ¶

type Curriculum struct {
	Version string        `json:"version"`
	Title   string        `json:"title,omitempty"`
	Steps   []JourneyStep `json:"steps"`
}

Curriculum is the ENGINE's view: an ordered set of steps plus metadata. It only ever holds ENABLED steps — it is the projection of a Blueprint (Blueprint.Curriculum()), so the next-step/gating logic never has to reason about enablement. Order is authoring order and is the tiebreak the next-step logic walks.

func (c Curriculum) Available(states map[string]State, id string) bool

func (c Curriculum) BlockedBy(states map[string]State, id string) []string

func (c Curriculum) Counts(states map[string]State) (done, total, percent int)

func (c Curriculum) Next(states map[string]State) string

type Detector ¶

type Detector func(ctx context.Context, org string, step JourneyStep) (bool, error)

Detector reports whether a step's done-criterion is satisfied by the org's real state. It is the auto-detect seam: a step names a Signal, the engine looks the detector up by that name and runs it. A detector MUST be honest — a data source it cannot reach returns an error (treated as "not present"), never a spurious true.

type Funnel ¶

type Funnel struct {
	Available  bool    `json:"available"`
	WindowDays int     `json:"windowDays"`
	Pageviews  int64   `json:"pageviews"`
	Visitors   int64   `json:"visitors"`
	Signups    int64   `json:"signups"`
	Orders     int64   `json:"orders"`
	Revenue    float64 `json:"revenue"`
}

Funnel is the org's top-of-funnel over the trailing window: traffic → signups → orders, with revenue. Available is false when the warehouse is unreachable or the org has emitted nothing (honest-empty), so the caller renders "turn on analytics" rather than a misleading row of zeros.

type JourneyStep ¶ added in v1.801.350

type JourneyStep struct {
	ID      string `json:"id"`
	Section string `json:"section,omitempty"` // the phase (section id) this step groups under
	Title   string `json:"title"`
	Detail  string `json:"detail,omitempty"` // the prose/juncture — what the Guide asks/explains here

	// Dependencies are step ids that must be done/skipped before this step is
	// available. The wire key is `deps` (the blueprint contract); the Go field keeps
	// its descriptive name.
	Dependencies []string `json:"deps,omitempty"`

	// Enabled is the admin on/off lever. A NIL pointer reads as ENABLED (absence ==
	// on): a legacy/org curriculum that omits the field keeps every step, and only an
	// explicit `enabled: false` (an admin disable) drops a step from the journey. See
	// on() in blueprint.go and the Blueprint.Curriculum() projection.
	Enabled *bool `json:"enabled,omitempty"`

	// Signal, when set, names a machine detector (detect.go). When the detector
	// reports the org's real state present, the step auto-marks done.
	Signal string `json:"signal,omitempty"`

	// Tool, when set, is the MCP tool the Business AI runs for "do it for me". Args
	// are its default arguments; Draft is an optional AI prompt whose output fills the
	// DraftInto arg (default "brief").
	Tool      string         `json:"tool,omitempty"`
	Args      map[string]any `json:"args,omitempty"`
	Draft     string         `json:"draft,omitempty"`
	DraftInto string         `json:"draftInto,omitempty"`
}

JourneyStep is one checklist item — one quest of the launch journey. The struct tags are JSON, and sigs.k8s.io/yaml decodes YAML through them — so one tag set is the ONE contract for both the embedded YAML blueprint and a JSON PUT body (DRY: no parallel yaml tags).

The qualifier is load-bearing, not decoration: the type NAME is the schema name in the published document, and that document is ONE flat namespace shared by every app in the fleet. Plain `Step` is already claimed there by apps/marketing (a step of a drip sequence — a different shape entirely), and openapi.Weave refuses one name with two shapes because a generated SDK would bind whichever it read last. Do not "simplify" this back to Step; that is the collision, not a tidier name. The wire is unaffected either way — the JSON keys live on the fields.

type Principle ¶

type Principle struct {
	N         int    `json:"n"`                   // 1..64, the hexagram number + canonical order
	Hexagram  string `json:"hexagram,omitempty"`  // the I-Ching hexagram (pinyin + gloss)
	Slug      string `json:"slug"`                // stable identifier a tactic files under
	Name      string `json:"name,omitempty"`      // the principle's short name
	Principle string `json:"principle,omitempty"` // the actionable growth law
	Change    string `json:"change,omitempty"`    // the Book of Changes reading
	SunTzu    string `json:"sunTzu,omitempty"`    // the Art of War teaching
	Domain    string `json:"domain,omitempty"`    // the growth / go-to-market domain it governs
}

Principle is one of the 64 archetypes of the Zen of Hanzo spine — the fixed backbone a tactic is filed under (Strategy.Principle == Principle.Slug). It weds an I-Ching hexagram to a Sun Tzu teaching and a modern growth domain. The spine is authored DATA (admin.hanzo.ai can see + organize by it), NOT engine logic: nothing in the checklist engine depends on it; it exists so the corpus has a stable, first-principles home.

type Section ¶

type Section struct {
	ID      string `json:"id"`
	Title   string `json:"title"`
	Detail  string `json:"detail,omitempty"`
	Order   int    `json:"order,omitempty"`
	Enabled *bool  `json:"enabled,omitempty"`
}

Section is one ordered phase of the journey. Steps group under a section by id; a DISABLED section drops all of its steps from the journey (the precedence rule).

type SeedAction ¶

type SeedAction string

SeedAction is the outcome of a SeedOrUpgrade call (for logging / test assertions).

const (
	SeedNone     SeedAction = "unchanged" // admin-edited, or seed already current
	SeedInserted SeedAction = "seeded"    // no row existed → fresh seed at version 1
	SeedUpgraded SeedAction = "upgraded"  // unedited seed replaced with a newer generation
)

type SignalSet ¶

type SignalSet map[string]bool

SignalSet is the observed growth facts about ONE org: signal name → present. It is a set of BOOLEANS / thresholds — never a secret, never another org's data. The profile emits it and classifyStage folds it into a Stage.

type Signals ¶

type Signals struct {
	// ModuleInstalled reports whether org has installed the named framework module
	// (framework.ModuleInstalled) — e.g. "cms", "erp".
	ModuleInstalled func(ctx context.Context, org, module string) bool
	// ConnectorPresent reports whether org has connected the named integration
	// provider — a BOOLEAN "is connected" (integrations.Connected), NEVER the token.
	ConnectorPresent func(ctx context.Context, org, provider string) bool
	// HasDeployment reports whether org has a live deployment.
	HasDeployment func(ctx context.Context, org string) (bool, error)
	// RevenueCents is org's OWN recorded revenue-of-record in minor units. The
	// number stays in the org's own profile; the signal it satisfies is revenue > 0.
	RevenueCents func(ctx context.Context, org string) (int64, error)
	// RecordCount is a count of org's OWN business records — the data-volume signal.
	RecordCount func(ctx context.Context, org string) (int64, error)
}

Signals are the org-scoped, cross-subsystem reads the growth observe layer composes. Every func takes the caller's VALIDATED org and reads ONLY that org's state; a signal is a boolean / a threshold / the org's OWN number — never a secret and never another org's data.

type Stage ¶

type Stage string

Stage is an org's observed growth stage — a first-principles ladder from nothing-observed to money-flowing. It is a pure function of the SignalSet.

const (
	StageFormed    Stage = "formed"    // the org exists; nothing else is observed yet
	StageLaunched  Stage = "launched"  // a live presence: a deployment is up or analytics is emitting
	StageActivated Stage = "activated" // real engagement: people are signing up or a book of records exists
	StageScaling   Stage = "scaling"   // money of record: revenue is recorded or orders are completing
)

type State ¶

type State string

State is a step's per-org lifecycle state.

const (
	StateTodo       State = "todo"
	StateInProgress State = "in_progress"
	StateDone       State = "done"
	StateSkipped    State = "skipped"
)

type StateRow ¶

type StateRow struct {
	State     State  `json:"state"`
	Source    string `json:"source,omitempty"`
	Note      string `json:"note,omitempty"`
	UpdatedAt int64  `json:"updatedAt,omitempty"`
}

StateRow is a step's persisted progress.

type Store ¶

type Store struct {
	// contains filtered or unexported fields
}

Store is one org's guide database. Isolation is PHYSICAL: cloud.OrgStore opens a distinct file per org ({DataDir}/orgs/{org}/guide.db), so there is no org column and no cross-org query is expressible. It holds three tables:

• progress: one row per step whose state has diverged from the todo default.
• actions: the Business AI action ledger — every "do it for me" tool call, its args, and its outcome. It is both the audit-visible record and the backing state for the "acted" auto-detect signal.
• curriculum: at most one row — the org's custom curriculum override (raw doc).

The caller (guide.Mount) opens it through cloud.NewOrgStore; openStore below is the per-org open func. cloud.OrgDB has already applied the WAL/busy pragmas and single-writer bound, so openStore only migrates.

func (s *Store) AddAction(ctx context.Context, a ActionRecord) error

func (s *Store) ClearCurriculum(ctx context.Context) error

func (s *Store) Close() error

func (s *Store) GetCurriculum(ctx context.Context) ([]byte, bool, error)

func (s *Store) HasSuccessfulAction(ctx context.Context, tool string) (bool, error)

func (s *Store) ListActions(ctx context.Context, limit int) ([]ActionRecord, error)

func (s *Store) ResetState(ctx context.Context, stepID string) error

func (s *Store) SetCurriculum(ctx context.Context, doc []byte, now int64) error

func (s *Store) SetState(ctx context.Context, stepID string, state State, source, note string, now int64) error

func (s *Store) States(ctx context.Context) (map[string]StateRow, error)

type Strategy ¶

type Strategy struct {
	ID        string   `json:"id"`
	Principle string   `json:"principle,omitempty"` // the spine slug this tactic files under
	Category  string   `json:"category"`
	Workload  string   `json:"workload,omitempty"`
	Action    string   `json:"action"`
	Tags      []string `json:"tags,omitempty"`
	Source    string   `json:"source,omitempty"` // provenance / attribution
	Era       string   `json:"era,omitempty"`    // modern | heritage
	Blog      *Blog    `json:"blog,omitempty"`   // long-form explainer (nil for un-blogged tactics)
	Enabled   *bool    `json:"enabled,omitempty"`
}

Strategy is one tactic in the recommendation corpus (strategies.go filters it by category/workload and by the org's observed profile via the tag join). `tags` are signal predicates — `stage:<research|launched|activated|scaling>` and `has:<capability>` — that the corpus join maps onto the observe layer's vocabulary. `principle` files the tactic under one of the 64 spine archetypes (Blueprint.Principles); `era` is `modern` (an AI-era tactic) or `heritage` (a classical one); `source` is its provenance; `blog` is its long-form explainer. See the Zen of Hanzo corpus README.

type Template ¶

type Template struct {
	ID      string `json:"id"`
	Title   string `json:"title"`
	Body    string `json:"body"`
	Enabled *bool  `json:"enabled,omitempty"`
}

Template is a reusable prompt/snippet a step references. `body` may carry {placeholder} tokens for client-specific bits ({client_name}, {domain}, {product}).

type VersionMeta ¶

type VersionMeta struct {
	Brand     string `json:"brand"`
	Version   int    `json:"version"`
	UpdatedAt int64  `json:"updatedAt"`
}

VersionMeta is one stored version's metadata (audit / PITR listing — never the full doc, which the GET returns for the active version).