CLI render path surfaces no authoring guidance; component-free pages ship without a hint

[bitgorust]

Summary

Nothing on the CLI path tells an author that component fences exist. render accepts any
Markdown file and produces a component-free prose page without comment, so a long document
renders as a long document.

What happened

An agent session produced an 872-line architecture document, then ran:

npx opencode-artifacts render "…/Settlement Guide.md" --open --version

The result was a 3.4 MB single-column prose page with zero components, published under the
slug artifact (see the separate title-fallback issue). Nothing in the run indicated that
stats, findings, table, compare, timeline, decisions, or the chart fences were
available. The authoring reference was found only by reading
node_modules/opencode-artifacts/skills/artifact-pages/reference/components.md directly.

Root cause

skills/artifact-pages is injected into the session only when the plugin option
proactive: true is set (dist/plugin.js, if (options?.["proactive"] === true)). Without
it, neither the tool description nor the CLI mentions components. The CLI verb render
also frames the operation as converting an existing document, while artifact_publish
frames it as authoring a page. The two framings lead to different output.

Suggestions

1. render --help should link skills/artifact-pages/reference/components.md, which is
   already in the published files list.
2. Print one hint line to stderr when a rendered source has no component fence and no
   frontmatter title. For example: no component fences found; see components.md for stats, findings, table, compare, timeline, decisions.
3. Consider stating in the README that proactive: true is what makes an agent author
   pages rather than convert documents. Today that is discoverable only from the source.

Point 2 is the cheap one. A single line at publish time would have redirected the session
that produced this report.

Environment

opencode-artifacts 0.14.4, Node v24.19.0, OpenCode 1.18.9, macOS 25.5.0.