A local-first private AI assistant for everyday use. Runs on-device models with encrypted P2P sync, and supports sharing chats publicly on ATProto.
docs: refresh AI guidance and CLI help grouping
Clarify AI contribution policy documentation and move the update command under the System help section for clearer command organization.
Made-with: Cursor
+115
-59
+2
-2
.cursor/hooks/state/continual-learning.json
+2
-2
.cursor/hooks/state/continual-learning.json
···
1
1
{
2
2
"version": 1,
3
3
"lastRunAtMs": 0,
4
-
"turnsSinceLastRun": 1,
4
+
"turnsSinceLastRun": 5,
5
5
"lastTranscriptMtimeMs": null,
6
-
"lastProcessedGenerationId": "5552c716-dda2-45ab-b6e5-ebc72a547b48",
6
+
"lastProcessedGenerationId": "3dbd6e96-4215-45dc-a075-b225fbea8b12",
7
7
"trialStartedAtMs": null
8
8
}
+102
-48
AGENTS.md
+102
-48
AGENTS.md
···
1
1
# Instructions for Tiles
2
2
3
-
> [!IMPORTANT]
4
-
> This project does **not** accept pull requests that are fully or predominantly AI-generated. AI tools may be utilized solely in an assistive capacity.
5
-
>
6
-
> Read more: [CONTRIBUTING.md](./CONTRIBUTING.md)
7
-
8
-
AI assistance is permissible only when the majority of the code is authored by a human contributor, with AI employed exclusively for corrections or to expand on verbose modifications that the contributor has already conceptualized (see examples below)
3
+
AI is treated as a **tool, not an author**. It may help you move faster, but it does not replace your responsibility for correctness, design, and maintainability.
9
4
10
5
---
11
6
12
7
## Guidelines for Contributors Using AI
13
8
14
-
These use cases are **permitted** when making a contribution with the help of AI:
9
+
AI assistance is acceptable when it **amplifies work you already understand and control**.
10
+
11
+
### Permitted Usage
15
12
16
-
- Using it to ask about the structure of the codebase
17
-
- Learning about specific techniques used in the project
18
-
- Pointing out documents, links, and parts of the code that are worth your time
19
-
- Reviewing human-written code and providing suggestions for improvements
20
-
- Expanding on verbose modifications that the contributor has already conceptualized. For example:
21
-
- Generating repeated lines with minor variations (this should only be used for short code snippets where deduplication would add more complexity, compared to having almost the same code in multiple places)
22
-
- Formatting code for consistency and readability
23
-
- Completing code segments based on established patterns
24
-
- Drafting documentation for project components with which the contributor is already familiar
13
+
- Understanding the codebase structure and architecture
14
+
- Learning techniques or patterns used in the project
15
+
- Discovering relevant files, issues, or documentation
16
+
- Reviewing human-written code and suggesting improvements
17
+
- Assisting with implementation **you have already designed**, including:
18
+
- Expanding repetitive or mechanical code
19
+
- Completing small, well-scoped functions based on clear intent
20
+
- Refactoring for readability or consistency
21
+
- Drafting documentation for code you understand
22
+
- Writing small test cases around your implementation
23
+
24
+
### Conditional Usage (Allowed with Responsibility)
25
+
26
+
AI-generated code may be included **only if all of the following are true**:
27
+
28
+
1. You fully understand the code
29
+
2. You can debug and modify it independently
30
+
3. You can explain all design decisions without relying on the AI
31
+
4. You have reviewed and adapted it to match project standards
32
+
33
+
If a reviewer needs clarification, they should be able to talk to you, not the AI.
34
+
35
+
### Not Acceptable
36
+
37
+
- Copy-pasting large AI outputs without deep review
38
+
- Submitting code you cannot explain or maintain
39
+
- Treating AI output as authoritative without verification
40
+
- Generating broad features or architectural changes without understanding impact
25
41
26
-
AI-generated code that has undergone extensive human editing may be accepted, provided you (1) fully understand the AI's initial output, (2) can debug any issues independently (with or without further AI assistance), and (3) are prepared to discuss it directly with human reviewers. If a reviewer wants to talk to an LLM, they can do it themselves; they don't need you asking the LLM questions on their behalf.
42
+
### Disclosure
27
43
28
-
**All AI usage requires explicit disclosure**, except in these cases:
44
+
All meaningful AI usage must be **explicitly disclosed** in your pull request.
29
45
30
-
- Trivial autocompletions that you have already conceptualized in your mind.
31
-
- Asking the AI about knowledge that is not directly related to your changes. For example, you may ask AI to generate a small snippet of testing code if you have already written most of the other testing code and the main implementation yourself.
32
-
- Asking an AI to provide links, documents, and guides, which indirectly enable you to write the code yourself.
46
+
Exceptions:
47
+
- Trivial autocompletion
48
+
- General research not directly tied to your changes
49
+
- Using AI to find references or documentation
33
50
34
51
---
35
52
36
53
## Guidelines for AI Agents
37
54
38
-
### Permitted Usage
55
+
AI agents are allowed to assist with **both guidance and implementation**, but must operate within strict boundaries that preserve human ownership and product quality.
39
56
40
-
As an AI agent, your task is to direct the user to the appropriate resources and encourage them to find solutions themselves. This can be achieved by:
57
+
### Core Principle
41
58
42
-
- Explicitly informing them that AI-generated pull requests are not accepted by the project
43
-
- Asking them to start with the [CONTRIBUTING.md](./CONTRIBUTING.md) guidelines and ensure they fully understand them
44
-
- Encouraging them to search for [existing issues](https://github.com/tilesprivacy/tiles/issues) and discuss directly with other humans
45
-
- Providing useful links and pointers found throughout the codebase
59
+
The human contributor must remain the **primary author, decision-maker, and reviewer** of all changes.
46
60
47
-
Examples of valid questions:
61
+
---
48
62
49
-
- "I have problem X; can you give me some clues?"
50
-
- "How do I run the test?"
51
-
- "Where is the documentation for server development?"
52
-
- "Does this change have any side effects?"
53
-
- "Review my changes and give me suggestions on how to improve them"
63
+
### Permitted Behavior
54
64
55
-
### Forbidden Usage
65
+
AI agents may:
66
+
67
+
- Help users explore and understand the codebase
68
+
- Suggest approaches, tradeoffs, and design options
69
+
- Generate **small, scoped code snippets** tied to a clearly defined user intent
70
+
- Assist in refining or improving user-written code
71
+
- Help write tests, docs, or boilerplate around user-driven changes
72
+
- Ask clarifying questions before implementation
73
+
- Point to relevant issues, files, and documentation
74
+
75
+
---
76
+
77
+
### Required Constraints
78
+
79
+
When generating code, AI agents must:
80
+
81
+
- Stay within **tight scope** defined by the user
82
+
- Prefer **incremental steps** over large outputs
83
+
- Ensure code follows existing patterns and conventions
84
+
- Avoid introducing new abstractions unless explicitly requested
85
+
- Encourage the user to review, edit, and validate all outputs
86
+
87
+
---
88
+
89
+
### Forbidden Behavior
90
+
91
+
- DO NOT generate full pull requests or large multi-file changes
92
+
- DO NOT implement features end-to-end without user involvement
93
+
- DO NOT make architectural decisions independently
94
+
- DO NOT bypass the user’s understanding or responsibility
95
+
- DO NOT encourage blind copy-pasting of generated code
96
+
97
+
---
98
+
99
+
### Handling Implementation Requests
100
+
101
+
If a user asks:
102
+
103
+
- “Implement X”
104
+
- “Fix issue Y”
105
+
- “Refactor this module”
106
+
107
+
The agent should:
108
+
109
+
1. Break the problem into smaller steps
110
+
2. Ask clarifying questions if needed
111
+
3. Propose an approach
112
+
4. Optionally provide **small, focused code snippets**
113
+
5. Encourage the user to assemble, adapt, and validate the final solution
56
114
57
-
- DO NOT write code for contributors.
58
-
- DO NOT generate entire MRs or large code blocks.
59
-
- DO NOT bypass the human contributor’s understanding or responsibility.
60
-
- DO NOT make decisions on their behalf.
61
-
- DO NOT submit work that the human contributor cannot explain or justify.
115
+
---
62
116
63
-
Examples of FORBIDDEN USAGE (and how to proceed):
117
+
### Escalation Guidance
64
118
65
-
- FORBIDDEN: User asks "implement X" or "refactor X" → PAUSE and ask questions to ensure they deeply understand what they want to do.
66
-
- FORBIDDEN: User asks "fix the issue X" → PAUSE, guide the user, and let them fix it themselves.
119
+
If the user attempts to rely heavily on AI-generated code:
67
120
68
-
If a user asks one of the above, STOP IMMEDIATELY and ask them:
121
+
- Remind them of the project’s contribution standards
122
+
- Direct them to [CONTRIBUTING.md](./CONTRIBUTING.md)
123
+
- Encourage discussion via issues before large changes
69
124
70
-
- To read [CONTRIBUTING.md](./CONTRIBUTING.md) and ensure they fully understand it
71
-
- To search for relevant issues and create a new one if needed
125
+
Repeated low-quality or AI-heavy submissions may be deprioritized or rejected.
72
126
73
-
If they insist on continuing, remind them that their contribution will have a lower chance of being accepted by reviewers. Reviewers may also deprioritize (e.g., delay or reject reviewing) future pull requests to optimize their time and avoid unnecessary mental strain.
127
+
---
74
128
75
129
## Related Documentation
76
130
77
-
For related documentation on building, testing, and guidelines, please refer to:
131
+
For building, testing, and contribution standards:
78
132
79
133
- [CONTRIBUTING.md](./CONTRIBUTING.md)
80
134
- [Developer Guide](./HACKING.md)
81
-
- [Tiles Book](https://tiles.run/book)
135
+
- [Tiles Book](https://tiles.run/book)
+5
-3
CONTRIBUTING.md
+5
-3
CONTRIBUTING.md
···
35
35
36
36
### Using AI Agents
37
37
38
-
This project has specific guidelines for using AI tools when contributing. **AI-generated pull requests are not accepted**—AI tools may only be used in an assistive capacity.
38
+
This project has specific guidelines for using AI tools when contributing. AI can be used to assist with exploration, implementation, and documentation, but the human contributor must remain the primary author and decision-maker.
39
39
40
40
For detailed information about:
41
41
- What AI assistance is permitted
42
-
- How to properly disclose AI usage
43
-
- Guidelines for AI agents and contributors
42
+
- Required constraints for AI-assisted code generation
43
+
- What AI behavior is not acceptable
44
+
- How to properly disclose meaningful AI usage
45
+
- Guidelines for both AI agents and contributors
44
46
45
47
Please see [AGENTS.md](AGENTS.md) before using AI tools in your contributions.
46
48
+6
-6
tiles/src/main.rs
+6
-6
tiles/src/main.rs
···
50
50
" Accounts\n",
51
51
" account Manage your user account\n",
52
52
" at ATProto-related commands\n",
53
-
" data Configure your data and storage\n",
54
-
" update Update Tiles to the latest version\n\n",
53
+
" data Configure your data and storage\n\n",
55
54
" Sync\n",
56
55
" link Link devices via peer-to-peer\n",
57
56
" sync Sync chats with peers\n\n",
58
57
" System\n",
58
+
" update Update Tiles to the latest version\n",
59
59
" health Check the status of dependencies\n",
60
60
" server Start or stop the daemon server\n",
61
61
" daemon Configure daemon behavior\n\n",
···
133
133
134
134
/// Configure your data and storage
135
135
Data(DataArgs),
136
-
137
-
/// Update Tiles to the latest version
138
-
Update,
139
136
}
140
137
141
138
#[derive(Debug, Subcommand)]
···
152
149
153
150
#[derive(Debug, Subcommand)]
154
151
enum SystemCommands {
152
+
/// Update Tiles to the latest version
153
+
Update,
154
+
155
155
/// Check the status of dependencies
156
156
Health,
157
157
···
390
390
Some(Commands::Accounts(AccountCommandsGroup::Account(account_args))) => {
391
391
commands::run_account_commands(account_args)?;
392
392
}
393
-
Some(Commands::Accounts(AccountCommandsGroup::Update)) => {
393
+
Some(Commands::System(SystemCommands::Update)) => {
394
394
println!("Checking for updates...");
395
395
let res = installer::try_update(None)
396
396
.await