plugin-docs


Placement	runtime (out-of-process over gRPC)
Source	`github.com/opencharly/plugin-docs/candy/plugin-docs`
Version	`2026.215.1140`
Candy	`plugin-docs`

This plugin is not listed in charly/charly.yml’s compiled_plugins:. It is not part of the shipped binary: charly builds and loads it out-of-process over gRPC when a plan references one of its words (the coexist path).

Providers

The reserved words this plugin serves:

docs — command class

What it does

RUNTIME (out-of-process) charly plugin serving charly docs … — the generator that renders the reference half of the opencharly.ai documentation site from this repo’s canonical sources: VISION.md, the plugins submodule’s skill corpus, every candy and box charly.yml, and every plugin candy’s plugin: block plus CUE schema.

PLACEMENT — deliberately NOT listed in charly/charly.yml compiled_plugins. This is a DEV-TIME documentation generator, run on a contributor’s machine to regenerate the site and nowhere else, so it has no business inside every shipped static charly binary. charly prescans the declared docs word into the Kong grammar before parse and syscall.Exec’s this binary in CLI mode on the first actual charly docs invocation. The generator is self-contained — it reads files and writes markdown, never reaching the host reverse channel — which is what makes the out-of-process placement free here (the same property that lets charly candy and charly migrate run in either placement). Being a runtime plugin also makes this candy its own worked example of the placement, on a site that documents exactly that.

WHAT IT GENERATES — one page per skill (plus each references/*.md split file, with every /charly-<plugin>:<skill> cross-reference rewritten to a site link and any unresolvable one failing the build); one page per plugin candy carrying its providers, its placement COMPUTED from compiled_plugins membership, and its rendered CUE parameter schema; a provider cross-index mapping every reserved word to the plugin that serves it; one page per defined candy and box; and VISION.md with its H1 dropped and links rewritten for the web.

DEFINED, NOT DEFAULT-ACTIVE — the catalog walks each repo (the superproject plus every box/ submodule) as its own project root and unions the results, rather than resolving through main’s import: closure. That closure pulls arch, cachyos and fedora only, so a catalog built on it silently omits every debian.* and ubuntu.* box while duplicating ten arch boxes under transitive cachyos.arch.* aliases.

Parameter schema

The CUE schema below is the authoritative grammar for this plugin’s input. It is the same single source that generates the plugin’s Go parameter types and answers the runtime Describe RPC, so this page cannot disagree with either.

`schema/docs.cue`

// plugin-docs's OWN self-contained CUE schema — the plugin's declaration
// surface, used two ways exactly like every other plugin's schema (there is
// no schema-less plugin):
//
//  1. SERVE over Describe — the host splices `base ++ plugin` at the load gate, so the
//     plugin's declarations travel WITH it and a self-contained schema that will not
//     splice is a LOUD load failure.
//  2. DOCUMENT the plugin's published surface — the reference site's per-plugin page is
//     rendered from its providers, this schema, and the candy description.
//
// command:docs's authored input is its pass-through CLI grammar (the OpRun `{args:
// [...]}` envelope), so this schema DOCUMENTS the command contract rather than a
// structured plugin_input. SELF-CONTAINED: it references no base def, so it compiles
// STANDALONE (the property that lets the SDK compile it serve-side).
#DocsPlugin: {
  // The declared capability words (the plugin.providers surface), recorded here as
  // part of the plugin's published declaration surface.
  providers: [...string]

  // The command word the plugin serves.
  command: "docs"

  // The subcommands of the `charly docs` CLI tree.
  subcommands: ["generate"]

  // What the command does, in one line (the public-docs surface).
  contract: string & !=""

  // The configuration surface: env var names the plugin reads, recorded here as part
  // of the plugin's published declaration surface.
  config?: [string]: string
}

See also the candy reference for this candy’s install surface.