# AI Chat Project Documentation Standard

This document defines the documentation structure, file naming policy, and minimum documentation requirements for a production AI chat application.

## Naming Standard

### Project-Owned Files and Directories

Use these rules for all project-created files and directories:

- Use lowercase ASCII names.
- Use `kebab-case` to separate words.
- Do not use spaces.
- Do not use underscores (`_`) unless required by an external tool.
- Do not use tildes (`~`) in filenames; `~` has shell meaning.
- Do not use special characters such as `&`, `?`, `!`, `:`, quotes, or parentheses.
- Use ISO dates when needed: `YYYY-MM-DD-description.md`.
- Do not rely on case-insensitive filesystem behavior.

Examples:

```text
prompt-architecture.md
model-provider-outage.md
data-classification.md
2026-08-11-release-notes.md
```

### Conventional Root Files

Keep these established repository filenames exactly as shown:

```text
README.md
AGENTS.md
CONTRIBUTING.md
SECURITY.md
CHANGELOG.md
LICENSE.md
CODE_OF_CONDUCT.md
```

### Tool-Recognized Directories

Do not rename tool-recognized paths without confirming the relevant tool supports the change:

```text
.github/
.github/ISSUE_TEMPLATE/
```

## Recommended Layout

```text
.
├── README.md
├── AGENTS.md
├── CONTRIBUTING.md
├── SECURITY.md
├── CHANGELOG.md
├── LICENSE.md
├── CODE_OF_CONDUCT.md
│
├── docs/
│   ├── project.md
│   ├── architecture.md
│   ├── development.md
│   ├── configuration.md
│   ├── deployment.md
│   ├── operations.md
│   ├── troubleshooting.md
│   ├── testing.md
│   ├── api.md
│   ├── database.md
│   ├── ui-ux.md
│   │
│   ├── ai/
│   │   ├── ai-overview.md
│   │   ├── model-policy.md
│   │   ├── prompt-architecture.md
│   │   ├── rag.md
│   │   ├── tools-and-actions.md
│   │   ├── evaluations.md
│   │   ├── safety-and-guardrails.md
│   │   ├── ai-observability.md
│   │   ├── cost-management.md
│   │   └── incident-response.md
│   │
│   ├── security/
│   │   ├── threat-model.md
│   │   ├── data-classification.md
│   │   ├── privacy.md
│   │   ├── authorization.md
│   │   └── secrets.md
│   │
│   ├── adr/
│   │   ├── README.md
│   │   └── 0001-architecture-decision-template.md
│   │
│   ├── runbooks/
│   │   ├── README.md
│   │   ├── deploy.md
│   │   ├── rollback.md
│   │   ├── model-provider-outage.md
│   │   ├── vector-store-outage.md
│   │   ├── prompt-injection-event.md
│   │   └── data-deletion-request.md
│   │
│   └── product/
│       ├── requirements.md
│       ├── user-flows.md
│       ├── acceptance-criteria.md
│       └── roadmap.md
│
└── .github/
    ├── pull-request-template.md
    └── ISSUE_TEMPLATE/
        ├── bug-report.md
        ├── feature-request.md
        └── security-issue.md
```

## Required Root Documents

| Document | Purpose |
|---|---|
| `README.md` | Project purpose, users, installation, run/test commands, and documentation index |
| `AGENTS.md` | AI-agent instructions, commands, conventions, architectural rules, testing, and documentation-update requirements |
| `CONTRIBUTING.md` | Branches, commits, pull requests, code review, local setup, and coding standards |
| `SECURITY.md` | Vulnerability reporting, supported versions, secret-handling rules, and security response policy |
| `CHANGELOG.md` | User-visible releases, changes, fixes, deprecations, and security updates |
| `LICENSE.md` | Use, modification, and distribution terms |

## Required Core Documents

| Document | Purpose |
|---|---|
| `docs/project.md` | Scope, users, stakeholders, non-goals, success metrics, and terminology |
| `docs/architecture.md` | Components, data flows, dependencies, trust boundaries, deployment topology, and failure paths |
| `docs/development.md` | Bootstrap steps, runtime requirements, `.env` setup, migrations, seed data, linting, and testing |
| `docs/configuration.md` | Configuration and environment variables, defaults, valid values, sensitivity, and environment use |
| `docs/deployment.md` | Build, deployment, migrations, health checks, rollback, and post-deploy validation |
| `docs/operations.md` | Ownership, alerts, dashboards, backups, retention, maintenance, capacity, and service objectives |
| `docs/troubleshooting.md` | Symptoms, diagnostics, likely causes, remediation, and escalation paths |
| `docs/testing.md` | Unit, integration, end-to-end, security, regression, and release testing strategy |
| `docs/api.md` | Authentication, endpoints, schemas, streaming, errors, rate limits, pagination, and versioning |
| `docs/database.md` | Schema, migrations, indexes, tenancy, audit logs, retention, backups, and restore procedure |

## Required AI Documents

| Document | Purpose |
|---|---|
| `docs/ai/ai-overview.md` | AI request lifecycle from input validation through output checks and audit logging |
| `docs/ai/model-policy.md` | Approved providers/models, routing, fallbacks, versioning, token limits, retries, and timeouts |
| `docs/ai/prompt-architecture.md` | Prompt layers, variables, versions, ownership, injection boundaries, and regression-test linkage |
| `docs/ai/rag.md` | Source documents, ingestion, chunking, embeddings, retrieval, citations, freshness, and deletion propagation |
| `docs/ai/tools-and-actions.md` | Tool schemas, authorization, confirmation, rate limits, idempotency, audits, and failure behavior |
| `docs/ai/evaluations.md` | Evaluation data, expected behavior, graders, quality thresholds, regressions, and release gates |
| `docs/ai/safety-and-guardrails.md` | Prompt-injection defenses, input/output controls, refusals, escalation, and human-review rules |
| `docs/ai/ai-observability.md` | Request IDs, model/prompt versions, retrievals, tool calls, token use, latency, metrics, errors, and redaction |
| `docs/ai/cost-management.md` | Budgets, quotas, caching, routing, usage tracking, alerts, and emergency shutoff |
| `docs/ai/incident-response.md` | Response to data leakage, unsafe output, injection, provider outage, regression, excess cost, and tool misuse |

## Required Security Documents

| Document | Purpose |
|---|---|
| `docs/security/threat-model.md` | Assets, actors, trust boundaries, threats, mitigations, residual risks, and review dates |
| `docs/security/data-classification.md` | Public, internal, confidential, regulated, and secret data classification and handling |
| `docs/security/privacy.md` | Collected data, storage, encryption, retention, deletion, access, and third-party provider handling |
| `docs/security/authorization.md` | Authentication, roles, permissions, tenant isolation, tool permissions, and access review |
| `docs/security/secrets.md` | Secret storage, rotation, revocation, access, and prohibited practices |

## Required Runbooks

| Runbook | Purpose |
|---|---|
| `docs/runbooks/deploy.md` | Execute a safe production deployment and validate health |
| `docs/runbooks/rollback.md` | Roll back application, migration, configuration, prompt, or model changes |
| `docs/runbooks/model-provider-outage.md` | Handle provider errors, outages, quotas, and model fallbacks |
| `docs/runbooks/vector-store-outage.md` | Handle embedding, retrieval, index, or vector-store failures |
| `docs/runbooks/prompt-injection-event.md` | Investigate and contain suspected prompt injection or unauthorized tool behavior |
| `docs/runbooks/data-deletion-request.md` | Delete applicable account, chat, upload, embedding, and audit data |

## Optional Documents

| Document | Add when |
|---|---|
| `docs/adr/*.md` | Important architecture decisions need an auditable record |
| `docs/product/requirements.md` | Product behavior needs a stable specification beyond tickets |
| `docs/product/user-flows.md` | User journeys or permission flows become complex |
| `docs/product/acceptance-criteria.md` | Features require stable engineering and QA expectations |
| `docs/product/roadmap.md` | Delivery plans need formal documentation |
| `docs/accessibility.md` | Accessibility requirements apply |
| `docs/integrations.md` | The application uses third-party services or internal APIs |
| `docs/multitenancy.md` | Multiple organizations require tenant isolation or billing boundaries |
| `docs/performance.md` | Latency, concurrency, streaming, or capacity targets require documentation |
| `docs/disaster-recovery.md` | Recovery objectives, restore drills, or regional/provider failures matter |
| `docs/compliance.md` | Compliance requirements such as SOC 2, HIPAA, GDPR, or PCI DSS apply |
| `docs/data-retention.md` | Chats, uploads, embeddings, logs, and backups have different retention policies |
| `docs/glossary.md` | AI, product, or business terminology needs consistent definitions |
| `docs/releases.md` | Releases use feature flags, staged rollout, formal approval, or release notes |

## Documentation Rules

- Keep documentation in version control with application source code.
- Update documentation in the same pull request as relevant code, schema, prompt, model, infrastructure, or policy changes.
- Assign an owner and review date for architecture, security, AI, operations, and runbook documents.
- Never store production credentials, API keys, customer records, private certificates, or unredacted production prompts in documentation.
- Link this document from `README.md` and `AGENTS.md`.
- Treat AI prompts, tool definitions, evaluation data, model policy, and guardrail policy as version-controlled production assets.