Skip to content

Fail docs CI when a page names a marfa command or flag that does not exist #580

Closed

Description

@aicayzer

Summary

Fail the docs CI when a page names a marfa command or flag that the command reference does not list.

Context

STYLE.md ("Examples") says every example must be checked against a real instance. I found no automated check for it: the content lint (src/lib/content-lint.test.ts) covers links, glossary terms, dashes and frontmatter, not code. An agent follows a documented command literally, so a flag that does not exist wastes its next step. The generated command reference is core/marfa-cli/COMMANDS.md in withmarfa/marfa, and the docs sync brings the CLI's global options and exit codes across.

Acceptance criteria

  • A test reads the code blocks and inline code of every page, finds each marfa <command> [subcommand] and each --flag that follows one, and fails when the command reference lacks it.
  • A page can mark a block as another tool's command or as an intentional counterexample, and the marker is documented in STYLE.md.
  • The test names the page, the line and the missing command or flag.
  • Today's pages pass, or each failure it finds is fixed in the same pull request.

Out of scope

  • Running the examples against a live instance.

Notes

The sync script copies only what marfa generates. If the full command tree is not available in the docs repository, the first step is to sync it from COMMANDS.md, by the same rules as the other generated files (AGENTS.md, "Syncing from marfa").

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions