{"owner":"tldr-pages","repo":"tldr","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"files":{"AGENTS.md":"# TLDR Pages - AI Assistant Guide\n\nThis guide helps AI assistants contribute to tldr-pages effectively. For detailed rules, see `contributing-guides/style-guide.md`.\n\n## Quick Decision Workflow\n\n```text\nUser asks about command X\n        │\n        ▼\nDoes page exist? (find pages* -name \"X.md\")\n        │\n   ┌────┴────┐\n  YES        NO\n   │          │\n   ▼          ▼\nEdit      Which platform?\n          │\n     ┌────┼────┐\n  2+ same  1 platform  Windows\n     │       │         │\n     ▼       ▼         ▼\n  common/  linux/    windows/\n                    osx/ etc.\n```\n\n## Project Overview\n\n**tldr-pages** - Community-maintained simplified help pages for command-line tools.\n\n- **License**: CC BY 4.0 (pages), MIT (scripts)\n- **Website**: https://tldr.sh/\n- **Languages**: 30+ translations in `pages.<locale>/`\n\n## Repository Structure\n\n```\npages/           # English pages\n  ├── common/    # 2+ platforms\n  ├── linux/     # Linux-only\n  ├── osx/       # macOS-only\n  ├── windows/   # Windows-only\n  └── ...        # android, freebsd, openbsd, netbsd, sunos, cisco-ios, dos\npages.<locale>/  # Translations (fr, es, zh, etc.)\nscripts/         # Python utilities\n```\n\n## Page Format\n\n```markdown\n# command-name\n\n> Short, snappy description (1-2 lines max).\n> More information: <https://url-to-upstream.tld>.\n\n- Description of example:\n\n`command --option {{path/to/file}}`\n\n- Another example:\n\n`command {{[-f|--flag]}} {{arg}}`\n\n- Display help:\n\n`command {{[-h|--help]}}`\n\n- Display version:\n\n`command {{[-V|--version]}}`\n```\n\n### Format Rules\n\n1. **Title**: Match filename exactly (lowercase in filename, case-insensitive in content)\n2. **Description**: Start with `>`, 1-2 lines preferred\n3. **More Information**: Required, wrapped in `< >`\n4. **Examples**: 5 preferred, 8 maximum\n5. **Descriptions**: Start with `- `, use **imperative mood** (\"List\" not \"Lists\")\n6. **Commands**: Wrapped in backticks, separate line after description\n7. **Blank Lines**: Required between examples\n8. **Trailing Newline**: File must end with newline\n\n## Style Guidelines\n\n### Writing Style\n\n- **Imperative mood**: \"List all files\" NOT \"Lists all files\"\n- **Concise**: Focus on practical examples\n- **No formatting**: No *italics*, **bold**, or other markdown styling\n- **Avoid general concepts**: Don't explain UNIX basics\n\n### Placeholder Conventions\n\n| Pattern | Usage |\n|---------|-------|\n| `{{path/to/file}}` | File paths |\n| `{{path/to/directory}}` | Directory paths |\n| `{{filename}}` | Filename only |\n| `{{file1 file2 ...}}` | Multiple arguments |\n| `{{option1\\|option2}}` | Alternatives |\n| `{{[-v\\|--verbose]}}` | Verbose output flag |\n| `{{[-it\\|--interactive --tty]}}` | Grouped flags |\n| `{{1..5}}` | Numeric range |\n| `{{*.ext}}` | Wildcard pattern |\n\n### Option Syntax\n\n- **When both forms exist**, use both: `{{[-h|--help]}}`\n- **Verify flags exist**: Check `man <command>` or `<command> --help` before documenting\n- Note: Version flag varies by command (`-V`, `--version`, or no short option) - check documentation\n- Space before args: `--option arg` NOT `--option=arg`\n- Short option hints: `[c]reate`, `[v]erbose`\n\n### Keypress Syntax\n\n- Single: `<a>`, `<Enter>`, `<Space>`\n- Special: `<Ctrl>`, `<Alt>`, `<Shift>` (PascalCase)\n- Combinations: `<Ctrl c>`, `<Alt F4>`\n- Sequence: `<Esc><u>`, `<Ctrl k><Ctrl s>`\n\n### More Information Link\n\n- Verify URL is reachable and returns HTTP 200 (follows redirects):\n\n```bash\n# Check URL and status code\ncurl -sL -o /dev/null -w \"%{http_code}\" https://example.com/command\n# Should return: 200\n```\n\n- Use official sources (man pages, docs, project sites)\n- Preferred: https://manned.org/[command], https://www.gnu.org/software/[command]/manual/\n\n### Help/Version Commands\n\nPlace as **last two** examples (in this order) to highlight practical commands first. Use wording: \"Display help\", \"Display version\". These are low-priority filler examples—if better practical examples exist, prefer those instead.\n\n## Platform-Specific Rules\n\n### Windows\n\n- **Filename**: lowercase (e.g., `invoke-webrequest.md`)\n- **Title**: as-is (`# Invoke-WebRequest`)\n- **Command**: as-is (`Invoke-WebRequest`)\n- **Paths**: backslashes `{{path\\to\\file}}`\n- **Environment vars**: `%VARIABLE%` (cmd), `$Env:VARIABLE` (PowerShell)\n- **PowerShell compatibility**: Must work on 5.1 and latest\n\n### Directory Selection\n\n- **pages/common/**: Command works on 2+ platforms with same syntax\n- **pages/<platform>/**: Command works on only ONE platform\n\n## Alias Pages\n\nUse `scripts/set-alias-page.py -p <platform>/<command> -l <locale>` for translations.\n\n```markdown\n# alias\n\n> This command is an alias of `original`.\n> More information: <https://example.com>.\n\n- View documentation for the original command:\n\n`tldr original`\n```\n\n## Subcommands\n\nCommands with subcommands (like `git`) should mention them in the description:\n\n```markdown\n# command\n\n> Brief description.\n> Some subcommands such as `sub1`, `sub2`, etc. have their own usage documentation.\n> More information: <https://example.com>.\n\n- Common usage:\n\n`command {{arg}}`\n\n- View documentation for subcommand:\n\n`tldr command-sub1`\n```\n\n**Note**: Each subcommand gets its own page: `git-commit.md`, `git-push.md`, etc.\n\n## Creating Pages\n\n1. Check existing: `find pages* -name \"<command>.md\"`\n2. Determine platform → `pages/common/` (2+ platforms) or `pages/<platform>/`\n3. Research: `man <command>`, `<command> --help`, official docs\n4. Create file: `pages/<platform>/<command>.md`\n5. Write content: 5-8 practical examples (help/version last)\n6. Test: `tldr-lint path/to/page.md`\n7. Commit: `git add pages/<platform>/<command>.md && git commit -m \"<command>: add page\"`\n\n### Editing Pages\n\nCommit format: `<command>: <description>` (e.g., `ls: fix typo`, `git-push: add --force example`)\n\n### Translations\n\n1. Ensure English page exists\n2. **For alias pages**: Use `scripts/set-alias-page.py -p <platform>/<command> -l <locale>`\n3. Create file: `pages.<locale>/<platform>/<command>.md`\n4. Translate:\n   - Maintain same example structure\n   - Keep placeholders in English\n   - Don't translate `example.com`\n   - Follow language-specific rules below\n5. Commit: `<command>: add <language> translation`\n\n## Language-Specific Rules\n\n### Chinese (zh)\n- Space around English/numbers: `docker 容器`\n- Full-width punctuation\n\n### French (fr)\n- Third person: \"Extrait\" not \"Extraire\"\n- Space before punctuation: `informations :`\n\n### Spanish (es)\n- Third person: \"Crea\" not \"Crear\"\n- Use `identificador` not `id`\n\n### Portuguese (pt_BR, pt_PT)\n- Third person: \"Lista\" not \"Listar\"\n\n### Indonesian (id)\n- No `ber-`/`me-` prefixes: \"Unduh\" not \"Mengunduh\"\n\n## Testing & Validation\n\n```bash\n# Install linter\nnpm install -g tldr-lint\n\n# Lint single page or all\ntldr-lint pages/common/tar.md\ntldr-lint ./pages\n\n# Via npm\nnpm run lint-tldr-pages\n```\n\n### Available Scripts\n\nIn `scripts/` directory:\n\n| Script | Purpose |\n|--------|---------|\n| `set-alias-page.py` | Create/update alias pages |\n| `set-more-info-link.py` | Update documentation links |\n| `set-page-title.py` | Update page titles |\n| `set-see-also.py` | Update \"See also\" references |\n| `update-command.py` | Update command examples |\n| `wrong-filename.py` | Find naming issues |\n\n**Flags**: `-p platform/command`, `-l locale`, `-s` (stage), `-n` (dry-run), `-S` (sync)\n\nExample: `python scripts/set-alias-page.py -p common/vi -s`\n\n## AI Review Checklist\n\nWhen reviewing PRs, verify:\n\n- [ ] Correct format (title, description, examples)\n- [ ] Imperative mood in descriptions\n- [ ] Proper placeholder syntax `{{}}`\n- [ ] Both option forms used when available: `{{[-h|--help]}}`\n- [ ] Appropriate platform directory\n- [ ] Max 8 examples\n- [ ] \"More information\" link present\n- [ ] Help/version examples present with wording \"Display help\" and \"Display version\"\n- [ ] No bold/italics/styling\n- [ ] Blank lines between examples\n- [ ] Language-specific rules (translations)\n\n## Resources\n\n- **Style Guide**: `contributing-guides/style-guide.md`\n- **CONTRIBUTING.md**: General contribution guidelines\n- **Translation Dashboard**: https://lukwebsforge.github.io/tldri18n/\n- **Linter**: https://github.com/tldr-pages/tldr-lint\n\n### Common URLs\n\n- https://manned.org/[command] - General man pages\n- https://www.gnu.org/software/[command]/manual/ - GNU tools\n- https://learn.microsoft.com/powershell/module/... - PowerShell\n- https://keith.github.io/xcode-man-pages/ - macOS\n- https://git-scm.com/docs/[command] - Git\n\n### Good Examples\n\n- Simple: `pages/common/pwd.md`\n- With placeholders: `pages/common/tar.md`\n- With subcommands: `pages/common/git.md`\n- With aliases: `pages/common/vi.md`\n- Windows: `pages/windows/Invoke-WebRequest.md`\n\n## Common Mistakes\n\n**Wrong:**\n```markdown\n- Lists all files:\n`ls -la`\n- **Delete** a file:\n`rm -rf {file}`\n```\n\n**Correct:**\n```markdown\n- List all files:\n\n`ls -la`\n\n- Delete a file:\n\n`rm -rf {{path/to/file}}`\n```\n\n**Other issues:**\n- Non-imperative mood: \"Lists\" instead of \"List\"\n- Wrong placeholders: `{file}` or `[file]` instead of `{{file}}`\n- Nested placeholders: `{{path/to/{{file}}}}`\n- Missing \"More information\" link\n- No blank lines between examples\n\n## API Cost-Saving Tips\n\nWhen using AI assistants to create tldr pages:\n\n1. **Check for existing pages first**: Always run `find pages* -name \"<command>.md\"` before creating new pages to avoid redundant work\n\n2. **Reuse patterns from similar commands**: Look at 2-3 existing pages (e.g., `pages/common/tar.md`, `pages/common/curl.md`) before generating new content instead of asking the AI to invent examples\n\n3. **Provide command help output**: When asking for a new page, include the output of `<command> --help` or `man <command>` to reduce the AI's need to research\n\n4. **Batch similar requests**: Group multiple related page creation requests together rather than making separate API calls\n\n5. **Use the templates**: Reference the templates in this file directly instead of asking the AI to recall them from memory\n\n6. **Verify with linter first**: Run `tldr-lint` before asking for human review to catch simple formatting errors\n\n7. **Limit examples to 5-6**: Use the minimum viable number of examples (5 preferred) rather than maxing out at 8\n\n**Remember**: These tips reduce API costs while maintaining output quality - the key is providing better context upfront so the AI generates correct content in fewer attempts.\n"}}