MokoConsulting/MokoCLI
Public Access
1
0
Fork 0
Code Issues 3 Pull Requests 1 Packages Releases 8 Wiki Activity

docs: update WIKI_STANDARDS

Jonathan Miller
2026-05-10 20:08:44 +00:00
parent 800db37b40
commit 5888124bbf
1 changed files with 112 additions and 91 deletions
Download Patch File Download Diff File Expand all files Collapse all files
WIKI_STANDARDS.md
+112 -91
@@ -22,15 +22,11 @@ Brief description of what this page covers.
## Section 1
Content...
## Section 2
Content...
---
## Related
- [Other Page](Other-Page) -- description
- [External Link](https://...) -- description
---
@@ -38,7 +34,7 @@ Content...
| Revision | Date | Author | Description |
|---|---|---|---|
| 1.0 | YYYY-MM-DD | Author | Initial version |
| 1.0 | YYYY-MM-DD | Moko Consulting | Initial version |
```
### Required elements
@@ -48,8 +44,8 @@ Content...
| Navigation link | First line | `[← Back to Home](Home)` |
| H1 title | After nav | Page title matching the wiki page name |
| Description | After title | 1-2 sentence summary |
| Horizontal rules | Between major sections | `---` separators for visual clarity |
| Related section | Before footer | Links to related pages and external resources |
| Horizontal rules | Between major sections | `---` separators |
| Related section | Before footer | Links to related pages |
| Metadata footer | Last lines | Repo link, MokoStandards link, revision table |
---
@@ -68,71 +64,40 @@ Every repo wiki must have a Home page with:
| Related wikis | Recommended | Links to related project wikis |
| MokoStandards backlink | Yes | Link to moko-platform wiki Home |
### Info table format
```markdown
| Field | Value |
|---|---|
| **Type** | MCP Server / Joomla Template / Joomla Plugin / etc. |
| **Language** | PHP / TypeScript / Bash |
| **License** | GPL-3.0-or-later |
| **Platform** | [Gitea](repo-url) · [GitHub](mirror-url) |
```
---
## Content Guidelines
### Formatting
| Rule | Example |
| Rule | Description |
|---|---|
| Use tables for structured data | Not bullet lists for key-value pairs |
| Use code blocks for commands | `` `make build` `` or fenced blocks |
| Use headers for sections | H2 for major sections, H3 for subsections |
| Use horizontal rules between sections | `---` |
| No emojis in headers | Use plain text |
| Em dashes | Use `--` not unicode `—` |
| Tables for structured data | Not bullet lists for key-value pairs |
| Code blocks with language | ` ```bash `, ` ```json `, ` ```php ` |
| Headers for sections | H2 for major, H3 for subsections |
| Horizontal rules | `---` between major sections |
| No emojis in headers | Plain text only |
| Em dashes | Use `--` not unicode |
### Writing style
- **Concise** -- lead with the answer, not the explanation
- **Scannable** -- headers, tables, and short paragraphs
- **Accurate** -- built from actual source code, not assumptions
- **Actionable** -- include commands, file paths, and examples
- **Concise** -- lead with the answer
- **Scannable** -- headers, tables, short paragraphs
- **Accurate** -- built from source code, not assumptions
- **Actionable** -- include commands, file paths, examples
- **Current** -- update when code changes
### Code blocks
Always specify the language:
````markdown
```bash
make build
```
```json
{"key": "value"}
```
```php
$app = Factory::getApplication('site');
```
````
---
## Page Categories
Organize wiki pages into these standard categories on the Home page:
| Category | Content |
|---|---|
| **Guides** | Step-by-step tutorials (Installation, Configuration, Getting Started) |
| **Reference** | Technical reference (API, Tools, CSS Variables, Endpoints) |
| **Operations** | Operational procedures (Backup, Restore, Monitoring, Troubleshooting) |
| **Architecture** | System design (Architecture, How It Works, Data Flow) |
| **Development** | Contributing (Development, Release Process, Testing) |
| **Guides** | Installation, Configuration, Getting Started |
| **Reference** | API, Tools, CSS Variables, Endpoints |
| **Operations** | Backup, Restore, Monitoring, Troubleshooting |
| **Architecture** | System design, How It Works, Data Flow |
| **Development** | Contributing, Release Process, Testing |
---
@@ -140,8 +105,8 @@ Organize wiki pages into these standard categories on the Home page:
| Type | Format | Example |
|---|---|---|
| Guide pages | Title case, hyphenated | `Installation`, `Getting-Started` |
| Reference pages | UPPER_CASE for standards | `WIKI_STANDARDS`, `MINIFICATION` |
| Guide pages | Title case | `Installation`, `Getting-Started` |
| Reference pages | UPPER_CASE | `WIKI_STANDARDS`, `MINIFICATION` |
| Technical pages | Title case | `Architecture`, `Configuration` |
| Compound names | Hyphenated | `Custom-Themes`, `Backup-Recovery` |
@@ -149,13 +114,7 @@ Organize wiki pages into these standard categories on the Home page:
## Metadata Footer
Every page ends with a metadata footer containing:
1. **Repo link** -- link to the source repository
2. **MokoStandards link** -- link to the central standards wiki
3. **Revision history table** -- tracks changes to the page
### Format
Every page ends with:
```markdown
---
@@ -165,45 +124,106 @@ Every page ends with a metadata footer containing:
| Revision | Date | Author | Description |
|---|---|---|---|
| 1.0 | 2026-05-09 | Moko Consulting | Initial version |
| 1.1 | 2026-05-10 | Moko Consulting | Added troubleshooting section |
```
### Rules
- Increment minor version for content updates (1.0 → 1.1)
- Increment major version for restructuring (1.x → 2.0)
- Author is always "Moko Consulting" for org work
- Date is ISO format (YYYY-MM-DD)
---
## Wiki Health Requirements
## Required Repository Files
The `check_wiki_health.php` validation checks:
Per the repo health check (`check_repo_health.php`), every repo must have:
| Check | Requirement |
### Required (positive points)
| File | Points | Purpose |
|---|---|---|
| `README.md` | 8 | Project overview (mirrors wiki Home) |
| `LICENSE` | 8 | GPL-3.0-or-later |
| `CHANGELOG.md` | 5 | Release history with [Unreleased] section |
| `CLAUDE.md` | 5 | Claude Code context (project overview, commands, architecture, rules) |
| `CONTRIBUTING.md` | 4 | Contribution guidelines |
| `SECURITY.md` | 4 | Security policy |
| `.gitignore` | 3 | Must include: `.claude/`, `TODO.md`, `*.min.css`, `*.min.js` |
| `Makefile` | 3 | Build targets (minify, build, release) |
### Disallowed (flagged if present)
| File | Reason |
|---|---|
| Home page exists | Required |
| MokoStandards backlink | Required on Home page |
| Page count | At least 1 (Home) |
| Navigation links | `[← Back to Home](Home)` on all non-Home pages |
| Metadata footer | Repo link + revision table on all pages |
| `TODO.md` | Use issue tracker, not committed files |
| `.claude/` | Local workspace config |
| `.mcp.json` | Local MCP config |
| `renovate.json` | Removed from ecosystem |
| `profile.ps1` | Local PowerShell profile |
| `vendor/` | Install via composer, don't commit |
| `node_modules/` | Install via npm, don't commit |
| `.env` / `credentials.json` | Secrets never committed |
### Manifest
Every repo must have `.gitea/.moko-platform` XML manifest with:
- Identity (name, org, description, license)
- Governance (platform type, standards version)
- Build (language, package type, entry point)
---
## CLAUDE.md Standard
Every repo must have a `CLAUDE.md` that provides context to Claude Code:
```markdown
# CLAUDE.md
This file provides guidance to Claude Code when working with this repository.
## Project Overview
**RepoName** -- description
| Field | Value |
|---|---|
| **Platform** | joomla / dolibarr / mcp-server / client / template / generic |
| **Language** | PHP / TypeScript / Shell |
| **Default branch** | main or dev |
| **Wiki** | [Wiki link](wiki-url) |
| **Standards** | [MokoStandards](moko-platform-wiki-url) |
## Common Commands
(make targets, npm scripts, composer commands)
## Architecture
(key directories and files for this platform type)
## Rules
- Never commit .claude/, .mcp.json, TODO.md, *.min.css/js
- Attribution: Authored-by: Moko Consulting
- Branch strategy: dev → main
- Standards: MokoStandards
```
---
## Repo Health Check
The `check_repo_health.php` script validates repos against these standards:
| Category | Points | Checks |
|---|---|---|
| Required Files | 40 | README, LICENSE, CHANGELOG, CONTRIBUTING, SECURITY, CLAUDE.md, .gitignore, Makefile |
| Manifest & Config | 20 | .moko-platform, workflows, README quality, .gitignore content, CLAUDE.md quality |
| Documentation | 15 | No docs/ (wiki-first), CHANGELOG [Unreleased] |
| Disallowed | 10 | No TODO.md, vendor/, node_modules/, .claude/, .mcp.json, renovate.json, profile.ps1 |
| Workflows | 15 | repo-health, sync-roadmap-wiki, CI/deploy |
| Security | 20 | SECURITY.md, scanning workflow, no renovate.json, no secrets |
| Rulesets | 15 | Main protected, dev branch, branch protections |
| Deployment | 10 | Deploy workflow, build system |
Threshold: 70% to pass.
---
## GitHub Mirror
All wikis are backed up daily to [mokoconsulting-tech/wiki](https://github.com/mokoconsulting-tech/wiki) on GitHub via `sync-wikis-to-github.sh` (runs daily at 5am UTC).
Structure:
```
wiki/
README.md (auto-generated index)
moko-platform/ (30+ pages)
MokoOnyx/ (9 pages)
monitor-mcp/ (6 pages)
...
```
All wikis are backed up daily to [mokoconsulting-tech/wiki](https://github.com/mokoconsulting-tech/wiki) on GitHub via `sync-wikis-to-github.sh` (runs daily at 5am UTC). Auto-discovers all repos with wikis across all orgs.
---
@@ -219,4 +239,5 @@ wiki/
| Revision | Date | Author | Description |
|---|---|---|---|
| 1.0 | 2026-05-09 | Moko Consulting | Initial wiki standards document |
| 1.0 | 2026-05-09 | Moko Consulting | Initial wiki standards |
| 2.0 | 2026-05-10 | Moko Consulting | Added CLAUDE.md standard, repo health check details, required/disallowed files |