My application has grown large and complex. I want you to generate a permanent internal documentation system for this codebase.

Step 1: Create a /docs directory
	•	Create a top-level folder called /docs
	•	Inside /docs, generate one markdown file per major feature, module, or system
	•	Name files clearly, for example:
	•	auth.md
	•	billing.md
	•	ai-engine.md
	•	notifications.md
	•	api.md
	•	etc

⸻

Step 2: Structure of each .md file

Each documentation file MUST contain:

1. Plain-English Overview
	•	What this feature does
	•	Who it’s for
	•	Why it exists
	•	How it impacts the product

2. Why This Matters
	•	Business value
	•	User impact
	•	What breaks if it fails

3. Technical Breakdown
	•	Architecture
	•	Key files and folders
	•	Data flow
	•	APIs used
	•	State management
	•	Edge cases

4. Dependencies
	•	Internal modules
	•	External services
	•	Environment variables
	•	Database tables
	•	Third-party APIs

5. Operational Notes
	•	Known pitfalls
	•	Performance concerns
	•	Security considerations
	•	Scaling risks
	•	Things future devs must not break

6. Change Guidelines
	•	What must be updated if this system changes
	•	Regression risks
	•	Tests to run

⸻

Step 3: Global Design System Documentation

Create a dedicated file:

/docs/design-system.md

This file is mandatory and acts as the UI/UX source of truth.

It must include:

Brand & Visual Rules
	•	Color palette (hex values)
	•	Typography (font families, weights, sizes)
	•	Spacing system
	•	Border radius standards
	•	Shadow usage
	•	Icon set rules

Component Standards
	•	Button styles and hierarchy
	•	Form styling
	•	Cards
	•	Modals
	•	Tables
	•	Alerts
	•	Loaders
	•	Empty states

Layout Rules
	•	Grid system
	•	Breakpoints
	•	Responsive behavior
	•	Mobile vs desktop behavior

UX Principles
	•	Accessibility requirements
	•	Interaction patterns
	•	Error handling
	•	Loading behavior
	•	Animations and transitions

Forbidden Patterns
	•	UI anti-patterns to avoid
	•	Things that must never be changed
	•	Legacy quirks to respect

⸻

Step 4: Enforce /docs as the source of truth

Modify replit.md and add this at the VERY TOP:

🚨 SYSTEM GOVERNANCE RULE

This project uses /docs as its source of truth for:
	•	Architecture
	•	Business logic
	•	API structure
	•	Design system & UI rules

Before making any code or UI changes, the agent MUST:
	1.	Read all relevant /docs files
	2.	Follow documented architecture
	3.	Follow design-system.md
	4.	Update /docs if behavior or UI changes

Any change made without consulting /docs is invalid.
⚠️ CRITICAL: Always check /docs first. All system knowledge lives there.

⸻

Step 5: Future behavior enforcement

From now on, you must automatically search /docs before:
	•	Writing code
	•	Refactoring
	•	Adding features
	•	Fixing bugs
	•	Making UI changes
	•	Introducing new components
	•	Making architectural decisions

If documentation is missing or unclear:
	•	STOP
	•	Ask me before proceeding

⸻

Step 6: Implementation

Scan the entire repo now and:
	•	Identify all major systems
	•	Generate the full /docs structure
	•	Populate every file fully
	•	Create design-system.md
	•	Add the enforcement block to root README

Do not summarize.
Do not skip sections.
Treat this as permanent system memory.