diary-docs 0.1.0

Scaffold DIARY documentation structure with MkDocs and Backstage support

diary-docs — DIARY Documentation Scaffolder

A CLI tool that scaffolds a DIARY documentation structure with MkDocs and Backstage support, indexes your codebase for knowledge retrieval, and keeps docs in sync with code changes.

Installation

pip install diary-docs

For development:

pip install -e .

Commands

diary-docs init

Initialize a new DIARY documentation project in the current directory.

diary-docs init

The tool prompts for a project name, then creates:

docs/
├── index.md
├── objectives.md
├── structure/
│   └── index.md
├── techdocs/
│   ├── index.md
│   ├── architecture.md
│   ├── api-contracts.md
│   ├── deployment.md
│   ├── adr.md
│   └── development-guide.md
├── product/
│   ├── index.md
│   ├── user-guide.md
│   └── modules.md
├── ops-governance/
│   ├── index.md
│   ├── runbooks.md
│   └── security.md
└── knowledge-base/
    ├── index.md
    ├── faq.md
    └── troubleshooting.md
mkdocs.yml
catalog-info.yaml

It also generates an AI agent skill file for content generation.

Options:

Flag	Description
-f, --force	Overwrite existing files
--help	Show help for this command

If files already exist, they are skipped (unless --force is used).

---

diary-docs index

Index the workspace codebase for knowledge retrieval. Extracts symbols, files, and relationships into a SQLite database.

diary-docs index

Options:

Flag	Description
-r, --report	Generate a documentation coverage report after indexing
--db-path PATH	Custom database path (default: docs/.index/knowledge.db)
--help	Show help for this command

The index powers the diary-docs generate-content skill, allowing AI agents to query the codebase structure without manually scanning files.

---

diary-docs sync

Synchronize documentation with detected code changes. Compares the current workspace against git history to find outdated AIMB (AI-Managed) blocks in markdown files.

# Preview changes without applying
diary-docs sync --dry-run

# Apply all detected changes
diary-docs sync --force

Options:

Flag	Description
-n, --dry-run	Preview changes as JSON without applying
-b, --branch NAME	Override branch detection
-f, --force	Skip conflict warnings
-o, --output FILE	Write JSON report to file
--help	Show help for this command

Dry-run output is a JSON SyncReport showing code changes, affected docs, confidence scores, and any conflicts.

---

Global Options

Flag	Description
--version	Show version
--help	Show top-level help

AI Agent Skills

diary-docs init generates two slash commands for AI coding agents (Claude Code, OpenCode). The skill files are placed in .claude/commands/ or .opencode/commands/ (you choose during init).

/diary-generate-content

Analyzes the workspace codebase via the pre-built index and generates enterprise-grade documentation content for every DIARY file.

# In Claude Code or OpenCode:
/diary-generate-content

The skill follows a multi-step workflow:

1. Reads existing docs structure
2. Queries the knowledge index (docs/.index/knowledge.db)
3. Asks clarifying questions for missing context
4. Generates content with Mermaid diagrams, tables, and use cases
5. Writes all docs/ files with AIMB (AI-Managed Block) wrappers

Output covers: architecture overview, API contracts, deployment flow, ADR log, user guide, runbooks, security compliance, FAQ, and troubleshooting.

---

/diary-sync

Synchronizes documentation with detected code changes. Compares the current git state against history to find outdated AIMB blocks.

# In Claude Code or OpenCode:
/diary-sync

The skill follows a structured workflow:

1. Verifies git state and runs diary-docs sync --dry-run
2. Parses the SyncReport JSON for changes and conflicts
3. Processes each high-confidence change by updating relevant AIMB blocks
4. Flags conflicts for manual review (never auto-resolves)
5. Finalizes with diary-docs sync --force
6. Prints a summary of all processed files

Prerequisites: All code changes must be committed to git before running /diary-sync.

---

What It Generates

File/Folder	Description
docs/	Main documentation folder
docs/index.md	Root documentation index
docs/objectives.md	Project objectives and goals
docs/structure/index.md	Writing guidelines and conventions
docs/techdocs/	Technical documentation section
docs/techdocs/architecture.md	System architecture overview
docs/techdocs/api-contracts.md	API endpoint specifications
docs/techdocs/deployment.md	Deployment flow and environments
docs/techdocs/adr.md	Architecture Decision Records
docs/techdocs/development-guide.md	Local development setup guide
docs/product/	Product documentation section
docs/product/user-guide.md	End-user guide with use cases
docs/product/modules.md	Module/component reference
docs/ops-governance/	Operations & governance section
docs/ops-governance/runbooks.md	Operational runbooks
docs/ops-governance/security.md	Security compliance docs
docs/knowledge-base/	Knowledge base section
docs/knowledge-base/faq.md	Frequently asked questions
docs/knowledge-base/troubleshooting.md	Troubleshooting guide
mkdocs.yml	MkDocs configuration with TechDocs Core plugin
catalog-info.yaml	Backstage component registration file

Development

pytest tests/ -v