Governance / Documentation Standards

Document Library Style Guide Draft

Authoritative internal style guide for creating Markdown documents for the company document library, including filename rules, slug and title rules, YAML frontmatter, document scope requirements, description style, heading structure, drafting standards, validation steps, and Codex handoff requirements.

Text size
Status: draftCreated: 2026-06-30Last updated: 2026-06-30

Document Scope

This document defines the required style, structure, metadata, naming, drafting, and validation rules for Markdown documents created for the company document library.

This document is written for human operators, employees, ChatGPT sessions, Codex sessions, AI-assisted development tools, documentation workers, automation workers, and future MCP/RAG workflows that create, update, review, index, or publish internal Markdown documentation.

This document applies to durable Markdown documentation files that are intended to become part of a company document library, internal knowledge base, standards library, runbook collection, process library, architecture library, or documentation-source repository.

This document does not govern temporary scratch notes, raw terminal logs, generated reports, one-time handoff files, source-code comments, customer-facing website copy, legal documents, README files in third-party context repositories, or private chat transcripts unless a task explicitly states that one of those files must follow the document-library standard.

The purpose of this document is to prevent future documentation work from being inconsistent, over-compressed, product-locked, poorly named, weakly described, or difficult for humans and AI agents to reuse. A document created under this standard should be clear enough that a later human, Codex session, ChatGPT session, or automation worker can understand the document’s purpose, scope, and operating rules without needing hidden chat context.

Standard

1. Core Rule

Every document-library Markdown file must be created as a durable internal document, not as a casual note, chat summary, or thin checklist.

A valid document-library Markdown file must have a stable filename, matching slug, clear title, complete YAML frontmatter, a # Document Scope opening section, and a body written in full sentences. The document must explain what it governs, who it is for, what it applies to, what it does not cover, and how it should be used.

The goal is not to make the shortest possible document. The goal is to make a useful document that can teach the relevant process or standard without requiring the reader to ask the original author what was meant.

A document created for the company document library should be written as a future-facing operating asset. It should support human review, AI-agent reading, search indexing, documentation publishing, and later conversion into database records or operational instructions.

2. Filename, Slug, and Title Rules

The filename, slug, and title are connected.

The filename is the slug plus .md.

The slug is the filename without .md.

The title is the slug converted into title case, with hyphens removed and replaced by spaces.

Example:

Filename:
document-library-style-guide.md

Slug:
document-library-style-guide

Title:
Document Library Style Guide

The filename must be lowercase.

The filename must use hyphens instead of spaces.

The filename must not use underscores.

The filename must not include product-specific branding, company-specific branding, temporary project names, or internal abbreviations unless the user explicitly requests that naming.

The filename should usually be no more than 30 characters before .md. This is a practical naming limit intended to keep document names readable, portable, and easy to reference. Do not force awkward names merely to hit exactly 30 characters unless a specific publishing system or user instruction requires an exact character count.

Use names that describe the document’s function.

Good examples:

document-library-style-guide.md
workspace-structure-guide.md
cloudflare-tunnel-to-server.md
local-server-port-allocation-guide.md
git-checkpoint-commit-standard.md
patch-codex-workflows-standard.md

Poor examples:

jh-document-library-style-guide.md
just-headlines-style-guide.md
new-doc-rules.md
stuff-for-codex.md
documentation-final-final.md
guide.md
standard.md

The first two poor examples are product-locked. They create unnecessary future rename work if the company name, product name, or service name changes. The last examples are too vague to serve as durable documentation-library names.

3. Product-Agnostic Naming Rule

Reusable standards must be product-agnostic unless the document is specifically about a product, service, repository, domain, vendor, or named implementation.

Do not put the company name, product name, internal product abbreviation, or service brand into a reusable standards filename merely because the current company uses the document.

A document about the general Markdown document library style should be named:

document-library-style-guide.md

It should not be named:

jh-document-library-style-guide.md
just-headlines-document-style-guide.md

A product-specific name is appropriate only when the document cannot make sense without the product-specific context. For example, a guide that governs a named product’s public website copy may include that product name if the name is the actual subject of the document. A reusable infrastructure, documentation, Git, workspace, patching, or process standard should normally avoid product-specific names.

This rule protects the documentation library from unnecessary future refactoring.

4. Required YAML Frontmatter

Every document-library Markdown file must begin with YAML frontmatter.

The required field set is:

---
title: "Document Title"
slug: "document-title"
description: "Clear full-sentence description of the document."
category: "Governance"
subcategory: "Documentation Standards"
status: "draft"
createdDate: "2026-06-30"
lastUpdated: "2026-06-30"
searchable: true
---

The actual values must be updated for the document being created.

The frontmatter must appear at the very top of the file. There must be no blank lines, comments, or text before the opening ---.

The frontmatter must close with ---. After the closing line, the document body begins.

Do not invent extra frontmatter fields unless the user asks for them or an existing document-library system requires them.

Do not remove required fields merely because a field is not known yet. Use a reasonable placeholder for category or subcategory when necessary, and make the placeholder clear enough for later human review.

5. Frontmatter Field Rules

The title field must contain the document title in title case.

The slug field must exactly match the filename without .md.

The description field must be a full-sentence description that explains what the document governs. It should be specific enough to help search, indexing, AI retrieval, and human review.

The category field should use the best known category at the time the document is created. If the exact category is uncertain, use a reasonable general value and leave the more precise classification for later human review.

The subcategory field should use the best known subcategory at the time the document is created. If the exact subcategory is uncertain, use a reasonable placeholder such as:

subcategory: "CHANGE-ME"

or a reasonable provisional value such as:

subcategory: "Documentation Standards"

The status field should usually be:

status: "draft"

unless the user explicitly says the document should be marked as published, authoritative, retired, superseded, or archived.

The createdDate field must be the date the document is first created.

The lastUpdated field must be updated whenever the document receives a substantive change.

The searchable field should normally be:

searchable: true

Do not treat searchable: true as access control. Searchability is a document-library behavior. It is not a security rule.

6. Description Style

The description should be written as a clear, useful sentence or sentence-like phrase that identifies the document’s operational role.

A weak description merely repeats the title.

A strong description explains what the document is for.

Weak example:

description: "Style guide."

Better example:

description: "Authoritative internal style guide for creating Markdown documents for the company document library, including filename rules, slug and title rules, YAML frontmatter, document scope requirements, description style, heading structure, drafting standards, validation steps, and Codex handoff requirements."

Weak example:

description: "Git rules."

Better example:

description: "Authoritative internal standard for branch-first Git work, verified checkpoint commits, detailed operational commit messages, staging discipline, push rules, and recovery decisions."

Weak example:

description: "Patching workflow."

Better example:

description: "Authoritative internal standard for inspecting, patching, refactoring, verifying, and handing off project file changes through either the standard patch-helper workflow or the bounded Codex-assisted implementation workflow."

The description should not be so long that it becomes a paragraph, but it should include enough context to support search, future indexing, and AI retrieval.

7. Required Opening Section

After the YAML frontmatter, every document-library Markdown file must begin with:

# Document Scope

The # Document Scope section must be written in full sentences.

It should explain:

  1. What the document governs.
  2. Who the document is written for.
  3. What repositories, workflows, systems, files, or processes it applies to.
  4. What it does not cover.
  5. Why the document exists.

The document scope should not be a generic placeholder. It should be tailored to the document.

Example structure:

# Document Scope

This document defines the required style, structure, metadata, naming, drafting, and validation rules for Markdown documents created for the company document library.

This document is written for human operators, employees, ChatGPT sessions, Codex sessions, AI-assisted development tools, documentation workers, automation workers, and future MCP/RAG workflows that create, update, review, index, or publish internal Markdown documentation.

This document applies to durable Markdown documentation files that are intended to become part of a company document library, internal knowledge base, standards library, runbook collection, process library, architecture library, or documentation-source repository.

This document does not govern temporary scratch notes, raw terminal logs, generated reports, one-time handoff files, source-code comments, customer-facing website copy, legal documents, README files in third-party context repositories, or private chat transcripts unless a task explicitly states that one of those files must follow the document-library standard.

The # Document Scope section is important because it prevents later readers and AI agents from applying the document too broadly or too narrowly.

8. Main Body Structure

After # Document Scope, use clear Markdown headings.

A common structure is:

---

# Standard

## 1. Core Rule

## 2. [Topic]

## 3. [Topic]

## 4. [Topic]

Use numbered second-level headings when the document is a standard, guide, runbook, workflow, or process document.

Numbered headings help future AI agents refer to sections precisely. They also make long standards easier for humans to scan.

Do not create heading-only documents. Every heading should be followed by meaningful explanation.

Do not rely on bullets where a full explanation is needed.

Do not use a heading merely because the document looks more structured with many headings. The heading structure should reflect the logic of the document.

9. Writing Style

The writing style must be clear, direct, and complete.

Use full sentences.

Explain the reason for important rules.

Include enough context for a future reader who did not participate in the original chat.

Avoid vague language such as:

Do the usual thing.
Handle this carefully.
Make sure it is good.
Use normal formatting.

Prefer specific language:

Every document-library Markdown file must begin with YAML frontmatter. The slug must exactly match the filename without `.md`, and the title must be the slug converted to title case with hyphens removed.

Do not over-summarize.

Do not over-compress.

Do not strip out context that explains why a standard exists.

Do not turn important operating rules into a thin checklist with no explanation.

Checklists are useful for validation. They are not a substitute for the document itself.

10. Bullets, Numbered Lists, and Tables

Bullets are allowed when they improve readability.

Numbered lists are appropriate for procedures, ordered steps, validation checks, and decision trees.

Tables are appropriate when comparing options, showing field meanings, mapping filenames to slugs and titles, or showing decision conditions.

Do not make the entire document a bullet list. A document-library standard must explain the rule, not merely list fragments.

Good use of bullets:

The handoff file must include:

1. Task completed.
2. Files changed.
3. Validation commands and exact output.
4. Risks and assumptions.
5. Final Git status.

Poor use of bullets:

- Metadata
- Scope
- Title
- Slug
- Validate
- Done

The poor example does not teach the reader anything. It only names topics.

11. Command Blocks

Use fenced code blocks for commands, file paths, YAML examples, terminal output, JSON examples, and exact text templates.

PowerShell commands must begin by changing to the correct directory.

For the current Windows application repository, use:

cd C:\dev\app

For durable documentation that should survive a future workspace move, prefer placeholder notation such as:

<workspace-root>/app

Use literal Windows paths only when writing commands that the user is expected to run on the current Windows machine.

Do not mix placeholder paths and literal paths in the same command block unless the text immediately explains the difference.

12. Path Notation

Durable documentation should avoid hard-coding current-machine absolute paths unless the document is specifically about the current machine.

Use:

<workspace-root>/app
<workspace-root>/admin
<workspace-root>/site
<workspace-root>/server

when writing general documentation.

Use:

C:\dev\app
C:\dev\admin
C:\dev\site
C:\dev\server

when giving current-machine commands or documenting current-machine facts.

The distinction matters because the workspace may later move from Windows to Linux. A durable standard should not require a full rewrite merely because the absolute path changes.

13. Documentation Source Locations

When creating or editing documents for the document library, inspect the existing documentation-source locations when available.

Current documentation-source examples may exist in:

C:\dev\admin\docs_source
C:\dev\site\docs_source

These locations can be used to confirm the current frontmatter pattern, heading style, description style, and document-library conventions.

A Codex or AI-assisted documentation task should use live examples from the relevant repository as the formatting source of truth when possible.

14. Codex Documentation Task Rule

When Codex is asked to create or edit Markdown documentation, the prompt should instruct Codex to read and follow this style guide first.

Standard instruction:

Before creating or editing Markdown documentation, read and follow:
docs/document-library-style-guide.md

If the task is occurring in a different repository, adjust the path to the copy of the style guide available in that repository or provide the style guide text directly in the prompt.

A Codex documentation task should also identify:

  1. The repository path.
  2. The branch.
  3. The exact documents to create or edit.
  4. The allowed files.
  5. The forbidden files.
  6. The source documents to read.
  7. The required validation commands.
  8. The required handoff file.
  9. Whether Codex may stage or commit.

Unless the user explicitly says otherwise, Codex must not stage, commit, push, delete, rename, or move files during a documentation drafting task.

15. Handoff Requirements for Documentation Tasks

When Codex creates or edits document-library Markdown files, it must create a handoff file if the task requires later review by ChatGPT or a human operator.

The handoff file should normally live in a repo-local durable state or handoff location if one exists.

For the current application repository, documentation handoff files should use:

state/

The handoff file must include:

  1. The task completed.
  2. The source files read.
  3. The files changed.
  4. The frontmatter pattern used.
  5. The filename, slug, and title values for each new document.
  6. Confirmation that each document begins with # Document Scope.
  7. Validation commands and exact output.
  8. Checks not run.
  9. Risks and assumptions.
  10. Final Git status.

The handoff file must not claim validation passed unless the validation command was actually run.

The handoff file must not omit unexpected file changes. If unexpected files changed, it must list them and explain why.

16. Validation Requirements

For Markdown documentation work, validation should check both formatting and Git state.

Minimum validation for the current application repository:

cd C:\dev\app

git status --short
git branch --show-current
Get-ChildItem .\docs -File -Filter *.md | Sort-Object Name | Select-Object Name, Length, LastWriteTime
Get-ChildItem .\state -File | Sort-Object Name | Select-Object Name, Length, LastWriteTime
git diff --check
git diff --stat
git status --short

If the documentation is created in a different repository, change the cd path and document locations accordingly.

If a document-library build process exists, run the relevant build or preview validation when appropriate.

Do not run unrelated expensive checks merely because a Markdown file changed.

Do not run application runtime processes, database migrations, Watchdog, Deep Audit, production jobs, or external publishing commands unless the documentation change specifically requires that validation and the user approves it.

17. Commit Readiness for Documentation Files

A documentation file is ready to commit only when:

  1. The filename follows the naming rule.
  2. The slug matches the filename without .md.
  3. The title matches the slug converted to title case.
  4. Required frontmatter is present.
  5. The body begins with # Document Scope.
  6. The document explains its standard or process in full sentences.
  7. The document does not over-compress important context.
  8. The document does not contain unintended product-specific or company-specific naming.
  9. git diff --check passes.
  10. git status --short shows only intended files.
  11. Any required handoff file is present and accurate.

Do not commit documentation merely because the file exists.

A documentation commit should also have a detailed commit message that explains the purpose of the new or changed document, the files changed, the standards added or updated, and the validation performed.

18. Product-Specific Content Inside Documents

A reusable style guide should not include product-specific branding in its filename, slug, or title.

However, the document body may refer to current repositories, current paths, or current examples when those references are necessary for clarity.

When using current project examples, make clear whether they are examples or durable rules.

For example:

The current Windows application repository path is C:\dev\app.

is a current-machine fact.

All future repositories must be named after the current product.

would be an improper product-locked rule.

Use product-specific references only when they are necessary to explain current implementation or when the document specifically governs that product.

19. Supersession and Updates

When a new Markdown document supersedes an older HTML document, the new document should say so clearly if supersession is part of the task.

The new document should preserve older valid guidance unless that guidance is intentionally replaced.

Do not delete old HTML files unless the user explicitly asks.

Do not silently edit old generated HTML files when the task is to create Markdown source documents.

If the document is updated later, update:

lastUpdated: "YYYY-MM-DD"

Do not change createdDate after initial creation.

If the document status changes, update:

status: "published"

or another approved value only when the user or publishing workflow requires it.

20. Common Mistakes to Avoid

Do not create a Markdown document without YAML frontmatter.

Do not create a slug that differs from the filename.

Do not create a title that does not match the slug.

Do not skip # Document Scope.

Do not begin with a generic introduction that fails to define the document’s scope.

Do not use a filename that includes company or product branding for a reusable standard.

Do not over-summarize an older source document into a weak outline.

Do not convert a process into a checklist unless the task specifically asks for a checklist.

Do not assume the category and subcategory are final if the user said they will adjust those manually.

Do not stage, commit, push, publish, or delete files unless the task explicitly allows it.

Do not edit generated HTML when the task is to create Markdown source.

Do not write vague descriptions.

Do not remove useful examples from older documents merely to make the new document shorter.

Do not treat documentation as less important than code. Documentation is part of the operating system of the project.

21. Future AI Session Instruction Block

Use this instruction block when asking an AI assistant or Codex session to create document-library Markdown files:

Before creating or editing Markdown documentation, follow the Document Library Style Guide.

Required rules:
- Use a product-agnostic filename unless the document is specifically about a named product, company, repository, vendor, or implementation.
- The filename must be lowercase and use hyphens.
- The slug must exactly match the filename without `.md`.
- The title must be the slug converted to title case with hyphens removed.
- Include YAML frontmatter with title, slug, description, category, subcategory, status, createdDate, lastUpdated, and searchable.
- Begin the body with `# Document Scope`.
- Write the document in full sentences.
- Do not over-summarize or over-compress.
- Preserve useful context from source documents.
- Use examples and command blocks where they help.
- Do not stage, commit, push, delete, or edit unrelated files unless explicitly instructed.
- Create a handoff file when the task requires later review.
- Run documentation validation and report exact output.

This instruction block does not replace the full style guide. It is only a compact reminder for future tasks.

22. Summary of the Standard

A document-library Markdown file must be stable, searchable, understandable, and reusable.

The filename, slug, and title must agree.

The YAML frontmatter must be complete.

The body must begin with # Document Scope.

The document must explain its subject in full sentences.

Reusable standards must avoid unnecessary company or product branding.

Documentation created for the library should not be a thin summary of chat context. It should be a durable operating document that can be read later by a human, Codex session, ChatGPT session, AI agent, automation worker, or future MCP/RAG system.

The standard exists so future documentation work can be created correctly the first time, without repeatedly rediscovering filename rules, metadata rules, title rules, scope rules, and writing-style expectations.