57 lines
2.3 KiB
Markdown
57 lines
2.3 KiB
Markdown
---
|
|
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
|