Documentation Standards

This is the current, authoritative documentation standards page. For the legacy version, see Documentation-Standards (legacy).

Repo Health Scoring (135 points)

Category	Points	Checks
Required Files	40	README (8), LICENSE (8), CHANGELOG (5), CONTRIBUTING (5), SECURITY (5), profile.ps1 (4), .mcp.json (3), .gitignore (2)
Manifest & Config	15	.moko-platform manifest (5), workflows dir (5), README >500 chars (3), CODE_OF_CONDUCT (2)
Documentation	10	No docs/ directory -- wiki-first (10)
Disallowed	10	No TODO.md (5), no vendor/ (3), no node_modules/ (2)
Workflows	15	Workflows dir (5), repo-health.yml (3), sync-roadmap-wiki.yml (3), CI/deploy workflow (4)
Security	20	SECURITY.md (5), scanning workflow (5), dependency mgmt (5), no secrets (5)
Rulesets	15	Main protected (5), dev branch exists (5), rulesets configured (5)
Deployment	10	Deploy workflow (5), build system (5)

Health Levels

Level	Score
Excellent	90%+
Good	80-89%
Fair	70-79%
Poor	60-69%
Critical	<60%

Wiki-First Policy

Rule	Enforcement
`docs/` in repos	NOT ALLOWED -- 10 point deduction
Documentation location	Gitea wiki per repo
DOCS_INDEX	Removed -- not checked
CHANGELOG search	Root and src/ only

Required Files

Every repo must have:

README.md -- project overview (>500 chars for full points)
LICENSE -- GPL-3.0-or-later
CHANGELOG.md -- version history
CONTRIBUTING.md -- contribution guidelines
SECURITY.md -- security policy
profile.ps1 -- auto-generated PowerShell profile
.mcp.json -- auto-generated MCP config
.gitignore
.gitea/.moko-platform -- repo manifest
.gitea/workflows/ -- CI/CD workflows

Disallowed

docs/ -- use wiki
TODO.md -- use Gitea issues
vendor/ -- gitignored, not committed
node_modules/ -- gitignored
.env / secret files -- never committed

Required Workflows

repo-health.yml -- validates against these standards
sync-roadmap-wiki.yml -- auto-generates roadmap from project board
At least one CI/deploy workflow

Branching

Branch	Purpose
`main`	Stable production release
`dev`	Integration (always ahead of main)
`feature`	Active feature development (merges to dev)
`version`	Version preparation and staging
`beta`	Beta testing channel
`alpha`	Alpha testing channel
`feature/*`	Named feature branches (merge to dev)
`fix/*`	Bug fix branches (merge to dev)
`hotfix/*`	Urgent fixes (merge to dev or main)
`rc/*`	Release candidates (merge to main)

Feature branches never bump version numbers.

Running the Check

php validate/check_repo_health.php --path /a/MokoCRM
php validate/check_repo_health.php --path /a/MokoCRM --repo MokoConsulting/MokoCRM --json
php validate/check_repo_health.php --path /a/MokoCRM --repo MokoConsulting/MokoCRM --create-issue

ARCHITECTURE -- Platform scripts architecture
WORKFLOW_STANDARDS -- CI/CD workflow conventions

Repo: moko-platform · moko-platform wiki

Field	Value
Minimum Version	04.07.00
Platform	all
Applies To	All repositories

Revision	Date	Author	Description
1.0	2026-05-09	Moko Consulting	Initial version

Documentation Standards

Repo Health Scoring (135 points)

Health Levels

Wiki-First Policy

Required Files

Disallowed

Required Workflows

Branching

Running the Check

Related