PicoClaw Documentation

PicoClaw documentation is organized by document type first and language second.

This file describes the recommended documentation layout, how translated files should be named, and what make lint-docs currently checks locally.

These conventions are intended as contributor guidance for new or moved docs. Existing docs may still have historical exceptions, and make lint-docs only checks a common subset of the patterns described here.

Reader Navigation

If you are browsing docs rather than reorganizing them, start with these directory indexes:

• Guides: setup, configuration, provider, and workflow guides.
• Reference: precise configuration and behavior reference.
• Operations: debugging and troubleshooting material.
• Security: security-focused guides and controls.
• Architecture: implementation notes and internal design docs.
• Migration: upgrade and migration notes.

For channel-specific setup, start with Chat Apps Configuration and then drill into docs/channels/<name>/README.md as needed.

Principles

• Choose the document type directory first. Do not create language buckets such as docs/zh/ or docs/fr/.
• Keep each translated document next to its English source document.
• Use English as the base filename with no locale suffix.
• Use lowercase locale suffixes for translations, for example configuration.zh.md or README.pt-br.md.
• Keep module-specific docs next to the code they describe instead of moving them into docs/.

Recommended Directories

• README.md: English project entry document at the repository root.
• docs/project/: translated project entry documents such as README.zh.md and CONTRIBUTING.zh.md.
• docs/guides/: setup and usage guides.
• docs/reference/: reference material and detailed configuration docs.
• docs/operations/: debugging and troubleshooting docs.
• docs/security/: security-related documentation.
• docs/architecture/: architecture and internal design notes.
• docs/channels/: channel-specific integration guides.
• docs/design/: design proposals and investigations.
• docs/migration/: migration notes.

Recommended Naming

• English documents use the base filename:
  • README.md
  • configuration.md
• Translations use .<locale>.md:
  • README.zh.md
  • configuration.fr.md
  • README.pt-br.md
• Code-adjacent translated READMEs follow the same rule:
  • pkg/audio/asr/README.zh.md
  • pkg/isolation/README.zh.md

Common Patterns To Avoid

• Root-level translated entry docs such as README.zh.md or CONTRIBUTING.fr.md
  • Use docs/project/README.zh.md or docs/project/CONTRIBUTING.fr.md instead.
• Language directories under docs/ such as docs/zh/, docs/ZH/, docs/ja/, or docs/fr/
  • Use docs/<type>/<name>.<locale>.md instead.
• Nested locale buckets such as docs/guides/zh/configuration.md or docs/channels/telegram/zh/README.md
  • Keep translations beside the English source file instead.
• Legacy translation filenames such as README_zh.md or README_CN.md
  • Use README.zh.md.
• Non-canonical locale suffixes such as configuration_zh.md or configuration.ZH.md
  • Use lowercase .<locale>.md, for example configuration.zh.md.

Translation Placement

• For docs under docs/guides, docs/reference, docs/operations, docs/security, docs/architecture, docs/channels, and docs/migration, keep translations beside the English source file.
• For project entry translations, keep translated files in docs/project/ and keep the English source in the repository root.
• In most cases, each translated file should have an English source document:
  • docs/guides/configuration.zh.md usually sits beside docs/guides/configuration.md
  • docs/project/README.zh.md usually corresponds to README.md
• Exception: docs/design/ may contain locale-specific working notes without an English source document. The naming rules still apply there.

Code-Adjacent Docs

Keep documentation next to the implementation when it primarily describes a package, command, example, or subproject.

Examples:

• pkg/**/README.md
• cmd/**/README.md
• web/README.md
• examples/**/README.md

These files still follow the same translation naming rules.

Adding a New Document

1. Pick the correct document type directory.
2. Create the English source file first.
3. Add translated siblings after the English source exists when that source is part of the same docs set.
4. Update links from existing docs when the new doc becomes a navigation target.
5. Run make lint-docs locally when adding or moving docs.

Examples

• New setup guide:
  • docs/guides/launcher-setup.md
  • docs/guides/launcher-setup.zh.md
• New security guide:
  • docs/security/token-rotation.md
• New translated package README:
  • pkg/channels/README.zh.md

Validation

Run:

make lint-docs

The local docs linter currently checks these common cases:

• no root-level translated README or CONTRIBUTING files
• no docs/<locale>/ language buckets, regardless of case
• no nested locale buckets under typed docs directories
• no legacy README_*.md filenames
• no non-canonical translation-like filenames such as _zh.md or .ZH.md
• no extra Markdown files directly under docs/ except docs/README.md
• every translated Markdown file has a matching English source file
  • except for locale-specific working notes under docs/design/

make lint-docs is a local consistency check for common naming and placement mistakes. It helps contributors stay close to the recommended layout, but it is not intended to describe every acceptable documentation pattern in the repository.

When a check fails, make lint-docs prints the failing path, the reason, and a suggested fix.

If you change these recommendations or want the local linter to reflect them more closely, update this file and scripts/lint-docs.sh together.