Docs generation and publishing

[mindsocket]

Overview

As config options and schema features grow, maintaining documentation manually across README, docs/, and agent skills becomes increasingly error-prone and labour-intensive. This issue tracks ideas for automating doc generation and making docs publicly accessible.

Ideas

Generation from source

• Plugin config schema → config reference: docs/config.md could be partially generated from MARKDOWN_CONFIG_SCHEMA and other plugin configSchema exports — field names, types, descriptions, and defaults are already machine-readable.
• Schema dialect reference: the metaschema (schemas/generated/_structured_context_schema_meta.json) and $metadata contract (src/metadata-contract.ts) could drive generation of the docs/schemas.md hierarchy/relationship/rules property tables.
• CLI command reference: Commander.js exposes command and option metadata; a generated reference could replace the manually-maintained references/commands.md in the agent skill.

Publishing

• Publish user-facing docs via mindsocket.github.io/structured-context (GitHub Pages). Candidates:
  • README.md
  • docs/concepts.md, docs/config.md, docs/schemas.md, docs/rules.md
  • Generated API/CLI reference
• Could use a static site generator (e.g. VitePress, Docusaurus) or a simple GitHub Pages action on the docs/ folder.

Coverage / evals

• A doc coverage check that asserts every public config field in MARKDOWN_CONFIG_SCHEMA (and any registered plugin schema) has a corresponding entry in docs/config.md.
• A test that verifies the TOPICS map in src/commands/docs.ts only references files that exist (prevents shipping a broken docs command).
• Smoke-test that sctx docs <topic> exits 0 and produces non-empty output for each registered topic.

Related

• Introduced sctx docs [topic] command in #[current PR] which ships docs/ files with the package and routes CLI help to individual doc files.
• docs/config.md currently maintained by hand; obvious first candidate for generation.