docs: add documentation for vcs object design (#49)

- add documentation for vcs object design

Author: wislertt

.amazonq/rules/source-code-lookup.md

@@ -0,0 +1,19 @@
+# Source Code Lookup Rules
+
+## MANDATORY: Check Local Cache First
+
+When user asks to "look at source code" or examine external project implementations:
+
+**ALWAYS check `.cache/repos/` directory first** before attempting external lookups.
+
+## Workflow
+
+1. **Check local cache**: Look in `.cache/repos/<project-name>/`
+2. **If found**: Use local cached version
+3. **If not found**: Then attempt external lookup (GitHub API, etc.)
+
+## Examples
+
+- "look at dunamai source code" → Check `.cache/repos/dunamai/` first
+- "examine ripgrep implementation" → Check `.cache/repos/ripgrep/` first
+- "see how X handles Y" → Check `.cache/repos/X/` first

.dev/00-roadmap.md

@@ -80,8 +80,8 @@
 
 ### Enhanced VCS Support
 
-- [ ] Archive support (`.git_archival.json`)
 - [ ] Shallow repository handling
+- [ ] Archive support (`.git_archival.json`) - _if requested by users_
 - [ ] Multiple VCS systems (Mercurial, SVN)
 
 ### Configuration System
@@ -107,8 +107,7 @@ zerv/
 ├── src/
 │   ├── vcs/
 │   │   ├── mod.rs           # VCS trait and detection
-│   │   ├── git.rs           # Git implementation
-│   │   └── archive.rs       # Archive support
+│   │   └── git.rs           # Git implementation (includes archive support)
 │   ├── cli/
 │   │   ├── mod.rs           # CLI framework
 │   │   ├── commands.rs      # Command implementations
@@ -180,10 +179,10 @@ zerv version --schema zerv-default --output-format pep440
 - Multiple VCS support (Mercurial, SVN, Darcs)
 - Advanced configuration system
 - Version bumping and manipulation
-- Archive format support
 
 **1.0 Features**:
 
+- Archive support (if user demand exists)
 - Complete dunamai feature parity
 - Performance optimizations
 - Comprehensive documentation