Skip to content

Commit 25f5260

Browse files
SipherSipher
committed
Add CLAUDE.md for agent guidelines and best practices in using the Torus documentation repository for consistency and clarity
1 parent f0a8cd5 commit 25f5260

File tree

3 files changed

+459
-0
lines changed

3 files changed

+459
-0
lines changed

‎CLAUDE.md‎

Lines changed: 255 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,255 @@
1+
# Assistant Instructions - Torus Documentation
2+
3+
**Required reading for AI agents modifying this repository**
4+
5+
## Project Overview
6+
7+
Torus documentation built with Astro and Starlight. Contains comprehensive guides, explanations, and tutorials for the Torus protocol ecosystem.
8+
9+
## Terminology Guidelines
10+
11+
### Correct Naming
12+
- **Protocol**: Torus (NOT "Torus Network")
13+
- **Token**: TORUS (uppercase when referring to the token)
14+
- **Usage Examples**:
15+
- ✅ "Torus is a decentralized protocol"
16+
- ✅ "Stake TORUS tokens"
17+
- ✅ "The Torus ecosystem"
18+
- ❌ "Torus Network protocol"
19+
- ❌ "The Torus Network"
20+
21+
### Consistent References
22+
- Always use "Torus" when referring to the protocol
23+
- Use "TORUS" when referring to the token/ticker
24+
- Never add "Network" suffix
25+
- Keep naming minimal and precise
26+
27+
## Essential Commands
28+
29+
### Development Workflow
30+
31+
```sh
32+
# Install dependencies
33+
pnpm install
34+
35+
# Start development server
36+
pnpm run dev
37+
# Server runs at localhost:4321
38+
39+
# Build for production
40+
pnpm run build
41+
42+
# Preview production build
43+
pnpm run preview
44+
45+
# Type checking
46+
pnpm run astro check
47+
```
48+
49+
## Critical Requirements
50+
51+
**ALWAYS follow these steps when working on this repository:**
52+
53+
1. Read this CLAUDE.md file first
54+
2. Maintain minimalistic approach - less is more
55+
3. Follow existing file standards exactly
56+
4. Validate all changes before committing
57+
58+
## File Standards
59+
60+
### MDX Files
61+
62+
- Use `.mdx` extension for all documentation
63+
- Include frontmatter with `title` and `description`
64+
- Import components at top after frontmatter
65+
- No emojis in documentation content
66+
- Keep language concise and technical
67+
68+
### Frontmatter Template
69+
70+
```yaml
71+
---
72+
title: Clear Descriptive Title
73+
description: One-line description of the content
74+
---
75+
```
76+
77+
## Critical Files to Update
78+
79+
### When Adding New Documentation
80+
81+
1. **Update astro.config.mjs**
82+
- Add new page to sidebar navigation
83+
- Maintain hierarchical structure
84+
- Use consistent naming: `{ label: "Display Name", slug: "path/to/file" }`
85+
- Collapsed sections for subcategories
86+
87+
2. **Update Table of Contents**
88+
- File: `src/content/docs/explanations/table-of-contents.mdx`
89+
- Add new entries in appropriate section
90+
- Include full URL links
91+
- Maintain alphabetical or logical ordering
92+
93+
3. **Update How-to Table of Contents (if applicable)**
94+
- File: `src/content/docs/how-to-guides/table-of-contents.mdx`
95+
- Follow same pattern as explanations
96+
97+
## Link Validation
98+
99+
**CRITICAL: Always check for broken references**
100+
101+
Before committing:
102+
103+
```sh
104+
# Find all references to a file
105+
grep -r "old-filename" src/content/docs/
106+
107+
# Check for broken internal links
108+
grep -r "slug:" astro.config.mjs
109+
110+
# Build to verify no broken links
111+
pnpm run build
112+
```
113+
114+
## Project Structure
115+
116+
```
117+
torus-docs/
118+
├── src/
119+
│ ├── content/
120+
│ │ └── docs/ # All documentation content
121+
│ │ ├── development/
122+
│ │ ├── explanations/
123+
│ │ ├── getting-started/
124+
│ │ ├── how-to-guides/
125+
│ │ └── index.mdx
126+
│ ├── assets/ # Images and static assets
127+
│ └── components/ # Custom React/Astro components
128+
├── astro.config.mjs # Main configuration and sidebar
129+
├── package.json
130+
├── TRAIN.md # AI training guide
131+
├── README.md
132+
└── CLAUDE.md # This file
133+
```
134+
135+
## Naming Conventions
136+
137+
### File Names
138+
- Use kebab-case: `permission-system.mdx`
139+
- Be descriptive but concise
140+
- Match slug in astro.config.mjs
141+
142+
### Paths
143+
- Organized by category:
144+
- `getting-started/` - Foundational concepts
145+
- `explanations/system/` - Core architecture
146+
- `explanations/builders/` - Agent development
147+
- `explanations/holders/` - Token and staking
148+
- `explanations/goal-leaders/` - Coordination
149+
- `how-to-guides/` - Step-by-step tutorials
150+
- `development/` - Technical implementation
151+
152+
## Content Guidelines
153+
154+
### Writing Style
155+
- Technical and precise
156+
- No marketing language
157+
- Direct and actionable
158+
- Use present tense
159+
- Avoid redundancy
160+
161+
### Structure
162+
- Start with core concept
163+
- Build complexity gradually
164+
- Use clear headers
165+
- Include practical examples
166+
- Reference related files
167+
168+
### Documentation Standards
169+
- Follow consistent formatting across all files
170+
- Use code blocks with appropriate language tags (`ts`, `sh`, `yaml`)
171+
- Include file paths when referencing code
172+
- Keep examples minimal but complete
173+
174+
## Testing Requirements
175+
176+
```sh
177+
# Check TypeScript and build integrity
178+
pnpm run astro check
179+
180+
# Build the site to check for errors
181+
pnpm run build
182+
183+
# Preview locally to verify changes
184+
pnpm run preview
185+
```
186+
187+
## Common Pitfalls to Avoid
188+
189+
1. **DO NOT** create duplicate entries in astro.config.mjs
190+
2. **DO NOT** forget to update table of contents
191+
3. **DO NOT** use relative links - use full paths or slugs
192+
4. **DO NOT** add unnecessary documentation
193+
5. **DO NOT** break existing link references
194+
6. **DO NOT** use inconsistent formatting
195+
7. **DO NOT** add emojis to documentation
196+
8. **DO NOT** use "Torus Network" - use "Torus" only
197+
198+
## Quick Checklist
199+
200+
### Before Making Changes
201+
- [ ] Read CLAUDE.md
202+
- [ ] Understand file naming conventions
203+
- [ ] Know which files need updates
204+
- [ ] Check current documentation structure
205+
- [ ] Review terminology guidelines
206+
207+
### After Making Changes
208+
- [ ] Updated astro.config.mjs if added new file
209+
- [ ] Updated table of contents if applicable
210+
- [ ] Searched for and fixed broken references
211+
- [ ] Ran `pnpm run build` to verify no errors
212+
- [ ] Maintained consistent formatting
213+
- [ ] Kept content minimalistic
214+
- [ ] Verified correct "Torus" naming (not "Torus Network")
215+
216+
## File Relationships
217+
218+
```
219+
New Documentation File
220+
├── Create .mdx file in appropriate directory
221+
├── Update astro.config.mjs sidebar
222+
├── Update relevant table-of-contents.mdx
223+
└── Check/update any cross-references
224+
```
225+
226+
## Component Usage
227+
228+
Available Starlight components:
229+
- `CardGrid`, `Card` - For feature grids
230+
- `LinkCard` - For navigation cards
231+
- `Aside` - For notes and warnings
232+
- `Steps` - For sequential instructions
233+
- `Tabs`, `TabItem` - For multiple code examples
234+
235+
Import at top of MDX files:
236+
```ts
237+
import { CardGrid, LinkCard, Aside } from "@astrojs/starlight/components";
238+
```
239+
240+
## Environment Configuration
241+
242+
- Site URL: https://docs.torus.network
243+
- Development port: 4321
244+
- Build output: `./dist/`
245+
246+
## Documentation Categories
247+
248+
1. **Getting Started**: Core concepts and onboarding
249+
2. **Explanations**: Deep technical understanding
250+
3. **How-to Guides**: Practical step-by-step tutorials (mostly UI-focused)
251+
4. **Development**: API and integration documentation
252+
253+
---
254+
255+
**Remember: Minimalistic, consistent, validated, and always "Torus" not "Torus Network"**

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,10 @@ Static assets, like favicons, can be placed in the `public/` directory.
2727

2828
To add new categories in the sibebar update the `astro.config.mjs` file.
2929

30+
## 🤖 For Agents
31+
32+
Agents can refer to **[TRAIN.md](./TRAIN.md)** for instructions on how to consume and navigate this documentation repository to understand the Torus protocol and system architecture.
33+
3034
## Commands
3135

3236
All commands are run from the root of the project, from a terminal:

0 commit comments

Comments
 (0)