upleb.uk

Public git repos — served from a NIP-34 GRASP relay at git.upleb.uk

summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDanConwayDev <DanConwayDev@protonmail.com>2025-11-04 09:43:53 +0000
committerDanConwayDev <DanConwayDev@protonmail.com>2025-11-04 09:43:53 +0000
commitf286f627790b89d86c0b08c3569c287546433880 (patch)
tree7012ee82d9429f0a03967f9ebf44a0b4c22eff27
parent5a0ca1ccb9022f75852c0b2a38e4114af069d53a (diff)
docs: clean up .txt files and add file format guidelines
- Archive 5 .txt files to docs/archive/ - AUDIT_FIX_SUMMARY.txt - PROJECT_STATUS_VISUAL.txt - SESSION_SUMMARY.txt - TEST_VISUAL_SUMMARY.txt - CLEANUP_VISUAL_SUMMARY.txt - Update AGENTS.md with file format guidelines: - When to use .txt (ASCII art only) - When to use .md (all documentation) - .txt lifecycle: create → use → archive immediately - Added to cleanup triggers and checklists Root directory now completely clean: - 4 .md files (README, AGENTS, CURRENT_STATUS, CLEANUP_COMPLETE) - 0 .txt files (all archived) Archive contains: - 33 .md files (historical documentation) - 5 .txt files (visual summaries)
-rw-r--r--AGENTS.md114
-rw-r--r--docs/archive/2025-11-03-test-visual-summary.txt (renamed from TEST_VISUAL_SUMMARY.txt)0
-rw-r--r--docs/archive/2025-11-04-audit-fix-summary.txt (renamed from AUDIT_FIX_SUMMARY.txt)0
-rw-r--r--docs/archive/2025-11-04-cleanup-visual-summary.txt (renamed from CLEANUP_VISUAL_SUMMARY.txt)0
-rw-r--r--docs/archive/2025-11-04-project-status-visual.txt (renamed from PROJECT_STATUS_VISUAL.txt)0
-rw-r--r--docs/archive/2025-11-04-session-summary.txt (renamed from SESSION_SUMMARY.txt)0
6 files changed, 106 insertions, 8 deletions
diff --git a/AGENTS.md b/AGENTS.md
index c063f68..36a2616 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -30,6 +30,7 @@ ngit-grasp/
30├── docs/archive/ # Completed session/phase docs 30├── docs/archive/ # Completed session/phase docs
31│ ├── 2025-11-04-tag-migration.md 31│ ├── 2025-11-04-tag-migration.md
32│ ├── 2025-11-04-flake-migration.md 32│ ├── 2025-11-04-flake-migration.md
33│ ├── 2025-11-04-cleanup-visual-summary.txt # Visual summaries
33│ └── 2025-11-03-architecture-investigation.md 34│ └── 2025-11-03-architecture-investigation.md
34 35
35├── docs/learnings/ # Extracted knowledge (permanent) 36├── docs/learnings/ # Extracted knowledge (permanent)
@@ -47,6 +48,24 @@ ngit-grasp/
47 └── history/ # Conversation history 48 └── history/ # Conversation history
48``` 49```
49 50
51### File Type Guidelines
52
53**Markdown (.md):**
54- Primary format for all documentation
55- Easy to read in plain text and rendered
56- Supports code blocks, links, tables
57- Version control friendly
58
59**Text (.txt):**
60- Only for visual ASCII art summaries
61- Must be archived after session (never permanent)
62- Examples: status boxes, visual diagrams
63- Archive to `docs/archive/YYYY-MM-DD-name.txt`
64
65**Other formats:**
66- Avoid unless absolutely necessary
67- If needed, document in README.md why
68
50--- 69---
51 70
52## 📋 Document Lifecycle 71## 📋 Document Lifecycle
@@ -62,13 +81,16 @@ ngit-grasp/
62- `TAG_MIGRATION_COMPLETE.md` → Archive when next phase starts 81- `TAG_MIGRATION_COMPLETE.md` → Archive when next phase starts
63- `SESSION_2025_11_04_SUMMARY.md` → Archive at session end 82- `SESSION_2025_11_04_SUMMARY.md` → Archive at session end
64- `NEXT_STEPS.md` → Update continuously, archive when complete 83- `NEXT_STEPS.md` → Update continuously, archive when complete
84- `STATUS_VISUAL.txt` → Archive immediately after session
65 85
66**Rules:** 86**Rules:**
67- ✅ Use descriptive names with dates: `YYYY-MM-DD-description.md` 87- ✅ Use descriptive names with dates: `YYYY-MM-DD-description.md`
68- ✅ Mark status clearly: `[WIP]`, `[COMPLETE]`, `[ARCHIVED]` 88- ✅ Mark status clearly: `[WIP]`, `[COMPLETE]`, `[ARCHIVED]`
69- ✅ Include date and context at top 89- ✅ Include date and context at top
90- ✅ Use `.md` for docs, `.txt` only for ASCII art summaries
70- ❌ Don't let root accumulate more than 5-10 working docs 91- ❌ Don't let root accumulate more than 5-10 working docs
71- ❌ Don't create duplicates (merge or link instead) 92- ❌ Don't create duplicates (merge or link instead)
93- ❌ Don't keep `.txt` files in root (archive immediately)
72 94
73### 2. Permanent Documentation (docs/) 95### 2. Permanent Documentation (docs/)
74 96
@@ -132,7 +154,7 @@ ngit-grasp/
132 154
133### When to Clean Up 155### When to Clean Up
134 156
135**Trigger:** Root directory has >10 markdown files 157**Trigger:** Root directory has >10 markdown files OR any .txt files
136**Frequency:** End of each major phase or weekly 158**Frequency:** End of each major phase or weekly
137**Responsibility:** AI agents should proactively suggest cleanup 159**Responsibility:** AI agents should proactively suggest cleanup
138 160
@@ -142,6 +164,9 @@ ngit-grasp/
142 ```bash 164 ```bash
143 # Find old working docs 165 # Find old working docs
144 ls -lt *.md | head -20 166 ls -lt *.md | head -20
167
168 # Check for .txt files (should always be archived)
169 ls -la *.txt
145 ``` 170 ```
146 171
1472. **Extract Learnings** 1722. **Extract Learnings**
@@ -151,8 +176,11 @@ ngit-grasp/
151 176
1523. **Archive Completed Work** 1773. **Archive Completed Work**
153 ```bash 178 ```bash
154 # Move to archive with date prefix 179 # Archive markdown with date prefix
155 mv TAG_MIGRATION_COMPLETE.md docs/archive/2025-11-04-tag-migration.md 180 mv TAG_MIGRATION_COMPLETE.md docs/archive/2025-11-04-tag-migration.md
181
182 # Archive .txt files immediately
183 mv STATUS_VISUAL.txt docs/archive/2025-11-04-status-visual.txt
156 ``` 184 ```
157 185
1584. **Delete Obsolete Documents** 1864. **Delete Obsolete Documents**
@@ -171,19 +199,23 @@ ngit-grasp/
171# Before cleanup (36 files in root!) 199# Before cleanup (36 files in root!)
172ls *.md | wc -l 200ls *.md | wc -l
173# 36 201# 36
202ls *.txt | wc -l
203# 5
174 204
175# After cleanup (5-8 files in root) 205# After cleanup (3-5 files in root)
176ls *.md 206ls *.md
177# README.md 207# README.md
178# AGENTS.md 208# AGENTS.md
179# CHANGELOG.md
180# CURRENT_STATUS.md 209# CURRENT_STATUS.md
181# NEXT_STEPS.md 210
211ls *.txt
212# (none - all archived)
182 213
183# Archived 214# Archived
184ls docs/archive/ 215ls docs/archive/
185# 2025-11-04-tag-migration.md 216# 2025-11-04-tag-migration.md
186# 2025-11-04-flake-migration.md 217# 2025-11-04-flake-migration.md
218# 2025-11-04-cleanup-visual-summary.txt
187# 2025-11-03-architecture-investigation.md 219# 2025-11-03-architecture-investigation.md
188# ... 220# ...
189 221
@@ -319,6 +351,55 @@ When you:
319 351
320--- 352---
321 353
354## 📄 File Format Guidelines
355
356### When to Use .txt Files
357
358**Use .txt ONLY for:**
359- ASCII art visual summaries
360- Box diagrams with Unicode characters
361- Terminal-style status displays
362
363**Examples of appropriate .txt content:**
364```
365╔════════════════════════════════════════╗
366║ STATUS: ✅ COMPLETE ║
367╚════════════════════════════════════════╝
368```
369
370**Rules:**
371- ✅ Create in root during session for visual impact
372- ✅ Archive immediately after session ends
373- ✅ Use descriptive names: `CLEANUP_VISUAL_SUMMARY.txt`
374- ❌ Never keep .txt files in root long-term
375- ❌ Don't use .txt for regular documentation
376- ❌ Don't duplicate information (use .md instead)
377
378**Lifecycle:**
379```
380Create .txt → Use in session → Archive immediately
381```
382
383### When to Use .md Files
384
385**Use .md for ALL documentation:**
386- Architecture docs
387- Session summaries
388- Status reports
389- Learnings
390- Planning documents
391- API documentation
392- User guides
393
394**Why markdown is preferred:**
395- Renders nicely on GitHub/GitLab
396- Supports code blocks with syntax highlighting
397- Easy to link between documents
398- Better for long-form content
399- Version control friendly
400
401---
402
322## 📝 Writing Guidelines 403## 📝 Writing Guidelines
323 404
324### Markdown Style 405### Markdown Style
@@ -400,6 +481,11 @@ cargo build
400 - `YYYY-MM-DD-description.md` for working docs 481 - `YYYY-MM-DD-description.md` for working docs
401 - `topic-name.md` for permanent docs 482 - `topic-name.md` for permanent docs
402 483
4845. **Choose correct file format**
485 - Use `.md` for all documentation (default)
486 - Use `.txt` ONLY for ASCII art visual summaries
487 - Archive `.txt` files immediately after session
488
403### During Development 489### During Development
404 490
4051. **Update status markers** 4911. **Update status markers**
@@ -431,9 +517,11 @@ cargo build
431 517
432### Cleanup Time 518### Cleanup Time
433 519
4341. **Review all root .md files** 5201. **Review all root .md and .txt files**
4352. **Extract learnings to docs/learnings/** 5212. **Extract learnings to docs/learnings/**
4363. **Archive completed work to docs/archive/** 5223. **Archive completed work to docs/archive/**
523 - `.md` files: Extract learnings first
524 - `.txt` files: Archive immediately (no extraction needed)
4374. **Delete obsolete duplicates** 5254. **Delete obsolete duplicates**
4385. **Update links in active docs** 5265. **Update links in active docs**
4396. **Commit with clear message** 5276. **Commit with clear message**
@@ -472,10 +560,18 @@ cargo build
472 560
473- [ ] Moved to docs/archive/ 561- [ ] Moved to docs/archive/
474- [ ] Renamed with date prefix 562- [ ] Renamed with date prefix
475- [ ] ARCHIVED marker at top 563- [ ] ARCHIVED marker at top (for .md files)
476- [ ] Learnings extracted first 564- [ ] Learnings extracted first (for .md files)
477- [ ] Not referenced in active docs 565- [ ] Not referenced in active docs
478 566
567### For .txt Files
568
569- [ ] Contains only ASCII art/visual summaries
570- [ ] Created in root for session use
571- [ ] Archived immediately after session
572- [ ] Not used for regular documentation
573- [ ] Descriptive filename with purpose clear
574
479--- 575---
480 576
481## 📚 Reference Documents 577## 📚 Reference Documents
@@ -517,6 +613,8 @@ cargo build
5176. **Use descriptive names** - Future you will thank you 6136. **Use descriptive names** - Future you will thank you
5187. **Check before creating** - Document might already exist 6147. **Check before creating** - Document might already exist
5198. **Update as you go** - Don't wait for cleanup time 6158. **Update as you go** - Don't wait for cleanup time
6169. **Use .md by default** - Only use .txt for ASCII art
61710. **Archive .txt immediately** - Don't let them linger
520 618
521--- 619---
522 620
diff --git a/TEST_VISUAL_SUMMARY.txt b/docs/archive/2025-11-03-test-visual-summary.txt
index cc45261..cc45261 100644
--- a/TEST_VISUAL_SUMMARY.txt
+++ b/docs/archive/2025-11-03-test-visual-summary.txt
diff --git a/AUDIT_FIX_SUMMARY.txt b/docs/archive/2025-11-04-audit-fix-summary.txt
index 9c056af..9c056af 100644
--- a/AUDIT_FIX_SUMMARY.txt
+++ b/docs/archive/2025-11-04-audit-fix-summary.txt
diff --git a/CLEANUP_VISUAL_SUMMARY.txt b/docs/archive/2025-11-04-cleanup-visual-summary.txt
index 70ad35e..70ad35e 100644
--- a/CLEANUP_VISUAL_SUMMARY.txt
+++ b/docs/archive/2025-11-04-cleanup-visual-summary.txt
diff --git a/PROJECT_STATUS_VISUAL.txt b/docs/archive/2025-11-04-project-status-visual.txt
index f945258..f945258 100644
--- a/PROJECT_STATUS_VISUAL.txt
+++ b/docs/archive/2025-11-04-project-status-visual.txt
diff --git a/SESSION_SUMMARY.txt b/docs/archive/2025-11-04-session-summary.txt
index 3692edb..3692edb 100644
--- a/SESSION_SUMMARY.txt
+++ b/docs/archive/2025-11-04-session-summary.txt