Narrative Commands

The narrative command group manages implementation narratives for controls. Narratives describe how a specific control is implemented within your system.

Create Local Narrative

pretorin narrative create ac-02 fedramp-moderate \
  -c "- RBAC enforced via IdP\n\n\`\`\`yaml\nroles:\n  admin: ...\n\`\`\`"

Creates a local markdown file at narratives/<framework>/<control>/<slug>.md with YAML frontmatter. Markdown is validated at create time (same rules as push).

Options:

• --content / -c — Narrative content (required)
• --name / -n — Custom name (defaults to <control>-<framework>)
• --ai-generated — Mark the narrative as AI-generated

List Local Narratives

pretorin narrative list
pretorin narrative list --framework fedramp-moderate

Displays a table of local narrative files: Control, Framework, Name, AI Generated, Synced.

Push Narratives

pretorin narrative push --dry-run
pretorin narrative push

Batch-pushes all unsynced local narratives to the platform. After a successful push, the local file’s platform_synced frontmatter is set to true.

Get Current Narrative

pretorin narrative get ac-02 fedramp-moderate --system "My System"

Returns the current narrative text, status, and AI confidence metadata when present.

Push a Single File (Legacy)

pretorin narrative push-file ac-02 fedramp-moderate "My System" narrative-ac02.md

Reads a markdown or text file and submits it as the implementation narrative for the specified control.

Markdown Quality Requirements

Narratives must be auditor-ready markdown:

• No section headers, including Markdown headings or standalone bold labels; start directly with substantive content
• At least one structural element — a code block, table, or list (prose plus a single one is enough)
• No markdown images (temporarily disabled pending platform image upload support)

These requirements are validated at create time and before push.

Generating Narratives with AI

To generate narratives using the agent runtime:

pretorin agent run --skill narrative-generation "Generate narrative for AC-02"

Or use the MCP server’s generate_control_artifacts tool for read-only drafts through your AI agent.

See Skills for more on agent-powered narrative generation.

For single-control agent work, evidence-to-expectation mapping is a required precondition to narrative drafting. The agent binds each evidence artifact to a stable key from get_control_context.expectation_coverage, records any artifact that is intentionally unbound with a reason, and rereads coverage before it writes. Evidence IDs cited in prose provide traceability, but citations alone do not mark an expectation covered.

Saving a narrative does not request an AI review by default. The agent may set trigger_review=true only when the user explicitly asks for review; that request also carries review_requested_by_user=true. If mapping was skipped, the tool refuses an automatic review and an explicit user-requested override returns a visible coverage warning instead of hiding the incomplete mapping.

Agent-generated control narratives use a stronger quality profile than the general CLI Markdown validator: target 150–300 words, require at least 800 characters, never exceed 400 words, open with a short implementation overview, include an Expectation | Implemented behavior | Evidence table, and add concise supported operating detail. A few bullets alone are not accepted. Built-in AI drafting gets one focused repair attempt, then fails explicitly if the revised narrative is still short or lacks the table.

No-Hallucination Requirements

Generated narratives must only document observable facts:

• Treat existing Pretorin narratives, issues, and status fields as a starting point, not proof that a control gap exists.
• Before writing a narrative update or issue, inspect the relevant implementation in the workspace and connected systems.
• If observed implementation is stronger than the current platform record, update the narrative to match the observed implementation and record any remaining evidence gap as an issue.
• Do not include gap lists, missing-information placeholders, unresolved caveats, or remediation backlog in narrative text.