---
inclusion: fileMatch
fileMatchPattern: "**/*"
---

# Component Documentation Standard

## COMPONENT.md Requirement

Every repo, tool, or subfolder that represents a distinct component in this monorepo MUST have a `COMPONENT.md` file at its root. This is the single source of truth for metadata that cannot be derived from dependency files.

## When to Create

- When creating a new project via `ctx-guard create-project`
- When adding a new repo to any context folder
- When onboarding an existing repo into the monorepo

## Required Format

```markdown
# Component: {name}

## Description
{1-2 sentence description of what this component does}

## Metadata
- **Deployment Target:** {one of: vps-docker, local-mcp-stdio, docker-mcp-http, gitlab-ci, local-cli, local-docker, content-library, file-based, none, planned}
- **Upstream URL:** {URL or "monorepo-internal"}
- **Status:** {active, needs-redo, planned, archived}

## Interconnections
{bullet list of connections, format: "- **{direction}** {target}: {description}"}
{directions: polls, consumed-by, provides-to, queries, integrates-with, shares-infra, listed-in, references, feeds, sources-from, related-to, used-by, manages}

## Notes
{any additional operational context — domains, ports, CI details, constraints}
```

## Scanner Integration

The `ctx-guard components scan` command reads COMPONENT.md files to populate registry fields that cannot be derived from dependency files:
- `description` <- from ## Description section
- `deployment-target` <- from Metadata -> Deployment Target
- `upstream-url` <- from Metadata -> Upstream URL
- `status` <- from Metadata -> Status (overrides scanner default of "active")

## Architecture Overview

The `docs/architecture-overview.md` is auto-generated from the component registry. It is NOT manually maintained. To update it, run a scan and the overview regenerates with current data including interconnections from COMPONENT.md files.

## Rules

1. COMPONENT.md is the source of truth for operational metadata — not requirements.md or design.md
2. Keep it current: update COMPONENT.md when deployment targets, interconnections, or status change
3. Requirements/design specs describe the *planned* state at spec time; COMPONENT.md describes the *current* state in production
4. The architecture overview is derived, never hand-edited