Authoring Documentation

All project documentation lives in the docs/ directory. The docfront CLI lets both humans and AI agents discover and read documents without leaving the terminal.

Browsing with CLI

Run commands via the project's package manager (e.g. npm run docfront --, pnpm docfront).

docfront                                          # list root docs
docfront --dir topic-a --dir topic-b/sub-topic-c  # list subdirectories
docfront --recursive                              # list everything
docfront --read doc-1.md topic-a/doc-2.md         # read documents (frontmatter stripped)
docfront --check                                  # validate all files

Workflow

1. Understand the Subject — clarify what needs to be documented. Ask the user if unclear.
2. Determine Placement — scan existing docs (docfront --recursive). Decide: new file, existing file, which subdirectory. Discuss with the user if unclear.
3. Write — follow the conventions below.

Writing Guidelines

• Target audience: an experienced newcomer — someone technically capable but unfamiliar with this specific project.
• Be brief and specific — no obvious information, no generic best practices.
• Typical document: 40–80 lines.
• Prefer referencing source files over large code blocks.
• If the title makes the purpose obvious, omit the summary.

File and Directory Naming

• Use lowercase-with-dashes (kebab-case) for new files and directories.
• Uppercase is allowed by the CLI (e.g. RELEASING.md).
• Names must be shell-safe: no spaces, no quotes, no special characters. The CLI validates this for both files and directories. Use docfront --check to verify.
• Use .md (Markdown) for all documents.
• Use short, descriptive names.
• Group related documents into subdirectories. Subdirectories can be nested.

YAML Frontmatter

Every .md file must start with a YAML frontmatter block with these fields:

Document Body

After the closing --- of the frontmatter, write standard Markdown. There are no constraints on the body format — use headings, code blocks, tables, and lists as needed.

---
title: Your Title Here
summary: A one-sentence description of what this document covers.
read_when:
  - first situation when this document is useful
  - second situation
---

# Your Title Here

Start your content here…

References

• Installing Docfront CLI — how to add docfront CLI to a project.
• Bootstrapping Documentation — instructions for creating or extending project documentation by exploring the codebase.
• Migrate Existing Documents — guide for bringing an existing folder of Markdown documents into docfront conventions (naming, frontmatter).
• Migrate Skills to Docfront Documentation — guide for moving internal project documentation from agent skills into docs/.