Artifacts

Product Brief

The product brief is a structured representation of your product extracted from analyzing the codebase. It serves as the foundation for all documentation generation.

{
  "productName": "Git2Docs",
  "oneLiner": "AI-powered documentation from code",
  "targetAudience": "Software development teams",
  "audienceLevel": "intermediate",
  "deploymentModel": "saas",
  "primaryWorkflows": [
    "Connect GitHub repository",
    "Generate documentation",
    "Review and edit content",
    "Publish to custom domain"
  ],
  "keyConcepts": [
    "Documentation spaces",
    "Doc nodes and sections",
    "Ownership states",
    "Confidence tiers"
  ],
  "components": [
    "Worker (documentation engine)",
    "Web app (portal and dashboard)",
    "Database (content storage)"
  ]
}

The brief is stored in the database. In practice you rarely hand-edit it: the Tell AI → Submit Reviewflow on the audit/edit page (and the runtime-validation findings ingest) both write brief patches through the AI consolidator, so the brief converges on what the validator and the maintainer collectively flag as wrong without anyone editing fields by hand.

Documentation Space

A space is a collection of related documentation pages. Each repository can have multiple spaces, such as:

• Getting Started - Onboarding and quickstart guides
• User Guide - In-depth usage documentation
• API Reference - Technical API documentation
• Architecture - System design and concepts

Spaces appear as cards on the documentation portal home page, allowing users to navigate to the documentation they need.

Doc Node

A doc node represents an individual documentation page. Nodes can be organized hierarchically with parent-child relationships.

Doc Types

Each page has a doc type that determines its structure and sections:

• guide - Step-by-step instructions for tasks
• tutorial - Learning-oriented walkthroughs
• concept - Explanations of key ideas
• architecture - System design documentation
• cli_reference - Command-line interface reference
• api_reference - API endpoint or function reference
• runbook - Operational procedures
• changelog - Version history and release notes

Doc Section

Each doc node contains multiple sections. Sections are the granular units of content that can be individually edited and tracked.

Ownership States

• ai_owned - Content generated by AI. Will be updated on regeneration.
• human_owned - Content edited by a human. Protected from AI overwrites.
• contested - AI wants to update human-owned content. Requires resolution.

Section Version

Each section maintains a version history. This enables tracking changes over time and understanding where content came from.

Comment

A piece of maintainer or validator feedback pinned to a specific section in a specific version. The Tell AI button on the audit page creates one; the runtime validator's findings ingest creates one per failed artifact (tagged with source_finding_id). Comments are the structured signal the AI consolidator reads when the maintainer hits Submit Review.

Validation Finding

A behavioural check produced by a validator: an external coding agent running Tier 1, or the worker's built-in Tier 0 static checker. One row per (section_version_id, tier, validator, artifact_kind, artifact_text); re-running a validator replaces its prior findings rather than appending.

Code Artifact

For API reference documentation, Git2Docs extracts code artifacts from your source files using tree-sitter parsing.

• Functions and methods
• Classes and interfaces
• Type definitions
• Constants and exports

Each artifact is tracked with dual hashes for smart change detection between versions.