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 human reference pages in docs/reference/ each hold one generated region rewritten wholesale (internal/docgen/page.go).

Only text between the generated markers is rewritten; see internal/docgen for what is deliberately NOT generated.

A command with no block yet is reported, not placed: ordering in these documents carries meaning, so the generator prints the block to paste and TestReferenceDocsConform fails until it is placed.

The tree comes from internal/clitest.FullTree, which the build gates also walk. Importing "clitest" from a 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.