gendocs

Overview ¶

Command gendocs regenerates the AI-agent reference documents from the live cobra tree. Run it with `make docs`.

There is one index, one index page per module and product sub-tree, and one page per resource below those (database one level further), each owning exactly the commands in its scope. A command belongs to the longest scope that prefixes its path, so byoc's index holds `pgedge starfleet byoc` itself and llms/database/mcp.txt holds the mcp sub-tree. The page set is derived from the files each module embeds (internal/reference), never listed here:

llms.txt                                       everything not under a module
internal/starfleet/llms.txt                    pgedge starfleet (index)
internal/starfleet/llms/client.txt             pgedge starfleet client ...
internal/starfleet/byoc/llms/database/mcp.txt  pgedge starfleet byoc database mcp ...

The same scopes also project onto the human reference pages in docs/reference/, one page per scope, each a single generated region rewritten wholesale — internal/docgen/page.go has the contract and the reasoning.

It rewrites only the text between the generated markers; every other line is hand-written and is left alone. See internal/docgen for the contract and for what is deliberately NOT generated.

A command with no block yet is reported, not placed. The generator will not guess where a section belongs in a document whose ordering carries meaning — it prints the block to paste, and stops. TestReferenceDocsConform fails until it is done, so a forgotten placement cannot ship.

The command tree is built through internal/clitest.FullTree, which is also what the build gates walk. Importing a package named "clitest" from a production tool reads oddly, but the alternative is a third copy of "root plus every registered module" that can drift from the two that already have to agree.