{"owner":"TeamAmaze","repo":"AmazeFileManager","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# Guidelines for AI Contributions to Amaze File Manager\n\nThis file provides guidance to AI coding assistants for contributing\nto the codebase. These guidelines are designed to produce \ncontributions that meet the same high standards we expect from human\ncontributors. The original reference for this file is the Zulip\nCLAUDE.md file, we thank the Zulip team for their work.\n\n## Philosophy\n\n### No detail is too small\n\nAmaze holds itself to a high bar for polish because users depend on\nthis software daily, and because the project is built to last for\ndecades. There is no category of \"minor issue\" that is acceptable\nto ship, if something is broken in any context where a user would\nencounter it, it must be fixed before merging. The project's\nextensive investment in testing, tooling, and review processes exists\nprecisely so that these issues get caught and fixed, not so that they\ncan be classified as low-priority and deferred.\n\nThe right attitude is: \"What could go wrong, and how do I verify that\nit doesn't?\" not \"It looks fine to me.\" **What isn't tested probably\ndoesn't work** - this applies to visual changes just as much as to\nbackend logic.\n\n### Understand before coding\n\nBefore writing any code, you must understand:\n\n1. What the existing code does and why, including the relevant help center or\n   developer-facing documentation.\n2. What problem you're solving, in its full scope.\n3. Why your approach is the right solution, and available alternatives.\n4. How you will verify that your work is correct, and avoid regressions\n   that are plausible for the type of work you're doing.\n\nThe answer to \"Why is X an improvement?\" should never be \"I'm not sure.\"\n\n## Workflow\n\nFollow this workflow for every task: **understand → propose → implement → verify**.\n\n### 1. Understand Before Coding\n\nBefore making any changes:\n\n```bash\n# Look at existing code patterns\ngit grep \"similar_function_name\"\ngit log --oneline -20 -- path/to/file.py\n\n# Check for related issues on GitHub\n```\n\nAlways show existing similar code and explain how it works before proposing\nchanges.\n\n### 2. Propose an Approach\n\nBefore writing code, explain the plan:\n\n- Explain your understanding of the problem and all relevant design decisions\n- What changes are needed and why\n- How the changes fit with existing patterns\n- What could break and how to prevent regressions\n\n### 3. Implement in Minimal, Coherent Commits\n\nEach commit should be self-contained, highly readable and reviewable\nusing `git show --color-moved`, and pass lint/tests independently. If\nextracting new files or moving code, always do that in a separate\ncommit from other changes.\n\n### 4. Verify Before Finalizing\n\nRun tests before making a commit. Always manage your time by running\nspecific test collections, not the entire test suite.\n\n## Before You Start\n\n### Read the Relevant Documentation\n\nBefore working on any area:\n\n- Read the @CONTRIBUTING.md guidelines.\n- Read existing code in the area you're modifying.\n- Use `git grep` to find similar patterns in the codebase and read those.\n\n### Understand the Code Style\n\n- **Be consistent with existing code.** Look at surrounding code and follow\n  the same patterns, as this is a thoughtfully crafted codebase.\n- **Use clear, greppable names** for functions, arguments, variables, and\n  tests. Future developers will `git grep` for relevant terms when\n  researching a problem, so names should communicate purpose clearly.\n- Keep everything well factored for maintainability. Avoid duplicating\n  code, especially where access control or subtle correctness is involved.\n- Prefer writing code that is readable without explanation over heavily\n  commented code using clever tricks. Comments should explain \"why\" when\n  the reason isn't obvious, not narrate \"what\" the code does.\n- Comments generally should have a line to themselves.\n\n## Commit Discipline\n\n### Each Commit Must:\n\n1. **Be coherent**: Implement one logical change completely and atomically.\n2. **Pass tests**: Include test updates in the same commit as code changes.\n3. **Not make Amaze worse**: Work is ordered so no commit has regressions.\n4. **Be safe to deploy individually**: Or explain in detail why not.\n5. **Be minimal** and **reviewable**: Don't combine moving code with changing\n   it in the same commit; make liberal use of small prep commits for\n   no-op refactoring that are easy to verify.\n\n### Never:\n\n- Mix multiple separable changes in a single commit.\n- Create a commit that \"fixes\" a mistake from an earlier commit in the same PR;\n  always edit Git to fix the original commit.\n- Add content in one commit only to remove or move it in the next;\n  plan upfront what belongs where and do it right the first time.\n- Include debugging code, commented-out code, or temporary TODOs.\n- Leave commits that break if a later commit in the PR is dropped.\n  When a commit is flagged as potentially droppable, verify all\n  earlier commits work correctly without it.\n\n### Commit Message Format\n\n```\nsubsystem: Summary in 72 characters or less.\n\nThe body explains why and how. Include context that helps reviewers\nand future developers understand your reasoning, analysis, and\nverification of the work above and beyond CI, without repeating\ndetails already well presented in the commit metadata (filenames,\netc.). Explain what the change accomplishes and why it won't break\nthings one might worry about.\n\nLine-wrap at 68-70 characters, except URLs and verbatim content\n(error messages, etc.).\n\nFixes #123.\n```\n\n**Commit summary format:**\n\n- Example: `Fix cursor position after emoji insertion`\n- Example: `Refactor immutable cache headers`\n- Bad examples: `Fix bug`, `Update code`, `gather_subscriptions was broken`\n\n**Linking issues:**\n\n- `Fixes #123` automatically closes the issue\n- `Addresses #123` does not close (for partial fixes)\n- In a multi-commit PR, use `Addresses #123` in earlier commits\n  and `Fixes #123` in the final commit.\n\n### Rebasing Commits (Non-Interactive)\n\nSince `git rebase -i` requires an interactive editor, use\n`GIT_SEQUENCE_EDITOR` to supply the todo list via a script:\n\n1. **Updating the HEAD commit:** If the commit you need to modify is\n   already at HEAD, just use `git commit --amend` directly. The\n   fixup+rebase workflow below is only needed for non-HEAD commits.\n\n2. **Squashing fixups into existing commits:** Create fixup commits with\n   `git commit --fixup=<target-hash>`, then write a shell script that\n   outputs the desired todo (with `pick` and `fixup` lines in order)\n   and run:\n\n   ```bash\n   GIT_SEQUENCE_EDITOR=/path/to/todo-script.sh git rebase -i <base>\n   ```\n\n   Note: `--autosquash` alone without `-i` does **not** reorder or\n   squash anything.\n\n3. **Rewording commit messages:** Use `git format-patch` to export\n   commits as patch files, edit the message headers in the patch\n   files, then reapply:\n\n   ```bash\n   git format-patch <base> -o /tmp/patches/\n   # Edit the commit message in each /tmp/patches/000N-*.patch file\n   # (the message is between the Subject: line and the --- line)\n   git reset --hard <base>\n   git am /tmp/patches/*.patch\n   ```\n\n## Testing Requirements\n\nAutomated code generation must include tests for all components\nto prevent regressions.\n\nThere are three kinds of tests:\n- Unit tests: Test single functions, simple functionality, very\n  easy to run, if at all possible, these should be used to test\n  functionality.\n- Headless tests: Robolectric is used for testing anything that\n  doesn't require a phone, it allows for extensive mocking and \n  UI interaction simulation without the full UI overhead.\n- Emulator tests: Using Espresso and other tools, very heavy to\n  run, create these tests as a last resort.\n\n### Before Submitting:\n\nCheck that the new features, or fixed bugs are being properly tested\nfor regressions.\n\n### Testing Philosophy:\n\n- Write end-to-end tests when possible verifying what's important.\n- A good failing test before implementing is good practice so your\n  test and code can jointly verify each other.\n- Remember to always assert state is correctly updated, not just \"success\".\n\n## Self-Review Checklist\n\nBefore finalizing, verify:\n\n- [ ] The PR addresses all points described in the issue\n- [ ] All relevant tests pass locally\n- [ ] Code follows existing patterns in the codebase\n- [ ] Names (functions, variables, tests) are clear and greppable\n- [ ] Commit messages, comments, and PR description are well done\n- [ ] Each commit is a minimal coherent idea\n- [ ] No debugging code or unnecessary comments remain\n- [ ] Type annotations are complete and correct\n- [ ] User-facing strings are in strings.xml\n- [ ] User-facing error messages are clear and actionable\n- [ ] No secrets or credentials are hardcoded\n- [ ] Documentation is updated if behavior changes\n- [ ] Refactoring is complete (`git grep` for remaining occurrences)\n- [ ] Security audit of changes\n\nAlways output a recommend pull request summary+description that\nfollow's Amaze's guidelines once you finish preparing a series of\ncommits.\n\n## Common Pitfalls\n\n### Treating Known Issues as Acceptable\n\nA common failure mode is discovering a problem during verification\nand then noting it as a known limitation rather than fixing it.\n\n**Mitigation:** When you find any issue during verification, fix it\nbefore presenting the work. If a fix would require a design decision,\nraise it as a question rather than shipping the broken state.\n\n### Missing Test Updates\n\nTests must be in the same commit as the code they test.\n\n**Mitigation:** Include test updates in each commit. Show what tests need to\nchange.\n\n### Verbose Commit Messages\n\nCommits are concise, say everything that's important for a reviewer to\nunderstand about the motivation for the work and changes, and nothing more.\nAvoid wordiness and details obvious to someone who is looking at the\ncommit and its metadata (lists of filenames, etc).\n\n**Mitigation:** Keep summary under 72 characters. Body should explain why,\nnot what.\n\n### Mixing Concerns\n\nMultiple changes in one commit makes review difficult.\n\n**Mitigation:** Each commit should do exactly one thing. Plan\nnecessary refactoring and preparatory commits in advance of functional\nchanges. You can split into good commits after the fact, but it's much\nfaster and easier to just plan and write them well the first time.\n\n## Pull Request Guidelines\n\n### PR Description Should:\n\nWhen opening a pull request, prefix the PR title with `[ai]` (e.g.,\n`[ai] compose: Fix cursor position after emoji insertion.`). Use\n`upstream/main` as the base branch.\n\nOutput the PR description in a markdown code block so that formatting\n(bold, headers, checkboxes, etc.) copy-pastes correctly into GitHub.\n\n1. Start with a `Fixes: #...` line linking the issue being addressed.\n2. Explain **why** the change is needed, not just what changed.\n3. Describe how you tested the change, using checkbox format for the\n   test plan (e.g., `- [x] ./tools/test-backend ...`).\n4. Include screenshots for UI changes.\n5. Link to relevant issues or discussions.\n6. Call out any open questions, concerns, or decisions you are uncertain\n   about, so they can be resolved during review.\n7. Include the self-review checklist from\n   `.github/pull_request_template.md` using checkbox format (`- [x]` /\n   `- [ ]`), checking off all applicable items.\n\n### PR Description Should Not:\n\n- Regurgitate information visible from the diff\n- Make claims you haven't double-checked\n- Express more certainty than is justified given the evidence\n\n## When to Pause and Discuss\n\nRecommend pausing for discussion when:\n\n- The approach involves security-sensitive code\n- Database migrations are needed\n- The change affects many files (>10)\n- Performance implications are unclear\n- The feature design isn't fully specified\n- The API or data model design isn't fully specified\n- Existing tests are failing for unclear reasons\n\n## Task-Specific Approaches\n\n### For Bug Fixes\n\n1. Show the relevant code and explain what's happening\n2. Brainstorm theories for how the bug might be possible\n3. Analyze and propose a fix with a clear explanation\n4. Write tests that would have caught this bug if possible\n5. Format as a single commit following commit guidelines\n6. Audit for whether the bug may exist elsewhere or might be\n   re-introduced and propose appropriate changes to address if so.\n\n### For New Features\n\n1. Show similar existing features in the codebase\n2. Propose an implementation approach before coding\n3. Implement in minimal, coherent commits\n4. Each commit must pass tests independently\n\n### For Refactoring\n\n1. Show the current implementation\n2. Explain what makes it problematic\n3. Propose the refactoring approach\n4. Implement in commits that each leave the codebase working\n5. No behavior changes unless explicitly discussed\n6. Verify completeness: use `git grep` to find all occurrences and\n   confirm nothing was missed\n\n## Repository Structure Quick Reference\n\n- `app` contains the main app\n- `commons_compress_7z` is the 7z compression and decompression library \n- `file_operations` is a rust library which contain some of the low level\n  operations needed by Amaze\n- `portscanner` is a network library used by various systems in Amaze\n- `scripts` is a directory that contains general tools for maintaining the \n  app\n- `fastlane` is a directory that maintains the resources for FDroid and other\n  open source app repositories \n"},"files":{"AGENTS.md":"# Guidelines for AI Contributions to Amaze File Manager\n\nThis file provides guidance to AI coding assistants for contributing\nto the codebase. These guidelines are designed to produce \ncontributions that meet the same high standards we expect from human\ncontributors. The original reference for this file is the Zulip\nCLAUDE.md file, we thank the Zulip team for their work.\n\n## Philosophy\n\n### No detail is too small\n\nAmaze holds itself to a high bar for polish because users depend on\nthis software daily, and because the project is built to last for\ndecades. There is no category of \"minor issue\" that is acceptable\nto ship, if something is broken in any context where a user would\nencounter it, it must be fixed before merging. The project's\nextensive investment in testing, tooling, and review processes exists\nprecisely so that these issues get caught and fixed, not so that they\ncan be classified as low-priority and deferred.\n\nThe right attitude is: \"What could go wrong, and how do I verify that\nit doesn't?\" not \"It looks fine to me.\" **What isn't tested probably\ndoesn't work** - this applies to visual changes just as much as to\nbackend logic.\n\n### Understand before coding\n\nBefore writing any code, you must understand:\n\n1. What the existing code does and why, including the relevant help center or\n   developer-facing documentation.\n2. What problem you're solving, in its full scope.\n3. Why your approach is the right solution, and available alternatives.\n4. How you will verify that your work is correct, and avoid regressions\n   that are plausible for the type of work you're doing.\n\nThe answer to \"Why is X an improvement?\" should never be \"I'm not sure.\"\n\n## Workflow\n\nFollow this workflow for every task: **understand → propose → implement → verify**.\n\n### 1. Understand Before Coding\n\nBefore making any changes:\n\n```bash\n# Look at existing code patterns\ngit grep \"similar_function_name\"\ngit log --oneline -20 -- path/to/file.py\n\n# Check for related issues on GitHub\n```\n\nAlways show existing similar code and explain how it works before proposing\nchanges.\n\n### 2. Propose an Approach\n\nBefore writing code, explain the plan:\n\n- Explain your understanding of the problem and all relevant design decisions\n- What changes are needed and why\n- How the changes fit with existing patterns\n- What could break and how to prevent regressions\n\n### 3. Implement in Minimal, Coherent Commits\n\nEach commit should be self-contained, highly readable and reviewable\nusing `git show --color-moved`, and pass lint/tests independently. If\nextracting new files or moving code, always do that in a separate\ncommit from other changes.\n\n### 4. Verify Before Finalizing\n\nRun tests before making a commit. Always manage your time by running\nspecific test collections, not the entire test suite.\n\n## Before You Start\n\n### Read the Relevant Documentation\n\nBefore working on any area:\n\n- Read the @CONTRIBUTING.md guidelines.\n- Read existing code in the area you're modifying.\n- Use `git grep` to find similar patterns in the codebase and read those.\n\n### Understand the Code Style\n\n- **Be consistent with existing code.** Look at surrounding code and follow\n  the same patterns, as this is a thoughtfully crafted codebase.\n- **Use clear, greppable names** for functions, arguments, variables, and\n  tests. Future developers will `git grep` for relevant terms when\n  researching a problem, so names should communicate purpose clearly.\n- Keep everything well factored for maintainability. Avoid duplicating\n  code, especially where access control or subtle correctness is involved.\n- Prefer writing code that is readable without explanation over heavily\n  commented code using clever tricks. Comments should explain \"why\" when\n  the reason isn't obvious, not narrate \"what\" the code does.\n- Comments generally should have a line to themselves.\n\n## Commit Discipline\n\n### Each Commit Must:\n\n1. **Be coherent**: Implement one logical change completely and atomically.\n2. **Pass tests**: Include test updates in the same commit as code changes.\n3. **Not make Amaze worse**: Work is ordered so no commit has regressions.\n4. **Be safe to deploy individually**: Or explain in detail why not.\n5. **Be minimal** and **reviewable**: Don't combine moving code with changing\n   it in the same commit; make liberal use of small prep commits for\n   no-op refactoring that are easy to verify.\n\n### Never:\n\n- Mix multiple separable changes in a single commit.\n- Create a commit that \"fixes\" a mistake from an earlier commit in the same PR;\n  always edit Git to fix the original commit.\n- Add content in one commit only to remove or move it in the next;\n  plan upfront what belongs where and do it right the first time.\n- Include debugging code, commented-out code, or temporary TODOs.\n- Leave commits that break if a later commit in the PR is dropped.\n  When a commit is flagged as potentially droppable, verify all\n  earlier commits work correctly without it.\n\n### Commit Message Format\n\n```\nsubsystem: Summary in 72 characters or less.\n\nThe body explains why and how. Include context that helps reviewers\nand future developers understand your reasoning, analysis, and\nverification of the work above and beyond CI, without repeating\ndetails already well presented in the commit metadata (filenames,\netc.). Explain what the change accomplishes and why it won't break\nthings one might worry about.\n\nLine-wrap at 68-70 characters, except URLs and verbatim content\n(error messages, etc.).\n\nFixes #123.\n```\n\n**Commit summary format:**\n\n- Example: `Fix cursor position after emoji insertion`\n- Example: `Refactor immutable cache headers`\n- Bad examples: `Fix bug`, `Update code`, `gather_subscriptions was broken`\n\n**Linking issues:**\n\n- `Fixes #123` automatically closes the issue\n- `Addresses #123` does not close (for partial fixes)\n- In a multi-commit PR, use `Addresses #123` in earlier commits\n  and `Fixes #123` in the final commit.\n\n### Rebasing Commits (Non-Interactive)\n\nSince `git rebase -i` requires an interactive editor, use\n`GIT_SEQUENCE_EDITOR` to supply the todo list via a script:\n\n1. **Updating the HEAD commit:** If the commit you need to modify is\n   already at HEAD, just use `git commit --amend` directly. The\n   fixup+rebase workflow below is only needed for non-HEAD commits.\n\n2. **Squashing fixups into existing commits:** Create fixup commits with\n   `git commit --fixup=<target-hash>`, then write a shell script that\n   outputs the desired todo (with `pick` and `fixup` lines in order)\n   and run:\n\n   ```bash\n   GIT_SEQUENCE_EDITOR=/path/to/todo-script.sh git rebase -i <base>\n   ```\n\n   Note: `--autosquash` alone without `-i` does **not** reorder or\n   squash anything.\n\n3. **Rewording commit messages:** Use `git format-patch` to export\n   commits as patch files, edit the message headers in the patch\n   files, then reapply:\n\n   ```bash\n   git format-patch <base> -o /tmp/patches/\n   # Edit the commit message in each /tmp/patches/000N-*.patch file\n   # (the message is between the Subject: line and the --- line)\n   git reset --hard <base>\n   git am /tmp/patches/*.patch\n   ```\n\n## Testing Requirements\n\nAutomated code generation must include tests for all components\nto prevent regressions.\n\nThere are three kinds of tests:\n- Unit tests: Test single functions, simple functionality, very\n  easy to run, if at all possible, these should be used to test\n  functionality.\n- Headless tests: Robolectric is used for testing anything that\n  doesn't require a phone, it allows for extensive mocking and \n  UI interaction simulation without the full UI overhead.\n- Emulator tests: Using Espresso and other tools, very heavy to\n  run, create these tests as a last resort.\n\n### Before Submitting:\n\nCheck that the new features, or fixed bugs are being properly tested\nfor regressions.\n\n### Testing Philosophy:\n\n- Write end-to-end tests when possible verifying what's important.\n- A good failing test before implementing is good practice so your\n  test and code can jointly verify each other.\n- Remember to always assert state is correctly updated, not just \"success\".\n\n## Self-Review Checklist\n\nBefore finalizing, verify:\n\n- [ ] The PR addresses all points described in the issue\n- [ ] All relevant tests pass locally\n- [ ] Code follows existing patterns in the codebase\n- [ ] Names (functions, variables, tests) are clear and greppable\n- [ ] Commit messages, comments, and PR description are well done\n- [ ] Each commit is a minimal coherent idea\n- [ ] No debugging code or unnecessary comments remain\n- [ ] Type annotations are complete and correct\n- [ ] User-facing strings are in strings.xml\n- [ ] User-facing error messages are clear and actionable\n- [ ] No secrets or credentials are hardcoded\n- [ ] Documentation is updated if behavior changes\n- [ ] Refactoring is complete (`git grep` for remaining occurrences)\n- [ ] Security audit of changes\n\nAlways output a recommend pull request summary+description that\nfollow's Amaze's guidelines once you finish preparing a series of\ncommits.\n\n## Common Pitfalls\n\n### Treating Known Issues as Acceptable\n\nA common failure mode is discovering a problem during verification\nand then noting it as a known limitation rather than fixing it.\n\n**Mitigation:** When you find any issue during verification, fix it\nbefore presenting the work. If a fix would require a design decision,\nraise it as a question rather than shipping the broken state.\n\n### Missing Test Updates\n\nTests must be in the same commit as the code they test.\n\n**Mitigation:** Include test updates in each commit. Show what tests need to\nchange.\n\n### Verbose Commit Messages\n\nCommits are concise, say everything that's important for a reviewer to\nunderstand about the motivation for the work and changes, and nothing more.\nAvoid wordiness and details obvious to someone who is looking at the\ncommit and its metadata (lists of filenames, etc).\n\n**Mitigation:** Keep summary under 72 characters. Body should explain why,\nnot what.\n\n### Mixing Concerns\n\nMultiple changes in one commit makes review difficult.\n\n**Mitigation:** Each commit should do exactly one thing. Plan\nnecessary refactoring and preparatory commits in advance of functional\nchanges. You can split into good commits after the fact, but it's much\nfaster and easier to just plan and write them well the first time.\n\n## Pull Request Guidelines\n\n### PR Description Should:\n\nWhen opening a pull request, prefix the PR title with `[ai]` (e.g.,\n`[ai] compose: Fix cursor position after emoji insertion.`). Use\n`upstream/main` as the base branch.\n\nOutput the PR description in a markdown code block so that formatting\n(bold, headers, checkboxes, etc.) copy-pastes correctly into GitHub.\n\n1. Start with a `Fixes: #...` line linking the issue being addressed.\n2. Explain **why** the change is needed, not just what changed.\n3. Describe how you tested the change, using checkbox format for the\n   test plan (e.g., `- [x] ./tools/test-backend ...`).\n4. Include screenshots for UI changes.\n5. Link to relevant issues or discussions.\n6. Call out any open questions, concerns, or decisions you are uncertain\n   about, so they can be resolved during review.\n7. Include the self-review checklist from\n   `.github/pull_request_template.md` using checkbox format (`- [x]` /\n   `- [ ]`), checking off all applicable items.\n\n### PR Description Should Not:\n\n- Regurgitate information visible from the diff\n- Make claims you haven't double-checked\n- Express more certainty than is justified given the evidence\n\n## When to Pause and Discuss\n\nRecommend pausing for discussion when:\n\n- The approach involves security-sensitive code\n- Database migrations are needed\n- The change affects many files (>10)\n- Performance implications are unclear\n- The feature design isn't fully specified\n- The API or data model design isn't fully specified\n- Existing tests are failing for unclear reasons\n\n## Task-Specific Approaches\n\n### For Bug Fixes\n\n1. Show the relevant code and explain what's happening\n2. Brainstorm theories for how the bug might be possible\n3. Analyze and propose a fix with a clear explanation\n4. Write tests that would have caught this bug if possible\n5. Format as a single commit following commit guidelines\n6. Audit for whether the bug may exist elsewhere or might be\n   re-introduced and propose appropriate changes to address if so.\n\n### For New Features\n\n1. Show similar existing features in the codebase\n2. Propose an implementation approach before coding\n3. Implement in minimal, coherent commits\n4. Each commit must pass tests independently\n\n### For Refactoring\n\n1. Show the current implementation\n2. Explain what makes it problematic\n3. Propose the refactoring approach\n4. Implement in commits that each leave the codebase working\n5. No behavior changes unless explicitly discussed\n6. Verify completeness: use `git grep` to find all occurrences and\n   confirm nothing was missed\n\n## Repository Structure Quick Reference\n\n- `app` contains the main app\n- `commons_compress_7z` is the 7z compression and decompression library \n- `file_operations` is a rust library which contain some of the low level\n  operations needed by Amaze\n- `portscanner` is a network library used by various systems in Amaze\n- `scripts` is a directory that contains general tools for maintaining the \n  app\n- `fastlane` is a directory that maintains the resources for FDroid and other\n  open source app repositories \n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Guidelines for AI Contributions to Amaze File Manager\n\nThis file provides guidance to AI coding assistants for contributing\nto the codebase. These guidelines are designed to produce \ncontributions that meet the same high standards we expect from human\ncontributors. The original reference for this file is the Zulip\nCLAUDE.md file, we thank the Zulip team for their work.\n\n## Philosophy\n\n### No detail is too small\n\nAmaze holds itself to a high bar for polish because users depend on\nthis software daily, and because the project is built to last for\ndecades. There is no category of \"minor issue\" that is acceptable\nto ship, if something is broken in any context where a user would\nencounter it, it must be fixed before merging. The project's\nextensive investment in testing, tooling, and review processes exists\nprecisely so that these issues get caught and fixed, not so that they\ncan be classified as low-priority and deferred.\n\nThe right attitude is: \"What could go wrong, and how do I verify that\nit doesn't?\" not \"It looks fine to me.\" **What isn't tested probably\ndoesn't work** - this applies to visual changes just as much as to\nbackend logic.\n\n### Understand before coding\n\nBefore writing any code, you must understand:\n\n1. What the existing code does and why, including the relevant help center or\n   developer-facing documentation.\n2. What problem you're solving, in its full scope.\n3. Why your approach is the right solution, and available alternatives.\n4. How you will verify that your work is correct, and avoid regressions\n   that are plausible for the type of work you're doing.\n\nThe answer to \"Why is X an improvement?\" should never be \"I'm not sure.\"\n\n## Workflow\n\nFollow this workflow for every task: **understand → propose → implement → verify**.\n\n### 1. Understand Before Coding\n\nBefore making any changes:\n\n```bash\n# Look at existing code patterns\ngit grep \"similar_function_name\"\ngit log --oneline -20 -- path/to/file.py\n\n# Check for related issues on GitHub\n```\n\nAlways show existing similar code and explain how it works before proposing\nchanges.\n\n### 2. Propose an Approach\n\nBefore writing code, explain the plan:\n\n- Explain your understanding of the problem and all relevant design decisions\n- What changes are needed and why\n- How the changes fit with existing patterns\n- What could break and how to prevent regressions\n\n### 3. Implement in Minimal, Coherent Commits\n\nEach commit should be self-contained, highly readable and reviewable\nusing `git show --color-moved`, and pass lint/tests independently. If\nextracting new files or moving code, always do that in a separate\ncommit from other changes.\n\n### 4. Verify Before Finalizing\n\nRun tests before making a commit. Always manage your time by running\nspecific test collections, not the entire test suite.\n\n## Before You Start\n\n### Read the Relevant Documentation\n\nBefore working on any area:\n\n- Read the @CONTRIBUTING.md guidelines.\n- Read existing code in the area you're modifying.\n- Use `git grep` to find similar patterns in the codebase and read those.\n\n### Understand the Code Style\n\n- **Be consistent with existing code.** Look at surrounding code and follow\n  the same patterns, as this is a thoughtfully crafted codebase.\n- **Use clear, greppable names** for functions, arguments, variables, and\n  tests. Future developers will `git grep` for relevant terms when\n  researching a problem, so names should communicate purpose clearly.\n- Keep everything well factored for maintainability. Avoid duplicating\n  code, especially where access control or subtle correctness is involved.\n- Prefer writing code that is readable without explanation over heavily\n  commented code using clever tricks. Comments should explain \"why\" when\n  the reason isn't obvious, not narrate \"what\" the code does.\n- Comments generally should have a line to themselves.\n\n## Commit Discipline\n\n### Each Commit Must:\n\n1. **Be coherent**: Implement one logical change completely and atomically.\n2. **Pass tests**: Include test updates in the same commit as code changes.\n3. **Not make Amaze worse**: Work is ordered so no commit has regressions.\n4. **Be safe to deploy individually**: Or explain in detail why not.\n5. **Be minimal** and **reviewable**: Don't combine moving code with changing\n   it in the same commit; make liberal use of small prep commits for\n   no-op refactoring that are easy to verify.\n\n### Never:\n\n- Mix multiple separable changes in a single commit.\n- Create a commit that \"fixes\" a mistake from an earlier commit in the same PR;\n  always edit Git to fix the original commit.\n- Add content in one commit only to remove or move it in the next;\n  plan upfront what belongs where and do it right the first time.\n- Include debugging code, commented-out code, or temporary TODOs.\n- Leave commits that break if a later commit in the PR is dropped.\n  When a commit is flagged as potentially droppable, verify all\n  earlier commits work correctly without it.\n\n### Commit Message Format\n\n```\nsubsystem: Summary in 72 characters or less.\n\nThe body explains why and how. Include context that helps reviewers\nand future developers understand your reasoning, analysis, and\nverification of the work above and beyond CI, without repeating\ndetails already well presented in the commit metadata (filenames,\netc.). Explain what the change accomplishes and why it won't break\nthings one might worry about.\n\nLine-wrap at 68-70 characters, except URLs and verbatim content\n(error messages, etc.).\n\nFixes #123.\n```\n\n**Commit summary format:**\n\n- Example: `Fix cursor position after emoji insertion`\n- Example: `Refactor immutable cache headers`\n- Bad examples: `Fix bug`, `Update code`, `gather_subscriptions was broken`\n\n**Linking issues:**\n\n- `Fixes #123` automatically closes the issue\n- `Addresses #123` does not close (for partial fixes)\n- In a multi-commit PR, use `Addresses #123` in earlier commits\n  and `Fixes #123` in the final commit.\n\n### Rebasing Commits (Non-Interactive)\n\nSince `git rebase -i` requires an interactive editor, use\n`GIT_SEQUENCE_EDITOR` to supply the todo list via a script:\n\n1. **Updating the HEAD commit:** If the commit you need to modify is\n   already at HEAD, just use `git commit --amend` directly. The\n   fixup+rebase workflow below is only needed for non-HEAD commits.\n\n2. **Squashing fixups into existing commits:** Create fixup commits with\n   `git commit --fixup=<target-hash>`, then write a shell script that\n   outputs the desired todo (with `pick` and `fixup` lines in order)\n   and run:\n\n   ```bash\n   GIT_SEQUENCE_EDITOR=/path/to/todo-script.sh git rebase -i <base>\n   ```\n\n   Note: `--autosquash` alone without `-i` does **not** reorder or\n   squash anything.\n\n3. **Rewording commit messages:** Use `git format-patch` to export\n   commits as patch files, edit the message headers in the patch\n   files, then reapply:\n\n   ```bash\n   git format-patch <base> -o /tmp/patches/\n   # Edit the commit message in each /tmp/patches/000N-*.patch file\n   # (the message is between the Subject: line and the --- line)\n   git reset --hard <base>\n   git am /tmp/patches/*.patch\n   ```\n\n## Testing Requirements\n\nAutomated code generation must include tests for all components\nto prevent regressions.\n\nThere are three kinds of tests:\n- Unit tests: Test single functions, simple functionality, very\n  easy to run, if at all possible, these should be used to test\n  functionality.\n- Headless tests: Robolectric is used for testing anything that\n  doesn't require a phone, it allows for extensive mocking and \n  UI interaction simulation without the full UI overhead.\n- Emulator tests: Using Espresso and other tools, very heavy to\n  run, create these tests as a last resort.\n\n### Before Submitting:\n\nCheck that the new features, or fixed bugs are being properly tested\nfor regressions.\n\n### Testing Philosophy:\n\n- Write end-to-end tests when possible verifying what's important.\n- A good failing test before implementing is good practice so your\n  test and code can jointly verify each other.\n- Remember to always assert state is correctly updated, not just \"success\".\n\n## Self-Review Checklist\n\nBefore finalizing, verify:\n\n- [ ] The PR addresses all points described in the issue\n- [ ] All relevant tests pass locally\n- [ ] Code follows existing patterns in the codebase\n- [ ] Names (functions, variables, tests) are clear and greppable\n- [ ] Commit messages, comments, and PR description are well done\n- [ ] Each commit is a minimal coherent idea\n- [ ] No debugging code or unnecessary comments remain\n- [ ] Type annotations are complete and correct\n- [ ] User-facing strings are in strings.xml\n- [ ] User-facing error messages are clear and actionable\n- [ ] No secrets or credentials are hardcoded\n- [ ] Documentation is updated if behavior changes\n- [ ] Refactoring is complete (`git grep` for remaining occurrences)\n- [ ] Security audit of changes\n\nAlways output a recommend pull request summary+description that\nfollow's Amaze's guidelines once you finish preparing a series of\ncommits.\n\n## Common Pitfalls\n\n### Treating Known Issues as Acceptable\n\nA common failure mode is discovering a problem during verification\nand then noting it as a known limitation rather than fixing it.\n\n**Mitigation:** When you find any issue during verification, fix it\nbefore presenting the work. If a fix would require a design decision,\nraise it as a question rather than shipping the broken state.\n\n### Missing Test Updates\n\nTests must be in the same commit as the code they test.\n\n**Mitigation:** Include test updates in each commit. Show what tests need to\nchange.\n\n### Verbose Commit Messages\n\nCommits are concise, say everything that's important for a reviewer to\nunderstand about the motivation for the work and changes, and nothing more.\nAvoid wordiness and details obvious to someone who is looking at the\ncommit and its metadata (lists of filenames, etc).\n\n**Mitigation:** Keep summary under 72 characters. Body should explain why,\nnot what.\n\n### Mixing Concerns\n\nMultiple changes in one commit makes review difficult.\n\n**Mitigation:** Each commit should do exactly one thing. Plan\nnecessary refactoring and preparatory commits in advance of functional\nchanges. You can split into good commits after the fact, but it's much\nfaster and easier to just plan and write them well the first time.\n\n## Pull Request Guidelines\n\n### PR Description Should:\n\nWhen opening a pull request, prefix the PR title with `[ai]` (e.g.,\n`[ai] compose: Fix cursor position after emoji insertion.`). Use\n`upstream/main` as the base branch.\n\nOutput the PR description in a markdown code block so that formatting\n(bold, headers, checkboxes, etc.) copy-pastes correctly into GitHub.\n\n1. Start with a `Fixes: #...` line linking the issue being addressed.\n2. Explain **why** the change is needed, not just what changed.\n3. Describe how you tested the change, using checkbox format for the\n   test plan (e.g., `- [x] ./tools/test-backend ...`).\n4. Include screenshots for UI changes.\n5. Link to relevant issues or discussions.\n6. Call out any open questions, concerns, or decisions you are uncertain\n   about, so they can be resolved during review.\n7. Include the self-review checklist from\n   `.github/pull_request_template.md` using checkbox format (`- [x]` /\n   `- [ ]`), checking off all applicable items.\n\n### PR Description Should Not:\n\n- Regurgitate information visible from the diff\n- Make claims you haven't double-checked\n- Express more certainty than is justified given the evidence\n\n## When to Pause and Discuss\n\nRecommend pausing for discussion when:\n\n- The approach involves security-sensitive code\n- Database migrations are needed\n- The change affects many files (>10)\n- Performance implications are unclear\n- The feature design isn't fully specified\n- The API or data model design isn't fully specified\n- Existing tests are failing for unclear reasons\n\n## Task-Specific Approaches\n\n### For Bug Fixes\n\n1. Show the relevant code and explain what's happening\n2. Brainstorm theories for how the bug might be possible\n3. Analyze and propose a fix with a clear explanation\n4. Write tests that would have caught this bug if possible\n5. Format as a single commit following commit guidelines\n6. Audit for whether the bug may exist elsewhere or might be\n   re-introduced and propose appropriate changes to address if so.\n\n### For New Features\n\n1. Show similar existing features in the codebase\n2. Propose an implementation approach before coding\n3. Implement in minimal, coherent commits\n4. Each commit must pass tests independently\n\n### For Refactoring\n\n1. Show the current implementation\n2. Explain what makes it problematic\n3. Propose the refactoring approach\n4. Implement in commits that each leave the codebase working\n5. No behavior changes unless explicitly discussed\n6. Verify completeness: use `git grep` to find all occurrences and\n   confirm nothing was missed\n\n## Repository Structure Quick Reference\n\n- `app` contains the main app\n- `commons_compress_7z` is the 7z compression and decompression library \n- `file_operations` is a rust library which contain some of the low level\n  operations needed by Amaze\n- `portscanner` is a network library used by various systems in Amaze\n- `scripts` is a directory that contains general tools for maintaining the \n  app\n- `fastlane` is a directory that maintains the resources for FDroid and other\n  open source app repositories \n","category":"root","tokens":3337}]}