export interface Field {
    name: string;
    type: string;
    required: boolean;
    /** Inline semantic constraint — bounds, enum, "must reference an active plan",
     *  token caps. Lives here, never in a separate Preconditions section. */
    constraint: string;
}
/** Positional argument — at most one per leaf. */
export interface PositionalParam {
    kind: 'positional';
    name: string;
    /** Display hint only; always parsed as string. */
    type?: 'string' | 'path';
    required: boolean;
    constraint: string;
    /** Local-file materialization contract, valid only on a `path` param. The
     *  CLI-side value is a path to a local file; the invoker reads that file and
     *  sends its CONTENT as the mapped value — 'text' as UTF-8, 'base64' as the
     *  base64 of its raw bytes. The path string itself never crosses the wire. */
    encoding?: FileEncoding;
    /** Ambient default: when the caller omits this param and the named client
     *  environment variable is set and non-empty, that value is used and counts as
     *  supplied — see FlagParam.defaultFromEnv. */
    defaultFromEnv?: string;
}
/** How a local file named by a `path` param is encoded into the request. */
export type FileEncoding = 'text' | 'base64';
/** Long-form flag (`--name`). */
export interface FlagParam {
    kind: 'flag';
    name: string;
    /** 'bool' flags take no value — presence = true. */
    type: 'string' | 'int' | 'bool' | 'path' | 'enum';
    /** Required only when type is 'enum'. */
    choices?: string[];
    required: boolean;
    constraint: string;
    default?: string | number | boolean;
    /** When true, the flag may appear multiple times; values accumulate into an
     *  array (parseArgv collects them; body-placed REST params ship as a JSON array). */
    repeatable?: boolean;
    /** When true, the flag is PARSED normally but never rendered in `-h`. For a
     *  deliberately-undiscoverable confirmation gate the agent must be TOLD about
     *  in the command's own output (not by reading the schema), never advertised. */
    hidden?: boolean;
    /** Local-file materialization contract, valid only on a `path` flag — see
     *  PositionalParam.encoding. */
    encoding?: FileEncoding;
    /** Ambient default sourced from the CALLER's environment: when the param is
     *  not supplied on the command line and this environment variable is set and
     *  non-empty, its value fills the param and counts as explicitly supplied (it
     *  therefore satisfies `required` and ships like a typed value — unlike a
     *  static `default`, which is a display/parse convenience only). This is how a
     *  leaf picks up ambient identity a caller should not have to retype, e.g.
     *  CRTR_NODE_ID, which every broker exports into its node's environment. */
    defaultFromEnv?: string;
}
/** Raw stdin content blob (piped text, not parsed as JSON). */
export interface StdinParam {
    kind: 'stdin';
    name: string;
    required: boolean;
    constraint: string;
}
/** --context-file PATH: reads and JSON-parses the file at PATH. */
export interface ContextFileParam {
    kind: 'context-file';
    name: string;
    required: boolean;
    constraint: string;
    /** Optional description of the expected JSON shape. */
    shape?: string;
}
export type InputParam = PositionalParam | FlagParam | StdinParam | ContextFileParam;
/** How prominently a subcommand surfaces in ancestor (parent / root) -h
 *  listings. Set per child in the parent branch's `help.children`. Default
 *  'normal'.
 *   - hidden    — never listed anywhere, not even in this branch's own -h.
 *                 You must already know it exists to invoke it.
 *   - normal    — listed in this branch's own -h only (the default).
 *   - common    — ALSO promoted into the parent's -h, as a bare qualified name.
 *   - important — ALSO promoted into the parent's -h, name + shortform desc. */
export type SubTier = 'hidden' | 'normal' | 'common' | 'important';
/** A child's assembled parent-level listing entry — computed by defineBranch
 *  from each child def's own self-description (`description`/`whenToUse`/`tier`).
 *  renderBranch consumes this; it is never authored by hand and there is no
 *  parent-side copy of a child's description (principle 16: each node owns its
 *  representation one level up). */
export interface ListingChild {
    name: string;
    /** Short description for this child's <subcommand> row. */
    description: string;
    /** Selection rubric — plainly states when to reach for this command. Expansive
     *  with a variety of examples for judgment-heavy commands; concise for
     *  genuinely single-purpose ones. Rendered verbatim (no prefix). */
    whenToUse: string;
    /** Visibility tier in ancestor listings (see SubTier). 'hidden' children are
     *  dropped from every listing. */
    tier: SubTier;
    /** How many non-hidden subcommands this child itself owns — drives the
     *  `subcommands="N"` attribute when a branch child is listed without
     *  expansion. Absent for leaves and childless branches. */
    subCount?: number;
}
/** A subtree's self-description at the parent (root) level. Each subtree owns
 *  the content that represents it one level up: its vocabulary line, its
 *  selection rubric, and any bounded block it contributes to the parent's -h.
 *  defineRoot assembles the root help from these — root never hardcodes a
 *  subtree's representation. See cli-design "Each node owns its parent-level
 *  representation". */
export interface RootEntry {
    /** One-line vocabulary desc — what this subtree is. Rendered first in the
     *  subtree's <name> block at root. */
    concept: string;
    /** Operations summary (verb list). Carried for completeness; the root block
     *  leads with concept + rubric, so this is available but not rendered. */
    desc: string;
    /** The selection rubric — `use when X` in the subtree's <name> block. */
    useWhen: string;
    /** Optional bounded block this subtree contributes to its <name> block at
     *  root. Returns a complete self-named state element (build it with
     *  stateBlock), e.g. `<kinds count="7">…</kinds>`. Aggregate, never an
     *  unbounded enumeration on a cold path. Soft-fails to omission on
     *  null/throw. */
    dynamicState?: () => string | null;
}
export interface RootHelp {
    tagline: string;
    /** One entry per listed subtree. Each renders as its own <name> XML block at
     *  root, carrying the subtree's concept, selection rubric, and any nested
     *  runtime-state block. Assembled from subtrees' RootEntry by defineRoot;
     *  root hardcodes none of it. */
    commands: RootCommand[];
    globals: {
        name: string;
        desc: string;
    }[];
}
/** A single command block at root. Most fields come from the subtree's
 *  RootEntry; `subcommands`/`otherSubcommandCount` are computed by defineRoot
 *  from the subtree's children tiers. */
export interface RootCommand {
    name: string;
    concept: string;
    desc: string;
    useWhen: string;
    dynamicState?: () => string | null;
    /** Promoted subcommands surfaced inline under this command at root, in
     *  declaration order. `desc` is present only for 'important' tier; 'common'
     *  tier carries the bare qualified path. */
    subcommands?: {
        path: string;
        desc?: string;
    }[];
    /** How many of this command's other (non-hidden, not-promoted) direct
     *  subcommands are not shown. Drives the "[+N (other) subcommands]" line. */
    otherSubcommandCount?: number;
}
export interface BranchHelp {
    name: string;
    /** The command's own description — rendered as the `description` attribute of
     *  its <command> card at its own -h. */
    summary: string;
    /** Local model prose orienting the agent to what the subtree contains and how
     *  the children differ as a group — never a per-child restatement (each
     *  child's purpose lives in its own listing row). */
    model?: string;
    /** Bounded runtime aggregate as a complete self-named state element (build
     *  it with stateBlock), e.g. `<kinds count="7">…</kinds>`. Renderer
     *  soft-fails to omission if this returns null or throws. */
    dynamicState?: () => string | null;
    /** Parent-level listing assembled by defineBranch from the actual child defs.
     *  renderBranch reads this; never author it by hand. */
    listing?: ListingChild[];
}
/** Viewer-only hint about how a leaf's result should preview in the attach
 *  viewer's chat — never part of `-h` output and never reaches agent-facing
 *  stdout (see renderLeafArgv / renderResult, neither of which read this
 *  field). Declared on the leaf that owns the behavior, so the attach viewer
 *  asks the command tree instead of guessing from rendered text. */
export interface PreviewMeta {
    /** When true, the attach viewer collapses this leaf's successful result to
     *  a one-line status by default (still expandable with Ctrl+O). For a
     *  command whose result is a machine-readable dump meant for a browser/tool
     *  rather than a human glance (e.g. a snapshot leaf). Never suppresses a
     *  failed run — errors always show in full. */
    suppressOutput?: boolean;
}
export interface LeafHelp {
    name: string;
    summary: string;
    /** Optional long-form workflow prose rendered immediately after the summary
     *  line. Only plan new / spec new carry this; it precedes the schema. */
    guide?: string;
    params?: InputParam[];
    /** Note appended when there is no input (replaces the Input block). */
    inputNote?: string;
    output: Field[];
    outputKind: 'object' | 'jsonl';
    /** Every persistent change the command makes to the world. For read-only
     *  leaves use exactly: ["None. Read-only."] */
    effects: string[];
    /** Bounded runtime aggregate as a complete self-named state element (build it
     *  with stateBlock), e.g. `<kinds count="7">…</kinds>`. Lazily evaluated at
     *  render time so it reflects the caller's cwd/project scope; appended after
     *  the schema. Renderer soft-fails to omission if it returns null or throws.
     *  Mirrors BranchHelp.dynamicState. */
    dynamicState?: () => string | null;
    /** Attach-viewer preview hint (see PreviewMeta). Optional; omit for the
     *  default preview behaviour. */
    preview?: PreviewMeta;
}
/** Build a self-named runtime-state element: `<tag attr="v">body</tag>`. The
 *  subtree that owns the state authors it through this, so the tag name and any
 *  scalar metadata (e.g. a count) travel with the data and render identically
 *  at every level the block appears. The tag name carries the label, so the
 *  body never repeats it. Attribute values are controlled (counts, short
 *  tokens) and not escaped. */
export declare function stateBlock(tag: string, attrs: Record<string, string | number>, body: string): string;
export declare function renderRoot(h: RootHelp): string;
export declare function renderBranch(h: BranchHelp): string;
export declare function renderLeafArgv(h: LeafHelp): string;